Skip to content

Basic Operations

Jump to bottom
hound22 edited this page Dec 1, 2023 · 3 revisions

Saving Schematics

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.

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.

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.

Placing Schematics

Inorder to display any of the Litematica schematic and have a 'blueprint' of that schematic in your world, you need to make a Schematic Placement for it.

To do that, open Litematica Menu with M and click on 'Load Schematics'. load 1

This will open the schematic browser. Select the schematic you want to make a placement for and click the 'Load Schematic' button. Make sure the 'Create a placement' checkbox is checked, this ensures that a schematic placement will be made automatically when the schematic is loaded. load 2

If the 'Create a placement' checkbox was not checked, then head back to the Litematica Menu and click on 'Loaded Schematics'. load 3

In the Manage Loaded Schematics browser, select the loaded schematic and click on 'Create a placement' button to make a placement for it. load 4

Editing Schematics

NOTE: The Edit Schematic mode was previously (and still is in some versions of the mod, for 1.17.0 or older) called Schematic Rebuild mode. it was renamed because lots of people used that mode while trying to build ("rebuild?") the schematic in the world.

To start, change to the Edit Schematic mode (either using the button in the bottom left of the Litematica main menu M, or Ctrl + scrolling while holding the "tool item").

When you are finished, change out of the Edit Schematic mode, as otherwise if you try to place or break blocks intersecting the schematic you will just keep editing the schematic instead!

Change a block type to another block, while keeping any block state properties

  1. Set a hotkey for schematicEditReplaceBlock
  2. Hold that hotkey and right click on one of the blocks you want to replace, while holding the new block in your hand
  3. Note: This hotkey was added a lot later than schematicEditReplaceAll, in one of the mod versions for MC 1.18.0. It's not in older versions of the mod, before the "big rewrite" brings it to older MC versions as well.

Change all identical block states to another block state (a 1:1 block state replacement)

  1. Set a hotkey for schematicEditReplaceAll.
  2. Hold that hotkey and right click on one of the blocks you want to replace, while holding the new block in your hand.
  3. Also see Getting the correct block state below for how to use blocks that you can't directly place in the correct state.

Remove everything except one block from the schematic

  1. Set a hotkey for schematicEditBreakAllExcept.
  2. Hold that hotkey and punch one of the blocks you want to keep in the schematic. All other blocks will get removed.

Add, remove or change individual blocks or blocks in lines/rows

  1. To remove blocks, just punch them out like in creative mode.
  2. To add blocks, just place them against other existing schematic blocks.
  3. To change blocks in continuous lines/rows, set a hotkey for schematicEditReplaceDirection, and then hold that key while right clicking on the old block either holding the new block or with an empty main hand (see Getting the correct block state).
  4. To remove blocks in continuous lines/rows, set a hotkey for schematicEditBreakPlaceDirection, and then hold that key while punching or placing the block.

Remove all identical blocks from the schematic

  1. Set a hotkey for schematicEditBreakPlaceAll.
  2. Hold that hotkey while punching out one of the blocks in the schematic you want to remove all of.

Fill all air spaces in the schematic with a given block

  1. Set a hotkey for schematicEditBreakPlaceAll.
  2. Hold the above hotkey and place the new block against an existing block in the schematic.

About the schematicEdit*Direction hotkeys

The 5-way overlay is like an arrow indicating in which direction the blocks in the schematic will get affected. The center region "points in" perpendicular to the surface. The operations only happen along that line of blocks for as long as there are identical block states in the schematic.

Getting the correct block state

  • When you are replacing blocks by right clicking with the new block/item, the block state that will be used depends on where you click in the schematic.
  • The new block will be selected using the same rules as how blocks are placed in vanilla.
  • For example to get a bottom slab, you must click on the bottom half of the side of a block, or on the top surface of a block. To get a top slab or stair, you must click on the top half of the side of the block, or on the bottom surface of the block.
  • The confusing part may be that instead of placing the block next to what you are clicking in the schematic, the block will replace that block (and all other identical blocks if you are using the schematicEditReplaceAll hotkey).
  • It's not possible to get the correct block state of all blocks like this, if the block you get from placing it normally is not the correct state. For example you can't get opened trap doors or any waterlogged blocks or fences with the correct connections etc. like this.
  • You can use any block state such as waterlogged blocks or open trapdoors by "preparing it in the world" first:
    • First normally place the block in the world in the correct state (with any surrounding blocks etc. if it connects to neighbor blocks).
    • Then Alt + middle click (using the default hotkey assignments) while looking at that block to "store" that block state in the Edit Schematic mode.
    • You can then use an empty main hand in any of the edit operations to use that stored block state
    • The name of the stored block is shown on the tool HUD in the bottom left when you have an empty main hand and a block stored.

Saving the edited schematic

  • When you do any of these schematic edit operations, they only affect the copy of the schematic that is currently loaded to memory.
  • The latest versions of the mod on 1.16.5+ (and in 1.12.2) have an indicator in the Loaded Schematics menu for edited, unsaved schematics.
  • If you want to keep the changes, save the schematic again from the Loaded Schematics list, using the Save to file button.
  • Don't override the original file when saving! Some (older) versions of the mod have a bug in the schematic block container handling that can corrupt the edited schematic in certain cases when it's reloaded from file (it depends on the number of unique block states in a given sub-region in the schematic before and after the edit operation).
  • Some versions of the mod based on newer code base (as of writing this only the 1.12.2 LiteLoader version) also give you an option to update the dependent placement(s) to point to the newly saved schematic, when you save an edited schematic to a new file.

Other tips

  • You can use the Render Layers to limit the range in which the blocks get added/removed/replaced. Only currently visible blocks are affected.
  • If you make a mistake or want to otherwise revert all the changes to the edited schematic, click the Reload button in the Loaded Schematics list.
  • The replacement currently always uses the exact full block state. There will be a "fuzzy replace" option later that allows you to replace a block type in any state with an (equivalent?) other block while keeping the properties (like stair orientations and connections when changing the stair type).

Schematic Pasting

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

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