Gosu : une bibliothèque pour faire des jeux avec Ruby

Xitog

Gosu est une bibliothèque pour Ruby permettant d'afficher des graphismes en 2D, de jouer des sons (via FMOD ou OpenAL) et d'interagir avec le clavier, la souris ou un joystick.

- Titre : Gosu : une bibliothèque pour faire des jeux avec Ruby

- Auteur : Xitog

- Parution : 6 février 2006

- Mise à jour : 5 juillet 2020

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2006 Xitog. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Crédits et droits d'auteurs

- II. Introduction

- III. Installation

- III-A. Sous Windows

- III-B. Sous Linux

- III-C. Sous Mac OS X

- IV. Premier pas

- V. Notes générales sur Gosu

- VI. Les classes de Gosu

- VI-A. Color

- VI-A-1. initialize(argb)

- VI-A-2. initialize(a, r, g, b)

- VI-B. Font

- VI-B-1. initialize(window, font_name, height)

- VI-B-2. height

- VI-B-3. text_width(text, factor_x=1)

- VI-B-4. draw(text, x, y, z=0, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- VI-B-5. draw_rel(text, x, y, z, rel_x, rel_y, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- VI-C. Image

- VI-C-1. initialize(window, filename, hard_borders)

- VI-C-2. initialize(window, filename, hard_borders, srcX, srcY, srcWidth, srcHeight)

- VI-C-3. width

- VI-C-4. height

- VI-C-5. draw(x, y, z=0, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- VI-C-6. draw_rot(x, y, z=0, angle=0, center_x=0.5, center_y=0.5, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- VI-C-7. from_text(window, text, font_name, font_height, line_spacing, max_width, align)

- VI-C-8. load_tiles(window, filename, tile_width, tile_height, hard_borders)

- VI-D. Sample

- VI-D-1. initialize(window, filename)

- VI-D-2. play(vol=1, speed=1)

- VI-D-3. play_pan(pan=0, vol=1, speed=1)

- VI-E. Song

- VI-E-1. initialize(window, filename, type)

- VI-E-2. play

- VI-E-3. stop

- VI-E-4. playing?

- VI-F. Window

- VI-F-1. initialize(width, height, fullscreen, update_interval)

- VI-F-2. caption

- VI-F-3. caption= une chaîne

- VI-F-4. show

- VI-F-5. close

- VI-F-6. visible?

- VI-F-7. update

- VI-F-8. draw

- VI-F-9. button_down(id)

- VI-F-10. button_up(id)

- VI-F-11. draw_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z=0, mode=:default)

- VI-F-12. mouse_x

- VI-F-13. mouse_y

- VI-F-14. button_down?(id)

- VI-F-15. button_id_to_char(id)

- VI-F-16. char_to_button_id(char)

- VI-F-17. width

- VI-F-18. height

- VII. Fonctions libres du module

- VII-A. offset_x(angle, dist)

- VII-B. offset_y(angle, dist)

- VII-C. angle(x1, y1, x2, y2)

- VII-D. distance(x1, y1, x2, y2)

- VII-E. milliseconds

- VII-F. default_font_name

- VIII. Constantes dans le module Gosu::Button

- IX. Tutoriels

- IX-A. Tutoriel n° 1 : Affichage d'une image

- IX-B. Tutoriel n° 2 : Affichage d'une image en suivant la souris

- IX-C. Tutoriel n° 3 : Affichage de tiles

- IX-D. Tutoriel n° 4 : Affichage d'un texte

- IX-E. Tutoriel n° 5 : Affichage d'une image avec rotation

- IX-F. Lancement des tutoriaux

- IX-G. Exemple plus complet

- X. Todo

- XI. Historique

- XII. Notes globales sur la documentation

I - Crédits et droits d'auteurs

La bibliothèque Gosu et le site présentant Gosu sont : Copyright © 2004 Julian Raschke, Jan Lücker and Alexander Post. Xitog pour la documentation (à partir de la documentation de référence).

- Première version : mardi 31 janvier 2006.

- Version 1.1 mercredi 1er février 2006.

- Version 1.2 jeudi 2 février 2006.

- Version w1.0 dimanche 5 février 2006.

- Version w1.1 lundi 6 février 2006.

- Version 1.3 jeudi 16 février 2006.

II - Introduction

Ruby est langage de script (=interprété) puissant, jeune et novateur. Gosu est une librairie pour C++ et Ruby, disponible pour les principaux systèmes d'exploitation pour programmer des jeux. . Le but de Gosu est d'apporter une bibliothèque de haut niveau pour la création de jeux vidéo. Gosu est disponible sur Windows, Linux et Mac OS X.

Elle permet donc l'affichage de graphisme, la gestion de sons et la gestion du clavier, de la souris et même du joystick. Pour la gestion du son, elle se repose sur la librairie FMOD ou OpenAL. L'affichage se base sur DirectX (pour Windows) ou OpenGL, et est accéléré

Page principale : http://www.raschke.de/julian/gosu/

Gosu pour accomplir sa tâche vous propose de manipuler :

- une fenêtre qui sera le lieu où vous afficherez tous vos graphismes ;

- des images ;

- des sons et des musiques : la différence entre les deux se faisant sur la longueur : un son est généralement un effet sonore court (avec généralement plusieurs sons à la fois) comme une explosion alors que les musiques sont généralement longues et il n'y en a qu'une à la fois ;

- des polices de caractères pour afficher du texte à l'écran.

Le chapitre suivant vous indiquera comment installer Gosu sous Windows. Pour installer Gosu sur d'autres systèmes d'exploitation reportez - vous à la page de référence. Le chapitre suivant vous proposera un premier exemple de programme Ruby avec Gosu. Si vous êtes intéressé par plus tutoriels, 5 tutoriels très simples ainsi qu'un programme complet sont proposés à la fin. Au milieu ce trouve la description exhaustive de tout ce qui compose Gosu.

Gosu existe aussi pour C++, mais cela n'est pas le but de la présente documentation. Pour plus d'information sur Gosu/C++, reportez - vous à la page de référence.

Version actuelle de Gosu : 0.6.0

III - Installation

III-A - Sous Windows

Pour installer Gosu pour Ruby, vous devez télécharger la dernière version de Gosu sur le site. Cette version contiendra normalement une bibliothèque pré - compilée « gosu.so » à mettre dans le répertoire :

(VotreRépertoireRuby)\lib\ruby\site_ruby\1.8\i386-msvcrt.

Pour pouvoir utiliser la partie son avec FMOD, vous aurez aussi besoin de cette bibliothèque, téléchargeable à : http://www.fmod.org/ (vous devez prendre la version 3.75). Vous devez mettre cette bibliothèque dans le répertoire de votre script. Une autre option est de mettre le fichier de la bibliothèque (fmod.dll) dans le répertoire :

(VotreRépertoireRuby)\bin.

Ainsi cette bibliothèque sera accessible pour tous les scripts Ruby sur votre machine.

Et voilà ! Vous êtes prêts pour vous lancer dans Gosu.

III-B - Sous Linux

Vous devrez avoir les packages suivants :

- xlibmesa-glu-dev ;

- libpango1.0-dev (Pango with freetype) ;

- X11, xf86 extensions (-lXxf86vm) ;

- libPNG3 (or higher) ;

- Boost (http://www.boost.org) and ;

- OpenGL ;

- Ruby-Dev ;

- FMOD (version >= 3.72).

À part FMOD, ces packages peuvent être obtenus via Apt.

Après il faut obtenir la bibliothèque gosu.so en jouant avec gcc. Pour cela, il faut faire :

chmod u+x configure

./configure

make

III-C - Sous Mac OS X

Pour que vos jeux tournent sous Max OS X, il vous faut une copie de Game.app, qui est incluse dans la distribution pour Mac OS de Gosu. C'est une application qui lancera votre jeu.

Copiez simplement les fichiers du jeu dans Game.app/Contents/Ressources. Une fois lancée, Game.app lancera le fichier Main.rb dans ce répertoire. Game.app nécessite que le framework Gosu soit installé (habituellement dans /Library/Frameworks) ainsi que la version dynamique de la bibliothèque libpng (qui n'est pas incluse dans le framework Gosu) qui devra être mise dans /usr/lib.

IV - Premier pas

Voici un « Hello World » pour vous montrer la facilité d'utilisation de Gosu :

# va chercher la librairie
require "gosu.so"
# évite de préfixer tous les éléments du module par Gosu::
include Gosu

# Nous définissons la classe de notre fenêtre principale
class MainWindow < Window

# Dans le constructeur, on appelle le constructeur de la classe mère
# Notre fenêtre sera en 640x480 en mode fenêtré
# avec un intervalle d'update de 20.
def initialize
super(640,480, false, 20)
end

# Méthode qui sera appelée lorsqu’on voudra dessiner l'intérieur de notre fenêtre
def update
# on définit la couleur rouge
red = 0xEEEE0000
# On dessine un quadrilatère de couleur rouge
draw_quad(0, 0, red, 0, 10, red, 10, 0, red, 10, 10, red)
end

end

# Création d'une instance de notre fenêtre
window = MainWindow.new()
# Affichage par appel implicite à la fonction update
window.show()

V - Notes générales sur Gosu

Toutes les fonctions et les classes sont contenues dans le module Gosu.

Lorsqu'un paramètre de type Gosu::Color est demandé, on peut mettre à la place un entier de la forme : 0xAARRGGBB (ici en hexadécimal).

- A = Code alpha (255 : aucune transparence, 0 : transparence totale)

- R = Code pour le rouge

- G = Code pour le vert

- B = Code pour le bleu

On peut utiliser une couleur lors du dessin pour modifier la couleur originale de l'image. Néanmoins, cela ne peut que réduire les codes A, R, G, B de ces images : pour R, G, B cela aura tendance à faire tendre l'image vers le sombre et pour A cela fera tendre l'image vers la transparence. Cet effet peut être utilisé pour changer la couleur d'une image blanche (voir l'exemple final, où des étoiles blanches sont dessinées de toutes les couleurs).

Pour les paramètres de mode pour les fonctions de dessins, les valeurs possibles sont :

- :default ;

- :additive.

Profondeur d'un dessin : lorsque deux dessins occupent la même place, il faut déterminer lequel écrase l'autre : pour cela certaines fonctions permettent de spécifier une profondeur : le dessin de profondeur la plus grande sera dessiné sur tous les autres. Si deux dessins ont la même priorité, le dernier dessiné écrasera l'autre (voir l'axe de profondeur).

Paramètre facultatif : tous paramètres ayant une valeur par défaut (=valeur) peut être ignoré lors de l'appel : il aura alors sa valeur par défaut. Néanmoins, seuls les derniers paramètres d'une fonction peuvent être ignorés :

f(a, b=0, c=3)
L'appel peut être :
f(4)        # a = 4, b = 0, c = 3
f(2, 3)        # a = 2, b = 3, c = 3
f(4, 5, 2)    # a = 4, b = 5, c = 2
On ne peut pas donner une valeur à c tout n'en donnant pas à b !

Les angles dans Gosu :

Gosu n'utilise pas les radians comme la bibliothèque C standard. Les angles dans Gosu sont compris entre 0 et 360 (automatiquement une valeur négative ou supérieure à 360 est transformée). Un angle de 0 signifie « orienté vers le haut ». Les angles augmentent dans le sens des aiguilles d'une montre.

L'axe de profondeur (Z-Ordering) : toutes les opérations de dessins dans Gosu acceptent en plus des arguments de position x et y un argument de profondeur appelé z : c'est un entier entre 0 et 255. Les objets dessinés avec une profondeur plus grande seront dessinés sur les objets ayant une profondeur plus petite. Si deux objets ont la même position z, ils seront dessinés dans l'ordre d'appel des fonctions. Si vous ne voulez pas utiliser l'axe des profondeurs, mettez simplement z à 0 tout le temps.

Bordure floue ou nette : lors du chargement des images, on peut spécifier si les contours de l'image doivent rester nets ou pas. En effet, à cause de l'accélération 3D, les contours des images ont tendance à devenir flous et à « fondre » avec le décor. Cela est parfois est un désavantage (par exemple pour les tests). Généralement, pour obtenir une image plus belle, on prendra des bordures floues. Ce paramètre est sous la forme d'un booléen :

- Vrai = bordure nette ;

- Faux = bordure floue.

Coins d'une image : Certaines fonctions attendent des arguments pour les 4 coins d'un rectangle (exemple : Window#draw_quad). L'ordre des coins est important lors du passage des paramètres. Le coin n° 1 sera celui en haut à gauche, le coin n° 2 en haut à droite, le coin n° 3 en bas à gauche et la 4e en bas à droite (sens de lecture normale : de haut en bas, de droite à gauche).

Couleurs transparentes : lorsque l'on affiche une image, on veut généralement qu'elle se fonde dans le décor. Parfois notre image (toujours contenue dans un rectangle) n'occupe pas tout le rectangle : que faire des pixels en trop pour qu'il ne s'affiche pas ?

Et bien tout simplement un utilisant la couleur de code RGB (255,0,255) (violet-rose). Cette couleur, généralement peu utilisée dans les jeux, sera considérée par Gosu comme transparente ! (pour les images de type bitmap. Pour les images de type png, on mettra l'alpha à 0).

VI - Les classes de Gosu

VI-A - Color

VI-A-1 - initialize(argb)

- argb : un entier sous la forme 0xAARRGGBB (cf. notes).

VI-A-2 - initialize(a, r, g, b)

- a : code alpha

- r : code pour le rouge

- g : code pour le vert

- b : code pour le bleu

VI-B - Font

VI-B-1 - initialize(window, font_name, height)

- window [Gosu::Window] : la fenêtre Gosu dans laquelle la font sera utilisée

- font_name [chaîne] : nom de la fonte

- height [entier] : taille de la fonte

Attention, font_name doit être un nom de police de caractère reconnue par le système d'exploitation. Utilisez default_font_name pour avoir un nom compatible sur tous les systèmes.

VI-B-2 - height

- retourne la taille de la fonte

VI-B-3 - text_width(text, factor_x=1)

- Returns the width in pixels the given text would span.

VI-B-4 - draw(text, x, y, z=0, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- text [chaîne] : texte à écrire

- x [entier] : coordonnée x où écrire ce texte

- y [entier] : coordonnée y où écrire ce texte

- z [entier] : profondeur du dessin du texte

- factor_x [entier] : facteur multiplicatif horizontal

- factor_y [entier] : facteur multiplicatif vertical

- color [Gosu::Color ou un entier] : couleur du texte (blanc par défaut)

- mode [paramètre de mode] : mode de dessin

Dessine un texte à partir d'un point.

VI-B-5 - draw_rel(text, x, y, z, rel_x, rel_y, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- text [chaîne] : texte à écrire

- x [entier] : coordonnée x où écrire ce texte

- y [entier] : coordonnée y où écrire ce texte

- z [entier] : profondeur du dessin du texte

- rel_x [flottant] : position du texte par rapport au point (voir note).

- rel_y [flottant] : position du texte par rapport au point (voir note).

- factor_x [entier] : facteur multiplicatif horizontal

- factor_y [entier] : facteur multiplicatif vertical

- color [Gosu::Color ou un entier] : couleur du texte (blanc par défaut)

- mode [paramètre de mode] : mode de dessin

Dessine un texte relativement à un point.

- Si relX = 0.0, le texte sera dessiné à la droite du point

- Si relX = 1.0, le texte sera dessiné à la gauche du point

- Si relX = 0.5, le texte sera centré horizontalement sur le point

- Si relY = 0.0, le texte sera dessiné en haut du point

- Si relY = 1.0, le texte sera dessiné en bas du point

- Si relY = 0.5, le texte sera centré verticalement sur le point

Toutes les valeurs sont possibles our relX et relY, ne sont mentionnées ici que les valeurs significatives.

VI-C - Image

Une image pour notre application. Gosu gère les images aux formats BMP ou PNG.

VI-C-1 - initialize(window, filename, hard_borders)

- window [Gosu::Window] : la fenêtre du jeu de laquelle dépendra l'objet créé

- filename [chaîne] : le nom du fichier où l'image est stocké

- hard_borders [booléen] : contour de l'image dur ou flou

VI-C-2 - initialize(window, filename, hard_borders, srcX, srcY, srcWidth, srcHeight)

- window [Gosu::Window] : la fenêtre du jeu de laquelle dépendra l'objet créé

- filename [chaîne] : le nom du fichier où l'image est stocké

- hard_borders [booléen] : contour de l'image dur ou flou

- srcX [entier] : coordonnée x du rectangle de découpe (voir note)

- srcY [entier] : coordonnée y du rectangle de découpe (voir note)

- srcWidth [entier] : largeur du rectangle de découpe (voir note)

- srcHeight [entier] : hauteur du rectangle de découpe (voir note)

En utilisant le constructeur rattaché à cette fonction, on peut spécifier un rectangle de découpe dans l'image source : notre objet Image ne contiendra que le rectangle spécifié.

VI-C-3 - width

- Retourne [entier]

Retourne la largeur de l'image.

VI-C-4 - height

- Retourne [entier]

Retourne la hauteur de l'image.

VI-C-5 - draw(x, y, z=0, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- x [entier] : coordonnée x à partir de laquelle l'image sera dessinée

- y [entier] : coordonnée y à partir de laquelle l'image sera dessinée

- z [entier] : profondeur du dessin

- factor_x [entier] : facteur multiplicatif horizontal du dessin

- factor_y [entier] : facteur multiplicatif vertical du dessin

- color [Gosu::Color ou entier] : couleur

- mode [paramètre de mode] : mode de dessin

Dessine l'image aux coordonnées spécifiées.

VI-C-6 - draw_rot(x, y, z=0, angle=0, center_x=0.5, center_y=0.5, factor_x=1, factor_y=1, color=0xffffffff, mode=:default)

- x [entier] : coordonnée x à partir de laquelle l'image sera dessinée

- y [entier] : coordonnée y à partir de laquelle l'image sera dessinée

- z [entier] : profondeur du dessin

- angle [flottant] : l'angle de dessin

- center_x [flottant] : coordonnée x du point de rotation (par rapport à l'image)

- center_y [flottant] : coordonnée y du point de rotation (par rapport à l'image)

- factor_x [entier] : facteur multiplicatif horizontal du dessin

- factor_y [entier] : facteur multiplicatif vertical du dessin

- color [Gosu::Color ou entier] : couleur

- mode [paramètre de mode] : mode de dessin

Dessine l'image aux coordonnées spécifiées selon l'angle voulu.

center_x et center_y ne sont pas 0 par défaut. Pour une rotation « sur place », mettre ces deux paramètres à 0.

VI-C-7 - from_text(window, text, font_name, font_height, line_spacing, max_width, align)

[méthode de classe]

- window [Gosu::Window] : la fenêtre Gosu dans laquelle la font sera utilisée

- text [chaîne] : texte servant à créer l'image

- font_name [chaîne] : nom de la fonte

- height [entier] : taille de la fonte

- line_spacing [entier] : surplus à ajouter à la hauteur de la fonte pour avoir la hauteur complète d'une ligne

- max_width [entier] : largeur maximale de l'image

- align [Valeurs spéciales] : alignement du texte (voir note).

- Retourne [Gosu::Image]

Fait une image à partir d'un texte.

align doit prendre une valeur parmi :

- :left

- :right

- :center

- :justify

VI-C-8 - load_tiles(window, filename, tile_width, tile_height, hard_borders)

[méthode de classe]

- window [Gosu::Window] : la fenêtre Gosu dans laquelle la font sera utilisée

- filename [chaîne] : nom du fichier ou le graphisme sera pris

- tile_width [entier] : largeur d'un tile en pixels ou nombre de colonnes

- tile_height [entier] : hauteur d'un tile en pixels ou nombre de lignes

- hard_borders [booléen] : contour de l'image dur ou flou

- Retourne [Array de Gossu::Image]

Permet de créer une image à partir d'un fichier de « tile ». Généralement, cela sert si dans un fichier vous avez plusieurs images et que vous voulez les manipuler séparément dans Gosu.

VI-D - Sample

Un Sample est un effet sonore court, généralement utilisé pour les effets sonores tels que des tirs, des explosions…

VI-D-1 - initialize(window, filename)

- window [Gosu::Window] : la fenêtre du jeu de laquelle dépendra l'objet créé

- filename [chaîne] : le nom du fichier où le son est stocké

VI-D-2 - play(vol=1, speed=1)

- vol [flottant] : volume auquel sera joué le morceau (de 0.0 = silence à 1.0 = volume maximum)

- speed [flottant] : vitesse à laquelle sera jouée le morceau (voir la note)

Joue l'effet sonore.

La vitesse est limitée seulement par les capacités de la librairie FMOD : cela peut aller de très hautes valeurs jusqu'à des valeurs basses. Utilisez 1.0 pour une vitesse normale.

VI-D-3 - play_pan(pan=0, vol=1, speed=1)

- vol [flottant] : volume auquel sera joué le morceau (de 0.0 = silence à 1.0 = volume maximum)

- speed [flottant] : vitesse à laquelle sera jouée le morceau (voir la note)

- pan [flottant] : Le paramètre pan est un flottant compris entre -1.0 (gauche) jusqu'à +1.0 (droite) pour avoir des effets stéréos (son venant d'une direction).

Joue l'effet sonore.

La vitesse est limitée seulement par les capacités de la librairie FMOD : cela peut aller de très hautes valeurs jusqu'à des valeurs basses. Utilisez 1.0 pour une vitesse normale.

VI-E - Song

Un Song est un effet sonore long. Généralement utilisé pour la musique du jeu.

VI-E-1 - initialize(window, filename, type)

- window [Gosu::Window] : la fenêtre du jeu de laquelle dépendra l'objet créé

- filename [chaîne] : le nom du fichier où le son est stocké

- type [Valeur spéciale] : soit : :stream (OGG…) ou :module (MID, IT, MOD, X3M…)

VI-E-2 - play

Joue la musique.

VI-E-3 - stop

Arrête la musique (si elle en train d'être jouée).

VI-E-4 - playing?

- Retourne [booléen]

Retourne vrai si la musique est en train d'être jouée, faux sinon.

VI-F - Window

Élément central de Gosu, la fenêtre représente la zone où vous afficherez tous vos graphismes.

VI-F-1 - initialize(width, height, fullscreen, update_interval)

- width [entier] : largeur

- height [entier] : hauteur

- fullscreen [booléen] : mode plein écran ou fenêtré

- update_interval [entier] : dans de rafraîchissement de la fenêtre (en millisecondes)

- * Avoir 2 ou plus fenêtres et charger des Sample ou des Song sur les deux crashera l'application. Si vous voulez rouvrir votre fenêtre de jeu, assurez-vous bien que la précédente est morte.

- * Hauteur et largeur doivent correspondre à un mode d'affichage disponible, sinon l'application crashera. Ex. : 640,480 800,600 1024,768

VI-F-2 - caption

- Retourne [chaîne]

Permet d'obtenir le titre de la fenêtre. «   » par défaut.

VI-F-3 - caption= une chaîne

Permet définir le titre de la fenêtre.

VI-F-4 - show

Ouvre la fenêtre

VI-F-5 - close

Ferme la fenêtre

VI-F-6 - visible?

- Retourne [booléen]

Retourne si la fenêtre est visible ou pas.

VI-F-7 - update

Fonction appelée automatiquement pour faire « vivre » le jeu. Vous la surchargez pour mettre dedans tous ce qui ce passe dans votre jeu.

VI-F-8 - draw

Fonction de dessin du monde du jeu dans la fenêtre, appelé automatiquement. Doit être surchargée pour que vous définissiez l'affichage de votre jeu.

VI-F-9 - button_down(id)

- id [constante de Gosu::Button]

Fonction appelée lorsque l'utilisateur appuie sur un bouton. Le paramètre id permet de déterminer quel bouton a été pressé.

VI-F-10 - button_up(id)

- id [constante de Gosu::Button]

Fonction appelée lorsque l'utilisateur relâche un bouton. Le paramètre id permet de déterminer quel bouton a été relâché.

VI-F-11 - draw_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z=0, mode=:default)

- xi [entier] : coordonnée x du point i

- yi [entier] : coordonnée y du point i

- ci [Gosu::Color ou un entier] : couleur du point i

- z [entier] : profondeur

- mode [paramètre de mode] : mode de dessin

Dessine un quadrilatère dans la fenêtre.

VI-F-12 - mouse_x

- Retourne [entier]

Retourne la coordonnée x de la souris.

VI-F-13 - mouse_y

- Retourne [entier]

Retourne la coordonnée y de la souris.

VI-F-14 - button_down?(id)

- Retourne [booléen]

Retourne vrai si le bouton id est pressé, faux sinon.

VI-F-15 - button_id_to_char(id)

- Retourne [caractère]

Retourne le caractère correspondant à l'id du bouton ou "" si le bouton ne correspond pas à un caractère.

VI-F-16 - char_to_button_id(char)

- char [caractère] : caractère dont on doit trouver le bouton

- Retourne [constante de Gosu::Button]

Retourne l'id du bouton correspondant au caractère, ou 0 si n'y en a pas.

VI-F-17 - width

Retourne la largeur de la fenêtre.

VI-F-18 - height

Retourne la hauteur de la fenêtre.

VII - Fonctions libres du module

VII-A - offset_x(angle, dist)

- angle [flottant] : direction du mouvement (en degrés)

- dist [entier] : distance à parcourir dans cette direction

- Retourne [entier]

Retourne la distance horizontale (sur l'axe des abscisses) entre le point d'origine et le point d'arrivée en bougeant selon la direction de l'angle et de la distance passés en paramètre.

VII-B - offset_y(angle, dist)

- angle [flottant] : direction du mouvement (en degrés)

- dist [entier] : distance à parcourir dans cette direction

- Retourne [entier]

Retourne la distance verticale (sur l'axe des ordonnées) entre le point d'origine et le point d'arrivée en bougeant selon la direction de l'angle et de la distance passés en paramètre.

VII-C - angle(x1, y1, x2, y2)

- xi [entier] : coordonnée x du point i

- yi [entier] : coordonnée y du point i

- Retourne [flottant]

Retourne l'angle entre les deux points en degrés, où 0.0 signifie que l'objet 2 est au-dessus de l'objet 1. Retourne 0 si les deux points sont égaux.

VII-D - distance(x1, y1, x2, y2)

- xi [entier] : coordonnée x du point i

- yi [entier] : coordonnée y du point i

- Retourne [entier]

Retourne la distance entre les deux points.

VII-E - milliseconds

- Retourne [entier]

Retourne, en millisecondes, une valeur depuis l'instant t. L'instant t n'est pas connu, en fait cette fonction sert pour savoir combien de temps s'est écoulé entre deux appels à cette fonction.

VII-F - default_font_name

- Retourne [chaîne]

Retourne le nom d'une police de caractère qui marchera sur tous les systèmes d'exploitation.

VIII - Constantes dans le module Gosu::Button

- Boutons du Clavier :

- Kb0

- Kb1

- Kb2

- Kb3

- Kb4

- Kb5

- Kb6

- Kb7

- Kb8

- Kb9

- KbBackSpace

- KbDelete

- KbDown

- KbEnd

- KbEnter

- KbEscape

- KbF1

- KbF10

- KbF11

- KbF12

- KbF2

- KbF3

- KbF4

- KbF5

- KbF6

- KbF7

- KbF8

- KbF9

- KbHome

- KbInsert

- KbLeft

- KbLeftAlt

- KbLeftControl

- KbLeftShift

- KbNumpad0

- KbNumpad1

- KbNumpad2

- KbNumpad3

- KbNumpad4

- KbNumpad5

- KbNumpad6

- KbNumpad7

- KbNumpad8

- KbNumpad9

- KbNumpadAdd

- KbNumpadDivide

- KbNumpadMultiply

- KbNumpadSubtract

- KbPageDown

- KbPageUp

- KbPause

- KbReturn

- KbRight

- KbRightAlt

- KbRightControl

- KbRightShift

- KbSpace

- KbTab

- KbUp

- Boutons de la souris :

- MsLeft

- MsMiddle

- MsRight

- MsWheelDown

- MsWheelUp

- Boutons du joystick:

- GpButton0

- GpButton1

- GpButton10

- GpButton11

- GpButton12

- GpButton13

- GpButton14

- GpButton15

- GpButton2

- GpButton3

- GpButton4

- GpButton5

- GpButton6

- GpButton7

- GpButton8

- GpButton9

- GpDown

- GpLeft

- GpRight

- GpUp

IX - Tutoriels

IX-A - Tutoriel n° 1 : Affichage d'une image

Ce premier tutoriel vous montre comment charger puis afficher une image dans notre fenêtre. Un script Gosu consiste toujours par définir la classe de notre fenêtre principale, qui hérite de Window. En redéfinissant les méthodes de cette classe, on obtiendra notre application. Ici, nous redéfinissons que la méthode initialize qui va initialiser notre jeu et la méthode update qui sera appelée toutes les 20 millisecondes pour rafraîchir notre fenêtre. update ne doit donc pas contenir de boucle principale de jeu, car celle-ci est implicite.

class Tut1 < Window
def initialize
super(640, 480, false, 20)
@image = Image.new(self, ".\\tut.bmp", true)
self.caption = "Tutoriel 1 : Affichage d'une image"
end

def update
@image.draw(10,10)
end
end

IX-B - Tutoriel n° 2 : Affichage d'une image en suivant la souris

Dans de nombreux jeux 2D, le joueur doit pouvoir bouger un curseur. Pour cela, il faut afficher une image aux coordonnées de la souris. Les coordonnées de la souris sont données par rapport à l'origine qui est le point en haut à gauche de la partie graphique de notre fenêtre (c'est-à-dire sans compter la barre Windows). Si la souris se trouve en dehors de la partie graphique de la fenêtre, cela ne pose pas de problème à Gosu. Pour voir comment cela fonctionne, on affichera également dans la console les coordonnées x et y de la souris. Pour le reste, il s'agit principalement des mêmes concepts employés dans le tutoriel n° 1.

class Tut2 < Window
def initialize
super(640, 480, false, 20)
@image = Image.new(self, ".\\tut.bmp", true)
self.caption = "Tutoriel 2 : Affichage d'une image suivant la souris"
end

def update
@image.draw(self.mouse_x,self.mouse_y)
print mouse_x, " ", mouse_y, "\n"
end
end

IX-C - Tutoriel n° 3 : Affichage de tiles

Généralement, un jeu 2D consiste à afficher des personnages, des objets. Mais le plus souvent, plusieurs images sont associées à un même objet : par exemple, une image montrera un personnage de dos, et une autre, ce même personnage, mais de face. Ainsi nous avons une succession d'images représentant le même objet ayant toutes la même taille. Au lieu de mettre chacune de ces images dans un fichier différent, on peut vouloir toutes les stocker dans un seul à la suite. Il faut après pouvoir découper toutes ces images facilement. Gosu propose la méthode load_tiles qui découpe le fichier et retourne un tableau d'images. On passera en paramètre simplement la largeur et la hauteur des images composant la suite.

Note : on peut aussi passer en paramètres le nombre d'images par ligne et par colonne dans notre fichier regroupant toutes les images.

class Tut3 < Window
def initialize
super(640, 480, false, 20)
@image_tab = Image.load_tiles(self, ".\\tut_tiles.bmp", 64, 64, true)
self.caption = "Tutoriel 3 : Affichage de tiles"
end

def update
@image_tab[0].draw(10,10)
@image_tab[1].draw(50,50)
end
end

IX-D - Tutoriel n° 4 : Affichage d'un texte

Ce tutoriel montre comment afficher un texte avec Gosu. Pour cela, il suffit de créer un nouvel objet de type Font, puis d'appeler la méthode draw en passant en paramètre les coordonnées où dessiner le texte ainsi que le texte à écrire.

class Tut4 < Window
def initialize
super(640, 480, false, 20)
@font = Font.new(self, "Arial", 36)
self.caption = "Tutoriel 4 : Affichage d'un texte"
end

def update
red = 0xFFFF0000
@font.draw("Youpi", 100, 100, 0, 2, 1, red)
end
end

IX-E - Tutoriel n° 5 : Affichage d'une image avec rotation

Une fonctionnalité puissante de Gosu est la possibilité d'afficher des images ayant fait une rotation autour d'un point grâce à la fonction draw_rot.

class Tut5 < Window
def initialize
super(640, 480, false, 20)
@image = Image.new(self, ".\\tut.bmp", true)
self.caption = "Tutoriel 5 : Affichage d'une image avec rotation"
end

def update
@image.draw_rot(30,30,0,30.0,0,0)
end
end

IX-F - Lancement des tutoriaux

Il faut faire un nouveau fichier Ruby (.rb) puis ajouter : En début du fichier script :

require "gosu.so"
include Gosu

En fin de fichier script :

t = TutX.new
t.show

Où X est le numéro du tutoriel.

IX-G - Exemple plus complet

Ceci est le code de l'exemple complet livré avec la bibliothèque. Il s'agit d'un jeu où vous devez, à l'aide de votre vaisseau, collecter des étoiles : néanmoins l'inertie de votre vaisseau rend la chose difficile. Une autre particularité de cet exemple est que si votre vaisseau dépasse un bord de la zone graphique, il réapparaît de l'autre côté. On notera aussi l'utilisation de son : à chaque fois que vous « mangez » une étoile avec votre vaisseau, un petit « bip » est émis. Cet exemple vous montrera mieux comment fonctionne un jeu écrit avec Gosu.

# On charge notre bibliothèque bien - aimée
require 'gosu'

# Définition du module ZOrder : celui à pour but de rassembler toutes les profondeurs des
# différents objets de notre jeu. Ainsi le fond aura une profondeur de 0, les étoiles de 1, le
# vaisseau du joueur de 2 et l'User Interface (le score) de 3. Plus la profondeur est grande,
# plus le dessin sera dessiné sur les autres dessins de profondeur plus petite.
module ZOrder
Background, Stars, Player, UI = *0..3
end

# Classe représentant une étoile pour notre jeu.
class Star
attr_reader :x, :y

# Initialisation d'une étoile
# On remarquera que sa couleur est aléatoire. De plus l'étoile utilise plusieurs images pour
# faire son animation (comme pour les dessins animés). Elle démarre aléatoire sur une des
# positions de son animation à une position également aléatoire.
def initialize(animation)
@animation = animation
@color = Gosu::Color.new(0xff000000)
@color.red = rand(255 - 40) + 40
@color.green = rand(255 - 40) + 40
@color.blue = rand(255 - 40) + 40
@x = rand * 640
@y = rand * 480
end

# Fonction pour dessiner notre étoile en fonction de son étape d'animation.
def draw
img = @animation[Gosu::milliseconds / 100 % @animation.size];
img.draw(@x - img.width / 2.0, @y - img.height / 2.0,
ZOrder::Stars, 1, 1, @color, :additive)
end
end

# Classe pour les objets incarnant le joueur à l'écran. Pour ce jeu, il s'agit d'un vaisseau
# spatial souffrant d'inertie.
class Player

# Fonction d'initialisation :
#    1 - chargement de l'image et du son propre aux instances de cette classe.
#    2 - initialisation des variables
def initialize(window)
@image = Gosu::Image.new(window, "media/Starfighter.bmp", false)
@beep = Gosu::Sample.new(window, "media/Beep.wav")
@x = @y = @vel_x = @vel_y = @angle = 0.0
end

# Fonction de télé - transportation du joueur : déplace le joueur aux coordonnées passées en
# paramètres.
def warp(x, y)
@x, @y = x, y
end

# Fonction pour tourner à gauche en diminuant l'angle du vaisseau.
# Le vaisseau peut donc tourner sur lui-même sans avoir besoin de vitesse pour le faire.
def turn_left
@angle -= 4.5
end

# Fonction pour tourner à droite en augmentant l'angle du vaisseau.
# Le vaisseau peut donc tourner sur lui-même sans avoir besoin de vitesse pour le faire.
def turn_right
@angle += 4.5
end

# Fonction pour faire accélérer le vaisseau selon son angle.
def accelerate
@vel_x += Gosu::offset_x(@angle, 0.5)
@vel_y += Gosu::offset_y(@angle, 0.5)
end

# Fonction faisant bouger le vaisseau. Chaque mouvement décélère le vaisseau.
def move
@x += @vel_x
@y += @vel_y
@x %= 640
@y %= 480

@vel_x *= 0.95
@vel_y *= 0.95
end

# Fonction pour ramasser les étoiles disséminées dans la fenêtre. Pour cela on parcourt toutes
# les étoiles et on détecte si une étoile entre en collision avec nous. La détection de collision
# se fait en regardant si la distance entre le centre de l'étoile et le centre du vaisseau est
#inférieure à 35 pixels. On joue un son si on est en contact avec une étoile et on augmente le
# score de 10.
def collect_stars(stars)
stars.reject! do |star|
dist_x = @x - star.x
dist_y = @y - star.y
dist = Math.sqrt(dist_x * dist_x + dist_y * dist_y)
if dist < 35 then
yield 10
@beep.play
true
else
false
end
end
end

# Fonction pour dessiner notre vaisseau selon son angle.
def draw
@image.draw_rot(@x, @y, ZOrder::Player, @angle)
end
end

# Classe pour la fenêtre du jeu. Elle va initialisé notre jeu en définissant un joueur et un
# tableau pour les étoiles. Ensuite, elle affichera son score et réagir aux touches pressées sur le
# clavier.
class GameWindow < Gosu::Window

# Initialisation du jeu :
#    1 - chargement des images et de la police de caractère
#    2 - initialisation des variables globales (le score, le titre de la fenêtre, les paramètres
#    d'affichages)
#    3 - création des éléments de base du jeu (un joueur et les étoiles)
# Note : le chargement des différentes animations de l'étoile se fait à l'aide d'un load_tiles.
def initialize
super(640, 480, false, 20)
self.caption = "Gosu Tutoriel Game"

@font = Gosu::Font.new(self, Gosu::default_font_name, 20)
@background_image = Gosu::Image.new(self, "media/Space.png", true)
@star_anim = Gosu::Image::load_tiles(self, "media/Star.png", 25, 25, false)

@player = Player.new(self)
@player.warp(320, 240)
@stars = Array.new
@score = 0
end

# Fonction principale du jeu : elle gère la " vie " du jeu :
#    1 - Réaction aux touches pressées (envoie d'un message à l'objet player)
#    2 - Génération d'étoiles
def update
if button_down? Gosu::Button::KbLeft or button_down? Gosu::Button::GpLeft then
@player.turn_left
end
if button_down? Gosu::Button::KbRight or button_down? Gosu::Button::GpRight then
@player.turn_right
end
if button_down? Gosu::Button::KbUp or button_down? Gosu::Button::GpButton0 then
@player.accelerate
end
@player.move
@player.collect_stars(@stars) { |gain| @score += gain }

if rand(100) < 4 and @stars.size < 25 then
@stars.push(Star.new(@star_anim))
end
end

# Fonction pour réagir aux boutons pressés puis relâchés. Typiquement, le bouton pour sortir
# du jeu.
def button_down(id)
if id == Gosu::Button::KbEscape
close
end
end

# Fonction de dessin. Elle est appelée après update et est chargée d'afficher le monde du jeu.
# Son action consiste à dessiner le score, l'arrière-plan puis le joueur et enfin toutes les
# étoiles.
def draw
@font.draw("Score: #{@score}", 10, 10, ZOrder::UI, 1.0, 1.0, 0xffffff00)
@background_image.draw(0, 0, ZOrder::Background)
@player.draw
@stars.each { |star| star.draw }
end
end

GameWindow.new.show

X - Todo

- Corriger le document et le tenir à jour.

XI - Historique

- Première version : mardi 31 janvier 2006

- Première version.

- Version 1.1 mercredi 1er février 2006

- Ajout des tutoriels

- Ajout de la rubrique todo

- Ajout de l'aide sur Window#caption

- Ajout de la rubrique sur l'installation de Gosu

- Version 1.2 jeudi 2 février 2006

- Ajout de l'exemple complet

- Commentaires des tutoriels

- Explication de Window#draw

- Correction de l'explication de Window#update

- Ajout de la section historique

- Ajout des concepts suivants :

- numérotations des coins

- modification de couleur

- bordure floue ou nette

- explication des angles avec Gosu

- Ajout d'une image (de la page de référence) pour l'explication des angles

- Introduction complétée avec plan

- Version 1.3 jeudi 16 février 2006

- Passage au format xml

- Ajout des installations sous Linux et Mac OS X

XII - Notes globales sur la documentation

Les couleurs des sources sont inspirées des couleurs par défaut de l'IDE Mondrian, un IDE pour Ruby en Ruby excellent : http://www.mondrian-ide.com/, libre et gratuit !