LitematicaFolia
面向 Paper 和 Folia 的服务端 Litematica。将 .litematic 文件直接加载到服务器,并让使用未修改版 Litematica 的玩家通过 Servux 将他们的结构图上传至服务器。没有 /fill 刷屏,不会因刷屏而被踢出,也不需要 WorldEdit 介入。
解决的问题
Litematica 是一个仅客户端的 Fabric 模组。其服务端配套组件(Servux、Syncmatica)也仅限于 Fabric。因此在 Paper 上,玩家只能获得 Litematica 的 /setblock 降级方案,而该降级方案体验较差:它会丢弃方块实体 NBT、实体以及待处理的方块刻和流体刻;聊天速率限制将其速度限制在每秒约 20 个方块;且当命令频率超过每秒约 30 条时,Paper 会直接将玩家踢出。
LitematicaFolia 填补了 Paper 缺失的服务端部分。它:
- 使用内置 NBT 解析器读取和写入 v6 和 v7 版本的
.litematic 文件,因此无需额外依赖
- 通过 Folia 的
RegionScheduler 进行粘贴,每次处理一个区块任务,保持 TileEntity、Entity、PendingBlockTick 和 PendingFluidTick 数据完整
- 在粘贴时对旧版本文件运行 DataFixerUpper
- 实现了足够的 Servux 协议交互,使得原版 Litematica 客户端可以直接向服务器粘贴结构图,就像在 Fabric + Servux 环境下那样
值得了解的粘贴细节:观察者和活塞会在第二遍操作中放置,物理效果被延迟处理,并且存在拆分上限(默认为 128 MiB),以防止超过 40 MiB 的结构图崩溃。
我测试过的最大规模是 420 万个方块,耗时 9.5 秒。直接粘贴的最高记录是在 5.6 秒内完成 87 万个方块(包含 6,500 个方块实体)。两种情况下均未出现区域文件损坏。
命令基于 Brigadier,整个插件采用 MIT 许可证。
0.5.1 (MC 26.2) 更新内容
首个适用于 26.2 版本的发布。
另一个修复项:Direct Paste 现在可以在 Leaves 系列核心(如 Lophine、Leaves 等)上正常工作。这些服务端核心自行处理 Servux 协议,并默默地吞掉了插件的 servux:* 通道,导致客户端上传永远挂起且无错误提示。插件现在会在启动时重新接管这些通道。在普通的 Paper 或 Folia 上,此操作为无效操作(no-op)。
已在 Paper 26.2 (build 62)、完整端到端 Direct Paste 功能的源码构建版 Folia 26.2,以及生产环境中的 Lophine 26.2 上经过测试。
安装
- 下载
LitematicaFolia-<version>-all.jar
- 放入
plugins/ 目录
- 重启(或热重载)服务器
- 如果你希望启用 Direct Paste,请在
plugins/LitematicaFolia/config.yml 中设置 protocol.enableServuxBridge: true
需要 Paper 或 Folia 26.2(分支版本也可用:Luminol、Lophine、Purpur)以及 Java 25。如果在 26.1.x 版本上运行,请停留在 0.4.x 版本。
Direct Paste 客户端设置
玩家需要 Fabric Loader 0.16 或更高版本,以及 Fabric API、MaLiLib 和 Litematica,所有组件均需与 Minecraft 版本匹配。
然后,在 Litematica 的 Configs → Generic 选项卡中:
| 设置 |
值 |
ENTITY_DATA_SYNC |
true |
PASTE_USING_SERVUX |
true |
PASTE_USE_FILL_COMMAND |
false |
PASTE_ALWAYS_USE_FILL |
false |
ENTITY_DATA_SYNC_BACKUP |
true |
ENTITY_DATA_SYNC 是最容易让人忽略的一项。如果关闭此项,Litematica 会静默拒绝我们的 S2C_METADATA 数据包,回退到 /setblock 刷屏模式,最终导致玩家被踢出。UI 中没有任何提示告知你发生了这种情况。
此外,他们还需要在 Configs → Hotkeys 中将 executeOperation 绑定到一个按键上,因为默认情况下它是未绑定的。
工作流程如下:
- 打开 Litematica 菜单 (
M)
- 加载 Schematics,选择文件
- Loaded Schematics → Create Placement,定位结构
- 手持 Litematica 工具(一根木棍)
- 切换 Tool Mode 为 "Paste Schematic in world"
- 看向放置位置并按下
executeOperation 键
已验证兼容 litematica-fabric-1.21.11-0.27.6。
如果你运行 Velocity
Direct Paste 产生的流量峰值会触发默认 5 MiB/s 的数据包限制器,对于大约 10 MiB 以上的结构图尤为明显,因此请在 velocity.toml 中添加:
[packet-limiter]
decompressed-bytes-per-second = -1
保持 compression-threshold 为默认的 256 不变。
对于 DataVersion 远低于当前版本的旧文件,给予客户端更多时间来完成任务并上传:
-Dpaper.playerconnection.keepalive=120
命令
| 命令 |
权限节点 |
/litematica paste <file> [x y z] [yaw] [--no-entities] [--no-physics] |
litematica.paste |
/litematica save <name> <x1 y1 z1> <x2 y2 z2> |
litematica.save |
/litematica materials <file> |
litematica.materials |
/litematica list [--filter <glob>] |
litematica.use |
/litematica info <file> |
litematica.use |
/litematica cancel [ticket] |
litematica.paste |
/litematica reload |
litematica.admin |
配置
paste:
maxBlocksPerChunkTask: 8192
allowEntities: true
allowTileEntities: true
allowPendingTicks: true
deferredPhysics: true
observersLast: true
runDataFixer: true
minDataVersion: 2586
protocol:
enableServuxBridge: false # 默认关闭
enableEasyPlace: false
maxDirectPasteSize: 134217728 # 128 MiB,若需支持 3200 万+ 方块的结构图可适当调高
与其他方案的对比
|
LitematicaFolia |
Litematica /fill 降级方案 |
FAWE |
.litematic 支持 |
原生支持 |
不适用(仅限客户端) |
非原生支持 |
| 服务端粘贴 |
是 |
否 |
是,针对 .schem |
| 来自客户端的直接粘贴 |
是,通过 Servux |
否 |
否 |
| 方块实体保留 |
完整 NBT |
无 |
部分保留 |
| 实体保留 |
完整 NBT |
无 |
部分保留 |
| 待处理方块刻 |
是 |
否 |
否 |
| Folia 支持 |
原生支持 |
取决于具体情况 |
部分支持 |
| 速率限制踢出风险 |
无 |
高 |
无 |
如果你需要进行通用的世界编辑,FAWE 仍然是更好的工具;本插件仅专注于 .litematic 格式。
许可与致谢
MIT,且符合 LGPL 清理标准:未复制上游代码。格式解析基于公开的 Litematica 规范,参考了 litemapy 和 Lite2Edit。Servux 线框格式与 sakura-ryoko/servux 逐字节匹配,并在 26.2-0.11.1 版本中重新验证确认无变更。
由 exo 为 ekaii 网络制作,借鉴了 AxiomPaperPlugin 和 PaperMC 的设计模式。
Litematica 是 maruohon 的作品,Servux 协议则是 sakura-ryoko 的杰作。没有这两者,本插件将无从诞生。
标签:litematica、servux、schematic、litematic、paper、folia、server-side、direct-paste、nbt、paste、worldedit-alternative、building
LitematicaFolia
Server-side Litematica for Paper and Folia. Load .litematic files straight onto the server, and let players on unmodified Litematica push their schematics up to it over Servux. No /fill spam, no getting kicked for spamming, no WorldEdit in the mix.
The problem this solves
Litematica is a client-only Fabric mod. Its server-side companions (Servux, Syncmatica) are Fabric-only too. So on Paper the only thing your players get is Litematica's /setblock fallback, and that fallback is rough: it drops tile entity NBT, entities and pending block ticks; the chat rate limit caps it around 20 blocks a second; and past roughly 30 commands a second Paper kicks them anyway.
LitematicaFolia is the missing server half for Paper. It:
- reads and writes
.litematic v6 and v7 with an inline NBT parser, so no extra dependencies
- pastes through Folia's
RegionScheduler, one chunk task at a time, keeping TileEntity, Entity, PendingBlockTick and PendingFluidTick data intact
- runs older files through DataFixerUpper at paste time
- speaks enough of the Servux wire protocol that a vanilla Litematica client can paste directly to the server, the same way it would against Fabric + Servux
Paste details worth knowing: observers and pistons go down in a second pass, physics is deferred, and there's a splitter cap (128 MiB by default) so 40 MiB+ schematics don't fall over.
The heaviest thing I've thrown at it is 4.2 million blocks, which took 9.5 seconds. Direct Paste peaked at 870k blocks with 6,500 tile entities in 5.6 seconds. No region file corruption in either case.
Commands are Brigadier-based, and the whole thing is MIT licensed.
What's new in 0.5.1 (MC 26.2)
First release for 26.2.
The other fix in here: Direct Paste now works on Leaves-lineage cores (Lophine, Leaves, etc.). Those server cores handle the Servux protocol themselves and were quietly swallowing the plugin's servux:* channels, so client uploads would just hang forever with no error. The plugin now reclaims its channels at startup. On plain Paper or Folia that's a no-op.
Tested against Paper 26.2 (build 62), a source-built Folia 26.2 with full end-to-end Direct Paste, and Lophine 26.2 in production.
Installation
- Grab
LitematicaFolia-<version>-all.jar
- Drop it in
plugins/
- Restart (or hot-reload)
- If you want Direct Paste, set
protocol.enableServuxBridge: true in plugins/LitematicaFolia/config.yml
Needs Paper or Folia 26.2 (forks are fine: Luminol, Lophine, Purpur) and Java 25. On 26.1.x, stay on the 0.4.x releases.
Client setup for Direct Paste
Players need Fabric Loader 0.16 or newer, Fabric API, MaLiLib and Litematica, all matching their Minecraft version.
Then, in Litematica's Configs → Generic tab:
| Setting |
Value |
ENTITY_DATA_SYNC |
true |
PASTE_USING_SERVUX |
true |
PASTE_USE_FILL_COMMAND |
false |
PASTE_ALWAYS_USE_FILL |
false |
ENTITY_DATA_SYNC_BACKUP |
true |
ENTITY_DATA_SYNC is the one that catches people out. With it off, Litematica silently rejects our S2C_METADATA packet, drops back to /setblock spam, and the player gets kicked. Nothing in the UI tells you that's what happened.
They'll also need to bind executeOperation to a key in Configs → Hotkeys, since it's unbound by default.
Then the workflow is:
- Open the Litematica menu (
M)
- Load Schematics, pick the file
- Loaded Schematics → Create Placement, position it
- Hold the Litematica tool (a stick)
- Cycle Tool Mode to "Paste Schematic in world"
- Look at the placement and hit the
executeOperation key
Validated against litematica-fabric-1.21.11-0.27.6.
If you run Velocity
Direct Paste bursts trip the default 5 MiB/s packet limiter on anything over about a 10 MiB schematic, so in velocity.toml:
[packet-limiter]
decompressed-bytes-per-second = -1
Leave compression-threshold alone at 256.
For old files where the DataVersion is well behind current, give clients more headroom to finish DataFixer plus upload:
-Dpaper.playerconnection.keepalive=120
Commands
| Command |
Permission |
/litematica paste <file> [x y z] [yaw] [--no-entities] [--no-physics] |
litematica.paste |
/litematica save <name> <x1 y1 z1> <x2 y2 z2> |
litematica.save |
/litematica materials <file> |
litematica.materials |
/litematica list [--filter <glob>] |
litematica.use |
/litematica info <file> |
litematica.use |
/litematica cancel [ticket] |
litematica.paste |
/litematica reload |
litematica.admin |
Configuration
paste:
maxBlocksPerChunkTask: 8192
allowEntities: true
allowTileEntities: true
allowPendingTicks: true
deferredPhysics: true
observersLast: true
runDataFixer: true
minDataVersion: 2586
protocol:
enableServuxBridge: false # off by default
enableEasyPlace: false
maxDirectPasteSize: 134217728 # 128 MiB, raise for 32M+ block schematics
Versus the alternatives
|
LitematicaFolia |
Litematica /fill fallback |
FAWE |
.litematic support |
native |
n/a (client-only) |
not natively |
| Server-side paste |
yes |
no |
yes, for .schem |
| Direct Paste from client |
yes, via Servux |
no |
no |
| TileEntity preservation |
full NBT |
none |
partial |
| Entity preservation |
full NBT |
none |
partial |
| Pending block ticks |
yes |
no |
no |
| Folia support |
native |
depends |
partial |
| Rate-limit kick risk |
none |
high |
none |
FAWE is still the better tool if you're doing general world editing; this plugin only cares about .litematic.
License and credits
MIT, and LGPL-clean: no upstream code was copied. The format parsing came from the public Litematica spec, with litemapy and Lite2Edit as references. The Servux wire format is matched byte-for-byte against sakura-ryoko/servux, re-verified as unchanged at 26.2-0.11.1.
Made by exo for the ekaii network, borrowing patterns from AxiomPaperPlugin and PaperMC.
Litematica is maruohon's work and the Servux protocol is sakura-ryoko's. This plugin wouldn't exist without either.
Tags: litematica, servux, schematic, litematic, paper, folia, server-side, direct-paste, nbt, paste, worldedit-alternative, building
评论 0
登录后参与评分
还没有评论,来抢沙发吧