Développement GameBoy #7 : Les sprites

Charger des tuiles en mémoire

Avant de pouvoir afficher le moindre sprite à l'écran, il faut, comme pour les autres couches, charger des tuiles dans la mémoire vidéo de la GameBoy. GBDK nous fournit bien sûr une fonction pour ça :

void set_sprite_data(UINT8 first_tile, UINT8 nb_tiles, unsigned char *data);

La seule différence avec set_bkg_data(), la fonction utilisée pour charger les tuiles utilisées par les couches Backrgound et Window, c'est que les données ne sont pas envoyées au même endroit dans la mémoire. Je ne vais donc pas rentrer plus dans les détails étant donné que ça marche de la même façon.

Activer / désactiver la « couche » Sprites

Comme pour les autres couches, les sprites ne sont pas affichés par défaut, il faudra donc les rendre visibles avec la macro suivante :

SHOW_SPRITES;

... et il est possible de les masquer avec la macro :

HIDE_SPRITES;

Afficher un sprite et le positionner

Passons enfin aux choses sérieuses : afficher un sprite là où on veut à l'écran. Comme je l'ai dit en introduction, la GameBoy peut afficher jusqu'à 40 sprites à l'écran. Chacun d'entre eux est identifié par un numéro (de 0 à 39) qui sera passé en paramètre aux fonctions manipulant les sprites.

Pour commencer, il va falloir assigner une tuile à l'un des sprites (sinon la GameBoy ne saurait pas quoi afficher). Cela se fait à l'aide de la fonction suivante :

void set_sprite_tile(UINT8 nb, UINT8 tile);

• nb correspond au numéro du sprite à modifier (0-39),
• tile correspond au numéro de la tuile qui sera contenu dans ce sprite (0-255)

On peut ensuite déplacer le sprite là où on le souhaite à l'écran à l'aide de l'une des deux fonction suivantes :

void move_sprite(UINT8 nb, UINT8 x, UINT8 y);

Cette fonction déplace le sprite nb aux coordonnées (x, y) indiquée.

void scroll_sprite(INT8 nb, INT8 x, INT8 y);

Cette fonction fait la même chose, mais le déplacement est relatif (si on met x à -5, le sprite sera déplacé de 5 pixels vers la gauche).

