Pick Target References

Context: HL Kit … Kit Reference … Target References 

Picks are going to be the most prevalent object type within any set of data files, so it's no surprise that picks have the largest and most varied assortment of target references. The complete list of target references for picks is presented in the table below.

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

livename	(Right, String) Returns an appropriate name for the pick. If the user has explicitly named the pick, that name is returned. If not named by the user, any name change dictated by scripts is returned. Otherwise, the name of the thing is used. Example: result = this.livename
idstring	(Right, String) Returns the unique id of the thing as a string. This can be extremely handy when synthesizing tag templates and tag expressions on-the-fly via scripts. Example: result = this.idstring
valid	(Right, Number) Returns non-zero if the pick is valid and zero if the pick has been designated as non-valid. Validity is controlled via mechanisms like pre-requisite tests and Eval Rules. Example: result = this.valid
isuser	(Right, Number) Returns non-zero if the pick was directly added by the user, else zero. Picks that are bootstrapped by containers or other picks are not considered user-added, even if the pick that does the bootstrapping is user-added. Example: result = this.isuser
ispick	(Right, Number) Returns non-zero if the current context is a pick and zero if it's a thing. This provides a means to discern the nature of the context when the circumstances make a distinction uncertain, such as within procedures. Example: result = this.ispick
isroot	(Right, Number) Returns non-zero if the pick has been bootstrapped and therefore has a root pick available. Example: result = this.isroot
isgizmo	(Right, Number) Returns non-zero if the pick directly attaches a child gizmo. Example: result = this.isgizmo
isunique	(Right, Number) Returns non-zero if the pick behaves as unique. Example: result = this.isunique
shadowed	(Right, Number) Returns non-zero if the pick has been shadowed and also exists within an alternate container. Example: result = this.shadowed
displaced	(Right, Number) Returns non-zero if the pick has been displaced and also exists within an alternate container. Example: result = this.displaced
countme	(Right, Number) Returns the total number of instances of the current pick that exist within the container of the current pick. As long as the thing id matches, two picks are considered equivalent. If stacking is utilized, this target reference returns the total number of distinct picks within the container, ignoring all stacked quantities. Example: result = this.countme
uniqcount	(Right, Number) Return the number of times that a unique pick has been added to the current container. Every time a unique pick is added, whether by the user or via bootstrapping, it's reference count is incremented, and this target reference returns the reference count. If the pick is not unique, a run-time error is reported and zero is returned. Example: result = this.uniqcount
assign[tag]	(Right, Number) Assigns the indicated tag to the pick. 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 pick 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 pick 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 pick 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 pick 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 pick 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 pick 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 pick 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 pick 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 pick 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 more details, please check here. 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]
pulltags[tmpl,grp]	(Right, Number) Copies tags from the transitioned pick context into the initial pick context and returns the total number of tags copied. The set of tags to be copied from the transitioned pick context are dictated by the tag template tmpl. If the second parameter is omitted, the identified tags are copied to the initial pick context. If the second parameter is provided, grp must specify a tag group. All tags identified by tmpl are mapped to equivalent tags within the tag group grp, and those mapped tags are then assigned to the initial pick context. When mapping, an equivalent mapped tag must exist for all identified tags. Both the initial and transitioned script context must be picks. Example: result = this.pulltags[thingid.?] Example: result = this.pulltags[thingid.?,Ability]
pushtags[tmpl,grp]	(Right, Number) Copies tags from the initial pick context into the transitioned pick context and returns the total number of tags copied. This target reference is identical in behavior to "pulltags", except that the tags are copied in the opposite direction. Example: result = this.pushtags[thingid.?] Example: result = this.pushtags[thingid.?,Ability]
forward[tmpl,target]	(Right, Number) Copies tags from the pick context into the corresponding container and returns the total number of tags copied. The set of tags to be copied are dictated by the tag template tmpl. The tags are copied to the container dictated by target, which must be one of the following values: parent – Tags are copied to the standard parent container of the pick. shadow – Tags are copied to the shadow container of the pick, which is only applicable when the pick has been shadowed. origin – Tags are copied to the origin container of the pick, which is only applicable when the pick has been displaced. The target parameter may be omitted, in which case all tags matching the tag template are copied to the "parent" container. Both parameters may also be omitted, in which case all tags within the pick are copied to the "parent" container. Example: result = this.forward[thingid.?,shadow] Example: result = this.forward[thingid.?] Example: result = this.forward
setidentity[grp]	(Right, Number) Assigns to the pick 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. For more details, please check here. 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 pick 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. For more details, please check here. 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 pick. The identity tag sought must be from the tag group grp and the tag id is dictated by the initial context of the script. For more details, please check here. Example: result = this.countidentity[groupid]
shareidentity[	(Right, Number)
pullidentity[	(Right, Number)
tagnames[tmpl,spl]	(Right, String) Generates and returns a list of tags within the pick. 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 pick 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.?,"+"]
prereqok	(Right, Number)
prereqnum	(Right, Number)
prereqmsg[	(Right, String)
isgear	(Right, Number)
isgearheld	(Right, Number)
gearcount	(Right, Number)
gearpath[	(Right, String)
isgearlist	(Right, Number)
gearlist[	(Right, String)
isholdable	(Right, Number)
stackable	(Right, Number)
isbootstrap[	(Right, Number)
islinkage[	(Right, Number)
autonomous	(Right, Number) Returns non-zero if the pick has zero other picks that are currently based upon it. Picks that have other picks based upon them are typically made non-deletable, so this target reference provides a means to detect that condition. Example: result = this.autonomous
creation	(Right, Number)
setfocus	(Right, Number)
ispanel	(Right, Number)
panelactive	(Right, Number)
sourcenames[	(Right, String)
sourcerefs[	(Right, String)
dynareg[	(Right, Number)
isminion	(Right, Number) Returns non-zero if the pick resides within a minion, else zero. Example: result = this.isminion
ismaster	(Right, Number) Returns non-zero if the pick resides within a master, else zero. Example: result = this.ismaster
hasminion[id]	(Right, Number) Returns non-zero if the pick resides within an actor that possesses a minion with the specified id. The parameter can be omitted, in which case non-zero is returned only if the pick directly attaches a minion. If the pick is not within a master or the specified minion does not exist, zero is returned. Example: result = this.hasminion[myminion] Example: result = this.hasminion