Skip to content

Schematic Pasting

Jump to bottom
Matti Ruohonen edited this page Jan 25, 2022 · 1 revision

Schematic Pasting - quickly place the entire schematic to the world

Schematic pasting allows you to quickly place the entire schematic (or a part of it, still to-be-implemented/improved) to the world. Pasting is a creative-only operation, and it does not consume any items, or have any kind of limitations on what blocks and in what states it can place. It will (at least try to) place everything that is in the original schematic, in the exact same way they are saved in the schematic. In single player it should be able to usually do exactly that - place it in the exactly same state.

Quick rundown

So to summarize the requirements, to paste a schematic:

  • Switch to Creative mode
  • Switch to the Paste schematic in world "tool mode"
    • Either use the button in the bottom left of the Litematica main menu, or hold Ctrl and scroll while holding the enabled tool item
  • You must be able to see the tool HUD on the bottom left, otherwise either the tool functionality or the main rendering is disabled, or you are holding the wrong item
  • Make sure the correct placement is selected (light cyan placement outline color in-world and the name is shown on the tool HUD)
  • Use the executeOperation hotkey to start the paste operation

Detailed requirements

For the Paste feature to work, you need the following things:

  • You need to be in Creative mode to be able to access and use the Paste mode.
    • Even if you change to the Paste mode while in creative, and then switch to survival, it won't allow you to execute while not in creative mode.
  • By default you need to be holding the enabled "tool item" when you use the executeOperation hotkey
    • The tool item functionality must be enabled (M + T to toggle it, or Generic -> toolItemEnabled).
    • You also need to have the main rendering option enabled (M + R or Visuals -> enableRendering).
    • Check that you are holding the correct item configured as the tool item, see Generic -> toolItem
    • Basically by default you need to be able to see the tool HUD on the bottom left for the executeOperation hotkey to work, as an indicator/safety feature.
    • There is a config option in Generic -> executeRequireHoldingTool to disable the requirement to be holding the tool item
  • You need to have the correct schematic placement selected.
    • The selected placement has the light cyan outline color in-world, and the selected placement's name is shown on the tool HUD on the bottom left corner, while you are in the Paste mode.
    • You can select the placement by looking at it in-world and (with the default hotkeys) middle clicking while holding the tool item. (Note that you don't need to be next to it, the targeting range is something around 200 blocks.)
    • Alternatively you can click on the placement in the Schematic Placements menu, so that it has the white outline. (A white thick outline in any of the menu lists indicates the currently selected entry. If you click on the selected entry again, it will be unselected.)
  • If you are on a server, then you need to have the permission to run the /setblock and the /fill commands, or alternatively (currently only in the 1.18.x+ versions) you need to have permission for the World Edit //pos1, //pos2 and //set commands.
    • You don't need to be OP if you have the permission to run the commands otherwise.
    • The actual used commands are configurable in the Generic config category. The command name can be changed, but (at least currently) the replacement must have the same arguments in the same order as the equivalent vanilla command.

Paste options

There are a number of config options related to the paste feature. The most common and probably the most important option is the block replace behavior option, most of the other options are only relevant when pasting on a server.

Paste block replace behavior

The block replace behavior option controls what blocks, if any, will get replaced when pasting the schematic blocks to the world. You can cycle the value by default with Ctrl + M, or change it in Generic -> pasteReplaceBehavior. The values and their effects are:

  • None - don't replace anything. Blocks will only get placed where there is currently air in the world.
  • With non-air - Only non-air blocks from the schematic will replace existing blocks in the world. In other words any air from the schematic is not placed and thus will not carve an empty room or air bubble underground or under water.
  • All - Everything from the schematic will get placed (if the existing block in the world is different).

Other common options

Note that many of these options for now are only in the 1.18.1+ versions of the mod.

  • commandUseWorldEdit - instead of using the vanilla (or equivalent) /setblock and /fill commands, use the World Edit //pos1, //pos2 and //set commands.
    • This also affects the Fill, Replace and Delete tool modes.
    • This can be useful if you don't have the permission for the vanilla commands, but you do have the permission for the World Edit commands.
    • In fact it's recommended to not use this if you have the permission for the vanilla commands, as the World Edit commands have more overhead (= the paste will be slower due to the command rate limit) compared to the vanilla commands (3 commands for "one operation" instead of just 1 command), and also the block replace behavior option will not work with these.
  • pasteIgnoreEntities - don't paste/summon any entities from the schematic
  • pasteIgnoreInventories - don't restore any inventory contents from the schematic (this really means don't restore NBT data)
  • pasteNbtRestoreBehavior - allows restoring block entity NBT data when pasting on a server. See the Restoring block entity NBT data on a server section
  • pasteToMcFunctionFiles - instead of actually placing the blocks, output all the commands to place the schematic into *.mcfunction files
  • pasteUseFillCommand - when pasting on a server, also use /fill commands to paste continuous regions of a single block state, instead of just individual /setblock commands for every block

