Hytale BetterMap Plugin

Enhance your world exploration with saved map data, cave map rendering, customizable zoom, waypoints, shared mapping, and performance-optimized rendering.

License

ASK US BEFORE IF YOU WANT TO PUBLISH A FORKED VERSION OF THIS PLUGIN.
YOU CAN FORK IT AS YOU WANT FOR A PRIVATE USE, OR CONTRIBUTE TO THE ORIGINAL PROJECT.

What is this?

By default, the Hytale in-game map is fleeting. It only displays a small circular area around the player, and as soon as you walk away, the map "forgets" where you have been.

Hytale BetterMap changes this. This server plugin introduces a saved exploration feature. As you travel through the world, the plugin records the areas you have visited, effectively removing the "fog of war" permanently. Your map grows bigger the more you explore, allowing you to retrace your steps and navigate with ease.

Key Features

Persistent Exploration: The map retains all previously visited areas across sessions. Data is saved automatically to prevent loss during server crashes.
Cave Mode: Seamlessly switch to cave chunks when entering underground areas. Includes options to view surface data while mining or use a specific "Fog of War" for caves.
Enhanced Waypoint System: Manage locations using Hytale's native markers. Includes a user-friendly menu, "Here" button for quick updates, and context-menu editing options.
Interactive Teleportation: Players with permission can teleport to waypoints via the UI or by simply right-clicking a location on the map.
World Border Visualization: View the server's world border limits directly on your map.
Linked Exploration (Shared Map): Optionally enable a shared map mode where all players contribute to a single global map, allowing you to see areas discovered by friends in real-time.
Compass/Map player Radar: Easily locate other players nearby directly on your compass. The range can be customized or toggled off by admins.
Customizable HUD & UI: A new in-game configuration menu (/bm) allows you to adjust settings, manage waypoints, and access help without doing other commands.
Position HUD: A Position HUD (compatible with MultipleHUD) that displays your coordinates on-screen.
Map Anchors: Quick-access shortcuts on the map UI for opening the waypoint and configuration menus.
Multi-World Support: Whitelist specific worlds for the mod to track, resolving compatibility issues with server hosts that change default world names. Auto-tracks the world on first join.

Performance & Optimization

Thanks to major optimizations, the map can now handle significantly higher chunk counts without performance loss.

Dynamic Chunk Loading: The plugin intelligently manages memory by loading only the explored chunks nearest to the player and unloading distant ones.
Map Quality Settings: Admins can balance visual fidelity and performance by choosing between LOW, MEDIUM, or HIGH quality.
LOW: Loads up to 80,000 chunks (8x8 resolution).
MEDIUM: Loads up to 25,000 chunks (16x16 resolution).
HIGH: Loads up to 8,000 chunks (32x32 resolution).

Note: High quality strictly limits loaded chunks to prevent memory errors.

You can also manually set the maximum number of loaded chunks via /bm config maxchunk, within recommended limits or using our UI config menu with /bm and in the admin tab (need admin permission).

Commands & Permissions

The command system has been overhauled with a new UI-based configuration. Basic features are available to all players, while admin features require specific permissions.

You can either do /op add <player> to give full access or assign specific permissions as needed using /perm group add Adventure <permission>.

Public Commands (No Permission Required)

/bettermap (or /bm)
- Opens the main BetterMap Configuration UI to manage user settings and view help.
/bm waypoint menu or /waypoint or /wp
- Opens the Waypoint UI to manage, share, or delete waypoints.
/bm min <value>
- Sets your personal minimum zoom scale (default base is 32).
/bm max <value>
- Sets your personal maximum zoom scale (default base is 256).

Admin

Permission: bettermap.admin

Grants full admin access to BetterMap. Allows viewing all settings and overrides under /bettermap.

Teleportation

Permission: bettermap.command.teleport

Map Teleport: Allows the user to teleport to locations via the Waypoint UI buttons or by right-clicking anywhere on the map.

Global Shared Waypoint Edit/Delete

Permission: bettermap.command.waypoint.editglobal

