• 游戏开发
• 插件系统

本文基于 REPENTOGON 官方安装文档 docs/docs/install.md 整理并扩充，覆盖 Windows 与 Linux/Steam Deck 两大平台的完整安装流程、通过 Steam 启动项接管游戏的可选配置、存档成就导入导出的底层原理，以及安装损坏、手柄输入错乱等常见问题的排查手段。读完本文，你将能够独立完成 REPENTOGON 的部署与 Steam 集成，并理解 Launcher 为何存在、版本为何被锁定在 v1.9.7.12.J273，以及从源码层面解释存档同步「只增不减」的安全机制。

安装前提：两个硬性依赖

要安装并运行 REPENTOGON，你需要同时具备以下两项：

1. REPENTOGON Launcher（按下文对应操作系统的步骤获取）；
2. 以下两者之一的游戏本体：
   • The Binding of Isaac: Repentance+ 的 Steam 最新正式版；
   • The Binding of Isaac: Repentance+ v1.9.7.12.J273。

之所以同时接受两种版本，是因为 REPENTOGON 当前的正式发布基线是v1.9.7.12.J273——这一点在 README.md 中有明确说明：项目针对该版本开发，但安装可以直接基于 Steam 上当前最新的 Repentance+ 进行，由 Launcher 负责处理版本适配。version.txt 显示当前仓库对应 REPENTOGON 版本为 1.1.3。

Windows 安装步骤

第一步：获取 Launcher

获取 Launcher 有两条路径：

方式一：手动下载

1. 从 REPENTOGON Launcher 项目的官方发布页下载最新版压缩包（官方安装文档 docs/docs/install.md 中附有直接的下载链接，请以该文档为准，始终保持 Launcher 为最新状态）。

2. 将 Launcher 解压到你选择的目录。Launcher 几乎可以放在任何位置，但有两点注意事项：

   • 不要放在受 OneDrive 保护或同步的目录（桌面、文档等），可能引发异常；
   • 两个经过验证的可靠位置：
     1. 在盘符根目录新建文件夹，例如C:/REPENTOGONLauncher/；
     2. 在 Isaac 的安装目录内新建名为REPENTOGONLauncher的子文件夹，例如.../steamapps/common/The Binding of Isaac Rebirth/REPENTOGONLauncher/。

   两条红线：不要把 Launcher 直接解压进游戏安装目录根部（可能产生文件冲突）；也不要在游戏安装目录下创建名为repentogon的文件夹——这个名字后续会被 REPENTOGON 本体占用。

方式二：从旧版自动升级

如果你此前安装过 Repentance 版的 REPENTOGON，它可能已通知你 Repentance+ 更新、自动下载了 Launcher 并在桌面创建了快捷方式。如需手动查找，Launcher 文件位于 Isaac 安装目录下的REPENTOGONLauncher子文件夹中。

第二步：安装 REPENTOGON 本体

1. 运行REPENTOGONLauncher.exe（或桌面上的REPENTOGON快捷方式），Launcher 的首次设置窗口将打开。Launcher 每次启动都会检查更新，请尽量保持其为最新版本以确保功能正常。
2. 设置窗口会要求指定 Binding of Isaac: Repentance+ 可执行文件的位置：
   • 通常可以自动检测；
   • 若未检测到，点击Select executable...手动定位你的isaac-ng.exe，然后点击Next继续。

如果 Launcher 提示你的 Isaac 安装与 REPENTOGON不兼容，说明你的游戏版本必须是v1.9.7.12.J273，或 Steam 上 Repentance+ 的最新正式版。若新补丁刚发布，先更新 Launcher；若仍不行，请耐心等待——官方最多可能需要一天时间适配新版本。

安装失败 / 启动即崩溃 / 提示安装损坏时，按以下顺序排查：

