Clipboard Examples

Note

This documentation covers the API for using clipboards. See Clipboard for in-game usage & explanations of what clipboards are.

Concepts used in these examples: Regions, Edit Sessions, Extents

Copying

Copying is the most common way to create a clipboard. To do it, you’ll need a Region, and a source and target extent, such as a World and a Clipboard. In this example we use a CuboidRegion and the standard BlockArrayClipboard. Then, all you need to do is pass the parameters to the ForwardExtentCopy, apply configuration (such as calling setCopyingEntities(true)) to copy entities), and call Operations.complete.

CuboidRegion region = new CuboidRegion(min, max);
BlockArrayClipboard clipboard = new BlockArrayClipboard(region);

ForwardExtentCopy forwardExtentCopy = new ForwardExtentCopy(
    world, region, clipboard, region.getMinimumPoint()
);
// configure here
Operations.complete(forwardExtentCopy);

You may want to save the clipboard after this. Note that if you are only copying a clipboard to paste it immediately again, you should skip making the clipboard entirely. Instead, build an EditSession for the target world and pass that to ForwardExtentCopy - it is capable of copying blocks between any two extents, or even between the same one, and is not limited to clipboards.

Pasting

Pasting is the only way to move blocks from a Clipboard to another Extent, typically a World. To paste, you’ll need a target Extent (generally an EditSession for a World) and a Clipboard. Create a ClipboardHolder with your clipboard, then get a PasteBuilder by calling createPaste with the EditSession. Call .to to set the position at which you want to paste (this will be offset by the clipboard offset, see the clipboard page above for more information). Add any other configuration you want (masks, paste entities, paste biomes, etc.), and then call build() to get an operation. Complete the operation, and all the blocks will be pasted. Note that if you want to rotate the clipboard, you’ll need to setTransform on the ClipboardHolder before calling createPaste.

Full example:

try (EditSession editSession = WorldEdit.getInstance().newEditSession(world)) {
    Operation operation = new ClipboardHolder(clipboard)
            .createPaste(editSession)
            .to(BlockVector3.at(x, y, z))
            // configure here
            .build();
    Operations.complete(operation);
}

You may want to load a clipboard before this.

Schematic Examples

This section deals with schematics, which are a related but distinct concept. Schematics specifically refer to a saved clipboard, not a clipboard in-memory.

Saving

A Clipboard can be saved to disk very easily. All you need is a ClipboardFormat, a Clipboard, and an OutputStream. Then you can call getWriter on the format and write on the writer with your Clipboard. Here’s an example for saving a clipboard to file.

File file = /* figure out where to save the clipboard */;

try (ClipboardWriter writer = BuiltInClipboardFormat.SPONGE_SCHEMATIC.getWriter(new FileOutputStream(file))) {
    writer.write(clipboard);
}

Loading

Loading a Clipboard is nearly as simple. You can either force a specific ClipboardFormat, or have WorldEdit discover the format of the schematic you want to load. The example does the latter. Then you can call getReader on the format and read on the reader to get a Clipboard instance.

Clipboard clipboard;

ClipboardFormat format = ClipboardFormats.findByFile(file);
try (ClipboardReader reader = format.getReader(new FileInputStream(file))) {
    clipboard = reader.read();
}
/* use the clipboard here */