Nat_VS Posted April 29 Report Posted April 29 Collectible & Entity Tags (from 1.22.0) Hi all, The team has had some questions about the new tag system that is being used throughout the assets, so I have collated some information about what they are, what they do, and how/why you should be using them. What are tags? A tag is, simply put, a small piece of text (a string for the coders) that can be attached to an itemtype, blocktype, or entity type. Tags are quite arbitrary, and their purpose is usually determined through other JSON assets or specific pieces of code. In general, tags are being used to describe an object’s use, shape, size, color, crafting capabilities, and more. An item, block, or entity can have a number of tags listed in its appropriate JSON file. What do they do? Currently, tags are being used for satisfying certain conditions in other systems. The two primary examples of this are to satisfy items for recipes, and to satisfy valid entities for AI tasks that require a target. A set of one or more tags (called a ‘TagSet’) can be compared against other TagSets. Specifically, TagSets can either use a basic matching system (e.g. does TagSet A have any of the tags in TagSet B), or tags can be compared against a “ComplexTagCondition”. This allows a group of tags to be matched like boolean properties, using JSON properties like “anyOf”, “allOf”, or “noneOf. The capabilities of the tag system, however, go much further, and I am personally excited to see what directions this new system may take us in. Why should we use them? There are three major reasons that you should be using tags. Runtime efficiency, mod compatibility, and expandability Runtime Efficiency On the surface, tags may appear to be a set of strings that are compared with each other. However, they are programmed in such a way that makes them extremely efficient to be compared, with some parts of the system using a highly efficient method called SIMD. By restricting the maximum number of tags allowed (255 for entities and 65535 for collectibles), tags can be compared extremely quickly, much faster than matching codes and variants. Compatibility Mods can make great use of the tag system. As the tag system develops, certain functionality that requires multiple steps to add to an object may be done with a single tag. Take an example: Before 1.22, to make an axe that worked in the current axe recipes, you would have to either register the new axe item in the game domain, or create an entire new set of recipes for your modded axe. This is not ideal. It takes a lot of time to do, and is much more susceptible to bugs. Now, in 1.22, the new axe can have the “tool-axe” tag. All recipes that need an axe will now be satisfied by that item. No extra recipes, no changing domain, no problems later on. This isn’t all. Mods can define their own tags in recipes for other mods to make use of. In the same example, if Mod A created a recipe that required an object with the “tool-axe” tag, then the recipe will work for any vanilla axes, as well as any other mod that uses the “tool-axe” tag. Looking for a different tag in the recipe is simple, and mods can begin interacting with each other in much more effective ways by using the tags system. Expandability As mentioned earlier, tags allow the team and modders to add content much faster and easier than other implementations. By using tags instead of variants, we can satisfy lists of objects without having to search for block codes and variants. How can you use them? In Content Mods Content mods are likely going to see the most benefit from the tag system right now. As mentioned earlier, tags can be used in recipes for pattern matching, target-able AI tasks, and some others. See the “Using Tags (Content)” page on the wiki for more information and examples on how to use them in a content mod. This page also contains some relevant technical information. In Code Mods Code mods can define their own tag sets in code and use these to check for conditions, but all tags must be registered during or before RunPhase.AssetsReady. See the “Using Tags (Code)” page on the wiki for more information and examples on how to use them in a code mod. This page also contains some relevant technical information. Conclusion Tags are a new system that is quite different to how things have been working in the past, but they are worth using. Over time, more systems may end up using tags and I am hopeful that the advantages of using tags will outweigh the changes to the older systems. Lastly, make sure to take a read of the following pages for more information on using tags: https://wiki.vintagestory.at/Modding:Using_Tags_(Content) https://wiki.vintagestory.at/Modding:Using_Tags_(Code) If you have any questions about tags, or would like to give your opinion on the new system, then please reply to this post. Thanks, Nat 2
CaptainFemboy Posted April 29 Report Posted April 29 Are there plans to eventually move most of the base game over to using tags for collectables and recipes? Like the example you gave for the axe, but for things that currently don't have tags (IE metal nails and strips). I'm wondering since right now adding something like a new metal either needs heavy patching or redefining every single recipe that might use your metal in any way, and tags on almost everything in the base game would really help with this. I'm really liking having tags so far though! While I haven't personally used any (yet), they're use cases are all over the place!
Recommended Posts