BetterMapFix

⚠️ APPLICABILITY NOTICE — please read this before installing.

This patch was written for my own, heavily modded setup (30+ mods enabled in an r2modman profile — BepInEx 5.4.2350 / Valheim 1.0.15). The symptom described below may be caused by my particular mod combination rather than by a bug in the original mod.

This is not a bug. xtavim-BetterMap is not defective — it behaves exactly as it was designed to. What this patch adds are cases the original mod does not implement at all (see the table below), plus a rename of pin labels that the original has no setting for. The original mod's author bears no blame — this patch has no relationship with them and was written without their consent or review.

• If you are not seeing exactly this symptom, please don't install this — it may do nothing for you.
• This patch may not apply to your setup at all — with a different mod list the symptom may never appear.
• Even with the same symptom, the root cause may be different — this is only a workaround derived from what I found on my machine.
• If you don't want these extra pins, just don't install it — this is a preference, not a right/wrong question.
• If you think the original mod misbehaves, please report it to its author first.

⚠️ 适用性声明 —— 请先读这一段，再决定装不装。

本补丁是在我自己那套环境里做出来的：r2modman 的 profile 里同时装着 30+ 个模组 （BepInEx 5.4.2350 / 游戏 1.0.15）。下面描述的“症状”有可能是我这套模组组合互相冲突造成的。

这不是 bug。 xtavim-BetterMap 本身没有问题，它完全按自身设计正常工作 —— 本补丁补的是它根本没有实现的那些情况（见下面的对照表），以及一个它本来就没有开关可调的 「图钉名中文化」。原模组作者不应被追责：本补丁与他没有任何关系， 未经其同意、也未经其审查。

• 如果你没有遇到完全相同的症状，请不要安装本补丁 —— 它可能什么都不做；
• 本补丁可能不适用于你的环境：换一套模组组合，症状也许根本不会出现；
• 就算症状一样，成因也可能不同 —— 本补丁只是我按本机情况查出来的绕行方案；
• 如果你不需要这些额外的图钉，那根本不用装 —— 这是一个取舍，不是「谁对谁错」；
• 如果你觉得原模组有问题，请先向原模组作者反馈。这只是我个人“能跑就行”的绕行方案， 不保证适用于任何人。

给 BetterMap 打的客户端补丁 —— 修三件事（另见 CHANGELOG 的 1.1.3）：

1. 迷雾之地的女王指引石（Vegvisir）不会被标记。
2. 洞穴/地牢条目不全：希尔迪的地牢、半埋墓穴等在原版地图上不会出现。 （腐疫矿区与腐朽之穴上游 1.0.5 已自己补上； 女王洞穴入口这类上游不该自动标记的，直接在上游 cfg 里关掉即可 —— 见下方「上游已有的开关」。）
3. 图钉名中文化（洞穴、要塞、祭坛那类地点图钉）。
4. 补一条上游没有的规则「软组织」（giant_brain = Soft Tissue = 软组织）—— 上游的 Giant Remains 只盯骨与盔甲武器，不认软组织。

   不要上游那几条（上古之剑/上古盔甲/骨）的话，在上游自己的 cfg 里关 [Auto Pins - Mistlands] Giant Remains = false 即可 —— 本补丁不碰上游规则。

⚠️ 本模组由 AI 生成（AI-generated）。

依赖：denikson-BepInExPack_Valheim-5.4.2350 + xtavim-BetterMap-1.0.5。 （1.1.3 起要求 1.0.5 —— 上游那一版自己补上了腐疫矿区与腐朽之穴，本补丁随之去掉这两条注入。）

上游已有的开关 —— 本补丁配套关掉了两个

这两条属于上游自己的行为，本补丁不去改它、也不去删图钉， 而是在上游自己的 cfg（BepInEx/config/xtav1m.BetterMap.cfg）里关掉：

cfg 键	设为	原因
[Auto Pins - Mistlands] Giant Remains	false	它盯的是骨与盔甲武器（giant_ribs / giant_helmet1-2 / giant_sword1-2），会把上古之剑、上古护甲、肋骨全钉出来。不要这些就关掉它
[Auto Pins - Mistlands] Entrance to the Queen	false	女王洞穴入口 —— 按游戏流程它该由女王指引石标记，不该再额外出一枚入口图钉

