Context Transitions

Context: HL Kit … Kit Reference 

Overview

Every script begins with an initial context that is dictated by the particular script. Quite often, though, you'll want to access information somewhere else within the data hierarchy. That's when context transitions come into play. A context transition allows you to move through the hierarchy, progressing to objects either above or below the current context. These transitions can be chained, allowing you to move through a sequence of contexts to reach the desired destination.

From within a given context, you are only able to transition to a specific set of other contexts. The sections below identify what the valid transitions are for each context.

NOTE! If transitions are utilized that result in an invalid (i.e. non-existent) context, any subsequent target reference will be invalid. If this occurs during run-time, the operation will be ignored and the target identifier will return zero. A suitable error will generally be displayed, but not always. An example of an invalid context is when a pick attempts to transition to a field that does not exist within that pick.

Using "this"

Every script has an initial context that is automatically established (see the specific script to know what it is). Normally, this context is implied, so you don't need to do anything to reference that context. However, some authors will want their scripts to clearly indicate when the implied context is being used. To accommodate this, scripts can utilize the reserved word "this" to indicate the implied context.

For example, an Eval Script starts with the pick as its implied context. So you could write a target identifier that checks the validity of that pick as simply "valid". Alternately, you could specify "this" as the context, yielding a target identifier of "this.valid". Either method is perfectly legal and you are welcome to use whichever method you prefer.

NOTE! The "this" reference identifies the implied context only. Therefore, you can only use "this" as the first context reference for a target identifier. If "this" is used anywhere else, a compilation error will occur.

Container Context

From within a "container" context, you can utilize the following set of valid context transitions:

state	Transitions to the state context. Example: "this.state".
hero	Transitions to the hero context corresponding to the hero that is the parent of the current container. If the current container is a hero, then this transition changes nothing but does resolve successfully. Example: "this.hero".
container	Transitions to the container context corresponding to whatever container is the immediate parent of the current container. If the current container is a hero, then the transition fails to resolve. Example: "this.container".
parent	Transitions to the pick context corresponding to the parent pick that attaches the container. If the container is a hero and has no parent pick, the transition fails to resolve. Example: "this.parent".
child[id]	Transitions to the pick context corresponding to the first pick within the container that derives from the thing with the id specified. If the container has no child pick with the given unique id, a run-time error notification is reported to the user and the transition fails to resolve. Example: "this.child[mypick]".
childfound[id]	Transitions to the pick context corresponding to the first pick within the container that derives from the thing with the id specified. This transition is identical to "child[id]", except that the existence of the child pick is optional. If the child is found, the transition occurs normally. If the child does not exist, no run-time error is reported, although the transition still fails to resolve. Example: "this.childfound[mypick]".
firstchild[expr,sort]	Transitions to the pick context corresponding to the first pick within the container that satisfies the tag expression given by expr. Since multiple children may satisfy the tag expression, an optional sort set id may be specified by sort, resulting in all matching children being sorted and the first child being used after the sort is performed. The tag expression may be either a literal string or a string expression. If no matching child exists, the transition fails to resolve. Example: "this.firstchild[expr,mysort]" or "this.firstchild[expr]".
anchor	Transitions to the pick context corresponding to the pick within the master actor that attaches the current actor as a minion. If the container does not reside within a minion, the transition fails to resolve. Example: "this.anchor".
master	Transitions to the hero context corresponding to the master actor for which this container is a minion. If the container is not a minion, the transition fails to resolve. Example: "this.master".
minion[id]	Transitions to the hero context corresponding to the minion actor with the given id that exists beneath the actor that possesses the current container. If the container is not a master or the specified minion does not exist, the transition fails to resolve. Example: "this.minion[myminion]".
herofield[id]	Transitions to the field context corresponding to the field given by id that exists on the "actor" pick for the containing actor. This is a shorthand notation for "hero.child[actor].field[id]". Example: "this.herofield[myfield]".
usagepool[id]	Transitions to the pool context corresponding to the usage pool given by id that exists within the container. This transition is only valid for actors, since gizmos do not possess usage pools. Example: "this.usagepool[mypool]".
transact	Transitions to the pick context corresponding to the transaction pick that is associated with the hero governing the current context. Example: "this.transact". NOTE! The transaction pick is only utilized within buy and sell transactions. As such, this transition is only valid within a few select scripts.
dynalink[index]	Transitions to the pick context corresponding to the registered dynamic linkage with the index specified. If no dynamic linkage has been registered with the given index, the transition fails to resolve. The index may be an arithmetic expression that calculates the actual index value to be used. Example: "this.dynalink[myindex]".

Hero Context

From within a "hero" context, you can utilize the following set of valid context transitions:

Pick Context

From within a "pick" context, you can utilize the following set of valid context transitions:

Thing Context

From within a "thing" context, you can utilize the following set of valid context transitions:

Field Context

From within a "field" context, you can utilize the following set of valid context transitions:

Pool Context

From within a "pool" context, you can utilize the following set of valid context transitions:

Scene Context

From within a "scene" context, you can utilize the following set of valid context transitions:

Layout Context

From within a "layout" context, you can utilize the following set of valid context transitions:

Template Context

From within a "template" context, you can utilize the following set of valid context transitions:

Portal Context

From within a "portal" context, you can utilize the following set of valid context transitions:

Value Context

From within a "value" context, you can utilize the following set of valid context transitions:

State Context

From within a "state" context, you can utilize the following set of valid context transitions:

Special Contexts

Within some scripts, special contexts are supported. These special contexts behave the same way within any script that uses them. However, what they correspond to may be different within each script. The specific scripts where special contexts can be used will explicitly cite the availability of the context in their description. Alternately, some special contexts can be established within a script via certain language mechanisms (e.g. "eachpick"). The behavior of these contexts is outlined below.

IMPORTANT! All special contexts must be specified at the start of an identifier. If not, they will not be acknowledged by the compiler. For example, if the "altpick" special context is supported by a script, the reference "altpick.field[livename].text" would work perfectly. However, the reference "this.altpick.field[livename].text" would fail to compile, since "altpick." is not given as the initial context for the identifier.