• 在主窗口点击Choose exe重新执行首次设置，确认选择的 Isaac 可执行文件正确；
• 在 Steam 中校验原版安装完整性（Steam 客户端「帮助 → Steam 支持」中的验证游戏缓存功能；若文件校验失败并开始重新下载，等待其完成）；
• 在主窗口点击Update/Repair Installation，然后选择Re-install/Repair REPENTOGON。

第三步（可选但推荐）：让 Steam 启动时走 Launcher

如果你希望通过 Steam 启动 Isaac 时实际运行的是 REPENTOGON Launcher，需要配置 Steam 启动参数。对于 Steam Remote Play，这一步是强制要求！

1. 在 Steam 中进入The Binding of Isaac: Rebirth条目；
2. 点击屏幕右侧的齿轮图标，选择Properties；
3. 在General页找到Launch Options（启动选项）输入框，填入：

"(PATH TO REPENTOGONLauncher.exe)" --isaac=%command%

其中(PATH TO REPENTOGONLauncher.exe)必须替换为你本机 REPENTOGON Launcher 可执行文件的完整路径，例如：

"C:\Program Files (x86)\Steam\steamapps\common\The Binding of Isaac Rebirth\REPENTOGONLauncher\REPENTOGONLauncher.exe" --isaac=%command%

从源码结构看，这条命令的语义是：把 Steam 原本的启动命令%command%通过--isaac=参数原样传递给 Launcher，由 Launcher 接管真正的游戏启动逻辑。Launcher 与游戏侧共享一套通信接口，见 repentogon/LauncherInterface.h——其中定义了双方约定使用的退出码（如LAUNCHER_EXIT_MODS_CHANGED，用于在模组装卸后提示用户立即重启游戏），该文件被明确要求与 Launcher 侧的对应文件保持同步。

Linux / Steam Deck 安装步骤

Linux 与 Steam Deck 上由于需要 Proton 环境，必须通过 Steam 启动选项接入 Launcher：

1. Steam Deck 用户先切换到桌面模式（Desktop Mode）；
2. 在 Steam 中进入The Binding of Isaac: Rebirth，点击齿轮图标选择Properties；
3. 进入Installed Files，点击Browse打开游戏安装目录；
4. 在安装目录内新建文件夹REPENTOGONLauncher。若该文件夹已存在且里面已有REPENTOGONLauncher.exe，说明你曾从旧版 REPENTOGON 升级器自动获得过 Launcher，可跳过下载步骤；
5. 从 Launcher 官方发布页下载最新版压缩包，解压到刚才新建的REPENTOGONLauncher子目录中；
6. 确认 Launcher 的完整路径必须是：

.../steamapps/common/The Binding of Isaac Rebirth/REPENTOGONLauncher/REPENTOGONLauncher.exe

注意不要写错文件夹名，也不要把文件再套进一层多余目录。

7. 回到 Steam 属性窗口General页，在Launch Options中粘贴以下命令：

echo "%command%" | sed 's|isaac-ng.exe|REPENTOGONLauncher/REPENTOGONLauncher.exe|' | sh

这条命令的作用是把 Steam 原始启动参数中出现的isaac-ng.exe用sed替换为REPENTOGONLauncher/REPENTOGONLauncher.exe，再用sh执行——从而让 Steam 启动的不再是原版游戏，而是相对游戏目录的 Launcher。

8. 在Compatability（兼容性）选项卡中，确认兼容性已启用，并且精确指定为Proton 9.0-4；
9. 通过 Steam 启动 Isaac，此时实际运行的是 REPENTOGON Launcher。如果无反应，请逐项复查：
   • Launcher 完整路径是否为.../steamapps/common/The Binding of Isaac Rebirth/REPENTOGONLauncher/REPENTOGONLauncher.exe；
   • Launch Options 是否与上文逐字一致；
   • 兼容性设置是否确认为Proton 9.0-4。
10. Launcher 首次设置窗口会要求定位 Repentance+ 可执行文件（可自动检测，或点击Select executable...手动指定isaac-ng.exe），后续的版本兼容性与安装损坏排查步骤与 Windows 完全相同。

