QQ飞车 3D 赛车游戏 · 源码解读

qq-speed/
├── src/
│   ├── util.js        (69 行)   数学工具 ← 最底层，谁都可以 import
│   ├── track.js       (625 行)  赛道几何与"一维化" ← 只依赖 util/textures
│   ├── vehicle.js     (369 行)  玩家车物理 ← 只依赖 util
│   ├── main.js        (1073 行) Game 主类：状态机、主循环、粘合 ← 依赖上面全部
│   ├── ai.js          (138 行)  AI 车 ← 依赖 vehicle 的 TUNE
│   ├── items.js       (228 行)  道具系统 ← 被 main 调用
│   ├── world.js       (278 行)  天空/地面/水/山/合批 ← 只依赖 util
│   ├── textures.js    (610 行)  Canvas 程序化贴图 ← 只依赖 util
│   ├── effects.js     (187 行)  粒子/胎痕 ← 只依赖 util
│   ├── audio.js       (297 行)  WebAudio 合成音效/BGM ← 零依赖
│   ├── hud.js         (290 行)  仪表盘/小地图 ← 零依赖
│   ├── input.js       (79 行)   键盘/触摸输入 ← 零依赖
│   ├── carModel.js    车模型程序化构建
│   ├── layouts.js     4 张地图的赛道控制点
│   ├── maps.js        地图主题配置（颜色/雾/道具点位）
│   ├── props.js       路边物件（楼、棕榈树、金字塔、路灯…）
│   └── index.html     唯一的 HTML
└── package.json / build.mjs / wrangler.jsonc

util.js ──→ track.js ──┐
   │                   ├──→ main.js ──→ ai.js / items.js
   ├──→ vehicle.js ────┤
   ├──→ world.js ──────┤        （main 也 import 它们）
   ├──→ textures.js ──→│
   ├──→ effects.js ────┤
   │                   │
audio.js ──→ main.js   │        audio / hud / input 互不依赖，只被 main 调用
hud.js   ──→ main.js   │
input.js ──→ main.js ──┘

npm install
npx wrangler dev     # 或 npm run preview —— 本地开发服务器
npx wrangler deploy  # 部署到 Cloudflare

↑↓←→ 驾驶 · Shift 漂移 · Ctrl 氮气/道具 · ↑(出弯点按) 或 W 小喷
Alt 道具换位 · R 复位 · C 视角 · Esc 暂停 · M 音乐

键盘/触摸 (input.js)
    ↓  每帧 frame() 返回 {up,down,left,right,shift,...}
main.js step()  ── 状态机 'menu'/'countdown'/'race'/'finish'/'paused'
    ↓  固定步长 1/120s
PlayerCar.update()   ← 车辆物理，产出 events 事件队列
AICar.update() ×5    ← AI 决策 + 同一套简化物理
    ↓
track.project()      ← 世界坐标 → 赛道坐标 (d, lat)，查碰撞/进度/腾空
    ↓
syncModel()          ← 把数字状态同步到 3D 模型（纯视觉）
    ↓
handleEvents()       ← 事件 → HUD 提示 / 音效 / 粒子
render(dt)           ← 相机、太阳、辉光后期 → WebGL 绘制

export const clamp = (v, a, b) => (v < a ? a : v > b ? b : v);   // util.js:1
export const lerp = (a, b, t) => a + (b - a) * t;                // util.js:2
export const damp = (a, b, lambda, dt) => lerp(a, b, 1 - Math.exp(-lambda * dt));  // util.js:3
export const smoothstep = (a, b, x) => {                          // util.js:4-7
  const t = clamp((x - a) / (b - a), 0, 1);
  return t * t * (3 - 2 * t);
};

a(t) = b + (a₀ - b)·e^(−λt)

export function wrapAngle(a) {          // util.js:9-13
  while (a > Math.PI) a -= Math.PI * 2;
  while (a < -Math.PI) a += Math.PI * 2;
  return a;
}
export function dampAngle(a, b, lambda, dt) {   // util.js:15-17
  return a + wrapAngle(b - a) * (1 - Math.exp(-lambda * dt));
}

