<!-- WebGPU鸟群模拟系统 - 功能描述与技术详解
🎯 项目概述
这是一个基于WebGPU和Three.js的实时鸟群行为模拟系统，实现了16,384只鸟的群体智能行为模拟与渲染。项目展示了现代Web图形编程的最新技术，包括GPU计算着色器、实例化渲染和物理模拟。

🕊️ 核心功能
1. 大规模鸟群模拟
模拟规模：同时模拟16,384只鸟的飞行行为

行为规则：基于Boids算法实现分离、对齐、凝聚三大群体行为

物理特性：每只鸟有独立的位置、速度和翅膀扇动相位

2. 实时交互系统
鼠标交互：鼠标移动会驱散鸟群，创建动态避让效果

相机控制：支持旋转、缩放和平移视角

参数调节：实时调整群体行为参数，观察不同效果

3. 视觉表现
动态翅膀动画：根据飞行速度和高度自然扇动翅膀

天空背景：渐变色的天空球体营造立体空间感

雾效系统：深度雾效增强场景的层次感和距离感

4. 性能优化
GPU加速计算：所有物理计算在GPU上并行执行

实例化渲染：一次性渲染所有鸟，极大减少绘制调用

帧率无关动画：使用deltaTime确保不同刷新率下的稳定表现

🔧 主要技术点
1. WebGPU图形API
javascript
// WebGPU渲染器初始化
renderer = new THREE.WebGPURenderer({ antialias: true, forceWebGL: false });
优势：相比WebGL，提供更低的驱动开销和更好的多线程支持

特性：原生支持计算着色器，适合大规模并行计算

兼容性：自动检测并优雅降级（本示例未实现WebGL回退）

2. Three.js着色器语言（TSL）
javascript
// TSL节点式着色器编程
const birdVertexTSL = Fn(() => {
    const position = positionLocal.toVar();
    // ... 节点操作
});
声明式编程：使用JavaScript语法编写着色器，更易读易维护

节点系统：将着色器操作抽象为可连接的节点

类型安全：编译时类型检查，减少运行时错误

3. GPU计算着色器
速度计算着色器
javascript
computeVelocity = Fn(() => {
    // 并行计算每只鸟的新速度
    const velocity = velocityStorage.element(birdIndex).toVar();
    // ... 应用群体规则
})()compute(BIRDS);
并行架构：每只鸟的计算在独立的GPU线程中执行

存储缓冲区：使用instancedArray在GPU内存中存储数据

线程同步：通过内存屏障确保计算顺序

Boids算法实现
javascript
// 三个交互区域的数学实现
If(percent.lessThan(separationThresh), () => {
    // 分离规则：避免碰撞
}).ElseIf(percent.lessThan(alignmentThresh), () => {
    // 对齐规则：统一方向
}).Else(() => {
    // 凝聚规则：向中心靠拢
});
4. 实例化渲染技术
javascript
const birdMesh = new THREE.InstancedMesh(birdGeometry, birdMaterial, BIRDS);
单次绘制调用：所有16,384只鸟通过一次GPU绘制命令完成

实例属性：通过instanceIndex在着色器中访问每只鸟的独有数据

性能优势：相比单独渲染每个对象，性能提升数百倍

5. 自定义几何体系统
javascript
class BirdGeometry extends THREE.BufferGeometry {
    constructor() {
        super();
        // 使用9个顶点定义鸟的三角形网格
        // 身体 + 左翅 + 右翅 = 3个三角形
    }
}
精简模型：仅用9个顶点（3个三角形）表示一只鸟

缓冲区优化：使用Float32Array存储顶点数据，内存连续

局部坐标系：在着色器中通过矩阵变换放置到正确位置

6. 高级渲染特性
动态翅膀动画
javascript
If(vertexIndex.equal(4).or(vertexIndex.equal(7)), () => {
    position.y = sin(newPhase).mul(5.0); // 正弦波翅膀扇动
});
相位系统：每只鸟有独立的翅膀扇动相位

速度影响：飞行越快，翅膀扇动频率越高

物理模拟：上升时翅膀扇动更剧烈

朝向计算
javascript
// 计算鸟朝向飞行方向的旋转矩阵
const maty = mat3(cosry, 0, negate(sinry), 0, 1, 0, sinry, 0, cosry);
const matz = mat3(cosrz, sinrz, 0, negate(sinrz), cosrz, 0, 0, 0, 1);
方向向量转矩阵：将速度方向转换为旋转矩阵

偏航和滚转：分别处理水平转向和倾斜飞行

矩阵组合：正确顺序应用旋转矩阵

7. 交互系统
鼠标射线检测
javascript
raycaster.setFromCamera(pointer, camera);
const closestPoint = rayOrigin.sub(rayDirection.mul(projectionLength));
屏幕到世界坐标：将2D鼠标位置转换为3D射线

距离计算：计算鸟到鼠标射线的最短距离

影响力衰减：距离越近，影响越大（平方反比）

实时参数调整
javascript
const gui = renderer.inspector.createParameters('鸟群行为参数');
gui.add(effectController.separation, 'value', 0.0, 100.0, 1.0).name('分离力');
即时反馈：参数调整立即影响GPU计算

统一变量：通过uniform节点在CPU和GPU间传递数据

可视化调试：Three.js Inspector提供实时调试界面

8. 性能优化技术
计算优化
避免开方运算：使用距离平方进行比较

提前退出：超出交互区域的鸟跳过计算

向量化操作：使用GPU原生向量运算

内存优化
紧凑数据布局：位置、速度、相位数据紧密排列

缓冲区复用：同一缓冲区在多个计算着色器间共享

PBO支持：Pixel Buffer Object确保WebGL2兼容性

渲染优化
禁用视锥体裁剪：对于大量快速移动的对象，裁剪开销大于收益

双面渲染：确保从任何角度都能看到鸟

中性色调映射：平衡HDR和LDR显示

🚀 技术架构
数据流架构
text
JavaScript CPU端
    ↓ (初始化)
GPU存储缓冲区 (位置、速度、相位)
    ↓ (每帧)
