Difference between revisions of "Tags"

From Forge Community Wiki
(Update to 1.18.2)
(Happy now Shrimp? ITagManager is included)
Line 29: Line 29:
 
Tags for all registries are automatically sent from the server to any remote clients on login and reload. <code><nowiki>Block</nowiki></code>s, <code><nowiki>Item</nowiki></code>s, <code><nowiki>EntityType</nowiki></code>s, <code><nowiki>Fluid</nowiki></code>s, and <code><nowiki>GameEvent</nowiki></code>s are special cased as they have <code><nowiki>Holder</nowiki></code>s allowing for available tags to be accessible through the object itself.
 
Tags for all registries are automatically sent from the server to any remote clients on login and reload. <code><nowiki>Block</nowiki></code>s, <code><nowiki>Item</nowiki></code>s, <code><nowiki>EntityType</nowiki></code>s, <code><nowiki>Fluid</nowiki></code>s, and <code><nowiki>GameEvent</nowiki></code>s are special cased as they have <code><nowiki>Holder</nowiki></code>s allowing for available tags to be accessible through the object itself.
  
Tags wrappers can be created using <code><nowiki>TagKey#create</nowiki></code> where the registry the tag should belong to and the tag name are supplied. Some vanilla defined helpers are also available to create wrappers via <code><nowiki>*Tags#create</nowiki></code> where <code><nowiki>*</nowiki></code> refers to the name of the registry object.
+
Tags wrappers can be created using <code><nowiki>TagKey#create</nowiki></code> where the registry the tag should belong to and the tag name are supplied. Some vanilla defined helpers are also available to create wrappers via <code><nowiki>*Tags#create</nowiki></code> where <code><nowiki>*</nowiki></code> refers to the name of the registry object. Forge wrapped registries can create a tag using <code><nowiki>ITagManager</nowiki></code> via <code><nowiki>IForgeRegistry#tags</nowiki></code>. <code><nowiki>TagKey</nowiki></code>s can then be obtained via <code><nowiki>ITagManager#createTagKey</nowiki>.
  
Forge wrapped registry objects can grab their associated holder using <code><nowiki>IForgeRegistry#getHolder</nowiki></code> while non-Forge registry objects use either <code><nowiki>Registry#getHolder</nowiki></code> or <code><nowiki>Registry#getHolderOrThrow</nowiki></code>. They then can compare if the registry object has a tag using <code><nowiki>Holder#is</nowiki></code>. Tag-holding registry objects contain a method called <code><nowiki>#is</nowiki></code> in either their registry object or state-aware class to check whether the object belongs to a certain tag.
+
Forge wrapped registry objects can grab their associated holder using <code><nowiki>IForgeRegistry#getHolder</nowiki></code>. Additionally, other streamlined operations can be performed using <code><nowiki>ITagManager</nowiki></code>. Non-Forge registry objects use either <code><nowiki>Registry#getHolder</nowiki></code> or <code><nowiki>Registry#getHolderOrThrow</nowiki></code> to get the current holder.
 +
 
 +
They then can compare if the registry object has a tag using <code><nowiki>Holder#is</nowiki></code>. Tag-holding registry objects contain a method called <code><nowiki>#is</nowiki></code> in either their registry object or state-aware class to check whether the object belongs to a certain tag.
  
 
As an example:  
 
As an example:  
Line 37: Line 39:
 
public static final TagKey<Item> myItemTag = ItemTags.create(new ResourceLocation("mymod", "myitemgroup"));
 
public static final TagKey<Item> myItemTag = ItemTags.create(new ResourceLocation("mymod", "myitemgroup"));
  
public static final TagKey<Potion> myPotionTag = TagKey.create(Registry.POTION, new ResourceLocation("mymod", "mypotiongroup"));
+
public static final TagKey<Potion> myPotionTag = ForgeRegistries.POTIONS.tags().createTagKey(new ResourceLocation("mymod", "mypotiongroup"));
  
 
public static final TagKey<VillagerType> myVillagerTypeTag = TagKey.create(Registry.VILLAGER_TYPE, new ResourceLocation("mymod", "myvillagertypegroup"));
 
