<!-- Three.js WebGPU 海洋场景演示 - 功能与技术分析
🎯 整体功能描述
这是一个基于Three.js WebGPU的实时3D海洋场景交互演示，模拟了一个动态的海天环境。主要功能包括：

核心功能
动态海洋渲染 - 具有波浪、反射、折射效果的逼真水面

大气天空系统 - 动态天空光照和大气散射效果

交互控制 - 用户可通过鼠标/触摸控制相机视角

实时参数调节 - 通过GUI面板调整场景参数

动态物体动画 - 一个上下浮动并旋转的立方体

响应式设计 - 自动适应不同屏幕尺寸

场景特点
时间周期变化 - 立方体随时间做周期性运动

环境反射 - 水面和物体反射天空环境

物理正确光照 - 基于物理的太阳位置计算

遮挡测试 - 演示物体被遮挡时的视觉效果

🔧 主要技术点
1. WebGPU渲染引擎
javascript
// 核心技术：新一代图形API
renderer = new THREE.WebGPURenderer();
优势：相比WebGL，WebGPU提供更低的CPU开销、更好的多线程支持

特性：直接访问现代GPU特性，支持计算着色器

兼容性：需要现代浏览器支持（Chrome 113+，Edge 113+）

2. 物理渲染系统（PBR）
javascript
// PBR材质配置
const material = new THREE.MeshStandardMaterial({ roughness: 0 });
renderer.toneMapping = THREE.ACESFilmicToneMapping;
基于物理的材质：MeshStandardMaterial模拟真实表面属性

色调映射：ACES Filmic算法处理HDR到LDR的转换

环境贴图：通过PMREMGenerator生成预滤波环境贴图

3. 水面着色器技术
javascript
// 水面特效配置
water = new WaterMesh(geometry, {
    waterNormals: waterNormals,
    distortionScale: 3.7
});
法线贴图：使用法线贴图模拟水面细节

Gerstner波浪：实现周期性波浪运动

菲涅尔效应：水面反射随视角变化

镜面反射：水面上的太阳光反射效果

4. 天空大气渲染
javascript
// 大气散射模型
sky.turbidity.value = 10;
sky.rayleigh.value = 2;
sky.mieCoefficient.value = 0.005;
瑞利散射：模拟空气分子散射（蓝色天空）

米氏散射：模拟较大颗粒散射（雾霾、光晕）

太阳位置计算：基于球面坐标的太阳定位

5. 模块化架构
javascript
// ES6模块导入
import * as THREE from 'three/webgpu';
import { WaterMesh } from 'three/addons/objects/WaterMesh.js';
ES6模块：现代JavaScript模块系统

Import Maps：浏览器原生模块解析

代码分离：核心库与附加组件分离

6. 交互控制系统
javascript
// 轨道控制器
controls = new OrbitControls(camera, renderer.domElement);
controls.maxPolarAngle = Math.PI * 0.495;
三轴控制：旋转、平移、缩放

约束限制：防止相机进入无效位置

平滑插值：动画缓动效果

7. 性能优化技术
javascript
// 渲染优化
renderer.setPixelRatio(window.devicePixelRatio);
pmremGenerator.fromScene(sceneEnv); // 预计算环境贴图
设备像素比适配：高DPI屏幕优化

离屏渲染：预计算环境贴图减少实时开销

几何体重用：水面几何体重复利用

8. 调试与开发工具
javascript
// 内置调试器
renderer.inspector = new Inspector();
const gui = renderer.inspector.createParameters('Settings');
实时参数调节：无需重新编译即可调整效果

场景检查：可视化查看场景结构

性能监控：帧率、内存等指标监控

🌊 水面特效技术详解
波浪算法
javascript
// 核心波浪计算（概念代码）
function computeWave(position, time) {
    // Gerstner波叠加
    const wave1 = amplitude1 * sin(dot(waveVector1, position) + time * frequency1);
    const wave2 = amplitude2 * sin(dot(waveVector2, position) + time * frequency2);
    return wave1 + wave2;
}
反射/折射计算
屏幕空间反射：计算水面反射图像

折射效果：模拟水下透视变形

法线扰动：基于法线贴图的表面细节

