<!-- Three.js WebGPU 鸟群模拟系统详解
🎯 一、项目核心功能
1. 实时鸟群行为模拟
模拟1024只鸟的群体行为，包括分离、对齐和凝聚三个基本原则

GPU并行计算：所有鸟的状态更新在GPU上同时进行，实现高性能模拟

交互式控制：用户可以通过鼠标移动影响鸟群行为（作为"捕食者"）

2. Boids算法完整实现
text
行为层次结构：
1. 分离行为：避免与邻近鸟碰撞（最近距离）
2. 对齐行为：与邻近鸟保持相同飞行方向（中间距离）
3. 凝聚行为：向群体中心靠拢（较远距离）
4. 边界约束：向场景中心聚集的倾向力
5. 捕食者回避：远离鼠标位置的逃离行为
3. 视觉表现
真实感翅膀动画：基于飞行速度和相位的周期性扇动

深度感知效果：远处的鸟颜色更暗，增强空间层次感

雾效支持：增加场景的大气透视效果

实时GUI控制：可调节算法参数观察不同行为模式

🔧 二、主要技术架构
1. GPU计算渲染管线
text
数据流：
1. 初始化阶段：
   位置纹理[32×32] → 速度纹理[32×32]
   (每像素存储一只鸟的RGBA数据)

2. 每帧更新：
   位置纹理 + 速度纹理 → GPU计算着色器
   ↓
   新位置纹理 ← 位置计算着色器
   新速度纹理 ← 速度计算着色器（应用Boids算法）
   ↓
   纹理数据 → 顶点着色器 → 渲染输出
2. 双通道纹理存储系统
javascript
// 位置纹理格式：
// R: X坐标 (-400到400)
// G: Y坐标 (-400到400)
// B: Z坐标 (-400到400)
// A: 翅膀相位 (0到62.83)

// 速度纹理格式：
// R: X速度分量 (-9到9)
// G: Y速度分量 (-9到9)
// B: Z速度分量 (-9到9)
// A: 未使用 (1.0)
3. 自定义几何体优化
javascript
class BirdGeometry extends THREE.BufferGeometry {
    // 每只鸟由3个三角形组成（共9个顶点）：
    // 1. 鸟身三角形：创建主体形状
    // 2. 左翅膀三角形：可动画的部分
    // 3. 右翅膀三角形：可动画的部分
    
    // 关键优化：
    // - 预计算所有9216个顶点
    // - 属性缓冲区：位置、颜色、纹理引用、顶点ID
    // - 矩阵自动更新关闭，手动控制
}
💡 三、核心技术点详解
1. GPU并行计算（核心创新）
glsl
// 关键概念：每个片元处理器 = 一只鸟
// 传统CPU方式：for循环1024次，串行处理
// GPU方式：1024个片元处理器同时执行着色器代码

// 速度计算着色器核心逻辑：
for (所有其他鸟) {
    if (在交互范围内) {
        计算相对距离百分比
        if (距离 < 分离阈值) 应用排斥力
        else if (距离 < 对齐阈值) 应用对齐力
        else 应用凝聚力
    }
}
2. 性能优化策略
优化技术	实现方式	性能提升
纹理采样优化	使用重复包裹模式，避免边界问题	减少条件判断
距离计算优化	使用距离平方比较，避免sqrt运算	减少30%计算量
早期剪枝	超出zoneRadius的鸟立即跳过	减少75%邻居检查
批量处理	所有鸟统一使用相同着色器	最大化GPU并行性
数据局部性	纹理缓存友好访问模式	提高缓存命中率
3. 平滑行为过渡算法
glsl
// 使用余弦函数实现平滑的力场过渡
float threshDelta = alignmentThresh - separationThresh;
float adjustedPercent = (percent - separationThresh) / threshDelta;

// 对齐力：余弦插值（0到1平滑变化）
f = (0.5 - cos(adjustedPercent * PI_2) * 0.5 + 0.5) * delta;

// 凝聚力：反向余弦插值（1到0平滑变化）
f = (0.5 - (cos(adjustedPercent * PI_2) * -0.5 + 0.5)) * delta;
4. 方向计算与动画系统
javascript
// 鸟类朝向计算：
// 1. 从速度向量提取偏航角（Y轴旋转）
// 2. 从速度向量提取俯仰角（Z轴旋转）
// 3. 构建旋转矩阵并应用到顶点

// 翅膀动画：
// 基于相位值的正弦函数，仅应用于翅膀尖端顶点
if (birdVertex == 4.0 || birdVertex == 7.0) {
    newPosition.y = sin(phase) * 5.0;  // 翅膀上下摆动
}
📊 四、技术规格与性能
1. 系统要求
text
- WebGL 2.0 或 WebGPU 支持
- 现代浏览器（Chrome 90+, Firefox 88+, Safari 14+）
- 推荐独立显卡以获得最佳性能
2. 资源占用
text
- 纹理内存：32×32×2×4 bytes ≈ 8KB
- 几何体内存：9216顶点 × 9 floats × 4 bytes ≈ 324KB
- GPU着色器：2个计算着色器 + 1个渲染着色器
3. 性能指标
text
- 目标帧率：60 FPS（稳定）
- 每帧计算量：1024只鸟 × 1024邻居检查 ≈ 100万次距离计算
- GPU利用率：高度并行，适合现代GPU架构
🎮 五、交互功能
1. GUI控制面板
javascript
可调节参数：
- 分离距离（0-100）：控制鸟之间的最小间距
- 对齐距离（0-100）：控制方向一致性的影响范围
- 凝聚距离（0-100）：控制群体聚集的强度
- 自由因子（0-1）：添加随机行为扰动
2. 鼠标交互
text
- 鼠标位置映射为"捕食者"位置
- 鸟群会自动避开捕食者区域
- 瞬时响应效果：鼠标移动后影响立即消失
🚀 六、扩展性与应用
1. 可扩展方向
text
1. 增加鸟的数量：提高纹理分辨率（64×64 → 4096只鸟）
2. 添加环境交互：障碍物、风力、地形影响
3. 优化渲染质量：法线贴图、镜面反射、阴影
4. 多群体模拟：不同行为模式的鸟群互动
2. 潜在应用场景
text
- 游戏开发：NPC群体AI，敌方单位行为
- 数据可视化：网络节点、粒子系统、流场显示
- 教育演示：群体智能、自组织系统教学
- 艺术创作：动态视觉效果、生成艺术
🏆 七、技术亮点总结
完全GPU加速：将计算密集型算法完全卸载到GPU

