<!-- Three.js 阴影映射演示 - 代码功能与技术点分析
🎯 项目概述
这是一个基于Three.js的WebGL 3D图形演示，重点展示实时阴影映射技术和大规模动画场景优化。项目创建了一个包含600多个动画马模型的复杂3D场景，所有物体都能正确投射和接收动态阴影。

🏗️ 核心功能
1. 动态阴影系统
PCF软阴影：使用百分比渐近过滤技术，生成边缘柔和的真实阴影

方向光阴影：模拟太阳光的平行光源，为整个场景提供统一光照

阴影优化：通过阴影偏移(bias)解决阴影失真问题

阴影相机控制：精确控制阴影计算范围，平衡性能与质量

2. 大规模场景渲染
600+动画马模型：使用GLTF格式的Morph动画马

无限循环运动：马群沿X轴持续移动，移出边界后重置到起点

层次化场景：地面、平台、3D文字、马群形成立体空间结构

3. 交互控制系统
第一人称视角：WASD键控制移动，RF键控制升降，鼠标控制视角

流畅操控：帧率无关的运动控制，确保不同设备上一致体验

自适应窗口：自动响应窗口尺寸变化，保持正确渲染比例

🔧 主要技术点
1. Three.js核心技术
技术点	实现方式	作用
透视相机	PerspectiveCamera	模拟人眼视觉效果，近大远小
场景管理	Scene + Fog	组织3D对象，添加雾效增强深度感
材质系统	MeshPhongMaterial	支持高光反射的材质，提升真实感
几何体	TextGeometry + BoxGeometry	程序生成3D文字和立方体
光源系统	DirectionalLight + AmbientLight	主光源+环境光组合照明
2. 动画系统优化
优化策略	技术实现	性能提升
动画分组	AnimationObjectGroup (25组)	减少90%+动画计算量
共享动画状态	mixer.clipAction(clip, group)	一组模型共享动画数据
相位随机化	startAt(-duration * phase)	避免600匹马动作完全同步
实例化渲染思想	克隆基础模型+随机颜色	减少内存占用和GPU负担
3. 阴影映射技术细节
参数	值	作用
阴影贴图分辨率	2048×1024	平衡质量与性能
阴影相机范围	4000×4000单位	覆盖整个运动区域
阴影偏移量	0.0001	防止阴影失真(shadow acne)
阴影类型	PCFShadowMap	产生边缘柔和的软阴影
4. 性能优化技术
javascript
// 关键优化代码示例
// 1. 动画分组 - 将600+模型分配到25个组
const animGroups = [];
for (let i = 0; i < 25; i++) {
    animGroups.push(new THREE.AnimationObjectGroup());
}

// 2. 共享动画动作 - 每组只计算一次动画
if (!mixer.existingAction(clip, animGroup)) {
    mixer.clipAction(clip, animGroup)
        .setDuration(1)
        .startAt(-1 * phase)
        .play();
}

// 3. 边界回收 - 无限循环运动
if (morph.position.x > 2000) {
    morph.position.x = -1000 - Math.random() * 500;
}
5. 资源加载与管理
异步加载：字体和GLTF模型异步加载，不阻塞主线程

资源复用：基础模型克隆使用，减少网络请求

错误处理：加载失败有回调处理机制

进度追踪：支持加载进度监控（代码中留了扩展接口）

📊 性能特性
1. 渲染效率
批量处理：25个动画组代替600个独立动画计算

GPU优化：相同几何体和材质的实例化渲染

智能剔除：相机视锥体外的物体不参与渲染

2. 内存管理
几何体共享：所有马模型共享同一个基础几何体

材质克隆：基础材质克隆后微调颜色，减少重复创建

动画状态共享：组内模型共享动画时间线

3. 视觉质量
抗锯齿：启用WebGL抗锯齿，边缘平滑

雾效：线性雾效增强场景深度感

高光反射：Phong材质提供真实的光照反应

响应式设计：适配不同分辨率和DPI的设备

🎮 交互体验
1. 控制方式
text
键盘控制：
- W: 前进
- A: 左移
- S: 后退
- D: 右移
- R: 上升
- F: 下降

鼠标控制：
- 移动: 旋转视角
- 无按钮限制: 任何状态下都可控制视角
2. 视觉反馈
实时阴影：所有物体动态投射和接收阴影

平滑动画：时间差(delta time)确保动画流畅

性能监控：左上角显示实时帧率(FPS)

深度提示：雾效和阴影共同提供空间深度感

🚀 技术亮点
1. 创新的动画优化方案
通过将大量动画对象分组管理，实现了数量级性能提升。传统方法（每个对象独立动画）需要600+次动画计算，而本方案仅需25次计算。

2. 专业的阴影实现
不仅实现了基础阴影，还通过：

阴影偏移解决自阴影问题

PCF过滤改善阴影边缘质量

合理的阴影相机参数避免无效计算

3. 生产级的错误处理
虽然演示代码简化了错误处理，但结构上支持完整的异步加载流程，包括成功、进度、失败三种回调状态。

4. 可扩展的架构设计
代码模块化清晰，易于：

替换模型（修改GLTF路径）

调整参数（修改常量和配置）

添加功能（在现有结构上扩展）

🔍 潜在优化方向
虽然当前实现已经很优秀，但还可以进一步优化：

LOD系统：根据距离使用不同细节级别的模型

遮挡剔除：完全被遮挡的马不参与渲染

GPU实例化：使用THREE.InstancedMesh进一步优化

Web Workers：动画计算移出主线程

压缩纹理：减少GLTF模型文件大小

📈 适用场景
这个演示项目展示了以下实际应用所需的技术：

游戏开发：大规模NPC群体动画

