Couche Comportement XML

Une des couches Comportement prédéfinies dans Crystal Entity Layer est la Couche Comportement XML. Dans cette Couche Comportement XML est utilisé un langage de script simple. Ceci permet de créer une logique de jeu utilisant XML que l'on puisse incruster dans un fichier map.

Exemple

La façon la plus simple de décrire les bases soutendant la Couche Comportement XML est de prendre l'exemple suivant :

<world>
    <textures>
        <texture name="chair">
            <file>/cellib/images/chair5.gif</file>
        </texture>
    </textures>
    <materials>
        <material name="chair">
	    <texture>chair</texture>
	</material>
    </materials>
    <settings>
        <clearscreen>yes</clearscreen>
    </settings>
 
    <addon plugin="cel.addons.xmlscripts">
        <script name="chair_clicker">
            <event name="init">
                <var name="counter" value="0" />
            </event>
            <event name="pcbillboard_select">
                <var name="counter" value="?counter+1" />
                <if eval="?counter < 10">
                    <true>
                       <print value="'You clicked '+?counter+' times.'" />
                    </true>
                    <false>
                        <print value="'It is time you stopped clicking!'" />
                    </false>
                </if>
            </event>
        </script>
 
        <script name="chair_mover">
            <event name="pctimer_wakeup">
                <bb_move x="rand(1)*250000" y="rand(1)*250000" delta="500" />
            </event>
        </script>
    </addon>
 
    <addon plugin="cel.addons.celentity" entityname="red_chair">
        <propclass name="pc2d.billboard">
            <property name="name" string="red_chair" />
            <property name="materialname" string="chair" />
            <property name="clickable" bool="1" />
            <property name="movable" bool="1" />
            <property name="restack" bool="1" />
            <property name="color" color="1,1,1" />
            <property name="widthpct" float=".7" />
            <property name="heightpct" float=".7" />
        </propclass>
        <behaviour name="chair_clicker" />
    </addon>
 
    <addon plugin="cel.addons.celentity" entityname="green_chair">
        <propclass name="pc2d.billboard">
            <property name="name" string="green_chair" />
            <property name="materialname" string="chair" />
            <property name="clickable" bool="1" />
            <property name="movable" bool="0" />
            <property name="restack" bool="1" />
            <property name="color" color="0,1,0" />
            <property name="widthpct" float=".7" />
            <property name="heightpct" float=".7" />
            <property name="x" long="100000" />
            <property name="y" long="100000" />
        </propclass>
        <propclass name="pctools.timer">
            <action name="WakeUp">
                    <par name="time" long="500" />
                    <par name="repeat" bool="true" />
            </action>
        </propclass>
        <behaviour name="chair_mover" />
    </addon>
</world>

Pour lancer cet exemple vous pouvez placer ce fichier XML dans le répertoire courant puis faire ceci :

• Sous GNU/Linux

./bootstrap cel.behaviourlayer.xml bootstrap load /this testscript.xml

• Sous Windows

bootstrap.exe cel.behaviourlayer.xml bootstrap load //this testscript.xml

Dans cet exemple nous créons deux Entités utilisant l'addon cel.addons.celentity. L'Entité red_chair (chaise rouge) a juste une Classe de Propriété, qui est la classe pc2d.billboard. Cette Classe de Propriété est conçue pour de simples graphismes 2D. Vous pouvez l'utiliser pour créer un jeu complet en 2D (comme le jeu CrystalDash inclus avec Crystal Entity Layer) ou encore pour les éléments d'un HUD dans un jeu 3D. L'Entité green_chair (chaise verte) a une Classe de Propriété pc2d.billboard et une Classe de Propriété pctools.timer.

Scripts

