MapSyncer for Xaero’s World Map

一款支持多平台的 Minecraft 模组，可将服务端已探索区域同步到客户端的 Xaero’s World Map。
BiliBili
GitHub

请在 GitHub 上报告问题！！拜托了

V1.0.4 Beta 版本已发布在 GitHub 的 Releases 页面。请在 Issues 页面报告错误；如果有任何建议，也请在那里留言。谢谢。

平台支持

优先支持较新的版本。NeoForge 在 1.20.4 之前并不是独立的加载器。Forge 在 26.1 之后不再提供开发者文档。

| MC 版本 | Forge | NeoForge | Fabric |
|————|:—–:|:——–:|:——:|
| 1.20.1 | ✅ | — | ✅ |
| 1.21.1 | ✅ | ✅ | ✅ |
| 1.21.11 | ✅ | ✅ | ✅ |
| 26.1 | — | ✅ | ✅ |

客户端依赖

支持专用服务器和集成服务器（单人游戏开放局域网）。在集成服务器上，会重复使用主机的 Xaero’s World Map 存档目录作为地图缓存，无需重复转换。

| 依赖项 | 要求 |
|————|————-|
| Xaero’s World Map | 1.40.11+ |

服务器要求

服务器无需安装 Xaero’s World Map
建议使用 Chunky 或类似的预生成工具

功能

命令

客户端命令

维度参数: overworld, the_nether, the_end，或模组维度 ID，例如 twilightforest:twilight_forest

服务端命令（需要 OP 权限）

Forge/NeoForge 使用 /mapsyncer；Fabric 使用 /mapsyncerserver，以避免与客户端的 /mapsyncer冲突。

配置

客户端配置

| 选项 | 默认值 | 范围 | 说明 |
|——–|——–|——-|————-|
| hashThreads | CPU cores/2 | 1–cores | CRC32 计算使用的线程数 |

服务器配置

Forge 配置：world/serverconfig/mapsyncer-server.toml（每个地图单独配置）
NeoForge / Fabric 配置：config/ 目录（NeoForge 使用 .toml，Fabric 使用 .properties）

常规设置 [general]

| 选项 | 默认值 | 范围 | 说明 |
|——–|——–|——-|————-|
| enableDebugLogging | false | — | 启用调试日志 |
| maxConcurrentRegions | 4 | 1–16 | 并发区域转换线程数 |
| maxSyncPacketSize | 262144 (256KB) | 64KB–1MB | 最大数据包大小（字节） |
| syncSpeedLimitKBps | 1024 (1MiB/s) | 0–10240 | 同步速率限制（0 = 不限速） |

增量更新 [incremental_update]

| 选项 | 默认值 | 说明 |
|——–|———|————-|
| incrementalUpdateMode | DISABLED | DISABLED / TICK / SCHEDULED |
| incrementalUpdateIntervalTicks | 200 | TICK 模式的更新间隔（20 ticks = 1 秒） |
| scheduledUpdateHour | 4 | 计划更新的小时（0–23） |
| scheduledUpdateMinute | 0 | 计划更新的分钟（0–59） |

维度扫描 [dimension_scan]

| 选项 | 默认值 | 说明 |
|——–|———|————-|
| default_scan_mode | SURFACE | 未配置维度的默认扫描模式 |
| default_cave_start | 63 | CAVE 模式的起始高度 |

维度配置格式：

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"
]

SURFACE：从高度图向下扫描。适用于主世界和末地。
CAVE：从固定高度向下扫描。适用于下界。

项目结构

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/

处理流程

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

文件存储

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

维度映射

| 维度 | Minecraft ID | Xaero目录 |
|———–|————–|—————–|
| 主世界 | minecraft:overworld | null |
| 下界 | minecraft:the_nether | DIM-1 |
| 末地 | minecraft:the_end | DIM1 |
| 模组维度 | namespace:path | namespace$path |

已知问题

| 问题 | 详情 | 影响 |
|——-|———|——–|
| 洞穴渲染异常 | 部分洞穴内容显示不准确 | 主要影响下界；正在调查中 |

构建

# 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/libs/ 目录中。

许可证: GPL-3.0

致谢: Xaero的世界地图和小地图

MapSyncer-for-XaeroWorldmap

介绍