<!-- Three.js WebGPU 流体粒子模拟系统
一、总体功能描述
这是一个基于WebGPU和Three.js的高性能流体粒子模拟系统，使用移动最小二乘物质点法（MLS-MPM） 实时模拟流体物理效果。系统的主要功能包括：

1. 核心模拟功能
粒子流体动力学模拟：模拟32,768-131,072个粒子的流体行为

物理特性模拟：

流体压力、密度变化

粘性效应

重力影响

边界碰撞

交互式操控：通过鼠标与流体进行实时交互

2. 可视化功能
实例化粒子渲染：高效渲染大量粒子

HDR环境光照：提供真实的环境反射效果

动态相机控制：支持旋转、缩放视角

实时参数调整：可通过GUI调整粒子数量等参数

3. 性能特性
GPU加速计算：所有物理计算在WebGPU计算着色器中执行

大规模粒子支持：最多支持131,072个粒子

实时性能：在主流GPU上保持60FPS的流畅模拟

二、主要技术点
1. WebGPU技术栈
WebGPU渲染器：使用Three.js的WebGPU后端，提供现代GPU API访问

计算着色器：执行所有物理模拟计算，充分利用GPU并行能力

存储缓冲区：使用存储缓冲区（Storage Buffer）进行GPU数据交换

2. MLS-MPM算法实现
这是系统的核心物理算法，包含五个关键步骤：

a. 清空网格（clearGridKernel）
每帧开始时重置网格数据

使用原子操作确保多线程安全

b. 粒子到网格传输（P2G）
P2G第一部分：传输粒子动量到网格

javascript
// 关键公式：贡献动量 = 权重 × (粒子速度 + C·Δx)
const velContrib = massContrib.mul(particleVelocity.add(Q));
P2G第二部分：计算压力并传输应力

javascript
// 状态方程：p = max(0, (ρ/ρ₀)⁵ - 1) × k
const pressure = max(0.0, pow(density/restDensity, 5.0) - 1) * stiffness;
c. 网格更新（updateGridKernel）
计算网格最终速度：v = p / m

处理边界条件：边界网格速度设为0

d. 网格到粒子传输（G2P）
从网格插值速度到粒子

更新粒子位置和速度

应用外部力（重力、鼠标交互）

3. 关键技术细节
a. 定点数原子操作
javascript
// WebGPU只支持整数原子操作
const encodeFixedPoint = (f32) => int(f32 * 1e7);  // 编码
const decodeFixedPoint = (i32) => float(i32) / 1e7; // 解码
原因：WebGPU原子操作仅支持整数类型

解决方案：使用定点数表示（乘/除1e7保持精度）

b. 三次B样条插值
javascript
// 权重函数（一维）
const w0 = 0.5 * (0.5 - d)²;  // 左权重
const w1 = 0.75 - d²;         // 中权重  
const w2 = 0.5 * (0.5 + d)²;  // 右权重
作用：平滑粒子与网格之间的数据传递

范围：每个粒子影响3×3×3=27个相邻网格

c. 仿射动量矩阵（C矩阵）
存储内容：粒子的局部速度梯度（∇v）

物理意义：描述粒子变形和旋转

更新公式：C_next = 4 × Σ(w × v_grid × Δxᵀ)

d. 实例化渲染优化
javascript
// 顶点着色器中的位置计算
material.positionNode = Fn(() => {
  return attribute('position') + particleBuffer[instanceIndex].position;
});
原理：单个几何体 + 实例数据缓冲区

优势：大幅减少Draw Call和GPU状态切换

4. 交互系统
a. 鼠标射线检测
将2D屏幕坐标转换为3D世界射线

计算与模拟平面（Y=0）的交点

基于距离施加交互力

b. 交互力计算
javascript
// 力随距离衰减
const force = max(0, 1 - 3×dist)²;
particleVelocity += mouseForce * force;
5. 边界处理
a. 硬边界
网格边界：速度设为0

粒子边界：使用clamp函数限制位置

b. 圆角框约束（更自然的边界）
javascript
// 将粒子推向圆角框内部
if (dist > radius) {
  position -= normalize(pp) * (dist - radius) * 1.3;
}
6. 性能优化技术
a. 间接调度
动态计算所需的工作组数量

避免重新编译着色器

b. 缓冲区重用
粒子缓冲区：存储位置、速度、C矩阵

网格缓冲区：双缓冲设计（原子缓冲区+浮点缓冲区）

c. 几何体优化
使用低多边形二十面体

合并重复顶点减少GPU负载

7. 渲染与视觉效果
a. HDR环境映射
使用HDR贴图提供高质量环境光照

支持反射和背景模糊

b. 色调映射
ACES电影级色调映射

可调节曝光值

8. 系统架构
text
CPU端（JavaScript）           GPU端（WebGPU）
├── 参数控制                   ├── 计算管线
├── 缓冲区管理                 │   ├── clearGridKernel
├── 渲染循环                   │   ├── p2g1Kernel
└── 用户交互                   │   ├── p2g2Kernel
                               │   ├── updateGridKernel
                               │   └── g2pKernel
                               │
                               └── 渲染管线
                                   ├── 顶点着色器
                                   ├── 片段着色器
                                   └── 输出合并
三、技术挑战与解决方案
1. 挑战：WebGPU限制
问题：缺乏浮点数原子操作

解决方案：定点数编码+整数原子操作

2. 挑战：数据同步
问题：多线程写入冲突

解决方案：原子操作+双缓冲区设计

3. 挑战：性能优化
问题：大量粒子渲染性能

解决方案：实例化渲染+几何体优化

4. 挑战：数值稳定性
问题：模拟发散

解决方案：时间步长限制+边界约束

四、应用场景
教育演示：物理模拟教学

创意可视化：艺术和设计展示

游戏开发：流体效果预研

科研模拟：小规模流体动力学研究

技术验证：WebGPU和计算着色器能力展示

五、技术亮点总结
完全GPU加速：物理模拟和渲染都在GPU完成

真实物理效果：基于MLS-MPM的准确流体模拟

高性能：支持十万级粒子的实时模拟

现代API：使用WebGPU替代传统WebGL

交互性强：实时鼠标交互+参数调整

