Votre premier script GUI

Écrit le 21/10/2004 par redneck
Dernière mise à jour : 06/02/2006

Introduction

Voici le premier tutorial sur les GUI de Doom3. Ce sont tous les écrans d'interaction que vous retrouver dans le jeu, comme les bornes de santé, les panneaux des ascenseurs, les différents panneaux de sécurité mais aussi le menu principal, le menu multiplayer, le PAD, le HUD (la barre de santé, les munitions, etc..).

Ce tutorial et ceux qui vont suivre sont tout simplement la traduction depuis l'anglais de tutoriaux disponibles sur le forum de doom3world.org.
Je me suis dit que ce serait sympa pour ceux qui ne sont pas familiers avec la langue anglaise de pouvoir bénéficier de l'expérience de l'auteur zeh que je remercie énormément de m'avoir permis de traduire et de passer son tuto (Tutorial 1 de Zeh) sur Game-lab. Avant de commencer, je voudrais donc souligner que tout le mérite lui revient.

Télécharger les fichiers du tutorial.

Les windowDefs

Un script GUI est composé d'un texte qui définit des éléments que vous verrez à l'écran y compris des images ou des animations qui rendront le tout un peu plus vivant.
Comme le contenu d'une page HTML, les scripts GUI possèdent une fonction principale et des fonctions secondaires qui créent chaque effet visuel. Alors que dans un fichier HTML la fonction principale serait quelque chose comme <HTML> ou dans un code en C quelque chose comme "void main (void)" , pour les scripts GUI nous utilisons windowDef (ce qui se traduirait par définition ou création de fenêtre).

windowDef est le coeur d'un script GUI. Il y a beaucoup à dire sur les windowDefs, mais pour le moment nous dirons seulement que nous avons besoin d'une windowDef principale afin de définir tous les éléments visuels que nous voudrons afficher par la suite. Créons une windowDef :

windowDef Desktop {
}

On commence le code par la déclaration d'une windowDef, en lui donnant un nom (ici "Desktop"), en ouvrant et fermant des accolades. Tout ce qui se trouve entre les accolades est le contenu de la windowDef.
Un truc important à noter est que le nom donné à la windowDef est "Desktop" par défaut. Tous les GUIs ont leur fonction principale appelée "Desktop".

Nous n'avons cependant pas encore ajouté d'éléments à cette windowDef. La première chose à faire est d'afficher la fenêtre principale en utilisant rect.

windowDef Desktop {
  rect         0, 0, 640, 480
}

L'attribut rect prend 4 valeurs - x, y, largeur et hauteur et sont présentées sur la même ligne séparées par des virgules. x et y représentant la position de l'origine.
Une chose à noter est que la taille 640*480 n'est pas vraiment exprimée en pixels. Dans les scripts DOOM 3, C'est comme si l'écran était toujours de 640x480, donc mettre une taille de rect de 640*480 veut dire que la windowDef prendra toute la taille de l'écran quelle que soit la résolution dans laquelle vous jouez.

Les attributs de windowDef

Maintenant on peut soit ajouter d'autres windowDefs soit changer les attributs de cette windowDef "Desktop". Même si ce n'est pas trop utilisé dans les vrais GUI pour la windowDef principale, ajoutons quelques attributs.

windowDef Desktop {
  rect         0, 0, 640, 480
  bordersize   3
  bordercolor  1, 1, 1, 1
  backcolor    0.5, 0.5, 0.5, 1
  visible      1

}

bordersize permet de dire que cette windowDef aura une bordure, et sa couleur sera définie par l'attribut bordercolor.
Alors que l'attribut bordersize est assez simple - il dessine une bordure à la windowDef, avec une largeur définie par la valeur attribuée à bordersize (en gros un nombre de pixels de largeur) - l'attribut bordercolor a besoin d'un peu plus de clarification.

bordercolor est un des nombreux attributs de GUI qui prend des couleurs comme paramètres - et la couleur pour les scripts GUI signifie 4 choses : R, G, B, et alpha.
Chaque valeur RGB représente une des trois composantes RGB qui composent une couleur - et dans ce cas, 0 est noir (pas de lumière) et 1 est le plus lumineux. Toutes les valeurs entre 0 et 1 sont autorises, et sont calculées pour avoir la couleur finale.
Comme les trois premières valeurs ici sont 1, cela signifie des intensités maximales pour le rouge, le vert et le bleu, et ainsi donne une couleur blanche. Ainsi les valeurs "1,1,1" sont la même chose que 255,255,255 en RGB ou #ffffff en hexadécimal.

