== Description d'item ==

Un item est dcrit entre les balises <item></item> qui contiennent,
dans l'entte, la classe de l'item et sa catgorie.

La classe de l'item est le nom de la classe dans le code source, la
catgorie est juste pour la convenance dans l'diteur de niveaux. Des
exemples de catgorie : "structural", "entity" et "tool". La premire
est pour les murs et tout ce qui dcrit la structure du monde ; la
deuxime est pour les objets "vivants" (bonus, ennemis, etc.) et la
troisime est pour les objets spciaux comme "lancer un niveau",
"dsactiver le mode pause" et d'autres.

Par exemple, si nous voulons dcrire l'ennemi "gupe", nous
commencerions par quelquechose comme a :

 <item class="wasp" category="entity/enemy" box_color="#FF00FF">
   ...
 </item>

L'attribut "box_color" est optionel et est juste la couleur de la
bote qui reprsente l'item dans l'diteur.

Quand un item hrite de "messageable_item", il a besoin d'un
nom. Cette information est donne en plaant la balise suivante dans
le corps de la description :

 <need_a_name/>

Une autre information  propos de l'item est s'il est  une position
fixe (comme un mur) ou s'il peut se dplacer dans le niveau. Si sa
position est constante, la balise suivante doit tre ajoute  la
description :

 <fixed/>

Souvenez-vous que l'attribut "fixed" est hrit. Si un item est fixe,
tous ses items fils seront fixes aussi.

Par exemple, la description d'un item fixe avec un nom devrait
ressembler 

 <item class="foo" category="entity/item" box_color="#FF24FF">
  <fixed/>
  <need_a_name/>
 </item>

et le code gnr sera

 create [fixed] foo["user_given_name"]
 {
  ...
 };

Une autre information est le type du calque dans lequel l'item peut
tre. Cette information est donne par la balise <layer>. Par
exemple :

 <layer type="action_layer"/>

o "type" est un des types de calques dfinis dans la documentation du
compilateur de niveaux. Remarquez que l'attribut "fixed" est, pour
l'instant, uniquement valide dans le calque d'activit.

Une fois que l'on a inform le lecteur  propos est proprits
globales de l'item, nous devons numrer les champs pouvant tre
configurs par l'utilisateur. C'est le rle de la section
<fields>. Cette section contient une liste de sections <field> et
ressemble 

 <fields>
  <field type="some_type" name="some_name">
   ...
  </field>
  <field  type="some_type" name="some_name">
   ...
  </field>
 <fields>

L'attribut "type" dfini le type du champ. Les valeurs valides sont
celles dfinies dans la documentation du compilateur de
niveaux. L'attribut "name" dfini le nom du champ. Si le champ
doit obligatoirement tre rempli, la balise <required/> doit tre
ajoute au copr de la section.

Certains champs ne peuvent prendre leur valeur que parmi des valeurs
prdfinies. Ces valeurs peuvent tre dfinies avec au plus une des
sections <range> et <set>.

La section <range> donne l'intervalle des valeurs [from, to] valide
pour le champ. Par exemple :

    <range>
      <from value="0"/>
      <to value="1000"/>
    </range>

Alors que <set> numre les valeurs valides pour le champ. Par
exemple :

    <set>
      <item value="top-left"/>
      <item value="top"/>
      <item value="top-right"/>
    </set>

Certains champs doivent tre dfinis dans un certain ordre. Pour
exprimer qu'un champ doit tre dfini avant un autre, nous utilisons
la balise <before> dans le corps de la section <field> :

    <before field=""/>

Notez que le parser doit alors vrifier que la valeur de "field" est
un champ et que a complique la possibilit d'utiliser le mme nom
pour deux champs de types diffrents.

Certains items necessitent la prsence de ressources graphiques ou
sonores. Ce besoin peut tre dclar dans la section <require>, dans
le corps de la section <item>, en utilisant les balises <sound> ou
<gfx> pour exprimer le besoin respectif d'un son ou d'une image.

 <require>
  <sound name="needed_sound" path="its_path"/>
  <gfx name="needed_picture" path="its_path"/>
 </require>

== Hritage ==

Certains items ont des champs en commun (comme la position). a
pourrait tre confortable pour l'utilisateur d'avoir la possibilit
d'utiliser un systme d'hritage, pour pouvoir dfinir les champs
commun une seule fois. L'hritage pourrait tre fait dans l'entte de
la section, comme

 <item inherit="parent_item" ...>

ou avec une balise spcifique

 <inherit class="parent_item"/>

La deuxime mthode autorise l'hritage multiple, qui est peut-tre un
concept un peu dur  implmenter et peut-tre pas trs utile. La
premire mthode serait donc probablement mieux.

La classe fille hrite de tout le corps de son parent. L'attribut
"fixed", si prsent dans le parent, ne peut pas tre redfini. Nous
aurons probablement besoin d'un moyen pour dsactiver la balise
<need_a_name/>, pour les items qui gnrent leur nom  l'excution. a
pourrait tre la balise <no_need_for_a_name/>. Tous les champs de la
classe mre peuvent tre redfinis ; toutes les ressources ncessaires
et les types de calques sont conservs.

Certains items ne seront alors dcrits que pour pouvoir tre hrits
(comme base_item). Ils ne seront pas ajoutables dans le niveau et, par
consquent, ne devraient pas apparatre dans les menus de l'diteur de
niveaux. Ces classes auront la catgorie "-abstract-" (avec les tirets).

== Exemple complet ==

Nous allons maintenant dcrire une ampoule que le joueur pourra
allumer en utilisant un interrupteur. L'activation se fait depuis un
objet distant ; nous donnerons un nom  l'ampoule pour qu'elle puisse
recevoir des messages. Sa position est constante. L'item a besoin d'un
son  jouer quand il est activ et d'une image de halo
lumineux. L'ampoule a besoin d'un sprite, une couleur et une intensit
(pour la lumire). La couleur doit tre dfinie avant l'intensit.

Tout d'abord, nous avons besoin de la dfinition des classes mres.

 <item class="base_item" category="-abstract-">
  <fields>
   <field type="u_integer" name="pos_x"/>
   <field type="u_integer" name="pos_y"/>
  </fields>
 </item>

Nous dcrivons ensuite la classe "light_bulb" de notre item.

 <item class="light_bulb" category="decoration/light"
       box_color="#00FFFF" inherit="base_item">
  <need_a_name/>
  <fixed/>
  <fields>
   <field type="sprite" name="sprite">
    </required>
   </field>
   <field type="real" name="intensity>
    <range>
     <from value="0"/>
     <to value="1"/>
    </range>
   </field>
   <field type="string" name="color">
    <set>
     <item value="red"/>
     <item value="green"/>
     <item value="yellow"/>
     <item value="blue"/>
    </set>
    <before field="intensity"/>
   </field>
  </fields>
  <require>
   <sound name="click" path="sound/click.ogg"/>
   <gfx name="halo" path="gfx/halo.tga"/>
  <require>
 </item>
