Thing Context

Context: HL Kit … Kit Reference  … Multiple Sources

Jump to: Target References

The "thing" context represents a thing that has not been added to the portfolio. The thing context is very similar to the pick context in behavior, with the only real difference being that the dynamic facets of picks don't exist for things, resulting in many valid actions for picks being inaccessible from things.

Context Transitions

A "thing" context is very similar to a "pick" context, except that a "thing" context represents a thing that has not yet been added to a container and therefore lacks any dynamic state. As a result, the "thing" context is much more restrictive than the "pick" context. From within a "thing" context, you can utilize the following set of valid context transitions:

state	Transitions to the state context. Example: this.state
field[id]	Transitions to the field context corresponding to the field within the current thing that has the id specified. If the given field does not exist for the current thing, the transition fails to resolve. Example: this.field[myfield] NOTE! Within things and picks, there are a number of pre-defined pseudo-fields that are always defined and that allow access to facets of the pick that are not governed by user-defined fields. These pseudo-fields behave like normal fields in all respects within scripts, except that some are read-only. The list of pre-defined fields can be found elsewhere in the Kit Reference documentation.
linkage[id]	Transitions to the pick context corresponding to the linkage with the id specified. If the linkage is not defined, an error is reported. Example: this.linkage[mylink]

Target References

There are a number of target references that apply to things that have not been added to a container. These come into play at times like testing pre-requisites and when things are selected via menus. While similar to picks in many ways, things have no dynamic facets and are therefore always read-only in behavior. The complete list of target references for thing is presented in the table below.

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
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
isunique	(Right, Number) Returns non-zero if the thing behaves as unique. Example: result = this.isunique
isentity	(Right, Number) Returns non-zero if the thing directly attaches a child entity. Example: result = this.isentity
tagis[tmpl]	(Right, Number) Returns non-zero if any tags assigned to the thing 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 thing 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 thing 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 thing 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 thing 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 thing 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 thing 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]
tagnames[tmpl,spl]	(Right, String) Generates and returns a list of tags within the thing. 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 thing 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 thing 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
stackable	(Right, Number) Returns non-zero if the thing can be stacked with other equivalent picks. Example: result = this.stackable
isbootstrap[thing]	(Right, Number) Returns non-zero if the current thing directly bootstraps a thing with the specified id thing. Example: result = this.isbootstrap[thingid]
islinkage[link]	(Right, Number) Returns non-zero if the current thing possesses a linkage with the specified id link. Example: result = this.islinkage[linkid]
ispanel	(Right, Number) Returns non-zero if the thing 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
sourcerefs[spl]	(Right, String) Generates and returns a list of all sources that the current thing 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 thing with no source dependencies will return the empty string. Example: result = this.sourcerefs["+"]
amendthing[targ,str]	(Right, String) Modifies the name or description of the thing henceforth for the current actor. Once amended, all subsequent references to the thing will return the new contents. This includes the details shown within chooser tables that display things for selection by the user. The targ parameter must be either "name" or "description", specifying which facet of the thing is being amended. The new contents are given by the string expression str. Always returns a value of zero. Example: result = this.amendthing[name,"New Name"] NOTE! The amendment is applied to the thing at the time of evaluation, so any access of the name or description on derived picks prior to the amendment will not show the effects of the amendment. All amendments persist until the start of the next evaluation cycle, at which time they are all reset. NOTE! Each actor maintains its own set of amendments, so it is perfectly valid to have multiple different actors with different amendments to the same thing.