Le dernier paramètre est alpha, et il s'utilise comme les composantes RGB : 0 signifie une transparence totale et 1 une opacité totale. Toutes les valeurs entre 0 et 1 sont autorisées, donc 0.5 serait 50% de transparence.
A la fin "1, 1, 1, 1" signifie une couleur complètement blanche.

Le même principe s'applique pour l'attribut backcolor (couleur de fond). "0.5, 0.5, 0.5, 1" est facile : 50% de blanc et une opacité max : 'est du gris.

En suivant l'attribut visible, qui est un booléen, peut prendre les valeurs 1 ou 0. Dans ce cas il est mis à 1 donc la fenêtre est visible. C'est assez basique mais ça montre l'étendu des possibilités des différents attributs.

Ajoutons du texte

Après avoir fait la fenêtre principale, nous allons ajouter plusieurs windowDefs. Comme dit plus haut, la windowDef Desktop est la fenêtre principale de notre GUI, donc les autres windowDef seront ses enfants. Voici ce que cela donne :

windowDef Desktop {
  rect         0, 0, 640, 480
  bordersize   3
  bordercolor  1, 1, 1, 1
  backcolor    0.5, 0.5, 0.5, 1
  visible      1
  windowDef monMessage {
  }
}

Vous notez que j'ai donné un nouveau nom - il est recommandé de créer des noms qui seront facilement reconnaissable pour coder vos scripts. Ces noms n'apparaîtront jamais à l'écran mais seront utilisés pour le codage.

Avec notre nouvelle windowDef (secondaire), il est temps d'ajouter quelques attributs.

windowDef Desktop {
  rect         0, 0, 640, 480
  bordersize   3
  bordercolor  1, 1, 1, 1
  backcolor    0.5, 0.5, 0.5, 1
  visible      1
  windowDef monMessage {
    rect         10, 10, 614, 40
    bordersize   1
    bordercolor  1, 0, 0, 1
    backcolor    0, 0, 0, 0.5
    text         "ON SE GELE"
    textscale    0.5
    font         "fonts/english"
    textalign    1
    forecolor    0,0,1,1
  }
}

Voici de nouveaux attributs, bien que la plupart sont faciles à comprendre, il y a quelques trucs à expliquer.

D'abord, notez le premier attribut rect. Je voulais qu'il soit au milieu de l'écran, éloigné un petit peu des coins, donc j'ai utilisé une position x/y de 10, 10 et une largeur de 614 et non pas de 620 (ce qui aurait été normal - 640 -10 (depuis la gauche) -10 (depuis la droite)).
Pourquoi ??

Les windowDef secondaires (ici monMessage) ont leur position x/y relative à celles de leur parent (ici Desktop). Le moteur prenant en compte la largeur du bord de la windowDef principale ( bordersiez 3), en fait la position 0, 0 pour la windowDef monMessage n'est pas la position 0, 0 de l'écran mais la position 3, 3. Ainsi de chaque côté de la windowDef monMessage il y a un bord de 3 plus le décalage de 10. La largeur totale que l'on peut utiliser est donc de 640 -13 -13 = 614 et la fenêtre sera centrée.
J'utilise un bordersize différent (1) pour un bord plus fin, un attribut bordercolor à "1,0,0,1" (ce qui est rouge) et une couleur de fond backcolor de 0,0,0,0.5 (noir avec une opacité à 50%).

Un nouvel attribut est text - avec un message basique "SALUT". Ici pas de problème, l'attribut permet d'afficher le texte entre guillemets.

Ensuite vient la taille du texte avec l'attribut textscale, 1 étant la taille d'origine de la fonte utilisée. Ici 0.5 représente une taille de 50% ce qui est assez grand dans notre cas.

L'attribut font dit quelle fichier de fonte on utilisera, ici on utilise la fonte anglaise du jeu, mais on peut soit en créer et les utiliser soit utiliser la fonte par défaut pour le jeu français (on a accès aux accents) et alors pas besoin de la spécifier.

