Unified Xaero Worldmap

Unified Xaero Worldmap 2.0.1

2.0.1 is a fix release for 2.0.0. It fixes two bugs that showed up on a live server: wrong map tiles and a crash in Xaero's World Map. It also carries a few smaller fixes, less work for the game and the server, and quieter logs. It adds no features and changes no settings.

Both main bugs are in the client part of the mod, so every player should update, not only the server.

Fixed

• Wrong map tiles (client). When other players' tiles arrived for a map region that World Map had loaded, 2.0.0 cleared and reloaded that region without World Map's own locking. World Map's render thread could clean up the same tiles at the same moment. The result was a 16x16-block map tile (one chunk) that showed the picture of another chunk of the same region, usually the next one. World Map then saved the wrong tile, the mod uploaded it as a fresh change, and the server and every other player took it over. The damage grew during a session and stopped only when the game was restarted. On the map it looked like normal chunks overwritten by wrong or broken chunks.
• Crash (same cause). java.lang.RuntimeException: Trying to save cache for a region with cache not prepared, reported by the game as "Xaero's World Map ... has crashed", with this mod in the stack trace. It happened when a region was queued for World Map's cache write just before the mod reloaded it.
• The fix: the mod now clears and reloads a loaded region the way World Map itself does it. It uses World Map's render pause, takes the region's lock, and first takes the region out of the cache queue. Both places that reload a region (applying a download, and merging tiles at save time) use the same sequence.
• Test result, in the real game with two clients and a server. The test made the race more likely than in normal play (shortened intervals, and on one client a small delay that widens the race window). With 2.0.0's code, after about 9 minutes of two players exploring together, about 7,100 of the 15,000 map tiles stored on the two clients and the server were copies of another tile (exactly 7,094 extra copies among 14,953 tiles, in 50 of 84 region files). With natural timing the race still occurred 3 times in 9 minutes on the other client. A second run of the same test, a variant that queues the region for World Map's cache write right before the reload, reproduced the crash with the exact text above. With the fixed code there were no copies of other tiles, and the same second run did not crash (32 reloads under that condition, no crash).
• A specially crafted map tile (a pixel marked as having overlays but with none) was accepted and then stored in a malformed form. On a server, one such upload from any player could make a stored region unreadable, after which that region started over from a single upload. Xaero's World Map never writes such a tile, so normal play was not affected. These tiles are now rejected. This protects a server once the server runs 2.0.1.
• Server: region files are now written completely or not at all. If the disk fills up and a write comes up short, the write fails cleanly and a truncated file can no longer replace a good one.
• Client: a region that World Map kept refusing (stuck loading) was re-read and re-assembled every 3 seconds for the whole session. It is now given up after 20 tries and fetched again at the next re-sync.
• Client: a download that cannot be read is now reported in the log (at most once a minute) instead of disappearing and being downloaded again silently every round.

If your map already has wrong tiles

2.0.1 stops new damage. It does not repair old damage automatically. A wrong tile is replaced as soon as any player running 2.0.1 walks through that chunk: World Map redraws it, and the fresh tile replaces the wrong one on the server and on everyone's map. Wrong tiles in places nobody visits again stay as they are. Restarting the game also ends the growth of the damage in a running 2.0.0 session.

Better

• Returning players: a map region that is already identical on your client and the server used to be uploaded whole the first time it was saved in a session, and the first real change in it reached other players only at the next periodic re-sync (up to 120 seconds by default). The client now recognises such regions from the server's answer, and the first real change goes out alone, live (about 5 seconds). This is a change in the client only and nothing sent over the network changed, so it also works against a 2.0.0 server.
• Less memory and CPU use when regions are put together from tiles. For a busy region (577 tiles) this allocates about 3.6 MB instead of 28.6 MB and is roughly a third faster, with identical output. It runs on the server for every merged upload, on the client for every applied download, and on Xaero's map thread when other players' tiles are merged into a region you are mapping.
• Saving a region reads it once instead of twice for the upload, uses one file-stat call per save instead of two, and one unused hash computation on Xaero's map thread was removed.
• Quieter logs: the server's "Catch-up complete ... (0 regions)" and the client's "Reconcile for ..." and "Sync complete for ..." lines are logged at INFO for the first round of a dimension and whenever data moved. Uneventful repeats (every re-sync interval, per player) are now DEBUG.

Good to know

A player standing still can still upload now and then. Each of those uploads is a single map tile (about 0.6-0.8 KB) that World Map redrew because a block nearby really changed: water spreading, grass turning to dirt under it, vines, leaves, sugar cane. In freshly generated terrain that was 12-14 uploads in the first 30 seconds, fading over about 5 minutes; in settled terrain, 0-3 per 30 seconds.

Compatibility

2.0.1 and 2.0.0 work together, in any combination of client and server: the network protocol (v5), the map file formats and every config key are unchanged, so you can update servers and players one by one. Update every client to get the fixes for wrong tiles and the crash: a 2.0.0 client can still produce wrong tiles and upload them, also to a 2.0.1 server, and can still crash. Update the server to get the fix for malformed tiles. Still not compatible with 1.0.0 (protocol v4); sync stays off with a chat message until both sides run 2.0.x.

Requirements

Unchanged from 2.0.0:

• Xaero's World Map 1.46.0 or newer, on the server and every client.
• Fabric: Fabric API for your Minecraft version. Forge / NeoForge: xaerolib, which World Map needs anyway.
• Xaero's Minimap is optional (client only); if you use it, 26.4.0 or newer.

The tile and crash fix uses three more members of Xaero's World Map. They exist in every World Map 1.46 build the mod supports (all 38 loader and Minecraft combinations were checked), and the mod's startup self-check covers them. If a future World Map lacks one, sync turns itself off with a message, as before.

Known limitations

• On a LAN game the host's own map does not sync (Xaero maps the host's world straight from the save); guests sync normally.
• Xaero's "full" cave mode layer is not synced; the sliced cave layers are.
• Map data you had before joining reaches other online players at their next periodic re-sync (every 120 seconds by default), not live. A new change in a region that was already identical on your client and the server goes out live.
• A live update for a dimension you have never visited is written to your disk right away only when the server has Xaero's World Map installed (it is required); otherwise it arrives when you enter that dimension.
• Xaero map files in a pre-6.x save format are skipped until Xaero rewrites them.
• Client and server must be on the same Minecraft family. Joining through a version-bridging proxy such as ViaVersion turns sync off for that player, with a message.
• After the server moves to a Minecraft family with a different region format, the shared map starts over and is rebuilt from what players upload. The old server data is kept on disk, not deleted; your own old local map syncs again once World Map rewrites it (by revisiting the area).
• A map region you are looking at reloads briefly when other players' tiles arrive for it.
• Server and every client must speak the same protocol version. All 2.0.x versions do, so 2.0.0 and 2.0.1 can be mixed; 1.0.0 cannot.

By Obscura. Unofficial add-on, not affiliated with Xaero.