<!-- Three.js 骨骼动画行走演示 - 代码功能与技术点详解
🎯 项目概述
这是一个基于 Three.js 的交互式 3D 骨骼动画演示，展示了如何实现第三人称视角的角色控制、动画混合、物理光照和无限地形系统。用户可以通过键盘控制角色在场景中行走或奔跑，同时使用鼠标控制相机视角。

🚀 主要功能模块
1. 角色控制系统
多按键支持：WASD、方向键、法语键盘布局（Z/Q键）

运动状态：

闲置（Idle）：角色站立不动时的呼吸动画

行走（Walk）：正常速度移动

奔跑（Run）：按住Shift加速移动

视角跟随：角色移动方向与相机视角同步

平滑转向：使用四元数插值实现平滑的旋转过渡

2. 动画管理系统
三种动画状态：Idle、Walk、Run

两种过渡模式：

固定过渡：动画时间同步，保证动作连续性

标准淡入淡出：传统权重混合过渡

动画混合器：统一管理所有动画的时间线和权重

3. 视觉渲染系统
HDR环境光照：使用 .hdr 文件提供高质量环境反射

物理渲染材质：基于PBR的金属/粗糙度工作流

动态阴影：方向光源投射实时阴影

雾效系统：增加场景深度感和氛围

无限地形：通过移动地板而非角色实现无限大场景

4. 交互界面
轨道控制器：鼠标控制相机旋转、缩放

调试面板：显示/隐藏骨骼、切换过渡模式

响应式设计：自动适配窗口大小变化

🔧 核心技术点详解
1. Three.js 核心架构
javascript
// 场景图结构
Scene
├── Group (角色组)
│   └── Model (士兵模型)
├── FollowGroup (跟随组)
│   ├── DirectionalLight (主光源)
│   └── Light.target (光源目标)
├── Floor (地板)
└── SkeletonHelper (骨骼辅助对象)
2. 骨骼动画实现原理
GLTF模型加载：包含网格、材质、骨骼、动画数据

AnimationMixer：动画状态机的核心

AnimationAction：每个动画的播放控制单元

骨骼绑定：顶点权重与骨骼变换矩阵

3. 动画过渡算法
javascript
// 固定过渡模式（同步时间）
if (play !== 'Idle') {
    current.time = old.time * (current.getClip().duration / old.getClip().duration);
}
// 权重调度
old._scheduleFading(fade, old.getEffectiveWeight(), 0);
current._scheduleFading(fade, current.getEffectiveWeight(), 1);
4. 无限地形算法
javascript
// 角色移动时检查与地板的距离差
const dx = (position.x - floor.position.x);
const dz = (position.z - floor.position.z);

// 超过阈值时移动地板而不是移动角色
if (Math.abs(dx) > controls.floorDecale) floor.position.x += dx;
if (Math.abs(dz) > controls.floorDecale) floor.position.z += dz;
5. 输入处理系统
事件分离：keydown/keyup 分离处理

多按键支持：处理同时按多个键的情况

键位防冲突：同一方向多个按键只记录一次

物理键位映射：使用 event.code 而非 event.key

6. 渲染优化技术
色调映射：ACES Filmic Tone Mapping

各向异性过滤：提升倾斜纹理质量

阴影优化：PCF软阴影，1024x1024阴影贴图

深度写入优化：地板禁用深度写入避免Z-fighting

📁 项目结构分析
资源文件依赖
text
项目根目录/
├── models/gltf/
│   └── Soldier.glb          # 角色模型（带动画）
├── textures/equirectangular/
│   └── lobe.hdr            # HDR环境贴图
├── textures/floors/
│   ├── FloorsCheckerboard_S_Diffuse.jpg
│   └── FloorsCheckerboard_S_Normal.jpg
├── build/
│   └── three.module.js     # Three.js核心库
├── jsm/                    # Three.js插件目录
└── main.css               # 基础样式文件
关键代码模块
模块	功能	复杂度
init()	初始化场景、渲染器、控制器	⭐⭐⭐⭐
addFloor()	创建无限地形系统	⭐⭐⭐
loadModel()	加载并配置3D模型	⭐⭐⭐⭐⭐
updateCharacter()	核心游戏逻辑更新	⭐⭐⭐⭐⭐
animate()	渲染循环和动画更新	⭐⭐
🔍 技术特色亮点
1. 现代渲染管线
使用Three.js r128+的ES6模块导入

