寻路者 [小地图]

🗺️ Wayfinder

一款用于 Hytale 的服务端小地图插件，可显示带有地图图像、指南针方向和坐标的实时 HUD 叠加层。

需要注意的是，此模组更像是一个概念验证/技术演示，而非完善的产品。虽然它在基本使用场景下功能正常，但仍存在一些限制和粗糙之处需要了解：

• 小地图是固定的 40x40 像素网格，不支持平移或滚动
• 地图图像比较基础，可能无法精确表示所有生物群系或建筑
• 未实现路径点、标记或自定义图标等高级功能
• 性能可能因服务器硬件和玩家数量而异


📋 依赖项

插件	版本	必需
MultipleHUD	1.0.2+	否 (可选)

注意： MultipleHUD 是可选的。如果已安装，Wayfinder 将使用它来与其他 HUD 插件兼容。如果未安装，Wayfinder 会直接显示 HUD，但如果你有其他 HUD 模组，则可能出现冲突，导致崩溃、显示问题、地图空白、被服务器踢出等情况。

⚠️ 已知不兼容性

插件	问题	替代方案
EyeSpy	导致小地图渲染为空白	Blocchio

✨ 特性

• 📍 实时小地图 — 40x40 像素网格，显示实际的世界地图数据
• 🧭 指南针显示 — 显示基本方向（N, NE, E, SE, S, SW, W, NW）和度数航向
• 📐 坐标显示 — 实时显示 X, Y, Z 坐标
• 🕐 游戏内时钟 — 显示当前游戏内时间（12小时或24小时制），带太阳/月亮指示器
• 🔍 可配置缩放等级 — 多个缩放预设（近、中、远）
• ⏱️ 可配置更新频率 — 选择极快、快速、正常或慢速
• 🔲 形状选择 — 将小地图显示为方形或圆形
• 📍 可调整位置 — 将小地图移动到屏幕的任意角落
• 🔴 敌对 NPC 标记 — 将附近的敌对生物显示为小地图上的彩色圆点
  • 可配置检测模式：静态 NPC 类型列表（支持通配符）或基于态度
  • 可在服务器和单人玩家级别自定义标记颜色
  • 服务器范围和单人玩家切换开关
• 🔵 玩家标记 — 将其他玩家显示为小地图上的彩色圆点
  • 可在服务器和单人玩家级别自定义标记颜色
  • 服务器范围和单人玩家切换开关
• 🔄 地图旋转 — 选择北向上（固定）或随玩家旋转方向
• ➡️ 方向性玩家指示器 — 在“北向上”模式下显示箭头指示玩家朝向
• 💾 每位玩家设置 — 可见性、缩放、位置、标记、时钟格式和旋转偏好设置会在会话间持久保存
• ⚡ 性能优化 — 仅当玩家位置变化时更新地图像素
• 🚀 性能模式 — 可选的交错更新，将像素变化分散到多个帧，以减少客户端卡顿
• 🎛️ 游戏内设置 UI — 通过可视化界面轻松配置

🎮 命令

命令	别名	描述
/wayfinder open	/wf open	显示小地图
/wayfinder close	/wf close	隐藏小地图
/wayfinder toggle	/wf toggle	切换小地图可见性
/wayfinder settings	/wf settings	打开设置菜单

⚙️ 配置

服务器配置

位于 mods/x3Dev_Wayfinder/config.json：

{
  "ZoomLevels": {
    "Close": 1,
    "Medium": 2,
    "Far": 4
  },
  "DefaultZoom": "Medium",
  "DefaultCorner": "TopLeft",
  "DefaultShape": "Square",
  "UpdateFrequencyOptions": {
    "Very Fast": 100,
    "Fast": 250,
    "Normal": 500,
    "Slow": 1000
  },
  "DefaultUpdateFrequency": "Normal",
  "UpdateIntervalMs": 500,
  "InitialDelayMs": 500,
  "AutoShowOnJoin": true,
  "EnableHostileMobTracking": true,
  "HostileMobColor": "#ff3333",
  "HostileMobRange": 48,
  "UseHostileList": true,
  "HostileNpcTypes": ["Skeleton*", "*_Void", "Trork_*", "Goblin_*"],
  "EnablePlayerTracking": true,
  "PlayerMarkerColor": "#3399ff",
  "PlayerTrackingRange": 64
}

