User Tools

Site Tools


tutorial:tags

Tags

Tags are groups of blocks, items, fluids, biomes or other registry objects which share similar properties. They can be used in recipes to allow for multiple items to be used in the same recipe interchangeably. Read more on what tags are on the Minecraft Wiki. Tags can also be used to group similar items or other pieces of content from different mods, to allow them to be compatible with each other. These are called conventional tags.

Creating tags

Defining through JSON

File Location:

  • src/main/resources/data/tutorial/tags/blocks/example_ores.json (before 1.21)
  • src/main/resources/data/tutorial/tags/block/example_ores.json (since 1.21)
{
    "replace": false,
    "values": [
        "tutorial:example_ore"
    ]
}

The “replace” tag determines whether the mod will remove all other items in the tag that are not mentioned in this file. It is not recommended to set this to true, as it may break compatibility with other mods. blocks in the file path can also be items or fluids. You should separate words with underscores, and tags should be plural.

Accessing tags in code

For some cases, you might want to have tags as registered objects on code. For example, methods like Block#isIn require these tag parameters. Besides, the Fabric registries like FlammableBlockRegistry, FuelRegistry and CompostingChanceRegistry also accept block tags or item tags.

Vanilla tag objects can be found in class BlockTags and ItemTags. To register tag objects in your mod, see the following.

Minecraft 1.21 and above

public class ModBlockTags {
  public static final TagKey<Block> EXAMPLE_ORES = TagKey.of(RegistryKeys.BLOCK, Identifier.of("tutorial", "example_ores"));
}

Minecraft 1.19.3 through 1.20.6

public class ModBlockTags {
  public static final TagKey<Block> EXAMPLE_ORES = TagKey.of(RegistryKeys.BLOCK, new Identifier("tutorial", "example_ores"));
}

Minecraft 1.18.2 through 1.19.2

public class ModBlockTags {
  public static final TagKey<Block> EXAMPLE_ORES = TagKey.of(Registry.BLOCK_KEY, new Identifier("tutorial", "example_ores"));
}

Minecraft 1.17.1 through 1.18.1

In Minecraft 1.17.1 through 1.18.1, Fabric API provides a helper method for creating a tag:

public class ModBlockTags {
  public static final Tag<Block> EXAMPLE_ORES = TagFactory.BLOCK.create(new Identifier("tutorial", "example_ores"));
}

Minecraft 1.17 and below

In Minecraft 1.17 (not including Minecraft 1.17.1) and earlier versions, Fabric API provides a different API for creating a tag:

public class ModBlockTags {
  public static final Tag<Block> EXAMPLE_ORES = TagRegistry.block(new Identifier("tutorial", "example_ores"));
}

Note that TagRegistry is deprecated since Fabric API 0.46.0, as TagFactory replaces it. TagRegistry is used in Minecraft 1.17 and below because Fabric API for these versions did not receive the TagFactory changes.

Conventional tags

Conventional tags are a standardized tag naming scheme that aims to reduce guesswork and inconsistency for mod developers, data pack authors, and mod pack authors. These tags share the c namespace and have explicit rules for naming.

Conventional tags should be used where one piece of content added by a mod is similar enough to another piece of content added by another mod that functionality should be considered interchangeable between the two items. For example, if a mod adds a custom chest for a wood type it adds, it may add this chest to the c:wooden_chests tag so that it can be used in other mods' recipes.

On the other hand, pieces of content that are unique enough to not be interchangable should not use conventional tags. For example, if a mod adds a unique set of machines that must be grouped within a tag, it should place these machines in a tag in its own namespace, such as yourmodid:custom_machines.

Creating new conventional tags

Conventional tags are simply tags in the c namespace. These tags are expected to be used by multiple mods, so the name scheme for conventional tags should be consistent between mods. The general format for conventional tags is plural, with words separated with underscores. The following tags are good examples of this convention:

  • c:chests block tag
  • c:water_buckets item tag
  • c:in_the_end biome tag

A flat structure is used rather than a hierarchal structure. For example, c:iron_ores is preferred over c:ores/iron.

Existing conventional tags

Fabric API ships definitions for conventional tags in its fabric-conventional-tags-v2 module. The provided tags can be viewed here.

A (possibly outdated) directory of general known conventional tags is available on a separate page.

tutorial/tags.txt · Last modified: 2024/06/17 13:05 by solidblock