MapSyncer-for-XaeroWorldmap

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

V1.0.4 Beta version is avaliable on github release page ,please report bug on issue page ,if you got any suggestion leave it on issue too ,thank you.

---

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/