# 资源还原工具说明

## 现在主要用这几个文件

- `RestoreGameAssets.bat`
  - 主入口。
  - 双击后默认优先启动 Qt5 GUI。
  - 如果没装 `PyQt5`，会自动退回命令行版。
  - 也支持把游戏解压目录直接拖到这个 `.bat` 上启动。

- `RestoreGameAssetsGUI.py`
  - Qt5 图形界面。
  - 适合平时跑整包、换同类游戏、看实时日志、保存配置档。

- `RestoreGameAssets.py`
  - 实际执行还原的核心脚本。
  - 支持本地 bundle、热更新 bundle、`gamecaches`、`beeplay`、ASTC 转 PNG、Spine 资源还原、错误 PNG 修复。

- `CleanRestoreBackups.bat`
  - 删除旧备份目录 `pack/restored/_partial_backups`。

## GUI 现在能做什么

- 自动识别这类项目常见目录：
  - `assets/assets`
  - `files/GameAssets/assets`
  - `files/gamecaches`

- 支持手动指定：
  - APK 本体解压目录
  - 热更新 `GameAssets` 目录
  - 热更新 `gamecaches` 目录
  - 输出目录
  - `astcenc` 路径
  - Spine 配置 json

- 支持保存配置档到 `restore_profiles`
  - 每个游戏可以存一套“规则 + 路径 + 特殊 Bundle 名”。
  - 以后跑同类游戏时，直接载入旧配置再微调即可。

- 支持实时日志框
  - 标准输出和报错会实时显示。
  - 每次运行也会自动保存到 `restore_logs`。
  - 如果后面遇到新加密或新目录结构，你把日志给我，我就能更快定位和补脚本。

- 支持拖拽目录
  - 可以把游戏根目录直接拖进 GUI 窗口。
  - 也可以拖 `assets/assets`、`files/GameAssets/assets`、`files/gamecaches` 这类子目录进去，工具会自动往上反推项目根目录。

## 哪些东西能跨游戏复用，哪些不能

### 能复用

- 目录识别方式
- 解包流程
- `beeplay` 解密流程
- XOR key 规则
- 特殊 Bundle 名
- Spine / Cocos bundle 的还原逻辑
- ASTC 转 PNG 的流程

### 不能直接通用

- 某个具体游戏的 `uuid -> logical path` 映射
- 某个具体游戏的缓存清单内容
- 某个具体游戏单独的 Spine 配置 json

也就是说：

- `uuid` 本身不是通用字典。
- 但“这个游戏该怎么解、哪些 key、哪些目录、哪些特殊规则”是可以沉淀成配置档复用的。

## 同公司换皮游戏能不能直接用

通常可以先直接试。

如果它们还是同一套 Cocos 资源结构，并且还在用接近的：

- `assets/assets`
- `files/GameAssets/assets`
- `files/gamecaches`
- `beeplay`
- 相近的 XOR key / Spine Bundle 名

那这套工具大概率可以直接跑，或者只需要在 GUI 里改少量配置。

## 推荐使用方式

1. 双击 `RestoreGameAssets.bat`
2. 也可以直接把游戏解压目录拖到 `RestoreGameAssets.bat`，或者拖进 GUI 窗口
3. 在 GUI 里点“自动识别”
4. 检查：
   - APK assets 目录
   - 热更新 `GameAssets` 目录
   - 热更新 `gamecaches` 目录
   - 输出目录
5. 必要时调整：
   - `AnimationSpine` 名
   - `Spine` 缓存名
   - `beeplay` 签名
   - XOR key
6. 点“开始还原”
7. 看日志框和 `restore_logs`
8. 确认结果没问题后，再决定要不要执行 `CleanRestoreBackups.bat`

## 默认输出位置

- 还原结果：`pack/restored`
- 旧备份：`pack/restored/_partial_backups`
- 配置档：`restore_profiles`
- 运行日志：`restore_logs`

## 命令行模式

如果你不想开 GUI，也可以直接跑：

```bat
RestoreGameAssets.bat --cli
```

或者：

```bat
py -3 RestoreGameAssets.py
```

## 说明

- 全量还原本来就比较久，尤其是 bundle 和 `gamecaches` 很多的时候。
- 如果中途异常中断，脚本下次启动会自动清理遗留的 `_xxx_stage` 临时目录。
- 如果官方后续更新，但资源结构和加密规则没大改，通常直接重新跑一遍就行。
