Description d'objet
De WikiPlee.
Les fichiers de description d'objet sont des fichiers XML décrivant les attributs d'un objet du jeu. Ils sont utilisés par l'éditeur de niveaux et l'éditeur de modèles.
Lors du chargement d'un niveau (ou d'un modèle), les valeurs données à ces attributs sont passées à l'objet en question via les méthodes set_*_field() de la classe base_item.
Sommaire |
[modifier] Description d'objet
Un objet est décrit dans un nœud ayant <item> comme balise. Cette balise a deux attributs obligatoires : la classe de l'objet et sa catégorie. Le premier doit être exactement le nom de la classe dans le code. Le second n'est, quant à lui, qu'un moyen de classer les objets dans l'éditeur, pour les présenter à l'utilisateur. La catégorie n'a aucune autre utilité. De plus, les objets ayant la catégorie particulière nommée -abstract- ne sont pas présentés à l'utilisateur. Cette catégorie ne sert que pour des classes destinées à être héritées (voir plus bas).
Les objets sont présentés à l'utilisateur sous forme arborescente, selon la catégorie. Celle donnée dans le fichier peut être divisée par le caractère '/' pour spécifier le chemin dans l'arbre, sous la forme "catégorie/sous_catégorie/…/sous_catégorie_finale".
La balise <item> a deux autres attributs, optionnels. L'attribut box_color permet d'indiquer la couleur de la boîte qui représente l'objet dans l'éditeur. Il prend comme valeur une couleur au format HTML, c'est à dire une chaîne de type "#RRVVBB", où RR représente la valeur de la composante rouge, en hexadécimal de 0 à FF (soit 0 à 255 en décimal) ; VV représente la valeur de la composante verte et BB représente la valeur de la composante bleue.
Une autre information à propos de l'item est s'il est autorisé à être fixe. Certains objets se déplacent dans le niveau, alors que d'autres, comme les murs, restent à une position fixe. Si l'objet se déplace, il n'est pas autorisé à être fixé. L'attribut fixable permet d'indiquer cette possibilité. Cet attribut est hérité ; si un objet est marqué comme non fixable, tous les objets en héritant seront non fixables aussi. Par défaut, les objets sont considérés comme pouvant être fixés.
L'exemple ci-dessous défini une classe nommée ma_classe, présentée dans la catégorie ma_catégorie, affichée en jaune et pouvant être fixé :
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"/>
[modifier] Héritage
Certains objets ont des champs en commun, comme le paramétrage de la taille ou de la position. Il est possible d'indiquer dans le fichier que l'objet hérite d'un autre et de récupérer, par ce biais, les champs de l'autre item. L'héritage se fait en listant les classes entre des balises <classe>, entre les balises <inherit>.
Par exemple, si la classe ma_classe de l'exemple précédent hérite de classe_generale et classe_particuliere, il faut rajouter le contenu suivant
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"> <inherit> <class>classe_generale</class> <class>classe_particuliere</class> </inherit></item>
Pour que l'éditeur puisse construire l'objet correctement, il est nécessaire que les classes héritées soient définies.
[modifier] Définition des attributs
Les attributs modifiables d'un objet sont listés entre les balises <fields></fields>. À chaque attribut est associé une entrée <field> (sans s cette fois) ayant comme propriété le nom du champ, name, et son type, type. L'attribut booléen is_list permet d'indiquer si le champ peut prendre une liste de valeurs, au lieu d'une unique valeur (comportement par défaut). Si un champ doit impérativement être renseigné par l'utilisateur, il est recommandé de lui ajouter l'attribut booléen required="true".
Les types valides pour les champs sont real, boolean, integer, u_integer, sprite, animation et item_reference ; représentant respectivement un nombre réel, un booléen, un entier, un entier positif, un sprite, une animation et une référence à un item.
Les noms des champs commencent par le nom de la classe, pour éviter les conflits de noms entre une classe fille et une classe mère. Ce préfixe est utilisée par l'éditeur pour ordonner les champs à l'affichage.
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"> <inherit> <class>classe_generale</class> <class>classe_particuliere</class> </inherit> <field type="real" name="ma_classe.pourcents" required="true"/> <field type="string" name="ma_classe.position" is_list="true"/></item>
Ces définitions suffisent pour permettre le paramétrage de l'objet. Néanmoins, il est possible de détailler chaque champ avec certaines balises filles de la balise <field> afin d'affiner son rôle et contrôler la valeur qui lui est affectée.
[modifier] Contraintes sur les valeurs
Certains champs ne peuvent prendre leur valeur que parmi des valeurs prédéfinies. Ces valeurs peuvent être indiquées avec, au plus, une des entrées <range> et <set>. Elles ne peuvent être utilisées que pour les champs de type numérique, sauf <set> qui peut aussi être utilisé pour des chaînes de caractères.
L'entrée <range> donne l'intervalle des valeurs valides pour le champ. Elle prend deux attributs, from qui indique la borne inférieure, to qui indique la borne supérieure.
L'entrée <set> énumère, quant à elle, les valeurs valides pour le champ. Chaque valeur est indiquée par un nœud fils <element> prenant comme attribut la valeur value.
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"> <inherit> <class>classe_generale</class> <class>classe_particuliere</class> </inherit> <field type="real" name="ma_classe.pourcents" required="true"> <range from="0" to="1"/> </field> <field type="string" name="ma_classe.position" is_list="true"> <set> <element value="top-left"/> <element value="top"/> <element value="top-right"/> </set> </field> </item>
[modifier] Balises informatives
Les balises <description> et <default_value> permettent respectivement de donner une petite description du rôle du champ et d'indiquer sa valeur par défaut.
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"> <inherit> <class>classe_generale</class> <class>classe_particuliere</class> </inherit> <field type="real" name="ma_classe.pourcents" required="true"> <range from="0" to="1"/> <description>Pourcentage de quelque chose.</description> <default_value>1</default_value> </field> <field type="string" name="ma_classe.position" is_list="true"> <set> <element value="top-left"/> <element value="top"/> <element value="top-right"/> </set> <description>Liste de positions.</description> <default_value>[top-left, top-right]</default_value> </field> </item>
[modifier] Contrainte sur l'ordre de traitement
Pour certains champs, il peut arriver que d'autres champs doivent impérativement être traités prioritairement. Dans ce cas, l'autre champ doit être indiqué dans l'attribut field d'une balise <before>.
Cette information ne concerne que l'éditeur de niveau, pour savoir dans quel ordre traiter les champs lors de la compilation.
Par exemple, si l'attribut ma_classe.position doit être traité avant l'attribut ma_classe.pourcents, il suffit d'ajouter
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"> <inherit> <class>classe_generale</class> <class>classe_particuliere</class> </inherit> <field type="real" name="ma_classe.pourcents" required="true"> <range from="0" to="1"/> <description>Pourcentage de quelque chose.</description> <default_value>1</default_value> <before field="ma_classe.position"/> </field> <field type="string" name="ma_classe.position" is_list="true"> <set> <element value="top-left"/> <element value="top"/> <element value="top-right"/> </set> <description>Liste de positions.</description> <default_value>[top-left, top-right]</default_value> </field> </item>
[modifier] Redéfinition de la valeur par défaut d'un attribut
Dans le cadre de l'héritage, il se peut que la valeur par défaut donnée à un objet parent ne soit plus correct pour l'objet en cours de définition. Cette valeur par défaut peut alors être redéfinie dans ce dernier à l'aide de la balise <new_default_value>. Celle-ci prend, en attribut, le nom du champ à redéfinir. Elle se place entre les balises <item> et fonctionne, pour le reste, comme la balise <default_value>.
Par exemple, si la classe ma_classe donne par défaut une valeur de 30 unités à l'attribut classe_generale.longueur, il faudrait redéfinir la valeur par défaut donnée par classe_generale :
<item class="ma_classe" category="ma_catégorie" box_color="#FFFF00" fixable="true"> <inherit> <class>classe_generale</class> <class>classe_particuliere</class> </inherit> <field type="real" name="ma_classe.pourcents" required="true"> <range from="0" to="1"/> <description>Pourcentage de quelque chose.</description> <default_value>1</default_value> <before field="ma_classe.position"/> </field> <field type="string" name="ma_classe.position" is_list="true"> <set> <element value="top-left"/> <element value="top"/> <element value="top-right"/> </set> <description>Liste de positions.</description> <default_value>[top-left, top-right]</default_value> </field> <new_default_value name="classe_generale.longueur">30</new_default_value></item>