export function mulberry32(seed) {              // util.js:19-27
  let s = seed >>> 0;
  return function () {
    s = (s + 0x6d2b79f5) | 0;
    let t = Math.imul(s ^ (s >>> 15), 1 | s);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

const rnd = mulberry32(id.length * 997 + 13);   // main.js:293 —— 地图 id 决定云/山的排布
const rnd = mulberry32((Date.now() & 0xffff) + 7);  // main.js:380 —— 每场比赛 AI 皮/名字不同

export function makeNoise2D(seed = 1) {              // util.js:30-61
  const rnd = mulberry32(seed);
  const perm = new Uint8Array(512);                  // 洗牌后的置换表
  ...
  const grad = new Float32Array(256);                // 每个格点一个 -1..1 的梯度值
  const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);   // util.js:41 五次缓动
  function noise(x, y) {                             // util.js:42-50
    const xi = Math.floor(x), yi = Math.floor(y);
    const xf = x - xi, yf = y - yi;
    ...                                              // 取周围 4 格的梯度值
    return lerp(lerp(a, b, u), lerp(c, d, u), v);    // 双线性混合
  }
  noise.fbm = (x, y, oct = 4) => {                   // util.js:51-59 分形叠加
    let s = 0, amp = 0.5, f = 1;
    for (let i = 0; i < oct; i++) {
      s += amp * noise(x * f, y * f);
      f *= 2.03;      // 故意不是 2，避免各倍频在同一坐标对齐产生纹路
      amp *= 0.5;
    }
    return s;
  };
  return noise;
}

noise.fbm(x * 0.004, z * 0.004, 4) * 26   // main.js:70 雪原地形：26 米高的丘陵

const curve = new THREE.CatmullRomCurve3(          // track.js:12-16
  layout.points.map((p) => new THREE.Vector3(p[0], p[2] || 0, p[1])),
  true,           // closed：闭环
  'centripetal',  // 样条类型
);
curve.arcLengthDivisions = 6000;                   // track.js:17
curve.updateArcLengths();
const approxLen = curve.getLength();
const N = Math.round(approxLen / 1.5);             // track.js:20 约 1.5 米一个采样点
const pts = curve.getSpacedPoints(N).slice(0, N);

this.px = new Float32Array(N);   // 每个采样点的 x
this.py = new Float32Array(N);   // y（高度！赛道本身有起伏）
this.pz = new Float32Array(N);   // z
this.hd = new Float32Array(N);   // heading 朝向
this.tx = new Float32Array(N);   // 切线向量 x 分量
this.tz = new Float32Array(N);   // 切线向量 z 分量
this.rx = new Float32Array(N);   // 右法线 x 分量
this.rz = new Float32Array(N);   // 右法线 z 分量
this.curv = new Float32Array(N); // 曲率
this.bank = new Float32Array(N); // 路面倾角
this.slope = new Float32Array(N);// 坡度

for (let i = 0; i < N; i++) {
  const a = (i - 1 + N) % N, b = (i + 1) % N;                  // track.js:48
  const h = Math.atan2(this.px[b] - this.px[a], this.pz[b] - this.pz[a]);  // :49
  this.hd[i] = h;
  this.tx[i] = Math.sin(h);  this.tz[i] = Math.cos(h);          // :51-52 切线
  this.rx[i] = -Math.cos(h); this.rz[i] = Math.sin(h);          // :53-54 右法线
  this.slope[i] = (this.py[b] - this.py[a]) / (2 * this.ds);    // :55 坡度
}

const raw = new Float32Array(N);
for (let i = 0; i < N; i++) raw[i] = wrapAngle(this.hd[(i+1) % N] - this.hd[i]) / this.ds;  // track.js:57-58
const W = 7;
for (let i = 0; i < N; i++) {
  let s = 0;
  for (let k = -W; k <= W; k++) s += raw[(i + k + N) % N];
  this.curv[i] = s / (2 * W + 1);   // track.js:59-64 ±7 点滑动平均
}

const bk = new Float32Array(N);
for (let i = 0; i < N; i++) bk[i] = clamp(this.curv[i] * 5.5, -0.13, 0.13);  // track.js:67
for (let i = 0; i < N; i++) {
  let s = 0;
  for (let k = -12; k <= 12; k++) s += bk[(i + k + N) % N];
  this.bank[i] = s / 25;   // track.js:68-72 再平滑一次（±12 点）
}

// 竖直曲率（平滑后）：v²·κ > g 时车辆会腾空（跳台）      track.js:73
const sy = new Float32Array(N);
for (let i = 0; i < N; i++) { let a = 0; for (let k = -3; k <= 3; k++) a += this.py[(i+k+N)%N]; sy[i] = a / 7; }
this.vcurv = new Float32Array(N);
this.sslope = new Float32Array(N);
const K = 4;
for (let i = 0; i < N; i++) {
  const s0 = (sy[i] - sy[(i - K + N) % N]) / (K * this.ds);   // 后 4 点坡度
  const s1 = (sy[(i + K) % N] - sy[i]) / (K * this.ds);       // 前 4 点坡度
  this.vcurv[i] = (s1 - s0) / (K * this.ds);                  // 坡度的变化率 = 竖直曲率
  this.sslope[i] = (sy[(i+1) % N] - sy[(i-1) % N]) / (2 * this.ds);  // 平滑坡度
}

this.cell = 16;                                    // track.js:92
this.grid = new Map();
for (let i = 0; i < N; i++) {
  const k = this._key(Math.floor(this.px[i] / this.cell), Math.floor(this.pz[i] / this.cell));
  let arr = this.grid.get(k);
  if (!arr) this.grid.set(k, (arr = []));
  arr.push(i);
}
_key(cx, cz) { return cx * 73856093 ^ cz * 19349663; }   // track.js:110

sample(d, out = this._tmp) {                       // track.js:148
  const L = this.length;
  d = ((d % L) + L) % L;                           // 任意 d 回绕到 [0, L)
  const f = d / this.ds;
  const i = Math.floor(f) % this.N;
  const j = (i + 1) % this.N;
  const t = f - Math.floor(f);
  out.x = this.px[i] + (this.px[j] - this.px[i]) * t;   // 位置线性插值
  ...
  const h = this.hd[i] + wrapAngle(this.hd[j] - this.hd[i]) * t;  // track.js:161 朝向必须 wrap！
  out.hd = h;
  out.tx = Math.sin(h); out.tz = Math.cos(h);
  out.rx = -out.tz; out.rz = out.tx;               // 派生量从插值后的 h 重算
  out.bank = this.bank[i] + (this.bank[j] - this.bank[i]) * t;
  return out;
}

project(x, y, z, hint, out) {                      // track.js:173
  const N = this.N;
  let bi = 0, best = Infinity;
  if (hint < 0) {                                  // 全局搜索（初始定位）
    for (let i = 0; i < N; i++) {
      const dx = this.px[i] - x, dz = this.pz[i] - z, dy = (this.py[i] - y) * 3;  // :178
      const d2 = dx * dx + dz * dz + dy * dy;
      if (d2 < best) { best = d2; bi = i; }
    }
  } else {                                         // 局部搜索（帧间跟踪）
    for (let k = -30; k <= 30; k++) {
      const i = (hint + k + N) % N;
      const dx = this.px[i] - x, dz = this.pz[i] - z;
      const d2 = dx * dx + dz * dz;
      if (d2 < best) { best = d2; bi = i; }
    }
  }
  // 在 bi 前后两段上精确投影                              track.js:190-202
  let i = bi, j = (i + 1) % N;
  let ex = this.px[j] - this.px[i], ez = this.pz[j] - this.pz[i];
  let t = ((x - this.px[i]) * ex + (z - this.pz[i]) * ez) / (ex * ex + ez * ez);
  if (t < 0) { /* 换到前一段重新投影 */ }
  t = clamp(t, 0, 1);
  const s = this.sample((i + t) * this.ds, out);
  s.lat = (x - s.x) * s.rx + (z - s.z) * s.rz;     // track.js:204
  s.surfY = s.y + s.lat * Math.sin(s.bank);        // track.js:205
  return s;
}

curvAhead(d, range) {                              // track.js:212-222
  const i0 = Math.floor(...);
  const steps = Math.max(1, Math.floor(range / this.ds));
  let m = 0;
  for (let k = 0; k < steps; k += 2) {             // 隔点采样省一半
    const c = this.curv[(i0 + k) % N];
    if (Math.abs(c) > Math.abs(m)) m = c;          // 绝对值最大的（带符号）
  }
  return m;
}

// 路面：每行 2 个顶点（左边缘、右边缘），行间距 = 采样间距 1.5 米
for (let r = 0; r < rows; r++) {
  const i = r % N;
  const sb = Math.sin(this.bank[i]);
  for (let s = 0; s < 2; s++) {
    const lat = s ? hw : -hw;                      // 半宽 hw，左右边缘
    const o = (r * 2 + s) * 3;
    pos[o]     = this.px[i] + this.rx[i] * lat;    // 中心点 + 法线 × lat
    pos[o + 1] = this.py[i] + lat * sb;            // 倾角抬边            track.js:240
    pos[o + 2] = this.pz[i] + this.rz[i] * lat;
    uv[(r*2+s)*2]     = s;                         // u: 0→1 横跨路宽
    uv[(r*2+s)*2 + 1] = (r * this.ds) / TEX_LEN;   // v: 每 24 米重复贴图   track.js:243
  }
}
for (let r = 0; r < N; r++) {
  const a = r*2, b = a+1, c = a+2, d = a+3;
  idx.push(a, b, c,  b, d, c);                     // 两三角形 = 一格路面
}

import { clamp, wrapAngle, damp } from './util.js';   // vehicle.js:1

export const TUNE = {          // vehicle.js:4-24
  vmax: 55,          // ~198 km/h   基础极速（米/秒；×3.6 = km/h）
  vmaxNitro: 76,     // ~274 km/h   氮气极速
  accel: 24,         // 基础加速度 m/s²
  nitroAccel: 40,    // 氮气加速度
  brake: 45,         // 刹车减速度
  reverseMax: 12,    // 倒车极速
  roll: 2.2,         // 松油门滑行减速度
  turnRate: 1.9,     // 最大转向角速度（弧度/秒 ≈ 109°/s）
  grip: 12,          // 抓地（车身回正速率 λ）
  driftMinSpeed: 13, // 低于此速无法起漂
  driftYaw: 1.5,     // 漂移中的额外角速度
  driftYawAlign: 0.85, // 反打方向修正量
  driftGrip: 2.0,    // 漂移中车身回正 λ（松→5.2，抓地 12）
  maxDriftAngle: 1.15, // 最大漂移角（约 66°）
  smallWindow: 0.5,  // 出弯小喷窗口 0.5 秒
  gaugeRate: 0.36,   // 集气速率
  nitroTime: 2.8,    // 一次氮气 2.8 秒
  gravity: 30,       // 重力（游戏常用的"放大重力"，30 而不是 9.8）
};

} else {                                              // vehicle.js:214-222 非漂移
  const turn = TUNE.turnRate * clamp(sp / 9, 0, 1)    // 低速转不动（避免原地掉头）
               * (1 - 0.55 * clamp(sp / TUNE.vmax, 0, 1.3));  // 高速衰减 55%
  this.h += this.steer * turn * dt * dir;             // 方向盘 → 车头
  if (this.s >= 0) this.m += wrapAngle(this.h - this.m) * (1 - Math.exp(-TUNE.grip * dt));  // :220
  else this.m = this.h;                               // 倒车时速度方向 = 车头
}

