Blocks: Block Models

.vitepress/sidebars/develop.ts

@@ -116,6 +116,10 @@ export default [
         text: "develop.blocks.first-block",
         link: "/develop/blocks/first-block",
       },
+      {
+        text: "develop.blocks.block-models",
+        link: "/develop/blocks/block-models",
+      },
       {
         text: "develop.blocks.blockstates",
         link: "/develop/blocks/blockstates",

develop/blocks/block-models.md

@@ -0,0 +1,126 @@
+---
+title: Block Models
+description: A guide to writing and understanding block models.
+authors:
+  - Fellteros
+  - its-miroma
+---
+
+<!-- markdownlint-disable search-replace -->
+
+This page will guide you through writing your own block models and understanding all their options and possibilities.
+
+## What Are Block Models? {#what-are-block-models}
+
+Block models are essentially the definition of a block's looks and visuals. They specify a texture, model translation, rotation, scale and other attributes.
+
+Models are stored as JSON files in your `resources` folder.
+
+## File Structure {#file-structure}
+
+Every block model file has a defined structure that has to be followed. It starts with empty curly brackets, which represent the **root tag** of the model. Here's a brief scheme of how block models are structured:
+
+```json
+{
+  "parent": "...",
+  "ambientocclusion": "true/false",
+  "display": {
+    "<position>": {
+      "rotation": [0.0, 0.0, 0.0],
+      "translation": [0.0, 0.0, 0.0],
+      "scale": [0.0, 0.0, 0.0]
+    }
+  },
+  "textures": {
+    "particle": "...",
+    "<texture_variable>": "..."
+  },
+  "elements": [
+    {
+      "from": [0.0, 0.0, 0.0],
+      "to": [0.0, 0.0, 0.0],
+      "rotation": {
+        "origin": [0.0, 0.0, 0.0],
+        "axis": "...",
+        "angle": "...",
+        "rescale": "true/false"
+      },
+      "shade": "true/false",
+      "light_emission": "...",
+      "faces": {
+        "<key>": {
+          "uv": [0, 0, 0, 0],
+          "texture": "...",
+          "cullface": "...",
+          "rotation": "...",
+          "tintindex": "..."
+        }
+      }
+    }
+  ]
+}
+```
+
+<!--@include: ..\items\item-models.md#parent-->
+
+Set this tag to `builtin/generated` to use a model created from the specified icon. Rotation can be achieved via [blockstates](./blockstates).
+
+### Ambient Occlusion {#ambient-occlusion}
+
+````json
+{
+  "ambientocclusion": "true/false"
+}
+````
+
+This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/wiki/Ambient_occlusion). Defaults to `true`.
+
+<!--@include: ..\items\item-models.md#display-->
+
+### Textures {#textures}
+
+```json
+{
+  "textures": {
+    "particle": "...",
+    "<texture_variable>": "..."
+  }
+}
+```
+
+The `textures` tag holds the textures of the model, in the form of an identifier or a texture variable. It contains three additional objects:
+
+1. `particle`: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as `#particle`.
+2. `<texture_variable>`: _String_. Creates a variable and assigns a texture. Can be later referenced with the `#` prefix (e.g., `"top": "namespace:path"` ⇒ `#top`)
+
+<!--@include: ..\items\item-models.md#elements-->
+
+<!--@include: ..\items\item-models.md#from-->
+
+`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
+The values of both must be between **-16** and **32**, which means that every block model can be at most 3×3 blocks big.
+
+<!--@include: ..\items\item-models.md#rotation-->
+
+`rotation` defines the rotation of an element. It contains four more values:
+
+1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
+2. `axis`: _String_. Specifies the direction of rotation, and must be one of these: `x`, `y` and `z`.
+3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45**.
+4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
+
+<!--@include: ..\items\item-models.md#shade-to-faces-->
+
+1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
+  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
+2. `texture`: _String_. Specifies the texture of the face in the form of a [texture variable](#textures), prepended with `#`.
+3. `cullface`: _String_. Can be: `down`, `up`, `north`, `south`, `west`, or `east`. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
+It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
+4. `rotation`: _Integer_. Rotates the texture clockwise by the specified number of degrees in 90 degree increments. Rotation does not affect which part of the texture is used.
+Instead, it amounts to permutation of the selected texture vertices (selected implicitly, or explicitly though `uv`).
+5. `tintidex`: _Integer_. Tints the texture on that face using a tint value. The default value, `-1`, indicates not to use the tint.
+Any other number is provided to `BlockColors` to get the tint value corresponding to that index (returns white when the block doesn't have a tint index defined).
+
+## Sources and Links {#sources-and-links}
+
+You can visit Minecraft Wiki's [Block Models page](https://minecraft.wiki/w/Model#Block_models) for a more detailed walkthrough. A lot of information here is from that page.

develop/items/item-models.md

@@ -3,9 +3,12 @@ title: Item Models
 description: A guide to writing and understanding item models.
 authors:
   - Fellteros
+  - its-miroma
   - VatinMc
 ---
 
+<!-- markdownlint-disable search-replace -->
+
 This page will guide you through writing your own item models and understanding all their options and possibilities.
 
 ## What Are Item Models? {#what-are-item-models}
@@ -47,7 +50,7 @@ Every item model file has a defined structure that has to be followed. It starts
       "shade": "true/false",
       "light_emission": "...",
       "faces": {
-        "<face>": {
+        "<key>": {
           "uv": [0, 0, 0, 0],
           "texture": "...",
           "cullface": "...",
@@ -60,6 +63,8 @@ Every item model file has a defined structure that has to be followed. It starts
 }
 ```
 
+<!-- #region parent -->
+
 ### Parent {#parent}
 
 ```json
@@ -70,8 +75,12 @@ Every item model file has a defined structure that has to be followed. It starts
 
 Loads a different model with all its attributes from the given path, as an identifier (`namespace:path`).
 
+<!-- #endregion parent -->
+
 Set this tag to `item/generated` to use a model created from the specified icon, or set it to `builtin/generated` to use the model without any translation, rotation, or scaling.
 
+<!-- #region display -->
+
 ### Display {#display}
 
 ```json
@@ -111,9 +120,11 @@ Furthermore, each position can contain these three values, in the form of an arr
 }
 ```
 
-1. `rotation`: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
-2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
-3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
+1. `rotation`: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
+2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
+3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
+
+<!-- #endregion display -->
 
 ### Textures {#textures}
 
@@ -147,6 +158,8 @@ The `textures` tag holds the textures of the model, in the form of an identifier
 
 This tag defines the direction from which the item model is illuminated. Can be either `front` or `side`, with the latter being the default. If set to `front`, the model is rendered like a flat item, if set `side`, the item is rendered like a block.
 
+<!-- #region elements -->
+
 ### Elements {#elements}
 
 ```json
@@ -177,7 +190,11 @@ This tag defines the direction from which the item model is illuminated. Can be
 }
 ```
 
-Contains all the elements of the model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
+Contains all elements of a model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
+
+<!-- #endregion elements -->
+
+<!-- #region from -->
 
 ```json
 {
@@ -186,9 +203,13 @@ Contains all the elements of the model, which can only be cubic. If both `parent
 }
 ```
 
-`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
+<!-- #endregion from -->
+
+`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
 The values of both must be between **-16** and **32**, which means that every item model can be at most 3×3 blocks big.
 
+<!-- #region rotation -->
+
 ```json
 {
   "rotation": {
@@ -200,13 +221,17 @@ The values of both must be between **-16** and **32**, which means that every it
 }
 ```
 
+<!-- #endregion rotation -->
+
 `rotation` defines the rotation of an element. It contains four more values:
 
-1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
+1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y z]`.
 2. `axis`: _String_. Specifies the direction of rotation, and must be one of these: `x`, `y` and `z`.
 3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45** in 22.5 degree increments.
 4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
 
+<!-- #region shade-to-faces -->
+
 ```json
 {
   "shade": "true/false"
@@ -226,7 +251,7 @@ The values of both must be between **-16** and **32**, which means that every it
 ```json
 {
   "faces": {
-    "<face>": {
+    "<key>": {
       "uv": [0, 0, 0, 0],
       "texture": "...",
       "cullface": "...",
@@ -237,10 +262,12 @@ The values of both must be between **-16** and **32**, which means that every it
 }
 ```
 
-`faces` holds all the faces of the cuboid. If a face is not set, it will not be rendered. Its keys can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each keys contains the properties for that face:
+`faces` holds all faces of a cuboid. If a face is not set, it will not be rendered. Its keys (`<key>`) can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each key contains the properties for that face:
+
+<!-- #endregion shade-to-faces -->
 
-1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
-  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
+1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
+  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
 2. `texture`: _String_. Specifies the texture of the face in the form of a [texture variable](#textures), prepended with `#`.
 3. `cullface`: _String_. Can be: `down`, `up`, `north`, `south`, `west`, or `east`. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
   It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.

sidebar_translations.json

@@ -35,6 +35,7 @@
   "develop.items.custom-data-components": "Custom Data Components",
   "develop.blocks": "Blocks",
   "develop.blocks.first-block": "Creating Your First Block",
+  "develop.blocks.block-models": "Block Models",
   "develop.blocks.blockstates": "Block States",
   "develop.blocks.block-entities": "Block Entities",
   "develop.blocks.block-entity-renderer": "Block Entity Renderers",