# 星尘穿梭 STARDUST RUNNER + SO-101

**Repository Path**: xerolab/spaceship-dodge

## Basic Information

- **Project Name**: 星尘穿梭 STARDUST RUNNER + SO-101
- **Description**: 手柄开 X-Wing 穿越陨石带，桌上的 SO-101 机械臂实时托着同一架飞船做出同样姿态。基于 LeRobot，自写 IK + 碰撞检查，带 3D 数字孪生、主臂遥操与力反馈，不接硬件也能在浏览器里玩。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 星尘穿梭 STARDUST RUNNER × SO-101

用手柄（或主臂）开一架 X-Wing 在陨石带里穿梭射击，**桌上的 SO-101 六轴机械臂实时托着同一架飞船做出同样的姿态**：被陨石击中时机械臂跟着抖，主臂遥操时还有力反馈。

![游戏 + 3D 数字孪生](docs/img/sim.png)

左边是浏览器游戏，右边是 three.js 3D 仿真（加载真实 URDF 网格，关节角来自桥接程序）。不接任何硬件也能玩、能看仿真。

## 特性

- **纯前端游戏**：单文件 `index.html`，线框风格，手柄 / 键盘，Web Audio 合成音乐音效，带 AI 自动游玩模式
- **6 自由度姿态映射**：游戏里的平移 + 横滚 / 俯仰 / 偏航 → 自写阻尼最小二乘 IK → SO-101 关节角
- **每帧碰撞检查**：飞船 / 转接件与机械臂各连杆、桌面的最近距离（KD 树，约 5ms），太近就停在上一个安全姿态
- **数字孪生**：`sim.html` 同屏显示游戏和 3D 仿真；接真机时显示的是真实关节角
- **主臂遥操 + 力反馈**：插上 SO-101 主臂自动识别，从臂跟随主臂，被击中时主臂手腕也会抖
- **持续运行保护**：舵机温度轮询降速 / 回休息位断扭矩、空闲自动休息、总限速
- **一键部署**：DGX Spark、Jetson Orin NX（开机自启、全屏、桌面图标）

## 快速开始（不接硬件）

```bash
git clone https://gitee.com/ZHUZIYUrgs_admin/spaceship-dodge.git
cd spaceship-dodge
python3 -m http.server 8211
```

打开 http://localhost:8211/ 就能玩。

想看 3D 仿真里的机械臂跟着动，再起一个模拟桥：

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cd arm && ../.venv/bin/python arm_bridge.py      # mock 后端，不碰串口
```

然后打开 http://localhost:8211/sim.html 。

### 操作

| | 手柄 | 键盘 |
|---|---|---|
| 移动 | 左摇杆 | WASD |
| 横滚 / 俯仰 | 右摇杆 | IJKL |
| 偏航 | LT / RT | U / O |
| 射击 / 开始 | A 或 RB | 空格 |
| 自动游玩 | X 进入，B 退出 | X / B |
| 静音 | | M |

## 接真机

硬件：SO-101 从臂（6 个飞特 STS3215）、末端换成 X-Wing 转接件（见 `arm/xwing_urdf/`），可选 SO-101 主臂、Xbox 手柄。软件依赖 [LeRobot](https://github.com/huggingface/lerobot)。

```bash
./spark/setup.sh              # 建 venv，装 LeRobot 等依赖（Linux）
./spark/run.sh calibrate      # 标定（带串口容错补丁）
./spark/run.sh read           # 关扭矩只读：手扳关节对照仿真，核对方向 / 零位
./spark/start.sh robot        # 后台启动：游戏 + 仿真全屏，机械臂跟随
./spark/stop.sh
```

`run.sh` 的全部模式：`mock | read | robot | align | calibrate | selftest`。参数都在 `arm/config.json`（中立位、活动范围、限速、命中抖动、温度保护、主从偏移等），字段旁都有 `_说明`。详细的接线、标定、方向核对步骤见 [arm/README.md](arm/README.md)。

**Jetson Orin NX**：`bash jetson/install.sh` 一键装好环境、开机自启和桌面图标，详见脚本开头注释。

> ⚠️ 安全：第一次上电先把 `max_joint_speed_dps` 调到 60；手放在 Ctrl+C 或电源开关附近。断电前用手托住机械臂。

## 架构

```
手柄/主臂 ─▶ 浏览器游戏 index.html ──WebSocket :8765──▶ arm/arm_bridge.py ──USB 串口──▶ SO-101
                 ▲                      目标位姿/命中事件     IK + 碰撞检查 + 平滑限速 + 抖动 + 温度保护
                 └──── sim.html 3D 仿真 ◀── 关节角回传 ──┘
```

| 路径 | 作用 |
|---|---|
| `index.html` / `audio.js` | 游戏本体、合成音乐音效 |
| `sim.html` | 游戏 + three.js 3D 仿真并排 |
| `arm/arm_bridge.py` | WebSocket 服务、姿态映射、控制循环，mock / LeRobot 两种后端 |
| `arm/kinematics.py` | URDF 链解析、正解、雅可比、带限位的 DLS IK |
| `arm/collision.py` | 飞船与机械臂、桌面的最近距离 |
| `arm/protect.py` | 舵机温度与空闲保护 |
| `arm/rumble.py` / `arm/padwake.py` | Linux 手柄震动（evdev）、失焦时手柄唤醒窗口 |
| `arm/lerobot_patch.py` | 微雪舵机驱动板同步读不稳的容错补丁 |
| `arm/xwing_urdf/` | SO-101 + 转接件 + X-Wing 的 URDF 与网格 |
| `arm/calibration/` | 各条臂的标定备份与参数对照 |
| `spark/` / `jetson/` | 部署与启动脚本 |
| `versions/` / `VERSIONS.md` | 每个版本的游戏快照和更新记录 |

## 许可证

本项目代码以 [MIT](LICENSE) 许可证发布。第三方内容沿用各自的许可：

- `vendor/three/`：[three.js](https://github.com/mrdoob/three.js)，MIT
- `arm/so101_new_calib.urdf` 与 `arm/xwing_urdf/meshes/` 下的 SO-101 网格：来自 [TheRobotStudio/SO-ARM100](https://github.com/TheRobotStudio/SO-ARM100)，Apache-2.0
- X-Wing 外形模型仅用于非商业的教学展示；Star Wars、X-Wing 相关商标归 Lucasfilm Ltd. 所有，本项目与其无关