数据可视化：复杂3D场景渲染

建筑可视化：实时阴影和光照效果

虚拟现实：第一人称交互体验

技术演示：WebGL性能极限测试

💡 学习价值
对于学习Three.js的开发者，这个项目展示了：

高级动画管理：如何处理大量动画对象

阴影系统深度使用：从基础到优化的完整实现

性能优化实践：理论优化在实际项目中的应用

项目架构设计：大型Three.js项目的组织方式

用户体验考虑：控制、视觉反馈、性能监控的集成 -->


<!DOCTYPE html>
<html lang="zh-CN">  <!-- 将语言改为中文 -->
	<head>
		<!-- 
			页面标题标签：显示在浏览器标签页上的标题
			已改为中文：Three.js WebGL - 阴影映射演示
		-->
		<title>Three.js WebGL - 阴影映射演示</title>
		<!-- 
			字符编码声明：指定文档使用的字符编码为UTF-8
			UTF-8可以支持中文字符和多种语言字符
		-->
		<meta charset="utf-8">
		<!-- 
			视口(viewport)元标签：控制移动端浏览器如何显示页面
			width=device-width: 宽度等于设备宽度
			user-scalable=no: 禁止用户手动缩放页面（保持固定比例）
			minimum-scale=1.0: 最小缩放比例为1.0（100%）
			maximum-scale=1.0: 最大缩放比例为1.0（100%）
			这确保了在不同设备上有一致的视觉体验
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 
			外部CSS样式表链接：
			type="text/css": 指定链接的资源类型为CSS样式表
			rel="stylesheet": 定义当前文档与链接资源的关系为样式表
			href="main.css": 指定样式表文件的路径
			注意：这里的main.css文件需要与HTML文件在同一目录或正确路径下
		-->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>

	<body>
		<!-- 
			信息展示区域div：
			id="info": 为该div元素分配一个唯一的标识符"info"
			这个id可以用于CSS样式选择或JavaScript DOM操作
			内容已替换为中文：
			- Three.js链接：链接到Three.js官方网站
			- 项目说明：说明这是阴影映射演示，模型来自Mirada公司
			- 控制说明：告知用户如何使用WASD/RF键和鼠标控制相机
			注意：rel="noopener"是一种安全特性，防止新打开的页面访问原页面的window对象
		-->
		<div id="info">
			<!-- 
				<a>标签创建超链接：
				href="https://threejs.org": 链接的目标URL
				target="_blank": 在新标签页中打开链接
				rel="noopener": 安全特性，防止新页面通过window.opener访问原页面
				链接文本：Three.js官网
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js官网</a> 
			- 阴影映射演示 - 模型由 
			<!-- Mirada公司链接 -->
			<a href="https://mirada.com/" target="_blank" rel="noopener">Mirada公司</a> 
			提供，来自 
			<!-- Rome项目链接 -->
			<a href="http://www.ro.me" target="_blank" rel="noopener">Rome项目</a>
			<!-- <br />是HTML中的换行标签，表示在此处换行 -->
			<br />
			<!-- 操作说明文本 -->
			使用 W/A/S/D 键和 R/F 键 + 鼠标控制相机移动和视角
		</div>

		<!-- 
			导入映射(Import Map)配置：
			type="importmap": 这是一种新的Web标准，允许浏览器理解模块导入的映射关系
			它在现代浏览器中用于将模块标识符映射到实际的URL路径
			这对于使用ES模块的JavaScript应用非常重要
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module": 表示这是一个ES6模块
			ES6模块支持import/export语法，具有自己的作用域
			模块中的代码默认在严格模式下运行
			模块中的变量不会污染全局作用域
		-->
		<script type="module">

			// ========== 模块导入部分 ==========
			// 导入Three.js核心库的所有导出，并将其命名为THREE
			// THREE对象现在包含了Three.js的所有核心功能（如Scene、Camera、Renderer等）
			import * as THREE from 'three';

			// 导入性能统计监视器（Stats.js）
			// Stats.js是一个轻量级的JavaScript性能监视器，用于显示FPS（帧率）等性能指标
			import Stats from 'three/addons/libs/stats.module.js';

			// 导入第一人称控制器
			// 第一人称控制器允许用户像在第一人称射击游戏中一样控制相机
			import { FirstPersonControls } from 'three/addons/controls/FirstPersonControls.js';
			
			// 导入GLTF模型加载器
			// GLTF（GL Transmission Format）是一种开放的3D模型格式标准
			// GLTFLoader用于加载.glb或.gltf格式的3D模型文件
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// 导入字体加载器
			// FontLoader用于加载JSON格式的字体文件，用于创建3D文字
			import { FontLoader } from 'three/addons/loaders/FontLoader.js';
			
			// 导入文本几何体生成器
			// TextGeometry可以根据指定的字体和参数生成3D文字网格
			import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';

			// ========== 常量定义部分 ==========
			// 阴影贴图的分辨率设置
			// 阴影贴图的分辨率决定了阴影的质量，分辨率越高阴影越清晰，但性能消耗也越大
			// 这里宽度2048像素，高度1024像素是一个平衡性能和质量的值
			const SHADOW_MAP_WIDTH = 2048, SHADOW_MAP_HEIGHT = 1024;

			// 屏幕尺寸变量（初始化为当前窗口尺寸）
			// let声明表示这些变量后续会被重新赋值
			// window.innerWidth和window.innerHeight获取浏览器窗口的内部宽度和高度（不包括工具栏等）
			let SCREEN_WIDTH = window.innerWidth;
			let SCREEN_HEIGHT = window.innerHeight;
			
			// 地面高度常量
			// FLOOR表示场景中地面的Y轴坐标，所有地面相关的物体都基于这个值定位
			const FLOOR = -250;

			// 动画组数量常量
			// 这个值用于性能优化：将多个动画对象分组，减少动画系统的开销
			// 25组意味着所有动画对象会被分配到25个动画组中，每组共享相同的动画状态
			const ANIMATION_GROUPS = 25;

			// ========== 全局变量声明部分 ==========
			// Three.js核心对象变量声明
			// 这些变量将在init()函数中被初始化
			let camera,      // 相机对象：决定场景的观察视角
				controls,   // 控制器对象：处理用户输入控制相机
				scene,      // 场景对象：包含所有3D对象、灯光、雾效等
				renderer;   // 渲染器对象：负责将3D场景渲染到2D画布上
			
			let stats;      // 性能统计监视器实例

			// 相机近裁剪面和远裁剪面距离
			// 近裁剪面(NEAR)：相机能看到的最近距离，小于这个距离的对象不会被渲染
			// 远裁剪面(FAR)：相机能看到的最远距离，大于这个距离的对象不会被渲染
			// 这个范围称为视锥体(frustum)，只有在这个范围内的对象才会被渲染
			const NEAR = 5,     // 近裁剪面：5个单位
				  FAR = 3000;   // 远裁剪面：3000个单位

			// 动画相关变量
			let morph,      // 当前处理的morph目标对象（用于循环中）
				mixer;      // 动画混合器：管理场景中所有的动画
			
			// 数组声明：用于存储所有的morph对象和动画组
			const morphs = [],      // 存储所有morph动画对象的数组
				  animGroups = [];  // 存储所有动画组的数组

			// 创建Three.js的Clock对象
			// Clock用于跟踪时间，计算帧与帧之间的时间差(delta time)
			// 这对于实现与帧率无关的平滑动画非常重要
			const clock = new THREE.Clock();

			// ========== 函数调用部分 ==========
			// 调用初始化函数，启动整个应用
			init();

			// ========== 函数定义部分 ==========

			/**
			 * 初始化函数 - 整个Three.js应用的入口点
			 * 功能：创建和设置Three.js的所有核心组件
			 * 包括：容器、相机、场景、灯光、渲染器、控制器、性能监视器等
			 * 执行顺序严格按照代码顺序，确保依赖关系正确
			 */
			function init() {

				// ---------- 创建容器元素 ----------
				// 创建一个div元素作为Three.js渲染的容器
				// 这个div将包含canvas元素和性能监视器
				const container = document.createElement('div');
				// 将创建的div添加到body元素的末尾
				// appendChild是DOM API，用于将节点添加到指定父节点的子节点列表末尾
				document.body.appendChild(container);

				// ---------- 相机设置 ----------
				/**
				 * 创建透视相机(PerspectiveCamera)
				 * 参数说明：
				 * 1. fov (field of view): 视野角度，单位为度，这里23度提供较自然的视野
				 * 2. aspect: 宽高比，通常设置为屏幕宽度/屏幕高度
				 * 3. near: 近裁剪面距离，相机能看到的最近距离
				 * 4. far: 远裁剪面距离，相机能看到的最远距离
				 * 
				 * 透视相机模拟人眼的视觉效果，近大远小
				 */
				camera = new THREE.PerspectiveCamera(23, SCREEN_WIDTH / SCREEN_HEIGHT, NEAR, FAR);
				
				/**
				 * 设置相机初始位置
				 * position.set(x, y, z): 设置相机在3D空间中的坐标
				 * x: 水平方向（右为正）
				 * y: 垂直方向（上为正）
				 * z: 深度方向（屏幕外为正，屏幕内为负）
				 * 这里的位置(700, 50, 1900)让相机有一定高度，能看到较广的场景
				 */
				camera.position.set(700, 50, 1900);

				// ---------- 场景设置 ----------
				/**
				 * 创建场景对象
				 * Scene是Three.js中所有3D对象的容器
				 * 它包含了网格(Mesh)、灯光(Light)、雾(Fog)等所有可见元素
				 */
				scene = new THREE.Scene();
				
				/**
				 * 设置场景背景颜色
				 * 使用十六进制颜色值0x59472b（深棕色）
				 * 0x前缀表示十六进制数字
				 */
				scene.background = new THREE.Color(0x59472b);
				
				/**
				 * 添加雾效(Fog)
				 * Fog创建线性雾效，随着距离增加，物体逐渐融入雾色中
				 * 参数说明：
				 * 1. color: 雾的颜色，这里与背景色相同
				 * 2. near: 雾效开始的距离（1000单位）
				 * 3. far: 雾效完全遮盖物体的距离（3000单位，与相机远裁剪面相同）
				 * 雾效可以增强场景的深度感和氛围
				 */
				scene.fog = new THREE.Fog(0x59472b, 1000, FAR);

				// ---------- 光照设置 ----------
				/**
				 * 创建环境光(AmbientLight)
				 * 环境光为整个场景提供均匀的基础照明
				 * 它没有方向，所有面的亮度相同
				 * 参数：颜色(白色)
				 * 环境光不会产生阴影，主要用于提高暗部的可见度
				 */
				const ambient = new THREE.AmbientLight(0xffffff);
				scene.add(ambient);  // 将环境光添加到场景

				/**
				 * 创建方向光(DirectionalLight) - 主光源
				 * 方向光模拟太阳光，光线是平行的，来自同一方向
				 * 参数说明：
				 * 1. color: 光的颜色（白色）
				 * 2. intensity: 光的强度，默认1.0，这里3.0表示非常明亮
				 */
				const light = new THREE.DirectionalLight(0xffffff, 3);
				
				/**
				 * 设置光源位置
				 * 方向光的位置决定了光的方向
				 * 这里设置在场景上方(1500)和后方(1000)
				 */
				light.position.set(0, 1500, 1000);
				
				/**
				 * 启用阴影投射
				 * 方向光可以投射阴影，这是本演示的核心特性
				 */
				light.castShadow = true;
				
				/**
				 * 设置阴影相机(Shadow Camera)参数
				 * 阴影相机是一个正交相机(OrthographicCamera)，用于从光源视角渲染阴影贴图
				 * 它定义了一个立方体区域（阴影视锥体），只有在这个区域内的对象才会计算阴影
				 * 
				 * 参数说明（单位：世界单位）：
				 * top: 2000     - 上边界
				 * bottom: -2000 - 下边界
				 * left: -2000   - 左边界
				 * right: 2000   - 右边界
				 * 
				 * 这个4000x4000的区域足够覆盖场景中的主要对象
				 */
				light.shadow.camera.top = 2000;
				light.shadow.camera.bottom = -2000;
				light.shadow.camera.left = -2000;
				light.shadow.camera.right = 2000;
				
				/**
				 * 设置阴影相机的近裁剪面和远裁剪面
				 * near: 1200 - 阴影计算开始的距离
				 * far: 2500  - 阴影计算结束的距离
				 * 这个范围应该包含所有需要投射阴影的对象
				 */
				light.shadow.camera.near = 1200;
				light.shadow.camera.far = 2500;
				
				/**
				 * 设置阴影偏移(shadow bias)
				 * 阴影偏移用于解决阴影失真(shadow acne)问题
				 * 当值为0.0001时，表示将阴影稍微偏移一点，避免表面自阴影
				 * 太小会有阴影失真，太大会使阴影脱离对象
				 */
				light.shadow.bias = 0.0001;

				/**
				 * 设置阴影贴图的分辨率
				 * 阴影贴图是一张从光源视角渲染的深度纹理
				 * 分辨率越高，阴影边缘越清晰，但性能消耗越大
				 * 这里使用之前定义的常量SHADOW_MAP_WIDTH和SHADOW_MAP_HEIGHT
				 */
				light.shadow.mapSize.width = SHADOW_MAP_WIDTH;
				light.shadow.mapSize.height = SHADOW_MAP_HEIGHT;

				// 将方向光添加到场景
				scene.add(light);

				// ---------- 创建场景内容 ----------
				// 调用createScene函数创建地面、文字、模型等场景元素
				createScene();

				// ---------- 渲染器设置 ----------
				/**
				 * 创建WebGL渲染器(WebGLRenderer)
				 * WebGLRenderer使用WebGL API在canvas元素上渲染3D场景
				 * 参数对象：{ antialias: true } 启用抗锯齿，使边缘更平滑
				 */
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				/**
				 * 设置设备像素比(device pixel ratio)
				 * 这确保了在高DPI屏幕（如Retina显示屏）上清晰显示
				 * window.devicePixelRatio返回当前显示设备的物理像素与CSS像素的比值
				 */
				renderer.setPixelRatio(window.devicePixelRatio);
				
				/**
				 * 设置渲染器尺寸
				 * 使用当前屏幕的宽度和高度
				 * 这确保渲染器填满整个浏览器窗口
				 */
				renderer.setSize(SCREEN_WIDTH, SCREEN_HEIGHT);
				
				/**
				 * 设置动画循环
				 * setAnimationLoop是Three.js的动画循环方法
				 * 它内部使用requestAnimationFrame，在每次屏幕重绘时调用指定的函数
				 * 这里指定animate函数作为动画循环的回调函数
				 */
				renderer.setAnimationLoop(animate);
				
				/**
				 * 将渲染器的DOM元素(canvas)添加到容器中
				 * renderer.domElement是渲染器创建的canvas元素
				 * 所有3D内容都将绘制在这个canvas上
				 */
				container.appendChild(renderer.domElement);

				/**
				 * 禁用自动清除(autoClear)
				 * 默认情况下，渲染器会在每次渲染前自动清除颜色、深度和模板缓冲区
				 * 设置为false后，需要手动调用renderer.clear()
				 * 这提供了更灵活的控制，但在大多数情况下保持默认true即可
				 */
				renderer.autoClear = false;

				// ---------- 阴影映射设置 ----------
				/**
				 * 启用阴影映射
				 * 这告诉Three.js在渲染时计算阴影
				 * 需要同时在灯光和物体上启用阴影相关属性
				 */
				renderer.shadowMap.enabled = true;
				
				/**
				 * 设置阴影映射类型
				 * THREE.PCFShadowMap: 使用百分比渐近过滤(Percentage-Closer Filtering)
				 * 这种类型的阴影边缘更柔和，质量更好，但计算成本更高
				 * 其他选项：
				 * - THREE.BasicShadowMap: 基本阴影，性能好但边缘锯齿明显
				 * - THREE.PCFSoftShadowMap: 软阴影，边缘最柔和但性能消耗最大
				 */
				renderer.shadowMap.type = THREE.PCFShadowMap;

				// ---------- 控制器设置 ----------
				/**
				 * 创建第一人称控制器(FirstPersonControls)
				 * 参数说明：
				 * 1. camera: 要控制的相机对象
				 * 2. domElement: 监听输入事件的DOM元素（通常是渲染器的canvas）
				 * 
				 * 第一人称控制器提供类似FPS游戏的操控方式：
				 * - W/A/S/D键控制前后左右移动
				 * - 鼠标控制视角旋转
				 * - R/F键控制上升/下降
				 */
				controls = new FirstPersonControls(camera, renderer.domElement);

				/**
				 * 设置控制器参数
				 * lookSpeed: 视角旋转速度，值越大鼠标移动时视角变化越快
				 * movementSpeed: 移动速度，值越大按键移动时移动越快
				 * lookVertical: 是否允许垂直视角移动（抬头/低头）
				 */
				controls.lookSpeed = 0.0125;
				controls.movementSpeed = 500;
				controls.lookVertical = true;

				/**
				 * 设置控制器的观察目标点
				 * 第一人称控制器通常不需要明确的观察目标
				 * 这里设置为场景中心位置(0,0,0)
				 */
				controls.lookAt(scene.position);

				// ---------- 性能监视器设置 ----------
				/**
				 * 创建Stats.js性能监视器实例
				 * Stats.js会显示一个小面板，通常包括：
				 * - FPS: 帧率（帧每秒）
				 * - MS: 每帧渲染时间（毫秒）
				 * - MB: 内存使用情况
				 */
				stats = new Stats();
				
				/**
				 * 将性能监视器的DOM元素添加到容器中
				 * stats.dom是包含性能显示面板的div元素
				 * 默认位置在左上角，可以通过CSS调整位置
				 */
				container.appendChild(stats.dom);

				// ---------- 事件监听器设置 ----------
				/**
				 * 添加窗口大小调整事件监听器
				 * 当浏览器窗口大小改变时，调用onWindowResize函数
				 * 这确保Three.js渲染尺寸与窗口尺寸保持一致
				 */
				window.addEventListener('resize', onWindowResize);

				// 至此，Three.js应用初始化完成，即将进入动画循环
			}

			/**
			 * 窗口大小调整事件处理函数
			 * 功能：当浏览器窗口大小改变时，更新Three.js的相关设置
			 * 确保渲染内容始终正确适应窗口尺寸
			 */
			function onWindowResize() {

				// 更新屏幕尺寸变量为新的窗口尺寸
				SCREEN_WIDTH = window.innerWidth;
				SCREEN_HEIGHT = window.innerHeight;

				/**
				 * 更新相机宽高比(aspect ratio)
				 * 相机宽高比需要与窗口宽高比保持一致，否则渲染会变形
				 */
				camera.aspect = SCREEN_WIDTH / SCREEN_HEIGHT;
				
				/**
				 * 更新相机投影矩阵
				 * 当相机参数（如宽高比）改变后，必须调用此方法重新计算投影矩阵
				 * 投影矩阵定义了3D空间如何映射到2D屏幕
				 */
				camera.updateProjectionMatrix();

				/**
				 * 更新渲染器尺寸
				 * 设置渲染器canvas的尺寸与窗口新尺寸一致
				 * 同时会更新渲染器的视口(viewport)设置
				 */
				renderer.setSize(SCREEN_WIDTH, SCREEN_HEIGHT);

				/**
				 * 通知控制器窗口尺寸已改变
				 * 控制器可能需要根据新尺寸调整内部计算
				 */
				controls.handleResize();
			}

			/**
			 * 创建场景内容函数
			 * 功能：向场景中添加具体的3D对象，包括地面、文字、立方体和模型
			 * 这个函数在init()中调用，在场景初始化后执行
			 */
			function createScene() {

				// ---------- 创建地面 ----------
				/**
				 * 创建平面几何体(PlaneGeometry)
				 * 参数说明：width, height, widthSegments, heightSegments
				 * 这里创建一个100x100单位的平面，没有分段（默认1x1）
				 */
				const geometry = new THREE.PlaneGeometry(100, 100);
				
				/**
				 * 创建Phong网格材质(MeshPhongMaterial)
				 * Phong材质支持高光反射，可以产生光泽效果
				 * 参数：{ color: 0xffdd99 } 设置材质颜色为浅橙色
				 */
				const planeMaterial = new THREE.MeshPhongMaterial({ color: 0xffdd99 });

				/**
				 * 创建地面网格对象(Mesh)
				 * Mesh是Three.js中可见对象的基本单位，由几何体和材质组成
				 */
				const ground = new THREE.Mesh(geometry, planeMaterial);

				/**
				 * 设置地面位置
				 * 将地面的Y坐标设置为FLOOR常量（-250）
				 * X和Z坐标设为0，使地面位于场景中心
				 */
				ground.position.set(0, FLOOR, 0);
				
				/**
				 * 旋转地面
				 * 默认情况下，PlaneGeometry创建的平面是垂直的
				 * 绕X轴旋转-90度（-π/2弧度）使其变为水平面
				 */
				ground.rotation.x = -Math.PI / 2;
				
				/**
				 * 缩放地面
				 * 将地面放大100倍，变为10000x10000单位的大平面
				 * 这确保地面足够大，能够覆盖整个可见区域
				 */
				ground.scale.set(100, 100, 100);

				/**
				 * 设置地面的阴影属性
				 * castShadow: false - 地面不投射阴影（节省性能，地面通常不需要投射阴影）
				 * receiveShadow: true - 地面接收其他物体投射的阴影
				 */
				ground.castShadow = false;
				ground.receiveShadow = true;

				// 将地面添加到场景
				scene.add(ground);

				// ---------- 创建3D文字 ----------
				/**
				 * 创建字体加载器(FontLoader)实例
				 * 字体加载器用于加载Three.js专用的JSON格式字体文件
				 */
				const loader = new FontLoader();
				
				/**
				 * 异步加载字体文件
				 * load方法参数：
				 * 1. url: 字体文件的路径（'fonts/helvetiker_bold.typeface.json'）
				 * 2. onLoad: 加载成功时的回调函数，接收加载的字体对象作为参数
				 * 3. onProgress: 加载进度回调（可选）
				 * 4. onError: 加载失败回调（可选）
				 */
				loader.load('fonts/helvetiker_bold.typeface.json', function(font) {
					/**
					 * 字体加载成功后的回调函数
					 * font参数是加载的字体对象，包含字形信息
					 */

					/**
					 * 创建文本几何体(TextGeometry)
					 * 参数说明：
					 * 1. text: 要生成的文字内容（'THREE.JS'）
					 * 2. parameters: 配置对象
					 *    - font: 使用的字体对象
					 *    - size: 字体大小（200单位）
					 *    - depth: 挤出深度（50单位），使文字有厚度
					 *    - curveSegments: 曲线分段数（12），值越高曲线越平滑
					 *    - bevelThickness: 倒角厚度（2）
					 *    - bevelSize: 倒角大小（5）
					 *    - bevelEnabled: 是否启用倒角（true）
					 * 
					 * 倒角(bevel)是在文字边缘创建的斜面，使文字看起来更精致
					 */
					const textGeo = new TextGeometry('THREE.JS', {
						font: font,              // 使用加载的字体
						size: 200,               // 字体大小
						depth: 50,               // 挤出深度
						curveSegments: 12,       // 曲线分段数

						bevelThickness: 2,       // 倒角厚度
						bevelSize: 5,            // 倒角大小
						bevelEnabled: true       // 启用倒角
					});

					/**
					 * 计算文本几何体的边界框(bounding box)
					 * 边界框是包含整个几何体的最小轴对齐长方体
					 * 用于快速进行碰撞检测、视锥体裁剪等计算
					 */
					textGeo.computeBoundingBox();
					
					/**
					 * 计算文字居中的偏移量
					 * 默认情况下，文字的左边缘在原点(0,0,0)
					 * 通过计算文字宽度的一半，然后取负值，可以使文字中心对齐原点
					 * boundingBox.max.x - boundingBox.min.x 得到文字的宽度
					 */
					const centerOffset = -0.5 * (textGeo.boundingBox.max.x - textGeo.boundingBox.min.x);

					/**
					 * 创建文字材质
					 * 使用Phong材质，颜色为红色(0xff0000)，高光为白色
					 * specular属性控制高光反射的颜色和强度
					 */
					const textMaterial = new THREE.MeshPhongMaterial({ color: 0xff0000, specular: 0xffffff });

					/**
					 * 创建文字网格对象
					 * 将文本几何体和材质组合成可见的网格对象
					 */
					const mesh = new THREE.Mesh(textGeo, textMaterial);
					
					/**
					 * 设置文字位置
					 * x: 使用计算出的居中偏移量，使文字水平居中
					 * y: 在地面高度(FLOOR)基础上加67单位，使文字浮在地面上方
					 * z: 默认为0，位于场景中心深度
					 */
					mesh.position.x = centerOffset;
					mesh.position.y = FLOOR + 67;

					/**
					 * 设置文字的阴影属性
					 * castShadow: true - 文字投射阴影
					 * receiveShadow: true - 文字接收阴影
					 * 这使文字与其他物体产生阴影交互，增强立体感
					 */
					mesh.castShadow = true;
					mesh.receiveShadow = true;

					// 将文字网格添加到场景
					scene.add(mesh);

				}); // 字体加载回调函数结束

				// ---------- 创建立方体平台 ----------
				/**
				 * 创建第一个立方体平台
				 * BoxGeometry参数：width, height, depth, widthSegments, heightSegments, depthSegments
				 * 这里创建1500x220x150的长方体，作为文字下方的平台
				 */
				const cubes1 = new THREE.Mesh(new THREE.BoxGeometry(1500, 220, 150), planeMaterial);

				// 设置位置：Y坐标比地面低50单位，Z坐标为20（稍微靠前）
				cubes1.position.y = FLOOR - 50;
				cubes1.position.z = 20;

				// 设置阴影属性
				cubes1.castShadow = true;    // 立方体投射阴影
				cubes1.receiveShadow = true; // 立方体接收阴影

				// 添加到场景
				scene.add(cubes1);

				/**
				 * 创建第二个立方体平台
				 * 尺寸稍大：1600x170x250
				 * 与第一个立方体重叠，创建层次感
				 */
				const cubes2 = new THREE.Mesh(new THREE.BoxGeometry(1600, 170, 250), planeMaterial);

				// 位置与第一个立方体相同，但尺寸不同，形成嵌套效果
				cubes2.position.y = FLOOR - 50;
				cubes2.position.z = 20;

				// 设置阴影属性
				cubes2.castShadow = true;
				cubes2.receiveShadow = true;

				// 添加到场景
				scene.add(cubes2);

				// ---------- 动画系统初始化 ----------
				/**
				 * 创建动画混合器(AnimationMixer)
				 * 动画混合器是Three.js动画系统的核心，管理场景中所有的动画剪辑
				 * 参数：rootObject - 动画的根对象，通常是场景或包含动画对象的父对象
				 */
				mixer = new THREE.AnimationMixer(scene);

				/**
				 * 创建动画对象组(AnimationObjectGroup)
				 * 动画对象组允许多个对象共享相同的动画状态，这是重要的性能优化手段
				 * 
				 * 原理：将600多个马模型分配到25个动画组中，每组约24个模型
				 * 每组只计算一次动画，然后应用到组内所有对象，大大减少计算量
				 * 
				 * 如果没有分组，每个马模型都需要单独计算动画，性能消耗巨大
				 */
				for (let i = 0; i !== ANIMATION_GROUPS; ++i) {
					// 创建新的动画组
					const group = new THREE.AnimationObjectGroup();
					// 将组添加到animGroups数组，便于后续访问
					animGroups.push(group);
				}

				// ---------- Morph动画模型加载 ----------

				/**
				 * 添加Morph动画对象的辅助函数
				 * 这个函数负责克隆、配置和添加单个Morph动画对象到场景
				 * 它被设计为可重用的，可以创建多个相似的动画对象
				 * 
				 * @param {THREE.Mesh} mesh - 原始网格对象（将被克隆）
				 * @param {THREE.AnimationClip} clip - 动画剪辑，包含动画数据
				 * @param {number} speed - 对象的移动速度（单位/秒）
				 * @param {number} duration - 动画持续时间（秒）
				 * @param {number} x - 初始X轴位置
				 * @param {number} y - 初始Y轴位置
				 * @param {number} z - 初始Z轴位置
				 * @param {boolean} fudgeColor - 是否随机调整颜色（增加变化性）
				 * @param {boolean} massOptimization - 是否使用批量优化（分组动画）
				 */
				function addMorph(mesh, clip, speed, duration, x, y, z, fudgeColor, massOptimization) {

					/**
					 * 克隆网格对象和材质
					 * 必须克隆以避免多个对象共享相同的几何体和材质引用
					 * 如果不克隆，修改一个对象会影响所有使用相同几何体/材质的对象
					 * 
					 * mesh.clone(): 浅克隆网格对象，但共享几何体和材质
					 * mesh.material.clone(): 深度克隆材质，创建独立的材质实例
					 */
					mesh = mesh.clone();
					mesh.material = mesh.material.clone();

					/**
					 * 如果启用了颜色随机化(fudgeColor)
					 * 为材质颜色添加随机色相(H)和亮度(L)偏移
					 * 使每个马模型有轻微的颜色差异，增加视觉多样性
					 * 
					 * offsetHSL参数：
					 * h: 色相偏移（0表示不变，这里保持0）
					 * s: 饱和度偏移（-0.25到+0.25的随机值）
					 * l: 亮度偏移（-0.25到+0.25的随机值）
					 */
					if (fudgeColor) {
						// 随机调整饱和度和亮度，保持色相不变
						mesh.material.color.offsetHSL(0, Math.random() * 0.5 - 0.25, Math.random() * 0.5 - 0.25);
					}

					/**
					 * 存储移动速度
					 * 将速度值直接附加到网格对象上，便于在渲染循环中访问
					 * 这不是Three.js的标准属性，而是自定义属性
					 */
					mesh.speed = speed;

					/**
					 * 批量优化模式：将对象分组到动画组中
					 * 这是本演示的关键性能优化
					 */
					if (massOptimization) {

						/**
						 * 随机选择一个动画组
						 * Math.random()返回0到1之间的随机数（含0不含1）
						 * Math.floor()向下取整，得到0到ANIMATION_GROUPS-1的整数
						 */
						const index = Math.floor(Math.random() * ANIMATION_GROUPS);
						// 获取对应的动画组对象
						const animGroup = animGroups[index];

						/**
						 * 将当前网格对象添加到动画组
						 * 动画组现在会管理这个对象的动画状态
						 */
						animGroup.add(mesh);

						/**
						 * 检查动画组是否已经有这个动画剪辑的动作
						 * 如果还没有，为动画组创建新的动画动作
						 * 
						 * mixer.existingAction(clip, root): 
						 * 检查是否已经为指定的剪辑和根对象创建了动作
						 */
						if (!mixer.existingAction(clip, animGroup)) {

							/**
							 * 为动画添加随机性
							 * randomness: -0.3到+0.3的随机值
							 * 这使不同组的动画有轻微的时间偏移，避免所有马同步移动
							 */
							const randomness = 0.6 * Math.random() - 0.3;
							
							/**
							 * 计算动画相位(phase)
							 * 将组索引加上随机性，然后除以总组数
							 * 得到0到1之间的相位值，表示动画开始的时间点
							 */
							const phase = (index + randomness) / ANIMATION_GROUPS;

							/**
							 * 创建并配置动画动作(AnimationAction)
							 * mixer.clipAction(clip, root): 为指定的剪辑和根对象创建动作
							 * 
							 * 方法链：
							 * .setDuration(duration): 设置动画持续时间为指定值
							 * .startAt(-duration * phase): 设置动画开始时间偏移
							 *   - 负值表示动画从中间开始，而不是从开头
							 *   - 乘以相位确保不同组在不同时间点开始
							 * .play(): 开始播放动画
							 */
							mixer.clipAction(clip, animGroup)
								.setDuration(duration)          // 设置动画时长
								.startAt(-duration * phase)    // 设置起始时间偏移
								.play();                       // 播放动画
						}

					} else {
						/**
						 * 非优化模式：为每个对象单独创建动画动作
						 * 这种模式更简单，但性能较差，适合对象数量少的情况
						 */
						mixer.clipAction(clip, mesh)     // 为单个网格创建动作
							.setDuration(duration)       // 设置时长
							.startAt(-duration * Math.random())  // 随机起始时间
							.play();                     // 播放
					}

					/**
					 * 设置网格的位置和旋转
					 * position.set(x, y, z): 使用传入的位置参数
					 * rotation.y = Math.PI / 2: 绕Y轴旋转90度（π/2弧度）
					 * 这使马模型面向正确的方向
					 */
					mesh.position.set(x, y, z);
					mesh.rotation.y = Math.PI / 2;

					/**
					 * 设置阴影属性
					 * 所有马模型都投射和接收阴影
					 */
					mesh.castShadow = true;
					mesh.receiveShadow = true;

					/**
					 * 将网格添加到场景
					 */
					scene.add(mesh);

					/**
					 * 将网格添加到morphs数组
					 * 这个数组用于在渲染循环中更新所有马的位置
					 */
					morphs.push(mesh);
				}

				// ---------- 加载GLTF模型并创建多个实例 ----------
				/**
				 * 创建GLTFLoader实例
				 * GLTFLoader是Three.js中加载GLTF/GLB格式模型的专用加载器
				 */
				const gltfLoader = new GLTFLoader();
				
				/**
				 * 异步加载马模型
				 * 加载完成后，创建多个马模型实例并设置动画
				 */
				gltfLoader.load('models/gltf/Horse.glb', function(gltf) {
					/**
					 * 加载成功回调函数
					 * gltf参数包含加载的模型数据和动画
					 */

					/**
					 * 获取模型中的网格对象
					 * gltf.scene是加载的3D场景，可能包含多个对象
					 * children[0]获取第一个（通常是唯一的一个）子对象
					 */
					const mesh = gltf.scene.children[0];
					
					/**
					 * 获取模型中的动画剪辑
					 * gltf.animations是包含所有动画剪辑的数组
					 * 马模型通常只有一个动画剪辑（奔跑动画）
					 */
					const clip = gltf.animations[0];

					/**
					 * 创建大量马模型实例
					 * 循环从Z轴-600到600，间隔2单位，共约600个马模型
					 * 
					 * 循环说明：
					 * let i = -600: 起始Z坐标
					 * i < 601: 结束条件（包含600）
					 * i += 2: 每次循环增加2，控制马的密度
					 */
					for (let i = -600; i < 601; i += 2) {
						/**
						 * 为每个位置创建一个马模型实例
						 * 参数详解：
						 * 1. mesh: 原始马网格
						 * 2. clip: 奔跑动画剪辑
						 * 3. 550: 移动速度（550单位/秒）
						 * 4. 1: 动画持续时间（1秒）
						 * 5. 100 - Math.random() * 3000: X位置（-2900到100之间的随机值）
						 *    - Math.random()返回0-1的随机数
						 *    - Math.random() * 3000得到0-3000的随机数
						 *    - 100 - 随机数得到-2900到100的随机数
						 * 6. FLOOR: Y位置（地面高度）
						 * 7. i: Z位置（循环变量，-600到600）
						 * 8. true: 启用颜色随机化
						 * 9. true: 启用批量优化（使用动画组）
						 */
						addMorph(mesh, clip, 550, 1, 100 - Math.random() * 3000, FLOOR, i, true, true);
					}

				}); // GLTF加载回调结束

				// 至此，场景内容创建完成
			}

			/**
			 * 动画循环函数
			 * 功能：由requestAnimationFrame驱动，每帧调用一次
			 * 这是Three.js应用的核心循环，负责更新和渲染
			 * 注意：这个函数本身不执行更新逻辑，它只是统计性能和调用render函数
			 */
			function animate() {
				/**
				 * 开始性能统计
				 * stats.begin()记录当前时间，用于计算帧率和渲染时间
				 */
				stats.begin();
				
				/**
				 * 执行渲染
				 * render()函数包含实际的场景更新和渲染逻辑
				 */
				render();
				
				/**
				 * 结束性能统计
				 * stats.end()计算从begin()到现在的时间差
				 * 并更新性能监视器显示
				 */
				stats.end();
			}

			/**
			 * 渲染函数
			 * 功能：每帧更新动画状态、对象位置，并渲染场景
			 * 这是动画循环的核心逻辑
			 */
			function render() {

				/**
				 * 获取时间差(delta time)
				 * clock.getDelta()返回自上一次调用getDelta()以来经过的时间（秒）
				 * 使用时间差而不是固定值可以使动画速度与帧率无关
				 * 无论帧率高还是低，动画速度都保持一致
				 */
				const delta = clock.getDelta();

				/**
				 * 更新动画混合器
				 * 如果mixer存在（已初始化），使用时间差更新所有动画
				 * mixer.update(delta)会根据时间差推进所有动画的状态
				 */
				if (mixer) mixer.update(delta);

				/**
				 * 更新所有马模型的位置（水平移动）
				 * 循环遍历morphs数组中的每个马模型
				 */
				for (let i = 0; i < morphs.length; i++) {
					// 获取当前马模型
					morph = morphs[i];

					/**
					 * 更新马的位置
					 * 根据马的速度(morph.speed)和时间差(delta)计算位移
					 * 公式：位移 = 速度 × 时间
					 * 马沿着X轴正方向（右方）移动
					 */
					morph.position.x += morph.speed * delta;

					/**
					 * 边界检查：如果马移出右边界，重置到左边界
					 * 这里右边界是X=2000，左边界是X=-1000到-1500之间的随机位置
					 * 
					 * 逻辑：
					 * 如果X坐标大于2000，说明马已经跑出屏幕右侧
					 * 将其重置到屏幕左侧（X=-1000到-1500），形成循环效果
					 */
					if (morph.position.x > 2000) {
						// 重置位置：-1000加上-500到0的随机偏移
						morph.position.x = -1000 - Math.random() * 500;
					}
				}

				/**
				 * 更新控制器
				 * controls.update(delta)处理用户输入，更新相机位置和方向
				 * 参数delta确保相机移动速度与帧率无关
				 */
				controls.update(delta);

				/**
				 * 手动清除渲染缓冲区
				 * 由于之前设置了renderer.autoClear = false
				 * 这里需要手动清除颜色、深度和模板缓冲区
				 * 为新的帧渲染做准备
				 */
				renderer.clear();
				
				/**
				 * 渲染场景
				 * renderer.render(scene, camera)是Three.js的核心渲染方法
				 * 它将3D场景从指定相机的视角渲染到2D画布上
				 * 包括：几何体、材质、灯光、阴影等所有可见元素
				 */
				renderer.render(scene, camera);
			}

		</script>
		<!-- 主JavaScript模块结束 -->

	</body>
</html>