<!-- Three.js WebGPU 平铺阴影映射阵列演示 - 功能和技术点详解
一、项目概述
这是一个基于Three.js WebGPU渲染器的高级3D图形技术演示，重点展示平铺阴影映射（Tile Shadow Mapping）技术。场景包含大量几何体实例，模拟了一个包含建筑物、树木、装饰物等的虚拟世界，实现了高效、高质量的实时阴影渲染。

二、核心功能模块
1. 渲染系统
WebGPU渲染器：使用下一代图形API WebGPU，相比WebGL提供更好的性能和更多高级功能

抗锯齿处理：开启MSAA抗锯齿，消除边缘锯齿

色调映射：采用ACES电影级色调映射算法，提供更自然的色彩和对比度

自适应分辨率：根据设备像素比自动调整渲染分辨率

2. 光影系统
多层光照模型：

环境光（Ambient Light）：基础均匀照明，模拟天空散射

方向光（Directional Light）：主光源，模拟太阳，投射动态阴影

高级雾效：基于距离的指数雾，增强场景深度感和氛围

动态光源：光源自动旋转，模拟太阳东升西落的自然光照变化

3. 阴影系统（核心技术）
平铺阴影映射（TSM）：

将大型阴影贴图分割为2×2=4个独立平铺

每个平铺独立渲染，提高阴影质量和渲染性能

避免传统阴影映射在远距离时的分辨率不足问题

阴影质量优化：

4096×4096高分辨率阴影贴图

阴影边缘模糊（radius: 1）

阴影偏移修正（bias: -0.005）防止阴影失真

4. 场景物体系统
多样化几何体：圆柱体、立方体、球体、圆环面结、圆锥体、平面等

层级化组织：使用Group对象管理相关物体

程序化生成：随机分布和参数化生成场景元素

三、主要技术亮点
1. 性能优化技术
实例化渲染（InstancedMesh）：

相同几何体和材质的物体共享渲染数据

大量减少GPU绘制调用（Draw Calls）

应用于：柱子（132个）、立方体（30个）、球体（25个）、圆环体（15个）

批处理网格（BatchedMesh）：

比实例化网格更高效的渲染技术

将多个几何体合并到单个绘制调用中

应用于：树木（40棵，每棵包含树干和树冠）

视锥体剔除优化：

对批处理网格禁用逐对象剔除，减少CPU开销

2. 着色器技术
TSL（Three.js Shading Language）：

Three.js的声明式着色器语言

简化着色器编程，提供类型安全和自动优化

程序化纹理生成：

使用分形噪声（Fractal Noise）动态生成地面纹理

无需纹理图片，节省内存和带宽

公式：noise.x.mix(green, brown) 混合草地和泥土颜色

3. 交互功能
轨道控制器（OrbitControls）：

鼠标左键：旋转视角

鼠标右键：平移场景

鼠标滚轮：缩放视图

响应式设计：

自动适应窗口大小变化

保持正确的宽高比和渲染质量

4. 调试与开发工具
Inspector调试器：实时查看场景树、编辑属性、监控性能

TSM辅助可视化：显示阴影平铺边界和状态，便于调试

四、技术架构
text
Three.js WebGPU应用架构
├── 渲染层（WebGPURenderer）
│   ├── 阴影映射系统（TileShadowNode）
│   ├── 色调映射系统（ACESFilmic）
│   └── 抗锯齿系统（MSAA）
│
├── 场景管理层（Scene）
│   ├── 光照系统
│   │   ├── 环境光
│   │   └── 方向光 + TSM
│   │
│   ├── 几何体系统
│   │   ├── 实例化网格（高性能）
│   │   ├── 批处理网格（最高性能）
│   │   └── 普通网格（可动画）
│   │
│   └── 摄像机系统
│       ├── 透视投影
│       └── 轨道控制
│
├── 着色器系统（TSL）
│   ├── 程序化纹理
│   ├── 分形噪声
│   └── 材质节点
│
└── 工具层
    ├── 调试器（Inspector）
    ├── TSM可视化助手
    └── 性能监控
五、性能表现
渲染优化策略：
静态批处理：树木等静态物体使用BatchedMesh

动态实例化：可移动但形状相同的物体使用InstancedMesh

阴影平铺：大场景阴影分块渲染，避免分辨率浪费

LOD策略：不同物体使用适当的分段数（柱子16段，球体32段）

内存优化：
几何体复用：相同形状物体共享几何体数据

材质共享：相同外观物体共享材质数据

