sp00nznet/shufflepuck-cafe
GitHub: sp00nznet/shufflepuck-cafe
将 1988 年 Macintosh 经典游戏 Shufflepuck Cafe 的 68k 二进制通过静态重编译技术提升为原生 C 代码并以 SDL2 运行，无需模拟器。
Stars: 2 | Forks: 0
# 🏓 SHUFFLEPUCK CAFE — 静态重编译
```
___ _ _ _ _ ___ ___ _ ___ ___ _ _ ___ _ _
/ __| || | | | | __| __| | | __| _ \ | | / __| |/ /
\__ \ __ | |_| | _|| _|| |__| _|| _/ |_| | (__| ' <
|___/_||_|\___/|_| |_| |____|___|_| \___/ \___|_|\_\
C A F E · 1 9 8 8
```
**Broderbund，1988 → 原生代码，今天。**
没有模拟器。原始的 68k Macintosh 二进制文件，被拆解并重新构建。
*标题画面 — 防拷保护已被破解，68k 已被提升为 C，
并且重编译后的游戏通过 Toolbox HAL 启动并绘制了此画面。*
## 这是什么？
*Shufflepuck Cafe* 是 **Broderbund** (Christopher Gross, Lauren Elliott, Gene
Portwood) 于 1988 年推出的一款空气曲棍球游戏。你坐在一个肮脏的太空港
食堂的桌前，与一群怪人一对一打曲棍球 puck — 神经质的机器人 **Skip
Feeney**，作弊的外星人 **Biff Raunch**，不可触碰的 **Princess Bejin**，怪物般的
**Adder** — 在华丽的 512×342 **1-bit 黑白**画面中。球拍跟随你的鼠标，puck
撞击墙壁反弹，而你的对手们*大喷垃圾话*。某类孩子 (👋) 把整个周末都沉浸在其中。
它也非常*小巧* — 一个 `PUCK` 创建者应用程序，**6 个 CODE 段，
约 52 KB 的 68k 代码**，以及作为资源的美术/声音 — 这使其成为
**静态重编译**的理想候选：不是模拟一台 Mac，而是将原始的 68000
机器码提取为 C，在今天原生编译和运行。
这个仓库就是这项成果，使用 [**macrecomp** 工具包](https://github.com/sp00nznet/macrecomp)
（ vendored 在 [`ext/macrecomp`](ext/macrecomp)）构建 — 它是
DOS 时代 pcrecomp 流程的经典 Mac 兄弟版本，曾让 *Bolo* 和 *SkiFree* 重获新生。
## 为什么要这么做？
因为模拟只是运行旧游戏；重编译则*释放*了它们。输出是你可以阅读、调试、修复和扩展的原生代码 — 宽屏、存档状态、恢复的声音，甚至可能是那些没人能打败的对手。而且因为有些游戏值得比它们的 800K 软盘活得更久。
## 工作原理
```
Shufflepuck Cafe (HFS app: CODE 0..5 + 187 PICT + 27 ASND + MENU/DITL/…)
│ ① extract ext/macrecomp/tools/extract_resources.py
▼
CODE segments + asset catalog
│ ② disassemble capstone M68K
│ ③ classify enumerate Toolbox A-traps ← the go/no-go gate
▼
function table + trap set
│ ④ lift 68k → C against the macrecomp runtime
▼
C source ──⑤ HAL──▶ QuickDraw→SDL2, Toolbox→runtime ──⑥ build──▶ native PUCK
```
## 状态
🚧 **阶段 0 已完成 — 病人已躺在手术台上，而且是个干净、小巧的病人。**
对 4am 破解的 v1.0 磁盘进行了真正的逆向侦察 (`Shufflepuck Cafe`，类型 `APPL`，
创建者 `PUCK`，644 KB 资源分支)：
- ✅ **获取并挂载**了 HFS 镜像；使用
macrecomp 的 `extract_resources.py` 提取了所有资源。完整映射见 [`docs/RECON.md`](docs/RECON.md)。
- ✅ **代码非常小：** `CODE` 0–5 = **54,202 字节**（段 0 是 2,136 字节的 A5
跳转表；真正的逻辑约 52 KB，分布在 5 个段中 — 比 Bolo 还小）。
- ✅ **资产已编目：** **187 个 `PICT`** (177 KB，标准 1-bit QuickDraw —
球桌、酒吧、每个对手的动画帧)，**27 个 `ASND`** (391 KB —
Broderbund 的*自定义*异步声音类型，待逆向)，位图 `FONT`/`FOND`，
以及正常的 `MENU`/`DITL`/`DLOG`/`WIND`/`ALRT`/`CURS`。
- 🔎 **范围已读取：** 单个黑白窗口 + 鼠标。Toolbox 接口面应该是
有限的 — QuickDraw 位块传输、事件循环、一些菜单/对话框，以及声音。
阶段 2 将统计确切的 trap 并进行确认。
| 阶段 | 内容 | 状态 |
|------:|------|-------|
| 0 | 获取 + 侦察 | ✅ [`docs/RECON.md`](docs/RECON.md) |
| 1 | 提取资源 (CODE + 资产) | ✅ 通过 `ext/macrecomp` |
| 2 | 反汇编 + 分类 trap 接口面 | ✅ [`docs/CLASSIFY.md`](docs/CLASSIFY.md) — **可以执行，但代码有保护** |
| 2.5 | 解包自解密的 CODE | ✅ [`docs/PROTECTION.md`](docs/PROTECTION.md) — **已破解，字节精确** |
| 3 | 将 68k 提升为 C | ✅ **98.5 / 99.9 / 100%** 覆盖率；整个程序编译 + 链接 |
| 4 | Toolbox HAL → SDL2 (QuickDraw/Event/Sound) | ✅ 约 95 个 trap + Resource Mgr + CopyBits/DrawPicture |
| 5 | 将游戏连接到 HAL + 调试至可玩的牌桌 | 🟢 **运行其主渲染循环** — 每帧 70 万+ trap 无崩溃；需要离屏位图 QuickDraw + 输入 (见下文) |
| 6 | 发布原生版本及附加内容 | ⬜ |
路线图见 [`docs/PLAN.md`](docs/PLAN.md)。
## 仓库布局
```
shufflepuck-cafe/
ext/macrecomp/ the 68k-Mac static-recomp toolkit (git submodule)
docs/ RECON.md · PLAN.md
original/ your own copy of the game (gitignored — see below)
work/ regeneratable extraction/analysis output (gitignored)
src/ lifted + hand-written runtime glue (later phases)
```
## 构建与运行
提升后的 C 代码现在可以**编译并链接**成原生二进制文件（目前还不能*游玩* —
这需要阶段 4 的 Toolbox HAL）。克隆时带上工具包子模块，将你自己的磁盘镜像放入
`original/`，然后构建：
```
git clone --recursive https://github.com/sp00nznet/shufflepuck-cafe.git
# 已经克隆过了？ git submodule update --init --recursive
# 需要：python3 + macresources/machfs/capstone，以及一个 C compiler
# (Windows/MSYS2：先 export PATH="/c/msys64/mingw64/bin:$PATH")
./build.sh "original/Shufflepuck Cafe - Disk 2 (Game).dc42"
```
`build.sh` 会从*你的*镜像重新生成提升后的代码并进行编译 —
**此仓库中没有提交任何游戏衍生的内容**（`src/gen/` 已被 gitignored；
见法律声明）。这里只有手写的支撑层 (`src/main.c`) 和工具包。
## 致谢与法律
原始游戏 © 1988 **Broderbund Software** (Christopher Gross, Lauren Elliott,
Gene Portwood)。*Shufflepuck Cafe* 早已绝版且不再受支持。这是一个
个人保存 / 逆向工程项目。
**本仓库不包含任何游戏代码或数据。** 与自由许可的共享软件不同，Shufflepuck
是商业废弃软件 — 因此磁盘镜像、提取的 `CODE`/`PICT`/`ASND`
资源，以及它们的任何提升表示形式都保留在仓库之外（`original/` 和
`work/` 已被 gitignored）。你需要提供自己的副本；v1.0 镜像由社区在
Internet Archive 和 Macintosh Garden 上保存。这里的所有原始代码（工具和手写的
runtime）均为 MIT 许可证 — 见 [LICENSE](LICENSE)。
使用 [macrecomp](https://github.com/sp00nznet/macrecomp) 构建，并伴随着对一个从未存在过的食堂
过多的怀旧之情。标签：68k架构, Macintosh, SDL2, 云资产清单, 复古游戏, 客户端加密, 逆向工具, 逆向工程, 静态重编译