<!-- Three.js + Rapier 车辆物理模拟系统
一、项目概述
这是一个基于 Three.js 和 Rapier 物理引擎的交互式车辆模拟系统。该项目实现了完整的3D车辆物理模拟，包括真实的悬挂系统、转向控制、加速刹车物理效果，以及逼真的视觉渲染。

二、核心功能模块
1. 3D可视化系统
场景管理: 创建完整的3D环境，包含地面、天空背景

相机系统: 透视相机 + 轨道控制器，支持自由视角切换

灯光系统: 环境光 + 定向光组合，实现真实阴影效果

渲染引擎: WebGL 2.0渲染，支持抗锯齿和高分辨率阴影

2. 物理模拟系统
刚体物理: 10kg质量的车辆刚体模拟

车辆控制器: Rapier专用的车辆物理控制器

悬挂系统: 四轮独立悬挂，支持压缩和回弹

碰撞检测: 精确的物理碰撞和地面接触检测

3. 车辆控制系统
输入响应: WASD/方向键控制，空格刹车，R键重置

力模拟: 渐进式加速/刹车力变化，避免突变

转向逻辑: 前轮转向，45度最大转向角

物理同步: 视觉模型与物理状态的实时同步

4. 用户交互系统
相机跟随: 自动跟随车辆，保持最佳视角

自由视角: 鼠标拖拽旋转，滚轮缩放

状态重置: 一键恢复车辆到初始状态

性能监控: 实时显示FPS和性能指标

三、主要技术点详解
1. Three.js 技术栈
javascript
// 核心组件
- THREE.Scene: 3D场景容器
- THREE.PerspectiveCamera: 透视相机
- THREE.WebGLRenderer: WebGL渲染器
- THREE.Mesh: 网格对象（车辆、地面）
- THREE.BoxGeometry/CylinderGeometry: 几何体

// 材质系统
- THREE.MeshStandardMaterial: PBR标准材质
- THREE.TextureLoader: 纹理加载器

// 灯光系统
- THREE.HemisphereLight: 环境半球光
- THREE.DirectionalLight: 定向光（主光源）
- 阴影系统: 2048x2048阴影贴图，模糊阴影

// 扩展功能
- OrbitControls: 轨道相机控制器
- Stats: 性能统计器
2. Rapier 物理引擎集成
javascript
// 物理核心
- 质量: 10kg (车辆), 0kg (静态地面)
- 摩擦系数: 车身0.8，车轮1000(高抓地力)
- 碰撞形状: 长方体(车身)，圆柱体(车轮)

// 车辆控制器API
- createVehicleController(): 创建车辆控制器
- addWheel(): 添加车轮物理属性
- setWheelSuspensionStiffness(): 设置悬挂刚度
- setWheelFrictionSlip(): 设置车轮摩擦
- setWheelSteering(): 设置转向角度
- setWheelEngineForce(): 设置引擎力
- setWheelBrake(): 设置刹车力

// 物理状态同步
- 刚体位置/旋转同步
- 悬挂长度实时计算
- 车轮旋转角度同步
3. 车辆物理参数系统
javascript
// 车身参数
尺寸: 2×1×4米 (宽×高×长)
质量: 10千克
重心位置: 几何中心
碰撞形状: 长方体

// 车轮参数
半径: 0.3米
宽度: 0.4米
位置分布:
  - 前轮: (-1,0,-1.5), (1,0,-1.5)
  - 后轮: (-1,0,1.5), (1,0,1.5)

// 悬挂系统
静止长度: 0.8米
刚度: 24牛顿/米
方向: 向下(Y轴负方向)
轴线: 向左(X轴负方向)

// 动力系统
最大前进力: 30牛顿
最大后退力: -30牛顿
力变化步长: 1牛顿/帧
刹车力范围: 0-1
刹车步长: 0.05/帧

// 转向系统
最大转向角: π/4弧度 (45度)
转向轮: 前轮
转向平滑: 线性插值 (lerp系数0.25)
4. 控制逻辑实现
javascript
// 输入处理
键盘事件监听: keydown/keyup
输入映射:
  - W/↑: 前进 (forward = -1)
  - S/↓: 后退 (forward = 1)
  - A/←: 左转 (right = 1)
  - D/→: 右转 (right = -1)
  - 空格: 刹车 (brake = 1)
  - R: 重置 (reset = true)

