统一 Xaero 世界地图

Unified Xaero Worldmap

为你的整个服务器提供一张共享的 Xaero 世界地图。 任何人探索过的区域都会实时显示在所有人的地图上，涵盖每个维度和每个洞穴层。离线玩家在加入的瞬间会自动补齐所有内容。

适用于 Fabric、Forge 和 NeoForge，支持 Xaero's World Map 1.46 所支持的所有 Minecraft 版本，从 1.16.5 到 26.3。

---

所有人的地图，一张地图

Xaero's World Map 通常是个人地图：你只能看到自己走过的区块。在和朋友一起玩的服务器上，这意味着每个人都在绘制相同的出生点区域，而没人知道其他人发现了什么。

Unified Xaero Worldmap 将地图变成整个服务器的共享资源：

• 你探索，所有人都能看到。 走到新地方，它会在几秒内出现在你朋友的地图上，无需重载、无需菜单、无需命令。
• 离线一周后重新登录： 你的地图已经填满了你不在时团队发现的所有内容。
• 包含洞穴和维度。 洞穴层的同步方式和地表一样，下界、末地以及服务器拥有的任何其他维度也是如此。你当前不在的维度中的发现也会到达，并在那里等待你。
• 你已有的地图也算数。 在安装此模组之前你就拥有的地图会在后台与服务器共享，因此团队地图从一开始就包含所有人已探索的内容。
• 无需任何设置。 没有网页地图，无需复制文件，无需命令。在服务器和每个玩家的游戏中安装此模组即可。

---

我应该下载哪个文件？

选择与你的 Minecraft 版本和你的模组加载器匹配的文件。服务器和每个玩家都需要相同的文件（相同的 Minecraft 版本、相同的加载器）。

Minecraft	Fabric	Forge	NeoForge	Java
1.16.2 – 1.16.5	✅	✅	–	8
1.18.2	✅	✅	–	17
1.19.1 – 1.19.2	✅	✅	–	17
1.20 – 1.20.1	✅	✅	–	17
1.20.3 – 1.20.4	✅	✅	✅	17
1.21 – 1.21.1	✅	✅	✅	21
1.21.4	✅	✅	✅	21
1.21.5	✅	✅	✅	21
1.21.8	✅	✅	✅	21
1.21.10	✅	✅	✅	21
1.21.11	✅	✅	✅	21
26.1 – 26.1.2	✅	✅	✅	25
26.2	✅	✅	✅	25
26.3	✅	✅	✅	25

文件名格式类似 unified-xaero-worldmap-<version>+1.21.1-neoforge.jar：模组版本，然后是 Minecraft 版本，最后是加载器。中间的 Minecraft 版本（1.17、1.19.3/1.19.4、1.20.2、1.20.5/1.20.6、1.21.2/1.21.3、1.21.6/1.21.7、1.21.9）不受支持，因为 Xaero's World Map 1.46 没有这些版本。

---

要求

在服务器和每个玩家的游戏上：

内容	版本
Xaero's World Map	1.46.0 或更高版本，服务器和每个客户端都需要
仅 Fabric： Fabric Loader	0.18.4 或更高版本
仅 Fabric： Fabric API	对应你 Minecraft 版本的版本
仅 Forge / NeoForge： xaerolib	你的 World Map 版本所需的版本（CurseForge 和大多数启动器会作为 World Map 的依赖项自动安装）
Forge	对应你 Minecraft 版本的 Forge 版本（例如 1.20.1 用 47，1.21.1 用 52）
NeoForge	对应你 Minecraft 版本的 NeoForge 版本（例如 1.21.1 用 21.1）；在 26.3 上目前只有 NeoForge 测试版

可选： Xaero's Minimap 可以与之配合使用（仅客户端）。如果你使用它，请选择与 World Map 1.46 兼容的 Minimap 版本（26.4.0 或更高版本；已用 26.5.x 测试）。

---

安装

服务器：

1. 为你的 Minecraft 版本安装加载器（Fabric / Forge / NeoForge）。
2. 将以下内容放入服务器的 mods 文件夹：Xaero's World Map、此模组，以及 Fabric API（Fabric）或 xaerolib（Forge/NeoForge）。
3. 启动服务器。共享地图及其配置会自动创建在 <world>/unified_xaero_worldmap/ 中。

每个玩家： 与服务器相同的模组，放入游戏的 mods 文件夹。Xaero's Minimap 是可选的。

就是这样。当玩家加入时，模组会检查双方是否匹配，同步会自动开始，无需做其他任何事情。

---

谁可以加入

此模组在双方都是可选的，因此它绝不会把任何人拒之门外：

