|
|
| (2 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| {{context|Kit Reference|Target References}} | | {{context|Kit Reference|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 complete list of these operations is presented in the table below.
| | See Also: [[Hero Context Transitions]] |
|
| |
|
| {{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. | | Heroes are a special type of container. As such, they share all of the same target references as normal containers. However, they also have quite a few additional target references that are unique to heroes. The complete list of these special target references is presented in the table below. |
| | |
| | {{important}}For the purposes of data file authoring, the "hero" context applies to all actors, whether they be leads, masters, or minions. |
| | |
| | {{important}}Actors also support [[Container Target References|all general container target references]]. |
| | |
| | {{note}}When an actor 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. |
|
| |
|
| :{| class="infotable" | | :{| class="infotable" |
| |class="leftnormal"|live | | |class="leftnormal"|setactor |
| |(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.<br>
| | |(Right, Number) Memorizes the current actor context as the "actor focus", allowing it to be instantly accessed thereafter via the "actor." initial script context. Always returns a value of zero.<br> |
| Example: result = this.live
| |
| |-
| |
| |ishero
| |
| |(Right, Number) Returns non-zero if the container is a hero, else zero for a gizmo.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| Example: result = this.playername
| |
| |-
| |
| |setactor | |
| |(Right, Number) Memorizes the current actor context as the "actor focus", allowing it to be instantly accessed thereafter via the "actor." initial script context. The current container context must be an actor and not a gizmo. Always returns a value of zero.<br> | |
| Example: perform this.setactor | | Example: perform this.setactor |
| |-
| |
| |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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| Example: result = this.tagsearch["class.wizard & (val:spelllevel.wizard? > 5)"]<br>
| |
| {{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, [[The "tagmatch" Target Reference|please check here]].<br>
| |
| Example: result = hero.tagmatch[NeedStatus,HasStatus,initial]
| |
| |-
| |
| |intersect[''init'',''curr'']
| |
| |(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).<br>
| |
| 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.<br>
| |
| Example: result = this.inherit[mypick]<br>
| |
| Example: result = this.inherit
| |
| |-
| |
| |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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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, [[Identity Target References|please check here]].<br>
| |
| 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, [[Identity Target References|please check here]].<br>
| |
| 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, [[Identity Target References|please check here]].<br>
| |
| Example: result = this.countidentity[groupid]
| |
| |-
| |
| |isminion
| |
| |(Right, Number) Returns non-zero if the container is a minion, else zero.<br>
| |
| Example: result = this.isminion
| |
| |-
| |
| |ismaster
| |
| |(Right, Number) Returns non-zero if the container is a master, else zero.<br>
| |
| Example: result = this.ismaster
| |
| |-
| |
| |hasminion[''id'']
| |
| |(Right, Number) Returns non-zero if the container possesses a minion with the specified ''id''. If the container is not a master or does not contain the specified minion, zero is returned.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| Example: result = this.panelvalid[mypanel]<br>
| |
| {{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.<br>
| |
| 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.<br>
| |
| 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.<br>
| |
| Example: result = this.tagids[Weapon.?,"+"]
| |
| |-
| |
| |weight
| |
| |(Right, Number) Returns the total weight of all "gear" picks within the container.<br>
| |
| Example: result = this.weight
| |
| |-
| |
| |gearlist[''spl'',''expr'']
| |
| |(Right, String) Generates and returns a list of gear held within the container. 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.<br>
| |
| Example: 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.<br>
| |
| Example: result = this.geartree[!Helper.NoMove]
| |
| |- | | |- |
| |miniontext | | |miniontext |
| |(Right, String) Returns the name of the thing that attaches the current minion. This makes it possible to retrieve the nature of the minion for display to the user. If invoked on a gizmo, an error is reported. If invoked on a lead, an empty string is returned.<br> | | |(Right, String) Returns the name of the thing that attaches the current minion. This makes it possible to retrieve the nature of the minion for display to the user. If invoked on a lead, an empty string is returned.<br> |
| Example: result = this.miniontext | | Example: result = this.miniontext |
| |- | | |- |
| |sourcetree | | |sourcetree |
| |(Right, String) Returns a summary of the various user-selected sources that have chosen for the current actor. This is intended for inclusion within character sheet output. The summary is synthesized solely from sources that are user-selected, although the entire chain of sources down to each selected source is included so that context is provided in case similar names are used in different contexts. Any source that is designated as not reportable is omitted from the summary, allowing sources governing printout and interface behaviors to be omitted. If a source specifies an alternate "reportname", that name is used instead. If a gizmo is the context, the containing actor context is used.<br> | | |(Right, String) Returns a summary of the various user-selected sources that have chosen for the current actor. This is intended for inclusion within character sheet output. The summary is synthesized solely from sources that are user-selected, although the entire chain of sources down to each selected source is included so that context is provided in case similar names are used in different contexts. Any source that is designated as not reportable is omitted from the summary, allowing sources governing printout and interface behaviors to be omitted. If a source specifies an alternate "reportname", that name is used instead.<br> |
| Example: result = this.sourcetree | | Example: result = this.sourcetree |
| |- | | |- |
| |errorcount | | |errorcount |
| |(Right, Number) Returns the total number of validation errors that were reported within the hero over the course of evaluation. This is intended for use within character sheet output. If accessed from within a gizmo or during evaluation processing, a run-time error is reported.<br> | | |(Right, Number) Returns the total number of validation errors that were reported within the hero over the course of evaluation. This is intended for use within character sheet output. If accessed during evaluation processing, a run-time error is reported.<br> |
| Example: result = this.errorcount | | Example: result = this.errorcount |
| |- | | |- |
| |errorlist | | |errorlist |
| |(Right, String) Returns a string containing all validation errors for the hero, based on the most recent evaluation cycle. This is intended for use within character sheet output. If accessed from within a gizmo or during evaluation processing, a run-time error is reported.<br> | | |(Right, String) Returns a string containing all validation errors for the hero, based on the most recent evaluation cycle. This is intended for use within character sheet output. If accessed during evaluation processing, a run-time error is reported.<br> |
| Example: result = this.errorlist | | Example: result = this.errorlist |
| |- | | |- |
