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. (https://www.bilibili.com/video/BV1ziLn6AE8G/) (https://github.com/RuoChennn/MapSyncer-for-XaeroWorldmap)

#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 ` | 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 ` | Generate cache for a specific dimension | | `/mapsyncer generate ` | Generate a single region | | `/mapsyncer generate --force` | Force rebuild (clears existing cache) | | `/mapsyncer status` | View generation progress and cache statistics | | `/mapsyncer incremental off` | Disable incremental updates | | `/mapsyncer incremental tick ` | Enable periodic updates (20–72000 ticks) | | `/mapsyncer incremental scheduled ` | 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 ``

| 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 ``

| 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 ``

| 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: ```toml 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" ] ```