public static final TagKey<VillagerType> myVillagerTypeTag = TagKey.create(Registry.VILLAGER_TYPE, new ResourceLocation("mymod", "myvillagertypegroup"));
Line 44: Line 46:
 
boolean isInItemGroup = stack.is(myItemTag);
 
boolean isInItemGroup = stack.is(myItemTag);
  
// In some method where potionName is a ResourceLocation
+
// In some method where potion is a Potion
boolean isInPotionGroup = ForgeRegistries.POTIONS.getHolder(potionName).map(holder -> holder.is(myPotionTag)).orElse(false);
+
boolean isInPotionGroup = ForgeRegistries.POTIONS.tags().getTag(myPotionTag).contains(potion);
  
 
// In some method where villagerTypeKey is a ResourceKey<VillagerType>
 
// In some method where villagerTypeKey is a ResourceKey<VillagerType>

Revision as of 13:26, 22 March 2022

Tags are generalized sets of objects in the game, used for grouping related things together and providing fast membership checks.

Declaring Your Own Groupings

Tags are declared in your mod’s datapack. For example, a TagKey<Block> with a given identifier of modid:foo/tagname will reference a tag at /data/<modid>/tags/blocks/foo/tagname.json. Tags for Blocks, Items, EntityTypes, Fluids, and GameEvents use the plural forms for their folder location while all other registries use the singular version (EntityType uses the folder entity_types while Potion would use the folder potion). Similarly, you may append to or override tags declared in other domains, such as Vanilla, by declaring your own JSONs. For example, to add your own mod’s saplings to the Vanilla sapling tag, you would specify it in /data/minecraft/tags/blocks/saplings.json, and Vanilla will merge everything into one tag at reload, if the replace option is false. If replace is true, then all entries before the json specifying replace will be removed.

Values listed that are not present will cause the tag to error unless the value is listed using an id string and required boolean set to false, as in the following example:

{
  "replace": false,
  "values": [
    "minecraft:gold_ingot",
    "mymod:my_ingot",
    {
      "id": "othermod:ingot_other",
      "required": false
    }
  ]
}

See the Vanilla wiki for a description of the base syntax.


There is also a Forge extension on the Vanilla syntax. You may declare a remove array of the same format as the values array. Any values listed here will be removed from the tag. This acts as a finer grained version of the Vanilla replace option.

Using Tags In Code

Tags for all registries are automatically sent from the server to any remote clients on login and reload. Blocks, Items, EntityTypes, Fluids, and GameEvents are special cased as they have Holders allowing for available tags to be accessible through the object itself.

Tags wrappers can be created using TagKey#create where the registry the tag should belong to and the tag name are supplied. Some vanilla defined helpers are also available to create wrappers via *Tags#create where * refers to the name of the registry object. Forge wrapped registries can create a tag using ITagManager via IForgeRegistry#tags. TagKeys can then be obtained via ITagManager#createTagKey.

Forge wrapped registry objects can grab their associated holder using IForgeRegistry#getHolder. Additionally, other streamlined operations can be performed using ITagManager. Non-Forge registry objects use either Registry#getHolder or Registry#getHolderOrThrow to get the current holder.

They then can compare if the registry object has a tag using Holder#is. Tag-holding registry objects contain a method called #is in either their registry object or state-aware class to check whether the object belongs to a certain tag.

As an example:

public static final TagKey<Item> myItemTag = ItemTags.create(new ResourceLocation("mymod", "myitemgroup"));

public static final TagKey<Potion> myPotionTag = ForgeRegistries.POTIONS.tags().createTagKey(new ResourceLocation("mymod", "mypotiongroup"));

public static final TagKey<VillagerType> myVillagerTypeTag = TagKey.create(Registry.VILLAGER_TYPE, new ResourceLocation("mymod", "myvillagertypegroup"));

// In some method where stack is an ItemStack
boolean isInItemGroup = stack.is(myItemTag);

// In some method where potion is a Potion
boolean isInPotionGroup = ForgeRegistries.POTIONS.tags().getTag(myPotionTag).contains(potion);

