# DriftCraft

**Repository Path**: Wilson_Lws/drift-craft

## Basic Information

- **Project Name**: DriftCraft
- **Description**: Claude Code + Qwen3.8-27B_NVFP4 本地部署写的Web版跑跑卡丁车游戏，基于threejs
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 跑跑卡丁车 Web（KartRider Web）

用 Three.js 在浏览器里玩的街机式漂移卡丁车：手刹漂移、氮气喷射、道具混战、AI 竞速。纯键盘操作，即开即玩。

## 快速开始

```bash
npm install
npm run dev        # 开发模式，默认 http://localhost:5173
```

其他脚本：

```bash
npm run build      # 类型检查 + 生产构建（dist/）
npm run preview    # 本地预览生产构建
npm run sim        # 无头仿真自测（不需要浏览器/GPU，见下文）
```

环境要求：Node.js ≥ 20.19（Vite 8 要求）。

## 玩法

### 按键

| 按键 | 作用 |
| --- | --- |
| `W` / `↑` | 油门 |
| `S` / `↓` | 刹车（速度为 0 时继续按则倒车） |
| `A` / `D` / `←` / `→` | 转向 |
| `Shift` | 漂移（手刹式：按一下转向进漂，松手出漂） |
| `空格` | 放氮气（消耗一枚氮气能量，整份 4 秒） |
| `E` | 使用拾取的道具 |
| `Enter` | 开始比赛（菜单） |
| `R` | 重新开始比赛 |
| `P` / `Esc` | 暂停 / 继续 |
| `M` / `Esc` | 结算画面回菜单 |

菜单中用 `A` / `D` 在 4 条赛道间循环切换。

### 核心系统

- **竞速**：你 + 5 台 AI 对手（闪电 / 小龟 / 阿飞 / 大壮 / 糖豆）同场 3 圈竞速，实时排名；AI 基于种子随机，每局轨迹完全确定。
- **漂移**：Shift 手刹进漂，漂移中持续减速并积攒氮气（连漂 2s/4s 有 1.5×/2× 充能加成）；带速松手有出漂小爆发。
- **JET**：漂移结束后 1 秒内新点一下 `W` 触发即时短加速（尾焰 + 镜头反应，不消耗氮气）；发车后同样可点 `W` 抢 JET。
- **氮气**：漂移/收集充能，满条生成一枚能量（上限 2 枚），按 `空格` 消耗一枚放 4 秒氮气（极速 120 km/h、提速尾焰、镜头拉远 + FOV 加大）。
- **道具**：赛道上 15 个道具箱（5 处 × 3 车道，拾取后 6 秒刷新），四种道具：
  - 🍌 香蕉 — 落地，砸中后车使其减速
  - 💦 水球 — 向后投射，命中对手减速
  - 🛡️ 护盾 — 4 秒无敌，挡下一次攻击
  - 🚀 加速 — 即时提速 + 短喷射尾焰
  - AI 会自动用道具；玩家按 `E`。
- **收集品**：赛道上漂浮的星星，拾取 +25 氮气。
- **互撞**：卡丁车之间有圆-圆碰撞（分离 + 冲量），追尾、别车都会影响对手。
- **墙壁围挡**：赛道两侧有红白相间的围挡墙，撞墙会反弹并打断漂移（带碰撞音效）。

### 赛道

| 赛道 | 特点 |
| --- | --- |
| 草原环道 | 默认，宽路少弯，适合熟悉操作 |
| 峡谷回旋 | 窄、弯多，考验走线与漂移 |
| 滨江快线 | 宽、长直道，适合氮气全开 |
| 发卡回廊 | 长直道 + 180° U 型弯，必须漂移手刹过弯 |

## 架构

- **确定性仿真**：物理以固定 1/60s 步长推进（`GameLoop` 的累加器），渲染用 rAF 并对上一状态做 α 插值；同输入必然同结果。`InputFrame`（throttle/brake/steer/drift/nitroPressed/itemUsed）是可序列化的纯数据帧，为未来网络同步预留。
- **确定性 AI**：AIBrain 用种子随机（mulberry32）与前瞻转向，无任何 `Math.random` 依赖，AI 轨迹可逐 tick 复现。
- **参数集中**：所有玩法/物理/相机数值集中在 `src/config/Tuning.ts`，调手感只改这一个文件。
- **合成音效**：无音频素材，Web Audio 实时合成（引擎声、漂移、氮气、碰撞、道具、倒计时等）。

### 目录结构

```
src/
  main.ts              入口：挂载 Game，DEV 暴露 window.__game 调试钩子
  game/                Game（主状态机 + 比赛逻辑）、GameLoop（固定步长循环）、
                       AIBrain（AI 驾驶）、Racer、Items（道具）、EventBus
  kart/                KartPhysics（纯逻辑物理）、Kart（状态+模型封装）、KartModel
  track/               TrackDef/TrackGenerator/TrackQuery（赛道采样与查询）、
                       Checkpoints（检查点/圈数计时）、tracks.ts（4 条赛道定义）
  world/               SceneManager（场景/赛道/装饰构建）、Collectibles（收集品）
  camera/              ChaseCamera（漂移/氮气镜头反应、抖动）
  effects/             DriftSmoke（漂移烟雾）
  audio/               SoundManager（Web Audio 合成音效）
  input/               KeyboardInput（键盘 → InputFrame）
  ui/                  Hud、Minimap、Speedometer、Screens（菜单/倒计时/暂停/结算）、Storage
  config/              Tuning.ts（全部可调参数）
sim_test.ts            无头仿真自测（入口）
vite.sim.config.ts     sim 构建配置（lib 模式，three 外置）
```

### 无头仿真自测

`npm run sim` 会把纯逻辑部分（物理/赛道/AI/道具）构建成 CJS 在 Node 里跑，验证：

- 转向方向（A/D 对应左右、倒车时左右反转）
- 漂移状态机、JET 窗口、氮气能量生成/消耗
- 全程自动驾驶完成 3 圈、不出界
- 检查点/圈数/计时一致性
- 跟随相机不冻结
- AI 确定性（同种子两次运行逐位一致）
- 车车互撞分离、道具减速/加速效果

改物理或 AI 后跑一遍即可回归。

## 技术栈

- TypeScript（strict）+ Vite 8
- Three.js（^0.185）
- Web Audio API（合成音效，无素材）
- localStorage（最佳圈持久化）