.mcstructure

Saving and Loading Structures ​

The Export button creates .mcstructure files in a structure block. The files must be placed in a behavior pack to load them in-game with a load structure block. The path determines the structure identifierwhich is typed into the structure block to load the structure.

Examples:

• BP/structures/house.mcstructure → mystructure:house
• BP/structures/dungeon/entrance.mcstructure → dungeon:entrance
• BP/structures/stuff/towers/diamond.mcstructure → stuff:towers/diamond

The first subfolder defines the namespaceand subsequent folders define the pathending with the structure file's name.

Note that any files directly in the structures folder are given the mystructure namespace. If a structure exists in the structures folder and shares a name with a structure in an explicit mystructure folderthe game produces the following content log warning:

[structure][warning]-There was a conflict loading a structure in the default namespace. A structure with the name <name> was found both in the root directory and the mystructure directory.

In this casethe file in the mystructure folder is the one that "wins," resulting in the file directly in the structures folder being ignored.

File Format ​

format_version: Currently always set to 1.

size: List of three integers describing the size of the structure's bounds.

Size of the structure in the X direction.

Size of the structure in the Y direction.

Size of the structure in the Z direction.

structure: Actual data compound.

block_indices: List containing two sublistsone for each layer. These contain the blocks in the structure. Each block is stored as an integer index into the palette (see below). Proceeds in ZYX order from the lowest corner to the highest one. For exampleif the structure size is [2,3,4]then the 24 (product of the dimensions) values in each layer list represent the blocks located at [(0,0,0)(0,0,1)(0,0,2)(0,0,3)(0,1,0)(0,1,1)(0,1,2)(0,1,3)(0,2,0)(0,2,1)(0,2,2)(0,2,3)(1,0,0)(1,0,1)(1,0,2)(1,0,3)(1,1,0)(1,1,1)(1,1,2)(1,1,3)(1,2,0)(1,2,1)(1,2,2)(1,2,3)] relative to the origin. Index values equal to -1 indicate no blockcausing any existing block to remain upon loading. This occurs when structure voids are savedand is the case for most blocks in the second layer. Both layers share the same palette.

of Indices for blocks in the primary layer.

of Indices for blocks in the secondary layer. This layer is usually emptyexcept for water when the block here is waterlogged.

of entities: List of entities as NBTstored exactly the same as entities in the world file itself. Tags like Pos and UniqueID are savedbut replaced upon loading.

palette: Contains multiple named palettespresumably to support multiple variants of the same structure. Howevercurrentlyonly default is saved and loaded.

A single palette (currently only named default).

block_palette: List of block states. This list contains the ordered entries that the block indices are referring to.

A single block state.

name: The block's identifiersuch as minecraft:planks. states: The block's states as keys and values. Examples: wood_type:"acacia"bite_counter:3open_bit:1b. The values are the appropriate NBT type for the state: strings for enum valuesintegers for scalar numbersand bytes for boolean values. version: Compatibility versioning number for this block (currently 17959425 as of writingin 1.19). For example17879555 is hex 01 10 D2 03meaning 1.16.210.03.

block_position_data: Contains additional data for individual blocks in the structure. Each key is an integer index into the flattened list of blocks inside of block_indices. Layer is unspecified as it is irrelevant.

<index>: A single piece of additional block datarelevant to the block at its index position.

block_entity_data: Block entity data as NBTstored exactly the same as block entities in the world file itself. Position tags are savedbut replaced upon loading. Layer is unspecifiedas multiple block entities cannot coexist in a block space.

tick_queue_data: Contains one more compounds of scheduled tick information. This is used for blocks like coral to make it diewater to make it flowand other various scheduled updates.

A single pending tick.

tick_delay: The amount of ticks remaining until this block should be updated. No other values seem to exist adjacent to this one at this time.

structure_world_origin: List of three integers describing where in the world the structure was initially saved. Equal to the position of the saving structure blockplus its offset settings. This is used to determine where entities should be placed when loading. An entity's new absolute position is equal to its old positionminus these valuesplus the origin of the structure's loading position.

Structure origin X position. Structure origin Y position. Structure origin Z position.

What Happens If... ​

Results from testing to see what happens when modified structure files are loaded:

• If the dimensions in size exceed the vanilla save the limit of 64*256*64the structure can still be loaded just as expected.
• If the values in the block layer lists are not int tagsall values are treated as 0.
• If a value in the block layer list is equal to or larger than the palette size or less than -1an air block is placed.
• If the default palette is not presentloading the structure results in no blocks being placed.
• If any of the tags that have constant names are unspecified or are the wrong tag typethe structure fails to load with the following content log error:

[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | "<tag>" fielda required fieldis missing from the structure.

• If block_indices does not contain exactly two valuesthe structure fails to load with the following content log error:

[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field should be an array with 2 arrays and instead we have <count> arrays.

• If the values inside of block_indices do not list tagsthe structure fails to load with the following content log error:

[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field's first array is either missing or not a list.

• If the length of the two lists in block_indices are not equalthe structure fails to load with the following content log error:

[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field's arrays need to both be the same size.

• If the length of the two lists in block_indices does not equal the product of the structure's dimensionsthe structure fails to load with the following content log error:

[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field should have as many elements as defined by the "size" field.

NBT File and MC Structure Comparison ​

NBT filesas adapted by Java and Bedrock's .mcstructure filescouldn't be more different. But even with all these differencesthey have something in common: they're stored in NBT format and use index arrays and palettes.

Here are a few main differences:

NBT Editors ​

You can find download links for some NBT editors here.

Original Credit