The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
This specification defines a format which describes a region of a Minecraft world for the purpose of serialization and storage of the region to disk. It is designed in order to allow maximum cross-compatibility between platforms, versions, and various states of modification.
| Version | Date | Notes |
|---|---|---|
| 1 | 2016-08-23 | Initial Version |
| 2 | 2019-05-08 | Entity and Biome support and DataVersion additions |
| 3 | 2021-05-04 | 3D Biome support Rename Palette to BlockPalette Wordsmithing varint and palette usages |
Named Binary Tag (NBT) is a binary format used by Minecraft for various files and storage of data. Its many supported types are used throughout this specification as a means of what expected tags are used, and how the data is stored using the tag type.
Resources identified by a Resource Location have an identifier string which is made up of two sections, the domain and the resource name, written as domain:name. If the domain is not specified then it is assumed to be minecraft. For example planks would identify the same resource as minecraft:planks as the minecraft: prefix is implicit. Many examples of resource locations can be found on the Minecraft wiki for Java Edition.
A Block State is an instance of a block type with a set of extra data used to further define the material or properties. The additional data varies by block type and a complete listing of vanilla types is available here. Mods can add additional block types and properties. A state is always referencable by a resource location.
A special Entity that resides at a position with a correlated blockstate. Specifically, these are instances that can have complex data contained within them and may perform various operations in the world and as a result, their data is stored separately and otherwise too complex to store as a BlockState. Examples of these include chests, furnaces, beacons, etc. where their data is specific to each position they may exist. More information on these can be read on the Minecraft wiki.
An Entity Type is a literal type of an Entity that is represented as a Resource Location. The additional data varies by entity type and a complete listing of vanilla types is available here.
An instance of an entity type that has a relative position to the origin of the schematic. Additional data is dependent on the type while vanilla optional data for entities can be found here. Mods can add extra data to any entity instance. Each entity in a Minecraft game instance is uniquely identifable through a UUID, however schematics can not be relied on to provide a UUID for the targeted entity as common Minecraft implementations will generate a new UUID for each entity spawned from a schematic.
A specific environmental aspect to a region that affects various rendering options, such as foliage coloring, rain, snow, temperature, mob spawning, and sometimes sky rendering. They do have potential physical effects based on implementation and are id'ed by ResourceLocations. More about these can be read on the Minecraft wiki.
A short explanation of the various data types used in schematics. A conversion is provided for each data type as NBT is used for storage. To find more information on how NBT tags are stored in binary format, click here.
| Specification Data Type | NBT Equivalent | Format Stored to target NBT Equivalent |
|---|---|---|
integer |
NBT Int |
No conversion |
short |
NBT Short |
No conversion |
byte |
NBT Byte |
No conversion |
long |
NBT Long |
No conversion |
float |
NBT Float |
No conversion |
double |
NBT Double |
No conversion |
unsigned short |
NBT Short |
Uses the 16 bits of the signed NBT Short to store an unsigned short. The value can be extracted to an integer in Java by using value & 0xFFFF. |
integer[] |
NBT Int Array |
No conversion |
varint[] |
NBT Byte Array |
Each integer is bitpacked with varint encoding. A Examples can be found with Sponge's implementation for retreving data and storing data. |
float[] |
NBT List of NBT Float |
Each float is stored as an NBT Float in an indexed NBT List |
double[] |
NBT List of NBT Double |
Each double is stored as an NBT Double in an indexed NBT List |
string |
NBT String |
No conversion |
string[] |
NBT List of NBT String |
No conversion |
Object |
NBT Compound |
No conversion, each object should serialize to supported types within a compound |
Object[] |
NBT List of NBT Compound |
No conversion, each Object is stored in an NBT List of NBT Compounds as indexed according to the Object[]. |
extra |
NBT Compound |
No conversion. The content of the compound is specified by Minecraft, not this format. |
The structure described by this specification is persisted to disk using the Named Binary Tag (NBT) format. Before writing to disk the NBT data must be compressed using the GZip data compression algorithm. The highly recommended file extension for files using this specification is .schem (chosen so as to not conflict with the legacy .schematic format allowing easy distinction between the two).
All field names in the specification are case sensitive.
The Schematic schema compound is nested inside the root compound, like with most of Minecraft's own data files:
{
"": {
"Schematic": {
//...
}
}
}This is the root object for the specification.
| Field Name | Type | Description |
|---|---|---|
| Version | integer |
Required. Specifies the format version being used. It may be used to provide validation and auto-conversion from older versions. The current version is 3. |
| DataVersion | integer |
Required. Specifies the data version of Minecraft that was used to create the schematic. This is to allow for block and entity data to be validated and auto-converted from older versions. This is dependent on the Minecraft version, eg. Minecraft 1.12.2's data version is 1343. |
| Metadata | Metadata Object | Provides optional metadata about the schematic. |
| Width | unsigned short |
Required. Specifies the width (the size of the area in the X-axis) of the schematic. |
| Height | unsigned short |
Required. Specifies the height (the size of the area in the Y-axis) of the schematic. |
| Length | unsigned short |
Required. Specifies the length (the size of the area in the Z-axis) of the schematic. |
| Offset | integer[3] |
Specifies the relative offset of the schematic from the paster. When pasting, if there is a reasonable location to use as a base position, implementations SHOULD offset the location of the paste by this vector. The default value if not provided is [0, 0, 0]. Example: If a player is pasting from 1, 2, 3, and the offset is 4, 5, 6, then the first block should be placed at 5, 7, 9 |
| Blocks | Block Container | Specifies Block related data such as placing BlockStates and BlockEntity instances. |
| Biomes | Biome Container | Specifies Biome related data. |
| Entities | Entity Object[] | Specifies entities to be placed in the schematic. If no additional data is provided for an entity type which normally requires extra data, then it is assumed that the Entity is initialized with all defaults. |
An object which provides optional additional meta information about the schematic. The fields outlined here are guidelines to assist with standardization but it is recommended that any program reading and writing schematics persist all fields found within this object.
| Field Name | Type | Description |
|---|---|---|
| Name | string |
The name of the schematic. |
| Author | string |
The name of the author of the schematic. |
| Date | long |
The date that this schematic was created on. This is specified as milliseconds since the Unix epoch. |
| RequiredMods | string[] |
An array of mod ids which have blocks which are referenced by this schematic's defined Palette. |
{
"Name": "My Schematic",
"Author": "Author Name",
"RequiredMods": [
"a_mod",
"another_mod"
]
}An object which holds a mapping of a resourced id to an index.
{
"minecraft:air": 0,
"minecraft:planks[variant=oak]": 1,
"a_mod:custom": 2
}The format of the BlockState identifier is the id of the block type and a set of comma-separated property key=value
pairs surrounded by square brackets. If the block has no properties then the square brackets can be omitted. The block
type id is specified as a Resource Location, for a full list of available block IDs, refer to
the particular Minecraft Java edition version of the official wiki.
For example the air block has no properties so its id representation would be just the block type id minecraft:air.
The wheat block has an integer property for the age so its id would be minecraft:wheat[age=3].
Properties ordering is nondeterministic, unknown properties for the particular game version may result in errors.
Biomes are simply referenced by their game's particular Resource Location. Due to the nature of game specific registries, it's necessary to consider that a biome may not exist between different game versions or game setups, such that a biome may only exist as part of a DataPack, or mod. A full list of available biomes for the vanilla game are available here.
| Field Pattern | Type | Description |
|---|---|---|
| {blockstate} | integer |
A single entry mapping a blockstate to an index. |
| {biome} | integer |
A single entry mapping a biome to an index |
An object which provides block based data and has particular requirements alone. Not all schematics need to consist of blocks.
| Field Name | Type | Description |
|---|---|---|
| Palette | Palette Object | Required Specifies the palette. This is a mapping of block states to indices which are local to this schematic. These indices are used to reference the block states from within the Data array. It is recommended for maximum data compression that your indices start at zero and skip no values. |
| Data | varint[] |
Required Specifies the main storage array which contains Width * Height * Length entries. Each entry is specified as a varint and refers to an index within the Palette. The entries are indexed by x + z * Width + y * Width * Length. |
| BlockEntities | BlockEntity Object[] | Specifies additional data for blocks which require extra data. If no additional data is provided for a block which normally requires extra data then it is assumed that the BlockEntity for the block is initialized to its default state. |
An object which provides biome based data and has particular requirements alone. Not all schematics need to consist of biomes.
| Field Name | Type | Description |
|---|---|---|
| Palette | Palette Object | Required Specifies the palette. This is a mapping of biomes to indices which are local to this schematic. These indices are used to reference the biomes from within the Data array. It is recommended for maximum data compression that your indices start at zero and skip no values. |
| Data | varint[] |
Required Specifies the main storage array which contains Width * Height * Length entries for Biomes at positions. Each entry is specified as a varint and refers to an index within the Palette. The entries are indexed by x + z * Width + y * Width * Length. |
An object to specify a BlockEntity which is within the region. Block entities are used by Minecraft to store additional data for a block (such as the lines of text on a sign). The fields used to describe a BlockEntity vary for each type, however the structure will be the same as used by the Minecraft Chunk Format.
| Field Pattern | Type | Description |
|---|---|---|
| Pos | integer[3] |
Required. The position of the BlockEntity relative to the [0, 0, 0] position of the schematic (without the offset applied). Must contain exactly 3 integer values. |
| Id | string |
Required. The id of the BlockEntity type defined by this BlockEntity Object, specified as a Resource Location. This should be used to identify which fields should be required for the definition of this type. |
| Data | extra |
Optional The extra information related to a BlockEntity that otherwise would define various bits of information for the BlockEntity associated by their respective types. |
An example of possible storage of a sign. See the Minecraft Chunk Format for a complete listing of data used to store various types of block entities present in vanilla minecraft. Mods may store additional data or have additional types of block entities.
{
"Pos": [0, 1, 0],
"Id": "minecraft:sign",
"Data": {
"Text1": "foo",
"Text2": "",
"Text3": "bar",
"Text4": ""
}
}An object to specify an instance of an entity type within the region. Entities usually occupy a three dimensional space within the region and have many characteristics, varied by the entity type, however the structure will be the same as used by the Minecraft Chunk Format, dependent on the Data Version the schematic is created from.
| Field Pattern | Type | Description |
|---|---|---|
| Pos | double[3] |
Required. The position of the entity relative to the [0, 0, 0] position of the schematic (without the offset applied). Must contain exactly 3 double values. |
| Id | string |
Required. The id of the entity type defined by this Entity Object, specified as a Resource Location. This should be used to identify which fields should be required for the definition of this type. |
| Data | extra |
Optional The extra information related to an Entity that otherwise is either defaulted or required by the entity associated with the entity type |
An example of possible storage of a creeper. See the Minecraft Chunk Format for a complete listing of data used to store various types of entities present in vanilla Minecraft. Mods may store additional data or have additional types of entities.
{
"Pos": [15.0043293, 68.000321, 40.452],
"Id": "minecraft:creeper",
"Data": {
"Motion": [0.00203, 0.00203, 1.000],
"Rotation": [189.30, 45],
"Fire": -20,
"NoGravity": 0,
"CustomName": "Sheep",
"CustomNameVisible": 1
}
}