The "tagmatch" Target Reference

Context: HL Kit … Kit Reference … Target References  … Multiple Sources

Overview

The purpose of the "tagmatch" target reference is to allow tags from one script context to be verified to exist within another script context. This makes it possible to easily perform tag-based comparisons between two objects. And that allows you to perform validations that one object complies with the requirement imposed by another object. For example, user-selected options on a hero might dictate requirements by assigning tags to the hero, while other options might be dependent on those requirements. By using "tagmatch", you can easily verify that the dependent options comply with the requirements by simply using two sets of tags.

Behavior

Let's first look at how the mechanism works on a conceptual level. The tags in two separate script contexts are being compared. The first context is referred to as the "reference" context and the second context is the "match" context. The reference context identifies a tag and a corresponding tag will then be sought within the match context. A match is declared if the corresponding tag is found within the match context.

A critical detail here is that different tag groups can be used within each of the two contexts. One tag group can be used within the reference context, and a separate tag group can be used within match context. This makes is possible to have one set of tags for dictating requirements and another set of tags for determining which requirements are actually satisfied.

The Mechanics

The syntax of the "tagmatch" target reference is below:

tagmatch[refgroup,matchgroup,refcontext]

The reference and match contexts are dictated by the initial script context and the transitioned script context, but not necessarily respectively. The refcontext parameter identifies which of those two contexts is considered the reference context. If the value "initial" is used, the initial script context is the reference context, while the value "current" indicates the currently transitioned script context is the reference context.

Two separate tag groups are given by the first two parameters, although the same tag group can be specified for both if you wish. The refgroup parameter identifies the tag group to be used within the reference context. The matchgroup parameter identifies the tag group to be used within the match context.

When processing the "tagmatch" target reference, the engine starts by identifying the first tag belonging to the refgroup tag group that exists within the reference context. The id of this tag is then saved. Next, the engine looks for any tag with the same id that belongs to the match tag group within the match context. If any matching tag is found, a non-zero value is returned, else zero.

NOTE! If the reference context contains no tag that belongs to the refgroup tag group, a successful match is automatically reported. A matching tag within the match context is only sought if there is actually something to be matched.

NOTE! Both the initial context and the transitioned context must be objects that possess tags. That means that both must a container, pick, or thing. If either context does not possess tags, an error is reported.

Example

To wrap up, let's look at a concrete example. In the World of Darkness game system, Vampire characters can possess an assortment of abilities, and some of those abilities require that the character achieve status within their order. The status is handled via one game mechanic, while abilities are handled by a completely different mechanic, yet the dependency must be validated.

To handle this, the data files define one tag group that governs the required status and another that governs the status that is possessed. We'll call these "NeedStatus" and "HasStatus", respectively. When status is conferred in an order, the hero is assigned the appropriate "HasStatus" tag (e.g. "HasStatus.MyOrder"). When an ability requires status in an order, it is assigned the appropriate "NeedStatus" tag (e.g. "NeedStatus.MyOrder").

With both sets of tags in place, it becomes easy to verify whether the hero satisfies the requirements of a particular ability using "tagmatch". The ability determines the required tag within the "NeedStatus" group and then compares it against the "HasStatus" tags possessed by the hero. The resulting line of script code would look similar to the one below, with the assumption that the script is associated with the ability, such as within a component script.

result = hero.tagmatch[NeedStatus,HasStatus,initial]

Let's break this line of script code down in detail.

1. Based on the code, the starting script context is the ability and the current script context is the hero.
2. The last parameter to "tagmatch" is "initial", which means that the reference context is the starting context (i.e. the ability) and the match context is the current context (i.e. the hero).
3. The reference tag group is "NeedStatus", so the engine looks for the first tag belonging to that group that exists within the reference context (the ability). We'll assume it finds a "NeedStatus.MyOrder" tag there.
4. The match tag group is "HasStatus", so the engine now looks for the tag "HasStatus.MyOrder" within the match context (the hero). The id of the tag is dictated by the reference tag identified above, but the group id is dictated by the "tagmatch" target reference.
5. The final value returned indicates whether the "HasStatus.MyOrder" tag exists within the hero.