MapSyncer for Xaero's World Map

A multi-platform Minecraft mod that syncs server-side explored areas to clients' Xaero's World Map. BiliBili GitHub

#REPORT ISSUE ON GITHUB！！PLEASE

Platform Support

Prioritizing modern versions. NeoForge didn't exist as an independent loader before 1.20.4. Forge provides no developer documentation after 26.1.

MC Version Forge NeoForge Fabric 1.20.1 ✅ — ✅ 1.21.1 ✅ ✅ ✅ 1.21.11 ✅ ✅ ✅ 26.1 — ✅ ✅

Client Dependencies

Supports both dedicated servers and integrated servers (single-player LAN sharing). On integrated servers, the host's Xaero's World Map save directory is reused as the map cache, eliminating redundant conversion.

Dependency Requirement Xaero's World Map 1.40.11+

Server Requirements

• Xaero's World Map is NOT required on the server
• Chunky or similar pre-generation tools are recommended

Features

Feature Description Incremental Sync CRC32 hash + timestamp comparison — only transfers changed regions Streaming Load Writes to Xaero directory as data arrives, triggers immediate reload per region Bandwidth-Aware Dynamic send rate adjustment to avoid blocking game network Resumable Sync Auto-resumes from interruption after reconnect (hash-based) View-Distance Priority Regions within player's view distance are prioritized Dimension Support Overworld, Nether, End, and mod dimensions (e.g. Twilight Forest) Incremental Update Server-side periodic/scheduled map cache regeneration Cave Mode Scans downward from a configurable height, outputs to caves subdirectory Multi-Threaded Hash Configurable parallel CRC32 computation on the client Auto Sync Automatically checks for newer server maps on join, no manual command needed

Commands

Client Commands

Command Description /mapsyncer Show help /mapsyncer sync Sync current dimension /mapsyncer sync <dim> Sync a specific dimension /mapsyncer sync all Sync all dimensions

Dimension arguments: overworld, the_nether, the_end, or mod dimension IDs like twilightforest:twilight_forest

Server Commands (OP required)

Forge/NeoForge uses /mapsyncer; Fabric uses /mapsyncerserver to avoid conflicts with the client-side /mapsyncer.

Command Description /mapsyncer generate Generate cache for all dimensions /mapsyncer generate <dim> Generate cache for a specific dimension /mapsyncer generate <dim> <x> <z> Generate a single region /mapsyncer generate <dim> --force Force rebuild (clears existing cache) /mapsyncer status View generation progress and cache statistics /mapsyncer incremental off Disable incremental updates /mapsyncer incremental tick [interval] Enable periodic updates (20–72000 ticks) /mapsyncer incremental scheduled [hour] [min] Enable scheduled updates (default 04:00)

Configuration

Client Config

Option Default Range Description hashThreads CPU cores/2 1–cores Number of threads for CRC32 computation

Server Config

Forge config: world/serverconfig/mapsyncer-server.toml (per-world) NeoForge / Fabric config: config/ directory (.toml for NeoForge, .properties for Fabric)

General [general]

Option Default Range Description enableDebugLogging false — Enable debug logging maxConcurrentRegions 4 1–16 Concurrent region conversion threads maxSyncPacketSize 262144 (256KB) 64KB–1MB Max packet size in bytes syncSpeedLimitKBps 1024 (1MiB/s) 0–10240 Sync rate limit (0 = unlimited)

Incremental Update [incremental_update]

Option Default Description incrementalUpdateMode DISABLED DISABLED / TICK / SCHEDULED incrementalUpdateIntervalTicks 200 TICK mode interval (20 ticks = 1 second) scheduledUpdateHour 4 Scheduled update hour (0–23) scheduledUpdateMinute 0 Scheduled update minute (0–59)

Dimension Scan [dimension_scan]

Option Default Description default_scan_mode SURFACE Default scan mode for unconfigured dimensions default_cave_start 63 Starting height for CAVE mode

Dimension config format:

dimension_configs = [ "minecraft:overworld|SURFACE|63|true|false|-64|384|384", "minecraft:the_nether|CAVE|63|false|true|0|256|256", "minecraft:the_end|SURFACE|63|false|false|0|256|256" ]

Format: dimensionID|scanMode|caveStart|hasSkylight|hasCeiling|minY|height|logicalHeight

• SURFACE: Scans downward from heightmap. For Overworld and End.
• CAVE: Scans downward from a fixed height. For Nether.

Project Structure

libs/ Abstract library layer (platform-agnostic, compiled as independent JARs) ├── core/ Pure Java core: MCA/NBT parsing, utilities └── platform-api/ Platform abstraction interfaces, network payload definitions mc-1.20.1/ 1.20.1 version ├── shared/ Shared source (referenced by platform modules via sourceSet) ├── fabric/ Platform implementation (produces final mod JAR) └── forge/ mc-1.21.1/ 1.21.1 version ├── shared/ ├── fabric/ ├── forge/ └── neoforge/ mc-26.1/ 26.1 version ├── shared/ ├── fabric/ └── neoforge/

Pipeline

Server MCA files (region/*.mca) │ ▼ MCA Parser (pure Java, no Xaero dependency) Decompress → NBT parse → Extract chunk data │ ▼ Region Conversion (RegionConverter) │ ▼ Encode to Xaero format (region.zip) │ ▼ Timestamp + Hash Cache (GenerationCache) │ ▼ Incremental Update Processor (optional) TICK mode / SCHEDULED mode │ ▼ Network Sync Protocol Hash comparison → View-distance priority sort Batched transfer + rate limiting │ ▼ Streaming Receive Write to Xaero directory as data arrives │ ▼ Xaero Reload Trigger (reflection) requestLoad → Map re-renders

File Storage

Server: <server>/server_map_cache/ ├── null/ # Overworld ├── DIM-1/ # Nether ├── DIM1/ # End ├── caves/<layer>/ # Cave mode output └── generation_cache.properties # Timestamp + hash cache Client: <client>/xaero/world-map/Multiplayer_<IP>/ # Modern Xaero unified path (preferred) <client>/XaeroWorldMap/Multiplayer_<IP>/ # Legacy Xaero path (compatibility fallback) ├── null/mw$<worldId>/ # Overworld ├── DIM-1/mw$<worldId>/ # Nether └── DIM1/mw$<worldId>/ # End

Dimension Mapping

Dimension Minecraft ID Xaero Directory Overworld minecraft:overworld null Nether minecraft:the_nether DIM-1 End minecraft:the_end DIM1 Mod dimensions namespace:path namespace$path

Known Issues

Issue Details Impact Cave rendering anomalies Some cave content is inaccurate Mostly affects Nether; under investigation

Build

# Build all active platforms (parallel) ./gradlew build -x test --parallel # Build a single platform ./gradlew :mc-1.21.1:forge:build -x test ./gradlew :mc-1.21.1:fabric:build -x test # Quick build scripts scripts/fastbuild/build-all.bat # All active platforms scripts/fastbuild/build-forge.bat # All Forge modules (Gradle 8.9 + JDK 17/21) scripts/fastbuild/build-fabric-26.1.bat # Fabric 26.1 (isolated Gradle process) scripts/fastbuild/build-26.1.bat # All 26.1 modules

Build artifacts are placed in each platform module's build/libs/ directory.

License: GPL-3.0

Acknowledgements: Xaero's World Map & Minimap