基于物理的材质和光照

HDR环境贴图和色调映射

2. 动画系统创新
支持动画时间同步的过渡模式

骨骼可视化调试工具

动画权重精确控制

3. 性能优化策略
按需渲染（requestAnimationFrame）

纹理复用和缓存

几何体LOD优化（地板细分）

4. 跨平台兼容性
响应式设计适配移动端

多种键盘布局支持

WebGL 2.0/1.0 降级支持

🎮 操作指南
基本控制
移动：WASD / 方向键

奔跑：按住Shift键

视角：鼠标拖拽旋转，滚轮缩放

重置视角：双击鼠标中键

调试功能
显示骨骼：通过右上角面板切换

切换过渡模式：标准淡入淡出 vs 固定过渡

📊 性能指标
组件	渲染开销	备注
角色模型	中等	~5000个三角形
骨骼动画	低	60fps下<1ms
阴影渲染	高	1024x1024阴影贴图
HDR环境	中等	预滤波降低实时开销
地板系统	低	静态几何体，复用材质
🔮 可扩展性
1. 功能扩展建议
添加更多动画状态（跳跃、攻击）

实现角色碰撞检测

添加多个NPC角色

集成声音系统（脚步声、环境音）

2. 技术升级路径
迁移到Three.js最新版本

集成后期处理效果（SSAO、Bloom）

添加WebXR支持（VR/AR体验）

