You are viewing a potentially older version of this package. View all versions.
s6652289-EasyPortal-1.0.2 icon

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.

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-5.4.2350 icon
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.2350

README

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 - Detection
    • Radius 60 / ScanInterval 5 / ActiveSeconds 10 —— 三个主参数
    • RequireTag:没名字的门是否跳过(默认跳过)
    • RehighlightOnRedetect:默认 false —— 每个门只高亮一次,站在自己家门口不会一直亮; 想让范围内的门一直保持高亮就改 true
    • ToggleKey:游戏里开关用的快捷键(默认未绑定,别和 OreFinder 的 F9 撞)
  • 2 - Highlight
    • BeamColor 格式 R,G,B,A,默认 0.95,0.62,0.10,0.75(琥珀色半透明)
    • BeamHeight 22 / BeamWidth 0.6 / LightRange 12 / LightIntensity 2
  • 3 - Screen Marker
    • ArrowSize 26 / FontSize 16 / EdgeMargin 60 / ShowDistance true
  • 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 声明、无内嵌同步框架,主机不装也能用、不挡联机。