<!-- Three.js 阴影映射演示项目 - 功能与技术点详解
一、项目功能概述
1. 核心演示功能
这是一个实时3D阴影映射技术演示，展示Three.js在WebGL环境下实现高质量动态阴影的能力。项目创建了一个包含多种3D元素的场景，所有物体都投射和接收实时计算的阴影。

2. 主要视觉元素
立体文字：红色的"THREE.JS"文字，具有3D挤出效果和斜角

地面平台：浅橙色的广阔地面，作为阴影接收面

几何体结构：两个大型立方体作为主要阴影投射体

动物模型群：马、火烈鸟、鹳、鹦鹉四种带动画的动物模型

动态光照：模拟太阳光的平行光源产生方向性阴影

3. 交互功能
相机控制：鼠标拖拽旋转视角，滚轮缩放

调试视图：按T键切换阴影贴图可视化（HUD显示）

自适应窗口：响应浏览器窗口大小变化

二、主要技术点详解
1. 阴影映射技术（核心）
1.1 阴影实现原理
javascript
// 关键配置
light.castShadow = true;  // 启用阴影投射
renderer.shadowMap.enabled = true;  // 启用阴影映射
renderer.shadowMap.type = THREE.PCFShadowMap;  // PCF软阴影算法
技术流程：

阴影相机渲染：从光源视角渲染场景深度到阴影贴图

深度比较：在主渲染时，比较片段与阴影贴图的深度值

PCF滤波：进行百分比渐近滤波，产生柔和阴影边缘

1.2 阴影质量优化
javascript
// 阴影贴图分辨率（影响阴影清晰度）
light.shadow.mapSize.width = 2048;   // 宽度
light.shadow.mapSize.height = 1024;  // 高度

// 阴影偏移（解决阴影痤疮问题）
light.shadow.bias = 0.0001;

// 阴影相机视锥体（控制阴影渲染范围）
light.shadow.camera.top = 2000;
light.shadow.camera.bottom = -2000;
// ...其他边界设置
2. 3D模型与动画系统
2.1 GLTF模型加载
javascript
const gltfloader = new GLTFLoader();
gltfloader.load('models/gltf/Horse.glb', function (gltf) {
    const mesh = gltf.scene.children[0];  // 获取模型网格
    const clip = gltf.animations[0];      // 获取动画片段
});
GLTF优势：

专为Web设计的3D格式

支持网格、材质、纹理、动画、骨骼

文件体积小，加载速度快

2.2 动画混合器（AnimationMixer）
javascript
// 创建动画混合器
mixer = new THREE.AnimationMixer(scene);

// 为模型创建动画动作
const action = mixer.clipAction(clip, mesh)
    .setDuration(1)                    // 动画时长
    .startAt(-1 * Math.random())      // 随机起始时间
    .play();                          // 开始播放
动画特性：

变形动画：动物模型的行走/飞行动画

相位随机化：错开动画起始时间，增加自然感

与帧率无关：使用时间增量(delta time)

2.3 模型实例化与优化
javascript
// 克隆模型而不是重复加载
mesh = mesh.clone();
mesh.material = mesh.material.clone();

// 随机化颜色
mesh.material.color.offsetHSL(0, Math.random()*0.5-0.25, Math.random()*0.5-0.25);
3. 渲染与性能优化
3.1 渲染器配置
javascript
renderer = new THREE.WebGLRenderer({
    antialias: true,              // 抗锯齿
    reversedDepthBuffer: true     // 反向深度缓冲
});
性能优化技术：

反向深度缓冲：提高深度测试精度，解决z-fighting

抗锯齿：平滑几何边缘

雾效：隐藏远处物体，减少渲染负载

3.2 动画循环优化
javascript
// 使用时间增量确保动画速度一致
const delta = clock.getDelta();
mixer.update(delta);

