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:

1. Reads .litematic v6/v7 files server-side via an inline NBT parser (zero external dep)
2. Pastes via Folia's RegionScheduler per-chunk dispatch — observers-last, deferred-physics, full TileEntity + Entity + PendingBlockTick NBT preserved
3. 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

1. Download LitematicaFolia-<version>-all.jar
2. Drop it in your server plugins/ folder
3. Restart the server (or hot-reload)
4. Edit plugins/LitematicaFolia/config.yml to flip protocol.enableServuxBridge: true if you want Direct Paste from clients
5. 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

1. Open Litematica menu (M)
2. Load Schematics → pick your .litematic
3. Loaded Schematics → Create Placement → position it
4. Hold the Litematica tool (a stick)
5. Tool Mode: Paste Schematic in world (cycle if needed)
6. 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

Tags

litematica, servux, schematic, litematic, paper, folia, server-side, direct-paste, nbt, paste, worldedit-alternative, building

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.