<!-- Three.js WebGPU 实例化变形动画演示
🎯 项目概述
这是一个基于 Three.js WebGPU 版本 的高级3D图形演示，展示了使用实例化渲染技术结合变形目标动画来高效渲染大量动画对象。场景中包含1024匹马模型实例，每匹马都独立播放奔跑动画，形成壮观的马群奔跑效果。

🏃‍♂️ 核心功能
1. 大规模实例化渲染
渲染数量：1024个独立实例

布局方式：32×32网格布局，形成马群阵列

位置随机：每个实例在网格位置基础上添加随机偏移，避免呆板的排列

颜色随机：每匹马使用HSL色彩空间的随机颜色，增强视觉多样性

2. 独立动画系统
变形动画：每匹马使用变形目标技术实现奔跑动作

时间偏移：为每个实例分配0-3秒的随机时间偏移，创造自然的非同步动画效果

实时更新：每帧更新所有实例的变形状态，通过纹理传输到GPU

3. 动态相机系统
环绕动画：相机围绕场景中心做圆周运动，同时上下起伏

自动聚焦：始终聚焦于场景中心（0,0,0）位置

平滑运动：使用三角函数实现平滑的相机轨迹

4. 完整光照与阴影
定向光：模拟太阳光，产生清晰阴影

半球光：模拟环境光照，提供柔和的天空和地面反射

阴影系统：支持投射阴影（马匹）和接收阴影（地面）

雾效：添加深度雾，增强场景的空间感和大气效果

⚙️ 主要技术点
1. WebGPU渲染
javascript
renderer = new THREE.WebGPURenderer({ antialias: true });
现代图形API：替代WebGL，提供更低的驱动开销

性能优势：更好的并行处理能力，适合大规模实例渲染

抗锯齿：启用硬件抗锯齿，提升视觉质量

2. 实例化网格（InstancedMesh）
javascript
mesh = new THREE.InstancedMesh(geometry, material, 1024);
单次绘制：1024个实例只需一次Draw Call

矩阵实例化：每个实例有自己的变换矩阵

颜色实例化：支持为每个实例设置不同颜色

性能优化：极大减少CPU-GPU通信开销

3. 变形目标动画
javascript
mesh.setMorphAt(i, dummy);
mesh.morphTexture.needsUpdate = true;
GPU加速：变形权重通过纹理传输到GPU

插值动画：在关键形状之间平滑过渡

独立控制：每个实例有独立的变形状态

4. 动画混合器系统
javascript
mixer = new THREE.AnimationMixer(glb.scene);
mixer.setTime(time + timeOffsets[i]);
时间管理：精确控制动画播放进度

状态隔离：每个实例独立的时间线

灵活控制：支持暂停、恢复、变速等操作

5. 阴影映射
javascript
light.shadow.mapSize.width = 2048;
light.shadow.mapSize.height = 2048;
renderer.shadowMap.enabled = true;
高质量阴影：2048×2048分辨率的阴影贴图

视锥体优化：合理设置阴影渲染范围

偏移调整：解决阴影痤疮问题

6. 资源加载与处理
javascript
const loader = new GLTFLoader();
loader.load('models/gltf/Horse.glb', callback);
GLTF格式：标准3D传输格式，包含几何体、材质、动画

异步加载：非阻塞资源加载

模型复用：单个模型几何体被1024个实例共享

🎨 视觉特效
1. 场景氛围
天空色：浅蓝色（0x99DDFF）背景

地面：绿色草地（0x669933）

雾效：从5000单位开始，到10000单位完全遮挡

2. 光照设计
主光角度：从右上方向下照射（200, 1000, 50）

阴影质量：大范围阴影，适合开阔场景

环境光：蓝色天空光 + 绿色地面反射

3. 颜色系统
javascript
new THREE.Color(`hsl(${Math.random() * 360}, 50%, 66%)`)
随机色调：0-360度随机选择

统一饱和度：50%饱和度

统一亮度：66%亮度，确保视觉协调

🔧 性能优化策略
1. 渲染优化
实例化渲染：大幅减少Draw Call数量

纹理存储：变形数据存储在纹理中，减少数据传输

视锥体裁剪：相机远裁剪面合理设置

2. 内存优化
几何体共享：所有实例共享同一个几何体数据

材质共享：所有实例使用相同的材质定义

纹理复用：避免重复加载资源