无纹理贴图：地面使用程序化纹理，节省纹理内存 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面元数据：定义文档类型和HTML版本 -->
		<!-- 页面标题：显示在浏览器标签页上的标题 -->
		<title>Three.js WebGPU - 平铺阴影映射阵列演示</title>
		<!-- 字符编码：指定文档使用UTF-8编码，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：控制移动端显示和缩放行为 -->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- CSS样式表链接：引入外部样式文件，控制页面样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>
		<!-- 页面顶部信息区域：显示标题和描述信息 -->
		<!-- id="info"：用于CSS样式选择器识别该元素 -->
		<!-- class="invert"：应用反转颜色样式，使文字在深色背景上显示 -->
		<div id="info" class="invert">
			<!-- Three.js官方链接：点击logo跳转到Three.js官网 -->
			<!-- target="_blank"：在新标签页打开链接 -->
			<!-- rel="noopener"：安全措施，防止新页面访问原页面的window.opener属性 -->
			<!-- class="logo-link"：CSS类，可能用于设置logo背景图片 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装容器：包含主标题和副标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接：Three.js官方网站链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：当前演示的特定功能名称 -->
				<span> - 平铺阴影映射阵列技术演示</span>
			</div>

			<!-- 描述文本：简要说明演示的核心功能 -->
			<small>
				本演示展示了如何使用阴影映射阵列技术实现高效的平铺阴影渲染
				<br>
				场景包含多种几何体实例，展示了WebGPU渲染器的高性能特性
			</small>
		</div>

		<!-- 导入映射配置：定义JavaScript模块的导入路径别名 -->
		<!-- type="importmap"：指定此script标签为导入映射，现代浏览器支持 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					"three/webgpu": "../build/three.webgpu.js",
					"three/tsl": "../build/three.tsl.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript模块：包含所有Three.js场景代码 -->
		<!-- type="module"：指定此script标签为ES6模块，支持模块化导入 -->
		<script type="module">

			// ============== 模块导入部分 ==============
			// 导入Three.js核心库的所有导出，使用WebGPU版本
			// * as THREE：将整个模块导出作为THREE对象，包含所有Three.js类和函数
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色器语言（TSL）的相关函数
			// mx_fractal_noise_vec3：分形噪声生成函数，用于创建程序化纹理
			// positionWorld：世界坐标系中的顶点位置变量
			// Fn：函数定义宏，用于创建可复用的着色器函数
			// color：颜色构造函数，用于在着色器中创建颜色值
			import { mx_fractal_noise_vec3, positionWorld, Fn, color } from 'three/tsl';

			// 导入平铺阴影映射相关模块
			// TileShadowNode：平铺阴影映射节点类，负责管理阴影的平铺和渲染
			import { TileShadowNode } from 'three/addons/tsl/shadows/TileShadowNode.js';
			// TileShadowNodeHelper：平铺阴影映射辅助可视化类，用于调试和显示阴影平铺信息
			import { TileShadowNodeHelper } from 'three/addons/tsl/shadows/TileShadowNodeHelper.js';

			// 导入轨道控制器：提供鼠标控制摄像机旋转、平移和缩放的功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入调试器：提供Three.js场景的实时调试和性能分析工具
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ============== 全局变量声明 ==============
			// 场景核心对象变量声明
			let camera;      // 摄像机对象：定义观察场景的视角和投影方式
			let scene;       // 场景对象：包含所有3D对象、灯光和相机的容器
			let renderer;    // 渲染器对象：负责将3D场景渲染到2D画布上
			let clock;       // 时钟对象：用于跟踪时间和计算帧间隔时间（delta time）
			
			// 光源相关变量
			let dirLight;    // 方向光对象：模拟太阳光，主要光源，投射阴影
			
			// 场景物体变量
			let torusKnot;   // 圆环面结对象：场景中的中心装饰物体，会旋转
			let dirGroup;    // 灯光组对象：用于组织和管理方向光及其相关物体
			
			// 阴影辅助对象
			let tsmHelper;   // 平铺阴影映射辅助器：可视化阴影平铺信息的辅助对象

			// ============== 主初始化函数调用 ==============
			// 调用异步初始化函数，启动Three.js场景的创建和设置
			init();

			// ============== 异步初始化函数 ==============
			// async function：异步函数声明，允许在函数内部使用await关键字
			// 负责初始化Three.js渲染器、场景、相机、灯光和所有物体
			async function init() {

				// ---------- 第1部分：WebGPU渲染器设置 ----------
				// 创建WebGPURenderer实例，使用WebGPU API进行硬件加速渲染
				// { antialias: true }：启用抗锯齿，减少物体边缘的锯齿状现象
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置渲染器的像素比，匹配设备屏幕的物理像素密度
				// window.devicePixelRatio：设备像素比，视网膜屏幕通常为2
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器画布尺寸为浏览器窗口尺寸
				// window.innerWidth：窗口内部宽度（不包括浏览器边框和滚动条）
				// window.innerHeight：窗口内部高度
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数，每帧自动调用animate函数
				// 这是Three.js游戏循环的核心，实现连续动画渲染
				renderer.setAnimationLoop( animate );

				// 创建并附加调试器到渲染器，方便开发时调试场景
				// Inspector提供场景树查看、属性编辑、性能监控等功能
				renderer.inspector = new Inspector();

				// ---------- 第2部分：阴影映射配置 ----------
				// 启用渲染器的阴影映射系统
				renderer.shadowMap.enabled = true;
				
				// 设置阴影映射类型为BasicShadowMap（基础阴影映射）
				// 这是最简单的阴影算法，性能好但阴影边缘有锯齿
				renderer.shadowMap.type = THREE.BasicShadowMap;
				
				// 注释掉的选项：PCFSoftShadowMap（百分比渐进过滤软阴影）
				// 提供更平滑的阴影边缘，但性能消耗更大
				// renderer.shadowMap.type = THREE.PCFSoftShadowMap;

				// ---------- 第3部分：色调映射和曝光设置 ----------
				// 设置色调映射算法为ACESFilmicToneMapping
				// 这是一种电影级色调映射，提供更自然的颜色和对比度
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				
				// 设置曝光值，控制场景的整体亮度
				// 1.2表示稍微过曝，使场景更明亮
				renderer.toneMappingExposure = 1.2;
				
				// 将渲染器的DOM元素（canvas画布）添加到网页body中
				// renderer.domElement是HTMLCanvasElement类型的画布元素
				document.body.appendChild( renderer.domElement );
			
				// 异步初始化WebGPU渲染器，等待WebGPU上下文准备就绪
				// await：等待异步操作完成，确保渲染器完全初始化后再继续
				await renderer.init();

				// ---------- 第4部分：摄像机设置 ----------
				// 创建透视投影摄像机（PerspectiveCamera）
				// 参数说明：
				// 45：视野角度（FOV），单位度，控制可见范围大小
				// window.innerWidth / window.innerHeight：宽高比，匹配窗口比例
				// 1：近裁剪面距离，比此距离近的物体不渲染
				// 1000：远裁剪面距离，比此距离远的物体不渲染
				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 1000 );
				
				// 设置摄像机的初始位置
				// set(x, y, z)：在世界坐标系中的位置
				// (45, 60, 100)：从右上方俯视场景的位置
				camera.position.set( 45, 60, 100 );

				// ---------- 第5部分：场景创建和基础设置 ----------
				// 创建场景对象，作为所有3D物体的容器
				scene = new THREE.Scene();
				
				// 设置场景背景色（使用TSL节点）
				// color(0xCCCCFF)：创建浅蓝色（RGB: 0.8, 0.8, 1.0）
				// 这是天空的近似颜色
				scene.backgroundNode = color( 0xCCCCFF );
				
				// 添加雾效到场景，增强深度感和距离感
				// 参数说明：
				// 0xCCCCFF：雾的颜色，与背景色一致
				// 700：雾效开始的距离（摄像机距离700单位开始有雾）
				// 1000：雾效完全覆盖的距离（摄像机距离1000单位完全雾化）
				scene.fog = new THREE.Fog( 0xCCCCFF, 700, 1000 );

				// ---------- 第6部分：环境光照设置 ----------
				// 添加环境光，为整个场景提供均匀的基础照明
				// AmbientLight没有方向，不投射阴影
				// 参数说明：
				// 0xCCCCFF：浅蓝色环境光，模拟天空散射光
				// 3：光照强度，值越大越亮（默认是1）
				scene.add( new THREE.AmbientLight( 0xCCCCFF, 3 ) );

				// ---------- 第7部分：主方向光（太阳光）设置 ----------
				// 创建方向光（DirectionalLight），模拟太阳光
				// 参数说明：
				// 0xFFFFAA：浅黄色光，模拟阳光颜色
				// 5：光照强度，比环境光亮，作为主光源
				dirLight = new THREE.DirectionalLight( 0xFFFFAA, 5 );
				
				// 设置方向光的位置
				// 方向光的位置表示光线的来源方向
				// (0, 80, 30)：从高处斜射下来
				dirLight.position.set( 0, 80, 30 );
				
				// 启用方向光的阴影投射功能
				dirLight.castShadow = true;
				
				// ---------- 第8部分：阴影相机参数配置 ----------
				// 阴影相机是专门用于渲染阴影的摄像机
				// 它定义了从光源视角看到的场景范围
				// dirLight.shadow.camera：方向光的正交投影摄像机
				
				// 阴影相机的近裁剪面：1单位距离
				dirLight.shadow.camera.near = 1;
				
				// 阴影相机的远裁剪面：200单位距离
				dirLight.shadow.camera.far = 200;
				
				// 阴影相机的视锥体边界（正交投影）
				// right：右边界（180单位）
				// left：左边界（-180单位）
				// top：上边界（180单位）
				// bottom：下边界（-160单位）
				// 这些值定义了从光源视角看到的场景矩形区域
				dirLight.shadow.camera.right = 180;
				dirLight.shadow.camera.left = - 180;
				dirLight.shadow.camera.top	= 180;
				dirLight.shadow.camera.bottom = - 160;
				
				// ---------- 第9部分：阴影贴图质量设置 ----------
				// 设置阴影贴图的分辨率（纹理尺寸）
				// mapSize.width：阴影贴图宽度（4096像素）
				// mapSize.height：阴影贴图高度（4096像素）
				// 1024 * 4 = 4096，高分辨率提供更清晰的阴影
				dirLight.shadow.mapSize.width = 1024 * 4;
				dirLight.shadow.mapSize.height = 1024 * 4;
				
				// 阴影边缘模糊半径：1像素模糊，使阴影边缘稍微柔化
				dirLight.shadow.radius = 1;
				
				// 阴影偏移：-0.005，防止阴影失真（阴影与物体分离的现象）
				// 负值表示将阴影拉向光源方向
				dirLight.shadow.bias = - 0.005;

				// ---------- 第10部分：平铺阴影映射（TSM）设置 ----------
				// 创建TileShadowNode实例，实现平铺阴影映射
				// 参数说明：
				// dirLight：要应用TSM的光源
				// { tilesX: 2, tilesY: 2 }：将阴影贴图分割为2x2=4个平铺
				// 每个平铺独立渲染，提高阴影质量和性能
				const tsm = new TileShadowNode( dirLight, {
					tilesX: 2,  // X轴方向2个平铺
					tilesY: 2   // Y轴方向2个平铺
				} );

				// 将TSM节点设置为方向光的阴影节点
				// shadowNode：Three.js新的阴影系统，支持自定义阴影渲染逻辑
				dirLight.shadow.shadowNode = tsm;
				
				// 将方向光添加到场景中
				scene.add( dirLight );

				// 创建平铺阴影映射辅助可视化器
				// 显示阴影平铺的边界和状态，用于调试和可视化
				tsmHelper = new TileShadowNodeHelper( tsm );
				scene.add( tsmHelper );

				// ---------- 第11部分：创建灯光组 ----------
				// 创建组对象来包含方向光，方便整体控制和变换
				dirGroup = new THREE.Group();
				dirGroup.add( dirLight );
				scene.add( dirGroup );

				// ---------- 第12部分：创建地面 ----------
				// 创建平面几何体作为地面
				// 参数说明：
				// 1500：宽度（X轴方向）
				// 1500：高度（Z轴方向）
				// 2：宽度分段数（简化的网格，减少顶点数）
				// 2：高度分段数
				const planeGeometry = new THREE.PlaneGeometry( 1500, 1500, 2, 2 );
				
				// 创建Phong材质（具有镜面高光的光照材质）
				const planeMaterial = new THREE.MeshPhongMaterial( {
					color: 0x88AA44,    // 基础颜色：草绿色（RGB: 0.53, 0.67, 0.27）
					shininess: 5,       // 高光光泽度：值越小高光区域越大
					specular: 0x222222  // 镜面反射颜色：深灰色
				} );

				// 使用TSL着色器语言为地面创建程序化纹理
				// Fn(() => { ... })：定义着色器函数
				// .saturate()：限制颜色值在0-1范围内
				planeMaterial.colorNode = Fn( () => {
					// 生成基于世界位置的分形噪声
					// positionWorld.mul(0.05)：将世界坐标缩小20倍，控制噪声尺度
					// mx_fractal_noise_vec3：生成三维分形噪声
					const noise = mx_fractal_noise_vec3( positionWorld.mul( 0.05 ) ).saturate();
					
					// 定义两种地面颜色
					const green = color( 0.4, 0.7, 0.3 );  // 鲜绿色
					const brown = color( 0.6, 0.5, 0.3 );  // 棕褐色
					
					// 使用噪声的x分量混合两种颜色
					// noise.x.mix(green, brown)：根据noise.x在0-1之间混合green和brown
					// 创建自然的草地和泥土混合效果
					return noise.x.mix( green, brown );
				} )();

				// 创建地面网格对象
				const ground = new THREE.Mesh( planeGeometry, planeMaterial );
				
				// 旋转地面使其水平
				// 默认平面是垂直的，绕X轴旋转-90度使其平放
				ground.rotation.x = - Math.PI / 2;
				
				// 启用地面接收阴影
				ground.receiveShadow = true;
				
				// 将地面添加到场景
				scene.add( ground );

				// ---------- 第13部分：创建场景中的所有物体 ----------
				// 调用自定义函数创建柱子、立方体、球体、树木等各种物体
				createScenery();

				// ---------- 第14部分：轨道控制器设置 ----------
				// 创建OrbitControls实例，连接摄像机和渲染器的DOM元素
				const controls = new OrbitControls( camera, renderer.domElement );
				
				// 设置控制器的目标点（摄像机围绕旋转的中心点）
				controls.target.set( 0, 5, 0 );  // 场景中心，稍微高于地面
				
				// 设置摄像机与目标点的最小距离
				controls.minDistance = 0.01;  // 允许非常近距离观察
				
				// 设置摄像机与目标点的最大距离
				controls.maxDistance = 400;   // 允许远距离观察整个场景
				
				// 设置最大极角（垂直旋转角度）
				// Math.PI / 2 = 90度，减去0.1防止摄像机完全垂直向下
				// 避免摄像机穿入地面下方
				controls.maxPolarAngle = Math.PI / 2 - 0.1;
				
				// 更新控制器内部状态
				controls.update();

				// 创建Three.js时钟对象，用于动画时间管理
				clock = new THREE.Clock();

				// ---------- 第15部分：窗口大小变化事件监听 ----------
				// 监听窗口大小变化事件，调整摄像机和渲染器设置
				// resize函数将在窗口大小变化时被调用
				window.addEventListener( 'resize', resize );

			}

			// ============== 创建场景物体函数 ==============
			// 负责创建和组织场景中的所有3D物体
			// 使用实例化网格（InstancedMesh）提高渲染性能
			function createScenery() {
				// 创建临时矩阵对象，用于设置实例化网格的变换
				const matrix = new THREE.Matrix4();

				// ---------- 1. 创建圆柱体柱子（使用实例化网格） ----------
				// 几何体：圆柱体，用于创建场景中的柱子
				// 参数说明：
				// 0.8：顶部半径
				// 1：底部半径（底部稍粗）
				// 1：高度（基础高度，后续会缩放）
				// 16：圆周分段数（值越大圆柱越圆滑）
				const columnGeometry = new THREE.CylinderGeometry( 0.8, 1, 1, 16 );
				
				// 材质：Phong材质，浅灰色，中等光泽
				const columnMaterial = new THREE.MeshPhongMaterial( {
					color: 0xDDDDDD,  // 浅灰色（RGB: 0.87, 0.87, 0.87）
					shininess: 20      // 中等光泽度
				} );

				// 存储柱子位置和缩放数据的数组
				const columnPositions = [];  // 存储每个柱子的X,Y,Z位置
				const columnScales = [];     // 存储每个柱子的X,Y,Z缩放值

				// 生成柱子位置：在200x200的网格区域内生成
				// 外层循环：X轴从-100到100，步长40
				// 内层循环：Z轴从-100到100，步长40
				for ( let x = - 100; x <= 100; x += 40 ) {
					for ( let z = - 100; z <= 100; z += 40 ) {
						// 70%的概率生成柱子（随机性增加自然感）
						if ( Math.random() > 0.3 ) {
							// 随机生成柱子高度：5-15单位
							const height = 5 + Math.random() * 10;
							
							// 在网格位置基础上添加随机偏移（-5到+5）
							const posX = x + ( Math.random() * 10 - 5 );
							const posY = height / 2;  // 柱子中心在高度的一半（因为圆柱原点在中心）
							const posZ = z + ( Math.random() * 10 - 5 );

							// 将位置数据添加到数组（顺序：X, Y, Z）
							columnPositions.push( posX, posY, posZ );
							
							// 将缩放数据添加到数组（只在Y轴缩放以改变高度）
							columnScales.push( 1, height, 1 ); // X和Z轴保持1，Y轴缩放为高度
						}
					}
				}

				// 计算实际生成的柱子数量
				// 每个柱子有3个位置值（X,Y,Z），所以总数除以3
				const columnCount = columnPositions.length / 3;
				
				// 创建实例化网格（InstancedMesh）
				// 参数说明：
				// columnGeometry：共享的几何体
				// columnMaterial：共享的材质
				// columnCount：实例数量
				// InstancedMesh允许多个物体共享相同的几何体和材质，但有不同的变换矩阵
				const columnInstancedMesh = new THREE.InstancedMesh(
					columnGeometry,
					columnMaterial,
					columnCount
				);

				// 为每个柱子实例设置变换矩阵
				for ( let i = 0; i < columnCount; i ++ ) {
					// 从数组中获取第i个柱子的位置数据
					const x = columnPositions[ i * 3 ];      // X坐标
					const y = columnPositions[ i * 3 + 1 ];  // Y坐标
					const z = columnPositions[ i * 3 + 2 ];  // Z坐标
					const scaleY = columnScales[ i * 3 + 1 ]; // Y轴缩放值（高度）
					
					// 创建变换矩阵
					// makeScale(1, scaleY, 1)：创建缩放矩阵（只在Y轴缩放）
					// setPosition(x, y, z)：设置位置矩阵
					matrix.makeScale( 1, scaleY, 1 );
					matrix.setPosition( x, y, z );
					
					// 将变换矩阵应用到第i个实例
					columnInstancedMesh.setMatrixAt( i, matrix );
				}

				// 启用柱子的阴影功能
				columnInstancedMesh.castShadow = true;    // 柱子投射阴影
				columnInstancedMesh.receiveShadow = true; // 柱子接收其他物体的阴影
				
				// 将柱子实例化网格添加到场景
				scene.add( columnInstancedMesh );

				// ---------- 2. 创建中心装饰物体 - 圆环面结（TorusKnot） ----------
				// 几何体：圆环面结（环形结状几何体）
				// 参数说明：
				// 25：主要半径（环的大小）
				// 8：次要半径（管道的粗细）
				// 100：管道分段数（圆周方向）
				// 30：环向分段数（环形方向）
				const torusKnotGeometry = new THREE.TorusKnotGeometry( 25, 8, 100, 30 );
				
				// 材质：Phong节点材质，支持TSL着色器
				const torusKnotMaterial = new THREE.MeshPhongNodeMaterial( {
					color: 0xFF6347, // 番茄红色（RGB: 1.0, 0.39, 0.28）
					shininess: 30,   // 高光泽度，表面反光明显
				} );

				// 创建圆环面结网格（非实例化，因为只有一个且需要单独控制动画）
				torusKnot = new THREE.Mesh( torusKnotGeometry, torusKnotMaterial );
				
				// 缩放圆环面结：原始尺寸太大，缩小为1/18
				torusKnot.scale.multiplyScalar( 1 / 18 );
				
				// 设置位置：场景中心偏右上方
				torusKnot.position.x = 5;
				torusKnot.position.y = 5;
				
				// 启用阴影
				torusKnot.castShadow = true;
				torusKnot.receiveShadow = true;
				
				// 添加到场景
				scene.add( torusKnot );

				// ---------- 3. 创建彩色立方体（使用实例化网格） ----------
				// 几何体：立方体（3x3x3单位）
				const cubeGeometry = new THREE.BoxGeometry( 3, 3, 3 );
				
				// 三种不同颜色的材质（每种材质对应一个实例化网格）
				const cubeMaterials = [
					new THREE.MeshPhongMaterial( { color: 0x6699CC, shininess: 20 } ), // 浅蓝色
					new THREE.MeshPhongMaterial( { color: 0xCC6666, shininess: 20 } ), // 浅红色
					new THREE.MeshPhongMaterial( { color: 0xCCCC66, shininess: 20 } )  // 浅黄色
				];

				// 每个材质创建10个实例（总共30个立方体）
				const cubeCount = 10;
				
				// 创建三个实例化网格，每个使用不同的材质
				const cubeInstances = cubeMaterials.map( material => {
					return new THREE.InstancedMesh( cubeGeometry, material, cubeCount );
				} );

				// 生成30个立方体（3种颜色各10个）
				for ( let i = 0; i < 30; i ++ ) {
					// 计算材质索引：0,1,2循环
					const materialIndex = i % 3;
					// 计算实例索引：0-9（每种材质的10个实例）
					const instanceIndex = Math.floor( i / 3 );

					// 随机生成位置：在300x300的区域内随机分布
					const x = Math.random() * 300 - 150;  // -150到+150
					const y = 1.5;  // 立方体高度的一半（3/2），使底部在地面上
					const z = Math.random() * 300 - 150;  // -150到+150
					
					// 随机Y轴旋转：0到360度
					const rotY = Math.random() * Math.PI * 2;

					// 创建变换矩阵：先旋转，再设置位置
					matrix.makeRotationY( rotY );  // 绕Y轴旋转
					matrix.setPosition( x, y, z ); // 设置位置
					
					// 应用变换矩阵到对应的实例化网格
					cubeInstances[ materialIndex ].setMatrixAt( instanceIndex, matrix );
				}

				// 遍历所有立方体实例化网格，启用阴影并添加到场景
				cubeInstances.forEach( instance => {
					instance.castShadow = true;
					instance.receiveShadow = true;
					scene.add( instance );
				} );

				// ---------- 4. 创建球体（使用实例化网格） ----------
				// 几何体：球体（半径2，32x32分段）
				const sphereGeometry = new THREE.SphereGeometry( 2, 32, 32 );
				
				// 材质：青绿色Phong材质
				const sphereMaterial = new THREE.MeshPhongMaterial( {
					color: 0x88CCAA,  // 青绿色（RGB: 0.53, 0.8, 0.67）
					shininess: 40      // 高光泽度
				} );

				// 创建25个球体实例
				const sphereCount = 25;
				const sphereInstancedMesh = new THREE.InstancedMesh(
					sphereGeometry,
					sphereMaterial,
					sphereCount
				);

				// 为每个球体设置随机位置
				for ( let i = 0; i < sphereCount; i ++ ) {
					const x = Math.random() * 180 - 90;  // -90到+90
					const y = 2;                         // 球体半径，使底部接触地面
					const z = Math.random() * 180 - 90;  // -90到+90
					
					// 创建单位矩阵（无旋转缩放）并设置位置
					matrix.makeScale( 1, 1, 1 );
					matrix.setPosition( x, y, z );
					
					sphereInstancedMesh.setMatrixAt( i, matrix );
				}

				// 启用阴影并添加到场景
				sphereInstancedMesh.castShadow = true;
				sphereInstancedMesh.receiveShadow = true;
				scene.add( sphereInstancedMesh );

				// ---------- 5. 创建树木（使用批处理网格BatchedMesh） ----------
				// 批处理网格比实例化网格更高效，特别适合大量简单物体
				
				// 树干几何体：圆柱体（半径0.5，高度2，8个分段）
				const trunkGeometry = new THREE.CylinderGeometry( 0.5, 0.5, 2, 8 );
				
				// 树冠几何体：圆锥体（底部半径2，高度8，8个分段）
				const topGeometry = new THREE.ConeGeometry( 2, 8, 8 );
				
				// 树木材质：使用顶点颜色的Phong材质
				const treeMaterial = new THREE.MeshPhongMaterial( {
					vertexColors: true,  // 启用顶点颜色（不同部分不同颜色）
					shininess: 5         // 低光泽度（树木表面较粗糙）
				} );

				// 树木数量：40棵
				const treeCount = 40;
				
				// 总实例数量：每棵树有树干和树冠2个部分
				const totalInstanceCount = treeCount * 2;

				// 计算几何体的顶点和索引数量
				const trunkVertexCount = trunkGeometry.attributes.position.count;  // 树干顶点数
				const trunkIndexCount = trunkGeometry.index ? trunkGeometry.index.count : 0;  // 树干索引数
				const topVertexCount = topGeometry.attributes.position.count;      // 树冠顶点数
				const topIndexCount = topGeometry.index ? topGeometry.index.count : 0;        // 树冠索引数

				// 计算批处理网格的总容量（乘以2预留额外空间）
				const totalVertexCount = ( trunkVertexCount + topVertexCount ) * 2;
				const totalIndexCount = ( trunkIndexCount + topIndexCount ) * 2;
				
				// 创建批处理网格（BatchedMesh）
				// 参数说明：
				// totalInstanceCount：最大实例数量
				// totalVertexCount：最大顶点数量
				// totalIndexCount：最大索引数量
				// treeMaterial：共享材质
				const treeBatchedMesh = new THREE.BatchedMesh( totalInstanceCount, totalVertexCount, totalIndexCount, treeMaterial );
				
				// 启用阴影
				treeBatchedMesh.castShadow = true;
				
				// 禁用每对象视锥剔除（因为树木较小且分散，逐个剔除可能更耗性能）
				treeBatchedMesh.perObjectFrustumCulled = false;
				
				// 将几何体添加到批处理网格，获取几何体ID
				const trunkGeometryId = treeBatchedMesh.addGeometry( trunkGeometry );
				const topGeometryId = treeBatchedMesh.addGeometry( topGeometry );

				// 定义树木各部分的颜色
				const trunkColor = new THREE.Color( 0x8B4513 ); // 棕色（RGB: 0.55, 0.27, 0.07）树皮色
				const topColor = new THREE.Color( 0x336633 );   // 深绿色（RGB: 0.2, 0.4, 0.2）树叶色

				// 创建40棵树
				for ( let i = 0; i < treeCount; i ++ ) {
					// 随机生成树木位置
					const x = Math.random() * 300 - 150;  // -150到+150
					const z = Math.random() * 300 - 150;  // -150到+150

					// 添加树干实例
					const trunkId = treeBatchedMesh.addInstance( trunkGeometryId );
					matrix.makeScale( 1, 1, 1 );           // 无缩放
					matrix.setPosition( x, 1, z );         // 位置：Y=1（树干高度的一半）
					treeBatchedMesh.setMatrixAt( trunkId, matrix );  // 设置变换矩阵
					treeBatchedMesh.setColorAt( trunkId, trunkColor ); // 设置颜色

					// 添加树冠实例
					const topId = treeBatchedMesh.addInstance( topGeometryId );
					matrix.makeScale( 1, 1, 1 );           // 无缩放
					matrix.setPosition( x, 6, z );         // 位置：Y=6（树干高度2 + 树冠高度8/2=4）
					treeBatchedMesh.setMatrixAt( topId, matrix );    // 设置变换矩阵
					treeBatchedMesh.setColorAt( topId, topColor );   // 设置颜色
				}

				// 将树木批处理网格添加到场景
				scene.add( treeBatchedMesh );

				// ---------- 6. 创建圆环体（Torus，使用实例化网格） ----------
				// 几何体：圆环体（甜甜圈形状）
				// 参数说明：
				// 3：主要半径（环的大小）
				// 1：次要半径（管道的粗细）
				// 16：管道分段数（圆周方向）
				// 50：环向分段数（环形方向）
				const torusGeometry = new THREE.TorusGeometry( 3, 1, 16, 50 );
				
				// 材质：粉色Phong材质
				const torusMaterial = new THREE.MeshPhongMaterial( {
					color: 0xFF99CC,  // 粉色（RGB: 1.0, 0.6, 0.8）
					shininess: 30      // 高光泽度
				} );

				// 创建15个圆环体实例
				const torusCount = 15;
				const torusInstancedMesh = new THREE.InstancedMesh(
					torusGeometry,
					torusMaterial,
					torusCount
				);

				// 为每个圆环体设置随机位置和旋转
				for ( let i = 0; i < torusCount; i ++ ) {
					const x = Math.random() * 320 - 160;  // -160到+160
					const y = 2;                          // 离地面高度
					const z = Math.random() * 320 - 160;  // -160到+160
					const rotZ = Math.random() * Math.PI * 2;  // 随机Z轴旋转

					// 创建变换矩阵
					// 先绕X轴旋转90度，使圆环体垂直站立（默认是平躺的）
					matrix.makeRotationX( Math.PI / 2 );
					
					// 创建Z轴旋转矩阵
					const rotMatrix = new THREE.Matrix4().makeRotationZ( rotZ );
					
					// 合并两个旋转矩阵
					matrix.multiply( rotMatrix );
					
					// 设置位置
					matrix.setPosition( x, y, z );
					
					// 应用到实例
					torusInstancedMesh.setMatrixAt( i, matrix );
				}

				// 启用阴影并添加到场景
				torusInstancedMesh.castShadow = true;
				torusInstancedMesh.receiveShadow = true;
				scene.add( torusInstancedMesh );
			}

			// ============== 窗口大小变化响应函数 ==============
			// 当浏览器窗口大小改变时调用此函数
			// 确保渲染画面始终正确适配窗口尺寸
			function resize() {
				// 更新摄像机的宽高比（aspect ratio）
				// 宽高比 = 窗口宽度 / 窗口高度
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新摄像机的投影矩阵
				// 投影矩阵定义了3D空间如何映射到2D屏幕
				// 当宽高比改变后，必须更新投影矩阵以防止画面拉伸变形
				camera.updateProjectionMatrix();
				
				// 更新渲染器的尺寸，使其与窗口新尺寸匹配
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ============== 动画循环函数 ==============
			// 这是Three.js的主渲染循环，每帧自动调用
			// time参数：从页面加载开始经过的时间（毫秒）
			async function animate( time ) {
				// 获取上一帧到当前帧的时间间隔（秒）
				// delta时间用于实现与帧率无关的平滑动画
				// 无论帧率高低，物体移动速度保持一致
				const delta = clock.getDelta();

				// ---------- 物体动画更新 ----------
				// 旋转中心圆环面结（三轴不同速度，创建复杂旋转效果）
				torusKnot.rotation.x += 0.25 * delta;  // X轴：每秒0.25弧度（约14.3度）
				torusKnot.rotation.y += 0.5 * delta;   // Y轴：每秒0.5弧度（约28.6度）
				torusKnot.rotation.z += 1 * delta;     // Z轴：每秒1弧度（约57.3度）

				// 让光源绕Y轴做圆周运动（模拟太阳东升西落）
				// Math.sin(time * 0.0001)：正弦函数，产生平滑的周期性运动
				// time * 0.0001：减慢运动速度，每10000毫秒（10秒）完成一个完整周期
				// * 30：运动半径30单位
				dirLight.position.x = Math.sin( time * 0.0001 ) * 30;  // X轴位置
				dirLight.position.z = Math.cos( time * 0.0001 ) * 30;  // Z轴位置

				// ---------- 场景渲染 ----------
				// 调用渲染器的render方法，将3D场景渲染到2D画布
				// 参数：
				// scene：要渲染的场景对象
				// camera：用于观察场景的摄像机
				renderer.render( scene, camera );

				// 更新平铺阴影映射辅助器
				// 可能更新可视化信息或调试显示
				tsmHelper.update();
			}

		</script>
	</body>
</html>