const dirSign = this.s >= 0 ? 1 : -1;
const mv = this.s >= 0 ? this.m : this.h;     // 前进沿 m，倒车沿 h
let vx = Math.sin(mv) * Math.abs(this.s) * dirSign;
let vz = Math.cos(mv) * Math.abs(this.s) * dirSign;
this.x += vx * dt;
this.z += vz * dt;

if (inp.up) {
  ...
  else if (this.s < vmax) this.s += acc * (1 - Math.pow(this.s / vmax, 2) * 0.85) * dt;  // vehicle.js:158
}
...
} else {  // 松油门
  const dec = (TUNE.roll + Math.abs(this.s) * 0.06) * dt;   // :163 滑行阻力随速增大
  this.s = Math.abs(this.s) <= dec ? 0 : this.s - Math.sign(this.s) * dec;
}
if (this.s > vmax) this.s -= (this.s - vmax) * 1.1 * dt;    // :166 超速回落
this.s -= tr.slope[this.hint] * Math.cos(this.h - tr.hd[this.hint]) * 6 * dt;  // :168 坡度

正常 ──Shift+方向+速度>13──→ 漂移中 ──松Shift且回正/掉速──→ 正常
                                    │
                                    └─出弯(clean)→ smallWindow=0.5s（小喷窗口）

