desintegrathor/VC_Scripter
GitHub: desintegrathor/VC_Scripter
面向《越共》游戏的AI增强型脚本反编译与开发工具链，支持字节码与C源码双向转换及场景文件解析。
Stars: 1 | Forks: 0
# VC Scripter
AI 驱动的《越共》(Vietcong, 2003) 逆向工程与脚本开发环境。
## 这是什么？
这是一个用于处理《越共》 游戏脚本的开发环境。克隆此代码仓库，在其中运行 AI 编程代理，代理会自动连接到 MCP 服务器，从而直接读取和分析游戏文件。
该仓库包含反编译器（`.scr` 字节码 → C 源码）、编译器（C 源码 → `.scr` 字节码）、场景文件解析器（`.sco`）、SDK 头文件以及原始参考脚本。这些工具共同为 AI 代理提供了逆向工程、修改和创建《越共》游戏脚本所需的一切。
## 你可以用它做什么
你只需提供解包后的游戏文件（`.scr` 脚本、`.sco` 场景文件）以及你拥有的任何参考脚本。AI 代理会处理剩下的所有工作 —— 反编译、分析、编写代码和编译。
## 前置条件
- **Python 3**（已在 3.10+ 版本上测试）
- **一个 AI 编程代理** — 推荐使用 [Claude Code](https://claude.ai/code)（通过 `.mcp.json` 自动检测 MCP）。Cursor、Windsurf 和其他支持 MCP 的代理也可以使用。
- **解包后的《越共》游戏文件** — 你需要游戏安装目录中的 `.scr` 和 `.sco` 文件
## 开始使用
```
# 克隆 repo
git clone https://github.com/pocketrice/VC_Scripter.git
cd VC_Scripter
# 安装 Python 依赖
pip install -r requirements.txt
# 在此目录启动你的 AI agent
# Claude Code 示例：
claude
# 然后只需询问：
# "打开 my_game_folder/ 中的 LEVEL.SCR 并反编译"
# "此脚本有哪些函数？"
# "重写 respawn 逻辑以使用这些新的 spawn points"
```
`.mcp.json` 文件已预配置好 —— Claude Code 和其他支持 MCP 的代理将自动启动工具服务器。
## 包含内容
| 目录 | 内容说明 |
|-|-|
| `vcdecomp/` | 反编译器 — 将 `.scr` 字节码转换为可读的 C 源码 |
| `vcdecomp/compiler/` | 原始 SCMP 编译器工具链 (SPP → SCC → SASM)，用于将 C 代码编译回 `.scr` |
| `vcdecomp_mcp/` | MCP 服务器，向 AI 代理暴露反编译器工具 |
| `sco_parser/` | `.sco` 场景文件解析器 + 供 AI 代理使用的 MCP 服务器 |
| `SDK/` | 《越共》脚本 SDK — `SC_GLOBAL.H`、`SC_DEF.H`、完整 SDK 文档 |
| `original-resources/` | 示例脚本 (`.c`)、头文件 (`.h`)、包含文件 (`.inc`)、机器人配置 (`.CXX`) |
| `.mcp.json` | 预配置的 MCP 服务器定义（由 Claude Code 自动检测） |
## MCP 工具
两个 MCP 服务器让 AI 代理能够直接访问游戏文件内部结构。完整工具参考请参见 [agents.md](agents.md)。
**vcdecomp-mcp** — 脚本字节码分析：
- 打开 `.scr` 文件并列出函数、全局变量、字符串、外部 API 调用
- 将单个函数反编译为 C 代码
- 查看反汇编、SSA 形式、基本块、调用图
- 重命名变量/函数、覆盖类型、添加注释
- 交叉引用谁调用了什么
**sco-parser** — 场景文件分析：
- 打开 `.sco` 文件并浏览节点层级结构
- 按名称或类型查找生成点、路径点、对象
- 提取 AI 导航图
- 获取实体引用、光照、元数据
- 将节点名称与脚本中的 `SC_NOD_Get()` 调用进行交叉引用
## CLI 使用
```
# 将脚本反编译为 C 源代码
py -3 -m vcdecomp structure script.scr > output.c
# 显示脚本信息（entry point、大小、计数）
py -3 -m vcdecomp info script.scr
# 反汇编为可读的汇编代码
py -3 -m vcdecomp disasm script.scr > output.asm
# 将 C 源代码编译回 .scr bytecode
# 将你的 .c 文件复制到 vcdecomp/compiler/，然后：
py -3 compile_simple.py
# 启动 GUI
py -3 -m vcdecomp gui
```
## 批量反编译
```
# PowerShell
Get-ChildItem *.scr | ForEach-Object {
py -3 -m vcdecomp structure $_.FullName > "$($_.BaseName)_decompiled.c"
}
# Bash
for file in *.scr; do
py -3 -m vcdecomp structure "$file" > "${file%.scr}_decompiled.c"
done
```
## 注意：反编译并非 100% 可靠
反编译器生成的是尽力而为的重构代码。某些内容可能出错或缺失 —— 变量类型不正确、表达式混乱、控制流丢失。**务必对照反汇编代码检查反编译输出。** 反汇编（`scr_disasm` 或 `py -3 -m vcdecomp disasm`）是字节码的忠实呈现，始终是正确的。
你可能还需要使用 `scr_set_type` 覆盖变量类型以获得正确的反编译输出 —— 反编译器的类型推断并不完整，有时会猜测错误。
## 已知限制
- **类型推断**不完整 —— 某些变量仍保留为 `dword`（未知类型），需使用 `scr_set_type` 覆盖
- **宏** 会丢失 —— 预处理器在编译前已将其展开
- **全局变量检测** 基于启发式算法，可能不准确
- **复杂控制流** —— 某些嵌套循环或 switch 语句可能无法完美重构
- **编译器** 需要 Windows（通过 WSL 或原生方式使用原始 Win32 可执行文件）
标签：LLM Agent, MCP协议, Mod工具, Python, Vietcong, 云安全监控, 云资产清单, 人工智能辅助开发, 代码生成, 反编译器, 场景解析, 无后门, 渗透测试工具, 游戏修改, 游戏脚本, 第一人称射击游戏, 编译原理, 自动化编程, 软件开发套件, 逆向工程, 遗留系统, 静态分析