This page is about the JSON required to define a material. For the JSON to make the material craftable, see Material Recipes.

See also Stat Types for the formats for different stat types supported by materials.

Materials require three basic components to define: definition, stats, and traits. The Material ID is determined by the name of each of the files.

Variants

Materials in recipes often support specifying material variants instead of material IDs. Material variants have the same definition, stats, and traits as the original material, but may have different display names, colors, textures, and recipes.

A material variant may either be expressed as a standard <domain>:<name> resource location representing a material ID with no variant, or can be expressed as <domain>:<name>#<variant> representing a material with ID <domain>:<name> and variant <variant>.

Most material recipes support specifying a material variant as the output. When used as a recipe input, a material variant of the form <domain>:<name>#<variant> will only match if the variants are equal. A material variant of the form <domain>:<name> will match any variant of that material. Sometimes, it is desirable to match a material ID with no variant as an input, which can be expressed using a material variant of <domain>:<name>#default (note this also matches the variant of default, but that variant name is discouraged from usage).

Definition

Can datagen using AbstractMaterialDataProvider.

Material definitions cause the material to be available in material lists, such as creative tabs and the books. They also allow the material to be craftable in some recipes, though the majority of recipes are defined separately. Definitions are the only part of the main material format that is conditional, other resources such as stats or traits are simply unused if the definition is disabled.

The material definition for <domain>:<name> will be located at data/<domain>/tinkering/materials/definition/<name>.json (since 1.18) or data/<domain>/materials/definition/<name>.json (in 1.16). They have the following format:

  • (Object): The root object.
    • condition (Condition): Condition that must pass for the material to be loaded. If unset, the material is loaded unconditionally.
    • craftable (Boolean): If true, this material is allowed to be crafted in the part builder. If false (default), the material may only be crafted by other means.
    • tier (Integer): Material tier. Used primarily for sorting, but has some other functions. See tiers for more info.
    • sortOrder (Integer): Sort order within the tier. See sort orders for common values.
    • hidden (Boolean): If true, this material is not shown in the book or as part of material items, though it may still show in crafting blocks. If false (default), the material is shown in all applicable lists.
    • redirect (Array): List of conditional redirects. The first redirect from the list that passes will cause the material ID to redirect to another material ID before stats or traits are processed.
      • (Object): A redirect object.
        • redirect (Material ID): If the condition passes, the material will be redirected to this ID.
        • condition (Condition): If this condition passes, the material will be redirect. If unset, the material will redirect unconditionally, useful for renaming or removing a material.

Tiers

Tiers can be defined as part of the material definition. In addition to determining sort order, they also define the books that display the material. While not enforced, the tier is used to determine how the material is gated, along with the general stat level of the material.

Tier Book Vanilla Baseline Crafting
1 Materials and You Wood
Stone		 Materials that require only the part builder to craft.
2 Puny Smelting Iron Materials that require melting and casting to create.

Some Nether or End only part builder materials are in tier 2.
3 Mighty Smelting Diamond Materials that require alloys to create.

Some Nether or End only melting and casting materials are in tier 3.
4 (Blazing Blood) Fantastic Foundry Netherite Materials that require blazing blood to create.
4 (Soul Forge) Unnamed book Netherite Materials that require the soul forge to create.

Not yet implemented in the mod.
5 Unnamed book Netherite+ Materials in this tier represent the pinacle of the material list, requiring combining several crafting methods and using end exclusive components.

Not yet implemented in the mod.

Sort orders

While not required, materials typically follow some conventions for their sorting:

Group Sort Order Description
General 0 Materials with a melee/harvest type of general.
Harvest 1 Materials with a melee/harvest type of harvest.
Melee 2 Materials with a melee/harvest type of melee.
Special 3 Materials with a melee/harvest type of special.
Ranged 4 Materials that are ranged exclusive.
Compat 5 Materials that are only added if a common metal is added.
Nether +10 Materials that require nether access. Add to a previous category.
End +15 Materials that require end access. Add to a previous category.
Binding 20 Materials that are binding or bowstring only.
Crafting 25 Materials that are just used for crafting.

Stats

Can datagen using AbstractMaterialStatsDataProvider.

Material stats have two functions. The first is the obvious function, it sets the stats when using the material for that stat type. The second function is making a material available to any material items or tool parts that use that stat type.

