LitematicaFolia

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

1. Grab LitematicaFolia-<version>-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:

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:

[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

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

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