挥挥手就能玩。 用普通电脑摄像头捕捉手部动作，隔空操控写实宇航员在整个屏幕里俯冲、躲避迎面飞来的小行星与星球。无需任何外设，打开浏览器即玩。
纯前端 Web demo，技术栈 Three.js + MediaPipe + Vite。手势隔空操控（摇杆式手感），写实 NASA 宇航员俯冲穿越，双喷口蓝色推进羽流 + Bloom 辉光 + 程序化行星。
- 🖐️ 零外设体感 — 只用摄像头，手势隔空操控，不需要手柄/体感设备
- 🕹️ 摇杆式手感 — 手轻推宇航员朝那飞、手回中即停，省力、不挡视线、不易出框
- 🎯 开局即用 — 伸手保持 ~1 秒自动校准，引导随即消失，干净沉浸
- 🚀 电影级视觉 — 写实 NASA 宇航员（CC0）+ 双喷口蓝色推进羽流 + UnrealBloom 辉光 + 程序化行星 / 星云 / 多色星空
- ⌨️ 键盘兜底 — 没有摄像头也能用方向键 / WASD 完整玩通
- 📦 离线自包含 — MediaPipe 模型、宇航员模型、DRACO 解码器全部本地托管，不依赖外部 CDN
迎面而来的小行星、碎石、星球从深空飞来，手控宇航员在整个屏幕 2D 躲避，存活计分，难度随时间递增，撞到即结束。
| 操作 | 说明 |
|---|---|
| 🖐️ 手势开始 | 进入中央校准，伸手保持不动 ~1 秒匹配成功，引导消失后即可摇杆推动飞行 |
| ⌨️ 键盘玩 | 方向键 / WASD 控制（无摄像头时的兜底） |
游戏内快捷键：R 重设中心 · V 切位置/摇杆模式 · M 镜像切换 · H 显隐摄像头预览
需要 Node.js ≥ 18。
# 1. 克隆
git clone https://github.com/Polly-Lou/space-runner.git
cd space-runner
# 2. 安装依赖
npm install
# 3. 启动开发服务器
npm run dev然后浏览器打开 http://localhost:5173 即可。
⚠️ 摄像头权限：getUserMedia仅在localhost或 HTTPS 下可用。 若在远程服务器运行，请用 SSH 端口转发到本地后以 localhost 访问：ssh -L 5173:localhost:5173 user@your-server
npm run build # 产物输出到 dist/
npm run preview # 本地预览构建产物space-runner/
├── index.html # 入口：摄像头 video + 游戏 canvas + 校准/HUD
├── vite.config.js # dev server(127.0.0.1:5173) + /__perf 诊断端点
├── public/
│ ├── mediapipe/ # MediaPipe wasm + hand_landmarker.task（离线托管）
│ ├── models/ # astronaut_nasa.glb（NASA 写实宇航员，CC0）
│ └── draco/ # DRACO 解码器（解压 NASA 模型）
└── src/
├── main.js # 组装模块 + 主循环
├── config.js # ★集中可调参数（飞行/速度/难度/手势/星空）
├── world.js # 星空/星云/程序化星球 + Bloom 后处理
├── player.js # 宇航员：glb 加载 + 2D 俯冲 + 双喷口推进光晕
├── obstacles.js # 小行星/碎石 + 程序化行星（双对象池）
├── effects.js # 粒子特效：喷射羽流 + 撞击爆炸
├── hands.js # 摄像头 + MediaPipe + 校准 + 摇杆映射
├── oneeuro.js # One-Euro 抗抖滤波器
├── input.js # 手势/键盘 → 统一 2D 意图
├── game.js # 状态机 + 计分/难度 + 特效编排
├── ui.js # HUD + 遮罩 + 校准面板
└── style.css # sci-fi HUD 样式
📄 详细产品设计见
prd.md（含调参手册、决策记录、迭代路线图）。
- 统一控制抽象：手势与键盘都写入
input.posX/posY ∈ [-1,1]，可无缝切换。 - 摇杆速度控制：手相对中心的偏移 → 宇航员移动速度，手回中即停（解决挡视线 / 出框）。
- One-Euro 滤波：低延迟抗抖，快速移动跟手、静止不漂。
- 开局手势校准：伸手保持稳定即匹配，以该位置为摇杆中心，引导随即隐藏。
- 写实宇航员：NASA 官方 Astronaut.glb（DRACO 压缩，GLTFLoader + DRACOLoader 加载，本地解码器）。
- 视觉：UnrealBloomPass 后处理辉光 + 程序化行星（canvas 纹理 + 大气辉光 + 光环）+ 柔和软粒子喷射羽流。
本项目代码以 MIT 许可证发布。
捆绑的第三方资源遵循各自许可证（详见 LICENSE）： NASA 宇航员模型（公共领域）· MediaPipe（Apache-2.0）· DRACO（Apache-2.0）· three.js（MIT）。
🤖 本项目由人机协作开发（GitHub Copilot CLI 辅助）。