Difference between revisions of "Context Transitions"

Latest revision as of 17:01, 7 December 2008

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.

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.

Transitions By Context

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

• Container Context Transitions
• Hero Context Transitions
• Pick Context Transitions
• Thing Context Transitions
• Field Context Transitions
• Pool Context Transitions
• Scene Context Transitions
• Layout Context Transitions
• Template Context Transitions
• Portal Context Transitions
• Table Context Transitions
• Value Context Transitions
• State 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.

eachpick	The "eachpick" context only applies within the context of a "foreach" statement and represents the pick that is currently being iterated upon by the "foreach" statement. The current pick is accessed via the "eachpick." initial context. When used, the script context is switched to the iterated pick, and all subsequent actions are performed relative to that pick.
altpick	The "altpick" context represents an alternate pick that is integral to the script and can be accessed readily. The alternate pick is accessed via the "altpick." initial context. When used, the script context is switched to the alternate pick, and all subsequent actions are performed relative to that pick.
altthing	The "altthing" context represents an alternate thing that is integral to the script and can be accessed readily. The alternate thing is accessed via the "altthing." initial context. When used, the script context is switched to the alternate thing, and all subsequent actions are performed relative to that thing.
focus	The "focus" context only applies when the "setfocus" target reference is utilized on a pick context to establish that pick as a memorized context. The established focus pick context is accessed via the "focus." initial context, after which the script context changes to that pick and all subsequent actions are performed relative to that pick.
actor	The "actor" context only applies when the "setactor" target reference is utilized on a hero context to establish that hero as a memorized context. The established actor context is accessed via the "actor." initial context, after which the script context changes to that actor and all subsequent actions are performed relative to that actor. IMPORTANT! This is a situation where there is a critical distinction between "hero" and "actor". The "actor" context only applies to whatever actor has been established as the "actor focus".
transaction	The "transaction" context represents an alternate pick that is integral to scripts involved in buy and sell transactions of objects. The alternate pick is accessed via the "transaction." initial context. When used, the script context is switched to the alternate pick, and all subsequent actions are performed relative to that pick.

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.