<!-- Three.js 八叉树碰撞演示系统
🎯 核心功能概述
这是一个第一人称物理模拟演示系统，展示了基于八叉树（Octree）的高效3D碰撞检测技术。用户可以在一个3D场景中自由移动、跳跃，并与环境中的小球进行物理交互。

📋 主要功能模块
1. 第一人称控制器
WASD移动：前、后、左、右移动

鼠标控制视角：360度自由环顾

空格跳跃：物理跳跃机制

鼠标蓄力投掷：按住左键蓄力，松开投掷小球

2. 物理碰撞系统
玩家碰撞：胶囊体与环境三角形网格的碰撞检测

小球物理：100个小球的物理模拟和碰撞

三层碰撞检测：

玩家 vs 世界（八叉树加速）

玩家 vs 小球（胶囊体近似）

小球 vs 小球（球体间碰撞）

小球 vs 世界（八叉树加速）

3. 场景管理
GLTF模型加载：加载3D环境模型

自动八叉树构建：从模型自动生成空间划分结构

光影系统：动态阴影、环境光、雾效

性能监控：实时FPS和内存使用显示

4. 调试功能
八叉树可视化：显示空间划分结构

GUI控制面板：开关调试显示

边界保护：玩家掉出边界自动重置

🛠️ 核心技术点
1. 八叉树空间划分算法
javascript
// 核心优势：
// - 将O(n²)碰撞检测复杂度降为O(n log n)
// - 递归地将3D空间划分为8个子节点
// - 每个节点包含场景三角形子集
// - 层次包围盒加速碰撞排除
2. 固定时间步长物理模拟
javascript
const STEPS_PER_FRAME = 5; // 每帧5个子步长
const deltaTime = Math.min(0.05, clock.getDelta()) / STEPS_PER_FRAME;

// 优势：
// 1. 帧率无关的物理稳定性
// 2. 防止高速物体穿透（tunneling）
// 3. 更精确的碰撞检测
3. 胶囊体碰撞表示
javascript
// 玩家使用胶囊体而非球体：
// - 更适合表示直立角色
// - 由两个半球+圆柱体组成
// - 在updatePlayer中近似为3个球体进行检测
const playerCollider = new Capsule(
    new THREE.Vector3(0, 0.35, 0), // 底部
    new THREE.Vector3(0, 1, 0),    // 顶部
    0.35                           // 半径
);
4. 弹性碰撞响应算法
javascript
// 球体-球体碰撞响应：
// 1. 计算碰撞法线
const normal = vector1.subVectors(s1.center, s2.center).normalize();

// 2. 计算速度在法线方向的分量
const v1 = vector2.copy(normal).multiplyScalar(normal.dot(s1.velocity));
const v2 = vector3.copy(normal).multiplyScalar(normal.dot(s2.velocity));

// 3. 交换法线方向速度分量（动量守恒）
s1.velocity.add(v2).sub(v1);
s2.velocity.add(v1).sub(v2);
5. 蓄力投掷力学
javascript
// 基于时间的指数蓄力函数
const impulse = 15 + 30 * (1 - Math.exp(-timeHeld));

// 特点：
// - 蓄力时间越长，投掷越远
// - 指数函数确保有上限值
// - 继承玩家当前速度（移动中投掷）
6. 渲染优化技术
VSM阴影映射：方差阴影映射，柔和阴影边缘

各向异性过滤：4x各向异性提高纹理质量

ACES色调映射：电影级色彩渲染

线性雾效：增强深度感，优化远处渲染

7. 对象池模式
javascript
// 复用100个小球，避免垃圾回收
for (let i = 0; i < NUM_SPHERES; i++) {
    // 初始化所有小球但隐藏
    spheres.push({ collider: new THREE.Sphere(new THREE.Vector3(0, -100, 0)) });
}

// 循环使用小球
sphereIdx = (sphereIdx + 1) % spheres.length;
8. 性能优化策略
javascript
// 1. 向量对象重用（避免GC）
const vector1 = new THREE.Vector3();
const vector2 = new THREE.Vector3();
const vector3 = new THREE.Vector3();