En utilisant la Couche Comportement XML vous créez simplement des scripts. Tout script correspond à un comportement pour une Entité (de multiples Entités peuvent bien sûr l'utiliser). Dans notre exemple en particulier, on utilise l'addon cel.addons.xmlscripts pour créer les deux scripts que l'on va utiliser pour les deux Entités. Le script chair_clicker attend simplement que le panneau soit cliqué et incrémente un compteur. Si le compteur est en deçà de 10, alors celà affichera le total. Sinon il sortira un avertissement. Le script chair_mover attend jusqu'à ce que le temporisateur se lance puis initie un mouvement du panneau vers une autre endroit. Le bb_move s'assurera que le panneau continue de bouger graduellement vers l'endroit désirée (remarquez que le système de localisation pour les panneaux utilise un système de coordonnées où O,O est le coin haut/gauche et 307200,307200 est le coin bas/droit, indépendamment de la résolution de la fenêtre).

Evènements

Tout évènement dans un script correspond strictement à une méthode d'appel dans un langage normal de programmation. Vous pouvez faire autant d'évènements que vous voulez, mais il existe quelques cas spéciaux.

Tout d'abord il y a l'évènement init, appelé lorsque l'Entité dotée de ce script est exécutée en premier. C'est une sorte de constructeur. Ensuite, lorsque l'Entité obtient un message d'une des Classes de Propriété, ce message est alors traduit en un évènement. Dans l'exemple précédent, le script chair_clicker réagit à la sélection du panneau, laquelle est un message provenant de la Classe de Propriété du panneau, et nommée pcbillboard_select. Le script chair_mover réagit à l'évènement temporisateur, qui est un message provenant de la Classe de Propriété du temporisateur, et nommé pctimer_wakeup.

Variables

Vous pouvez utiliser deux sortes de variables dans un évènement. Il y a tout d'abord les variables globales. Pour assigner une valeur à une telle variable, vous pouvez utiliser :

<var name="variable" value="1000" />

Notez que les variables sont typées. Les types suivants sont possibles :

• int32 (entier 32-bit signé)

reconnu par une valeur comme 345 ou -398.

• uint32 (entier 32-bit non-signé)

reconnu par une valeur comme 345u.

• float (nombre à virgule flottante - réel)

les possibilités sont 342.33 ou -2.33e-33.

• bool (vrai ou faux)

les valeurs possibles sont true ou false.

• vector2 (vecteur à 2 dimensions)

écrit sous la forme [x,y].

• vector3 (vecteur à 3 dimensions)

écrit sous la forme [x,y,z].

• string (une chaîne de caractères)

écrit grâce à un simple signe sans espace ni signe spécial (comme 'bla321') ou encore entouré d'apostrophes simples.

Pour utiliser une variable globale, utilisez l'opérateur (?) comme ceci :

<print value="?variable" />

Vous pouvez faire des combinaisons d'expressions complexes :

<print value="3.14*(?variable+?othervar)" />

Les variables globales ont un énorme avantage : elles sont persistantes. En interne la Couche Comportement XML utilisera automatiquement une Classe de Propriété pcproperties pour stocker ces variables (une telle Classe de Propriété sera créée sur l'Entité si jamais elle n'existe pas déjà). Ceci signifie aussi que vous pouvez définir et accéder aux variables depuis d'autres Entités (notez comment l'opérateur (?) est combiné avec l'opérateur (.) pour accéder à la variable depuis une autre Entité :

<var entity="other_entity" name="variable" value="'some string'" />
<print value="'x in other_entity is equal to '+?other_entity.x" />

Contrastant avec les variables globales, vous avez également les variables locales. Ces variables locales ne conservent pas leur valeur et vous ne pouvez pas y accéder depuis d'autres Entités non plus. D'un autre côté, elle sont considérablement plus performantes. Voici comment définir et utiliser une variable locale :

<lvar name="localvar" value="3.1415" />
<print value="'Our local variable is equal to '+#localvar"/>

Tout ça peut devenir sacrément complexe. Regarder cet exemple :

<print value="?#entity.#variable" />

Ceci affichera la variable dont le nom figure dans la variable locale nommée variable depuis l'Entité qui porte le nom donné dans la variable locale nommée entity.

Evènements appelants

Certains évènements (comme init et des messages des Classes de Propriété) sont automatiquement appelés, mais vous pouvez définir vos propres évènements, auquel cas vous aurez besoin de pouvoir les appeler (comme vous appelez des fonctions). Voici un exemple d'appel d'un évènement :

<call event="myevent" />

C'est l'exemple le plus simple. Dans ce cas nous allons simplement passer le contrôle à l'évènement myevent et lorsqu'il sera terminé, l'exécution reprendra à l'opération suivant l'appel.

Il est aussi possible d'appeler un évènement dans une autre Entité. Prosaïquement, ceci appellera l'évènement dans le script (comportement) attaché à cette autre Entité :

<call entity="other_entities" event="myevent" />

Vous pouvez aussi passer les paramètres dans un appel d'évènement :

<call event="myevent">
    <par id="parid(x)" value="100" />
    <par id="parid(y)" value="50" />
</call>

Ceci passera les paramètres x et y dans l'évènement. Dans ce dernier vous pouvez accéder à ces paramètres avec l'opérateur (@), comme ceci :

<event name="addsomething">
    <print value="@x+@y" />
</event>

Les évènements peuvent aussi être utilisés comme des fonctions retournant une valeur. Dans ce cas vous rédigerez l'évènement ainsi :

<event name="addsomething">
    <return value="@x+@y" />
</event>

Ensuite vous pouvez utiliser cette fonction comme suit :

<print value="addsomething(x=3,y=5)" />

Vous pouvez voir comment les paramètres sont traités par le nom.

Il est également possible d'appeler un évènement dans une autre Entité comme une fonction en utilisant l'opérateur scope (::)

<print value="otherentity::addsomething(x=3,y=5)" />

Un cas spécial pour l'appel de fonction est l'opérateur ... . Si vous utilisez cela, alors les paramètres pour la fonction seront les mêmes que les paramètres ayant appelé cette fonction. Par exemple :

<event name="process">
    <return value="addsomething(...)*3" />
</event>

Cette fonction appelera addsomething avec les mêmes paramètres donnés à process puis multipliera le résultat par 3.

Tableaux (Arrays)

La Couche Comportement XML supporte les tableaux éparses à une ou deux dimensions. Ils sont éparses au sens ou seuls les éléments qui sont assignés existent réellement et consomment de la mémoire. Donc vous pouvez mettre une valeur dans le tableau à l'index 5 et une à l'index 1000000, et le tableau aura une taille équivalent à deux objets. Aussi les indices n'ont pas à être numérique. Vous pouvez utiliser n'importe quel type.

En interne les tableaux fonctionnent par concaténation du nom du tableau avec l'index. Par exemple, bla['testing',3] correspond en fait à une variable normale appelée bla_testing_3. Donc tout élément dans un tableau est en réalité juste une variable normale. La syntaxe du tableau est juste une syntaxe destinée à vous aider à rédiger des tableaux plus facilement. Voici un exemple sur la façon d'assigner une valeur dans un tableau et comment l'utiliser :

<lvar name="index" value="1000" />
<var name="bla[#index,3]" value="100" />
<print value="?bla[#index,3]" />

Commandes

Cette section propose un résumé de toutes les commandes disponibles pour la Couche Comportement XML.

Il est préférable de se référer à la documentation officielle (eng) pour une liste complète et à jour.