<!-- Three.js 骨骼附加动画混合演示 - 功能描述与技术点详解
📋 项目概述
这是一个基于Three.js的WebGL 3D动画演示项目，展示了骨骼动画与附加动画混合的高级技术。项目加载一个带骨骼的3D人物模型，实现了多种动画的实时混合控制，用户可以通过GUI界面直观地控制动画切换和混合效果。

🎯 核心功能
1. 动画系统架构
基础动画层：包含完整的角色动作（空闲、行走、跑步）

附加动画层：提供叠加效果（表情、姿势），可与基础动画混合

动画混合器：统一管理和调度所有动画

2. 动画控制功能
基础动作切换：通过按钮选择不同的基础动画

附加动画权重调节：使用滑块控制叠加动画的强度

全局速度控制：调整所有动画的播放速度

平滑过渡：动画切换时采用交叉淡入淡出效果

3. 用户交互功能
3D场景查看：支持鼠标拖动旋转视角

实时控制面板：直观的GUI界面调节动画参数

视觉反馈：当前激活的动画按钮高亮显示

4. 视觉展示功能
真实感渲染：包含灯光、阴影、雾效

骨骼可视化：可显示/隐藏角色骨骼结构

性能监控：实时显示帧率和性能指标

🔧 主要技术点
1. Three.js 核心组件
javascript
// 核心Three.js对象
THREE.Scene        // 3D场景容器
THREE.WebGLRenderer // WebGL渲染器
THREE.PerspectiveCamera // 透视相机
THREE.AnimationMixer   // 动画混合器
THREE.Clock         // 高精度时间管理
2. 动画系统技术
附加动画原理
javascript
// 将普通动画转换为附加动画
THREE.AnimationUtils.makeClipAdditive(clip);
// 附加动画特点：只记录相对于基础姿势的变化量
// 可以叠加在任何基础动画上
动画混合策略
权重混合：每个动画有0-1的权重值，控制影响程度

加法混合：附加动画在基础动画上叠加变化

交叉淡入淡出：平滑过渡，避免动画跳变

动画状态管理
javascript
// 关键数据结构
const baseActions = {
    idle: { weight: 1, action: AnimationAction },
    walk: { weight: 0, action: AnimationAction },
    run: { weight: 0, action: AnimationAction }
};

const additiveActions = {
    sneak_pose: { weight: 0, action: AnimationAction },
    // ... 其他附加动画
};
3. 动画切换算法
智能切换策略
javascript
function prepareCrossFade(startAction, endAction, duration) {
    // 策略1：如果当前是空闲状态，立即切换
    // 策略2：否则等待当前动画完成当前循环
    // 确保动画在自然位置切换
}
动画同步机制
javascript
// 监听动画循环事件
mixer.addEventListener('loop', onLoopFinished);
// 确保切换发生在动画循环结束时
4. 性能优化技术
基于时间的动画更新
javascript
// 使用时间增量而非固定帧率
const deltaTime = clock.getDelta();
mixer.update(deltaTime);
// 确保动画在不同设备上速度一致
渲染优化
javascript
// 阴影优化
dirLight.shadow.camera.left = -2;
dirLight.shadow.camera.right = 2;
// 限制阴影渲染范围，提高性能

// 材质优化
new THREE.MeshPhongMaterial({ depthWrite: false });
// 减少深度写入操作
5. 用户界面技术
lil-gui 集成
javascript
// 创建控制面板
const panel = new GUI({ width: 310 });

// 控制器状态管理
control.setActive = function() {
    control.domElement.classList.remove('control-inactive');
};
实时数据绑定
javascript
// 双向数据绑定：GUI ↔ 动画系统
panelSettings['sneak_pose'] = settings.weight;
folder.add(panelSettings, 'sneak_pose', 0.0, 1.0, 0.01)
    .listen()  // 监听外部变化
    .onChange(updateAnimationWeight); // 响应UI变化
