<!-- Ammo.js地形高度场物理模拟演示 - 详细技术分析
🎯 整体功能概述
这是一个基于Web的3D物理模拟演示程序，使用Three.js进行3D图形渲染，结合Ammo.js（Bullet物理引擎的WebAssembly版本）实现真实的物理模拟。核心功能是展示物体在动态生成的地形上的物理行为，包括碰撞检测、重力模拟和运动物理。

🗺️ 主要功能模块
1. 地形系统
动态生成波浪形地形：使用正弦函数生成自然起伏的高度场

双精度高度数据：地形高度范围从-2到+8个单位

网格细分：128×128的高分辨率网格，确保地形平滑

2. 物理模拟系统
重力环境：Y轴方向-6单位的重力加速度

碰撞检测：支持地形与各种几何形状的精确碰撞

刚体动力学：质量、惯性、速度等物理属性的真实模拟

3. 物体生成系统
四种几何形状：球体、盒子、圆柱体、圆锥体

随机化参数：随机尺寸、随机颜色、随机位置

生成控制：每3秒生成一个新物体，最多30个物体

4. 可视化系统
逼真的光照：环境光+方向光的组合照明

实时阴影：支持物体投射和接收阴影

相机控制：轨道控制器实现鼠标交互控制

🔧 核心技术点详解
1. WebAssembly与Ammo.js集成
javascript
// 关键技术：WebAssembly内存管理与数据传递
ammoHeightData = Ammo._malloc(4 * terrainWidth * terrainDepth);
Ammo.HEAPF32[ammoHeightData + p2 >> 2] = heightData[p];
技术要点：

内存直接操作：通过Ammo._malloc()在WebAssembly堆内存中分配空间

高效数据传输：将JavaScript的Float32Array直接写入WebAssembly内存

指针运算：使用位运算>> 2进行高效的浮点数索引计算

2. 高度场物理形状创建
javascript
const heightFieldShape = new Ammo.btHeightfieldTerrainShape(
    terrainWidth, terrainDepth, ammoHeightData,
    heightScale, terrainMinHeight, terrainMaxHeight,
    upAxis, hdt, flipQuadEdges
);
参数详解：

PHY_FLOAT数据类型：使用32位浮点数保证精度

局部缩放映射：将顶点索引坐标映射到实际物理尺寸

碰撞边界设置：setMargin(0.05)避免穿透问题

3. 物理-图形同步机制
javascript
// 每帧执行的同步过程
physicsWorld.stepSimulation(deltaTime, 10);  // 1. 物理模拟
ms.getWorldTransform(transformAux1);        // 2. 获取物理变换
objThree.position.set(p.x(), p.y(), p.z());  // 3. 同步位置
objThree.quaternion.set(q.x(), q.y(), q.z(), q.w());  // 4. 同步旋转
关键设计：

分离式架构：物理引擎和图形引擎独立运行

状态同步：每帧从物理世界读取状态并更新3D对象

变换重用：使用transformAux1避免频繁创建变换对象

4. 地形网格生成算法
javascript
// 基于距离的正弦波地形生成
const radius = Math.sqrt(Math.pow((i - w2) / w2, 2.0) + 
                         Math.pow((j - d2) / d2, 2.0));
const height = (Math.sin(radius * phaseMult) + 1) * 0.5 * hRange + minHeight;
数学原理：

归一化距离：将网格坐标转换到[-1,1]范围

正弦函数变换：(sin(x)+1)*0.5将输出范围映射到[0,1]

径向对称：从中心向外扩散的波浪效果

5. 碰撞形状系统
几何形状	Three.js几何体	Ammo.js碰撞形状	关键参数
球体	SphereGeometry	btSphereShape	半径
盒子	BoxGeometry	btBoxShape	半长宽高向量
圆柱体	CylinderGeometry	btCylinderShape	(半径, 半高, 半径)
圆锥体	ConeGeometry	btConeShape	(半径, 高度)
技术特点：

惯性计算：shape.calculateLocalInertia(mass, localInertia)

碰撞边界：setMargin()提高碰撞检测稳定性

质量差异：根据物体尺寸自动计算质量

6. 渲染优化技术
javascript
// 1. 阴影优化
light.shadow.mapSize.x = 1024 * 2;  // 高分辨率阴影贴图
light.shadow.camera.near = dLight / 30;  // 近裁剪面优化

// 2. 抗锯齿
renderer = new THREE.WebGLRenderer({ antialias: true });

// 3. 设备像素比适配
renderer.setPixelRatio(window.devicePixelRatio);
🚀 性能优化策略
1. 广相碰撞检测
javascript
broadphase = new Ammo.btDbvtBroadphase();
动态边界体积层次树：快速筛选可能碰撞的对象对

减少精确检测：从O(n²)优化到近似O(n log n)

2. 分帧处理
物理模拟限制：stepSimulation(deltaTime, 10)限制最大子步数

物体生成间隔：每3秒生成一个物体，避免瞬时性能压力

3. 内存管理
WebAssembly内存重用：地形数据只分配一次

对象池模式：动态物体数组管理所有物理对象

4. 渲染优化
视锥体裁剪：相机近/远裁剪面设置优化

阴影相机优化：精确设置阴影投射范围

🔄 系统架构
text
┌─────────────────────────────────────────────────┐
│               HTML5文档结构                      │
│  ┌─────────────┐  ┌─────────────┐              │
│  │   容器DIV   │  │   信息DIV   │              │
│  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────┐
│            JavaScript ES6模块系统                │
│  ┌─────────────┐        ┌─────────────┐        │
│  │  Three.js   │←同步→│   Ammo.js    │        │
│  │  图形引擎   │        │  物理引擎   │        │
│  └─────────────┘        └─────────────┘        │
└─────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────┐
│               Web底层技术栈                      │
│  ┌─────────────┐  ┌─────────────┐              │
│  │   WebGL     │  │ WebAssembly │              │
│  │ (图形API)   │  │ (物理计算)  │              │
│  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────┘
🎨 视觉效果特性
1. 光照系统
环境光：整体环境照明（0xbbbbbb）

