FOX-cOSMIC/cp2077-mac-mods

# cp2077-mac-mods **将《赛博朋克 2077》的 PC 模组生态引入原生 macOS (Apple Silicon) 移植版** — 首先从 [RED4ext](https://github.com/WopsS/RED4ext) + [TweakXL](https://github.com/psiberx/cp2077-tweak-xl) 开始，使得为 Windows 版本编写的数据/tweak 模组能够在 Mac 上运行。 《赛博朋克 2077》于 2025 年发布了原生 Apple Silicon 版本。它运行得非常出色 — 但社区所依赖的模组框架（RED4ext、TweakXL、ArchiveXL、CET、Codeware、redscript）仅支持 Windows。本项目旨在逐步填补这一空白： - **v1.0 — 基础：** 一个等效于 RED4ext 的加载器 + TweakXL（TweakDB 数据/`.tweak`/YAML flat 模组）。← 当前重点 - **v1.x — 资产：** ArchiveXL 对齐（自定义档案、网格/纹理/声音）。 - **v2.0 — 脚本：** CET（Lua + ImGui-on-Metal）、redscript、Codeware。 ## 状态 **实现了首个可见、已验证的原生 macOS 游戏内更改** ✅ — 通过直接进行活动内存写入，在实时存档中将玩家的欧金（eddies）从 **310,915 修改为 1,000,000**，无需重新加载，没有崩溃，干净地还原（事实 **F-044**）。 **redscript 模组在 macOS 上原生运行** ✅ — 在游戏内验证：一个由游戏自带的 `scc` 编译的 `@wrapMethod` 钩子，在加载存档时触发并调用了具有可见效果的原生游戏系统（事实 **F-050**–**F-052**）。不需要 RED4ext、不需要 CET、不需要代码 hook — 只需原版安装自带的工具链。这是本项目中最简单的实质性胜利：任何纯 redscript 的 Nexus 模组（无 Codeware/ArchiveXL 依赖）都极有可能在保持原状的情况下直接运行。 **内联（`__TEXT`）hook 确认被阻断，而不仅仅是未经测试** — 对游戏二进制文件进行了 6 次真实的重新签名副本，测试了已知社区分支声称有效的所有 entitlement 组合，它们全部在内核级别以相同的方式失败（事实 **F-053**）。`__DATA`/GOT/vtable hook 仍然是该平台上唯一有效的底层操作方式；完整的 RED4ext 等效插件宿主仍然是一个悬而未决的问题。 **阶段 1（TweakXL 基础） — 端到端验证。** 数据 pipeline 可在游戏内运行，并已通过游戏自身的代码进行了验证： `DYLD` 注入 → 映像偏移捕获 → TweakDB 单例 → 应用触发器（轮询） → flat 查找 → flat **写入 / 创建 + 数组追加** → 记录重构（`UpdateRecord`） — 每一项都由游戏*自身的* `GetFlat`/`GetRecord` 访问器确认（而不仅仅是我们的写回）。YAML/`.tweak` 解析和应用器可端到端运行。 **壁垒。** TweakDB-flat 编辑在引擎的访问器处进行了验证，但**不会**在 macOS 上传播到实时的游戏玩法中：游戏读取的是按实体的*实例化*结构（StatsContainers，record 实例），这些结构在我们运行编辑之前就已经生成了快照，因此 flat 更改不会显示出来。触及这些结构是一个棘手且悬而未决的问题（[`docs/FAILED_APPROACHES.md`](docs/FAILED_APPROACHES.md)）。因此，首个可见的更改来自一种*不同*的机制 — 直接写入活动进程内存。 **阶段 2 — 实时编辑工具（基于该突破的产品化）。** 一款小巧、安全的原生 macOS 工具，用于在运行中的游戏里定位并编辑**已存储的计数器**（金钱、制作组件、XP 等）： - 使用 `set ` 处理唯一值，或使用 `find → narrow → setcand`（双快照差量）处理常见/较小的值； - 一键 **`revert`**（还原） — 并且每次写入都仅在 RAM 中生效，因此重新加载存档也会进行恢复； - 防范崩溃（饱和度保护、数值上限）以及游戏补丁（Mach-O **版本门控**会在无法识别的版本上禁用写入）； - 经过对抗性审查、单元测试 (`ctest`)，并记录在 [`docs/guides/live-edit.md`](docs/guides/live-edit.md) 中。 **尚未完成的工作：** 常规的 Windows 模组文件（`.yaml`）更改产生可见效果（如上文所述的壁垒）、资产/纹理模组、脚本生态系统的其余部分（CET、Codeware、带有自定义 native 的 redscript 模组）、稳定性强化以及打包的安装程序。完整计划详见 [`docs/ROADMAP.md`](docs/ROADMAP.md)；当前状态、阻碍因素及下一步行动详见 [`state/status.yaml`](state/status.yaml)；工程记录详见 [`docs/FACTS.md`](docs/FACTS.md) 和 [`state/session-log.md`](state/session-log.md)。 ## 它与 Windows 上的 RED4ext/TweakXL 有何不同 Windows 技术栈依赖于 DLL 注入 + **内联 hook**。在 macOS 上，这种方法无法直接套用： - **内联 hook 已被阻断，经验证属实** — 在 macOS Hardened Runtime / 代码签名下，`__TEXT` 段是只读的，无论是原始二进制文件还是测试过的所有临时重签名 entitlement 组合（包括社区分支声称有效的那些）皆是如此（事实 **F-053**）。我们改用数据端技术（GOT/vtable/函数指针表）以及轮询应用触发器。目前唯一未测试的手段是真正的（非临时的） Apple Developer ID 签名 — 参见 [`docs/ROADMAP.md`](docs/ROADMAP.md) 阶段 5。 - **内存中的 TweakDB 布局有所不同** — 结构体偏移量、flat 值表示形式和访问器都是针对 macOS 版本重新推导出来的。 - **可见的更改通过实时内存进行，而不是 TweakDB** — 由于 flat 编辑无法触及游戏已实例化的运行时结构，实时编辑工具会直接写入运行中的进程内存（`mach_vm_write`）并保留/还原结果。 - **注入**使用 `DYLD_INSERT_LIBRARIES`；发布的构建版本已经自带了使其生效的 entitlement。 完整的图景详见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ## 仓库结构 | 路径 | 说明 | |------|------| | `src/` | C++ 源码 — `red4ext-mac/`（加载器 + TweakDB 运行时），`tweakxl-mac/`（解析器 + 应用器） | | `docs/` | 工程记录 — `ROADMAP.md`、`PHASE_*_PLAN.md`、`FACTS.md`、`FAILED_APPROACHES.md`、`ARCHITECTURE.md`、`guides/`、参考资料 | | `state/` | 机器可读的项目状态 — `status.yaml`、`session-log.md` | | `tools/` | 辅助脚本（Ghidra 分析、探针、构建/运行辅助工具） | | `reference/` | 外部参考资料指引（见下文备注） | | `.openclaw/`, `AGENTS.md`, `CLAUDE.md` | 针对 AI 代理在此仓库中工作的约定 | **关于 `reference/` 的备注：** 庞大的外部输入（Ghidra 项目、第三方模组、gibbed TweakDB schema）**并没**有被放到本仓库中 — 它们在本地通过获取/符号链接的方式引入，并被 git 忽略。在需要它们的地方，相关文档会提供获取命令（例如 `git clone https://github.com/gibbed/Cyberpunk-TweakDB-Schema.git reference/gibbed-schema`）。 ## 构建 要求安装 CMake 3.15+ 以及较新版本的 Apple Clang。详见 [`docs/BUILD.md`](docs/BUILD.md)。简而言之： ``` cmake -B build -S . cmake --build build # -> build/src/{red4ext-mac,tweakxl-mac}/lib*.dylib ``` ## 免责声明 这是一个**独立的、非商业性的互操作性 / 研究项目**。它**不隶属于 CD PROJEKT S.A.，也未获得其认可或赞助。** - **不重新分发任何游戏代码或资产。** 本仓库仅包含原创的源代码、文档和分析笔记。 - 《赛博朋克 2077》（Cyberpunk 2077）、REDengine 以及所有相关的代码、资产和数据均为 **CD PROJEKT S.A.** 及其许可方的财产。“Cyberpunk 2077”是 CD PROJEKT S.A. 的商标。 - 运行本软件需要您自己合法获取的游戏副本。对游戏进行逆向工程和修改可能会受到其 EULA 的限制；**您有责任确保您的使用行为符合您所在司法管辖区的适用许可和法律。** - 使用风险自负。修改正在运行的游戏进程可能会导致游戏崩溃或存档损坏 — 请做好备份。 MIT [`LICENSE`](LICENSE) 仅适用于本仓库中的原创作品。 ## 致谢 - **[psiberx](https://github.com/psiberx)** — TweakXL / TweakDB 研究（Windows 行为以此为基础进行建模） - **[WopsS](https://github.com/WopsS/RED4ext)** — RED4ext - **[WolvenKit](https://github.com/WolvenKit)** & **[gibbed](https://github.com/gibbed)** — TweakDB 格式与 schema 研究 - **RedModding 社区** — 文档和逆向工程的基础工作 与 CD PROJEKT RED 无关联。

标签：Bash脚本, Lua脚本, macOS原生开发, rizin, 内存修改, 游戏Mod开发, 《赛博朋克2077》, 跨平台移植