Difference between revisions of "Thing Element (Data)"

From HLKitWiki
Jump to: navigation, search
(New page: {{context|Kit Reference|Data File Reference}} ==The "thing" Element== The vast majority of objects that will comprise your data files are "things", which will be added to actors and cust...)
 
(The "minion" Element{{anchor|minion}})
 
(13 intermediate revisions by one other user not shown)
Line 34: Line 34:
 
|-
 
|-
 
|stacking
 
|stacking
|(Optional) Set – Designates the default stacking behavior to be assumed whenever this thing is purchased by the user. Must be one of these values:<br>
+
|(Optional) Set – Designates the default stacking behavior to be assumed whenever this thing is purchased by the user. Must be one of these values:
solo – Item is created individually, so buying 5 of the thing will add 5 separate instances of the thing to the container.<br>
+
<ul class="sets">
new – Item is purchased as a new group, so buying 5 of the thing will add one new instance of the thing that has a quantity of 5.<br>
+
<li>solo – Item is created individually, so buying 5 of the thing will add 5 separate instances of the thing to the container.</li>
merge – Item is merged to any existing instance of the thing within the container, adding the quantity purchased to the existing quantity. If item does not currently exist, "new" behavior is used.<br>
+
<li>new – Item is purchased as a new group, so buying 5 of the thing will add one new instance of the thing that has a quantity of 5.</li>
never – Item can never support stacking.<br>
+
<li>merge – Item is merged to any existing instance of the thing within the container, adding the quantity purchased to the existing quantity. If item does not currently exist, "new" behavior is used.</li>
Default: "solo".
+
<li>never – Item can never support stacking.</li>
 +
<li>Default: "solo".</li>
 +
</ul>
 
|-
 
|-
 
|lotsize
 
|lotsize
Line 58: Line 60:
 
|}
 
|}
  