• 没有安装此模组的玩家可以正常加入服务器，并使用自己未共享的 Xaero 地图进行游戏。
• 安装了此模组的玩家加入没有安装此模组的服务器也能正常游戏；只是没有可同步的内容。
• 使用此模组不兼容版本的玩家保持连接。同步对他们关闭，他们会收到一条聊天消息，说明双方各自运行的版本。
• 使用不同 Minecraft 版本的玩家通过 ViaVersion 之类的版本桥接代理加入时：Xaero's World Map 在某些 Minecraft 版本上存储地图的方式不同，因此如果格式不同，该玩家的同步会关闭，并显示一条清晰的聊天消息。使用服务器自身版本的玩家会继续正常同步。

---

为什么它是安全的

• 没有人能清除共享地图。 合并是增量式的，一次一个 16×16 方块的图块：图块只会被添加或更新，绝不会被删除。无论玩家发送什么，都无法擦除或清空其他人探索过的内容，无论是有意还是无意。
• 新数据优于旧数据，旧数据永远无法覆盖新数据。 你刚刚探索的图块会更新共享地图。你加入之前的旧地图数据只会填补空白；它绝不会覆盖其他玩家最近绘制的内容。
• 你自己的地图文件受到保护。 传入的地图数据会按照 Xaero 自身的保存周期，谨慎地合并到你的地图中。模组无法安全读取的文件（例如来自较旧 Minecraft 版本的地图文件）会保持原样，绝不会被覆盖或删除。
• 为公共服务器而构建。 服务器只接受属于其自身维度以及那里可能存在的洞穴层的地图数据。它会拒绝格式错误的数据，使其无法到达任何人。每个玩家都有上传速率限制，以及在服务器后台工作中被限制的份额，整个共享地图在磁盘上有大小上限（默认 4 GiB）。玩家从未接近过的地方的实时更新绝不会广播给其他人。
• Xaero 更新时安全失效。 模组在启动时会检查它从 Xaero's World Map 所需的一切是否仍然存在。如果未来的 World Map 更新改变了某些内容，同步会自动关闭，并输出一行聊天信息和一行日志。你的游戏和地图会继续正常工作，绝不会崩溃。
• 单人游戏不受影响。 单人游戏世界绝不会被同步。随时卸载此模组都会让 Xaero's World Map 保持原样。

---

配置（服务器）

服务器在首次启动时会写入带有默认值的 <world>/unified_xaero_worldmap/config.json。更改在重启后生效。超出允许范围的值会被自动修正，损坏的配置文件会被备份并替换为默认值，而不是让服务器崩溃。默认值适合 5–20 人的生存服务器。

设置	默认值	范围	作用
syncEnabled	true		主开关。false 会为所有人关闭同步。
liveSaveIntervalMillis	5000	1000 – 60000	新探索的区域到达其他在线玩家的速度（仅在至少 2 名已同步玩家在线时）。越低 = 地图越新，每个客户端工作量越大。如果玩家在一起探索时注意到卡顿，可以提高它。
reconcileIntervalSeconds	120	10 – 86400	每个客户端多久对照服务器复核一次自己的地图。也是加入玩家的已有地图到达已在线玩家所需的时间。
maxRegionsPerTick	2	1 – 64	每轮发送给追赶中玩家的地图区域数（使用默认间隔时：每秒 2 个，约 200–600 KB/s）。如果你有带宽，可以提高它以加快追赶速度。
syncIntervalTicks	20	1 – 1200	这些下载轮次之间的刻数（20 = 每秒一次）。
maxUploadsPerSecond	8	1 – 256	每位玩家的上传速率限制。
persistIntervalSeconds	30	0 – 3600	合并后的地图数据多久写入磁盘一次。0 表示每次更改都立即写入。
maxStoreBytes	4 GiB	256 MiB – 1 TiB	整个共享地图在磁盘上的大小上限。达到后，不会添加新区域，但已绘制区域会继续更新。一个充分探索的区域约占 100–200 KB，因此 4 GiB 大约可容纳 20 000–40 000 个区域。
maxRegionsPerLayer	50000	1 – 65536	每个维度和洞穴层存储区域的上限。
maxIoMillisPerSecondPerPlayer	500	50 – 1000	单个玩家可使用的服务器后台地图线程份额，这样拥有巨大地图的玩家就不会拖慢其他所有人。
maxPayloadBytes	1 MiB	64 KiB – 1.5 MiB	单次最大地图上传或下载。
maxInFlightBytesPerPlayer	8 MiB	– 64 MiB	单个玩家可排队的未处理上传数据量。
regionCacheSize	128	8 – 4096	服务器在内存中保留的地图区域数（默认约 10–30 MB）。
ioQueueCapacity	512	16 – 65536	服务器后台工作队列的深度。

大多数服务器永远不需要更改任何内容。人们实际会调整的是 liveSaveIntervalMillis、maxRegionsPerTick 和 maxStoreBytes。

---

性能

