The "tagmatch" Target Reference
Context: HL Kit … Kit Reference … Target References … Multiple Sources
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.
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.
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 "StatusReq" and "Status", respectively. When status is conferred in an order, the hero is assigned the appropriate "Status" tag (e.g. "Status.MyOrder"). When an ability requires status in an order, it is assigned the appropriate "StatusReq" tag (e.g. "StatusReq.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 "StatusReq" group and then compares it against the "Status" 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[StatusReq,Status,initial]
Let's break this line of script code down in detail.
- Based on the code, the starting script context is the ability and the current script context is the hero.
- 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).
- The reference tag group is "StatusReq", 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 "StatusReq.MyOrder" tag there.
- The match tag group is "Status", so the engine now looks for the tag "Status.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.
- The final value returned indicates whether the "Status.MyOrder" tag exists within the hero.
-Identifies the first matching tag for a given tag group within a "reference"
context and then searches for an equivalent tag of a potentially different
tag group within a "match" context
Returns non-zero if any tags within a reference context also exist within a match context, else zero. This allows tags from one context to be verified to exist within another context, making tag-based comparisons between two objects possible. The reference and match contexts are dictated by the initial script context and the transitioned script context. The ref parameter identifies which of those two contexts is considered the reference context for the target reference. If the value "initial" is used, the initial script context is the reference context, while the value "current" indicates the current transitioned script context is the reference context. A tag group within the reference context is given by refgrp and another tag group within the match context is given by match. The engine identifies the first tag belonging to the refgrp tag group within the reference context and saved the id of the tag. Then the engine looks for any tag with the same id that belongs to the match tag group within the match context (i.e. the group may be different, but the tag id is the same). If any matching tag is found, a non-zero value is returned, else zero.
-The "tagmatch" script target reference provides the means to match tags from one
context with the tags in another context
-Identifies the first matching tag for a given tag group within a "reference"
context and then searches for an equivalent tag of a potentially different
tag group within a "match" context
-The initial script context and the current script context are the two
contexts that are used, with one being designated as "reference" and the
other as "match" context
-If the reference context has no tag in the reference tag group, a successful
match is reported (a match is only sought if there is something to be
actually matched)
-Syntax is "tagmatch[refgroup,matchgroup,refcontext]"
-"refgroup" is id of tag group to be used within the reference context
-"matchgroup" is id of tag group to used within the match context
-"refcontext" indicates which context is to be considered the "reference"
context and the value must be either "initial" or "current"
-Accessible within container, pick, and thing script contexts
-Initial context must provide a container/pick/thing else error reported
-Allows tags from one context to be verified to exist within another, much
like the "needtags" and "denytags" mechanism works on tables/choosers
-Example: "tagmatch[StatusReq,Status,current]"
-Since the reference context is the "current" context, the tag to be
matched is pulled from the current script context and a matching tag
is sought within the initial script context
-Identifies the first tag belonging to the "StatusReq" tag group within
the current script context
-Looks for a tag with the same tag id but belonging to the "Status" tag
group within the initial script context
-If equivalent tag is found, a non-zero value is returned, else zero
