<!-- 代码功能与技术点详解
🎯 项目功能概述
这是一个基于Web的3D物理模拟演示，展示了使用Rapier.js物理引擎和Three.js图形库实现的动态地形高度场物理交互系统。主要功能包括：

核心功能
动态地形生成 - 使用数学函数生成有起伏的3D地形

物理模拟 - 物体受到重力影响，与地形发生碰撞

物体生成系统 - 自动生成随机形状、大小、颜色的物理对象

实时交互 - 用户可以通过鼠标控制视角观察场景

交互体验
物体从高处随机位置掉落，与地形碰撞后滚动、堆积

超过30个物体时自动清理掉落地形之外的物体

物理系统自动处理卡住的物体，确保模拟流畅

🛠 主要技术栈
技术	用途	版本/特点
Three.js	3D图形渲染	WebGL渲染、几何体生成、光照阴影
Rapier.js	物理引擎	WASM高性能、刚体动力学、碰撞检测
ES6 Modules	模块化开发	现代JavaScript模块系统
OrbitControls	相机控制	鼠标/触摸交互视角控制
📐 关键技术点详解
1. 地形生成技术
javascript
// 关键技术：正弦函数地形算法
const height = (Math.sin(radius * phaseMult) + 1) * 0.5 * hRange + minHeight;
算法原理：基于距离中心点的半径计算正弦波高度

参数控制：

phaseMult=12：控制地形波动频率

hRange=10：控制地形高度变化范围(-2到8)

terrainWidth/Depth=128：地形网格分辨率

2. 高度场物理系统
javascript
physics.addHeightfield(
  terrainMesh,        // Three.js网格
  terrainWidth - 1,   // 列数
  terrainDepth - 1,   // 行数
  heightData,         // 高度数据数组
  {x, y, z}          // 缩放因子
);
物理-图形同步：同一组高度数据用于渲染和物理碰撞

性能优化：静态高度场碰撞体，物理引擎优化处理

精度控制：Float32Array确保高度数据精度

3. 动态物理对象管理
javascript
// 物体生成策略
const maxNumObjects = 30;          // 性能限制
const objectTimePeriod = 3;        // 生成间隔
const objectSize = 3;              // 尺寸范围
const mass = objectSize * 5;       // 质量计算
const restitution = 0.3;           // 弹性系数
对象类型系统
类型	几何体	物理特性	应用场景
球体	SphereGeometry	各向同性碰撞	滚动测试
立方体	BoxGeometry	面碰撞检测	堆积测试
圆柱体	CylinderGeometry	复杂碰撞	稳定性测试
4. 物理异常处理机制
javascript
// 物理卡顿检测与修复
if (speed < 0.5) {  // 速度过低检测
  body.applyImpulse({ x: 0, y: -2.0, z: 0 }, true); // 施加冲量
}

// 物理体丢失恢复
if (!objThree.userData.physics) {
  physics.addMesh(objThree, mass, restitution); // 重新创建
}
5. 渲染与性能优化
光照系统
javascript
// 双光源配置
const ambientLight = new THREE.AmbientLight(0xbbbbbb);  // 环境光
const light = new THREE.DirectionalLight(0xffffff, 3); // 方向光

// 阴影优化配置
light.shadow.mapSize.x = 1024 * 2;  // 高分辨率阴影贴图
light.shadow.camera.near = dLight / 30; // 近裁剪面优化
性能监控
javascript
import Stats from 'three/addons/libs/stats.module.js';
// 实时显示FPS、渲染时间等指标
6. 内存管理与资源清理
javascript
// 自动清理策略
if (obj.position.y < terrainMinHeight - 10) {
  scene.remove(obj);              // 从场景移除
  dynamicObjects.splice(i, 1);    // 从数组移除
  // 注意：实际项目中应从物理世界同步移除
}
🔧 技术实现细节
坐标系统与缩放
世界坐标：地形尺寸100×100单位

网格坐标：128×128顶点

高度坐标：-2到8单位范围

相机位置：自适应地形高度

