MapSyncer-for-XaeroWorldmap

MapSyncer for Xaero's World Map

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

#请在 GitHub 上报告问题！！请务必

平台支持

优先支持现代版本。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 或类似的预生成工具

---

特性

特性	描述
增量同步	CRC32 哈希 + 时间戳比较 — 仅传输已更改的区域
流式加载	数据到达时即写入 Xaero 目录，按区域触发即时重新加载
带宽感知	动态调整发送速率以避免阻塞游戏网络
可恢复同步	重连后自动从中断处恢复（基于哈希）
视距优先	玩家视距内的区域优先同步
维度支持	主世界、下界、末地以及模组维度（例如暮色森林）
增量更新	服务器端周期性/定时地图缓存重新生成
洞穴模式	从可配置的高度向下扫描，输出到 caves 子目录
多线程哈希	客户端可配置的并行 CRC32 计算
自动同步	加入游戏时自动检查服务器上更新的地图，无需手动输入命令

---

命令

客户端命令

命令	描述
/mapsyncer	显示帮助
/mapsyncer sync	同步当前维度
/mapsyncer sync <dim>	同步指定维度
/mapsyncer sync all	同步所有维度

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

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

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

命令	描述
/mapsyncer generate	为所有维度生成缓存
/mapsyncer generate <dim>	为指定维度生成缓存
/mapsyncer generate <dim> <x> <z>	生成单个区域
/mapsyncer generate <dim> --force	强制重建（清除现有缓存）
/mapsyncer status	查看生成进度和缓存统计
/mapsyncer incremental off	禁用增量更新
/mapsyncer incremental tick [interval]	启用周期性更新（20–72000 ticks）
/mapsyncer incremental scheduled [hour] [min]	启用定时更新（默认 04:00）

---

配置

客户端配置

选项	默认值	范围	描述
hashThreads	CPU 核心数/2	1–核心数	用于 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"
]

格式：dimensionID|scanMode|caveStart|hasSkylight|hasCeiling|minY|height|logicalHeight

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

---

项目结构

libs/                   抽象库层（平台无关，编译为独立的 JAR 文件）
├── core/               纯 Java 核心：MCA/NBT 解析、工具函数
└── platform-api/       平台抽象接口、网络数据包定义

mc-1.20.1/              1.20.1 版本
├── shared/             共享源代码（通过 sourceSet 被平台模块引用）
├── fabric/             平台实现（生成最终模组 JAR）
└── forge/

mc-1.21.1/              1.21.1 版本
├── shared/
├── fabric/
├── forge/
└── neoforge/

mc-26.1/                26.1 版本
├── shared/
├── fabric/
└── neoforge/

流程

服务器 MCA 文件 (region/*.mca)
        │
        ▼
    MCA 解析器（纯 Java，无 Xaero 依赖）
   解压缩 → NBT 解析 → 提取区块数据
        │
        ▼
   区域转换 (RegionConverter)
        │
        ▼
   编码为 Xaero 格式 (region.zip)
        │
        ▼
   时间戳 + 哈希缓存 (GenerationCache)
        │
        ▼
   增量更新处理器（可选）
   TICK 模式 / SCHEDULED 模式
        │
        ▼
    网络同步协议
   哈希比较 → 视距优先级排序
   批量传输 + 速率限制
        │
        ▼
    流式接收
   数据到达时写入 Xaero 目录
        │
        ▼
   Xaero 重载触发器（反射）
   requestLoad → 地图重新渲染

文件存储

服务器：
  <server>/server_map_cache/
  ├── null/               # 主世界
  ├── DIM-1/              # 下界
  ├── DIM1/               # 末地
  ├── caves/<layer>/      # 洞穴模式输出
  └── generation_cache.properties  # 时间戳 + 哈希缓存

客户端：
  <client>/xaero/world-map/Multiplayer_<IP>/     # 现代 Xaero 统一路径（推荐）
  <client>/XaeroWorldMap/Multiplayer_<IP>/       # 旧版 Xaero 路径（兼容性备选）
  ├── null/mw$<worldId>/   # 主世界
  ├── DIM-1/mw$<worldId>/  # 下界
  └── DIM1/mw$<worldId>/   # 末地

维度映射

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

---

已知问题

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

---

构建

# 构建所有活跃平台（并行）
./gradlew build -x test --parallel

# 构建单个平台
./gradlew :mc-1.21.1:forge:build -x test
./gradlew :mc-1.21.1:fabric:build -x test

# 快速构建脚本
scripts/fastbuild/build-all.bat              # 所有活跃平台
scripts/fastbuild/build-forge.bat            # 所有 Forge 模块（Gradle 8.9 + JDK 17/21）
scripts/fastbuild/build-fabric-26.1.bat      # Fabric 26.1（独立的 Gradle 进程）
scripts/fastbuild/build-26.1.bat             # 所有 26.1 模块

构建产物位于各平台模块的 build/libs/ 目录中。

---

许可证：GPL-3.0

致谢：Xaero's World Map & Minimap