Wayfinder [Minimap]

🗺️ Wayfinder

A server-side minimap plugin for Hytale that displays a real-time HUD overlay with map imagery, compass direction, and coordinates.

Its worth noting that this mod is more of a PoC / tech demo than a fully polished product. While it functions well for basic use cases, there are some limitations and rough edges to be aware of:

• The minimap is a fixed 40x40 pixel grid and does not support panning or scrolling
• Map imagery is basic and may not represent all biomes or structures accurately
• Advanced features like waypoints, markers, or custom icons are not implemented
• Performance may vary based on server hardware and player count

📋 Dependencies

Plugin	Version	Required
MultipleHUD	1.0.2+	No (Optional)

Note: MultipleHUD is optional. If installed, Wayfinder uses it for compatibility with other HUD plugins. If not installed, Wayfinder displays the HUD directly, but if you do have other HUD mods, they may conflict and cause crashes, display issues, blank maps, kicks from the servers etc.

⚠️ Known Incompatibilities

Plugin	Issue	Alternative
EyeSpy	Causes the minimap to render blank	Blocchio

✨ Features

• 📍 Real-time Minimap — 40x40 pixel grid displaying actual world map data
• 🧭 Compass Display — Shows cardinal direction (N, NE, E, SE, S, SW, W, NW) with degree heading
• 📐 Coordinate Display — Live X, Y, Z coordinates
• 🕐 In-Game Clock — Displays current in-game time (12-hour or 24-hour format) with sun/moon indicator
• 🔍 Configurable Zoom Levels — Multiple zoom presets (Close, Medium, Far)
• ⏱️ Configurable Update Frequency — Choose from Very Fast, Fast, Normal, or Slow update speeds
• 🔲 Shape Selection — Display the minimap as a square or circle
• 📍 Adjustable Position — Move the minimap to any corner of the screen
• 🔴 Hostile NPC Blips — See nearby hostile mobs as colored dots on the minimap
  • Configurable detection mode: static NPC type list (with wildcards) or attitude-based
  • Customizable blip color at server and per-player level
  • Server-wide and per-player toggles
• 🔵 Player Markers — See other players as colored dots on the minimap
  • Customizable blip color at server and per-player level
  • Server-wide and per-player toggles
• 🔄 Map Rotation — Choose north-up (fixed) or rotate-with-player orientation
• ➡️ Directional Player Indicator — Arrow shows which way you're facing in north-up mode
• 💾 Per-Player Settings — Visibility, zoom, position, blips, clock format, and rotation preferences persist across sessions
• ⚡ Performance Optimized — Map pixels only update when player position changes
• 🚀 Performance Mode — Optional staggered updates spread pixel changes across multiple frames to reduce client stuttering
• 🎛️ In-Game Settings UI — Easy configuration through a visual interface

🎮 Commands

Command	Alias	Description
/wayfinder open	/wf open	Show the minimap
/wayfinder close	/wf close	Hide the minimap
/wayfinder toggle	/wf toggle	Toggle minimap visibility
/wayfinder settings	/wf settings	Open the settings menu

⚙️ Configuration

Server Configuration

Located at 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
}

Option	Type	Default	Description
ZoomLevels	Map	Close: 1, Medium: 2, Far: 4	Available zoom levels (name → blocks per pixel)
DefaultZoom	String	"Medium"	Default zoom level for new players
DefaultCorner	String	"TopLeft"	Default minimap position for new players. Valid values: TopLeft, TopRight, BottomLeft, BottomRight
DefaultShape	String	"Square"	Default minimap shape for new players. Valid values: Square, Circle
UpdateFrequencyOptions	Map	Very Fast: 100, Fast: 250, Normal: 500, Slow: 1000	Available update frequencies (name -> milliseconds)
DefaultUpdateFrequency	String	"Normal"	Default update frequency for new players
UpdateIntervalMs	Integer	500	Legacy fallback milliseconds between minimap updates
InitialDelayMs	Integer	500	Delay before first update after showing minimap
AutoShowOnJoin	Boolean	true	Automatically show minimap when players join
EnableHostileMobTracking	Boolean	true	Master toggle for hostile NPC blips on the minimap
HostileMobColor	String	"#ff3333"	Default hex color for hostile NPC blips
HostileMobRange	Integer	48	Detection range in blocks for hostile NPCs (8-128)
UseHostileList	Boolean	true	true = use HostileNpcTypes list, false = use NPC attitude system
HostileNpcTypes	Array	(see below)	NPC type patterns to mark as hostile. Supports wildcards: Skeleton* (prefix), *_Void (suffix), *Spider* (contains)
EnablePlayerTracking	Boolean	true	Master toggle for player markers on the minimap
PlayerMarkerColor	String	"#3399ff"	Default hex color for player markers
PlayerTrackingRange	Integer	64	Detection range in blocks for other players (8-128)

Player Configuration

Stored per-player at 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
}

Option	Type	Default	Description
Visible	Boolean	true	Whether the minimap is currently shown
Zoom	Integer	2	Current zoom level (blocks per pixel)
Corner	String	"TopLeft"	Minimap position on screen
Shape	String	"Square"	Minimap shape (Square or Circle)
UpdateIntervalMs	Integer	500	Update frequency in milliseconds (from server options)
ShowHostileMobs	Boolean	true	Whether to show hostile NPC blips
HostileMobColor	String	null	Custom hostile blip color override (null = use server default)
RotateWithPlayer	Boolean	false	false = north always up, true = map rotates with player
Use24HourClock	Boolean	false	false = 12-hour format (AM/PM), true = 24-hour format
ShowPlayers	Boolean	true	Whether to show other players on the minimap
PlayerMarkerColor	String	null	Custom player marker color override (null = use server default)
PerformanceMode	Boolean	false	Enables staggered pixel updates to reduce client stuttering

⚠️ Performance Considerations

Important: Wayfinder is a server-side mod. All minimap rendering and updates are processed by the server and sent to clients as UI packets.

Recommendations for High-Population Servers

If you plan to run Wayfinder on servers with many concurrent players, consider the following adjustments:

Players	Recommended UpdateIntervalMs
1-3	100
4-5	200-300
6-10	500
11+	1000

Note: I haven't tested the above values, it all comes down to your server hardware. Adjust based on actual performance and player experience.

Additional tips:

• 🔄 The minimap only sends pixel updates when a player's position changes, reducing unnecessary traffic
• 📊 Monitor server performance and adjust UpdateIntervalMs accordingly
• 🚫 Consider setting AutoShowOnJoin to false and letting players opt-in on very large servers
• 🔍 Higher zoom levels (more blocks per pixel) may reduce update frequency as players traverse the world faster relative to the map

Performance Mode

If players experience client stuttering when the minimap updates, they can enable Performance Mode in the settings menu. This spreads pixel updates across multiple frames:

Mode	Behavior	Best For
Off (default)	All 1,600 pixels update at once	Maximum visual responsiveness
On	Updates split into 2 horizontal bands	Reducing client-side stuttering

When Performance Mode is enabled:

• The 40x40 grid is divided into top and bottom halves
• Each half updates on alternating ticks
• A full map refresh takes 2 update cycles instead of 1
• The update cycle always completes fully, even if the player stops moving (prevents half-map desync)

📦 Installation

1. Download Wayfinder and place into your server's mods folder
2. (Optional) Download MultipleHUD for compatibility with other HUD plugins
3. Start the server — default configuration will be created automatically
4. Adjust config.json as needed for your server's requirements