BlockState JSONs

Blockstate JSONs are Minecraft’s way to map “variant strings” to models. A variant string can be absolutely anything, from “inventory” to “power=5” to “I am your father.” They represent an actual model, where the blockstate is just a container for them. In code, a variant string within a blockstate JSON is represented by a ModelResourceLocation.

When the game searches for a model corresponding to a block in the world, it takes the blockstate for that position, and then it uses a map within ModelManager to find the corresponding ModelResourceLocation for it, which then refers to the actual model. BlockModelShapes uses the block's registry name as the location of the blockstate JSON. (E.g. block examplemod:testblock goes to the ResourceLocation examplemod:testblock.) The variant string is pieced together from the BlockState's properties.

As an example, let’s take a look at the vanilla oak_log.json:

{
  "variants": {
    "axis=y": { "model": "block/oak_log" },
    "axis=z": { "model": "block/oak_log", "x": 90 },
    "axis=x": { "model": "block/oak_log", "x": 90, "y": 90 }
  }
}

Here we define three variant strings, and for each we use a certain model, either the upright log and the sideways log (rotated in the y direction or not). These variants will define the look of a log depending on the property `axis`.

A blockstate always has to be defined for all possible variant strings. When you have many properties, this results in lots of possible variants, as every combination of properties must be defined. There is also a "multipart" format that can be used to simplify defining a model separately for every single state like so:

{ 
  "when": { "east": "true" },
  "apply": { "model": "oak_fence_side", "y": 90, "uvlock": true }
}

This is one case of five. You can read this as “when east is true, use the model oak_fence_side rotated 90 degrees”. This allows the final model to be built up from five smaller parts, four of which (the connections) are conditional and the fifth being the unconditional central post. This uses only two models, one for the post, and one for the side connection.