|
|
| (9 intermediate revisions by the same user not shown) |
| Line 4: |
Line 4: |
| | | | |
| | 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. | | 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. | | {{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. |
| Line 17: |
Line 15: |
| | {{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. | | {{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{{anchor|container}}== | + | ==Transitions By Context== |
| | | | |
| − | From within a "container" context, you can utilize the following set of valid context transitions: | + | 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. |
| | | | |
| − | :{| class="infotable"
| + | *[[Container Context#transitions|Container Context Transitions]] |
| − | |class="leftnormal"|state
| + | *[[Hero Context#transitions|Hero Context Transitions]] |
| − | |Transitions to the [[#state|state context]].<br>
| + | *[[Pick Context#transitions|Pick Context Transitions]] |
| − | Example: this.state
| + | *[[Thing Context#transitions|Thing Context Transitions]] |
| − | |-
| + | *[[Field Context#transitions|Field Context Transitions]] |
| − | |hero
| + | *[[Pool Context#transitions|Pool Context Transitions]] |
| − | |Transitions to the [[#hero|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.<br> | + | *[[Scene Context#transitions|Scene Context Transitions]] |
| − | Example: this.hero
| + | *[[Layout Context#transitions|Layout Context Transitions]] |
| − | |-
| + | *[[Template Context#transitions|Template Context Transitions]] |
| − | |container
| + | *[[Portal Context#transitions|Portal Context Transitions]] |
| − | |Transitions to the [[#container|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.<br>
| + | *[[Table Context#transitions|Table Context Transitions]] |
| − | Example: this.container
| + | *[[Value Context#transitions|Value Context Transitions]] |
| − | |-
| + | *[[State Context#transitions|State Context Transitions]] |
| − | |parent
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.parent
| + | |
| − | |-
| + | |
| − | |child[''id'']
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.child[mypick]
| + | |
| − | |-
| + | |
| − | |childfound[''id'']
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.childfound[mypick]
| + | |
| − | |-
| + | |
| − | |firstchild[''expr'',''sort'']
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.firstchild[expr,mysort]
| + | |
| − | Example: this.firstchild[expr]
| + | |
| − | |-
| + | |
| − | |anchor
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.anchor
| + | |
| − | |-
| + | |
| − | |master
| + | |
| − | |Transitions to the [[#hero|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.<br>
| + | |
| − | Example: this.master
| + | |
| − | |-
| + | |
| − | |minion[''id'']
| + | |
| − | |Transitions to the [[#hero|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.<br>
| + | |
| − | Example: this.minion[myminion]
| + | |
| − | |-
| + | |
| − | |herofield[''id'']
| + | |
| − | |Transitions to the [[#field|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]".<br>
| + | |
| − | Example: this.herofield[myfield]
| + | |
| − | |-
| + | |
| − | |usagepool[''id'']
| + | |
| − | |Transitions to the [[#pool|pool context]] corresponding to the usage pool given by ''id'' that exists within the current container. This transition is only valid for actors, since gizmos do not possess usage pools.<br>
| + | |
| − | Example: this.usagepool[mypool]
| + | |
| − | |-
| + | |
| − | |transact
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the transaction pick that is associated with the hero governing the current context.<br>
| + | |
| − | Example: this.transact<br>
| + | |
| − | {{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|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.<br>
| + | |
| − | Example: this.dynalink[myindex]
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Hero Context{{anchor|hero}}==
| + | |
| − | | + | |
| − | A "hero" context is very similar to a "container" context, except that the options available are a bit more limited (e.g. heroes don't have parents). From within a "hero" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|state
| + | |
| − | |Transitions to the [[#state|state context]].<br>
| + | |
| − | Example: this.state
| + | |
| − | |-
| + | |
| − | |child[''id'']
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.child[mypick]
| + | |
| − | |-
| + | |
| − | |childfound[''id'']
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.childfound[mypick]
| + | |
| − | |-
| + | |
| − | |firstchild[''expr'',''sort'']
| + | |
| − | |Transitions to the [[#pick|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.<br>
| + | |
| − | Example: this.firstchild[expr,mysort]<br>
| + | |
| − | Example: this.firstchild[expr]
| + | |
| − | |-
| + | |
| − | |minion[''id'']
| + | |
| − | |Transitions to the [[#hero|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.<br>
| + | |
| − | Example: this.minion[myminion]
| + | |
| − | |-
| + | |
| − | |herofield[''id'']
| + | |
| − | |Transitions to the [[#field|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]".<br>
| + | |
| − | Example: this.herofield[myfield]
| + | |
| − | |-
| + | |
| − | |usagepool[''id'']
| + | |
| − | |Transitions to the [[#pool|pool context]] corresponding to the usage pool given by ''id'' that exists within the current actor.<br>
| + | |
| − | Example: this.usagepool[mypool]
| + | |
| − | |-
| + | |
| − | |transact
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the transaction pick that is associated with the hero governing the current context.<br>
| + | |
| − | Example: this.transact<br>
| + | |
| − | {{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|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.<br>
| + | |
| − | Example: this.dynalink[myindex]
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Pick Context{{anchor|pick}}==
| + | |
| − | | + | |
| − | From within a "pick" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|state
| + | |
| − | |Transitions to the [[#state|state context]].<br>
| + | |
| − | Example: this.state
| + | |
| − | |-
| + | |
| − | |hero
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the hero that contains the current pick.<br>
| + | |
| − | Example: this.hero
| + | |
| − | |-
| + | |
| − | |container
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the immediate container of the current pick, whether it be a hero or a gizmo.<br>
| + | |
| − | Example: this.container
| + | |
| − | |-
| + | |
| − | |parent
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the immediate container of the current pick, just like the "container" transition.<br>
| + | |
| − | Example: this.parent
| + | |
| − | |-
| + | |
| − | |gizmo
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the child gizmo directly attached by the pick. If the pick has no attached child gizmo, the transition fails to resolve.<br>
| + | |
| − | Example: this.gizmo
| + | |
| − | |-
| + | |
| − | |field[''id'']
| + | |
| − | |Transitions to the [[#field|field context]] corresponding to the field within the current pick that has the ''id'' specified. If the given field does not exist for the current pick, the transition fails to resolve.<br>
| + | |
| − | Example: this.field[myfield]<br>
| + | |
| − | {{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.
| + | |
| − | |-
| + | |
| − | |root
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the root pick that bootstraps the current pick into the container. If the current pick is not bootstrapped, or if the current pick is designated as unique and can possess multiple bootstraps, the transition fails to resolve.<br>
| + | |
| − | Example: this.source
| + | |
| − | |-
| + | |
| − | |gearholder
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the pick that is assigned as the gear holder of the current pick. If the current pick is not held, the transition fails to resolve. If the current pick is not gear, an error is reported and the transition fails to resolve.<br>
| + | |
| − | Example: this.gearholder
| + | |
| − | |-
| + | |
| − | |linkage[''id'']
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the linkage with the ''id'' specified. If the linkage is not defined, an error is reported.<br>
| + | |
| − | Example: this.linkage[mylink]
| + | |
| − | |-
| + | |
| − | |anchor
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the pick within the master actor that attaches the current actor as a minion. If the pick does not reside within a minion, the transition fails to resolve.<br>
| + | |
| − | Example: this.anchor
| + | |
| − | |-
| + | |
| − | |master
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the master actor for which this pick's container is a minion. If the pick is not within a minion, the transition fails to resolve.<br>
| + | |
| − | Example: this.master
| + | |
| − | |-
| + | |
| − | |minion[''id'']
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the minion actor with the given ''id'' that exists beneath the actor that possesses the current pick. The ''id'' can be omitted, in which case the minion is implicitly identified and must be directly attached by the current pick. If the pick does not reside within a master or the specified minion does not exist, the transition fails to resolve.<br>
| + | |
| − | Example: this.minion[myminion]<br>
| + | |
| − | Example: this.minion
| + | |
| − | |-
| + | |
| − | |herofield[''id'']
| + | |
| − | |Transitions to the [[#field|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]".<br>
| + | |
| − | Example: this.herofield[myfield]
| + | |
| − | |-
| + | |
| − | |usagepool[''id'']
| + | |
| − | |Transitions to the [[#pool|pool context]] corresponding to the usage pool with the ''id'' specified for the current pick.<br>
| + | |
| − | Example: this.usagepool[mypool]
| + | |
| − | |-
| + | |
| − | |shadow
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the container into which the current pick is shadowed. If the pick is not shadowed, an error is reported and the transition fails to resolve.<br>
| + | |
| − | Example: this.shadow
| + | |
| − | |-
| + | |
| − | |origin
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the container into which the current pick was originally added. If the pick is displaced, the container is where the pick was added by the user. If not displaced, the container is simply the container for the pick.<br>
| + | |
| − | Example: this.origin
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Thing Context{{anchor|thing}}==
| + | |
| − | | + | |
| − | 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:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|state
| + | |
| − | |Transitions to the [[#state|state context]]. Example: "this.state".
| + | |
| − | |-
| + | |
| − | |hero
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the hero that the thing will be potentially added to. Example: "this.hero".
| + | |
| − | |-
| + | |
| − | |field[''id'']
| + | |
| − | |Transitions to the [[#field|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]".<br> | + | |
| − | {{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|pick context]] corresponding to the linkage with the ''id'' specified. If the linkage is not defined, an error is reported. Example: "this.linkage[mylink]".
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Field Context{{anchor|field}}==
| + | |
| − | | + | |
| − | From within a "field" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|state
| + | |
| − | |Transitions to the [[#state|state context]]. Example: "this.state".
| + | |
| − | |-
| + | |
| − | |pick
| + | |
| − | |Transitions to the [[#pick|pick context]] corresponding to the pick that contains the current field. Example: "this.pick".
| + | |
| − | |-
| + | |
| − | |chosen
| + | |
| − | |Transitions to either the pick context corresponding to the user-selected pick stored within the field or the thing context corresponding to the user-selected thing stored within the field, depending on the nature of the field. The transition is only valid for use on fields that store menu selections made by the user. Example: "this.chosen".
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Pool Context{{anchor|pool}}==
| + | |
| − | | + | |
| − | From within a "pool" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|-None-
| + | |
| − | |There are no transitions from within a pool context.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Scene Context{{anchor|scene}}==
| + | |
| − | | + | |
| − | From within a "scene" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|layout[''id'']
| + | |
| − | |Transitions to the [[#layout|layout context]] corresponding to the layout within the current scene that possesses the ''id'' specified. If the layout does not exist within the scene, the transition fails to resolve. Example: "this.layout[mylayout]".
| + | |
| − | |-
| + | |
| − | |container
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the container to which the scene applies, whether it be an actor or a gizmo. Example: "this.container".<br>
| + | |
| − | {{note}}After transitioning, access within the new container context will be read-only and limited in what information can be retrieved.<br>
| + | |
| − | {{note}}This transition can only be used as the '''first''' transition when within a visual script.
| + | |
| − | |-
| + | |
| − | |hero
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the hero to which the scene applies. Example: "this.hero".<br>
| + | |
| − | {{note}}After transitioning, access within the new hero context will be read-only and limited in what information can be retrieved.<br>
| + | |
| − | {{note}}This transition can only be used as the '''first''' transition when within a visual script.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Layout Context{{anchor|layout}}==
| + | |
| − | | + | |
| − | From within a "layout" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|parent
| + | |
| − | |Transitions to the [[#scene|scene context]] corresponding to the visual element that contains the layout. Example: "this.parent".
| + | |
| − | |-
| + | |
| − | |template[''id'']
| + | |
| − | |Transitions to the [[#template|template context]] corresponding to the template within the current layout that possesses the ''id'' specified. If the template does not exist within the layout, the transition fails to resolve. Example: "this.template[mytemplate]".<br>
| + | |
| − | {{note}}The id specified is the id of the template '''reference''', as defined within the layout, and not necessarily the id of the template itself.
| + | |
| − | |-
| + | |
| − | |portal[''id'']
| + | |
| − | |Transitions to the [[#portal|portal context]] corresponding to the portal within the current layout that possesses the ''id'' specified. If the portal does not exist within the layout, the transition fails to resolve. Example: "this.portal[myportal]".<br>
| + | |
| − | {{note}}The id specified is the id of the portal '''reference''', as defined within the layout, and not necessarily the id of the portal itself.<br>
| + | |
| − | {{note}}Only portals defined directly within the layout can be accessed via this transition. Portals within templates must be accessed via the template.
| + | |
| − | |-
| + | |
| − | |container
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the container to which the layout applies, whether it be an actor or a gizmo. Example: "this.container".<br> | + | |
| − | {{note}}After transitioning, access within the new container context will be read-only and limited in what information can be retrieved.<br>
| + | |
| − | {{note}}This transition can only be used as the '''first''' transition when within a visual script.
| + | |
| − | |-
| + | |
| − | |hero
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the hero to which the layout applies. Example: "this.hero".<br>
| + | |
| − | {{note}}After transitioning, access within the new hero context will be read-only and limited in what information can be retrieved.<br>
| + | |
| − | {{note}}This transition can only be used as the '''first''' transition when within a visual script.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Template Context{{anchor|template}}==
| + | |
| − | | + | |
| − | From within a "template" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|parent
| + | |
| − | |Transitions to the [[#layout|layout context]] or [[#table|table context]] corresponding to the visual element that contains the tmeplate. Example: "this.parent".<br>
| + | |
| − | {{note}}The "parent" transition can only be utilized a '''single''' time, so it is not possible to go upwards two or more levels within the hierarchy.
| + | |
| − | |-
| + | |
| − | |portal[''id'']
| + | |
| − | |Transitions to the [[#portal|portal context]] corresponding to the portal within the current template that possesses the ''id'' specified. If the portal does not exist within the template, the transition fails to resolve. Example: "this.portal[myportal]".<br>
| + | |
| − | {{note}}Only portals defined directly within the template can be accessed via this transition.
| + | |
| − | |-
| + | |
| − | |field[''id'']
| + | |
| − | |Transitions to the [[#value|value context]] corresponding to the field within the current template that has the ''id'' specified. The fields for a template are dictated by the pick or thing that is associated with the template. If the given field does not exist for the pick/thing, the transition fails to resolve. Example: "this.field[myfield]".<br> | + | |
| − | {{note}}Within templates, all fields are treated as read-only, which is controlled by transitioning to a distinct "value" context instead of "field" context.
| + | |
| − | |-
| + | |
| − | |container
| + | |
| − | |Transitions to the [[#container|container context]] corresponding to the container to which the template applies, whether it be an actor or a gizmo. Example: "this.container".<br>
| + | |
| − | {{note}}After transitioning, access within the new container context will be read-only and limited in what information can be retrieved.<br>
| + | |
| − | {{note}}This transition can only be used as the '''first''' transition when within a visual script.
| + | |
| − | |-
| + | |
| − | |hero
| + | |
| − | |Transitions to the [[#hero|hero context]] corresponding to the hero to which the template applies. Example: "this.hero".<br>
| + | |
| − | {{note}}After transitioning, access within the new hero context will be read-only and limited in what information can be retrieved.<br>
| + | |
| − | {{note}}This transition can only be used as the '''first''' transition when within a visual script.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Portal Context{{anchor|portal}}==
| + | |
| − | | + | |
| − | From within a "portal" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|parent
| + | |
| − | |Transitions to the [[#layout|layout context]] or [[#template|template context]] corresponding to the visual element that contains the portal. Example: "this.parent".<br>
| + | |
| − | {{note}}The "parent" transition can only be utilized a '''single''' time, so it is not possible to go upwards two or more levels within the hierarchy.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Value Context{{anchor|value}}==
| + | |
| − | | + | |
| − | The "value" context parallels a "field" context, with the key distinction being that all values are read-only, since they are intended for display only. From within a "value" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|-None-
| + | |
| − | |There are no transitions from within a value context.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==Table Context{{anchor|table}}==
| + | |
| − | | + | |
| − | The "table" context is essentially the same as a "portal" context, since the context simply corresponds to a table portal within a layout. From within a "table" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|parent
| + | |
| − | |Transitions to the [[#layout|layout context]] corresponding to the visual element that contains the portal. Example: "this.parent".<br>
| + | |
| − | {{note}}The "parent" transition can only be utilized a '''single''' time, so it is not possible to go upwards two or more levels within the hierarchy.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ==State Context{{anchor|state}}==
| + | |
| − | | + | |
| − | From within a "state" context, you can utilize the following set of valid context transitions:
| + | |
| − | | + | |
| − | :{| class="infotable"
| + | |
| − | |class="leftnormal"|-None-
| + | |
| − | |There are no transitions from within a state context.
| + | |
| − | |-
| + | |
| − | |}
| + | |
| | | | |
| | ==Special Contexts== | | ==Special Contexts== |
| Line 384: |
Line 51: |
| | |- | | |- |
| | |actor | | |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. | + | |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.<br> |
| | + | {{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 | | |transaction |
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.
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.
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.
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.