关掉之后：

• 上游不再为它们落新图钉；
• 地图上已存在的那几枚要你自己右键删（本补丁不再代为删除）。

装不装本补丁都能这么关 —— 这跟补丁无关，是上游自己的配置。

上游 1.0.4 / 1.0.5 已经修了一部分（2026-09-21 核对）

上游 BetterMap 在 1.0.4 里自己修好了「Boss 指引石不落钉」并补上「冰霜洞穴」； 1.0.5 又补上了「腐疫矿区」与「腐朽之穴」（后者改名 Putrid Holes）。 本补丁重新逐项核对后，收缩到上游仍然缺的那部分。想弄清两边的边界，看这张表：

功能	上游 1.0.4	本补丁
Boss 指引石落钉机制	✅ 已修（Rule.Component + 挂在 Location 生成事件上扫内部组件）	迷雾之地那一段交给上游；自己的扫描器留作兜底
迷雾之地的女王指引石	❌ 仍然没有 —— 上游 Vegvisirs 规则只有 7 个群系（无 Mistlands）	✅ 补上 [Mistlands] Vegvisirs
女王洞穴入口（Entrance to the Queen）	✅ 有（IsLocation=1 / 默认开）⇒ 会自动出一枚入口图钉	默认跳过（Skip Rules）—— 按游戏流程它该由女王指引石标记，不该双重标记
冰霜洞穴 Frost Caves	✅ 已补	兼容旧版仍注入（上游已有则自动跳过，不重复）
腐疫矿区 Mistlands_DvergrTownEntrance1/2	✅ 1.0.5 起已有 Infested Mines（同名同 prefab、默认开）	不再注入；但映射 Infested Mines=腐疫矿区 仍保留（上游那条无 NameToken，图钉名是英文）
腐朽之穴 MorgenHole1/2/3	✅ 1.0.5 起已有 Putrid Holes（NameToken $location_morgenhole ⇒ 游戏自己翻）	不再注入；映射改为 Putrid Holes=腐朽之穴（保险）
希尔迪三个地牢 Hildir_cave/crypt/plainsfortress	❌ 没有	✅ 补上（默认关）
图钉名中文化	❌ 没有	✅ 本补丁的主要价值

所以：只装 BetterMap 1.0.5 而不装本补丁，迷雾之地女王指引石依旧不会出现在地图上 （腐疫矿区与腐朽之穴 1.0.5 已经有了，但希尔迪地牢、半埋墓穴、以及图钉中文名仍然缺）。

⚠️ 一个容易看错的陷阱：Dvergr Town 不是腐疫矿区

上游规则表里有一条叫 Dvergr Town、描述写着 "The dvergr settlements out on the ash sea." 的规则， 光看名字很像"矮人要塞/矿区"。它实际是：

Prefabs   = ['CharredTowerRuins1_dvergr']   ← 灰烬之海的矮人据点
Biome     = AshLands                        ← 灰烬之地，不是迷雾之地
DefaultOn = false                           ← 默认还是关的

BetterMap 落钉要过群系过滤（Heightmap.FindBiome(位置) == 规则.Biome）， 所以它永远命中不了迷雾之地的 Mistlands_DvergrTownEntrance1/2。 这就是「规则名看着像、群系一票否决」的静默失效形态 —— 核对覆盖率时必须逐条比 prefab 名 + 群系， 不能看规则名。

---

为什么指引石标记不了（根因）

BetterMap 的自动标记（AutoPins.Sweep）只遍历 ZNetScene.instance.m_instances —— 那是一张 Dictionary<ZDO, ZNetView>，只包含有网络对象的东西。 而指引石是烘焙进 Location 预制体里的子物体，没有自己的 ZDO； 它们也不在 ZNetScene 的名字表里（GetPrefab 实测返回 null），于是 ZNetScene.IsPrefabZDOValid 永远过不了、ZDO 永远不存在。 BetterMap 自己在日志里就把结论写出来了：

