<!-- Three.js WebGPU 水面模拟 - 功能说明与技术分析
🎯 项目概述
这是一个基于 WebGPU 和 Three.js 的交互式水面物理模拟演示。用户可以通过鼠标点击和拖拽来扰动水面，观察水面波浪的传播、衰减以及与漂浮物体（鸭子）的物理交互。

🌊 核心功能
1. 动态水面模拟
实时波浪计算：基于简化的波动方程实现水面高度场动态更新

鼠标交互：点击拖拽产生涟漪效果，支持力度和范围调节

自然衰减：通过粘性系数控制波浪的持续时间和衰减速度

初始噪声：使用分形噪声生成自然的初始水面形态

2. 物理交互系统
鸭子漂浮模拟：

100只鸭子实例随水面起伏

受水面坡度影响移动（从高处流向低处）

边界碰撞检测和反弹

阻尼模拟实现自然的运动衰减

鼠标物理影响：

基于距离的余弦函数实现平滑扰动

移动速度影响扰动强度

可调节的影响深度和范围

3. 视觉渲染效果
PBR材质：基于物理的金属度/粗糙度工作流

动态法线计算：实时计算水面法线，实现准确的光照和反射

HDR环境照明：使用HDR贴图提供真实的环境光和反射

高质量渲染：ACES色调映射、抗锯齿、透明效果

4. 用户交互界面
相机控制：轨道控制器（旋转、缩放、平移）

实时参数调节：通过GUI控制模拟参数

模式切换：线框模式、鸭子显示/隐藏

性能调节：模拟速度控制

🔧 主要技术点
1. WebGPU 计算着色器
javascript
// 关键技术实现：
- 并行计算：利用GPU同时处理16,384个水面网格点
- 乒乓缓冲区：A/B缓冲区交替读写，避免数据竞争
- 存储缓冲区：高效的数据传输和访问
2. Three.js 高级特性
TSL（Three.js Shading Language）：在JavaScript中编写GPU着色器

节点材质系统：可编程的材质管线

实例化渲染：高效绘制大量相同对象

后处理管线：色调映射、抗锯齿

3. 物理模拟算法
text
高度场更新算法：
newHeight = (neighborAvg - prevHeight) * viscosity

鸭子物理：
1. 垂直：跟随水面高度 + 响应延迟
2. 水平：水面坡度 × 推力系数 + 阻尼
3. 边界：位置钳制 + 速度反向衰减
4. 性能优化技术
计算频率控制：根据速度参数调整更新频率

实例化：100个鸭子仅需1个绘制调用

矩阵缓存：禁用自动矩阵更新

内存对齐：数据结构按GPU要求对齐

5. 交互系统
射线检测：3D空间中的精确拾取

坐标转换：屏幕坐标 ↔ 标准化设备坐标 ↔ 世界坐标

状态管理：鼠标交互与相机控制的智能切换

🏗️ 系统架构
数据流架构：
text
鼠标输入 → 射线检测 → 计算参数 → GPU计算 → 渲染输出
                ↓
           鸭子物理更新
缓冲区管理：
text
帧循环：
1. 读取缓冲区A → 计算 → 写入缓冲区B
2. 材质从缓冲区B读取渲染
3. 下一帧：读取B → 计算 → 写入A
4. 材质从缓冲区A读取渲染
（如此循环）
🚀 技术亮点
1. 真正的GPU计算
使用WebGPU的计算管线，非传统WebGL的纹理模拟

充分发挥现代GPU的并行计算能力

支持更大规模的模拟网格

2. 物理准确性
基于经典波动方程的简化版本

考虑能量守恒（粘性阻尼）

真实的浮力和水面张力模拟

3. 视觉效果优化
实时法线计算，无需预计算

基于物理的材质参数

HDR环境提供真实反射

4. 交互友好性
直观的鼠标交互

实时参数反馈

平滑的状态过渡

📊 性能指标
组件	计算复杂度	备注
水面网格	O(n²)	128×128网格，16,384个计算点
鸭子物理	O(n)	100个实例，线性复杂度
鼠标影响	O(1)	常数时间，仅影响局部区域
渲染	O(n)	与顶点数成线性关系
🎮 用户体验
交互流程：
观察：默认场景展示自然波动的水面和漂浮鸭子

探索：使用鼠标右键或中键控制相机视角

交互：左键点击拖拽产生水面涟漪

调节：通过右侧GUI面板调整模拟参数

切换：启用/禁用线框模式观察几何结构

可调节参数：
鼠标影响范围：0.1-0.3（调节涟漪大小）

鼠标影响深度：0.1-1（调节涟漪强度）

水的粘性：0.9-0.96（调节波浪衰减速度）

模拟速度：1-6级（调节更新频率）

显示选项：鸭子显示/隐藏、线框模式

🔮 扩展可能性
技术扩展：
更大网格：升级到256×256或512×512网格

更多物理：添加风力、降雨、障碍物交互

高级渲染：焦散效果、水下折射、泡沫粒子

多人交互：WebSocket同步多用户交互

应用场景：
游戏开发：水面交互场景

教育演示：物理波动力学教学

产品展示：液体产品可视化

艺术创作：动态数字艺术

💡 学习价值
这个示例是学习以下技术的优秀案例：

WebGPU入门：了解计算着色器的基本概念

GPU物理模拟：学习在GPU上实现物理算法

Three.js高级应用：掌握节点材质、实例化等高级特性

实时图形编程：理解渲染管线和性能优化

🛠️ 开发说明
环境要求：
支持WebGPU的浏览器（Chrome 113+、Edge 113+）

Three.js r160+ 版本

现代GPU硬件