优雅的数学实现：使用三角函数实现平滑行为过渡

高效的数据结构：利用纹理作为通用存储介质

模块化架构：计算与渲染分离，易于维护和扩展

实时交互性：保持60FPS的同时支持参数动态调整

跨平台兼容：基于WebGL标准，无需插件或安装 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面基本信息：标题、字符编码、视口设置 -->
		<title>Three.js WebGL GPU计算 - 鸟群模拟</title>
		<meta charset="utf-8">
		<!-- 移动端视口设置：禁止用户缩放，最小缩放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="main.css">
		<!-- 内联CSS样式：设置页面基本样式 -->
		<style>
			body {
				background-color: #fff; /* 设置背景颜色为白色 */
				color: #444;/* 设置文字颜色为深灰色 */
			}
			a {
				color:#08f;/* 设置超链接颜色为蓝色 */
			}
		</style>
	</head>
	<body>
		<!-- 信息显示区域：显示项目信息和操作提示 -->
		<div id="info">
			<a href="https://threejs.org" target="_blank" rel="noopener">three.js</a> - WebGL GPU计算鸟群模拟<br/>
			移动鼠标干扰鸟群运动 | 1024只鸟实时模拟 | GPU并行计算
		</div>


		<!-- 开发者待办事项注释：提供代码改进建议 -->
		<!--
		待优化项：如果您正在阅读此代码，可以考虑以下改进：
			- 为鸟类创建更真实的着色效果
			- 添加更多群体行为参数控制
			- 优化移动端性能表现
			- 添加更多交互功能
		-->

		<!-- ==================== 着色器代码开始 ==================== -->
		
		<!-- 位置计算着色器：负责计算每只鸟的新位置 -->
		<script id="fragmentShaderPosition" type="x-shader/x-fragment">
			/*
			 * 位置计算片元着色器
			 * 功能：基于当前速度和相位计算鸟的新位置
			 * 输入：
			 *   - time: 当前时间（用于动画）
			 *   - delta: 时间增量（帧间隔时间）
			 *   - texturePosition: 位置纹理（存储当前位置）
			 *   - textureVelocity: 速度纹理（存储当前速度）
			 * 输出：包含新位置和相位值的vec4
			 */
			
			// 统一变量声明：从JavaScript传递到着色器的常量
			uniform float time; // 当前时间（秒）
			uniform float delta; // 时间增量（约0.016秒，对应60FPS）

			void main()	{
				// 计算当前像素在纹理中的归一化坐标
				// gl_FragCoord.xy：当前像素在屏幕空间的位置
				// resolution.xy：渲染目标（纹理）的分辨率
				vec2 uv = gl_FragCoord.xy / resolution.xy;

				// 从纹理中读取当前位置和速度数据
				// texture2D(): GLSL内置函数，从纹理采样颜色值
				// texturePosition: 存储鸟的当前位置(x,y,z)和相位(w)
				vec4 tmpPos = texture2D( texturePosition, uv );

				vec3 position = tmpPos.xyz;// 提取位置向量(x,y,z)
				vec3 velocity = texture2D( textureVelocity, uv ).xyz;// 提取速度向量

				float phase = tmpPos.w; // 相位值：用于翅膀扇动动画

				phase = mod( ( phase + delta +
					length( velocity.xz ) * delta * 3. + // 水平飞行时翅膀扇动
					max( velocity.y, 0.0 ) * delta * 6. ), // 向上飞行时更快扇动
					62.83 );

				/*
				 * 位置更新：position + velocity * delta * 15.
				 * - delta * 15.: 速度缩放因子，控制鸟的移动速度
				 * - 输出格式：vec4(新位置, 新相位)
				*/
				gl_FragColor = vec4( position + velocity * delta * 15. , phase );

			}

		</script>

		<!-- 速度计算着色器：负责计算每只鸟的新速度 -->
		<script id="fragmentShaderVelocity" type="x-shader/x-fragment">
			/*
			 * 速度计算片元着色器
			 * 功能：模拟鸟群行为（分离、对齐、聚合），计算新速度
			 * 基于Craig Reynolds的Boids算法实现
			 * 参考：https://www.red3d.com/cwr/boids/
			 */
			
			// 统一变量：从JavaScript传递的模拟参数
			uniform float time;                // 当前时间
			uniform float testing;             // 测试标志（当前未使用）
			uniform float delta;               // 时间增量（约0.016秒）
			uniform float separationDistance;  // 分离距离（避免碰撞）
			uniform float alignmentDistance;   // 对齐距离（匹配方向）
			uniform float cohesionDistance;    // 聚合距离（向中心靠拢）
			uniform float freedomFactor;       // 自由因子（随机行为强度）
			uniform vec3 predator;             // 捕食者位置（鼠标位置）

			// 常量定义
			const float width = resolution.x;	// 纹理宽度（32）
			const float height = resolution.y;	// 纹理高度（32）

			const float PI = 3.141592653589793;	// 圆周率
			const float PI_2 = PI * 2.0;		// 2π

			// 群体行为参数（会在main函数中根据uniforms更新）
			float zoneRadius = 40.0;           // 感知区域半径
			float zoneRadiusSquared = 1600.0;  // 半径平方（优化距离比较）
			float separationThresh = 0.45;     // 分离行为阈值（百分比）
			float alignmentThresh = 0.65;      // 对齐行为阈值（百分比）

			// 模拟边界限制
			const float UPPER_BOUNDS = BOUNDS;      // 上边界（800）
			const float LOWER_BOUNDS = -UPPER_BOUNDS; // 下边界（-800）

			// 物理限制
			const float SPEED_LIMIT = 9.0;     // 最大速度限制

			/*
			 * 伪随机数生成函数
			 * 基于sin和点积的哈希函数，产生[0,1)范围内的随机数
			 * 用于添加随机行为（当前未使用）
			 */
			float rand( vec2 co ){
				return fract( sin( dot( co.xy, vec2(12.9898,78.233) ) ) * 43758.5453 );
			}

			void main() {
				/*
				 * 步骤1：计算动态行为参数
				 * 根据GUI控制的距离参数计算感知区域和阈值
				 */
				zoneRadius = separationDistance + alignmentDistance + cohesionDistance;
				separationThresh = separationDistance / zoneRadius;
				alignmentThresh = ( separationDistance + alignmentDistance ) / zoneRadius;
				zoneRadiusSquared = zoneRadius * zoneRadius;

				/*
				 * 步骤2：获取当前鸟的数据
				 * uv: 当前像素在纹理中的坐标（对应一只鸟）
				 */
				vec2 uv = gl_FragCoord.xy / resolution.xy;
				vec3 birdPosition, birdVelocity;	// 其他鸟的数据

				vec3 selfPosition = texture2D( texturePosition, uv ).xyz;// 自身位置
				vec3 selfVelocity = texture2D( textureVelocity, uv ).xyz;// 自身速度

				// 临时变量声明
				float dist;			// 距离
				vec3 dir; 			// 方向向量
				float distSquared;	// 距离平方（优化计算）

				float separationSquared = separationDistance * separationDistance;
				float cohesionSquared = cohesionDistance * cohesionDistance;

				float f;		// 行为力系数
				float percent;	// 距离百分比（用于平滑过渡）

				// 初始化速度为当前速度
				vec3 velocity = selfVelocity;

				float limit = SPEED_LIMIT; // 当前速度限制

				/*
				 * 步骤3：躲避捕食者行为（对鼠标的反应）
				 * 原理：当鼠标靠近时，鸟会逃离鼠标位置
				 */
				dir = predator * UPPER_BOUNDS - selfPosition;	// 指向捕食者的方向
				dir.z = 0.;		 // 忽略Z轴，主要在2D平面反应						
				// dir.z *= 0.6;	// 计算到捕食者的距离
				dist = length( dir );
				distSquared = dist * dist;

				// 捕食者影响范围参数
				float preyRadius = 150.0;       // 影响半径
				float preyRadiusSq = preyRadius * preyRadius;  // 半径平方


				// 如果在影响范围内
				if ( dist < preyRadius ) {
					/*
					 * 逃离力计算：(distSquared / preyRadiusSq - 1.0) * delta * 100.
					 * - distSquared / preyRadiusSq: 归一化距离（0到1）
					 * - -1.0: 当距离=preyRadius时力为0
					 * - * 100.: 力的大小系数
					 * 特性：距离越近，逃离力越大（负反馈）
					 */
					f = ( distSquared / preyRadiusSq - 1.0 ) * delta * 100.;
					velocity += normalize( dir ) * f;  // 沿逃离方向加速
					limit += 5.0;  // 紧急情况下允许更快速度
				}


				/*
				 * 步骤4：向中心聚集的全局力
				 * 目的：防止鸟群飞散到边界外
				 */
				vec3 central = vec3( 0., 0., 0. );  // 场景中心
				dir = selfPosition - central;       // 指向中心的方向
				dist = length( dir );
				dir.y *= 2.5;  // Y方向加强，保持一定高度
				velocity -= normalize( dir ) * delta * 5.;  // 向中心加速


				/*
				 * 步骤5：遍历所有其他鸟，计算群体行为
				 * 通过双层循环遍历纹理的每个像素（每只鸟）
				 * 优化：实际通过纹理采样，这里是逻辑表示
				 */
				for ( float y = 0.0; y < height; y++ ) {
					for ( float x = 0.0; x < width; x++ ) {
						// 获取另一只鸟的数据
						vec2 ref = vec2( x + 0.5, y + 0.5 ) / resolution.xy;
						birdPosition = texture2D( texturePosition, ref ).xyz;

						dir = birdPosition - selfPosition; // 指向其他鸟的方向
						dist = length( dir );

						if ( dist < 0.0001 ) continue; // 跳过自身（距离为0）

						distSquared = dist * dist;

						if ( distSquared > zoneRadiusSquared ) continue;// 超出感知范围
						
						percent = distSquared / zoneRadiusSquared;// 计算相对距离百分比（0到1）

						/*
						 * 群体行为分为三个区域：
						 * 1. 内圈（0% - separationThresh%）：分离行为
						 * 2. 中圈（separationThresh% - alignmentThresh%）：对齐行为
						 * 3. 外圈（alignmentThresh% - 100%）：聚合行为
						 */

						// 分离行为：避免与太近的鸟碰撞
						if ( percent < separationThresh ) {
							/*
							 * 分离力公式：(separationThresh / percent - 1.0) * delta
							 * - separationThresh / percent: 当percent接近0时值很大
							 * - -1.0: 当percent=separationThresh时力为0
							 * 特性：距离越近，分离力越大（反比关系）
							 */
							f = ( separationThresh / percent - 1.0 ) * delta;
							velocity -= normalize( dir ) * f;  // 远离其他鸟

						// 对齐行为：与邻近鸟保持相同飞行方向
						} else if ( percent < alignmentThresh ) {
							// 计算在中间区域的相对位置
							float threshDelta = alignmentThresh - separationThresh;
							float adjustedPercent = ( percent - separationThresh ) / threshDelta;
							birdVelocity = texture2D( textureVelocity, ref ).xyz;
							
							/*
							* 对齐力使用余弦函数平滑过渡：
							* 0.5 - cos(adjustedPercent * PI_2) * 0.5 + 0.5
							* 在区域边界处力较小，中间力较大
							*/
							f = ( 0.5 - cos( adjustedPercent * PI_2 ) * 0.5 + 0.5 ) * delta;
							velocity += normalize( birdVelocity ) * f;  // 对齐到邻居方向

						// 聚合行为：向鸟群中心靠拢
						} else {
							float threshDelta = 1.0 - alignmentThresh;
							float adjustedPercent;
							if( threshDelta == 0. ) adjustedPercent = 1.;
							else adjustedPercent = ( percent - alignmentThresh ) / threshDelta;
							
							/*
							* 聚合力使用余弦函数平滑过渡：
							* 0.5 - (cos(adjustedPercent * PI_2) * -0.5 + 0.5)
							* 在区域边界处力较小，远离时力较大
							*/
							f = ( 0.5 - ( cos( adjustedPercent * PI_2 ) * -0.5 + 0.5 ) ) * delta;
							velocity += normalize( dir ) * f;  // 向邻居移动
						}

					}

				}


				/*
				 * 步骤6：应用物理限制
				 * 确保速度不超过限制，防止数值不稳定
				 */
				if ( length( velocity ) > limit ) {
					velocity = normalize( velocity ) * limit;  // 标准化并限制大小
				}

				// 输出最终速度向量
				gl_FragColor = vec4( velocity, 1.0 );

			}

		</script>

		<!-- 鸟模型顶点着色器：负责鸟的3D变换和渲染 -->
		<script type="x-shader/x-vertex" id="birdVS">
			/*
			 * 鸟模型顶点着色器
			 * 功能：将鸟的几何体根据位置和速度进行变换
			 * 输入属性（每个顶点不同）：
			 *   - reference: 纹理坐标（用于查找位置/速度）
			 *   - birdVertex: 顶点索引（0-8，用于识别翅膀顶点）
			 *   - birdColor: 顶点颜色
			 * 输出：
			 *   - vColor: 传递给片元着色器的颜色
			 *   - z: Z坐标（用于深度效果）
			 */
			
			// 顶点属性：每个顶点特有的数据
			attribute vec2 reference;    // 纹理参考坐标（查找该鸟的数据）
			attribute float birdVertex;  // 顶点索引（0-8，9个顶点每只鸟）
			attribute vec3 birdColor;    // 顶点颜色（从几何体传入）

			// 统一变量：从JavaScript传递
			uniform sampler2D texturePosition;  // 位置纹理
			uniform sampler2D textureVelocity;  // 速度纹理
			uniform float time;                 // 当前时间

			// 输出到片元着色器的变量
			varying vec4 vColor;   // 顶点颜色
			varying float z;       // 变换后的Z坐标（用于深度着色）

			void main() {

				// 从纹理中获取该鸟的位置和速度数据
				vec4 tmpPos = texture2D( texturePosition, reference );
				vec3 pos = tmpPos.xyz;  // 鸟的世界位置
				vec3 velocity = normalize(texture2D( textureVelocity, reference ).xyz);  // 标准化速度

				vec3 newPosition = position;  // 原始模型空间位置

				/*
				 * 翅膀扇动动画
				 * birdVertex索引对应关系：
				 * 0-2: 身体三角形
				 * 3-5: 左翅膀三角形（顶点4和7是翅膀尖端）
				 * 6-8: 右翅膀三角形
				 * 只有翅膀尖端顶点（索引4和7）参与扇动
				 */
				if ( birdVertex == 4.0 || birdVertex == 7.0 ) {
					// 使用相位值（tmpPos.w）控制翅膀上下运动
					// sin()产生周期性运动，*5控制运动幅度
					newPosition.y = sin( tmpPos.w ) * 5.;
				}

				// 应用模型矩阵变换（旋转、缩放）
				newPosition = mat3( modelMatrix ) * newPosition;

				/*
				 * 计算旋转矩阵，使鸟朝向飞行方向
				 * 步骤：
				 * 1. 调整速度方向（Z轴反转，适应坐标系）
				 * 2. 计算绕Y轴的旋转（偏航角yaw）
				 * 3. 计算绕Z轴的旋转（俯仰角pitch）
				 * 4. 组合旋转矩阵
				 */

				velocity.z *= -1.;  // 反转Z轴，适应Three.js坐标系

				// 计算水平分量长度
				float xz = length( velocity.xz );
				float xyz = 1.;
				float x = sqrt( 1. - velocity.y * velocity.y );

				// 计算绕Y轴旋转的三角函数（偏航）
				float cosry = velocity.x / xz;
				float sinry = velocity.z / xz;

				// 计算绕Z轴旋转的三角函数（俯仰）
				float cosrz = x / xyz;
				float sinrz = velocity.y / xyz;

				// 构建绕Y轴旋转矩阵（偏航）
				mat3 maty =  mat3(
					cosry, 0, -sinry,  // 第一列
					0    , 1, 0     ,  // 第二列
					sinry, 0, cosry    // 第三列
				);

				// 构建绕Z轴旋转矩阵（俯仰）
				mat3 matz =  mat3(
					cosrz , sinrz, 0,  // 第一列
					-sinrz, cosrz, 0,  // 第二列
					0     , 0    , 1   // 第三列
				);

				// 应用旋转：先俯仰后偏航
				newPosition =  maty * matz * newPosition;
				
				// 加上鸟的世界位置
				newPosition += pos;

				// 存储Z坐标供片元着色器使用
				z = newPosition.z;

				// 传递颜色到片元着色器
				vColor = vec4( birdColor, 1.0 );
				
				// 计算最终裁剪空间位置
				gl_Position = projectionMatrix * viewMatrix * vec4( newPosition, 1.0 );
			}

		</script>

		<!-- 鸟模型片元着色器：负责鸟的颜色计算 -->
		<script type="x-shader/x-fragment" id="birdFS">
			/*
			* 鸟模型片元着色器
			* 功能：计算每个像素的最终颜色
			* 当前实现：简单的深度着色效果
			*/
		   
		   // 从顶点着色器传递的变量
		   varying vec4 vColor;  // 顶点颜色
		   varying float z;      // 顶点Z坐标（深度）

		   // 统一变量（当前未使用，预留）
		   uniform vec3 color;

		   void main() {
			   /*
				* 深度着色效果：
				* 1. 0.2: 基础亮度
				* 2. (1000. - z) / 1000.: 深度因子
				*    - z越大（越远），值越小
				*    - z越小（越近），值越大
				* 3. * vColor.x: 乘以颜色R分量（灰度图的R=G=B）
				* 效果：远处的鸟较暗，近处的鸟较亮
				*/
			   float z2 = 0.2 + ( 1000. - z ) / 1000. * vColor.x;
			   
			   // 输出灰度颜色（R=G=B）
			   gl_FragColor = vec4( z2, z2, z2, 1. );
		   }

		</script>

		<!-- ==================== JavaScript模块开始 ==================== -->

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

		<!-- 主JavaScript模块：应用入口点 -->
		<script type="module">
			// ==================== 模块导入 ====================
			// 导入Three.js核心功能
			import * as THREE from 'three';

			// 导入Three.js附加组件
			import Stats from 'three/addons/libs/stats.module.js';// 性能统计监视器
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';// 轻量级GUI控制面板

			import { GPUComputationRenderer } from 'three/addons/misc/GPUComputationRenderer.js';// GPU计算渲染器

			// ==================== 常量定义 ====================
			/* 模拟参数配置 */
			const WIDTH = 32;// 模拟纹理宽度（32像素）

			const BIRDS = WIDTH * WIDTH; // 鸟的总数（32*32=1024只）

			// ==================== 自定义几何体类 ====================
			/**
			 * 鸟类几何体类
			 * 扩展自THREE.BufferGeometry，为每只鸟创建9个顶点（3个三角形）
			 * 每只鸟由3个三角形组成：身体、左翅膀、右翅膀
			 */
			class BirdGeometry extends THREE.BufferGeometry {

				constructor() {

					super(); // 调用父类构造函数

					// 计算几何数据大小
					const trianglesPerBird = 3;          // 每只鸟3个三角形
					const triangles = BIRDS * trianglesPerBird;  // 总三角形数：1024*3=3072
					const points = triangles * 3;        // 总顶点数：3072*3=9216

					/**
					 * 创建缓冲区属性：
					 * 1. 顶点位置（position）：每个顶点3个float（x,y,z）
					 * 2. 顶点颜色（birdColor）：每个顶点3个float（r,g,b）
					 * 3. 纹理参考（reference）：每个顶点2个float（u,v）
					 * 4. 顶点索引（birdVertex）：每个顶点1个float（0-8）
					 */
					const vertices = new THREE.BufferAttribute( new Float32Array( points * 3 ), 3 );
					const birdColors = new THREE.BufferAttribute( new Float32Array( points * 3 ), 3 );
					const references = new THREE.BufferAttribute( new Float32Array( points * 2 ), 2 );
					const birdVertex = new THREE.BufferAttribute( new Float32Array( points ), 1 );

					// 将缓冲区属性绑定到几何体
					this.setAttribute( 'position', vertices );
					this.setAttribute( 'birdColor', birdColors );
					this.setAttribute( 'reference', references );
					this.setAttribute( 'birdVertex', birdVertex );

					// this.setAttribute( 'normal', new Float32Array( points * 3 ), 3 );


					let v = 0;  // 顶点数组索引

					/**
					 * 辅助函数：向顶点数组添加顶点坐标
					 * @param {...number} args - 顶点坐标(x,y,z)
					 */
					 function verts_push() {
						for ( let i = 0; i < arguments.length; i ++ ) {
							vertices.array[ v ++ ] = arguments[ i ];
						}
					}

					const wingsSpan = 20; // 翅膀跨度

					/**
					 * 为每只鸟生成三角形数据
					 * 每只鸟9个顶点，组成3个三角形：
					 * 三角形1（顶点0-2）：身体
					 * 三角形2（顶点3-5）：左翅膀
					 * 三角形3（顶点6-8）：右翅膀
					 */
					for ( let f = 0; f < BIRDS; f ++ ) {
						// 身体三角形（垂直平面）
						verts_push(
							0, - 0, - 20,  // 顶点0：身体左下
							0, 4, - 20,    // 顶点1：身体左上
							0, 0, 30       // 顶点2：身体尖端
						);

						// 左翅膀三角形
						verts_push(
							0, 0, - 15,      // 顶点3：翅膀根部
							- wingsSpan, 0, 0,// 顶点4：翅膀尖端（左）
							0, 0, 15         // 顶点5：翅膀后部
						);

						// 右翅膀三角形
						verts_push(
							0, 0, 15,        // 顶点6：翅膀后部
							wingsSpan, 0, 0,  // 顶点7：翅膀尖端（右）
							0, 0, - 15       // 顶点8：翅膀根部
						);

					}
					/**
					 * 为每个顶点设置颜色、纹理参考坐标和顶点索引
					 * 颜色：基于顶点索引的渐变灰色
					 * 纹理参考：将鸟索引映射到纹理坐标(0-1)
					 * 顶点索引：标识顶点在鸟模型中的位置(0-8)
					 */
					 for ( let v = 0; v < triangles * 3; v ++ ) {
						// 计算几何索引
						const triangleIndex = ~ ~ ( v / 3 );           // 当前三角形索引
						const birdIndex = ~ ~ ( triangleIndex / trianglesPerBird ); // 当前鸟索引
						const x = ( birdIndex % WIDTH ) / WIDTH;      // 纹理U坐标（0-1）
						const y = ~ ~ ( birdIndex / WIDTH ) / WIDTH;  // 纹理V坐标（0-1）

						// 生成渐变色：基础灰色 + 基于索引的偏移
						const c = new THREE.Color(
							0x666666 +                     // 基础颜色
							~ ~ ( v / 9 ) / BIRDS * 0x666666 // 基于顶点索引的渐变
						);

						// 设置顶点颜色
						birdColors.array[ v * 3 + 0 ] = c.r;  // 红色分量
						birdColors.array[ v * 3 + 1 ] = c.g;  // 绿色分量
						birdColors.array[ v * 3 + 2 ] = c.b;  // 蓝色分量

						// 设置纹理参考坐标（用于在着色器中查找位置/速度）
						references.array[ v * 2 ] = x;      // U坐标
						references.array[ v * 2 + 1 ] = y;  // V坐标

						// 设置顶点索引（0-8，标识顶点在鸟模型中的位置）
						birdVertex.array[ v ] = v % 9;
					}

					// 缩放整个几何体（鸟的大小）
					this.scale( 0.2, 0.2, 0.2 );

				}

			}

			// ==================== 全局变量声明 ====================
			let container;      // 主容器DOM元素
			let stats;          // 性能统计对象
			let camera;         // 3D相机
			let scene;          // 3D场景
			let renderer;       // WebGL渲染器

			// 交互变量
			let mouseX = 0;     // 鼠标X坐标（相对屏幕中心）
			let mouseY = 0;     // 鼠标Y坐标（相对屏幕中心）

			let windowHalfX = window.innerWidth / 2;   // 屏幕半宽
			let windowHalfY = window.innerHeight / 2;  // 屏幕半高

			const BOUNDS = 800, BOUNDS_HALF = BOUNDS / 2;

			// 时间变量
			let last = performance.now();  // 上一帧时间戳（用于计算deltaTime）

			// GPU计算相关变量
			let gpuCompute;                // GPU计算渲染器实例
			let velocityVariable;          // 速度计算变量
			let positionVariable;          // 位置计算变量
			let positionUniforms;          // 位置着色器统一变量
			let velocityUniforms;          // 速度着色器统一变量
			let birdUniforms;              // 鸟渲染着色器统一变量

			// ==================== 初始化函数调用 ====================
			init();  // 启动应用

			// ==================== 核心函数定义 ====================
			/**
			 * 主初始化函数
			 * 职责：初始化所有Three.js组件、GPU计算、事件监听和GUI
			 */
			function init() {

				// 1. 创建DOM容器
				container = document.createElement( 'div' );
				document.body.appendChild( container );


				// 2. 创建透视相机
				camera = new THREE.PerspectiveCamera( 
					75,                                   // 视野角度（度）
					window.innerWidth / window.innerHeight, // 宽高比
					1,                                    // 近裁剪面
					3000                                  // 远裁剪面
				);
				camera.position.z = 350;  // 将相机向后移动，以便看到整个场景

				// 3. 创建场景并设置背景和雾效
				scene = new THREE.Scene();
				scene.background = new THREE.Color( 0xffffff );  // 白色背景
				scene.fog = new THREE.Fog( 0xffffff, 100, 1000 ); // 白色雾效，增强深度感

				// 4. 创建WebGL渲染器
				renderer = new THREE.WebGLRenderer();
				renderer.setPixelRatio( window.devicePixelRatio );  // 设置设备像素比
				renderer.setSize( window.innerWidth, window.innerHeight );  // 设置渲染尺寸
				renderer.setAnimationLoop( animate );  // 设置动画循环回调
				container.appendChild( renderer.domElement );  // 将canvas添加到DOM


				// 5. 初始化GPU计算渲染器
				initComputeRenderer();

				// 6. 初始化性能监视器（FPS、帧时间等）
				stats = new Stats();
				container.appendChild( stats.dom );

				// 7. 设置交互事件
				container.style.touchAction = 'none';  // 禁用默认触摸行为
				container.addEventListener( 'pointermove', onPointerMove );  // 监听指针移动

				// 8. 窗口大小改变事件
				window.addEventListener( 'resize', onWindowResize );

				// 9. 创建控制面板（GUI）
				const gui = new GUI();


				// GUI控制参数对象
				const effectController = {
					separation: 20.0,   // 分离距离（避免碰撞）
					alignment: 20.0,    // 对齐距离（匹配方向）
					cohesion: 20.0,     // 聚合距离（向中心靠拢）
					freedom: 0.75       // 自由因子（随机行为强度）
				};

				/**
				 * GUI参数改变回调函数
				 * 将GUI的值同步到着色器统一变量
				 */
				const valuesChanger = function () {

					velocityUniforms[ 'separationDistance' ].value = effectController.separation;
					velocityUniforms[ 'alignmentDistance' ].value = effectController.alignment;
					velocityUniforms[ 'cohesionDistance' ].value = effectController.cohesion;
					velocityUniforms[ 'freedomFactor' ].value = effectController.freedom;

				};

				valuesChanger();  // 初始化参数

				// 添加GUI控件
				gui.add( effectController, 'separation', 0.0, 100.0, 1.0 )
				   .name( '分离距离' )
				   .onChange( valuesChanger );
				   
				gui.add( effectController, 'alignment', 0.0, 100, 0.001 )
				   .name( '对齐距离' )
				   .onChange( valuesChanger );
				   
				gui.add( effectController, 'cohesion', 0.0, 100, 0.025 )
				   .name( '聚合距离' )
				   .onChange( valuesChanger );
				   
				gui.close();  // 默认关闭GUI面板

				// 10. 初始化鸟群网格
				initBirds();

			}

			/**
			 * 初始化GPU计算渲染器
			 * 职责：创建和管理GPU计算着色器、纹理和变量
			 */
			function initComputeRenderer() {
				// 1. 创建GPU计算渲染器实例
				// 参数：纹理宽度、高度、渲染器
				gpuCompute = new GPUComputationRenderer( WIDTH, WIDTH, renderer );

				// 2. 创建初始纹理
				const dtPosition = gpuCompute.createTexture();  // 位置纹理
				const dtVelocity = gpuCompute.createTexture();  // 速度纹理
				
				// 3. 用初始数据填充纹理
				fillPositionTexture( dtPosition );  // 随机位置
				fillVelocityTexture( dtVelocity );  // 随机速度

				// 4. 添加计算变量（速度）
				velocityVariable = gpuCompute.addVariable( 
					'textureVelocity',  // 变量名（在着色器中引用）
					document.getElementById( 'fragmentShaderVelocity' ).textContent,  // 着色器代码
					dtVelocity          // 初始纹理
				);
				// 5. 添加计算变量（位置）
				positionVariable = gpuCompute.addVariable( 
					'texturePosition', 
					document.getElementById( 'fragmentShaderPosition' ).textContent,
					dtPosition
				);
				/**
				 * 6. 设置变量依赖关系
				 * 速度变量依赖：位置变量和自身（用于迭代计算）
				 * 位置变量依赖：位置变量和速度变量
				 */
				gpuCompute.setVariableDependencies( velocityVariable, [ positionVariable, velocityVariable ] );
				gpuCompute.setVariableDependencies( positionVariable, [ positionVariable, velocityVariable ] );
				// 7. 获取统一变量集合（用于从JavaScript传递数据到着色器）
				positionUniforms = positionVariable.material.uniforms;
				velocityUniforms = velocityVariable.material.uniforms;

				// 8. 初始化统一变量值
				positionUniforms[ 'time' ] = { value: 0.0 };  // 时间
				positionUniforms[ 'delta' ] = { value: 0.0 }; // 时间增量
				velocityUniforms[ 'time' ] = { value: 1.0 };
				velocityUniforms[ 'delta' ] = { value: 0.0 };
				velocityUniforms[ 'testing' ] = { value: 1.0 };  // 测试标志
				// 群体行为参数（初始值，会被GUI覆盖）
				velocityUniforms[ 'separationDistance' ] = { value: 1.0 };
				velocityUniforms[ 'alignmentDistance' ] = { value: 1.0 };
				velocityUniforms[ 'cohesionDistance' ] = { value: 1.0 };
				velocityUniforms[ 'freedomFactor' ] = { value: 1.0 };
				// 捕食者位置（鼠标）
				velocityUniforms[ 'predator' ] = { value: new THREE.Vector3() };
				// 定义着色器常量（边界值）
				velocityVariable.material.defines.BOUNDS = BOUNDS.toFixed( 2 );
				// 9. 设置纹理包装模式（超出范围时重复）
				velocityVariable.wrapS = THREE.RepeatWrapping;
				velocityVariable.wrapT = THREE.RepeatWrapping;
				positionVariable.wrapS = THREE.RepeatWrapping;
				positionVariable.wrapT = THREE.RepeatWrapping;
				// 10. 初始化GPU计算器
				const error = gpuCompute.init();

				if ( error !== null ) {
					console.error( 'GPU计算初始化错误:', error );
				}

			}
			/**
			 * 初始化鸟群网格
			 * 职责：创建鸟的几何体、材质和网格对象
			 */
			function initBirds() {
				// 1. 创建自定义鸟几何体
				const geometry = new BirdGeometry();

				// 2. 创建鸟着色器的统一变量
				birdUniforms = {
					'color': { value: new THREE.Color( 0xff2200 ) },  // 基础颜色
					'texturePosition': { value: null },  // 位置纹理（从GPU计算器获取）
					'textureVelocity': { value: null },  // 速度纹理（从GPU计算器获取）
					'time': { value: 1.0 },              // 当前时间
					'delta': { value: 0.0 }              // 时间增量
				};

				// 3. 创建着色器材质
				const material = new THREE.ShaderMaterial( {
					uniforms: birdUniforms,// 统一变量集合
					vertexShader: document.getElementById( 'birdVS' ).textContent,// 顶点着色器
					fragmentShader: document.getElementById( 'birdFS' ).textContent,// 片元着色器
					side: THREE.DoubleSide// 双面渲染（鸟的两面都可见）

				} );
				// 4. 创建网格对象
				const birdMesh = new THREE.Mesh( geometry, material );
				birdMesh.rotation.y = Math.PI / 2;// 旋转90度（初始朝向）
				birdMesh.matrixAutoUpdate = false;// 禁用自动矩阵更新（性能优化）
				birdMesh.updateMatrix();// 手动更新一次矩阵
				// 5. 将鸟网格添加到场景
				scene.add( birdMesh );

			}
			/**
			 * 填充位置纹理
			 * 职责：用随机位置初始化位置纹理
			 * @param {THREE.DataTexture} texture - 要填充的位置纹理
			 */
			function fillPositionTexture( texture ) {
				// 获取纹理的数据数组（RGBA格式，每个像素4个浮点数）
				const theArray = texture.image.data;
				// 遍历每个像素（每个像素代表一只鸟）
				for ( let k = 0, kl = theArray.length; k < kl; k += 4 ) {
					// 在边界范围内随机生成位置
					const x = Math.random() * BOUNDS - BOUNDS_HALF;  // X: -400 到 400
					const y = Math.random() * BOUNDS - BOUNDS_HALF;  // Y: -400 到 400
					const z = Math.random() * BOUNDS - BOUNDS_HALF;  // Z: -400 到 400

					// 设置RGBA值
					theArray[ k + 0 ] = x;  // R通道存储X位置
					theArray[ k + 1 ] = y;  // G通道存储Y位置
					theArray[ k + 2 ] = z;  // B通道存储Z位置
					theArray[ k + 3 ] = 1;  // A通道存储相位值（初始为1）

				}

			}
			/**
			 * 填充速度纹理
			 * 职责：用随机速度初始化速度纹理
			 * @param {THREE.DataTexture} texture - 要填充的速度纹理
			 */
			function fillVelocityTexture( texture ) {

				const theArray = texture.image.data;

				for ( let k = 0, kl = theArray.length; k < kl; k += 4 ) {
					// 生成随机方向向量（各分量在-0.5到0.5之间）
					const x = Math.random() - 0.5;
					const y = Math.random() - 0.5;
					const z = Math.random() - 0.5;

					// 设置速度值（乘以10放大初始速度）
					theArray[ k + 0 ] = x * 10;  // R通道存储X速度
					theArray[ k + 1 ] = y * 10;  // G通道存储Y速度
					theArray[ k + 2 ] = z * 10;  // B通道存储Z速度
					theArray[ k + 3 ] = 1;       // A通道（未使用）

				}

			}
			/**
			 * 窗口大小改变事件处理
			 * 职责：响应窗口大小变化，更新相机和渲染器
			 */
			function onWindowResize() {
				// 更新窗口半宽高（用于鼠标坐标计算）
				windowHalfX = window.innerWidth / 2;
				windowHalfY = window.innerHeight / 2;

				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				camera.updateProjectionMatrix();  // 必须调用此方法生效

				// 更新渲染器大小
				renderer.setSize( window.innerWidth, window.innerHeight );

			}

			/**
			 * 指针移动事件处理
			 * 职责：捕获鼠标/触摸位置，用于捕食者模拟
			 * @param {PointerEvent} event - 指针事件对象
			 */
			 function onPointerMove( event ) {
				// 忽略非主指针（多点触控时的次要触点）
				if ( event.isPrimary === false ) return;

				// 计算相对于屏幕中心的鼠标位置
				// 范围：-windowHalfX 到 windowHalfX
				mouseX = event.clientX - windowHalfX;
				mouseY = event.clientY - windowHalfY;
			}

			/**
			 * 动画循环函数
			 * 职责：每一帧调用，更新渲染和统计
			 */
			 function animate() {
				render();        // 渲染场景
				stats.update();  // 更新性能统计显示
			}

			/**
			 * 主渲染函数
			 * 职责：更新模拟状态并渲染场景
			 */
			function render() {
				// 1. 计算时间增量（deltaTime）
				const now = performance.now();          // 当前时间戳
				let delta = ( now - last ) / 1000;      // 转换为秒
				if ( delta > 1 ) delta = 1;             // 安全限制：最大1秒（防止卡顿时的异常）
				last = now;                             // 保存当前时间

				// 2. 更新所有着色器的统一变量
				positionUniforms[ 'time' ].value = now;   // 传递当前时间
				positionUniforms[ 'delta' ].value = delta; // 传递时间增量
				velocityUniforms[ 'time' ].value = now;
				velocityUniforms[ 'delta' ].value = delta;
				birdUniforms[ 'time' ].value = now;
				birdUniforms[ 'delta' ].value = delta;

				/**
				 * 3. 更新捕食者（鼠标）位置
				 * 将鼠标坐标从屏幕空间转换到模拟空间
				 * mouseX/windowHalfX: 归一化到[-1, 1]
				 * * 0.5: 缩放因子
				 * -mouseY: 反转Y轴（屏幕Y向下，3D Y向上）
				 */
				 velocityUniforms[ 'predator' ].value.set( 
					0.5 * mouseX / windowHalfX,     // X坐标
					- 0.5 * mouseY / windowHalfY,   // Y坐标（反转）
					0                                // Z坐标（2D平面）
				);

				/**
				 * 4. 重置鼠标位置
				 * 将鼠标移到远处，模拟"鼠标移动后消失"的效果
				 * 这样鸟只会对鼠标的移动有短暂反应
				*/
				mouseX = 10000;
				mouseY = 10000;

				// 5. 执行GPU计算（更新位置和速度纹理）
				gpuCompute.compute();

				/**
				 * 6. 更新鸟渲染材质的纹理
				 * 获取GPU计算器计算出的最新纹理
				 */
				birdUniforms[ 'texturePosition' ].value = gpuCompute.getCurrentRenderTarget( positionVariable ).texture;
				birdUniforms[ 'textureVelocity' ].value = gpuCompute.getCurrentRenderTarget( velocityVariable ).texture;

				// 7. 渲染场景（相机视角）
				renderer.render( scene, camera );

			}

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