cruuz/2k-football-mod-tools

# 2K Football Mod 工具 这些工具允许你浏览游戏资源的已解码目录，并替换那些拥有经过验证且独立确认写入路径的资源——包括球衣、肖像、球队艺术、比分栏图像、体育场纹理（包含**球迷、啦啦队、教练、裁判、场务人员、摄像机和边线道具**）、球员名单、文本和音频——然后构建一份可以在模拟器中运行的 mod 副本。 ## 两个编辑器 ### 2K5 Mod Studio — ESPN NFL 2K5 (原版 Xbox) - **完整球队套装** — 每套物理装备包含全部 39 个组件（球衣、护袖、球裤、两个头盔系列、数字 0–9、姓名牌、球队选择卡），HOME/AWAY，支持 GIMP 文件夹/ZIP 往返处理。 - **Stadium Studio** — 包含 477 个场景，23,838 个可编辑的 P8 纹理实例，带有**“仅人物和边线”**过滤器，可单独提取球迷、啦啦队、教练、裁判、场务人员、摄像机/媒体、引座员和边线道具。 - **音频** — 包含全部 850 个独立提示音和全部 53,571 个可播放流式范围（精确插槽替换），并附带基于项目的提示音标签/备注。 - **球员名单** — 包含当前主力球员（姓名 + 球衣号码）和历史球队；可通过通用的光盘球员名单写入器处理替补池的球衣号码。 - **文本** — 跨越 716 个存储库的 20,074 条可编辑字符串。 - 包含肖像、真人面孔、创建球队场地艺术、比分栏/演示艺术。 - 可在 **xemu** 中运行。 ### APF 2K8 Mod Studio — All-Pro Football 2K8 (Xbox 360) - **制服** — 96 个可编辑纹理（球衣/球裤/头盔/护肩）以及共享的 `digital_font` 和 `draft_logo`。 - **球员名单与球员** — 球队显示名称、球员姓名、每位球员的全部 28 项基础评分、精确位置，以及一个 53 行的球员名单规划器。 - **音频** — 全部 47,775 个可单独编辑的 AUDO/AUSB 提示音（通过用户提供的编码器进行精确插槽 XMA1 替换），支持提示音标签/备注和批量文件夹/ZIP 制作。 - 包含场地艺术清单、Stadium Studio 和演示检查器。 - 可在 **Xenia Canary** 中运行。 请参阅 [`docs/mod_editor/2k5_mod_studio_getting_started.md`](docs/mod_editor/2k5_mod_studio_getting_started.md) 和 [`docs/mod_editor/apf2k8_mod_studio_getting_started.md`](docs/mod_editor/apf2k8_mod_studio_getting_started.md) 以获取完整的、有证据支持的功能和边界列表。 ## Beta 状态与诚实声明 这是一个 **beta** 版本。这在这里意味着： - 每个已发布的写入器都经过了**离线验证**：它会重建一份游戏镜像的副本，并由独立的验证器确认仅目标字节发生了更改。 - 还有一部分较小规模的写入器经过了**运行时验证**（可以在运行中的模拟器内看到变化）。 许多写入器虽然经过了离线验证，但尚未在游戏画面中被捕获验证；功能注册表会对每一个进行标记（`PROVED` / `READ ONLY` / `PORTME`）。 - 可执行文件补丁（例如游戏性测试）**仅限模拟器使用** — 它们会使零售签名失效，且不能用于原版硬件。 - 一些高级领域（3D 模型导入、整个音频库的重新打包、战术路线制作、选秀 AI、存档编辑）**尚未完成**，并在 [`docs/product/NFL2K5_COMPLETION_STATUS_AND_WALLS.md`](docs/product/NFL2K5_COMPLETION_STATUS_AND_WALLS.md) 中进行追踪。 ## 环境要求 - **Python 3, PyQt5, Pillow** — 适用于 Linux、Windows 或 macOS。 - **Linux** (Debian/Mint/Ubuntu)： sudo apt install python3 python3-pyqt5 python3-pil - **Windows / macOS** （上面的 `apt` 命令仅适用于 Linux）：从 [python.org](https://www.python.org/downloads/) 安装 Python 3，然后执行： pip install PyQt5 Pillow - 需要一个模拟器来运行你的 mod 游戏： - 运行 ESPN NFL 2K5 使用 **xemu**。 - 运行 All-Pro Football 2K8 使用 **Xenia Canary**。 - 需要你自己合法转储的游戏光盘（一个 `.iso`/XISO 文件，或其解压后的文件夹）。 **平台支持。** **Linux、Windows 和 macOS 都通过了相同的测试套件。** CI 会在所有这三个平台上运行它（基于 Python 3.11 和 3.12），并且每个任务都报告了一致的结果——这六个任务在文件和测试上完全吻合。 **Linux 仍然是测试最充分的平台**：桌面应用程序已经在那里进行了端到端的冒烟测试，而 GUI 尚未在 Windows 或 macOS 上进行过手动驱动测试，因此请将后者视为经过良好测试的核心代码加上一个测试较少的窗口界面。这里有两个具体的限制： - 部分 CI 流程在所有的 CI 运行器上预计都会失败，无论操作系统是什么，因为这个代码库特意没有提供任何游戏数据和生成的报告。 - 捆绑的 `extract-xiso` 提取器**同时**提供 Linux 二进制文件和 Windows `.exe` 版本，它们都是基于相同的内置 2.7.1 源代码构建的，因此无论在哪个系统上，将 `.iso` 交给编辑器都能正常工作。**macOS** 没有提供预编译版本——请在此处将编辑器指向一个**已经解压好的游戏文件夹**，或者自行构建 extract-xiso 并将其传递给 `SourceManager(extract_xiso=...)`。有关确切的构建命令和哈希值，请参阅 `tools/vendor/extract-xiso/BUILDING-THE-BUNDLED-BINARIES.md`。 这三个平台都提供了双击启动器（见 *安装*）。 ## 安装 ### 从发布归档安装（推荐） 1. 从 [Releases](../../releases) 页面下载适用于你所选编辑器的发布归档，并进行校验（在 Windows 上，使用 `certutil -hashfile SHA256` 命令并与 `.sha256` 文件进行对比）： sha256sum -c 2K5-Mod-Studio-*.tar.gz.sha256 # 必须显示 OK 2. 将其解压，然后根据你的平台启动它： - **Linux** — 进行单用户安装（无需 `sudo`）或以便携模式运行： tar -xzf 2K5-Mod-Studio-*.tar.gz cd 2K5-Mod-Studio-*/ ./install.sh # 添加应用菜单快捷方式 + 将命令加入 PATH # 或者，便携模式运行： ./2K5-Mod-Studio.sh - **Windows** — 解压归档，然后双击 **`2K5-Mod-Studio.bat`**。 - **macOS** — 解压归档，然后双击 **`2K5-Mod-Studio.command`**（第一次运行时，请右键点击它并选择 **打开** 以绕过 Gatekeeper）。 每个启动器都会检查是否存在 Python 3、PyQt5 和 Pillow，如果缺少某些内容，会显示一条简单的提示信息。（APF 2K8 Mod Studio 提供了同名的三个启动器，名称为 `APF-2K8-Mod-Studio.sh` / `.bat` / `.command`。） ### 从源码安装 ``` git clone https://github.com//2k-football-mod-tools.git cd 2k-football-mod-tools python3 -m mod_editor --studio # 2K5 Mod Studio # APF 2K8 Mod Studio：参见 docs/mod_editor/apf2k8_mod_studio_getting_started.md ``` ## 使用说明（简版） 1. **加载游戏** → 选择你纯净的 ISO 文件（或其解压后的文件夹）。编辑器会对支持的游戏源版本进行哈希校验和识别；它绝不会修改你的原始文件。 2. **浏览**资源目录。可编辑的资源会显示 **替换** 按钮；只读资源会显示 **检查/导出**。 3. 用你自己的文件（例如尺寸完全一致的 PNG 或 WAV）**替换** 某个资源。编辑器会根据固定分配的契约对其进行验证。 4. **保存** 一个项目（`.2k5mod` / `.apf2k8mod`） — 这是一个便携、易读的计划文件，绝不包含任何游戏字节数据。 5. 将其 **构建** 到一个 **全新的、空白的** 文件夹中。编辑器会将你的游戏源文件复制到那里并应用你的修改；它会拒绝覆盖你的源文件。 6. 在你的模拟器中运行构建好的 `default.xbe` / `default.xex` 文件。 ## 安全性、法律与隐私 - **自备游戏。** 如果没有识别到有效的游戏源，编辑器将拒绝运行，并且永远不会提供、存储或传输任何游戏数据。 - **结构上杜绝零售文件。** 发布的归档文件必须通过一道自动化检查门，该检查会验证它们不包含任何游戏字节数据、已解码的像素/音频、私人路径、符号链接或未声明的文件，此外还会进行一次运行时闭包检查，从干净阶段导入每个已发布的模块。 - **你的源文件是只读的。** 所有输出都会进入一个新创建的文件夹。 - **无遥测。** 绝不进行任何后台数据回传。 - **仅限模拟器的可执行文件补丁。** 任何修改游戏可执行文件的功能都会使零售签名失效，并且仅在指定的模拟器上受支持，绝不适用于原版硬件。 ## 代码库布局 ``` mod_editor/ the editors (core/, gui/, studio/ = 2K5, apf_studio/ = APF) packaging/ release tooling, allowlists, desktop entries, installer tools/ CLI build/verify tools + Ghidra analysis scripts docs/ getting-started guides, capability matrix, research notes tests/ test suite (unittest) ``` 完整的内部研究日志保留在 [`docs/README_full.md`](docs/README_full.md) 中。 ## 许可证 基于 **MIT License** 发布 — 详见 [`LICENSE`](LICENSE)。 [`NOTICE.md`](NOTICE.md) 说明了该许可证*未*授予的权利：它仅适用于这些工具及其源代码，不授予你对任何游戏、游戏数据或商标的任何权利。请使用你自己的合法获取的副本。它还包含了免责零售声明以及有关捆绑的 `extract-xiso` 的署名信息。 发布历史记录请见 [`CHANGELOG.md`](CHANGELOG.md)。 ## Beta 免责声明 本软件按“原样”提供，不提供任何形式的担保。它是一款面向爱好者的进行中 beta 版本，仅用于修改他们合法拥有的游戏。使用风险自负；请务必保留原始游戏文件的备份。

标签：Xbox, 批量测试, 游戏Modding, 游戏模组, 游戏资产编辑器, 跨平台工具, 逆向工具, 逆向工程工具