[Warning: BetterMap] AutoPins: "Vegvisirs" watches a prefab named Vegvisir_DragonQueen,
  which this game has none of. Nothing will ever be pinned for it.

7 种 Boss 指引石全都是这个下场（不是龙母特有），cfg 里也没有自定义名字的选项。

上游 1.0.4 的修法（与本补丁当初的诊断完全一致）：规则改填新字段 Component = typeof(Vegvisir)， 新增 AutoPins.Spawned(LocationProxy) / Inside(...)，挂在 Location 生成事件上扫内部组件 —— 比本补丁「按 Exploration Radius 扫玩家附近」更彻底（Location 一生成就能标记，不受半径限制）。 但上游只给 7 个群系加了 Vegvisirs 规则，没有迷雾之地，所以女王指引石仍然要靠本补丁。

这个补丁怎么做（尽量走 BetterMap 自己的路）

功能	做法
洞穴/地牢补全	在 Plugin.BindPinRules 跑之前，往 PinRules.All 里补几条规则。剩下的 BetterMap 自己全包 —— 在它自己的 cfg 里生成开关（分区 Auto Pins - <群系>、中文注释）、并进 _byLocation 地点表、进图例、按 Merge Distance 去重、"删掉的钉不会再出现"。名字与群系跟上游已有的重了会自动跳过，不会出双份。
指引石	1.0.4+：把迷雾之地那条规则也填成 Component=typeof(Vegvisir)，交给上游自己的新机制；本补丁的扫描器保留作兜底（上游落过钉的位置会被去重记录挡住，不会双钉）。 1.0.2/1.0.3：上游没有这条通道，靠本补丁挂在它自己的 AutoPins.Sweep 之后，沿用它的扫描节奏与探索半径找玩家附近的 Vegvisir 组件，再调它自己的 AutoPins.Place(rule, null, pos) 落钉。

补的规则（开关出现在 BetterMap 自己的 cfg 里）：

规则名	分区	位置名（ZoneLocation.m_prefabName）	默认	中文图钉名
Infested Mines	Auto Pins - Mistlands	Mistlands_DvergrTownEntrance1、…2	开	腐疫矿区
Morgen Holes	Auto Pins - AshLands	MorgenHole1、2、3	开	腐朽之穴
Frost Caves	Auto Pins - Mountain	MountainCave02（1.0.4 上游已有，会自动跳过）	开	冰霜洞穴
Hildir Cave	Auto Pins - Mountain	Hildir_cave	关	希尔迪洞穴
Hildir Crypt	Auto Pins - BlackForest	Hildir_crypt	关	希尔迪墓穴
Hildir Fortress	Auto Pins - Plains	Hildir_plainsfortress	关	希尔迪平原要塞
Half Burried Crypt	Auto Pins - BlackForest	HalfBurried_ForestCrypt（实测 m_enable=**False**，原版不放置）	关	半埋墓穴
Vegvisirs	Auto Pins - Mistlands	组件通道 Vegvisir（1.0.4+）/ Vegvisir_SeekerQueen（旧版）	开	沿用游戏本地化

位置名不是猜的：本地化表 resources.assets 里 location_dvergrtown = Infested Mine = 简中「腐疫矿区」； 资产表 SoftRef/manifest 里 Assets/world/Locations/Mistlands/Mistlands_DvergrTownEntrance1.prefab 等。 名字如果写错，BetterMap 自己的自检会打 "watches a place named X, which this game has none of" —— 日志里没有这条就说明名字对。

本补丁自己的配置（BepInEx/config/bettermapfix.client.only.cfg）

