Please disclose if any significant portion of your mod was created using AI tools by adding the 'AI Generated' category. Failing to do so may result in the mod being removed from Thunderstore.
EasyPortal
[AI-generated] Every 5 s, finds portals within 60 m, highlights them for 10 s, draws a screen arrow with the tag and distance, and auto-places a named map pin (portal icon) that follows the portal. Portal clusters are skipped. Client-only.
By s6652289
| Date uploaded | 2 months ago |
| Version | 1.0.2 |
| Download link | s6652289-EasyPortal-1.0.2.zip |
| Downloads | 34 |
| Dependency string | s6652289-EasyPortal-1.0.2 |
This mod requires the following mods to function
denikson-BepInExPack_Valheim
BepInEx pack for Valheim. Preconfigured with the correct entry point for mods and preferred defaults for the community.
Preferred version: 5.4.2350README
EasyPortal
传送门探测器。 纯客户端模组 —— 每 5 秒扫一遍周围 60 米内的传送门,探测到就高亮 10 秒、 在屏幕上用箭头指向它(带标签名与距离),并在地图上按标签名自动打图钉。
AI 生成声明:本模组由 AI 智能体(WorkBuddy)在用户的明确需求与逐项验收下编写; 需求描述、交互设计与发布决定均由用户主导。
功能
| # | 功能 | 默认 | 配置节 |
|---|---|---|---|
| 1 | 每 N 秒探测周围 R 米内的传送门 | 5 秒 / 60 米 | 1 - Detection |
| 2 | 探测到就高亮 M 秒(光柱 + 脉动点光) | 10 秒 | 1 - Detection / 2 - Highlight |
| 3 | 屏幕上画箭头指向它,显示标签名 + 距离(m) | 开 | 3 - Screen Marker |
| 4 | 地图上按标签名打图钉;同名旧图钉自动挪过来 | 开 | 4 - Map Pin |
| 5 | 传送门群(家里那一片)整体跳过 | 开 | 1 - Detection |
1.0.2 改动: ① 地图图钉图标默认改为
Portal,且已有的同名图钉会自动换成新图标(不必手动删); ② 修掉两处误导性日志/策略 —— 传送后"登记册为空"属正常,不再错报Warning; 兜底扫描改为带冷却重试(原来只试一次)。详见CHANGELOG.md。
传送门群(建在一起的门)整体跳过
家里的传送门通常是建在一起的。如果逐个高亮 + 逐个建图钉,等于在一个地图坐标上叠一堆图标、
屏幕上还挂一排箭头。所以本模组会先把探测到的门按物理位置聚簇,
任何一片里门数达到 ClusterSkipMin 就整片都不标记(不高亮、不画箭头、不建图钉)。
配置(1 - Detection) |
默认 | 说明 |
|---|---|---|
SkipClusters |
true | 总开关。关掉就按普通规则逐个处理 |
ClusterRadius |
12 米 | 判定「聚在一起」的间距。链式判定 —— 一排门只要彼此相邻,就会连成同一大片 |
ClusterSkipMin |
2 | 一片里达到几个门就整体跳过 |
判定用的是本轮探测到的、且会参与标记的门(没起名的门不算),所以刚放下一个还没命名的门, 不会把旁边正常的门误带进"群"里。
想让小规模(两三个门)照常标记、只有大群才跳过,把
ClusterSkipMin调大即可。被跳过的门若此前已建过同名图钉,会被一并清掉(受
TakeOverSameName约束), 免得地图上留一个永不更新的图标。
地图图钉的规则(重点)
| 情况 | 行为 |
|---|---|
| 该位置附近已有同名图钉 | 什么都不做("已经有图标了不用标记") |
| 该标签只探测到 1 个传送门,且地图上同名图钉在别处 | 删掉旧位置的、在新位置重建("=> 移动了同标签传送门,不用手工去删旧图标") |
| 该标签同时探测到多个传送门 | 各自保一个图钉,互不删除 |
| 没设标签的传送门 | 默认跳过,不标记也不高亮 |
最后一条是多加的保护:原版里两个同标签的传送门是互相连通的(很常见), 若不加区分,两头会被反复"删旧建新",图钉一直在闪。 只有"该标签当前只看到一个门"时才执行自动迁移 —— 那才是真正的"把门搬走了"。
⚠️
TakeOverSameName开启时会一并接管你手工放的同名图钉。 不想要就把它关掉(那样只补建、不删除)。
配置
BepInEx/config/easyportal.client.only.cfg
1 - DetectionRadius60 /ScanInterval5 /ActiveSeconds10 —— 三个主参数RequireTag:没名字的门是否跳过(默认跳过)RehighlightOnRedetect:默认 false —— 每个门只高亮一次,站在自己家门口不会一直亮; 想让范围内的门一直保持高亮就改 trueToggleKey:游戏里开关用的快捷键(默认未绑定,别和 OreFinder 的 F9 撞)
2 - HighlightBeamColor格式R,G,B,A,默认0.95,0.62,0.10,0.75(琥珀色半透明)BeamHeight22 /BeamWidth0.6 /LightRange12 /LightIntensity2
3 - Screen MarkerArrowSize26 /FontSize16 /EdgeMargin60 /ShowDistancetrue
4 - Map Pin—— 见上面那张规则表5 - Debug→Verbose:排查用,每次扫描与建图钉都打日志
⚠️ 改完必须重启游戏(BepInEx 只在插件 Awake 读一次配置)。
实现要点(来自 IL 实证,2026-09-17)
- 传送门类叫
TeleportWorld(不叫Portal);标签名读TeleportWorld.GetText(), 其内部是 ZDO 字符串ZDOVars.s_tag再过一遍敏感词过滤。 - 枚举传送门:不在扫描时全场景搜 —— Valheim 的 ZDO 是按距离流式实例化的,
远处的门根本不在场景里,搜也搜不到,而且每 5 秒搜一遍代价太大。
改为
TeleportWorld.Awake时登记进册(PortalRegistry),扫描时只做"剔除已销毁 + 距离筛选"。 另带一条兜底:登记册为空时会用ZNetScene.m_instances(反射)扫一次并打警告, 免得像 EasyGear 1.0.0 那样静默失效。 - 地图图钉走原版
Minimap.AddPin / RemovePin(public)。 参数照抄原版玩家放图钉的调用方式(ShowPinNameInput的 IL):类型由PinIcon决定,save=true跟着地图存档。RemovePin内部会DestroyPinMarker,图标与名字标签一起清掉。Minimap.PinType/Minimap.PinData是Minimap的嵌套类型(踩过,编译期才会发现)。 - 换图钉图标为什么必须"删旧建新":
Minimap.UpdatePins的 IL 显示m_iconElement.set_sprite(m_icon)只在 UI 元素被重建时才执行 (先判m_uiElement == null或父节点不对)⇒ 已存在的图钉不会重新set_sprite, 光改PinData.m_icon字段界面不会刷新。所以本模组在检测到图标不符时删掉重建。 另有防死循环保护:AddPin在类型不可用时会悄悄把类型改写成 Dot, 若不设限就会无限删建 —— 故每个标签最多升级一次(IconUpgradeTried)。 - 屏幕箭头走 IMGUI(
OnGUI),完全不碰游戏的 uGUI 层级 —— 所以不怕后续版本改 UI 预制体。世界坐标 → 屏幕用Camera.main.WorldToViewportPoint, 相机背后的情况要手动把镜像坐标翻回来。 - 中文字体:IMGUI 内置字体没有中文字形,直接画中文会是方块。
解发是
Font.CreateDynamicFontFromOSFont从系统字体现造一个(优先"微软雅黑")。 - 箭头/底色贴图用
Texture2D.SetPixels32运行时生成,不依赖任何美术资源。
兼容性
- 纯客户端:无 Jotunn、无 ServerSync、无
NetworkCompatibilityAttribute(NotEnforced)。 - 联机:主机与其他玩家都不需要装;只读场景与本地地图数据,不改任何网络权威数据。
- 与 OreFinder 功能重叠但不冲突 (都往地图加图钉,但图钉互不干扰)。默认快捷键未绑定,避免与它的 F9 撞车。
安装
r2modman「Install from file」选 EasyPortal-1.0.0.zip,
或把 EasyPortal.dll 丢进 BepInEx/plugins/。
前置:BepInExPack_Valheim 5.4.2350。
版本
- 1.0.0(2026-09-17):首个版本。
CHANGELOG
更新日志
1.0.4(2026-09-17)
调整:传送门群的判定间距 12 米 → 20 米。
- 起因:「传送门簇的检测加上一个传送门周围的 20 米内」。
1 - Detection → ClusterRadius默认值改为 20 米:一个传送门周围 20 米内有别的门, 就算同一片。仍是链式判定(一条链上的门彼此相邻就连成一大片)。- 影响:原本被漏判成"两个独立门"的中等间距(12~20 米)现在会正确判成门群并整片跳过。 例:两门相距 15 米 —— 旧默认会都标记,新默认整片跳过。 相距 40 米仍不属同一片(照常标记);相距 5 米仍跳过。
- ⚠️ 已存在
easyportal.client.only.cfg的也要一起改 —— 只改代码默认值对已生成的 cfg 无效(BepInEx 只在配置项首次创建时写默认值)。 本次已同时把 cfg 里的ClusterRadius = 12改成20(改前有备份)。 - 想调回去:把
ClusterRadius改回 12 即可(或按需调成任意 1~60 的值)。
离线验证
verify_portal_cluster.py 更新到 20 米后重跑,并新增一组改动效果对照:
- 边界确认:19.9 / 20.0 米 → 跳过;20.1 米 → 照常标记(20.0 为闭区间)
- 12~20 米之间(12.5 / 15.0 / 18.0 / 19.5)在新默认下全部正确判成簇, 并标注"旧默认(12)会漏判成两个独立门" 原有 8 个场景(家里门群成片跳过、一排门链式连成一片、野外单门照常标记、 两门 40 米各自标记、门群在探测圈外不参与 等)在新参数下结论不变。
1.0.3(2026-09-17)
三项改动:标签底衬改成 OreFinder 同款、已标记的门不再重复检测、传送门被拆自动删图标。
1. 标签底衬 → OreFinder 同款(LabelBackground = Outline,默认)
- 起因:「箭头显示的背景是黑色的,改成和 OreFinder 一样的背景色」。
- 实查 OreFinder:它的
MarkerOverlay.DrawLabel根本不画任何背景块 —— 全程序集里GUI.DrawTexture的调用者为 0。它的做法是GUI.color=(0,0,0,a)画一次偏移 +1 的文字(黑描边),再GUI.color=(1,1,1,a)画原位文字(白字)。 - ⇒ 现在默认同样不画底块,改用一圈黑色描边保证可读性。
- 新增
LabelBackground可选:Outline(默认,OreFinder 同款)/Box(旧的半透明色块)/None(纯文字);Box模式下底块颜色由新增的LabelBoxColor控制。 - 🔴 顺带修掉一个真 bug:旧实现画完底块后没有恢复
GUI.color, 而GUI.Label的实际颜色 =GUI.color×style.normal.textColor⇒ 紧接着的文字被乘黑、整体半透明 —— 这才是「整块发黑」观感的主因(不只是底块本身黑)。 现在每一段绘制前都显式设好GUI.color,并在finally里还原。
2. 已标记过的传送门不再重复检测(SkipAlreadyPinned = true,默认)
- 起因:「同一个传送门会一直被标记,如果被标记过了就不要再检测了」。
- 现在一个门被标记过之后,后续扫描直接略过它:不再高亮、不再画屏幕箭头、不再重复建图钉。
- 🔑 身份用的是游戏的网络对象 id(
ZDOID),不是标签名。 这点很关键: 若用标签名做身份,「搬门」= 拆掉重建(标签没变、位置变了)就会被误判成"已标记过"、 永远不再标记,直接破坏"搬门要更新图标"这条既有行为。ZDOID天然区分:同一个门 id 不变;拆掉重建必然是新 id。 - 拿不到
ZDOID时(理论上不该发生)该门退回旧行为(每轮照常处理),并不会被错误地记住。 - 想回到旧行为(每次靠近都高亮)把这项设为
false即可,配合RehighlightOnRedetect使用。
3. 传送门被拆掉 → 自动删除地图标记
- 起因:「如果传送门没了,自动从地图上删除标记」。
- 追踪表会检测:玩家就在它附近、却连续 2 轮都探测不到 → 判定已被拆除 → 按「标签 + 位置」精确删除对应图钉(不会误伤别处的图钉),并清掉追踪记录。
- ⚠️ 两条防误删约束(都是为了不出现"图钉莫名其妙消失"):
- 必须玩家在附近(该位置落在探测半径内)—— 远处的门无法验证: ZDO 是按距离流式加载的,查不到 ≠ 被删。玩家走远时保留图钉,并重置计数 (避免把"走远了"攒成"被拆了",回来时图钉已被误删)。
- 必须连续 2 轮 —— 单轮漏看可能是瞬时抖动(刚传送完场景还在加载、对象正在销毁)。
- 门被拆后重建会得到新
ZDOID⇒ 会被当作新门重新标记(图钉重新出现),无需手动干预。
离线验证
verify_portal_tracking.py 13 组用例全过,重点覆盖:
- 首次标记 → 再探跳过 → 连扫 20 轮零重复标记
- 门被拆:第 1 轮不判拆(防抖动)、第 2 轮判拆;追踪记录被清除
- 玩家走远 10 轮:绝不误判为被拆,且计数被重置
- 搬门(同标签、新 ZDOID)→ 正确重新标记,旧门随后被清理
- 混合场景(部分已标记 / 新增 / 被拆)三者并存时互不干扰
SkipAlreadyPinned=false回到旧行为;ZDOID取不到时退回每轮处理- 探测半径边界(59.9 / 60.0 / 60.1 米)
⚠️ 本脚本第一版有 2 个 FAIL,查下来都是我自己的测试写错了轮次 (判拆需要连续 2 轮,而我多扫了一轮把期望值算错),实现逻辑本身是对的。 教训:带状态累进的逻辑,写用例时要把"第几轮"数准。
1.0.2(2026-09-17)
改动一:地图图钉图标默认改为 Portal,并且已有图钉会自动跟着换。
PinIcon默认值Dot→Portal(传送门用传送门图标最直观)。 另外本机已生成的easyportal.client.only.cfg也已同步改成PinIcon = Portal—— 只改代码默认值对已存在的 cfg 无效,必须同时改 cfg。- 已有图钉会自动迁移图标:发现「位置对得上、但图标不是当前配置那个」时,
删旧建新。所以你把
PinIcon从 Dot 改成 Portal 后,地图上原来那些传送门图钉 会自己换成 Portal 图标,不必手动删。 - ⚠️ 为什么必须"删旧建新"而不能直接改
PinData.m_icon字段:Minimap.UpdatePins的 IL 显示m_iconElement.set_sprite(m_icon)只在 UI 元素被重建时才执行(先判m_uiElement == null或父节点不对), 已存在的图钉不会重新 set_sprite ⇒ 光改字段 UI 不刷新、图标看着不变。 删掉后m_uiElement被置 null,重建时才会走到那一句。 - 🔴 防死循环:
Minimap.AddPin开头有一段边界判定(IL 实证)——if (type >= m_visibleIconTypes.Length || type < 0) type = 3;, 即请求的图标类型若不可用,原版会悄悄改写成 Dot。 万一发生,我们的「图标不符 → 删旧建新」每轮都会认为不符 → 无限删建。 故加了IconUpgradeTried集合:每个标签最多升级一次,升级后仍不符就放弃。 - 顺带新增图标改写检测:
AddPin后核对实际m_type,若被游戏改写会打Warning说明"你填的 X 在当前版本不可用,已退回 Dot",而不是让你对着"设了 Portal 却是 Dot"干瞪眼。 - 启动日志新增配置生效值一行,含解析后的
PinType:… 地图图钉=开(PinIcon="Portal" → Portal);…
改动二:修掉两处会误导人的地方(上一轮已完成)。
背景:真机日志里出现过
[Warning:EasyPortal] 登记册为空 → 已用兜底扫描补登记 0 个传送门。(…若非 0 说明挂载点没生效)
看起来像故障,但实际是完全正常的 —— 那次日志紧跟在 Teleportation TRIGGER 之后,
传送后旧场景的传送门 ZDO 被卸载、新地点附近没有传送门,所以登记册为空、兜底也扫不到。
- 日志级别按结果区分:原来无论结果都打
Warning。 现在只有「登记册为空 但 兜底扫描补登记到了 >0 个」才打Warning—— 那才说明TeleportWorld.Awake挂载点真的没生效。 补登记 0 个(附近本来就没有传送门)属正常,降为Verbose下的Info。 - 兜底扫描不再「只试一次」:原来用一次性标志,若第一次触发时玩家恰好在没有传送门的 野外(很常见),标志就永久置位、以后再也不会检测 —— 真出问题时反而发现不了。 改为带 20 秒冷却重试。
- 图标名日志加上映射说明:运行时
m_icons[].m_name报的是资源名Icon0..Icon4, 而 cfg 用的是可读名Fire / House / Hammer / Dot / Portal(按位置对应,不是同名)。 现在日志会打成Fire(=Icon0), House(=Icon1), …并附一句提示。
离线验证
verify_pin_icon_upgrade.py 7 个场景全过,其中两个是重点:
- 场景 3/4 证明不会无限删建:图标已对时 20 轮扫描零动作; 模拟"原版把类型改写成 Dot"时,50 轮也只删建 1 次(升级尝试一次后即放弃)。
- 场景 7 证明同标签双门稳定:5 轮扫描零动作,两个门各自的图钉都保留。
1.0.1(2026-09-17)
新增:「传送门群」整体跳过 —— 一个地方聚着多个门(例如家里那一片)就不标记它们。
- 起因:家里的传送门是建在一起的。1.0.0 会把它们逐个高亮、逐个建图钉, 等于在一张地图坐标上叠一堆图标、屏幕上还挂一排箭头。
- 现在的规则:把本轮探测到的门按物理位置聚簇(单链判定 —— 一排门彼此相邻即连成一片),
任何一片里达到
ClusterSkipMin(默认 2)个门,整片都不标记: 不高亮、不画屏幕箭头、也不建地图图钉。 - 涉及的配置(都在
1 - Detection):SkipClusters(默认 true)—— 总开关ClusterRadius(默认 12 米)—— 判定「聚在一起」的间距;链式判定,一排门会连成一片ClusterSkipMin(默认 2)—— 一片里达到几个就整体跳过
- 顺带处理:被跳过的门如果此前已建过同名图钉,会把它清掉(受
TakeOverSameName约束), 免得地图上留一个永不更新的图标;已经亮着的也会立刻熄灭。 - 聚簇统计只算"会被标记的门" —— 刚放下还没起名的门不会把旁边正常的门误带进"群"里。
- 离线复现验证 8 个场景 + 边界值(11.9/12.0/12.1 米): 家里 5 个门成片跳过 ✅ / 一排门间距 8 米链式连成一片 ✅ / 野外单个门照常标记 ✅ / 两门相距 40 米不属同一片、都标记 ✅ / 野外两门相距 5 米也跳过 ✅。
1.0.0(2026-09-17)
首个版本:传送门探测器。
- 每 N 秒(默认 5)探测周围 R 米(默认 60)内的传送门;带标签的才处理(可配)。
- 探测到高亮 M 秒(默认 10):向上一根光柱 + 一团脉动点光;
默认每个门只亮一次,站自己家门口不会一直亮(
RehighlightOnRedetect可改)。 - 屏幕上画箭头指向它:视野内压在目标上方朝下指,视野外贴屏幕边缘朝外指; 箭头旁显示标签名 + 距离(米)。
- 地图上按标签名打图钉;同名图钉已存在于别处时自动删旧建新(可关)。 为"两个同标签传送门同时可见"的情况加了保护:那种情况只各自补建、不会互相删。
- 中文字体:从系统字体现造(优先微软雅黑),否则中文标签会显示成方块。
- 纯客户端:无 Jotunn、无
NetworkCompatibility声明、无内嵌同步框架,主机不装也能用、不挡联机。