<!-- 一、代码功能概述
这是一个基于Three.js WebGPU和TSL着色器节点系统的动态精灵粒子演示。主要功能是创建并渲染200个在三维空间中运动的精灵粒子，每个粒子具有独立的动画效果，整体形成美观的视觉体验。

核心功能特点：
粒子系统创建：

生成200个精灵粒子，均匀分布在一个半径为500单位的球体表面上

每个粒子使用相同的纹理贴图（sprite1.png）

粒子之间保持适当的间距，形成球状分布

动态动画效果：

独立脉动缩放：每个粒子根据时间和自身位置进行周期性缩放，产生呼吸般的脉动效果

独立旋转：每个粒子以不同的速度绕自身中心旋转

整体旋转：整个粒子群沿X、Y、Z轴以不同速度旋转，形成复杂的空间运动轨迹

非同步动画：粒子间动画有相位差，避免机械的同步效果

视觉特效：

蓝色范围雾效：距离相机1500-2100单位范围内逐渐显现蓝色雾效，增强空间深度感

材质效果：使用纹理的alpha通道实现透明度，结合UV坐标产生色彩变化

抗锯齿渲染：启用WebGPU抗锯齿，确保边缘平滑

交互与响应：

自适应窗口大小，支持浏览器窗口动态调整

实时渲染，保持60fps流畅动画

支持高DPI屏幕（Retina显示）

二、主要技术点
1. WebGPU渲染技术（核心）
现代图形API：使用WebGPU替代传统的WebGL，性能更高，功能更强大

硬件加速：直接调用GPU进行渲染，支持更复杂的着色器计算

THREE.WebGPURenderer：Three.js的WebGPU渲染器实现

优势：更好的多线程支持、更低的CPU开销、更高效的内存管理

2. TSL节点着色器系统（关键技术）
Three.js Shading Language：Three.js的视觉编程系统

节点化材质：将材质属性表示为可连接的节点网络

javascript
// 节点网络示例
material.colorNode = textureNode.mul(uv()).mul(2).saturate();
material.opacityNode = textureNode.a;
material.rotationNode = userData('rotation', 'float');
主要节点类型：

texture()：纹理采样节点

uv()：UV坐标节点

userData()：用户数据绑定节点

fog()：雾效节点

rangeFogFactor()：范围雾效控制节点

3. 精灵材质自定义（材质系统）
SpriteNodeMaterial：专门用于精灵的节点材质

动态绑定机制：通过userData节点将材质属性与对象数据动态绑定

多通道控制：独立控制颜色、透明度、旋转等属性

实时更新：材质属性可以在运行时动态修改

4. 粒子系统架构（程序设计）
组（Group）管理：使用THREE.Group统一管理200个精灵

批量操作：通过遍历group.children批量更新粒子状态

数据驱动：每个粒子的状态存储在userData中

性能优化：最小化每帧的状态更新操作

5. 动画系统（时间与状态管理）
时间驱动：基于Date.now()的时间戳进行动画计算

正弦函数动画：使用Math.sin()产生平滑的周期性变化

javascript
// 脉动缩放公式
const scale = Math.sin(time + sprite.position.x * 0.01) * 0.3 + 1.0;
分层动画：

第一层：每个粒子独立缩放（本地动画）

第二层：每个粒子独立旋转（本地动画）

第三层：整个粒子群旋转（全局动画）

6. 雾效系统（视觉深度）
范围雾效：在特定距离范围内渐变的雾效

TSL雾节点：使用fog()和rangeFogFactor()节点

参数：1500单位开始，2100单位完全覆盖

效果：增强三维空间感，模拟大气透视

7. 响应式设计（适配性）
窗口大小监听：window.addEventListener('resize', ...)

相机宽高比更新：camera.aspect = width / height

渲染器尺寸同步：renderer.setSize(width, height)

设备像素比适配：renderer.setPixelRatio(window.devicePixelRatio)

8. 模块化架构（代码组织）
ES6模块导入：使用import语句导入依赖

Import Maps：模块路径映射配置

分离关注点：初始化、渲染、事件处理分离

可维护性：清晰的函数划分和注释

三、技术栈总结
技术层	具体实现	作用
渲染引擎	Three.js WebGPU	3D图形渲染
图形API	WebGPU	底层图形接口
着色语言	TSL节点系统	材质和效果定义
材质系统	SpriteNodeMaterial	精灵材质管理
几何类型	THREE.Sprite	2D精灵对象
动画系统	时间驱动+三角函数	动态效果生成
雾效系统	TSL雾节点	空间深度增强
响应式	窗口事件监听	多设备适配 -->


