<!-- Three.js 3D角色动画演示系统
一、核心功能概述
1. 基础3D场景展示
创建完整的WebGL 3D渲染环境

实现角色模型的加载和显示

提供视觉辅助（地面、网格、灯光、雾效）

2. 高级动画控制系统
双轨动画系统：

基础状态动画：持续循环的Idle、Walking、Running等

表情动作动画：一次性的Jump、Wave、Punch等

面部表情控制：

通过变形目标独立控制面部各个表情

支持表情权重的精细调整

3. 智能动画过渡
平滑的动画切换和交叉淡化

表情动作完成后自动返回基础状态

防止动画播放状态的冲突

4. 交互式控制面板
三层控制结构：基础状态 → 表情动作 → 面部表情

实时参数调整和立即生效

直观的UI设计便于用户操作

二、主要技术点详解
1. Three.js核心架构
text
场景图(Scene Graph)
├── 相机(Camera) - 透视投影，定义观察视角
├── 灯光系统(Lighting)
│   ├── 半球光(HemisphereLight) - 环境光照
│   └── 平行光(DirectionalLight) - 主要光源
├── 几何物体(Geometry)
│   ├── 地面平面(PlaneGeometry)
│   ├── 网格辅助(GridHelper)
│   └── 角色模型(GLTF)
└── 材质系统(Material)
2. 动画系统架构
javascript
// 三级动画管理结构
AnimationClip (数据层)    // 存储关键帧数据
  ↓
AnimationAction (控制层)   // 控制播放行为
  ↓
AnimationMixer (管理层)    // 混合多个动画
关键技术：

AnimationMixer：动画调度中心，管理所有动画的时间线

Clip-Action机制：分离动画数据和播放控制

权重混合(Weight Blending)：实现动画平滑过渡

事件系统：监听动画完成事件

3. 骨骼动画(Skinning)
实现原理：

骨骼层级结构（Skeleton Hierarchy）

顶点权重（Vertex Weights）

骨骼变换矩阵（Bone Transformation Matrices）

技术优势：

内存效率高（只需存储骨骼变换）

动画质量好（支持复杂动作）

易于重用（同一骨骼可驱动不同模型）

4. 变形目标(Morph Targets)
实现原理：

存储多组顶点位置数据

通过权重插值混合不同形态

实时计算最终顶点位置

公式表示：

text
V_final = V_base + Σ(weight_i × (V_target_i - V_base))
应用场景：

面部表情控制

嘴唇同步

肌肉变形

5. GLTF模型加载与解析
javascript
GLTF文件结构
├── scene - 场景图数据
├── animations - 动画剪辑数组
├── skins - 骨骼皮肤数据
├── meshes - 几何体数据
└── materials - 材质数据
技术要点：

异步加载和渐进式渲染

资源依赖解析（纹理、缓冲区）

动画数据与几何体绑定

6. 性能优化技术
帧率无关动画：基于时间的动画更新

渲染优化：

视锥体裁剪

层次细节(LOD)

实例化渲染

内存管理：

资源重复使用

几何体合并

纹理压缩

7. GUI交互系统
javascript
控制面板架构
├── 状态控制层 (State Control)
│   ├── 下拉选择器
│   └── 自动动画切换
├── 动作控制层 (Emotion Control)
│   ├── 按钮触发
│   └── 事件监听恢复
└── 表情控制层 (Expression Control)
    └── 滑块精确控制
8. 响应式设计
视口适配：自动调整渲染分辨率

事件处理：窗口大小变化响应

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

三、技术实现亮点
1. 动画状态机设计
javascript
// 简化的状态机逻辑
状态管理 = {
  当前状态: 'Walking',
  待机状态: ['Idle', 'Walking', 'Running'],
  临时状态: ['Jump', 'Wave'],
  过渡时间: 0.5,
  恢复机制: 临时状态 → 当前状态
}
2. 混合动画技术
时间线同步：确保不同动画的相位对齐

权重计算：基于时间的权重插值算法

层级混合：允许不同身体部位独立动画