if (!this.drifting && inp.shift && steerT !== 0 && this.s > TUNE.driftMinSpeed && onGround && !spinning) {
  this.drifting = true;
  this.driftDir = steerT;      // 记住漂移方向（之后方向键含义改变！）
  this.driftTime = 0;
  this.h += this.driftDir * 0.07;   // :178 起漂瞬间车头猛甩一下
  this.emit('driftStart', {});
}

const align = steerT * this.driftDir;        // :184 方向键与漂移方向同向=+1，反打=-1
const held = inp.shift;
if (held) this.releaseTime = 0;
else this.releaseTime += dt;
const yaw = held
  ? TUNE.driftYaw + TUNE.driftYawAlign * align                     // 按住 Shift
  : (0.45 + 0.9 * align) * Math.exp(-2.2 * this.releaseTime);      // 松开后衰减
this.h += this.driftDir * yaw * clamp(this.s / 26, 0.35, 1) * dt * (onGround ? 1 : 0.4);  // :188

const k = held ? TUNE.driftGrip : TUNE.driftGripRelease;   // :189 松开后回正加速 5.2
this.m += wrapAngle(this.h - this.m) * (1 - Math.exp(-k * dt));    // :190
let a = wrapAngle(this.h - this.m);
if (Math.abs(a) > TUNE.maxDriftAngle) {                    // :191-195
  this.m = this.h - Math.sign(a) * TUNE.maxDriftAngle;     // 漂移角封顶 66°
  a = Math.sign(a) * TUNE.maxDriftAngle;
}
this.driftAngle = a;
const sa = Math.abs(Math.sin(a));
if (onGround) this.s -= (2.5 + 11 * sa) * dt;              // :198 漂移掉速

if (!itemMode && onGround) {                                              // :199-209
  this.gauge += dt * TUNE.gaugeRate * (0.3 + sa * 1.7) * clamp(this.s / 35, 0.3, 1.1);
  while (this.gauge >= 1) {
    if (this.nitroCount < 2) { this.nitroCount++; this.gauge -= 1; this.emit('gaugeFull', {}); }
    else { this.gauge = 1; break; }      // 满两罐后集气值封顶囤着
  }
}
this.driftTime += dt;
if ((!held && (Math.abs(a) < 0.1 || (align < 0 && Math.abs(a) < 0.26))) || this.s < 7)
  this.endDrift(this.s >= 7);            // :213

