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

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

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)

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

📦 Installation

Download Wayfinder and place into your server's mods folder

(Optional) Download MultipleHUD for compatibility with other HUD plugins

Start the server — default configuration will be created automatically

Adjust config.json as needed for your server's requirements