dfn_typ_form - ryzom/ryzomcore GitHub Wiki

Georges is a versatile and flexible form loader built upon XML. A basic Georges form is comprised of three basic elements:

• The Form itself — an XML file with a game-specific extension (e.g. .creature, .sitem).
• Definition (.dfn) files — define the structure (fields, arrays, sub-structures) of a form.
• Type (.typ) files — define the primitive value types used by definition fields.

To better understand how the pieces of a form come together it is easiest to learn the files in reverse order. Forms rely on definitions which rely on types. A type is the simplest piece of configuration in a Georges form.

Types are the smallest block of information in creating a Georges form. Before doing anything else you will need a set of basic types and an understanding of creating custom ones for your data types. First we'll show you two samples. These are types that can be used in a real application but are simple enough to see the basics of a type and give some examples elements to describe.

<?xml version="1.0"?>
<TYPE Type="SignedInt" UI="EditSpin" Default="0" Min="-9223372036854775808" Max="9223372036854775807">
</TYPE>

<?xml version="1.0"?>
<TYPE Type="String" UI="NonEditableCombo" Default="false">
  <DEFINITION Label="true" Value="true"/>
  <DEFINITION Label="false" Value="false"/>
</TYPE>

All type files should contain only one TYPE element but can contain several DEFINITION elements under TYPE. You can place other elements inside of a TYPE tag. For example some of the NeL tools will add a COMMENT and a LOG entry into the block to track changes on the type. Most of the properties of a type are self explanatory, but the DEFINITION elements need some extra commentary. DEFINITIONs have a Label and a Value. The Label is the information used in form comparison and validation. The Value is what is returned when an atom is requested via the API for an atom matching that label. This is a way to create a list of valid values that don't adhere to minimum and maximum, for example the string-based boolean type above.

All types can contain the following properties:

• Type — the type of data this will return. Required.
• UI — the type of UI widget an editor would use to edit this. Required.
• Default — the default value of elements/atoms using this data type.
• Min — for numeric types, the minimum valid value.
• Max — for numeric types, the maximum valid value.
• Increment — for numeric values, the increment step the UI should use for editing.

There are five valid data types:

The following are valid UI types that Georges will parse and provide to any editor tool:

Not all UI types are valid for all data types. For example, ColorEdit can only be used with the Color type, and FileBrowser can only be used with String.

Definitions define the types of arrays, structures and atoms available in the form and the type of information they provide. All forms require one definition file at the minimum, the first definition file is loaded based upon the form's file extension. For example if your form file is named sample.config_data Georges will load the config_data.dfn definition file (and any definitions or types it utilizes) before it processes the form data. Definition files have two main elements:

• ELEMENT — this describes the data contained in an atom, struct, or array.
• PARENT — this forces a definition to load other definitions as dependencies. This is useful if you have some often-used atoms that you want to share across multiple DFN files.

Here is an example definition file:

<?xml version="1.0"?>
<DFN>
        <ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/>
        <ELEMENT Name="TestVal2" Type="Type" Filename="int.typ" Default="0"/>
        <ELEMENT Name="WriteVal" Type="Type" Filename="int.typ" Default="0" />
        <ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/>
        <ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/>
        <ELEMENT Name="TestByBracket" Type="Type" Filename="boolean.typ" Array="true"/>
        <ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" />
</DFN>

Elements are the most complicated piece of a definition as they have a number of variations depending on the type of data their atoms, etc. would contain. Elements with a type of "Type" will represent atoms that contain values. Elements require a Name, Type, and Filename property at the minimum. Elements represent three different types of data types: structs, arrays, and atoms. If you look ahead to forms, these different types of data may make more sense. In the XML above we see five examples of atom types, two arrays, and a structure.

When setting up an element for an atom you need to name it (this is the name will be the one that the atom will use in the form,) you need to define its type as "Type," and you need to define a filename. The filename defines the type of data (see types, above) any atoms using this element will use. Elements for atoms are the most simple types of element definitions. Note that you can also set the default value for an atom here, overriding the default value defined by the type.

<ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/>

In our example we also define a named struct. In the form when you do <STRUCT Name="PositionData"> you need to create an element to describe this struct. Here is the example from above:

<ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" />

