wesellis/genesis-rom-workshop

# Genesis ROM Workshop 一个用于分析和提取 Sega Genesis/Mega Drive ROM 文件中资源的 Python 工具包。 [](https://python.org) [](LICENSE) [](https://github.com/wesellis/genesis-rom-workshop/stargazers) [](https://github.com/wesellis/genesis-rom-workshop/commits) ## 概述 Genesis ROM Workshop (GRW) 是一个用于处理 Sega Genesis ROM 文件的工具集合。它可以提取调色板、文本字符串和其他资源，以进行分析或修改。本项目旨在用于教育目的、游戏保存研究以及翻译项目。 **✨ 全新！** 现已包含专业的图形渲染功能 - 将 Genesis 图块提取并查看为 PNG 图像！ ## 功能 - **调色板提取**：从 ROM 文件中提取调色板 - **调色板预览图像**：✨ 全新！将调色板导出为可视化的 PNG 图像 - **图形渲染**：✨ 全新！渲染 Genesis 图块以生成可查看的 PNG 文件 - **图块表创建**：✨ 全新！创建专业的精灵图 - **文本提取**：查找并导出文本字符串 - **资源分析**：基础的 ROM 结构分析 - **Hex 编辑工具**：简单的十六进制查看器和编辑器 - **资源管理**：组织提取出的资源 - **批处理**：处理多个 ROM 文件 ## 要求 - Python 3.8 或更高版本 - 对 ROM 文件结构有基本了解 - 用于分析的 ROM 文件（不包含在内） ## 安装说明 ``` git clone https://github.com/wesellis/genesis-rom-workshop.git cd genesis-rom-workshop pip install -r requirements.txt ``` **图形渲染要求：** ``` # palette 预览和 tile 渲染所需 pip install Pillow ``` ## 图形渲染 ✨ 全新！ 该工具包现已包含专业的图形渲染功能！提取 Genesis 图形并**将其作为实际的 PNG 图像查看**，而不是原始二进制数据。 ### 快速开始：图形演示 ``` # 运行完整的 graphics demo python examples/example_graphics_rendering.py your_rom.bin ``` 这将创建： - **调色板预览图像** - 查看实际颜色，而不是十六进制值 - **渲染的图块表** - 专业的精灵图，就像精灵提取工具一样 - **单独的图块** - 带有可选网格覆盖的像素级完美预览 ### 您将获得 **之前（旧版本）：** - ❌ 原始的 `.bin` 文件（无法读取） - ❌ JSON 调色板文件（难以直观显示颜色） - ❌ 需要外部工具才能查看图形 **之后（当前版本）：** - ✅ 您可以在任何图像查看器中打开的 PNG 图像 - ✅ 可视化的调色板颜色条 - ✅ 专业的图块表 - ✅ 用于分析的像素网格 - ✅ 一切都包含在内！ 有关完整文档，请参阅 [GRAPHICS_FEATURES.md](docs/GRAPHICS_FEATURES.md)。 ## 用法 ### 基础分析 ``` # 分析 ROM 文件 python grw_pipeline.py analyze game.bin --output-dir ./analysis # 仅提取 palette python grw_pipeline.py extract-palettes game.bin --format png # 提取文本字符串 python grw_pipeline.py extract-text game.bin --output text.json ``` ### 使用工具 每个工具目录都包含专门的实用程序： - **palette_editor**：提取和修改调色板 - **text_extractor**：查找和导出文本字符串 - **hex_editor**：查看和编辑 ROM 字节 - **asset_extractor**：提取图形和资源 - **rom_analyzer**：分析 ROM 结构 ### 示例：带有可视预览的调色板提取 ``` from tools.palette_editor import PaletteEditor editor = PaletteEditor() palettes = editor.extract_palettes('sonic.bin') # 导出为 JSON editor.export_palettes(palettes, 'palettes/') # NEW! 导出为可视的 PNG 图像 editor.export_palette_as_image(palettes[0], 'palette_preview.png') editor.export_all_palettes_as_images(palettes, 'palettes/') ``` ### 示例：图形渲染 ``` from tools.palette_editor import PaletteEditor from tools.asset_extractor import AssetExtractor # 提取 palette editor = PaletteEditor() palettes = editor.extract_palettes('sonic.bin') # NEW! 提取并将 graphics 渲染为可查看的 PNG 图像 extractor = AssetExtractor() result = extractor.extract_and_render_graphics( 'sonic.bin', palettes[0], max_tiles=256 ) # 创建专业的 tile sheet PNG！ print(f"Tile sheet created: {result['sheet_file']}") ``` ### 示例：文本提取 ``` from tools.text_extractor import TextExtractor extractor = TextExtractor() strings = extractor.find_text('game.bin') extractor.export_strings(strings, 'text.json') ``` ## 项目结构 ``` genesis-rom-workshop/ ├── grw_pipeline.py # Main CLI interface ├── requirements.txt # Python dependencies ├── LICENSE # MIT License ├── README.md # This file │ ├── tools/ # Core toolkit modules │ ├── palette_editor/ # Palette extraction tools │ ├── graphics_renderer.py # ✨ Graphics rendering engine │ ├── text_extractor/ # Text finding tools │ ├── hex_editor/ # Hex editing utilities │ ├── asset_extractor/ # Asset extraction with rendering │ ├── rom_analyzer/ # ROM analysis tools │ ├── asset_manager/ # Asset organization │ └── security_utils.py # Security validation │ ├── examples/ # Example scripts and demos │ ├── example_graphics_rendering.py # Graphics demo │ ├── example_palette_extraction.py │ ├── example_text_extraction.py │ └── example_hex_editing.py │ ├── tests/ # Test suites │ ├── test_graphics.py # Graphics rendering tests │ └── test_tools.py # Core tools tests │ ├── docs/ # Documentation │ ├── GRAPHICS_FEATURES.md # Graphics rendering guide │ ├── USAGE_GUIDE.md # Usage instructions │ ├── API_REFERENCE.md # API documentation │ ├── SECURITY_HARDENING.md # Security documentation │ └── ... │ └── workspace/ # Working directory ├── backups/ # ROM backups ├── exports/ # Extracted assets └── projects/ # Project files ``` ## 技术细节 ### 依赖项 - **Pillow (PIL)**：✨ 图形渲染和调色板图像导出所必需 - **NumPy**：二进制数据处理（可选） - **Python 标准库**：struct、pathlib、json、hashlib ### 图形格式支持 该工具包包含一个专业的 4 位平面图形解码器，用于 Genesis 图块： - **图块格式**：8x8 像素，每个图块 32 字节 - **颜色深度**：4 位（每个调色板 16 种颜色） - **编码**：平面位平面格式（Genesis 标准） - **输出**：具有可配置缩放比例（1 倍到 16 倍）的 PNG 图像 - **功能**：网格覆盖、图块表、调色板渲染 ### ROM 文件支持 - Sega Genesis/Mega Drive (.bin, .gen, .smd) - Sega Master System (.sms) - Game Gear (.gg) - Sega 32X (.32x) 注意：ROM 文件格式检测是基础性的，可能不适用于所有 ROM 变体。 ## 已知限制 - 不同游戏之间的 ROM 结构差异很大 - 文本检测可能会产生误报 - 调色板提取假定为标准的 VDP 格式 - 不支持压缩数据 - 关于 ROM 内部结构的文档有限 - 需要手动验证结果 ## 用例 - **ROM 修改**：提取和查看图形、修改调色板、创建精灵图 - **游戏保存**：为存档目的记录 ROM 结构和资源 - **翻译项目**：为本地化工作提取文本 - **精灵提取**：创建专业的精灵图和纹理包 - **研究**：研究游戏开发技术和像素艺术 - **教育**：学习 ROM 文件结构、图形编码和游戏设计 - **资源分析**：检查调色板、图块布局和图形技术 ## 法律声明 此工具仅供教育和研究目的使用。 **重要提示**： - 此工具不包含 ROM 文件 - 用户必须拥有其分析的任何 ROM 的合法副本 - 请遵守您所在司法管辖区的版权法 - 请勿分发受版权保护的 ROM 文件 - 此工具仅供分析，不得用于盗版 ROM 修改和分发在您所在的国家/地区可能是非法的。请负责任且合乎道德地使用。 ## 文档 ### 用户文档 - **[GRAPHICS_FEATURES.md](docs/GRAPHICS_FEATURES.md)**：✨ 全新！完整的图形渲染指南 - **[USAGE_GUIDE.md](docs/USAGE_GUIDE.md)**：详细的用法说明和示例 - **[API_REFERENCE.md](docs/API_REFERENCE.md)**：完整的 API 文档 ### 项目文档 - **[WEEK1_IMPROVEMENTS_COMPLETE.md](docs/WEEK1_IMPROVEMENTS_COMPLETE.md)**：图形渲染实现细节 - **[SECURITY_HARDENING.md](docs/SECURITY_HARDENING.md)**：安全功能和最佳实践 - **[CHANGELOG.md](docs/CHANGELOG.md)**：版本历史和更新 - **[CONTRIBUTING.md](docs/CONTRIBUTING.md)**：贡献指南 - **[ROADMAP.md](docs/ROADMAP.md)**：未来开发计划 - **[SECURITY.md](docs/SECURITY.md)**：安全政策 ## 许可证 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。 ## 免责声明 这是一个个人的教育项目。提供的工具按“原样”提供，不保证准确性或可靠性。不同游戏之间的 ROM 文件结构差异很大，可能需要手动验证结果。 作者不纵容盗版或侵犯版权行为。此工具仅用于对合法获取的 ROM 文件进行研究、保存和教育目的。 ## 作者 Wesley Ellis ## 项目状态与路线图 ### 正常运行的功能 ✅ **核心功能：** - ✅ 调色板提取和修改（完整实现） - ✅ 将调色板导入/导出为 JSON 格式 - ✅ **全新！** 调色板预览图像（可视化 PNG 导出） - ✅ **全新！** 图形图块渲染（4 位平面解码） - ✅ **全新！** 图块表创建（专业的精灵图） - ✅ **全新！** 用于像素分析的网格覆盖 - ✅ 支持 ASCII 的文本提取 - ✅ 文本替换和翻译工作流 - ✅ 翻译文件的生成和应用 - ✅ 带有地址/Hex/ASCII 显示的十六进制查看 - ✅ 十六进制编辑和字节写入 - ✅ ROM 比较和补丁创建 - ✅ ROM 分析（头部验证、校验和） - ✅ 资源提取（图形、图块映射、精灵） - ✅ 资源组织和清单生成 - ✅ 交互式 CLI 界面 - ✅ 所有工具模块均已使用 __init__.py 正确打包 **工具模块 - 全部实现：** - ✅ **palette_editor/**：完整的调色板提取、修改、颜色交换和 PNG 导出 - ✅ **graphics_renderer/**：✨ 全新！4 位平面解码和图块渲染 - ✅ **text_extractor/**：文本查找、翻译导出和 ROM 修补 - ✅ **hex_editor/**：十六进制查看、编辑、搜索和 ROM 比较 - ✅ **asset_extractor/**：带有渲染支持的图形图块提取 - ✅ **rom_analyzer/**：头部分析、校验和验证、熵计算 - ✅ **asset_manager/**：精灵/音频提取、项目组织 ### 已知限制 **仍然缺失：** - ⚠️ **GUI**：仅限命令行（未实现图形界面） - ⚠️ **ROM 格式**：主要以 Genesis 为主，对 SMS/Game Gear/32X 的支持有限 - ⚠️ **压缩数据**：不支持压缩的 ROM 数据（Nemesis/Kosinski） - ⚠️ **自动化测试**：存在图形测试套件，需要完整的 pytest 覆盖率 - ⚠️ **精灵组装**：未实现自动多图块精灵合成 - ⚠️ **音频播放**：仅提取音频数据，无播放功能 **有待增强的领域：** - 为非 ASCII 文本（日文 ROM）提供更好的编码支持 - 更复杂的图形格式检测 - 自动调色板位置检测 - 压缩算法支持（Nemesis、Kosinski 等） - 完整的 .smd 格式支持改进 ### 最新添加（最新更新） **第 1 周图形渲染功能** ✨（最新）： 1. ✅ **graphics_renderer.py** - 全新模块！4 位平面图块解码 2. ✅ **调色板预览图像** - 将调色板导出为可视化的 PNG 文件 3. ✅ **图块渲染** - 将 Genesis 图块渲染为可查看的 PNG 图像 4. ✅ **图块表创建** - 专业的精灵图生成 5. ✅ **网格覆盖** - 带有网格覆盖支持的像素分析 6. ✅ **AssetExtractor 集成** - 一步提取并渲染 7. ✅ **test_graphics.py** - 全面的测试套件（3/3 测试通过） 8. ✅ **GRAPHICS_FEATURES.md** - 完整的文档 有关详细的文档和示例，请参阅 [GRAPHICS_FEATURES.md](docs/GRAPHICS_FEATURES.md)。 **之前的更新 - 核心工具实现：** 1. ✅ **palette_editor.py** - 完整的调色板提取、修改、JSON 导入/导出 2. ✅ **text_extractor.py** - 全面的文本提取和翻译工作流 3. ✅ **asset_manager.py** - 带有启发式检测的精灵/音频提取 4. ✅ **hex_editor.py** - 完整的十六进制查看、编辑、搜索和修补 5. ✅ **rom_analyzer.py** - 头部解析、校验和验证、统计信息 6. ✅ **asset_extractor.py** - 图形图块、图块映射和精灵提取 7. ✅ **所有 __init__.py 文件** - 正确的 Python 包结构 8. ✅ **security_utils.py** - 全面的安全强化 ### 未来增强功能 未来开发的优先功能： 1. **压缩支持** - Nemesis、Kosinski、Enigma 解压缩（第 2-3 周） 2. **精灵组装** - 自动多图块精灵合成 3. **图块映射渲染** - 完整的场景/关卡渲染 4. **GUI 应用程序** - 用户友好的图形界面 5. **测试套件** - 所有模块的全面 pytest 覆盖 6. **音频播放器** - YM2612/PSG 播放功能 7. **多 ROM 格式** - 更好的 SMS/Game Gear/32X 支持 8. **高级文本编码** - Shift-JIS 和其他字符集 9. **调色板检测** - 自动调色板位置查找 ### 贡献 欢迎贡献！带有图形渲染的核心工具包已经完成，但仍有增强的空间： - 扩大所有模块的测试覆盖率 - 使用 tkinter 或 PyQt 实现 GUI - 添加压缩/解压缩支持（Nemesis、Kosinski） - 实现从多个图块组装精灵 - 添加图块映射渲染功能 - 添加音频播放功能（YM2612/PSG） - 通过更多示例增强文档 -添加对更多 ROM 格式的支持 **注意**：本项目旨在学习 ROM 文件结构和游戏保存。请始终遵守版权法并使用合法获取的 ROM 文件。README 中描述的许多功能已部分实现或已计划在未来的开发中实现。

标签：Python, 世嘉创世纪, 云资产清单, 无后门, 游戏ROM, 资产提取, 逆向工具, 逆向工程