sp00nznet/macrecomp
GitHub: sp00nznet/macrecomp
macrecomp 是一套经典 68k Macintosh 应用的静态重编译工具包，通过提取资源、反汇编、代码提升和基于 SDL2 的 Toolbox 抽象层，将老 Mac 程序转换为可在现代平台运行的原生 C 代码。
Stars: 1 | Forks: 0
# 🖥️ macrecomp
**为您的静态重编译项目提供即插即用的经典 Macintosh 支持。**
```
68k CODE resources Your recompiled C
from a 1980s Mac app (one function per 68k sub)
│ │
│ extract · disassemble · lift │ calls Toolbox traps
▼ ▼
┌──────────────────────────────────────────────────────┐
│ macrecomp │
│ m68k CPU state · A5 world · resource mgr · QuickDraw │
│ Event/Menu/Window/Dialog Mgr · Sound Mgr │
└──────────────────────────────────────────────────────┘
│
▼
SDL2 window + audio
```
*将 System 6/7 的 Toolbox 切割为可链接的 C 库 —— 这样您就不必对 QuickDraw 进行两次逆向工程。*
## 这是什么？
静态重编译（Static recompilation）会提取旧程序的机器码，并将其转换为如今仍可运行的
原生 C 代码。对于主机游戏而言，最困难的部分是*硬件*
（这正是 [snesrecomp](https://github.com/sp00nznet/snesrecomp) 所提供的内容）。对于
**经典 Macintosh** 应用程序而言，最困难的部分是 **Toolbox** —— 每个 Mac 应用程序在处理图形、窗口、菜单、事件和声音时都会调用的约 1000 个 ROM/System 陷阱。
每个 68k Mac 应用程序都通过 QuickDraw 进行绘制，不断轮询 `GetNextEvent`，并通过 Sound Manager 播放声音。那么，为什么还要为每一次重编译重新实现这些功能呢？
**macrecomp** 将提取出的 68k Mac 应用程序所需的组件打包在一起 —— 一个小型的 m68k CPU 状态模型、A5 world + segment/jump-table 加载器、resource-fork 管理器，以及一个不断扩展、将 Toolbox 陷阱映射到 **SDL2** 的 HAL —— 作为一个可链接的库，外加帮助您实现目标的工具集。这与 N64Recomp 和 snesrecomp 采用的“将平台切割成库，让每个游戏链接它们”的方法相同，只不过它是针对 Mac 的。
它是 x86/DOS [pcrecomp](../tools) 工具包的同胞项目，主要针对 68k + Toolbox，
而不是 8086 + DOS 中断。
## 流水线
```
App (HFS resource fork: CODE 0..N + PICT/snd/ASND/MENU…)
│ ① extract tools/extract_resources.py (dc42/HFS → CODE + assets + inventory.json)
▼
CODE segments + asset catalog
│ ② disassemble tools/disasm_code.py (capstone M68K)
│ ③ classify tools/scan_traps.py (enumerate A-line Toolbox traps ← the scope gate)
▼
function table + trap set
│ ④ lift tools/lift68k.py (68k → C against the macrecomp runtime)
▼
C source ──⑤ HAL──▶ QuickDraw→SDL2, traps→runtime ──⑥ build──▶ native app
```
步骤 ①–③ 成本很低，并且能在您正式投入*之前*告知一款游戏的实际开销：从 ③ 得到的**陷阱集（trap set）**正是您必须实现的确切 Toolbox 表面。
## 状态
🚧 **v0 —— 工具优先。** 提取工具已完备；运行时 HAL 会随每个游戏逐步扩展。
| 组件 | 功能描述 | 状态 |
|-----------|--------------|-------|
| `extract_resources.py` | DiskCopy 4.2 / raw HFS → CODE segments, asset catalog, `inventory.json` | ✅ 可用 |
| `disasm_code.py` | capstone-M68K 反汇编，附带 traps + A5 jump-table 调用注释 | ✅ 可用 |
| `scan_traps.py` | 枚举 A-line (`$Axxx`) Toolbox 陷阱；解析 CODE 0 跳转表 | ✅ 可用（已在 Finder 上验证） |
| `traps.json` | 上述两个工具所需的 1177 个陷阱 word↔name 映射（源自《Inside Macintosh》） | ✅ |
| `pict2png.py` | 解码 1-bit QuickDraw PICT (v1) 资源 → PNG (BitsRect/PackBitsRect) | ✅ |
| `unprotect.py` | 静态解包自解密/受保护的 CODE | ✅ **完全解决**（跳转表 + segment bodies，字节精确） |
| `ghidra/EmuDecrypt.java` | 在 Ghidra 的 p-code 模拟器中运行独立的解密例程（破解未知密码的 oracle） | ✅ |
| `lift68k.py` | 机械化的 68k → C lifter（基于函数；branches→goto；traps→HAL） | ✅ **98–100% 指令覆盖率** |
| 运行时 `m68k.{h,c}`: CPU 状态 + big-endian memory + 忠实还原的 CCR flags + 函数表/dispatch | 执行基础底座 | ✅ |
| 运行时 `quickdraw.c` + `platform_sdl.c`: 1-bit framebuffer + pen/rect/line/oval/text/CopyBits → SDL2 window | 视频 HAL | ✅ 核心（已自测） |
| 运行时 `toolbox.c`: A-trap dispatch, Resource Mgr (serves the app's resources), QuickDraw incl. **CopyBits + DrawPicture**, Window/Menu/Dialog/File stubs, Memory Mgr heap | OS HAL | 🟢 ~95 traps; 可启动真实游戏 |
| 声音 (ASND) · 完整的 Menu/Dialog 交互 | | ⬜ |
首个客户：[**shufflepuck-cafe**](https://github.com/sp00nznet/shufflepuck-cafe)
(Broderbund, 1988) — 6 个 CODE segments，约 52 KB 的 68k 代码，黑白 QuickDraw。
## 在您的项目中使用 macrecomp
将其添加为 submodule（游戏仓库正是通过这种方式引用它的）：
```
git submodule add https://github.com/sp00nznet/macrecomp.git ext/macrecomp
```
```
# 在你的游戏的 CMakeLists.txt 中：
add_subdirectory(ext/macrecomp)
target_link_libraries(my_recomp PRIVATE macrecomp SDL2::SDL2main)
```
提取游戏资源以开始挖掘：
```
python ext/macrecomp/tools/extract_resources.py "MyGame.dc42" -o work/
# → work/code/CODE_0.bin … CODE_N.bin, work/inventory.json, work/assets/…
```
## 仓库结构
```
macrecomp/
tools/ extract / disasm / scan-traps / lift (the dig kit, Python)
runtime/ the linkable C library — m68k state, A5 world, Toolbox HAL → SDL2
include/ public headers (macrecomp/*.h)
docs/ ARCHITECTURE.md and trap-mapping notes
examples/ minimal harnesses
```
## 致谢与参考来源
- **[macresources](https://github.com/tashtego/macresources) + [machfs](https://github.com/tashtego/machfs)** 作者 Elliot Nunn —— 纯 Python 编写的 HFS + resource-fork 解析。提取器正是建立在这些项目之上。
- **[capstone](https://www.capstone-engine.org/)** —— M68K 反汇编。
- *Inside Macintosh* (Apple, 1985–) 以及开源的 **[Executor](https://github.com/autc04/executor)** 洁净室 Toolbox —— 为陷阱 HAL 提供参考语义。此处未使用或分发任何 Apple ROM 或代码。
- 方法借鉴自 **[N64Recomp](https://github.com/N64Recomp/N64Recomp)** 和 **[snesrecomp](https://github.com/sp00nznet/snesrecomp)**。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。该工具包为原创作品。它**不**包含任何 Apple
ROM、System 软件或受版权保护的游戏数据 —— 您需要为正在重编译的任何内容自带副本。标签：68k架构, Bash脚本, Mac OS System 6/7, SDL2, 云资产清单, 客户端加密, 工具链, 经典游戏/应用移植, 逆向工具, 逆向工程, 静态重编译