// In some method where villagerTypeKey is a ResourceKey<VillagerType>
boolean isInVillagerTypeGroup = Registry.VILLAGER_TYPE.getHolder(villagerTypeKey).map(holder -> holder.is(myVillagerTypeTag)).orElse(false);

Migration from OreDictionary

  • For recipes, tags can be used directly in the vanilla recipe format (see below)
  • For matching items in code, see the section above.
  • If you are declaring a new type of item grouping, follow a couple naming conventions:
    • Use domain:type/material. When the name is a common one that all modders should adopt, use the forge domain.
    • For example, brass ingots should be registered under the forge:ingots/brass tag, and cobalt nuggets under the forge:nuggets/cobalt tag.

Using Tags in Recipes and Advancements

Tags are directly supported by Vanilla, see the respective Vanilla wiki pages for recipes and advancements for usage details.

Conventions

There are several conventions that will help facilitate compatibility in the ecosystem:

  * If there is a Vanilla tag that fits your block or item, add it to that tag. See the list of Vanilla tags. 
  * If there is a Forge tag that fits your block or item, add it to that tag. The list of tags declared by Forge can be seen on GitHub. 
  * If there is a group of something you feel should be shared by the community, consider PR-ing it to Forge instead of making your own tag 
  * Tag naming conventions should follow Vanilla conventions. In particular, item and block groupings are plural instead of singular. E.g. minecraft:logs, minecraft:saplings. 
  * Item tags should be sorted into subdirectories according to the type of item, e.g. forge:ingots/iron, forge:nuggets/brass, etc.

Forge Tags

This is a list of all tags using the forge namespace that are currently defined by Forge along those that are commonly used by other mods. These can all be found within the Tags class.

Important

Tags that are not officially defined within the Forge codebase will have * as a suffix. To use those outside the Forge codebase, an IOptionalNamedTag must be created using *Tags#createOptional where the asterisk can be replaced by its associated class name.

Blocks

