Forge Blockstate V1 specs

<blockstate> == {
  "forge_marker": 1,
  "defaults": <variant>, // optional, added to all variants
  "variants": {
    "<property>": {
    "<value>": <variant> // variant definition for the specified value of this property; variants for multiple values can be specified.
  },
    "<variant name>": <variant>, // variant definition for the full variant string
    "<variant name>": [<variant1>, ...], // array of definitions for the full variant - result will be the random variant
  }
}

<variant> == {
  "model": "<model location>",
  "textures": {  // remaps the <from> texture in the model to <to>; multiple remappings can be specified
    "<from>": "<to>"
  },
  "x": <angle-90>, // vanilla rotation compatibility; only multiples of 90 degrees are supported, see vanilla specification
  "y": <angle-90>,
  "transform": <root-transform>, // transformations
  "uvlock": <bool>, // see vanilla specification
  "weight": <int>, // random weight, see vanilla specification
  // submodels: all stuff specified will be merged into the base model. If this is the root variant without the model - base will be chosen from one of the submodels.
  "submodel": "<model location>",
  "submodel": <variant>,
  "submodel": [<variant>, ...],
  "custom": { "<key>": <value> } // custom data that models can use
}

<root-transform> == <transform>

<root-transform> == {
  "thirdperson": <transform>,
  "firstperson": <transform>,
  "gui": <transform>,
  "head": <transform>,
  // or any of the <transform> keys
}

<transform> == "<builtin string>"
currently supported builtin strings:
  "identity" - identity transformation
  "forge:default-block" - default block transformation (example: stone)
  "forge:default-item" - default 2d item transformation (example: bucket)
  "forge:default-tool" - default 2d tool transformation (example: pickaxe)
This may be expanded to something more generic in the future.

<transform> == <matrix>
<transform> == { "matrix": <matrix> }

<matrix> == [
  [<number>, <number>, <number>, <number>],
  [<number>, <number>, <number>, <number>],
  [<number>, <number>, <number>, <number>]
]
4x3 matrix (3x3 affine part + translation column)

<transform> == {
  // all keys are optional
  "translation": [<number>, <number>, <number>],
  "rotation": <rotation>,
  "scale": [<number>, <number>, <number>], // per-axis scale
  "scale": <number>, // uniform scale
  "post-rotation": <rotation>
}

<rotation> == [<number>, <number>, <number>, <number>]
Quaternion(x, y, z, w)

<rotation> == {"<axis>": <number>}
Rotation around the coordinate axis, in degrees. Value is unrestricted

<rotation> == [{"<axis1>": <number>}, ...]
Composition of rotations around multiple axes, in the specified order

Lines 6 and 7 seem to have incorrect indentation.
For variants, "x" and "y" can't be set to non-90 rotations? It would be preferable to allow this, since it's much simpler than having to specify the transform tag. (also, these rotate around the center of the block and TRSRs don't, IIRC.)

Is there a better documentation of this with more examples ? I can't figure this forge out for the life of me.

It would be great to have a tutorial explain how to properly create custom transforms for inventory rendering.

This is awesome information however one thing remains unclear to me. If i have a block that has 6 Properties that are correctly synced between the block and tile entity, How do i properly implement the blockstate where each of those Properties represents a different model within the block. I've tried separate Properties and i've tried nesting them. Each of the 6 properties can be true or false meaning there are 64 possible states (although in practice 2 of those states are impossible to place in world) Thanks in advance! :D

The <variant> object can also have the property "gui3d": <bool> (same effect as IBakedModel::isGui3D) and the property "smooth_lighting": <bool> (that replaces "ambientocclusion" in vanilla models)