This file contains the definitions of all of the properties available to event scripts and to Abeille forms. It is an XML file that consists of three main sections. The first is just header information about the game. The second section is in the element <property-sets> which contains common MAP definitions that can be used over and over in the third section. More on this later. The third section actually contains the definition for all of the properties used by the game. It is defined in the <properties> element right after the end of the <property-sets> element of the second section.
A property definition consists of a <property> element with a set of attributes that describe the data. There can also be elements within the <property> element depending on what type of data the property holds. Here is an example of a simple STRING property:
Code: Select all
<property name="name" type="STRING"><description>Name of the combatant.</description></property>
The @name attribute (the @ sign only appears in the documentation to highlight it from normal text) is required on all <property>s. It must be unique for all properties that have the same parent element or an error will occur. The name must be defined as a Java identifier which means that the first character should be a letter or an underscore, and all other characters in the name are alphanumeric, an underscore ('_'), or a dash ('-'). It should also follow Java variable naming conventions which are the first character is lower case and if there are any other words in the name they should start with upper case. This naming convention is also called
lowerCamelCase. While this is not required, it allows the code to automatically generate display names and database column names from the property name. If needed the values can be set explicitly by using the @display and @column attributes for the display name and database column name respectively. If the database column name is defined it is not case sensitive and does not allow dash characters. Otherwise it is the same as the property name.
The @type attribute contains one of the valid data types allowed for a property. The data types are:
- BOOLEAN: A true/false value. The RPScript language has functions that work with this type of value. The actual Java class of this type is java.lang.Boolean.
- NUMBER: A decimal number. It can also be expressed in scientific notation. The RPScript language provides add, subtract, multiply, and divide operators as well as many number manipulation functions for this type of data. The actual Java class of this type is java.math.BigDecimal, however JavaScript automatically converts all java.lang.Number subclass values into java.lang.Double values.
- STRING: Text of any kind. This is the default value for the @type attribute on the <property> element. So if the @type attribute is not set the property will automatically be a STRING. The RPScript language provides an add operator for concatenation and some string manipulation functions as well. The actual Java class of this type is java.lang.String
- MAP: This data type contains a set of named property values which can be any type, including other MAP properties. The properties in the set are defined within a child <properties> element of the MAP <property> element, which is exactly like the <properties> element that contains the third section of the propertyDescriptorSet.xml file. That element can contain as many child properties as needed. The MAP type of data also supports a special attribute named @extends. This attribute contains the name of a map defined in the second section of the propertyDescriptorSet.xml file. When the @extends attribute is set all of the properties defined in the named property set are added into this MAP. If the <properties> element defines a property with the same name as the property set named in @extends then that definition supersedes the one in the property set. See the examples below. The values in a map are referred to using a dot notation in RPScript that work like this map-property-name.child-property-name. The actual Java class of this type is net.rptools.chartool.model.property.PropertyMap.
- LIST: This data type contains a list of property values which are indexed starting at 0. The values may be all the same type or different types. To make the values all have the same type a child <property> element is defined that contains the desired type. Any type of data may be contained in the list including MAP data and other LIST's. The values in the list are referred to using a dot notation in RPScript where the child name is an index within the list. The resulting request looks like list-property-name.child-index. The actual Java class of this type is net.rptools.chartool.model.property.PropertyList.
- SLOT: A reference to a record in a database table. This lets the code look-up the values for things like race or class from a provided set of races or classes. The @data attribute is used to tell which database is used to look up the value. When the slot value is set it acts exactly like a MAP property would. The difference between them is that when the character.xml data is saved only the reference to the record is stored and not the individual properties from the database. This means that updates to values in the database tables of the game settings file automatically get inserted into the character the next time it is loaded. The values in a map are referred to using a dot notation in RPScript that work like this: slot-property-name.rpdat-property-name. The actual Java class of this type is net.rptools.chartool.model.property.SlotPropertyValue which is a sublcass of net.rptools.chartool.model.property.PropertyMap.
- IMAGE: Internally this value is a text reference to an image stored elsewhere. The reference can be to any URL supported by Java including the http, file, and jar protocols. It can also refer to an asset in a RPToken file or to an image file in the currently loaded game settings file. The RPScript code currently doesn't have any specific support for IMAGE type properties. If the property is read normally using the dot notation or the get() method then a a net.rptools.chartool.ui.component.RPIcon object is returned which is a subclass of java.swing.ImageIcon. If it is read using the internal nodeGet() method then the value returned is a java.lang.String.
- SCRIPT: This is either an RPScript or a JavaScript that returns a value. When the property value is read normally using the dot notiation or the get() method the script will be executed and the results returned. In general the value returned should be a BOOLEAN, NUMBER, STRING, or IMAGE data type because that is what RPScript supports and what most Abeille form components are expecting. This is not required if the value is never referenced from RPScript or an Abeille form. The SCRIPT data type stores its code within a <script> element that is a child of the <property> element. The first part of the contents of this element determines the type of script. The two values supported by default are RPScript and JavaScript. The script type is followed by two colons ('::'). If the script type is not defined it is assumed to be RPScript. If not using RPScript it is important to include the code in a CDATA tag so that the code does not interfere with the XML parsing. The <script> element may contain a @cacheable attribute that defines if the script value can cached for later use. When this value is true the script will not be executed to generate a value unless the parent MAP has changed since the last time the script was run. When false the script is executed every time the property value is read. In general it should only be set to false if the script generates or uses random numbers. The default value is true which is what is used if the @cacheable attribute is not defined. When the property is read using the internal nodeGet() method the data type returned is a net.rptools.chartool.model.property.Script.
Any <property> element may contain a <description> element that contains text that describes the property. It is used to provide information to users about what a property is used for. It is also useful to describe what internal properties do as you would use a comment. If any <property> element other than those of @type="SCRIPT" contain a <script> element then that script will be called when the parent property value changes. It doesn't do that for SCRIPT types because those types may not be set. There is also a some other attributes that may be set on any <property> element:
- @group This is used to group properties together when viewing a character in a property table. The property table shows a character as name value pairs and shows the property hierarchy using the expand and collapse controls like a tree. At the root of the tree @group attribute value further categorizes the properties. These groups can be defined to anything the game settings file editor needs. They are not used when displaying a character sheet.
- @visibility This attribute is used to control the display of a property in IT's table or list. It is also used to restrict access to values to just the GM, the GM & Owner, or Every one or No One. This is currently not used in the character sheets. There is also a flag for including this value in MT's Statsheets, but this has not been implemented yet either.
- @slot This is a special value only valid in RPData files. When set to the value 'modifiable' it allows scripts to update the property value in SLOT properties and to have those updated values saved with the other character data.
- @game-prop This is a special value only valid in RPData files. Since the RPData files are not hierarchical but the property data the names of the properties can not be used to match data between the structures when copying from the database to the property data. This allows for a mapping between the flat database and the hierarchical property data. This was used extensively when loading combatants from IT's look-up file.
- @mt-prop This value is used to read and write values to the content.xml file within RPToken files. These values can then be displayed in MT's Statsheet. If the property type is STRING, BOOLEAN or NUMBER the value may also be edited in MT and shown in CT.
Property examples follow:
Code: Select all
Properties for the simple data types BOOLEAN, NUMBER, & STRING:
<property name="trained" type="BOOLEAN"><description>Flag indicating a +5 trained bonus.</description> </property>
<property name="experience" type="NUMBER" group="Description"><description>The experience points earned by this character.</description></property>
<property name="gender" group="Description" visibility="IN_IT_TABLE"><description>Gender of the character.</description></property>
A MAP property that extends a property set and then overrides a SCRIPT property in that property set"
<property name="initModifier" type="MAP" group="Combat" display="Initiative Modifier" extends="modifiableValue">
<description>The calculated initiative modifier for this creature.</description>
<properties>
<property name="current" type="SCRIPT">
<description>Current initiative modifier.</description>
<script>root.dex.currentMod + totalModifiers + root.itInitiativeModifier + userMod + floor(root.level / 2)</script>
</property>
</properties>
</property>
A LIST property that only contains SLOT values from the 'modifier' database table:
<property name="modifiers" type="LIST">
<description>Modifiers applied to this value.</description>
<property name="modifier" type="SLOT" data="modifier"/>
</property>
A SLOT property value that looks up data in the 'race' database table.
<property name="race" type="SLOT" data="race" group="Description" visibility="IN_IT_TABLE">
<description>Race of this combatant.</description>
<script>replaceModifiers(rpEvent)</script>
</property>
An IMAGE property used to display the token image in MT & CT.
<property name="itToken" group="Description" display="Token" type="IMAGE" visibility="IN_IT_TABLE"><description>Token used for this creature. Used in map tool and init tool.</description></property>
A SCRIPT property for both RPScript and JavaScript:
<property name="useActionPoint" type="SCRIPT" visibility="BY_NO_ONE">
<description>The combatant uses one action point.</description>
<script cacheable="false">script("actions", "useActionPoint", root)</script>
</property>
<property name="totalDie" type="SCRIPT">
<description>This appends all of the modifiers into a single RPScript that can be eval()'ed.</description>
<script><![CDATA[JavaScript::
var script = "";
if (modifiers != null && !modifiers.isEmpty()) {
var i = modifiers.iterator();
while (i.hasNext()) {
var mod = i.next();
if (!mod.get("applies").booleanValue()) continue;
if (script.length > 0) script = script + " + ";
script = script + mod.get("bonus")
} // endwhile
} // endif
script;
]]></script>
</property>
The <properties> element is used to define the property sets used for extension in the <property-set> element and the children of other MAP type properties. It has a @default attribute that is used to determine which child property is displayed by default when showing the character in the property table view. That allows the user to see the value without having to expand the tree and find the default value manually. When the <properties> element is inside of the <property-set> element it must have an @name attribute as well. The naming follows the same rules as the @name attribute in <property> elements. These <properties> elements may also have an @extends attribute which can contain the name of property set that has already been defined earlier in the propertyDescriptorSet.xml file. It works the same was as if it had been defined in a MAP <property> element later in the file by adding all of the previously defined properties into the currently defined property set. Child properties of the property set override the property definitions provided by the extended property set. The <properties> element for the third section of the XML file which comes after the <property-set> element and contains the property definitions has no attributes at all.
The last thing (!) to talk about is the header and the over all structure of the propertyDescriptorSet.xml file. The header contains 5 required elements. The elements are <type>, <name>, <description>, <game>, and <source>. All of these attributes are just plain text. The <type> attribute is only used in RPData files, but is still required. The <name> attribute is text that describes the type and is also only used by RPData files but is still required. The <game> property is displayed in CT's & IT's title bars and Game Settings menu and dialog. The <description> and <source> properties are text describing the file and where the game settings file editor got the data. The over all structure looks like this:
Code: Select all
<property-set>
<!-- Property Header elements -->
<type>4eCombatant</type>
<name>D & D 4e</name>
<description>This is the descriptor set for D & D 4th Edition combatants.</description>
<game>D & D 4e</game>
<source>PHB</source>
<property-sets>
<!-- Property set definitions go here. Each child is a <properties> element -->
...
</property-sets>
<properties>
<!-- Property definitions go here. Each child is a <property> element -->
...
</properties>
</property-set>