从另一台服务器的世界中提取区域文件到当前服务器,通过地图进行选择。
RegionCast 会显示自上次复制以来哪些区域发生了更改,你点击需要的区域,它会在受控重启期间将地形、兴趣点和实体传输过来。最近的几次更新支持撤销操作。
阅读西班牙语版
用途
你运行着一个镜像构建服务器的第二台服务器:一个创造模式的副本、一个测试世界、一个渲染世界,或者一个向他人展示基地但又不让他们进入真实世界的地方。保持其同步意味着需要复制整个世界,而这个世界有 8 GB 大小,其中 97% 的内容并未发生变化。
在真实服务器上,数据大致如下:1812 个主世界区域,总大小 8.0 GB,而在整整一天的游戏过程中,只有 59 个区域发生了变化。这仅占 407 MB。RegionCast 只会复制这 59 个区域。
其背后的理念与 TISUnion 的 region_file_updater 插件和旧的 !!region 命令相同,唯一的区别是:你可以在实际世界的地图上选择区域,而不是输入坐标并碰运气看是否选对了文件。
工作原理
- 地图瓦片大小为 512 x 512 方块。区域文件大小也是 512 x 512 方块。因此,一个瓦片就是一个区域,无需任何转换,地图直接绘制自客户端已拥有的区块。
- 颜色来源于账本(ledger),而非比较两个文件。进行比较并不可行:副本会获得一个新的时间戳,而镜像服务器会在有人走动时立即重写自己的区域文件。账本记录了源文件在被复制时的时间戳,并将后续源文件的时间戳与之进行比较。
- 复制操作发生在关闭期间。由于模组运行在 Minecraft 进程内部,它无法自行停止服务器、执行复制然后重新启动服务器:这会导致它在任务中途“杀死”自己。它可以做的是在
SERVER_STOPPED 阶段进行复制,此时世界已保存且所有区域文件均已关闭,但 JVM 仍处于存活状态。随后由外部程序重新启动服务器(参见 MCDReforged 插件)。
- 在复制之前,会通过 RCON 向源服务器发送
save-off 和 save-all flush 指令,并在之后发送 save-on,带有重试机制,因为让别人的服务器处于关闭存档状态比这个模组试图造成的任何影响都要糟糕。
区块
放大足够程度后,网格会从区域切换到区块,点击即可选择单个区块。没有模式切换按钮:在该缩放级别下,一个区域的宽度超过屏幕;缩小后,一个区块只是一个像素,因此手势在任何时候只能代表一种含义。
零散的区块与整个区域的复制方式不同。整个区域是直接的文件复制。而区块是从源区域的区域文件中读取出来,并写入到我们自己的文件中,使用 Minecraft 自带的 RegionFile 类,因此结果与游戏自行写入的数据逐字节一致。这样做的好处是可以单独传输一个建筑,而不必连带复制与其共享文件的 512 个方块的地形。
代价如下:
- 光照以及跨越区块边界的事物在游戏重新计算之前会处于半完成状态。虽然最终会完成,但在短时间内可见,主要是在洞穴中。
- 每块方块的耗时增加:每个区块都会被解压缩和重新压缩,并且源区域文件首先会被复制到工作文件夹中(
RegionFile 坚持要以写入模式打开文件,而源文件应该是只读挂载的)。尽管如此,耗时仍是秒级而非分钟级。
- 源文件仅对整个区域文件打时间戳,因此区块只能据此判断。区域中任何地方的更改都会导致你从中取出的所有区块都被标记为过时,即使那些区块无人触碰。这种错误方向是正确的——它会提示你去查看。
已复制的区块显示为绿色,当源区域更新后变为红色,排队等待时显示为金色。
备份
每次更新都会预留即将被替换的区域文件。最近的 3 次更新保留可撤销状态,较旧的备份会自动丢弃。
一个备份对应一次更新,而非一个区域:你点击若干区域,按下“更新”,稍后决定整批操作是个错误。恢复操作会将文件放回原位,恢复其原始时间戳,并用它们回滚账本,从而使恢复后的区域再次正确地被识别为过时,而不是声称匹配一个不再匹配的源文件。
/rc backups 列出可以回滚的备份
/rc restore 恢复最新的备份
/rc restore 2 恢复倒数第二个最新的备份
恢复操作的路径与更新相同:它已就绪,服务器重启,文件在世界关闭期间被写回。
有两点值得注意:
- 磁盘空间。一批 60 个区域大约占用这 60 个区域本身的大小,在一个繁忙的世界中约为 400 MB。三个这样的批次就超过 1 GB。请检查是否有足够的空间,或者降低配置项
backup_keep。
- 恢复操作不会备份它所覆盖的内容。恢复操作丢弃的是 RegionCast 从源服务器拉取的副本,而这正是你只需再次按下“更新”就能随时获取的东西。
要求
- Minecraft 1.21 / 1.21.1 或 26.3,Fabric 加载器及对应的 Fabric API。
- 1.21 版本需要 Java 21;26.3 版本需要 Java 25 和 Fabric Loader 0.19.5 或更高版本。
- 目标服务器必须能访问两个世界所在的文件系统。 这是真正的硬性要求:模组需要复制文件,因此源世界必须对目标进程可见。适用于 VPS 或专用机器,不适用于像 Aternos 或 Shockbyte 低端套餐那样的共享主机,因为你只能访问自己的文件夹。
- 可选但推荐:源服务器开启 RCON,以及能在目标服务器停止后自动重启它的工具。
客户端模组是可选的。没有它,一切仍可通过 /rc 命令正常工作;只是你将无法使用地图功能。
设置
1. 安装 jar 包 到目标服务器(镜像服务器)。如果你想要使用地图功能,也请在你的客户端上安装。
从 Modrinth 或
GitHub Releases 获取匹配的 jar 包。
更新时,请保留 config/regioncast.properties、世界文件以及你的备份目录。
复制账本、排队中的区块和区域以及现有备份均保持原有格式不变。
2. 使源世界对目标服务器可见,且仅设为只读。在 Linux 上,在世界文件夹旁边进行绑定挂载:
mount --bind -o ro /path/to/source/world /path/to/mirror/smp_world
将其添加到 /etc/fstab 并加上 nofail 选项,这样即使源目录缺失也不会阻止服务器启动。
RegionCast 绝不会写入源数据,但将其挂载为只读意味着即便此模组存在 bug,也无法对其进行写入。
3. 启动一次服务器。 它将生成 config/regioncast.properties:
# 要从中复制的世界文件夹路径,相对于世界文件夹的路径或绝对路径
source_world=../../smp_world
# 源服务器的 RCON,用于在执行前 save-off 和执行后 save-on
rcon_host=
rcon_port=25575
rcon_password=
# 打开地图和排队区域所需的操作员权限等级
permission_level=3
# 当有其他玩家在线时拒绝执行更新
require_empty=false
# 保留多少个可撤销的更新,设为 0 则从不备份任何内容
backup_keep=3
backup_dir=../regioncast-backups
配置文件应放入目标服务器的 mods 配置文件夹中。如果你使用 working_directory: server 运行 MCDReforged,那就是 server/config/,而不是旁边的 MCDR config/。
之后的重启
模组会停止服务器以进行复制,并在退出前打印最后一行信息:
[RegionCast] RESTART_REQUESTED
任何监控该信息的程序都可以重新启动服务器。mcdr/ 中提供了一个现成的
MCDReforged 插件:将
regioncast_restart.py 放入你的 MCDR plugins/ 文件夹即可。
如果你使用 MCDReforged,则必须安装它。当服务器进程自行结束时,MCDR 也会随之关闭,而在容器中这会连同整个容器一起关闭。该插件会在检测到标记的那一刻取消这一行为,此时服务器仍在关闭过程中:等到 on_server_stop 运行时,决定已经做出。
使用方法
/rc 打开地图;如果无法打开,则打印状态
/rc map 打开地图(需要客户端模组)
/rc status 显示哪些内容过期、哪些已排队、哪些备份存在
/rc here 将你所在的区域加入队列
/rc here chunk 仅将你所在的区块加入队列
/rc add <dim> <x> <z> 按索引逐个添加区域,维度为 -1、0 或 1
/rc scan 重新读取源数据
/rc list 显示排队内容
/rc clear 清空队列
/rc run 复制所有内容,然后重启
/rc backups 列出可以回滚的更新
/rc restore [n] 回滚其中一个更新,然后重启
在地图界面:左键点击 以排队或取消排队你指向的区域,右键拖拽
以平移视图,滚轮滚动 以缩放。缩小后显示的是区域;放大后显示的是区块。颜色含义如下:红色表示自上次复制以来已更改,蓝色表示从未复制,金色表示已排队。
队列会在重启后保留,因此因其他原因宕机的服务器不会迫使你重新点击四十个区域。
注意事项
- 不要通过比较两个世界的 md5 值来验证副本。 这正是账本旨在避免的比较方式,它会错误地报告区域失败而实际上并未失败:源世界仍在持续游玩,镜像会在这些区块加载后立即重写其自身的副本。请通过每个区域的日志行(
copied 3 deleted 0)以及 /rc scan 进行验证。
- 不要覆盖正在运行的服务器上的 jar 包。 Java 采用惰性加载类的方式,因此在活动服务器下替换 jar 包意味着任何尚未加载的类将无法再次被读取。请先停止服务器,替换 jar 包,再重新启动。
- 下界地图如果从上往下绘制看起来像一个灰色天花板。 RegionCast 在有天花板的维度中从你自己的 Y 坐标开始扫描,并在你垂直移动超过 8 格时重新绘制。
构建
./gradlew build
python3 tools/multiversion.py
基础构建需要 JDK 21。多版本构建需要 JDK 21 和 25,并将两个 jar 包放置在 build/multiversion/ 中。
model 和 sync 包故意不包含任何 Minecraft 类,因此复制、账本、队列、备份以及 RCON 协议的所有单元测试都是针对临时文件夹而非 13 GB 的世界进行的。唯一的例外是 anvil,它必须与 Minecraft 自身的区域文件代码通信,因此它是针对真实区域文件进行测试的。共有 125 项测试,在每次推送时在 CI 中运行。
许可证
MIT。请参阅 LICENSE。
W4VE 的一部分,Ware 4 Vanilla Experience。
Pull region files from another server's world into this one, picked off a map.
RegionCast shows you which regions changed since the last time you copied them, you click the ones
you want, and it brings terrain, points of interest and entities across during a controlled
restart. The last few updates stay undoable.
Leer en español
What it is for
You run a second server that mirrors a build server: a creative copy, a testing world, a render
world, a place to show people a base without letting them into the real one. Keeping it up to date
means copying the world across, and the world is 8 GB, and 97% of it did not change.
On a real server the numbers look like this: 1812 overworld regions, 8.0 GB, and in a whole day of
play only 59 of them change. That is 407 MB. RegionCast copies those 59.
The idea is the same one behind TISUnion's region_file_updater plugin and the old !!region
commands, with one difference: you pick the regions on a map of the actual world instead of typing
coordinates and hoping you got the right file.
How it works
- A map tile is 512 by 512 blocks. A region file is 512 by 512 blocks. So a tile is a region,
no conversion anywhere, and the map is drawn from the chunks your client already has.
- Colours come from a ledger, not from comparing the two files. Comparing does not work: the
copy gets a fresh timestamp, and the mirror rewrites its own region files the moment somebody
walks around. The ledger records the timestamp the source file had when it was copied, and
compares future source timestamps against that.
- Copying happens during shutdown. A mod lives inside the Minecraft process, so it cannot stop
the server, copy, and start it again: it would be killing itself half way through the job. What
it can do is copy in
SERVER_STOPPED, when the world is saved and every region file is closed
but the JVM is still alive. Something outside then starts the server again (see
MCDReforged plugin).
- Before copying, the source server is told
save-off and save-all flush over RCON, and
save-on afterwards, with retries, because leaving somebody else's server with saving off is
worse than anything this mod was trying to do.
Chunks
Zoom in far enough and the grid switches from regions to chunks, and clicking picks a single
chunk. No mode button: at that zoom a region is wider than the screen, and zoomed out a chunk is a
pixel, so the gesture can only mean one thing at a time.
Loose chunks are copied differently to whole regions. A region is a file copy. A chunk is opened
out of the source's region file and written into ours, using Minecraft's own RegionFile, so the
result is byte for byte what the game would have written itself. What that buys you is taking one
build across without the 512 blocks of terrain it shares a file with.
What it costs:
- Lighting and anything crossing a chunk border arrives half done until the game recalculates
it. It does, but it is visible for a moment, mostly in caves.
- Slower per block: every chunk is decompressed and recompressed, and the source region file
is copied to a work folder first (
RegionFile insists on opening its file for writing, and the
source is supposed to be mounted read only). Still seconds, not minutes.
- The source only timestamps whole region files, so a chunk can only be judged against that.
A change anywhere in a region marks every chunk you took out of it as out of date, even ones
nobody touched. Wrong in the direction that tells you to look.
Copied chunks are painted green, red once the source moves on, gold while queued.
Backups
Every update sets aside the region files it is about to replace. The last 3 updates stay
undoable, and older ones are dropped automatically.
A backup is one update, not one region: you click a handful of regions, press Update, and later
decide that whole batch was a mistake. Restoring puts the files back with their original
timestamps and rewinds the ledger with them, so restored regions correctly read as out of date
again rather than claiming to match a source they no longer match.
/rc backups list what can be taken back
/rc restore put the newest one back
/rc restore 2 put the second newest one back
Restoring takes the same route as an update: it is armed, the server restarts, and the files go
back while the world is closed.
Two things worth knowing:
- Disk. A batch of 60 regions costs roughly the size of those 60 regions, around 400 MB on a
busy world. Three of those is over a gigabyte. Check you have the room, or lower
backup_keep.
- Restoring does not back up what it overwrites. What a restore throws away is the copy
RegionCast pulled from the source, and that is the one thing here you can always fetch again by
pressing Update.
Requirements
- Minecraft 1.21 / 1.21.1 or 26.3, Fabric and the matching Fabric API.
- Java 21 for 1.21; Java 25 and Fabric Loader 0.19.5 or newer for 26.3.
- Filesystem access to both worlds from the destination server. This is the real requirement:
the mod copies files, so the source world has to be visible to the destination process. A VPS or
a dedicated machine, not a shared host like Aternos or the cheap end of Shockbyte where you only
get your own folder.
- Optional but recommended: RCON on the source server, and something that restarts the destination
server after it stops.
The client mod is optional. Without it everything still works through /rc; you just do not get
the map.
Setup
1. Install the jar on the destination server (the mirror). Install it on your client too if
you want the map.
Get the matching jar from Modrinth or
GitHub Releases.
When updating, keep config/regioncast.properties, the world and your backup directory.
The copy ledger, queued regions and chunks, and existing backups keep their format.
2. Make the source world visible to the destination server, read only. On Linux, a bind mount
next to the world folder:
mount --bind -o ro /path/to/source/world /path/to/mirror/smp_world
Add it to /etc/fstab with nofail so a missing source never stops the server from booting.
RegionCast never writes to the source, but mounting it read only means a bug in this mod cannot
either.
3. Start the server once. It writes config/regioncast.properties:
# path to the world folder to copy FROM, relative to the world folder or absolute
source_world=../../smp_world
# the source server's RCON, used for save-off before and save-on after
rcon_host=
rcon_port=25575
rcon_password=
# operator level needed to open the map and queue regions
permission_level=3
# refuse to run an update while other players are online here
require_empty=false
# how many updates stay undoable, 0 to never back anything up
backup_keep=3
backup_dir=../regioncast-backups
The config goes in the mods config folder of the destination server. If you run MCDReforged
with working_directory: server, that is server/config/, not the MCDR config/ beside it.
Restarting afterwards
The mod stops the server to copy, and prints one last line on the way out:
[RegionCast] RESTART_REQUESTED
Anything that watches for that can start the server again. A ready made
MCDReforged plugin is in mcdr/: drop
regioncast_restart.py into your MCDR plugins/ folder.
If you use MCDReforged, you need it. When the server process ends on its own MCDR shuts itself
down with it, and in a container that takes the whole container with it. The plugin cancels that
the moment it sees the marker, which is while the server is still on its way down: by the time
on_server_stop runs the decision has already been made.
Using it
/rc open the map, or print the status if you cannot open one
/rc map open the map (needs the client mod)
/rc status what is out of date, what is queued, what backups exist
/rc here queue the region you are standing in
/rc here chunk queue only the chunk you are standing in
/rc add <dim> <x> <z> queue one by index, dimension -1, 0 or 1
/rc scan re-read the source
/rc list what is queued
/rc clear empty the queue
/rc run copy it all, then restart
/rc backups list the updates that can be taken back
/rc restore [n] put one back, then restart
On the map: left click to queue or unqueue whatever you are pointing at, right click drag
to pan, scroll to zoom. Zoomed out that is a region; zoomed in it is a chunk. Colours are red
for changed since the last copy, blue for never copied, gold for queued.
The queue survives a restart, so a server that went down for some other reason does not make you
click forty regions again.
Things that will bite you
- Do not verify a copy by comparing md5 between the two worlds. That is exactly the comparison
the ledger exists to avoid, and it will tell you regions failed when they did not: the source
keeps being played, and the mirror rewrites its own copy as soon as those chunks load. Verify by
the log line per region (
copied 3 deleted 0) and /rc scan.
- Do not copy the jar over a running server. Java loads classes lazily, so replacing the jar
underneath a live server means any class it had not needed yet can never be read again. Stop the
server, replace the jar, start it.
- Nether maps look like a grey ceiling if you draw them from the top down. RegionCast starts
the scan at your own Y in dimensions with a ceiling, and redraws when you move more than 8 blocks
vertically.
Building
./gradlew build
python3 tools/multiversion.py
The base build needs JDK 21. Multiversion builds need JDK 21 and 25 and place both jars
in build/multiversion/.
The model and sync packages contain no Minecraft classes on purpose, so the copying, the
ledger, the queue, the backups and the RCON protocol are all unit tested against temporary folders
rather than a 13 GB world. The one exception is anvil, which has to talk to Minecraft's own
region file code, and is tested against real region files instead. 125 tests, run in CI on every
push.
License
MIT. See LICENSE.
Part of W4VE, Ware 4 Vanilla Experience.
评论 0
登录后参与评分
还没有评论,来抢沙发吧