为什么 REPENTOGON 需要 Launcher？

安装文档的 FAQ 部分给出了三个层次的动机，这也是理解整个项目定位的关键：

1. 加载方式的兼容性问题：早期 REPENTOGON 依赖 DLL 注入式加载，在部分 Windows 环境下无法工作。团队意识到不存在一种只靠 DLL 就能覆盖所有环境的通用方案，Launcher 由此而生（时间点恰在 Repentance+ 公布之前）。
2. 版本快速迭代带来的移植困境：与传统 Lua 模组依赖跨版本（相对）稳定的 API 不同，REPENTOGON 基于对游戏内部结构的逆向工程，这些结构随版本剧烈变化。Repentance+ 发布后更新节奏较快，移植工作变成「还没移植完，目标版本又变了」的循环。团队最终选定v1.9.7.12.J273作为发布基线，玩家就需要把游戏降级——降级过程本身容易出错，于是 Launcher 顺带承担了这个职能：无缝把游戏降级到 REPENTOGON 兼容版本。
3. 存档结构不兼容的风险：v1.9.7.12.J273 与最新版的存档文件结构不同，用 A 版本加载 B 版本的存档可能直接毁掉整个存档——特别是把 REPENTOGON 兼容存档放到最新版游戏里，可能清空全部成就。Launcher 对 Isaac 可执行文件加入了多项针对此问题的对抗性措施。

版本锁定意味着什么

由于当前 REPENTOGON 运行在v1.9.7.12.J273之上，即使 Launcher 允许你基于最新正式版安装，游戏在 REPENTOGON 环境下运行时也会缺少后续官方补丁中的新内容。官方解释称：移植此类项目耗时且会引入大量需要长时间打磨的 bug，而 Repentance+ 尚在活跃开发中，因此选择基于 v1.9.7.12 先行发布，让 MOD 作者和玩家尽早用上，同时摆脱「每个新补丁都要移植一遍」的被动局面。

Launcher 内置 Mod 管理器

Launcher 里的 Mod 管理器最初只是开发者的一个副项目。将其集成进 Launcher 并用来完全替换游戏自带的模组管理逻辑后，团队发现加载时间和整体模组管理体验都有显著提升，因此保留了这一设计。

成就与解锁的导入 / 导出（Save Management）

官方文档指出一个隐蔽的坑：Repentance+ 使用独立于 Repentance 的存档文件，而且Repentance+ 只会在你第一次启动它时导入一次 Repentance 的存档数据。如果你过去曾启动过 Repentance+，之后又回到 Repentance 继续游玩，那么 Repentance+ 的存档大概率仍停留在你上次启动它时的状态——表现为「丢了成就/解锁」。

REPENTOGON 提供了双向补救：可以从 Repentance 导入缺失的成就/解锁，也可以把新获得的成就/解锁导回 Repentance。操作步骤：

1. 在Title Screen（标题画面）按~键打开 REPENTOGON Console；
2. 在屏幕左上角依次进入Tools → Game Options，弹出选项窗口；
3. 切换到Save Management标签页；
4. 选择Import from Repentance即可从 Repentance 存档导入所有缺失的成就和解锁。注意：按钮被禁用时，请确认自己正处于标题画面。官方同时强调：导入/导出过程永远不会移除已有成就或进度，只会补上一边获得而另一边缺失的项目。

这部分能力有完整的源码支撑。在 repentogon/SaveSyncing/SaveSyncing.cpp 中，SAVE_DATA_PATHS表登记了各版本存档的本地与 Steam 云路径，其中 REPENTOGON 使用独立存档Repentogon/rgon_persistentgamedata%d.dat，Repentance 对应../Binding of Isaac Repentance/persistentgamedata%d.dat。导入/导出入口SaveSyncing::ImportFrom(REPENTANCE, slot)与ExportTo(REPENTANCE, slot)在 repentogon/ImGuiFeatures/GameOptions.h 的 Save Management 标签页中被绑定到 UI 按钮上；源码中saveManagementAllowed的条件判断（菜单 ID 为 1 或 2，即标题/角色选择菜单且未载入存档）与文档「按钮被禁用时请确认在标题画面」的提示完全对应。

