🗺️ 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

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

✨ 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

⚙️ 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
}

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
}

⚠️ 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:

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:

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