Pour que le tutoriel soit plus visible que dans le repo de mon jeu de pong ( https://git.planet-casio.com/mibi88/pong/src/branch/master/TUTORIAL_fr.md ), je le poste ici aussi. J'ai utilisé https://rtxa.github.io/mdtobb/ pour la conversion du markdown vers du BBCode. J'ai réécrit la table à la main. J'ai aussi réécrit les listes.

Tutoriel d'utilisation de libMicrofx

Dans ce tutoriel nous allons coder un jeu de pong en C avec libMicrofx.

Préréquis

Des connaissances solides du C sont requises.

Pour pouvoir suivre ce tutoriel, vous avez besoin du fxsdk, car libMicrofx réquis sh-elf-gcc etc. et fxgxa. Vous avez donc besoin d'un système d'exploitation UNIX-like compatible avec celui-ci. Vous avez bien sûr besoin d'une calculatrice CASIO monochrome sh-4 pour pouvoir tester l'add-in.

Quelques infos utiles

Le coin en haut à gauche est l'origine du repère. Le pixel en haut à gauche est aux coordonnées 0;0 et le pixel en bas à droite aux coordonnées 127;63, car l'écran fait 128x64 pixels.

Création du projet

Clonez le dépot libMicrofx (branche master). Faites une copie du dossier template, c'est un exemple de projet. Renommez votre copie de ce dossier avec le nom de votre nouveau projet (par exemple: pong).

Lancez make dans ce dossier. Si vous n'avez pas d'erreurs et obtenez un add-in fonctionnel, vous pouvez continuer.

Dans le dossier du projet, crééz un dossier assets pour y mettre les graphismes, ainsi qu'un dossier inc pour les headers.

Structure du projet

Nous allons structurer le projet comme ceci:

• main.c Lancement du jeu et boucle du jeu.
• game.c et game.h logique du jeu et rendu. game.h contiendra toutes les structures.
• ball.c et ball.h mouvement, collisions et rendu de la balle.
• paddle.c et paddle.h gestion des collisions entre la balle et la raquette, mouvement et rendu de la raquette.
• fixed.h Calculs à virgule fixe (si vous ne savez pas ce que c'est, c'est pas grave, j'en parlerais plus tard).

Créez ces fichiers, les fichiers .c dans src et les fichier .h dans inc.

Dans assets, créez un écran de titre (title_img.png) pour le jeu. Il doit avoir une dimension de 128x64 (la taille de l'écran). Vous pouvez aussi prendre celui du dépôt du tutoriel. Pour pouvoir l'utiliser depuis le code, il faut le convertir en code source. Vous pouvez utiliser sprite coder pour cela (https://tools.planet-casio.com/SpriteCoder/index.php).

Vous devriez avoir un dossier comme ça :


Makefile

Ajoutez les fichiers .c à SRC, changez NAME et ajoutez -Wall -Wextra -Wpedantic à la ligne


pour avoir plus de warnings, pour rendre le débogage plus facile.

Ajoutez aussi -Iinc, pour ne pas avoir à écrire le chemin vers les headers.

Si vous n'avez pas l'habitude du C ANSI enlevez -std=c89.

Code

Nous sommes enfin prêts à coder le jeu.

- main.c, la boucle du jeu

Nous allons commencer par faire la boucle du jeu. Pour que notre jeu soit agréable à jouer, nous allons limiter le nombre d'images par seconde à lequel il peut tourner, car la calculatrice est en mesure de l'exécuter très très vite.

Nous allons quitter la boucle si EXIT est appuyé, ce que nous pouvons voir avec kcheck(KCEXIT).

J'ai donc choisi de limiter le framerate à 50fps (cela vous rapelle peut être les jeux vidéos PAL des années 80).

libMicrofx propose une variété de fonctions pour controller le temps. Nous allons utiliser treset, tgetticks et tiselapsed, car ils nous offrent la meilleure précision que libMicrofx est capable de fournir (1/128 secondes). Si vous avez besoin d'une plus grande précision, utilisez gint.

tgetticks permet d'obtenir le temps écoulé depuis minuit.

tiselapsed permet de savoir si X milisecondes se sont écoulés depuis un certain nombre de ticks. Nous allons nous en servir pour attendre de 20ms s'écoulent depuis le début de l'image.

treset permet de réinitialiser le comptage du temps. On en a besoin, car au bout de 24h le temps est remis à zéro, ce qui pourrait faire crasher notre jeu.

Nous allons donc d'abord réinitialiser le RTC et ensuite utiliser tgetticks pour obtenir le temps écoulé. Nous allons ensuite exécuter une image du jeu, puis, dans une boucle, utiliser tiselapsed pour attendre que 20ms soient écoulées.

sclear efface l'écran et supdate met à jour l'écran donc mettez les entre tgetticks et tiselapsed.

Essayez par vous même, et regardez ensuite mon implémentation.


Testez. Si vous arrivez bien à quitter le jeu en appuyant sur EXIT, continuez.

- game.h, les structures

Maintenant que nous avons une boucle de jeu, nous pouvons commencer à coder le jeu en lui même.

Nous allons créer trois structures, Game, qui rassemble toutes les informations sur le jeu, Ball, qui représente la balle, et Paddle qui représente une raquette.

Nous allons mettre toutes les structures dans game.h (pour éviter le cross referencing).

Nous allons commencer par créer la structure Paddle, c'est celle qui nous intéressera en premier. Celle pour la balle sera plus compliquée.

Nous avons juste besoin de stocker la position de la raquette.


Ensuite nous allons créer la structure Game avec deux raquettes.


- paddle.c et paddle.h, gestion des raquettes.

Maintenant que nous avons crée toutes les structures, il est temps de coder le mouvement et l'affichage des raquettes.

- Initialisation d'une raquette.

Dans paddle.h, écrivez, comme vous en avez sûrement l'habitude


Dans paddle.c, nous allons commencer par coder inclure paddle.h. Nous allons aussi inclure microfx/microfx.h.


Nous allons créer une fonction paddle_init pour initialiser la raquette:


Dans cette fonction, nous allons mettre paddle->y à SHEIGHT/2: SWIDTH et SHEIGHT sont définis par microfx/microfx.h et SWIDTH contient la largeur de l'écran. SHEIGHT contient sa hauteur. paddle->x sera égal à x.


Mettez le prototype de cette fonction dans paddle.h.

- Mouvement d'une raquette.

Nous allons ensuite créer une fonction paddle_move pour pouvoir bouger la raquette.


Comme nous l'avons fait précédemment, nous allons utiliser kcheck pour récupérer les entrées clavier.

KCUP est la flèche vers le haut et KCDOWN est la flèche vers le bas.

Dans paddle.h nous allons définir la vitesse du paddle, ansi que sa taille.


Nous n'allons pas bêtement incrémenter et décrémenter la position du paddle, car il ne doit pas sortir de l'écran.

Mon implémentation :


Mettez le prototype de cette fonction dans paddle.h.

- Dessin d'une raquette

Maintenant que notre raquette peut être initialisée et bougée, nous devons la dessiner. Nous allons dessiner un rectangle.

Nous allons donc créer une fonction pour dessiner une raquette, et dessiner un rectangle à la position de la raquette, avec


Mon implémentation :


Mettez le prototype de cette fonction dans paddle.h.

- game.c et game.h, initialisation, rendu et logique

Maintenant nous avons grand besoin de tester si tout ce que nous avons codé fonctionne.

Nous allons donc créer trois fonctions:

• game_init pour initialiser le jeu.
• game_logic pour la logique du jeu.
• game_draw pour le rendu.

- Initialisation du jeu.

Dans game_init nous allons créer une première raquette avec une abscisse de 16 et une deuxième avec une abscisse de SWIDTH-16-PADDLE_WIDTH.

Mon implémentation :


Ajoutez le prototype de cette fonction à game.h.

- Logique du jeu.

Dans game_logic nous allons appeler paddle_move pour la première raquette.

Mon implémentation :


Ajoutez le prototype de cette fonction à game.h.

- Rendu

Dans game_draw nous allons dessiner les raquettes avec paddle_draw.

Mon implémentation :


Ajoutez le prototype de cette fonction à game.h.

- main.c, appel des fonctions de game.c

Avant de pouvoir tester, nous devons appeler toutes ces nouvelles fonctions.

Créez une variable game, et au début de main, et initialisez la avec game_init. Ensuite, dans la boucle du jeu, après sclear et avant supdate, appelez game_logic puis game_draw.

Mon implémentation de main :


- game.h et fixed.h, la balle et les nombres à virgule fixe.

- Opérations à virgule fixe.

Comme vous le savez sûrement déjà, l'écran de la calculatrice fait 128x64 pixels. Si l'on dessine un pixel à (0;0), et qu'on le déplace de 1 pixel sur l'axe des abscisses 50 fois par seconde, le pixel traverse l'écran en 2,56 secondes. C'est très rapide. Nous avons donc besoin de bouger le pixel de moins d'un pixel par image, mais comment faire ?

C'est très simple: nous allons stocker sa position comme un nombre réel, et l'incrémenter d'un nombre plus petit que 1 (ex: 0,1), ce qui nous permet de gérer la vitesse de son déplacement plus précisément. Pour trouver ses coordonnés à l'écran, nous ne prendrons que les chiffres avant la virgule.

Intuitivement, vous utiliseriez des floats mais la calculatrice n'a pas de FPU (une puce qui permet de faire des calculs à virgule flottante rapidement), donc tout est effectué sur le CPU ce qui rend les calculs avec des float très lent. De plus cela rend l'add-in plus volumineux (ce que nous ne voulons pas).

Nous allons donc utiliser des entiers : nous allons garder quelque bits pour les chiffres après la virgule. C'est ce que l'on appelle les nombres à virgule fixe.

Exemple: 19,2 comme entier 16 bit non signé avec une précision de 8 bits après la virgule :

Avant la virgule	Après la virgule
00010011	00110011

[/table]
Si l'on reconvertit ce chiffre en float, on obtient environ 19,199, car nous avons perdu en précision, mais ce n'est pas grave dans un jeu vidéo (19,199 c'est quand même très proche de 19,2 !).

Maintenant, codons quelque macros pour convertir des nombres en nombres à virgule fixe, et d'autres pour la multiplication et la division (nous pouvons faire les additions et les soustractions comme d'habitude).

La conversion est très facile, il suffit d'effectuer des décalages de bits.


Note : Je multiplie num par (1*PRECISION) pour pouvoir passer des floats à la macro.

Les macros pour la multiplication et la division sont très simples, elles aussi :


Nous allons finir par définir un type fixed_t, pour que notre code soit plus lisible :


- Structure Ball.

Dans game.h, nous pouvons donc créer une structure pour la balle, qui va contenir sa position, sa direction (sous forme de vecteur) et sa vitesse.


Nous allons aussi l'ajouter à la structure Game:


- ball.c, ball.h et game.c, le dessin et le mouvement de la balle.

- Initialisation de la balle.

Avant de faire quoi que ce soit avec la balle, nous devons l'initialiser. Nous allons donc créer une fonction ball_init dans ball.c. Elle aura pour paramètres la direction et la vitesse de la balle. Elle sera placée au milieu de l'écran.

Mon implémentation :


Ajoutez le prototype à ball.h et appelez cette fonction depuis game_init, pour l'initialiser au lancement du jeu.

- Dessin de la balle

Mainenant que nous avons initialisé la balle, nous pouvons la dessiner. Nous allons tout simplement récupérer ses coordonnés à l'écran, et dessiner un rectangle de 3x3 que nous allons remplir (vu que l'intérieur ne fait qu'un pixel, nous allons utiliser spixel), pour qu'elle soit assez visible.


Nous allons appeler cette fonction dans game_draw.

Vérifiez que tout fonctionne, et si tout est bon, vous pouvez continuer. Sinon relisez votre code et le tutoriel.

- Mouvement de la balle

Mainenant que nous dessinons la balle, nous pouvons la faire bouger. Nous allons créer une nouvelle fonction char ball_move(Ball *ball); et commencer par calculer la position qu'elle atteindra à l'écran :


Nous allons tout d'abord vérifier si la balle sortira du côté droit ou gauche de l'écran, pour pouvoir donner un point au joueur qui a marqué.


Nous pouvons aussi vérifier si elle doit rebondir sur les bords de l'écran, et nous allons la faire rebondir si besoin :


Nous allons finir par faire bouger la balle :


Mon implémentation :


Appelez cette fonction depuis game_logic, et récupérez ce qu'elle retourne, on en aura besoin.

Si la balle sort, réinitialisez la, pour pouvoir tester ce que nous venons de coder.

- paddle.h et paddle.c, collisions avec la balle et paddle de l'ordinateur

- Collision avec le paddle

Maintenant que nous avons une balle qui bouge, nous devonss pouvoir vérifier lorsqu'elle touche le paddle. Pour la simplicité de ce tutoriel, je garderais les collisions très simple, mais n'hésitez pas à les améliorer (en vérifiant pour une collision des deux côtés du paddle). Créez une fonction paddle_will_collide_with_ball qui a pour paramètres la raquette et la balle. Elle vérifiera si, lors du prochain mouvement de la balle, elle entrera en collision avec le paddle.

Nous allons commencer par calculer la position de la balle sur l'axe des abscisses après son mouvement :


Ensuite nous allons vérifier si la balle passera d'un côté à l'autre du côté gauche du paddle. Si c'est le cas, nous retournons 1 :


Sinon, retournez 0.

Appelez cette fonction depuis game_logic et inversez y_inc lors d'une collision pour pouvoir tester les collisions :


- Mouvement du paddle de l'ordinateur

Nous pouvons maintenant faire bouger le paddle de l'ordinateur en fonction de la position de la balle, maintenant que nous pouvons la renvoyer. Créez une fonction paddle_computer_move qui prend pour paramètres le paddle à bouger et la balle.

Si la position à l'écran, sur l'axe des ordonnées, de la balle est plus petite que la position de la raquette, nous allons la monter, et si elle est plus grande nous allons la monter. Sinon nous allons rien faire vu que la raquette est en face de la balle.


- game.c et game.h, affichage des scores.

- Initialisation et affichage des scores.

Nous avons déjà (presque) un jeu fonctionnel, mais nous devons compter le score, pour pouvoir savoir qui a gagné et qui a perdu.

Nous allons commencer par ajouter deux variables à la structure Game pour le stocker :


Nous allons ensuite l'initialiser dans game_init :


Pour l'afficher, nous allons utiliser itoa pour convertir le score en chaine de caractères et stext pour l'afficher à l'écran.

Les scores sont des unsigned char, donc un tableau de 4 caractères sera suffisant.

Pour afficher le score, nous allons d'abord appeler itoa pour obtenir une chaine de caractères :


Ensuite nous pouvons l'afficher avec stext :


Les deux premiers arguments sont la position à laquelle afficher le texte, le troisième, le texte à afficher et le dernier argument est la couleur (SWHITE ou SBLACK).

Nous allons faire de même pour le score de l'ordinateur ce qui nous donne


- Incrémentation des scores.

Le nombre retourné par ball_move va enfin nous être utile ! Si il retourne 1 le joueur obtient un point, sinon c'est l'ordinateur qui obtient un point :


- game.c, écran de titre et écran de fin du jeu.

- Mise en place

Lorsque le joueur ou l'ordinateur atteint un certain score, il faut que la partie se termine et que le joueur puisse recommencer. Nous avons donc besoin d'ajouter un écran de fin. Nous allons aussi ajouter un écran de titre.

Nous allons définir une énumération dans game.h qui liste les différents écrans :


Nous allons stocker l'écran actuel dans la structure Game :


Ensuite, nous allons l'initialiser dans game_init :


Nous allons créer un grand switch dans game_logic et game_draw pour effectuer des actions différentes selon l'écran affiché. Nous allons mettre le code que nous y avons actuellement dans le cas S_INGAME.

Dans game_logic :


Dans game_draw :


Note : Je n'ai pas mis de break à la fin de S_END, et je l'ai mis avant S_INGAME dans game_draw pour toujours afficher l'écran de jeu lorsque la partie est terminé. On écrira juste du texte en plus ("GAME OVER" ou "YOU WIN").

- Écran de titre

Nous allons commencer par ajouter l'écran de titre. Dans game_draw nous allons juste dessiner l'image de l'écran de titre :


Les deux premiers paramètres de simage indiquent la position à laquelle l'image doit être dessinée. Les deux prochains sont la taille de l'image, le cinquième un pointeur vers les données de l'image et le dernier comment l'image doit être dessinée :

• SNORMAL : On dessine le noir aussi bien que le blanc
• SINVERTED : On inverse les couleurs.
• STRANSP : le blanc est dessiné comme du noir et le noir n'est pas dessiné. Utile pour faire de la transparence.
• SNOWHITE : On ne dessine pas le blanc.
• SNOBLACK : On ne dessine pas le noir.

Dans game_logic nous allons réinitialiser le jeu (pour tout remettre à zéro) et aller vers l'écran S_INGAME, si la touche SHIFT est pressée :


- Écran de fin de la partie.

Nous allons ensuite coder l'écran de fin de la partie. Dans game_draw, nous allons afficher "GAME OVER" ou "YOU WIN!" selon le score.

Pour l'afficher au milieu, j'ai ajouté quelque defines en haut de game.c :


Dans game_draw il suffit d'appeler stext selon le score obtenu par le joueur :


Ensuite, dans game_logic nous allons attendre que SHIFT est pressé, puis attendre que cette touche soit relachée pour que l'écran de titre ne soit pas sauté.


Ensuite, nous devons aller à l'écran de fin au score maximal, lorsqu'on change le score :


- ball.c, ball.h et game.c, rebond de la balle sur la raquette.

Pour l'instant, le rebond de la balle n'est pas très fidèle à celui de pong. Je trouve que faire l'interpolation linéaire entre y_inc = -1 et y_inc = 1 de la position de la balle par rapport à la raquette est assez fidèle à l'original.

Nous allons donc créer une fonction ball_bounce qui a pour paramètre la balle et le paddle, dans laquelle nous allons calculer le nouveau y_inc comme je l'ai décrit ci-dessus.

Mon implémentation :


Ajoutez son prototype à ball.h et appelez la lors d'une collision, là où on a précedemment fait game->ball.y_inc = -game->ball.y_inc;.

Améliorations possibles

Améliorez les collisions, essayez de rendre le jeu le plus petit possible, cela vous entrainera bien. Vous pouvez aussi ajouter un mode deux joueurs ou un mode robot contre robot. Vous pouvez aussi rendre possible la séléction du score maximal (libMicrofx propose des fonctions de saisie de nombres et de texte).

Étendre vos connaissances de libMicrofx

Pour étendre vos connassances de libMicrofx je vous conseille de lire les headers dans lib/include/microfx. La plupart des fonctions sont dans microfx.h. Il y a des fonctions très utiles à la création de jeux vidéos dans les headers dans le dossier ext.

C'est la fin de ce tutoriel

Voilà ! Vous avez fini de lire ce tutoriel (ou presque). J'espère que ce tutoriel vous a plu et que vous vous amuserez bien avec libMicrofx !