endDrift(clean = true) {                    // vehicle.js:98-106
  if (!this.drifting) return;
  this.drifting = false;
  if (clean && this.driftTime > 0.22) {     // :101 漂移短于 0.22s 不算
    this.smallWindow = TUNE.smallWindow;    // 0.5s 小喷窗口开启！
    this.windowKind = 'drift';
  }
  this.emit('driftEnd', { time: this.driftTime });
}

if (this.smallWindow > 0) {                 // vehicle.js:135-149
  this.smallWindow -= dt;
  if (inp.upPressed || inp.wPressed) {      // 注意是"按下沿"不是"按住"
    const elapsed = (this.windowKind === 'drift' ? TUNE.smallWindow : 0.45) - this.smallWindow;
    const perfect = elapsed < 0.2;          // :139 出弯 0.2s 内点 = 完美喷
    const dbl = this.nitroTime > 0;         // :140 氮气中还接小喷 = 双喷素材
    this.smallBoost = perfect ? 1.0 : 0.75;
    this.smallBoostPower = (perfect ? 11 : 8) + (dbl ? 5 : 0);   // :142
    this.s += perfect ? 5.5 : 4;
    if (dbl) this.nitroTime += 0.3;
    this.emit(this.windowKind === 'land' ? 'landBoost' : 'smallBoost', { perfect, double: dbl });
    if (dbl) this.emit('double', {});
    this.smallWindow = 0;
  }
}

this.emit('land', { air: this.airTime, v: hard });
if (this.airTime > 0.3) {           // 腾空超过 0.3s 落地才有
  this.smallWindow = 0.45;
  this.windowKind = 'land';
}

let vmax = TUNE.vmax, acc = TUNE.accel;
if (this.nitroTime > 0)      { vmax = TUNE.vmaxNitro; acc = TUNE.nitroAccel; this.nitroTime -= dt; }  // 氮气：换档
if (this.smallBoost > 0)     { vmax += this.smallBoostPower; acc += 14; this.smallBoost -= dt; }       // 小喷：加成
if (this.padTime > 0)        { vmax += 12; acc += 20; this.padTime -= dt; }                            // 加速带
if (this.startBoost > 0)     { vmax += 10; acc += 26; this.startBoost -= dt; }                          // 完美起步
if (this.magnet > 0)         { vmax += 10; acc += 12; this.magnet -= dt; }                              // 磁铁
vmax = Math.min(vmax, 86);    // :129 物理上限封顶
if (this.slowTime > 0)        { vmax *= 0.55; this.slowTime -= dt; }                                    // 香蕉：减速 debuff

const lim = tr.halfW - 1.1;                 // vehicle.js:238 离墙留 1.1m 车身余量
this.impact = 0;
if (Math.abs(p.lat) > lim) {
  const sg = Math.sign(p.lat);
  const nx = p.rx * sg, nz = p.rz * sg;     // 墙的法线（指向路内）
  const over = Math.abs(p.lat) - lim;
  this.x -= nx * over;                      // :244-245 位置修正：直接推回墙内
  this.z -= nz * over;
  const vn = vx * nx + vz * nz;             // 速度在法线上的分量（>0 = 往墙里撞）
  if (vn > 0) {
    const sp = Math.max(1, Math.hypot(vx, vz));
    const impact = vn / sp;                 // 法向分量占速度的比例 ∈ (0,1]
    vx -= nx * vn * 1.25;                   // :250-251 反弹 1.25 倍法向速度
    vz -= nz * vn * 1.25;
    const keep = 1 - 0.45 * impact;         // :252-254 正撞失去 45%，蹭墙几乎不掉速
    vx *= keep; vz *= keep;
    const ns = Math.hypot(vx, vz);
    if (this.s >= 0) {
      this.s = ns;
      if (ns > 0.5) this.m = Math.atan2(vx, vz);     // :257 速度方向改为反弹后方向
      // 车头顺着墙摆正                                          :259-261
      const th = Math.abs(wrapAngle(this.h - p.hd)) < Math.PI / 2 ? p.hd : p.hd + Math.PI;
      this.h += wrapAngle(th - this.h) * Math.min(1, 0.6 * impact + 0.05);
    } else this.s = -ns;
    this.impact = impact * sp;
    if (impact > 0.3 && this.drifting) this.endDrift(false);      // :263 重撞终止漂移（无小喷）
    if (impact * sp > 6) this.emit('crash', {...});               // :265
    else if (sp > 8) this.emit('scrape', {...});
  }
  p.lat = sg * lim;
}

