<!-- 代码功能描述
这是一个基于Three.js和Ammo.js物理引擎的3D物理模拟演示，主要功能是：

核心功能
物理场景模拟：创建了一个包含800个物理物体的3D场景（400个立方体 + 400个球体）

实时物理交互：所有物体都受到重力影响，会自然下落、相互碰撞和堆积

动态物理刺激：每16.67毫秒随机将两个物体"抛到"空中，观察其下落和碰撞效果

交互式观察：用户可以通过鼠标控制摄像机，从任意角度观察物理模拟过程

视觉效果
物体具有随机颜色，视觉上易于区分

真实的阴影效果：物体投射阴影到地面

柔和的光照系统：环境光 + 方向光组合

简洁的灰色背景，突出物理模拟效果

主要技术点
1. 实例化渲染技术（核心优化）
javascript
// 创建包含400个实例的网格
boxes = new THREE.InstancedMesh(geometryBox, material, 400);
boxes.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
原理：使用单个Draw Call渲染数百个相同几何体的不同实例

优势：相比单独渲染800个Mesh对象，性能提升数十倍

动态更新：DynamicDrawUsage允许每帧更新实例位置（由物理引擎驱动）

2. Ammo.js物理引擎集成
javascript
// 初始化物理引擎
physics = await AmmoPhysics();
// 将整个场景添加到物理引擎
physics.addScene(scene);
质量系统：mass: 0为静态物体（地面），mass: 1为动态物体（可移动物体）

自动同步：物理引擎计算的位置自动更新到Three.js渲染对象

碰撞检测：自动处理所有刚体间的碰撞检测和物理响应

3. 分层场景设计
可视层：阴影平面（接收阴影）+ 实例化物体（投射阴影）

物理层：不可见的厚碰撞体（防止物体掉落）

光照层：半球光（环境照明）+ 方向光（主照明和阴影）

4. 性能优化策略
优化技术	实现方式	效果
实例化渲染	InstancedMesh	减少Draw Calls
对象复用	重用Vector3/Matrix4	减少GC压力
WASM加速	ammo.wasm.js	物理计算性能提升
动态缓冲区	DynamicDrawUsage	高效更新实例数据
5. 用户交互系统
OrbitControls：鼠标左键（旋转）、右键（平移）、滚轮（缩放）

定时物理刺激：定期重置物体位置，保持场景动态性

性能监控：Stats.js显示实时帧率（FPS）

6. 阴影系统实现
javascript
// 光源设置
dirLight.castShadow = true;
// 物体设置
boxes.castShadow = true;
boxes.receiveShadow = true;
// 渲染器启用
renderer.shadowMap.enabled = true;
阴影投射：方向光源产生阴影

阴影接收：地面平面接收阴影

阴影优化：调整阴影相机缩放控制阴影质量和范围

7. 异步加载和初始化
javascript
async function init() {
    physics = await AmmoPhysics();  // 等待物理引擎加载
    // ...后续初始化
}
确保依赖：物理引擎完全加载后再初始化场景

错误处理：异步加载失败时不会阻塞页面

