🗺️ AtlasSync: Server World Map

A high-performance, server-authoritative world map built for seamless multiplayer synchronization.

🌟 Overview

Unlike traditional client-side map mods that require players to explore the world themselves to uncover the map, AtlasSync generates the map on the server and streams it to clients. This means players immediately see the world exactly as the server knows it.

Powered by a custom, highly optimized .rpg binary region format and an intelligent chunk caching system, this mod operates with minimal server overhead while providing a beautifully rendered interactive map on the client.

✨ Key Features

Server Map: Every chunk surface map is generated from the server this means your friends explored regions will come to you as well, and also this is for any chunks means if they are generated by DistantHorizon or Chunky the map is still created and sent to all players.
Real-Time Synchronization: Map data, player positions, and global waypoints are seamlessly synced between the server and all connected clients.
Multi-Layered Mapping: Switch effortlessly between Surface Map generated by the server its data cached in both client and server, Cave/Depth Map generated by client only when player is on the map and data saved in client, and Player Layer Map generated by client only when player is on the map its data not saved to navigate complex terrain, Waypoints and other data is sheared don't worry.
Waystones Integration: Automatically detects and syncs with the Waystones mod—your activated waystones instantly become map waypoints!
Live Ping System: Press [1] while looking at a block (or click the map) to send a visual ping to all players on the server.
Togglable Structures Marks: Structure are mapped on the map by default I excluded important structures like stronghold, but you can disable structures if you want its not forced in the map.

🖥️ The Interactive Map Screen (Press 'M')

The client-side map screen is packed with powerful, user-friendly features to make navigation a breeze, here are some of the features:

Advanced Waypoint Manager: Create, edit, and color-code waypoints. Organize them into custom Waypoint Groups, toggle group visibility, and even Share Globally to send a waypoint to everyone on the server.
Smart Structure Tracking: Structures are automatically mapped. Hover over them to see details, right-click to mark them as Looted (✓), or completely hide specific structure types (e.g., "Hide all Villages" or "Hide Exact: Desert Pyramid").
Dynamic Tooltips: Hover over the map to view precise coordinates, chunk/region data, Biome Names, Temperature, and Humidity.
Smooth Navigation: Free-pan with the mouse, use the scroll wheel for buttery-smooth zooming, or click the "Recenter" button to lock onto your player, follow other players, or find them.
Map Switcher Menu: You can open other dimensions maps, or your other worlds maps from this menu and on top of that you can edit them.

⚙️ Detailed Command Guide

This mod includes a robust set of commands for server administrators to manage map data, and client commands for UI customization.

🛡️ Server / Admin Commands

Requires Permission Level 2 (OP). Base command: /worldmap

/worldmap retrogen ... (Generate Old Terrain Map)
Used to generate map data for chunks that existed before the mod was installed, or missed chunks when world generation is really fast, retrogen can get slow because of performance mods, but it get the job done with no problems.
- start [replace] [safe] [force_gen] [does_nothing] [minX minZ maxX maxZ] - Initiates the Retro-Generator.
  - replace: If true, overwrites existing map data.
  - safe: If true, runs slower but ensures server TPS isn't heavily impacted.
  - force_gen: If true, forces half-generated chunks to fully generate so they can be mapped, this doesn't generate chunks, these chunks already exist but not fully.
  - does_nothing: it does nothing I removed this flag.
  - minX minZ maxX maxZ: Define a specific chunk region to generate.
- stop - Safely cancels an active Retro-Gen process after the current region finishes.

/worldmap rebuild ... (Rebuild Specific Data)
- index_file - Rebuilds the index.dat file. Use this if the server crashes or forgets which chunks have been mapped, always run this before running the retrogen so no chunks will be missied.
- <flags> <dim> <rx1> <rz1> [rx2] [rz2] - Fast-rebuilds specific attributes in a region. Flags include -biome_tags, -structure_tags, or -both, biome_tags also include color data.

/worldmap delete region <dim> <rx1> <rz1> [rx2] [rz2]
Deletes the physical .rpg files and clears the cache for the specified dimension and region coordinates.

/worldmap chunkgen [with_radius chunkX chunkZ radius] | [with_region_range regionStartX regionStartZ regionEndX regionEndZ]
Yet another chunk generator, it uses minecraft generator to generate the chunks, this same as chunky or DistantHorizon pregen it does the same, but you can use the map coordinates and also see the generation in the map screen.

/worldmap config <key> <value>
Live-edit server properties without restarting:
- mapgenerator.useMutiThreadedLoading: this is only for the retro gen its not really safe but tries to make the game load mulitple chunk at a time.
- mapgenerator.threadpoolSize: Number of threads used for mapping, maps generated outside main thread, default is 3 but you can even go higher since it doesnt take too much of the thread, its multithready so it can keep up with world generation speed without holding chunk data, and overtake server RAM, which is limited by below command.
- mapgenerator.chunkQueueSize: how many chunks can be held at a time, default is 128 this settings only effect RAM not performance the 128 chunks is around 75MB, if world generation is too fast and you set threadpoolSize and chunkQueueSize low you will be seeing a lot of missing chunk maps, I personally use the default settings because my server sucks but I rarely see missing chunks which can also be due to low server TPS not my mod and when I do I just run a /worldmap retrogen start, to check and do all the missing maps, and I also use distant horizon which generates chunks really fast, this is only when you give the mod 75MB and 1% of three other threads.
- mapgenerator.biomeGridSize: Detail level of biome blending (4, 8, or 16), 16 recommended but you can use others if you prioritize disk usage and performance, you can test.
- server.playerSyncFps: How often player positions are synced to clients per second, player indicators fps.

💻 Client Commands

Base command: /worldmap_client

/worldmap_client config ... (Visual Customization)
Customize exactly how in-world markers and pings render on your screen.
- global render_distance <value>: Set the max distance (in blocks) that in-world markers are visible.
- global map_ping_color <hex>: Set the default color of map pings (e.g., #FF0000).
- map.player_layer_mode_mapper_y_offset: The player layer mode maps from the player's Y + y_offset to bedrock or void.
- player_color <name> <hex>: Assign a custom color to a specific player's tracker.
- <marker_type> <component> <property> <value>: Deeply customize markers (Types: map_ping, player_ping, waypoint_marker, player_marker).

🚀 Performance, Flaws, & Technical Details

How it achieves high performance:

Strict Memory Constraints: The client utilizes a strict LRU cache for VRAM. You can adjust the Cache Limit in the map UI. It will safely drop old map textures to prevent your GPU from locking up.
Custom Binary Format: Map data is stored in specialized .rpg files, severely reducing disk footprint compared to standard image rendering.
Throttled I/O Threading: Map generation relies on a custom ThreadPoolExecutor running at minimum priority. It will intentionally drop mapping requests rather than lag the server's main tick thread if overloaded.

Known Limitations & Things to Keep in Mind:

Massive Retro-Gens: Running a /worldmap retrogen on tens of thousands of chunks will take time and CPU resources. It is highly recommended to use the safe parameter (set to true) on live servers to avoid TPS drops, while the performance mods wont let the mod take as much as chunks it wants so either way the process might be slow, but with highest server TPS, means play free while it runs in the background.
Index Desyncs: If the server crashes abruptly, the index.dat file (which tells the server what it has mapped) might miss the last few seconds of data. If players report "black chunks" that they know are generated, run /worldmap rebuild index_file to fix it, always run this before retrogen.
Shaders: In-world waypoints and pings render beautifully, but heavily modified shader pipelines might occasionally cause depth-sorting quirks.