Unified Xaero Worldmap
- By
shared world map for the whole server, built on Xaero's World Map. Explored tiles sync live to everyone online and catch you up automatically on rejoin - caves and every dimension included. Additive merging: nobody can wipe another player's exploration.
Everyone's map, one map
Xaero's World Map is normally personal: you only see the chunks you walked through yourself. Unified Xaero Worldmap turns it into a shared resource for the whole server. Explore a cave, cross into the Nether, chart a coastline — everyone else online sees it too, usually within seconds, and anyone who logs back in after days away finds their map already caught up with everything the group explored while they were gone.
What it does
- Uploads the map tiles you explore to the server as you play.
- Merges them into one canonical, shared map stored in the world save.
- Pushes new tiles out to every other online player immediately.
- Catches a (re)joining player's map up with everything explored since they were last on.
- Syncs every cave layer and every dimension, not just the overworld surface.
- Requires no manual file copying, no web map, and no extra client-side setup beyond installing the mod.
How it feels in play
Walk somewhere new, and within a few seconds it appears on your friends' maps too — no reload, no menu, no command. Log off for a week and log back in: your map is already filled in with everything the group discovered while you were away. Duck into a cave system and it syncs like the surface does. Step into the Nether or the End and the same sharing keeps working there. If a friend is exploring a different dimension than you right now, their discoveries still arrive and wait for them, and yours wait for them too.
Why it's safe
Merging is additive at the level of individual 16x16 map tiles, not whole regions. A tile only gets added, never deleted, and the two upload modes are deliberately asymmetric: a freshly-explored tile you just saved always wins over what the server had (so your map stays current), while a large batch of older map data you already had before joining only fills in gaps the server didn't have — it never overwrites a tile someone else contributed more recently. Nothing a client sends can ever delete or blank out data another player added. The server keeps the canonical merged map inside the world save itself, alongside everything else Minecraft already writes there. Singleplayer worlds are never touched by any of this. If the mod is ever removed, or something goes wrong with sync, Xaero's World Map itself keeps working exactly as it always has — this mod only adds a background sync layer on top of it.
Requirements
| Component | Requirement |
|---|---|
| Minecraft | 1.21.1 |
| Fabric Loader | >=0.18.4 (built and tested on 0.19.5) |
| Fabric API | required, matching your Minecraft version |
| Xaero's World Map | >=1.46.0, required on the server and every client |
| Xaero's Minimap | optional, client-side only, >=26.4.0 if installed |
| Java | 21 |
Installation
Server: install Fabric Loader, Fabric API, Xaero's World Map (>=1.46.0), and this mod's jar in the server's mods folder.
Every client: install Fabric Loader, Fabric API, Xaero's World Map (>=1.46.0), and this mod's jar. Xaero's Minimap is optional.
Players who join without the mod installed are not rejected — they play normally with their own local, unsynced Xaero map and simply do not take part in sync.
Configuration
Written to <world>/unified_xaero_worldmap/config.json on first start; changes take effect on server restart.
| Key | Default | What it does |
|---|---|---|
syncEnabled |
true |
Master switch for the whole feature. |
reconcileIntervalSeconds |
120 |
How often clients re-sync with the server; also how long a joining player's existing map takes to reach everyone else. |
maxRegionsPerTick |
2 |
How fast a catching-up player downloads the map — controls catch-up bandwidth. |
persistIntervalSeconds |
30 |
How often merged map data is flushed to disk. |
maxUploadsPerSecond |
8 |
Per-player upload rate limit. |
liveSaveIntervalMillis |
5000 |
How quickly a freshly-explored tile reaches other online players; see Performance below. |
Performance
The mod's own per-frame code costs roughly 0.01 ms per client tick on the render thread. All parsing, merging, and disk work happen on background threads at the lowest priority, measured at 0-4% busy. Playing alone on a server, the mod changes nothing about Xaero's own behavior or timing at all.
With at least one other synced player online, Xaero is told to save map regions every 5 seconds instead of its own default 60, so tiles reach friends quickly — this is what liveSaveIntervalMillis controls, and it can be raised on a busy server. In an uncapped-FPS A/B test on one machine this cost about 10% at roughly 2000 FPS, i.e. a few hundred microseconds per frame — noticeable only well above normal capped framerates.
Bulk sync was tested with 1000 regions seeded on one client: upload to the server took 147 seconds, and catching up a newly joined second client to the same tile set took 433 seconds at the default download rate, ending with identical tile sets on both sides. The server never logged a "Can't keep up" warning during the bulk transfer.
How it works (for the curious)
Every explored area is broken into 16x16-block tiles, the same granularity Xaero already stores internally. Tiles are hashed, compared, and merged individually rather than replacing whole map regions, which is what makes the additive guarantee above possible. The full wire protocol, merge rules, and threading model are documented in the project's docs/PROTOCOL.md on the source repository, for anyone who wants the exact contract.
Known limitations
- A live update for a dimension you have never visited only lands on your disk immediately if the server itself has Xaero's World Map installed (already required); otherwise it arrives the next time you enter that dimension.
- Map data you already had before joining is uploaded in the background and is not broadcast live to others — they pick it up at their next periodic re-sync (every 120 seconds by default).
- Xaero map files in a very old save format are skipped until Xaero itself upgrades them on its next save.
- A download landing on a map region you currently have open causes a brief reload of just that region.
- Both sides — server and client — must run the same mod version to sync at all.
- Extreme artificial load (scripted teleporting of several players into ungenerated terrain every second) can overwhelm vanilla world generation on the server; this was observed once in stress testing and is not specific to this mod's code paths, which never block the server thread.
FAQ
Does the server need Xaero's World Map installed? Yes. It's required on the server as well as every client — this is what lets a freshly-explored tile be written to disk immediately for dimensions you haven't visited yet, instead of only when you enter them.
Do waypoints sync? No. Only explored map tiles sync. Waypoints are entirely local to each player, unmodified.
Does it work with Forge, NeoForge, or other Minecraft versions? Not currently. This is a Fabric mod built for Minecraft 1.21.1 only.
Can a griefer wipe the shared map? No. Merging is strictly additive — nothing a client uploads can delete or overwrite-away another player's exploration.
Does it sync my singleplayer maps? No. Singleplayer worlds are never touched.
What happens to players without the mod? They can join the server normally. They just don't take part in sync — their map stays personal, exactly like vanilla Xaero.
Is this affiliated with Xaero? No. This is an independent, unofficial add-on. It requires Xaero's World Map (and optionally Xaero's Minimap) and does not include or redistribute either.
Credits
This project is an unofficial add-on for Xaero's World Map by Xaero96 (CurseForge Project ID: 317780).
It extends Xaero's World Map with server-wide shared map synchronization, allowing explored map tiles to be shared between players while continuing to use Xaero's World Map as the underlying map system.
Xaero's World Map is a required dependency and this add-on does not function without it. Xaero's Minimap is optionally supported but is not required.
All credit for the original map system, map rendering, map storage, exploration tracking, and related functionality belongs to Xaero96 and the original Xaero's World Map project.
This project is independent, unofficial, and not affiliated with or endorsed by Xaero96. It does not include or redistribute Xaero's World Map or Xaero's Minimap.
Original project:
https://www.curseforge.com/minecraft/mc-mods/xaeros-world-map
Original author: Xaero96
CurseForge Project ID: 317780
The Unified Xaero Worldmap Team
Owner
