-
Notifications
You must be signed in to change notification settings - Fork 7
Reference: JMX Specification
NOTE: You should already be familiar with the un-modded Minecraft JSON model format before trying to create JMX model files. You can find more information on the Gamepedia Minecraft Wiki.
The jmx
root-level tag defines textures and materials that should be used when JMX is loaded. It will not be used if a frex
tag is present and a FREX renderer (i.e. Canvas) is active.
"jmx": {
"textures": { },
"materials": { }
}
The frex
root-level tag defines textures and materials that should be used when a FREX renderer (i.e. Canvas) is active. When present and active, it overrides the jmx
tag.
A frex
block allows models to use different textures and material properties when shaders are available. Such models should still define a still-enhanced-but-without-shaders appearance in the jmx
block to be used when shaders aren't available.
This "override" behavior only applies within the same JSON file. Texture and material names within the frex
block can reference texture and material names provided via jmx
blocks in other JSON model files (or even vanilla models for texture names.)
"frex": {
"textures": { },
"materials": { }
}
Textures are included in the jmx
or frex
elements via the textures
tag. Usage of this tag is similar to textures for vanilla model JSON files. However, the textures are only available and applied only when JMX is loaded. Additionally, the special tag layered_textures
can be used to apply textures to a certain sprite layer.
The layered_textures
tag should contain an array of objects. Each object in the array has the same format as a regular textures
object, but the textures defined within are adapted by JMX to match up with the given sprite layer.
If jmx
and frex
elements are both present, only one of them will be loaded. If a FREX-compliant renderer is active, the frex
textures will be used. Otherwise the textures in the jmx
element will apply.
Note that a vanilla textures
element at the root level is not overriden by the jmx
and frex
blocks. This avoids compatibility problems with parent/child vanilla models that may still depend on the vanilla textures. For this reason, texture variable names within a block (names that are meant to be used with a # prefix) should be different from their vanilla counterparts.
Materials operate much like textures, but instead define a RenderMaterial to be associated with one or more faces.
Like textures, a materials
element can occur inside both the jmx
and frex
elements. When a FREX renderer is active, the materials in the frex
element will be used instead of the materials inside the jmx
element.
A material value can be defined three ways:
As with textures, materials can reference material variables to be defined in a child model, using the #
prefix.
"materials": {
"jmx_mat_down": "#jmx_mat_all",
"jmx_mat_up": "#jmx_mat_all",
"jmx_mat_north": "#jmx_mat_all",
"jmx_mat_east": "#jmx_mat_all",
"jmx_mat_south": "#jmx_mat_all",
"jmx_mat_west": "#jmx_mat_all"
}
Material attributes can be directly specified within a sub-element. The name of the sub-element will be used to resolve symbolic material names.
"materials": {
"jmx_mat_all": {
"layers": [
{ "layer": "cutout_mipped" },
{ "layer": "cutout_mipped", "emissive": true, "ambient_occlusion": false, "diffuse": false }
]
}
}
The material attributes that can be specified are listed below. If an attribute is omitted, the default value will be used.
Attribute Name | Default Value | Description |
---|---|---|
layers |
(none) | List of material layer attribute objects. |
depth |
length of layers array, 0 if layers is not present. |
Defines the number of sprite layers. Can be larger than the size of layers . |
tag |
0 | Can be used to identify quads or carry other information. Useful when the quad is meant to transformed or filtered by a mod. |
preset |
(none) | See the following section on "Named Materials." |
The material layer attributes that can be specified are listed below. If an attribute is omitted, the default value will be used.
Attribute Name | Default Value | Description |
---|---|---|
layer |
solid |
Render layer for this sprite. See Choosing the Right Layer(s) for more info. |
emissive |
false | When true, sprite texture and color will be rendered at full brightness. |
ambient_occlusion |
determined by model | When true, sprite color will be modified for ambient occlusion shading. |
diffuse |
determined by shade attribute |
When true, sprite color will be modified for diffuse shading. |
colorIndex |
true | When true, sprite color will be affected by the quad's color index. (If the color index is some value other than -1.) |
color |
true | Values other than 0xFFFFFFFF modify the sprite color. The effect is in addition to any tinting done via quad color index. Colors must be in ARGB order and can be signed integers or hex values that begin with 0x . |
Technical Note: In the Fabric Renderer API
color
andtag
are not attributes of a render material but are instead part of the quad itself. JMX represents colors and tags as part of a material so they can be easily included in material inheritance.
"materials": {
"jmx_mat_all": { "preset": "jmx:redstone" }
}
The preset
tag causes JMX to look for a named render material that is pre-registered by the active renderer or by another mod.
If a named material is found, it will override all other material settings except color
and tag
.
Presets are useful for shader-based materials in the Canvas Render. FREX provides a material loader that can create named, custom shader materials without Java code. For more information, see: How To: Create Named Shader Materials with JSON Files
JMX introduces new tags that can be included in a model face element.
{
"parent": "minecraft:block/block",
"elements": [
{
"from": [ 0, 0, 0 ],
"to": [ 16, 16, 16 ],
"faces": {
"down": {
"texture": "#down",
"cullface": "down",
"jmx_material": "#jmx_mat_down",
"layered_textures": [ { "jmx_tex": "#jmx_tex_down" }, { "jmx_tex": "#jmx_tex_down" } ]
},
"up": {
"texture": "#up",
"cullface": "up",
"jmx_material": "#jmx_mat_up",
"layered_textures": [ { "jmx_tex": "#jmx_tex_up" }, { "jmx_tex": "#jmx_tex_up" } ]
},
"north": {
"texture": "#north",
"cullface": "north",
"jmx_material": "#jmx_mat_north",
"layered_textures": [ { "jmx_tex": "#jmx_tex_north" }, { "jmx_tex": "#jmx_tex_north" } ]
},
"south": {
"texture": "#south",
"cullface": "south",
"jmx_material": "#jmx_mat_south",
"layered_textures": [ { "jmx_tex": "#jmx_tex_south" }, { "jmx_tex": "#jmx_tex_south" } ]
},
"west": {
"texture": "#west",
"cullface": "west",
"jmx_material": "#jmx_mat_west",
"layered_textures": [ { "jmx_tex": "#jmx_tex_west" }, { "jmx_tex": "#jmx_tex_west" } ]
},
"east": {
"texture": "#east",
"cullface": "east",
"jmx_material": "#jmx_mat_east",
"layered_textures": [ { "jmx_tex": "#jmx_tex_east" }, { "jmx_tex": "#jmx_tex_east" } ]
}
}
}
]
}
The tags and their meaning are as follows.
Tag | Description |
---|---|
layered_textures |
An array of JMX texture data objects. If not present, the vanilla texture attribute will be used instead. |
jmx_material |
Reference to a material variable defined in a materials element. Must be prefixed with a # . |
The JMX texture data format is defined below.
Tag | Description |
---|---|
jmx_tex |
Reference to a texture variable defined in a textures element. Must be prefixed with a # . |
jmx_uv_rot |
Defines non-locked UV texture coordinates and/or texture rotation for the current sprite layer. Value must be an new element, enclosed by curly braces ( { } ), that contains a uv array, a rotation value, or both. The uv and rotation tags work the same as they normally do within a vanilla face element, except they apply only to the current sprite layer. |