Difference between revisions of "TableDef Element (Data)"

From HLKitWiki
Jump to: navigation, search
(The "select" Child Element)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{contextmulti|Kit Reference|Data File Reference}}
+
{{context|Kit Reference|Data File Reference}}
  
 
==The "tabledef" Element==
 
==The "tabledef" Element==
 +
 +
Note that for a tabledef to be associated with a table or chooser portal, you must specify the id of the tabledef for the portal's "usetabledef" attribute.
  
 
:{| class="infotable"
 
:{| class="infotable"
Line 8: Line 10:
 
|-
 
|-
 
|component
 
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table, only things / picks from this component will be shown in the table.
+
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table portal, only things / picks from this component will be shown in the table.
 
|-
 
|-
 
|isglobal
 
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify isglobal="yes". This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character of any type will need it. Default: "no".
+
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify "yes". If this is specified, you don't need to add "allowtable" tags for this table, as it's assumed to be present on all characters. This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character for the game system will need it. Default: "no".
 
|-
 
|-
 
|description
 
|description
|Text – A short string intended to communicate what the table does to the UI developers. This is is required for all tabledefs.
+
|Text – A short string intended to communicate what the table does (in very general terms, like "Adds magic weapons") to the UI developers.
 
|-
 
|-
 
|errorcategory
 
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of the appropriate category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error. See error categories and table error reporting, below, for more details.
+
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of this category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error.
 
|-
 
|-
 
|}
 
|}
  
The "tabledef" element also possesses child elements that define the specifics of the table. Both of these child elements are optional.
+
The "tabledef" element also possesses two child elements that define the specifics of the table. Both of these child elements are optional.
  
 
:{| class="infotable"
 
:{| class="infotable"
Line 98: Line 100:
 
|-
 
|-
 
|maxchoicelimit
 
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
+
|(Optional) Number – How many picks can be added to this table. Default: no limit. Must be 1 for tabledefs associated with choosers.
 
|-
 
|-
 
|transactiontype
 
|transactiontype
Line 157: Line 159:
 
|-
 
|-
 
|listpick
 
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work in concert with table portals. Default: None.
+
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work when used with portals. Default: None.
 
|-
 
|-
 
|listfield
 
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work in concert with table portals. Default: None.
+
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work when used with portals. Default: None.
 
|-
 
|-
 
|}
 
|}
Line 168: Line 170:
 
:{| class="infotable"
 
:{| class="infotable"
 
|class="leftnormal"|[[#list|list]]
 
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
+
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the table.
 +
|-
 +
|}
 +
 
 +
==The "list" Element{{anchor|list}}==
 +
 
 +
The "list" element defines a [[List Tag Expression]] for the table that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this table are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.
 +
 
 +
:{| class="infotable"
 +
|class="leftnormal"|PCDATA
 +
|TagExpr – Specifies the code comprising the List tag expression.
 
|-
 
|-
 
|}
 
|}

Latest revision as of 15:52, 10 November 2017

Context: HL KitKit Reference … Data File Reference 

The "tabledef" Element

Note that for a tabledef to be associated with a table or chooser portal, you must specify the id of the tabledef for the portal's "usetabledef" attribute.

id Id – Specifies the unique id of the tabledef.
component Id – Specifies the unique id of the component the tabledef is associated with. Like a table portal, only things / picks from this component will be shown in the table.
isglobal (Optional) Boolean – if the table is used by ALL characters for the game system, specify "yes". If this is specified, you don't need to add "allowtable" tags for this table, as it's assumed to be present on all characters. This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character for the game system will need it. Default: "no".
description Text – A short string intended to communicate what the table does (in very general terms, like "Adds magic weapons") to the UI developers.
errorcategory (Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of this category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error.

The "tabledef" element also possesses two child elements that define the specifics of the table. Both of these child elements are optional.

select Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
show Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).

The "select" Child Element

choosepicks (Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
  • thing – The selectable objects are things.
  • container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.
  • hero – The selectable objects are picks from the active actor.
  • Default: "thing".
buyaction (Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
sellaction (Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
wrapupaction (Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
linkage (Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
candidatepick (Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated Candidate tag expression for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
candidatefield (Optional) Id – Specifies the unique id of a text-based field that contains the Candidate tag expression used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
secondphase (Optional) Id – Specifies the phase of the Secondary tag expression for this table, if one is present. Default: Empty.
secondprior (Optional) Number – Specifies the priority of the Secondary tag expression for this table, if one is present. Default: Priority specified in the game system definition file.
existphase (Optional) Id – Specifies the phase of the Existence tag expression for this table, if one is present. Default: Empty.
existprior (Optional) Number – Specifies the priority of the Existence tag expression for this table, if one is present. Default: Priority specified in the game system definition file.
prereqtarget (Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
  • container – The default parent container is used.
  • parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.
  • hero – The top-level hero is used, which parallels the corresponding displacement target.
  • Default: "container".
empty (Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
useagentcandidate (Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
useagentlinkage (Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
agentautotag (Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
maxchoicelimit (Optional) Number – How many picks can be added to this table. Default: no limit. Must be 1 for tabledefs associated with choosers.
transactiontype Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
autothing (Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
selectnone (Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".

The "select" element also possesses child elements that define additional behaviors of the table. 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.

candidate An optional "candidate" element may appear as defined by the given link. This element defines a Candidate Tag Expression for the table.
restriction An optional "restriction" element may appear as defined by the given link. This element defines a Restriction Tag Expression for the table that identifies things which cannot be selected if they've already been added to this table.
needtag Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
denytag Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must not exist between a prospective object and the container in order to list the object among the available items.
secondary An optional "secondary" element may appear as defined by the given link. This element defines a Secondary Tag Expression that is associated with every new pick added via the table.
existence An optional "existence" element may appear as defined by the given link. This element defines an Existence Tag Expression that is associated with every new pick added via the table.
autotag Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
ignorerequirements An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
change An optional "change" element may appear as defined by the given link. This element defines a Change Script for the table.

The "show" Child Element

allowstack (Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
agentlist (Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
allowmove (Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
listpick (Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work when used with portals. Default: None.
listfield (Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work when used with portals. Default: None.

The "show" element also possesses child elements that define additional behaviors of the table. 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.

list An optional "list" element may appear as defined by the given link. This element defines a List Tag Expression for the table.

The "list" Element

The "list" element defines a List Tag Expression for the table that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this table are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

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

The "candidate" Element

The "candidate" element defines a Candidate Tag Expression for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

inheritlist (Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
PCDATA TagExpr – Specifies the code comprising the Candidate tag expression.

The "restriction" Element

The "restriction" element defines a Restriction Tag Expression for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to this table. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

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

The "needtag" Element

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

container Id – Specifies the unique id of the tag group to utilize within the container.
thing Id – Specifies the unique id of the tag group to check within the thing/pick.
usehero (Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".

The "denytag" Element

The "denytag" element defines a tag relationship that must not exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

container Id – Specifies the unique id of the tag group to utilize within the container.
thing Id – Specifies the unique id of the tag group to check within the thing/pick.
usehero (Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".

The "secondary" Element

The "secondary" element defines a Secondary Tag Expression that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional Container Tag Expression for the pick that must also be satisfied. The complete list of attributes for this element is below.

phase (Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
priority Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
PCDATA TagExpr – Specifies the code comprising the Secondary tag expression.

The "existence" Element

The "existence" element defines an Existence Tag Expression that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

phase (Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
priority Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
PCDATA TagExpr – Specifies the code comprising the Secondary tag expression.

The "change" Element

The "change" element defines a Change Script for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

PCDATA Script – Specifies the code comprising the Change script.