native-gb/gbre

# GBRE GBRE 是一个研究与互操作性工具包，用于分析用户提供的 Game Boy 软件，并开发原生重实现。 它提供了 ROM 范围数据模型、source-map 生成、HTML 覆盖率地图、 VS Code 导航、确定性模拟器控制、语义场景以及 原生/原始对比基础设施。如果存在完整的反编译，它将非常有用，但并非必需： 一个新的清单可以从一个未知的 ROM 大小范围开始，并通过手动分析、trace、资源 检测器和部分反编译来积累证据。 GBRE 有意与每个游戏移植版和每个 特定游戏的研究数据库保持为独立的仓库。 ## 仓库边界 ``` GBRE/ generic tools, schemas, editor support native-gb-/ public native C++ port native-gb--re/ private game map, scenarios, oracle glue ``` 公共移植版是唯一活跃的 C++ 工作区。`-re` 仓库包含 注释和可重现的证据；它决不能成为移植版的 fork。 GBRE 包含可复用的机制。在 adapter API 被泛化期间，一些早期的 Tetris 专用 adapter 仍保留在此处， 但不包含 Tetris 清单和场景 数据库。 ## 核心工具 - `tools/build_rom_map.py` 从语义 清单和任何可用的证据地图构建一个无间隙的字节清单。 - `tools/build_rgbds_source_map.py` 将发出的 RGBDS 源代码行映射到确切的 ROM 范围，同时验证插桩不会更改重建的 ROM。 - `tools/build_report.py` 生成本地交互式 ROM 热力图。 - `tools/gbre.py` 按地址、单元或源执行命令行查找。 - `tools/gbre_scenario.py` 验证并运行外部场景数据库。 - `tools/gbre_live.py` 提供原生开发 UI 使用的面向行的协调器。 - `editor/vscode-gbre` 添加了 CodeLens 以及原生代码、 参考源代码和 ROM 范围之间的跳转导航。 ## 运行测试 ``` ./scripts/test.sh ``` 通用测试套件无需 ROM 即可运行。当 `../native-gb-tetris-re` 和被忽略的本地输入存在时， Tetris 集成检查将变为可用。 ## 安装编辑器导航 ``` ./scripts/install-vscode-navigation.sh ``` 每个原生工作区配置四个路径：其清单、ROM 地图、参考 根目录和 HTML 报告。这些路径通常指向相应的私有 `-re` 同级目录。`F12` 或 Ctrl-click 会跟随 `GBRE: game.unit` 标记；专用 命令可跳转到汇编、原生代码或热力图。 ## 在没有反编译的情况下启动游戏 创建一个包含 ROM 大小、接受的哈希值和初始 未知单元的清单。仅使用该清单运行 `build_rom_map.py` 就已经可以生成 完整的清单。使用来自以下各项的 evidence-span CSV 文件对其进行细化： - 卡带标头和指针表分析； - 模拟器执行和内存访问 trace； - 图块、文本、音频、压缩、地图和脚本检测器； - 手动注释或稍后的部分/可重建反编译。 证据和实现是独立的声明。一个原生函数可以 对一个源 范围进行 `implement`、被 `derived_from`、`reference` 或 `verified_against`。密集的现代实现不需要镜像原始的 内存布局。 ## 数据与分发 GBRE 不包含 ROM，也不包含特定游戏的场景数据库。获取的模拟器 和参考仓库、构建、报告、trace、捕获和本地输入 均被忽略。请参阅[仓库与法律模型](docs/repository-and-legal-model.md) 和[公开发布检查清单](docs/public-release-checklist.md)。 ## 许可证 本仓库中的原始源代码在 GPL-3.0-only 下提供。 第三方组件和获取的参考保留其各自的许可证。

标签：C++, Game Boy, Python, ROM分析, 云资产清单, 互操作性, 多模态安全, 数据擦除, 无后门, 游戏开发, 逆向工具, 逆向工程