3. GPU优化
WebGPU管道：现代渲染管道，更好的GPU利用率

批处理：实例化本身就是一种批处理形式

数据对齐：使用Float32Array等类型化数组

🎮 交互与体验
1. 自动演示
自动开始：页面加载后自动运行

循环动画：无限循环的马群奔跑

动态相机：自动环绕场景，展示不同角度

2. 调试支持
javascript
renderer.inspector = new Inspector();
内置检查器：Three.js调试工具

场景检查：查看场景层次结构

性能分析：监控渲染性能

3. 响应式设计
窗口适应：自动调整渲染尺寸

像素比适配：支持高DPI显示器

视口配置：移动端友好设置

📊 技术指标
实例数量：1024个

渲染分辨率：自适应窗口大小

阴影分辨率：2048×2048

动画精度：60fps（取决于设备性能）

内存占用：高效，共享大部分资源

GPU使用：充分利用WebGPU并行能力

🚀 应用场景
这个演示展示了适用于以下场景的技术方案：

游戏开发：大规模军队、人群、动物群渲染

模拟仿真：交通流、人群行为模拟

数据可视化：大规模数据点的3D展示

影视特效：群体动画和特效制作

虚拟现实：高密度环境渲染

🔮 技术趋势
这个示例体现了现代3D图形技术的几个重要趋势：

WebGPU标准化：下一代Web图形API

实例化渲染普及：大规模场景的标准解决方案

GPU驱动动画：将动画计算转移到GPU

PBR材质系统：基于物理的渲染成为标准

