====== 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 [[https://minecraft.wiki/w/Tag|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)

<code javascript>
{
    "replace": false,
    "values": [
        "tutorial:example_ore"
    ]
}
</code>

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 ''<yarn class_3481>'' and ''<yarn class_3489>''. To register tag objects in your mod, see the following.

=== Minecraft 1.21 and above ===

<yarncode java>
public class ModBlockTags {
  public static final TagKey<class_2248> EXAMPLE_ORES = class_6862.method_40092(class_7924.field_41254, class_2960.of("tutorial", "example_ores"));
}
</yarncode>

=== Minecraft 1.19.3 through 1.20.6 ===

<yarncode java>
public class ModBlockTags {
  public static final TagKey<class_2248> EXAMPLE_ORES = class_6862.method_40092(class_7924.field_41254, new class_2960("tutorial", "example_ores"));
}
</yarncode>

=== Minecraft 1.18.2 through 1.19.2 ===

<yarncode java>
public class ModBlockTags {
  public static final TagKey<class_2248> EXAMPLE_ORES = class_6862.method_40092(class_2378.BLOCK_KEY, new class_2960("tutorial", "example_ores"));
}
</yarncode>

=== 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:

<yarncode java>
public class ModBlockTags {
  public static final Tag<class_2248> EXAMPLE_ORES = TagFactory.BLOCK.create(new class_2960("tutorial", "example_ores"));
}
</yarncode>

=== 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:

<yarncode java>
public class ModBlockTags {
  public static final Tag<class_2248> EXAMPLE_ORES = TagRegistry.block(new class_2960("tutorial", "example_ores"));
}
</yarncode>

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 [[https://github.com/FabricMC/fabric/tree/HEAD/fabric-convention-tags-v2/src/generated/resources/data/c/tags|here]].

A (possibly outdated) directory of general known conventional tags is available on [[community:common_tags|a separate page]].