// 力计算逻辑
前进力: 逐步增加到最大值
后退力: 逐步增加到最大值
刹车力: 逐步增加到最大值
力衰减: 释放按键时保持当前力值

// 转向平滑处理
当前角度获取: vehicleController.wheelSteering()
目标角度计算: steerAngle * steerDirection
插值更新: THREE.MathUtils.lerp(current, target, 0.25)
5. 渲染优化技术
javascript
// 阴影优化
阴影贴图尺寸: 2048×2048
阴影模糊: radius = 3, blurSamples = 8
阴影相机范围: 40×40单位
仅投射/接收必要物体

// 性能优化
物体休眠机制: chassis.isSleeping()
纹理重复使用: 地面网格纹理
几何体实例化: 车轮使用相同几何体
动画循环优化: setAnimationLoop

// 视觉质量
抗锯齿: WebGLRenderer({ antialias: true })
设备像素比适配: setPixelRatio()
高分辨率纹理: 网格纹理80×80重复
6. 系统架构特点
javascript
// 模块化设计
1. 初始化模块: init() - 设置场景、相机、灯光
2. 物理模块: initPhysics() - 物理引擎初始化
3. 车辆模块: createCar() - 车辆创建和配置
4. 控制模块: updateCarControl() - 输入处理
5. 更新模块: animate() - 主循环更新
6. 工具模块: 辅助器、统计器、控制器

// 数据流设计
用户输入 → 控制状态 → 物理参数 → 物理计算 → 视觉更新

// 事件系统
键盘事件: 控制输入
窗口事件: 大小调整
动画事件: 每帧更新
物理事件: 碰撞检测
四、物理模拟原理
1. 悬挂系统工作原理
text
悬挂模型: 弹簧-阻尼系统
计算公式: F = -k × x - c × v
  k: 悬挂刚度 (24 N/m)
  x: 压缩位移
  c: 阻尼系数 (Rapier内置)
  v: 压缩速度
2. 转向几何学
text
阿克曼转向原理: 内外轮不同转向角度
转向半径计算: R = L / tan(θ)
  L: 轴距 (3.0米)
  θ: 转向角度
实际实现: 简化模型，左右轮相同角度
3. 摩擦力模型
text
车轮摩擦: 基于库仑摩擦定律
最大静摩擦: F_max = μ × N
  μ: 摩擦系数 (1000)
  N: 法向力 (质量×重力)