键	默认	说明
1 - General / Enabled	开	总开关
2 - Vegvisirs / Scan Vegvisirs	开	指引石补标记（1.0.4 上相当于兜底）
3 - Caves / Inject Cave Rules	开	注入上面那几条洞穴规则
4 - Labels / Log Unknown Pin Names	开	诊断：把映射表没命中、且像英文的图钉名打进日志（去重，最多 60 个）。看到不认识的英文名就加进 Name Map
4 - Labels / Chinese Labels	开	图钉名中文化
4 - Labels / Name Map	71 条	内置表已覆盖 BetterMap 全部规则名 + 2 条 NameToken 变体，正常不用动。写 英文名=你的译名 可覆盖；写 英文名=（值留空）= 删掉这一条
4 - Labels / Merge Default Map	开	把内置默认译名表合并进上面那张表（你的条目优先）。见下节
4 - Labels / Rename Existing Pins	开	连已放在地图上的旧图钉一起改名
9 - Debug / Dump Location Names	关	世界加载后把游戏的地点表整表打进日志，用来核对位置名
9 - Debug / Verbose Pin Log	开	每落一个指引石图钉打一行日志

为什么需要 Merge Default Map

BepInEx 的配置有个特性：cfg 文件里已经存在某个键时，它不会用新的默认值覆盖文件里的旧值。

于是本补丁每次升级新增的内置译名，对"cfg 里早就写过旧表"的老用户永远不会生效 —— 症状是「新补的图钉标出来了，但名字还是英文」。补丁 1.1.0 实际踩到了这个坑： 新增 Infested Mines=腐疫矿区 之后，腐疫矿区图钉能标出来，名字却仍是 Infested Mines。

所以现在会把内置表与你的表做并集（内置先铺、你的覆盖）：

你想做的事	怎么做
什么都不管，希望自动获得新译名	保持 Merge Default Map = 开（默认）
改某条的译名	在 Name Map 里写 英文名=你的译名（你的优先）
删掉某条内置译名	在 Name Map 里写 英文名=（值留空）
完全自己掌控，不要任何内置译名	关掉 Merge Default Map

图钉中文化怎么实现的（只动标签这一层）

原模组落钉时用 PinNames.For(Rule, GameObject) 算图钉名；地点类规则的 NameToken 是空的、 go 传 null ⇒ 图钉名就等于英文规则名（这就是 Troll Caves / Bear Caves 的由来）。 本补丁只给这个函数的返回值做精确整串替换：

• 不改 rule.Name —— 那是原模组 cfg 的键名，改了会把你的配置项也改名；
• 不动规则表、图标、图例、去重记录；
• 表里没有的名字原样放行，所以只影响你想翻的那几个。

内置表覆盖 BetterMap 全部 69 条规则名，外加 2 条 NameToken 变体（共 71 条，见下方 ⚠️）。

为什么必须全覆盖：图钉名由 PinNames.For(Rule, GameObject) 决定， 只有 NameToken 与 For(go) 两条路都取不到名字时，才会兜底用英文规则名； 而 AutoPins.Place 里没有任何本地化调用 ⇒ 落到兜底支的图钉就是英文。 会落到兜底支的包括：① 全部地点类规则（落钉时 go 传 null）； ② 预制体类里那些没有 Piece / Pickable / MineRock 组件的预制体（如 Leviathans）。 与其逐个判断哪些预制体缺组件，不如一次全覆盖 —— 整串精确匹配，多余条目无副作用。

译名优先取游戏自己的本地化表，与你在游戏里看到的名词一致；游戏里没有的才自拟（ Sulfur Arches / Frozen Trolls / Ash Pots / Unstable Lava Rock）。 Leviathans 现为「甲壳素」（按需求定的译名）。

⚠️ 有一类图钉名不是规则名，而是规则的 NameToken（PinNames.For 的第一分支）： 若 NameToken 是 $ 开头的本地化键（如 $piece_vegvisir），游戏自己会翻，不用管； 但若它是裸英文，就原样显示。上游有两条这样的规则 —— Ash Pots 的 NameToken = "Ash Pot"、Greydwarf Nests 的 NameToken = "Greydwarf Nest" （规则名复数、钉名单数）⇒ 只写规则名（复数）永远命不中，单数写法也必须收进表里（1.1.12 补）。

⚠️ 替换挂在两个地方：PinNames.For（规则路径）+ Minimap.AddPin（兜底）。 全量反汇编 BetterMap 1.0.4 发现 Minimap.AddPin 有 6 个调用方 （AutoPins.Place / CreatureTracker.Add / NamedPins.Retag / DeathMarkers.Rebuild / VehicleTracker.Reconcile / AutoPins.Portal）， 而只有 AutoPins.Place 走 PinNames.For —— 生物、传送门、死亡标记这些路径各自算名字， 只补前者会漏（1.1.1 就漏了 Leviathans）。在 AddPin 上兜一层后与走哪条路无关。