时间管理与动画循环
javascript
const clock = new THREE.Clock();  // 高精度计时器
const deltaTime = clock.getDelta(); // 帧间时间差
renderer.setAnimationLoop(animate); // 请求动画帧
异步加载与初始化
javascript
// 顺序初始化确保依赖关系
1. 生成高度数据 → 2. 初始化图形 → 3. 初始化物理 → 4. 启动动画
🚀 性能特征分析
优点
分层设计：图形与物理系统解耦

渐进加载：按需生成物体，避免初始卡顿

自动优化：物体数量限制、掉落物体清理

异常恢复：物理状态异常自动检测与修复 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面元数据设置 -->
		<!-- 页面标题：Rapier.js地形高度场物理模拟演示 -->
		<title>Rapier.js地形高度场物理模拟演示</title>
		<!-- 字符编码设置为UTF-8，支持多语言字符显示 -->
		<meta charset="utf-8">
		<!-- 
			视口设置，优化移动端显示：
			width=device-width: 宽度设置为设备宽度
			user-scalable=no: 禁止用户手动缩放
			minimum-scale=1.0: 最小缩放比例为1.0
			maximum-scale=1.0: 最大缩放比例为1.0
			确保页面在不同设备上显示一致
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 引入外部CSS样式表，用于页面基本样式 -->
		<link type="text/css" rel="stylesheet" href="main.css">
		<style>
			body {
				color: #333; /* 设置页面文字颜色为深灰色，提高可读性 */
			}
		</style>
	</head>
	<body>
		<!-- 
			Three.js渲染器画布容器：
			Three.js会将WebGL画布创建并插入到这个div中
			所有3D图形都将在该容器内渲染显示
		-->
		<div id="container"></div>
		<!-- 
			信息显示区域：
			用于显示页面标题或说明信息
			这里显示中文的演示标题
		-->
		<div id="info">Rapier.js地形高度场物理模拟演示 - 三维地形与动态物体交互</div>

		<!-- 
			ES6模块导入映射表：
			定义JavaScript模块的导入路径映射关系
			使得在代码中使用import语句时可以简写路径
			例如："three"模块将指向"../build/three.module.js"文件
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module"表示这是一个ES6模块
			模块内部的变量和函数默认具有模块作用域
			不会污染全局命名空间
		-->
		<script type="module">
			// ========== 模块导入区域 ==========
			// 导入Three.js核心库，* as THREE表示将所有导出内容作为THREE对象导入
			import * as THREE from 'three';
			// 导入性能监视器，用于显示帧率等性能指标
			import Stats from 'three/addons/libs/stats.module.js';
			// 导入轨道控制器，允许用户通过鼠标/触摸控制相机视角
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入Rapier物理引擎的Three.js集成模块
			import { RapierPhysics } from 'three/addons/physics/RapierPhysics.js';

			// ========== 地形高度场参数配置 ==========
			// 地形在世界空间中的实际宽度（单位：Three.js单位）
			const terrainWidthExtents = 100;
			// 地形在世界空间中的实际深度（单位：Three.js单位）
			const terrainDepthExtents = 100;
			// 地形网格的宽度顶点数（决定地形细节程度）
			const terrainWidth = 128;
			// 地形网格的深度顶点数（决定地形细节程度）
			const terrainDepth = 128;
			// 地形宽度的一半，用于计算中心点
			const terrainHalfWidth = terrainWidth / 2;
			// 地形深度的一半，用于计算中心点
			const terrainHalfDepth = terrainDepth / 2;
			// 地形的最大高度值（相对于基准平面的高度）
			const terrainMaxHeight = 8;
			// 地形的最小高度值（相对于基准平面的高度，可以为负值表示凹陷）
			const terrainMinHeight = - 2;

			// ========== 图形渲染相关变量声明 ==========
			// 容器DOM元素，Three.js渲染器将把画布插入到此元素中
			let container;
			// 性能监视器实例，用于显示FPS等性能信息
			let stats;
			// Three.js相机对象，定义观察3D场景的视角
			let camera;
			// Three.js场景对象，包含所有需要渲染的3D对象
			let scene;
			// Three.js渲染器对象，负责将3D场景渲染到2D画布
			let renderer;
			// 地形网格对象，是Three.js中地形几何体和材质的组合
			let terrainMesh;
			// Three.js时钟对象，用于计算动画帧之间的时间差
			const clock = new THREE.Clock();

			// ========== 物理引擎相关变量声明 ==========
			// Rapier物理引擎实例，管理物理世界和物理计算
			let physics;
			// 动态物体数组，存储所有具有物理属性的可移动物体
			const dynamicObjects = [];
			// 地形高度数据数组，存储每个顶点的高度值，用于地形生成和物理碰撞
			let heightData = null;

			// ========== 物体生成与时间管理变量 ==========
			// 累计时间（秒），从程序开始运行起计算
			let time = 0;
			// 物体生成的基本时间间隔（秒）
			const objectTimePeriod = 3;
			// 下一次生成物体的时间点
			let timeNextSpawn = time + objectTimePeriod;
			// 场景中允许存在的最大物体数量，避免性能下降
			const maxNumObjects = 30;

			// ========== 程序初始化入口 ==========
			// 调用主初始化函数，启动整个应用程序
			init();

			// ========== 异步初始化函数 ==========
			// async关键字表示此函数是异步函数，内部可以使用await等待异步操作完成
			async function init() {
				// 步骤1: 生成地形高度数据
				// 调用generateHeight函数，根据参数生成地形的高度值数组
				// 这个数组将同时用于图形渲染和物理碰撞检测
				heightData = generateHeight(terrainWidth, terrainDepth, terrainMinHeight, terrainMaxHeight);
				
				// 步骤2: 初始化图形渲染系统
				// 创建场景、相机、渲染器、灯光等图形渲染所需的所有组件
				initGraphics();
				
				// 步骤3: 异步初始化物理引擎系统
				// await关键字等待Rapier物理引擎异步加载和初始化完成
				// 物理引擎初始化可能需要加载WASM模块等异步操作
				await initPhysics();
				
				// 步骤4: 启动动画循环
				// 物理引擎初始化完成后，启动渲染循环
				// setAnimationLoop是Three.js提供的动画循环方法，每帧自动调用
				renderer.setAnimationLoop(animate);
			}

			// ========== 图形系统初始化函数 ==========
			// 负责创建和配置所有与图形渲染相关的Three.js组件
			function initGraphics() {
				// 获取HTML页面中的容器元素
				// 这个div将包含Three.js的WebGL渲染画布
				container = document.getElementById('container');
				
				// 创建WebGL渲染器实例
				// antialias: true 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer({ antialias: true });
				// 设置渲染器的像素比率，匹配设备像素比率
				// 在高DPI屏幕上可以获得更清晰的图像
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器大小与窗口大小一致
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 启用阴影映射功能
				// 允许物体投射和接收阴影，增加场景真实感
				renderer.shadowMap.enabled = true;
				// 将渲染器的canvas元素添加到页面容器中
				container.appendChild(renderer.domElement);

				// 初始化性能监视器
				// Stats.js是一个轻量级的性能监控库，显示FPS、渲染时间等信息
				stats = new Stats();
				// 设置性能监视器显示位置为绝对定位
				stats.domElement.style.position = 'absolute';
				// 设置性能监视器距离顶部0像素
				stats.domElement.style.top = '0px';
				// 将性能监视器添加到页面容器中
				container.appendChild(stats.domElement);

				// 创建透视相机
				// 参数说明：
				// 60 - 视场角（Field of View），单位度，影响视野广度
				// window.innerWidth / window.innerHeight - 宽高比，匹配窗口比例
				// 0.2 - 近裁剪平面，距离相机0.2单位以内的物体不渲染
				// 2000 - 远裁剪平面，距离相机2000单位以外的物体不渲染
				camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.2, 2000);
				
				// 创建Three.js场景
				// 场景是所有3D对象的容器，包含网格、灯光、相机等
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅蓝色
				// 0xbfd1e5是十六进制颜色值，对应RGB(191, 209, 229)
				scene.background = new THREE.Color(0xbfd1e5);

				// 计算相机初始位置
				// 相机Y轴位置：基于地形中心点高度 + 5个单位高度
				// heightData[terrainHalfWidth + terrainHalfDepth * terrainWidth] 获取地形中心点高度
				// 乘以高度范围得到实际高度，再加上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);

				// 初始化轨道控制器
				// 允许用户通过鼠标拖拽旋转视角，鼠标滚轮缩放，右键拖拽平移
				const controls = new OrbitControls(camera, renderer.domElement);
				// 禁用缩放功能（通过鼠标滚轮）
				// 这里设置为false，但可以通过其他方式实现缩放
				controls.enableZoom = false;

				// 创建地形几何体
				// 使用平面几何体作为地形基础，通过高度数据变形得到3D地形
				// PlaneGeometry参数：
				// 1. terrainWidthExtents - 平面宽度（世界单位）
				// 2. terrainDepthExtents - 平面深度（世界单位）
				// 3. terrainWidth - 1 - 宽度分段数（顶点数-1）
				// 4. terrainDepth - 1 - 深度分段数（顶点数-1）
				// 分段数决定地形网格的密度，影响地形细节和性能
				const geometry = new THREE.PlaneGeometry(
					terrainWidthExtents,
					terrainDepthExtents,
					terrainWidth - 1,
					terrainDepth - 1
				);
				// 将平面绕X轴旋转-90度（顺时针90度）
				// 默认的PlaneGeometry是垂直的平面，旋转后变成水平地面
				geometry.rotateX(-Math.PI / 2);

				// 获取几何体顶点位置数组
				// 这是一个Float32Array，包含所有顶点的x, y, z坐标
				// 每三个元素构成一个顶点的(x, y, z)坐标
				const vertices = geometry.attributes.position.array;

				// 将生成的高度数据应用到几何体顶点
				// 遍历所有顶点，修改它们的Y坐标（高度）
				// i - 高度数据索引，对应每个顶点
				// j - 顶点数组索引，每次增加3（x, y, z三个分量）
				// l - 顶点数组总长度
				for (let i = 0, j = 0, l = vertices.length; i < l; i++, j += 3) {
					// j+1 对应顶点的Y轴坐标（高度）
					// 将预生成的高度数据赋值给每个顶点的Y坐标
					vertices[j + 1] = heightData[i];
				}

				// 计算几何体顶点法线
				// 法线是垂直于表面的向量，用于光照计算
				// 修改顶点高度后需要重新计算法线，否则光照不正确
				geometry.computeVertexNormals();

				// 创建地形材质
				// MeshPhongMaterial是Phong光照模型的材质，支持高光反射
				// color: 0xC7C7C7 设置材质基础颜色为浅灰色
				const groundMaterial = new THREE.MeshPhongMaterial({ color: 0xC7C7C7 });
				
				// 创建地形网格对象
				// Mesh是Three.js中几何体和材质的组合，代表一个可渲染的3D对象
				terrainMesh = new THREE.Mesh(geometry, groundMaterial);
				// 设置地形可以接收其他物体投射的阴影
				terrainMesh.receiveShadow = true;
				// 设置地形可以投射阴影到其他物体上
				terrainMesh.castShadow = true;
				// 将地形网格添加到场景中
				scene.add(terrainMesh);

				// 加载地形纹理贴图
				// TextureLoader是Three.js的纹理加载器，用于加载图片作为纹理
				const textureLoader = new THREE.TextureLoader();
				// 异步加载网格纹理图片
				textureLoader.load('textures/grid.png', function(texture) {
					// 设置纹理在U方向（水平）的包裹方式为重复
					texture.wrapS = THREE.RepeatWrapping;
					// 设置纹理在V方向（垂直）的包裹方式为重复
					texture.wrapT = THREE.RepeatWrapping;
					// 设置纹理重复次数，匹配地形网格分段数
					// 使网格纹理覆盖整个地形表面
					texture.repeat.set(terrainWidth - 1, terrainDepth - 1);
					// 将纹理设置为地形材质的漫反射贴图
					groundMaterial.map = texture;
					// 标记材质需要更新，Three.js会在下一帧应用纹理
					groundMaterial.needsUpdate = true;
				});

				// 添加环境光
				// AmbientLight是环境光，均匀照亮场景中的所有物体
				// 没有方向性，不产生阴影，用于模拟间接光照
				// 0xbbbbbb 表示浅灰色环境光
				const ambientLight = new THREE.AmbientLight(0xbbbbbb);
				scene.add(ambientLight);

				// 添加方向光（主光源）
				// DirectionalLight是方向光，模拟太阳等远距离光源
				// 参数1: 0xffffff - 白光
				// 参数2: 3 - 光照强度，数值越大越亮
				const light = new THREE.DirectionalLight(0xffffff, 3);
				// 设置光源位置
				light.position.set(100, 100, 50);
				// 启用光源的阴影投射功能
				light.castShadow = true;
				
				// 配置阴影相机参数
				// 方向光的阴影是通过阴影相机（正交相机）渲染的
				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);
			}

			// ========== 窗口大小变化处理函数 ==========
			function onWindowResize() {
				// 更新相机的宽高比，匹配新的窗口尺寸比例
				camera.aspect = window.innerWidth / window.innerHeight;
				// 通知相机投影矩阵已更新，Three.js会重新计算投影矩阵
				camera.updateProjectionMatrix();
				// 更新渲染器大小，使其填充整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ========== 物理系统初始化函数 ==========
			// 异步函数，初始化Rapier物理引擎
			async function initPhysics() {
				// 初始化Rapier物理引擎
				// await等待物理引擎完全加载，可能包括WASM模块的加载和初始化
				physics = await RapierPhysics();

				// 将地形网格添加到物理世界作为静态碰撞体
				// addHeightfield函数将地形高度数据转换为物理引擎的高度场碰撞体
				// 参数详解：
				// 1. terrainMesh - Three.js地形网格对象
				// 2. terrainWidth - 1 - 高度场宽度（列数）
				// 3. terrainDepth - 1 - 高度场深度（行数）
				// 4. heightData - 高度数据数组，包含每个网格点的高度值
				// 5. {x: terrainWidthExtents, y: 1.0, z: terrainDepthExtents} - 缩放因子
				//    x: 地形宽度缩放
				//    y: 高度缩放（1.0表示使用原始高度值）
				//    z: 地形深度缩放
				physics.addHeightfield(
					terrainMesh,
					terrainWidth - 1,
					terrainDepth - 1,
					heightData,
					{ x: terrainWidthExtents, y: 1.0, z: terrainDepthExtents }
				);
				
				// 注意：动态物体的物理属性将在它们生成时通过physics.addMesh()添加
				// 这里只初始化了静态地形，动态物体在generateObject()函数中初始化
			}

			// ========== 地形高度数据生成函数 ==========
			// 生成用于地形网格的高度数据数组
			// 参数：
			// width - 地形宽度方向顶点数
			// depth - 地形深度方向顶点数
			// minHeight - 最小高度值
			// maxHeight - 最大高度值
			function generateHeight(width, depth, minHeight, maxHeight) {
				// 计算总顶点数（每个网格点一个高度值）
				const size = width * depth;
				// 创建Float32Array存储高度数据
				// Float32Array是32位浮点数数组，适合存储高度值
				const data = new Float32Array(size);
				// 计算高度范围（最大值 - 最小值）
				const hRange = maxHeight - minHeight;
				// 计算地形中心点在网格坐标系中的位置
				const w2 = width / 2;  // 宽度中心
				const d2 = depth / 2;   // 深度中心
				// 相位乘数，控制地形波动的频率
				// 值越大，地形波动越密集
				const phaseMult = 12;
				// 数据索引，从0开始递增
				let p = 0;

				// 双重循环遍历所有网格点
				// 外层循环：深度方向（j坐标）
				// 内层循环：宽度方向（i坐标）
				for (let j = 0; j < depth; j++) {
					for (let i = 0; i < width; i++) {
						// 计算当前点到地形中心的归一化距离（半径）
						// 使用欧几里得距离公式
						// (i - w2) / w2: 将i坐标归一化到[-1, 1]范围
						// (j - d2) / d2: 将j坐标归一化到[-1, 1]范围
						// Math.sqrt: 计算平方根，得到实际距离
						const radius = Math.sqrt(
							Math.pow((i - w2) / w2, 2.0) +
							Math.pow((j - d2) / d2, 2.0)
						);
						
						// 使用正弦函数生成高度值
						// 公式解析：
						// 1. radius * phaseMult: 将距离乘以相位乘数，控制波动频率
						// 2. Math.sin(...): 计算正弦值，范围[-1, 1]
						// 3. +1: 将正弦值范围变为[0, 2]
						// 4. * 0.5: 将范围变为[0, 1]
						// 5. * hRange: 缩放为实际高度范围
						// 6. + minHeight: 加上最小高度，确保最终值在[minHeight, maxHeight]范围内
						const height = (Math.sin(radius * phaseMult) + 1) * 0.5 * hRange + minHeight;
						
						// 将计算得到的高度值存入数组
						data[p] = height;
						// 递增索引，准备存储下一个高度值
						p++;
					}
				}

				// 返回生成的高度数据数组
				return data;
			}

			// ========== 动态物体生成函数 ==========
			// 在场景中生成一个具有物理属性的动态物体
			// 物体类型随机选择，从高处掉落，受重力影响
			function generateObject() {
				// 定义可生成的物体类型数量
				// 当前支持3种：球体、立方体、圆柱体
				// 圆锥体类型已注释掉，可能因为物理模拟问题暂时不用
				const numTypes = 3;
				// 随机选择物体类型
				// Math.random()生成[0, 1)的随机数
				// 乘以numTypes得到[0, numTypes)的随机数
				// Math.ceil向上取整，得到1, 2, 3中的随机整数
				const objectType = Math.ceil(Math.random() * numTypes);
				// 声明Three.js物体对象变量，初始为null
				let threeObject = null;
				// 物体基础尺寸参数，用于随机生成不同大小的物体
				const objectSize = 3;
				// 临时变量，用于存储几何体参数
				let radius, height;

				// 使用switch语句根据物体类型创建不同的几何体
				switch (objectType) {
					case 1: // 球体
						// 随机生成半径：基础半径1 + [0, objectSize]的随机值
						radius = 1 + Math.random() * objectSize;
						// 创建球体几何体
						// SphereGeometry参数：
						// radius - 球体半径
						// 20 - 宽度分段数（经线数），影响球体平滑度
						// 20 - 高度分段数（纬线数），影响球体平滑度
						threeObject = new THREE.Mesh(
							new THREE.SphereGeometry(radius, 20, 20),
							createObjectMaterial()  // 调用函数生成随机颜色的材质
						);
						break;
					
					case 2: // 立方体
						// 随机生成立方体三边尺寸
						// 每条边长度：基础长度1 + [0, objectSize]的随机值
						const sx = 1 + Math.random() * objectSize;
						const sy = 1 + Math.random() * objectSize;
						const sz = 1 + Math.random() * objectSize;
						// 创建立方体几何体
						// BoxGeometry参数：
						// sx, sy, sz - 立方体三个方向的尺寸
						// 1, 1, 1 - 每个方向的分段数，这里为1表示每个面不细分
						threeObject = new THREE.Mesh(
							new THREE.BoxGeometry(sx, sy, sz, 1, 1, 1),
							createObjectMaterial()
						);
						break;
					
					case 3: // 圆柱体
						// 随机生成圆柱体半径和高度
						radius = 1 + Math.random() * objectSize;
						height = 1 + Math.random() * objectSize;
						// 创建圆柱体几何体
						// CylinderGeometry参数：
						// radius, radius - 顶部半径和底部半径（相同则为圆柱体）
						// height - 圆柱体高度
						// 20 - 圆周方向分段数，影响圆柱体平滑度
						// 1 - 高度方向分段数
						threeObject = new THREE.Mesh(
							new THREE.CylinderGeometry(radius, radius, height, 20, 1),
							createObjectMaterial()
						);
						break;
					
					default: // 圆锥体（当前未使用）
						// 如果未来需要启用圆锥体，可以取消注释
						radius = 1 + Math.random() * objectSize;
						height = 2 + Math.random() * objectSize;
						threeObject = new THREE.Mesh(
							new THREE.ConeGeometry(radius, height, 20, 2),
							createObjectMaterial()
						);
						break;
				}

				// 设置物体的初始位置
				// 物体将从高处随机位置掉落
				threeObject.position.set(
					// X轴位置：在地形宽度范围内随机分布
					// (Math.random() - 0.5) 生成[-0.5, 0.5)的随机数
					// 乘以terrainWidth * 0.6，使物体分布在地形中央60%区域
					(Math.random() - 0.5) * terrainWidth * 0.6,
					
					// Y轴位置（高度）：确保物体从足够高的位置开始掉落
					// terrainMaxHeight - 地形最高点高度
					// + objectSize - 加上物体本身尺寸
					// + 15 - 额外增加15单位高度，确保物体从高处开始
					// + Math.random() * 5 - 添加0-5单位的随机高度变化
					terrainMaxHeight + objectSize + 15 + Math.random() * 5,
					
					// Z轴位置：在地形深度范围内随机分布
					// 与X轴类似，分布在地形中央60%区域
					(Math.random() - 0.5) * terrainDepth * 0.6
				);

				// 设置物体的物理属性
				// 质量：基于物体尺寸计算，尺寸越大质量越大
				const mass = objectSize * 5;
				// 弹性系数（恢复系数）：决定物体碰撞时的反弹程度
				// 0.3表示碰撞后保留30%的能量，有70%的能量损失
				// 值范围[0, 1]，0表示完全非弹性碰撞，1表示完全弹性碰撞
				const restitution = 0.3;

				// 步骤1: 将物体添加到Three.js场景中
				// 使物体在3D场景中可见
				scene.add(threeObject);

				// 步骤2: 为物体添加物理属性
				// physics.addMesh函数将Three.js网格转换为物理引擎的刚体
				// 参数：网格对象、质量、弹性系数
				physics.addMesh(threeObject, mass, restitution);

				// 步骤3: 将物体引用存储到动态物体数组中
				// 方便后续统一管理和清理
				dynamicObjects.push(threeObject);

				// 步骤4: 设置下次生成物体的时间点
				// 增加0.5秒延迟，避免物体生成过于密集
				timeNextSpawn = time + 0.5;

				// 设置物体的阴影属性
				// 使物体能够接收其他物体投射的阴影
				threeObject.receiveShadow = true;
				// 使物体能够向其他物体投射阴影
				threeObject.castShadow = true;
			}

			// ========== 物体材质生成函数 ==========
			// 创建具有随机颜色的物体材质
			function createObjectMaterial() {
				// 生成随机颜色值
				// 1 << 24 等于 2^24 = 16777216，表示24位颜色范围
				// Math.random() * (1 << 24) 生成[0, 16777216)的随机数
				// Math.floor向下取整，得到0到16777215之间的整数
				// 这个整数可以表示24位RGB颜色（每个颜色通道8位）
				const c = Math.floor(Math.random() * (1 << 24));
				// 创建Phong材质并设置随机颜色
				return new THREE.MeshPhongMaterial({ color: c });
			}

			// ========== 动画循环函数 ==========
			// 每一帧自动调用，驱动动画和物理模拟
			function animate() {
				// 调用渲染函数，更新场景状态并渲染
				render();
				// 更新性能监视器显示
				// 显示当前帧率(FPS)、渲染时间等性能指标
				stats.update();
			}

			// ========== 主渲染函数 ==========
			// 每一帧执行的逻辑，包括物体生成、物理更新、渲染
			function render() {
				// 获取上一帧到当前帧的时间差（秒）
				// 用于与时间相关的计算，确保动画速度与帧率无关
				const deltaTime = clock.getDelta();

				// 物体生成逻辑
				// 条件1: 当前动态物体数量小于最大允许数量
				// 条件2: 当前时间超过了下次生成物体的时间
				if (dynamicObjects.length < maxNumObjects && time > timeNextSpawn) {
					// 生成一个新的动态物体
					generateObject();
					// 注意：timeNextSpawn已经在generateObject()函数中更新
				}

				// 清理掉落地形之外的物体
				// 从数组末尾开始向前遍历，避免删除元素时索引错乱
				for (let i = dynamicObjects.length - 1; i >= 0; i--) {
					const obj = dynamicObjects[i];
					// 检查物体是否掉落得太低
					// terrainMinHeight - 10: 地形最低点以下10个单位
					// 如果物体低于这个高度，认为它已掉落出场景
					if (obj.position.y < terrainMinHeight - 10) {
						// 从Three.js场景中移除物体
						// 注意：这里只是从图形场景移除，物理引擎中可能还存在
						// 实际项目中应该同时从物理世界移除，避免内存泄漏
						scene.remove(obj);
						// 从动态物体数组中移除该物体的引用
						dynamicObjects.splice(i, 1);
					}
				}

				// 更新物理系统状态
				// 处理物理异常情况，如卡住的物体
				updatePhysics();
				
				// 使用Three.js渲染器渲染场景
				// 参数：场景对象、相机对象
				// 内部执行：遍历场景所有对象，计算光照、阴影、投影等，最终绘制到画布
				renderer.render(scene, camera);
				
				// 累加时间，用于物体生成计时
				time += deltaTime;
			}

			// ========== 物理系统更新函数 ==========
			// 处理物理引擎可能出现的异常情况
			// 例如：物体卡住、物理体休眠等问题
			function updatePhysics() {
				// 遍历所有动态物体
				for (let i = 0, il = dynamicObjects.length; i < il; i++) {
					const objThree = dynamicObjects[i];

					// 检查物体是否需要物理帮助
					// 条件：物体位置高于1.0（表示在高处，不应该静止不动）
					if (objThree.position.y > 1.0) {
						// 检查物体是否有物理数据
						// Three.js与Rapier物理引擎集成时，物理数据通常存储在userData.physics中
						if (objThree.userData && objThree.userData.physics && objThree.userData.physics.body) {
							// 获取物理体对象
							const body = objThree.userData.physics.body;

							// 唤醒物理体（如果处于休眠状态）
							// 物理引擎为了优化性能，会让静止的物体进入休眠状态
							// 当物体应该运动时，需要手动唤醒
							if (typeof body.wakeUp === 'function') {
								body.wakeUp();
							}

							// 检查物体的运动速度
							// 如果物体速度太慢，可能卡住了，需要施加外力
							if (typeof body.linvel === 'function') {
								// 获取物体的线速度向量
								const velocity = body.linvel();
								// 计算速度大小（标量）
								// 使用欧几里得距离公式计算速度向量的长度
								const speed = Math.sqrt(
									velocity.x * velocity.x +
									velocity.y * velocity.y +
									velocity.z * velocity.z
								);

								// 如果速度非常小（小于0.5单位/秒），认为物体可能卡住了
								if (speed < 0.5) {
									// 施加一个向下的冲量，帮助物体继续下落
									// 参数1: {x: 0, y: -2.0, z: 0} - 冲量向量，主要向下
									// 参数2: true - 是否唤醒物体（确保应用冲量时物体是激活状态）
									body.applyImpulse({ x: 0, y: -2.0, z: 0 }, true);
								}
							}
						} else {
							// 如果物体没有物理体但应该有（例如物理体意外丢失）
							// 重新为物体创建物理属性
							const mass = 5;            // 默认质量
							const restitution = 0.3;   // 默认弹性系数

							// 重新为物体添加物理属性
							physics.addMesh(objThree, mass, restitution);
						}
					}
				}
			}
		</script>
	</body>
</html>