// 模型位置更新（与帧率无关）
morph.position.x += morph.speed * delta;
4. 相机与控制系统
4.1 透视相机设置
javascript
camera = new THREE.PerspectiveCamera(
    23,                             // 视野角度(FOV)
    SCREEN_WIDTH / SCREEN_HEIGHT,   // 宽高比
    10,                             // 近裁剪面
    3000                            // 远裁剪面
);
4.2 轨道控制器
javascript
controls = new OrbitControls(camera, renderer.domElement);
controls.enablePan = false;                     // 禁用平移
controls.maxPolarAngle = Math.PI / 2;           // 限制垂直旋转
controls.minDistance = 200;                     // 最小缩放距离
controls.maxDistance = 2200;                    // 最大缩放距离
5. 场景构建技术
5.1 3D文字生成
javascript
const textGeo = new TextGeometry('THREE.JS', {
    font: font,            // 加载的字体
    size: 200,             // 字体大小
    depth: 50,             // 挤出深度
    bevelEnabled: true,    // 启用斜角
    bevelThickness: 2,     // 斜角厚度
    bevelSize: 5           // 斜角大小
});
5.2 雾效系统
javascript
scene.fog = new THREE.Fog(0x59472b, 1000, 3000);
作用：

增强场景深度感和距离感

性能优化：远处物体被雾遮挡，减少细节渲染

6. 调试与开发工具
6.1 阴影贴图查看器
javascript
lightShadowMapViewer = new ShadowMapViewer(light);
// 位置和尺寸配置
lightShadowMapViewer.position.x = 10;
lightShadowMapViewer.size.width = SHADOW_MAP_WIDTH / 4;
6.2 性能监控
javascript
import Stats from 'three/addons/libs/stats.module.js';
const stats = new Stats();
// 显示FPS、渲染时间等指标（默认注释）
7. 现代JavaScript特性
7.1 ES6模块系统
javascript
// 使用import/export语法
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
7.2 Import Maps（浏览器原生模块映射）
html
<script type="importmap">
{
    "imports": {
        "three": "../build/three.module.js",
        "three/addons/": "./jsm/"
    }
}
</script>
三、技术亮点总结
1. 高质量的实时阴影
PCF软阴影算法，边缘柔和自然

可调节的阴影质量和性能平衡

阴影偏移优化，避免失真问题

2. 高效的动画系统
GLTF变形动画支持

动画混合器统一管理

实例化复用模型资源

3. 完善的交互体验
流畅的相机控制

实用的调试工具

响应式设计

4. 良好的代码架构
模块化组织

清晰的函数职责分离

充分的代码注释

5. 性能优化考虑
与帧率无关的动画

雾效减少渲染负载

适当的质量/性能平衡设置

四、适用场景
技术演示：展示Three.js阴影映射能力

学习参考：Three.js高级功能学习案例

性能测试：阴影渲染性能基准测试

功能原型：3D交互应用的概念验证

五、扩展可能性
增加阴影类型：支持VSM、CSM等高级阴影算法

添加后期处理：Bloom、SSAO等后处理效果

物理系统集成：添加碰撞检测和物理模拟

多光源支持：实现多光源阴影混合