☀️ 天空系统技术详解
大气散射模型
text
I(θ) = I₀ * [exp(-β_R * L) + exp(-β_M * L)] * P(θ)
其中：
- β_R: 瑞利散射系数
- β_M: 米氏散射系数  
- L: 光路长度
- P(θ): 相位函数
太阳位置计算
javascript
// 球面坐标转换
const phi = degToRad(90 - elevation);    // 极角
const theta = degToRad(azimuth);         // 方位角
sun.setFromSphericalCoords(1, phi, theta);
🚀 高级特性
1. 异步初始化
javascript
renderer.init().then(updateSun); // WebGPU上下文异步准备
2. 响应式设计
javascript
window.addEventListener('resize', onWindowResize); // 自适应窗口大小
3. 动画系统
javascript
renderer.setAnimationLoop(render); // 基于requestAnimationFrame的动画循环
4. 资源管理
javascript
if (renderTarget !== undefined) renderTarget.dispose(); // GPU资源释放
📊 性能考量
GPU优化
纹理重复：水面法线贴图使用RepeatWrapping减少纹理内存

几何体简化：使用PlaneGeometry而非复杂网格

着色器优化：预计算复杂光照项

CPU优化
矩阵更新：仅在必要时更新投影矩阵

事件节流：resize事件合理处理

对象池：复用几何体和材质

🎨 视觉效果层次
视觉层次结构
text
1. 背景层：天空盒（最远）
2. 环境层：大气散射效果
3. 水面层：海洋表面（动态波浪）
4. 物体层：浮动立方体（前景）
5. 特效层：反射/折射效果
色彩系统
水色：0x001e0f（深蓝绿色）

天色：动态计算（基于太阳位置）

光照：白色太阳光 + 环境反射

🔍 扩展可能性
可扩展功能
天气系统：雨、雾、风暴效果

日夜循环：随时间变化的太阳位置

海洋生物：鱼群、海豚等动态元素

船只系统：可控制的船舶模型

水下世界：潜水视角和水下效果

技术增强
计算着色器：WebGPU特有，用于复杂物理模拟

光线追踪：WebGPU支持的光追特性

AI增强：机器学习优化的图像处理

多线程渲染：Worker中的并行处理

📱 跨平台适配
设备支持
桌面端：完整WebGPU功能

移动端：触摸交互适配

平板：响应式布局优化

浏览器兼容
主流程：WebGPU实现

降级方案：可回退到WebGL版本