技术架构图
text
┌─────────────────────────────────────────────────────────┐
│                     浏览器窗口                           │
├─────────────────────────────────────────────────────────┤
│  Three.js渲染管线         │   Ammo.js物理管线           │
│  ├─ 场景图管理            │   ├─ 刚体管理                │
│  ├─ 实例化渲染器          │   ├─ 碰撞检测               │
│  ├─ 光照和阴影系统        │   ├─ 约束求解器             │
│  └─ 摄像机控制系统        │   └─ 世界模拟               │
├─────────────────────────────────────────────────────────┤
│                    WebGL渲染上下文                       │
├─────────────────────────────────────────────────────────┤
│                     GPU硬件加速                          │
└─────────────────────────────────────────────────────────┘
                            │
                    ┌───────┴───────┐
                    │  数据同步通道    │
                    │ (每帧更新位置)   │
                    └───────────────┘ -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：描述页面内容和使用的技术 -->
		<title>Three.js物理引擎演示 - 使用Ammo.js和实例化渲染技术</title>
		<!-- 字符编码：设置为UTF-8以支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：确保页面在移动设备上正确显示，禁止用户缩放 -->
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 外部CSS样式表：引入主样式文件 -->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<body>

		<!-- 页面顶部信息展示区 -->
		<div id="info">
			<!-- 技术标识和链接 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 
			物理引擎演示 - 
			<span class="tech">Ammo.js物理引擎</span> + 
			<span class="tech">实例化渲染技术</span><br>
			<small>
				场景包含800个物理物体（400个立方体 + 400个球体）<br>
				每隔约16.7毫秒随机重置两个物体的位置，观察物理碰撞效果
			</small>
		</div>

		<!-- 引入Ammo.js物理引擎的WebAssembly版本 -->
		<!-- 
			Ammo.js是Bullet物理引擎的JavaScript/WebAssembly移植版本
			wasm版本比纯JS版本性能更好，支持复杂的物理模拟
		-->
		<script src="jsm/libs/ammo.wasm.js"></script>

		<!-- 
			模块导入映射（Import Maps）
			这是ES6模块系统的一部分，允许我们定义模块的别名
			使得导入语句更加简洁和可维护
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主程序模块
			type="module"表示这是一个ES6模块，支持模块化导入
			模块具有自己的作用域，不会污染全局命名空间
		-->
		<script type="module">

			// ========== 模块导入部分 ==========
			
			// 导入Three.js核心库的所有功能
			// Three.js是一个基于WebGL的3D图形库，用于创建和显示3D图形
			import * as THREE from 'three';
			
			// 导入轨道控制器，允许用户通过鼠标控制摄像机（旋转、缩放、平移）
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入AmmoPhysics物理引擎的封装类
			// 这个类提供了Three.js与Ammo.js物理引擎之间的桥梁
			import { AmmoPhysics } from 'three/addons/physics/AmmoPhysics.js';
			
			// 导入Stats.js性能监视器
			// 显示FPS（帧率）、渲染时间等性能指标，便于性能优化
			import Stats from 'three/addons/libs/stats.module.js';

			// ========== 全局变量声明 ==========
			
			// Three.js核心组件变量
			let camera;      // 摄像机：决定场景的观察视角
			let scene;       // 场景：包含所有3D对象的容器
			let renderer;    // 渲染器：负责将3D场景渲染到2D画布上
			let stats;       // 性能监视器实例
			
			// 物理引擎相关变量
			let physics;     // Ammo物理引擎实例
			let position;    // 临时位置向量，用于避免重复创建对象
			
			// 实例化网格对象
			let boxes;       // 实例化立方体网格（包含400个立方体实例）
			let spheres;     // 实例化球体网格（包含400个球体实例）

			// ========== 初始化函数调用 ==========
			// 页面加载完成后立即开始初始化
			init();

			// ========== 异步初始化函数 ==========
			// async关键字表示这是一个异步函数，可以使用await等待异步操作完成
			async function init() {

				// ========== 1. 物理引擎初始化 ==========
				// 等待Ammo物理引擎异步加载和初始化完成
				// Ammo.wasm.js文件较大，可能需要一些时间加载
				physics = await AmmoPhysics();
				// 创建一个可重用的三维向量对象，用于临时存储位置信息
				// 这避免了在动画循环中频繁创建新对象，提高性能
				position = new THREE.Vector3();

				// ========== 2. 场景摄像机设置 ==========
				// 创建透视摄像机（模拟人眼视角）
				// 参数说明：50度视野角，自适应宽高比，0.1单位近裁剪面，100单位远裁剪面
				camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.1, 100 );
				// 设置摄像机初始位置：x=-1, y=1.5, z=2
				camera.position.set( -1, 1.5, 2 );
				// 设置摄像机看向场景中心偏上的位置（y=0.5）
				// 这样可以看到物体从空中落下的效果
				camera.lookAt( 0, 0.5, 0 );

				// ========== 3. 场景创建 ==========
				// 创建主场景对象，所有3D对象都将添加到此场景中
				scene = new THREE.Scene();
				// 设置场景背景色为中性灰色（RGB: 0x666666）
				// 灰色背景不会分散注意力，能更好地突出3D物体
				scene.background = new THREE.Color( 0x666666 );

				// ========== 4. 光照系统设置 ==========
				
				// 4.1 创建半球光（环境光）
				// 半球光模拟天空和地面的环境反射，提供柔和的基础照明
				// 默认情况下，天空色为0xffffff（白色），地面色为0x000000（黑色）
				const hemiLight = new THREE.HemisphereLight();
				scene.add( hemiLight );

				// 4.2 创建方向光（主光源）
				// 方向光模拟太阳光，提供主要照明和阴影
				const dirLight = new THREE.DirectionalLight( 0xffffff, 3 );
				// 设置光源位置（从右上后方照射）
				dirLight.position.set( 5, 5, 5 );
				// 启用阴影投射：光源照射的物体会产生阴影
				dirLight.castShadow = true;
				// 调整阴影相机的缩放系数，控制阴影的覆盖范围
				dirLight.shadow.camera.zoom = 2;
				scene.add( dirLight );

				// ========== 5. 地面和阴影系统 ==========
				
				// 5.1 创建阴影接收平面
				// 这是一个可视的平面，用于显示物体的阴影
				const shadowPlane = new THREE.Mesh(
					// 创建10x10单位的平面几何体
					new THREE.PlaneGeometry( 10, 10 ),
					// 使用阴影材质，只显示阴影，不反射光线
					new THREE.ShadowMaterial( {
						color: 0x444444  // 深灰色阴影
					} ),
				);
				// 将平面旋转-90度（绕X轴），使其水平放置
				shadowPlane.rotation.x = - Math.PI / 2;
				// 启用阴影接收：这个平面可以接收其他物体投射的阴影
				shadowPlane.receiveShadow = true;
				scene.add( shadowPlane );

				// 5.2 创建物理碰撞地面（不可见）
				// 这是一个比可视平面更厚的不可见碰撞体，用于物理模拟
				const floorCollider = new THREE.Mesh(
					// 创建10x5x10单位的立方体几何体
					// 比可视平面厚，确保物体不会掉出世界
					new THREE.BoxGeometry( 10, 5, 10 ),
					// 使用基础材质，但设置为不可见
					new THREE.MeshBasicMaterial( { color: 0x666666 } )
				);
				// 将碰撞体向下移动2.5单位，使其顶部与阴影平面齐平
				floorCollider.position.y = -2.5;
				// 为物体添加物理属性：mass=0表示静态物体（不受力影响）
				floorCollider.userData.physics = { mass: 0 };
				// 设为不可见，因为只需要它的物理碰撞功能
				floorCollider.visible = false;
				scene.add( floorCollider );

				// ========== 6. 实例化物体设置 ==========
				
				// 6.1 创建共用材质
				// Lambert材质计算每个面的光照，适合非光泽表面
				const material = new THREE.MeshLambertMaterial();

				// 6.2 创建辅助对象（避免在循环中重复创建）
				const matrix = new THREE.Matrix4();  // 4x4变换矩阵，用于设置实例位置
				const color = new THREE.Color();     // 颜色对象，用于设置实例颜色

				// 6.3 创建实例化立方体（400个）
				// 每个立方体尺寸为0.075x0.075x0.075单位
				const geometryBox = new THREE.BoxGeometry( 0.075, 0.075, 0.075 );
				// 创建实例化网格：一个几何体 + 一个材质 + 400个实例
				// 实例化渲染比单独渲染400个网格对象性能高得多
				boxes = new THREE.InstancedMesh( geometryBox, material, 400 );
				// 标记实例矩阵为动态使用，因为物理引擎会每帧更新它们的位置
				boxes.instanceMatrix.setUsage( THREE.DynamicDrawUsage );
				// 启用阴影投射和接收
				boxes.castShadow = true;
				boxes.receiveShadow = true;
				// 设置物理属性：mass=1表示动态物体（受重力和其他力影响）
				boxes.userData.physics = { mass: 1 };
				scene.add( boxes );

				// 6.4 初始化每个立方体实例的位置和颜色
				for ( let i = 0; i < boxes.count; i ++ ) {
					// 设置随机位置：
					// x和z坐标在-0.5到0.5之间随机（水平分散）
					// y坐标在0到2之间随机（垂直分散，部分在空中）
					matrix.setPosition( 
						Math.random() - 0.5, 
						Math.random() * 2, 
						Math.random() - 0.5 
					);
					// 设置第i个实例的变换矩阵
					boxes.setMatrixAt( i, matrix );
					// 设置随机颜色：0x000000到0xffffff之间的随机RGB颜色
					boxes.setColorAt( i, color.setHex( 0xffffff * Math.random() ) );
				}

				// 6.5 创建实例化球体（400个）
				// 使用二十面体几何体近似球体，半径0.05单位，细分4级（较平滑）
				const geometrySphere = new THREE.IcosahedronGeometry( 0.05, 4 );
				// 创建包含400个球体实例的实例化网格
				spheres = new THREE.InstancedMesh( geometrySphere, material, 400 );
				// 标记为动态使用
				spheres.instanceMatrix.setUsage( THREE.DynamicDrawUsage );
				// 启用阴影
				spheres.castShadow = true;
				spheres.receiveShadow = true;
				// 设置物理属性
				spheres.userData.physics = { mass: 1 };
				scene.add( spheres );

				// 6.6 初始化每个球体实例的位置和颜色
				for ( let i = 0; i < spheres.count; i ++ ) {
					matrix.setPosition( 
						Math.random() - 0.5, 
						Math.random() * 2, 
						Math.random() - 0.5 
					);
					spheres.setMatrixAt( i, matrix );
					spheres.setColorAt( i, color.setHex( 0xffffff * Math.random() ) );
				}

				// ========== 7. 物理引擎集成 ==========
				// 将整个场景添加到物理引擎中
				// 物理引擎会自动扫描场景中所有具有userData.physics属性的对象
				// 并根据mass属性创建相应的刚体（静态或动态）
				physics.addScene( scene );

				// ========== 8. 渲染器设置 ==========
				// 创建WebGL渲染器，启用抗锯齿以获得更平滑的边缘
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				// 设置设备像素比，确保在高DPI显示器上清晰显示
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为整个浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 设置动画循环回调函数（每帧调用animate函数）
				renderer.setAnimationLoop( animate );
				// 启用阴影映射，这是渲染阴影的必要步骤
				renderer.shadowMap.enabled = true;
				// 将渲染器的canvas元素添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ========== 9. 性能监视器设置 ==========
				// 创建Stats.js实例
				stats = new Stats();
				// 默认显示FPS（帧率）面板
				// 点击可以切换显示MS（渲染时间）和MB（内存使用）面板
				document.body.appendChild( stats.dom );

				// ========== 10. 交互控制设置 ==========
				// 创建轨道控制器，绑定到摄像机和渲染器的canvas元素
				const controls = new OrbitControls( camera, renderer.domElement );
				// 设置控制器的目标点（摄像机围绕旋转的中心点）
				controls.target.y = 0.5;
				// 初始化更新控制器
				controls.update();

				// ========== 11. 定时物理交互 ==========
				// 使用setInterval创建一个定时器，每1/60秒（约16.67毫秒）执行一次
				// 这模拟了60Hz的更新频率，与大多数显示器的刷新率匹配
				setInterval( () => {
					// 11.1 随机选择一个立方体实例
					// Math.random()返回0-1之间的随机数，乘以boxes.count并取整得到随机索引
					let index = Math.floor( Math.random() * boxes.count );
					
					// 设置新位置：x=0, z=0（中心上方），y在1到2之间随机
					// 这样物体会从空中落下，产生物理碰撞效果
					position.set( 0, Math.random() + 1, 0 );
					
					// 通过物理引擎设置该立方体的位置
					// 与直接设置mesh.position不同，这会触发物理响应
					// 物体会受到重力影响落下，并与其他物体碰撞
					physics.setMeshPosition( boxes, position, index );

					// 11.2 同样随机选择一个球体实例
					index = Math.floor( Math.random() * spheres.count );
					position.set( 0, Math.random() + 1, 0 );
					physics.setMeshPosition( spheres, position, index );

				}, 1000 / 60 );  // 1000毫秒除以60 = 约16.67毫秒

			}

			// ========== 动画循环函数 ==========
			// 这个函数每帧被调用一次（通常是60次/秒）
			function animate() {
				// 1. 渲染场景：将3D场景通过摄像机视角渲染到2D画布上
				// 这会自动处理所有物体的位置更新、光照计算、阴影生成等
				renderer.render( scene, camera );
				
				// 2. 更新性能监视器显示
				// Stats.js会自动计算并显示当前帧率和性能数据
				stats.update();
				
				// 注意：物理模拟的更新是由Ammo.js物理引擎内部处理的
				// 物理引擎每帧自动计算所有刚体的运动，并更新对应的Three.js对象位置
				// 这就是为什么我们不需要在animate函数中手动更新物体位置
			}

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