计算着色器1: 更新速度
    ↓ (GPU内存屏障)
计算着色器2: 更新位置和相位
    ↓
顶点着色器: 实例化渲染
    ↓
片元着色器: 像素着色
    ↓
屏幕显示
渲染管线
初始化阶段：创建几何体、材质、存储缓冲区

计算阶段：GPU并行计算群体行为

渲染阶段：实例化绘制所有鸟

后处理阶段：雾效、色调映射等效果

📊 性能指标
三角形数量：16,384只鸟 × 3个三角形 × 2面 = 98,304个三角形

计算并行度：16,384个GPU线程同时计算

内存占用：约1.5MB的顶点和实例数据

帧率目标：在支持WebGPU的现代硬件上保持60FPS

🎨 视觉效果特点
群体行为涌现：简单的个体规则产生复杂的群体模式

自然运动：基于物理的速度和位置更新

深度感知：雾效和透视相机创造立体空间感

实时响应：鼠标交互立即影响整个鸟群

🔮 扩展可能性
技术扩展
更复杂的鸟模型：增加细节层次（LOD）系统

环境交互：添加障碍物、风力、天气效果

多群体模拟：不同行为规则的鸟群交互

声音系统：根据群体行为添加环境音效

应用场景
游戏开发：NPC群体AI、粒子系统

数据可视化：大规模数据点的动态展示

教育演示：群体智能算法的直观展示