打滑处理: 超出最大摩擦时滑动 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面元信息配置 -->
		<title>Three.js物理模拟 - Rapier3D车辆控制器演示</title>
		<!-- 字符编码设置 -->
		<meta charset="utf-8">
		<!-- 移动端视口设置，禁止用户缩放 -->
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 外部样式表链接 -->
		<link type="text/css" rel="stylesheet" href="main.css">
		<!-- 内联样式：设置基本文本颜色 -->
		<style>
			body {
				color: #333; /* 深灰色文本，提高可读性 */
			}
		</style>
	</head>
	<body>

		<!-- 信息提示面板，显示操作说明 -->
		<div id="info">
			<!-- 使用中文显示技术栈信息 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 物理模拟 - <a href="https://github.com/dimforge/rapier.js" target="_blank">Rapier</a> 车辆控制器
			<!-- 操作说明列表 -->
			<p>WASD 或 方向键 控制车辆移动</p>
			<p>空格键 刹车</p>
   			<p>R键 重置车辆位置</p>
			<!-- 可额外添加的说明 -->
			<p>鼠标拖动旋转视角，滚轮缩放</p>
			<p>这是一个基于物理的车辆模拟演示</p>
		</div>

		<!-- ES模块导入映射配置 -->
		<!-- 这个配置告诉浏览器如何解析模块导入路径 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js核心库
			import * as THREE from 'three';
			// 导入轨道控制器，用于鼠标控制相机旋转和平移
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入Rapier物理引擎的Three.js封装
			import { RapierPhysics } from 'three/addons/physics/RapierPhysics.js';
			// 导入物理辅助器，用于可视化碰撞体等物理元素
			import { RapierHelper } from 'three/addons/helpers/RapierHelper.js';
			// 导入性能统计库，显示帧率等信息
			import Stats from 'three/addons/libs/stats.module.js';

			// ==================== 全局变量声明 ====================
			// Three.js核心变量
			let camera, scene, renderer, stats;
			// 物理引擎相关变量
			let physics, physicsHelper, controls;
			// 车辆相关变量
			let car, chassis, wheels, movement, vehicleController;

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

			// ==================== 初始化函数 ====================
			// 异步初始化函数，负责创建场景、相机、灯光等所有基础元素
			async function init() {

				// ---------- 1. 场景初始化 ----------
				// 创建Three.js场景对象
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅蓝色（十六进制颜色代码）
				scene.background = new THREE.Color( 0xbfd1e5 );

				// ---------- 2. 相机初始化 ----------
				// 创建透视相机，参数：视野角度、宽高比、近裁剪面、远裁剪面
				camera = new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 0.1, 100 );
				// 设置相机初始位置（X, Y, Z坐标）
				camera.position.set( 0, 4, 10 );

				// ---------- 3. 灯光系统 ----------
				// 创建环境光（半球光），模拟天空和地面的反射光
				// 参数：天空颜色、地面颜色、光照强度
				const ambient = new THREE.HemisphereLight( 0x555555, 0xFFFFFF );
				// 将环境光添加到场景
				scene.add( ambient );

				// 创建平行光（主光源），模拟太阳光
				const light = new THREE.DirectionalLight( 0xffffff, 4 );
				// 设置光源位置
				light.position.set( 0, 12.5, 12.5 );
				// 启用阴影投射
				light.castShadow = true;
				// 阴影模糊半径，值越大阴影越模糊
				light.shadow.radius = 3;
				// 阴影模糊采样数，影响阴影质量
				light.shadow.blurSamples = 8;
				// 阴影贴图尺寸，影响阴影精度
				light.shadow.mapSize.width = 2048;
				light.shadow.mapSize.height = 2048;

				// 配置平行光的阴影相机（正交相机）
				// 设置阴影相机的可视范围
				const size = 40;
				light.shadow.camera.left = - size;      // 左边界
				light.shadow.camera.bottom = - size;    // 下边界
				light.shadow.camera.right = size;       // 右边界
				light.shadow.camera.top = size;         // 上边界
				light.shadow.camera.near = 1;           // 近裁剪面
				light.shadow.camera.far = 50;           // 远裁剪面

				// 将平行光添加到场景
				scene.add( light );
			
				// ---------- 4. 渲染器初始化 ----------
				// 创建WebGL渲染器，启用抗锯齿
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				// 设置设备像素比率，适配高分辨率屏幕
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 启用阴影映射
				renderer.shadowMap.enabled = true;
				// 将渲染器的canvas元素添加到页面body中
				document.body.appendChild( renderer.domElement );
				// 设置动画循环回调函数
				renderer.setAnimationLoop( animate );

				// ---------- 5. 相机控制器 ----------
				// 创建轨道控制器，实现鼠标拖拽旋转、滚轮缩放
				controls = new OrbitControls( camera, renderer.domElement );
				// 设置控制器的目标点（相机看向的点）
				controls.target = new THREE.Vector3( 0, 2, 0 );
				// 更新控制器状态
				controls.update();

				// ---------- 6. 地面创建 ----------
				// 创建立方体几何体作为地面，参数：宽度、高度、深度
				const geometry = new THREE.BoxGeometry( 100, 0.5, 100 );
				// 创建标准材质，颜色为白色
				const material = new THREE.MeshStandardMaterial( { color: 0xFFFFFF } );
				// 创建网格对象
				const ground = new THREE.Mesh( geometry, material );
				// 启用地面接收阴影
				ground.receiveShadow = true;
				// 设置地面位置，Y轴稍微向下偏移使地面表面在Y=0位置
				ground.position.set( 0, - 0.25, - 20 );
				// 在用户数据中存储物理属性，质量为0表示静态物体（不受力影响）
				ground.userData.physics = { mass: 0 };
  				// 将地面添加到场景
				scene.add( ground );

				// 异步加载地面纹理
				new THREE.TextureLoader().load( 'textures/grid.png', function ( texture ) {
					// 设置纹理重复模式
					texture.wrapS = THREE.RepeatWrapping;  // 水平方向重复
					texture.wrapT = THREE.RepeatWrapping;  // 垂直方向重复
					// 设置纹理重复次数
					texture.repeat.set( 80, 80 );
					// 将纹理设置为地面的漫反射贴图
					ground.material.map = texture;
					// 标记材质需要更新
					ground.material.needsUpdate = true;
				} );

				// ---------- 7. 性能统计 ----------
				// 创建性能统计器
				stats = new Stats();
				// 将统计器DOM元素添加到页面
				document.body.appendChild( stats.dom );
			
				// ---------- 8. 初始化物理引擎 ----------
				// 异步初始化物理引擎
				await initPhysics();
			
				// ---------- 9. 初始窗口大小调整 ----------
				// 确保渲染器和相机适应窗口大小
				onWindowResize();

				// ---------- 10. 车辆控制输入系统 ----------
				// 创建车辆控制状态对象，记录用户输入
				movement = {
					// 前进/后退控制：-1=前进，1=后退，0=停止
					forward: 0,
					// 左右转向控制：-1=右转，1=左转，0=直行
					right: 0,
					// 刹车控制：0=未刹车，1=刹车
					brake: 0,
					// 重置标志：true时重置车辆状态
					reset: false,
					// 加速力配置对象
					accelerateForce: { 
						value: 0,    // 当前加速力值
						min: - 30,   // 最小加速力（倒车最大力）
						max: 30,     // 最大加速力（前进最大力）
						step: 1      // 每帧加速力变化步长
					},
					// 刹车力配置对象
					brakeForce: { 
						value: 0,    // 当前刹车力值
						min: 0,      // 最小刹车力
						max: 1,      // 最大刹车力
						step: 0.05   // 每帧刹车力变化步长
					}
				};

				// ---------- 11. 键盘事件监听 ----------
				// 监听键盘按下事件
				window.addEventListener( 'keydown', ( event ) => {
					// 前进控制：W键或上箭头
					if ( event.key === 'w' || event.key === 'ArrowUp' ) movement.forward = - 1;
					// 后退控制：S键或下箭头
					if ( event.key === 's' || event.key === 'ArrowDown' ) movement.forward = 1;
					// 左转控制：A键或左箭头
					if ( event.key === 'a' || event.key === 'ArrowLeft' ) movement.right = 1;
					// 右转控制：D键或右箭头
					if ( event.key === 'd' || event.key === 'ArrowRight' ) movement.right = - 1;
					// 重置控制：R键
					if ( event.key === 'r' ) movement.reset = true;
					// 刹车控制：空格键
					if ( event.key === ' ' ) movement.brake = 1;
				} );

				// 监听键盘释放事件
				window.addEventListener( 'keyup', ( event ) => {
					// 释放前进/后退键时停止加速
					if ( event.key === 'w' || event.key === 's' || event.key === 'ArrowUp' || event.key === 'ArrowDown' ) movement.forward = 0;
					// 释放转向键时方向盘回正
					if ( event.key === 'a' || event.key === 'd' || event.key === 'ArrowLeft' || event.key === 'ArrowRight' ) movement.right = 0;
					// 释放重置键
					if ( event.key === 'r' ) movement.reset = false;
					// 释放刹车键
					if ( event.key === ' ' ) movement.brake = 0;
				} );

				// ---------- 12. 窗口大小调整事件 ----------
				// 监听窗口大小变化事件
				window.addEventListener( 'resize', onWindowResize, false );
			}

			// ==================== 物理引擎初始化函数 ====================
			// 负责初始化Rapier物理引擎和相关组件
			async function initPhysics() {
				// 异步加载Rapier物理引擎
				// 注意：RapierPhysics()返回一个Promise，需要使用await
				physics = await RapierPhysics();

				// 创建物理辅助器，用于调试和可视化物理元素
				// 参数：物理世界对象
				physicsHelper = new RapierHelper( physics.world );
				// 将辅助器添加到场景
				scene.add( physicsHelper );

				// 将场景中的所有具有物理属性的物体添加到物理世界
				// 这会遍历场景中的网格，检查userData.physics属性
				physics.addScene( scene );

  				// 创建车辆（在物理引擎初始化完成后创建）
				createCar();
			}

			// ==================== 创建车辆函数 ====================
			// 创建车辆的3D模型和物理表示
			function createCar( ) {
				// 创建车身几何体：长方体，尺寸2x1x4（宽x高x长）
				const geometry = new THREE.BoxGeometry( 2, 1, 4 );
				// 创建车身材质：标准材质，红色
				const material = new THREE.MeshStandardMaterial( { color: 0xFF0000 } );
				// 创建车身网格对象
				const mesh = new THREE.Mesh( geometry, material );
				// 启用车身投射阴影
				mesh.castShadow = true;
				// 将车身添加到场景
				scene.add( mesh );
				// 将车身网格保存到全局变量
				car = mesh;

				// 设置车身初始高度（Y坐标）
				mesh.position.y = 1;

				// 将车身添加到物理世界
				// 参数：网格对象、质量(kg)、摩擦系数
				// addMesh函数会在mesh.userData.physics中创建刚体
				physics.addMesh( mesh, 10, 0.8 );
				// 从网格的用户数据中获取刚体引用
				// 这个刚体是Rapier物理引擎中的物理表示
				chassis = mesh.userData.physics.body;

				// 创建车辆控制器
				// 车辆控制器是Rapier提供的专门用于车辆模拟的组件
				// 参数：底盘刚体
				vehicleController = physics.world.createVehicleController( chassis );

				// 初始化车轮数组
				wheels = [];

				// 添加四个车轮
				// 参数：车轮索引、相对车身的位置、父对象（车身）
				// 左前轮：位置(-1, 0, -1.5)
				addWheel( 0, { x: - 1, y: 0, z: - 1.5 }, mesh );
				// 右前轮：位置(1, 0, -1.5)
				addWheel( 1, { x: 1, y: 0, z: - 1.5 }, mesh );
				// 左后轮：位置(-1, 0, 1.5)
				addWheel( 2, { x: - 1, y: 0, z: 1.5 }, mesh );
				// 右后轮：位置(1, 0, 1.5)
				addWheel( 3, { x: 1, y: 0, z: 1.5 }, mesh );

				// 设置前轮的初始转向角度
				// 参数：车轮索引、转向角度（弧度）
				// Math.PI/4 = 45度，这是最大转向角
				vehicleController.setWheelSteering( 0, Math.PI / 4 );
				vehicleController.setWheelSteering( 1, Math.PI / 4 );
			}

			// ==================== 添加车轮函数 ====================
			// 创建单个车轮的物理表示和视觉模型
			function addWheel( index, pos, carMesh ) {
				// ---------- 1. 车轮物理参数定义 ----------
				const wheelRadius = 0.3;           // 车轮半径（米）
				const wheelWidth = 0.4;            // 车轮宽度（米）
				const suspensionRestLength = 0.8;  // 悬挂静止长度（米）
				const wheelPosition = pos;         // 车轮相对于车身的位置
				// 车轮方向向量：向下（Y轴负方向）
				const wheelDirection = { x: 0.0, y: - 1.0, z: 0.0 };
				// 车轮轴线向量：向左（X轴负方向）
				const wheelAxle = { x: - 1.0, y: 0.0, z: 0.0 };

				// ---------- 2. 向车辆控制器添加车轮 ----------
				// 这个调用会在物理引擎中创建车轮的物理表示
				vehicleController.addWheel(
					wheelPosition,           // 车轮位置（相对于车身）
					wheelDirection,          // 车轮方向
					wheelAxle,               // 车轮轴线
					suspensionRestLength,    // 悬挂静止长度
					wheelRadius              // 车轮半径
				);

				// ---------- 3. 配置车轮物理属性 ----------
				// 设置悬挂刚度：值越大悬挂越硬
				// 单位：牛顿/米，表示每压缩一米需要多少牛顿的力
				vehicleController.setWheelSuspensionStiffness( index, 24.0 );

				// 设置车轮摩擦系数：值越大抓地力越强
				// 这个值控制车轮与地面的摩擦力
				vehicleController.setWheelFrictionSlip( index, 1000.0 );

				// 设置车轮是否可以转向
				// 这里通过车轮的Z坐标判断：Z<0的是前轮，可以转向
				// pos.z < 0 返回布尔值，true表示可以转向
				vehicleController.setWheelSteering( index, pos.z < 0 );

				// ---------- 4. 创建车轮视觉模型 ----------
				// 创建圆柱体几何体作为车轮
				// 参数：顶部半径、底部半径、高度、分段数
				const geometry = new THREE.CylinderGeometry( wheelRadius, wheelRadius, wheelWidth, 16 );
				// 旋转几何体90度，使圆柱体侧躺（车轮的朝向）
				geometry.rotateZ( Math.PI * 0.5 );
				// 创建黑色标准材质
				const material = new THREE.MeshStandardMaterial( { color: 0x000000 } );
				// 创建车轮网格对象
				const wheel = new THREE.Mesh( geometry, material );

				// 启用车轮投射阴影
				wheel.castShadow = true;

				// 设置车轮初始位置（相对于车身）
				wheel.position.copy( pos );

				// ---------- 5. 保存引用并添加到场景 ----------
				// 将车轮添加到车轮数组
				wheels.push( wheel );
				// 将车轮添加为车身的子对象
				// 这样车轮会跟随车身移动和旋转
				carMesh.add( wheel );
			}

			// ==================== 更新车轮函数 ====================
			// 根据物理引擎的计算结果更新车轮的视觉位置和旋转
			function updateWheels() {
				// 安全检查：如果车辆控制器不存在则退出
				if ( vehicleController === undefined ) return;

				// 创建临时变量用于旋转计算
				// 转向四元数：存储车轮的转向旋转
				const wheelSteeringQuat = new THREE.Quaternion();
				// 旋转四元数：存储车轮的自转（前进时旋转）
				const wheelRotationQuat = new THREE.Quaternion();
				// 向上向量：用于转向旋转的轴
				const up = new THREE.Vector3( 0, 1, 0 );

				// 遍历所有车轮（4个）
				wheels.forEach( ( wheel, index ) => {
					// ---------- 1. 从物理引擎获取车轮状态 ----------
					// 获取车轮轴线方向（车辆坐标系）
					const wheelAxleCs = vehicleController.wheelAxleCs( index );
					// 获取车轮与车身的连接点Y坐标
					const connection = vehicleController.wheelChassisConnectionPointCs( index ).y || 0;
					// 获取当前悬挂长度（压缩后的长度）
					const suspension = vehicleController.wheelSuspensionLength( index ) || 0;
					// 获取当前转向角度（弧度）
					const steering = vehicleController.wheelSteering( index ) || 0;
					// 获取当前旋转角度（弧度，车轮自转）
					const rotationRad = vehicleController.wheelRotation( index ) || 0;

					// ---------- 2. 更新车轮位置 ----------
					// 车轮的Y坐标 = 连接点Y坐标 - 悬挂长度
					// 当悬挂压缩时，suspension变小，车轮向上移动
					wheel.position.y = connection - suspension;

					// ---------- 3. 计算车轮旋转 ----------
					// 计算转向旋转：绕Y轴旋转steering角度
					wheelSteeringQuat.setFromAxisAngle( up, steering );
					// 计算车轮自转：绕车轮轴线旋转rotationRad角度
					wheelRotationQuat.setFromAxisAngle( wheelAxleCs, rotationRad );

					// ---------- 4. 应用旋转 ----------
					// 将两个旋转组合：先转向再自转
					// 四元数乘法顺序很重要：q1 * q2 表示先应用q2再应用q1
					wheel.quaternion.multiplyQuaternions( wheelSteeringQuat, wheelRotationQuat );
				} );
			}

			// ==================== 更新车辆控制函数 ====================
			// 根据用户输入更新车辆的物理控制参数
			function updateCarControl() {
				// ---------- 1. 重置处理 ----------
				// 如果按下了R键（重置）
				if ( movement.reset ) {
					// 重置车身位置：坐标(0, 1, 0)
					chassis.setTranslation( new physics.RAPIER.Vector3( 0, 1, 0 ), true );
					// 重置车身旋转：无旋转的四元数
					chassis.setRotation( new physics.RAPIER.Quaternion( 0, 0, 0, 1 ), true );
					// 重置线速度：零向量
					chassis.setLinvel( new physics.RAPIER.Vector3( 0, 0, 0 ), true );
					// 重置角速度：零向量
					chassis.setAngvel( new physics.RAPIER.Vector3( 0, 0, 0 ), true );

					// 重置控制参数
					movement.accelerateForce.value = 0;
					movement.brakeForce.value = 0;

					// 退出函数，不执行后续控制逻辑
					return;
				}

				// ---------- 2. 加速控制逻辑 ----------
				// 初始化加速力
				let accelerateForce = 0;
				
				// 前进控制（W键或上箭头）
				if ( movement.forward < 0 ) {
					// 逐渐增加前进力
					accelerateForce = movement.accelerateForce.value - movement.accelerateForce.step;
					// 限制最小加速力（防止无限加速）
					if ( accelerateForce < movement.accelerateForce.min ) accelerateForce = movement.accelerateForce.min;
				} 
				// 后退控制（S键或下箭头）
				else if ( movement.forward > 0 ) {
					// 逐渐增加后退力
					accelerateForce = movement.accelerateForce.value + movement.accelerateForce.step;
					// 限制最大加速力
					if ( accelerateForce > movement.accelerateForce.max ) accelerateForce = movement.accelerateForce.max;
				} 
				// 没有加速输入
				else {
					// 如果车身处于休眠状态，唤醒它
					// 物理引擎会让静止的物体休眠以节省性能
					if ( chassis.isSleeping() ) chassis.wakeUp();
				}

				// 更新加速力值
				movement.accelerateForce.value = accelerateForce;

				// ---------- 3. 刹车控制逻辑 ----------
				// 初始化刹车力
				let brakeForce = 0;
				
				// 如果按下了空格键（刹车）
				if ( movement.brake > 0 ) {
					// 逐渐增加刹车力
					brakeForce = movement.brakeForce.value + movement.brakeForce.step;
					// 限制最大刹车力
					if ( brakeForce > movement.brakeForce.max ) brakeForce = movement.brakeForce.max;
				}

				// 更新刹车力值
				movement.brakeForce.value = brakeForce;

				// ---------- 4. 应用引擎力 ----------
				// 将加速力应用到前轮（前轮驱动）
				const engineForce = accelerateForce;
				// 左前轮引擎力
				vehicleController.setWheelEngineForce( 0, engineForce );
				// 右前轮引擎力
				vehicleController.setWheelEngineForce( 1, engineForce );

				// ---------- 5. 转向控制逻辑 ----------
				// 获取当前转向角度
				const currentSteering = vehicleController.wheelSteering( 0 );
				// 获取转向方向：-1=右转，1=左转，0=直行
				const steerDirection = movement.right;
				// 最大转向角度：45度（π/4弧度）
				const steerAngle = Math.PI / 4;
				// 使用线性插值实现平滑转向
				// 参数：当前值、目标值、插值系数（0.25表示每帧完成25%的转向）
				const steering = THREE.MathUtils.lerp( currentSteering, steerAngle * steerDirection, 0.25 );

				// 应用转向角度到前轮
				vehicleController.setWheelSteering( 0, steering );
				vehicleController.setWheelSteering( 1, steering );

				// ---------- 6. 应用刹车力 ----------
				// 计算刹车力值：刹车状态 × 刹车力强度
				const wheelBrake = movement.brake * brakeForce;
				// 将刹车力应用到所有四个车轮
				vehicleController.setWheelBrake( 0, wheelBrake );
				vehicleController.setWheelBrake( 1, wheelBrake );
				vehicleController.setWheelBrake( 2, wheelBrake );
				vehicleController.setWheelBrake( 3, wheelBrake );
			}

			// ==================== 窗口大小调整函数 ====================
			// 响应窗口大小变化，调整相机和渲染器
			function onWindowResize( ) {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机投影矩阵（必须调用）
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 动画循环函数 ====================
			// 每一帧调用的主循环函数
			function animate() {
				// ---------- 1. 更新车辆系统 ----------
				if ( vehicleController ) {
					// 根据用户输入更新控制参数
					updateCarControl();
					// 更新车辆物理状态
					// 参数：时间步长（假设60FPS，所以是1/60秒）
					vehicleController.updateVehicle( 1 / 60 );
					// 根据物理计算结果更新车轮视觉
					updateWheels();
				}

				// ---------- 2. 更新相机控制器 ----------
				if ( controls && car ) {
					// 设置相机控制器的目标点为车辆位置
					// 这样相机始终看向车辆
					controls.target.copy( car.position );
					// 更新控制器状态
					controls.update();
				}

				// ---------- 3. 更新物理辅助器 ----------
				// 如果启用了物理辅助器，更新其显示
				if ( physicsHelper ) physicsHelper.update();

				// ---------- 4. 渲染场景 ----------
				// 将3D场景渲染到canvas
				renderer.render( scene, camera );

				// ---------- 5. 更新性能统计 ----------
				// 更新帧率等性能信息显示
				stats.update();
			}

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