• 在服务器上独自游玩： 此模组不会改变 Xaero 自身的行为或时机。
• 每帧： 模组自身代码每个客户端刻的开销约为 0.01 毫秒。所有地图解析、合并和磁盘工作都在最低优先级的后台线程上运行。
• 一起游玩： 当至少有一名其他已同步玩家在线时，Xaero 会被要求每 5 秒保存一次地图区域，而不是每 60 秒一次，这样发现能快速到达朋友那里。在无上限 FPS 测试中，这在约 2000 FPS 时花费约 10%，即每帧几百微秒；在正常帧率下你不会注意到。服务器管理员可以提高 liveSaveIntervalMillis，以新鲜度换取更少的工作量。
• 追赶一张大地图： 服务器上有 1000 个地图区域时，新加入的玩家在默认下载速率下约 7 分钟内完全追上，并且服务器在发送过程中从未落后（“Can't keep up”）。

---

已知限制

• 局域网世界： 主机自己的地图不会同步，因为 Xaero 已经直接从存档中绘制主机的世界。加入的访客会同步，由主机充当服务器。
• 已有地图按计时器传输，而非实时： 玩家在加入之前已有的地图数据会在后台上传，并在其他在线玩家下一次周期性检查时到达他们（默认每 120 秒）。新探索的区域是实时的。
• 升级 Minecraft： Xaero's World Map 在某些 Minecraft 版本上存储地图的方式不同（1.16.5、1.18.2 – 1.21.4、1.21.5 – 26.2 和 26.3 各自使用自己的格式）。如果你的服务器迁移到格式不同的版本，共享地图会重新开始，并根据玩家上传的内容重建。不会删除任何内容：旧的服务器地图会保留在磁盘上。一旦 Xaero's World Map 以新格式重写每个玩家自己的旧地图，它就会再次同步，这会在他们重新访问该区域时发生。
• Xaero 的“完整”洞穴模式不会同步；常规洞穴层会同步。
• 你正在查看的地图区域在其他玩家的图块到达时会短暂重新加载。
• 同一服务器上的混合加载器，例如在 NeoForge 服务器上的 Fabric 玩家，尚未经过测试。
• 大量人为负载，例如每秒将多名玩家脚本传送到未生成的地形中，可能会压垮原版世界生成。这是原版的限制；模组本身绝不会阻塞服务器线程。

---

常见问题

服务器需要 Xaero's World Map 吗？ 是的，服务器和每个玩家都需要。这正是新区域能立即出现在你地图上的原因，即使是你尚未访问过的维度也是如此。

其他玩家能看到我的基地吗？ 如果你探索过它，就能看到：任何人绘制的每个区域都会成为共享地图的一部分。这就是此模组的意义所在，所以在有秘密基地的服务器上请记住这一点。路径点绝不会被共享；它们对每个玩家保持私密。

路径点会同步吗？ 不会。只有已探索的地图本身会同步。

破坏者能清除或搞乱共享地图吗？ 不能。合并只会添加或更新图块，玩家发送的任何内容都无法删除其他人探索过的内容，并且玩家从未接近过的地方的数据绝不会被广播。

它会同步我的单人游戏地图吗？ 不会。单人游戏世界绝不会被触及。对局域网开放的世界会为加入的访客同步，而不是为主机同步。

没有安装此模组的玩家会怎样？ 他们可以正常加入和游玩，使用自己的个人 Xaero 地图。

如果 Xaero's World Map 更新了怎么办？ 模组会在启动时自检。如果它需要的某些内容发生了变化，它会用一条聊天消息关闭同步并继续运行；不会崩溃，你的地图也会继续工作。

我可以在不卸载的情况下关闭它吗？ 可以：在服务器配置中将 syncEnabled 设为 false 并重启。

共享地图存储在哪里？ 在世界存档中，位于 <world>/unified_xaero_worldmap/ 下。它会与你的世界一起备份。

这是 Xaero 制作的吗？ 不是。这是一个独立、非官方的附加组件。请参阅致谢。

---

致谢

本项目是 Xaero96 的 Xaero's World Map 的非官方附加组件（CurseForge 项目 ID：317780）。

它通过服务器范围的共享地图同步扩展了 Xaero's World Map，允许已探索的地图图块在玩家之间共享，同时继续使用 Xaero's World Map 作为底层地图系统。

Xaero's World Map 是必需的依赖项，没有它此附加组件无法运行。Xaero's Minimap 可选支持，但不是必需的。

原始地图系统、地图渲染、地图存储、探索追踪及相关功能的所有功劳归 Xaero96 和原始 Xaero's World Map 项目所有。

本项目独立、非官方，与 Xaero96 无关联，也未得到其认可。它不包含或重新分发 Xaero's World Map 或 Xaero's Minimap。

原始项目： https://www.curseforge.com/minecraft/mc-mods/xaeros-world-map 原作者： Xaero96 CurseForge 项目 ID： 317780