Blockstates definition

Blockstates definition (also known as block state model dispatch) are used to render blocks when there are several different variants of them (like doors, which can be open or closed). Each block has its own blockstates definition file, which lists all the existing variants and links them to their corresponding model. Blocks can also be composed of several different models at the same time, called "multipart". The models are then used depending on the block state of the block.

The blockstates definitions are stored as JSON files in a resource pack in the assets/<namespace>/blockstates folder.

JSON format

• [NBT Compound / JSON Object] Root object
  • [NBT Compound / JSON Object] variants: Holds the names of all the variants of the block.​^{[more information needed]}
    • [NBT Compound / JSON Object][NBT List / JSON Array] A variant: Name of a variant, which consists of the relevant block states separated by commas. A block with just one variant uses "" as a name for its variant. Each variant can have one model or an array of models and contains their properties. If set to an array, the model is chosen randomly from the options given, with each option being specified in separate subsidiary [NBT Compound / JSON Object]-tags. Item frames are treated as blocks and use "map=false" for a map-less item frame, and "map=true" for item frames with maps.
      • A single model see Template:Nbt inherit/blockstates/model/template
      • Several models see Template:Nbt inherit/blockstates/models/template
  • [NBT List / JSON Array] multipart: Used instead of variants to combine models based on block state attributes.
    • [NBT Compound / JSON Object] A case: Determines a case and the model that should apply in that case.
      • [NBT Compound / JSON Object] when: A list of cases that have to be met for the model to be applied. If unset, the model always applies.
        • [NBT List / JSON Array] OR: Matches if any of the contained cases return true. Cannot be set alongside other cases.
          • [NBT Compound / JSON Object] A condition: A list of cases that all have to match the block to return true.
            • [String] State: Name of a block state. A single case that has to match one of the block states. It can be set to a list separated by | to allow multiple values to match.
        • [NBT List / JSON Array] AND: Matches if all of the contained cases return true. Cannot be set alongside other cases.
          • [NBT Compound / JSON Object] A condition: A list of cases that all have to match the block to return true.
            • [String] State: Name of a block state. A single case that has to match one of the block states. It can be set to a list separated by | to allow multiple values to match.
        • [String] State: Name of a block state. A single case that has to match one of the block states. It can be set to a list separated by | to allow multiple values to match. Cannot be set alongside the OR or AND tag.
      • [NBT Compound / JSON Object][NBT List / JSON Array] apply: Determines the model(s) to apply and its properties. There can be one model or an array of models. If set to an array, the model is chosen randomly from the options given, with each option being specified in separate subsidiary [NBT Compound / JSON Object]-tags.
        • A single model see Template:Nbt inherit/blockstates/model/template
        • Several models see Template:Nbt inherit/blockstates/models/template

"uvlock": true	"uvlock": false

History

Java Edition
1.8			14w10a				Added first blockstates definitions into the assets/<namespace>/models/block folder. They come with a warning that this format is unstable and highly likely to change even more in the future.
			14w25a				Moved assets/<namespace>/models/block to assets/<namespace>/blockstates.
			14w27a				Format change to the current one.​[more information needed]
			14w28a				Blockstates definition are no longer considered unstable.
1.21.11			25w46a				New optional field z for rotate the model of a variant.