6. 资源加载与管理
GLTF模型加载
javascript
const loader = new GLTFLoader();
loader.load('models/gltf/Xbot.glb', function(gltf) {
    // 加载模型、材质、动画
    // 自动处理骨骼动画数据
});
动画剪辑处理
javascript
// 动画剪辑预处理
if (clip.name.endsWith('_pose')) {
    // 姿势类动画：提取关键帧
    clip = THREE.AnimationUtils.subclip(clip, clip.name, 2, 3, 30);
}
7. 相机与交互
轨道控制器配置
javascript
const controls = new OrbitControls(camera, renderer.domElement);
controls.enablePan = false;   // 禁用平移
controls.enableZoom = false;  // 禁用缩放
controls.target.set(0, 1, 0); // 设置注视点
响应式设计
javascript
window.addEventListener('resize', onWindowResize);
// 自动适应窗口大小变化
🏗️ 系统架构图
text
┌─────────────────────────────────────────────────┐
│                   GUI控制面板                    │
│  ┌───────────┐ ┌──────────────┐ ┌──────────┐  │
│  │ 基础动作  │ │ 附加动作权重 │ │ 全局速度 │  │
│  └───────────┘ └──────────────┘ └──────────┘  │
└─────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────┐
│               Three.js动画系统                   │
│  ┌──────────┐     ┌─────────────┐     ┌──────┐│
│  │ 用户输入 │────▶│动画控制器   │────▶│混合器││
│  └──────────┘     └─────────────┘     └──────┘│
│                            │                   │
│                    ┌───────┴───────┐           │
│                    │                │           │
│              ┌─────▼────┐   ┌──────▼─────┐     │
│              │ 基础动画  │   │ 附加动画   │     │
│              └──────────┘   └────────────┘     │
└─────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────┐
│               WebGL渲染管线                     │
│  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐    │
│  │ 模型 │──▶│ 骨骼 │──▶│ 动画 │──▶│ 渲染 │    │
│  └──────┘   └──────┘   └──────┘   └──────┘    │
└─────────────────────────────────────────────────┘
📊 数据结构设计
1. 动画配置对象
javascript
{
    weight: 0.5,      // 当前权重（0-1）
    action: null,     // THREE.AnimationAction对象
    clip: null        // THREE.AnimationClip对象
}
2. 状态管理
javascript
// 全局状态
{
    currentBaseAction: 'idle',  // 当前基础动画名称
    allActions: [],            // 所有动画动作数组
    mixer: null,               // 动画混合器实例
    crossFadeControls: []      // GUI控制器数组
}
🚀 技术亮点
模块化设计：代码结构清晰，功能模块分离

高性能动画：基于时间的更新，优化渲染性能

用户友好：直观的GUI，实时视觉反馈

可扩展性：易于添加新的动画和控制选项

