Friday, 26 December 2014

Block Models - texturing quads (faces)

The Block Models used by Minecraft rely on textured quads.  The texturing follows a relatively straightforward system, although it can be tricky to get it right.

If you just have a simple model, you can do it manually using the instructions below.
Alternatively, you can use a program to help you create Block Models, such as BDcraft Cubik.

The model file below produces a cube with six faces numbered 0 to 5.  In the diagram below, the red block points south (zpos) and the blue block points east (xpos).

  "parent": "block/cube",
  "textures": {
       "down": "minecraftbyexample:blocks/mbe01_block_simple_face0",
         "up": "minecraftbyexample:blocks/mbe01_block_simple_face1",
      "north": "minecraftbyexample:blocks/mbe01_block_simple_face2",
      "south": "minecraftbyexample:blocks/mbe01_block_simple_face3",
       "west": "minecraftbyexample:blocks/mbe01_block_simple_face4",
       "east": "minecraftbyexample:blocks/mbe01_block_simple_face5",
   "particle": "blocks/lapis_block"

The numbered cube produced by the mbe01_block_simple_model.json file above.  The red block points south (Z pos), the blue block points east (X pos).

Points to note:
  •  The faces always render with the same as the texture when you are looking directly at the face, i.e. the texture is never mirror imaged.
  • On the side faces, the texture is always facing up.
  • The texture on the top face (up, YPos) points north- if you are facing north and looking down, the face will have the same orientation as the texture.
  • The texture on the bottom face points south- if you are facing south and looking up, the face will have the same orientation as the texture. 

Texturing using the UV fields

The UV field used by each face has the format [U1, V1, U2, V2].  These are always oriented to the texture such that [0,0] is the top left (i.e. V is "upside down") corner.  However, because the direction of the face is different, sometimes U1 corresponds to the maximum x value, sometimes to the minimum x value.  This makes it pretty hard to get right in your head.  The picture below shows a summary of how the texture coordinates line up with the [x,y,z] coordinates for each face.  The cuboid was created using the JSON excerpt below.

Mapping of the textures onto each face, showing how the x,y,z axes are mapped on each face.

from test_numbered_part_model.json:
  "elements": [
    {  "from": [0, 0, 0],
       "to": [15, 9, 12],
       "faces": {
         "down": {"uv": [ 0, 4, 15, 16], "texture": "#down"},
         "up": {"uv": [ 0, 0, 15, 12], "texture": "#up"},
         "north": {"uv": [ 1, 7, 16, 16], "texture": "#north"},
         "south": {"uv": [ 0, 7, 15, 16], "texture": "#south"},
         "west": {"uv": [ 0, 7, 12, 16], "texture": "#west"},
         "east": {"uv": [ 4, 7, 16, 16], "texture": "#east"}

If you want to flip the texture left <--> right, then swap the position of u1 and u2.  For example,
 "west":  { "uv": [ 0, 0, 16, 16], "texture": "#west"},
 "west":  { "uv": [16, 0,  0, 16], "texture": "#west"},
Likewise, if you want to flip top <-->bottom, swap v1 and v2, eg
 "west":  { "uv": [0,  0, 16, 16], "texture": "#west"},
 "west":  { "uv": [0, 16, 16,  0], "texture": "#west"},
Basically this boils down to the fact that making model files by hand leads to serious head damage. To lessen the pain for myself, I wrote a simple excel spreadsheet to take a cuboid defined by "from" and "to" and create the corresponding UV coordinates.  You can find it here.  Probably easier just to use a program like BDcraft Cubik instead.


  1. How to explain negative value in "from" and "to" fields (e.g in template_torch_wall)? Is the texture is repeated, because in both fields contains negative value.


  2. Good god top left is 0.0 you don't know how much this random dude thanks you for this info!