艺术创作：生成式艺术和动态视觉效果 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<title>three.js WebGPU - 计算鸟群模拟</title>
		<!-- 设置文档字符编码为UTF-8，支持中文显示 -->
		<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="example.css">
	</head>
	<body>
		<!-- 页面信息展示区域 -->
		<div id="info">
			<!-- Three.js官方Logo链接，点击跳转到Three.js官网 -->
			<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>WebGPU计算鸟群模拟</span>
			</div>
			
			<!-- 操作说明提示 -->
			<small>
				鼠标移动会影响鸟群的飞行轨迹<br>
				可以使用鼠标滚轮缩放，按住鼠标左键拖拽旋转视角<br>
				右侧面板可以调整鸟群的群体行为参数
			</small>
		</div>
		
		<!-- 
			模块导入映射配置（Import Maps）
			作用：定义JavaScript模块的导入路径映射关系
			说明：将模块标识符映射到实际的JavaScript文件路径
		-->
		<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模块，使用ES6模块语法
			type="module"表示这是一个ES6模块，支持import/export语法
		-->
		<script type="module">
			// 导入Three.js核心模块的WebGPU版本
			// WebGPU是新一代图形API，提供比WebGL更好的性能和功能
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js Shader Language）相关函数和节点
			// TSL允许使用JavaScript语法编写着色器，更易读易维护
			import {
				// 基本节点类型
				uniform,     // 统一变量节点，在着色器间共享的常量
				varying,     // 可变变量节点，在顶点和片元着色器间传递数据
				vec4,        // 四维向量节点
				
				// 数学运算节点
				add,         // 加法
				sub,         // 减法
				max,         // 最大值
				dot,         // 点积
				sin,         // 正弦
				cos,         // 余弦
				sqrt,        // 平方根
				length,      // 向量长度
				normalize,   // 向量归一化
				
				// 矩阵和向量操作
				mat3,        // 3x3矩阵
				negate,      // 取反（必须使用此函数，不能用"-"运算符）
				
				// 数据类型节点
				float,       // 浮点数节点
				uint,        // 无符号整数节点
				
				// 数据存储节点
				instancedArray,  // 实例化数组，用于存储每只鸟的数据
				
				// 变换矩阵节点
				cameraProjectionMatrix,  // 相机投影矩阵
				cameraViewMatrix,        // 相机视图矩阵
				modelWorldMatrix,        // 模型世界矩阵
				
				// 内置属性节点
				positionLocal,   // 局部空间位置
				instanceIndex,   // 实例索引（当前渲染的鸟的ID）
				vertexIndex,     // 顶点索引（当前顶点的ID）
				
				// 控制流节点
				Fn,      // 定义函数
				If,      // 条件判断
				Loop,    // 循环
				Continue // 继续下一次循环
			} from 'three/tsl';
			
			// 导入调试工具 - Inspector（检查器）
			// 提供3D场景的实时调试和参数调整界面
			import { Inspector } from 'three/addons/inspector/Inspector.js';
			
			// 导入轨道控制器 - OrbitControls
			// 允许用户用鼠标控制相机旋转、平移和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入WebGPU能力检测模块
			// 检查浏览器是否支持WebGPU，并提供回退方案
			import WebGPU from 'three/addons/capabilities/WebGPU.js';
			
			/* 
			=======================
			全局变量声明区域
			=======================
			*/
			
			// DOM元素变量
			let container;           // 主容器元素，用于承载整个3D场景
			
			// Three.js核心对象变量
			let camera;              // 相机对象，决定观察视角和投影方式
			let scene;               // 场景对象，包含所有3D对象和光源
			let renderer;            // 渲染器对象，负责将3D场景绘制到Canvas
			
			// 时间相关变量
			let last = performance.now();  // 上一帧的时间戳，用于计算时间增量
			
			// 交互相关变量
			let pointer;             // 2D指针坐标，存储鼠标在屏幕上的位置
			let raycaster;           // 射线投射器，将2D屏幕坐标转换为3D空间射线
			
			// GPU计算相关变量
			let computeVelocity;     // 计算速度的GPU计算着色器
			let computePosition;     // 计算位置的GPU计算着色器
			let effectController;    // 效果控制器，包含所有可调参数
			
			/* 
			=======================
			常量定义区域
			=======================
			*/
			
			// 鸟群规模 - 总共有16384只鸟
			// 这个数字是2的14次方，GPU计算时通常选择2的幂次方以获得最佳性能
			const BIRDS = 16384;
			
			// 速度限制 - 单只鸟的最大飞行速度
			// 防止鸟飞得过快，保持视觉效果自然
			const SPEED_LIMIT = 9.0;
			
			// 鸟群活动范围 - 鸟可以在800×800×800的立方体内自由飞行
			const BOUNDS = 800;
			
			// 范围的一半 - 用于计算随机位置时的偏移
			const BOUNDS_HALF = BOUNDS / 2;
			
			/* 
			=======================
			自定义几何体类：BirdGeometry
			功能：定义单只鸟的3D模型几何数据
			说明：每只鸟由3个三角形组成（身体、左翅、右翅），共9个顶点
			=======================
			*/
			class BirdGeometry extends THREE.BufferGeometry {
				constructor() {
					super(); // 调用父类THREE.BufferGeometry的构造函数
					
					// 计算顶点总数：3个三角形 × 每个三角形3个顶点 = 9个顶点
					const points = 3 * 3;
					
					// 创建顶点位置缓冲区属性
					// Float32Array：使用32位浮点数数组存储顶点坐标，精度高
					// 每个顶点有x、y、z三个坐标，所以数组长度是points * 3
					const vertices = new THREE.BufferAttribute(new Float32Array(points * 3), 3);
					
					// 将顶点属性添加到几何体，属性名为'position'
					// Three.js会根据这个属性渲染顶点位置
					this.setAttribute('position', vertices);
					
					// 当前顶点索引，用于跟踪在数组中的写入位置
					let v = 0;
					
					/* 
					辅助函数：verts_push
					功能：将一组顶点坐标推入顶点数组
					参数：可变参数，每个参数是一个顶点的x、y、z坐标
					说明：简化顶点数据添加过程
					*/
					function verts_push() {
						// 遍历所有传入的参数（顶点坐标）
						for (let i = 0; i < arguments.length; i++) {
							// 将坐标值依次存入顶点数组，然后递增索引
							vertices.array[v++] = arguments[i];
						}
					}
					
					// 翅膀跨度 - 控制鸟翅膀的宽度
					const wingsSpan = 20;
					
					/* 
					第一部分：鸟身体（一个三角形）
					坐标说明：使用局部坐标系，鸟头朝向正Z轴
					顶点1 (0, 0, -20): 尾部
					顶点2 (0, -8, 10): 身体底部
					顶点3 (0, 0, 30): 头部
					*/
					verts_push(
						0, 0, -20,   // 尾部顶点
						0, -8, 10,   // 底部顶点
						0, 0, 30     // 头部顶点
					);
					
					/* 
					第二部分：左翅膀（一个三角形）
					顶点1 (0, 0, -15): 翅膀根部后点
					顶点2 (-wingsSpan, 0, 5): 翅膀尖端（左侧）
					顶点3 (0, 0, 15): 翅膀根部前点
					*/
					verts_push(
						0, 0, -15,           // 翅膀根部后点
						-wingsSpan, 0, 5,    // 翅膀尖端（左侧，负X方向）
						0, 0, 15             // 翅膀根部前点
					);
					
					/* 
					第三部分：右翅膀（一个三角形）
					顶点1 (0, 0, 15): 翅膀根部前点
					顶点2 (wingsSpan, 0, 5): 翅膀尖端（右侧）
					顶点3 (0, 0, -15): 翅膀根部后点
					*/
					verts_push(
						0, 0, 15,            // 翅膀根部前点
						wingsSpan, 0, 5,     // 翅膀尖端（右侧，正X方向）
						0, 0, -15            // 翅膀根部后点
					);
					
					// 几何体缩放：将鸟模型缩小到原始大小的20%
					// 这样鸟的大小更符合场景比例
					this.scale(0.2, 0.2, 0.2);
				}
			}
			
			/* 
			=======================
			WebGPU兼容性检测
			功能：检查浏览器是否支持WebGPU API
			说明：如果浏览器不支持WebGPU，显示错误信息并终止执行
			=======================
			*/
			
			// TODO: 未来可能需要添加WebGL回退方案
			
			// 检测WebGPU是否可用
			if (WebGPU.isAvailable() === false) {
				// 获取预制的错误信息HTML元素并添加到页面
				document.body.appendChild(WebGPU.getErrorMessage());
				// 抛出错误，停止JavaScript执行
				throw new Error('浏览器不支持WebGPU，请使用支持WebGPU的浏览器（如Chrome 113+、Edge 113+）');
			}
			
			/* 
			=======================
			初始化函数：init()
			功能：初始化所有Three.js对象、场景、渲染器和交互
			说明：这是整个应用的入口点，创建所有必要的3D对象和设置
			=======================
			*/
			function init() {
				/* 
				----------------------------------------
				第一步：创建DOM容器和基础Three.js对象
				----------------------------------------
				*/
				
				// 创建主容器div元素，用于承载整个3D场景
				container = document.createElement('div');
				// 将容器添加到页面body中
				document.body.appendChild(container);
				
				/* 
				创建透视相机（PerspectiveCamera）
				参数说明：
				50: 垂直视野角度（FOV），单位度，类似人眼视角
				window.innerWidth / window.innerHeight: 宽高比
				1: 近裁剪面距离，距离相机1个单位以内的物体不显示
				5000: 远裁剪面距离，距离相机5000个单位以外的物体不显示
				*/
				camera = new THREE.PerspectiveCamera(
					50, 
					window.innerWidth / window.innerHeight, 
					1, 
					5000
				);
				
				// 设置相机初始位置：沿Z轴正方向1000个单位
				// 这样可以从远处观察整个鸟群
				camera.position.z = 1000;
				
				// 创建场景对象，所有3D对象（网格、光源等）都将添加到场景中
				scene = new THREE.Scene();
				
				// 添加雾效（Fog），增强场景的深度感和距离感
				// 参数：颜色（白色），近处雾开始的距离，远处雾完全覆盖的距离
				scene.fog = new THREE.Fog(0xffffff, 700, 3000);
				
				/* 
				----------------------------------------
				第二步：初始化交互系统
				----------------------------------------
				*/
				
				// 创建2D向量存储鼠标指针位置
				// 坐标范围：x和y都在-1到1之间（标准化设备坐标）
				pointer = new THREE.Vector2();
				
				// 创建射线投射器，用于将2D屏幕坐标转换为3D空间中的射线
				// 用于检测鼠标与3D对象的交互
				raycaster = new THREE.Raycaster();
				
				/* 
				----------------------------------------
				第三步：创建天空背景
				----------------------------------------
				*/
				
				// 创建二十面体几何体作为天空球的基础形状
				// 参数：半径1，细分级别6（细分越多球体越圆滑）
				const geometry = new THREE.IcosahedronGeometry(1, 6);
				
				// 创建节点材质（NodeMaterial），使用TSL定义着色器逻辑
				const material = new THREE.MeshBasicNodeMaterial({
					// colorNode: 定义颜色输出的节点逻辑
					// 使用顶点位置的y坐标创建垂直渐变颜色
					colorNode: varying(
						vec4(
							sub(0.25, positionLocal.y),   // 红色分量：0.25 - y
							sub(-0.25, positionLocal.y),  // 绿色分量：-0.25 - y
							add(1.5, positionLocal.y),    // 蓝色分量：1.5 + y
							1.0                           // 透明度：完全不透明
						)
					),
					// 渲染背面，因为天空球是从内部观察的
					side: THREE.BackSide
				});
				
				// 创建网格对象，将几何体和材质组合
				const mesh = new THREE.Mesh(geometry, material);
				
				// 旋转天空球，使渐变方向更自然
				mesh.rotation.z = 0.75;
				
				// 放大天空球，使其足够大包围整个场景
				mesh.scale.setScalar(1200);
				
				// 将天空球添加到场景
				scene.add(mesh);
				
				/* 
				----------------------------------------
				第四步：创建WebGPU渲染器
				----------------------------------------
				*/
				
				// 创建WebGPU渲染器
				renderer = new THREE.WebGPURenderer({
					antialias: true,      // 开启抗锯齿，使边缘更平滑
					forceWebGL: false     // 不强制使用WebGL回退
				});
				
				// 设置设备像素比，适配高DPI屏幕（如Retina显示屏）
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数，每一帧都会调用render函数
				renderer.setAnimationLoop(render);
				
				// 设置色调映射为中性色调映射，控制HDR到LDR的转换
				renderer.toneMapping = THREE.NeutralToneMapping;
				
				// 附加调试检查器到渲染器
				renderer.inspector = new Inspector();
				
				// 将渲染器的Canvas DOM元素添加到容器中
				container.appendChild(renderer.domElement);
				
				/* 
				----------------------------------------
				第五步：添加用户交互控制
				----------------------------------------
				*/
				
				// 创建轨道控制器，允许用户用鼠标控制相机
				const controls = new OrbitControls(camera);
				// 将控制器连接到渲染器的Canvas元素
				controls.connect(renderer.domElement);
				
				/* 
				----------------------------------------
				第六步：初始化鸟群数据
				----------------------------------------
				*/
				
				/* 
				创建鸟群数据数组：
				- 位置数组：每只鸟有x、y、z三个坐标，所以长度是BIRDS * 3
				- 速度数组：每只鸟有x、y、z三个速度分量，长度同样是BIRDS * 3
				- 相位数组：每只鸟的翅膀扇动相位，长度是BIRDS
				
				使用Float32Array的原因：
				1. GPU计算需要精确的浮点数
				2. Float32Array在内存中连续存储，传输到GPU效率高
				3. 与WebGPU的存储缓冲区兼容
				*/
				const positionArray = new Float32Array(BIRDS * 3);
				const velocityArray = new Float32Array(BIRDS * 3);
				const phaseArray = new Float32Array(BIRDS);
				
				// 为每只鸟生成随机初始数据
				for (let i = 0; i < BIRDS; i++) {
					// 生成随机位置：在-BOUNDS_HALF到BOUNDS_HALF范围内
					const posX = Math.random() * BOUNDS - BOUNDS_HALF;
					const posY = Math.random() * BOUNDS - BOUNDS_HALF;
					const posZ = Math.random() * BOUNDS - BOUNDS_HALF;
					
					// 将位置存入数组
					positionArray[i * 3 + 0] = posX;
					positionArray[i * 3 + 1] = posY;
					positionArray[i * 3 + 2] = posZ;
					
					// 生成随机速度方向：每个分量在-0.5到0.5之间
					const velX = Math.random() - 0.5;
					const velY = Math.random() - 0.5;
					const velZ = Math.random() - 0.5;
					
					// 将速度放大10倍，并存入数组
					velocityArray[i * 3 + 0] = velX * 10;
					velocityArray[i * 3 + 1] = velY * 10;
					velocityArray[i * 3 + 2] = velZ * 10;
					
					// 设置初始相位为1（翅膀扇动起始相位）
					phaseArray[i] = 1;
				}
				
				/* 
				----------------------------------------
				第七步：创建GPU存储节点
				----------------------------------------
				*/
				
				/* 
				创建实例化数组存储节点：
				- instancedArray: 创建一个可以在着色器中按实例索引访问的数组
				- 'vec3': 数组元素类型是三维向量
				- setName(): 为节点设置名称，便于调试时识别
				
				这些存储节点将在GPU计算着色器中被读写
				*/
				const positionStorage = instancedArray(positionArray, 'vec3').setName('positionStorage');
				const velocityStorage = instancedArray(velocityArray, 'vec3').setName('velocityStorage');
				const phaseStorage = instancedArray(phaseArray, 'float').setName('phaseStorage');
				
				/* 
				设置PBO（Pixel Buffer Object）属性：
				- 在WebGL2回退模式下，需要PBO来在GPU和CPU之间传输数据
				- WebGPU原生支持存储缓冲区，不需要PBO
				- 这里设为true是为了确保WebGL2回退能正常工作
				*/
				positionStorage.setPBO(true);
				velocityStorage.setPBO(true);
				phaseStorage.setPBO(true);
				
				/* 
				----------------------------------------
				第八步：定义鸟群行为控制参数
				----------------------------------------
				*/
				
				// 创建效果控制器对象，包含所有可调节的鸟群行为参数
				effectController = {
					// 分离力：鸟与鸟之间保持的最小距离，避免碰撞
					// 值越大，鸟之间相隔越远
					separation: uniform(15.0).setName('separation'),
					
					// 对齐力：鸟与相邻鸟保持相同飞行方向的程度
					// 值越大，鸟群飞行方向越一致
					alignment: uniform(20.0).setName('alignment'),
					
					// 凝聚力：鸟向群体中心靠拢的强度
					// 值越大，鸟群聚集得越紧密
					cohesion: uniform(20.0).setName('cohesion'),
					
					// 自由因子：鸟的随机运动程度
					// 值越大，鸟的运动越随机、越不受群体规则约束
					freedom: uniform(0.75).setName('freedom'),
					
					// 当前时间（毫秒），用于时间相关计算
					now: uniform(0.0),
					
					// 时间增量（秒），上一帧到当前帧的时间差
					// 用于确保在不同帧率下运动速度一致
					deltaTime: uniform(0.0).setName('deltaTime'),
					
					// 鼠标射线起点：从相机位置发出的射线的起点
					rayOrigin: uniform(new THREE.Vector3()).setName('rayOrigin'),
					
					// 鼠标射线方向：从相机指向鼠标所在3D位置的方向
					rayDirection: uniform(new THREE.Vector3()).setName('rayDirection')
				};
				
				/* 
				----------------------------------------
				第九步：创建鸟的渲染材质和网格
				----------------------------------------
				*/
				
				// 创建鸟的几何体实例
				const birdGeometry = new BirdGeometry();
				
				// 创建节点材质，使用TSL定义顶点着色器逻辑
				const birdMaterial = new THREE.NodeMaterial();
				
				/* 
				定义鸟的顶点着色器函数（使用TSL）
				功能：
				1. 根据相位计算翅膀扇动
				2. 根据飞行方向旋转鸟的模型
				3. 将鸟放置到正确的位置
				*/
				const birdVertexTSL = Fn(() => {
					// 获取当前顶点的局部位置，并转换为变量节点以便修改
					const position = positionLocal.toVar();
					
					// 获取当前鸟实例的相位（翅膀扇动周期）
					const newPhase = phaseStorage.element(instanceIndex).toVar();
					
					// 获取当前鸟实例的速度，并归一化得到方向
					const newVelocity = normalize(velocityStorage.element(instanceIndex)).toVar();
					
					/* 
					翅膀扇动逻辑：
					- 顶点索引4和7对应翅膀的特定顶点
					- 根据相位（正弦波）调整这些顶点的y坐标
					- 实现翅膀上下扇动的动画效果
					*/
					If(vertexIndex.equal(4).or(vertexIndex.equal(7)), () => {
						// 使用正弦函数创建周期性运动
						// sin(newPhase)产生-1到1的波动
						// 乘以5.0控制翅膀扇动幅度
						position.y = sin(newPhase).mul(5.0);
					});
					
					// 将顶点从局部空间转换到世界空间
					const newPosition = modelWorldMatrix.mul(position);
					
					/* 
					计算鸟的旋转矩阵，使其朝向飞行方向
					这是3D图形学中常见的"注视"（look-at）问题简化版
					*/
					
					// 调整速度向量的z分量符号，匹配坐标系
					newVelocity.z.mulAssign(-1.0);
					
					// 计算速度在XZ平面上的投影长度
					const xz = length(newVelocity.xz);
					
					// 常量1.0，用于后续计算
					const xyz = float(1.0);
					
					// 计算旋转所需的x分量
					const x = sqrt((newVelocity.y.mul(newVelocity.y)).oneMinus());
					
					// 计算绕Y轴旋转的余弦和正弦值
					const cosry = newVelocity.x.div(xz).toVar();
					const sinry = newVelocity.z.div(xz).toVar();
					
					// 计算绕Z轴旋转的余弦和正弦值
					const cosrz = x.div(xyz);
					const sinrz = newVelocity.y.div(xyz).toVar();
					
					/* 
					创建绕Y轴的旋转矩阵（偏航，Yaw）
					矩阵结构：
					[ cosry,  0, -sinry ]
					[   0,    1,    0   ]
					[ sinry,  0,  cosry ]
					*/
					const maty = mat3(
						cosry, 0, negate(sinry),
						0, 1, 0,
						sinry, 0, cosry
					);
					
					/* 
					创建绕Z轴的旋转矩阵（滚转，Roll）
					矩阵结构：
					[ cosrz,  sinrz, 0 ]
					[ -sinrz, cosrz, 0 ]
					[   0,      0,   1 ]
					*/
					const matz = mat3(
						cosrz, sinrz, 0,
						negate(sinrz), cosrz, 0,
						0, 0, 1
					);
					
					/* 
					组合旋转并应用：
					1. 先绕Z轴滚转
					2. 再绕Y轴偏航
					3. 最后加上鸟的世界位置
					*/
					const finalVert = maty.mul(matz).mul(newPosition);
					finalVert.addAssign(positionStorage.element(instanceIndex));
					
					/* 
					最终变换：将世界坐标转换为裁剪空间坐标
					裁剪空间坐标是GPU最终用于渲染的坐标
					变换顺序：局部坐标 -> 世界坐标 -> 视图坐标 -> 投影坐标
					*/
					return cameraProjectionMatrix.mul(cameraViewMatrix).mul(finalVert);
				});
				
				// 设置材质的顶点着色器节点
				birdMaterial.vertexNode = birdVertexTSL();
				
				// 设置材质为双面渲染，确保从任何角度都能看到鸟
				birdMaterial.side = THREE.DoubleSide;
				
				/* 
				创建实例化网格（InstancedMesh）
				实例化渲染是一种高效渲染大量相同几何体的技术
				参数：
				birdGeometry: 基础几何体
				birdMaterial: 材质
				BIRDS: 实例数量（16384只鸟）
				*/
				const birdMesh = new THREE.InstancedMesh(birdGeometry, birdMaterial, BIRDS);
				
				// 初始旋转：将整个鸟群绕Y轴旋转90度（π/2弧度）
				birdMesh.rotation.y = Math.PI / 2;
				
				// 禁用自动矩阵更新，因为我们使用GPU计算位置
				birdMesh.matrixAutoUpdate = false;
				
				// 禁用视锥体裁剪，对于大量快速移动的对象，裁剪开销可能大于收益
				birdMesh.frustumCulled = false;
				
				// 手动更新一次世界矩阵
				birdMesh.updateMatrix();
				
				/* 
				----------------------------------------
				第十步：定义GPU计算着色器
				----------------------------------------
				
				计算着色器说明：
				- 在GPU上并行执行，每只鸟对应一个GPU线程
				- 两个着色器按顺序执行：先计算速度，再更新位置
				- 实现了简化的Boids群体行为算法
				*/
				
				/* 
				计算速度的GPU着色器
				功能：根据群体行为规则和鼠标交互更新每只鸟的速度
				*/
				computeVelocity = Fn(() => {
					/* 
					---------------
					常量定义
					---------------
					*/
					const PI = float(3.141592653589793);  // 圆周率π
					const PI_2 = PI.mul(2.0);             // 2π，用于周期计算
					const limit = float(SPEED_LIMIT).toVar('limit');  // 速度限制
					
					/* 
					---------------
					从控制器解构参数
					---------------
					*/
					const { 
						alignment,      // 对齐力
						separation,     // 分离力
						cohesion,       // 凝聚力
						deltaTime,      // 时间增量
						rayOrigin,      // 鼠标射线起点
						rayDirection    // 鼠标射线方向
					} = effectController;
					
					/* 
					---------------
					计算交互区域参数
					---------------
					鸟的行为受三个同心球区域影响：
					1. 内层（红色）：分离区 - 避免碰撞
					2. 中层（绿色）：对齐区 - 统一方向
					3. 外层（蓝色）：凝聚区 - 向中心靠拢
					*/
					
					// 总交互区域半径 = 分离 + 对齐 + 凝聚
					const zoneRadius = separation.add(alignment).add(cohesion).toConst();
					
					// 分离阈值：分离区占整个区域的比例
					const separationThresh = separation.div(zoneRadius).toConst();
					
					// 对齐阈值：分离区+对齐区占整个区域的比例
					const alignmentThresh = (separation.add(alignment)).div(zoneRadius).toConst();
					
					// 区域半径的平方，用于距离比较（避免开方运算）
					const zoneRadiusSq = zoneRadius.mul(zoneRadius).toConst();
					
					/* 
					---------------
					获取当前鸟的数据
					---------------
					*/
					
					// 当前鸟的索引（0到BIRDS-1）
					const birdIndex = instanceIndex.toConst('birdIndex');
					
					// 当前鸟的位置（三维向量）
					const position = positionStorage.element(birdIndex).toVar();
					
					// 当前鸟的速度（三维向量）
					const velocity = velocityStorage.element(birdIndex).toVar();
					
					/* 
					---------------
					鼠标交互影响
					---------------
					当鼠标靠近鸟时，鸟会受到排斥力
					实现原理：计算鸟到鼠标射线的最短距离
					*/
					
					// 从鸟位置指向射线起点的向量
					const directionToRay = rayOrigin.sub(position).toConst();
					
					// 投影长度：directionToRay在射线方向上的投影
					const projectionLength = dot(directionToRay, rayDirection).toConst();
					
					// 射线上离鸟最近的点
					const closestPoint = rayOrigin.sub(rayDirection.mul(projectionLength)).toConst();
					
					// 从鸟位置指向最近点的向量
					const directionToClosestPoint = closestPoint.sub(position).toConst();
					
					// 鸟到射线的距离
					const distanceToClosestPoint = length(directionToClosestPoint).toConst();
					
					// 距离的平方（避免开方）
					const distanceToClosestPointSq = distanceToClosestPoint.mul(distanceToClosestPoint).toConst();
					
					// 鼠标影响半径和半径平方
					const rayRadius = float(150.0).toConst();
					const rayRadiusSq = rayRadius.mul(rayRadius).toConst();
					
					/* 
					如果鸟在鼠标影响范围内，施加排斥力
					排斥力大小与距离成反比：距离越近，排斥力越大
					*/
					If(distanceToClosestPointSq.lessThan(rayRadiusSq), () => {
						// 计算速度调整量：
						// (distanceToClosestPointSq / rayRadiusSq - 1.0) 范围：-1到0
						// 乘以deltaTime确保帧率无关
						// 乘以100.0调整影响力强度
						const velocityAdjust = (distanceToClosestPointSq.div(rayRadiusSq).sub(1.0))
							.mul(deltaTime)
							.mul(100.0);
						
						// 向远离鼠标的方向调整速度
						velocity.addAssign(normalize(directionToClosestPoint).mul(velocityAdjust));
						
						// 临时提高速度限制，让鸟能快速逃离鼠标
						limit.addAssign(5.0);
					});
					
					/* 
					---------------
					向心力：吸引鸟群向场景中心
					---------------
					防止鸟群飞散到边界外
					*/
					const dirToCenter = position.toVar();  // 指向场景中心的向量
					dirToCenter.y.mulAssign(2.5);          // Y方向权重更高，保持鸟群在水平面
					
					// 施加向中心的速度调整
					velocity.subAssign(normalize(dirToCenter).mul(deltaTime).mul(5.0));
					
					/* 
					---------------
					群体行为计算：遍历所有其他鸟
					---------------
					这是Boids算法的核心部分
					计算当前鸟与群体中其他鸟的交互
					*/
					
					// 循环遍历所有鸟（GPU并行执行每个实例）
					Loop({
						start: uint(0),        // 起始索引：0
						end: uint(BIRDS),      // 结束索引：BIRDS
						type: 'uint',          // 循环变量类型：无符号整数
						condition: '<'         // 循环条件：i < BIRDS
					}, ({ i }) => {  // i是循环变量，代表其他鸟的索引
						
						// 跳过自身（当前鸟）
						If(i.equal(birdIndex), () => {
							Continue();  // 继续下一次循环
						});
						
						/* 
						获取其他鸟的位置和计算相对向量
						*/
						const birdPosition = positionStorage.element(i);      // 其他鸟的位置
						const dirToBird = birdPosition.sub(position);         // 从当前鸟指向其他鸟的向量
						const distToBird = length(dirToBird);                 // 到其他鸟的距离
						
						// 避免除零错误：如果距离非常小，跳过计算
						If(distToBird.lessThan(0.0001), () => {
							Continue();
						});
						
						// 计算距离的平方（优化性能，避免重复开方）
						const distToBirdSq = distToBird.mul(distToBird);
						
						// 如果其他鸟在交互区域外，跳过计算
						If(distToBirdSq.greaterThan(zoneRadiusSq), () => {
							Continue();
						});
						
						/* 
						计算相对位置百分比
						范围：0（在当前鸟位置）到1（在区域边界）
						*/
						const percent = distToBirdSq.div(zoneRadiusSq);
						
						/* 
						根据距离应用不同的群体行为规则
						使用条件判断实现三个区域的切换
						*/
						
						// 区域1：分离区（最近，红色区域）
						If(percent.lessThan(separationThresh), () => {
							/* 
							分离规则：避免碰撞
							当其他鸟太近时，施加远离的力
							力的大小与距离成反比：距离越近，排斥力越大
							*/
							const velocityAdjust = (separationThresh.div(percent).sub(1.0))
								.mul(deltaTime);
							
							// 向远离其他鸟的方向调整速度
							velocity.subAssign(normalize(dirToBird).mul(velocityAdjust));
							
						// 区域2：对齐区（中等距离，绿色区域）
						}).ElseIf(percent.lessThan(alignmentThresh), () => {
							/* 
							对齐规则：与邻近鸟保持相同飞行方向
							实现鸟群飞行的协调性
							*/
							
							// 计算对齐区的宽度
							const threshDelta = alignmentThresh.sub(separationThresh);
							
							// 在对齐区内的归一化位置（0到1）
							const adjustedPercent = (percent.sub(separationThresh))
								.div(threshDelta);
							
							// 获取其他鸟的速度
							const birdVelocity = velocityStorage.element(i);
							
							/* 
							使用余弦函数创建平滑的过渡效果：
							cos(2π * adjustedPercent) 范围：-1到1
							通过变换得到0到1的平滑权重
							*/
							const cosRange = cos(adjustedPercent.mul(PI_2));
							const cosRangeAdjust = float(0.5)
								.sub(cosRange.mul(0.5))
								.add(0.5);
							
							// 速度调整量
							const velocityAdjust = cosRangeAdjust.mul(deltaTime);
							
							// 向其他鸟的方向调整速度
							velocity.addAssign(normalize(birdVelocity).mul(velocityAdjust));
							
						// 区域3：凝聚区（最远，蓝色区域）
						}).Else(() => {
							/* 
							凝聚规则：向群体中心靠拢
							实现鸟群的聚集效应
							*/
							
							// 计算凝聚区的宽度（从对齐阈值到1.0）
							const threshDelta = alignmentThresh.oneMinus();
							
							// 在凝聚区内的归一化位置（0到1）
							// 如果宽度为0，直接设为1.0
							const adjustedPercent = threshDelta.equal(0.0).select(
								1.0,
								(percent.sub(alignmentThresh)).div(threshDelta)
							);
							
							/* 
							使用余弦函数创建平滑的过渡效果：
							这里的余弦函数经过了特殊变换，使得：
							- 在凝聚区边缘（靠近对齐区）影响力小
							- 在凝聚区中心影响力大
							- 在凝聚区外边缘（靠近边界）影响力又变小
							*/
							const cosRange = cos(adjustedPercent.mul(PI_2));
							const adj1 = cosRange.mul(-0.5);      // -0.5到0.5
							const adj2 = adj1.add(0.5);          // 0到1
							const adj3 = float(0.5).sub(adj2);   // -0.5到0.5，再变换
							
							// 速度调整量
							const velocityAdjust = adj3.mul(deltaTime);
							
							// 向其他鸟的方向调整速度（吸引）
							velocity.addAssign(normalize(dirToBird).mul(velocityAdjust));
						});
					});
					
					/* 
					---------------
					速度限制
					---------------
					防止鸟飞得过快，保持视觉效果自然
					*/
					If(length(velocity).greaterThan(limit), () => {
						// 如果速度超过限制，将其缩放到限制值
						velocity.assign(normalize(velocity).mul(limit));
					});
					
					/* 
					---------------
					将计算出的速度写回存储
					---------------
					GPU计算的结果需要写回存储缓冲区
					供后续的位置计算和渲染使用
					*/
					velocityStorage.element(birdIndex).assign(velocity);
				})().compute(BIRDS).setName('Birds Velocity');
				
				/* 
				计算位置的GPU着色器
				功能：根据速度更新鸟的位置，并更新翅膀扇动相位
				*/
				computePosition = Fn(() => {
					// 获取时间增量参数
					const { deltaTime } = effectController;
					
					/* 
					更新位置：基于物理的运动公式
					位置 = 位置 + 速度 × 时间 × 系数
					系数15.0用于调整运动速度，使鸟群运动更明显
					*/
					positionStorage.element(instanceIndex).addAssign(
						velocityStorage.element(instanceIndex)
							.mul(deltaTime)
							.mul(15.0)
					);
					
					/* 
					更新翅膀扇动相位
					相位决定翅膀的位置，实现扇动动画
					*/
					const velocity = velocityStorage.element(instanceIndex);
					const phase = phaseStorage.element(instanceIndex);
					
					/* 
					相位更新公式：
					新相位 = 旧相位 + 基础增量 + 水平速度影响 + 上升速度影响
					
					说明：
					1. deltaTime: 基础时间增量，确保动画与时间相关
					2. length(velocity.xz).mul(deltaTime).mul(3.0): 
					   水平飞行速度越快，翅膀扇动越快
					   xz平面速度的长度反映水平飞行速度
					3. max(velocity.y, 0.0).mul(deltaTime).mul(6.0):
					   只有上升时（velocity.y > 0）才加速扇动
					   上升时翅膀扇动更快，符合鸟类飞行物理
					   乘以6.0给予上升更大的权重
					*/
					const modValue = phase.add(deltaTime)
						.add(length(velocity.xz).mul(deltaTime).mul(3.0))
						.add(max(velocity.y, 0.0).mul(deltaTime).mul(6.0));
					
					/* 
					相位取模运算：modValue % 62.83
					62.83 ≈ 10π ≈ 10 * 2π，确保相位在合理范围内循环
					取模操作防止相位无限增长
					*/
					phaseStorage.element(instanceIndex).assign(modValue.mod(62.83));
				})().compute(BIRDS).setName('Birds Position');
				
				/* 
				----------------------------------------
				第十一步：将鸟网格添加到场景
				----------------------------------------
				*/
				scene.add(birdMesh);
				
				/* 
				----------------------------------------
				第十二步：设置事件监听器
				----------------------------------------
				*/
				
				// 禁用容器的默认触摸行为，防止与页面滚动冲突
				container.style.touchAction = 'none';
				
				// 监听指针移动事件（支持鼠标和触摸）
				container.addEventListener('pointermove', onPointerMove);
				
				// 监听窗口大小变化事件
				window.addEventListener('resize', onWindowResize);
				
				/* 
				----------------------------------------
				第十三步：创建调试GUI界面
				----------------------------------------
				*/
				
				// 从渲染器的检查器创建参数面板
				const gui = renderer.inspector.createParameters('鸟群行为参数');
				
				// 添加分离力控制滑块
				gui.add(effectController.separation, 'value', 0.0, 100.0, 1.0)
					.name('分离力')
					.onChange((value) => {
						console.log('分离力设置为:', value);
					});
				
				// 添加对齐力控制滑块
				gui.add(effectController.alignment, 'value', 0.0, 100, 0.001)
					.name('对齐力')
					.onChange((value) => {
						console.log('对齐力设置为:', value);
					});
				
				// 添加凝聚力控制滑块
				gui.add(effectController.cohesion, 'value', 0.0, 100, 0.025)
					.name('凝聚力')
					.onChange((value) => {
						console.log('凝聚力设置为:', value);
					});
			}
			
			/* 
			=======================
			窗口大小调整处理函数
			功能：当浏览器窗口大小改变时，调整相机和渲染器
			=======================
			*/
			function onWindowResize() {
				// 更新相机的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 必须调用updateProjectionMatrix()使新的宽高比生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器大小为新的窗口尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 可选：输出日志，用于调试
				console.log(`窗口大小已调整: ${window.innerWidth} × ${window.innerHeight}`);
			}
			
			/* 
			=======================
			鼠标移动处理函数
			功能：将鼠标事件转换为标准化设备坐标
			说明：标准化设备坐标范围：x从-1（左）到1（右），y从-1（下）到1（上）
			=======================
			*/
			function onPointerMove(event) {
				// 检查是否为主要的指针事件（避免多点触摸的干扰）
				if (event.isPrimary === false) return;
				
				/* 
				计算标准化设备坐标（NDC）：
				
				对于x坐标：
				event.clientX / window.innerWidth: 得到0到1的比例
				乘以2: 得到0到2的范围
				减去1: 得到-1到1的范围
				
				对于y坐标：
				event.clientY / window.innerHeight: 得到0到1的比例
				1 - ... : 反转y轴，使屏幕顶部为1，底部为-1
				乘以2: 得到0到2的范围
				减去1: 得到-1到1的范围
				*/
				pointer.x = (event.clientX / window.innerWidth) * 2.0 - 1.0;
				pointer.y = 1.0 - (event.clientY / window.innerHeight) * 2.0;
				
				// 可选：输出调试信息
				// console.log(`鼠标位置: x=${pointer.x.toFixed(3)}, y=${pointer.y.toFixed(3)}`);
			}
			
			/* 
			=======================
			渲染循环函数
			功能：每一帧执行的逻辑，驱动整个动画
			说明：通过requestAnimationFrame或setAnimationLoop调用
			=======================
			*/
			function render() {
				/* 
				---------------
				计算时间增量
				---------------
				时间增量（deltaTime）是帧率无关动画的关键
				确保无论帧率高还是低，动画速度都保持一致
				*/
				const now = performance.now();  // 获取当前时间戳（毫秒）
				let deltaTime = (now - last) / 1000;  // 转换为秒
				
				// 安全限制：如果deltaTime太大（如页面从后台恢复），限制为1秒
				if (deltaTime > 1) deltaTime = 1;
				
				// 更新last变量，为下一帧做准备
				last = now;
				
				/* 
				---------------
				更新鼠标射线
				---------------
				根据当前鼠标位置和相机状态，更新射线投射器
				用于检测鼠标与3D空间的交互
				*/
				raycaster.setFromCamera(pointer, camera);
				
				/* 
				---------------
				更新控制器参数
				---------------
				将JavaScript中的值传递到GPU着色器
				*/
				effectController.now.value = now;                   // 当前时间
				effectController.deltaTime.value = deltaTime;       // 时间增量
				effectController.rayOrigin.value.copy(raycaster.ray.origin);      // 射线起点
				effectController.rayDirection.value.copy(raycaster.ray.direction); // 射线方向
				
				/* 
				---------------
				GPU计算阶段
				---------------
				顺序很重要：先计算速度，再根据速度更新位置
				*/
				
				// 第一步：计算所有鸟的新速度
				renderer.compute(computeVelocity);
				
				// 第二步：根据速度更新所有鸟的位置和相位
				renderer.compute(computePosition);
				
				/* 
				---------------
				渲染阶段
				---------------
				将3D场景绘制到Canvas
				*/
				renderer.render(scene, camera);
				
				/* 
				---------------
				重置鼠标位置
				---------------
				将鼠标y坐标设为10（屏幕外），确保只有移动鼠标时才会影响鸟群
				这样鼠标停止移动后，鸟群会恢复正常行为
				*/
				pointer.y = 10;
				
				// 可选：性能监控
				// 可以在此添加帧率显示或性能统计
			}
			
			/* 
			=======================
			启动应用
			调用初始化函数，开始整个应用
			=======================
			*/
			init();
			
		</script>
	</body>
</html>