The RPData file contains any static data you might need for a game. I've used it to hold races, modifiers, monsters and more. If there is a large amount of data that needs to be referenced by a character sheet then RPData files are the way to do it.
RPData files are loaded into an internal database w/in CT. Each property defined in the file ends up as a column in the table. There isn't anything that the game settings file editors have to know about the database as it is completely hidden. But you can access the database directly outside of CT see what is going on. I've found that this is a useful way to debug things. The code provides a numeric key for each of the records, but this isn't very useful in a character sheet since it just numbers the records as they are loaded. So there should always be a unique property that is stored in the table. By convention I use a property called name. I make the value if it displayable to the user so that it is easy to show in tables and combo boxes, but that isn't required it just makes other things easier. If you have a unique property defined for the data file then it is possible to refer to the data in the file using a SLOT type of property in the propertyDescriptorSet.xml file.
The actual file format consists of two sections. The first is a limited version of the property descriptor set xml file described in an earlier post. The second section is the definition of each item in the table. These are wrapped in a document element called <rptools-data>. It looks like this:
<!-- Limited form of the property descriptor set defined earlier -->
<!-- A single record in the database. The element name is the same as the type defined in the property-set above. -->
<!-- Last record in the table -->
The limitations placed on the <property-set> element are that there can be no MAP or LIST data types defined within it. This is because the the database tables are not hierarchical. Since there aren't any MAP properties there isn't a need for the <property-sets> element in this file either. The only data types can be stored in a table are BOOLEAN, NUMBER, STRING, IMAGE, SCRIPT & SLOT. The MAP & LIST types and the <property-sets> element are ignored by the database code and will not generate exceptions.
There are two attributes defined that are only used in RPData files. These are @slot and @game-prop. When the @slot attribute is defined on any property and it contains the value 'modifiable' CT will allow that value to be modified by scripts and forms that display that value from a SLOT. Trying to modify any other child property values in a SLOT type of property will generate an error. These property values are also saved with the rest of the character data for use later. It is possible to add new properties to a SLOT value, but they would have to contain string values. The @slot attribute lets you define a data type for them as well.
The other special attribute is @game-prop. It is used to link a property in the table with a property from the propertyDescriptorSet.xml. Normally they would be linked by name, but the propertyDescriptorSet has a hierarchical structure and the table does not. So there is a need to map the property names for those values that are not stored at the root of the propertyDescriptorSet. Right now this is only used for IT's combatant look up table. It contains a bunch of monsters that can be loaded from the database and placed into the hierarchical structure of a combatant.
The <property-set> element contains a <type> element (See propertyDescriptorSet.xml in an earlier post). This element describes the type of data and is used in the @data attribute for SLOT type values. It is also the element name for each record in the table. The above example shows this. The value for <type> is stuff, each record in the second section is stored in a <stuff> element. The child elements for each record are the names of the properties defined in the <property-set> element. The order you define the children is not important, and it is not required that you have an element for each property defined. If no element is in the record then the default value for the property type is used. Here is an example of a RPData file with all of the pieces:
<description>Classes available to characters.</description>
<game>D & D 4e</game>
<property name="name"><description>Unique name of the class.</description></property>
<property name="role"><description>Text describing the roles of this class.</description></property>
<property name="powerSource"><description>Text describing the source of your powers.</description></property>
<property name="keyAbilities"><description>Text describing the key abilities for this class.</description></property>
<property name="armorProficiencies"><description>Text describing the armor proficiencies for this class.</description></property>
<property name="weaponProficiencies"><description>Text describing the weapon proficiencies for this class.</description></property>
<property name="bonusToDefense"><description>Text describing the defense bonus for this class.</description></property>
<property name="firstLevelHitPoints"><description>The number of hit points received at first level.</description></property>
<property name="firstLevelHitPointScript" type="SCRIPT"><description>The number of hit points received at first level.</description></property>
<property name="hitPointsPerLevel" type="NUMBER"><description>The modifier applied to the AC defense.</description></property>
<property name="healingSurges" type="SCRIPT"><description>The number of healing surges for this class.</description></property>
<property name="trainedSkills"><description>Text describing the skills available and the number trained for this class.</description></property>
<property name="buildOptions"><description>Text describing the build options for this class.</description></property>
<property name="classFeatures"><description>Text listing the class features for this class.</description></property>
<property name="modifierSetName"><description>Name of modifier set that provides defense.</description></property>
<role>Defender. You are very tough and have the exceptional ability to contain enemies in melee.</role>
<powerSource>Martial. You have become a master of combat through endless hours of practice, determination, and your own sheer physical toughness.</powerSource>
<keyAbilities>Strength, Dexterity, Wisdom, Constitution</keyAbilities>
<armorProficiencies>Cloth, leather, hide, chainmail, scale; light shield, heavy shield</armorProficiencies>
<weaponProficiencies>Simple melee, military melee, simple ranged, military ranged</weaponProficiencies>
<firstLevelHitPoints>15 + Constitution Score</firstLevelHitPoints>
<firstLevelHitPointScript>15 + root.con.current</firstLevelHitPointScript>
<healingSurges>9 + root.con.currentMod</healingSurges>
From the class skills list below, choose three trained skills at 1st level.<br/><i>Class Skills:</i> Athletics (Str),
Endurance (Con), Heal (Wis), Intimidate (Cha), Streetwise (Cha)
<buildOptions>Great weapon fighter, guardian fighter</buildOptions>
<classFeatures>Combat Challenge, Combat Superiority, Fighter Weapon Talent</classFeatures>
- type The type of data is class. Therefore each record in the file is kept in an element named <class>.
- name This is the unique class name. I use it in combo boxes on my Abeille form so that the user can easily pick their class. It's value has to be unique within the table or the SLOT property won't know which of the 2 records to load.
- firstLevelHitPoints is a SCRIPT property type. In this example it has it's script defined in the <firstLevelHitPoints> of the <class> data element. But it is also possible to define the script with the property. It will become the default script for those <class> elements that do not have a <firstLevelHitPoints> element. This is also a useful way to define default values for other columns.
- trainedSkills is a regular STRING type of data that contains html. CT does not use html directly, but some of the components that you would place on an Abeille form do recognize it. The two main ones are Labels and Editor Panes. If you try to show this value in a component that doesn't recognize html, you will see all of the markup in the component.