Pick Target References

Context: HL Kit … Kit Reference … Target References 

See Also: Pick Context Transitions

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[curr,init]	(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[grp,pick]	(Right, Number) The pick with unique id pick is assigned the identity tag from the tag group grp for the current pick context. This allows a script to explicitly identify a pick and assign an identity tag to it. The identity tag id is dictated by the initial context of the script. For more details, please check here. If the specified pick does not exist, a run-time error is reported. A value of zero is always returned. Example: perform this.shareidentity[ClassSkill,mypick]
pullidentity[grp]	(Right, Number) Locates the identity tag from the tag group grp for the current pick context and assigns it to the initial script context. The identity tag id is dictated by the initial context of the script. For more details, please check here. If the initial script context is neither a pick nor a container, a run-time error is reported. A value of zero is always returned. Example: perform this.pullidentity[groupid]
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) Returns non-zero if the pick satisfies all of its pre-requisites. May not be used during evaluation. Example: result = this.prereqok
prereqnum	(Right, Number) Returns the total number of pre-requisite rules that exist for the current pick. May not be used during evaluation. Example: result = this.prereqnum
prereqmsg[index]	(Right, String) Returns the message associated with a specific pre-requisite test for the current pick, where the desired test is given by index. The index is zero-based, so the values 0 through 4 should be used for a pick with 5 pre-requisites. If the individual pre-requisite is satisfied, the text returned is the empty string. Otherwise, the text returned is the corresponding message. May not be used during evaluation. Example: result = this.prereqmsg[i] NOTE! Retrieving the message for individual pre-requisite tests will trigger a re-calculation every time, so it is expensive and should only be used sparingly.
isgear	(Right, Number) Returns non-zero if the pick is a piece of gear. Example: result = this.isgear
isholdable	(Right, Number) Returns non-zero if the pick is gear that can be placed into a gear holder. Example: result = this.isholdable
isgearheld	(Right, Number) Returns non-zero if the pick is a piece of gear that is currently being held within another piece of gear. Example: result = this.isgearheld
gearcount	(Right, Number) Returns the total number of pieces of gear that are currently being held within the pick. If the pick is not a gear holder, the count will always be zero. Example: result = this.gearcount
gearpath[spl]	(Right, String) Generates and returns the entire gear containment hierarchy for this piece of gear. The hierarchy starts with the topmost gear holder of this pick and works downward through the immediate holder of the pick, showing the sequence. The generated string lists all the holders by name, inserting the splicing string spl between each name if there is more than one. A piece of gear that is not held will return the empty string. Example: result = this.gearpath["+"]
isgearlist	(Right, Number) Returns non-zero if the pick is a gear holder and can contain a list of held gear, regardless of whether any gear is actually held. Example: result = this.isgearlist
gearlist[spl,expr]	(Right, String) Generates and returns a list of gear held within the pick, provided the pick is a gear holder. Only picks that are designated as gear and that are assigned to this pick as their 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 pick that holds no gear matching the tag expression will return the empty string. Example: result = this.gearlist["+",!Equipment.Natural]
stackable	(Right, Number) Returns non-zero if the pick can be stacked with other equivalent picks. Example: result = this.stackable
isbootstrap[thing]	(Right, Number) Returns non-zero if the current pick directly bootstraps a pick with the specified id thing. Example: result = this.isbootstrap[thingid]
rootnames[spl]	(Right, String) Generates and returns a list of picks that bootstrap the current pick. The generated string appends the names of the root picks together, inserting the splicing string spl between each name if there is more than one. A pick with no root picks will return the empty string. Example: result = this.rootnames["+"]
islinkage[link]	(Right, Number) Returns non-zero if the current pick possesses a linkage with the specified id link. Example: result = this.islinkage[linkid]
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) Returns non-zero if the pick was added to the character during "creation" mode and zero if added during "advancement" mode. This makes it possible to validate options that are only seelctable during character creation. If advancement mode is not enabled for the game system, all picks are always added in creation mode. Example: result = this.creation
setfocus	(Right, Number) Establishes the current pick context as the new "pick focus". Thereafter, the script can use the "focus." initial context transition to directly access the pick that is setup as the focus. Always returns a value of zero. Example: perform this.setfocus
ispanel	(Right, Number) Returns non-zero is the pick has a panel linkage defined for it. This allows generic handling of panel linkages within component scripts when the actual panel linkage is optionally controlled by the thing. Example: result = this.ispanel
panelactive	(Right, Number) Returns non-zero if the current active tab panel is the one specified as a panel linkage for the current pick. If the pick has no designated panel linkage, zero is returned. Example: result = this.panelactive
sourcerefs[spl]	(Right, String) Generates and returns a list of all sources that the current pick is dependent upon. The generated string appends the names of the sources together, inserting the splicing string spl between each name if there is more than one. A pick with no source dependencies will return the empty string. Example: result = this.sourcerefs["+"]
dynareg[index]	(Right, Number) Registers a dynamic linkage to the current pick context and assigns that linkage the unique index value index. Once registered, the current pick can be accessed from the "hero" context via the "dynalink" context transition. This makes it possible to dynamically setup access to a special pick throughout an actor. This target reference can only be utilized from within a Creation Script. Always returns a value of zero. Example: perform this.dynareg[42]
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