fjkorf/rustretro

# rustretro 一个完全使用 Rust 从头编写的 libretro 前端 —— 使用 Bevy 处理视频，cpal 处理音频，并内置了一个 egui 调试器，用于在老游戏运行时对其进行解剖分析。 ## 为什么做这个 模拟器前端非常适合*玩*游戏。但我想要一个同时也是**仪器**的前端： 暂停任何一帧，读取 68000 的寄存器，在程序计数器附近进行反汇编，为你已弄懂的 代码区域添加标签，并通过缩略图为机器状态添加书签 —— 这是你在逆向工程一款 CPS2 格斗游戏（而不仅仅是玩它）时所需要的那种 工具。我没有将这些功能硬塞到别人的前端上，而是自己写了一个：约 4,000 行 Rust 代码， 可在运行时动态加载任何 libretro 核心，并将其 C 回调接入到 Bevy 应用中。 ## 它的功能 - **在运行时加载任何 libretro 核心** —— 通过 `libloading` 实现，切换系统无需重新编译。 已测试 Nestopia (NES)、Genesis Plus GX (Mega Drive) 和 MAME 2003-Plus (街机/CPS2)。 - **通过 Bevy 渲染** —— 将所有三种 libretro 像素格式 (0RGB1555, XRGB8888, RGB565) 转换并作为 sprite 纹理上传；标题栏显示实时 FPS/分辨率。 - **通过 cpal 处理音频** —— 核心的采样回调将数据馈入环形缓冲区，再流入 cpal 流。 - **10 面板调试覆盖层** (`--debug`)：带有像素拾取器的帧检查器、hex dump、 VRAM 图块查看器、输入监视器、带有逐帧寄存器增量的 M68K/Z80 CPU 状态、实时的 Capstone 反汇编（断点、单步、运行到地址）、音频控制、事件日志，以及 帧/像素暂停触发器。 - **区域与书签** —— 标记反汇编代码范围，带有 64×48 缩略图的机器状态快照，查看 PC 热力图为你自动发现代码；所有数据都会持久化保存到 你的存档目录旁的 `.regions.json` 伴随文件中。 ## 踩坑纪实 有一段时间，MAME 核心在加载时崩溃，而 Nestopia 却运行得很好 —— 调查过程 （发生时即提交到了此代码库中，`MAME_FFI_INVESTIGATION.md` → `FINAL_MAME_REPORT.md`）发现了一个绝佳的 bug：**我的 FFI 层中几乎每一个 libretro 环境回调 常量都是错的。** 我是按顺序给它们编号的；但规范并非如此。 恰好只有一个常量 (`GET_SYSTEM_DIRECTORY = 9`) 碰巧是对的，并且 Nestopia 足够宽容， 仅靠这个就能蹒跚前行。但 MAME 不行。根据 `libretro.h` 修正这些常量后，街机核心完全焕发了生机 —— 这是一个生动的教训，说明了宽容的对端 如何隐藏了一个损坏的协议。 ## 构建与运行 ``` cargo build --release # NES cargo run --release -- --core ./nestopia_libretro.dylib --rom ./game.nes # Arcade，且 debugger 已打开 cargo run --release -- --core ./mame2003_plus_libretro.dylib --rom ./game.zip --debug ``` | 标志 | 默认值 | 描述 | |------|---------|-------------| | `--core ` | 必填 | libretro 核心动态库 (`.dylib`/`.so`/`.dll`) | | `--rom ` | 必填 | ROM / 内容文件 | | `--scale ` | `3` | 整数窗口缩放比例 | | `--save-dir ` | `.` | SRAM / 伴随文件目录 | | `--system-dir ` | `.` | BIOS 目录 | | `--fullscreen` | 关 | 全屏 | | `--no-audio` | 关 | 禁用音频 | | `--debug` | 关 | 启动时打开调试覆盖层 | 输入：方向键 → D-pad，Z/X/A/S → B/A/Y/X，Q/W → L/R，Enter → Start，Shift → Select。 ## 技术栈 Rust 2021 · [Bevy](https://bevyengine.org/) (窗口/渲染) · `bevy_egui` (调试 UI) · [cpal](https://github.com/RustAudio/cpal) (音频) · `libloading` (核心 FFI) · [Capstone](https://www.capstone-engine.org/) (M68K 反汇编，约 0.5 ms/帧) · `clap` · `serde`。架构深度解析详见 [ARCHITECTURE.md](ARCHITECTURE.md)。 ## 诚实的局限性 `RETRO_ENVIRONMENT_GET_VARIABLE` 尚未实现（需要选项的核心可能会出现异常）， 仅接入了 0 号控制器端口，并且没有存档状态、倒带或作弊功能。它首先是一个 调试仪器，其次才是一个日常使用的模拟器。 — Frank Korf · [fkorf.com](https://fkorf.com)

标签：libretro, Rust, 云资产清单, 可视化界面, 游戏开发, 网络流量审计, 逆向工程, 通知系统