LitematicaFolia

Server-side Litematica for Paper and Folia. Load .litematic schematics directly on your Minecraft server and accept Direct-Paste uploads from vanilla Litematica clients via the Servux protocol — no /fill spam, no kick-for-spamming, no WorldEdit dependency.

First Paper/Folia plugin to natively parse and paste .litematic files. Replaces Litematica's legacy /setblock + /fill fallback (lossy, slow, kick-prone) with a real server-side pipeline.

Why does this exist?

Litematica is a client-only Fabric mod. Its companion server tooling (Servux, Syncmatica) is Fabric-only. On Paper/Bukkit servers the only available behaviour is Litematica's /setblock-spam fallback, which is:

lossy — no tile-entity NBT, no entities, no pending block ticks
slow — chat-command rate limit caps it at ~20 blocks/sec
fragile — Paper kicks for spamming after 30+ commands/second

LitematicaFolia is the missing piece for the Paper side of the wall:

Reads .litematic v6/v7 files server-side via an inline NBT parser (zero external dep)
Pastes via Folia's RegionScheduler per-chunk dispatch — observers-last, deferred-physics, full TileEntity + Entity + PendingBlockTick NBT preserved
Speaks the Servux wire protocol so vanilla Litematica clients can Direct-Paste their in-memory schematics directly to the server — same way it works on a Fabric+Servux server

Features

✅ Native .litematic v6/v7 reader and writer (NBT-gzipped, compact cross-word packing, multi-region, palette resolution)
✅ Folia-safe paste — per-chunk RegionScheduler.run, observers/pistons placed in a second pass, full TileEntity + Entity + PendingBlockTick + PendingFluidTick NBT preserved
✅ Servux Direct Paste — vanilla Litematica clients paste from their schematic GUI directly to the server (validated against litematica-fabric-1.21.11-0.27.6)
✅ DataFixerUpper bridge — older .litematic files are upgraded to the current MC version at paste time
✅ Brigadier commands — /litematica paste|save|materials|list|info|reload|cancel
✅ Production stress-tested — 4.2 M blocks pasted in 9.5 s, 870 k blocks + 6,500 tile entities via Direct Paste in 5.6 s, zero region-file corruption
✅ Configurable splitter cap (default 128 MiB) for 40 MiB+ schematics
✅ MIT licensed, LGPL-clean (Servux wire format reverse-engineered, no upstream code copied)

Installation

Download LitematicaFolia-<version>-all.jar
Drop it in your server plugins/ folder
Restart the server (or hot-reload)
Edit plugins/LitematicaFolia/config.yml to flip protocol.enableServuxBridge: true if you want Direct Paste from clients
Done.

Requirements: Paper 26.1.2 build 53+ (or any fork: Folia, Luminol, Purpur 26.1+), Java 25.

Client setup — Direct Paste

For players to paste directly from their own client, they need: Fabric Loader 0.16+, Fabric API, MaLiLib 0.28.6+, and Litematica 0.27.6+ (for 1.21.11).

Critical client config (the one nobody documents)

In Litematica's Configs → Generic tab, set:

Setting	Value
`ENTITY_DATA_SYNC`	`true` ← the hidden gate. Without this, Litematica silently rejects our `S2C_METADATA` packet → falls back to `/setblock` spam → kicked for spamming.
`PASTE_USING_SERVUX`	`true`
`PASTE_USE_FILL_COMMAND`	`false`
`PASTE_ALWAYS_USE_FILL`	`false`
`ENTITY_DATA_SYNC_BACKUP`	`true`

Then bind executeOperation to a free key in Configs → Hotkeys (default unbound).

Player workflow

Open Litematica menu (M)
Load Schematics → pick your .litematic
Loaded Schematics → Create Placement → position it
Hold the Litematica tool (a stick)
Tool Mode: Paste Schematic in world (cycle if needed)
Aim at the placement, press your executeOperation keybind

Done — full block-state + TileEntity + Entity fidelity, no command spam, no kick risk.

Server admin — Velocity proxy tuning

If your players connect through Velocity, set in velocity.toml:

[packet-limiter]
decompressed-bytes-per-second = -1

The default 5 MiB/s kicks any Direct Paste burst > 10 MiB schematic. Leave compression-threshold at default 256.

For old .litematic files (DataVersion < current), add to your Paper JVM args:

-Dpaper.playerconnection.keepalive=120

This gives clients 2 min to finish Mojang DataFixer + upload.

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 — flip to true to enable Direct Paste
  enableEasyPlace: false
  maxDirectPasteSize: 134217728    # 128 MiB — raise for 32M+ block schematics

How does it compare?

	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 (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

License

MIT. Format parsing reverse-engineered from the public Litematica spec (litemapy, Lite2Edit). Servux wire format aligned byte-for-byte with upstream sakura-ryoko/servux 26.1.2-0.10.2 — no upstream code copied; LGPL clean.

Made by exo for the ekaii Minecraft network. Built on patterns from Moulberry/AxiomPaperPlugin. Litematica by maruohon. Servux protocol by sakura-ryoko.