Table des matières

Datasheets

Datasheets

Toute les informations sur l'univers de jeu sont générées à partir de formulaires de données écrits sous l'aspect de fichiers xml. Ils sont généralement édités par le biais de Georges Editor mais peuvent également être modifiés par un simple éditeur de texte, comme n'importe quel fichier xml¹⁾. Pour se familiariser avec l'aspect de ces données, il est possible d'aller consulter ceux qui sont fournis avec les sources du serveur Ryzom Core dans votre arborescence dans :

code/ryzom/common/data_leveldesign/leveldesign

Les fichiers .dfn et .typ sont dans le sous-répertoire DFN.

Les formulaires FORM

Un formulaire contient des éléments formels obligatoires.

Exemple

default.sample_config

<?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>

La première chose à indiquer est le type de fichier :

<?xml version="1.0"?>

Il faut ensuite,dans l'ordre :

un élément <FORM></FORM> qui peut indiquer comme là la version du fichier Version=“” et l'état State=“” - OBLIGATOIRE ;
un élément <PARENT Filename=“” /> - qui indique un fichier de dépendance qui sera traité avant le formulaire lui-même - FACULTATIF ;
un élément <STRUCT></STRUCT> - pour organiser les données que le formulaire contient - OBLIGATOIRE ;
un élément <COMMENT></COMMENT> - pour donner des indications générales - FACULTATIF ;
un élément <LOG></LOG> - pour garder trace des changements - FACULTATIF.

Pour pouvoir créer des formulaires, on va se baser sur un système de parentage et d'héritage.
Un formulaire nécessite un fichier de définition au minimum (.dfn), la première définition chargée se basant sur l'extension du nom du formulaire.
Exemple
Si vous créez un formulaire qui s'appelle exemple.config_data, Georges chargera la définition config_date.dfn (et donc toutes les définitions et types qu'elle contient) avant d'exécuter ce formulaire de données.
Commençons donc par voir comment établir les Définitions (fichiers .dfn) et les Types (fichiers .typ).

Les deux types de base : .typ et .dfn

Il existe deux types essentiels : les .typ (type) et les .dfn (définition).
Les Définitions s'expriment elles-mêmes à l'aide de Types.

Les fichiers .dfn et .typ les plus basiques sont classés dans les sources de Ryzom Core dans :
/code/ryzom/common/data_leveldesign/leveldesign/DFN/basics

Les Types .typ

Les Types sont les plus petits blocs d'information qui puissent être enregistrés dans un formulaire Georges. Avant de pouvoir définir des données plus complexes, il est essentiel de mettre en place les types les plus basiques. Créer de tels documents manuellement permet de mieux en comprendre le fonctionnement.

Exemple 1 : int.typ, entier

int.typ

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

Exemple 2 : boolean.typ, booléen

boolean.typ

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

On le voit dans ces deux exemples, le formulaire Georges .typ contient tout d'abord :

<?xml version="1.0"?>

Puis un élément “TYPE”, qui doit être unique, s'ouvrant par <TYPE> et se fermant par </TYPE>.
Il contient lui-même éventuellement un ou plusieurs éléments “DEFINITION”, : <DEFINITION Label=“” Value=“”/>
Il est possible d'ajouter également un élément “COMMENT” pour donner des indications générales et/ou “LOG” pour garder trace des changements.

Les TYPEs peuvent avoir les caractéristiques suivantes :

Type - le genre de données que ce type renvoie - OBLIGATOIRE ;
UI - le type de widget qui devra être utilisé par un éditeur pour ouvrir ce type - OBLIGATOIRE ;
Default - La valeur par défault des éléments qui utiliseront ce type de data ;
Min - Pour les valeurs numériques, la valeur minimale valide ;
Max - Pour les valeurs numériques, la valeur maximale valide ;
Increment - Pour les valeurs numériques l'incrément à laquelle l'UI devra recourir.

Le genre de données renvoyé peut avoir plusieurs valeurs possibles :

UnsignedInt (Entier non signé)
SignedInt (Entier signé)
Double (Nombre réel en double précision 64bits)
String (Chaîne de caractères)
Color (liste de 3 nombres définissant la couleur en mode RVB, par ex “255,255,255”)

Les UI reconnues par Georges et pour lesquelles il saura traiter les données sont :