Name Map 里键名写错只会静默不生效，所以交付前有一条机器校验（拿 BetterMap.dll 的字符串堆逐个核）。

旧图钉：名字是落钉那一刻写进地图数据的，光改上面那个函数对它们无效， 因此另有一趟 2 秒一次的低频重命名，只动名字精确命中映射表的图钉，直接改显示文本（不重建 UI）。

指引石仍然听 BetterMap 各群系里的 Vegvisirs 开关 —— 本补丁不改它。

怎么确认它在干活

日志里出现这些就说明工作正常：

[Info   : BetterMapFix] BetterMapFix 1.1.2 已加载：洞穴规则注入=True，指引石扫描=True，中文图钉名=True（接口自检通过）。
[Info   : BetterMapFix] 检测到 BetterMap 支持 Rule.Component（1.0.4+）：是 —— 迷雾之地 Vegvisirs 交给它自己的「Location 内部组件」通道，本补丁扫描仅兜底。
[Info   : BetterMapFix] 中文名映射 = 内置 71 条 ∪ 用户表（覆盖 33 / 用户新增 0 / 显式删除 0）→ 生效 71 条
[Info   : BetterMapFix] +规则 [Mistlands] Infested Mines → Mistlands_DvergrTownEntrance1, Mistlands_DvergrTownEntrance2（默认 开，地点类）
[Info   : BetterMapFix] +规则 [AshLands] Morgen Holes → MorgenHole1, MorgenHole2, MorgenHole3（默认 开，地点类）
[Info   : BetterMapFix] +规则 [Mistlands] Vegvisirs → 组件 Vegvisir（默认 开，组件类）
[Info   : BetterMapFix] 规则 [Mountain] Frost Caves 已存在（原模组自己提供，或本补丁已注入过），跳过。
[Info   : BetterMapFix] 已有图钉改中文名 1 个（累计 1 个）。
[Info   : BetterMapFix] 指引石已标记 [Mountain] 位置 1234.5,-678.9（距玩家 42.3 m）
[Info   : BetterMapFix] 本轮扫到附近指引石 2 块 → 新落钉 1，跳过 1（已记过账 / 该段开关关着）。

「中文名映射」那行的三个数字要盯一下：生效条数应当 ≥ 内置条数（71）。 若生效条数明显少于内置条数，说明 Merge Default Map 被关了。

装的是 BetterMap 1.0.4 时两条都是正常的：

• +规则 [Mountain] Frost Caves … 已存在，跳过 —— 上游自己有了，本补丁不重复注入（预期行为）；
• BetterMap 仍可能对 Vegvisir_SeekerQueen 打 "which this game has none of" 警告 （1.0.2/1.0.3 上是因为我们把它放进了规则表，而它的 ZDO 扫描永远够不着）； 在 1.0.4 上我们改走组件通道，这条警告应该消失。

兼容性

• 面向 BetterMap 1.0.2 / 1.0.3 / 1.0.4（xtav1m.BetterMap）编写，按版本自动选择通道： 有 Rule.Component（1.0.4+）就走上游的组件机制，没有就退回本补丁自己扫描。
• 所有内部调用都走反射并做存在性自检；Rule.Component 是可选字段， 缺了不会让自检失败（否则 1.0.2 上会把整个补丁停用）。 BetterMap 换版本时本补丁只会打印一条"接口自检不通过"并停用，不会拖垮游戏加载。
• 纯客户端、不声明 NetworkCompatibility（NotEnforced）⇒ 主机不装也能用、不挡联机。
• 只读场景对象与本地地图数据，不改任何网络权威数据。

卸载

删掉 BepInEx/plugins/<这个包>/BetterMapFix.dll 即可。 留在 BetterMap cfg 里的那几个键（Infested Mines / Morgen Holes 等）删不删都行， 删掉下次启动会按默认值重建。