Allows editing/deleting shared waypoints created by other players.
Marker owners can always edit/delete their own shared waypoints.
This permission overrides the global toggle if the toggle is disabled.

Map Privacy Overrides

Permissions:

bettermap.command.override.players - Bypass global hide players
bettermap.command.override.warps - Bypass global hide all/other warps
bettermap.command.override.unexploredwarps - Bypass global hide unexplored warps
bettermap.command.override.poi - Bypass global hide all POIs and hidden POI names
bettermap.command.override.unexploredpoi - Bypass global hide unexplored POIs
bettermap.command.override.spawn - Bypass global hide spawn
bettermap.command.override.death - Bypass global hide death markers
bettermap.command.override.waypoints - Bypass global hide waypoints

Configuration Commands

Permission: bettermap.command.config

Required to use /bm config subcommands and to access admin settings in the UI.

/bm config radar <range>
- Sets the radar range (use -1 for infinite).
/bm config location
- Toggles the server-wide default for the location HUD.
/bm config hideplayers
- Hides player cursors on the map.
/bm config hidewarps
- Hides other players' warps on the map.
/bm config hideunexploredwarps
- Hides warps in unexplored regions.
/bm config hidepois
- Hides all POI markers on the map.
/bm config hideunexploredpoi
- Hides POIs in unexplored regions.
/bm config hideglobalwaypoints
- Hides global waypoints on the map for all players.
/bm config editglobalwaypoints
- Toggles whether all players can edit/delete shared waypoints created by others.
/bm config waypointteleport
- Toggles the ability to teleport to waypoints.
/bm config markerteleport
- Toggles the ability to teleport to map markers.
/bm config shareallexploration
- Toggles "Linked Map" mode (shared exploration data).
/bm config track / untrack
- Adds or removes the current world from the active whitelist.
/bm config maxchunk <number>
- Manually overrides the maximum number of loaded chunks.
/bm config autosave <minutes>
- Sets the interval for auto-saving map data.
/bm config worldborder
- Toggles the world border visualization on the map.
/bm config worldborderradius <radius>
- Sets the world border radius in blocks.
/bm config worldborderoffset <x> <z>
- Sets the world border center offset (X and Z coordinates).

Reload Command

Permission: bettermap.command.reload

/bm reload
Reloads the configuration file immediately.

Configuration & Data Storage

All plugin files are located within the server's mods directory.

Configuration File

You can modify the plugin settings in mods/bettermap/config.json.

Note: Changing mapQuality or maxChunksToLoad requires a server restart to take effect.

Default Configuration:

{
  "explorationRadius": 16,
  "updateRateMs": 500,
  "mapQuality": "MEDIUM",
  "minScale": 10.0,
  "maxScale": 256.0,
  "debug": false,
  "locationEnabled": true,
  "locationHudPosition": "top_right",
  "shareAllExploration": false,
  "maxChunksToLoad": 25000,
  "radarEnabled": true,
  "radarRange": -1,
  "hidePlayersOnMap": false,
  "hideAllWarpsOnMap": false,
  "hideOtherWarpsOnMap": false,
  "hideUnexploredWarpsOnMap": true,
  "allowWaypointTeleports": true,
    "allowGlobalWaypointEditsForEveryone": false,
  "allowMapMarkerTeleports": true,
  "hideAllPoiOnMap": false,
  "hideUnexploredPoiOnMap": true,
  "hideSpawnOnMap": false,
  "hideDeathMarkerOnMap": false,
  "hideGlobalWaypointsOnMap": false,
  "hiddenPoiNames": [],
  "autoSaveInterval": 5,
  "maxPersonalMarkersPerPlayer": 12,
  "maxSharedMarkersPerPlayer": 12,
  "allowedWorlds": [
    "default",
    "world"
  ],
  "caveModeEnabled": true,
  "caveModeLayerSize": 10,
  "caveModeUndergroundThreshold": 100,
  "caveModeRadius": 4,
  "discoverSurfaceUnderground": false,
  "caveFogOfWar": false,
  "worldBorderEnabled": false,
  "worldBorderRadius": 5000,
  "worldBorderOffsetX": 0,
  "worldBorderOffsetZ": 0
}