视觉效果优秀：HDR照明+实例化渲染 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js WebGPU流体粒子模拟 -->
		<title>Three.js WebGPU - 流体粒子计算模拟</title>
		<meta charset="utf-8">
		<!-- 视口设置：禁止用户缩放，确保WebGPU渲染的准确性 -->
		<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="example.css">
	</head>
	<body>

		<!-- 页面信息展示区域 -->
		<div id="info">
			<!-- Three.js Logo链接 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装器 -->
			<div class="title-wrapper">
				<!-- Three.js官网链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 当前项目标题 -->
				<span>流体粒子模拟系统</span>
			</div>

			<!-- 项目描述 -->
			<small>基于移动最小二乘物质点法(MLS-MPM)的粒子流体模拟，运行在WebGPU计算着色器中。</small>
			<!-- 技术细节补充 -->
			<small style="display:block; margin-top:20px;">
				使用64×64×64的计算网格，支持最多131,072个粒子，实时模拟流体物理效果。
			</small>
			<br />
			<!-- 操作提示 -->
			<small style="display:block; margin-top:40px;">
				鼠标拖动旋转视角，在流体区域移动鼠标可以产生交互效果。
			</small>
		</div>

		<!-- 模块导入映射配置 -->
		<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>

		<script type="module">

			// ============ 导入Three.js WebGPU核心模块 ============
			import * as THREE from 'three/webgpu';

			// ============ 导入Three.js着色器语言(TSL)函数 ============
			// TSL是Three.js的着色器语言，用于在JavaScript中编写GPU着色器代码
			// 以下导入的都是在计算着色器中使用的关键函数：
			// - Fn: 定义着色器函数
			// - If/Return: 条件判断和返回语句
			// - instancedArray: 创建实例化数组缓冲区
			// - instanceIndex: 获取当前实例索引
			// - uniform: 创建uniform变量
			// - attribute: 创建attribute变量
			// - 数据类型: uint, float, int, ivec3, vec3, vec4, mat3等
			// - 数学函数: clamp, max, pow, cross等
			// - 原子操作: atomicStore, atomicAdd, atomicLoad
			// - 控制流: Loop (用于GPU循环)
			// - 结构体: struct (定义数据结构)
			import { Fn, If, Return, instancedArray, instanceIndex, uniform, attribute, uint, float, clamp, struct, atomicStore, int, ivec3, array, vec3, atomicAdd, Loop, atomicLoad, max, pow, mat3, vec4, cross, step, storage } from 'three/tsl';

			// ============ 导入Three.js插件模块 ============
			import { Inspector } from 'three/addons/inspector/Inspector.js';  // 调试检查器
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';  // 轨道控制器
			import { UltraHDRLoader } from 'three/addons/loaders/UltraHDRLoader.js';  // HDR加载器
			import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';  // 几何体工具
			import WebGPU from 'three/addons/capabilities/WebGPU.js';  // WebGPU能力检测

			// ============ 全局变量声明 ============
			// 渲染相关
			let renderer;      // WebGPU渲染器实例
			let scene;         // 3D场景对象
			let camera;        // 相机对象
			let controls;      // 相机控制器
			
			// 时间管理
			const clock = new THREE.Clock();  // 用于获取精确的时间差

			// ============ 模拟参数常量定义 ============
			const maxParticles = 8192 * 16;      // 最大粒子数量: 131,072个粒子
			const gridSize1d = 64;               // 网格单维度大小: 64个单元
			const workgroupSize = 64;            // WebGPU工作组大小: 64个线程
			// 三维网格尺寸对象: 64×64×64的立方体网格
			const gridSize = new THREE.Vector3( gridSize1d, gridSize1d, gridSize1d );
			// 定点数乘数: 用于将浮点数转换为整数进行原子操作
			// 值1e7表示将浮点数乘以10,000,000后转为整数，保持7位小数精度
			const fixedPointMultiplier = 1e7;

			// ============ 计算着色器相关变量 ============
			// Uniform变量（可在CPU端设置，GPU端读取）
			let particleCountUniform;    // 当前粒子数量
			let stiffnessUniform;        // 刚度参数（控制流体压缩性）
			let restDensityUniform;      // 静止密度（影响浮力和压力）
			let dynamicViscosityUniform; // 动态粘度（控制流体粘性）
			let dtUniform;               // 时间步长（Δt）
			let gravityUniform;          // 重力加速度
			let gridSizeUniform;         // 网格尺寸
			
			// GPU缓冲区
			let particleBuffer;          // 粒子数据缓冲区（位置、速度、C矩阵）
			let cellBuffer;              // 网格单元缓冲区（使用原子操作）
			let cellBufferFloat;         // 网格单元浮点缓冲区（用于读取）
			
			// 计算着色器内核
			let clearGridKernel;         // 清空网格内核
			let p2g1Kernel;              // 粒子到网格传输内核（第一部分）
			let p2g2Kernel;              // 粒子到网格传输内核（第二部分）
			let updateGridKernel;        // 更新网格内核
			let g2pKernel;               // 网格到粒子传输内核
			let workgroupKernel;         // 工作组计算内核
			
			// 间接调度缓冲区（用于动态确定工作组数量）
			let p2g1KernelWorkgroupBuffer;
			let p2g2KernelWorkgroupBuffer;
			let g2pKernelWorkgroupBuffer;
			
			// 渲染网格
			let particleMesh;            // 粒子实例化网格对象
			
			// ============ 鼠标交互相关变量 ============
			const mouseCoord = new THREE.Vector3();          // 当前鼠标3D坐标
			const prevMouseCoord = new THREE.Vector3();      // 上一帧鼠标3D坐标
			let mouseRayOriginUniform;    // 鼠标射线起点（uniform）
			let mouseRayDirectionUniform; // 鼠标射线方向（uniform）
			let mouseForceUniform;        // 鼠标施加的力（uniform）

			// ============ WebGPU兼容性检查 ============
			// 检查浏览器是否支持WebGPU，如果不支持则显示错误信息
			if ( WebGPU.isAvailable() === false ) {
				document.body.appendChild( WebGPU.getErrorMessage() );
				throw new Error( '浏览器不支持WebGPU，请使用Chrome 113+、Edge 113+或Safari 16.4+' );
			}

			// ============ 模拟参数配置对象 ============
			// 这些参数可以通过GUI界面实时调整
			const params = {
				particleCount: 8192 * 4,  // 初始粒子数量: 32,768个
			};

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

			// ============ 主初始化函数 ============
			async function init() {
				console.log("开始初始化WebGPU流体模拟系统...");

				// ---------- 1. 初始化WebGPU渲染器 ----------
				// 创建WebGPU渲染器实例，开启抗锯齿
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				renderer.setPixelRatio( window.devicePixelRatio );  // 设置设备像素比
				renderer.setSize( window.innerWidth, window.innerHeight );  // 设置渲染尺寸
				renderer.toneMapping = THREE.ACESFilmicToneMapping;  // 设置ACES电影级色调映射
				renderer.toneMappingExposure = 1.35;  // 设置曝光值，影响整体亮度
				renderer.inspector = new Inspector();  // 创建调试检查器
				document.body.appendChild( renderer.domElement );  // 将canvas添加到DOM

				// ---------- 2. 创建3D场景 ----------
				scene = new THREE.Scene();
				console.log("3D场景创建完成");

				// ---------- 3. 创建并配置相机 ----------
				// 透视相机参数：40度视野，当前窗口宽高比，近裁剪面0.01，远裁剪面10
				camera = new THREE.PerspectiveCamera( 40, window.innerWidth / window.innerHeight, 0.01, 10 );
				camera.position.set( -1.3, 1.3, -1.3 );  // 设置相机初始位置
				console.log(`相机初始化完成，位置: ${camera.position.toArray()}`);

				// ---------- 4. 创建并配置轨道控制器 ----------
				// 允许用户通过鼠标控制相机旋转、缩放
				controls = new OrbitControls( camera, renderer.domElement );
				controls.minDistance = 1;  // 最小缩放距离
				controls.maxDistance = 3;  // 最大缩放距离
				controls.maxPolarAngle = Math.PI * 0.35;  // 最大俯仰角（限制上下旋转范围）
				controls.touches = { TWO: THREE.TOUCH.DOLLY_ROTATE };  // 触控双指操作设置
				console.log("轨道控制器配置完成");

				// ---------- 5. 加载HDR环境贴图 ----------
				// HDR贴图提供高质量的环境光照和反射
				console.log("开始加载HDR环境贴图...");
				const hdrLoader = new UltraHDRLoader().setPath( 'textures/equirectangular/' );
				const hdrTexture = await hdrLoader.loadAsync( 'royal_esplanade_2k.hdr.jpg' );
				hdrTexture.mapping = THREE.EquirectangularReflectionMapping;  // 设置等距柱状投影映射
				scene.background = hdrTexture;      // 设置场景背景
				scene.backgroundBlurriness = 0.5;   // 设置背景模糊度（增强景深效果）
				scene.environment = hdrTexture;     // 设置环境贴图（影响物体反射）
				console.log("HDR环境贴图加载完成");

				// ---------- 6. 设置粒子系统 ----------
				console.log("开始初始化粒子系统...");
				setupParticles();

				// ---------- 7. 创建GUI参数面板 ----------
				// 通过调试检查器创建参数控制面板
				const gui = renderer.inspector.createParameters( '模拟参数' );
				console.log("GUI参数面板创建完成");

				// ---------- 8. 计算间接调度缓冲区 ----------
				// 根据粒子数量和工作组大小计算需要的工作组数量
				// 公式：工作组数 = ceil(粒子数 / 工作组大小)
				const numWorkgroups = Math.ceil( params.particleCount / workgroupSize );
				console.log(`计算工作组数量: ${numWorkgroups} (粒子数: ${params.particleCount}, 工作组大小: ${workgroupSize})`);

				// 创建间接调度缓冲区，存储要调度的工作组数量
				// 这些缓冲区允许动态调整工作组数量，而不需要重新编译着色器
				p2g1KernelWorkgroupBuffer = new THREE.IndirectStorageBufferAttribute( 
					new Uint32Array( [ numWorkgroups, 1, 1 ] ), 1 
				);
				p2g2KernelWorkgroupBuffer = new THREE.IndirectStorageBufferAttribute( 
					new Uint32Array( [ numWorkgroups, 1, 1 ] ), 1 
				);
				g2pKernelWorkgroupBuffer = new THREE.IndirectStorageBufferAttribute( 
					new Uint32Array( [ numWorkgroups, 1, 1 ] ), 1 
				);
				console.log("间接调度缓冲区创建完成");

				// ---------- 9. 创建TSL存储对象 ----------
				// 将JavaScript缓冲区包装为TSL可访问的存储对象
				const p2g1WorkgroupStorage = storage( p2g1KernelWorkgroupBuffer, 'uint', 3 );
				const p2g2WorkgroupStorage = storage( p2g2KernelWorkgroupBuffer, 'uint', 3 );
				const g2pWorkgroupStorage = storage( g2pKernelWorkgroupBuffer, 'uint', 3 );

				// ---------- 10. 创建工作组计算内核 ----------
				// 这个内核在每一帧开始时运行，动态计算需要调度的工作组数量
				workgroupKernel = Fn( () => {
					// 计算公式：工作组数 = floor((粒子数 - 1) / 工作组大小) + 1
					const workgroupsToDispatch = ( particleCountUniform.sub( 1 ) ).div( workgroupSize ).add( 1 );
					// 将计算结果存储到间接调度缓冲区
					p2g1WorkgroupStorage.element( 0 ).assign( workgroupsToDispatch );
					p2g2WorkgroupStorage.element( 0 ).assign( workgroupsToDispatch );
					g2pWorkgroupStorage.element( 0 ).assign( workgroupsToDispatch );
				} )().compute( 1 );  // 只需要1个线程执行
				console.log("工作组计算内核创建完成");

				// ---------- 11. 添加GUI控件 ----------
				// 粒子数量滑块控件，允许用户实时调整粒子数量
				gui.add( params, 'particleCount', 4096, maxParticles, 4096 )
					.name( "粒子数量" )
					.onChange( value => {
						console.log(`粒子数量调整为: ${value}`);
						particleMesh.count = value;        // 更新渲染的实例数量
						particleCountUniform.value = value; // 更新uniform值
					} );

				// ---------- 12. 添加其他模拟参数控件 ----------
				// 注：这里可以添加更多参数控件，如刚度、密度、粘度等
				// 示例（当前被注释）：
				// gui.add(restDensityUniform, "value", 1.0, 3, 0.1).name("静止密度");

				// ---------- 13. 设置事件监听器 ----------
				window.addEventListener( 'resize', onWindowResize );  // 窗口大小变化事件
				controls.update();  // 更新控制器状态
				
				// ---------- 14. 启动渲染循环 ----------
				console.log("启动渲染循环...");
				renderer.setAnimationLoop( render );  // 使用WebGPU的动画循环
				console.log("初始化完成，模拟系统已启动！");
			}

			// ============ 设置模拟缓冲区函数 ============
			function setupBuffers() {
				console.log("开始设置模拟缓冲区...");

				// ---------- 1. 定义粒子数据结构 ----------
				// 每个粒子包含：
				// - position: vec3 - 位置向量 (x, y, z)
				// - velocity: vec3 - 速度向量 (vx, vy, vz)
				// - C: mat3 - 仿射动量矩阵（3×3矩阵，存储局部速度梯度信息）
				const particleStruct = struct( {
					position: { type: 'vec3' },
					velocity: { type: 'vec3' },
					C: { type: 'mat3' },
				} );
				
				// ---------- 2. 计算粒子结构内存大小 ----------
				// WebGPU内存对齐规则：
				// - vec3 占用 4 个 float（16字节对齐）
				// - mat3 占用 12 个 float（按列存储，每列4个float）
				// 总大小：vec3(4) + vec3(4) + mat3(12) = 20个float = 80字节
				const particleStructSize = 20;
				
				// ---------- 3. 创建粒子数据数组 ----------
				// 分配足够存储最大粒子数的Float32Array
				const particleArray = new Float32Array( maxParticles * particleStructSize );
				console.log(`粒子缓冲区分配: ${particleArray.length} 个浮点数, ${particleArray.length * 4} 字节`);

				// ---------- 4. 随机初始化粒子位置 ----------
				// 在0.1到0.9的范围内随机分布，避免粒子紧贴边界
				for ( let i = 0; i < maxParticles; i ++ ) {
					const baseIndex = i * particleStructSize;
					particleArray[ baseIndex ] = ( Math.random() * 0.8 + 0.1 );      // x: 0.1 ~ 0.9
					particleArray[ baseIndex + 1 ] = ( Math.random() * 0.8 + 0.1 );  // y: 0.1 ~ 0.9
					particleArray[ baseIndex + 2 ] = ( Math.random() * 0.8 + 0.1 );  // z: 0.1 ~ 0.9
					// 速度和C矩阵初始为0（由数组默认值保证）
				}
				console.log(`初始化了 ${maxParticles} 个粒子的初始位置`);

				// ---------- 5. 创建粒子缓冲区 ----------
				// 将JavaScript数组包装为GPU可访问的TSL实例化数组
				particleBuffer = instancedArray( particleArray, particleStruct );
				console.log("粒子缓冲区创建完成");

				// ---------- 6. 计算网格单元总数 ----------
				const cellCount = gridSize.x * gridSize.y * gridSize.z;
				console.log(`网格系统: ${gridSize.x}×${gridSize.y}×${gridSize.z} = ${cellCount} 个单元`);

				// ---------- 7. 定义网格单元数据结构 ----------
				// 每个网格单元包含：
				// - x, y, z: int - 三个方向的动量（使用定点数存储）
				// - mass: int - 质量（使用定点数存储）
				// atomic: true 表示这些字段支持原子操作，避免多线程数据竞争
				const cellStruct = struct( {
					x: { type: 'int', atomic: true },
					y: { type: 'int', atomic: true },
					z: { type: 'int', atomic: true },
					mass: { type: 'int', atomic: true },
				} );

				// ---------- 8. 创建网格缓冲区 ----------
				// 用于原子操作的网格缓冲区（存储定点数）
				cellBuffer = instancedArray( cellCount, cellStruct );
				// 用于读取的浮点网格缓冲区（存储最终计算出的速度和质量）
				cellBufferFloat = instancedArray( cellCount, 'vec4' );
				console.log("网格缓冲区创建完成");

				console.log("模拟缓冲区设置完成");
			}

			// ============ 设置Uniform变量函数 ============
			function setupUniforms() {
				console.log("开始设置Uniform变量...");

				// ---------- 1. 模拟参数Uniforms ----------
				gridSizeUniform = uniform( gridSize );  // 网格尺寸
				particleCountUniform = uniform( params.particleCount, 'uint' );  // 粒子数量（无符号整数）
				stiffnessUniform = uniform( 50 );  // 刚度参数：控制流体抵抗压缩的能力，值越大越难压缩
				restDensityUniform = uniform( 1.5 );  // 静止密度：流体在静止状态下的密度
				dynamicViscosityUniform = uniform( 0.1 );  // 动态粘度：控制流体内部摩擦，值越大越粘稠
				dtUniform = uniform( 1 / 60 );  // 时间步长：默认1/60秒（60FPS）
				gravityUniform = uniform( new THREE.Vector3( 0, - ( 9.81 * 9.81 ), 0 ) );  // 重力：Y轴负方向，放大了9.81倍以增强效果
				
				// ---------- 2. 鼠标交互Uniforms ----------
				mouseRayOriginUniform = uniform( new THREE.Vector3( 0, 0, 0 ) );      // 鼠标射线起点
				mouseRayDirectionUniform = uniform( new THREE.Vector3( 0, 0, 0 ) );   // 鼠标射线方向
				mouseForceUniform = uniform( new THREE.Vector3( 0, 0, 0 ) );         // 鼠标施加的力

				console.log("Uniform变量设置完成");
				console.log(`模拟参数: 刚度=${stiffnessUniform.value}, 密度=${restDensityUniform.value}, 粘度=${dynamicViscosityUniform.value}`);
			}

			// ============ 设置计算着色器函数 ============
			function setupComputeShaders() {
				console.log("开始设置MLS-MPM计算着色器...");
				console.log("MLS-MPM算法流程: 清空网格 → P2G(动量) → P2G(压力) → 更新网格 → G2P");

				// ---------- 辅助函数：定点数编码/解码 ----------
				// WebGPU只支持整数原子操作，因此需要将浮点数转换为定点数
				const encodeFixedPoint = ( f32 ) => {
					// 将浮点数乘以固定乘数后转为整数
					// 例如：0.1234567 × 10,000,000 = 1234567
					return int( f32.mul( fixedPointMultiplier ) );
				};

				const decodeFixedPoint = ( i32 ) => {
					// 将整数除以固定乘数得到原始浮点数
					// 例如：1234567 ÷ 10,000,000 = 0.1234567
					return float( i32 ).div( fixedPointMultiplier );
				};

				// ---------- 1. 清空网格内核 ----------
				// 在每个模拟步骤开始前，重置所有网格单元的数据
				const cellCount = gridSize.x * gridSize.y * gridSize.z;
				clearGridKernel = Fn( () => {
					// 边界检查：确保线程索引不超过网格单元总数
					If( instanceIndex.greaterThanEqual( uint( cellCount ) ), () => {
						Return();  // 超出范围则提前返回
					} );
					
					// 原子操作将网格单元的动量（x,y,z）和质量（mass）重置为0
					// atomicStore比直接赋值更安全，确保多线程写入的原子性
					atomicStore( cellBuffer.element( instanceIndex ).get( 'x' ), 0 );
					atomicStore( cellBuffer.element( instanceIndex ).get( 'y' ), 0 );
					atomicStore( cellBuffer.element( instanceIndex ).get( 'z' ), 0 );
					atomicStore( cellBuffer.element( instanceIndex ).get( 'mass' ), 0 );
				} )().compute( cellCount ).setName( 'clearGridKernel' );
				console.log("清空网格内核创建完成");

				// ---------- 2. 粒子到网格传输内核（第一部分） ----------
				// 主要任务：将粒子的动量（考虑仿射项）和质量传输到相邻网格
				p2g1Kernel = Fn( () => {
					// 边界检查：确保只处理有效的粒子
					If( instanceIndex.greaterThanEqual( particleCountUniform ), () => {
						Return();
					} );
					
					// 读取当前粒子的数据
					const particlePosition = particleBuffer.element( instanceIndex ).get( 'position' ).toConst( 'particlePosition' );
					const particleVelocity = particleBuffer.element( instanceIndex ).get( 'velocity' ).toConst( 'particleVelocity' );
					const C = particleBuffer.element( instanceIndex ).get( 'C' ).toConst( 'C' );

					// 将粒子位置从[0,1]范围映射到网格坐标[0, gridSize]
					const gridPosition = particlePosition.mul( gridSizeUniform ).toVar();
					
					// 计算基础网格索引（向下取整）
					const cellIndex = ivec3( gridPosition ).sub( 1 ).toConst( 'cellIndex' );
					
					// 计算与网格中心的相对偏移（-0.5到0.5范围）
					const cellDiff = gridPosition.fract().sub( 0.5 ).toConst( 'cellDiff' );
					
					// ---------- 三次B样条权重函数计算 ----------
					// MLS-MPM使用三次B样条进行粒子与网格的插值
					// 公式：
					// w0 = 0.5 * (0.5 - d)²  (左权重)
					// w1 = 0.75 - d²        (中权重)
					// w2 = 0.5 * (0.5 + d)²  (右权重)
					// 这三个权重分别对应粒子在网格中的左、中、右三个位置的影响
					const w0 = float( 0.5 ).mul( float( 0.5 ).sub( cellDiff ) ).mul( float( 0.5 ).sub( cellDiff ) );
					const w1 = float( 0.75 ).sub( cellDiff.mul( cellDiff ) );
					const w2 = float( 0.5 ).mul( float( 0.5 ).add( cellDiff ) ).mul( float( 0.5 ).add( cellDiff ) );
					
					// 将权重存入数组，方便后续三维循环访问
					const weights = array( [ w0, w1, w2 ] ).toConst( 'weights' );

					// ---------- 遍历3×3×3邻域网格 ----------
					// 每个粒子影响周围27个网格单元（三维各±1个单元）
					Loop( { start: 0, end: 3, type: 'int', name: 'gx', condition: '<' }, ( { gx } ) => {
						Loop( { start: 0, end: 3, type: 'int', name: 'gy', condition: '<' }, ( { gy } ) => {
							Loop( { start: 0, end: 3, type: 'int', name: 'gz', condition: '<' }, ( { gz } ) => {
								
								// 计算三维总权重：w_total = w_x * w_y * w_z
								const weight = weights.element( gx ).x.mul( weights.element( gy ).y ).mul( weights.element( gz ).z );
								
								// 计算当前邻域网格的坐标
								const cellX = cellIndex.add( ivec3( gx, gy, gz ) ).toConst();
								
								// 计算粒子到网格中心的距离向量 Δx
								const cellDist = vec3( cellX ).add( 0.5 ).sub( gridPosition ).toConst( 'cellDist' );
								
								// ---------- 计算仿射动量项 ----------
								// Q = C · Δx
								// C是仿射动量矩阵，表示粒子的局部速度梯度
								// 这一项考虑了粒子变形的速度场
								const Q = C.mul( cellDist );

								// 计算贡献到网格的质量和动量
								// 假设每个粒子质量为1.0，所以质量贡献就是权重本身
								const massContrib = weight;
								
								// 速度贡献：权重 × (粒子速度 + 仿射项Q)
								const velContrib = massContrib.mul( particleVelocity.add( Q ) ).toConst( 'velContrib' );
								
								// ---------- 计算网格单元索引 ----------
								// 三维索引转一维索引公式：index = x*(sizeY*sizeZ) + y*sizeZ + z
								const cellPtr = cellX.x.mul( int( gridSize.y * gridSize.z ) )
								                  .add( cellX.y.mul( int( gridSize.z ) ) )
								                  .add( cellX.z ).toConst();
								
								// 获取网格单元引用
								const cell = cellBuffer.element( cellPtr );

								// ---------- 原子操作累加到网格 ----------
								// 使用原子加法避免多线程竞争
								// 将浮点速度转换为定点数后累加
								atomicAdd( cell.get( 'x' ), encodeFixedPoint( velContrib.x ) );
								atomicAdd( cell.get( 'y' ), encodeFixedPoint( velContrib.y ) );
								atomicAdd( cell.get( 'z' ), encodeFixedPoint( velContrib.z ) );
								atomicAdd( cell.get( 'mass' ), encodeFixedPoint( massContrib ) );
							} );
						} );
					} );
				} )().compute( params.particleCount, [ workgroupSize, 1, 1 ] ).setName( 'p2g1Kernel' );
				console.log("P2G第一部分内核创建完成（动量传输）");

				// ---------- 3. 粒子到网格传输内核（第二部分） ----------
				// 主要任务：计算粒子密度、压力、应力，并将应力贡献传输到网格
				p2g2Kernel = Fn( () => {
					If( instanceIndex.greaterThanEqual( particleCountUniform ), () => {
						Return();
					} );
					
					// 读取粒子位置
					const particlePosition = particleBuffer.element( instanceIndex ).get( 'position' ).toConst( 'particlePosition' );
					const gridPosition = particlePosition.mul( gridSizeUniform ).toVar();

					// 计算网格索引和偏移（与p2g1相同）
					const cellIndex = ivec3( gridPosition ).sub( 1 ).toConst( 'cellIndex' );
					const cellDiff = gridPosition.fract().sub( 0.5 ).toConst( 'cellDiff' );
					
					// 计算三次B样条权重（与p2g1相同）
					const w0 = float( 0.5 ).mul( float( 0.5 ).sub( cellDiff ) ).mul( float( 0.5 ).sub( cellDiff ) );
					const w1 = float( 0.75 ).sub( cellDiff.mul( cellDiff ) );
					const w2 = float( 0.5 ).mul( float( 0.5 ).add( cellDiff ) ).mul( float( 0.5 ).add( cellDiff ) );
					const weights = array( [ w0, w1, w2 ] ).toConst( 'weights' );

					// ---------- 计算粒子密度 ----------
					// 密度 ρ = Σ (网格质量 × 权重)
					// 通过对相邻网格的质量进行加权求和得到
					const density = float( 0 ).toVar( 'density' );
					Loop( { start: 0, end: 3, type: 'int', name: 'gx', condition: '<' }, ( { gx } ) => {
						Loop( { start: 0, end: 3, type: 'int', name: 'gy', condition: '<' }, ( { gy } ) => {
							Loop( { start: 0, end: 3, type: 'int', name: 'gz', condition: '<' }, ( { gz } ) => {
								const weight = weights.element( gx ).x.mul( weights.element( gy ).y ).mul( weights.element( gz ).z );
								const cellX = cellIndex.add( ivec3( gx, gy, gz ) ).toConst();
								const cellPtr = cellX.x.mul( int( gridSize.y * gridSize.z ) )
								                  .add( cellX.y.mul( int( gridSize.z ) ) )
								                  .add( cellX.z ).toConst();
								const cell = cellBuffer.element( cellPtr );
								
								// 原子读取网格质量并解码为浮点数
								const mass = decodeFixedPoint( atomicLoad( cell.get( 'mass' ) ) );
								
								// 累加加权质量得到密度
								density.addAssign( mass.mul( weight ) );
							} );
						} );
					} );

					// ---------- 计算粒子体积 ----------
					// 体积 V = 1 / ρ （假设粒子质量为1）
					const volume = float( 1 ).div( density );
					
					// ---------- 计算压力 ----------
					// 状态方程：p = max(0, (ρ/ρ₀)^γ - 1) * k
					// 其中：
					// - ρ: 当前密度
					// - ρ₀: 静止密度（restDensityUniform）
					// - γ: 绝热指数，这里使用5（典型值）
					// - k: 刚度参数（stiffnessUniform）
					// 这个公式模拟了流体的可压缩性
					const pressure = max( 0.0, pow( density.div( restDensityUniform ), 5.0 ).sub( 1 ).mul( stiffnessUniform ) ).toConst( 'pressure' );
					
					// ---------- 计算应力张量 ----------
					// 初始化应力张量为负压力（压力是各向同性的）
					// σ = -pI，其中I是单位矩阵
					const stress = mat3( pressure.negate(), 0, 0, 
					                     0, pressure.negate(), 0, 
					                     0, 0, pressure.negate() ).toVar( 'stress' );
					
					// 读取粒子的仿射动量矩阵C（速度梯度）
					const dudv = particleBuffer.element( instanceIndex ).get( 'C' ).toConst( 'C' );

					// ---------- 添加粘性应力项 ----------
					// 应变率张量：ε = ∇u + (∇u)ᵀ = C + Cᵀ
					// 粘性应力：μ * ε，其中μ是动态粘度
					const strain = dudv.add( dudv.transpose() );
					stress.addAssign( strain.mul( dynamicViscosityUniform ) );
					
					// ---------- 计算动量更新项 ----------
					// 根据MPM公式：-4Δt * V * σ * w * Δx
					// 这个项表示应力对网格动量的贡献
					const eq16Term0 = volume.mul( -4 ).mul( stress ).mul( dtUniform );

					// ---------- 将应力贡献传输到网格 ----------
					Loop( { start: 0, end: 3, type: 'int', name: 'gx', condition: '<' }, ( { gx } ) => {
						Loop( { start: 0, end: 3, type: 'int', name: 'gy', condition: '<' }, ( { gy } ) => {
							Loop( { start: 0, end: 3, type: 'int', name: 'gz', condition: '<' }, ( { gz } ) => {
								const weight = weights.element( gx ).x.mul( weights.element( gy ).y ).mul( weights.element( gz ).z );
								const cellX = cellIndex.add( ivec3( gx, gy, gz ) ).toConst();
								const cellDist = vec3( cellX ).add( 0.5 ).sub( gridPosition ).toConst( 'cellDist' );
								
								// 计算应力贡献的动量：term0 * 权重 * Δx
								const momentum = eq16Term0.mul( weight ).mul( cellDist ).toConst( 'momentum' );

								const cellPtr = cellX.x.mul( int( gridSize.y * gridSize.z ) )
								                  .add( cellX.y.mul( int( gridSize.z ) ) )
								                  .add( cellX.z ).toConst();
								const cell = cellBuffer.element( cellPtr );
								
								// 原子操作累加应力贡献到网格
								atomicAdd( cell.get( 'x' ), encodeFixedPoint( momentum.x ) );
								atomicAdd( cell.get( 'y' ), encodeFixedPoint( momentum.y ) );
								atomicAdd( cell.get( 'z' ), encodeFixedPoint( momentum.z ) );
							} );
						} );
					} );
				} )().compute( params.particleCount, [ workgroupSize, 1, 1 ] ).setName( 'p2g2Kernel' );
				console.log("P2G第二部分内核创建完成（压力/应力传输）");

				// ---------- 4. 更新网格内核 ----------
				// 主要任务：计算网格最终速度，处理边界条件
				updateGridKernel = Fn( () => {
					If( instanceIndex.greaterThanEqual( uint( cellCount ) ), () => {
						Return();
					} );
					
					// 获取当前网格单元
					const cell = cellBuffer.element( instanceIndex );
					
					// 读取并解码网格质量
					const mass = decodeFixedPoint( atomicLoad( cell.get( 'mass' ) ) ).toConst();
					
					// 如果网格质量为0或负值，跳过处理（没有粒子贡献）
					If( mass.lessThanEqual( 0 ), () => {
						Return();
					} );

					// ---------- 计算网格速度 ----------
					// 速度 v = 动量 p / 质量 m
					const vx = decodeFixedPoint( atomicLoad( cell.get( 'x' ) ) ).div( mass ).toVar();
					const vy = decodeFixedPoint( atomicLoad( cell.get( 'y' ) ) ).div( mass ).toVar();
					const vz = decodeFixedPoint( atomicLoad( cell.get( 'z' ) ) ).div( mass ).toVar();

					// ---------- 从一维索引计算三维网格坐标 ----------
					// 公式推导：
					// index = x*(sizeY*sizeZ) + y*sizeZ + z
					// 因此：
					// x = floor(index / (sizeY*sizeZ))
					// y = floor((index % (sizeY*sizeZ)) / sizeZ)
					// z = index % sizeZ
					const x = int( instanceIndex ).div( int( gridSize.z * gridSize.y ) );
					const y = int( instanceIndex ).div( int( gridSize.z ) ).mod( int( gridSize.y ) );
					const z = int( instanceIndex ).mod( int( gridSize.z ) );
					
					// ---------- 处理边界条件 ----------
					// 在网格边界（最外层网格）处设置速度为0
					// 这模拟了固体墙壁，防止粒子逃出模拟区域
					
					// X方向边界：最左（x<1）和最右（x>gridSize.x-2）
					If( x.lessThan( int( 1 ) ).or( x.greaterThan( int( gridSize.x ).sub( int( 2 ) ) ) ), () => {
						vx.assign( 0 );
					} );
					
					// Y方向边界：最下（y<1）和最上（y>gridSize.y-2）
					If( y.lessThan( int( 1 ) ).or( y.greaterThan( int( gridSize.y ).sub( int( 2 ) ) ) ), () => {
						vy.assign( 0 );
					} );
					
					// Z方向边界：最前（z<1）和最后（z>gridSize.z-2）
					If( z.lessThan( int( 1 ) ).or( z.greaterThan( int( gridSize.z ).sub( int( 2 ) ) ) ), () => {
						vz.assign( 0 );
					} );

					// ---------- 存储最终结果到浮点缓冲区 ----------
					// 将计算出的速度和原始质量存储到浮点缓冲区
					// 使用vec4存储：xyz=速度，w=质量
					cellBufferFloat.element( instanceIndex ).assign( vec4( vx, vy, vz, mass ) );
				} )().compute( cellCount ).setName( 'updateGridKernel' );
				console.log("更新网格内核创建完成（边界条件处理）");

				// ---------- 辅助函数：圆角框约束 ----------
				// 将粒子位置限制在圆角框内，提供更自然的边界
				const clampToRoundedBox = ( pos, box, radius ) => {
					// 1. 将位置转换到以原点为中心（-0.5到0.5范围）
					const result = pos.sub( 0.5 ).toVar();
					
					// 2. 计算超出矩形框的部分
					// step(box, abs(result))：如果|result| > box则为1，否则为0
					// 这部分将超出矩形框的向量投影到框边界上
					const pp = step( box, result.abs() ).mul( result.add( box.negate().mul( result.sign() ) ) );
					
					// 3. 计算超出部分的长度
					const ppLen = pp.length().toVar();
					const dist = ppLen.sub( radius );
					
					// 4. 如果超出圆角半径，施加回复力
					// 将粒子向框内推，因子1.3增加一些过冲以模拟弹性
					If( dist.greaterThan( 0.0 ), () => {
						result.subAssign( pp.normalize().mul( dist ).mul( 1.3 ) );
					} );
					
					// 5. 转换回原始坐标空间（0到1范围）
					result.addAssign( 0.5 );
					return result;
				};

				// ---------- 5. 网格到粒子传输内核 ----------
				// 主要任务：从网格插值速度到粒子，更新粒子状态
				g2pKernel = Fn( () => {
					If( instanceIndex.greaterThanEqual( particleCountUniform ), () => {
						Return();
					} );
					
					// ---------- 读取并准备粒子数据 ----------
					const particlePosition = particleBuffer.element( instanceIndex ).get( 'position' ).toVar( 'particlePosition' );
					const gridPosition = particlePosition.mul( gridSizeUniform ).toVar();
					const particleVelocity = vec3( 0 ).toVar();  // 初始化粒子速度为0

					// 计算网格索引和偏移（与P2G相同）
					const cellIndex = ivec3( gridPosition ).sub( 1 ).toConst( 'cellIndex' );
					const cellDiff = gridPosition.fract().sub( 0.5 ).toConst( 'cellDiff' );

					// 计算三次B样条权重（与P2G相同）
					const w0 = float( 0.5 ).mul( float( 0.5 ).sub( cellDiff ) ).mul( float( 0.5 ).sub( cellDiff ) );
					const w1 = float( 0.75 ).sub( cellDiff.mul( cellDiff ) );
					const w2 = float( 0.5 ).mul( float( 0.5 ).add( cellDiff ) ).mul( float( 0.5 ).add( cellDiff ) );
					const weights = array( [ w0, w1, w2 ] ).toConst( 'weights' );

					// ---------- 计算新的仿射动量矩阵B ----------
					// B = Σ (权重 × 网格速度 × Δxᵀ)
					// 这个矩阵将在下一帧的P2G中用作C矩阵
					const B = mat3( 0 ).toVar( 'B' );
					
					// 遍历3×3×3邻域网格（与P2G对称）
					Loop( { start: 0, end: 3, type: 'int', name: 'gx', condition: '<' }, ( { gx } ) => {
						Loop( { start: 0, end: 3, type: 'int', name: 'gy', condition: '<' }, ( { gy } ) => {
							Loop( { start: 0, end: 3, type: 'int', name: 'gz', condition: '<' }, ( { gz } ) => {
								const weight = weights.element( gx ).x.mul( weights.element( gy ).y ).mul( weights.element( gz ).z );
								const cellX = cellIndex.add( ivec3( gx, gy, gz ) ).toConst();
								const cellDist = vec3( cellX ).add( 0.5 ).sub( gridPosition ).toConst( 'cellDist' );
								const cellPtr = cellX.x.mul( int( gridSize.y * gridSize.z ) )
								                  .add( cellX.y.mul( int( gridSize.z ) ) )
								                  .add( cellX.z ).toConst();

								// 从浮点缓冲区读取网格速度
								const weightedVelocity = cellBufferFloat.element( cellPtr ).xyz.mul( weight ).toConst( 'weightedVelocity' );
								
								// 更新B矩阵：B += 加权速度 × Δxᵀ
								// 外积运算：v ⊗ Δx
								const term = mat3(
									weightedVelocity.mul( cellDist.x ),  // 第一列：v * Δx_x
									weightedVelocity.mul( cellDist.y ),  // 第二列：v * Δx_y
									weightedVelocity.mul( cellDist.z )   // 第三列：v * Δx_z
								);
								B.addAssign( term );
								
								// 累加加权速度得到粒子速度
								// v_particle = Σ (权重 × v_grid)
								particleVelocity.addAssign( weightedVelocity );
							} );
						} );
					} );

					// ---------- 更新仿射动量矩阵 ----------
					// C_next = 4 * B
					// 系数4来自MLS-MPM的数学推导
					particleBuffer.element( instanceIndex ).get( 'C' ).assign( B.mul( 4 ) );

					// ---------- 添加重力加速度 ----------
					// v += g * Δt
					particleVelocity.addAssign( gravityUniform.mul( dtUniform ) );

					// ---------- 从网格空间缩放到世界空间 ----------
					// 之前的计算都在网格坐标下进行，现在缩放回[0,1]范围
					particleVelocity.divAssign( gridSizeUniform );

					// ---------- 鼠标交互力 ----------
					// 计算粒子到鼠标射线的垂直距离
					// 使用叉积长度公式：dist = |(p - o) × d| / |d|，这里假设|d|=1
					const dist = cross( mouseRayDirectionUniform, particlePosition.sub( mouseRayOriginUniform ) ).length();
					
					// 计算力的大小：随距离增加而减小
					// force = max(0, 1 - 3*dist)²
					// 距离越近，力越大；超过1/3距离则力为0
					const force = dist.mul( 3.00 ).oneMinus().max( 0.0 ).pow( 2 );
					
					// 应用鼠标力：v += mouseForce * force
					particleVelocity.addAssign( mouseForceUniform.mul( force ) );

					// ---------- 更新粒子位置 ----------
					// 前向欧拉积分：x += v * Δt
					particlePosition.addAssign( particleVelocity.mul( dtUniform ) );

					// ---------- 限制粒子位置 ----------
					// 确保粒子不超出最外层网格单元
					// 最小位置：1/gridSize（避免紧贴边界）
					// 最大位置：(gridSize-1)/gridSize（避免超出边界）
					const minPos = vec3( 1 ).div( gridSizeUniform );
					const maxPos = vec3( gridSize ).sub( 1 ).div( gridSizeUniform );
					particlePosition.assign( clamp( particlePosition, minPos, maxPos ) );

					// ---------- 圆角框约束 ----------
					// 创建一个内部的圆角框，提供更自然的边界效果
					// 内框尺寸：网格一半减去9个单元
					const innerBox = gridSizeUniform.mul( 0.5 ).sub( 9.0 ).div( gridSizeUniform ).toVar();
					
					// 内框圆角半径：6个网格单元
					const innerRadius = float( 6.0 ).div( gridSizeUniform.x );
					
					// 预测下一帧位置（使用2倍时间步长以获得更稳定的约束）
					const posNext = particlePosition.add( particleVelocity.mul( dtUniform ).mul( 2.0 ) ).toConst( 'posNext' );
					
					// 将预测位置约束到圆角框内
					const posNextClamped = clampToRoundedBox( posNext, innerBox, innerRadius );
					
					// 计算约束力并应用到速度
					// 这使粒子在接近边界时被推回
					particleVelocity.addAssign( posNextClamped.sub( posNext ) );

					/* 
					// 注释掉的简单边界约束代码
					// 替代方案：使用简单的弹簧力将粒子推回边界内
					const wallStiffness = 1.0;
					const xN = particlePosition.add( particleVelocity.mul( dtUniform ).mul( 2.0 ) ).toConst( 'xN' );
					const wallMin = vec3( 3 ).div(gridSizeUniform).toConst( 'wallMin' );
					const wallMax = vec3( gridSize ).sub( 3 ).div(gridSizeUniform).toConst( 'wallMax' );
					particleVelocity.addAssign( wallMin.sub( xN ).max( 0.0 ).mul( wallStiffness ) );
					particleVelocity.addAssign( wallMax.sub( xN ).min( 0.0 ).mul( wallStiffness ) );
					*/

					// ---------- 将速度缩放回网格空间 ----------
					// 为下一帧的P2G步骤准备，将速度转换回网格坐标
					particleVelocity.mulAssign( gridSizeUniform );

					// ---------- 更新粒子缓冲区 ----------
					// 将计算出的新位置和速度写回GPU缓冲区
					particleBuffer.element( instanceIndex ).get( 'position' ).assign( particlePosition );
					particleBuffer.element( instanceIndex ).get( 'velocity' ).assign( particleVelocity );
				} )().compute( params.particleCount, [ workgroupSize, 1, 1 ] ).setName( 'g2pKernel' );
				console.log("G2P内核创建完成（粒子状态更新）");

				console.log("所有计算着色器设置完成");
			}

			// ============ 设置粒子渲染网格函数 ============
			function setupMesh() {
				console.log("开始设置粒子渲染网格...");

				// ---------- 1. 创建基础几何体 ----------
				// 使用二十面体作为粒子形状（低多边形，适合实例化渲染）
				const baseGeometry = new THREE.IcosahedronGeometry( 0.008, 1 );
				baseGeometry.deleteAttribute( 'uv' );  // 删除UV坐标（不需要纹理）
				
				// 合并几何体顶点
				// 优化：将重复顶点合并，减少GPU处理的顶点数量
				const geometry = BufferGeometryUtils.mergeVertices( baseGeometry );
				console.log(`几何体优化完成: 顶点数 ${geometry.attributes.position.count}`);

				// ---------- 2. 创建材质 ----------
				// 使用MeshStandardNodeMaterial（基于物理的渲染材质）
				const material = new THREE.MeshStandardNodeMaterial( {
					color: '#0066FF',  // 粒子颜色：蓝色
					// 其他可选参数：
					// roughness: 0.1,      // 粗糙度（控制漫反射）
					// metalness: 0.0,      // 金属度（0=非金属，1=金属）
					// envMapIntensity: 1.0 // 环境贴图强度
				} );

				// ---------- 3. 设置位置节点 ----------
				// 关键：使用计算着色器中的粒子位置来定位每个实例
				// 这里创建了一个TSL函数，在顶点着色器中执行
				material.positionNode = Fn( () => {
					// instanceIndex: 当前实例的索引（0到particleCount-1）
					// particleBuffer.element(instanceIndex).get('position'): 从GPU缓冲区读取粒子位置
					// attribute('position'): 二十面体几何体的原始顶点位置
					// 最终位置 = 几何体局部坐标 + 粒子世界位置
					const particlePosition = particleBuffer.element( instanceIndex ).get( 'position' );
					return attribute( 'position' ).add( particlePosition );
				} )();
				console.log("粒子位置节点设置完成");

				// ---------- 4. 创建实例化网格 ----------
				// 使用实例化渲染：一个几何体 + 一个材质 + 多个实例
				// GPU高效绘制大量相同几何体
				particleMesh = new THREE.Mesh( geometry, material );
				particleMesh.count = params.particleCount;  // 设置实例数量
				particleMesh.position.set( -0.5, 0, -0.5 );  // 整体偏移，使粒子群居中
				particleMesh.frustumCulled = false;  // 禁用视锥体裁剪（粒子可能分布在视野外）
				scene.add( particleMesh );
				
				console.log(`粒子网格创建完成: ${params.particleCount} 个实例`);
			}

			// ============ 设置鼠标交互函数 ============
			function setupMouse() {
				console.log("设置鼠标交互系统...");

				// ---------- 1. 创建射线检测器 ----------
				const raycaster = new THREE.Raycaster();
				
				// ---------- 2. 创建射线检测平面 ----------
				// 平面方程：法向量(0,1,0)通过原点，即Y=0平面
				// 这个平面与粒子系统的底部对齐
				const raycastPlane = new THREE.Plane( new THREE.Vector3( 0, 1, 0 ) );

				// ---------- 3. 鼠标移动处理函数 ----------
				const onMove = ( event ) => {
					// 将鼠标屏幕坐标转换为归一化设备坐标（NDC）
					// NDC范围：x从-1（左）到1（右），y从-1（下）到1（上）
					const pointer = new THREE.Vector2( 
						( event.clientX / window.innerWidth ) * 2 - 1,      // x: [-1, 1]
						- ( event.clientY / window.innerHeight ) * 2 + 1   // y: [-1, 1]（反转Y轴）
					);
					
					// 从相机发射射线
					raycaster.setFromCamera( pointer, camera );
					
					// 调整射线原点以匹配粒子系统坐标
					// 粒子系统在[-0.5,0.5]范围，相机在[-1.3,1.3,-1.3]
					raycaster.ray.origin.x += 0.5;
					raycaster.ray.origin.z += 0.5;
					
					// 更新Uniform变量
					mouseRayOriginUniform.value.copy( raycaster.ray.origin );
					mouseRayDirectionUniform.value.copy( raycaster.ray.direction );
					
					// 计算射线与平面的交点（粒子系统的"地面"）
					raycaster.ray.intersectPlane( raycastPlane, mouseCoord );
					
					// 调试信息（可选）
					// console.log(`鼠标射线: 原点=${mouseRayOriginUniform.value.toArray()}, 方向=${mouseRayDirectionUniform.value.toArray()}`);
					// console.log(`地面交点: ${mouseCoord.toArray()}`);
				};

				// ---------- 4. 添加事件监听器 ----------
				renderer.domElement.addEventListener( 'pointermove', onMove );
				console.log("鼠标交互系统设置完成");
			}

			// ============ 设置完整粒子系统函数 ============
			function setupParticles() {
				console.log("========== 开始设置完整粒子系统 ==========");
				
				// 按顺序调用各个设置函数
				setupBuffers();        // 1. 设置GPU缓冲区
				setupUniforms();       // 2. 设置Uniform变量
				setupComputeShaders(); // 3. 设置计算着色器（MLS-MPM核心）
				setupMesh();           // 4. 设置渲染网格
				setupMouse();          // 5. 设置鼠标交互
				
				console.log("========== 粒子系统设置完成 ==========");
			}

			// ============ 窗口大小调整处理函数 ============
			function onWindowResize() {
				console.log(`窗口大小调整: ${window.innerWidth}×${window.innerHeight}`);
				
				// 1. 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 2. 更新相机投影矩阵（必须手动调用）
				camera.updateProjectionMatrix();
				
				// 3. 更新渲染器尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				console.log("相机和渲染器已更新");
			}

			// ============ 主渲染循环函数 ============
			async function render() {
				// ---------- 1. 计算时间步长 ----------
				// 使用clock.getDelta()获取上一帧到当前帧的时间差（秒）
				// 限制时间步长范围：最小0.00001秒，最大1/60秒（约16.67毫秒）
				// 限制最大步长防止模拟不稳定（如页面隐藏时deltaTime可能很大）
				const deltaTime = THREE.MathUtils.clamp( clock.getDelta(), 0.00001, 1 / 60 );
				dtUniform.value = deltaTime;  // 更新Uniform变量
				
				// 调试信息：显示当前帧率
				// const fps = 1 / deltaTime;
				// if (frameCount % 60 === 0) console.log(`FPS: ${fps.toFixed(1)}, 粒子数: ${particleMesh.count}`);

				// ---------- 2. 计算鼠标力 ----------
				// 鼠标力 = (当前鼠标位置 - 上一帧鼠标位置) × 2
				// 系数2用于增强交互效果
				mouseForceUniform.value.copy( mouseCoord ).sub( prevMouseCoord ).multiplyScalar( 2 );
				
				// 限制鼠标力大小，避免过大的力导致模拟不稳定
				const mouseForceLength = mouseForceUniform.value.length();
				if ( mouseForceLength > 0.3 ) {
					mouseForceUniform.value.multiplyScalar( 0.3 / mouseForceLength );
				}
				
				// 保存当前鼠标位置供下一帧使用
				prevMouseCoord.copy( mouseCoord );

				// ---------- 3. 执行计算着色器序列 ----------
				// MLS-MPM算法的五个核心步骤：
				
				// 步骤0：计算工作组数量（动态调整）
				renderer.compute( workgroupKernel );
				
				// 步骤1：清空网格缓冲区
				renderer.compute( clearGridKernel );
				
				// 步骤2：粒子到网格传输（动量部分）
				// 使用间接调度缓冲区确定工作组数量
				renderer.compute( p2g1Kernel, p2g1KernelWorkgroupBuffer );
				
				// 步骤3：粒子到网格传输（压力/应力部分）
				renderer.compute( p2g2Kernel, p2g2KernelWorkgroupBuffer );
				
				// 步骤4：更新网格（计算速度，处理边界）
				renderer.compute( updateGridKernel );
				
				// 步骤5：网格到粒子传输（更新粒子状态）
				renderer.compute( g2pKernel, g2pKernelWorkgroupBuffer );
				
				// 注意：以上步骤必须按顺序执行，因为每个步骤依赖于前一步的结果

				// ---------- 4. 渲染3D场景 ----------
				renderer.render( scene, camera );
				
				// 帧计数器（用于调试）
				// frameCount++;
			}

			// 全局帧计数器（调试用）
			// let frameCount = 0;

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