「只增不减」的保证来自同步算法本身：repentogon/SaveSyncing/SaveFile.cpp 中SyncData模板函数对两个存档的共享元素逐条取std::max(srcVal, dstVal)（SAVE_SYNC_TAKE_MAX模式），并且仅同步两边都存在的条目——源文件注释也明确说明：即使两个存档的成就/计数器数量不同，也只同步交集部分；当同步无法进行时，REPENTOGON 继续使用自己的独立存档文件，「用户永远不会丢失进度，因为合并时取两边的最大值」。此外，repentogon/SaveSyncing/SaveSyncing.cpp 还安装了一个 ASM 补丁：若游戏试图加载成就数量不匹配的存档（原版会保留成就、清空其余数据），补丁会直接抛出异常而不是放任存档被破坏。

手柄输入错乱的处理

针对控制器按键映射错乱，文档给出三级处理方案，第三级方案在源码中可以直接对应到具体钩子：

1. 第三方手柄（如 8BitDo）：为 Isaac 启用 Steam Input 覆盖（override），一致性最好。注意：必须同时完全关闭 Isaac 和 REPENTOGON Launcher 该设置才生效；
2. 进入游戏内按键映射菜单，点击Reset To Default；
3. 若游戏内控制菜单中出现一个或多个Unknown Device，可以在 REPENTOGON Console 菜单中启用Block Unknown Device选项后重启游戏。

从源码结构看，该选项由 repentogon/REPENTOGONOptions.h 中的blockUnknownDevices字段承载（配置文件节VanillaTweaks/BlockUnknownDevices），UI 入口位于 repentogon/ImGuiFeatures/GameOptions.h，实际拦截逻辑在 repentogon/Patches/MiscFixes.cpp：钩住InputDeviceBase::Initialize，当选项开启且设备名为"Unknown Device"时直接返回false，阻止其注册为控制器。

与 Basement Renovator 配合

使用 Basement Renovator 房间编辑器时：

1. 确保 Basement Renovator 已更新至3.3.1 或更高版本（低于此版本无法与 REPENTOGON 配合工作；最新版见官方发布页）；
2. 确认你已完成上文安装流程，且 REPENTOGON 本身运行正常；
3. 在 Basement Renovator 中进入File→Set Paths，在弹出的对话框里把.exe Path改为指向你的REPENTOGONLauncher.exe；
4. 此后测试房间时游戏将带 REPENTOGON 启动；若出现安装损坏等问题，Launcher 会弹出来处理。

问题反馈渠道

Bug、问题或建议应提交到 REPENTOGON 或 Launcher 对应的 GitHub Issues 页面（链接见 docs/docs/install.md 的 Reporting / Contact 一节）。提交时请附上相关日志文件——Launcher 主窗口的Check Game Logs按钮可以快速定位日志。此外也可以加入 The Modding of Isaac Discord 服务器的#repentogon频道寻求帮助。

小结

REPENTOGON 的部署链路是「Launcher 负责版本与安装、Steam 启动选项负责接管、游戏内 Console 负责运行期维护」：Launcher 把游戏钉在 v1.9.7.12.J273 兼容环境（或以最新版安装后自动处理），sed替换或--isaac=%command%参数把启动权交给 Launcher，而成就同步、未知设备拦截等运维能力则由仓库中repentogon/SaveSyncing/、repentogon/Patches/下的实现提供。按本文步骤操作并保留 Launcher 为最新状态，即可覆盖绝大多数安装与运行期问题。

• 游戏开发
• 插件系统