选项	类型	默认值	描述
ZoomLevels	Map	Close: 1, Medium: 2, Far: 4	可用的缩放等级 (名称 -> 每像素方块数)
DefaultZoom	String	"Medium"	新玩家的默认缩放等级
DefaultCorner	String	"TopLeft"	新玩家的默认小地图位置。有效值：TopLeft, TopRight, BottomLeft, BottomRight
DefaultShape	String	"Square"	新玩家的默认小地图形状。有效值：Square, Circle
UpdateFrequencyOptions	Map	Very Fast: 100, Fast: 250, Normal: 500, Slow: 1000	可用的更新频率 (名称 -> 毫秒)
DefaultUpdateFrequency	String	"Normal"	新玩家的默认更新频率
UpdateIntervalMs	Integer	500	小地图更新之间的旧版回退毫秒数
InitialDelayMs	Integer	500	显示小地图后首次更新前的延迟
AutoShowOnJoin	Boolean	true	玩家加入时自动显示小地图
EnableHostileMobTracking	Boolean	true	小地图上敌对 NPC 标记的总开关
HostileMobColor	String	"#ff3333"	敌对 NPC 标记的默认十六进制颜色
HostileMobRange	Integer	48	检测敌对 NPC 的范围 (方块) (8-128)
UseHostileList	Boolean	true	true = 使用 HostileNpcTypes 列表，false = 使用 NPC 态度系统
HostileNpcTypes	Array	(见下文)	标记为敌对的 NPC 类型模式。支持通配符：Skeleton* (前缀)，*_Void (后缀)，*Spider* (包含)
EnablePlayerTracking	Boolean	true	小地图上玩家标记的总开关
PlayerMarkerColor	String	"#3399ff"	玩家标记的默认十六进制颜色
PlayerTrackingRange	Integer	64	检测其他玩家的范围 (方块) (8-128)

玩家配置

每位玩家的配置存储在 mods/x3Dev_Wayfinder/players/{uuid}.json：

{
  "PlayerUuid": "player-uuid-here",
  "Visible": true,
  "Zoom": 2,
  "Corner": "TopLeft",
  "Shape": "Square",
  "UpdateIntervalMs": 500,
  "ShowHostileMobs": true,
  "HostileMobColor": null,
  "RotateWithPlayer": false,
  "Use24HourClock": false,
  "ShowPlayers": true,
  "PlayerMarkerColor": null,
  "PerformanceMode": false
}

选项	类型	默认值	描述
Visible	Boolean	true	小地图当前是否显示
Zoom	Integer	2	当前缩放等级 (每像素方块数)
Corner	String	"TopLeft"	小地图在屏幕上的位置
Shape	String	"Square"	小地图形状 (Square 或 Circle)
UpdateIntervalMs	Integer	500	以毫秒为单位的更新频率 (来自服务器选项)
ShowHostileMobs	Boolean	true	是否显示敌对 NPC 标记
HostileMobColor	String	null	自定义敌对标记颜色覆盖 (null = 使用服务器默认值)
RotateWithPlayer	Boolean	false	false = 北始终向上，true = 地图随玩家旋转
Use24HourClock	Boolean	false	false = 12小时制 (AM/PM)，true = 24小时制
ShowPlayers	Boolean	true	是否在小地图上显示其他玩家
PlayerMarkerColor	String	null	自定义玩家标记颜色覆盖 (null = 使用服务器默认值)
PerformanceMode	Boolean	false	启用交错像素更新以减少客户端卡顿

⚠️ 性能考量

重要提示： Wayfinder 是一个服务端模组。所有小地图的渲染和更新都由服务器处理，并通过 UI 数据包发送给客户端。

针对高人口服务器的建议

如果你计划在拥有大量同时在线玩家的服务器上运行 Wayfinder，请考虑以下调整：

玩家数	推荐的 UpdateIntervalMs
1-3	100
4-5	200-300
6-10	500
11+	1000

注意：我未测试过上述值，具体取决于你的服务器硬件。请根据实际性能和玩家体验进行调整。

附加提示：

• 🔄 小地图仅在玩家位置发生变化时发送像素更新，减少了不必要的流量
• 📊 监控服务器性能并相应地调整 UpdateIntervalMs
• 🚫 考虑将 AutoShowOnJoin 设置为 false，让玩家在大型服务器上主动选择加入
• 🔍 更高的缩放等级（每像素更多方块）可能会降低更新频率，因为玩家相对于地图的遍历速度更快

性能模式

如果玩家在小地图更新时遇到客户端卡顿，他们可以在设置菜单中启用性能模式。这会将像素更新分散到多个帧：

模式	行为	最适合
关闭 (默认)	所有 1,600 个像素同时更新	最佳的视觉响应
开启	更新分为 2 个水平带	减少客户端卡顿

启用性能模式后：

• 40x40 网格被分为上半部分和下半部分
• 每半边在交替的游戏刻更新
• 完整刷新一次地图需要 2 个更新周期，而不是 1 个
• 更新周期始终会完整完成，即使玩家停止移动（防止半幅地图不同步）

📦 安装

1. 下载 Wayfinder 并将其放入服务器的 mods 文件夹
2. (可选) 下载 MultipleHUD 以与其他 HUD 插件兼容
3. 启动服务器 — 将自动创建默认配置
4. 根据服务器需求调整 config.json