const groundY = p.y + p.lat * Math.sin(p.bank);   // vehicle.js:273 车底路面高度（含倾角）
if (this.airborne) {
  this.vy -= T.gravity * dt;                       // 简单重力积分
  this.y += this.vy * dt;
  this.airTime += dt;
  if (this.y <= groundY) {                         // 落地判定
    ...
    this.emit('land', { air: this.airTime, v: hard });
    if (this.airTime > 0.3) { this.smallWindow = 0.45; this.windowKind = 'land'; }   // :285-288
  }
} else {
  const va = this.s * Math.cos(this.m - p.hd);     // :293 沿赛道方向的速度分量
  if (va > 18 && va * va * -tr.vcurv[p.i] > T.gravity) {   // :294 腾空条件！
    this.airborne = true;
    this.vy = tr.sslope[p.i] * va;                 // :297 起跳初速 = 坡度×前进速度
    this.y = groundY + this.vy * dt;
    if (this.drifting) this.endDrift(false);
  } else {
    this.y = groundY;                              // 贴地
  }
}

syncModel(dt) {                                    // vehicle.js:326-351
  const mdl = this.model;
  mdl.position.set(this.x, this.y, this.z);
  const rel = this.h - tr.hd[i];                   // 车头相对赛道夹角
  const slopeAlong = tr.slope[i] * Math.cos(rel);  // 坡度在车头方向的分量
  const bankAlong = tr.bank[i] * Math.cos(rel);
  const pitchT = this.airborne ? clamp(-this.vy * 0.012, -0.3, 0.3) : -Math.atan(slopeAlong);
  this.pitchVis = damp(this.pitchVis, pitchT, 10, dt);   // 视觉俯仰也做平滑！
  this.rollVis = damp(this.rollVis, -bankAlong, 10, dt);
  mdl.rotation.set(this.pitchVis, this.h, this.rollVis, 'YXZ');   // :338
  ...
  u.root.rotation.z = damp(u.root.rotation.z, lean, 8, dt);        // 车身侧倾（子节点）
  u.root.rotation.x = damp(u.root.rotation.x, pitchDyn - (nitro ? 0.02 : 0), 6, dt);  // 加减速点头
  for (const w of u.wheels) {
    w.spin.rotation.x += (this.s * dt) / 0.47;      // :346 轮子滚动（0.47=轮半径）
    if (w.front) w.steer.rotation.y = this.drifting ? -this.driftDir * 0.3 : this.steer * 0.38;
  }
  updateFlames(u, this.nitroTime > 0, ...);
}

this.state = 'menu';     // main.js:106
// 取值：'menu' | 'countdown' | 'race' | 'finish' | 'paused'

loop() {                                          // main.js:468-477
  requestAnimationFrame(() => this.loop());       // 自我排程，60/120/144fps 由显示器决定
  const now = performance.now();
  const dt = Math.min(0.05, (now - this.last) / 1000);   // :471 帧间隔，上限 50ms
  this.last = now;
  this.time += dt;
  const inp = this.input.frame();                 // 本帧输入快照
  if (this.state !== 'paused') this.step(dt, inp);
  this.render(dt);
}

// main.js:527-536（step() 内）
const DT = 1 / 120;                              // 物理步长固定 1/120 秒（main.js:37）
this.acc += dt;
let first = true;
const noEdge = { ...pin, upPressed: false, wPressed: false, nitroPressed: false };
while (this.acc >= DT) {
  this.acc -= DT;
  if (P) P.update(DT, first ? pin : noEdge, active, this.itemMode);
  first = false;
  for (const r of this.racers) if (!r.isPlayer) r.update(DT, aiActive, this.raceTime, this.rubber(r));
  this.collide();                                 // 车与车的碰撞也按物理步算
}

step(dt, inp)
 ├─ ① countdown 阶段（482-502）：3-2-1 倒计时动画；cdT>2.72 检测起步喷射时机；
 │      cdT>=3 → state='race'（起跑门 gate.set(0) 打开）
 ├─ ② 玩家输入组装（511-523）：菜单里代跑用 autopilot、触屏自动油门、
 │      Ctrl=道具、Alt=换位、R=复位（resetPlayer）
 ├─ ③ active 判定（524-525）：玩家物理只在 'race'/'finish' 跑；AI 额外在 'menu' 也跑（演示模式）
 ├─ ④ 固定步长物理（527-536）↑
 ├─ ⑤ syncModel + updateProgress（537-540）：视觉同步、计圈
 ├─ ⑥ standings 排序（541-546）：名次
 ├─ ⑦ 道具系统 update + aiThink（547-550）
 ├─ ⑧ handleEvents（551）：消费玩家车事件队列
 ├─ ⑨ emitEffects（552）：烟雾/火花/胎痕
 ├─ ⑩ 杂项：加速带贴图滚动（558）、HUD（560-561）、引擎音（563-566）