Name Super Tag(s) Contains
forge:barrels None Barrels
forge:barrels/wooden forge:barrels Wooden barrels
forge:chests None Chests
forge:chests/ender forge:chests Ender chests
forge:chests/trapped forge:chests Trapped chests
forge:chests/wooden forge:chests Wooden chests
forge:cobblestone None Cobblestones
forge:cobblestone/normal forge:cobblestone Normal cobblestones
forge:cobblestone/infested forge:cobblestone Infested cobblestones
forge:cobblestone/mossy forge:cobblestone Mossy cobblestones
forge:cobblestone/deepslate forge:cobblestone Deepslate cobblestones
forge:end_stones None End stones
forge:enderman_place_on_blacklist None Blocks that an enderman cannot place its held block on
forge:fence_gates None Fence gates
forge:fence_gates/wooden forge:fence_gates Wooden fence gates
forge:fences None Fences
forge:fences/nether_brick forge:fences Nether brick fences
forge:fences/wooden forge:fences Wooden fences
forge:glass None Glass
forge:glass/black None Black glass
forge:glass/blue None Blue glass
forge:glass/brown None Brown glass
forge:glass/colorless forge:glass Normal glass
forge:glass/cyan None Cyan glass
forge:glass/gray None Gray glass
forge:glass/green None Green glass
forge:glass/light_blue None Light blue glass
forge:glass/light_gray None Light gray glass
forge:glass/lime None Lime glass
forge:glass/magenta None Magenta glass
forge:glass/orange None Orange glass
forge:glass/pink None Pink glass
forge:glass/purple None Purple glass
forge:glass/red None Red glass
forge:glass/silica None Sand-based glass with minor ingredient variation
forge:glass/tinted forge:glass Tinted glass
forge:glass/white None White glass
forge:glass/yellow None Yellow glass
forge:glass_panes None Glass panes
forge:glass_panes/black None Black glass panes
forge:glass_panes/blue None Blue glass panes
forge:glass_panes/brown None Brown glass panes
forge:glass_panes/colorless forge:glass_panes Normal glass panes
forge:glass_panes/cyan None Cyan glass panes
forge:glass_panes/gray None Gray glass panes
forge:glass_panes/green None Green glass panes
forge:glass_panes/light_blue None Light blue glass panes
forge:glass_panes/light_gray None Light gray glass panes
forge:glass_panes/lime None Lime glass panes
forge:glass_panes/magenta None Magenta glass panes
forge:glass_panes/orange None Orange glass panes
forge:glass_panes/pink None Pink glass panes
forge:glass_panes/purple None Purple glass panes
forge:glass_panes/red None Red glass panes
forge:glass_panes/white None White glass panes
forge:glass_panes/yellow None Yellow glass panes
forge:gravel None Gravel
forge:netherrack None Netherrack
forge:obsidian None Obsidian
forge:ore_bearing_ground/deepslate None Blocks replaced by deepslate ores during world generation
forge:ore_bearing_ground/netherrack None Blocks replaced by netherrack ores during world generation
forge:ore_bearing_ground/stone None Blocks replaced by stone ores during world generation
forge:ore_rates/dense None Ores which produce numerous resources on average
forge:ore_rates/singular None Ores which produce a single resource on average
forge:ore_rates/sparse None Ores which produce less than a single resource on average
forge:ores None Ores
forge:ores/coal forge:ores Coal ores
forge:ores/copper forge:ores Copper ores
forge:ores/diamond forge:ores Diamond ores
forge:ores/emerald forge:ores Emerald ores
forge:ores/gold forge:ores Gold ores
forge:ores/lapis forge:ores Lapis ores
forge:ores/netherite_scrap forge:ores Netherite scrap ores
forge:ores/quartz forge:ores Quartz ores
forge:ores/redstone forge:ores Redstone ores
forge:ores_in_ground/deepslate None Ores which can be found in deepslate
forge:ores_in_ground/netherrack None Ores which can be found in netherrack
forge:ores_in_ground/stone None Ores which can be found in stone
forge:sand None Sand
forge:sand/colorless forge:sand Normal sand
forge:sand/red forge:sand Red sand
forge:sandstone None Sandstone
forge:stained_glass forge:glass Stained glass
forge:stained_glass_panes forge:glass_panes Stained glass planes
forge:stone None Stones
forge:storage_blocks None Storage blocks
forge:storage_blocks/amethyst forge:storage_blocks Amethyst blocks
forge:storage_blocks/coal forge:storage_blocks Coal blocks
forge:storage_blocks/copper forge:storage_blocks Copper blocks
forge:storage_blocks/diamond forge:storage_blocks Diamond blocks
forge:storage_blocks/emerald forge:storage_blocks Emerald blocks
forge:storage_blocks/gold forge:storage_blocks Gold blocks
forge:storage_blocks/iron forge:storage_blocks Iron blocks
forge:storage_blocks/lapis forge:storage_blocks Lapis blocks
forge:storage_blocks/netherite forge:storage_blocks Netherite blocks
forge:storage_blocks/quartz forge:storage_blocks Quartz blocks
forge:storage_blocks/raw_copper forge:storage_blocks Raw copper blocks
forge:storage_blocks/raw_gold forge:storage_blocks Raw gold blocks
forge:storage_blocks/raw_iron forge:storage_blocks Raw iron blocks
forge:storage_blocks/redstone forge:storage_blocks Redstone blocks
forge:needs_wood_tool None Blocks which need a wooden tool to be mined efficiently
forge:needs_gold_tool None Blocks which need a gold tool to be mined efficiently
forge:needs_netherite_tool None Blocks which need a netherite tool to be mined efficiently

Items