The material stats for <domain>:<name> will be located at data/<domain>/tinkering/materials/stats/<name>.json (since 1.18) or data/<domain>/materials/stats/<name>.json (in 1.16). They have the following format:

  • (Object): The root object.
    • stats (Object): Object containing all stats. Keys in this object are stat type IDs, while the values have a format based on the type.
      • <domain>:<name> (Object): Defines the stats for the type <domain>:<name>. Format is defined by the stat type.
      • <domain>:<name> (Null): Removes the stats for the type <domain>:<name>.

Merging

Material stats support merging across different data packs on the level of the stat types. This means both that an addon can provide new stats for an existing material type, and a modpack can modify specific stat values for a material without needing to override the rest.

Example:

The following material stats exists in the first data pack:

{
    "stats": {
        "example:type1": { "field_a": 1, "field_b": 2 }
        "example:type2": { "field_c": 3 }
    }
}

along with the following material stats in the second data pack:

{
    "stats": {
        "example:type_1": { "field_b": 4 }
        "example:type_2": null,
        "example:type_3": {}
    }
}

Together, they are equivalent to the following material stats defined in a single pack:

{
    "stats": {
        "example:type1": { "field_a": 1, "field_b": 4 }
        "example:type3": {}
    }
}

Traits

Can datagen using AbstractMaterialTraitDataProvider.

Material traits defines the traits associated with a material. There are two methods to define traits: default and per stat. Additionally (since 1.18.2), traits can be assigned either to a stat type or a stat group within per stats. The materials final traits will be the first one present between the stat group, stat type, then the default traits.

The material traits for <domain>:<name> will be located at data/<domain>/tinkering/materials/traits/<name>.json (since 1.18) or data/<domain>/materials/traits/<name>.json (in 1.16). They have the following format:

  • (Object): The root object.
    • default (Array): List of traits to add by default (that is, if the stat type has no per stat list).
      • (Object): A modifier entry.
        • name (Modifier ID): Modifier to apply.
        • level (Integer): Modifier level to apply. If unset, defaults to 1.
    • perStat (Object): Object containing all stats. Keys in this object are stat type IDs, while the values have a format based on the type.
      • <domain>:<name> (Array): Defines the traits for the type <domain>:<name>.
        • (Object): A modifier entry.
          • name (Modifier ID): Modifier to apply.
          • level (Integer): Modifier level to apply. If unset, defaults to 1.
      • <domain>:<name> (Null): Removes the traits for the type <domain>:<name>, causing that type to default.

Merging

Material traits support merging across different data packs. The default field will pull from the top loaded pack where default is defined, meaning an addon can add traits specific to its stat type without worrying about the default changing. perStat will also pull from the top loaded pack where the type is defined, with the additional behavior that if the stat is set to null it will remove the list from all lower packs. Lists will not merge across data packs, there is no way to add a new trait to an existing default or per stat list without redefining the list.

Example:

The following material traits exists in the first data pack:

{
    "default": [{ "name": "example:modifier_0"}],
    "perStat": {
        "example:type1": [{ "name": "example:modifier_1" }],
        "example:type2": [{ "name": "example:modifier_2" }],
        "example:type3": [{ "name": "example:modifier_3" }]
    }
}

along with the following material traits in the second data pack:

{
    "perStat": {
        "example:type2": null,
        "example:type3": [{ "name": "example:modifier_5" }],
        "example:type4": [{ "name": "example:modifier_4" }]
    }
}

Together, they are equivalent to the following material traits defined in a single pack:

{
    "default": [{ "name": "example:modifier_0"}],
    "perStat": {
        "example:type1": [{ "name": "example:modifier_1" }],
        "example:type3": [{ "name": "example:modifier_5" }],
        "example:type4": [{ "name": "example:modifier_4" }]
    }
}

Material Providers

Some JSON contexts support specifying material providers that may be possibly randomized given a stat type. Random material providers have the following format:

  • (Object): The material provider object.
    • type (Resource Location): Random material provider type.
    • Additional fields based on the random material provider.

The following subsections describe the different random material serializers provided by default.

Fixed

The fixed material provider always returns the same fixed material. It has the following format:

First

The first material provider the first material for the stat type, as determined by the material’s sort order and tier. It has the following format:

  • (Object): The material provider object.

Random

The random material provider selects a random material from the material registry, possibly filtered by a tier or tag. It has the following format:\

  • (Object): The material provider object.
    • type (Resource Location): Always tconstruct:random.
    • tier (Integer Range): If set, only provides materials with a tier within the range.
    • tag (Material tag): If set, only provides materials within the tag.
    • allow_hidden (Boolean): If true, may provide hidden materials. Defaults to false.