// 2. 平方距离比较（避免开方运算）
const d2 = point.distanceToSquared(sphere_center);
const r2 = r * r;
if (d2 < r2) { /* 碰撞 */ }

// 3. 增量式物理更新
for (let i = 0; i < STEPS_PER_FRAME; i++) {
    updatePhysics(deltaTime);
}
🎮 物理特性
重力系统
javascript
const GRAVITY = 30; // 重力加速度
// 空中：playerVelocity.y -= GRAVITY * deltaTime;
阻尼系统（摩擦力/空气阻力）
javascript
// 地面阻尼：exp(-4 * deltaTime) - 1
// 空中阻尼：exp(-0.4 * deltaTime) - 1 （10%的地面阻尼）
地面检测
javascript
// 通过碰撞法线y分量判断
playerOnFloor = result.normal.y > 0.5;
// >0.5 确保不是斜坡或墙壁
滑动碰撞响应
javascript
// 墙壁碰撞时移除法线方向速度分量
// 保持切向速度，实现滑动效果
playerVelocity.addScaledVector(result.normal, -result.normal.dot(playerVelocity));
📊 系统架构
text
输入系统 → 玩家控制器 → 物理引擎 → 渲染系统
   ↓          ↓           ↓         ↓
键盘/鼠标 → 速度计算 → 碰撞检测 → 画面输出
                 ↓           ↓
             位置更新 → 碰撞响应
                 ↓
             相机同步
🔧 调试与开发
调试工具集成
Stats.js：性能监控面板

OctreeHelper：八叉树结构可视化

lil-gui：参数调试面板

控制台日志：详细的碰撞和物理信息