The "component" element also possesses child elements that define various facets of the component. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.
+
The "thing" element also possesses child elements that define various facets of the thing. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|[[Field Element (Data)|field]]
+
|class="leftnormal"|[[#fieldval|fieldval]]
|Zero or more "field" elements may appear as defined by the given link. This element specifies the fields that exist for the component.
+
|Zero or more "fieldval" elements may appear as defined by the given link. This element specifies the starting value for individual fields within the thing.
 
|-
 
|-
|[[#usage|usage]]
+
|[[#arrayval|arrayval]]
|Zero or more "usage" elements may appear as defined by the given link. This element specifies the [[Leveraging Usage Pools|pick-based usage pools]] associated with all things derived from the component.
+
|Zero or more "arrayval" elements may appear as defined by the given link. This element specifies the starting value for individual array and matrix elements within the thing.
 
|-
 
|-
|[[#linkage|linkage]]
+
|[[#usesource|usesource]]
|Zero or more "linkage" elements may appear as defined by the given link. This element specifies the [[Pick Linkages|pick linkages]] that exist for all things derived from the component.
+
|Zero or more "usesource" elements may appear as defined by the given link. This element specifies the sources relied upon for this thing to be accessible to the user.
 
|-
 
|-
|[[#identity|identity]]
+
|[[Tag Element (Data)|tag]]
|Zero or more "identity" elements may appear as defined by the given link. This element specifies any [[Identity Tags|identity tag groups]] that are defined for the component.
+
|Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to the thing.
 +
|-
 +
|[[Bootstrap Element (Data)|bootstrap]]
 +
|Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped when this thing is added to a container.
 
|-
 
|-
 
|[[ContainerReq Element (Data)|containerreq]]
 
|[[ContainerReq Element (Data)|containerreq]]
|Zero or more "containerreq" elements may appear as defined by the given link. This element specifies any container requirements for things derived from the component.
+
|Zero or more "containerreq" elements may appear as defined by the given link. This element specifies any container requirements for the thing.
 
|-
 
|-
|[[#displace|displace]]
+
|[[#holdlimit|holdlimit]]
|An optional "displace" element may appear as defined by the given link. This element specifies any [[Displacement|displacement behaviors]] that the component must perform.
+
|An optional "holdlimit" element may appear as defined by the given link. This element defines a [[HoldLimit Tag Expression]] that restricts the valid set of gear that can be held by the thing.
 
|-
 
|-
|[[#shadow|shadow]]
+
|[[#gear|gear]]
|An optional "shadow" element may appear as defined by the given link. This element specifies any [[Shadowing|shadowing behaviors]] that the component must perform.
+
|An optional "gear" element may appear as defined by the given link. This element defines a [[Gear Script]] for the thing to calculate its weight.
 
|-
 
|-
|[[#creation|creation]]
+
|[[#link|link]]
|An optional "creation" element may appear as defined by the given link. This element defines a [[Creation Script]] for the component.
+
|Zero or more "link" elements may appear as defined by the given link. This element specifies the specific [[Pick Linkages|pick linkages]] that exist for this thing.
 
|-
 
|-
|[[#deletion|deletion]]
+
|[[Eval Element (Data)|eval]]
|An optional "deletion" element may appear as defined by the given link. This element defines a [[Deletion Script]] for the component.
+
|Zero or more "eval" elements may appear as defined by the given link. This element specifies any [[Eval Script|Eval Scripts]] that must be performed for the thing.
 
|-
 
|-
|[[#xactsetup|xactsetup]]
+
|[[EvalRule Element (Data)|evalrule]]
|An optional "xactsetup" element may appear as defined by the given link. This element defines an [[TransactSetup Script]] for the component.
+
|Zero or more "evalrule" elements may appear as defined by the given link. This element specifies any [[EvalRule Script|EvalRule Scripts]] that must be performed for the thing.
 
|-
 
|-
|[[#xactbuy|xactbuy]]
+
|[[#pickreq|pickreq]]
|An optional "xactbuy" element may appear as defined by the given link. This element defines an [[TransactBuy Script]] for the component.
+
|Zero or more "pickreq" elements may appear as defined by the given link. This element specifies any [[Dependencies on Specific Things|dependencies upon other picks]] within the container.
 
|-
 
|-
|[[#xactsell|xactsell]]
+
|[[#exprreq|exprreq]]
|An optional "xactsell" element may appear as defined by the given link. This element defines an [[TransactSell Script]] for the component.
+
|Zero or more "exprreq" elements may appear as defined by the given link. This element specifies any [[Expression-Based Requirements|expression-based dependencies ]] upon the state of the container.
|-
+
|[[Tag Element (Data)|tag]]
+
|Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to every thing derived from the component.
+
|-
+
|[[Bootstrap Element (Data)|bootstrap]]
+
|Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped to every thing derived from the component.
+
|-
+
|[[#loadfixup|loadfixup]]
+
|An optional "loadfixup" element may appear as defined by the given link. This element defines a [[LoadFixup Script]] for the component.
+
|-
+
|[[Eval Element (Data)|eval]]
+
|Zero or more "eval" elements may appear as defined by the given link. This element specifies any [[Eval Script|Eval Scripts]] that must be performed for the component.
+
|-
+
|[[EvalRule Element (Data)|evalrule]]
+
|Zero or more "evalrule" elements may appear as defined by the given link. This element specifies any [[EvalRule Script|EvalRule Scripts]] that must be performed for the component.
+
 
|-
 
|-
 
|[[PreReq Element (Data)|prereq]]
 
|[[PreReq Element (Data)|prereq]]
|Zero or more "prereq" elements may appear as defined by the given link. This element specifies any [[General Pre-Requisites|pre-requisite tests]] that are applied to every thing derived from the component.
+
|Zero or more "prereq" elements may appear as defined by the given link. This element specifies any [[General Pre-Requisites|pre-requisite tests]] that are applied to the thing.
 
|-
 
|-
|[[#merge|merge]]
+
|[[#child|child]]
|An optional "merge" element may appear as defined by the given link. This element defines a [[Merge Script]] for the component.
+
|An optional "child" element may appear as defined by the given link. This element defines the particulars of a child entity that is attached by the thing.
 
|-
 
|-
|[[#split|split]]
+
|[[#minion|minion]]
|An optional "split" element may appear as defined by the given link. This element defines a [[Split Script]] for the component.
+
|An optional "minion" element may appear as defined by the given link. This element defines the particulars of a minion that is attached by the thing.
 
|-
 
|-
 
|}
 
|}
  
==The "usage" Element{{anchor|usage}}==
+
==The "fieldval" Element{{anchor|fieldval}}==
  
The "usage" element defines a [[Leveraging Usage Pools|pick-based usage pool]] to associate with every thing for the component. The complete list of attributes for this element is below.  
+
The "fieldval" element defines the starting values to use for various fields within the thing. To initialize elements within arrays and matrices, please see the "arrayval" element (below). The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|usage
+
|class="leftnormal"|field
|Id – Unique id of the usage pool to be associated with all picks derived from this component.
+
|Id – Unique id of the field for which to specify a starting value.
 +
|-
 +
|value
 +
|Text – Starting value to assign to the field. If the field is text-based, the value is simply assigned, although it may be truncated if it exceeds the defined maximum length for the field. If the field is value-based, the text is converted to a floating point value and assigned.
 
|-
 
|-
 
|}
 
|}
  
==The "linkage" Element{{anchor|linkage}}==
+
==The "arrayval" Element{{anchor|arrayval}}==
  
The "linkage" element defines a [[Pick Linkages|linkage to another pick]] that is associated with every thing for the component. The complete list of attributes for this element is below.  
+
The "arrayval" element defines the starting values to use for individual elements within array and matrix fields of the thing. To initialize elements within fields that are not an array or matrix, please see the "fieldval" attribute (above). The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|linkage
+
|class="leftnormal"|field
|Id – Specifies the unique id of the linkage being defined for the component.
+
|Id – Unique id of the field for which to specify a starting value. If the field is not an array or matrix, an error is reported.
 
|-
 
|-
|optional
+
|index
|(Optional) Boolean Indicates whether this linkage is optional or required for all picks. Default: "no".
+
|Integer Specifies the row index of the element to be initialized. The first element of arrays and matrices is index zero.
 
|-
 
|-
|}
+
|column
 
+
|(Optional) Integer – Specifies the column of the element to be initialized within a matrix. The first element of matrices is index zero. This attribute is required for matrix elements and may be omitted for array elements. Default: Empty.
==The "identity" Element{{anchor|identity}}==
+
|-
 
+
|value
The "identity" element defines an [[Identity Tags|identity tag group]] for the component and all derived things. The complete list of attributes for this element is below.  
+
|Text Starting value to assign to the field element. If the field is text-based, the value is simply assigned, although it may be truncated if it exceeds the defined maximum length for the field. If the field is value-based, the text is converted to a floating point value and assigned.
 
+
:{| class="infotable"
+
|class="leftnormal"|group
+
|Id Unique id of the tag group that will be used for identity handling of all things derived from this component.
+
{{note}}This tag group does '''not''' need to exist. If it does not, it is automatically created and setup appropriately by the Kit, but you may not add further dynamic tags to a tag group that is auto-created in this way.
+
 
|-
 
|-
 
|}
 
|}
  
==The "displace" Element{{anchor|displace}}==
+
==The "usesource" Element{{anchor|usesource}}==
  
The "displace" element defines the [[Displacement|displacement behavior]] for the component and all derived things. The complete list of attributes for this element is below.  
+
The "usesource" element specifies a [[Sources|source]] that this thing is dependent upon. If the designated source is not enabled by the user, this thing will be treated as not existing for the character. You may define a new source on-the-fly via this element by providing a new unique id and the appropriate additional information. However, you should typically avoid doing so, since you cannot control important facets of sources with just-in-time definition. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|target
+
|class="leftnormal"|source
|(Optional) Set Designates the target into which picks derived from this component will be displaced. Must be one of these values:<br>
+
|Id Specifies the unique id of the source with which to establish a dependence.
hero – Picks are displaced into the hero/actor, regardless of location in the structural hierarchy.
+
parent – Picks are displaced into the immediate container.
+
Default: "hero".
+
 
|-
 
|-
|PCDATA
+
|name
|TagExpr – Specifies a tag expression that determines whether an individual pick is displaced. This tag expression is applied to the '''pick''' itself - not the container. Furthermore, the tag expression '''does''' include tags that are automatically added to the pick at creation, such as auto-tags from a table or a bootstrap. The tag expression is only applied once, when the pick is first added to the container, after which the pick is either displaced or not for the rest of its existence.
+
|(Optional) Text – Name to be displayed to the user for this source. Maximum length is 50 characters. If the source already exists, this attribute can be left empty. Default: Empty.
 +
|-
 +
|parent
 +
|(Optional) Id – Specifies the unique id of a different source that is treated as the parent of this source. All sources are displayed in a hierarchy within the "Configure Hero" form. If the source already exists, this attribute can be left empty and the behaviors of the existing source are utilized. If empty and the source does not yet exist, the new source is presented to the user as a top-level selection. Default: Empty.
 
|-
 
|-
 
|}
 
|}
  
==The "shadow" Element{{anchor|shadow}}==
+
==The "holdlimit" Element{{anchor|holdlimit}}==
  
The "shadow" element defines the [[Shadowing|shadowing behavior]] for the component and all derived things. The complete list of attributes for this element is below.  
+
The "holdlimit" element defines a [[HoldLimit Tag Expression]] for the thing, which restricts the set of things that can be assigned to this thing as held gear. The tag expression is compared against the tags assigned to each prospective piece of gear that the user wants to move. If the tag expression is satisfied, the gear can be held within the thing, else it cannot. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|target
+
|class="leftnormal"|PCDATA
|(Optional) Set – Designates the target into which picks derived from this component will be shadowed. Must be one of these values:<br>
+
|TagExpr – Specifies the code comprising the HoldLimit tag expression.
hero – Picks are shadowed into the hero/actor, regardless of location in the structural hierarchy.
+
parent – Picks are shadowed into the immediate container.
+
Default: "hero".
+
|-
+
|PCDATA
+
|TagExpr – Specifies a tag expression that determines whether an individual pick is shadowed. This tag expression is applied to the '''pick''' itself - not the container. Furthermore, the tag expression '''does''' include tags that are automatically added to the pick at creation, such as auto-tags from a table or a bootstrap. The tag expression is only applied once, when the pick is first added to the container, after which the pick is either shadowed or not for the rest of its existence.
+
 
|-
 
|-
 
|}
 
|}
  
==The "creation" Element{{anchor|creation}}==
+
==The "gear" Element{{anchor|gear}}==
  
The "creation" element defines a [[Creation Script]] for the component. The complete list of attributes for this element is below.  
+
The "gear" element defines a [[Gear Script]] for the thing, which is used to calculate the weight of held items and perform additional gear processing on the thing. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
 
|class="leftnormal"|PCDATA
 
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Creation script.
+
|Script – Specifies the code comprising the Gear script.
 
|-
 
|-
 
|}
 
|}
  
==The "deletion" Element{{anchor|deletion}}==
+
==The "link" Element{{anchor|link}}==
  
The "deletion" element defines a [[Deletion Script]] for the component. The complete list of attributes for this element is below.  
+
The "link" element defines a [[Pick Linkages|linkage to another thing]] based on the set of possible linkages defined for the underlying components. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|linkage
|Script Specifies the code comprising the Deletion script.
+
|Id Unique id of the linkage that is being setup for this thing.
 +
|-
 +
|thing
 +
|Id – Unique id of the thing to which the linkage should be established.
 
|-
 
|-
 
|}
 
|}
  
==The "xactsetup" Element{{anchor|xactsetup}}==
+
==The "pickreq" Element{{anchor|pickreq}}==
  
The "xactsetup" element defines an [[TransactSetup Script]] for the component. The complete list of attributes for this element is below.  
+
The "pickreq" element defines a [[Dependencies on Specific Things|dependency on a specific thing]] whose existence is important within the container. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|thing
|Script Specifies the code comprising the TransactSetup script.
+
|Id Unique id of the thing upon which the dependency is being established.
 +
|-
 +
|iserror
 +
|(Optional) Boolean – Indicates whether failure of the requirement should be treated as an error or merely a warning. Default: "yes".
 +
|-
 +
|ispreclude
 +
|(Optional) Boolean – Indicates whether the specified thing must exist or must not exist within the container in order for the requirement to be satisfied. Preclusion implies that the thing is not allowed to exist. Default: "no".
 +
|-
 +
|onlyonce
 +
|(Optional) Boolean – Indicates whether the pre-requisite should only be reported to the user a single time if it fails, regardless of the number of times the thing is added to the container. Default: "no".
 +
|-
 +
|issilent
 +
|(Optional) Boolean – Indicates whether the pre-requisite should report an error message to the user if failed. Default: "no".
 
|-
 
|-
 
|}
 
|}
  
==The "xactbuy" Element{{anchor|xactbuy}}==
+
==The "exprreq" Element{{anchor|exprreq}}==
  
The "xactbuy" element defines an [[TransactBuy Script]] for the component. The complete list of attributes for this element is below.  
+
The "exprreq" element defines a [[Expression-Based Requirements|dependency on an arithmetic expression]] that must be satisfied by the container. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|message
|Script – Specifies the code comprising the TransactBuy script.
+
|Text – Specifies the message to be reported if the requirement is not satisfied.
 +
|-
 +
|iserror
 +
|(Optional) Boolean – Indicates whether failure of the requirement should be treated as an error or merely a warning. Default: "yes".
 +
|-
 +
|onlyonce
 +
|(Optional) Boolean – Indicates whether the pre-requisite should only be reported to the user a single time if it fails, regardless of the number of times the thing is added to the container. Default: "no".
 +
|-
 +
|issilent
 +
|(Optional) Boolean – Indicates whether the pre-requisite should report an error message to the user if failed. Default: "no".
 +
|-
 +
|PCDATA
 +
|Text – Specifies an arithmetic expression that is applied to the container to determine whether the requirement is satisfied. The expression must be a valid chunk of script code that can be placed between the parentheses in a standard "if/then" statement (e.g. "if (expr) then").
 
|-
 
|-
 
|}
 
|}
  
==The "xactsell" Element{{anchor|xactsell}}==
+
==The "child" Element{{anchor|child}}==
  
The "xactsell" element defines an [[TransactSell Script]] for the component. The complete list of attributes for this element is below.  
+
The "child" element specifies an entity that is always added as a [[Advanced Gizmos|child gizmo]] of the thing. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|entity
|Script – Specifies the code comprising the TransactSell script.
+
|Id – Specifies the unique id of the entity to be attached as a child gizmo.
 
|-
 
|-
 
|}
 
|}
  
==The "loadfixup" Element{{anchor|loadfixup}}==
+
The "child" element also possesses child elements that tailor the entity. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.  
 
+
The "loadfixup" element defines a [[LoadFixup Script]] for the component. The complete list of attributes for this element is below.  
+
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|[[Tag Element (Data)|tag]]
|Script – Specifies the code comprising the LoadFixup script.
+
|Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to the gizmo when it is created.
 +
|-
 +
|[[Bootstrap Element (Data)|bootstrap]]
 +
|Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped into the gizmo when it is created.
 
|-
 
|-
 
|}
 
|}
  
==The "merge" Element{{anchor|merge}}==
+
==The "minion" Element{{anchor|minion}}==
  
The "merge" element defines a [[Merge Script]] for the component. The complete list of attributes for this element is below.  
+
The "minion" element specifies that the thing always [[Minions and Masters|attaches a minion]]. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|id
|Script – Specifies the code comprising the Merge script.
+
|Id – Specifies the unique id to be used for the minion attached via this thing.
 +
|-
 +
|ownmode
 +
|(Optional) Boolean – Indicates whether the minion has an independent creation/advancement mode from its master. In some cases, you will want the minion to possess the same behavior as the master and transition with the master. However, if the minion is constructed as an independent character, you may want to handle advancement separately. Default: "yes".
 +
|-
 +
|isinherit
 +
|(Optional) Boolean – Indicates whether the minion inherits the set of enabled sources from its master. If inheritance is active, the source selections for the master are locked in for the minion, with any changes to the master being immediately reflected within the minion. Default: "yes".
 
|-
 
|-
 
|}
 
|}
  
==The "split" Element{{anchor|split}}==
+
The "minion" element also possesses child elements that tailor the minion. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.  
 
+
The "split" element defines a [[Split Script]] for the component. The complete list of attributes for this element is below.  
+
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|PCDATA
+
|class="leftnormal"|[[Tag Element (Data)|tag]]
|Script – Specifies the code comprising the Split script.
+
|Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to the minion when it is created.
 +
|-
 +
|[[Bootstrap Element (Data)|bootstrap]]
 +
|Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped into the minion when it is created.
 
|-
 
|-
 
|}
 
|}
Line 271: Line 288:
 
==Example==
 
==Example==
  
The following example demonstrates what a "component" element might look like. All default values are assumed for optional attributes.
+
The following example demonstrates what a "thing" element might look like. All default values are assumed for optional attributes.
  
 
<pre>
 
<pre>
<component id="WeaponBase" name="Weapon"
+
<thing id="MyThing" name="Sample" compset="Race" isunique="yes"
      autocompset="no" hasshortname="yes" panellink="armory">
+
   description="Description goes here">
   <field id="wpDamage" name="Damage" type="derived" maxlength="20"/>
+
   <fieldval field="FieldId" value="42"/>
   <field id="wpNetAtk" name="Net Attack" type="derived"/>
+
   <tag group="Helper" tag="MyTag"/>
   <usage usagepool="mypool"/>
+
   <bootstrap thing="MyAbility"/>
  <linkage linkage="attribute" optional="no"/>
+
   <eval phase="Setup" priority="5000">
  <identity group="Weapon"/>
+
     ~script code goes here
  <displace target="hero">Helper.Displace</displace>
+
     </eval>
   <tag group="Equipment" tag="Hand"/>
+
   </thing>
   <eval index="1" phase="Final" priority="5000"><![CDATA[
+
     ~insert script code here
+
     ]]></eval>
+
  <evalrule value="1" phase="Validate" priority="5000" message="Resource overspent">
+
    ~insert script code here
+
    ]]></evalrule>
+
  <prereq message="Requirement not met">
+
    <match>Helper.WeapCheck</match>
+
    <valid><![CDATA[
+
      ~insert script code here
+
      ]]></valid>
+
    </prereq>
+
   </component>
+
 
</pre>
 
</pre>

Latest revision as of 18:32, 8 September 2011

Context: HL KitKit Reference … Data File Reference 

The "thing" Element

The vast majority of objects that will comprise your data files are "things", which will be added to actors and customized via scripts. By definition, all behaviors for things are inherited by any derived picks, unless specified otherwise. Each thing is specified through the use of a "thing" element. The complete list of attributes for this element is below.

id Id – Specifies the unique id of the thing. This id is used in all references to the thing.
compset Id – Specifies the unique id of the component set from which this thing is derived.
name Text – Public name associated with the thing. Maximum length of 100 characters.
description (Optional) Text – Detailed description text associated with the thing, for display to the user. Default: Empty.
summary (Optional) Text – Brief summary description for the thing, for display to the user in space-constrained situations. If empty, the full description is always used as the summary. Default: Empty.
isunique (Optional) Boolean – Indicates whether this thing is treated as unique within each container. If unique, a single pick is only ever added, while non-unique things can be separately added any number of times. Default: "no".
holdable (Optional) Boolean – Indicates whether this thing can be held within other other things, such as backpacks hold various pieces of gear. Default: "yes".
maxlimit (Optional) Integer – Specifies the maximum number of instances of this thing that can be added to a given container. If zero, there is no limit imposed. Default: "0".
panellink (Optional) Id – Specifies the unique id of a panel that is officially associated with this thing. Scripts can generically determine the panel linked to a thing to mark it invalid if picks within the panel are invalid. If empty, the default panel linkage defined by components is assumed. Default: Empty.
stacking (Optional) Set – Designates the default stacking behavior to be assumed whenever this thing is purchased by the user. Must be one of these values:
  • solo – Item is created individually, so buying 5 of the thing will add 5 separate instances of the thing to the container.
  • new – Item is purchased as a new group, so buying 5 of the thing will add one new instance of the thing that has a quantity of 5.
  • merge – Item is merged to any existing instance of the thing within the container, adding the quantity purchased to the existing quantity. If item does not currently exist, "new" behavior is used.
  • never – Item can never support stacking.
  • Default: "solo".
lotsize (Optional) Integer – Specifies the number of items typically purchased as a single unit when buying this thing. For example, bullets might be purchased by the box, with a box having 25 bullets in it. Default: "1".
replaces (Optional) Id – Specifies the unique id of another thing which is completely replaced by this thing. All references to the replaced thing are automatically mapped to this thing, such as bootstrapping. This allows you to wholesale replace a built-in item with new behaviors of your own choosing. If empty, no replacement behavior is utilized. Default: Empty.
buytemplate (Optional) Id – Specifies the unique id of a template that is used for purchasing the thing. This attribute is only applicable to things which have a child entity and whose purchase cost is variable based on the user-specified composition of the child entity. The specified template is used similarly to the buy template that appears within tables and choosers. However, the template is centered at the bottom of the form used for editing the child gizmo. This mechanism is needed when you have something like a user-customizable magic item within the d20 System, where the cost is based on the options selected by the user. If empty, no template is associated with the thing. Default: Empty.
xactspecial (Optional) Integer – When a buy template is shared between two or more portals or things, the template behavior may need to be tailored based on the usage. If this need arises, this attribute specifies a unique value that identifies this particular usage. By assigning a different value to each usage and keying on it within the template's Position script, you can tailor the template appropriately. Default: "0".
isprivate (Optional) Boolean – Indicates whether this thing should be kept private from users within the integrated Editor. When a user creates a new thing as a copy of another thing, all existing things derived from the compset are presented for use as the copy source. By making this thing private, it will not appear for selection. Default: "no".

The "thing" element also possesses child elements that define various facets of the thing. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

fieldval Zero or more "fieldval" elements may appear as defined by the given link. This element specifies the starting value for individual fields within the thing.
arrayval Zero or more "arrayval" elements may appear as defined by the given link. This element specifies the starting value for individual array and matrix elements within the thing.
usesource Zero or more "usesource" elements may appear as defined by the given link. This element specifies the sources relied upon for this thing to be accessible to the user.
tag Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to the thing.
bootstrap Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped when this thing is added to a container.
containerreq Zero or more "containerreq" elements may appear as defined by the given link. This element specifies any container requirements for the thing.
holdlimit An optional "holdlimit" element may appear as defined by the given link. This element defines a HoldLimit Tag Expression that restricts the valid set of gear that can be held by the thing.
gear An optional "gear" element may appear as defined by the given link. This element defines a Gear Script for the thing to calculate its weight.
link Zero or more "link" elements may appear as defined by the given link. This element specifies the specific pick linkages that exist for this thing.
eval Zero or more "eval" elements may appear as defined by the given link. This element specifies any Eval Scripts that must be performed for the thing.
evalrule Zero or more "evalrule" elements may appear as defined by the given link. This element specifies any EvalRule Scripts that must be performed for the thing.
pickreq Zero or more "pickreq" elements may appear as defined by the given link. This element specifies any dependencies upon other picks within the container.
exprreq Zero or more "exprreq" elements may appear as defined by the given link. This element specifies any expression-based dependencies upon the state of the container.
prereq Zero or more "prereq" elements may appear as defined by the given link. This element specifies any pre-requisite tests that are applied to the thing.
child An optional "child" element may appear as defined by the given link. This element defines the particulars of a child entity that is attached by the thing.
minion An optional "minion" element may appear as defined by the given link. This element defines the particulars of a minion that is attached by the thing.

The "fieldval" Element

The "fieldval" element defines the starting values to use for various fields within the thing. To initialize elements within arrays and matrices, please see the "arrayval" element (below). The complete list of attributes for this element is below.

field Id – Unique id of the field for which to specify a starting value.
value Text – Starting value to assign to the field. If the field is text-based, the value is simply assigned, although it may be truncated if it exceeds the defined maximum length for the field. If the field is value-based, the text is converted to a floating point value and assigned.

The "arrayval" Element

The "arrayval" element defines the starting values to use for individual elements within array and matrix fields of the thing. To initialize elements within fields that are not an array or matrix, please see the "fieldval" attribute (above). The complete list of attributes for this element is below.

field Id – Unique id of the field for which to specify a starting value. If the field is not an array or matrix, an error is reported.
index Integer – Specifies the row index of the element to be initialized. The first element of arrays and matrices is index zero.
column (Optional) Integer – Specifies the column of the element to be initialized within a matrix. The first element of matrices is index zero. This attribute is required for matrix elements and may be omitted for array elements. Default: Empty.
value Text – Starting value to assign to the field element. If the field is text-based, the value is simply assigned, although it may be truncated if it exceeds the defined maximum length for the field. If the field is value-based, the text is converted to a floating point value and assigned.

The "usesource" Element

The "usesource" element specifies a source that this thing is dependent upon. If the designated source is not enabled by the user, this thing will be treated as not existing for the character. You may define a new source on-the-fly via this element by providing a new unique id and the appropriate additional information. However, you should typically avoid doing so, since you cannot control important facets of sources with just-in-time definition. The complete list of attributes for this element is below.

source Id – Specifies the unique id of the source with which to establish a dependence.
name (Optional) Text – Name to be displayed to the user for this source. Maximum length is 50 characters. If the source already exists, this attribute can be left empty. Default: Empty.
parent (Optional) Id – Specifies the unique id of a different source that is treated as the parent of this source. All sources are displayed in a hierarchy within the "Configure Hero" form. If the source already exists, this attribute can be left empty and the behaviors of the existing source are utilized. If empty and the source does not yet exist, the new source is presented to the user as a top-level selection. Default: Empty.

The "holdlimit" Element

The "holdlimit" element defines a HoldLimit Tag Expression for the thing, which restricts the set of things that can be assigned to this thing as held gear. The tag expression is compared against the tags assigned to each prospective piece of gear that the user wants to move. If the tag expression is satisfied, the gear can be held within the thing, else it cannot. The complete list of attributes for this element is below.

PCDATA TagExpr – Specifies the code comprising the HoldLimit tag expression.

The "gear" Element

The "gear" element defines a Gear Script for the thing, which is used to calculate the weight of held items and perform additional gear processing on the thing. The complete list of attributes for this element is below.

PCDATA Script – Specifies the code comprising the Gear script.

The "link" Element

The "link" element defines a linkage to another thing based on the set of possible linkages defined for the underlying components. The complete list of attributes for this element is below.

linkage Id – Unique id of the linkage that is being setup for this thing.
thing Id – Unique id of the thing to which the linkage should be established.

The "pickreq" Element

The "pickreq" element defines a dependency on a specific thing whose existence is important within the container. The complete list of attributes for this element is below.

thing Id – Unique id of the thing upon which the dependency is being established.
iserror (Optional) Boolean – Indicates whether failure of the requirement should be treated as an error or merely a warning. Default: "yes".
ispreclude (Optional) Boolean – Indicates whether the specified thing must exist or must not exist within the container in order for the requirement to be satisfied. Preclusion implies that the thing is not allowed to exist. Default: "no".
onlyonce (Optional) Boolean – Indicates whether the pre-requisite should only be reported to the user a single time if it fails, regardless of the number of times the thing is added to the container. Default: "no".
issilent (Optional) Boolean – Indicates whether the pre-requisite should report an error message to the user if failed. Default: "no".

The "exprreq" Element

The "exprreq" element defines a dependency on an arithmetic expression that must be satisfied by the container. The complete list of attributes for this element is below.

message Text – Specifies the message to be reported if the requirement is not satisfied.
iserror (Optional) Boolean – Indicates whether failure of the requirement should be treated as an error or merely a warning. Default: "yes".
onlyonce (Optional) Boolean – Indicates whether the pre-requisite should only be reported to the user a single time if it fails, regardless of the number of times the thing is added to the container. Default: "no".
issilent (Optional) Boolean – Indicates whether the pre-requisite should report an error message to the user if failed. Default: "no".
PCDATA Text – Specifies an arithmetic expression that is applied to the container to determine whether the requirement is satisfied. The expression must be a valid chunk of script code that can be placed between the parentheses in a standard "if/then" statement (e.g. "if (expr) then").

The "child" Element

The "child" element specifies an entity that is always added as a child gizmo of the thing. The complete list of attributes for this element is below.

entity Id – Specifies the unique id of the entity to be attached as a child gizmo.

The "child" element also possesses child elements that tailor the entity. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

tag Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to the gizmo when it is created.
bootstrap Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped into the gizmo when it is created.

The "minion" Element

The "minion" element specifies that the thing always attaches a minion. The complete list of attributes for this element is below.

id Id – Specifies the unique id to be used for the minion attached via this thing.
ownmode (Optional) Boolean – Indicates whether the minion has an independent creation/advancement mode from its master. In some cases, you will want the minion to possess the same behavior as the master and transition with the master. However, if the minion is constructed as an independent character, you may want to handle advancement separately. Default: "yes".
isinherit (Optional) Boolean – Indicates whether the minion inherits the set of enabled sources from its master. If inheritance is active, the source selections for the master are locked in for the minion, with any changes to the master being immediately reflected within the minion. Default: "yes".

The "minion" element also possesses child elements that tailor the minion. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

tag Zero or more "tag" elements may appear as defined by the given link. This element specifies any tags that are automatically assigned to the minion when it is created.
bootstrap Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies any things that are automatically bootstrapped into the minion when it is created.

Example

The following example demonstrates what a "thing" element might look like. All default values are assumed for optional attributes.

<thing id="MyThing" name="Sample" compset="Race" isunique="yes"
  description="Description goes here">
  <fieldval field="FieldId" value="42"/>
  <tag group="Helper" tag="MyTag"/>
  <bootstrap thing="MyAbility"/>
  <eval phase="Setup" priority="5000">
    ~script code goes here
    </eval>
  </thing>