Single Player vs. Multiplayer

There is a difference in what data is available for saving a schematic, and what data the mod is able to restore while pasting, based on whether you are in single player vs. when on a server.

Saving a schematic

A base rule of thumb is that you want to turn off any redstone contraptions before you save a schematic. Otherwise you will get weird and annoying stuff like moving piston heads or powered observers in the schematic. You would also get (or need) the scheduled block ticks for such running redstone components to be able to paste back a working (= not broken/de-synced/stuck) contraption.

Single Player

Schematics saved in single player will contain all the NBT data of block entities and entities, and the scheduled block ticks (for example for some redstone components). In single player the mod saves the schematic directly from the integrated server's server-side world, so it has access to all the data.

Multiplayer

The vanilla server does not send the full NBT data of block entities and entities to the clients, as the client normally doesn't need it, and it would waste a lot of network bandwidth and also server resources to keep syncing all the data all the time for no benefit. The server only sends data that the client actually needs for something, which usually means it affects the rendering of blocks or entities in some way. This is why in schematics saved from a server for example all inventories will be empty, and entities would also not contain their inventories or villager trades etc. Inventory contents are only synced to the client when you open the inventory GUI of the target object (block or entity), and the vanilla client also doesn't store those, it discards them as soon as you close the GUI again. Similarly the scheduled block ticks are never synced to the client, as the client has no need for those whatsoever.

So basically by default (in the case of "any random server") you won't be able to save a schematic with any NBT data such as inventory contents in tact. If you need all the NBT data of block entities (such as inventories) or entities to be saved in the schematic, you would need to save the schematic from a single player world.

There is however a mod combination which also allows you to save schematics with the block inventories in tact on servers. But this will need a mod to be present on the server side, so the default case is "no NBT when saving in multiplayer". If the server has the PCA extension mod for the Fabric Carpet mod, and the client has the MasaGadget mod, and the pcaSyncProtocol Carpet rule is enabled on the server, then you can also save schematics on that server while getting the inventory contents in the schematic. I haven't yet tested this myself, so I don't know if it also works for entities, and if it also fetches the scheduled block ticks (I doubt it?).

The Servux mod is also meant to get support both for saving and pasting schematics on servers while keeping all the data. No timeline or ETA yet as to when that will happen though.

Pasting

The paste operation works very differently in single player vs. when on a server.

Single Player pasting

In single player the paste operation is done directly in the integrated server's server-side world. Because of this, the mod is able to directly place the schematic in the exact same original state that it is in the schematic. This means that all the block entity NBT data and entity NBT data is also restored, as well as any scheduled block ticks stored in the schematic. The mod is also able to prevent block updates while placing the blocks, so that for example redstone contraptions won't get activated or floating blocks or fluids won't get updated. Obviously the mod is only able to restore any data that is saved in the schematic, so it also matters where the schematic was saved from (see Saving a schematic above).

Pasting on servers

When you paste a schematic on a server, then by default the mod only has two options for how to do it: place the blocks as the player, or use commands. Litematica only uses commands for this, as they have several advantages over trying to place stuff as a player:

  • You can place almost any block state directly via a /setblock command (some blocks may update their state when being added to the world, such that the requested state gets changed to something else that is "valid")
  • There is no range limitation for the player to have to be closer than 6 or 8 blocks
  • The player looking direction does not matter
  • There are no limitations like "block X needs block Y below to be able to be placed"
  • You can also place blocks that don't have an item, such as nether portal blocks or end portal blocks