关键配置参数
javascript
// 可调参数：
GRAVITY = 30;           // 重力强度
NUM_SPHERES = 100;      // 最大小球数
STEPS_PER_FRAME = 5;    // 物理子步数
PLAYER_RADIUS = 0.35;   // 玩家碰撞半径
JUMP_FORCE = 15;        // 跳跃力量 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<title>Three.js 八叉树碰撞演示 - 静态三角网格基础碰撞系统</title>
		<meta charset="utf-8" />
		<!-- 移动端视口配置：禁用用户缩放，确保正确的视口缩放 -->
		<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="main.css">
	</head>
	<body>
		<!-- 操作说明面板 -->
		<div id="info">
			Three.js 八叉树演示 - 静态三角网格基础碰撞系统<br />
			鼠标：环顾四周并投掷小球<br/>
			WASD：移动角色，空格键：跳跃<br/>
			左键按住蓄力，松开投掷 - 蓄力越久投掷越远
		</div>
		
		<!-- Three.js渲染器的容器 -->
		<div id="container"></div>

		<!-- 导入映射配置：告诉浏览器从哪里加载ES模块 -->
		<!-- 这是现代JavaScript模块系统的一部分，用于解决模块路径问题 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<script type="module">
			// ==============================
			// 模块导入部分
			// ==============================
			
			// 导入Three.js核心库 - 所有Three.js功能的入口点
			import * as THREE from 'three';

			// 导入性能监控器 - 显示FPS、内存使用等性能指标
			import Stats from 'three/addons/libs/stats.module.js';

			// 导入GLTF加载器 - 用于加载.glb/.gltf格式的3D模型
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

			// 导入八叉树相关工具
			// Octree：空间分割数据结构，用于高效碰撞检测
			// OctreeHelper：可视化八叉树的调试工具
			import { Octree } from 'three/addons/math/Octree.js';
			import { OctreeHelper } from 'three/addons/helpers/OctreeHelper.js';

			// 导入胶囊体几何结构 - 用于表示玩家角色的碰撞体
			// 胶囊体由两个半球和一个圆柱体组成，适合表示角色
			import { Capsule } from 'three/addons/math/Capsule.js';

			// 导入GUI调试界面库 - 用于创建可调节参数的调试面板
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// ==============================
			// 场景初始化部分
			// ==============================
			
			// 创建Three.js时钟对象 - 用于计算帧与帧之间的时间差（deltaTime）
			// deltaTime对于实现与帧率无关的动画和物理计算至关重要
			const clock = new THREE.Clock();

			// 创建场景对象 - 所有3D对象的容器
			const scene = new THREE.Scene();
			// 设置场景背景色为浅蓝色
			scene.background = new THREE.Color(0x88ccee);
			// 添加雾效：增强场景的深度感和距离感
			// 参数：颜色，近雾距离，远雾距离
			scene.fog = new THREE.Fog(0x88ccee, 0, 50);

			// 创建透视相机 - 模拟人眼视角
			// 参数：视野角度(FOV)，宽高比，近裁剪面，远裁剪面
			const camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.1, 1000);
			// 设置旋转顺序为YXZ：先绕Y轴旋转（偏航），再绕X轴旋转（俯仰），最后绕Z轴旋转（翻滚）
			// 这是第一人称射击游戏中常用的旋转顺序
			camera.rotation.order = 'YXZ';

			// ==============================
			// 灯光设置部分
			// ==============================
			
			// 创建半球光 - 模拟天空和地面的环境光
			// 参数：天空颜色，地面颜色，光照强度
			const fillLight1 = new THREE.HemisphereLight(0x8dc1de, 0x00668d, 1.5);
			fillLight1.position.set(2, 1, 1);  // 设置光源位置
			scene.add(fillLight1);

			// 创建平行光 - 模拟太阳光（方向性光源）
			const directionalLight = new THREE.DirectionalLight(0xffffff, 2.5);
			directionalLight.position.set(-5, 25, -1);
			directionalLight.castShadow = true;  // 启用阴影投射
			
			// 配置阴影相机参数 - 决定阴影的渲染范围和精度
			directionalLight.shadow.camera.near = 0.01;    // 近裁剪面
			directionalLight.shadow.camera.far = 500;      // 远裁剪面
			directionalLight.shadow.camera.right = 30;     // 阴影相机右边界
			directionalLight.shadow.camera.left = -30;     // 阴影相机左边界
			directionalLight.shadow.camera.top = 30;       // 阴影相机上边界
			directionalLight.shadow.camera.bottom = -30;   // 阴影相机下边界
			
			// 阴影贴图大小 - 决定阴影的质量（越大质量越高，性能消耗越大）
			directionalLight.shadow.mapSize.width = 1024;
			directionalLight.shadow.mapSize.height = 1024;
			
			// 阴影模糊参数
			directionalLight.shadow.radius = 4;      // 阴影边缘模糊半径
			directionalLight.shadow.bias = -0.00006; // 阴影偏移，防止阴影失真（阴影痤疮）
			
			scene.add(directionalLight);

			// ==============================
			// 渲染器设置部分
			// ==============================
			
			// 获取DOM容器元素
			const container = document.getElementById('container');

			// 创建WebGL渲染器
			// antialias: true 开启抗锯齿，使边缘更平滑
			const renderer = new THREE.WebGLRenderer({ antialias: true });
			
			// 设置设备像素比 - 适应高DPI屏幕（Retina显示屏等）
			renderer.setPixelRatio(window.devicePixelRatio);
			
			// 设置渲染器尺寸为窗口大小
			renderer.setSize(window.innerWidth, window.innerHeight);
			
			// 设置动画循环回调函数 - 替代传统的requestAnimationFrame
			renderer.setAnimationLoop(animate);
			
			// 阴影配置
			renderer.shadowMap.enabled = true;  // 启用阴影映射
			renderer.shadowMap.type = THREE.VSMShadowMap;  // 使用方差阴影映射算法
			
			// 色调映射 - 将HDR颜色映射到显示器的LDR范围
			// ACESFilmicToneMapping提供电影级的色调映射效果
			renderer.toneMapping = THREE.ACESFilmicToneMapping;
			
			// 将渲染器的canvas元素添加到DOM中
			container.appendChild(renderer.domElement);

			// ==============================
			// 性能监控器设置
			// ==============================
			
			// 创建Stats.js性能监控器
			const stats = new Stats();
			// 设置样式：绝对定位在左上角
			stats.domElement.style.position = 'absolute';
			stats.domElement.style.top = '0px';
			container.appendChild(stats.domElement);

			// ==============================
			// 物理和游戏常量定义
			// ==============================
			
			// 物理常量
			const GRAVITY = 30;  // 重力加速度，影响下坠速度

			// 小球系统常量
			const NUM_SPHERES = 100;      // 场景中最大小球数量
			const SPHERE_RADIUS = 0.2;    // 小球的物理半径
			
			// 物理模拟精度设置
			// 每帧分割为多个物理步长，防止高速物体穿透
			const STEPS_PER_FRAME = 5;

			// ==============================
			// 小球系统初始化
			// ==============================
			
			// 创建小球几何体 - 使用二十面体近似球体（性能优化）
			// 参数：半径，细分级别（细分越多越接近球体，但性能消耗越大）
			const sphereGeometry = new THREE.IcosahedronGeometry(SPHERE_RADIUS, 5);
			
			// 创建小球材质 - 使用Lambert材质（考虑光照但不考虑高光）
			const sphereMaterial = new THREE.MeshLambertMaterial({ color: 0xdede8d });

			// 小球对象数组 - 存储所有小球的状态
			const spheres = [];
			
			// 当前可投掷的小球索引 - 实现小球池的循环使用
			let sphereIdx = 0;

			// 初始化所有小球对象
			for (let i = 0; i < NUM_SPHERES; i++) {
				// 创建小球的3D网格对象
				const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
				sphere.castShadow = true;    // 小球投射阴影
				sphere.receiveShadow = true; // 小球接收阴影

				// 将小球添加到场景中
				scene.add(sphere);

				// 存储小球的完整状态信息
				spheres.push({
					mesh: sphere,  // 3D渲染对象
					// 物理碰撞体 - 初始位置放在屏幕外
					collider: new THREE.Sphere(new THREE.Vector3(0, -100, 0), SPHERE_RADIUS),
					velocity: new THREE.Vector3()  // 速度向量（初始为零）
				});
			}

			// ==============================
			// 八叉树和碰撞系统初始化
			// ==============================
			
			// 创建世界八叉树 - 用于高效的空间划分和碰撞检测
			// 八叉树将3D空间递归地划分为八个子节点，直到每个节点包含的三角形数量足够少
			const worldOctree = new Octree();

			// 创建玩家碰撞体 - 使用胶囊体（适合表示角色）
			// 胶囊体参数：起点，终点，半径
			// 起点高度0.35：胶囊体底部略高于地面，避免陷入地面
			// 终点高度1.0：胶囊体高度约为0.65米（1.0-0.35）
			const playerCollider = new Capsule(
				new THREE.Vector3(0, 0.35, 0),  // 胶囊体起点（底部）
				new THREE.Vector3(0, 1, 0),     // 胶囊体终点（顶部）
				0.35                            // 胶囊体半径
			);

			// ==============================
			// 玩家状态变量
			// ==============================
			
			// 玩家物理状态
			const playerVelocity = new THREE.Vector3();  // 玩家当前速度向量
			const playerDirection = new THREE.Vector3(); // 玩家当前朝向向量
			
			// 玩家状态标志
			let playerOnFloor = false;  // 玩家是否接触地面（用于跳跃检测）
			let mouseTime = 0;          // 鼠标按下时间戳（用于计算投掷蓄力）

			// ==============================
			// 输入状态管理
			// ==============================
			
			// 键盘状态对象 - 记录每个按键的按下/释放状态
			const keyStates = {};

			// ==============================
			// 重用向量对象（性能优化）
			// ==============================
			// 在物理计算中频繁创建和销毁Vector3对象会产生垃圾回收压力
			// 预创建并重用这些对象可以显著提高性能
			const vector1 = new THREE.Vector3();
			const vector2 = new THREE.Vector3();
			const vector3 = new THREE.Vector3();

			// ==============================
			// 事件监听器设置
			// ==============================
			
			// 键盘按下事件监听
			document.addEventListener('keydown', (event) => {
				// 记录按下的按键状态为true
				keyStates[event.code] = true;
			});

			// 键盘释放事件监听
			document.addEventListener('keyup', (event) => {
				// 记录释放的按键状态为false
				keyStates[event.code] = false;
			});

			// 鼠标按下事件监听（在容器上）
			container.addEventListener('mousedown', () => {
				// 请求浏览器指针锁定 - 实现无限制的鼠标旋转
				// 指针锁定后鼠标不会离开窗口，可以实现连续旋转
				document.body.requestPointerLock();
				
				// 记录鼠标按下的时间（用于计算投掷蓄力）
				mouseTime = performance.now();  // performance.now()提供高精度时间戳
			});

			// 鼠标释放事件监听（在整个文档上）
			document.addEventListener('mouseup', () => {
				// 检查指针是否已锁定（防止非游戏区域触发投掷）
				if (document.pointerLockElement !== null) {
					throwBall();  // 执行投掷小球函数
				}
			});

			// 鼠标移动事件监听（第一人称视角控制）
			document.body.addEventListener('mousemove', (event) => {
				// 只有当指针被锁定时才处理鼠标移动
				if (document.pointerLockElement === document.body) {
					// 根据鼠标移动量旋转相机
					// event.movementX/Y：鼠标在X/Y轴上的移动量
					// 除以500：控制鼠标灵敏度
					camera.rotation.y -= event.movementX / 500;  // 偏航（左右看）
					camera.rotation.x -= event.movementY / 500;  // 俯仰（上下看）
					
					// 限制俯仰角度，防止相机翻转过头
					// Three.js中X轴旋转的范围是-π/2到π/2（-90°到90°）
					camera.rotation.x = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, camera.rotation.x));
				}
			});

			// 窗口大小调整事件监听
			window.addEventListener('resize', onWindowResize);

			// ==============================
			// 窗口大小调整处理函数
			// ==============================
			function onWindowResize() {
				// 更新相机的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵 - 必须调用此方法使宽高比生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器大小为新的窗口尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ==============================
			// 投掷小球函数
			// ==============================
			function throwBall() {
				// 获取当前要投掷的小球对象
				const sphere = spheres[sphereIdx];

				// 获取相机当前的朝向向量（玩家看向的方向）
				camera.getWorldDirection(playerDirection);

				// 设置小球的初始位置
				// 1. 从玩家胶囊体的顶部开始
				// 2. 沿着玩家朝向移动一小段距离（避免从玩家体内发射）
				sphere.collider.center.copy(playerCollider.end)
					.addScaledVector(playerDirection, playerCollider.radius * 1.5);

				// 计算投掷力度（基于蓄力时间）
				// 基础力度：15
				// 蓄力加成：30 * (1 - e^(-Δt))，其中Δt是按下时间到当前时间的差值
				// 指数函数确保蓄力有上限，不会无限增长
				const timeHeld = (performance.now() - mouseTime) * 0.001;  // 转换为秒
				const impulse = 15 + 30 * (1 - Math.exp(-timeHeld));

				// 设置小球的速度
				// 1. 主要速度：沿着玩家朝向，乘以蓄力力度
				sphere.velocity.copy(playerDirection).multiplyScalar(impulse);
				
				// 2. 附加速度：继承玩家的当前速度（如果玩家在移动中投掷）
				// 乘以系数2，使投掷效果更明显
				sphere.velocity.addScaledVector(playerVelocity, 2);

				// 更新小球索引，指向下一个可用的小球
				// 使用取模运算实现循环队列效果
				sphereIdx = (sphereIdx + 1) % spheres.length;
			}

			// ==============================
			// 玩家碰撞检测函数
			// ==============================
			function playerCollisions() {
				// 使用八叉树检测胶囊体与世界的碰撞
				// 返回碰撞信息对象，包含法线、穿透深度等
				const result = worldOctree.capsuleIntersect(playerCollider);

				// 假设玩家不在地面上，除非检测到地面碰撞
				playerOnFloor = false;

				// 如果检测到碰撞
				if (result) {
					// 判断碰撞表面是否为地面
					// 地面法线的y分量应该接近1（垂直向上）
					playerOnFloor = result.normal.y > 0.5;  // 使用0.5作为阈值

					// 如果碰撞的不是地面（比如墙壁）
					if (!playerOnFloor) {
						// 移除速度在碰撞法线方向的分量
						// 这实现了沿表面的滑动效果，而不是直接停止
						// 公式：v' = v - (v·n) * n
						playerVelocity.addScaledVector(result.normal, -result.normal.dot(playerVelocity));
					}

					// 如果穿透深度大于最小阈值（防止微小穿透导致抖动）
					if (result.depth >= 1e-10) {
						// 将玩家沿着碰撞法线方向推出穿透区域
						playerCollider.translate(result.normal.multiplyScalar(result.depth));
					}
				}
			}

			// ==============================
			// 玩家状态更新函数
			// ==============================
			function updatePlayer(deltaTime) {
				// 计算阻尼系数 - 模拟空气阻力和地面摩擦力
				// 阻尼公式：damping = exp(-k * Δt) - 1
				// 其中k是阻尼常数（4表示较大的阻尼，即较快的减速）
				let damping = Math.exp(-4 * deltaTime) - 1;

				// 如果玩家在空中，应用重力
				if (!playerOnFloor) {
					// 重力加速度：每秒钟速度减少GRAVITY个单位
					playerVelocity.y -= GRAVITY * deltaTime;
					
					// 空中阻尼较小（空气阻力比地面摩擦力小）
					damping *= 0.1;
				}

				// 应用阻尼到速度
				playerVelocity.addScaledVector(playerVelocity, damping);

				// 计算玩家在这一帧的位移
				// 位移 = 速度 × 时间
				const deltaPosition = playerVelocity.clone().multiplyScalar(deltaTime);
				
				// 移动玩家碰撞体
				playerCollider.translate(deltaPosition);

				// 检测并处理碰撞（可能会调整玩家位置）
				playerCollisions();

				// 更新相机位置到玩家位置（第一人称视角）
				camera.position.copy(playerCollider.end);
			}

			// ==============================
			// 玩家与小球碰撞检测函数
			// ==============================
			function playerSphereCollision(sphere) {
				// 计算胶囊体的中心点（用于近似碰撞检测）
				const center = vector1.addVectors(playerCollider.start, playerCollider.end)
					.multiplyScalar(0.5);

				// 获取小球中心点（使用临时变量避免修改原对象）
				const sphere_center = sphere.collider.center;

				// 计算碰撞阈值
				const r = playerCollider.radius + sphere.collider.radius;  // 碰撞半径和
				const r2 = r * r;  // 碰撞半径的平方（用于距离比较，避免开方运算）

				// 将胶囊体近似为三个球体进行碰撞检测：
				// 1. 胶囊体底部球体
				// 2. 胶囊体顶部球体
				// 3. 胶囊体中心球体
				// 这种近似简化了胶囊体-球体的碰撞检测
				for (const point of [playerCollider.start, playerCollider.end, center]) {
					// 计算点到球心的平方距离（使用平方距离避免开方，提高性能）
					const d2 = point.distanceToSquared(sphere_center);

					// 如果发生碰撞（距离小于碰撞半径）
					if (d2 < r2) {
						// 计算碰撞法线：从球心指向碰撞点，并归一化
						const normal = vector1.subVectors(point, sphere_center).normalize();
						
						// 计算速度在碰撞法线方向的分量
						// v1：玩家速度在法线方向的分量
						// v2：小球速度在法线方向的分量
						const v1 = vector2.copy(normal).multiplyScalar(normal.dot(playerVelocity));
						const v2 = vector3.copy(normal).multiplyScalar(normal.dot(sphere.velocity));

						// 弹性碰撞响应：交换法线方向的速度分量
						// 玩家获得小球在法线方向的速度，反之亦然
						playerVelocity.add(v2).sub(v1);
						sphere.velocity.add(v1).sub(v2);

						// 计算穿透深度并分离物体
						// 穿透深度 = (碰撞半径 - 实际距离) / 2
						const d = (r - Math.sqrt(d2)) / 2;
						
						// 将小球沿着法线反方向推出穿透区域
						sphere_center.addScaledVector(normal, -d);
						
						// 注意：这里只移动了小球，玩家胶囊体位置在playerCollisions中处理
					}
				}
			}

			// ==============================
			// 小球之间碰撞检测函数
			// ==============================
			function spheresCollisions() {
				// 双重循环检查所有小球对
				// 注意：j从i+1开始，避免重复检查同一对小球
				for (let i = 0, length = spheres.length; i < length; i++) {
					const s1 = spheres[i];

					for (let j = i + 1; j < length; j++) {
						const s2 = spheres[j];

						// 计算两球心的平方距离
						const d2 = s1.collider.center.distanceToSquared(s2.collider.center);
						
						// 计算碰撞阈值
						const r = s1.collider.radius + s2.collider.radius;
						const r2 = r * r;

						// 如果发生碰撞
						if (d2 < r2) {
							// 计算碰撞法线：从s2指向s1
							const normal = vector1.subVectors(s1.collider.center, s2.collider.center).normalize();
							
							// 计算速度在法线方向的分量
							const v1 = vector2.copy(normal).multiplyScalar(normal.dot(s1.velocity));
							const v2 = vector3.copy(normal).multiplyScalar(normal.dot(s2.velocity));

							// 弹性碰撞：交换法线方向的速度分量
							s1.velocity.add(v2).sub(v1);
							s2.velocity.add(v1).sub(v2);

							// 计算穿透深度并分离小球
							const d = (r - Math.sqrt(d2)) / 2;
							
							// 将两个小球沿着法线方向推开
							// s1沿着法线方向移动
							s1.collider.center.addScaledVector(normal, d);
							// s2沿着法线反方向移动
							s2.collider.center.addScaledVector(normal, -d);
						}
					}
				}
			}

			// ==============================
			// 小球状态更新函数
			// ==============================
			function updateSpheres(deltaTime) {
				// 遍历所有小球，更新物理状态
				spheres.forEach(sphere => {
					// 根据速度和时间更新位置
					// 公式：新位置 = 旧位置 + 速度 × 时间
					sphere.collider.center.addScaledVector(sphere.velocity, deltaTime);

					// 检测小球与世界的碰撞
					const result = worldOctree.sphereIntersect(sphere.collider);

					if (result) {
						// 如果发生碰撞，处理碰撞响应
						// 1. 反弹：移除速度在法线方向的分量，并乘以反弹系数1.5
						// 反弹系数>1表示有能量增益，<1表示有能量损失
						sphere.velocity.addScaledVector(result.normal, -result.normal.dot(sphere.velocity) * 1.5);
						
						// 2. 修正位置：将小球推出穿透区域
						sphere.collider.center.add(result.normal.multiplyScalar(result.depth));
					} else {
						// 如果没有碰撞，应用重力
						sphere.velocity.y -= GRAVITY * deltaTime;
					}

					// 应用空气阻力阻尼
					// 阻尼系数1.5：小球比玩家受到更大的空气阻力
					const damping = Math.exp(-1.5 * deltaTime) - 1;
					sphere.velocity.addScaledVector(sphere.velocity, damping);

					// 检测小球与玩家的碰撞
					playerSphereCollision(sphere);
				});

				// 检测小球之间的碰撞
				spheresCollisions();

				// 更新所有小球的3D渲染位置
				// 将物理碰撞体的位置同步到渲染网格
				for (const sphere of spheres) {
					sphere.mesh.position.copy(sphere.collider.center);
				}
			}

			// ==============================
			// 移动方向计算函数
			// ==============================
			
			// 获取前进方向向量（忽略垂直分量）
			function getForwardVector() {
				// 获取相机的世界空间朝向
				camera.getWorldDirection(playerDirection);
				
				// 将y分量设为0，使移动仅限于水平面
				playerDirection.y = 0;
				
				// 归一化向量，确保长度为1
				playerDirection.normalize();
				
				return playerDirection;
			}

			// 获取右侧方向向量
			function getSideVector() {
				// 获取相机的世界空间朝向
				camera.getWorldDirection(playerDirection);
				
				// 将y分量设为0
				playerDirection.y = 0;
				playerDirection.normalize();
				
				// 计算右侧向量：前向向量与上向量的叉积
				// 叉积结果是一个垂直于两个输入向量的向量
				playerDirection.cross(camera.up);
				
				return playerDirection;
			}

			// ==============================
			// 玩家控制输入处理函数
			// ==============================
			function controls(deltaTime) {
				// 计算速度增量
				// 在地面上移动更快（25单位/秒），在空中移动较慢（8单位/秒）
				const speedDelta = deltaTime * (playerOnFloor ? 25 : 8);

				// 前向移动（W键）
				if (keyStates['KeyW']) {
					playerVelocity.add(getForwardVector().multiplyScalar(speedDelta));
				}

				// 后向移动（S键）
				if (keyStates['KeyS']) {
					playerVelocity.add(getForwardVector().multiplyScalar(-speedDelta));
				}

				// 左侧移动（A键）
				if (keyStates['KeyA']) {
					playerVelocity.add(getSideVector().multiplyScalar(-speedDelta));
				}

				// 右侧移动（D键）
				if (keyStates['KeyD']) {
					playerVelocity.add(getSideVector().multiplyScalar(speedDelta));
				}

				// 跳跃（空格键） - 只有在地面上才能跳跃
				if (playerOnFloor) {
					if (keyStates['Space']) {
						// 设置垂直向上的跳跃速度
						playerVelocity.y = 15;
					}
				}
			}

			// ==============================
			// 3D模型加载部分
			// ==============================
			
			// 创建GLTF加载器，并设置模型文件的基础路径
			const loader = new GLTFLoader().setPath('./models/gltf/');

			// 加载碰撞测试世界模型
			loader.load('collision-world.glb', (gltf) => {
				// gltf.scene包含整个加载的3D场景
				scene.add(gltf.scene);

				// 从场景图形节点构建八叉树
				// 这个过程会分析场景中的所有三角形，构建空间索引结构
				worldOctree.fromGraphNode(gltf.scene);

				// 遍历场景中的所有对象
				gltf.scene.traverse(child => {
					// 检查是否为网格对象
					if (child.isMesh) {
						// 启用阴影投射和接收
						child.castShadow = true;
						child.receiveShadow = true;

						// 如果材质有贴图，设置各向异性过滤
						// 各向异性过滤提高斜角度观看纹理时的质量
						if (child.material.map) {
							child.material.map.anisotropy = 4;  // 4倍各向异性过滤
						}
					}
				});

				// ==============================
				// 调试工具设置
				// ==============================
				
				// 创建八叉树可视化助手
				const helper = new OctreeHelper(worldOctree);
				helper.visible = false;  // 默认隐藏
				scene.add(helper);

				// 创建调试GUI界面
				const gui = new GUI({ width: 200 });
				
				// 添加调试开关
				gui.add({ debug: false }, 'debug')
					.name('显示八叉树')  // 中文标签
					.onChange(function (value) {
						// 切换八叉树可视化助手的可见性
						helper.visible = value;
					});
			});

			// ==============================
			// 玩家边界检查函数
			// ==============================
			function teleportPlayerIfOob() {
				// 如果玩家掉出世界（y坐标低于-25）
				if (camera.position.y <= -25) {
					// 重置玩家碰撞体到初始位置
					playerCollider.start.set(0, 0.35, 0);  // 起点
					playerCollider.end.set(0, 1, 0);       // 终点
					playerCollider.radius = 0.35;          // 半径
					
					// 重置相机位置和旋转
					camera.position.copy(playerCollider.end);  // 位置
					camera.rotation.set(0, 0, 0);              // 旋转归零
					
					// 重置玩家速度
					playerVelocity.set(0, 0, 0);
				}
			}

			// ==============================
			// 主动画循环函数
			// ==============================
			function animate() {
				// 计算时间增量（deltaTime）
				// Math.min(0.05, ...)：限制最大时间增量，防止物理模拟在卡顿时出错
				// 除以STEPS_PER_FRAME：将时间分割为多个子步长
				const deltaTime = Math.min(0.05, clock.getDelta()) / STEPS_PER_FRAME;

				// 子步长物理更新循环
				// 使用多个子步长可以提高物理模拟的精度，防止高速物体穿透
				for (let i = 0; i < STEPS_PER_FRAME; i++) {
					// 处理玩家控制输入
					controls(deltaTime);
					
					// 更新玩家物理状态
					updatePlayer(deltaTime);
					
					// 更新所有小球物理状态
					updateSpheres(deltaTime);
					
					// 检查玩家是否掉出世界边界
					teleportPlayerIfOob();
				}

				// 渲染场景
				renderer.render(scene, camera);

				// 更新性能监控器显示
				stats.update();
			}
		</script>
	</body>
</html>