L'attribut textalign est utilisé pour savoir comment est aligné le text avec les bord de la fenêtre windowDef monMessage, 0 pour aligner à gauche, 1 pour centrer et 2 pour aligner à droite ce texte. Ici 1 signifie que le texte sera centré dans la fenêtre monMessage et par conséquence sera centré à l'écran.

Enfin l'attribut forecolor est un attribut de couleur donnant la couleur de l'avant plan et ici du texte. avec la valeur "0,0,1,1", le texte sera en bleu.

Bien sur, les scripts GUI ne seront pas que des rectangles avec des couleurs, mais c'était juste pour l'exemple. Maintenant on va s'attaquer à des choses un peu plus sérieuse. Et bien sur on va commencer par ajouter une image. On utilisera une petite image toute simple que vous pouvez aussi utiliser en la prenant dans les fichiers sources en fin de tutorial.

windowDef Desktop {
  rect         0, 0, 640, 480
  bordersize   3
  bordercolor  1, 1, 1, 1
  backcolor    0.5, 0.5, 0.5, 1
  visible      1
  windowDef monMessage {
    rect         10, 10, 614, 40
    bordersize   1
    bordercolor  1, 0, 0, 1
    backcolor    0, 0, 0, 0.5
    text         "ON SE GELE"
    textscale    0.5
    font         "fonts/english"
    textalign    1
    forecolor    0,0,1,1
  }
  windowDef monImage {
    rect         218, 170, 200, 134
    background   "Kenny_gelé"
    matcolor     1,1,1,1
    visible 1
  }
}

On fait des progrès. La windowDef monImage ressemble un peu plus à ce que vous allez trouver dans des vrais GUI : une image et des attributs.

En premier lieu il ya l'attribut obligatoire rect. Dans ce cas Dans ce cas c'est un rectangle au milieu de l'écran.

L'attribut background est un nom de fichier - le nom du material (image, textures,...) que vous voulez utiliser. Il y a cependant quelques pièges.

D'abord c'est relatif au répertoire base de Doom3 -donc si vous utilisez le jeu de base (sans mods) , ce sera traduit par "<répertoire doom 3>/base/<nom de fichier>". Comme j'ai pas mis de nom de répertoire, cela signifie que l'image doit être dans le répertoire /base de Doom3.

Ensuite le fichier 'background' est au format TGA sans extension. Donc au final, le script va chercher le fichier "/base/Kenny_gelé.tga".

Enfin le material sera mis à l'échelle pour être à la taille de tout le fond de votre windowDef. A mois que vous utilisiez des options d'échelle (pour créer des tuiles), peu importe la taille du rectangle de la windowDef, le material en fond sera montré en entier.

Ensuite vient l'attribut matcolor. Malgré le nom ce n'est pas une couleur. c'est toujours au format R, G, B mais les premières valeurs diffèrent. Ce n'est pas des valeurs absolues de couleur à utiliser mais des pourcentages de chaque composante, c'est à dire à quel pourcentage chaque composante sera rendue.

Normalement, cette valeur serait de "1,1,1,1" pour un affichage d'image avec 100% opacité. Cependant vous pouvez enlever une partie de chaque composante - si un material a une valeur de matcolor de "0,1,1,1", par exemple, la composante rouge sera ôtée et l'image résultante serait un mix de vert et de bleu. C'est un outil très puissant, en utilisant une image en grayscale (dégradé de gris), vous pouvez manipuler ses composantes de couleur pendant le jeu et utiliser différents paramètres de couleur, comme si l'image était colorisée - vous pouvez utiliser la même image en grayscale pour des HUD de deux équipes rouge et bleu.

Le résultat

Voilà maintenant il est temps de tester le GUI dans le moteur de Doom3. Sauvez le script ci-dessus sous un nom quelconque avec l'extension .gui (par exemple tutorial1.gui) et placez le dans le répertoire /base. N'oubliez pas l'image.

Lancez le jeu, appelez la console (CTRL+ALT+²) et tapez:

testgui tutorial1.gui

Et voilà, votre GUI devrait apparaître remplissant tout l'écran.

http://www.game-lab.com/images/tuts/doom3_gui/resultat_tutorial1.jpg

C'est pas beau mais c'est un vrai script GUI.

Télécharger les fichiers du tutorial.