Litematica originally only used individual /setblock commands for pasting, which means that you need one command for each block being placed. The pasting was improved (starting in the 0.10.0 version for MC 1.18.1) to have an option (Generic -> pasteUseFillCommand, enabled by default) to also split the schematic into larger regions that will get placed via /fill commands, to often greatly reduce the number of commands required to paste the schematic.

Since the server usually doesn't like too many commands being sent too quickly, there are two config options to control how quickly Litematica send the commands to the server, both in the Generic config category:

  • commandLimitPerTick (previously called pasteCommandLimit) - how many commands to send per each execution of the paste task
    • Note: not related to the executeOperation hotkey usage or name - the entire schematic will get pasted every time you use the hotkey
  • commandTaskInterval (previously called pasteCommandInterval) - the interval (in game ticks) between executing the paste task (basically to be able to spread out the command bursts and/or the server load)

If you need to prevent block updates while pasting (for example to not trigger redstone contraptions), then there would need to be some mod on the server that can do that. Often that is the Carpet mod, which has the fillUpdates Carpet rule to prevent block updates from /fill, /clone and /setblock commands. The command is /carpet fillUpdates false.

The World Edit paste mode can also prevent block updates, but it has more command overhead (= is slower) and it doesn't support the pasteReplaceBehavior option.

Restoring block entity NBT data on a server

The main issue with restoring NBT data on servers is that the vanilla chat messages are limited to 256 characters. So it's often not possible to send the full NBT data via a single /setblock or /summon command. Some versions of the mod (currently 1.16.5+) have an option to restore block entity NBT data when pasting via the command-based paste method that is used on servers. There is an option in Generic -> pasteNbtRestoreBehavior to control how this is done, but the only option that really makes sense and works correctly is Place & Data Modify.

What this option does, is basically:

  • First place the target block with a /setblock command like normally
  • Then do a creative Ctrl + pick block equivalent to get the full NBT data of the block to the server side via the item in the creative pick block packet
  • Find an empty position near the player, and place that "Ctrl + pick blocked" block there
  • Then send a /data modify command to the server to copy the NBT data from that "manually placed" block to the actual /setblock'd target block
  • Use a /setblock ... air command to remove that temporary, "manually placed" block

Due to these several additional operations and commands per each block with a block entity, this adds significant overhead to the paste operation. It is therefore recommended to only enable this restore option while you need to paste something that actually really needs to have the full NBT data restored, and then disable the option again afterwards.

Also note that the NBT restore will not happen for any fill regions, if you use the pasteUseFillCommand option. Which basically means that if you have any two or more adjacent identical block states that are supposed to have their data restored, then you should not paste those blocks using the fill option.

It might be a good idea to separately paste the "inventory blocks" from the rest of the schematic (at least if you have a large schematic with lots of block entities, for small-ish schematics it doesn't really matter either way, for small schematics you can just paste it all with NBT restore enabled and fill regions disabled).

  • First remove all the "inventory blocks" you want to restore the data for from the schematic using the Edit Schematic mode (schematicEditBreakPlaceAll + punch the blocks)
  • Then do the "initial paste" operation ie paste all the rest of the blocks
  • Then reload the schematic from file (Loaded Schematics -> Reload) to restore its initial state
  • Then using the option pasteReplaceBehavior = None and pasteUseFillCommand disabled, paste the schematic a second time with the pasteNbtRestoreBehavior option set to Place & Data Modify

This way only the blocks that you actually need the data restored for will use the slower and "packet spammier" paste behavior.

About the paste operation

In single player the paste operation happens in per-chunk pieces over multiple game ticks in "later" versions of the mod. In "older" versions the paste operation happened all at once, which with larger schematics caused a massive lag spike due to light updates, and also might have required a larger amount of memory allocated for the game. (That's only really an issue with schematics that are larger than something like 100x100 blocks or so with "significant coverage".)

("Later" versions here means Litematica version 1.16.5-0.0.0-dev.20210917.192300 or later for MC 1.16.5, and 0.9.0 or later for MC 1.17+, and also the 1.12.2 LiteLoader version as of 2020-03-22 or so. So the 1.13.2 - 1.16.4 mod versions released before a yet-to-happen release in 2022 or later will always paste the entire schematic in one go in single player.)

In multiplayer the paste operation always happens in per-chunk pieces, and also rate limited to a configurable command rate.

Clone this wiki locally