The name of the element must match the name of the struct in the form. You will set your type to Dfn and define the definition file's filename in the Filename property. This tells Georges this is a struct and how to determine what atoms are members of it. Finally you need to flag Array="false" so that Georges knows it's just one struct, not a named array of them.

There are two types of arrays to consider when creating an element entry for an array.

Arrays of atoms are the easiest types of array to define. Take the following snippet from the definition example above:

<ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/>

In essence what we've done was created an element definition for an atom and used the Array="true" property to tell Georges to expect a list of strings. You'll see an example of defining this array in the section on creating and editing forms.

An array of structs is slightly more complicated, but still fairly simple in syntax. Instead of defining the type as "Type" you would define it as "Dfn." This tells Georges that it should expect a list of structures containing the elements listed in the Filename. Look at the following snippet from the XML above:

<ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/>

We've informed Georges here that an array named "CoolFilesInfo" is going to contain a list of structs with the info contained in the definition file "coolfilesinfo.dfn."

Elements can have the following properties:

Valid Element Type values are:

Using the information from above about types and definitions you can finally get down to working on creating your form. Below is a trimmed down version of the form used in the Georges sample. Notice that the file extension of the form matches the definition filename: a .sample_config form loads sample_config.dfn.

<?xml version="1.0"?>
<FORM Version="0.0" State="modified">
        <STRUCT>
                <ATOM Name="TestVal1" Value="1"/>
                <ARRAY Name="TestArray">
                        <ATOM Value="Array Val 1"/>
                        <ATOM Value="Array Val 2"/>
                </ARRAY>
                <ARRAY Name="CoolFilesInfo">
                        <STRUCT>
                                <ATOM Name="ShortName" Value="Tiger Attack"/>
                                <ATOM Name="Ranking" Value="55"/>
                        </STRUCT>
                        <STRUCT>
                                <ATOM Name="ShortName" Value="Crazy Car Jump"/>
                                <ATOM Name="Ranking" Value="40"/>
                        </STRUCT>
                </ARRAY>
                <STRUCT Name="PositionData">
                        <ATOM Name="x" Value="1"/>
                        <ATOM Name="y" Value="1"/>
                        <ATOM Name="z" Value="2"/>
                </STRUCT>
        </STRUCT>
</FORM>

Looking at the example form above you should start to see how forms reference elements in definitions. Some important things to note about forms. The first element must always be either a STRUCT or a PARENT and parents should come before STRUCTs. You should never put any other element type directly under a FORM. In the code example you will see that you can access the ATOMs in the first (default) struct by referring to them in dot notation such as ".TestVal1" — the dot denotes they're a member of the root structure.

ATOMs represent individual data values. Atoms all have a Name property and a Value property. A name for an atom may be left out only if it is a member of a named array. Look at the TestArray example — the atoms contained in that array inherit their name (and thus element info) from the array.

Arrays in a form are simple. All they require is a name. This name allows Georges to find the element type from the definition and thus atom or definition information required to describe the items in the array. In the example above I provided two types of arrays: an array of structures and an array of atoms. Arrays can be accessed programmatically by index using bracket notation. In the case of TestArray you can access elements using TestArray[0], and in the case of CoolFilesInfo you could access member data as CoolFilesInfo[0].Ranking.

Structs are used in a number of ways already described in detail. But they can also be used as standalone named sub-structures, accessed in dot notation. You can see this in the PositionData example in the form. Members of this structure can programmatically be accessed via the root node using the name PositionData.x or any of the other members.

A VSTRUCT is used for DfnPointer elements. Unlike a regular STRUCT whose definition is fixed by the DFN, a virtual struct specifies which DFN it uses at the form level. This allows different form instances to have different structures in the same field. This is useful for polymorphic or variant data.

<VSTRUCT Name="MyPolymorphicField" DfnName="specific_variant.dfn">
        <ATOM Name="FieldFromVariant" Value="42"/>
</VSTRUCT>

A form can inherit from one or more parent forms using PARENT elements. This allows creating a base form with default values and then overriding only the fields that differ in child forms. Parent forms are listed before the main STRUCT.

<FORM Version="0.0" State="modified">
        <PARENT Filename="base_creature.creature"/>
        <STRUCT>
                <ATOM Name="HitPoints" Value="500"/>
        </STRUCT>
</FORM>

Forms can contain the following XML elements:

• Nevrax.org : NeLGeorgesForms (archive.org)