Il y a une petite subtilité que je n'ai pas encore abordé dans le placement des sprites : le coin en haut à gauche de l'écran a pour coordonnées (8, 16) (et pas (0, 0) comme on aurait pu s'y attendre). Ceci permet de faire déborder un sprite sur les bords gauche et haut de l'écran :

Enfin, dernière information à propos du placement des sprites : les sprites se retrouvent masqués lorsque leurs coordonnées les placent en dehors de l'écran :

• lorsque x est égal à 0 ou supérieur ou égal à 168,
• ou lorsque y est égal à 0 ou supérieur ou égal à 160.

C'est d'ailleurs de cette façon que l'on masque individuellement un sprite.

Modifier les propriétés d'un sprite

Comme on l'a vu dans l'introduction, la GameBoy permet d'opérer un certain nombre de modifications sur un sprite :

• changer la palette de couleur servant à l'afficher,
• le retourner horizontalement,
• le retourner verticalement,
• changer sa priorité (pour le placer devant ou derrière les autres couches).

Toutes ces modifications peuvent être effectuées à l'aide de la fonction set_sprite_prop() :

void set_sprite_prop(UINT8 nb, UINT8 prop);

• nb correspond au numéro du sprite à modifier (0-39),
• prop correspond aux modifications à apporter au sprite.

L'argument prop est donc un nombre dont 4 des 8 bits correspondent à des flags activant l'une des modifications. Les 4 bits restants ne sont pas utilisés sur la GameBoy originale, mais le seront plus tard par la GameBoy Color (mais ça,c'est une autre histoire).

GBDK nous fournit des constantes contenant les masques permettant de manipuler chacun des bits qui nous intéressent. Pour utiliser ces masques, il faudra donc encore jouer avec des opérations binaires... mais pas de panic, je vous explique ça tout de suite.

Pour activer l'une des modifications (passer le bit à 1), il faudra appliquer le masque correspondant au bit à modifier à la valeur actuelle de prop à l'aide de l'opération binaire OU. Ceci peut être réalisé à l'aide du code suivant :

UINT8 nb = 0;  // Numéro de la tuile à modifier
set_sprite_prop(nb, get_sprite_prop(nb) | MASQUE_DU_BIT);
//                                      ---------------
//                                    passe le bit désigné
//                                      par le masque à 1

Et pour désactiver l'une des modifications (et donc passer le bit correspondant à 0), il faudra appliquer le complément du masque à la valeur courante de prop à l'aide de l'opération binaire ET :

UINT8 nb = 0;  // Numéro de la tuile à modifier
set_sprite_prop(nb, get_sprite_prop(nb) & ~MASQUE_DU_BIT);
//                                      ----------------
//                                     passe le bit désigné
//                                      par le masque à 0

set_sprite_prop(10, get_sprite_prop(10) | S_PALETTE);

set_sprite_prop(10, get_sprite_prop(10) & ~S_PALETTE);

Utiliser des sprites en 8×16

Dernière possibilité offerte par la GameBoy : utiliser des sprites de 8×16 pixels. Cette configuration s'active par contre de manière globale : il n'est pas possible d'utiliser en même temps des sprites de 8×8 px et de 8×16 px.

Les sprites de 8×16 px affichent donc 2 tuiles, l'une en dessous de l'autre, et il y a quelques subtilités à savoir. On a vu plus tôt comment définir la tuile qui doit être affichée par un sprite de 8×8 px, eh bien pour les sprites plus grand c'est la même chose... sauf que les tuiles fonctionnent par paire : il suffit d'indiquer n'importe laquelle des deux tuiles d'une paire, et la première s'affichera en haut et la seconde en bas (donc indiquer la tuile 0 ou 1 aura strictement le même effet) :

Pour activer les sprites de 8×16 px, il faut utiliser la macro suivante :

SPRITES_8x16;

Et pour repasser les sprites en 8×8 px, la macro à utiliser est :

SPRITES_8x8;

Un petit exemple pour digérer

Après tous ces détails techniques sur le fonctionnement des sprites il est enfin temps de mettre les mains dans le cambouis histoire de voir comment ça marche en situation réellement. Je vous propose donc ce petit exemple dans lequel on va animer un petit personnage en forme de GameBoy, que nous appellerons Gaby (pour Gameboy Animated Blayer Yolo, #JaiPasTrouvéMieux). Gaby pourra être déplacée dans les quatre directions à l'aide du D-Pad, et... ce sera déjà bien 😁️

Voici là liste des caractéristiques de Gaby la GameBoy :

• Elle mesure 16×16 px : il faudra donc 2 sprites de 8×16 px pour la représenter.
• Elle se promène dans les 4 directions : il faudra donc prévoir des tuiles pour chaque direction (en réalité 3 directions suffiront : on va utiliser la fonction miroir pour les directions droite et gauche).
• Elle est animée : il va falloir dessiner toutes les tuiles de l'animation et prévoir du code pour changer les tuiles avec le bon timing.
• Étant donnée que Gaby est une GameBoy blanche, on va utiliser la palette de couleur alternative (la couleur noire sera donc transparente).

Pour commencer, il faut dessiner les tuiles qui seront utilisées dans les sprites. Voici quelques petites précisions à noter pour le dessin :

• Je vais dessiner les tuiles comme si j'allais utiliser la palette de couleur normale (en gardant à l'esprit que le noir sera la couleur transparente), et je laisserais img2gb inverser les couleurs à l'aide de son option --alternative-palette.
• Comme on l'a vu plus tôt, il faut agencer les tuiles d'une manière particulière pour les utiliser dans des sprites de 8×16 : il faut positionner les tuiles d'une même paire l'une à côté de l'autre, alors qu'elles seront affichées l'une en dessous de l'autre... ce qui n'est pas pratique pour le dessin. Je vais donc quand même les dessiner l'une en dessous de l'autre, et utiliser l'option --sprite8x16 d'img2gb pour les réorganiser automatiquement.

Voici donc à quoi ressemble les tuiles qui composent Gaby une fois mon dessin terminé (j'ai zoomé l'image et mis en évidence les deux premières paires afin de bien illustrer la transformation qui sera opérée par img2gb) :

Maintenant que l'on a dessiné les tuiles, on peut générer le tileset qui pourra être utilisé sur GameBoy. Pour ce faire, on va utiliser img2gb, le petit outil que je vous avais présenté dans un précédent article :

img2gb tileset \
    --output-c-file=src/player.sprites.c \
    --output-header-file=src/player.sprites.h \
    --output-image=src/player.sprites.png \
    --alternative-palette \
    --sprite8x16 \
    --name PLAYER_SPRITES \
    ./player.png

Cette commande nous génère des fichiers .c et .h que nous pourrons utiliser dans notre programme, et un fichier .png qui nous permet de voir le résultat de la transformation (cette fois encore j'ai zoomé l'image et mis en évidence les deux premières paires) :

Maintenant qu'on a tout ce qu'il faut du côté des graphismes, on peut passer au code. Voici donc le code complet de l'exemple tout bien commenté, (oui il est un peu long, mais si on prend le temps de le lire tranquillement en commençant par la fonction main(), ça se comprend assez bien) :

#include <gb/gb.h>

#include "player.sprites.h"

// Id ("nb") des deux sprites utilisés pour représenter le joueur
#define PLAYER_SPRITE_L_ID 0
#define PLAYER_SPRITE_R_ID 1

// Données de l'animation des sprites du joueur
UINT8 PLAYER_SPRITE_ANIM_L[] = {
// TAILLE | MIROIR | ID DES TUILES   | DIRECTION
   4,       0,        0 , 4,  0,  8,   // Bas
   4,       0,       12, 16, 12, 20,   // Haut
   4,       0,       24, 28, 24, 32,   // Droite
   4,       1,       26, 30, 26, 34,   // Gauche
};
UINT8 PLAYER_SPRITE_ANIM_R[] = {
// TAILLE | MIROIR | ID DES TUILES   | DIRECTION
   4,       0,        2,  6,  2, 10,   // Bas
   4,       0,       14, 18, 14, 22,   // Haut
   4,       0,       26, 30, 26, 34,   // Droite
   4,       1,       24, 28, 24, 32,   // Gauche
};

// Liste des sous-animation (les nombre représentent l'octet où la
// sous-animation commence dans les données globales de l'animation du
// joueur)
#define PLAYER_DIRECTION_DOWN  0
#define PLAYER_DIRECTION_UP    6
#define PLAYER_DIRECTION_RIGHT 12
#define PLAYER_DIRECTION_LEFT  18

// Variables stockant l'état du joueur
UINT8 player_x;
UINT8 player_y;
UINT8 player_direction;
UINT8 player_animation_frame;
UINT8 is_player_walking;

// Retourne un sprite horizontalement (sur l'axe X).
//
// sprite_id: l'id ("nb") du sprite à modifier.
void flip_sprite_horiz(UINT8 sprite_id) {
    set_sprite_prop(sprite_id, get_sprite_prop(sprite_id) | S_FLIPX);
}

// Supprime le retournement horizontal d'un sprite.
//
// sprite_id: l'id ("nb") du sprite à modifier.
void unflip_sprite_horiz(UINT8 sprite_id) {
    set_sprite_prop(sprite_id, get_sprite_prop(sprite_id) & ~S_FLIPX);
}

// Met à jour les tuiles d'un sprite pour l'animer.
//
// sprite_id: l'id ("nb") du sprite à modifier
// anim:      pointeur vers les données de l'animation
// direction: direction de l'animation (= offset de la sous-animation)
// frame:     la nouvelle frame de l'animation qui doit être affichée
//
// Retourne la prochaine frame de l'animation.
UINT8 update_sprite_animation(UINT8 sprite_id, UINT8 *anim, UINT8 direction, UINT8 frame) {
    UINT8 len = anim[direction];
    UINT8 flip = anim[direction + 1];
    UINT8 tile_id = anim[direction + 2 + frame];

    if (flip) {
        flip_sprite_horiz(sprite_id);
    } else {
        unflip_sprite_horiz(sprite_id);
    }

    set_sprite_tile(sprite_id, tile_id);

    return (frame + 1) % len;
}

void main(void) {
    UINT8 keys = 0;
    UINT8 frame_skip = 8;  // On met à jour l'animation toutes les 8 frames
                           // seulement, sinon l'animation serait trop
                           // rapide (8 frames = ~133 ms entre chaque frame
                           // de l'animation)

    // On initialise l'état du joueur
    player_x = 80;
    player_y = 72;
    player_direction = PLAYER_DIRECTION_DOWN;
    player_animation_frame = 0;
    is_player_walking = 0;

    // Charge les tuiles des sprites dans la mémoire vidéo
    set_sprite_data(0, PLAYER_SPRITES_TILE_COUNT, PLAYER_SPRITES);

    // On utilise des sprites de 8×16 px
    SPRITES_8x16;

    // On rend les sprites visibles
    SHOW_SPRITES;

    // On initialise les deux sprites qui représentent le joueur
    move_sprite(PLAYER_SPRITE_L_ID, player_x, player_y);
    set_sprite_prop(PLAYER_SPRITE_L_ID, S_PALETTE);

    move_sprite(PLAYER_SPRITE_R_ID, player_x + 8, player_y);
    set_sprite_prop(PLAYER_SPRITE_R_ID, S_PALETTE);

    while (1) {
        // On attend le rafraichissement de l'écran (v-sync)
        wait_vbl_done();

        // On lit les touche du gamepad pour savoir si le joueur
        // se déplace, et dans quelle direction
        keys = joypad();
        if (keys & J_UP) {
            player_direction = PLAYER_DIRECTION_UP;
            is_player_walking = 1;
        } else if (keys & J_DOWN) {
            player_direction = PLAYER_DIRECTION_DOWN;
            is_player_walking = 1;
        } else if (keys & J_LEFT) {
            player_direction = PLAYER_DIRECTION_LEFT;
            is_player_walking = 1;
        } else if (keys & J_RIGHT) {
            player_direction = PLAYER_DIRECTION_RIGHT;
            is_player_walking = 1;
        } else {
            is_player_walking = 0;
            frame_skip = 1;  // On force le rafraîchissement de l'animation
        }

        // On met à jour la position du joueur s'il est en train de marcher
        if (is_player_walking) {
            if (player_direction == PLAYER_DIRECTION_RIGHT) player_x += 1;
            else if (player_direction == PLAYER_DIRECTION_LEFT) player_x -= 1;
            else if (player_direction == PLAYER_DIRECTION_UP) player_y -= 1;
            else if (player_direction == PLAYER_DIRECTION_DOWN) player_y += 1;
            move_sprite(PLAYER_SPRITE_L_ID, player_x, player_y);
            move_sprite(PLAYER_SPRITE_R_ID, player_x + 8, player_y);

            // Ici on compte les frames pour ne pas mettre à jour l'animation
            // à chaque rafraîchissement de l'écran : l'animation serait trop
            // rapide sinon...
            frame_skip -= 1;
            if (!frame_skip) {
                frame_skip = 8;
            } else {
                continue;
            }
        } else {
            player_animation_frame = 0;
        }

        // On met à jour les tuiles utilisées dans les sprites
        update_sprite_animation(
                PLAYER_SPRITE_L_ID,
                PLAYER_SPRITE_ANIM_L,
                player_direction,
                player_animation_frame);
        player_animation_frame = update_sprite_animation(
                PLAYER_SPRITE_R_ID,
                PLAYER_SPRITE_ANIM_R,
                player_direction,
                player_animation_frame);
    }
}

Lorsque l'on compile tout ça et qu'on le lance dans un émulateur, ça donne le résultat suivant :

Comme d'habitude vous retrouverez le code complet du projet sur Github :

• https://github.com/flozz/gameboy-examples/tree/master/07-graphics4-sprites

C'est ainsi que s'achève cet article sur les sprites. Le prochain article, que je vais essayer de sortir rapidement (edit: raté... 😅️), traitera de la couche Window, et sera l'avant dernier article de la partie « graphismes » de cette série d'articles.