Attribute‐based Matching

Matching Logic

This library uses a similar system to vanilla's XByType variant groups system. When using this mod's classes or behaviors, the settings are always matched against the attributes present on the itemstack. You can think of these fields as being XByAttribute; eg shapeByAttribute or texturesByAttribute. The ByAttribute part of it is assumed, and should not be explicitly stated; just use shape or textures.

Format of the "Matching Strings"

The format it will compare your wildcard match to is: {key}-{value}. You must define attributes nested within a root attribute, called types. It will then scan each of the key-value pairs inside that root attribute, and create a "Matching string" for each of them, similar to generating variants in vanilla. For example, let's say we want to add new shoes, which can have their laces either tied or untied, and would have different shapes for each. The itemstacks for those would look like this:

[
  { "type": "item", "code": "my_shoes", "attributes": { "types": { "laces": "tied" } } },
  { "type": "item", "code": "my_shoes", "attributes": { "types": { "laces": "untied" } } },
]

These attributes would generate a "Matching string" for each itemstack: laces-tied, and laces-untied. You could then assign different shapes to them by matching based on:

"shape": {
  "laces-tied": { "base": "my_shoes/tied" },
  "laces-untied": { "base": "my_shoes/untied" }
}

When multiple matches are valid, ones defined earlier have priority, much like vanilla's ByType behavior.

Wildcards

Full support for vanilla's Wildcards. They work the same way they do for variant groups.

Placeholders

You can also use placeholders here, much like vanilla's variants. The placeholder should use the Key of the attribute. We could use this to simplify the previous example:

"shape": {
  "laces-*": { "base": "my_shoes/{laces}" }
}

This method of matching, laces-*, matches anything that has the laces attribute defined within types at all, regardless of the value.

Matching multiple attributes

Unlike vanilla, the matching strings you define do not need to match against all of the attributes. In the previous color example, even if other attributes were present for things like metal color, or shape, those do not need to be specified in the Matching Rule you define. Each attribute is compared separately.

:: acts as && (AND operator). It is used to define texture/shape/name etc. based on few existing attributes, e.g. stone-*::wood-* would match attributes that have both stone-andesite and wood-oak. We could then use their values in placeholders by referencing {stone} or {wood}.

Regex

Regex is supported in the same way as it is for vanilla variant groups, using @ symbol. Eg @color-(red|blue|green).

If you need to use AND operator with Regex groups, keep in mind that the Regex declaration using @ is specific to each ::-delineated section of your Matching string. So if you wanted to match on only specific types AND only specific colors, you could do so like: @type-(face|body)::@color-(red|blue)

Examples

Overwriting original textures only if specific attributes are set

I want to vary the color of this item, as well as other parts such as metal type or wood type used. But I want to only do it selectively; eg if I only set color, I want the other textures to remain untouched. Any textures you do not define an override for in the attribute-specific section will default back to vanilla's texture logic.

"textures": {
    "color-*::wood-*::metal-*": {
        "plain": {
            "base": "game:block/leather/{color}"
        },
        "birch": {
            "base": "game:block/wood/debarked/{wood}"
        },
        "brass": {
            "base": "game:block/metal/plate/{metal}"
        }
    },
    "color-*::metal-*": {
        "plain": {
            "base": "game:block/leather/{color}"
        },
        "brass": {
            "base": "game:block/metal/plate/{metal}"
        }
    },
    "color-*": {
        "plain": {
            "base": "game:block/leather/{color}"
        }
    },
    "wood-*": {
        "birch": {
            "base": "game:block/wood/debarked/{wood}"
        }
    }
}

This evaluates, in order, like this:

1. If color AND wood AND metal are set, replace all 3 textures using their values as placeholders
2. If color AND metal are both set, replace those 2 textures using their values as placeholders
3. If color is set, replace that 1 texture using its value as a placeholder
4. If wood is set (implying color is not set, as otherwise #3 would have matched and stopped evaluation), then replace that 1 texture using the wood value as a placeholder