<!-- Three.js GPGPU 水面物理模拟系统
🎯 项目概述
这是一个基于WebGL和GPU通用计算(GPGPU)的实时交互式水面物理模拟系统。系统模拟了真实的水面波动效果，支持鼠标交互扰动水面，并有12只小鸭在水面上随波逐流。

🌊 核心功能
1. 水面物理模拟
实时波动计算：在GPU上执行波动方程模拟

鼠标交互：点击拖动鼠标可产生水波涟漪

参数可调：可通过GUI调整水的粘性、鼠标影响范围等

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

2. 鸭子物理系统
浮力模拟：鸭子高度随水面实时变化

水面滑行：鸭子沿水面倾斜方向滑动

碰撞检测：与水池边界的弹性碰撞

动态旋转：鸭子朝向运动方向并适应水面倾斜

3. 视觉渲染效果
PBR材质：基于物理的渲染，真实的水面反射

HDR环境：使用实拍的日出HDR贴图

实时阴影：可开关的软阴影系统

透明效果：半透明水面材质

🔧 主要技术点
1. GPGPU计算技术
javascript
// 核心：GPUComputationRenderer进行波动模拟
gpuCompute = new GPUComputationRenderer(WIDTH, WIDTH, renderer);
128×128模拟网格：在性能和质量间取得平衡

波动方程离散化：newHeight = (邻居平均*0.5 - 前一帧高度) * 粘性

双缓冲纹理：R通道存当前高度，G通道存前一帧高度

2. 浮点数编码技术
glsl
// 将32位浮点数编码为4个8位RGBA值
vec4 encode_float(float val) {
    // IEEE 754单精度浮点数编码
    // 1位符号 + 8位指数 + 23位尾数
}
问题：WebGL的readPixels只能读取0-255整数

解决方案：将浮点数拆分到RGBA四个通道

应用：鸭子位置查询时传递水位和法线数据

3. 中心差分法计算法线
glsl
// 从高度图计算水面法线
vec2 normal = vec2(
    (左邻居高度 - 右邻居高度) * 分辨率/边界,
    (下邻居高度 - 上邻居高度) * 分辨率/边界
);
实时法线生成：每帧从高度图计算

水面倾斜度：决定鸭子滑动方向

4. 分形噪声生成
javascript
// 15层Simplex噪声叠加
for (let i = 0; i < 15; i++) {
    r += multR * simplex.noise(x * mult, y * mult);
    multR *= 0.53 + 0.025 * i; // 振幅递减
    mult *= 1.25; // 频率递增
}
多倍频程噪声：模拟自然水面波动

参数控制：振幅递减、频率递增产生真实感

5. 着色器注入技术
javascript
// 修改Three.js标准材质的着色器
onBeforeCompile(shader) {
    shader.vertexShader = shader.vertexShader.replace(
        '#include <beginnormal_vertex>',
        customNormalShaderCode
    );
}
扩展标准材质：保持PBR特性，添加高度图支持

顶点位移：根据高度图调整顶点Z坐标

法线计算：实时从高度图计算法线

6. 物理碰撞系统
javascript
// 鸭子边界碰撞检测
if (pos.x < -limit) {
    pos.x = -limit + decal;
    velocity.x *= -0.3; // 能量损失70%的反弹
}
弹性碰撞：带有能量损失的反弹

边界偏移：防止物体卡在边界

水面约束：鸭子始终在水面上

7. 四元数旋转插值
javascript
// 鸭子平滑旋转
tmpQuatX.setFromUnitVectors(zAxis, dir); // 朝向运动方向
tmpQuatZ.setFromUnitVectors(yAxis, normal); // 适应水面倾斜
sphere.quaternion.slerp(combinedQuat, 0.017); // 平滑插值
双旋转组合：运动方向 + 水面倾斜

球面线性插值：平滑的旋转过渡

🎮 交互与控制
GUI控制面板
鼠标大小：影响范围 0.1-1.0

下压深度：扰动强度 0.01-1.0

水的粘性：波动衰减速度 0.9-0.999

模拟速度：更新频率 1-6

鸭子开关：显示/隐藏鸭子

线框模式：切换网格显示

阴影开关：启用/禁用阴影

鼠标交互
点击拖动：在水面产生波动

实时响应：波动立即传播

圆形影响：平滑的余弦函数分布

🚀 性能优化
1. 模拟频率控制
javascript
// 根据speed参数控制更新频率
if (frame >= 7 - effectController.speed) {
    gpuCompute.compute(); // 执行GPU计算
    frame = 0;
}
2. 最小化GPU读取
4×1像素渲染目标：仅读取必要数据

浮点数编码：一次读取获取多个浮点值

3. 静态对象优化
javascript
waterMesh.matrixAutoUpdate = false; // 禁用自动矩阵更新
waterMesh.updateMatrix(); // 只更新一次
4. 阴影优化
VSM阴影：视觉更平滑的软阴影

2048×2048分辨率：高质量阴影贴图

阴影偏移：减少"阴影痤疮"现象

🏗️ 系统架构
数据流架构
text
鼠标输入 → 射线检测 → GPU计算 → 高度图更新
    ↓                              ↓
控制参数 → 鸭子物理 ← 水位查询 ← 法线计算
    ↓                              ↓
GUI界面 → 材质更新 → 渲染输出 → 屏幕显示
核心模块
输入处理模块：鼠标交互和GUI控制

GPU计算模块：波动方程求解

物理模拟模块：鸭子动力学

渲染模块：PBR材质和阴影

资源管理模块：模型和纹理加载

📊 技术指标
模拟分辨率：128×128网格（16,384个计算点）

渲染帧率：60 FPS（取决于硬件）

内存使用：约50-100MB（包含HDR纹理）

GPU要求：支持WebGL 2.0的显卡

浏览器兼容：现代浏览器（Chrome、Firefox、Edge）

🎨 视觉效果特色
真实反射：基于HDR环境贴图的PBR反射

半透明水面：80%透明度，能看到水下

动态法线：实时计算的水面波纹

软阴影：VSM阴影映射，边缘柔和

抗锯齿：MSAA抗锯齿，边缘平滑

🔄 物理模拟精度
波动传播：符合简化波动方程

能量衰减：粘性系数控制衰减速度

法线精度：中心差分法，一阶精度

碰撞响应：动量守恒的能量损失模型

