Описание
# LitematicaFolia
Server-side Litematica for Paper and Folia. Load `.litematic` files straight onto the server, and let players on unmodified [Litematica](https://github.com/maruohon/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](https://github.com/sakura-ryoko/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
1. Grab `LitematicaFolia--all.jar`
2. Drop it in `plugins/`
3. Restart (or hot-reload)
4. 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:
1. Open the Litematica menu (`M`)
2. Load Schematics, pick the file
3. Loaded Schematics → Create Placement, position it
4. Hold the Litematica tool (a stick)
5. Cycle Tool Mode to "Paste Schematic in world"
6. 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`:
```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 [x y z] [yaw] [--no-entities] [--no-physics]` | `litematica.paste` |
| `/litematica save ` | `litematica.save` |
| `/litematica materials ` | `litematica.materials` |
| `/litematica list [--filter ]` | `litematica.use` |
| `/litematica info ` | `litematica.use` |
| `/litematica cancel [ticket]` | `litematica.paste` |
| `/litematica reload` | `litematica.admin` |
## Configuration
```yaml
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](https://forgejo.ekaii.fr/admin_ekaii/litematica-folia-ekaii/src/branch/mc-26.2/LICENSE), and LGPL-clean: no upstream code was copied. The format parsing came from the public Litematica spec, with [litemapy](https://litemapy.readthedocs.io/) and [Lite2Edit](https://github.com/GoldenDelicios/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](https://ekaii.fr) network, borrowing patterns from [AxiomPaperPlugin](https://github.com/Moulberry/AxiomPaperPlugin) and [PaperMC](https://papermc.io).
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`