How To: Choosing the Right Layer(s)

Intro

With Vanilla Minecraft JSON models, the texture blending mode (solid, cutout, cutout-mipped or translucent) is determined for the entire model by the type of block. JMX, thanks to the Fabric Rendering API, allows every quad to be assigned a different "layer" that overrides the block-level mode.

Developer Notes: In the Fabric view of the Minecraft source code, what JMX calls "layer" is known as BlockRenderLayer. In the Rendering API it is set via MaterialFinder.blendMode().

Layer Choices

Minecraft offers four layers to choose from, described in the table below.

Layer	Alpha Channel Effect	Use For
solid	Ignored	Faces that are fully opaque, with no holes or translucency.
cutout	Sprite pixels with alpha < 0.5 are not rendered. ("cut out")	Faces with visible holes. The visible and clear areas should ideally be at least 2 pixels wide and have clean lines.
cutout_mipped	Sprite pixels with alpha < 0.5 are not rendered. ("cut out")	Faces with visible holes. Use when the visible or clear areas are small (1 pixel) and/or irregular. This will prevent "moire" effects.
translucent	Sprite pixels are blended with background to appear translucent. Alpha = 0 is invisible, and alpha = 1 appears fully opaque solid, with values in between appearing more or less opaque.	Stained or cloudy glass, faces that look like fluids, ice, etc. Has a minor performance penalty - avoid on terrain and primary building blocks.

Further Reading

• Alpha What?: For a brief explanation of alpha channel, consult this article. (quora.com)

• Moire? Mipmap?: Wikipedia has the answers.

• Cutout or translucent sprites look bad? Maybe this will help. (adriancourreges.com)

Double-Layer Combinations

JMX enables faces with two sprites and each sprite can have a different layer. This is useful for overlay and partial emissive effects. More information on this feature is available here.

The table below shows which layer combinations work and what they are useful for.

First Layer	Second Layer	Use For
solid	solid	Useless. The second layer will Z-fight with the first layer, or the first layer won't be visible at all.
solid	cutout or cutout_mipped	Avoid in jmx material definitions. Renders properly in Canvas but will Z-fight with the Indigo default renderer. Is OK in frex material definitions because those will only be used when Canvas is present.
solid	translucent	This is the most versatile and reliable option but has a minor performance penalty in the Indigo renderer because of the sorting and extra draw calls needed for translucency. In jmx materials: Use for accent blocks. Avoid for common terrain blocks and primary building blocks. In frex materials: Generally the best option - this combination has no performance penalty running on Canvas.
cutout or cutout_mipped	solid	Useless. The layers will Z-fight or the first layer won't be visible at all.
cutout or cutout_mipped	cutout or cutout_mipped	Works well on any renderer with better performance than translucent but requires special texture preparation to avoid Z-fighting and does not permit blended effects.
cutout or cutout_mipped	translucent	Works but generally not as reliable and versatile as translucent/translucent. Has the same minor performance penalty associated with a single-layer translucent quad.
translucent	solid	Useless. The first layer won't be visible at all (Canvas) or it will render the same as solid/translucent (Indigo).
translucent	cutout or cutout_mipped	Avoid. May work using Canvas but will (probably) render the same as cutout/translucent using Indigo.
translucent	translucent	Another versatile and reliable choice. Works on any renderer. Has the same minor performance penalty associated with a single-layer translucent quad, except this penalty is doubled using Indigo. (Because Indigo actually does render two separate quads.)