handleEvents() {
  const P = this.player;
  if (!P || !P.events.length) return;
  for (const ev of P.events.splice(0)) {        // splice(0)：取出并清空
    const d = ev.data || {};
    switch (ev.type) {
      case 'driftStart': /* 音效+开始胎痕 */ break;
      case 'gaugeFull':  this.hud.message('集气完成！'); this.audio.play('gauge'); break;
      case 'smallBoost': P.stats.small++; ... break;
      case 'double':     P.stats.double++; this.hud.message('双喷！'); this.audio.play('double'); break;
      case 'crash':      this.shake = Math.min(1, this.shake + d.power * 0.05); ... break;
      ...
    }
  }
}

// 玩家：用"欠账"标记法（main.js:608-617）
const L = this.track.length;
let dist = r.d;
if (r.owed) {                                    // 还没过第一圈起点
  if (r.half && dist > L * 0.6 && r.lastD < L * 0.4) {  // 跨过 0 线（2995→5 的特征）
    dist -= L; r.owed = false;                   // 补上 -L：真实进度是负的（起点后退车）
  }
  else if (dist < L * 0.5) r.half = true;        // 记录"到过后半圈"
} else if (r.lastD > L * 0.6 && dist < L * 0.4) {  // 正常跨线
  dist += r.lapsDone * L + L; ...                // 总里程 = 圈数×L + d
}
r.lastD = r.d;

// AI 更简单（621-624）：直接 floor
r.totalD = r.d + r.lapsDone * L;
// 名次排序（541-546）：按 totalD 降序排，完赛者按 finishTime
this.standings = [...this.racers].sort((a, b) =>
  b.finished !== a.finished ? (a.finished ? -1 : 1) : (b.finished ? b.finishTime - a.finishTime : 0) || b.totalD - a.totalD);

rubber(r) {                                       // main.js:569-575
  const P = this.player;
  const gap = (r.totalD || 0) - (P ? P.totalD : 0);
  return gap > 0
    ? Math.max(diff.rubber[0], 1 - gap * 0.00045)   // AI 领先越多，被压越狠
    : Math.min(diff.rubber[1], 1 + (-gap) * 0.0004); // AI 落后越多，buff 越强
}

const R = 3.1;                                    // :704 两车碰撞半径之和
for (let i = 0; i < this.racers.length; i++)
  for (let j = i + 1; j < this.racers.length; j++) {
    const a = this.racers[i], b = this.racers[j];
    if (Math.abs(a.y - b.y) > 2.5) continue;      // :710 立体交叉上下层不撞
    const dx = b.x - a.x, dz = b.z - a.z;
    const d2 = dx * dx + dz * dz;
    if (d2 > R * R || d2 < 1e-6) continue;
    const d = Math.sqrt(d2);
    // 推开 + 交换动量
    ...
    const imp = -rel * 0.5;                       // :720 相对速度的 50% 转为冲量
    ...
  }

const MODES = [
  { dist: 8.2, h: 3.0, look: 5, lookH: 1.3 },     // :1003 近景
  { dist: 12.5, h: 4.6, look: 6, lookH: 1.5 },    // 远景
  { dist: 5.2, h: 1.9, look: 8, lookH: 1.1 },     // 车头视角
];
const yawT = P.s >= 0 ? P.m + wrapAngle(P.h - P.m) * 0.35 : P.h;   // :1010
this.camYaw = dampAngle(this.camYaw, yawT, P.drifting ? 4.5 : 7, dt);  // :1011

this.camPos.lerp(want, 1 - Math.exp(-14 * dt));  // :1019 位置强跟随 λ=14

render(dt) {                                      // main.js:1041-1062
  if (this.skyMesh) this.skyMesh.position.copy(this.camera.position);   // :1045
  // 太阳阴影相机对齐到纹素网格，消除阴影边缘闪烁       :1049-1052
  const texel = 150 / this.sun.shadow.mapSize.x;
  sun.position.set(...Math.round(v / texel) * texel...);
  this.hud.speedLines(k, dt);                     // :1056 速度线（高速时）
  if (this.bloom) this.bloom.strength = lerp(0.55, 1.05, ...nitro/speed);   // :1059
  this.composer ? this.composer.render() : this.renderer.render(this.scene, this.camera);
}

const cNow = this.track.curvAhead(this.dist, 8);        // ai.js:59 眼前 8 米曲率
const look = 18 + this.s * 1.25;                        // :60 视距随速度拉长
const cAhead = this.track.curvAhead(this.dist, look);
const A = 16 + this.skill;                              // 等等，实际是 16 + 30*skill
const vCorner = Math.sqrt(A / Math.max(Math.abs(cAhead), 1e-4));  // :64 弯速公式！
let vt = Math.min(vmaxBase, vCorner);                   // 目标速度 = min(极速, 弯速)

向心加速度 a = v²·κ ≤ A（轮胎抓地上限）
        ⇒  v ≤ √(A/κ)

if (this.s > vt + 1) this.s -= (16 + this.skill * 8) * dt;   // 刹车
else this.s += (nitro ? 34 : 20 + 4*skill) * (1 - Math.pow(this.s / Math.max(vt,1), 2) * 0.7) * dt;  // :69 加速曲线同款