glTF生态系统：3D内容的标准化传输格式 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 
			页面基础设置
			- title: 页面标题，显示在浏览器标签页上
			- charset: 字符编码设置为UTF-8，支持多语言字符
			- viewport: 视口设置，适配移动端设备，禁用用户缩放功能
		-->
		<title>Three.js WebGPU技术演示 - 实例化变形目标动画</title>
		<meta charset="utf-8">
		<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="example.css": 指向外部CSS文件的路径
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			页面信息展示区域
			id="info": 用于CSS样式选择和JavaScript操作的标识符
			这个div包含页面标题、描述和Three.js品牌信息
		-->
		<div id="info">
			<!-- 
				Three.js品牌logo链接
				- href: 指向Three.js官方网站
				- target="_blank": 在新标签页打开链接
				- rel="noopener": 安全属性，防止新页面通过window.opener访问原页面
				- class="logo-link": CSS类名，用于样式控制（通常包含背景图片）
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装容器，用于组织标题元素 -->
			<div class="title-wrapper">
				<!-- 主标题链接：Three.js官方网站 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：当前演示的名称 -->
				<span>实例化变形动画演示</span>
			</div>

			<!-- 
				演示描述文本
				<small>标签：表示旁注和小号字体，通常用于版权信息、免责声明等
			-->
			<small>
				本演示展示使用实例化渲染技术，渲染1024个马模型实例，每个实例通过变形目标技术独立播放动画。
				核心技术包括：WebGPU渲染、实例化网格、变形动画和动态阴影。
			</small>
			
			<!-- 添加技术要点说明 -->
			<div class="tech-points" style="margin-top: 50px;">
				<small>
					<strong>技术亮点：</strong><br>
					• WebGPU现代图形API渲染<br>
					• 1024个模型实例单次绘制<br>
					• 每个实例独立变形动画<br>
					• 实时动态阴影效果<br>
					• 相机环绕动画<br>
					• 随机时间偏移创造自然效果
				</small>
			</div>
		</div>

		<!-- 
			模块导入映射配置 (Import Maps)
			这是现代JavaScript模块系统的重要特性，允许定义模块标识符与具体文件路径的映射关系
			type="importmap": 指定脚本类型为模块导入映射
			
			作用：
			1. 简化导入语句：可以使用简短名称代替完整路径
			2. 版本管理：集中管理模块版本
			3. 路径别名：为长路径创建短别名
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					"three/webgpu": "../build/three.webgpu.js",
					"three/tsl": "../build/three.tsl.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module": 声明为ECMAScript模块，支持ES6模块语法
			模块特点：
			1. 自动启用严格模式
			2. 有自己的作用域，不会污染全局
			3. 支持顶级await
			4. 可以导入导出模块
		-->
		<script type="module">

			// ============ 模块导入区域 ============
			
			// 导入Three.js的WebGPU版本
			// * as THREE: 将所有导出内容作为一个对象导入，通过THREE.访问
			import * as THREE from 'three/webgpu';

			// 从Three.js扩展库导入特定功能
			// GLTFLoader: GLTF/GLB格式的3D模型加载器，支持包含动画、材质、纹理的完整场景
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			// Inspector: 3D场景调试检查器，可以查看场景结构、对象属性等
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ============ 全局变量声明 ============
			
			// 核心Three.js对象变量声明
			let camera;     // 相机对象：控制视图和投影
			let scene;      // 场景对象：包含所有3D对象的容器
			let renderer;   // 渲染器对象：负责将3D场景渲染到2D画布
			let mesh;       // 实例化网格对象：包含1024个马实例
			let mixer;      // 动画混合器：管理和播放动画
			let dummy;      // 临时对象：用于处理单个实例的动画状态

			// 常量定义
			const offset = 5000; // 网格布局的基准偏移量，用于控制实例分布范围

			// 创建时间偏移数组：为每个实例提供不同的动画起始时间
			// Float32Array: 32位浮点型数组，性能优于普通数组，适合WebGL/WebGPU
			// 长度1024：对应1024个实例
			const timeOffsets = new Float32Array( 1024 );

			// 初始化时间偏移数组：为每个实例分配0-3秒的随机时间偏移
			// 这使得动画不同步，创造更自然的效果（如同真实马群的奔跑）
			for ( let i = 0; i < 1024; i ++ ) {
				// Math.random()返回0-1之间的随机数，*3得到0-3秒的偏移
				timeOffsets[ i ] = Math.random() * 3;
			}

			// 创建Three.js时钟对象，用于精确的时间管理
			// true参数表示时钟自动开始计时
			const clock = new THREE.Clock( true );

			// ============ 初始化函数调用 ============
			// 页面加载完成后调用init函数，开始设置3D场景
			init();

			// ============ 函数定义区域 ============

			/**
			 * 初始化函数 - Three.js应用程序的入口点
			 * 作用：创建和配置所有必要的Three.js对象，设置场景、相机、灯光、加载模型等
			 * 执行流程：
			 * 1. 创建相机和场景
			 * 2. 设置灯光系统
			 * 3. 创建地面
			 * 4. 加载马模型并创建实例化网格
			 * 5. 设置渲染器
			 * 6. 绑定窗口事件
			 */
			function init() {

				// ---------- 相机设置 ----------
				// 创建透视相机：模拟人眼视角，物体近大远小
				// 参数说明：
				// 60 - 视野角度（FOV），单位度，60度接近人眼自然视野
				// window.innerWidth / window.innerHeight - 宽高比，适应浏览器窗口
				// 100 - 近裁剪平面，距离相机100单位以内的物体不渲染
				// 10000 - 远裁剪平面，距离相机10000单位以外的物体不渲染
				camera = new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 100, 10000 );

				// ---------- 场景设置 ----------
				// 创建场景对象：所有3D对象的容器
				scene = new THREE.Scene();
				// 设置场景背景颜色：浅蓝色（十六进制颜色码）
				// 0x99DDFF 分解：0x表示十六进制，99=蓝色，DD=绿色，FF=红色（WebGL中颜色顺序是RGB）
				scene.background = new THREE.Color( 0x99DDFF );
				// 添加雾效：模拟大气透视，增强深度感
				// 参数：雾的颜色，雾开始的距离，雾完全遮盖物体的距离
				scene.fog = new THREE.Fog( 0x99DDFF, 5000, 10000 );

				// ---------- 灯光系统设置 ----------
				
				// 1. 主定向光 - 模拟太阳光
				// 参数：颜色（白色），强度（1.0）
				const light = new THREE.DirectionalLight( 0xffffff, 1 );
				// 设置光源位置：x=200, y=1000, z=50
				light.position.set( 200, 1000, 50 );

				// 阴影配置
				// 阴影贴图分辨率：影响阴影质量，越高越清晰但性能消耗越大
				light.shadow.mapSize.width = 2048;      // 阴影贴图宽度2048像素
				light.shadow.mapSize.height = 2048;     // 阴影贴图高度2048像素
				light.castShadow = true;                // 启用阴影投射

				// 阴影相机视锥体设置：定义阴影的渲染范围
				// 这是一个正交相机，用于生成深度贴图
				light.shadow.camera.left = - 5000;      // 左边界
				light.shadow.camera.right = 5000;       // 右边界
				light.shadow.camera.top = 5000;         // 上边界
				light.shadow.camera.bottom = - 5000;    // 下边界
				light.shadow.camera.far = 2000;         // 阴影渲染最远距离

				// 阴影偏移：解决阴影痤疮问题（阴影与表面错误交互）
				// 负值将阴影稍微远离表面
				light.shadow.bias = - 0.01;

				// 更新阴影相机的投影矩阵：应用上面的参数设置
				light.shadow.camera.updateProjectionMatrix();

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

				// 2. 半球光 - 模拟环境光照（天空和地面的颜色反射）
				// 参数：天空颜色（浅蓝），地面颜色（绿色），强度（1/3）
				const hemi = new THREE.HemisphereLight( 0x99DDFF, 0x669933, 1 / 3 );
				scene.add( hemi );

				// ---------- 地面设置 ----------
				
				// 创建地面网格
				// PlaneGeometry: 平面几何体，参数：宽度，高度，宽度分段，高度分段
				// 这里创建非常大的平面（1000000x1000000单位）以确保视野范围内都有地面
				const ground = new THREE.Mesh(
					new THREE.PlaneGeometry( 1000000, 1000000 ),
					// MeshStandardMaterial: 基于物理的材质，支持光照和阴影
					new THREE.MeshStandardMaterial( { color: 0x669933 } ) // 绿色材质
				);
				// 旋转地面：默认平面是垂直的，需要旋转90度使其水平
				// -Math.PI/2 表示逆时针旋转90度
				ground.rotation.x = - Math.PI / 2;
				// 启用阴影接收：地面可以接收其他物体投射的阴影
				ground.receiveShadow = true;
				// 将地面添加到场景
				scene.add( ground );

				// ---------- 3D模型加载 ----------
				
				// 创建GLTF加载器实例
				const loader = new GLTFLoader();

				// 加载马模型文件
				// 参数1: 模型文件路径
				// 参数2: 加载完成后的回调函数，接收加载的glb对象
				loader.load( 'models/gltf/Horse.glb', function ( glb ) {
					// glb对象包含场景、动画、相机等信息
					
					// 获取模型中的第一个子对象（通常是网格对象）
					// glb.scene是包含所有模型对象的组
					// children[0]获取第一个子对象（马模型）
					dummy = glb.scene.children[ 0 ];

					// 创建实例化网格对象
					// InstancedMesh是Three.js的特殊网格，可以高效渲染大量相同几何体的实例
					// 参数说明：
					// 1. dummy.geometry - 马的几何体数据（顶点、面、UV等）
					// 2. new THREE.MeshStandardNodeMaterial - 节点材质（Three.js的新材质系统）
					//    { flatShading: true } - 平面着色，每个面呈现平坦效果，适合低多边形风格
					// 3. 1024 - 实例数量
					mesh = new THREE.InstancedMesh( 
						dummy.geometry,
						new THREE.MeshStandardNodeMaterial( {
							flatShading: true,
						} ), 
						1024
					);
					// 启用实例化网格的阴影投射
					mesh.castShadow = true;

					// ---------- 设置实例位置和颜色 ----------
					// 使用32x32的网格布局放置1024个实例（32*32=1024）
					// i: 实例索引，从0到1023
					// x, y: 网格坐标，从0到31
					for ( let x = 0, i = 0; x < 32; x ++ ) {
						for ( let y = 0; y < 32; y ++ ) {
							// 为每个实例设置随机位置
							// 位置计算：
							// X坐标: offset - 300*x + 随机偏移
							//   offset是基准偏移5000
							//   -300*x 使实例在X轴负方向排列
							//   +200*Math.random() 添加随机性
							// Y坐标: 0，放置在地面上
							// Z坐标: offset - 300*y，在Z轴负方向排列
							dummy.position.set( 
								offset - 300 * x + 200 * Math.random(),
								0,
								offset - 300 * y
							);

							// 更新dummy对象的变换矩阵
							// 矩阵包含位置、旋转、缩放信息
							dummy.updateMatrix();

							// 将dummy的矩阵应用到第i个实例
							// 这是实例化渲染的关键：每个实例有自己的变换矩阵
							mesh.setMatrixAt( i, dummy.matrix );

							// 为每个实例设置随机颜色
							// 使用HSL色彩模式：
							// H: 色调，0-360度随机
							// S: 饱和度，50%
							// L: 亮度，66%
							mesh.setColorAt( i, new THREE.Color( `hsl(${Math.random() * 360}, 50%, 66%)` ) );

							i ++; // 递增实例索引
						}
					}

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

					// ---------- 动画系统设置 ----------
					
					// 创建动画混合器：管理动画剪辑和时间
					// 参数：动画目标对象（这里使用glb.scene）
					mixer = new THREE.AnimationMixer( glb.scene );

					// 获取并播放第一个动画剪辑
					// glb.animations包含模型中的所有动画
					const action = mixer.clipAction( glb.animations[ 0 ] );
					// 开始播放动画
					action.play();
				} );

				// ---------- 渲染器设置 ----------
				
				// 创建WebGPU渲染器
				// WebGPURenderer是Three.js的WebGPU后端渲染器
				// { antialias: true }: 启用抗锯齿，平滑边缘
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用
				renderer.setAnimationLoop( animate );
				
				// 设置设备像素比
				// 在高DPI屏幕（如Retina）上渲染更清晰
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 启用阴影映射
				renderer.shadowMap.enabled = true;
				
				// 附加调试检查器
				// Inspector提供3D场景的调试界面
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ---------- 事件监听器 ----------
				
				// 监听窗口大小变化事件
				// 当浏览器窗口大小改变时，调用onWindowResize函数
				window.addEventListener( 'resize', onWindowResize );
			}

			/**
			 * 窗口大小变化处理函数
			 * 作用：当浏览器窗口大小改变时，调整相机和渲染器以适应新尺寸
			 * 这是响应式WebGL应用的必要功能
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 保持透视正确，避免图像拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 应用新的宽高比设置
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				// 使3D渲染填满整个窗口
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 动画循环函数
			 * 作用：每一帧执行，更新动画状态并渲染场景
			 * 这是Three.js应用的核心循环，通常以显示器刷新率运行（60fps）
			 */
			function animate() {
				// 获取从时钟启动到现在经过的时间（秒）
				// 用于基于时间的动画，确保动画速度与时间而非帧率绑定
				const time = clock.getElapsedTime();

				// ---------- 相机动画 ----------
				// 创建相机环绕动画，让相机围绕场景中心运动
				const r = 3000; // 环绕半径
				
				// 设置相机位置：
				// X: Math.sin(time/10)*r - 正弦运动，10秒完成一个周期
				// Y: 1500 + 1000*Math.cos(time/5) - 上下运动，基准高度1500，振幅1000，5秒周期
				// Z: Math.cos(time/10)*r - 余弦运动，与X轴配合形成圆周运动
				camera.position.set( 
					Math.sin( time / 10 ) * r,
					1500 + 1000 * Math.cos( time / 5 ),
					Math.cos( time / 10 ) * r
				);
				
				// 相机始终看向场景中心点(0,0,0)
				camera.lookAt( 0, 0, 0 );

				// ---------- 实例动画更新 ----------
				// 如果实例化网格已经加载完成
				if ( mesh ) {
					// 遍历所有1024个实例
					for ( let i = 0; i < 1024; i ++ ) {
						// 设置动画混合器的时间
						// 关键：每个实例使用不同的时间（当前时间+该实例的随机偏移）
						// 这创造了动画不同步的效果，使马群看起来更自然
						mixer.setTime( time + timeOffsets[ i ] );
						
						// 将dummy对象的当前变形状态应用到第i个实例
						// setMorphAt是InstancedMesh的特殊方法，用于更新实例的变形目标权重
						mesh.setMorphAt( i, dummy );
					}
					
					// 标记变形纹理需要更新
					// morphTexture存储所有实例的变形状态数据
					// needsUpdate=true告诉Three.js将更新的数据传输到GPU
					mesh.morphTexture.needsUpdate = true;
				}

				// ---------- 渲染场景 ----------
				// 调用渲染器的render方法，将3D场景渲染到2D画布
				// 参数：场景对象，相机对象
				renderer.render( scene, camera );
				
				// 注意：这个函数会自动被requestAnimationFrame或WebGPU的渲染循环调用
				// 形成连续的动画循环
			}

		</script>

	</body>
</html>