跨平台：兼容现代浏览器，响应式设计 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js WebGL 动画演示 - 骨骼动画与附加动画混合 -->
		<title>Three.js WebGL - 附加动画混合与骨骼动画演示</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="main.css">
		<!-- 内联样式：页面特定样式 -->
		<style>
			/* 超链接样式：设置为蓝色 */
			a {
				color: blue;
			}
			/* 非激活状态的控制器按钮样式：设置为灰色 */
			.control-inactive button {
				color: #888;
			}
		</style>
	</head>
	<body>
		<!-- 3D场景渲染容器：Three.js将在此div中渲染3D内容 -->
		<div id="container"></div>
		<!-- 页面信息区域：显示项目信息和版权信息 -->
		<div id="info">
			<!-- 链接到Three.js官网 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 骨骼附加动画混合演示
			<!-- 模型来源信息：Mixamo是一个提供3D角色动画的网站 -->
			(模型来自 <a href="https://www.mixamo.com/" target="_blank" rel="noopener">Mixamo.com</a>)<br/>
			<!-- 功能说明：介绍本页面的核心功能 -->
			<small>本示例演示了如何将基础动画（行走、跑步）与附加动画（表情、姿势）进行混合</small>
		</div>

		<!-- 模块导入映射表：定义JavaScript模块的导入路径别名 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<script type="module">
			// 导入Three.js核心库的所有功能
			import * as THREE from 'three';

			// 导入Three.js的附加模块
			import Stats from 'three/addons/libs/stats.module.js';        // 性能统计模块：显示FPS、内存使用等
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js'; // 轻量级GUI库：创建控制面板
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; // 轨道控制器：实现相机旋转、平移
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';       // GLTF模型加载器：加载3D模型

			// ============ 全局变量声明区域 ============
			
			// Three.js核心对象
			let scene;      // 场景对象：包含所有3D物体、灯光、相机
			let renderer;   // 渲染器：负责将3D场景渲染到2D画布
			let camera;     // 相机：定义观察3D场景的视角
			let stats;      // 性能统计对象：显示帧率等性能指标
			
			// 动画相关对象
			let model;      // 3D模型对象：包含网格、材质、骨骼等
			let skeleton;   // 骨骼辅助对象：用于可视化模型的骨骼结构
			let mixer;      // 动画混合器：管理和混合多个动画
			let clock;      // 时钟对象：提供精确的时间计算，用于动画更新

			// 控制面板相关
			const crossFadeControls = []; // 存储交叉淡入淡出控制器的数组

			let currentBaseAction = 'idle'; // 当前正在播放的基础动画名称，默认为'idle'(空闲状态)
			
			// 所有动画动作的数组：包含基础动画和附加动画
			const allActions = [];
			
			// 基础动画配置对象：
			// weight: 动画权重（0-1），控制动画的影响程度
			// action: 动画动作对象（稍后赋值）
			const baseActions = {
				idle: { weight: 1 },    // 空闲动画：角色站立不动，初始权重为1（完全播放）
				walk: { weight: 0 },    // 行走动画：角色行走，初始权重为0（不播放）
				run: { weight: 0 }      // 跑步动画：角色跑步，初始权重为0（不播放）
			};
			
			// 附加动画配置对象：
			// 这些动画会叠加在基础动画之上，实现复杂的动画效果
			const additiveActions = {
				sneak_pose: { weight: 0 }, // 潜行姿势：角色弯腰潜行的姿势
				sad_pose: { weight: 0 },   // 悲伤姿势：角色表现悲伤的姿势
				agree: { weight: 0 },      // 点头同意：角色点头的动作
				headShake: { weight: 0 }   // 摇头：角色摇头的动作
			};
			
			// 其他变量
			let panelSettings;   // GUI面板的设置对象
			let numAnimations;   // 动画总数

			// 程序入口：调用初始化函数
			init();

			// ============ 初始化函数 ============
			// 功能：初始化Three.js场景、加载资源、设置事件监听
			function init() {
				// 获取DOM容器元素，Three.js将把Canvas画布添加到此元素中
				const container = document.getElementById( 'container' );
				
				// 创建Three.js时钟对象
				// 用途：提供精确的时间计算，确保动画在不同帧率下保持稳定速度
				clock = new THREE.Clock();

				// ============ 创建3D场景 ============
				scene = new THREE.Scene(); // 创建场景对象
				scene.background = new THREE.Color( 0xa0a0a0 ); // 设置场景背景颜色为浅灰色
				scene.fog = new THREE.Fog( 0xa0a0a0, 10, 50 ); // 添加雾效：颜色、近处距离、远处距离

				// ============ 创建灯光系统 ============
				
				// 创建半球光（环境光）：模拟天空和地面的环境光照
				const hemiLight = new THREE.HemisphereLight( 0xffffff, 0x8d8d8d, 3 );
				// 参数说明：天空颜色、地面颜色、光照强度
				hemiLight.position.set( 0, 20, 0 ); // 设置灯光位置（x, y, z）
				scene.add( hemiLight ); // 将灯光添加到场景

				// 创建平行光（主光源）：模拟太阳光，产生阴影
				const dirLight = new THREE.DirectionalLight( 0xffffff, 3 );
				dirLight.position.set( 3, 10, 10 ); // 设置灯光位置
				dirLight.castShadow = true; // 启用阴影投射
				
				// 配置阴影相机参数：定义阴影的渲染范围
				dirLight.shadow.camera.top = 2;      // 阴影相机上边界
				dirLight.shadow.camera.bottom = - 2; // 阴影相机下边界
				dirLight.shadow.camera.left = - 2;   // 阴影相机左边界
				dirLight.shadow.camera.right = 2;    // 阴影相机右边界
				dirLight.shadow.camera.near = 0.1;   // 阴影相机近平面
				dirLight.shadow.camera.far = 40;     // 阴影相机远平面
				scene.add( dirLight ); // 将平行光添加到场景

				// ============ 创建地面 ============
				const mesh = new THREE.Mesh( 
					new THREE.PlaneGeometry( 100, 100 ), // 创建平面几何体：宽度100，高度100
					new THREE.MeshPhongMaterial( {       // 使用Phong材质：支持高光反射
						color: 0xcbcbcb,                 // 地面颜色：浅灰色
						depthWrite: false                // 禁用深度写入：优化渲染性能
					} ) 
				);
				mesh.rotation.x = - Math.PI / 2; // 将平面旋转90度，使其水平放置（作为地面）
				mesh.receiveShadow = true;       // 允许地面接收阴影
				scene.add( mesh );               // 将地面添加到场景

				// ============ 加载3D模型和动画 ============
				const loader = new GLTFLoader(); // 创建GLTF加载器实例
				
				// 加载GLB格式的模型文件（包含模型、材质、动画）
				loader.load( 'models/gltf/Xbot.glb', function ( gltf ) {
					// 加载成功回调函数
					
					// 获取模型的主场景
					model = gltf.scene;
					scene.add( model ); // 将模型添加到3D场景

					// 遍历模型中的所有对象
					model.traverse( function ( object ) {
						// 检查对象是否为网格（Mesh）
						if ( object.isMesh ) {
							object.castShadow = true; // 启用网格的阴影投射
						}
					} );

					// 创建骨骼辅助对象：可视化模型的骨骼结构
					skeleton = new THREE.SkeletonHelper( model );
					skeleton.visible = false; // 默认隐藏骨骼（可切换显示）
					scene.add( skeleton );

					// 获取模型中的动画数据
					const animations = gltf.animations;
					
					// 创建动画混合器：用于管理和混合多个动画
					// 参数：动画的根对象（通常是模型本身）
					mixer = new THREE.AnimationMixer( model );

					// 记录动画总数
					numAnimations = animations.length;

					// ============ 处理所有动画剪辑 ============
					// 遍历动画数组，为每个动画创建动画动作
					for ( let i = 0; i !== numAnimations; ++ i ) {
						let clip = animations[ i ]; // 当前动画剪辑对象
						const name = clip.name;     // 动画名称

						// 判断动画类型并处理
						
						// 情况1：基础动画（idle, walk, run）
						if ( baseActions[ name ] ) {
							// 为动画剪辑创建动画动作
							const action = mixer.clipAction( clip );
							// 激活动画动作（设置权重并播放）
							activateAction( action );
							// 将动画动作存储到配置对象中
							baseActions[ name ].action = action;
							// 添加到所有动画动作数组
							allActions.push( action );

						} 
						// 情况2：附加动画（表情、姿势等）
						else if ( additiveActions[ name ] ) {
							// 关键步骤：将动画剪辑转换为附加动画格式
							// 附加动画的特点：不包含基础姿势，只包含相对于基础姿势的变化
							// 这样可以叠加在任意基础动画之上
							THREE.AnimationUtils.makeClipAdditive( clip );

							// 特殊处理：如果是姿势类动画（名称以_pose结尾）
							if ( clip.name.endsWith( '_pose' ) ) {
								// 创建子剪辑：从原动画中提取特定帧范围
								// 参数：原剪辑、新名称、起始帧、结束帧、帧率
								clip = THREE.AnimationUtils.subclip( clip, clip.name, 2, 3, 30 );
								// 这里提取第2-3帧（共30fps），用于创建静态姿势
							}

							// 为附加动画创建动画动作
							const action = mixer.clipAction( clip );
							// 激活动画动作
							activateAction( action );
							// 存储动画动作
							additiveActions[ name ].action = action;
							// 添加到所有动画动作数组
							allActions.push( action );
						}
						// 注意：如果动画既不是基础动画也不是附加动画，会被忽略
					}

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

					// 启动动画循环
					// setAnimationLoop是Three.js推荐的动画循环方法，替代原来的requestAnimationFrame
					renderer.setAnimationLoop( animate );

				} ); // 模型加载结束

				// ============ 创建WebGL渲染器 ============
				renderer = new THREE.WebGLRenderer( { 
					antialias: true // 启用抗锯齿，使边缘更平滑
				} );
				// 设置设备像素比：适配高DPI屏幕（如Retina显示屏）
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 启用阴影映射
				renderer.shadowMap.enabled = true;
				// 将渲染器的Canvas元素添加到DOM容器中
				container.appendChild( renderer.domElement );

				// ============ 创建相机 ============
				// 创建透视相机：模拟人眼视角，近大远小
				camera = new THREE.PerspectiveCamera( 
					45, // 视野角度（FOV），单位：度，越大看到的范围越广
					window.innerWidth / window.innerHeight, // 宽高比，保持与窗口一致
					1,   // 近裁剪面：距离相机多近开始渲染
					100  // 远裁剪面：距离相机多远停止渲染
				);
				// 设置相机位置（x, y, z）
				camera.position.set( -1, 2, 3 );

				// ============ 创建轨道控制器 ============
				// 允许用户通过鼠标/触摸控制相机旋转和平移
				const controls = new OrbitControls( camera, renderer.domElement );
				controls.enablePan = false;  // 禁用平移（保持相机水平位置固定）
				controls.enableZoom = false; // 禁用缩放（保持相机距离固定）
				controls.target.set( 0, 1, 0 ); // 设置控制目标点（相机围绕此点旋转）
				controls.update(); // 初始化更新控制器

				// ============ 创建性能统计面板 ============
				stats = new Stats();
				// 将统计面板的DOM元素添加到容器中
				container.appendChild( stats.dom );

				// ============ 事件监听器 ============
				// 监听窗口大小变化事件，调整相机和渲染器
				window.addEventListener( 'resize', onWindowResize );
			}

			// ============ 创建GUI控制面板函数 ============
			function createPanel() {
				// 创建GUI实例，设置宽度为310像素
				const panel = new GUI( { width: 310 } );

				// 创建三个折叠面板，用于组织不同的控制选项
				const folder1 = panel.addFolder( '基础动作' );        // 基础动画选择
				const folder2 = panel.addFolder( '附加动作权重' );    // 附加动画权重调节
				const folder3 = panel.addFolder( '全局速度' );        // 动画播放速度控制

				// 初始化面板设置对象
				panelSettings = {
					'modify time scale': 1.0 // 时间缩放因子：1.0为正常速度
				};

				// ============ 创建基础动作控制器 ============
				// 基础动作名称数组，包含"无"选项和所有基础动作
				const baseNames = [ '无', ...Object.keys( baseActions ) ];

				// 遍历基础动作名称，为每个动作创建控制器
				for ( let i = 0, l = baseNames.length; i !== l; ++ i ) {
					const name = baseNames[ i ];            // 当前动作名称
					const settings = baseActions[ name ];   // 对应的配置对象
					
					// 为每个动作创建回调函数，当用户选择该动作时执行
					panelSettings[ name ] = function () {
						// 获取当前基础动作的配置
						const currentSettings = baseActions[ currentBaseAction ];
						// 获取当前动作对象（可能为null）
						const currentAction = currentSettings ? currentSettings.action : null;
						// 获取新选择的动作对象（可能为null）
						const action = settings ? settings.action : null;

						// 只有当当前动作与新动作不同时，才执行交叉淡入淡出
						if ( currentAction !== action ) {
							// 准备动画切换，参数：当前动作、目标动作、过渡时间
							prepareCrossFade( currentAction, action, 0.35 );
						}
					};

					// 将控制器添加到面板，并保存到crossFadeControls数组
					crossFadeControls.push( folder1.add( panelSettings, name ) );
				}

				// ============ 创建附加动作权重控制器 ============
				// 遍历所有附加动作
				for ( const name of Object.keys( additiveActions ) ) {
					const settings = additiveActions[ name ]; // 获取动作配置

					// 将当前权重值添加到面板设置
					panelSettings[ name ] = settings.weight;
					
					// 创建滑块控制器
					folder2.add( panelSettings, name, 0.0, 1.0, 0.01 )
						.listen() // 监听值变化：当权重在其他地方被修改时，更新滑块显示
						.onChange( function ( weight ) {
							// 当滑块值改变时的回调函数
							setWeight( settings.action, weight ); // 设置动画权重
							settings.weight = weight;             // 更新配置对象中的权重值
						} );
				}

				// ============ 创建全局速度控制器 ============
				folder3.add( panelSettings, 'modify time scale', 0.0, 1.5, 0.01 )
					.onChange( modifyTimeScale ); // 值改变时调用modifyTimeScale函数

				// ============ 设置面板默认状态 ============
				// 打开所有折叠面板
				folder1.open();
				folder2.open();
				folder3.open();

				// ============ 设置控制器激活状态 ============
				// 为每个交叉淡入淡出控制器添加激活/非激活状态方法
				crossFadeControls.forEach( function ( control ) {
					// 设置控制器为非激活状态的方法
					control.setInactive = function () {
						// 添加CSS类，使按钮变为灰色
						control.domElement.classList.add( 'control-inactive' );
					};

					// 设置控制器为激活状态的方法
					control.setActive = function () {
						// 移除CSS类，恢复按钮正常颜色
						control.domElement.classList.remove( 'control-inactive' );
					};

					// 获取当前控制器对应的动作配置
					const settings = baseActions[ control.property ];

					// 如果没有配置或权重为0，设置为非激活状态
					if ( ! settings || ! settings.weight ) {
						control.setInactive();
					}
				} );
			}

			// ============ 激活动画动作函数 ============
			// 功能：初始化动画动作，设置权重并开始播放
			function activateAction( action ) {
				const clip = action.getClip(); // 获取动画剪辑对象
				// 查找对应的配置（可能在基础动画或附加动画中）
				const settings = baseActions[ clip.name ] || additiveActions[ clip.name ];
				setWeight( action, settings.weight ); // 设置动画权重
				action.play(); // 开始播放动画
			}

			// ============ 修改时间缩放函数 ============
			// 功能：控制所有动画的播放速度
			// 参数speed：时间缩放因子，1.0为正常速度，0.5为半速，2.0为双倍速
			function modifyTimeScale( speed ) {
				mixer.timeScale = speed; // 设置动画混合器的时间缩放
			}

			// ============ 准备交叉淡入淡出函数 ============
			// 功能：准备从一个动画切换到另一个动画
			// 参数：startAction（开始动作）、endAction（结束动作）、duration（过渡时间）
			function prepareCrossFade( startAction, endAction, duration ) {
				// 判断是否立即执行交叉淡入淡出
				// 条件1：当前基础动作是'idle'（可以立即切换）
				// 条件2：没有开始动作（淡入情况）
				// 条件3：没有结束动作（淡出情况）
				if ( currentBaseAction === 'idle' || ! startAction || ! endAction ) {
					// 立即执行交叉淡入淡出
					executeCrossFade( startAction, endAction, duration );
				} else {
					// 同步执行：等待当前动作完成当前循环再切换
					// 这样能避免动画在奇怪的位置切换
					synchronizeCrossFade( startAction, endAction, duration );
				}

				// ============ 更新控制器状态 ============
				// 确定新的当前基础动作
				if ( endAction ) {
					const clip = endAction.getClip();
					currentBaseAction = clip.name; // 更新为结束动作的名称
				} else {
					currentBaseAction = '无'; // 没有动作时设为'无'
				}

				// 更新所有控制器的视觉状态
				crossFadeControls.forEach( function ( control ) {
					const name = control.property; // 控制器对应的动作名称

					// 如果控制器对应的是当前动作，设为激活状态
					if ( name === currentBaseAction ) {
						control.setActive();
					} else {
						// 否则设为非激活状态
						control.setInactive();
					}
				} );
			}

			// ============ 同步交叉淡入淡出函数 ============
			// 功能：等待当前动画完成一个循环后再执行切换
			// 这能确保动画切换更自然，不会在动作中途突然切换
			function synchronizeCrossFade( startAction, endAction, duration ) {
				// 监听动画混合器的'loop'事件（动画循环完成时触发）
				mixer.addEventListener( 'loop', onLoopFinished );

				// 循环完成事件处理函数
				function onLoopFinished( event ) {
					// 检查完成循环的是否是起始动作
					if ( event.action === startAction ) {
						// 移除事件监听器，避免重复执行
						mixer.removeEventListener( 'loop', onLoopFinished );
						// 执行交叉淡入淡出
						executeCrossFade( startAction, endAction, duration );
					}
				}
			}

			// ============ 执行交叉淡入淡出函数 ============
			// 功能：实际执行动画之间的过渡
			function executeCrossFade( startAction, endAction, duration ) {
				// 情况1：有结束动作（切换或淡入）
				if ( endAction ) {
					// 关键：结束动作必须先设置权重为1
					setWeight( endAction, 1 );
					// 重置结束动作的播放时间为0，从头开始播放
					endAction.time = 0;

					// 情况1a：有开始动作（动画切换）
					if ( startAction ) {
						// 使用crossFadeTo进行动画切换
						// 参数：目标动作、过渡时间、是否启用扭曲（warping）
						// 扭曲功能：调整播放速度，使两个动画的特定点对齐
						startAction.crossFadeTo( endAction, duration, true );
					} 
					// 情况1b：没有开始动作（淡入）
					else {
						// 直接淡入结束动作
						endAction.fadeIn( duration );
					}
				} 
				// 情况2：没有结束动作（淡出）
				else {
					// 淡出开始动作
					startAction.fadeOut( duration );
				}
			}

			// ============ 设置动画权重函数 ============
			// 功能：设置动画动作的权重和状态
			// 说明：这个函数是必要的，因为crossFadeTo()会自动调整起始动作的时间缩放
			// 我们需要确保动作处于正确的状态
			function setWeight( action, weight ) {
				action.enabled = true; // 确保动作启用
				action.setEffectiveTimeScale( 1 ); // 重置时间缩放为正常速度
				action.setEffectiveWeight( weight ); // 设置有效权重
			}

			// ============ 窗口大小变化处理函数 ============
			// 功能：当浏览器窗口大小改变时，调整相机和渲染器
			function onWindowResize() {
				// 更新相机的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵（必须调用）
				camera.updateProjectionMatrix();

				// 更新渲染器大小为新的窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ============ 动画循环函数 ============
			// 功能：每一帧执行，更新动画和渲染场景
			// 这是Three.js应用的核心循环
			function animate() {
				// ============ 第一步：更新动画权重设置 ============
				// 遍历所有动画，更新配置对象中的权重值
				// 这样GUI面板可以正确显示当前权重
				for ( let i = 0; i !== numAnimations; ++ i ) {
					const action = allActions[ i ];      // 当前动画动作
					const clip = action.getClip();       // 获取对应的动画剪辑
					// 查找配置对象（可能在基础动画或附加动画中）
					const settings = baseActions[ clip.name ] || additiveActions[ clip.name ];
					// 从动作获取当前有效权重，更新到配置对象
					settings.weight = action.getEffectiveWeight();
				}

				// ============ 第二步：计算时间增量 ============
				// 获取自上一帧以来的时间（秒）
				// 这是动画系统的核心：基于时间而非帧率，确保动画速度一致
				const mixerUpdateDelta = clock.getDelta();

				// ============ 第三步：更新动画混合器 ============
				// 基于时间增量更新所有动画状态
				mixer.update( mixerUpdateDelta );

				// ============ 第四步：渲染场景 ============
				// 将3D场景渲染到2D画布
				renderer.render( scene, camera );

				// ============ 第五步：更新性能统计 ============
				// 更新FPS、内存等性能指标的显示
				stats.update();
			}
			// 注意：动画循环会持续运行，直到页面关闭或调用renderer.setAnimationLoop(null)
		</script>
	</body>
</html>