const hw = this.track.halfW - 2.2;                       // ai.js:81 安全半宽
// 弯心偏移：进弯切弯心，越急切得越深
const inside = -Math.sign(cAhead) * clamp(Math.abs(cAhead) * 45, 0, 1) * hw * 0.8;   // :82
const target = clamp(inside + this.personal * hw * 0.8, -hw, hw);                     // :83 个人习惯偏移
// PD 控制器
this.latV += clamp((target - this.lat) * 2.2 - this.latV * 2.4, -14, 14) * dt;       // :84
this.lat += this.latV * dt;
if (Math.abs(this.lat) > hw) { this.lat = clamp(this.lat, -hw, hw); this.latV *= -0.3; }  // :87 撞墙轻弹

输出 = Kp·(target − lat) − Kd·latV
      = 2.2 × 位置误差     − 2.4 × 当前横向速度

if (Math.abs(this.track.curvAhead(this.dist, 140)) < 0.006   // ai.js:74 前方 140 米无弯
    && this.s > 35 && this.nitroCd <= 0) { ... }             // :75 且速度够
this.nitroCd = (6 + Math.random() * 8) / this.skill;          // :77 冷却随难度缩短

// 视觉漂移（ai.js:109-113）：不改变运动，只摆姿态
const wantDrift = Math.abs(cNow) > 0.012 && this.s > 26;
this.drift = damp(this.drift, wantDrift ? 1 : 0, 5, dt);
const yawT = Math.sign(cNow) * Math.min(0.62, Math.abs(cNow) * 22);
this.yawOff = dampAngle(this.yawOff, this.drift * yawT, 5, dt);
// :115 车头 = 赛道朝向 + 横向速度角 + 漂移甩尾角
this.h = s.hd + Math.atan2(this.latV, Math.max(this.s, 3)) + this.yawOff;

const WEIGHTS = {                                  // items.js:4-8
  lead:  { banana: 35, shield: 30, nitro: 20, missile: 10, magnet: 5 },   // 领头：防
  mid:   { missile: 25, nitro: 25, banana: 20, magnet: 15, shield: 15 },  // 中游：均衡
  back:  { missile: 32, nitro: 30, magnet: 25, shield: 10, banana: 3 },   // 落后：追
};

if (dx*dx + dz*dz < 6.5 && Math.abs(dy) < 3) { giveRandom(r); box.t = 2.5; }   // 2.5s 后重生

// items.js:186-203（节选）
const to = _v.set(target.x - m.x, target.y - m.y, target.z - m.z);
const dist = to.length();
m.dir.lerp(to.normalize(), Math.min(1, dt * 6)).normalize();   // 转向速率限制
m.v = Math.max(m.v, Math.abs(target.s) + 35);                  // 永远比目标快 35
m.x += m.dir.x * m.v * dt; ...
if (dist < 2.6) hitRacer(target, 'missile');                   // 命中
if (m.life > 6) explode(m);                                    // 6 秒寿命（防绕圈）

// world.js:59-89 buildSky 的 ShaderMaterial（节选）
varying vec3 vWorld;
void main() {
  vec4 p = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
  gl_Position = p.xyww;              // world.js:69 —— 关键技巧
  vWorld = position;
}
// 片元：按方向向量算渐变天幕 + 太阳光斑
float h = normalize(vWorld).y;
vec3 c = h > 0.0
  ? mix(horizon, top,    pow(clamp(h, 0.0, 1.0), 0.55))
  : mix(horizon, bottom, pow(clamp(-h, 0.0, 1.0), 0.4));     // :74
float s = dot(normalize(vWorld), sunDir);
vec3 sun = vec3(pow(s, 900.0) * 6.0 + pow(s, 40.0) * 0.35 + pow(s, 6.0) * 0.12);   // :76

h = fbm 噪声地形;                                   // world.js:113-141 三个包络函数
h = Math.max(h, lo(x, z));  h = Math.min(h, hi(x, z));   // 上下包络钳制
if (离赛道中心 < flatR) h = lerp(赛道高, h, 平滑衰减);    // 赛道周围压平
colorAt(x, z, h, col);                                // :152-165 顶点色（省一张大贴图）

// 法线 = 4 个不同频率/速度的余弦波梯度之和      world.js:201-204
// 频率 0.09/0.17/0.41/0.83，速度 1.3/1.9/2.7/3.4（大浪慢、涟漪快）
float fres = pow(1.0 - max(dot(n, v), 0.0), 3.0);        // :207 菲涅尔
vec3 col = mix(deepColor, skyColor, fres);
vec3 spec = pow(max(dot(reflect(-sunDir, n), v), 0.0), 180.0) * 2.5;   // :211-212 高光
// sparkle：伪随机像素闪烁                       :213