Registering Variants

Transform into a mob!

  1. Registry Variants
  2. Advanced NBT Method
  3. Custom Names for Variants
  4. Registering Variants in Woodwalkers before 6.4
    1. General File Structure
    2. Boolean NBT Tags
    3. Integer NBT Tags
    4. String NBT Tags
    5. Variants with multiple NBT Tags

Alright, so here is your default path for the variants:

data\<your_namespace>\walkers\variants

In this folder, you can create a JSON-file. I recommend naming it like minecraft_wolf.json if you’re registering Variants for the minecraft:wolf.

Registry Variants

As of Minecraft 1.21.5 some mobs have a custom registry for their variants. In order to make woodwalkers recognise those registries and map them to the correct entity types, you can create a file similiar to this one:

{
  "entity_type": "minecraft:wolf",
  "type_provider": {
    "fallback": 0,
    "registry": "minecraft:wolf_variant"
  }
}
  • entity_type - the entity type you want to register variants for
  • fallback - the variant id (registry index) minecraft defaults to when no valid NBT is given, optional
  • registry - the name of the minecraft registry that contains the valid variants

Advanced NBT Method

As of Walkers 6.4, there is a new option to register variants.

At first,here’s an example script for sheep (I’ve stripped it to 6 colors instead of 16):

{
  "entity_type": "minecraft:sheep",
  "type_provider": {
    "fallback": 0,
    "variants": {
      "0": {
        "Color": 0
      },
      "1": {
        "Color": 1
      },
      "2": {
        "Color": 2
      },
      "3": {
        "Color": 3
      },
      "4": {
        "Color": 4
      },
      "5": {
        "Color": 5
      }
    }
  }
}

Here, the entity_type is the type of entity you want to register variants for. In the variants tag of the type_provider tag a numerical increasing number (starting with 0) is matched to a series of NBT tags. Here, there is only one NBT tag matched to the variant ids- the Color tag of the sheep. You can determinate what tags to use by experimenting with Minecraft’s /summon command: /summon sheep ~ ~ ~ {Color:15} will spawn a black sheep.

The fallback key is optional and used to determinate the variant in case something goes wrong creating the entity.

Of course it’s also possible with multiple NBT Keys:

{
  "entity_type": "minecraft:bee",
  "type_provider": {
    "variants": {
      "0": {
        "HasStung": false,
        "HasNectar": false
      },
      "1": {
        "HasStung": true,
        "HasNectar": false
      },
      "2": {
        "HasStung": false,
        "HasNectar": true
      },
      "3": {
        "HasStung": true,
        "HasNectar": true
      }
    }
  }
}

Using a string tag, the script could look similar to this one:

{
  "entity_type": "namespace:entity",
  "type_provider": {
    "variants": {
      "0": {
        "someNBTKey": "someValue",
        "otherNBTKey": false
      },
      "1": {
        "2ndNbtKey": "hello world",
        "otherNBTKey": true
      }
    }
  }
}

Again, you’ll notice that the NBT Tags don’t have to be in every variant. Only the registered tag will be checked per variant.

Custom Names for Variants

If you like to specify a name for your Variant you can do so with the following:

{
  "entity_type": "minecraft:snow_golem",
  "type_provider": {
    "variants": {
      "0": {
        "Pumpkin": false
      },
      "1": {
        "Pumpkin": true
      }
    },
    "names": {
      "0": "walkers.variants.minecraft.snow_golem.0"
    }
  }
}

In this example, we’ll continue the example from the Boolean NBT Tags. You’ll notice the names key. In it is a language key for the variant id 0 specified. Any variant id not specified will defer to the default entity name, in this example “Snow Golem”. You can name the language keys whatever you want, though I recommend the layout walkers.variants.<namespace>.<mob>.<id>.

Once you specified them, you also need to add them to a language file. For example I added this entry to the en_us.json:

{
  "walkers.variants.minecraft.snow_golem.0": "Headless %s"
}

%s means, this will be replaced by the default name. In this example, you’ll see an output of “Headless Snow Golem”.

Registering Variants in Woodwalkers before 6.4

Here’s an example for a Variant, which is based on another mob (e.g. you have a subclass of the sheep and want to apply sheep variants to it, too).

{
  "entity_type": "modid:wolf",
  "parent": "minecraft:wolf"
}

There are also ways to add it via classes, though it’s not recommended:

{
  "entity_type": "modid:llama",
  "type_provider_class": "tocraft.walkers.impl.variant.LlamaTypeProvider"
}

A list of possible TypeProvider-Classes for 1.20.2 can be found in the source code.

