Keen:Item Tags

OFFICIAL CONTENT NOTICE 

OFFICIAL CONTENT

This article contains official content from or verified by the developers at Keen Software House. This information is intended to be accurate at the time it is posted, but may become obsolete over time. If you find errors in this article please describe the errors in the Discussion Page.

Item tags are a system that allows you to consider some items as equivalents for some action. The items still can be used explicitly, but the tag system allows a lot of convenience and even inter-compatibility between mods.

Version:

0.6.1

How to use

Using tags is very simple. You need to make sure a tag with the given name exists and then just apply it to the item in question. To learn more about various item types, refer to the Items Guide.

Item tags have very simple definitions, which only contain visual information about them.

<Definition xsi:type="MyObjectBuilder_ItemTagDefinition">
  <Id Type="ItemTagDefinition" Subtype="Stone"/>
  <DisplayName>Stone</DisplayName>
  <Description>A stone-like item.</Description>
  <Icon>Textures\GUI\Icons\Items\StoneSmall.dds</Icon>
</Definition>

Id: as any other definition, this one also has the mandatory Id. If you want other mods to be compatible with your tags, it is best to not have any special prefix and follow the tag naming guidelines. If you don't want, or care about, other mods being compatible with your tag, name it however you want.

DisplayName: name that will be displayed in places where this tag is used (crafting, quests, etc..).

Description: if this tag needs some explanation or cool flavor text, this field is your friend.

Icon: icon that is displayed for this tag. Some places may have special behavior and not use this icon, but it is still advised to have one.

NOTICE: As you can see, the tag definition does not include any items. This is because each item decides its tags in its own definition.

When to use

A good example from the base game are timber blocks. The game has 3 main timber types: Timber, Round Timber, and Diagonal Timber. For most uses of timber, such as the construction of large blocks, it does not really matter which one you use, you just want some timber, not necessarily a specific kind of timber. The game contains the item tag Timber precisely for this reason. Any place that does not care about a specific type of timber, just "some kind of timber", can use Tag="Timber" instead.

Now imagine you want to add a new kind of tree to the game. For the sake of this example, it is going to be a birch, because it provides a visually distinct wood from the base timber. Because of the big visual distinction, you want to use it for your castle building, to provide some contrast. So you define Birch Timber, Round Birch Timber, and Diagonal Birch Timber to cover all of your decorative uses of it. But you still want to use it to build the regular blocks that need timber. All you need to achieve this compatibility is adding xml <Tag>Timber</Tag> to your newly defined timber block items.

After some time you make your own birch-colored variants of Small Chest and Large Chest, and you only want to be able to use your birch wood to craft those chests. This can be solved by introducing a new TimberBirch tag and adding it to your birch timber variants. Then you just need to modify the crafting recipe for your Small Birch Chest and Large Birch Chest to use that tag instead of whatever you used before.

How to name

The item tag system is not meant to be used within the base game only, but it is also meant to be used by mods. To ensure the best compatibility between mods, it is therefore important to use a common naming scheme for these tags. That way, if multiple mods introduce the same type of resource, maybe Aluminium Ingot, they can be used interchangeably, assuming all of those mods tag that item with a IngotAluminium tag. There will still be multiple items called Aluminium Ingot in the game, but now they will be considered equivalent when it comes to recipes that use their tag.

The name should consist of maximum three parts [Type][Material][Other], in exactly that order. There is no need to always use all of the parts and a general rule of thumb is using as few as possible. The only part that should always be present in a tag is [Type].

Examples:

Tag	Description
Ingot	Any kind of ingot, since no material is specified (iron ingot, aluminium ingot, nickel ingot, etc.)
IngotAluminium	An ingot made of aluminium
TimberBirch	A timber made of birch wood (birch timber, round birth timber, etc.)
DustIron	Iron crushed into dust, likely usable for ingot casting
OreNickel	Nickel ore, probably mined from nickel ore voxels
Sword	Any sword type (iron sword, wooden sword, broken sword, etc.)
Stone	Any type of stone (small, large, etc.)
StoneHuge	Any type of huge stone (huge stone, huge sandstone, huge basalt, etc.)
OreIronRich	A piece of iron ore probably mined from a very rich iron vein
BrickStone	A stone brick (stone brick, sandstone brick, etc.)
Brick	Some brick (stone brick, clay brick, etc.)
Dye	Some form of a dye (blue dye, magenta dye, black dye, etc.)
DyeRed	A red dye of some sort (pressed berries, cactus fruit extract, etc.)

NOTICE: If your item tag name has more than three parts, you should rethink that name.

How not to use

Item tags are very versatile and usable in various situations. There is not necessarily a wrong use for them from the technical standpoint, but there are some wrong usages from the conceptual point of view.

Bad Examples:

Tag	Description
Gold:10	This probably means something has the value of 10 gold. It is wrong because this kind of usage requires parsing the subtype into substrings, and that is a very bad practice in any subtype.
LargeSmallHardStone	Very specific name, not adhering to naming guidelines.
Item	Incredibly vague tag name. If you need any item, you are better off creating a custom check instead.