3. 渲染管道优化
text
渲染流程：
1. 场景更新 → 2. 动画计算 → 3. 矩阵变换
4. 视锥体裁剪 → 5. 材质准备 → 6. WebGL绘制
4. 内存管理策略
资源池：重复使用几何体和材质

延迟加载：按需加载高质量资源

缓存机制：存储计算结果避免重复计算 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题 -->
		<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">
		<!-- 内部样式定义 -->
		<style>
			/* 全局正文文字颜色为深灰色 */
			body {
				color: #222;
			}

			/* 所有链接颜色设置为浅蓝色 */
			a {
				color: #2fa1d6;
			}

			/* 段落样式：最大宽度、居中、内边距 */
			p {
				max-width: 600px;        /* 最大宽度限制 */
				margin-left: auto;       /* 左外边距自动，实现水平居中 */
				margin-right: auto;      /* 右外边距自动，实现水平居中 */
				padding: 0 2em;          /* 左右内边距2em，上下为0 */
			}
		</style>
	</head>

	<body>
		<!-- 页面顶部信息展示区域 -->
		<div id="info">
			<!-- 主标题：链接到Three.js官网 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> WebGL - 骨骼动画与变形目标演示<br />
			<!-- 功能描述段落 -->
			<p>
				<!-- 详细功能描述 -->
				本动画系统支持动画剪辑的单独播放、循环播放或与其他剪辑的平滑过渡。此示例展示了一个角色在多种基础动画状态中循环，
				然后平滑过渡到一次性动作。面部表情通过变形目标独立控制。
			</p>
			<!-- 模型来源和版权信息 -->
			模型由
			<!-- 模型原作者链接 -->
			<a href="https://www.patreon.com/quaternius" target="_blank" rel="noopener">Tomás Laulhé</a>制作，
			<!-- 模型修改者链接 -->
			修改由<a href="https://donmccurdy.com/" target="_blank" rel="noopener">Don McCurdy</a>完成。遵循CC0协议。<br />
		</div>

		<!-- ES模块导入映射配置 -->
		<!-- importmap用于定义模块别名，浏览器根据此配置解析import语句 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript代码模块 -->
		<script type="module">
			// ========== 模块导入部分 ==========
			// 导入Three.js核心库的所有功能
			import * as THREE from 'three';

			// 导入性能监视器（用于显示FPS、内存等性能指标）
			import Stats from 'three/addons/libs/stats.module.js';
			// 导入轻量级GUI库（用于创建调试控制面板）
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// 导入GLTF模型加载器（用于加载.glb或.gltf格式的3D模型）
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

			// ========== 全局变量声明 ==========
			// DOM元素引用
			let container;      // 主容器div
			let stats;         // 性能监视器实例
			
			// Three.js相关对象
			let clock;         // 用于跟踪时间的时钟对象
			let gui;           // GUI控制面板实例
			let mixer;         // 动画混合器，用于混合和管理多个动画
			let actions;       // 存储所有动画动作的对象（键值对：动作名->动作实例）
			let activeAction;  // 当前正在播放的动画动作
			let previousAction; // 上一个动画动作（用于动画过渡）
			
			// 3D场景对象
			let camera;        // 相机
			let scene;         // 场景（包含所有3D对象的容器）
			let renderer;      // 渲染器
			let model;         // 加载的3D模型
			let face;          // 模型的头部对象（用于控制面部变形）

			// 用于GUI控制的API对象，state属性控制基础动画状态
			const api = { state: 'Walking' };  // 初始状态为'行走'

			// ========== 初始化函数调用 ==========
			// 程序入口点，页面加载完成后立即执行
			init();

			/**
			 * 初始化函数
			 * 创建整个3D场景的基础环境：
			 * 1. 创建HTML容器
			 * 2. 设置相机、场景、灯光
			 * 3. 创建地面和辅助网格
			 * 4. 加载3D模型
			 * 5. 设置渲染器和事件监听
			 * 6. 添加性能监视器
			 */
			function init() {
				// ---------- 创建DOM容器 ----------
				// 创建一个div元素作为Three.js渲染的容器
				container = document.createElement('div');
				// 将容器添加到body中
				document.body.appendChild(container);

				// ---------- 相机设置 ----------
				// 创建透视相机（模拟人眼视角）
				// 参数：视野角度45度，宽高比，近裁剪面0.25单位，远裁剪面100单位
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.25, 100);
				// 设置相机位置（x, y, z坐标）
				camera.position.set(-5, 3, 10);
				// 设置相机看向的点（场景中心点偏上）
				camera.lookAt(0, 2, 0);

				// ---------- 场景设置 ----------
				// 创建主场景对象
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色
				scene.background = new THREE.Color(0xe0e0e0);
				// 添加雾效（颜色，近处开始距离，远处结束距离）
				// 雾效可以让远处的物体逐渐淡出，增加深度感
				scene.fog = new THREE.Fog(0xe0e0e0, 20, 100);

				// ---------- 时钟对象 ----------
				// 创建Three.js时钟，用于跟踪时间和计算帧间隔
				clock = new THREE.Clock();

				// ========== 灯光系统设置 ==========
				// 半球光：模拟天空和地面的环境光
				// 参数：天空颜色，地面颜色，光照强度
				const hemiLight = new THREE.HemisphereLight(0xffffff, 0x8d8d8d, 3);
				hemiLight.position.set(0, 20, 0);  // 将灯光放置在场景上方
				scene.add(hemiLight);  // 将灯光添加到场景

				// 平行光：模拟太阳光，产生阴影和明暗对比
				// 参数：颜色，光照强度
				const dirLight = new THREE.DirectionalLight(0xffffff, 3);
				dirLight.position.set(0, 20, 10);  // 设置灯光位置和方向
				scene.add(dirLight);

				// ========== 地面和网格设置 ==========
				// 地面平面：作为角色站立的基础
				// 创建平面几何体（宽2000，高2000）
				// 创建Phong材质（模拟光泽表面），颜色为浅灰色
				const mesh = new THREE.Mesh(
					new THREE.PlaneGeometry(2000, 2000),
					new THREE.MeshPhongMaterial({ 
						color: 0xcbcbcb,      // 地面颜色
						depthWrite: false     // 深度写入关闭，防止地面影响其他物体的深度测试
					})
				);
				// 将平面旋转-90度，使其从垂直变为水平
				mesh.rotation.x = -Math.PI / 2;
				scene.add(mesh);

				// 网格辅助线：帮助判断位置和比例
				// 参数：网格大小200单位，划分40格，网格线颜色
				const grid = new THREE.GridHelper(200, 40, 0x000000, 0x000000);
				grid.material.opacity = 0.2;     // 设置透明度为20%
				grid.material.transparent = true; // 启用透明度
				scene.add(grid);

				// ========== 加载3D模型 ==========
				// 创建GLTF加载器实例
				const loader = new GLTFLoader();
				// 加载机器人模型
				loader.load(
					// 模型文件路径
					'models/gltf/RobotExpressive/RobotExpressive.glb',
					
					// 加载成功回调函数
					function (gltf) {
						// gltf.scene包含整个加载的场景（包括模型、灯光、相机等）
						model = gltf.scene;
						// 将模型添加到主场景
						scene.add(model);
						
						// 模型加载完成后创建GUI控制面板
						// 传入模型和动画数据
						createGUI(model, gltf.animations);
					},
					
					// 加载进度回调（此处未实现）
					undefined,
					
					// 加载失败回调函数
					function (e) {
						// 在控制台输出错误信息
						console.error(e);
					}
				);

				// ========== 渲染器设置 ==========
				// 创建WebGL渲染器，开启抗锯齿
				renderer = new THREE.WebGLRenderer({ antialias: true });
				// 设置设备像素比（适配高清屏幕）
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环回调函数（替代旧的requestAnimationFrame）
				renderer.setAnimationLoop(animate);
				// 将渲染器的canvas元素添加到容器中
				container.appendChild(renderer.domElement);

				// ========== 事件监听器 ==========
				// 监听窗口大小变化事件
				window.addEventListener('resize', onWindowResize);

				// ========== 性能监视器 ==========
				// 创建Stats.js性能监视器实例
				stats = new Stats();
				// 将监视器的DOM元素添加到容器中
				container.appendChild(stats.dom);
			}

			/**
			 * 创建GUI控制面板
			 * 该函数在模型加载完成后调用，创建完整的控制界面
			 * 
			 * @param {THREE.Object3D} model - 已加载的3D模型对象
			 * @param {Array<THREE.AnimationClip>} animations - 模型包含的动画剪辑数组
			 */
			function createGUI(model, animations) {
				// 定义基础动画状态（循环播放）
				// 这些状态会持续循环播放，直到切换到其他状态
				const states = ['Idle', 'Walking', 'Running', 'Dance', 'Death', 'Sitting', 'Standing'];
				
				// 定义表情动作（一次性播放）
				// 这些动作播放一次后会自动返回到之前的状态
				const emotes = ['Jump', 'Yes', 'No', 'Wave', 'Punch', 'ThumbsUp'];

				// 创建GUI实例
				// lil-gui是一个轻量级的调试界面库
				gui = new GUI();

				// 创建动画混合器
				// AnimationMixer是Three.js的动画系统核心，管理动画的播放、混合和过渡
				mixer = new THREE.AnimationMixer(model);

				// 初始化actions对象，用于存储所有动画动作
				actions = {};

				// 遍历所有动画剪辑，创建对应的动画动作
				for (let i = 0; i < animations.length; i++) {
					// 获取当前动画剪辑
					const clip = animations[i];
					// 从动画剪辑创建动画动作
					// clipAction方法将AnimationClip转换为AnimationAction
					const action = mixer.clipAction(clip);
					
					// 将动画动作存储到actions对象中，使用动画名作为键
					actions[clip.name] = action;

					// 特殊处理：对表情动画和部分状态动画设置播放参数
					// 检查当前动画是否是表情动画或states数组中索引>=4的动画
					if (emotes.indexOf(clip.name) >= 0 || states.indexOf(clip.name) >= 4) {
						// 设置动画播放结束时保持在最后一帧
						// 这对于死亡、坐下等动画很重要，避免突然跳回第一帧
						action.clampWhenFinished = true;
						
						// 设置动画循环模式为只播放一次
						// THREE.LoopOnce表示不循环
						action.loop = THREE.LoopOnce;
					}
				}

				// ========== 基础状态控制面板 ==========
				// 在GUI中创建一个名为"States"的折叠面板
				const statesFolder = gui.addFolder('基础状态');
				
				// 添加状态选择下拉框
				// 绑定到api.state属性，选项为states数组
				// 当用户选择不同状态时，api.state的值会改变
				const clipCtrl = statesFolder.add(api, 'state').options(states);
				
				// 监听状态变化事件
				clipCtrl.onChange(function () {
					// 当状态改变时，执行动画过渡
					// 参数：目标状态名，过渡时间0.5秒
					fadeToAction(api.state, 0.5);
				});
				
				// 默认展开状态控制面板
				statesFolder.open();

				// ========== 表情动作控制面板 ==========
				// 创建表情动作的折叠面板
				const emoteFolder = gui.addFolder('表情动作');

				/**
				 * 创建表情动作的回调函数
				 * 为每个表情动作创建一个函数，当点击GUI按钮时执行
				 * 
				 * @param {string} name - 表情动作的名称
				 */
				function createEmoteCallback(name) {
					// 在api对象上动态添加方法
					// 方法名与表情动作名相同
					api[name] = function () {
						// 执行动画过渡到指定表情动作，过渡时间0.2秒
						fadeToAction(name, 0.2);
						
						// 监听动画混合器的"finished"事件
						// 当表情动作播放完成后，恢复之前的基础状态
						mixer.addEventListener('finished', restoreState);
					};
					
					// 将这个方法添加到表情控制面板中
					// 这会创建一个按钮，点击时触发上面定义的函数
					emoteFolder.add(api, name);
				}

				/**
				 * 恢复基础状态函数
				 * 当表情动作播放完成后调用，切换回之前的基础动画状态
				 */
				function restoreState() {
					// 移除事件监听器，避免重复触发
					mixer.removeEventListener('finished', restoreState);
					
					// 切换回当前的基础状态，过渡时间0.2秒
					fadeToAction(api.state, 0.2);
				}

				// 为每个表情动作创建控制按钮
				for (let i = 0; i < emotes.length; i++) {
					createEmoteCallback(emotes[i]);
				}
				
				// 默认展开表情控制面板
				emoteFolder.open();

				// ========== 面部表情控制面板 ==========
				// 获取模型的头部对象
				// 通过对象名'Head_4'在模型场景图中查找
				face = model.getObjectByName('Head_4');
				
				// 获取头部所有的变形目标（表情）名称
				// morphTargetDictionary是一个对象，键为表情名，值为索引
				const expressions = Object.keys(face.morphTargetDictionary);
				
				// 创建面部表情控制面板
				const expressionFolder = gui.addFolder('面部表情');

				// 为每个面部表情创建滑块控制器
				for (let i = 0; i < expressions.length; i++) {
					// 创建滑块控制面部表情的权重（影响程度）
					// 参数：
					// - face.morphTargetInfluences: 变形目标权重数组
					// - i: 控制第i个表情
					// - 0: 最小值
					// - 1: 最大值
					// - 0.01: 步进值
					expressionFolder.add(face.morphTargetInfluences, i, 0, 1, 0.01)
						.name(expressions[i]);  // 设置滑块标签为表情名称
				}

				// ========== 初始动画设置 ==========
				// 设置初始活动动作为"行走"
				activeAction = actions['Walking'];
				// 开始播放动画
				activeAction.play();
				
				// 默认展开面部表情控制面板
				expressionFolder.open();
			}

			/**
			 * 动画过渡函数
			 * 实现动画之间的平滑淡入淡出过渡
			 * 
			 * @param {string} name - 要切换到的动画名称
			 * @param {number} duration - 过渡持续时间（秒）
			 */
			function fadeToAction(name, duration) {
				// 保存当前正在播放的动作
				previousAction = activeAction;
				// 获取目标动作
				activeAction = actions[name];

				// 如果当前动作和目标动作不同，执行淡出
				if (previousAction !== activeAction) {
					// 淡出当前动作，duration秒内权重降为0
					previousAction.fadeOut(duration);
				}

				// 设置并播放新动作
				activeAction
					.reset()                     // 重置动画到起始状态
					.setEffectiveTimeScale(1)    // 设置播放速度（1表示正常速度）
					.setEffectiveWeight(1)       // 设置权重为1（完全影响）
					.fadeIn(duration)            // 淡入动画，duration秒内权重从0升到1
					.play();                     // 开始播放动画
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当浏览器窗口大小改变时调用，确保3D场景正确适配
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 窗口大小改变后，宽高比也会改变
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 更改相机参数后必须调用此方法
				camera.updateProjectionMatrix();
				
				// 更新渲染器的尺寸
				// 确保渲染输出与窗口大小一致
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数
			 * 每帧自动调用，是Three.js应用的核心循环
			 * 负责：
			 * 1. 更新动画
			 * 2. 渲染场景
			 * 3. 更新性能监视器
			 */
			function animate() {
				// 获取上一帧到当前帧的时间差（秒）
				// 用于确保动画在不同帧率下保持一致的速度
				const dt = clock.getDelta();

				// 如果动画混合器存在，更新动画状态
				// mixer.update()会根据时间差推进所有动画
				if (mixer) mixer.update(dt);

				// 渲染3D场景
				// 将相机视角下的场景绘制到canvas上
				renderer.render(scene, camera);

				// 更新性能监视器显示
				// 显示FPS、帧时间等性能指标
				stats.update();
			}
		</script>
	</body>
</html>