渐进增强：根据设备能力启用特性 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：显示在浏览器标签页上的文本
			three.js: WebGL/WebGPU 3D图形库
			WebGPU: 新一代图形API，替代WebGL，提供更好的性能和功能
			ocean: 场景主题为海洋
		-->
		<title>Three.js WebGPU - 海洋场景演示</title>
		
		<!-- 
			字符编码设置：
			utf-8: 通用字符集编码，支持中文字符显示
			确保中文文本能正确显示，避免乱码问题
		-->
		<meta charset="utf-8">
		
		<!-- 
			视口(viewport)设置：
			width=device-width: 视口宽度等于设备宽度
			user-scalable=no: 禁止用户手动缩放页面
			minimum-scale=1.0: 最小缩放比例为1.0（100%）
			maximum-scale=1.0: 最大缩放比例为1.0（100%）
			这些设置确保3D场景在不同设备上保持固定比例，提供最佳视觉体验
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		
		<!-- 
			外部样式表链接：
			type="text/css": 指定链接文件为CSS样式表
			rel="stylesheet": 定义当前文档与链接资源的关系为样式表
			href="example.css": 外部样式表文件的路径
			该文件包含页面的布局、颜色、字体等样式定义
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>
		<!-- 
			3D场景渲染容器：
			id="container": 为元素分配唯一标识符，便于JavaScript获取引用
			此div将作为Three.js渲染器的挂载点，渲染器创建的canvas元素会插入到这里
			所有3D图形都将在这个容器内渲染显示
		-->
		<div id="container"></div>

		<!-- 
			页面信息展示区域：
			id="info": 用于存放场景信息、操作说明、版权信息等文本内容
			这个区域通常显示在3D场景之上，通过CSS定位实现层叠效果
		-->
		<div id="info">
			<!-- 
				Three.js官网链接（带logo样式）：
				href="https://threejs.org/": 链接到Three.js官方网站
				target="_blank": 在新标签页中打开链接
				rel="noopener": 安全设置，防止新打开的页面通过window.opener访问原页面
				class="logo-link": CSS类名，通常用于添加Three.js的logo背景图片
				点击此链接可以访问Three.js的官方网站获取更多信息和文档
			-->
			<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>标签是行内元素，用于对标题的一部分应用特殊样式
					"海洋场景"描述了当前3D场景的主题内容
				-->
				<span>海洋场景</span>
			</div>

			<!-- 
				场景功能说明：
				<small>标签表示旁注或小号文字，通常用于次要信息
				这里描述了场景的一个特殊功能：当立方体完全被遮挡时，平面会变成绿色
				这是一个遮挡测试的视觉反馈机制
			-->
			<small>
				这是一个动态海洋场景演示。蓝色立方体在绿色水面上方浮动和旋转。
				您可以：
				1. 使用鼠标左键拖动旋转视角
				2. 使用鼠标右键拖动平移视角  
				3. 使用鼠标滚轮缩放视角
				4. 右侧面板可以调整天空和海洋的参数
			</small>
		</div>

		<!-- 
			导入映射表(Import Map)：
			type="importmap": 定义模块导入的映射关系，是现代JavaScript模块系统的配置
			允许在模块导入语句中使用简短的模块标识符，而不是完整的URL路径
			这是在浏览器中支持ES6模块的一种配置方式
		-->
		<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语法
			这是现代Web开发中组织JavaScript代码的标准方式
		-->
		<script type="module">
			// ============= 模块导入部分 =============
			// 导入Three.js核心库的WebGPU版本
			// * as THREE: 将整个模块的所有导出内容作为一个名为THREE的对象导入
			// 这样我们可以通过THREE.Vector3、THREE.Scene等方式访问所有Three.js类
			import * as THREE from 'three/webgpu';

			// 导入调试检查器模块
			// Inspector: 一个可视化调试工具，允许在运行时检查和修改场景参数
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入控制模块
			// OrbitControls: 轨道控制器，提供鼠标/触摸交互控制相机围绕目标点旋转
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入特殊效果模块
			// WaterMesh: 专门的水面网格对象，包含复杂的水面着色器效果
			// SkyMesh: 天空网格对象，提供动态天空盒和大气散射效果
			import { WaterMesh } from 'three/addons/objects/WaterMesh.js';
			import { SkyMesh } from 'three/addons/objects/SkyMesh.js';

			// ============= 全局变量声明 =============
			// 这些变量在整个模块中共享，存储对Three.js核心对象和DOM元素的引用
			
			let container;        // 存储对id="container"的DOM元素的引用
			
			// Three.js核心三要素：
			let camera;          // 相机：定义观察者的视角和视锥体
			let scene;           // 场景：包含所有3D对象的容器
			let renderer;        // 渲染器：负责将3D场景绘制到2D画布上
			
			// 场景特定对象：
			let controls;        // 用户交互控制器
			let water;           // 水面对象
			let sun;             // 太阳位置向量（用于光照计算）
			let mesh;            // 动态立方体网格

			// 初始化函数调用 - 程序入口点
			init();

			/**
			 * 初始化函数 - 整个3D应用程序的启动入口
			 * 职责：
			 * 1. 创建并配置Three.js核心对象
			 * 2. 设置场景内容（几何体、材质、光照等）
			 * 3. 配置用户交互控件
			 * 4. 设置事件监听器
			 * 5. 启动渲染循环
			 * 
			 * 这是一个自包含函数，不接收参数也不返回值
			 * 所有设置都在函数内部完成，通过修改全局变量共享对象
			 */
			function init() {
				// 获取场景容器DOM元素
				// document.getElementById(): DOM API，通过id获取元素
				// 'container': 要查找的元素的id值
				container = document.getElementById('container');

				// ============= 1. 渲染器设置 =============
				// 创建WebGPURenderer实例
				// WebGPURenderer: Three.js的WebGPU后端渲染器，比WebGLRenderer更高效
				renderer = new THREE.WebGPURenderer();
				
				// 设置设备像素比
				// window.devicePixelRatio: 获取设备物理像素与CSS像素的比率
				// 在高DPI屏幕（如Retina显示屏）上，这个值通常大于1
				// 设置这个值可以确保3D图形在高分辨率屏幕上清晰显示
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个浏览器窗口大小
				// window.innerWidth/innerHeight: 浏览器视口的内部宽度和高度
				// 这样3D场景会填满整个浏览器窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// render: 每帧调用的渲染函数，驱动场景动画
				// setAnimationLoop是requestAnimationFrame的封装，用于游戏和动画
				renderer.setAnimationLoop(render);
				
				// 设置色调映射
				// toneMapping: 将HDR（高动态范围）颜色转换到LDR（低动态范围）显示器的过程
				// ACESFilmicToneMapping: 一种电影级色调映射算法，产生更自然的高光和阴影
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				
				// 设置色调映射曝光值
				// 0.5: 中等曝光值，1.0是默认值，小于1会降低整体亮度
				renderer.toneMappingExposure = 0.5;
				
				// 创建并附加调试检查器
				// Inspector: 一个GUI面板，允许实时调整场景参数
				renderer.inspector = new Inspector();
				
				// 将渲染器的canvas元素添加到页面容器中
				// renderer.domElement: 渲染器创建的<canvas>元素
				// appendChild(): DOM方法，将元素添加为容器的最后一个子元素
				container.appendChild(renderer.domElement);

				// ============= 2. 场景设置 =============
				// 创建场景对象
				// Scene: Three.js的场景图根容器，所有3D对象都添加到场景中
				// 场景管理对象层次结构、雾效、背景等
				scene = new THREE.Scene();

				// ============= 3. 相机设置 =============
				// 创建透视相机
				// PerspectiveCamera: 模拟人眼视角，有近大远小的透视效果
				// 参数详解：
				//   55: 视野角度(Field of View)，单位是度，决定相机能看到多宽的范围
				//      较小的值产生类似望远镜的效果，较大的值产生类似广角镜的效果
				//   window.innerWidth / window.innerHeight: 宽高比，确保图像不变形
				//   1: 近裁剪面，距离相机多近的物体开始显示
				//   20000: 远裁剪面，距离相机多远的物体不再显示
				camera = new THREE.PerspectiveCamera(
					55,
					window.innerWidth / window.innerHeight,
					1,
					20000
				);
				
				// 设置相机初始位置
				// position.set(x, y, z): 设置相机在世界坐标系中的位置
				// (30, 30, 100): 相机位于(30, 30, 100)坐标点
				// 这个位置提供了从斜上方俯瞰场景的视角
				camera.position.set(30, 30, 100);

				// ============= 4. 太阳光源初始化 =============
				// 创建三维向量表示太阳位置
				// Vector3: 表示三维空间中的点或方向
				// 太阳位置用于水面反射和天空光照计算
				sun = new THREE.Vector3();

				// ============= 5. 水面效果设置 =============
				// 创建水面几何体
				// PlaneGeometry: 平面几何体，由两个三角形组成的矩形
				// (10000, 10000): 宽度和高度，创建一个巨大的水面
				// 这么大的尺寸确保从任何角度都看不到水面的边界
				const waterGeometry = new THREE.PlaneGeometry(10000, 10000);
				
				// 创建纹理加载器
				// TextureLoader: 用于从图像文件加载纹理的实用工具
				const loader = new THREE.TextureLoader();
				
				// 加载水面法线贴图
				// 法线贴图：一种特殊的纹理，存储表面法线信息而非颜色
				// 用于在不增加几何体复杂度的情况下模拟复杂的表面细节
				// 'textures/waternormals.jpg': 法线贴图文件路径
				const waterNormals = loader.load('textures/waternormals.jpg');
				
				// 设置纹理重复模式
				// wrapS/wrapT: 分别控制纹理在U(水平)和V(垂直)方向上的包裹方式
				// RepeatWrapping: 纹理重复模式，纹理在超出[0,1]范围时重复
				// 这对于大面积的水面非常重要，可以避免纹理拉伸
				waterNormals.wrapS = waterNormals.wrapT = THREE.RepeatWrapping;

				// 创建水面网格对象
				// WaterMesh: 专门的水面对象，包含复杂的着色器代码
				// 参数：
				//   waterGeometry: 水面几何体
				//   配置对象：包含水面外观的各种参数
				water = new WaterMesh(
					waterGeometry,
					{
						waterNormals: waterNormals,       // 水波法线贴图，控制水面起伏细节
						sunDirection: new THREE.Vector3(), // 太阳方向向量（初始为零向量）
						sunColor: 0xffffff,               // 太阳光颜色（白色）
						waterColor: 0x001e0f,             // 水的基础颜色（深蓝绿色）
						distortionScale: 3.7              // 扭曲缩放系数，控制水波强度
					}
				);
				
				// 旋转水面使其水平
				// 默认的PlaneGeometry是垂直创建的，需要旋转90度使其水平
				// -Math.PI / 2: 负的90度（-π/2弧度），绕X轴旋转
				// 这样水面就变成了水平的平面
				water.rotation.x = -Math.PI / 2;
				
				// 将水面添加到场景中
				// scene.add(): 将对象添加到场景图中
				// 现在水面成为场景的一部分，会被渲染器绘制
				scene.add(water);

				// ============= 6. 天空盒设置 =============
				// 创建天空盒网格
				// SkyMesh: 专门的天空对象，模拟大气散射和天空颜色
				const sky = new SkyMesh();
				
				// 设置天空盒尺寸
				// scale.setScalar(10000): 在所有三个轴向上均匀缩放10000倍
				// 天空盒需要非常大，确保相机永远不会到达其边界
				sky.scale.setScalar(10000);
				
				// 将天空盒添加到场景
				scene.add(sky);

				// 设置天空盒的大气参数
				// 这些参数控制天空的视觉外观：
				sky.turbidity.value = 10;        // 浑浊度：空气中悬浮颗粒的浓度，影响天空颜色
				sky.rayleigh.value = 2;          // 瑞利散射：空气分子散射，影响天空蓝色程度
				sky.mieCoefficient.value = 0.005; // Mie散射系数：较大颗粒的散射，影响雾霾效果
				sky.mieDirectionalG.value = 0.8;   // Mie散射方向性：控制光晕效果

				// 太阳位置参数对象
				// 用于GUI控制太阳位置的两个角度参数：
				const parameters = {
					elevation: 2,   // 仰角：太阳相对于地平线的高度角度（0-90度）
					azimuth: 180    // 方位角：太阳相对于正北方向的水平角度（-180到180度）
				};

				// ============= 7. 环境贴图生成设置 =============
				// 创建预滤波环境贴图(PMREM)生成器
				// PMREMGenerator: 生成用于基于物理的渲染(PBR)的环境贴图
				// 它预先计算环境光照，提高实时渲染性能
				const pmremGenerator = new THREE.PMREMGenerator(renderer);
				
				// 创建专门用于生成环境贴图的场景
				// 这个场景只包含天空盒，用于生成环境反射贴图
				const sceneEnv = new THREE.Scene();
				
				// 声明渲染目标变量（稍后赋值）
				// 渲染目标(RenderTarget)是一个离屏缓冲区，用于存储渲染结果
				let renderTarget;

				/**
				 * 更新太阳位置并重新生成环境贴图
				 * 
				 * 这个函数执行以下操作：
				 * 1. 根据仰角和方位角计算太阳位置
				 * 2. 更新天空盒和水面的太阳方向
				 * 3. 生成新的环境贴图
				 * 4. 将环境贴图应用到场景
				 * 
				 * 当用户通过GUI调整太阳位置时，这个函数会被调用
				 */
				function updateSun() {
					// 将角度转换为弧度
					// 球面坐标系统：
					// phi: 极角（从正Z轴测量），这里用90-elevation计算
					// theta: 方位角（在XY平面内从正X轴测量）
					const phi = THREE.MathUtils.degToRad(90 - parameters.elevation);
					const theta = THREE.MathUtils.degToRad(parameters.azimuth);

					// 根据球面坐标设置太阳位置
					// setFromSphericalCoords(radius, phi, theta):
					//   radius: 半径（距离），设为1表示单位向量
					//   phi: 极角（前面计算的值）
					//   theta: 方位角（前面计算的值）
					sun.setFromSphericalCoords(1, phi, theta);

					// 更新天空盒的太阳位置
					// sky.sunPosition: 天空盒着色器中的uniform变量
					// value.copy(): 复制太阳位置向量到着色器uniform
					sky.sunPosition.value.copy(sun);
					
					// 更新水面的太阳方向并归一化
					// water.sunDirection: 水面着色器中的uniform变量
					// normalize(): 将向量转换为单位向量（长度为1）
					water.sunDirection.value.copy(sun).normalize();

					// 清理旧的渲染目标（如果存在）
					// 每次更新太阳位置都需要重新生成环境贴图
					// 旧的渲染目标需要手动释放GPU内存
					if (renderTarget !== undefined) {
						renderTarget.dispose();
					}

					// 将天空盒添加到环境场景
					// 这里暂时将天空盒从主场景移除，添加到专用环境场景
					sceneEnv.add(sky);
					
					// 从环境场景生成新的预滤波环境贴图
					// pmremGenerator.fromScene(): 从场景渲染并生成环境贴图
					// 这个过程包括渲染立方体贴图并进行预滤波处理
					renderTarget = pmremGenerator.fromScene(sceneEnv);
					
					// 将天空盒添加回主场景
					// 天空盒需要在主场景中显示，同时也用于环境光照计算
					scene.add(sky);

					// 将生成的环境贴图设置为主场景的环境贴图
					// scene.environment: 场景的环境贴图，影响所有PBR材质的反射
					// 这个贴图会被水面和立方体材质用来计算环境反射
					scene.environment = renderTarget.texture;
				}

				// 初始化渲染器后更新太阳位置
				// renderer.init(): WebGPURenderer的异步初始化方法
				// .then(): Promise链，初始化完成后执行回调
				// 确保WebGPU上下文就绪后再开始渲染
				renderer.init().then(updateSun);

				// ============= 8. 动态立方体设置 =============
				// 创建立方体几何体
				// BoxGeometry: 立方体几何体，由6个面组成
				// (30, 30, 30): 立方体的宽度、高度和深度（各30单位）
				const geometry = new THREE.BoxGeometry(30, 30, 30);
				
				// 创建立方体材质
				// MeshStandardMaterial: 基于物理的渲染(PBR)标准材质
				// { roughness: 0 }: 配置对象，粗糙度为0表示完全光滑
				// 完全光滑的材质会产生清晰的镜面反射
				const material = new THREE.MeshStandardMaterial({ roughness: 0 });
				
				// 创建立方体网格对象
				// Mesh: 网格是几何体和材质的组合，是Three.js中最基本的3D对象
				mesh = new THREE.Mesh(geometry, material);
				
				// 将立方体添加到场景
				scene.add(mesh);

				// ============= 9. 轨道控制器设置 =============
				// 创建轨道控制器
				// OrbitControls: 允许用户用鼠标控制相机围绕目标点旋转
				// 参数：
				//   camera: 要控制的相机对象
				//   renderer.domElement: 事件监听的目标DOM元素（canvas）
				controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置最大极角
				// maxPolarAngle: 相机可以向下旋转的最大角度
				// Math.PI * 0.495: 约89.1度，防止相机旋转到完全垂直向下
				// 这样可以避免相机翻转到水面以下（可能会产生奇怪的效果）
				controls.maxPolarAngle = Math.PI * 0.495;
				
				// 设置控制目标点
				// target.set(x, y, z): 设置相机围绕旋转的中心点
				// (0, 10, 0): 场景中心点上方10个单位，使视角稍微俯视
				controls.target.set(0, 10, 0);
				
				// 设置最小缩放距离
				// 防止相机过于接近目标点（可能穿入物体内部）
				controls.minDistance = 40.0;
				
				// 设置最大缩放距离
				// 防止相机过于远离场景
				controls.maxDistance = 200.0;
				
				// 更新控制器内部状态
				// 应用所有设置，确保控制器处于正确状态
				controls.update();

				// ============= 10. 调试GUI设置 =============
				// 创建主调试面板
				// renderer.inspector.createParameters(): 创建参数面板
				// 'Settings': 面板的标题
				const gui = renderer.inspector.createParameters('Settings');

				// 创建天空盒参数调节文件夹
				// gui.addFolder(): 创建可折叠的参数分组
				// 'Sky': 文件夹标签
				const folderSky = gui.addFolder('Sky');
				
				// 添加仰角控制滑块
				// folderSky.add(): 在文件夹中添加参数控制器
				// 参数详解：
				//   parameters: 要控制的对象
				//   'elevation': 要控制的属性名
				//   0: 最小值（太阳在地平线上）
				//   90: 最大值（太阳在头顶正上方）
				//   0.1: 步进值（每次调整的变化量）
				//   .onChange(updateSun): 值变化时的回调函数
				folderSky.add(parameters, 'elevation', 0, 90, 0.1).onChange(updateSun);
				
				// 添加方位角控制滑块
				folderSky.add(parameters, 'azimuth', -180, 180, 0.1).onChange(updateSun);

				// 创建水面参数调节文件夹
				const folderWater = gui.addFolder('Water');
				
				// 添加水面扭曲缩放控制
				// water.distortionScale: 水面着色器的uniform变量
				// .name('distortionScale'): 设置控制器在GUI中的显示名称
				folderWater.add(water.distortionScale, 'value', 0, 8, 0.1).name('distortionScale');
				
				// 添加水面波浪大小控制
				folderWater.add(water.size, 'value', 0.1, 10, 0.1).name('size');

				// ============= 11. 窗口大小变化监听 =============
				// 监听窗口大小变化事件
				// 'resize': 当浏览器窗口大小改变时触发的事件
				// onWindowResize: 事件处理函数
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 
			 * 当用户调整浏览器窗口大小时，这个函数会被自动调用
			 * 主要职责：
			 * 1. 更新相机的宽高比，防止图像拉伸
			 * 2. 更新渲染器尺寸，确保画布填满窗口
			 * 
			 * 这是一个重要的响应式设计功能，确保3D场景适应不同尺寸的显示设备
			 */
			function onWindowResize() {
				// 更新相机宽高比
				// camera.aspect: 相机的宽高比属性
				// window.innerWidth / window.innerHeight: 新的窗口宽高比
				// 如果不更新这个值，当窗口形状改变时，3D场景会被拉伸或压缩
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵
				// updateProjectionMatrix(): 重新计算相机的投影矩阵
				// 投影矩阵定义了3D空间如何映射到2D屏幕
				// 当相机参数改变后，必须调用此方法更新内部状态
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				// 确保canvas元素的大小与窗口大小一致
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 渲染循环函数 - 每帧调用一次
			 * 
			 * 这是Three.js动画循环的核心函数，负责：
			 * 1. 更新场景中物体的状态（位置、旋转等）
			 * 2. 渲染当前帧到屏幕
			 * 
			 * 函数由requestAnimationFrame驱动，通常每秒调用60次（60fps）
			 * 浏览器会在每次重绘前自动调用这个函数
			 * 
			 * @note 这个函数必须保持高效，因为它是每帧执行的
			 * 复杂的计算应该避免在这里进行，或者使用节流/防抖技术
			 */
			function render() {
				// 获取当前时间（秒为单位）
				// performance.now(): 高精度时间戳，返回从页面加载开始的毫秒数
				// * 0.001: 转换为秒，便于三角函数计算
				// 时间值用于创建平滑的动画效果
				const time = performance.now() * 0.001;

				// 更新立方体的垂直位置（Y轴）
				// Math.sin(time): 正弦函数，产生-1到1之间的周期性波动
				// * 20: 振幅，控制波动的大小范围
				// + 5: 垂直偏移，确保立方体不会沉入水面以下
				// 整体效果：立方体在水面上方上下浮动
				mesh.position.y = Math.sin(time) * 20 + 5;
				
				// 更新立方体的X轴旋转
				// time * 0.5: 旋转速度因子，控制旋转的快慢
				// 立方体会围绕X轴持续旋转
				mesh.rotation.x = time * 0.5;
				
				// 更新立方体的Z轴旋转
				// time * 0.51: 使用略微不同的速度因子
				// 这样会产生复杂的旋转轨迹，而不是简单的单一轴旋转
				mesh.rotation.z = time * 0.51;

				// 渲染场景
				// renderer.render(): 执行渲染管线的核心方法
				// 参数：
				//   scene: 要渲染的场景（包含所有3D对象）
				//   camera: 观察场景的视角
				// 这个方法会：
				//   1. 遍历场景图，收集所有可渲染对象
				//   2. 应用材质和着色器
				//   3. 执行光照计算
				//   4. 将3D几何体投影到2D屏幕
				//   5. 最终绘制到canvas元素上
				renderer.render(scene, camera);
			}
			// 注意：这里没有调用render()函数，因为它被设置为动画循环回调
			// renderer.setAnimationLoop(render)已经确保了它会自动被调用
		</script>
		<!-- 
			脚本结束，页面加载完成后会自动执行init()函数
			整个3D场景的创建和动画开始运行
		-->
	</body>
</html>