实现网络多人同步 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<title>Three.js WebGL - 骨骼动画行走演示</title>
		<meta charset="utf-8">
		<!-- 
			视口元标签，确保在不同设备上正确显示：
			- width=device-width: 视口宽度等于设备宽度
			- user-scalable=no: 禁止用户缩放
			- minimum-scale=1.0, maximum-scale=1.0: 锁定缩放比例为1.0
		-->
		<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">
		<style>
			/* 内联CSS样式：设置超链接颜色为红色 */
			a {
				color: #f00;
			}
		</style>
	</head>
	<body>
		<!-- 主容器：用于承载Three.js渲染的3D场景 -->
		<div id="container"></div>
		
		<!-- 信息显示区域：展示项目信息和操作说明 -->
		<div id="info">
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 骨骼动画行走演示
			(模型来自 <a href="https://www.mixamo.com/" target="_blank" rel="noopener">Mixamo.com</a>)<br/>
			操作说明：使用方向键或WASD控制角色移动，Shift键切换行走/奔跑
		</div>

		<!-- 
			模块导入映射配置：
			定义JavaScript模块的路径别名，方便在代码中导入
			- three: 指向Three.js核心库
			- three/addons/: 指向Three.js插件和附加组件目录
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module" 表示这是一个ES6模块，支持import/export语法
			所有Three.js相关的代码都写在这里
		-->
		<script type="module">
			// ==================== 模块导入部分 ====================
			
			// 导入Three.js核心库的所有功能
			import * as THREE from 'three';

			// 导入轨道控制器：允许用户用鼠标控制相机旋转、平移和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入GUI库：用于创建调试和控制面板
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
			// 导入GLTF加载器：用于加载GLTF格式的3D模型（包含动画、材质等）
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			// 导入HDR加载器：用于加载高动态范围图像作为环境贴图
			import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';

			// ==================== 全局变量声明部分 ====================
			
			// 核心Three.js对象
			let scene,      // 3D场景对象，包含所有3D元素
				renderer,   // WebGL渲染器，负责将3D场景渲染到2D画布
				camera,     // 透视相机，定义观察视角和投影方式
				floor,      // 地板网格对象
				orbitControls; // 轨道控制器实例

			// 角色和动画相关对象
			let group,      // 角色组：包含角色模型和所有相关对象
				followGroup, // 跟随组：包含跟随角色的灯光等对象
				model,      // 加载的3D模型对象
				skeleton,   // 骨骼辅助对象：用于可视化显示骨骼结构
				mixer,      // 动画混合器：管理和混合多个动画
				clock;      // 时钟对象：用于精确的时间计算和动画同步

			// 动画动作集合：存储所有可用的动画动作（Idle, Walk, Run等）
			let actions;

			// ==================== 设置参数对象 ====================
			
			// 用于GUI控制面板的设置参数
			const settings = {
				show_skeleton: false,   // 是否显示骨骼结构（调试用）
				fixe_transition: true,  // 是否使用固定过渡方式（true:同步过渡，false:淡入淡出过渡）
			};

			// ==================== 数学常量定义 ====================
			
			const PI = Math.PI;           // 圆周率π
			const PI90 = Math.PI / 2;     // 90度对应的弧度值

			// ==================== 角色控制参数对象 ====================
			
			// 集中管理所有角色控制相关的参数和状态
			const controls = {
				// 键盘按键状态数组：[前后移动, 左右移动, 是否加速]
				// 值说明：前后(0:停止, -1:前, 1:后), 左右(0:停止, -1:左, 1:右), 加速(0:行走, 1:奔跑)
				key: [ 0, 0, 0 ],
				
				ease: new THREE.Vector3(),          // 平滑移动向量：用于角色位置插值计算
				position: new THREE.Vector3(),      // 角色当前世界坐标位置
				up: new THREE.Vector3( 0, 1, 0 ),   // 上方向向量：始终指向世界坐标系Y轴正方向
				rotate: new THREE.Quaternion(),     // 旋转四元数：表示角色的朝向
				current: 'Idle',                    // 当前正在播放的动画名称
				fadeDuration: 0.5,                  // 动画过渡的持续时间（秒）
				runVelocity: 5,                     // 奔跑速度：单位/秒
				walkVelocity: 1.8,                  // 行走速度：单位/秒
				rotateSpeed: 0.05,                  // 角色旋转速度：控制转向的平滑度
				floorDecale: 0,                     // 地板移动阈值：角色移动超过此值时移动地板
			};

			// ==================== 主初始化函数调用 ====================
			
			init(); // 页面加载完成后立即执行初始化

			// ==================== 初始化函数定义 ====================
			
			/**
			 * 初始化整个Three.js应用
			 * 包括：创建场景、相机、渲染器、灯光、控制器等
			 */
			function init() {
				// 获取页面中的容器元素
				const container = document.getElementById( 'container' );

				// 创建透视相机
				// 参数：视野角度(FOV)，宽高比，近裁剪面，远裁剪面
				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 0.1, 100 );
				camera.position.set( 0, 2, -5 ); // 设置相机初始位置：X=0, Y=2（人眼高度）, Z=-5（向后5个单位）

				// 创建Three.js时钟对象
				// 用于计算帧间隔时间，保证动画在不同刷新率设备上的一致性
				clock = new THREE.Clock();

				// 创建3D场景
				scene = new THREE.Scene();
				scene.background = new THREE.Color( 0x5e5d5d ); // 设置场景背景色（深灰色）
				// 添加雾效：增强场景的深度感和距离感
				scene.fog = new THREE.Fog( 0x5e5d5d, 2, 20 ); // 颜色，近雾距离，远雾距离

				// 创建角色组：用于统一管理角色相关的所有对象
				group = new THREE.Group();
				scene.add( group );

				// 创建跟随组：用于管理跟随角色的对象（如灯光）
				followGroup = new THREE.Group();
				scene.add( followGroup );

				// ==================== 灯光设置 ====================
				
				// 创建主定向光源（模拟太阳光）
				const dirLight = new THREE.DirectionalLight( 0xffffff, 5 ); // 颜色，强度
				dirLight.position.set( -2, 5, -3 ); // 设置光源位置
				dirLight.castShadow = true; // 启用阴影投射
				
				// 配置阴影相机参数：控制阴影的可见范围和质量
				const cam = dirLight.shadow.camera;
				cam.top = cam.right = 2;     // 阴影相机上边界和右边界
				cam.bottom = cam.left = -2;  // 阴影相机下边界和左边界
				cam.near = 3;                // 阴影相机近裁剪面
				cam.far = 8;                 // 阴影相机远裁剪面
				dirLight.shadow.mapSize.set( 1024, 1024 ); // 阴影贴图分辨率（影响阴影质量）
				
				// 将灯光和灯光目标添加到跟随组，使其随角色移动
				followGroup.add( dirLight );
				followGroup.add( dirLight.target );

				// （调试用）可取消注释显示阴影相机范围
				// scene.add( new THREE.CameraHelper( cam ) );

				// ==================== 渲染器设置 ====================
				
				// 创建WebGL渲染器
				renderer = new THREE.WebGLRenderer( { antialias: true } ); // 启用抗锯齿
				renderer.setPixelRatio( window.devicePixelRatio ); // 设置设备像素比，支持高清屏
				renderer.setSize( window.innerWidth, window.innerHeight ); // 设置渲染尺寸为窗口大小
				renderer.setAnimationLoop( animate ); // 设置动画循环回调函数
				
				// 色调映射设置：将HDR颜色映射到显示器的颜色范围
				renderer.toneMapping = THREE.ACESFilmicToneMapping; // 使用ACES电影级色调映射
				renderer.toneMappingExposure = 0.5; // 曝光度设置
				
				// 阴影设置
				renderer.shadowMap.enabled = true; // 启用阴影映射
				renderer.shadowMap.type = THREE.PCFShadowMap; // 使用PCF软阴影算法
				
				// 将渲染器的canvas元素添加到页面容器中
				container.appendChild( renderer.domElement );

				// ==================== 控制器设置 ====================
				
				// 创建轨道控制器，允许用户用鼠标控制相机
				orbitControls = new OrbitControls( camera, renderer.domElement );
				orbitControls.target.set( 0, 1, 0 ); // 设置控制器的目标点（角色大致高度）
				orbitControls.enableDamping = true; // 启用阻尼效果（惯性）
				orbitControls.enablePan = false; // 禁用平移操作
				orbitControls.maxPolarAngle = PI90 - 0.05; // 限制垂直旋转角度（避免相机翻转）
				orbitControls.update(); // 首次更新控制器

				// ==================== 事件监听器绑定 ====================
				
				// 窗口大小改变事件：确保渲染尺寸与窗口尺寸同步
				window.addEventListener( 'resize', onWindowResize );
				// 键盘按下事件：处理角色控制输入
				document.addEventListener( 'keydown', onKeyDown );
				// 键盘释放事件：处理角色控制输入结束
				document.addEventListener( 'keyup', onKeyUp );

				// ==================== 资源加载和场景构建 ====================
				
				// 加载HDR环境贴图（高动态范围图像）
				new HDRLoader()
					.setPath( 'textures/equirectangular/' ) // 设置资源路径
					.load( 'lobe.hdr', function ( texture ) {
						// 设置贴图映射方式为等距柱状投影
						texture.mapping = THREE.EquirectangularReflectionMapping;
						// 将HDR贴图设置为场景环境贴图（用于全局光照和反射）
						scene.environment = texture;
						// 设置环境光强度
						scene.environmentIntensity = 1.5;

						// 环境贴图加载完成后，加载角色模型和添加地板
						loadModel();  // 加载士兵模型
						addFloor();   // 添加地板
					} );
			}

			// ==================== 添加地板函数 ====================
			
			/**
			 * 创建并添加地板到场景中
			 * 包含：地板几何体、材质、纹理和装饰灯光
			 */
			function addFloor() {
				const size = 50;    // 地板平面尺寸（50x50单位）
				const repeat = 16;  // 纹理重复次数（创建棋盘效果）

				// 获取显卡支持的最大各向异性过滤级别
				// 各向异性过滤可以提高倾斜角度观察纹理时的清晰度
				const maxAnisotropy = renderer.capabilities.getMaxAnisotropy();

				// 加载地板漫反射贴图（颜色纹理）
				const floorT = new THREE.TextureLoader().load( 'textures/floors/FloorsCheckerboard_S_Diffuse.jpg' );
				floorT.colorSpace = THREE.SRGBColorSpace; // 设置颜色空间为sRGB（确保颜色正确显示）
				floorT.repeat.set( repeat, repeat ); // 设置纹理重复次数
				floorT.wrapS = floorT.wrapT = THREE.RepeatWrapping; // 设置纹理包裹方式为重复
				floorT.anisotropy = maxAnisotropy; // 应用各向异性过滤

				// 加载地板法线贴图（模拟表面凹凸细节）
				const floorN = new THREE.TextureLoader().load( 'textures/floors/FloorsCheckerboard_S_Normal.jpg' );
				floorN.repeat.set( repeat, repeat );
				floorN.wrapS = floorN.wrapT = THREE.RepeatWrapping;
				floorN.anisotropy = maxAnisotropy;

				// 创建地板材质（基于物理的渲染材质）
				const mat = new THREE.MeshStandardMaterial( { 
					map: floorT, // 漫反射贴图
					normalMap: floorN, // 法线贴图
					normalScale: new THREE.Vector2( 0.5, 0.5 ), // 法线强度（0.5表示中等强度）
					color: 0x404040, // 基础颜色（深灰色）
					depthWrite: false, // 禁用深度写入（优化性能，防止Z-fighting）
					roughness: 0.85 // 粗糙度（0.0光滑如镜，1.0完全粗糙）
				} );

				// 创建地板几何体（平面）
				const g = new THREE.PlaneGeometry( size, size, 50, 50 ); // 宽度，高度，宽度分段数，高度分段数
				g.rotateX( -PI90 ); // 将平面从垂直旋转到水平（Three.js中平面默认是垂直的）

				// 创建地板网格对象（几何体+材质）
				floor = new THREE.Mesh( g, mat );
				floor.receiveShadow = true; // 启用阴影接收（地板可以接收角色的阴影）
				scene.add( floor );

				// 计算地板移动阈值：当角色移动超过此距离时，移动地板而不是移动整个场景
				// 这样可以实现无限大的地板效果
				controls.floorDecale = ( size / repeat ) * 4;

				// ==================== 添加装饰点光源（模拟灯泡） ====================
				
				// 创建灯泡几何体（小圆球）
				const bulbGeometry = new THREE.SphereGeometry( 0.05, 16, 8 ); // 半径，经度分段数，纬度分段数
				// 创建点光源：颜色，强度，衰减距离，衰减指数
				const bulbLight = new THREE.PointLight( 0xffee88, 2, 500, 2 );

				// 创建灯泡材质（自发光材质）
				const bulbMat = new THREE.MeshStandardMaterial( { 
					emissive: 0xffffee,       // 自发光颜色（浅黄色）
					emissiveIntensity: 1,     // 自发光强度
					color: 0x000000           // 基础颜色（黑色，只显示自发光）
				} );
				
				// 将灯泡网格添加到点光源（光源本身也是一个Object3D，可以添加子对象）
				bulbLight.add( new THREE.Mesh( bulbGeometry, bulbMat ) );
				bulbLight.position.set( 1, 0.1, -3 ); // 设置灯泡位置
				bulbLight.castShadow = true; // 灯泡也投射阴影
				floor.add( bulbLight ); // 将灯泡添加到地板上作为子对象
			}

			// ==================== 加载模型函数 ====================
			
			/**
			 * 加载GLTF格式的角色模型并设置相关动画
			 */
			function loadModel() {
				// 创建GLTF加载器实例
				const loader = new GLTFLoader();
				
				// 加载模型文件
				loader.load( 'models/gltf/Soldier.glb', function ( gltf ) {
					// gltf参数包含：scene（场景图）、animations（动画数组）、cameras（相机数组）等
					
					// 获取模型场景图（包含所有网格、骨骼、材质等）
					model = gltf.scene;
					// 将模型添加到角色组
					group.add( model );
					// 初始旋转：使角色面向正确方向（根据模型导出方向可能需要调整）
					model.rotation.y = PI; // 旋转180度
					group.rotation.y = PI;

					// ==================== 遍历模型所有对象并设置材质 ====================
					
					// traverse方法递归遍历模型的所有子对象
					model.traverse( function ( object ) {
						// 只处理网格对象
						if ( object.isMesh ) {
							// 根据对象名称区分不同部分的材质
							if ( object.name == 'vanguard_Mesh' ) {
								// 主要身体网格设置（金属盔甲部分）
								object.castShadow = true;     // 投射阴影
								object.receiveShadow = true;  // 接收阴影
								object.material.metalness = 1.0;  // 金属度设为1（完全金属）
								object.material.roughness = 0.2;  // 粗糙度设为0.2（比较光滑）
								object.material.color.set( 1, 1, 1 ); // 基础颜色设为白色
								// 使用漫反射贴图作为金属度贴图（金属部分有不同金属度）
								object.material.metalnessMap = object.material.map;
							} else {
								// 其他网格（可能是眼睛、头发等非金属部分）
								object.material.metalness = 1;      // 金属度
								object.material.roughness = 0;      // 粗糙度（完全光滑）
								object.material.transparent = true; // 启用透明
								object.material.opacity = 0.8;      // 不透明度80%
								object.material.color.set( 1, 1, 1 ); // 基础颜色
							}
						}
					} );

					// ==================== 创建骨骼辅助对象 ====================
					
					// SkeletonHelper用于可视化显示模型的骨骼结构（调试用）
					skeleton = new THREE.SkeletonHelper( model );
					// 设置骨骼颜色：根骨骼紫色，子骨骼青色
					skeleton.setColors( new THREE.Color( 0xe000ff ), new THREE.Color( 0x00e0ff ) );
					skeleton.visible = false; // 默认隐藏骨骼
					scene.add( skeleton ); // 将骨骼辅助对象添加到场景

					// ==================== 创建控制面板 ====================
					
					createPanel();

					// ==================== 动画系统初始化 ====================
					
					// 获取模型中的所有动画剪辑
					const animations = gltf.animations;

					// 创建动画混合器，传入模型作为混合目标
					mixer = new THREE.AnimationMixer( model );

					// 初始化动画动作字典
					// 从动画数组中创建对应的动画动作对象
					actions = {
						Idle: mixer.clipAction( animations[ 0 ] ), // 闲置动画（通常第一个）
						Walk: mixer.clipAction( animations[ 3 ] ), // 行走动画
						Run: mixer.clipAction( animations[ 1 ] )   // 奔跑动画
					};

					// 配置所有动画动作的初始状态
					for ( const m in actions ) {
						actions[ m ].enabled = true; // 启用动画
						actions[ m ].setEffectiveTimeScale( 1 ); // 设置播放速度为1（正常速度）
						// 除了闲置动画，其他动画权重设为0（不播放）
						if ( m !== 'Idle' ) actions[ m ].setEffectiveWeight( 0 );
					}

					// 播放闲置动画作为初始状态
					actions.Idle.play();

					// 启动动画循环
					animate();

				} );
			}

			// ==================== 更新角色函数 ====================
			
			/**
			 * 每帧更新角色的位置、旋转和动画状态
			 * @param {number} delta - 距离上一帧的时间（秒）
			 */
			function updateCharacter( delta ) {
				// 从controls对象中解构需要的参数
				const fade = controls.fadeDuration;
				const key = controls.key;
				const up = controls.up;
				const ease = controls.ease;
				const rotate = controls.rotate;
				const position = controls.position;
				// 获取轨道控制器的方位角（水平旋转角度）
				const azimuth = orbitControls.getAzimuthalAngle();

				// 判断是否有移动输入：前后或左右键是否被按下
				const active = key[ 0 ] === 0 && key[ 1 ] === 0 ? false : true;
				// 根据输入状态决定播放的动画
				// 如果有输入：检查Shift键是否按下决定奔跑或行走
				// 如果没有输入：播放闲置动画
				const play = active ? ( key[ 2 ] ? 'Run' : 'Walk' ) : 'Idle';

				// ==================== 动画状态切换逻辑 ====================
				
				// 如果当前动画状态需要改变
				if ( controls.current != play ) {
					// 获取新动画和旧动画的动作对象
					const current = actions[ play ];
					const old = actions[ controls.current ];
					// 更新当前动画状态
					controls.current = play;

					// 根据设置选择过渡方式
					if ( settings.fixe_transition ) {
						// 方式1：固定过渡（同步过渡）
						// 重置新动画到起始状态
						current.reset();
						current.weight = 1.0;
						// 停止所有淡入淡出效果
						current.stopFading();
						old.stopFading();
						
						// 如果切换到移动动画（非Idle），同步动画时间
						// 这样可以从旧动画的相同时间点开始新动画，过渡更自然
						if ( play !== 'Idle' ) {
							current.time = old.time * ( current.getClip().duration / old.getClip().duration );
						}
						
						// 安排淡入淡出过渡
						// 旧动画从当前权重淡出到0
						old._scheduleFading( fade, old.getEffectiveWeight(), 0 );
						// 新动画从当前权重淡入到1
						current._scheduleFading( fade, current.getEffectiveWeight(), 1 );
						// 播放新动画
						current.play();
					} else {
						// 方式2：标准淡入淡出过渡
						// 设置新动画权重为1
						setWeight( current, 1.0 );
						// 旧动画淡出
						old.fadeOut( fade );
						// 新动画重置、淡入并播放
						current.reset().fadeIn( fade ).play();
					}
				}

				// ==================== 角色移动逻辑 ====================
				
				// 如果当前不是闲置状态（角色正在移动）
				if ( controls.current !== 'Idle' ) {
					// 根据动画状态决定移动速度
					const velocity = controls.current == 'Run' ? controls.runVelocity : controls.walkVelocity;

					// 根据键盘输入计算基础移动向量
					// X轴：左右移动，Y轴：0（垂直方向不移动），Z轴：前后移动
					// 注意：Three.js中Z轴是垂直屏幕方向，前是负Z方向
					ease.set( key[ 1 ], 0, key[ 0 ] ).multiplyScalar( velocity * delta );

					// 计算角色应该朝向的角度
					// 1. Math.atan2(ease.x, ease.z)：计算原始移动方向的角度
					// 2. + azimuth：加上相机水平旋转角度（确保角色朝向相机视角方向）
					// 3. unwrapRad：将角度标准化到[-π, π]范围
					const angle = unwrapRad( Math.atan2( ease.x, ease.z ) + azimuth );
					// 根据角度创建旋转四元数
					rotate.setFromAxisAngle( up, angle );

					// 根据相机方位角调整移动向量
					// 这样WASD键的移动方向会与相机视角保持一致
					controls.ease.applyAxisAngle( up, azimuth );

					// 更新角色位置和相机位置
					position.add( ease );
					camera.position.add( ease );

					// 应用新的位置和旋转到角色组
					group.position.copy( position );
					// 平滑旋转到目标方向（rotateSpeed控制旋转速度）
					group.quaternion.rotateTowards( rotate, controls.rotateSpeed );

					// 更新轨道控制器的目标点（始终跟随角色）
					orbitControls.target.copy( position ).add( { x: 0, y: 1, z: 0 } );
					// 更新跟随组的位置（灯光等跟随元素）
					followGroup.position.copy( position );

					// ==================== 无限地板移动逻辑 ====================
					
					// 计算角色位置与地板位置的差值
					const dx = ( position.x - floor.position.x );
					const dz = ( position.z - floor.position.z );
					
					// 如果差值超过阈值，移动地板而不是移动整个场景
					// 这样角色可以无限移动，而地板会循环移动
					if ( Math.abs( dx ) > controls.floorDecale ) floor.position.x += dx;
					if ( Math.abs( dz ) > controls.floorDecale ) floor.position.z += dz;
				}

				// 更新动画混合器（推进所有动画的时间）
				if ( mixer ) mixer.update( delta );

				// 更新轨道控制器（处理阻尼等效果）
				orbitControls.update();
			}

			// ==================== 角度标准化函数 ====================
			
			/**
			 * 将角度标准化到 [-π, π] 范围内
			 * 使用atan2(sin(r), cos(r))可以确保结果在[-π, π]之间
			 * @param {number} r - 输入角度（弧度）
			 * @returns {number} 标准化后的角度
			 */
			function unwrapRad( r ) {
				return Math.atan2( Math.sin( r ), Math.cos( r ) );
			}

			// ==================== 创建控制面板函数 ====================
			
			/**
			 * 创建调试和控制面板
			 * 使用lil-gui库实现
			 */
			function createPanel() {
				// 创建GUI实例，设置宽度为310像素
				const panel = new GUI( { width: 310 } );

				// 添加"显示骨骼"复选框
				panel.add( settings, 'show_skeleton' )
					.name('显示骨骼') // 设置显示名称
					.onChange( ( b ) => {
						// 切换骨骼辅助对象的可见性
						skeleton.visible = b;
					} );

				// 添加"固定过渡"复选框
				panel.add( settings, 'fixe_transition' )
					.name('固定动画过渡');
			}

			// ==================== 设置动画权重函数 ====================
			
			/**
			 * 辅助函数：设置动画动作的权重
			 * @param {THREE.AnimationAction} action - 动画动作对象
			 * @param {number} weight - 权重值（0.0-1.0）
			 */
			function setWeight( action, weight ) {
				action.enabled = true; // 确保动画启用
				action.setEffectiveTimeScale( 1 ); // 设置播放速度为正常
				action.setEffectiveWeight( weight ); // 设置权重
			}

			// ==================== 键盘按下事件处理 ====================
			
			/**
			 * 处理键盘按下事件
			 * 更新controls.key数组中的对应状态
			 * @param {KeyboardEvent} event - 键盘事件对象
			 */
			function onKeyDown( event ) {
				const key = controls.key;
				// 使用event.code而不是event.key，因为code是物理键位，不受键盘布局影响
				switch ( event.code ) {
					// 向前移动（上箭头、W键、Z键（法语键盘））
					case 'ArrowUp': case 'KeyW': case 'KeyZ': 
						key[ 0 ] = -1; // Z轴负方向
						break;
					// 向后移动（下箭头、S键）
					case 'ArrowDown': case 'KeyS': 
						key[ 0 ] = 1; // Z轴正方向
						break;
					// 向左移动（左箭头、A键、Q键（法语键盘））
					case 'ArrowLeft': case 'KeyA': case 'KeyQ': 
						key[ 1 ] = -1; // X轴负方向
						break;
					// 向右移动（右箭头、D键）
					case 'ArrowRight': case 'KeyD': 
						key[ 1 ] = 1; // X轴正方向
						break;
					// 加速/奔跑（Shift键）
					case 'ShiftLeft': case 'ShiftRight': 
						key[ 2 ] = 1; // 第三个位置标记为加速状态
						break;
				}
			}

			// ==================== 键盘释放事件处理 ====================
			
			/**
			 * 处理键盘释放事件
			 * 重置controls.key数组中的对应状态
			 * @param {KeyboardEvent} event - 键盘事件对象
			 */
			function onKeyUp( event ) {
				const key = controls.key;
				switch ( event.code ) {
					// 释放向前键：只有当当前值是-1时才重置为0（防止多个向前键冲突）
					case 'ArrowUp': case 'KeyW': case 'KeyZ': 
						key[ 0 ] = key[ 0 ] < 0 ? 0 : key[ 0 ]; 
						break;
					// 释放向后键：只有当当前值是1时才重置为0
					case 'ArrowDown': case 'KeyS': 
						key[ 0 ] = key[ 0 ] > 0 ? 0 : key[ 0 ]; 
						break;
					// 释放向左键：只有当当前值是-1时才重置为0
					case 'ArrowLeft': case 'KeyA': case 'KeyQ': 
						key[ 1 ] = key[ 1 ] < 0 ? 0 : key[ 1 ]; 
						break;
					// 释放向右键：只有当当前值是1时才重置为0
					case 'ArrowRight': case 'KeyD': 
						key[ 1 ] = key[ 1 ] > 0 ? 0 : key[ 1 ]; 
						break;
					// 释放Shift键
					case 'ShiftLeft': case 'ShiftRight': 
						key[ 2 ] = 0; 
						break;
				}
			}

			// ==================== 窗口大小改变事件处理 ====================
			
			/**
			 * 处理窗口大小改变事件
			 * 调整相机宽高比和渲染器尺寸
			 */
			function onWindowResize() {
				// 更新相机宽高比为新的窗口宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 必须调用updateProjectionMatrix()才能使新的宽高比生效
				camera.updateProjectionMatrix();
				// 更新渲染器尺寸为新的窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 动画循环函数 ====================
			
			/**
			 * 主动画循环函数
			 * 由renderer.setAnimationLoop()自动每帧调用
			 */
			function animate() {
				// 获取距离上一帧的时间（秒）
				// 使用delta time可以确保动画速度与帧率无关
				const delta = clock.getDelta();

				// 更新角色状态（位置、旋转、动画）
				updateCharacter( delta );

				// 渲染场景：将3D场景通过相机视角渲染到2D画布
				renderer.render( scene, camera );
			}

		</script>

	</body>
</html>