<html lang="zh-CN">
	<head>
		<!-- 
			页面元数据设置
			- 设置页面标题为中文，说明这是一个使用WebGPU和Three.js的精灵粒子演示
			- charset指定字符编码为UTF-8，确保中文正常显示
			- viewport设置移动端适配：禁止用户手动缩放，保持1:1的缩放比例
		-->
		<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样式文件，用于页面布局和美化 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			信息展示面板
			id="info"：为这个div元素设置标识符，便于CSS和JavaScript操作
			这个面板将显示在页面的某个位置（通常由CSS控制为左上角或右上角浮动）
		-->
		<div id="info">
			<!-- 
				Three.js官方网站链接
				- href：指向Three.js官网
				- target="_blank"：在新标签页打开链接
				- rel="noopener"：安全设置，防止新页面访问原页面的window对象
				- class="logo-link"：CSS类名，通常用于添加Three.js的logo背景图片
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
				<!-- 点击这个链接可以访问Three.js官方网站 -->
			</a>

			<!-- 标题包装容器，用于布局和样式控制 -->
			<div class="title-wrapper">
				<!-- 主标题链接：点击可以跳转到Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：显示当前演示的具体内容 -->
				<span>WebGPU精灵粒子演示</span>
			</div>

			<!-- 
				详细描述区域
				<small>标签表示小号字体，适合用于说明、注释等次要内容
				这里描述了本示例的核心技术特点
			-->
			<small>
				本示例展示了使用Three.js的节点着色器系统（TSL）创建的自定义精灵材质。
				实现了200个动态粒子的三维空间分布，每个粒子具有独立的旋转和脉动效果。
				采用WebGPU渲染技术，支持硬件加速，性能更优。
			</small>
			
		</div>

		<!-- 
			导入映射（Import Maps）
			这是现代JavaScript模块系统的一部分，允许我们定义模块的别名和路径
			type="importmap"：告诉浏览器这是一个导入映射配置
			作用：简化模块导入语句，避免冗长的相对路径
		-->
		<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"：表示这是一个ES6模块，支持模块化导入导出
			模块中的代码在严格模式下运行，有自己的作用域
		-->
		<script type="module">

			// ==================== 模块导入部分 ====================
			// 使用import语句导入所需的库和模块
			
			// 导入Three.js的WebGPU版本
			// * as THREE：将整个模块导出对象重命名为THREE，方便访问
			import * as THREE from 'three/webgpu';
			
			// 从three/tsl模块导入特定的着色器节点函数
			// 这些函数用于构建材质着色器网络
			import { 
				texture,    // 纹理节点：用于读取纹理贴图
				uv,         // UV坐标节点：提供纹理坐标
				userData,   // 用户数据节点：从对象的userData属性读取值
				fog,        // 雾效节点：创建雾效
				rangeFogFactor, // 范围雾效因子：控制雾效的起始和结束范围
				color       // 颜色节点：创建颜色值
			} from 'three/tsl';

			// ==================== 全局变量声明 ====================
			// 这些变量在整个模块中共享，用于存储Three.js的核心对象
			
			let camera;     // 相机对象：控制场景的观察视角
			let scene;      // 场景对象：包含所有的3D对象、灯光等
			let renderer;   // 渲染器对象：负责将3D场景渲染到2D画布上
			let map;        // 纹理贴图对象：存储精灵的纹理图片
			let group;      // 组对象：用于将多个精灵组织在一起，方便统一操作
			
			// 纹理图片的原始尺寸（默认值为1，加载纹理后更新为实际尺寸）
			let imageWidth = 1, imageHeight = 1;

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

			// ==================== 初始化函数定义 ====================
			/**
			 * 初始化函数
			 * 这是整个程序的入口点，负责创建和设置所有的Three.js对象
			 * 包括：场景、相机、渲染器、材质、几何体、灯光等
			 */
			function init() {
				// 1. 获取当前浏览器窗口的尺寸
				const width = window.innerWidth;   // 窗口宽度（像素）
				const height = window.innerHeight; // 窗口高度（像素）

				// 2. 创建透视相机（Perspective Camera）
				// 参数说明：
				// - 60: 视野角度（Field of View），单位是度，60度是常用值
				// - width/height: 宽高比，确保渲染内容不变形
				// - 1: 近裁剪面（Near Clipping Plane），距离相机1个单位以内的物体不显示
				// - 2100: 远裁剪面（Far Clipping Plane），距离相机2100个单位以外的物体不显示
				camera = new THREE.PerspectiveCamera(60, width / height, 1, 2100);
				// 设置相机位置：沿Z轴正方向移动1500个单位
				// 这样相机就位于场景中央，面向原点（0,0,0）
				camera.position.z = 1500;

				// 3. 创建场景
				scene = new THREE.Scene();
				// 设置场景的雾效（使用TSL节点系统）
				// fog()函数创建雾效，第一个参数是雾的颜色（蓝色）
				// rangeFogFactor()创建范围雾效，1500单位开始，2100单位完全覆盖
				// 这意味着物体越远，蓝色雾效越明显
				scene.fogNode = fog(color(0x0000ff), rangeFogFactor(1500, 2100));

				// 4. 创建精灵粒子系统
				const amount = 200;    // 精灵粒子的总数
				const radius = 500;    // 粒子分布的球体半径

				// 创建纹理加载器，用于从服务器加载图片纹理
				const textureLoader = new THREE.TextureLoader();

				// 加载精灵纹理图片
				// 参数1: 纹理图片的路径
				// 参数2: 加载完成后的回调函数
				map = textureLoader.load('textures/sprite1.png', (loadedMap) => {
					// 当纹理加载完成后，获取图片的实际尺寸
					// 这些尺寸将用于正确设置精灵的缩放比例
					imageWidth = loadedMap.image.width;   // 纹理图片的宽度（像素）
					imageHeight = loadedMap.image.height; // 纹理图片的高度（像素）
				});

				// 创建组对象，用于容纳所有的精灵粒子
				// 组可以看作是一个容器，可以对其中的所有子对象进行统一操作（如旋转、移动等）
				group = new THREE.Group();

				// 5. 创建自定义材质（使用TSL节点系统）
				// 首先创建纹理节点，将加载的纹理转换为着色器节点
				const textureNode = texture(map);

				// 创建SpriteNodeMaterial（精灵节点材质）
				// 这是一种特殊材质，专门用于精灵对象，支持节点系统
				const material = new THREE.SpriteNodeMaterial();
				
				// 设置材质的颜色节点：
				// - textureNode.mul(uv()): 将纹理颜色与UV坐标相乘
				// - .mul(2): 将结果乘以2，增强亮度
				// - .saturate(): 将颜色值限制在0-1之间（饱和化处理）
				// 最终效果：纹理颜色会根据UV坐标变化，产生色彩渐变效果
				material.colorNode = textureNode.mul(uv()).mul(2).saturate();
				
				// 设置材质的透明度节点：
				// - textureNode.a: 使用纹理的alpha通道（透明度通道）
				// 这意味着纹理中透明的部分，精灵也会是透明的
				material.opacityNode = textureNode.a;
				
				// 设置材质的旋转节点：
				// - userData('rotation', 'float'): 创建一个用户数据节点
				// - 这个节点会从精灵对象的userData.rotation属性中读取浮点数值
				// - 每个精灵可以有自己独立的旋转值
				material.rotationNode = userData('rotation', 'float');

				// 6. 批量创建精灵粒子
				for (let a = 0; a < amount; a++) {
					// 生成随机的方向向量（每个分量的范围是-0.5到0.5）
					const x = Math.random() - 0.5;
					const y = Math.random() - 0.5;
					const z = Math.random() - 0.5;

					// 使用上面创建的自定义材质实例化一个新的精灵
					const sprite = new THREE.Sprite(material);

					// 设置精灵的位置
					sprite.position.set(x, y, z);          // 设置初始位置
					sprite.position.normalize();           // 将位置向量归一化（长度为1）
					sprite.position.multiplyScalar(radius);// 乘以半径，将精灵分布到球面上

					// 为每个精灵设置独立的旋转初始值
					// userData是一个对象，可以存储任意自定义数据
					// 这里存储的rotation值会被上面的userData节点读取
					sprite.userData.rotation = 0;

					// 将精灵添加到组中
					// 组可以统一管理所有精灵，方便进行整体操作
					group.add(sprite);
				}

				// 7. 将精灵组添加到场景中
				// 只有添加到场景中的对象才会被渲染
				scene.add(group);

				// 8. 创建WebGPU渲染器
				// WebGPU是新一代的图形API，比WebGL性能更好，功能更强大
				// { antialias: true }: 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置渲染器的像素比
				// window.devicePixelRatio: 设备像素比（通常是1或2，视网膜屏是2）
				// 这确保在高DPI屏幕上也能清晰渲染
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器的大小为整个浏览器窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环
				// setAnimationLoop函数接受一个回调函数，这个函数会在每一帧被调用
				// 这里传入的是render函数，它包含了所有的动画逻辑
				renderer.setAnimationLoop(render);
				
				// 将渲染器的canvas元素添加到页面的body中
				// renderer.domElement就是canvas元素，所有的3D内容都绘制在上面
				document.body.appendChild(renderer.domElement);

				// 9. 添加窗口大小变化事件监听器
				// 当用户调整浏览器窗口大小时，需要更新相机和渲染器
				window.addEventListener('resize', onWindowResize);
			}

			// ==================== 窗口大小变化处理函数 ====================
			/**
			 * 处理浏览器窗口大小变化的函数
			 * 当窗口大小改变时，需要更新相机和渲染器，确保3D场景正确显示
			 */
			function onWindowResize() {
				// 获取新的窗口尺寸
				const width = window.innerWidth;
				const height = window.innerHeight;

				// 更新相机的宽高比
				// 如果不更新，画面会被拉伸或压缩
				camera.aspect = width / height;
				
				// 更新相机的投影矩阵
				// 这是必须的，让Three.js重新计算相机如何将3D空间映射到2D屏幕
				camera.updateProjectionMatrix();

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

			// ==================== 渲染循环函数 ====================
			/**
			 * 渲染循环函数（每帧执行）
			 * 这是Three.js动画的核心，每一帧都会调用这个函数
			 * 在这里更新物体的状态，然后重新渲染场景
			 * 
			 * @param {number} time - WebGPU渲染器传入的时间戳（单位：毫秒）
			 * 但我们这里使用Date.now()获取时间，以保持与原有代码一致
			 */
			function render() {
				// 1. 获取当前时间（以秒为单位）
				// Date.now()返回从1970年1月1日到现在的毫秒数
				// 除以1000转换为秒，方便用于三角函数计算
				const time = Date.now() / 1000;

				// 2. 更新每个精灵粒子的状态
				// group.children是一个数组，包含组中所有的精灵对象
				for (let i = 0, l = group.children.length; i < l; i++) {
					// 获取当前遍历到的精灵
					const sprite = group.children[i];
					
					// 计算精灵的缩放比例（产生脉动效果）
					// Math.sin(): 正弦函数，产生-1到1之间的周期性变化
					// time: 随时间变化
					// sprite.position.x * 0.01: 根据精灵的X坐标添加微小差异，使每个精灵的脉动不同步
					// * 0.3: 将振幅限制在0.3（避免变化过大）
					// + 1.0: 将范围从[-0.3, 0.3]偏移到[0.7, 1.3]
					const scale = Math.sin(time + sprite.position.x * 0.01) * 0.3 + 1.0;

					// 更新精灵的旋转值
					// 每个精灵的旋转速度不同：索引越大的精灵旋转越快
					// i/l: 标准化到0-1之间，第一个精灵最慢，最后一个精灵最快
					sprite.userData.rotation += 0.1 * (i / l);
					
					// 应用缩放效果到精灵
					// sprite.scale.set(x, y, z): 设置三个轴上的缩放
					// 乘以imageWidth/Height: 确保精灵保持纹理的原始宽高比
					// Z轴始终为1，因为精灵是2D对象，不需要在深度方向缩放
					sprite.scale.set(scale * imageWidth, scale * imageHeight, 1.0);
				}

				// 3. 旋转整个精灵组（所有精灵一起旋转）
				// 这产生了粒子群在三维空间中的整体运动
				// time * 系数：系数越大，旋转速度越快
				group.rotation.x = time * 0.5;   // 绕X轴旋转（俯仰角），中等速度
				group.rotation.y = time * 0.75;  // 绕Y轴旋转（偏航角），较快速度
				group.rotation.z = time * 1.0;   // 绕Z轴旋转（翻滚角），最快速度

				// 4. 渲染场景
				// 这是最关键的一步：将3D场景通过相机视角渲染到2D画布上
				// 参数1: 要渲染的场景对象
				// 参数2: 用于渲染的相机对象
				renderer.render(scene, camera);
			}

		</script>
	</body>
</html>