Edit (champ texte court utilisé avec le type String)
EditSpin (zone numérique avec bouton d'incrément +1 -1 utilisée avec les types UnsignedInt, SignedInt et Double)
NonEditableCombo (liste déroulante non éditable utilisée avec le type String pour restreindre les valeurs à une liste prédéfinie)
FileBrowser (sélectionneur de nom fichier, utilisé avec le type String
BigEdit (Zone d'édition de textes longs, utilisée en conjonction avec le type String)
ColorEdit (Interface de sélection de couleur pour le type Color)

Chaque élément DEFINITION possède :

un “Label”, une étiquette. C'est avec cette identifiant que sont faites les comparaisons et les validations ;
une “Value”, une valeur. C'est ce qui est retourné en réponse à une requête ATOM via l'API dont la valeur correspond à celle de l'étiquette.

Notre fichier .typ de base doit donc ressembler à ça :

base.typ

<?xml version="1.0"?>
<TYPE Type="UnsignedInt/SignedInt/Double/String" UI="Edit/EditSpin/NonEditableCombo/FileBrowser/BigEdit/ColorEdit" [Default=""] [Min=""] [Max=""] [Increment=""]>
  <DEFINITION Label="" Value=""/>
  <DEFINITION Label="" Value=""/>
    <COMMENTS></COMMENTS>
  <LOG>Mon Jan 01 00:00:00 0000 (god) Light, please !</LOG>
</TYPE>

Les Définitions .dfn

Les Définitions indiquent les STRUCT (structures), ARRAY (tableaux) et ATOM (atomes) utilisables dans les formulaires et le type d'information qu'elles fournissent.

UN fichier .dfn se compose de deux éléments :

ELEMENT - Obligatoire, qui décrit les données en ATOM (atome), STRUCT(structure) ou ARRAY(tableau) ;
PARENT - Facultatif, qui charge un autre .dfn comme dépendance, ce qui est utile si on utilise souvent les mêmes ATOM(atomes).

Exemple

sample_config.dfn

<?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>

Là encore, le formulaire Georges .dfn contient tout d'abord :

<?xml version="1.0"?>

Puis on voit <DFN></DFN> qui encadra des <ELEMENTS […] />

Les ELEMENTS sont les parties les plus sensibles d'une définition car ils varient grandement selon le type de données qu'ils peuvent contenir. Ils contiennent à la base :

Name - le nom de cet ELEMENT - OBLIGATOIRE;
Filename - le .typ/.dfn auquel se réfère ce type - OBLIGATOIRE;
FilenameExt - Par défaut, indiqué comme “.”, indique le type d'extension de fichier à traiter - FACULTATIF;
Type - le type de cet ELEMENT (voir ci-dessous) - OBLIGATOIRE;
Default - la valeur par default de cet élément - FACULTATIF;
Array - peut être indiqué “true”/“false” selon que le formulaire donnera plusieurs éléments en tableau ou pas - FACULTATIF/OBLIGATOIRE selon type d'ELEMENT

Le type peut être :

Type - pour définir des ATOM, atomes;
Dfn - pour définir des STRUCT, structures ou ARRAY, tableaux;
DfnPointer - dont l'usage n'a pu être défini.

Les différents ELEMENT possibles

Pour définir des ATOM, Atomes, les plus simples

Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
Type - son type est “Type” - OBLIGATOIRE;
Filename - indiquer le fichier .typ pour définir le type de données que cet ELEMENT utilisera - OBLIGATOIRE;
Default - il est possible d'indiquer une valeur par défaut qui remplacera le cas échéant celle indiquée dans le fichier .typ indiqué dans Filename - FACULTATIF.

Une ligne de ce genre donnera donc :

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

Pour définir des STRUCT, Structures

Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
Type - son type est “Dfn” - OBLIGATOIRE;
Filename - indiquer le fichier .dfn pour définir les ATOM, atomes qui composeront cet ELEMENT - OBLIGATOIRE;
Array=“false” - il faut impérativement indiquer à Georges que cela n'est pas un Tableau, mais une Structure - OBLIGATOIRE.

Une ligne de ce genre donnera donc :

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

Pour définir des ARRAY d'ATOM, Tableaux d'Atomes

Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
Type - son type est “Type” - OBLIGATOIRE;
Filename - indiquer le fichier .typ pour définir les ATOM, atomes qui composeront cet ELEMENT - OBLIGATOIRE;
Array=“true” - il faut impérativement indiquer à Georges que c'est un Tableau - OBLIGATOIRE.

Une ligne de ce genre donnera donc :

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

Pour définir des ARRAY de STRUCT, Tableaux de Structures

Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
Type - son type est “Dfn” - OBLIGATOIRE;
Filename - indiquer le fichier .dfn pour définir les STRUCT, Structures qui composeront cet ELEMENT - OBLIGATOIRE;
Array=“true” - il faut impérativement indiquer à Georges que c'est un Tableau de Structures - OBLIGATOIRE.

Une ligne de ce genre donnera donc :

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

ATOM, Atomes, ARRAY, Tableaux et STRUCT, Structures

Le fichier sample_config.dfn tel qu'il a été mis en place permettra donc au fichier default.sample_config (présenté au début de cette page) de fonctionner car il définit les ATOM, STRUCT et ARRAY que ce Formulaire utilise.

les ATOM, Atomes sont les fragments de données individuels les plus petits définissables. Dans le cas où il font partie d'un ARRAY, ils peuvent ne pas avoir de nom propre, d'étiquette mais être désigné du nom de l'ARRAY suivi d'un point puis de leur position dans le tableau. Dans notre exemple, l'ATOM “TestArray.1” a comme valeur “Array Val 1” mais pas de nom explicitement indiqué ;
les ARRAY, Tableaux, qui contiennent des listes de données, peuvent concerner des ATOM (“TestArray” dans notre exemple) ou des STRUCT (“CoolFilesInfo”) dans notre exemple. Dans ce dernier cas, on extrait les données de l'ARRAY en les désignant du nom de l'ARRAY suivi d'un point puis de l'étiquette (Label) de la STRUCT. “CoolFilesInfo.Ranking” dans notre exemple
les STRUCT, Structures, indiquent également leurs valeurs en faisant appel à leur nom suivi d'un point puis de l'étiquette (Label) de l'ATOM dont on souhaite connaitre la valeur. Dans notre exemple, PositionData.x a une valeur de 1

outils, datasheet

¹⁾

Cette page est une traduction/adaptation de http://dev.ryzom.com/projects/ryzom/wiki/CreatingABasicForm.