方向光：主光源模拟太阳（强度3.0）

阴影系统：PCF软阴影，2048×2048分辨率

2. 材质系统
地形材质：网格纹理贴图，平铺重复

物体材质：随机颜色的Phong材质

反射模型：Phong光照模型，支持高光

3. 相机系统
透视投影：60度视野，近裁剪面0.2，远裁剪面2000

轨道控制：鼠标左键旋转，右键平移

自动定位：相机初始位置基于地形高度

📊 性能监控
javascript
// Stats.js性能监控
stats = new Stats();
stats.domElement.style.position = 'absolute';
监控指标：

FPS（帧率）：实时显示渲染性能

MS（渲染时间）：每帧渲染耗时

MB（内存使用）：WebGL内存使用情况

🛠️ 配置参数总结
参数类别	参数名	默认值	作用
地形参数	terrainWidthExtents	100	地形物理宽度
terrainDepthExtents	100	地形物理深度
terrainWidth/Depth	128	网格分辨率
terrainMax/MinHeight	8/-2	高度范围
物理参数	重力	-6	Y轴重力加速度
碰撞边界	0.05	避免穿透的额外厚度
生成参数	objectTimePeriod	3	物体生成间隔(秒)
maxNumObjects	30	最大物体数量
渲染参数	阴影分辨率	2048×2048	阴影贴图大小
抗锯齿	true	启用抗锯齿
相机视野	60度	透视相机视野角度 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			HTML文档类型声明和语言设置
			lang="zh-CN" 表示文档使用简体中文
		-->
		<title>Ammo.js 物理引擎地形高度场演示 - 3D物理模拟示例</title>
		<!-- 
			字符编码设置为UTF-8，支持中文字符
			UTF-8是一种变长字节编码，可以表示Unicode中的所有字符
		-->
		<meta charset="utf-8">
		<!-- 
			视口元标签，用于移动端响应式设计：
			width=device-width: 视口宽度等于设备宽度
			user-scalable=no: 禁止用户缩放（保持固定比例）
			minimum-scale=1.0: 最小缩放比例为1倍
			maximum-scale=1.0: 最大缩放比例为1倍
			这样设置可以确保在移动设备上获得更好的体验
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 
			引入外部CSS样式表文件
			type="text/css" 指定样式表类型为CSS
			rel="stylesheet" 定义当前文档与被链接文档之间的关系为样式表
		-->
		<link type="text/css" rel="stylesheet" href="main.css">
		<!-- 
			内联CSS样式
			这里只设置了body的文字颜色，更多样式可能在外部的main.css文件中
		-->
		<style>
			body {
				color: #333; /* 设置深灰色文字，提高可读性 */
			}
		</style>
	</head>
	<body>
		<!-- 
			3D场景渲染容器
			Three.js会将WebGL渲染器的canvas元素插入到这个div中
			这个div是3D内容的承载容器
		-->
		<div id="container"></div>
		<!-- 
			信息显示区域，用于显示标题或说明文字
			id="info" 方便JavaScript通过DOM API获取这个元素
		-->
		<div id="info">Ammo.js 物理引擎地形高度场演示 - 使用WebAssembly的3D物理模拟</div>

		<!-- 
			引入Ammo.js物理引擎库（WebAssembly版本）
			Ammo.js是Bullet物理引擎的JavaScript/WebAssembly移植版本
			.wasm.js文件包含WebAssembly模块和JavaScript包装器
			这是同步加载，但实际使用在Ammo().then()中异步初始化
		-->
		<script src="jsm/libs/ammo.wasm.js"></script>

		<!-- 
			ES模块导入映射表（Import Maps）
			这是ES模块系统的一个特性，允许定义模块标识符的映射关系
			现代浏览器支持的模块解析机制
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module" 表示这是一个ES模块
			ES模块支持import/export语法，有自己的作用域
		-->
		<script type="module">

			// ==================== 模块导入部分 ====================
			// 导入Three.js核心库的所有导出内容
			// Three.js是一个流行的3D图形库，用于创建和显示3D计算机图形
			import * as THREE from 'three';

			// 导入性能监视器（Stats.js）
			// Stats.js是一个简单的JavaScript性能监视器
			// 可以显示帧率(FPS)、渲染时间等性能指标
			import Stats from 'three/addons/libs/stats.module.js';

			// 导入轨道控制器
			// OrbitControls允许用户用鼠标控制相机视角
			// 支持旋转、缩放、平移等操作
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ==================== 常量定义部分 ====================
			// 地形高度场参数配置
			// 这些参数控制地形的外观和物理属性
			const terrainWidthExtents = 100;  // 地形在X轴方向的物理范围（单位）
			const terrainDepthExtents = 100;  // 地形在Z轴方向的物理范围（单位）
			const terrainWidth = 128;         // 地形网格宽度方向的顶点数（分辨率）
			const terrainDepth = 128;         // 地形网格深度方向的顶点数（分辨率）
			const terrainHalfWidth = terrainWidth / 2;  // 地形宽度的一半，用于计算中心点
			const terrainHalfDepth = terrainDepth / 2;  // 地形深度的一半，用于计算中心点
			const terrainMaxHeight = 8;       // 地形的最大高度值（Y轴正方向）
			const terrainMinHeight = -2;      // 地形的最小高度值（Y轴负方向）
			// 注意：terrainMaxHeight和terrainMinHeight决定了地形的高度变化范围

			// ==================== 全局变量声明部分 ====================
			// 图形渲染相关变量（Three.js相关）
			let container;     // 指向HTML容器元素的引用（DOM元素）
			let stats;         // 性能监视器实例
			let camera;        // 3D相机对象（观察3D场景的视角）
			let scene;         // 3D场景对象（包含所有3D对象的容器）
			let renderer;      // WebGL渲染器（负责将3D场景渲染到2D画布）
			let terrainMesh;   // 地形网格对象（Three.js的Mesh对象）
			const clock = new THREE.Clock();  // Three.js的时钟对象，用于精确的时间计算
			// clock.getDelta()可以获取上一帧到当前帧的时间差（秒）

			// 物理引擎相关变量（Ammo.js相关）
			let collisionConfiguration;  // 碰撞配置对象，定义物理世界的碰撞检测配置
			let dispatcher;              // 碰撞分发器，管理碰撞检测过程
			let broadphase;              // 广相碰撞检测，快速筛选可能发生碰撞的对象对
			let solver;                  // 约束求解器，解决物理约束（如接触、关节）
			let physicsWorld;            // 物理世界，包含所有物理对象并执行物理模拟
			const dynamicObjects = [];   // 存储所有动态物体的Three.js对象数组
			// dynamicObjects数组用于在渲染循环中更新物体的位置和旋转
			let transformAux1;           // 辅助变换对象，用于在Ammo.js和Three.js之间转换坐标
			// 这是一个btTransform对象，用于临时存储物理变换数据

			// 高度数据相关变量
			let heightData = null;      // JavaScript中的高度数据数组（Float32Array类型）
			// 存储每个顶点的高度值，长度为terrainWidth * terrainDepth
			let ammoHeightData = null;  // Ammo.js堆内存中的高度数据指针
			// 这是Ammo.js分配的WebAssembly内存区域的指针，用于将高度数据传递给物理引擎

			// 物体生成计时相关变量
			let time = 0;                     // 累计时间（秒），从应用启动开始计算
			const objectTimePeriod = 3;       // 生成物体的时间间隔（秒）
			let timeNextSpawn = time + objectTimePeriod;  // 下一次生成物体的时间点
			const maxNumObjects = 30;         // 场景中允许的最大物体数量，避免性能问题

			// ==================== Ammo.js异步加载 ====================
			// Ammo()函数返回一个Promise，当Ammo.js库加载完成后解析
			Ammo().then(function (AmmoLib) {
				// AmmoLib参数是加载完成的Ammo.js库对象
				Ammo = AmmoLib;  // 将Ammo实例赋值给全局变量Ammo（假设Ammo已声明）
				// 注意：这里假设Ammo已经在全局作用域声明（如通过var Ammo;）
				init();           // 初始化整个应用程序
			});

			// ==================== 初始化主函数 ====================
			/**
			 * 应用程序主初始化函数
			 * 按顺序执行初始化步骤：
			 * 1. 生成地形高度数据
			 * 2. 初始化图形渲染系统
			 * 3. 初始化物理引擎系统
			 */
			function init() {
				// 生成地形高度数据
				// 调用generateHeight函数创建地形的高度场数据
				heightData = generateHeight(terrainWidth, terrainDepth, terrainMinHeight, terrainMaxHeight);
				
				// 初始化图形渲染系统（Three.js部分）
				initGraphics();
				
				// 初始化物理引擎系统（Ammo.js部分）
				initPhysics();
			}

			// ==================== 图形渲染初始化函数 ====================
			/**
			 * 初始化Three.js图形渲染系统
			 * 包括：渲染器、场景、相机、灯光、控制器、地形网格等
			 */
			function initGraphics() {
				// 获取HTML容器元素
				// document.getElementById()是DOM API，通过id获取元素
				container = document.getElementById('container');

				// ==================== 创建WebGL渲染器 ====================
				/**
				 * 创建Three.js的WebGL渲染器
				 * 参数说明：
				 * { antialias: true } - 启用抗锯齿，使边缘更平滑
				 */
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				// 设置设备像素比
				// window.devicePixelRatio获取设备的物理像素与CSS像素的比率
				// 在高DPI屏幕（如Retina屏幕）上，这个值可能大于1
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器大小为整个窗口
				// window.innerWidth和window.innerHeight获取浏览器视口内部尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// setAnimationLoop是Three.js r125+的API，替换了之前的requestAnimationFrame
				// animate函数将在每一帧被调用
				renderer.setAnimationLoop(animate);
				
				// 启用阴影映射
				// Three.js支持多种阴影类型，这里启用默认的阴影映射
				renderer.shadowMap.enabled = true;
				
				// 将渲染器的canvas元素添加到HTML容器中
				// renderer.domElement是WebGL渲染器创建的<canvas>元素
				container.appendChild(renderer.domElement);

				// ==================== 初始化性能监视器 ====================
				// 创建Stats.js性能监视器实例
				stats = new Stats();
				// 设置性能监视器的CSS样式
				// position: 'absolute' 使用绝对定位
				// top: '0px' 距离顶部0像素
				stats.domElement.style.position = 'absolute';
				stats.domElement.style.top = '0px';
				// 将性能监视器DOM元素添加到容器中
				container.appendChild(stats.domElement);

				// ==================== 创建3D相机 ====================
				/**
				 * 创建透视投影相机
				 * 参数说明：
				 * 1. 60 - 视野角度（Field of View），单位是度，垂直方向的角度
				 * 2. window.innerWidth / window.innerHeight - 宽高比（aspect ratio）
				 * 3. 0.2 - 近裁剪面（near clipping plane），比这个距离近的物体不会被渲染
				 * 4. 2000 - 远裁剪面（far clipping plane），比这个距离远的物体不会被渲染
				 */
				camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.2, 2000);

				// ==================== 创建3D场景 ====================
				// 创建Three.js场景对象，所有3D对象都添加到场景中
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅蓝色
				// 0xbfd1e5是十六进制颜色值，对应RGB(191, 209, 229)
				scene.background = new THREE.Color(0xbfd1e5);

				// ==================== 设置相机初始位置 ====================
				// 计算地形中心点的高度值
				// heightData[terrainHalfWidth + terrainHalfDepth * terrainWidth] 获取中心点的高度索引
				// 地形高度数据是按行存储的一维数组，索引计算：行索引*宽度 + 列索引
				// 乘以(terrainMaxHeight - terrainMinHeight)将归一化高度转换为实际高度
				// 最后加5，使相机位于地形上方5个单位的位置
				camera.position.y = heightData[terrainHalfWidth + terrainHalfDepth * terrainWidth] * (terrainMaxHeight - terrainMinHeight) + 5;
				
				// 设置相机在Z轴上的位置为地形深度范围的一半
				camera.position.z = terrainDepthExtents / 2;
				
				// 设置相机看向场景原点(0, 0, 0)
				camera.lookAt(0, 0, 0);

				// ==================== 创建轨道控制器 ====================
				/**
				 * 创建轨道控制器
				 * 参数说明：
				 * 1. camera - 要控制的相机对象
				 * 2. renderer.domElement - 事件监听的DOM元素（canvas）
				 * OrbitControls允许用户：
				 * - 鼠标左键拖动：旋转相机
				 * - 鼠标右键拖动：平移相机
				 * - 鼠标滚轮：缩放（这里禁用了）
				 */
				const controls = new OrbitControls(camera, renderer.domElement);
				// 禁用缩放功能
				controls.enableZoom = false;

				// ==================== 创建地形几何体 ====================
				/**
				 * 创建平面几何体作为地形的基础网格
				 * 参数说明：
				 * 1. terrainWidthExtents - 平面宽度（X轴方向）
				 * 2. terrainDepthExtents - 平面高度（Z轴方向，Three.js中平面默认在XZ平面）
				 * 3. terrainWidth - 1 - 宽度分段数（顶点数减1）
				 * 4. terrainDepth - 1 - 高度分段数（顶点数减1）
				 * 分段数决定了网格的细分程度，分段数越多，地形细节越丰富
				 */
				const geometry = new THREE.PlaneGeometry(
					terrainWidthExtents, 
					terrainDepthExtents, 
					terrainWidth - 1, 
					terrainDepth - 1
				);
				
				// 旋转几何体使其水平
				// 默认情况下，PlaneGeometry创建的是垂直的平面（在XY平面）
				// rotateX(-Math.PI / 2)将其绕X轴旋转-90度，使其在XZ平面（水平）
				geometry.rotateX(-Math.PI / 2);

				// ==================== 应用高度数据到几何体 ====================
				// 获取几何体的顶点位置数组
				// geometry.attributes.position.array 是Float32Array类型
				// 每3个元素表示一个顶点的(x, y, z)坐标
				const vertices = geometry.attributes.position.array;

				// 遍历所有顶点，应用高度数据
				// i: 高度数据数组的索引（0到terrainWidth*terrainDepth-1）
				// j: 顶点位置数组的索引（0到vertices.length-1，步长为3）
				// l: 顶点位置数组的长度
				for (let i = 0, j = 0, l = vertices.length; i < l; i++, j += 3) {
					// 将高度数据赋值给顶点的Y坐标
					// vertices[j]是X坐标，vertices[j+1]是Y坐标（高度），vertices[j+2]是Z坐标
					// 这里只修改Y坐标，X和Z坐标由PlaneGeometry自动生成
					vertices[j + 1] = heightData[i];
				}

				// 计算顶点法线
				// 顶点法线用于光照计算，决定每个顶点面对光线的方向
				// 修改顶点位置后需要重新计算法线
				geometry.computeVertexNormals();

				// ==================== 创建地形材质和网格 ====================
				// 创建Phong材质（一种基于物理的光照模型）
				// color: 0xC7C7C7 是浅灰色
				const groundMaterial = new THREE.MeshPhongMaterial({ color: 0xC7C7C7 });
				
				// 创建网格对象（Mesh）
				// Mesh是Three.js中基本的3D对象，包含几何体和材质
				terrainMesh = new THREE.Mesh(geometry, groundMaterial);
				
				// 设置地形接收阴影
				// 当其他物体在地形上投射阴影时，地形会显示这些阴影
				terrainMesh.receiveShadow = true;
				
				// 设置地形投射阴影
				// 地形本身也会向其他物体投射阴影
				terrainMesh.castShadow = true;
				
				// 将地形网格添加到场景中
				scene.add(terrainMesh);

				// ==================== 加载和应用纹理 ====================
				// 创建纹理加载器
				const textureLoader = new THREE.TextureLoader();
				
				// 异步加载网格纹理
				// 'textures/grid.png' 是纹理文件的相对路径
				textureLoader.load('textures/grid.png', function (texture) {
					// 设置纹理重复模式
					// THREE.RepeatWrapping允许纹理在U和V方向上重复
					texture.wrapS = THREE.RepeatWrapping;  // U方向（水平）
					texture.wrapT = THREE.RepeatWrapping;  // V方向（垂直）
					
					// 设置纹理重复次数
					// 根据地形网格的分段数设置重复，确保每个网格单元都有一个完整的纹理
					texture.repeat.set(terrainWidth - 1, terrainDepth - 1);
					
					// 将纹理设置为材质的漫反射贴图
					groundMaterial.map = texture;
					
					// 标记材质需要更新
					// Three.js中修改材质属性后需要手动通知渲染器
					groundMaterial.needsUpdate = true;
				});

				// ==================== 设置灯光 ====================
				// 创建环境光（Ambient Light）
				// 环境光均匀地照亮场景中的所有物体，没有方向性
				// 参数：颜色（0xbbbbbb是浅灰色）
				const ambientLight = new THREE.AmbientLight(0xbbbbbb);
				scene.add(ambientLight);

				// 创建平行光（Directional Light）
				// 平行光模拟远处的光源（如太阳），所有光线平行照射
				// 参数1：颜色（0xffffff是白色）
				// 参数2：强度（3.0是较高的强度值）
				const light = new THREE.DirectionalLight(0xffffff, 3);
				// 设置光源位置
				light.position.set(100, 100, 50);
				// 启用阴影投射
				light.castShadow = true;
				
				// 设置阴影相机参数
				// 平行光的阴影使用正交相机（OrthographicCamera）
				const dLight = 200;   // 阴影相机远裁剪面距离
				const sLight = dLight * 0.25;  // 阴影相机边界（左/右/上/下）
				
				// 设置阴影相机的边界
				light.shadow.camera.left = -sLight;    // 左边界
				light.shadow.camera.right = sLight;    // 右边界
				light.shadow.camera.top = sLight;      // 上边界
				light.shadow.camera.bottom = -sLight;  // 下边界
				
				// 设置阴影相机的近裁剪面和远裁剪面
				light.shadow.camera.near = dLight / 30;  // 近裁剪面
				light.shadow.camera.far = dLight;        // 远裁剪面
				
				// 设置阴影贴图分辨率
				// 更高的分辨率意味着更清晰的阴影，但性能开销更大
				light.shadow.mapSize.x = 1024 * 2;  // 宽度方向像素数
				light.shadow.mapSize.y = 1024 * 2;  // 高度方向像素数
				
				// 将平行光添加到场景中
				scene.add(light);

				// ==================== 窗口大小变化事件监听 ====================
				// 监听窗口大小变化事件
				// 当浏览器窗口大小改变时，调整相机和渲染器
				window.addEventListener('resize', onWindowResize);
			}

			// ==================== 窗口大小变化响应函数 ====================
			/**
			 * 处理浏览器窗口大小变化事件
			 * 确保3D场景正确适应新的窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 窗口大小改变后，需要更新相机的aspect属性
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵
				// 修改相机参数后，必须调用updateProjectionMatrix()更新内部矩阵
				camera.updateProjectionMatrix();
				
				// 更新渲染器大小
				// 将渲染器的画布大小调整为新的窗口尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ==================== 物理引擎初始化函数 ====================
			/**
			 * 初始化Ammo.js物理引擎系统
			 * 包括：创建物理世界、设置重力、创建地形物理体等
			 */
			function initPhysics() {
				// ==================== 创建物理引擎组件 ====================
				// 1. 创建碰撞配置
				// btDefaultCollisionConfiguration是Bullet物理引擎的默认碰撞配置
				// 它定义了碰撞检测算法、持久性管理器等
				collisionConfiguration = new Ammo.btDefaultCollisionConfiguration();
				
				// 2. 创建碰撞分发器
				// btCollisionDispatcher处理碰撞检测的具体逻辑
				// 它使用碰撞配置来确定如何检测和处理碰撞
				dispatcher = new Ammo.btCollisionDispatcher(collisionConfiguration);
				
				// 3. 创建广相碰撞检测器
				// btDbvtBroadphase使用动态边界体积层次树（Dynamic Bounding Volume Tree）
				// 快速筛选可能发生碰撞的对象对，减少精确碰撞检测的计算量
				broadphase = new Ammo.btDbvtBroadphase();
				
				// 4. 创建约束求解器
				// btSequentialImpulseConstraintSolver是顺序脉冲约束求解器
				// 用于解决物理约束（如接触约束、关节约束）
				solver = new Ammo.btSequentialImpulseConstraintSolver();
				
				// ==================== 创建物理世界 ====================
				/**
				 * 创建离散动力学世界
				 * 参数说明：
				 * 1. dispatcher - 碰撞分发器
				 * 2. broadphase - 广相碰撞检测器
				 * 3. solver - 约束求解器
				 * 4. collisionConfiguration - 碰撞配置
				 * btDiscreteDynamicsWorld是Bullet物理引擎的动力学世界实现
				 * 它管理所有物理对象并执行物理模拟
				 */
				physicsWorld = new Ammo.btDiscreteDynamicsWorld(dispatcher, broadphase, solver, collisionConfiguration);
				
				// 设置物理世界的重力
				// 参数：btVector3(0, -6, 0)表示Y轴负方向（向下）6个单位/秒²
				// 地球重力约为9.8，这里设为6以获得较好的视觉效果
				physicsWorld.setGravity(new Ammo.btVector3(0, -6, 0));

				// ==================== 创建地形物理体 ====================
				// 创建地形碰撞形状
				// createTerrainShape()函数返回一个btHeightfieldTerrainShape对象
				const groundShape = createTerrainShape();
				
				// 创建变换对象（描述位置和旋转）
				const groundTransform = new Ammo.btTransform();
				groundTransform.setIdentity();  // 设置为单位变换（无旋转，原点位置）
				
				// 设置地形物理体的位置
				// Bullet物理引擎会自动将高度场居中，所以需要手动偏移到正确位置
				// 将地形Y轴位置设置为最大高度和最小高度的平均值
				groundTransform.setOrigin(new Ammo.btVector3(0, (terrainMaxHeight + terrainMinHeight) / 2, 0));
				
				// 设置地形质量
				// 质量为0表示静态物体（不受力的影响，不移动）
				const groundMass = 0;
				
				// 创建局部惯性张量（对于静态物体为0）
				// 惯性张量描述物体绕不同轴旋转的难易程度
				const groundLocalInertia = new Ammo.btVector3(0, 0, 0);
				
				// 创建运动状态
				// btDefaultMotionState管理物体的位置和旋转状态
				const groundMotionState = new Ammo.btDefaultMotionState(groundTransform);
				
				// 创建刚体构造信息
				// btRigidBodyConstructionInfo包含创建刚体所需的所有参数
				const groundBody = new Ammo.btRigidBody(
					new Ammo.btRigidBodyConstructionInfo(
						groundMass,           // 质量
						groundMotionState,    // 运动状态
						groundShape,          // 碰撞形状
						groundLocalInertia    // 局部惯性张量
					)
				);
				
				// 将地形刚体添加到物理世界
				physicsWorld.addRigidBody(groundBody);

				// ==================== 初始化辅助变换对象 ====================
				// 创建辅助变换对象，用于在渲染循环中获取物理对象的位置和旋转
				transformAux1 = new Ammo.btTransform();
			}

			// ==================== 生成地形高度数据函数 ====================
			/**
			 * 生成地形高度场数据
			 * 使用正弦函数创建波浪形地形
			 * @param {number} width - 地形宽度方向的顶点数
			 * @param {number} depth - 地形深度方向的顶点数
			 * @param {number} minHeight - 地形最小高度值
			 * @param {number} maxHeight - 地形最大高度值
			 * @returns {Float32Array} - 包含所有顶点高度数据的浮点数组
			 */
			function generateHeight(width, depth, minHeight, maxHeight) {
				// 计算数据总大小（顶点总数）
				const size = width * depth;
				
				// 创建Float32Array存储高度数据
				// Float32Array是JavaScript的类型化数组，存储32位浮点数
				// 与WebAssembly内存兼容
				const data = new Float32Array(size);
				
				// 计算高度范围
				const hRange = maxHeight - minHeight;
				
				// 计算宽度和深度的一半（用于中心点计算）
				const w2 = width / 2;
				const d2 = depth / 2;
				
				// 相位乘数，控制正弦波的频率
				// 值越大，波浪越密集
				const phaseMult = 12;
				
				// 数据数组索引
				let p = 0;

				// 遍历所有顶点（按行遍历）
				for (let j = 0; j < depth; j++) {
					for (let i = 0; i < width; i++) {
						// 计算当前顶点到地形中心的归一化距离
						// 使用欧几里得距离公式，并归一化到[0,1]范围
						const radius = Math.sqrt(
							Math.pow((i - w2) / w2, 2.0) +  // X方向归一化距离
							Math.pow((j - d2) / d2, 2.0)   // Z方向归一化距离
						);

						// 使用正弦函数生成高度值
						// 1. Math.sin(radius * phaseMult)：计算正弦值，范围[-1, 1]
						// 2. +1：将范围转换为[0, 2]
						// 3. * 0.5：将范围转换为[0, 1]
						// 4. * hRange：将范围缩放到高度范围
						// 5. + minHeight：加上最小高度作为基准
						const height = (Math.sin(radius * phaseMult) + 1) * 0.5 * hRange + minHeight;
						
						// 将高度值存储到数组中
						data[p] = height;
						
						// 增加索引
						p++;
					}
				}
				
				// 返回生成的高度数据
				return data;
			}

			// ==================== 创建地形物理碰撞形状函数 ====================
			/**
			 * 创建地形高度场物理碰撞形状
			 * 将高度数据从JavaScript传递到Ammo.js的WebAssembly内存中
			 * @returns {Ammo.btHeightfieldTerrainShape} - 地形碰撞形状对象
			 */
			function createTerrainShape() {
				// ==================== 高度场参数设置 ====================
				const heightScale = 1;      // 高度缩放因子（使用PHY_FLOAT类型时被忽略）
				const upAxis = 1;           // 上方向轴（0:X轴, 1:Y轴, 2:Z轴）
				const hdt = 'PHY_FLOAT';    // 高度数据类型：'PHY_FLOAT'表示32位浮点数
				const flipQuadEdges = false; // 是否翻转四边形边缘（影响碰撞检测方向）

				// ==================== 在Ammo.js内存中分配空间 ====================
				/**
				 * 在Ammo.js的WebAssembly堆内存中分配空间
				 * Ammo._malloc()是Ammo.js的内存分配函数
				 * 参数：4 * terrainWidth * terrainDepth （字节数）
				 * 每个浮点数占4字节，所以总字节数 = 顶点数 * 4
				 */
				ammoHeightData = Ammo._malloc(4 * terrainWidth * terrainDepth);

				// ==================== 复制高度数据到Ammo.js内存 ====================
				// p: JavaScript高度数据数组的索引
				// p2: 字节偏移量（Ammo.js内存中的位置）
				let p = 0;
				let p2 = 0;

				// 遍历所有顶点
				for (let j = 0; j < terrainDepth; j++) {
					for (let i = 0; i < terrainWidth; i++) {
						// 将高度数据写入Ammo.js的WebAssembly内存
						// HEAPF32是Ammo.js暴露的Float32Array视图，指向WebAssembly内存
						// ammoHeightData + p2 >> 2：计算浮点数在HEAPF32中的索引
						// >> 2 相当于除以4（因为每个浮点数占4字节）
						// 这是指针算术，将字节偏移转换为浮点数索引
						Ammo.HEAPF32[ammoHeightData + p2 >> 2] = heightData[p];
						
						// 增加JavaScript数组索引
						p++;
						
						// 增加字节偏移量（每个浮点数4字节）
						p2 += 4;
					}
				}

				// ==================== 创建高度场碰撞形状 ====================
				/**
				 * 创建Bullet物理引擎的高度场地形碰撞形状
				 * btHeightfieldTerrainShape是Bullet中表示高度场的碰撞形状
				 * 参数说明：
				 * 1. terrainWidth - 高度场宽度（X方向的采样点数）
				 * 2. terrainDepth - 高度场深度（Z方向的采样点数）
				 * 3. ammoHeightData - 高度数据在WebAssembly内存中的指针
				 * 4. heightScale - 高度缩放因子（当使用浮点数时通常设为1）
				 * 5. terrainMinHeight - 最小高度值
				 * 6. terrainMaxHeight - 最大高度值
				 * 7. upAxis - 上方向轴（0:X, 1:Y, 2:Z）
				 * 8. hdt - 高度数据类型字符串
				 * 9. flipQuadEdges - 是否翻转四边形边缘
				 */
				const heightFieldShape = new Ammo.btHeightfieldTerrainShape(
					terrainWidth,
					terrainDepth,
					ammoHeightData,
					heightScale,
					terrainMinHeight,
					terrainMaxHeight,
					upAxis,
					hdt,
					flipQuadEdges
				);

				// ==================== 设置碰撞形状的局部缩放 ====================
				// 计算X和Z方向的缩放因子
				// 将顶点索引坐标映射到实际物理尺寸
				const scaleX = terrainWidthExtents / (terrainWidth - 1);  // X方向缩放
				const scaleZ = terrainDepthExtents / (terrainDepth - 1);  // Z方向缩放
				
				// 设置局部缩放
				// btVector3(scaleX, 1, scaleZ)表示：
				// X方向缩放scaleX倍，Y方向不缩放，Z方向缩放scaleZ倍
				heightFieldShape.setLocalScaling(new Ammo.btVector3(scaleX, 1, scaleZ));

				// ==================== 设置碰撞边界 ====================
				// 设置碰撞形状的边界（margin）
				// 边界是碰撞检测时使用的额外厚度，可以避免穿透问题
				heightFieldShape.setMargin(0.05);

				// 返回创建好的碰撞形状
				return heightFieldShape;
			}

			// ==================== 生成随机物理物体函数 ====================
			/**
			 * 生成随机形状的物理物体
			 * 随机选择球体、盒子、圆柱体或圆锥体
			 * 并创建对应的Three.js图形对象和Ammo.js物理体
			 */
			function generateObject() {
				// 物体类型数量
				const numTypes = 4;
				
				// 随机选择物体类型（1-4）
				// Math.random()返回[0,1)的随机数
				// Math.ceil()向上取整
				const objectType = Math.ceil(Math.random() * numTypes);

				// 声明变量
				let threeObject = null;  // Three.js网格对象
				let shape = null;        // Ammo.js碰撞形状
				
				// 物体尺寸参数
				const objectSize = 3;    // 基础尺寸范围
				const margin = 0.05;     // 碰撞边界

				// 临时变量
				let radius, height;

				// 根据物体类型创建不同的形状
				switch (objectType) {
					case 1:
						// ==================== 球体 ====================
						// 随机生成半径（1到1+objectSize之间）
						radius = 1 + Math.random() * objectSize;
						
						// 创建Three.js球体几何体
						// 参数：半径，宽度分段数，高度分段数
						threeObject = new THREE.Mesh(
							new THREE.SphereGeometry(radius, 20, 20), 
							createObjectMaterial()
						);
						
						// 创建Ammo.js球体碰撞形状
						shape = new Ammo.btSphereShape(radius);
						
						// 设置碰撞边界
						shape.setMargin(margin);
						break;
						
					case 2:
						// ==================== 盒子 ====================
						// 随机生成长宽高
						const sx = 1 + Math.random() * objectSize;
						const sy = 1 + Math.random() * objectSize;
						const sz = 1 + Math.random() * objectSize;
						
						// 创建Three.js盒子几何体
						// 参数：宽度，高度，深度，宽度分段，高度分段，深度分段
						threeObject = new THREE.Mesh(
							new THREE.BoxGeometry(sx, sy, sz, 1, 1, 1), 
							createObjectMaterial()
						);
						
						// 创建Ammo.js盒子碰撞形状
						// 注意：btBoxShape参数是半长宽高
						shape = new Ammo.btBoxShape(new Ammo.btVector3(sx * 0.5, sy * 0.5, sz * 0.5));
						
						// 设置碰撞边界
						shape.setMargin(margin);
						break;
						
					case 3:
						// ==================== 圆柱体 ====================
						// 随机生成半径和高度
						radius = 1 + Math.random() * objectSize;
						height = 1 + Math.random() * objectSize;
						
						// 创建Three.js圆柱体几何体
						// 参数：顶面半径，底面半径，高度，径向分段，高度分段
						threeObject = new THREE.Mesh(
							new THREE.CylinderGeometry(radius, radius, height, 20, 1), 
							createObjectMaterial()
						);
						
						// 创建Ammo.js圆柱体碰撞形状
						// 参数：btVector3(半径，半高，半径)
						shape = new Ammo.btCylinderShape(new Ammo.btVector3(radius, height * 0.5, radius));
						
						// 设置碰撞边界
						shape.setMargin(margin);
						break;
						
					default:
						// ==================== 圆锥体 ====================
						// 随机生成半径和高度
						radius = 1 + Math.random() * objectSize;
						height = 2 + Math.random() * objectSize;
						
						// 创建Three.js圆锥体几何体
						// 参数：底面半径，高度，径向分段，高度分段
						threeObject = new THREE.Mesh(
							new THREE.ConeGeometry(radius, height, 20, 2), 
							createObjectMaterial()
						);
						
						// 创建Ammo.js圆锥体碰撞形状
						// 参数：底面半径，高度
						shape = new Ammo.btConeShape(radius, height);
						break;
				}

				// ==================== 设置物体初始位置 ====================
				// 随机生成物体在地形上方的位置
				// X和Z坐标在[-terrainWidth*0.3, terrainWidth*0.3]范围内随机
				// Y坐标在地形最大高度上方，确保物体从空中掉落
				threeObject.position.set(
					(Math.random() - 0.5) * terrainWidth * 0.6,  // X坐标
					terrainMaxHeight + objectSize + 2,           // Y坐标（地形上方）
					(Math.random() - 0.5) * terrainDepth * 0.6   // Z坐标
				);

				// ==================== 创建物理刚体 ====================
				// 计算物体质量（与尺寸相关）
				const mass = objectSize * 5;
				
				// 创建局部惯性张量（初始为0）
				const localInertia = new Ammo.btVector3(0, 0, 0);
				
				// 计算局部惯性张量
				// 根据质量和碰撞形状计算物体的惯性
				shape.calculateLocalInertia(mass, localInertia);
				
				// 创建变换对象
				const transform = new Ammo.btTransform();
				transform.setIdentity();  // 设置为单位变换
				
				// 获取Three.js对象的位置
				const pos = threeObject.position;
				
				// 设置变换的原点（位置）
				transform.setOrigin(new Ammo.btVector3(pos.x, pos.y, pos.z));
				
				// 创建运动状态
				const motionState = new Ammo.btDefaultMotionState(transform);
				
				// 创建刚体构造信息
				const rbInfo = new Ammo.btRigidBodyConstructionInfo(
					mass,           // 质量
					motionState,    // 运动状态
					shape,          // 碰撞形状
					localInertia    // 局部惯性张量
				);
				
				// 创建刚体
				const body = new Ammo.btRigidBody(rbInfo);

				// ==================== 关联物理体和图形对象 ====================
				// 将物理体存储在Three.js对象的userData中
				// userData是Three.js对象的自定义数据存储属性
				threeObject.userData.physicsBody = body;

				// ==================== 设置阴影属性 ====================
				threeObject.receiveShadow = true;  // 物体接收阴影
				threeObject.castShadow = true;     // 物体投射阴影

				// ==================== 添加到场景和数组 ====================
				// 将Three.js对象添加到3D场景
				scene.add(threeObject);
				
				// 将Three.js对象添加到动态物体数组
				// 这个数组用于在渲染循环中更新所有物体的位置
				dynamicObjects.push(threeObject);
				
				// 将物理刚体添加到物理世界
				physicsWorld.addRigidBody(body);
			}

			// ==================== 创建随机颜色材质函数 ====================
			/**
			 * 创建随机颜色的Phong材质
			 * @returns {THREE.MeshPhongMaterial} - 随机颜色的Phong材质对象
			 */
			function createObjectMaterial() {
				// 生成24位随机颜色值
				// 1 << 24 等于 2^24 = 16777216（可能的颜色数）
				// Math.random() * (1 << 24) 生成[0, 16777216)的随机数
				// Math.floor()向下取整
				const c = Math.floor(Math.random() * (1 << 24));
				
				// 创建Phong材质并设置颜色
				return new THREE.MeshPhongMaterial({ color: c });
			}

			// ==================== 动画循环函数 ====================
			/**
			 * Three.js动画循环函数
			 * 由renderer.setAnimationLoop()自动调用每一帧
			 */
			function animate() {
				render();       // 渲染场景
				stats.update(); // 更新性能监视器显示
			}

			// ==================== 渲染函数 ====================
			/**
			 * 主渲染函数
			 * 每一帧执行：更新物理、生成物体、渲染场景
			 */
			function render() {
				// 获取上一帧到当前帧的时间差（秒）
				// deltaTime用于物理模拟的时间步长
				const deltaTime = clock.getDelta();

				// ==================== 物体生成逻辑 ====================
				// 检查是否需要生成新物体
				// 条件1：当前物体数量小于最大限制
				// 条件2：当前时间超过了下一个生成时间点
				if (dynamicObjects.length < maxNumObjects && time > timeNextSpawn) {
					generateObject();  // 生成新物体
					timeNextSpawn = time + objectTimePeriod;  // 更新下一个生成时间点
				}

				// ==================== 更新物理模拟 ====================
				// 执行物理模拟步进
				updatePhysics(deltaTime);

				// ==================== 渲染3D场景 ====================
				// 使用渲染器将3D场景绘制到画布上
				renderer.render(scene, camera);

				// ==================== 更新时间 ====================
				// 累计游戏时间
				time += deltaTime;
			}

			// ==================== 更新物理模拟函数 ====================
			/**
			 * 执行物理模拟步进并同步物理和图形对象
			 * @param {number} deltaTime - 时间步长（秒）
			 */
			function updatePhysics(deltaTime) {
				// ==================== 执行物理模拟步进 ====================
				/**
				 * 执行物理世界的时间步进
				 * 参数说明：
				 * 1. deltaTime - 时间步长（秒）
				 * 2. 10 - 最大子步数（maximum sub-steps）
				 * 
				 * 物理引擎内部会将deltaTime分割成多个更小的子步长
				 * 以确保模拟的稳定性和准确性
				 * 第二个参数限制最大子步数，避免性能问题
				 */
				physicsWorld.stepSimulation(deltaTime, 10);

				// ==================== 同步物理和图形对象 ====================
				// 遍历所有动态物体
				for (let i = 0, il = dynamicObjects.length; i < il; i++) {
					// 获取Three.js对象
					const objThree = dynamicObjects[i];
					
					// 从Three.js对象的userData中获取对应的物理体
					const objPhys = objThree.userData.physicsBody;
					
					// 获取物理体的运动状态
					const ms = objPhys.getMotionState();
					
					// 如果运动状态存在（物体不是静态的）
					if (ms) {
						// 从物理引擎获取世界变换
						// transformAux1是之前创建的辅助变换对象
						ms.getWorldTransform(transformAux1);
						
						// 获取位置（原点）
						const p = transformAux1.getOrigin();
						
						// 获取旋转（四元数）
						const q = transformAux1.getRotation();
						
						// 将物理位置同步到Three.js对象
						objThree.position.set(p.x(), p.y(), p.z());
						
						// 将物理旋转同步到Three.js对象
						// 四元数(w, x, y, z)用于表示3D旋转
						objThree.quaternion.set(q.x(), q.y(), q.z(), q.w());
					}
				}
			}

		</script>

	</body>
</html>