文件结构：
text
项目目录/
├── index.html          # 主HTML文件（本文件）
├── example.css         # 样式文件
├── build/              # Three.js构建文件
│   ├── three.webgpu.js
│   └── three.tsl.js
├── jsm/                # Three.js插件
│   ├── capabilities/
│   ├── controls/
│   ├── loaders/
│   └── math/
├── models/gltf/        # 3D模型
│   └── duck.glb
└── textures/equirectangular/  # 纹理
    └── blouberg_sunrise_2_1k.hdr -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：
			three.js webgpu - 计算水面模拟
			这是一个使用WebGPU和three.js实现的水面物理模拟示例
		-->
		<title>three.js webgpu - 计算水面模拟</title>
		<!-- 
			字符编码设置：
			UTF-8编码，支持中文和国际字符集
		-->
		<meta charset="utf-8">
		<!-- 
			视口设置：
			width=device-width - 宽度等于设备宽度
			user-scalable=no - 禁止用户缩放（保持固定比例）
			minimum-scale=1.0 - 最小缩放比例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">
		<!-- 
			外部样式表链接：
			引入example.css文件，包含页面的基本样式
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			页面信息区域：
			这个div包含页面的标题、logo和操作说明
			id="info"用于CSS样式和JavaScript选择
		-->
		<div id="info">
			<!-- 
				Three.js官方链接：
				href="https://threejs.org/" - 链接到Three.js官方网站
				target="_blank" - 在新标签页打开
				rel="noopener" - 安全属性，防止新页面访问原页面的window对象
				class="logo-link" - CSS类，可能包含logo背景图片样式
				这个链接通常显示Three.js的logo
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
			</a>

			<!-- 
				标题包装器：
				包含主标题和副标题
			-->
			<div class="title-wrapper">
				<!-- 
					主标题链接：
					同样链接到Three.js官网，显示"three.js"文本
				-->
				<a href="https://threejs.org/" target="_blank" rel="noopener">three.js</a>
				<!-- 
					副标题：
					显示当前示例的具体名称"计算水面模拟"
					<span>标签用于内联文本样式
				-->
				<span>计算水面模拟</span>
			</div>

			<!-- 
				操作说明：
				<small>标签表示小号字体，用于辅助说明
				提示用户如何与模拟场景交互
			-->
			<small>
				<!-- 
					中文操作说明：
					点击并移动鼠标来扰动水面。
					这个操作会在水面产生涟漪效果。
				-->
				点击并移动鼠标来扰动水面。
			</small>
			
			<!-- 
				额外说明（可选添加）：
			-->
			<small style="margin-top: 20px;">
				这是一个基于WebGPU的水面物理模拟演示，展示了GPU计算在three.js中的应用。
			</small>
		</div>

		<!-- 
			导入映射配置 (Import Maps)：
			这是一个现代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模块：
			type="module" 表示这是一个ES6模块，支持import/export语法
			模块代码具有自己的作用域，不会污染全局命名空间
		-->
		<script type="module">

			// ============================================================================
			// 模块导入部分
			// ============================================================================
			
			// 导入Three.js的WebGPU版本
			// 这个版本专门为WebGPU API优化，支持GPU计算功能
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js Shading Language (TSL) 的核心功能
			// TSL允许在JavaScript中编写GPU着色器代码，支持自动类型推导和优化
			// 各个导入项的详细说明：
			// instanceIndex - 计算着色器中当前实例的索引
			// struct - 定义结构化数据类型
			// If - 条件判断语句
			// uint, int, float - 无符号整数、整数、浮点数类型
			// floor - 向下取整函数
			// length - 向量长度计算
			// clamp - 数值钳制函数（限制在最小最大值之间）
			// vec2, vec3 - 2D和3D向量类型
			// cos - 余弦函数
			// vertexIndex - 顶点着色器中当前顶点的索引
			// Fn - 函数定义包装器
			// uniform - 定义uniform变量（在着色器间共享的常量）
			// instancedArray - 创建实例化数组缓冲区
			// min, max - 最小最大值函数
			// positionLocal - 局部空间位置
			// transformNormalToView - 法线向量从模型空间转换到视图空间
			// select - 条件选择函数（类似三元运算符）
			// globalId - 计算着色器中的全局工作项ID
			import { instanceIndex, struct, If, uint, int, floor, float, length, clamp, vec2, cos, vec3, vertexIndex, Fn, uniform, instancedArray, min, max, positionLocal, transformNormalToView, select, globalId } from 'three/tsl';

			// 导入调试检查器工具
			// Inspector提供实时参数调整界面，类似于GUI控制面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入Simplex噪声生成器
			// Simplex噪声是Perlin噪声的改进版本，计算效率更高
			// 用于生成自然的随机高度场
			import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
			
			// 导入GLTF模型加载器
			// GLTF是3D模型的开放标准格式，类似于3D界的JPEG
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 			
			// 导入HDR图像加载器
			// HDR（高动态范围）图像包含更丰富的亮度信息，用于环境照明
 			import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 			
			// 导入Draco压缩解码器
			// Draco是Google开发的3D几何压缩库，可以大幅减小3D模型文件大小
 			import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
			
			// 导入轨道控制器
			// 允许用户用鼠标控制相机：旋转、缩放、平移视图
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入WebGPU兼容性检测模块
			// 检查浏览器是否支持WebGPU API
			import WebGPU from 'three/addons/capabilities/WebGPU.js';

			// ============================================================================
			// 全局常量定义
			// ============================================================================
			
			// 模拟网格的宽度和高度（网格分辨率）
			// 128x128的网格提供足够细节的水面模拟，同时保持计算性能
			const WIDTH = 128;

			// 水体在三维空间中的实际尺寸（单位：Three.js单位）
			// BOUNDS = 6 表示水面是一个6x6的正方形区域
			const BOUNDS = 6;
			// 半尺寸，常用于边界计算
			const BOUNDS_HALF = BOUNDS * 0.5;
			// 限制范围：稍微小于半尺寸，为物体（鸭子）留出边界空间
			// 0.2的偏移确保物体不会到达绝对边缘
			const limit = BOUNDS_HALF - 0.2;

			// 水面的最大波动高度
			// 控制水面起伏的幅度，值越大波浪越高
			const waterMaxHeight = 0.1;

			// ============================================================================
			// 全局变量声明
			// ============================================================================
			
			// Three.js核心对象
			let container;      // 包含Three.js渲染器的HTML容器
			let camera;         // 场景相机（观察视角）
			let scene;          // 3D场景对象（包含所有3D元素）
			let renderer;       // WebGPU渲染器
			let controls;       // 用户交互控制器

			// 鼠标状态跟踪
			let mouseDown = false;          // 鼠标是否按下
			let firstClick = true;          // 是否是当前操作序列的第一次点击
			let updateOriginMouseDown = false; // 是否需要更新鼠标点击的起始位置

			// 鼠标坐标系统
			// THREE.Vector2用于存储2D坐标
			const mouseCoords = new THREE.Vector2(); // 标准化设备坐标（范围：-1到1）
			const raycaster = new THREE.Raycaster(); // 射线投射器，用于3D拾取
			let frame = 0; // 帧计数器，用于控制模拟更新频率

			// 效果控制器对象
			// 包含所有可调节的模拟参数，可以通过GUI修改
			const effectController = {
				// 鼠标当前位置（世界坐标）
				// uniform类型表示这些值在着色器中是常量，可以在GPU上访问
				mousePos: uniform( new THREE.Vector2() ).setName( 'mousePos' ),
				
				// 鼠标移动速度（基于位置变化计算）
				// 影响水面扰动的强度
				mouseSpeed: uniform( new THREE.Vector2() ).setName( 'mouseSpeed' ),
				
				// 鼠标点击的深度影响因子
				// 值越大，鼠标产生的凹陷越深
				mouseDeep: uniform( .5 ).setName( 'mouseDeep' ),
				
				// 鼠标影响的范围大小
				// 值越大，鼠标影响的水面区域越大
				mouseSize: uniform( 0.12 ).setName( 'mouseSize' ),
				
				// 水的粘性系数
				// 控制波浪衰减的速度，值越大波浪持续时间越长
				viscosity: uniform( 0.96 ).setName( 'viscosity' ),
				
				// 是否启用鸭子模拟
				// 切换鸭子物体的显示和计算
				ducksEnabled: true,
				
				// 是否显示线框模式
				// 线框模式有助于调试和理解几何结构
				wireframe: false,
				
				// 模拟速度
				// 控制物理模拟的更新频率，值越大模拟越快
				speed: 5,
			};

			// 3D对象引用
			let sun;            // 太阳光（平行光源）
			let waterMesh;      // 水面网格对象
			let poolBorder;     // 水池边框模型
			let meshRay;        // 用于射线检测的不可见平面
			
			// 计算着色器对象
			let computeHeightAtoB;  // 从缓冲区A计算到B的高度场
			let computeHeightBtoA;  // 从缓冲区B计算到A的高度场
			let computeDucks;       // 鸭子物理模拟计算
			
			// 乒乓缓冲区状态
			let pingPong = 0; // 当前使用哪个缓冲区：0=从A读向B写，1=从B读向A写
			const readFromA = uniform( 1 ); // 材质应该从哪个缓冲区读取：1=A，0=B
			
			// 鸭子模型引用
			let duckModel = null;

			// 鸭子数量常量
			// 100只鸭子提供了丰富的场景，同时保持在性能可接受范围内
			const NUM_DUCKS = 100;

			// 噪声生成器实例
			// 用于生成初始的水面高度场，创建自然的波浪效果
			const simplex = new SimplexNoise();

			// ============================================================================
			// WebGPU兼容性检查
			// ============================================================================
			
			// TODO: 未来可能需要添加WebGL后端的支持
			// 目前这个示例专门为WebGPU设计
			
			if ( WebGPU.isAvailable() === false ) {
				// 如果浏览器不支持WebGPU，显示错误信息
				document.body.appendChild( WebGPU.getErrorMessage() );
				// 抛出错误停止脚本执行
				throw new Error( '浏览器不支持WebGPU' );
			}

			// 启动初始化过程
			init();

			// ============================================================================
			// 工具函数定义
			// ============================================================================
			
			/**
			 * 生成水面初始高度的噪声函数
			 * 使用分形噪声（多个频率的噪声叠加）创建自然的波浪效果
			 * 
			 * @param {number} x - 水平方向坐标
			 * @param {number} y - 垂直方向坐标
			 * @returns {number} 计算得到的高度值
			 * 
			 * 分形噪声原理：
			 * 1. 使用多个不同频率和振幅的噪声层叠加
			 * 2. 高频层（细节）使用较小振幅
			 * 3. 低频层（形状）使用较大振幅
			 * 4. 每层频率增加，振幅减小，产生自相似的分形结构
			 */
			function noise( x, y ) {
				// 初始振幅：使用最大水面高度
				let multR = waterMaxHeight;
				// 初始频率：较小的值产生较大尺度的波浪
				let mult = 0.025;
				// 总高度值
				let r = 0;
				
				// 叠加15层噪声（15个八度）
				// 层数越多，细节越丰富，但计算成本也越高
				for ( let i = 0; i < 15; i ++ ) {
					// 当前层的贡献 = 振幅 × 噪声值
					r += multR * simplex.noise( x * mult, y * mult );
					
					// 更新下一层的参数：
					// 振幅递减：每次减少约53%，加上随层数增加的额外衰减
					// 这确保高频层（细节）对总高度的贡献较小
					multR *= 0.53 + 0.025 * i;
					
					// 频率递增：每次增加25%
					// 高频层提供更精细的细节
					mult *= 1.25;
				}
				
				return r;
			}

			/**
			 * 主初始化函数
			 * 异步加载资源并设置整个3D场景
			 * 
			 * 初始化流程：
			 * 1. 创建Three.js基本结构（场景、相机、渲染器）
			 * 2. 初始化水面模拟系统
			 * 3. 创建水面几何体和材质
			 * 4. 设置鸭子模拟系统
			 * 5. 加载外部资源（模型、纹理）
			 * 6. 设置用户交互
			 * 7. 创建GUI控制面板
			 */
			async function init() {
				// 步骤1: 创建基础Three.js结构
				// ------------------------------------------------------------
				
				// 创建容器div，Three.js渲染器将附加到这个元素
				container = document.createElement( 'div' );
				document.body.appendChild( container );

				// 创建透视相机
				// 参数说明：
				// 75 - 视野角度（FOV），单位度，类似人眼视野
				// window.innerWidth / window.innerHeight - 宽高比，匹配窗口比例
				// 1 - 近裁剪平面，距离相机1个单位以内的物体不显示
				// 3000 - 远裁剪平面，距离相机3000个单位以外的物体不显示
				camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 1, 3000 );
				// 设置相机初始位置
				camera.position.set( 0, 2.00, 4 );
				// 让相机看向场景中心点
				camera.lookAt( 0, 0, 0 );

				// 创建3D场景对象
				// 场景是所有3D对象的容器，包含网格、灯光、相机等
				scene = new THREE.Scene();

				// 创建平行光（模拟太阳光）
				// 平行光的特点是光线平行，没有衰减，类似太阳光
				sun = new THREE.DirectionalLight( 0xFFFFFF, 4.0 );
				// 设置光源位置，这个角度产生良好的阴影和高光
 				sun.position.set( - 1, 2.6, 1.4 );
				scene.add( sun );

				// 步骤2: 初始化水面模拟系统
				// ------------------------------------------------------------
				
				// 创建高度存储数组
				// Float32Array是类型化数组，提供高效的内存使用和GPU数据传输
				// WIDTH * WIDTH = 16384个高度值
				const heightArray = new Float32Array( WIDTH * WIDTH );
				const prevHeightArray = new Float32Array( WIDTH * WIDTH );

				// 使用噪声函数初始化水面高度
				// 创建自然的初始波浪形态
				let p = 0; // 数组索引
				for ( let j = 0; j < WIDTH; j ++ ) {
					for ( let i = 0; i < WIDTH; i ++ ) {
						// 将网格索引映射到噪声空间
						// 乘以128/WIDTH确保无论网格分辨率如何，都覆盖相同的噪声空间
						const x = i * 128 / WIDTH;
						const y = j * 128 / WIDTH;
						
						// 计算该点的高度值
						const height = noise( x, y );
						
						// 存储到数组中
						heightArray[ p ] = height;        // 当前高度
						prevHeightArray[ p ] = height;    // 前一帧高度（初始相同）
						
						p ++;
					}
				}

				// 创建乒乓缓冲区系统
				// 这是GPU计算中常用的技术：使用两个缓冲区交替作为输入和输出
				// 避免在同一帧中同时读写同一个缓冲区
				const heightStorageA = instancedArray( heightArray ).setName( 'HeightA' );
				const heightStorageB = instancedArray( new Float32Array( heightArray ) ).setName( 'HeightB' );
				const prevHeightStorage = instancedArray( prevHeightArray ).setName( 'PrevHeight' );

				/**
				 * TSL函数：获取网格中指定索引的邻居索引
				 * 在GPU计算着色器中，需要访问当前像素周围的数据
				 * 
				 * @param {TSLNode} index - 当前计算元素的索引（一维）
				 * @returns {Object} 包含四个方向邻居索引的对象
				 * 
				 * 网格布局：
				 *    north (上)
				 * west  中心  east (右)
				 *    south (下)
				 * 
				 * 边界处理：使用clamp模拟纹理的"边缘钳制"（clamp-to-edge）寻址
				 */
				const getNeighborIndicesTSL = ( index ) => {
					// 将网格宽度转换为无符号整数类型（GPU需要明确的类型）
					const width = uint( WIDTH );

					// 从一维索引计算二维网格坐标
					// 例如：索引65在128x128网格中 => x=65, y=0
					const x = int( index.mod( WIDTH ) );  // 取模得到x坐标
					const y = int( index.div( WIDTH ) );   // 整除得到y坐标

					// 计算邻居坐标，使用clamp确保不超出网格边界
					// 这模拟了纹理采样时的"边缘钳制"行为
					const leftX = max( 0, x.sub( 1 ) );      // 左邻居x坐标
					const rightX = min( x.add( 1 ), width.sub( 1 ) ); // 右邻居x坐标

					const bottomY = max( 0, y.sub( 1 ) );    // 下邻居y坐标
					const topY = min( y.add( 1 ), width.sub( 1 ) );   // 上邻居y坐标

					// 将二维坐标转换回一维索引
					// 公式：index = y * width + x
					const westIndex = y.mul( width ).add( leftX );    // 左邻居索引
					const eastIndex = y.mul( width ).add( rightX );   // 右邻居索引
					const southIndex = bottomY.mul( width ).add( x ); // 下邻居索引
					const northIndex = topY.mul( width ).add( x );    // 上邻居索引

					// 返回四个方向的邻居索引
					return { northIndex, southIndex, eastIndex, westIndex };
				};

				/**
				 * TSL函数：获取指定索引的邻居高度值
				 * 基于邻居索引从存储缓冲区读取实际高度值
				 * 
				 * @param {TSLNode} index - 当前索引
				 * @param {TSLNode} store - 高度存储缓冲区（A或B）
				 * @returns {Object} 包含四个方向邻居高度的对象
				 */
				const getNeighborValuesTSL = ( index, store ) => {
					// 首先获取邻居索引
					const { northIndex, southIndex, eastIndex, westIndex } = getNeighborIndicesTSL( index );

					// 从存储缓冲区读取邻居高度值
					// .element(index)是TSL语法，表示访问数组的特定元素
					const north = store.element( northIndex ); // 上邻居高度
					const south = store.element( southIndex ); // 下邻居高度
					const east = store.element( eastIndex );   // 右邻居高度
					const west = store.element( westIndex );   // 左邻居高度

					return { north, south, east, west };
				};

				/**
				 * 创建高度场更新计算着色器
				 * 这个函数返回一个配置好的计算着色器，用于更新水面高度
				 * 
				 * @param {TSLNode} readBuffer - 读取源缓冲区
				 * @param {TSLNode} writeBuffer - 写入目标缓冲区
				 * @returns {ComputeNode} 配置好的计算着色器节点
				 * 
				 * 物理原理：
				 * 基于简化的波动方程（wave equation）：
				 * newHeight = (neighborAvg - prevHeight) * viscosity
				 * 其中neighborAvg是四个邻居的平均高度
				 * 
				 * 这模拟了水面的波动传播：高处向低处流动，受到粘性阻尼
				 */
				const createComputeHeight = ( readBuffer, writeBuffer ) => Fn( () => {
					// 从效果控制器获取物理参数
					// 这些uniform值可以在运行时通过GUI修改
					const { viscosity, mousePos, mouseSize, mouseDeep, mouseSpeed } = effectController;

					// 获取当前网格点的状态
					// instanceIndex是计算着色器内置变量，表示当前处理元素的索引
					const height = readBuffer.element( instanceIndex ).toVar();      // 当前高度
					const prevHeight = prevHeightStorage.element( instanceIndex ).toVar(); // 上一帧高度

					// 获取四个邻居的高度值
					const { north, south, east, west } = getNeighborValuesTSL( instanceIndex, readBuffer );

					// === 核心物理计算 ===
					// 计算邻居平均高度
					const neighborHeight = north.add( south ).add( east ).add( west );
					neighborHeight.mulAssign( 0.5 ); // 除以2（四个邻居平均）
					
					// 计算高度变化：邻居平均高度减去上一帧高度
					neighborHeight.subAssign( prevHeight );
					
					// 应用粘性阻尼：乘以粘性系数
					// viscosity接近1.0表示低粘性（波浪持续久）
					// viscosity接近0.0表示高粘性（波浪快速衰减）
					const newHeight = neighborHeight.mul( viscosity );

					// === 鼠标交互影响 ===
					// 计算当前处理点在水平面上的位置（归一化坐标，0到1）
					// globalId.x和globalId.y是计算着色器中的工作项ID
					const x = float( globalId.x ).mul( 1 / WIDTH );
					const y = float( globalId.y ).mul( 1 / WIDTH );

					// 计算鼠标影响的相位（基于距离）
					// 原理：距离鼠标越近，影响越大，使用余弦函数创建平滑过渡
					const centerVec = vec2( 0.5 ); // 平面中心点（归一化坐标）
					
					// 计算步骤：
					// 1. vec2(x, y) - centerVec: 从中心点到当前点的向量（归一化坐标）
					// 2. .mul(BOUNDS): 转换为世界坐标
					// 3. .sub(mousePos): 减去鼠标位置，得到到鼠标的向量
					// 4. length(): 计算到鼠标的距离
					// 5. .mul(Math.PI).div(mouseSize): 将距离映射到相位角度
					// 6. clamp(..., 0.0, Math.PI): 限制相位在0到π之间
					const mousePhase = clamp( 
						length( ( vec2( x, y ).sub( centerVec ) ).mul( BOUNDS ).sub( mousePos ) )
						.mul( Math.PI ).div( mouseSize ), 
						0.0, Math.PI 
					);

					// 计算鼠标影响的高度变化：
					// 1. cos(mousePhase): 余弦函数，在鼠标中心为1，边缘为-1
					// 2. .add(1.0): 调整范围到0到2
					// 3. .mul(mouseDeep): 乘以深度系数
					// 4. .mul(mouseSpeed.length()): 乘以鼠标移动速度（速度越快影响越大）
					newHeight.addAssign( cos( mousePhase ).add( 1.0 ).mul( mouseDeep ).mul( mouseSpeed.length() ) );

					// === 更新存储 ===
					// 将当前高度保存为"上一帧高度"，供下一帧使用
					prevHeightStorage.element( instanceIndex ).assign( height );
					// 将计算的新高度写入输出缓冲区
					writeBuffer.element( instanceIndex ).assign( newHeight );

				} )().compute( WIDTH * WIDTH, [ 16, 16 ] ); // 配置计算着色器的工作组

				// 创建两个计算着色器，实现乒乓缓冲
				// computeHeightAtoB: 从缓冲区A读取，计算结果写入缓冲区B
				computeHeightAtoB = createComputeHeight( heightStorageA, heightStorageB ).setName( '更新高度 A→B' );
				// computeHeightBtoA: 从缓冲区B读取，计算结果写入缓冲区A
				computeHeightBtoA = createComputeHeight( heightStorageB, heightStorageA ).setName( '更新高度 B→A' );

				// 步骤3: 创建水面几何体和材质
				// ------------------------------------------------------------
				
				// 创建平面几何体作为水面基础形状
				// 参数说明：
				// BOUNDS, BOUNDS - 宽度和高度（6x6单位）
				// WIDTH - 1, WIDTH - 1 - 宽度和高度分段数（127x127个四边形）
				// 分段数必须与计算网格匹配，每个顶点对应一个计算点
				const waterGeometry = new THREE.PlaneGeometry( BOUNDS, BOUNDS, WIDTH - 1, WIDTH - 1 );

				// 创建水面材质（基于物理的渲染材质）
				// MeshStandardNodeMaterial是Three.js的PBR材质，支持金属度/粗糙度工作流
				const waterMaterial = new THREE.MeshStandardNodeMaterial( {
					color: 0x9bd2ec,        // 基础颜色：浅水蓝色（RGB: 155, 210, 236）
 					metalness: 0.9,          // 金属度：接近1.0表示高度金属（水有强镜面反射）
 					roughness: 0,            // 粗糙度：0表示完全光滑（镜面般的水面）
 					transparent: true,       // 启用透明度
 					opacity: 0.8,            // 不透明度：80%透明
 					side: THREE.DoubleSide   // 双面渲染（从水面下也能看到水）
				} );

				/**
				 * TSL函数：获取当前读取缓冲区的高度值
				 * 根据pingPong状态决定从缓冲区A还是B读取
				 * 
				 * @param {TSLNode} index - 要读取的索引
				 * @returns {TSLNode} 高度值
				 * 
				 * select函数相当于三元运算符：
				 * select(condition, valueIfTrue, valueIfFalse)
				 */
				const getCurrentHeight = ( index ) => {
					return select( 
						readFromA,                     // 条件：是否从A读取
						heightStorageA.element( index ), // 真：从A读取
						heightStorageB.element( index )  // 假：从B读取
					);
				};

				/**
				 * TSL函数：获取当前读取缓冲区的法线
				 * 通过高度差计算表面法线，用于光照计算
				 * 
				 * @param {TSLNode} index - 当前顶点索引
				 * @returns {Object} 包含法线X和Y分量的对象
				 * 
				 * 法线计算原理：
				 * 表面法线垂直于表面，可以通过相邻点的高度差计算
				 * normalX = (west - east) * 缩放因子
				 * normalY = (south - north) * 缩放因子
				 */
				const getCurrentNormals = ( index ) => {
					// 获取邻居索引
					const { northIndex, southIndex, eastIndex, westIndex } = getNeighborIndicesTSL( index );

					// 获取邻居高度
					const north = getCurrentHeight( northIndex );
					const south = getCurrentHeight( southIndex );
					const east = getCurrentHeight( eastIndex );
					const west = getCurrentHeight( westIndex );

					// 通过高度差计算法线分量
					// 注意：这里使用的是简化的法线计算，假设网格均匀分布
					const normalX = ( west.sub( east ) ).mul( WIDTH / BOUNDS );
					const normalY = ( south.sub( north ) ).mul( WIDTH / BOUNDS );

					return { normalX, normalY };
				};

				// 设置水面材质的法线节点
				// 这是Three.js节点材质系统的关键：自定义着色器逻辑
				waterMaterial.normalNode = Fn( () => {
					// 获取当前顶点的法线（基于计算的高度场）
					const { normalX, normalY } = getCurrentNormals( vertexIndex );
					
					// 构建法线向量并转换到视图空间
					// vec3(normalX, normalY.negate(), 1.0) - 构造法线向量
					// 注意：Y分量取反是因为Three.js的坐标系惯例
					// transformNormalToView() - 将法线从模型空间转换到视图空间
					// .toVertexStage() - 指定在顶点着色器阶段执行
					return transformNormalToView( vec3( normalX, normalY.negate(), 1.0 ) ).toVertexStage();
				} )();

				// 设置水面材质的位置节点
				// 将计算的高度应用到顶点位置，使水面起伏
				waterMaterial.positionNode = Fn( () => {
					// 获取当前顶点在计算网格中的高度
					// positionLocal.x, positionLocal.y - 平面上的原始位置
					// getCurrentHeight(vertexIndex) - 从计算网格获取的Z高度
					return vec3( positionLocal.x, positionLocal.y, getCurrentHeight( vertexIndex ) );
				} )();

				// 创建水面网格对象
				waterMesh = new THREE.Mesh( waterGeometry, waterMaterial );
				waterMesh.rotation.x = - Math.PI * 0.5;  // 旋转90度，使平面水平（Three.js中平面默认是竖直的）
				waterMesh.matrixAutoUpdate = false;      // 禁用自动矩阵更新（提高性能）
				waterMesh.updateMatrix();                // 手动更新一次矩阵
				scene.add( waterMesh );

				// 步骤4: 创建水池边框
				// ------------------------------------------------------------
				
				// 创建圆环几何体作为水池边框
				// 参数说明：
				// 4.2 - 圆环主要半径（中心到管中心）
				// 0.1 - 圆环管半径
				// 12 - 径向分段数（环绕圆的分段）
				// 4 - 管状分段数（管的粗细分段）
				const borderGeom = new THREE.TorusGeometry( 4.2, 0.1, 12, 4 );
 				borderGeom.rotateX( Math.PI * 0.5 );     // 旋转到水平面
 				borderGeom.rotateY( Math.PI * 0.25 );    // 旋转45度，产生菱形效果
 				
 				// 创建边框材质
 				poolBorder = new THREE.Mesh( borderGeom, new THREE.MeshStandardMaterial( { 
					color: 0x908877,  // 颜色：土黄色/石材色（RGB: 144, 136, 119）
					roughness: 0.2     // 粗糙度：略带粗糙，模拟石材表面
				} ) );
 				scene.add( poolBorder );

				// 步骤5: 创建射线检测网格（用于鼠标交互）
				// ------------------------------------------------------------
				
				// 创建一个简单平面，专门用于鼠标射线检测
				// 这个网格不可见，但可以与其他网格共享相同的变换
				const geometryRay = new THREE.PlaneGeometry( BOUNDS, BOUNDS, 1, 1 );
				meshRay = new THREE.Mesh( geometryRay, new THREE.MeshBasicMaterial( { 
					color: 0xFFFFFF, 
					visible: false  // 关键：设置为不可见
				} ) );
				meshRay.rotation.x = - Math.PI / 2;  // 与水面对齐
				meshRay.matrixAutoUpdate = false;    // 提高性能
				meshRay.updateMatrix();
				scene.add( meshRay );

				// 步骤6: 初始化鸭子模拟系统
				// ------------------------------------------------------------
				
				// 鸭子实例数据结构说明：
				// 每个实例需要8个浮点数（32字节）：
				// - position: vec3 (3个浮点数) - 位置（x, y, z）
				// - velocity: vec2 (2个浮点数) - 速度（x, z方向）
				// - 填充: vec3 (3个浮点数) - 确保内存对齐（GPU要求）
				// 总：3 + 2 + 3 = 8个浮点数
				const duckStride = 8;
				const duckInstanceDataArray = new Float32Array( NUM_DUCKS * duckStride );

				// 随机初始化鸭子的位置
				// Y位置初始为0，将在模拟中根据水面高度调整
				for ( let i = 0; i < NUM_DUCKS; i ++ ) {
					duckInstanceDataArray[ i * duckStride + 0 ] = ( Math.random() - 0.5 ) * BOUNDS * 0.7;  // X位置：随机在70%范围内
					duckInstanceDataArray[ i * duckStride + 1 ] = 0;                                      // Y位置：初始为0
					duckInstanceDataArray[ i * duckStride + 2 ] = ( Math.random() - 0.5 ) * BOUNDS * 0.7;  // Z位置：随机在70%范围内
					// 注意：速度初始为0（数组默认值）
				}

				// 定义鸭子数据的结构类型
				// 使用TSL的struct语法定义GPU上的数据结构
				const DuckStruct = struct( {
					position: 'vec3',  // 位置：三维向量
					velocity: 'vec2'   // 速度：二维向量（只在水平面移动）
				} );

				// 创建鸭子实例数据存储缓冲区
				const duckInstanceDataStorage = instancedArray( duckInstanceDataArray, DuckStruct ).setName( '鸭子实例数据' );

				// 创建鸭子物理模拟计算着色器
				// 这个着色器每帧更新所有鸭子的位置和速度
				computeDucks = Fn( () => {
					// 物理参数定义
					const yOffset = float( - 0.04 );              // Y轴偏移：让鸭子浮在水面上方一点
					const verticalResponseFactor = float( 0.98 );  // 垂直响应因子：控制鸭子跟随水面的速度
					const waterPushFactor = float( 0.015 );        // 水推力因子：水面坡度对鸭子的推力强度
					const linearDamping = float( 0.92 );           // 线性阻尼：速度的自然衰减
					const bounceDamping = float( - 0.4 );          // 反弹阻尼：碰撞时的速度反向和衰减

					// 获取当前鸭子的数据
					const instancePosition = duckInstanceDataStorage.element( instanceIndex ).get( 'position' ).toVar();
					const velocity = duckInstanceDataStorage.element( instanceIndex ).get( 'velocity' ).toVar();

					// === 将世界坐标转换为计算网格坐标 ===
					// 公式：gridCoord = (worldCoord / BOUNDS + 0.5) * WIDTH
					// 解释：将[-BOUNDS/2, BOUNDS/2]范围映射到[0, WIDTH-1]索引
					const gridCoordX = instancePosition.x.div( BOUNDS ).add( 0.5 ).mul( WIDTH );
					const gridCoordZ = instancePosition.z.div( BOUNDS ).add( 0.5 ).mul( WIDTH );

					// 钳制坐标到有效网格范围内
					const xCoord = uint( clamp( floor( gridCoordX ), 0, WIDTH - 1 ) );
					const zCoord = uint( clamp( floor( gridCoordZ ), 0, WIDTH - 1 ) );
					
					// 计算一维索引：index = z * WIDTH + x
					const heightInstanceIndex = zCoord.mul( WIDTH ).add( xCoord );

					// 获取当前位置的水面信息
					const waterHeight = getCurrentHeight( heightInstanceIndex );  // 水面高度
					const { normalX, normalY } = getCurrentNormals( heightInstanceIndex ); // 水面法线（坡度）

					// === 垂直运动：鸭子随水面起伏 ===
					// 计算目标高度：水面高度 + 偏移（让鸭子浮在水上）
					const targetY = waterHeight.add( yOffset );
					
					// 计算高度差
					const deltaY = targetY.sub( instancePosition.y );
					
					// 渐进式更新Y位置：当前位置 + 差值 * 响应因子
					// 响应因子接近1.0表示快速响应，接近0.0表示缓慢响应
					instancePosition.y.addAssign( deltaY.mul( verticalResponseFactor ) );

					// === 水平运动：鸭子受水面坡度影响 ===
					// 将水面法线（坡度）转换为推力
					// 原理：水会从高处流向低处，带动漂浮物
					const pushX = normalX.mul( waterPushFactor );  // X方向推力
					const pushZ = normalY.mul( waterPushFactor );  // Z方向推力

					// 应用速度阻尼（模拟水阻）
					velocity.x.mulAssign( linearDamping );
					velocity.y.mulAssign( linearDamping );

					// 添加水面推力
					velocity.x.addAssign( pushX );
					velocity.y.addAssign( pushZ );

					// 根据速度更新位置
					instancePosition.x.addAssign( velocity.x );
					instancePosition.z.addAssign( velocity.y );

					// === 边界碰撞检测和处理 ===
					// X轴边界检查
					If( instancePosition.x.lessThan( - limit ), () => {
						// 如果超出左边界，将位置设置到边界上
						instancePosition.x = - limit;
						// 速度反向并衰减（反弹效果）
						velocity.x.mulAssign( bounceDamping );
					} ).ElseIf( instancePosition.x.greaterThan( limit ), () => {
						// 如果超出右边界
						instancePosition.x = limit;
						velocity.x.mulAssign( bounceDamping );
					} );

					// Z轴边界检查
					If( instancePosition.z.lessThan( - limit ), () => {
						// 如果超出下边界
						instancePosition.z = - limit;
						velocity.y.mulAssign( bounceDamping );
					} ).ElseIf( instancePosition.z.greaterThan( limit ), () => {
						// 如果超出上边界
						instancePosition.z = limit;
						velocity.y.mulAssign( bounceDamping );
					} );

					// 将更新后的数据写回存储缓冲区
					duckInstanceDataStorage.element( instanceIndex ).get( 'position' ).assign( instancePosition );
					duckInstanceDataStorage.element( instanceIndex ).get( 'velocity' ).assign( velocity );

				} )().compute( NUM_DUCKS ).setName( '更新鸭子' );

				// 步骤7: 加载外部资源（HDR环境贴图和鸭子模型）
				// ------------------------------------------------------------
				
				// 配置加载器
				const hdrLoader = new HDRLoader().setPath( './textures/equirectangular/' );
 				const glbloader = new GLTFLoader().setPath( 'models/gltf/' );
 				// 设置Draco解码器（用于加载压缩的GLTF模型）
 				glbloader.setDRACOLoader( new DRACOLoader().setDecoderPath( 'jsm/libs/draco/gltf/' ) );

 				// 异步加载所有资源
 				// Promise.all同时加载多个资源，提高加载效率
 				const [ env, model ] = await Promise.all( [ 
					hdrLoader.loadAsync( 'blouberg_sunrise_2_1k.hdr' ),  // HDR环境贴图
					glbloader.loadAsync( 'duck.glb' )                     // 鸭子GLTF模型
				] );
 				
				// 配置环境贴图
 				env.mapping = THREE.EquirectangularReflectionMapping;  // 设置映射类型为等距柱状投影
 				scene.environment = env;          // 设置场景环境贴图（用于反射）
 				scene.background = env;           // 设置场景背景
 				scene.backgroundBlurriness = 0.3; // 背景模糊度：30%模糊，增加景深效果
 				scene.environmentIntensity = 1.25; // 环境光强度：125%，增强照明

				// 获取鸭子模型（GLTF场景的第一个子对象）
				duckModel = model.scene.children[ 0 ];
				
				// 修改鸭子材质，使其支持实例化位置
				// 每个实例根据其存储的位置数据进行偏移
				duckModel.material.positionNode = Fn( () => {
					// 获取当前实例的位置数据
					const instancePosition = duckInstanceDataStorage.element( instanceIndex ).get( 'position' );
					// 计算最终位置：局部坐标 + 实例偏移
					const newPosition = positionLocal.add( instancePosition );
					return newPosition;
				} )();

				// 创建鸭子实例化网格
				// InstancedMesh可以高效渲染大量相同几何体，每个实例有不同的变换
				const duckMesh = new THREE.InstancedMesh( duckModel.geometry, duckModel.material, NUM_DUCKS );
				scene.add( duckMesh );

				// 步骤8: 创建WebGPU渲染器
				// ------------------------------------------------------------
				
				// 创建WebGPU渲染器实例
				// antialias: true 启用抗锯齿，平滑边缘
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				renderer.setPixelRatio( window.devicePixelRatio );  // 设置像素比，支持高DPI显示器
				renderer.setSize( window.innerWidth, window.innerHeight ); // 设置渲染器尺寸
				renderer.toneMapping = THREE.ACESFilmicToneMapping;  // 使用ACES电影级色调映射
				renderer.toneMappingExposure = 0.5;                  // 曝光值：0.5（中等亮度）
				renderer.setAnimationLoop( render );                 // 设置渲染循环回调函数
				container.appendChild( renderer.domElement );        // 将渲染器canvas添加到DOM

				// 步骤9: 添加调试工具
				// ------------------------------------------------------------
				
				// 创建并附加调试检查器
				// Inspector提供实时参数调整和场景检查功能
				renderer.inspector = new Inspector();
				document.body.appendChild( renderer.inspector.domElement );

				// 步骤10: 添加用户交互控制
				// ------------------------------------------------------------
				
				// 创建轨道控制器
				// 允许用户用鼠标旋转、缩放、平移相机
				controls = new OrbitControls( camera, container );

				// 步骤11: 设置事件监听器
				// ------------------------------------------------------------
				
				// 禁用触摸缩放（防止与相机控制冲突）
				container.style.touchAction = 'none';
				
				// 鼠标/指针事件监听
				container.addEventListener( 'pointermove', onPointerMove );  // 指针移动
				container.addEventListener( 'pointerdown', onPointerDown );  // 指针按下
				container.addEventListener( 'pointerup', onPointerUp );      // 指针释放
				
				// 窗口大小变化事件
				window.addEventListener( 'resize', onWindowResize );

				// 步骤12: 创建GUI控制面板
				// ------------------------------------------------------------
				
				// 通过Inspector创建参数控制面板
				const gui = renderer.inspector.createParameters( '设置' );
				
				// 添加鼠标影响范围控制
				// 参数：对象，属性名，最小值，最大值
				gui.add( effectController.mouseSize, 'value', 0.1, .3 ).name( '鼠标影响范围' );
				
				// 添加鼠标影响深度控制
				gui.add( effectController.mouseDeep, 'value', 0.1, 1 ).name( '鼠标影响深度' );
				
				// 添加水的粘性控制
				// 第三个参数是步长（0.001）
				gui.add( effectController.viscosity, 'value', 0.9, 0.96, 0.001 ).name( '水的粘性' );
				
				// 添加模拟速度控制（整数步长）
				gui.add( effectController, 'speed', 1, 6, 1 ).name( '模拟速度' );
				
				// 添加鸭子显示切换
				gui.add( effectController, 'ducksEnabled' ).name( '显示鸭子' ).onChange( () => {
					// 当值改变时，更新鸭子网格的可见性
					duckMesh.visible = effectController.ducksEnabled;
				} );
				
				// 添加线框模式切换
				gui.add( effectController, 'wireframe' ).name( '线框模式' ).onChange( () => {
					// 切换所有材质的线框模式
					waterMesh.material.wireframe = ! waterMesh.material.wireframe;
					poolBorder.material.wireframe = ! poolBorder.material.wireframe;
					duckModel.material.wireframe = ! duckModel.material.wireframe;
					
					// 通知材质需要更新
					waterMesh.material.needsUpdate = true;
					poolBorder.material.needsUpdate = true;
				} );

			} // init()函数结束

			// ============================================================================
			// 事件处理函数
			// ============================================================================
			
			/**
			 * 窗口大小变化事件处理函数
			 * 当浏览器窗口大小改变时，调整相机和渲染器
			 */
			function onWindowResize() {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 通知相机投影矩阵需要更新
				camera.updateProjectionMatrix();
				// 更新渲染器尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 将屏幕坐标转换为标准化设备坐标（NDC）
			 * 将像素坐标转换为WebGL/WebGPU使用的[-1, 1]范围
			 * 
			 * @param {number} x - 屏幕X坐标（像素）
			 * @param {number} y - 屏幕Y坐标（像素）
			 * 
			 * 转换公式：
			 * ndcX = (screenX / width) * 2 - 1
			 * ndcY = -(screenY / height) * 2 + 1  (Y轴反转，因为屏幕坐标系与WebGL相反)
			 */
			function setMouseCoords( x, y ) {
				mouseCoords.set( 
					( x / renderer.domElement.clientWidth ) * 2 - 1,    // X: [-1, 1]
					- ( y / renderer.domElement.clientHeight ) * 2 + 1   // Y: [-1, 1]（反转）
				);
			}

			/**
			 * 鼠标按下事件处理
			 * 开始水面交互
			 */
			function onPointerDown() {
				mouseDown = true;            // 标记鼠标为按下状态
				firstClick = true;           // 这是当前点击序列的第一次
				updateOriginMouseDown = true; // 需要更新鼠标起始位置
			}

			/**
			 * 鼠标释放事件处理
			 * 结束水面交互，恢复相机控制
			 */
			function onPointerUp() {
				mouseDown = false;           // 标记鼠标为释放状态
				firstClick = false;          // 点击序列结束
				updateOriginMouseDown = false; // 不再需要更新起始位置
				controls.enabled = true;     // 重新启用轨道控制器
			}

			/**
			 * 鼠标移动事件处理
			 * 跟踪鼠标位置，用于射线检测
			 * 
			 * @param {PointerEvent} event - 指针事件对象
			 */
			function onPointerMove( event ) {
				// 检查是否是主指针（避免处理多点触控的额外指针）
				if ( event.isPrimary === false ) return;
				// 更新鼠标坐标
				setMouseCoords( event.clientX, event.clientY );
			}

			/**
			 * 射线检测函数
			 * 计算鼠标与水面的交点，更新模拟参数
			 * 
			 * 工作原理：
			 * 1. 从相机发射射线，方向由鼠标屏幕位置决定
			 * 2. 检测射线与水面检测平面的交点
			 * 3. 根据交点位置更新鼠标影响参数
			 */
			function raycast() {
				// 检查是否应该进行射线检测：
				// 1. 鼠标必须按下
				// 2. 是第一次点击 或者 轨道控制器被禁用（表示正在进行水面交互）
				if ( mouseDown && ( firstClick || ! controls.enabled ) ) {
					// 设置射线：从相机出发，方向指向鼠标在3D空间中的位置
					raycaster.setFromCamera( mouseCoords, camera );
					
					// 检测射线与水面检测平面的交点
					const intersects = raycaster.intersectObject( meshRay );

					// 如果有交点（鼠标在水面上方）
					if ( intersects.length > 0 ) {
						// 获取交点在世界坐标中的位置
						const point = intersects[ 0 ].point;

						// 如果需要更新鼠标起始位置（每次点击开始时）
						if ( updateOriginMouseDown ) {
							// 设置鼠标位置为当前交点（只取X和Z，忽略Y高度）
							effectController.mousePos.value.set( point.x, point.z );
							updateOriginMouseDown = false; // 已更新，重置标志
						}

						// 计算鼠标移动速度（当前帧位置与上一帧位置的差值）
						// 速度用于控制水面扰动的强度
						effectController.mouseSpeed.value.set(
							( point.x - effectController.mousePos.value.x ), // X方向速度
							( point.z - effectController.mousePos.value.y )  // Z方向速度
						);

						// 更新鼠标位置为当前交点
						effectController.mousePos.value.set( point.x, point.z );

						// 如果是第一次点击，禁用轨道控制器（避免与水面交互冲突）
						if ( firstClick ) {
							controls.enabled = false;
						}

					} else {
						// 如果没有交点（鼠标不在水面上方）
						updateOriginMouseDown = true; // 下次需要重新设置起始位置
						effectController.mouseSpeed.value.set( 0, 0 ); // 速度清零
					}

					// 标记已经不是第一次点击了
					firstClick = false;

				} else {
					// 鼠标没有按下，重置状态
					updateOriginMouseDown = true; // 准备下次点击
					effectController.mouseSpeed.value.set( 0, 0 ); // 速度清零
				}
			}

			/**
			 * 主渲染循环函数
			 * 由Three.js的动画循环自动调用（通常每秒60次）
			 * 
			 * 渲染流程：
			 * 1. 执行射线检测（处理鼠标交互）
			 * 2. 更新模拟状态（基于速度设置）
			 * 3. 执行GPU计算（更新水面和鸭子）
			 * 4. 渲染场景
			 */
			function render() {
				// 步骤1: 执行射线检测，更新鼠标交互参数
				raycast();

				// 步骤2: 更新帧计数器，控制模拟更新频率
				frame ++;

				// 检查是否应该更新模拟：
				// 公式：frame >= 7 - speed
				// speed=1时：每6帧更新一次（约10次/秒）
				// speed=6时：每1帧更新一次（60次/秒）
				if ( frame >= 7 - effectController.speed ) {
					// 步骤3: 执行水面高度场更新（乒乓缓冲）
					if ( pingPong === 0 ) {
						// 模式0：从缓冲区A读取，计算结果写入缓冲区B
						renderer.compute( computeHeightAtoB, [ 8, 8, 1 ] );
						// 材质现在应该从缓冲区B读取（刚写入的最新数据）
						readFromA.value = 0;
					} else {
						// 模式1：从缓冲区B读取，计算结果写入缓冲区A
						renderer.compute( computeHeightBtoA, [ 8, 8, 1 ] );
						// 材质现在应该从缓冲区A读取
						readFromA.value = 1;
					}

					// 切换乒乓标志：0变1，1变0
					pingPong = 1 - pingPong;

					// 如果鸭子模拟启用，更新鸭子物理
					if ( effectController.ducksEnabled ) {
						renderer.compute( computeDucks );
					}

					// 重置帧计数器
					frame = 0;
				}

				// 步骤4: 渲染整个场景
				// 这将使用当前的水面高度和鸭子位置绘制所有对象
				renderer.render( scene, camera );
			}

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