RepoMapX —— R.E.P.O. 全图标记 Mod（从零手写教程 + 完整可编译源码）

这是一个 纯客户端 的 BepInEx 插件，实现你想要的全部效果：

游戏内按 M 循环切换：关闭 → 角落小地图 → 居中大地图。 所有开关都能在 BepInEx/config/You.RepoMapX.cfg 里改。

一、工作原理（先说清楚，越懂越好改）

R.E.P.O. 是 Unity 游戏，它的 Mod 一般走这条链路：

BepInEx（Mod 加载器）-> 启动时把你编译好的 .dll 注入游戏进程 -> HarmonyX（函数补丁框架，是 Harmony 的改版）-> 在游戏函数"执行前/后"挂钩子 -> 你的代码读游戏内存里的对象、改 UI、玩游戏自己的 API。

关键知识点（全部来自社区逆向出来的游戏内部类，见文末参考）：

1. 游戏自带一张"全图"：Dirt Finder Map Camera 是一个固定俯视的正交相机， 它把整个关卡渲染到一张 RenderTexture 上（就是原版"地图工具"的画面）。 Map.Instance.ActiveSet(true) 可以强制让它工作。
2. 地图上的圆点：游戏类 MapCustom（挂在任意物体上，设置 sprite``color 再调用 Add()），地图相机就会把它渲染成一个彩色圆点。 玩家身上、怪物身上都可以挂。
3. 房间显示：RoomVolume.SetExplored() 把房间标记为已探索，地图上就全亮。
4. 贵重物品：ValuableObject.discovered = true + Map.Instance.AddValuable(item)， 物品就出现在地图上，dollarValueCurrent 字段是它的价值。
5. 名字/状态/价值：这些原版地图不显示，所以用 OnGUI（Unity 老式 UI 绘制） 在世界坐标 → 地图相机视口坐标 → 屏幕矩形坐标的映射下画文字标签。 推车价值（haulCurrent）和撤离点状态是私有字段，用反射读取（Refl.cs）， 字段名变了也不会崩，只是显示不出来，看日志改一行就行。

为什么这样做而不是"猜测并硬编码"？TheEverythingMap 和 r.e.p.o-cheat 这两个开源项目把上面所有 API 都用过了（编译通过、运行正常）， 本项目的写法跟它们完全一致，是经过社区验证的。

二、搭建开发环境

1. 安装 .NET 9 SDK（装完开新终端验证：dotnet --version）。
2. 千万不要直接往游戏目录塞 Mod：用 Gale 或 r2modman 给 R.E.P.O. 建一个专用 profile（会帮你装好 BepInEx 和依赖）。Mod 管理器按官方 wiki 推荐： Gale / r2modman / Thunderstore Mod Manager。
3. 在项目目录（本目录）里建一个 Directory.Repo.props（这是"本机配置"，只在你机器上生效）：

<Project>
  <PropertyGroup>
    <!-- 你的游戏安装目录（SDK 也能自动从 Steam 注册表找到，这行可以省略） -->
    <GameDirectory>D:\SteamLibrary\steamapps\common\REPO\</GameDirectory>

    <!-- 把你建的开发档的 BepInEx 目录填进来，编译完自动部署 -->
    <!-- Gale 的路径长这样： -->
    <BepInExDirectory>$(UserProfile)\AppData\Roaming\com.kesomannen.gale\repo\profiles\Default\BepInEx\</BepInExDirectory>
    <!-- r2modman 的路径长这样（二选一，用哪个填哪个）： -->
    <!-- <BepInExDirectory>$(UserProfile)\AppData\Roaming\r2modmanPlus-local\REPO\profiles\Default\BepInEx\</BepInExDirectory> -->

    <StartArguments>--doorstop-enable true --doorstop-target "$(BepInExDirectory)\core\BepInEx.Preloader.dll"</StartArguments>
  </PropertyGroup>
</Project>

三、编译、安装、运行

cd D:\self\repo-mod\RepoMapX
dotnet restore   # 第一次会下载 BepInEx/Unity/游戏引用 DLL（需要联网）
dotnet build     # 编译，成功后自动把 dll 复制到上面的 BepInEx plugins 目录

然后在 Mod 管理器里用你的开发档启动游戏，进任意关卡看效果：

• 进入关卡后地图右上角出现小地图（默认模式），所有房间全亮；
• 怪物出现立即显示红点 + 名字；队友是彩色点+名字；自己是白色点+名字（你）；
• 撤离点绿点、物品金点带 $价值、推车橙点带当前价值；
• 按 M 切大地图/关闭；看 BepInEx/log.log 有没有报错。

也可以 dotnet run 直接启动游戏调试（SDK 支持）。

想装进 r2modman 或发布到 Thunderstore：看下面 第七节「打包并上传」。

四、代码文件导览

想做新功能，从这三个文件开始改：

• 想加"队友距离"：MapOverlay.cs 的 DrawLabels 里加 Vector3.Distance。
• 想把地图框放大/换角落：改 Settings.cs 或 MapOverlay.ComputeRect。
• 想加"全图显示装尸袋/箱子"：模仿 UpdateExtractionMarkers，找到对应类 （UnityEngine.Object.FindObjectsOfType<Xxx>()）挂 MapCustom 就行。

五、修改配色和标签

颜色在 Settings.cs 顶部（TeamPalette + SelfColor 等常量）， 直接把 new Color(r, g, b, a) 换成你喜欢的即可。 想要热键切换某类标记（比如按 F 显示/隐藏怪物），在 Plugin.cs 的 Update 里加 Input.GetKeyDown(...) 并翻转对应 Settings.ShowXxx.Value。

六、常见问题

