yuna0x0/murder-unpack
GitHub: yuna0x0/murder-unpack
专为 Murder Engine 游戏设计的逆向与恢复工具，解包、反编译与资源提取一体化。
Stars: 1 | Forks: 0
# murder-unpack
逆向工程导出的 [Murder Engine](https://github.com/isadorasophia/murder) 游戏，还原为可在编辑器中打开的项目。提取精灵、对话、世界数据等。
## 功能特性
- **项目恢复** — 从导出的游戏重建 Murder Engine 编辑器项目
- **C# 反编译** — 通过捆绑的每类型反编译器（ilspycmd 回退）从托管单文件程序包中完整恢复源代码
- **C# 存根生成** — 备用方案：从打包的 JSON 数据自动生成类型化的 C# 类（适用于 NativeAOT 游戏）
- **每游戏修复** — 自动检测反编译器产生的特定问题并应用可扩展注册表的修复
- **资源提取** — 将 `.gz` 数据文件解包为独立的 JSON 资产
- **精灵提取** — 从纹理图集切片中提取单个精灵并保存为 PNG
- **对话导出** — 重建 `.gum` 脚本并导出为 Markdown
- **本地化导出** — 导出与 Murder 编辑器格式匹配的本地化 CSV 文件
- **引擎版本检测** — 通过游戏配置指纹自动检测引擎版本
- **二进制分析** — 检测 .NET 部署格式（NativeAOT、单文件、自包含）
- **重新打包** — 将修改后的资源重新打包为 `.gz` 格式
- **插件系统** — 通过 `.py` 文件或 pip 安装的可插包进行扩展
## 快速开始
### 要求
- Python 3.11+
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
- Git（用于克隆引擎）
- .NET 8 SDK（用于构建恢复的项目和捆绑的反编译器）
### 安装
```
# 使用 uv（推荐）
uv tool install murder-unpack
# 或从源代码安装
git clone https://github.com/yuna0x0/murder-unpack.git
cd murder-unpack
uv sync
```
### 用法
```
# 显示游戏信息和检测到的引擎版本
murder-unpack info "path/to/game"
# 提取所有数据、精灵、对话和本地化
murder-unpack extract-all "path/to/game" output/
# 恢复为完整编辑器项目
murder-unpack recover "path/to/game" recovered/
# 使用可选过滤器列出资源
murder-unpack list-assets "path/to/game" --type WorldAsset
```
## 命令
| 命令 | 描述 |
|------|------|
| `info` | 显示游戏信息、资源数量、检测到的引擎版本 |
| `extract-all` | 完整提取：数据、精灵、对话、本地化 |
| `extract-data` | 将所有 `.gz` 数据文件导出为纯 JSON |
| `extract-sprites` | 从图集切片中提取精灵为 PNG |
| `extract-dialogue` | 将对话导出为 `.gum` 脚本、Markdown 或两者 |
| `list-assets` | 列出资源（支持 `--type` 和 `--name` 过滤） |
| `decode-qoi` | 将单个 QOI 图像转换为 PNG |
| `recover` | 完整编辑器项目恢复 |
| `engine-versions` | 列出可用的 Murder Engine 分支与标签 |
| `repack` | 将修改后的资源重新打包为 `.gz` 格式 |
| `analyze-binary` | 检测 .NET 格式、提取类型并反编译 |
| `plugins` | 列出已加载的插件与插件目录 |
### 恢复选项
```
murder-unpack recover "path/to/game" recovered/ \
--engine-version rel/11.0 \ # Override auto-detected version
--game-name MyGame \ # Project name (auto-detected)
--engine-path /path/to/murder # Use existing engine clone
--skip-engine \ # Don't clone engine
--no-stubs \ # Skip C# stub/decompilation
--decompile-timeout 1200 # Decompilation timeout (default: 600)
--game-fix neverway # Per-game fix (auto-detected, 'none' to skip)
```
## 每游戏修复
反编译的代码有时包含无法通用修复的游戏特定问题（丢失的元组元素名称、只读字段赋值、重复的局部函数）。修复注册表会自动检测游戏并应用已知修复。
检测依据包括：程序集名称、游戏命名空间、Steam App ID 或游戏配置的 `$type`。
### 为新游戏添加修复
创建 `murder_unpack/fixes/my_game.py`：
```
from murder_unpack.fixes import GameFix, Replacement
FIX = GameFix(
id="my-game",
name="My Game",
assembly_names=["MyGame"],
steam_app_ids=["123456"],
replacements=[
Replacement(
file_glob="**/SomeFile.cs",
old="broken code",
new="fixed code",
description="CS1234: description of the issue",
),
],
)
```
在 `murder_unpack/fixes/__init__.py` 中注册：
```
def _load_builtin_fixes() -> None:
from murder_unpack.fixes import my_game
_registry.register(my_game.FIX)
```
或通过插件注册：
```
def register(registry):
from murder_unpack.fixes import get_registry
get_registry().register(my_fix)
```
## 插件系统
插件通过自定义资源处理器、提取器、命令和钩子扩展 murder-unpack。
**即时插件** — 将 `.py` 文件放入 `~/.murder-unpack/plugins/` 或 `./plugins/`：
```
# plugins/my_plugin.py
def register(registry):
registry.asset_handlers["my_handler"] = MyHandler()
class MyHandler:
name = "my_handler"
asset_types = ["Custom.Assets.MyAsset"]
def export(self, asset, output_path):
output_path.write_text(str(asset))
```
**可 pip 安装的插件** — 在 `pyproject.toml` 中使用入口点：
```
[project.entry-points."murder_unpack.asset_handlers"]
my_handler = "my_plugin:MyHandler"
[project.entry-points."murder_unpack.commands"]
my_cmd = "my_plugin.cli:my_command"
```
**可用扩展点：** `asset_handlers`、`extractors`、`commands`、`hooks`（`pre_extract`、`post_extract`、`pre_recover`、`post_recover`）
## 限制
### C# 源代码恢复
- **单文件托管程序包** — 通过捆绑的反编译辅助程序进行完整源代码恢复（带超时机制的每类型反编译）。回退到 ilspycmd，再回退到存根生成。
- **NativeAOT 二进制文件** — 无法反编译。恢复过程生成用于编译的 C# 存根，但不含实际行为。
在完整反编译模式下，恢复过程直接使用反编译后的游戏类，并应用有针对性的兼容性修复：`init` → `set`（用于引发 CS8852 错误的引擎类型，通过试构建检测）、移除类字段上的 `readonly` 以支持 JSON 反序列化，以及为基于字符串的枚举键使用 `JsonStringEnumConverter`。
### 引擎版本检测
覆盖 **rel/3.6 到 rel/11.0**。部分版本范围无法区分（rel/8.0–10.0 默认归为 rel/10.0）。可使用 `--engine-version` 手动覆盖。
### 对话重建
从编译后的对话图重建 `.gum` 脚本属于尽力而为。语义内容得以保留，但原始格式可能有所不同。
## 开发
```
git clone https://github.com/yuna0x0/murder-unpack.git
cd murder-unpack
uv sync
```
## 许可证
[MIT](LICENSE) - yuna0x0
标签：CSV 导出, C# 反编译, Decompile, Gum 脚本, ILSpy, Murder Engine, NativeAOT, .NET 逆向, Python 工具, Recover, Repack, Sprite 提取, Unpack, URL提取, 二进制分析, 云安全运维, 反编译, 对话导出, 本地化导出, 游戏修复, 游戏开发工具, 游戏数据提取, 游戏编辑, 游戏资产提取, 游戏逆向, 纹理图集, 解包, 资源恢复, 资源管理, 逆向工具, 逆向工程工具, 重打包, 项目恢复