Name Super Tag(s) Contains
forge:barrels None Barrels
forge:barrels/wooden forge:barrels Wooden barrels
forge:bones None Bones
forge:bookshelves None Bookshelves
forge:chests None Chests
forge:chests/ender forge:chests Ender chests
forge:chests/trapped forge:chests Trapped chests
forge:chests/wooden forge:chests Wooden chests
forge:cobblestone None Cobblestones
forge:cobblestone/normal forge:cobblestone Normal cobblestones
forge:cobblestone/infested forge:cobblestone Infested cobblestones
forge:cobblestone/mossy forge:cobblestone Mossy cobblestones
forge:cobblestone/deepslate forge:cobblestone Deepslate cobblestones
forge:crops None Crops
forge:crops/beetroot forge:crops Beetroot crops
forge:crops/carrot forge:crops Carrot crops
forge:crops/nether_wart forge:crops Nether wart crops
forge:crops/potato forge:crops Potato crops
forge:crops/wheat forge:crops Wheat crops
forge:dusts None Dusts
forge:dusts/prismarine forge:dusts Prismarine dusts
forge:dusts/redstone forge:dusts Redstone dusts
forge:dusts/glowstone forge:dusts Glowstone dusts
forge:dyes None Dyes
forge:dyes/black forge:dyes Black dyes
forge:dyes/blue forge:dyes Blue dyes
forge:dyes/brown forge:dyes Brown dyes
forge:dyes/cyan forge:dyes Cyan dyes
forge:dyes/gray forge:dyes Gray dyes
forge:dyes/green forge:dyes Green dyes
forge:dyes/light_blue forge:dyes Light blue dyes
forge:dyes/light_gray forge:dyes Light green dyes
forge:dyes/lime forge:dyes Lime dyes
forge:dyes/magenta forge:dyes Magenta dyes
forge:dyes/orange forge:dyes Orange dyes
forge:dyes/pink forge:dyes Pink dyes
forge:dyes/purple forge:dyes Purple dyes
forge:dyes/red forge:dyes Red dyes
forge:dyes/white forge:dyes White dyes
forge:dyes/yellow forge:dyes Yellow dyes
forge:eggs None Eggs
forge:enchanting_fuels None Enchantment table fuels
forge:end_stones None End stones
forge:ender_pearls None Ender pearls
forge:feathers None Feathers
forge:fence_gates None Fence gates
forge:fence_gates/wooden forge:fence_gates Wooden fence gates
forge:fences None Fences
forge:fences/nether_brick forge:fences Nether brick fences
forge:fences/wooden forge:fences Wooden fences
forge:gems None Gems
forge:gems/amethyst forge:gems Amethyst gems
forge:gems/diamond forge:gems Diamond gems
forge:gems/emerald forge:gems Emerald gems
forge:gems/lapis forge:gems forge:enchanting_fuels Lapis gems
forge:gems/prismarine forge:gems Prismarine gems
forge:gems/quartz forge:gems Quartz gems
forge:glass None Glass
forge:glass/black None Black glass
forge:glass/blue None Blue glass
forge:glass/brown None Brown glass
forge:glass/colorless forge:glass Normal glass
forge:glass/cyan None Cyan glass
forge:glass/gray None Gray glass
forge:glass/green None Green glass
forge:glass/light_blue None Light blue glass
forge:glass/light_gray None Light gray glass
forge:glass/lime None Lime glass
forge:glass/magenta None Magenta glass
forge:glass/orange None Orange glass
forge:glass/pink None Pink glass
forge:glass/purple None Purple glass
forge:glass/red None Red glass
forge:glass/silica None Sand-based glass with minor ingredient variation
forge:glass/tinted forge:glass Tinted glass
forge:glass/white None White glass
forge:glass/yellow None Yellow glass
forge:glass_panes None Glass panes
forge:glass_panes/black None Black glass panes
forge:glass_panes/blue None Blue glass panes
forge:glass_panes/brown None Brown glass panes
forge:glass_panes/colorless forge:glass_panes Normal glass panes
forge:glass_panes/cyan None Cyan glass panes
forge:glass_panes/gray None Gray glass panes
forge:glass_panes/green None Green glass panes
forge:glass_panes/light_blue None Light blue glass panes
forge:glass_panes/light_gray None Light gray glass panes
forge:glass_panes/lime None Lime glass panes
forge:glass_panes/magenta None Magenta glass panes
forge:glass_panes/orange None Orange glass panes
forge:glass_panes/pink None Pink glass panes
forge:glass_panes/purple None Purple glass panes
forge:glass_panes/red None Red glass panes
forge:glass_panes/white None White glass panes
forge:glass_panes/yellow None Yellow glass panes
forge:gravel None Gravel
forge:gunpowder None Gunpowder
forge:heads None Heads
forge:ingots None Ingots
forge:ingots/brick forge:ingots Brick ingots
forge:ingots/copper forge:ingots Copper ingots
forge:ingots/gold forge:ingots Gold ingots
forge:ingots/iron forge:ingots Iron ingots
forge:ingots/netherite forge:ingots Netherite ingots
forge:ingots/nether_brick forge:ingots Nether brick ingots
forge:leather None Leather
forge:mushrooms None Mushrooms
forge:nether_stars None Nether stars
forge:netherrack None Netherrack
forge:nuggets None Nuggets
forge:nuggets/gold forge:nuggets Gold nuggets
forge:nuggets/iron forge:nuggets Iron nuggets
forge:obsidian None Obsidian
forge:ore_bearing_ground/deepslate None Blocks replaced by deepslate ores during world generation
forge:ore_bearing_ground/netherrack None Blocks replaced by netherrack ores during world generation
forge:ore_bearing_ground/stone None Blocks replaced by stone ores during world generation
forge:ore_rates/dense None Ores which produce numerous resources on average
forge:ore_rates/singular None Ores which produce a single resource on average
forge:ore_rates/sparse None Ores which produce less than a single resource on average
forge:ores None Ores
forge:ores/coal forge:ores Coal ores
forge:ores/copper forge:ores Copper ores
forge:ores/diamond forge:ores Diamond ores
forge:ores/emerald forge:ores Emerald ores
forge:ores/gold forge:ores Gold ores
forge:ores/lapis forge:ores Lapis ores
forge:ores/netherite_scrap forge:ores Netherite scrap ores
forge:ores/quartz forge:ores Quartz ores
forge:ores/redstone forge:ores Redstone ores
forge:ores_in_ground/deepslate None Ores which can be found in deepslate
forge:ores_in_ground/netherrack None Ores which can be found in netherrack
forge:ores_in_ground/stone None Ores which can be found in stone
forge:raw_materials None Raw materials
forge:raw_materials/copper forge:raw_materials Copper raw materials
forge:raw_materials/gold forge:raw_materials Gold raw materials
forge:raw_materials/iron forge:raw_materials Iron raw materials
forge:rods None Rods
forge:rods/blaze forge:rods Blaze rods
forge:rods/wooden forge:rods Wooden rods
forge:sand None Sand
forge:sand/colorless forge:sand Normal sand
forge:sand/red forge:sand Red sand
forge:sandstone None Sandstone
forge:seeds None Seeds
forge:seeds/beetroot forge:seeds Beetroot seeds
forge:seeds/melon forge:seeds Melon seeds
forge:seeds/pumpkin forge:seeds Pumpkin seeds
forge:seeds/wheat forge:seeds Wheat seeds
forge:shears None Shears
forge:slimeballs None Slimeballs
forge:stained_glass forge:glass Stained glass
forge:stained_glass_panes forge:glass_panes Stained glass planes
forge:stone None Stones
forge:storage_blocks None Storage blocks
forge:storage_blocks/amethyst forge:storage_blocks Amethyst blocks
forge:storage_blocks/coal forge:storage_blocks Coal blocks
forge:storage_blocks/copper forge:storage_blocks Copper blocks
forge:storage_blocks/diamond forge:storage_blocks Diamond blocks
forge:storage_blocks/emerald forge:storage_blocks Emerald blocks
forge:storage_blocks/gold forge:storage_blocks Gold blocks
forge:storage_blocks/iron forge:storage_blocks Iron blocks
forge:storage_blocks/lapis forge:storage_blocks Lapis blocks
forge:storage_blocks/netherite forge:storage_blocks Netherite blocks
forge:storage_blocks/quartz forge:storage_blocks Quartz blocks
forge:storage_blocks/raw_copper forge:storage_blocks Raw copper blocks
forge:storage_blocks/raw_gold forge:storage_blocks Raw gold blocks
forge:storage_blocks/raw_iron forge:storage_blocks Raw iron blocks
forge:storage_blocks/redstone forge:storage_blocks Redstone blocks
forge:string None String

Fluids

Name Super Tag(s) Contains
forge:milk None Milk