Container Context

From HLKitWiki
Revision as of 11:06, 5 September 2014 by Colen (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Context: HL KitKit Reference  … Multiple Sources

Jump to: Target References

The "container" context represents any container within the portfolio. The container could be an actor or a gizmo.

IMPORTANT! If the container context happens to be an actor, then you can utilize the context as either a standard container context or as a Hero Context.

Context Transitions

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]
Example: 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 current 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]

Target References

There are a wide assortment of operations that can be performed on containers, some of which modify the container and some that simply retrieve information about the container. The container context applies equally to heroes and gizmos, although there are some behavioral differences that arise for some target references. The complete list of target references for containers is presented in the table below.

NOTE! When a container is accessed from within a visual script, all operations are restricted to read-only behavior. Any attempts to modify a container from within a visual script will fail.

live (Right, Number) Returns non-zero if the container is currently considered "live", else zero if non-live. The live state for a gizmo is dictated by the live state of its parent pick that attaches it, while a hero is always considered live.

Example: result = this.live

ishero (Right, Number) Returns non-zero if the container is a hero, else zero for a gizmo.

Example: result = this.ishero

isactive (Right, Number) Returns non-zero if the container either is or resides within the currently active actor within the HL interface. If the container is or resides within a different actor, zero is returned.

Example: result = this.isactive

livename (Right, String) Returns a suitable name for the container that is based on dynamic changes made via scripts. If the container is an actor, the name of the actor is returned, else the name of the parent pick of the gizmo is returned.

Example: result = this.livename

actorname (Right, String) Returns the name of the actor that encompasses the current container context. The name is whatever has been assigned by the user.

Example: result = this.actorname

playername (Right, String) Returns the name of the player that is associated with the current lead. The name is whatever has been entered by the user.

Example: result = this.playername

assign[tag] (Right, Number) Assigns the indicated tag to the container. 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 container 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 container 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 container 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 container 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 container 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 container 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 container 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 container 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 container 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]

heromatch[refgrp,match,ref] (Right, Number) Returns non-zero if any tags within the actor also exist within a match context, else zero. This allows tags from the actor to be verified to exist within another context, making tag-based comparisons between the actor and another object possible. The key difference between "heromatch" and "tagmatch" is that this target reference always assumes the initial context is the actor, which is then compared against the context that is transitioned to. For more details, please check here.

Example: result = this.heromatch[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]

inherit[id] (Right, Number) The container inherits all tags from one or all of its child picks. If an id is given, then all tags from the pick with that id are inherited into the container. If no parameter is given, then all tags from all child picks are inherited. The return value is the total number of tags inherited.

Example: result = this.inherit[mypick]
Example: result = this.inherit

pulltags[tmpl,grp] (Right, Number) Copies tags from the transitioned container context into the initial pick or container context and returns the total number of tags copied. The set of tags to be copied from the transitioned context are dictated by the tag template tmpl. If the second parameter is omitted, the identified tags are copied to the initial 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 context. When mapping, an equivalent mapped tag must exist for all identified tags. Both the initial and transitioned script context must be either picks or containers.

Example: result = hero.pulltags[thingid.?]
Example: result = hero.pulltags[thingid.?,Ability]

pushtags[tmpl,grp] (Right, Number) Copies tags from the initial pick or container context into the transitioned container 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 = hero.pushtags[thingid.?]
Example: result = hero.pushtags[thingid.?,Ability]

childexists[id] (Right, Number) Returns non-zero if any child pick with the given id exists within the container, else zero if no matching pick is found.

Example: result = this.childexists[mypick]

childlives[id] (Right, Number) Returns non-zero if any child pick with the given id exists within the container and is "live". If either no matching pick is found or all matching picks found are "non-live", zero is returned.

Example: result = this.childlives[mypick]

childcount[id] (Right, Number) Returns the number of child picks with the given id that exist within the container. A value of zero indicates that no matching picks were found.

Example: result = this.childcount[mypick]

haschild[str] (Right, Number) Returns the number of child picks within the container that match the tag expression given by str. The parameter is a string expression that must contain a valid tag expression and is tested against all children of the container. The parameter can be synthesized dynamically within the script.

Example: result = this.haschild["component.Skill"]

setidentity[grp] (Right, Number) Assigns to the container 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 container 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 container. 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]

isminion (Right, Number) Returns non-zero if the container is or resides within a minion, else zero.

Example: result = this.isminion

ismaster (Right, Number) Returns non-zero if the container is or resides within a master, else zero.

Example: result = this.ismaster

hasminion[id] (Right, Number) Returns non-zero if the container is or resides within an actor that possesses a minion with the specified id. If the container is not within a master or does not contain the specified minion, zero is returned.

Example: result = this.hasminion[myminion]

isdynalink[expr] (Right, Number) Returns non-zero if a dynamic linkage has been defined for the implied hero context with the index specified, else zero if no linkage exists. If the container is a gizmo, then the containing actor is used as the hero context. The value given by index may be an arithmetic expression that will be resolved properly at run-time.

Example: result = this.isdynalink[4]

istransact (Right, Number) Returns non-zero if a viable transaction context exists for the container. This allows scripts to check that a transaction context exists before attempting to transition into the transaction context.

Example: result = this.istransact

panelvalid[id] (Left, Number) Sets the validity state of the tab panel given by id. If the value assigned is zero, the panel is designated as non-valid and its name will be highlighted in red to the user. Since the default state of all panels is valid, if a non-zero value is assigned, this target reference is ignored. This means you can simply designate a panel as invalid when appropriate and do nothing when the panel is valid.

Example: result = this.panelvalid[mypanel]
NOTE! This target reference can only be used from within an Eval Rule or a Validate script.

tagnames[tmpl,spl] (Right, String) Generates and returns a list of tags within the container. 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 container 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.?,"+"]

weight (Right, Number) Returns the total weight of all "gear" picks within the container.

Example: result = this.weight

gearlist[spl,expr] (Right, String) Generates and returns a list of gear held within the container, which means gear that is not held within another gear holder. Only picks that are designated as gear and that are not assigned to a 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 container that holds no gear matching the tag expression will return the empty string.

Example: result = this.gearlist["+",!Equipment.Natural]

geartree[expr] (Right, String) Generates and returns a hierarchical tree view of the gear picks possessed by the container context, as appropriate for use within the Dashboard and Tactical Console. Only picks that are designated as gear are candidates for inclusion in the report. 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 report. All gear is output in a hierarchy, where each level of containment is indented beneath the level above it. Gear within child gizmos is also included, with indentation as if the gizmo were a holder within the container and its contents indented beneath it.

Example: result = this.geartree[!Helper.NoMove]