🏗 Schematic
Paste schematic files into block worlds using the cocoa-beans-schematic modules.
Getting Started
Installation
Quick Start
Building Schematics
Creating from Scratch
Build schematics programmatically block by block using SpigotSchematicBuilder:
Capturing from the World
Extract a region from a live Bukkit world using SpigotSchematicHelper:
Transforming Schematics
Use toBuilder() to create a modified copy of an existing schematic:
Available transformations:
rotate(90|180|270)— Rotate schematicflip(Axis)— Mirror along axistranslate(Position)— Change paste offsettranslate(AxisOrder)— Reorder block storage axisshift(Axis, int)— Move all blocks along an axis
Saving and Loading Schematics
Setting Up the Format
CocoaSchematicFormat handles reading and writing .cbschem files. Create one instance and reuse it:
Saving to a File
Saving to Bytes (In-Memory)
Useful for caching, network transfer, or database storage:
Loading from a File
Loading from Bytes
Full Round-Trip Example
Capture a region, save to disk, reload later, and paste it:
Pasting Schematics
Basic Pasting
The simplest paste operation places all non-air blocks at the given location:
Incremental Pasting
For large schematics, paste gradually to avoid lag:
Axis Order Control
Control placement direction for visual effect:
Advanced Placement Control
Placement Filters
Control which world blocks are overwritten via setShouldPlace:
Block Mapping
Transform block data before placement via setMapper:
Post-Placement Actions
Execute code after each block is placed:
Multiple actions are executed in the order they were registered.
Dynamic Configuration
Filters and mappers can be swapped mid-operation:
Complete Examples
Example 1: Capture, Save, and Load
Plugin command that captures a selection and saves it to disk:
Example 2: Async Paste with Progress
Show progress while pasting a large schematic:
Example 3: Layer-by-Layer with Sound Effects
Paste one Y-layer per tick with a sound:
Example 4: Block Substitution on Paste
Replace worn materials when pasting a renovation schematic:
API Reference
Core Classes
Schematic<T> — Represents an immutable 3D schematic
size()—AreaSizewithwidth(),height(),depth()metadata()—SchematicMetadatawithtitle()andauthor()offset()— Origin offset asPositionaxisOrder()— Block storage ordergetBlockData(x, y, z)— Block at relative position (null= air)blocksIterator()— Iterate all non-air blockstoBuilder()— Create a mutable copy
SchematicBuilder<T> — Fluent schematic builder
metadata(Function<SchematicMetadataBuilder, SchematicMetadata>)— Set title, author, custom keyssize(AreaSize)— Set bounding boxsetBlock(x, y, z, BlockData)— Place a blockremoveBlock(x, y, z)— Remove a blockrotate(90|180|270)— Rotate contentflip(Axis)— Mirror contenttranslate(Position)— Change paste offsetshift(Axis, int)— Shift all blocksbuild()— Produce the schematic
CocoaSchematicFormat<T> — Serializes/deserializes .cbschem files
write(schematic, SeekableOutputStream)— Write schematicread(SeekableInputStream)— Read schematic
PasteOperation — Stateful paste iterator
hasNext()— Whether more blocks remainperformAll()— Place everything at onceadvanceAllAxis(n)— Place up to n blocksperformAllOnDualAxis()— Place one layer (two axes fixed)performAllOnSingleAxis()— Place one line (one axis fixed)
PasteResult — Outcome of a paste step
blockPlaces()— Number of blocks placedleftOver()— Remaining quota (when usingadvanceAllAxis)
Spigot Classes
SpigotSchematic — Spigot implementation of Schematic
paste(Location)— Create paste operation (replaces air only)paste(Location, AxisOrder)— With explicit axis order
SpigotPasteOperation — Spigot paste operation
setShouldPlace(BiPredicate<Block, BlockPlacement>)— Override placement filtersetMapper(Function<BlockPlacement, BlockData>)— Override block mapperaddPostPlaceAction(BiConsumer<Block, BlockData>)— Add callbackorigin()— Location where the paste started
SpigotSchematicHelper — Captures schematics from the world
load(title, author, playerPos, world, pos0, pos1, placer)— Extract region
SeekableOutputStream — Writable seekable channel
SeekableOutputStream.open(Path)— Open/create a file
SeekableInputStream — Readable seekable channel
SeekableInputStream.open(Path)— Open an existing file
ByteArraySeekableChannel — In-memory seekable channel
ByteArraySeekableChannel()— Empty, for writingByteArraySeekableChannel.of(byte[])— Pre-filled, for readingtoByteArray()— Extract written bytes
Performance Tips
Use incremental pasting for large schematics — 100–200 blocks per tick is a safe budget
Choose axis order wisely — how you would like to build the structure
Minimise post-placement actions — they run per block; keep them cheap
Re-use
CocoaSchematicFormat— constructing it is expensive; create one instance at plugin startupSave with GZIP compression (default) for disk storage; consider
CompressionType.RAWfor hot in-memory caches where CPU matters more than size
Version: 0.0.46 Repository: GitHub