浮力模拟：简单跟随水面高度 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js GPGPU 水面模拟演示 -->
		<title>Three.js WebGL - GPGPU 水面物理模拟</title>
		<meta charset="utf-8">
		<!-- 视口设置：禁止用户缩放，适应移动设备 -->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<body>

		<!-- 页面信息显示区域 -->
		<div id="info">
			<!-- 项目链接和基本信息 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 
			<!-- 显示水面网格分辨率 -->
			<span id="waterSize">128×128网格</span> WebGL GPGPU 水面物理模拟<br/>
			<!-- 操作提示：鼠标交互 -->
			点击并移动鼠标以扰动水面，12只小鸭会随波逐流<br/>
			<!-- 技术说明：实时GPU计算物理模拟 -->
			<small>基于GPU通用计算(GPGPU)的实时波动方程模拟</small>
		</div>


		<!-- ============================================================
			平滑计算着色器
			用途：用于手动平滑水面，通过5点平均滤波算法
			工作原理：对每个纹素及其上下左右4个邻居取平均值
			注意：此着色器当前被注释掉，需要时可启用
		============================================================ -->
		<script id="smoothFragmentShader" type="x-shader/x-fragment">
			// 输入：需要平滑的纹理
			uniform sampler2D smoothTexture;

			void main()	{
				// 计算单个纹素在纹理坐标中的大小
				// resolution是GPUComputationRenderer提供的uniform变量，表示纹理分辨率
				vec2 cellSize = 1.0 / resolution.xy;
				
				// 将当前像素坐标转换为纹理坐标(UV坐标)
				// gl_FragCoord是当前片段在渲染目标中的像素坐标
				vec2 uv = gl_FragCoord.xy * cellSize;

				// ============================================================
				// 5点平均滤波算法（卷积核：[0,1,0; 1,1,1; 0,1,0] / 5）
				// 这种滤波可以消除高频噪声，使水面更平滑
				// ============================================================
				
				// 中心点值
				vec4 textureValue = texture2D( smoothTexture, uv );
				// 上邻居（Y轴正方向）
				textureValue += texture2D( smoothTexture, uv + vec2( 0.0, cellSize.y ) );
				// 下邻居（Y轴负方向）
				textureValue += texture2D( smoothTexture, uv + vec2( 0.0, - cellSize.y ) );
				// 右邻居（X轴正方向）
				textureValue += texture2D( smoothTexture, uv + vec2( cellSize.x, 0.0 ) );
				// 左邻居（X轴负方向）
				textureValue += texture2D( smoothTexture, uv + vec2( - cellSize.x, 0.0 ) );

				// 计算5个点的平均值
				textureValue /= 5.0;

				// 输出平滑后的颜色值
				gl_FragColor = textureValue;

			}

		</script>

		<!-- ============================================================
			读取水位计算着色器
			用途：从高度图纹理中读取特定点的水位高度和法线方向
			工作原理：通过中心差分法计算法线，将浮点数编码为RGBA颜色
			特殊：设计为在1x4像素的渲染目标上运行，每个像素存储不同类型的数据
		============================================================ -->
		<script id="readWaterLevelFragmentShader" type="x-shader/x-fragment">

			// 输入：要查询的点的UV坐标
			uniform vec2 point1;
			// 输入：水位高度图纹理
			uniform sampler2D levelTexture;

			// ============================================================
			// 浮点数到RGBA编码函数
			// 问题：WebGL的readPixels只能读取0-255的整数值
			// 解决方案：将32位浮点数拆分为4个8位整数存储在RGBA通道中
			// 编码标准：IEEE 754单精度浮点数标准
			// ============================================================
			
			// 右移位函数：模拟整数右移操作
			float shift_right( float v, float amt ) {
				v = floor( v ) + 0.5;
				return floor( v / exp2( amt ) );
			}

			// 左移位函数：模拟整数左移操作
			float shift_left( float v, float amt ) {
				return floor( v * exp2( amt ) + 0.5 );
			}

			// 掩码函数：保留指定位数的值
			float mask_last( float v, float bits ) {
				return mod( v, shift_left( 1.0, bits ) );
			}

			// 位提取函数：从数字中提取指定范围的位
			float extract_bits( float num, float from, float to ) {
				from = floor( from + 0.5 ); to = floor( to + 0.5 );
				return mask_last( shift_right( num, from ), to - from );
			}

			// 浮点数编码主函数：将32位浮点数编码为4个0-1的浮点数（对应RGBA通道）
			vec4 encode_float( float val ) {
				// 处理零值特殊情况
				if ( val == 0.0 ) return vec4( 0, 0, 0, 0 );
				
				// IEEE 754单精度浮点数结构：1位符号 + 8位指数 + 23位尾数
				float sign = val > 0.0 ? 0.0 : 1.0;  // 符号位：0正1负
				val = abs( val );  // 取绝对值
				
				// 计算指数部分
				float exponent = floor( log2( val ) );  // 以2为底的对数取整
				float biased_exponent = exponent + 127.0;  // 加上偏移量127
				
				// 计算尾数部分（小数部分）
				// 8388608 = 2^23，用于将小数部分转换为整数
				float fraction = ( ( val / exp2( exponent ) ) - 1.0 ) * 8388608.0;
				
				// 将指数拆分为两部分，适应RGBA编码
				float t = biased_exponent / 2.0;
				float last_bit_of_biased_exponent = fract( t ) * 2.0;  // 指数的最后一位
				float remaining_bits_of_biased_exponent = floor( t );  // 指数的剩余7位
				
				// 将尾数拆分为3个字节
				float byte4 = extract_bits( fraction, 0.0, 8.0 ) / 255.0;   // 最低8位 -> R通道
				float byte3 = extract_bits( fraction, 8.0, 16.0 ) / 255.0;  // 中间8位 -> G通道
				// byte2包含尾数的最高7位和指数的最后1位 -> B通道
				float byte2 = ( last_bit_of_biased_exponent * 128.0 + extract_bits( fraction, 16.0, 23.0 ) ) / 255.0;
				// byte1包含符号位和指数的剩余7位 -> A通道
				float byte1 = ( sign * 128.0 + remaining_bits_of_biased_exponent ) / 255.0;
				
				// 返回编码后的RGBA颜色
				return vec4( byte4, byte3, byte2, byte1 );
			}

			void main()	{
				// 计算纹素大小：1除以纹理分辨率
				vec2 cellSize = 1.0 / resolution.xy;
				
				// 读取指定点的水位高度（R通道存储高度值）
				float waterLevel = texture2D( levelTexture, point1 ).x;

				// ============================================================
				// 中心差分法计算水面法线
				// 原理：通过相邻点的高度差计算梯度，梯度方向即为法线方向
				// 公式：∂h/∂x ≈ (h(x-Δx) - h(x+Δx)) / (2Δx)
				// ============================================================
				vec2 normal = vec2(
					// X方向梯度：左右邻居的高度差
					( texture2D( levelTexture, point1 + vec2( - cellSize.x, 0 ) ).x 
					- texture2D( levelTexture, point1 + vec2( cellSize.x, 0 ) ).x ) * WIDTH / BOUNDS,
					// Y方向梯度：上下邻居的高度差
					( texture2D( levelTexture, point1 + vec2( 0, - cellSize.y ) ).x 
					- texture2D( levelTexture, point1 + vec2( 0, cellSize.y ) ).x ) * WIDTH / BOUNDS
				);

				// ============================================================
				// 数据打包：将不同数据存储到不同的像素中
				// 渲染目标大小为4x1像素，每个像素存储一种数据
				// ============================================================
				
				// 像素0（X坐标0-1）：存储水位高度
				if ( gl_FragCoord.x < 1.5 ) {
					gl_FragColor = encode_float( waterLevel );
				} 
				// 像素1（X坐标1-2）：存储法线X分量
				else if ( gl_FragCoord.x < 2.5 ) {
					gl_FragColor = encode_float( normal.x );
				} 
				// 像素2（X坐标2-3）：存储法线Y分量
				else if ( gl_FragCoord.x < 3.5 ) {
					gl_FragColor = encode_float( normal.y );
				} 
				// 像素3（X坐标3-4）：保留位，当前未使用
				else {
					gl_FragColor = encode_float( 0.0 );
				}

			}

		</script>


		<!-- ============================================================
			ES模块导入映射（Import Maps）
			作用：定义JavaScript模块的导入路径别名
			说明：现代浏览器中替代传统构建工具的方式
		============================================================ -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- ============================================================
			主应用程序模块
			这是整个水面模拟的核心逻辑
		============================================================ -->
		<script type="module">

			// ============================================================
			// 模块导入部分
			// ============================================================
			
			// 导入Three.js核心库
			import * as THREE from 'three';

			// 导入各种工具库
			import Stats from 'three/addons/libs/stats.module.js'; // 性能监控器（FPS、内存等）
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js'; // 轻量级GUI控制面板
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; // 相机轨道控制器

			// 导入GPGPU相关库
			import { GPUComputationRenderer } from 'three/addons/misc/GPUComputationRenderer.js'; // GPU计算渲染器
			import { SimplexNoise } from 'three/addons/math/SimplexNoise.js'; // 单纯形噪声生成器（优于Perlin噪声）

			// 导入资源加载器
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'; // GLTF 3D模型加载器
			import { HDRLoader } from 'three/addons/loaders/HDRLoader.js'; // HDR环境贴图加载器
			import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'; // Draco压缩模型解码器

			// ============================================================
			// 常量定义
			// ============================================================
			
			// 模拟纹理宽度（分辨率）：决定水面模拟的精度
			// 128x128纹理 = 16384个模拟点，在性能和质量间取得平衡
			const WIDTH = 128;

			// 水面实际尺寸（世界单位）：6个单位，水池的大小
			const BOUNDS = 6;
			const BOUNDS_HALF = BOUNDS * 0.5; // 半尺寸，常用于边界检查

			// ============================================================
			// 全局变量声明
			// ============================================================
			
			let tmpHeightmap = null; // 当前帧的高度图纹理引用
			
			// 临时四元数，用于鸭子旋转插值计算
			const tmpQuat = new THREE.Quaternion();
			const tmpQuatX = new THREE.Quaternion();
			const tmpQuatZ = new THREE.Quaternion();
			
			let duckModel = null; // 鸭子3D模型引用

			// Three.js核心对象
			let container, stats; // DOM容器和性能监控器
			let camera, scene, renderer, controls; // 相机、场景、渲染器、控制器
			
			// 鼠标交互相关
			let mousedown = false; // 鼠标按下状态标志
			const mouseCoords = new THREE.Vector2(); // 鼠标标准化设备坐标（NDC）
			const raycaster = new THREE.Raycaster(); // 光线投射器，用于3D拾取

			// 场景对象
			let sun; // 平行光源（模拟太阳）
			let waterMesh; // 水面网格对象
			let poolBorder; // 水池边界网格
			let meshRay; // 用于射线检测的不可见平面（鼠标交互）
			
			// GPGPU相关
			let gpuCompute; // GPU计算渲染器实例
			let heightmapVariable; // 高度图计算变量
			let readWaterLevelShader; // 读取水位着色器材质
			let readWaterLevelRenderTarget; // 读取水位的渲染目标（4x1像素）
			let readWaterLevelImage; // 读取的水位数据（Uint8Array）
			const waterNormal = new THREE.Vector3(); // 水的法线向量（临时计算用）

			// 鸭子模拟相关
			const NUM_DUCK = 12; // 鸭子数量
			const ducks = []; // 鸭子对象数组
			let ducksEnabled = true; // 鸭子模拟是否启用

			// 噪声生成器：用于创建初始水面波动
			const simplex = new SimplexNoise();

			let frame = 0; // 帧计数器，用于控制模拟更新频率

			// ============================================================
			// GUI控制参数
			// 这些参数可以通过界面实时调整
			// ============================================================
			const effectController = {
				mouseSize: 0.2,        // 鼠标影响范围：0.1-1.0
				mouseDeep: 0.01,       // 鼠标下压深度：0.01-1.0
				viscosity: 0.93,       // 水的粘性/阻尼：0.9-0.999（越高衰减越快）
				speed: 5,              // 模拟速度：1-6（越高更新越快）
				ducksEnabled: ducksEnabled, // 是否启用鸭子模拟
				wireframe: false,      // 是否显示线框模式
				shadow: false,         // 是否启用阴影
			};

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

			// ============================================================
			// 异步初始化函数
			// 作用：设置Three.js场景、加载资源、初始化模拟
			// ============================================================
			async function init() {

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

				// --------------------------------------------------------
				// 2. 初始化相机
				// --------------------------------------------------------
				// 透视相机：75度视野，基于窗口的宽高比，近裁剪面0.1，远裁剪面1000
				camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 );
				camera.position.set( 0, 2.00, 4 ); // 相机位置：X=0, Y=2, Z=4
				camera.lookAt( 0, 0, 0 ); // 看向原点

				// --------------------------------------------------------
				// 3. 初始化场景
				// --------------------------------------------------------
				scene = new THREE.Scene();

				// --------------------------------------------------------
				// 4. 创建光源
				// --------------------------------------------------------
				// 平行光：模拟太阳光，白色，强度4.0
				sun = new THREE.DirectionalLight( 0xFFFFFF, 4.0 );
				sun.position.set( - 1, 2.6, 1.4 ); // 光源位置
				scene.add( sun );

				// --------------------------------------------------------
				// 5. 初始化渲染器
				// --------------------------------------------------------
				renderer = new THREE.WebGLRenderer( { antialias: true } ); // 开启抗锯齿
				renderer.setPixelRatio( window.devicePixelRatio ); // 设置设备像素比
				renderer.setSize( window.innerWidth, window.innerHeight ); // 设置渲染尺寸
				renderer.toneMapping = THREE.ACESFilmicToneMapping; // 使用ACES电影级色调映射
				renderer.toneMappingExposure = 0.5; // 曝光度0.5
				container.appendChild( renderer.domElement ); // 将canvas添加到DOM

				// --------------------------------------------------------
				// 6. 初始化轨道控制器
				// --------------------------------------------------------
				controls = new OrbitControls( camera, container );

				// --------------------------------------------------------
				// 7. 初始化性能监控器
				// --------------------------------------------------------
				stats = new Stats();
				container.appendChild( stats.dom );

				// --------------------------------------------------------
				// 8. 添加事件监听器
				// --------------------------------------------------------
				container.style.touchAction = 'none'; // 禁用触摸默认行为（防止页面滚动）
				container.addEventListener( 'pointermove', onPointerMove ); // 鼠标/触摸移动
				container.addEventListener( 'pointerdown', onPointerDown ); // 鼠标/触摸按下
				container.addEventListener( 'pointerup', onPointerUp ); // 鼠标/触摸释放
				window.addEventListener( 'resize', onWindowResize ); // 窗口大小变化

				// --------------------------------------------------------
				// 9. 异步加载资源
				// --------------------------------------------------------
				const hdrLoader = new HDRLoader().setPath( './textures/equirectangular/' );
				const glbloader = new GLTFLoader().setPath( 'models/gltf/' );
				glbloader.setDRACOLoader( new DRACOLoader().setDecoderPath( 'jsm/libs/draco/gltf/' ) );

				// 并行加载HDR环境贴图和鸭子模型
				const [ env, model ] = await Promise.all( [ 
					hdrLoader.loadAsync( 'blouberg_sunrise_2_1k.hdr' ), // HDR环境贴图
					glbloader.loadAsync( 'duck.glb' ) // GLTF鸭子模型
				] );
				
				// --------------------------------------------------------
				// 10. 设置场景环境
				// --------------------------------------------------------
				env.mapping = THREE.EquirectangularReflectionMapping; // 设置环境贴图映射方式
				scene.environment = env; // 设置场景环境贴图（用于PBR反射）
				scene.background = env; // 设置场景背景
				scene.backgroundBlurriness = 0.3; // 背景模糊度
				scene.environmentIntensity = 1.25; // 环境光强度

				// 获取鸭子模型（GLTF场景的第一个子对象）
				duckModel = model.scene.children[ 0 ];
				duckModel.receiveShadow = true; // 鸭子接收阴影
				duckModel.castShadow = true; // 鸭子投射阴影

				// --------------------------------------------------------
				// 11. 初始化GUI控制面板
				// --------------------------------------------------------
				const gui = new GUI();
				gui.domElement.style.right = '0px'; // 将GUI定位到右侧

				// GUI参数变更回调函数
				const valuesChanger = function () {
					// 更新GPU计算着色器的uniforms值
					heightmapVariable.material.uniforms[ 'mouseSize' ].value = effectController.mouseSize;
					heightmapVariable.material.uniforms[ 'deep' ].value = effectController.mouseDeep;
					heightmapVariable.material.uniforms[ 'viscosity' ].value = effectController.viscosity;
					ducksEnabled = effectController.ducksEnabled; // 更新鸭子启用状态

					// 更新所有鸭子的可见性
					let i = NUM_DUCK;
					while ( i -- ) {
						if ( ducks[ i ] ) ducks[ i ].visible = ducksEnabled;
					}
				};

				// 添加GUI控制器
				gui.add( effectController, 'mouseSize', 0.1, 1.0, 0.1 ).name('鼠标影响范围').onChange( valuesChanger );
				gui.add( effectController, 'mouseDeep', 0.01, 1.0, 0.01 ).name('鼠标下压深度').onChange( valuesChanger );
				gui.add( effectController, 'viscosity', 0.9, 0.999, 0.001 ).name('水的粘性').onChange( valuesChanger );
				gui.add( effectController, 'speed', 1, 6, 1 ).name('模拟速度'); // 模拟速度控制器
				gui.add( effectController, 'ducksEnabled' ).name('显示鸭子').onChange( valuesChanger ); // 鸭子开关
				gui.add( effectController, 'wireframe' ).name('线框模式').onChange( ( v )=>{
					waterMesh.material.wireframe = v; // 水面线框模式
					poolBorder.material.wireframe = v; // 水池边界线框模式
				} );
				gui.add( effectController, 'shadow' ).name('启用阴影').onChange( addShadow ); // 阴影开关

				// --------------------------------------------------------
				// 12. 初始化水面模拟
				// --------------------------------------------------------
				initWater();

				// --------------------------------------------------------
				// 13. 创建鸭子
				// --------------------------------------------------------
				createducks();

				// --------------------------------------------------------
				// 14. 应用初始参数
				// --------------------------------------------------------
				valuesChanger();

				// --------------------------------------------------------
				// 15. 启动动画循环
				// --------------------------------------------------------
				renderer.setAnimationLoop( animate );

			}

			// ============================================================
			// 初始化水面函数
			// 作用：创建水面网格、水池边界、设置GPGPU模拟
			// ============================================================
			function initWater() {
				// --------------------------------------------------------
				// 1. 创建水面几何体
				// --------------------------------------------------------
				// 平面几何体：尺寸BOUNDS×BOUNDS，细分WIDTH-1×WIDTH-1个面片
				// 细分数量与模拟分辨率匹配，每个顶点对应一个模拟点
				const geometry = new THREE.PlaneGeometry( BOUNDS, BOUNDS, WIDTH - 1, WIDTH - 1 );

				// --------------------------------------------------------
				// 2. 创建自定义水面材质
				// --------------------------------------------------------
				const material = new WaterMaterial( {
					color: 0x9bd2ec, // 水的颜色（浅蓝色）
					metalness: 0.9,   // 金属度：接近1表示像金属一样反射
					roughness: 0,     // 粗糙度：0表示完全光滑（镜面反射）
					transparent: true, // 透明：允许透明度
					opacity: 0.8,     // 不透明度：80%
					side: THREE.DoubleSide // 双面渲染：两面都显示
				} );

				// --------------------------------------------------------
				// 3. 创建水面网格对象
				// --------------------------------------------------------
				waterMesh = new THREE.Mesh( geometry, material );
				waterMesh.rotation.x = - Math.PI * 0.5; // 旋转-90度，使平面水平
				waterMesh.matrixAutoUpdate = false; // 禁用自动矩阵更新（优化性能）
				waterMesh.updateMatrix(); // 手动更新一次矩阵

				waterMesh.receiveShadow = true; // 水面接收阴影
				waterMesh.castShadow = true;    // 水面投射阴影

				scene.add( waterMesh );

				// --------------------------------------------------------
				// 4. 创建水池边界
				// --------------------------------------------------------
				// 圆环几何体：半径4.2，管径0.1，径向分段12， tubular分段4
				const borderGeom = new THREE.TorusGeometry( 4.2, 0.1, 12, 4 );
				borderGeom.rotateX( Math.PI * 0.5 ); // 旋转90度，使圆环水平
				borderGeom.rotateY( Math.PI * 0.25 ); // 旋转45度，美观角度
				poolBorder = new THREE.Mesh( borderGeom, new THREE.MeshStandardMaterial( { 
					color: 0x908877, // 水池颜色（灰褐色）
					roughness: 0.2   // 粗糙度0.2
				} ) );
				scene.add( poolBorder );
				poolBorder.receiveShadow = true;
				poolBorder.castShadow = true;

				// --------------------------------------------------------
				// 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. 初始化GPU计算渲染器
				// --------------------------------------------------------
				// 创建WIDTH×WIDTH分辨率的GPU计算渲染器
				gpuCompute = new GPUComputationRenderer( WIDTH, WIDTH, renderer );

				// 创建初始高度图纹理
				const heightmap0 = gpuCompute.createTexture();
				fillTexture( heightmap0 ); // 用噪声填充初始纹理

				// 添加高度图计算变量
				// shaderChange.heightmap_frag是波动模拟的核心着色器
				heightmapVariable = gpuCompute.addVariable( 'heightmap', shaderChange.heightmap_frag, heightmap0 );
				
				// 设置变量依赖关系（这里高度图只依赖自身前一帧）
				gpuCompute.setVariableDependencies( heightmapVariable, [ heightmapVariable ] );

				// 设置着色器uniforms
				heightmapVariable.material.uniforms[ 'mousePos' ] = { 
					value: new THREE.Vector2( 10000, 10000 ) // 初始鼠标位置远离水面
				};
				heightmapVariable.material.uniforms[ 'mouseSize' ] = { value: 0.2 };
				heightmapVariable.material.uniforms[ 'viscosity' ] = { value: 0.93 };
				heightmapVariable.material.uniforms[ 'deep' ] = { value: 0.01 };
				heightmapVariable.material.defines.BOUNDS = BOUNDS.toFixed( 1 ); // 定义常量

				// 初始化GPU计算系统
				const error = gpuCompute.init();
				if ( error !== null ) console.error( error );

				// --------------------------------------------------------
				// 7. 创建读取水位着色器材质
				// --------------------------------------------------------
				readWaterLevelShader = gpuCompute.createShaderMaterial( 
					document.getElementById( 'readWaterLevelFragmentShader' ).textContent, 
					{
						point1: { value: new THREE.Vector2() }, // 查询点坐标
						levelTexture: { value: null } // 水位纹理
					} 
				);
				// 定义着色器常量
				readWaterLevelShader.defines.WIDTH = WIDTH.toFixed( 1 );
				readWaterLevelShader.defines.BOUNDS = BOUNDS.toFixed( 1 );

				// --------------------------------------------------------
				// 8. 创建水位数据读取缓冲区
				// --------------------------------------------------------
				// 4像素 × 1行 × 4通道 = 16字节
				readWaterLevelImage = new Uint8Array( 4 * 1 * 4 );

				// 创建渲染目标：4x1像素，用于存储编码后的浮点数
				readWaterLevelRenderTarget = new THREE.WebGLRenderTarget( 4, 1, {
					wrapS: THREE.ClampToEdgeWrapping, // 边缘包裹方式：拉伸边缘像素
					wrapT: THREE.ClampToEdgeWrapping,
					minFilter: THREE.NearestFilter, // 最小过滤：最近邻（防止插值）
					magFilter: THREE.NearestFilter, // 放大过滤：最近邻
					format: THREE.RGBAFormat, // 格式：RGBA四通道
					type: THREE.UnsignedByteType, // 数据类型：无符号字节（0-255）
					depthBuffer: false // 禁用深度缓冲（不需要深度测试）
				} );
			}

			// ============================================================
			// 填充纹理函数
			// 作用：用分形噪声生成初始水面高度图
			// 参数：texture - 要填充的纹理对象
			// ============================================================
			function fillTexture( texture ) {
				const waterMaxHeight = 0.1; // 最大波高

				// --------------------------------------------------------
				// 分形噪声函数（多倍频程噪声）
				// 原理：叠加多个不同频率和振幅的噪声层
				// 效果：产生自然的水面波动效果
				// --------------------------------------------------------
				function noise( x, y ) {
					let multR = waterMaxHeight; // 初始振幅
					let mult = 0.025; // 初始频率
					let r = 0; // 结果值
					
					// 叠加15层噪声
					for ( let i = 0; i < 15; i ++ ) {
						// 添加当前频率和振幅的噪声
						r += multR * simplex.noise( x * mult, y * mult );
						// 振幅递减：每一层振幅减少约一半
						multR *= 0.53 + 0.025 * i;
						// 频率递增：每一层频率增加25%
						mult *= 1.25;
					}
					return r;
				}

				// 获取纹理像素数据
				const pixels = texture.image.data;

				let p = 0; // 像素数据指针
				// 遍历纹理的每个像素
				for ( let j = 0; j < WIDTH; j ++ ) {
					for ( let i = 0; i < WIDTH; i ++ ) {
						// 将像素坐标映射到噪声空间
						const x = i * 128 / WIDTH;
						const y = j * 128 / WIDTH;

						// ----------------------------------------------------
						// 设置像素的RGBA值：
						// R通道：当前高度（用于显示）
						// G通道：前一帧高度（用于波动计算）
						// B通道：未使用（保留）
						// A通道：未使用（保留）
						// ----------------------------------------------------
						pixels[ p + 0 ] = noise( x, y ); // R = 当前高度
						pixels[ p + 1 ] = pixels[ p + 0 ]; // G = 当前高度（复制）
						pixels[ p + 2 ] = 0; // B = 0
						pixels[ p + 3 ] = 1; // A = 1（完全不透明）

						p += 4; // 移动到下一个像素
					}
				}
			}

			// ============================================================
			// 添加/移除阴影函数
			// 作用：配置和启用/禁用阴影渲染
			// 参数：v - 布尔值，是否启用阴影
			// ============================================================
			function addShadow( v ) {
				// 启用/禁用渲染器的阴影映射
				renderer.shadowMap.enabled = v;
				// 设置光源是否投射阴影
				sun.castShadow = v;

				if ( v ) {
					// ----------------------------------------------------
					// 阴影配置
					// ----------------------------------------------------
					renderer.shadowMap.type = THREE.VSMShadowMap; // 使用VSM阴影（视觉上更平滑）
					const shadow = sun.shadow;
					
					// 阴影贴图分辨率：2048x2048
					shadow.mapSize.width = shadow.mapSize.height = 2048;
					shadow.radius = 2; // 阴影模糊半径
					shadow.bias = - 0.0005; // 阴影偏移，减少"阴影痤疮"现象
					
					// 阴影相机配置（正交相机）
					const shadowCam = shadow.camera, s = 5;
					shadowCam.near = 0.1; // 近裁剪面
					shadowCam.far = 6;    // 远裁剪面
					// 设置正交相机边界
					shadowCam.right = shadowCam.top	= s;    // 右边界和上边界
					shadowCam.left = shadowCam.bottom = - s; // 左边界和下边界
				} else {
					// 禁用阴影时释放阴影贴图资源
					if ( sun.shadow ) sun.shadow.dispose();
				}
			}

			// ============================================================
			// 创建鸭子函数
			// 作用：在场景中创建NUM_DUCK个鸭子实例
			// ============================================================
			function createducks() {
				for ( let i = 0; i < NUM_DUCK; i ++ ) {
					let sphere = duckModel; // 第一个鸭子使用原始模型
					
					// 克隆模型（除了最后一个，因为第一个已经使用了原始模型）
					if ( i < NUM_DUCK - 1 ) {
						sphere = duckModel.clone();
					}

					// 设置随机初始位置（限制在水池中心区域）
					sphere.position.x = ( Math.random() - 0.5 ) * BOUNDS * 0.7;
					sphere.position.z = ( Math.random() - 0.5 ) * BOUNDS * 0.7;

					// 为每个鸭子存储速度向量（用于物理模拟）
					sphere.userData.velocity = new THREE.Vector3();

					// 添加到场景和数组
					scene.add( sphere );
					ducks[ i ] = sphere;
				}
			}

			// ============================================================
			// 鸭子动力学模拟函数
			// 作用：更新鸭子的位置和旋转，使其随水面波动
			// 原理：读取鸭子当前位置的水面高度和法线，施加物理力
			// ============================================================
			function duckDynamics() {
				// 设置水位纹理为当前高度图
				readWaterLevelShader.uniforms[ 'levelTexture' ].value = tmpHeightmap;

				// 遍历所有鸭子
				for ( let i = 0; i < NUM_DUCK; i ++ ) {
					const sphere = ducks[ i ];

					if ( sphere ) {
						// ----------------------------------------------------
						// 1. 世界坐标转UV坐标
						// ----------------------------------------------------
						// 将鸭子的XZ世界坐标转换为纹理UV坐标
						// UV范围：0到1，中心点为(0.5, 0.5)
						const u = 0.5 * sphere.position.x / BOUNDS_HALF + 0.5;
						const v = 1 - ( 0.5 * sphere.position.z / BOUNDS_HALF + 0.5 ); // 注意Y轴翻转
						
						// 设置着色器查询点
						readWaterLevelShader.uniforms[ 'point1' ].value.set( u, v );
						
						// 执行计算着色器，将结果渲染到4x1的渲染目标
						gpuCompute.doRenderTarget( readWaterLevelShader, readWaterLevelRenderTarget );
						
						// 从GPU读取渲染结果到CPU内存
						renderer.readRenderTargetPixels( 
							readWaterLevelRenderTarget, // 源渲染目标
							0, 0, // 起始坐标
							4, 1, // 读取区域：4像素宽，1像素高
							readWaterLevelImage // 目标数组
						);
						
						// 将Uint8Array转换为Float32Array（解码浮点数）
						const pixels = new Float32Array( readWaterLevelImage.buffer );

						// ----------------------------------------------------
						// 2. 获取水面法线
						// ----------------------------------------------------
						// pixels[1]是法线X分量，pixels[2]是法线Y分量
						// 注意：Z分量取负，因为法线计算时Z方向与世界坐标相反
						waterNormal.set( pixels[ 1 ], 0, - pixels[ 2 ] );

						const pos = sphere.position;
						const startPos = pos.clone(); // 保存起始位置（用于计算运动方向）

						// ----------------------------------------------------
						// 3. 设置鸭子高度（跟随水面）
						// ----------------------------------------------------
						pos.y = pixels[ 0 ]; // pixels[0]是水位高度

						// ----------------------------------------------------
						// 4. 根据水面法线移动鸭子
						// ----------------------------------------------------
						// 水面倾斜会产生重力分量，使鸭子滑向低处
						waterNormal.multiplyScalar( 0.01 ); // 缩放法线影响强度
						sphere.userData.velocity.add( waterNormal ); // 将法线方向力添加到速度
						sphere.userData.velocity.multiplyScalar( 0.998 ); // 阻尼：模拟水阻
						pos.add( sphere.userData.velocity ); // 更新位置

						// ----------------------------------------------------
						// 5. 边界碰撞检测
						// ----------------------------------------------------
						const decal = 0.001; // 边界偏移量（防止卡在边界）
						const limit = BOUNDS_HALF - 0.2; // 边界限制（留出0.2单位的边缘）

						// X轴边界检测
						if ( pos.x < - limit ) {
							pos.x = - limit + decal; // 限制位置
							sphere.userData.velocity.x *= - 0.3; // 反弹（损失70%能量）
						} else if ( pos.x > limit ) {
							pos.x = limit - decal;
							sphere.userData.velocity.x *= - 0.3;
						}

						// Z轴边界检测
						if ( pos.z < - limit ) {
							pos.z = - limit + decal;
							sphere.userData.velocity.z *= - 0.3;
						} else if ( pos.z > limit ) {
							pos.z = limit - decal;
							sphere.userData.velocity.z *= - 0.3;
						}

						// ----------------------------------------------------
						// 6. 鸭子旋转计算
						// ----------------------------------------------------
						// 计算水面的倾斜法线（Y分量设为1，使鸭子始终向上）
						const startNormal = new THREE.Vector3( pixels[ 1 ], 1, - pixels[ 2 ] ).normalize();
						
						// 计算运动方向（水平方向）
						const dir = startPos.sub( pos ); // 从当前位置指向起始位置
						dir.y = 0; // 忽略垂直分量
						dir.normalize(); // 归一化

						// 定义参考轴
						const yAxis = new THREE.Vector3( 0, 1, 0 ); // 世界Y轴
						const zAxis = new THREE.Vector3( 0, 0, - 1 ); // 鸭子初始朝向

						// 计算两个旋转：
						tmpQuatX.setFromUnitVectors( zAxis, dir ); // 旋转到运动方向
						tmpQuatZ.setFromUnitVectors( yAxis, startNormal ); // 旋转到水面法线方向
						
						// 组合旋转：先按法线旋转，再按方向旋转
						tmpQuat.multiplyQuaternions( tmpQuatZ, tmpQuatX );
						
						// 平滑插值到目标旋转（0.017 ≈ 1/60，每帧旋转一小部分）
						sphere.quaternion.slerp( tmpQuat, 0.017 );
					}
				}
			}

			// ============================================================
			// 窗口大小变化处理函数
			// 作用：当浏览器窗口大小改变时，更新相机和渲染器
			// ============================================================
			function onWindowResize() {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				camera.updateProjectionMatrix(); // 必须调用此方法使更改生效
				
				// 更新渲染器尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ============================================================
			// 鼠标按下事件处理函数
			// ============================================================
			function onPointerDown() {
				mousedown = true;
			}

			// ============================================================
			// 鼠标释放事件处理函数
			// ============================================================
			function onPointerUp() {
				mousedown = false;
				controls.enabled = true; // 重新启用轨道控制
			}

			// ============================================================
			// 鼠标移动事件处理函数
			// 作用：将鼠标屏幕坐标转换为标准化设备坐标（NDC）
			// ============================================================
			function onPointerMove( event ) {
				const dom = renderer.domElement;
				// 将屏幕坐标转换为NDC坐标：
				// X: -1到1（左到右）
				// Y: -1到1（下到上，注意Y轴翻转）
				mouseCoords.set( 
					( event.clientX / dom.clientWidth ) * 2 - 1,
					- ( event.clientY / dom.clientHeight ) * 2 + 1
				);
			}

			// ============================================================
			// 射线检测函数
			// 作用：处理鼠标与水面交互，将鼠标位置传递给GPU着色器
			// ============================================================
			function raycast() {
				const uniforms = heightmapVariable.material.uniforms;
				
				if ( mousedown ) {
					// 从相机发射射线到鼠标指向的方向
					raycaster.setFromCamera( mouseCoords, camera );
					
					// 检测射线与不可见平面的交点
					const intersects = raycaster.intersectObject( meshRay );

					if ( intersects.length > 0 ) {
						// 获取交点的世界坐标
						const point = intersects[ 0 ].point;
						// 将鼠标位置传递给着色器（只传递XZ坐标）
						uniforms[ 'mousePos' ].value.set( point.x, point.z );
						if ( controls.enabled ) controls.enabled = false; // 禁用轨道控制
					} else {
						// 没有交点时，将鼠标位置设为远离水面
						uniforms[ 'mousePos' ].value.set( 10000, 10000 );
					}
				} else {
					// 鼠标未按下时，重置鼠标位置
					uniforms[ 'mousePos' ].value.set( 10000, 10000 );
				}
			}

			// ============================================================
			// 动画循环函数
			// 作用：Three.js的主循环，每帧调用
			// ============================================================
			function animate() {
				render(); // 渲染帧
				stats.update(); // 更新性能统计显示
			}

			// ============================================================
			// 渲染函数
			// 作用：更新模拟状态并渲染场景
			// ============================================================
			function render() {
				// 1. 执行鼠标交互检测
				raycast();

				// 2. 更新帧计数器
				frame ++;

				// 3. 根据模拟速度控制更新频率
				// effectController.speed: 1-6，速度越高更新越快
				if ( frame >= 7 - effectController.speed ) {
					// ----------------------------------------------------
					// 执行GPU计算（水面模拟核心）
					// ----------------------------------------------------
					gpuCompute.compute();
					
					// 获取当前高度图纹理
					tmpHeightmap = gpuCompute.getCurrentRenderTarget( heightmapVariable ).texture;

					// 如果鸭子启用，执行鸭子动力学模拟
					if ( ducksEnabled ) duckDynamics();

					// 将高度图传递给水面材质
					if ( waterMesh ) waterMesh.material.heightmap = tmpHeightmap;

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

				// 4. 渲染场景到屏幕
				renderer.render( scene, camera );
			}

			// ============================================================
			// 自定义水面材质类
			// 继承自THREE.MeshStandardMaterial，添加高度图支持
			// ============================================================
			class WaterMaterial extends THREE.MeshStandardMaterial {
				constructor( parameters ) {
					super();

					// ----------------------------------------------------
					// 着色器定义
					// 这些定义会在编译着色器时被替换
					// ----------------------------------------------------
					this.defines = {
						'STANDARD': '', // 标准材质定义
						'USE_UV': '',   // 使用UV坐标
						'WIDTH': WIDTH.toFixed( 1 ), // 传递模拟宽度
						'BOUNDS': BOUNDS.toFixed( 1 ), // 传递边界尺寸
					};

					this.extra = {}; // 存储自定义uniforms

					// 添加高度图参数
					this.addParameter( 'heightmap', null );

					// 设置材质参数
					this.setValues( parameters );
				}

				// --------------------------------------------------------
				// 添加自定义参数的方法
				// 作用：创建属性的getter/setter，自动更新着色器uniform
				// --------------------------------------------------------
				addParameter( name, value ) {
					this.extra[ name ] = value;
					
					// 使用Object.defineProperty创建响应式属性
					Object.defineProperty( this, name, {
						// getter：返回当前值
						get: () => ( this.extra[ name ] ),
						// setter：设置新值并更新着色器uniform
						set: ( v ) => {
							this.extra[ name ] = v;
							// 如果着色器已编译，更新对应的uniform
							if ( this.userData.shader ) {
								this.userData.shader.uniforms[ name ].value = this.extra[ name ];
							}
						}
					} );
				}

				// --------------------------------------------------------
				// 在编译着色器前修改着色器代码
				// 作用：注入自定义的uniform和着色器代码
				// --------------------------------------------------------
				onBeforeCompile( shader ) {
					// 1. 添加自定义uniforms到着色器
					for ( const name in this.extra ) {
						shader.uniforms[ name ] = { value: this.extra[ name ] };
					}

					// 2. 修改顶点着色器代码
					// 替换标准材质的代码片段为自定义实现
					shader.vertexShader = shader.vertexShader.replace( 
						'#include <common>', 
						shaderChange.common // 注入高度图uniform声明
					);
					
					shader.vertexShader = shader.vertexShader.replace( 
						'#include <beginnormal_vertex>', 
						shaderChange.beginnormal_vertex // 注入法线计算代码
					);
					
					shader.vertexShader = shader.vertexShader.replace( 
						'#include <begin_vertex>', 
						shaderChange.begin_vertex // 注入顶点高度计算代码
					);

					// 保存着色器引用，以便后续更新uniforms
					this.userData.shader = shader;
				}
			}

			// ============================================================
			// 着色器代码片段对象
			// 包含所有自定义的GLSL代码片段
			// ============================================================
			const shaderChange = {
				// --------------------------------------------------------
				// 高度图计算着色器（波动模拟核心）
				// 运行在GPU上的片段着色器，每帧对每个纹素执行
				// --------------------------------------------------------
				heightmap_frag: /* glsl */`
				#include <common>  // 包含Three.js公共着色器函数

				// Uniforms（由JavaScript传递）
				uniform vec2 mousePos;   // 鼠标位置（世界坐标XZ）
				uniform float mouseSize; // 鼠标影响半径
				uniform float viscosity; // 水的粘性/阻尼系数
				uniform float deep;      // 鼠标下压深度

				void main()	{
					// 计算单个纹素在纹理坐标中的大小
					vec2 cellSize = 1.0 / resolution.xy;
					// 当前纹素的UV坐标
					vec2 uv = gl_FragCoord.xy * cellSize;

					// 读取当前纹素的高度信息
					// heightmapValue.x: 当前帧高度
					// heightmapValue.y: 前一帧高度
					// heightmapValue.z: 未使用
					// heightmapValue.w: 未使用
					vec4 heightmapValue = texture2D( heightmap, uv );

					// 获取四个邻居的高度值
					vec4 north = texture2D( heightmap, uv + vec2( 0.0, cellSize.y ) ); // 上
					vec4 south = texture2D( heightmap, uv + vec2( 0.0, - cellSize.y ) ); // 下
					vec4 east = texture2D( heightmap, uv + vec2( cellSize.x, 0.0 ) ); // 右
					vec4 west = texture2D( heightmap, uv + vec2( - cellSize.x, 0.0 ) ); // 左

					// ====================================================
					// 波动方程离散化（简化2D波动方程）
					// 公式：newHeight = (邻居平均 * 0.5 - 前一帧高度) * 粘性
					// 物理意义：水面高度变化受邻居影响，并逐渐衰减
					// ====================================================
					float newHeight = ( ( north.x + south.x + east.x + west.x ) * 0.5 - (heightmapValue.y) ) * viscosity;

					// ====================================================
					// 鼠标交互影响
					// 在鼠标位置产生圆形下压效果
					// ====================================================
					// 计算当前纹素到鼠标位置的距离（转换为世界坐标）
					float mousePhase = clamp( 
						length( ( uv - vec2( 0.5 ) ) * BOUNDS - vec2( mousePos.x, - mousePos.y ) ) 
						* PI / mouseSize, // 标准化距离
						0.0, 
						PI // 限制在0-PI之间
					);
					
					// 使用余弦函数创建平滑的下压效果
					// cos(mousePhase)+1 在中心为2，边缘为0，产生平滑过渡
					newHeight -= ( cos( mousePhase ) + 1.0 ) * deep;

					// ====================================================
					// 更新高度历史
					// ====================================================
					heightmapValue.y = heightmapValue.x; // 当前帧变为前一帧
					heightmapValue.x = newHeight;        // 设置新的高度

					// 输出更新后的高度信息
					gl_FragColor = heightmapValue;
				}
				`,
				
				// --------------------------------------------------------
				// 水面材质公共部分
				// 注入到标准材质的<common>代码块中
				// --------------------------------------------------------
				common: /* glsl */`
				#include <common>
				// 声明高度图uniform
				uniform sampler2D heightmap;
				`,
				
				// --------------------------------------------------------
				// 法线计算代码
				// 替换标准材质的<beginnormal_vertex>代码块
				// 作用：从高度图计算水面法线
				// --------------------------------------------------------
				beginnormal_vertex: /* glsl */`
				// 计算纹素大小
				vec2 cellSize = vec2( 1.0 / WIDTH, 1.0 / WIDTH );
				
				// 使用中心差分法计算法线
				// 法线X分量：左右邻居的高度差
				// 法线Y分量：上下邻居的高度差
				// 法线Z分量：固定为1（垂直方向）
				vec3 objectNormal = vec3(
					( texture2D( heightmap, uv + vec2( - cellSize.x, 0 ) ).x 
					- texture2D( heightmap, uv + vec2( cellSize.x, 0 ) ).x ) * WIDTH / BOUNDS,
					( texture2D( heightmap, uv + vec2( 0, - cellSize.y ) ).x 
					- texture2D( heightmap, uv + vec2( 0, cellSize.y ) ).x ) * WIDTH / BOUNDS,
					1.0 // Z分量固定，因为水面主要是垂直波动
				);
				
				// 如果使用切线空间，保持原有切线
				#ifdef USE_TANGENT
					vec3 objectTangent = vec3( tangent.xyz );
				#endif
				`,
				
				// --------------------------------------------------------
				// 顶点高度计算代码
				// 替换标准材质的<begin_vertex>代码块
				// 作用：从高度图读取高度值并应用到顶点
				// --------------------------------------------------------
				begin_vertex: /* glsl */`
				// 从高度图读取当前UV坐标的高度值
				float heightValue = texture2D( heightmap, uv ).x;
				
				// 修改顶点位置：XY保持不变，Z坐标使用高度值
				// position是几何体的原始顶点位置
				vec3 transformed = vec3( position.x, position.y, heightValue );
				
				// 如果使用Alpha Hash，传递原始位置
				#ifdef USE_ALPHAHASH
					vPosition = vec3( position );
				#endif
				`,
			};

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