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