Container Target References

Context: HL Kit … Kit Reference … Target References 

There are a wide assortment of operations that can be performed on containers, some of which modify the container and some that simply retrieve information about the container. The complete list of these operations is presented in the table below.

NOTE! When a container is accessed from within a visual script, all operations are restricted to read-only behavior. Any attempts to modify a container from within a visual script will fail.

live	(Right, Number) Returns non-zero if the container is currently considered "live", else zero if non-live. The live state for a gizmo is dictated by the live state of its parent pick that attaches it, while a hero is always considered live. Example: result = this.live
ishero	(Right, Number) Returns non-zero if the container is a hero, else zero for a gizmo. Example: result = this.ishero
isactive	(Right, Number) Returns non-zero if the container either is or resides within the currently active actor within the HL interface. If the container is or resides within a different actor, zero is returned. Example: result = this.isactive
livename	(Right, String) Returns a suitable name for the container that is based on dynamic changes made via scripts. If the container is an actor, the name of the actor is returned, else the name of the parent pick of the gizmo is returned. Example: result = this.livename
actorname	(Right, String) Returns the name of the actor that encompasses the current container context. The name is whatever has been assigned by the user. Example: result = this.actorname
playername	(Right, String) Returns the name of the player that is associated with the current lead. The name is whatever has been entered by the user. Example: result = this.playername
setactor	(Right, Number) Memorizes the current actor context as the "actor focus", allowing it to be instantly accessed thereafter via the "actor." initial script context. The current container context must be an actor and not a gizmo. Always returns a value of zero. Example: perform this.setactor
assign[tag]	(Right, Number) Assigns the indicated tag to the container. The tag must be specified using the standard "group.id" syntax. The tag is verified to exist during compilation of the script. Always returns a value of zero. Example: perform this.assign[skill.appraise]
delete[tmpl]	(Right, Number) Deletes all tags from the container that match the tag template tmpl. The template must use the standard "group.id" syntax and may contain a wildcard. If the template employs a wildcard, all tags matching the template are deleted. If the template specifies an explicit tag, and the tag has been assigned to the container multiple times, the tag is deleted only once, thereby providing detailed control to authors when needed. Always returns a value of zero. Example: perform this.delete[skill.craft?]
assignstr[str]	(Right, Number) This target reference is identical to "assign", except that the str parameter is a string expression that is evaluated within the script. This allows the tag to be dynamically determined via the script instead of being hard-wired at compilation. Always returns a value of zero. Example: perform this.assignstr[skill.appraise]
deletestr[str]	(Right, Number) This target reference is identical to "delete", except that the str parameter is a string expression that is evaluated within the script. This allows the tag template to be dynamically determined via the script instead of being hard-wired at compilation. Always returns a value of zero. Example: perform this.deletestr["skill.craft?"]
tagis[tmpl]	(Right, Number) Returns non-zero if any tags assigned to the container match the tag template tmpl, else zero if no tags match. The template must use the standard "group.id" syntax and may contain a wildcard. Example: this.tagis[skill.?]
tagcount[tmpl]	(Right, Number) Returns the number of tags assigned to the container that match the tag template tmpl. The template must use the standard "group.id" syntax and may contain a wildcard. Example: result = this.tagcount[skill.?]
tagvalue[tmpl]	(Right, Number) Returns the value of a tag assigned to the container that matches the tag template tmpl. The rules associated with tag values in tag expressions apply. The template must use the standard "group.id" syntax and may contain a wildcard. Example: result = this.tagvalue[spelllevel.wizard?]
tagmin[tmpl]	(Right, Number) Returns the minimum value of all tags assigned to the container that match the tag template tmpl. The rules associated with tag values in tag expressions apply. The template must use the standard "group.id" syntax and may contain a wildcard. Example: result = this.tagmin[spelllevel.wizard?]
tagmax[tmpl]	(Right, Number) Returns the maximum value of all tags assigned to the container that match the tag template tmpl. The rules associated with tag values in tag expressions apply. The template must use the standard "group.id" syntax and may contain a wildcard. Example: result = this.tagmax[spelllevel.wizard?]
tagunique[tmpl]	(Right, Number) Returns the number of unique tags assigned to the container that match the tag template tmpl. If a tag is assigned multiple times, it is only counted once. The template must use the standard "group.id" syntax and may contain a wildcard. Example: result = this.tagunique[skill.?]
tagexpr[expr]	(Right, Number) Returns non-zero if the tags assigned to the container match the tag expression expr, else zero is returned. The expr parameter must be a valid tag expression. Example: result = this.tagexpr[class.wizard & (val:spelllevel.wizard? > 5)]
tagcountstr[str]	(Right, Number) This target reference is identical to "tagcount", except that the str parameter is a string expression that is evaluated within the script. This allows the tag template to be dynamically determined via the script instead of being hard-wired at compilation. Example: result = this.tagcountstr["skill.?"]
tagvaluestr[str]	(Right, Number) This target reference is identical to "tagvalue", except that the str parameter is a string expression that is evaluated within the script. This allows the tag template to be dynamically determined via the script instead of being hard-wired at compilation. Example: result = this.tagvaluestr["spelllevel.wizard?"]
tagminstr[str]	(Right, Number) This target reference is identical to "tagmin", except that the str parameter is a string expression that is evaluated within the script. This allows the tag template to be dynamically determined via the script instead of being hard-wired at compilation. Example: result = this.tagminstr["spelllevel.wizard?"]
tagmaxstr[str]	(Right, Number) This target reference is identical to "tagmax", except that the str parameter is a string expression that is evaluated within the script. This allows the tag template to be dynamically determined via the script instead of being hard-wired at compilation. Example: result = this.tagmaxstr["spelllevel.wizard?"]
taguniquestr[str]	(Right, Number) This target reference is identical to "tagunique", except that the str parameter is a string expression that is evaluated within the script. This allows the tag template to be dynamically determined via the script instead of being hard-wired at compilation. Example: result = this.taguniquestr["skill.?"]
tagsearch[str]	(Right, Number) This target reference is identical to "tagexpr", except that the str parameter is a string expression that is evaluated within the script. This allows the tag expression to be dynamically determined via the script instead of being hard-wired at compilation. Example: result = this.tagsearch["class.wizard & (val:spelllevel.wizard? > 5)"] NOTE! Using "tagsearch" is MUCH slower in performance than using "tagexpr", since the tagexpr must be parsed and compiled every time the script is evaluated. Be sure to use "tagexpr" whenever possible.
tagmatch[refgrp,match,ref]	(Right, Number) 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. For details, please see The "tagmatch" Target Reference. Example: result = hero.tagmatch[NeedStatus,HasStatus,initial]
intersect[init,curr]	(Right, Number) Returns non-zero if tags within the initial script context also exist within the currently transitioned context, else zero. All of the tags that belong to the init tag group within the initial script context are compared against the tags that belong to the curr tag group within the current context. If any of those tags possess the identical tag id, then a match is returned (i.e. non-zero). The same tag group may be used for both contexts, and both contexts must be objects that possess tags (i.e. container, pick, or thing). Example: result = this.interset[MyGroup,AltGroup]
inherit[id]	(Right, Number) The container inherits all tags from one or all of its child picks. If an id is given, then all tags from the pick with that id are inherited into the container. If no parameter is given, then all tags from all child picks are inherited. The return value is the total number of tags inherited. Example: result = this.inherit[mypick] Example: result = this.inherit
childexists[id]	(Right, Number) Returns non-zero if any child pick with the given id exists within the container, else zero if no matching pick is found. Example: result = this.childexists[mypick]
childlives[id]	(Right, Number) Returns non-zero if any child pick with the given id exists within the container and is "live". If either no matching pick is found or all matching picks found are "non-live", zero is returned. Example: result = this.childlives[mypick]
childcount[id]	(Right, Number) Returns the number of child picks with the given id that exist within the container. A value of zero indicates that no matching picks were found. Example: result = this.childcount[mypick]
haschild[str]	(Right, Number) Returns the number of child picks within the container that match the tag expression given by str. The parameter is a string expression that must contain a valid tag expression and is tested against all children of the container. The parameter can be synthesized dynamically within the script. Example: result = this.haschild["component.Skill"]
setidentity[grp]	(Right, Number) Assigns to the container the identity tag from the tag group grp that corresponds to the initial context of the script. The identity tag id is dictated by the initial context of the script. Example: result = this.setidentity[groupid]
isidentity[grp]	(Right, Number) As the counterpart of "setidentity", this target reference returns non-zero if the indicated identity tag has been assigned to the container and zero if not. The identity tag sought must be from the tag group grp and the tag id is dictated by the initial context of the script. Example: result = this.isidentity[groupid]
countidentity[grp]	(Right, Number) Similar to "isidentity", this target reference returns the count of the identity tags assigned to the container. The identity tag sought must be from the tag group grp and the tag id is dictated by the initial context of the script. Example: result = this.countidentity[groupid]
isminion	(Right, Number) Returns non-zero if the container is a minion, else zero. Example: result = this.isminion
ismaster	(Right, Number) Returns non-zero if the container is a master, else zero. Example: result = this.ismaster
hasminion[id]	(Right, Number) Returns non-zero if the container possesses a minion with the specified id. If the container is not a master or does not contain the specified minion, zero is returned. Example: result = this.hasminion[myminion]
isdynalink[expr]	(Right, Number) Returns non-zero if a dynamic linkage has been defined for the implied hero context with the index specified, else zero if no linkage exists. If the container is a gizmo, then the containing actor is used as the hero context. The value given by index may be an arithmetic expression that will be resolved properly at run-time. Example: result = this.isdynalink[4]
istransact	(Right, Number) Returns non-zero if a viable transaction context exists for the container. This allows scripts to check that a transaction context exists before attempting to transition into the transaction context. Example: result = this.istransact
panelvalid[id]	(Left, Number) Sets the validity state of the tab panel given by id. If the value assigned is zero, the panel is designated as non-valid and its name will be highlighted in red to the user. Since the default state of all panels is valid, if a non-zero value is assigned, this target reference is ignored. This means you can simply designate a panel as invalid when appropriate and do nothing when the panel is valid. Example: result = this.panelvalid[mypanel] NOTE! This target reference can only be used from within an Eval Rule or a Validate script.
tagnames[tmpl,spl]	(Right, String) Generates and returns a list of tags within the container. Only tags that match the tag template tmpl are included in the list. The generated string appends the names of the tags together, inserting the splicing string spl between each name if there is more than one. A container with no tags matching the template will return the empty string. Example: result = this.tagnames[Weapon.?,"+"]
tagabbrevs[tmpl,spl]	(Right, String) Works identically to "tagnames", except that the generated string is comprised of the abbreviations for all matching tags instead of their names. Example: result = this.tagabbrevs[Weapon.?,"+"]
tagids[tmpl,spl]	(Right, String) Works identically to "tagnames", except that the generated string is comprised of the unique ids for all matching tags instead of their names. Example: result = this.tagids[Weapon.?,"+"]
weight	(Right, Number) Returns the total weight of all "gear" picks within the container. Example: result = this.weight
gearlist[spl,expr]	(Right, String) Generates and returns a list of gear held within the container. Only picks that are designated as gear and that are not assigned to a holder are candidates for inclusion in the list. Each candidate piece of gear is compared against the tag expression expr, and only those that satisfy the tag expression are included in the final list. The generated string appends the names of all pieces of gear together, inserting the splicing string spl between each name if there is more than one. A container that holds no gear matching the tag expression will return the empty string. Example: this.gearlist["+",!Equipment.Natural]
geartree[expr]	(Right, String) Generates and returns a hierarchical tree view of the gear picks possessed by the container context, as appropriate for use within the Dashboard and Tactical Console. Only picks that are designated as gear are candidates for inclusion in the report. Each candidate piece of gear is compared against the tag expression expr, and only those that satisfy the tag expression are included in the final report. All gear is output in a hierarchy, where each level of containment is indented beneath the level above it. Gear within child gizmos is also included, with indentation as if the gizmo were a holder within the container and its contents indented beneath it. Example: result = this.geartree[!Helper.NoMove]
miniontext	(Right, String) Returns the name of the thing that attaches the current minion. This makes it possible to retrieve the nature of the minion for display to the user. If invoked on a gizmo, an error is reported. If invoked on a lead, an empty string is returned. Example: result = this.miniontext
sourcetree	(Right, String) Returns a summary of the various user-selected sources that have chosen for the current actor. This is intended for inclusion within character sheet output. The summary is synthesized solely from sources that are user-selected, although the entire chain of sources down to each selected source is included so that context is provided in case similar names are used in different contexts. Any source that is designated as not reportable is omitted from the summary, allowing sources governing printout and interface behaviors to be omitted. If a source specifies an alternate "reportname", that name is used instead. If a gizmo is the context, the containing actor context is used. Example: result = this.sourcetree
errorcount	(Right, Number) Returns the total number of validation errors that were reported within the hero over the course of evaluation. This is intended for use within character sheet output. If accessed from within a gizmo or during evaluation processing, a run-time error is reported. Example: result = this.errorcount
errorlist	(Right, String) Returns a string containing all validation errors for the hero, based on the most recent evaluation cycle. This is intended for use within character sheet output. If accessed from within a gizmo or during evaluation processing, a run-time error is reported. Example: result = this.errorlist
combatant	(Right, Left, Number) Indicates whether the actor is managed as a combatant or not within the Tactical Console, with a non-zero value indicating a combatant. If a new value is assigned, the combatant state of the actor is changed. Example: result = this.combatant Example: this.combatant = 0
initchange	(Right, Number) Returns non-zero if the actor's current initiative value has been modified by the user. Example: result = this.initchange
ismoveup	(Right, Number) Returns non-zero if the actor can be moved upwards within the Tactical Console, thereby adjusting its initiative value. Example: result = this.ismoveup
ismovedown	(Right, Number) Returns non-zero if the actor can be moved downwards within the Tactical Console, thereby adjusting its initiative value. Example: result = this.ismovedown
combatmove[expr]	(Right, Number) Moves the actor upwards or downwards within the Tactical Console, thereby adjusting its initiative position. The number of slots to move is given by the numeric expression expr, with a positive value moving the actor later in the initiative sequence and a negative value earlier. To move an actor down in the order (i.e. later in combat), use "+1", and use "-1" to move the actor upwards. To move an actor to the top or bottom of the initiative order, simply use a very large value, as the engine will safely bound all adjustments. Always returns a value of zero. Example: perform this.combatmove[-1]
combatmovenow
combatact
combatdefer