动态天气系统：实时变化的光照和阴影效果 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：显示Three.js阴影映射演示
			UTF-8编码确保中文正常显示
			视口设置：适配移动设备，禁止用户缩放
		-->
		<title>Three.js WebGL - 阴影映射演示</title>
		<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="main.css">
	</head>

	<body>

		<!-- 
			信息面板：显示项目信息和操作说明
			id="info" 用于CSS样式或JavaScript操作
		-->
		<div id="info">
			<!-- 
				项目信息链接：
				1. Three.js官网链接
				2. 模型提供方链接
				3. 来源项目链接
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 阴影映射演示 - 模型由 <a href="https://mirada.com/" target="_blank" rel="noopener">Mirada工作室</a> 提供，来自项目 <a href="http://www.ro.me" target="_blank" rel="noopener">ROME</a><br />
			<!-- 操作提示：使用t键切换HUD（头部显示）的显示与隐藏 -->
			按 T 键：切换HUD（阴影贴图调试视图）显示/隐藏<br />
			<!-- 鼠标操作提示：控制相机视角 -->
			鼠标左键拖拽：旋转视角，鼠标滚轮：缩放视图
		</div>

		<!-- 
			Import Maps：现代浏览器支持的模块导入映射系统
			作用：将模块名称映射到具体的文件路径
			注意：这是一个相对较新的浏览器功能，需要现代浏览器支持
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module"表示这是一个ES6模块，支持import/export语法
			模块具有自己的作用域，不会污染全局命名空间
		-->
		<script type="module">

			// ============================================
			// 模块导入部分
			// ============================================
			
			// 导入Three.js核心库的所有功能
			// * as THREE 表示将整个模块重命名为THREE对象
			import * as THREE from 'three';

			// 导入Stats.js性能监控工具
			// 用于显示帧率(FPS)、渲染时间等性能指标
			import Stats from 'three/addons/libs/stats.module.js';

			// 导入轨道控制器：允许用户用鼠标拖拽来旋转、平移、缩放相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入GLTF加载器：用于加载.glb/.gltf格式的3D模型文件
			// GLTF是3D模型的"JPEG格式"，广泛用于WebGL应用
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			// 导入字体加载器：用于加载JSON格式的字体文件
			// 这些字体文件通常使用Typeface.js或Facetype.js工具生成
			import { FontLoader } from 'three/addons/loaders/FontLoader.js';
			// 导入文本几何体生成器：根据字体创建3D文本几何体
			import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';
			// 导入阴影贴图查看器：用于调试和可视化阴影贴图
			// 可以将阴影贴图渲染为2D图像在屏幕上显示
			import { ShadowMapViewer } from 'three/addons/utils/ShadowMapViewer.js';

			// ============================================
			// 全局常量定义
			// ============================================
			
			// 阴影贴图尺寸常量：影响阴影的质量和性能
			// 较大的尺寸提供更清晰的阴影，但消耗更多GPU内存和性能
			const SHADOW_MAP_WIDTH = 2048;   // 阴影贴图宽度（像素）
			const SHADOW_MAP_HEIGHT = 1024;  // 阴影贴图高度（像素）

			// 获取当前窗口的尺寸，用于设置渲染器大小和相机宽高比
			const SCREEN_WIDTH = window.innerWidth;   // 屏幕宽度（像素）
			const SCREEN_HEIGHT = window.innerHeight; // 屏幕高度（像素）
			
			// 地板高度常量：场景中所有地面对象的基础Y坐标
			// 负值表示地板位于世界坐标系的原点以下
			const FLOOR = -250;

			// ============================================
			// 全局变量声明
			// ============================================
			
			// Three.js核心对象
			let camera;      // 相机：决定场景的观察视角和投影方式
			let controls;    // 控制器：处理用户输入，控制相机
			let scene;       // 场景：包含所有3D对象、灯光、相机的容器
			let renderer;    // 渲染器：负责将3D场景绘制到2D画布上
			
			// DOM元素和工具
			let container;   // HTML容器元素，用于包含Three.js画布
			let stats;       // Stats.js实例，用于性能监控

			// 相机裁剪面常量：定义可见范围的近处和远处边界
			// 任何比NEAR更近或比FAR更远的物体都不会被渲染
			const NEAR = 10;     // 近裁剪面：相机前方10个单位
			const FAR = 3000;    // 远裁剪面：相机前方3000个单位

			// 动画相关变量
			let mixer;      // 动画混合器：管理和混合多个动画
			const morphs = []; // 存储所有变形动画模型的数组

			// 光照和阴影相关
			let light;                      // 主方向光，产生阴影
			let lightShadowMapViewer;       // 阴影贴图查看器实例

			// 时间管理：用于计算帧间时间差，实现与帧率无关的动画
			const clock = new THREE.Clock();

			// HUD显示状态标志：控制阴影调试视图的显示/隐藏
			let showHUD = false;

			// ============================================
			// 初始化函数调用
			// ============================================
			init();

			/**
			 * 初始化函数 - 整个应用的入口点
			 * 作用：创建和设置Three.js的所有核心组件
			 * 执行顺序：场景→相机→灯光→几何体→材质→渲染器→控制器→事件监听
			 */
			function init() {

				// 创建容器div元素并添加到body
				// 这个容器将包含Three.js的渲染画布
				container = document.createElement('div');
				document.body.appendChild(container);

				// ========== 相机设置 ==========
				// 使用透视相机（PerspectiveCamera）：模拟人眼视角，近大远小
				camera = new THREE.PerspectiveCamera(
					23,                                  // 视野角度（Field of View, FOV）
					                                    // 单位：度，较小的值产生望远镜效果，较大的值产生鱼眼效果
					SCREEN_WIDTH / SCREEN_HEIGHT,        // 宽高比：确保渲染内容不被拉伸
					NEAR,                                // 近裁剪面：相机前方10个单位以内的物体不渲染
					FAR                                  // 远裁剪面：相机前方3000个单位以外的物体不渲染
				);
				// 设置相机初始位置：(x, y, z)坐标
				// x=700：相机在X轴（左右方向）偏右700单位
				// y=50：相机在Y轴（上下方向）偏上50单位
				// z=1900：相机在Z轴（前后方向）偏后1900单位
				camera.position.set(700, 50, 1900);

				// ========== 场景设置 ==========
				// 创建场景对象：所有3D对象的容器
				scene = new THREE.Scene();
				
				// 设置场景背景颜色：使用十六进制颜色值（深棕色）
				// 0x表示十六进制，59472b是RGB颜色值
				scene.background = new THREE.Color(0x59472b);
				
				// 添加雾效：增强场景的深度感和距离感
				// 参数：雾的颜色、雾开始的距离、雾完全覆盖的距离
				scene.fog = new THREE.Fog(0x59472b, 1000, FAR);

				// ========== 灯光设置 ==========
				// 环境光：均匀照亮整个场景，没有方向性，不产生阴影
				// 参数：光的颜色，光的强度（可选，默认1）
				const ambient = new THREE.AmbientLight(0xffffff);
				scene.add(ambient);

				// 平行光：模拟太阳光，所有光线平行，产生清晰的阴影
				// 参数：光的颜色，光的强度（3表示比环境光亮3倍）
				light = new THREE.DirectionalLight(0xffffff, 3);
				
				// 设置光源位置：模拟从左上后方照射的光源
				light.position.set(0, 1500, 1000);
				
				// 启用阴影投射：这个光源会产生阴影
				light.castShadow = true;
				
				// 阴影相机参数设置：
				// 阴影贴图是通过一个虚拟的"阴影相机"从光源视角渲染得到的
				// 这些参数定义阴影相机的视锥体（看到的世界范围）
				light.shadow.camera.top = 2000;     // 上边界：2000单位
				light.shadow.camera.bottom = -2000; // 下边界：-2000单位
				light.shadow.camera.left = -2000;   // 左边界：-2000单位
				light.shadow.camera.right = 2000;   // 右边界：2000单位
				light.shadow.camera.near = 1200;    // 近裁剪面：1200单位
				light.shadow.camera.far = 2500;     // 远裁剪面：2500单位
				
				// 阴影偏移：解决阴影失真问题（阴影痤疮/阴影条纹）
				// 微小的偏移可以避免表面自阴影
				light.shadow.bias = 0.0001;
				
				// 阴影贴图分辨率：决定阴影的清晰度
				// 更高的分辨率=更清晰的阴影，但性能消耗更大
				light.shadow.mapSize.width = SHADOW_MAP_WIDTH;   // 宽度2048像素
				light.shadow.mapSize.height = SHADOW_MAP_HEIGHT; // 高度1024像素

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

				// 创建HUD（头部显示）和主场景内容
				createHUD();
				createScene();

				// ========== 渲染器设置 ==========
				// 创建WebGL渲染器：使用WebGL API进行硬件加速的3D渲染
				renderer = new THREE.WebGLRenderer({
					antialias: true,            // 启用抗锯齿：平滑边缘锯齿
					reversedDepthBuffer: true   // 启用反向深度缓冲：提高深度测试精度，解决z-fighting问题
				});
				
				// 设置设备像素比：适配高DPI屏幕（Retina显示器）
				// 使渲染更清晰，但可能影响性能
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器画布尺寸为整个窗口大小
				renderer.setSize(SCREEN_WIDTH, SCREEN_HEIGHT);
				
				// 设置动画循环回调函数：浏览器每帧自动调用animate函数
				// 替代传统的requestAnimationFrame手动调用
				renderer.setAnimationLoop(animate);
				
				// 将渲染器的DOM元素（canvas画布）添加到容器中
				container.appendChild(renderer.domElement);

				// 禁用自动清除：允许在渲染主场景后渲染HUD
				// 如果为true，每次render()调用前会自动清除画布
				renderer.autoClear = false;

				// 阴影映射设置
				renderer.shadowMap.enabled = true; // 启用阴影映射
				renderer.shadowMap.type = THREE.PCFShadowMap; // 使用PCF软阴影算法
				// PCF（Percentage Closer Filtering）会产生边缘柔和的阴影

				// ========== 控制器设置 ==========
				// 创建轨道控制器：允许用户通过鼠标控制相机
				controls = new OrbitControls(camera, renderer.domElement);
				controls.enablePan = false; // 禁用平移（鼠标右键拖拽）
				
				// 限制垂直旋转角度：防止相机翻转到地面以下
				// Math.PI / 2 = 90度，限制相机最多看到地平线
				controls.maxPolarAngle = Math.PI / 2;
				
				// 限制缩放距离：防止相机太近或太远
				controls.minDistance = 200;  // 最小距离200单位
				controls.maxDistance = 2200; // 最大距离2200单位

				// 设置控制焦点：相机围绕哪个点旋转
				controls.target.set(0, -75, 25);
				
				// 更新控制器：应用所有设置
				controls.update();

				// ========== 性能统计设置 ==========
				// 创建Stats.js实例，默认显示FPS（帧率）
				stats = new Stats();
				
				// 默认注释掉性能统计显示，取消注释可查看性能信息
				// container.appendChild(stats.dom);

				// ========== 事件监听器设置 ==========
				// 窗口大小变化事件：当浏览器窗口大小改变时调整渲染
				window.addEventListener('resize', onWindowResize);
				
				// 键盘按下事件：监听用户按键操作
				window.addEventListener('keydown', onKeyDown);

			}

			/**
			 * 窗口大小变化处理函数
			 * 作用：响应浏览器窗口大小变化，调整相机和渲染器
			 * 触发条件：用户调整浏览器窗口大小、切换全屏、设备旋转等
			 */
			function onWindowResize() {

				// 更新相机的宽高比：确保渲染内容比例正确
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵：应用新的宽高比设置
				// 注意：修改相机参数后必须调用此方法
				camera.updateProjectionMatrix();

				// 更新渲染器画布尺寸：适应新窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);

			}

			/**
			 * 键盘按下事件处理函数
			 * 作用：处理用户的键盘输入
			 * @param {KeyboardEvent} event - 键盘事件对象，包含按键信息
			 */
			function onKeyDown(event) {

				// 使用event.keyCode判断按下的按键（已弃用，但广泛支持）
				// 更现代的方式是使用event.key或event.code
				switch (event.keyCode) {

					case 84: // 'T'键的键码：84
						// 切换HUD显示状态：如果当前显示则隐藏，反之亦然
						showHUD = !showHUD;
						break;

					// 可以在此添加更多按键处理
					// case 27: // ESC键
					// case 32: // 空格键
					// ...

				}

			}

			/**
			 * 创建HUD（头部显示）
			 * 作用：创建阴影贴图调试视图，用于开发和调试
			 * HUD通常显示在屏幕角落，不影响主场景交互
			 */
			function createHUD() {

				// 创建阴影贴图查看器实例
				// 参数：要查看的光源对象（包含阴影贴图）
				lightShadowMapViewer = new ShadowMapViewer(light);
				
				// 设置查看器在屏幕上的位置（像素坐标）
				// 左上角位置，留出10像素边距
				lightShadowMapViewer.position.x = 10; // 距离左边10像素
				lightShadowMapViewer.position.y = SCREEN_HEIGHT - (SHADOW_MAP_HEIGHT / 4) - 10;
				// 计算方式：屏幕高度 - 查看器高度 - 边距

				// 设置查看器显示尺寸：原始阴影贴图的1/4大小
				// 保持宽高比，避免图像变形
				lightShadowMapViewer.size.width = SHADOW_MAP_WIDTH / 4;
				lightShadowMapViewer.size.height = SHADOW_MAP_HEIGHT / 4;
				
				// 更新查看器：应用位置和尺寸设置
				lightShadowMapViewer.update();

			}

			/**
			 * 创建主场景内容
			 * 作用：创建场景中的所有3D对象，包括地面、文字、模型等
			 * 这是场景构建的核心函数，创建所有可见内容
			 */
			function createScene() {

				// ========== 地面 ==========
				// 创建平面几何体：基础尺寸100x100单位
				const geometry = new THREE.PlaneGeometry(100, 100);
				
				// 创建Phong材质：支持高光反射，适合模拟光滑表面
				// 颜色：浅橙色（0xffdd99）
				const planeMaterial = new THREE.MeshPhongMaterial({ color: 0xffdd99 });

				// 创建网格对象：将几何体和材质组合成可渲染对象
				const ground = new THREE.Mesh(geometry, planeMaterial);

				// 设置地面位置：位于场景底部
				ground.position.set(0, FLOOR, 0); // x=0居中，y=FLOOR，z=0
				
				// 旋转地面：平面几何体默认是垂直的，需要旋转90度使其水平
				// -Math.PI / 2 = -90度，绕X轴旋转
				ground.rotation.x = -Math.PI / 2;
				
				// 缩放地面：放大100倍，创建广阔的地面
				ground.scale.set(100, 100, 100); // x,y,z方向都放大100倍

				// 阴影设置：
				ground.castShadow = false;   // 地面不投射阴影（不需要）
				ground.receiveShadow = true; // 地面接收阴影（显示其他物体的阴影）

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

				// ========== 3D文字 ==========
				// 创建字体加载器实例
				const loader = new FontLoader();
				
				// 加载字体文件（JSON格式）
				// 注意：字体文件需要预先使用工具转换
				loader.load('fonts/helvetiker_bold.typeface.json', function (font) {

					// 创建文本几何体：生成"THREE.JS"的3D文字
					const textGeo = new TextGeometry('THREE.JS', {
						font: font,           // 使用的字体
						size: 200,            // 字体大小：200单位
						depth: 50,            // 挤出深度：50单位，创建3D厚度
						curveSegments: 12,    // 曲线分段数：影响圆角的光滑度
						bevelThickness: 2,    // 斜角厚度：边缘斜角的深度
						bevelSize: 5,         // 斜角大小：边缘斜角的宽度
						bevelEnabled: true    // 启用斜角：创建有斜角的3D文字
					});

					// 计算文本的边界框：获取文字的实际尺寸
					textGeo.computeBoundingBox();
					
					// 计算居中偏移：使文字在X轴居中
					// boundingBox.max.x - boundingBox.min.x = 文字宽度
					// -0.5 * 宽度 = 向左移动一半宽度，使中心点在原点
					const centerOffset = -0.5 * (textGeo.boundingBox.max.x - textGeo.boundingBox.min.x);

					// 创建文字材质：红色高光材质
					const textMaterial = new THREE.MeshPhongMaterial({
						color: 0xff0000,     // 红色：RGB(255, 0, 0)
						specular: 0xffffff   // 高光颜色：白色，产生明亮反光
					});

					// 创建文字网格对象
					const mesh = new THREE.Mesh(textGeo, textMaterial);
					
					// 设置文字位置
					mesh.position.x = centerOffset; // 水平居中
					mesh.position.y = FLOOR + 67;   // 地面上方67单位
					// z默认为0，在地面中心

					// 阴影设置：
					mesh.castShadow = true;     // 文字投射阴影
					mesh.receiveShadow = true;  // 文字接收阴影（自身可能有阴影）

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

				});

				// ========== 立方体 ==========
				// 创建第一个大立方体：1500x220x150单位
				// 作用：作为场景中的大型障碍物，产生明显阴影
				const cubes1 = new THREE.Mesh(
					new THREE.BoxGeometry(1500, 220, 150), // 几何体：长方体
					planeMaterial                           // 材质：使用地面的浅橙色材质
				);

				// 设置立方体1位置
				cubes1.position.y = FLOOR - 50; // 地面下方50单位（部分埋入地面）
				cubes1.position.z = 20;         // 向前（相机方向）20单位
				// x默认为0，场景中心

				// 阴影设置
				cubes1.castShadow = true;     // 投射阴影
				cubes1.receiveShadow = true;  // 接收阴影

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

				// 创建第二个大立方体：1600x170x250单位
				// 比第一个立方体略宽但更矮，增加场景变化
				const cubes2 = new THREE.Mesh(
					new THREE.BoxGeometry(1600, 170, 250), // 更大的长方体
					planeMaterial                           // 相同材质
				);

				// 设置立方体2位置（与立方体1相同位置，但尺寸不同）
				cubes2.position.y = FLOOR - 50;
				cubes2.position.z = 20;

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

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

				// ========== 变形动画模型（动物） ==========
				// 创建动画混合器：管理场景中所有动画
				// 参数：动画的根对象（通常为场景或模型根节点）
				mixer = new THREE.AnimationMixer(scene);

				/**
				 * 辅助函数：添加变形动画模型到场景
				 * 作用：封装模型加载、动画设置、位置设置的重复代码
				 * 
				 * @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 - 是否随机调整颜色（true=随机）
				 */
				function addMorph(mesh, clip, speed, duration, x, y, z, fudgeColor) {

					// 克隆模型网格：避免引用问题，每个实例独立
					// 重要：如果不克隆，所有实例会共享相同的几何体和材质
					mesh = mesh.clone();
					
					// 克隆材质：使每个实例可以有自己的材质属性
					mesh.material = mesh.material.clone();

					// 如果需要随机调整颜色
					if (fudgeColor) {
						// offsetHSL：调整HSL（色相、饱和度、亮度）颜色空间
						// 参数：色相偏移、饱和度偏移、亮度偏移
						// Math.random() * 0.5 - 0.25：生成-0.25到0.25的随机数
						mesh.material.color.offsetHSL(
							0,                                // 色相不变
							Math.random() * 0.5 - 0.25,       // 饱和度随机变化
							Math.random() * 0.5 - 0.25        // 亮度随机变化
						);
						// 效果：创建颜色略有不同的动物，增加自然感
					}

					// 存储移动速度：后续动画循环中使用
					// 将其作为网格的自定义属性存储
					mesh.speed = speed;

					// 创建动画动作并配置
					// clipAction：为指定动画片段和对象创建动作控制器
					mixer.clipAction(clip, mesh)
						.setDuration(duration)                 // 设置动画持续时间
						.startAt(-duration * Math.random())   // 随机起始时间：错开动画相位
						.play();                              // 立即播放动画

					// 设置模型位置
					mesh.position.set(x, y, z);
					
					// 旋转模型：绕Y轴旋转90度（使模型面向正确方向）
					mesh.rotation.y = Math.PI / 2; // 90度弧度值

					// 阴影设置
					mesh.castShadow = true;     // 动物投射阴影
					mesh.receiveShadow = true;  // 动物接收阴影（如其他动物的阴影）

					// 将模型添加到场景
					scene.add(mesh);

					// 将模型添加到全局数组，便于后续统一更新
					morphs.push(mesh);

				}

				// 创建GLTF加载器实例
				const gltfloader = new GLTFLoader();

				// ========== 加载马模型 ==========
				// 马模型有行走动画，将创建多个实例
				gltfloader.load('models/gltf/Horse.glb', function (gltf) {
					// gltf.scene：包含模型网格、材质、骨骼等的完整场景
					// children[0]：获取第一个（通常是唯一一个）子对象
					const mesh = gltf.scene.children[0];
					
					// gltf.animations：包含所有动画片段的数组
					// [0]：获取第一个动画片段（通常是行走/奔跑动画）
					const clip = gltf.animations[0];

					// 添加6匹马，分两组分布在场景两侧
					// 右侧的马（z坐标为正）
					addMorph(mesh, clip, 550, 1, 100 - Math.random() * 1000, FLOOR, 300, true);
					addMorph(mesh, clip, 550, 1, 100 - Math.random() * 1000, FLOOR, 450, true);
					addMorph(mesh, clip, 550, 1, 100 - Math.random() * 1000, FLOOR, 600, true);

					// 左侧的马（z坐标为负）
					addMorph(mesh, clip, 550, 1, 100 - Math.random() * 1000, FLOOR, -300, true);
					addMorph(mesh, clip, 550, 1, 100 - Math.random() * 1000, FLOOR, -450, true);
					addMorph(mesh, clip, 550, 1, 100 - Math.random() * 1000, FLOOR, -600, true);
				});

				// ========== 加载火烈鸟模型 ==========
				// 火烈鸟有站立/行走动画
				gltfloader.load('models/gltf/Flamingo.glb', function (gltf) {
					const mesh = gltf.scene.children[0];
					const clip = gltf.animations[0];
					// 添加一只火烈鸟，在地面上方较高位置
					addMorph(mesh, clip, 500, 1, 500 - Math.random() * 500, FLOOR + 350, 40);
					// FLOOR + 350：地面上方350单位（模拟较高的鸟类）
				});

				// ========== 加载鹳模型 ==========
				// 鹳有行走/飞行动画
				gltfloader.load('models/gltf/Stork.glb', function (gltf) {
					const mesh = gltf.scene.children[0];
					const clip = gltf.animations[0];
					// 添加一只鹳
					addMorph(mesh, clip, 350, 1, 500 - Math.random() * 500, FLOOR + 350, 340);
				});

				// ========== 加载鹦鹉模型 ==========
				// 鹦鹉可能有飞行/栖息动画
				gltfloader.load('models/gltf/Parrot.glb', function (gltf) {
					const mesh = gltf.scene.children[0];
					const clip = gltf.animations[0];
					// 添加一只鹦鹉，动画持续时间较短（0.5秒）
					addMorph(mesh, clip, 450, 0.5, 500 - Math.random() * 500, FLOOR + 300, 700);
				});

			}

			/**
			 * 动画循环函数 - 每帧调用
			 * 作用：浏览器每帧自动调用的主循环
			 * 这是所有动画、更新的核心驱动函数
			 * 使用setAnimationLoop而不是requestAnimationFrame（Three.js r125+）
			 */
			function animate() {
				render();       // 执行渲染
				stats.update(); // 更新性能统计显示
				// 注意：stats.update()被注释掉了，取消注释可启用性能显示
			}

			/**
			 * 渲染函数 - 执行实际的渲染操作
			 * 作用：更新动画状态，渲染场景，渲染HUD
			 * 这是每帧执行的核心渲染逻辑
			 */
			function render() {

				// 获取时间增量（delta time）：上一帧到当前帧的时间（秒）
				// 使用时间增量可以使动画速度与帧率无关
				// 60FPS时delta≈0.0167，30FPS时delta≈0.0333
				const delta = clock.getDelta();

				// 更新动画混合器：推进所有动画的时间
				// 参数：时间增量，使动画以正确速度播放
				mixer.update(delta);

				// 更新所有变形动画模型的位置
				// 遍历morphs数组中的每个模型
				for (let i = 0; i < morphs.length; i++) {
					const morph = morphs[i]; // 获取当前模型

					// 根据速度移动模型：distance = speed * time
					// 使模型沿X轴正方向移动（从屏幕左侧向右侧移动）
					morph.position.x += morph.speed * delta;

					// 边界检查：如果模型移出右边界
					// 2000是自定义的右边界值
					if (morph.position.x > 2000) {
						// 重置到左边界：-1000到-1500之间的随机位置
						// 产生连续循环移动的效果
						morph.position.x = -1000 - Math.random() * 500;
					}
				}

				// 更新轨道控制器：处理用户输入，更新相机位置
				// 参数：时间增量，使控制器移动平滑
				controls.update(delta);

				// ========== 渲染流程 ==========
				// 1. 清除渲染缓冲区：清除上一帧的内容
				renderer.clear();
				
				// 2. 渲染主场景：将3D场景绘制到画布
				// 参数：场景对象，相机对象
				renderer.render(scene, camera);

				// 3. 如果HUD显示标志为true，渲染阴影贴图调试视图
				if (showHUD) {
					// 渲染阴影贴图查看器：将阴影贴图以2D图像形式覆盖在场景上
					lightShadowMapViewer.render(renderer);
				}

			}

		</script>

	</body>
</html>