1. 编译报错说找不到某个类/字段：游戏更新改了 API。去 https://github.com/davidewetzel/TheEverythingMap 或 https://github.com/D4rkks/r.e.p.o-cheat 对照最新代码改名字， 或者用 dnSpy 打开 REPO_Data/Managed/Assembly-CSharp.dll 搜一下。
2. 界面出来了但标记不显示：看 BepInEx/log.log 里 RepoMapX 开头的 Warning，八成是字段名变了，反射已经自动跳过，改 Refl.Field 的参数列表。
3. 队友没名字：SemiFunc.PlayerGetName 在不同版本可能改名，用反射兜底。
4. 只在本地生效：这是刻意的。所有标记都是你本机客户端自己画的， 不开网络同步，不影响其他玩家（单机/联机都安全，不会被别人看到你的"外挂视野"）。
5. 游戏版本：每次游戏大更新后建议重新 dotnet build 确认没被 API 变更弄坏。

七、打包并上传（装进 r2modman / 发布到 Thunderstore）

先明确一件事：r2modman 本身不是"上传"平台，它只是 Mod 管理器；R.E.P.O. 的 Mod 都托管在 Thunderstore 上，r2modman 从那里下载。 所以有两条路：

路线 A：本地离线安装（只想自己用，最快）

1. 运行打包脚本（编译 + 生成标准的 Thunderstore 包）：

   cd D:\self\repo-mod
   powershell -ExecutionPolicy Bypass -File package.ps1
   

   输出 dist\RepoMapX-1.0.0.zip，zip 根目录直接是： manifest.json、README.md、icon.png（256x256）、RepoMapX.dll。

2. 打开 r2modman -> 选择 R.E.P.O. -> 创建/选中你的 profile：

   • 直接把 zip 拖进 r2modman 主窗口（Mods 页面），它会识别为 Thunderstore 包并 自动安装到当前 profile（离线安装）。如果没有拖拽入口，就手动解压到 profile 目录下的 BepInEx\plugins\ 里（子文件夹无所谓，BepInEx 5 会递归加载）。

3. 点 r2modman 的 Start Modded 启动，进关卡即可。BepInEx 依赖不用管， r2modman 在安装时会自动装上依赖（这里依赖的是 BepInEx-BepInExPack-5.4.2100）。

路线 B：发布到 Thunderstore（让所有人都能搜到、一键安装）

1. 注册/登录 thunderstore.io（Discord / GitHub / Overwolf 账号都行）。
2. 右上角头像 -> Teams -> Create Team 建一个发布团队（相当于你的作者名）。 ⚠️ Team 名字 创建后不能改、不能删，想好再取。
3. 用路线 A 的 package.ps1 生成 zip（这一步会自动带上 manifest.json 和版本号）。
4. 打开 https://thunderstore.io/package/create：
   • 拖入 zip；
   • Team 选你刚建的；
   • Community 选 R.E.P.O.；
   • Categories 勾 Tools / Quality of Life 之类（选最贴切的）;
   • NSFW 选 No；
   • Submit。
5. 提交前可以先用官方校验工具检查 manifest： https://thunderstore.io/tools/manifest-v1-validator
6. 上传后 通常要几小时 才会出现在 r2modman 的在线搜索里（Thunderstore 有缓存）， 之后搜 RepoMapX 即可安装；也可以直接在网站上点 Install with mod manager。

包格式要点（自己手动打包时必须遵守）

• zip 不要包外层文件夹：全选文件（manifest.json、README.md、icon.png、dll）再压缩， 根目录直接是这几个文件；
• icon.png 必须是 256x256 PNG；
• manifest.json 的 dependencies 写 BepInEx-BepInExPack-5.4.2100（REPO 社区 通用 BepInEx 包），mod 管理器会自动帮安装；
• 包是不可变的：上传后不能删除或修改，出了 bug 只能改 version_number 升版本重传（遵循语义化版本号 1.0.0 -> 1.0.1）；
• 更新时不要改 manifest.json 的 name，改了 Thunderstore 会当新 Mod 而不是更新；
• Thunderstore 有社区审核规则（https://wiki.thunderstore.io/moderation/global-rules）， 描述里写清楚是"地图信息增强工具"就行，别写作弊/外挂类词汇。

八、参考资源（你后面自己开发全靠这些）

• 官方社区 Wiki：https://repomods.com（/develop 里的两条路线：Unity 工作流 + HarmonyX 工作流；/harmonyx 有完整搭建教程）
• 官方 SDK 模板：https://github.com/linkoid/Repo.Sdks （本项目的 csproj 照抄它的模板）
• TheEverythingMap（图地图、全开房间、玩家/敌人/物品标记的完整实现）： https://github.com/davidewetzel/TheEverythingMap （Thunderstore: Nubez-TheEverythingMap）
• r.e.p.o-cheat（怪物/物品/玩家/撤点 ESP、价值读取的完整实现）： https://github.com/D4rkks/r.e.p.o-cheat
• REPO_SelfMovingCart（推车类 PhysGrabCart 的用法（含 haulCurrent、isSmallCart））： https://github.com/Synt-Axe/REPO_SelfMovingCart
• BepInEx 文档：https://docs.bepinex.dev ；Harmony 文档：https://harmony.pardeike.net
• 社区 Discord（REPO Modding，最权威的问题解答）： https://discord.gg/vPJtKhYAFe （wiki 侧边栏有入口）

九、提醒

• 这类"全图视野"功能本质上是透视信息增强（ESP），公共房间连麦玩没问题， 但在竞技/速通、需要公平性的场合会被认为是作弊，自己把握使用场合，别拿去卖钱。
• Mod 只影响你自己，性能开销很小（每 2 秒才刷新一次列表，标签绘制是几十个字符串）， 比同类 mod 更省。