Now, let’s get to registering custom Variants.

General File Structure

{
  "entity_type": "minecraft:sheep",
  "required_mod": "some_modid",
  "type_provider": {
    "fallback": 0,
    "range": 15,
    "nbt": [
      {
        "nbt_type": "INTEGER",
        "nbt_field": "Color",
        "is_mutable": false,
        "parameters": {
          "0": "5"
        }
      }
    ],
    "names": {
      "0": "<some lang key for that variant, like 'White %s'.>"
    }
  }
}
  • entity_type is the mob you want to register the Variants for.
  • required_mod is optional and only required if adding support for mods like MoreMobVariants.
  • fallback isn’t required and is only needed for INTEGER values which should start with zero.
  • range this is essentially the range of possible variants. Note that 0 is a variant and therefore counted. (e.g. there are 16 colors for sheep, therefore the range is 15)
  • nbt the NBT Tags you want to modify (Yes, you can modify multiple at once, see below for more details).
    • nbt_type specifies, what type of NBT Tag you want to modify.
      • Possible entries are BOOLEAN, INTEGER and STRING.
      • BOOLEAN doesn’t require any extra arguments.
      • INTEGER requires that range is specified.
      • STRING requires that parameters is specified.
    • nbt_field specifies the NBT Field, in this example Pumpkin since /summon minecraft:snow_golem ~ ~ ~ {Pumpkin:true} spawns a Snow Golem with a pumpkin and /summon minecraft:snow_golem ~ ~ ~ {Pumpkin:false} spawns one without one, therefore the nbt_field must be set to Pumpkin.
    • is_mutable this is only required for String Tags and is still a bit unstable.
    • parameters this is only required if the variant id shouldn’t match the Tag Value (for Integer Tags) or for Strings to specify, what Variant id equals what String value (see below).
  • names take a look at Custom Names for Variants

Boolean NBT Tags

Since it’s getting more complicated from now on, we’ll take a look at a simple example:

{
  "entity_type": "minecraft:snow_golem",
  "type_provider": {
    "nbt": [
      {
        "nbt_type": "BOOLEAN",
        "nbt_field": "Pumpkin"
      }
    ]
  }
}

This essentially registers two Snow Golem Variants - one with and one without the Pumpkin. True is a variant id of 1 and False a variant id of 0.

Integer NBT Tags

This is still simple since most things are automatically detected.

{
  "entity_type": "minecraft:sheep",
  "type_provider": {
    "range": 16,
    "nbt": [
      {
        "nbt_type": "INTEGER",
        "nbt_field": "Color"
      }
    ]
  }
}

You need to specify range so you have a range of possible Integer values for your NBT Tag.

String NBT Tags

Now it’s getting a bit more advanced.

{
  "entity_type": "minecraft:sheep",
  "type_provider": {
    "range": 1,
    "nbt": [
      {
        "nbt_type": "STRING",
        "nbt_field": "CustomName",
        "is_mutable": true,
        "parameters": {
          "1": "\"jeb_\""
        }
      }
    ]
  }
}

Now, we’ll have a look at the keys again.

  • range is required in this example, because we only specified one parameter. If no range is specified, it will default to the parameters list.
  • is_mutable this means, the specified String Tag is a mutable component. Normally, this is only required for CustomName.
  • parameters is a list of possible String Entries per Variant id. In this example, a sheep with the variant id 1 will have a CustomName of \"jeb_\". If not specified, the String Tag will be empty for that variant id. So, in this example, a sheep with the variant id 0 won’t have a CustomName at all.

Variants with multiple NBT Tags

If you’ve understood the above code, you’ll find your way around this, too.

{
  "entity_type": "minecraft:sheep",
  "type_provider": {
    "range": 16,
    "nbt": [
      {
        "nbt_type": "string",
        "nbt_field": "CustomName",
        "is_mutable": true,
        "parameters": {
          "16": "\"jeb_\""
        }
      },
      {
        "nbt_type": "int",
        "nbt_field": "Color",
        "parameters": {
          "16": "0"
        }
      }
    ]
  }
}

You’ll notice that more than one nbt is specified. In this example, a sheep with the variant id 0 will have an empty CustomName (since no parameters entry is specified) and a color of 0. If the variant id equals 16 the sheep will have the CustomName "\jeb_\" because it’s specified in the respective parameters list and a Color of 16. You won’t notice the Color of 16 though, since there isn’t a color with that id.

Note that it’s important to specify parameters with multiple nbt tags. Every jeb_-sheep has technically a white color, so you have to specify the parameters for this.