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.

   -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