Carré coloré, petit jeu en Forth, le résultat

Trois mois après... ou presque. En août, j'étais parti sur l'idée de porter en Forth un petit jeu en BASIC trouvé dans un recueil dont le titre est « Astounding Games for your Apple Computer ». Après étude du programme initial et première mise sur papier (numérique) d'un équivalent Forth, j'avais choisi Forth Abersoft sur Amstrad CPC comme environnement de cette récréation.

Et puis... les activités de septembre sont arrivées, ça s'est enchaîné, j'ai participé aux RPUfOS sur le Sinclair QL puis enchaîné avec une petite Game Jam sur Pico Computer 6502 (pas encore traitée ici mais le résultat est là et c'est même jouable en ligne).

Bref, le temps passe vite. Mais porter le jeu en Forth le fut aussi, voici donc le résultat !

Abersoft Forth

À la recherche d'un peu plus de documentation sur ce Forth, la première découverte est qu'il semble être l'adaptation sur Amstrad CPC d'un Forth pour ZX Spectrum. Je n'ai pas poussé plus sur l'historique, ma déduction n'est basée que sur le fait que l'éditeur pleine page sur CPC est une version dégradée de la version sur Spectrum.

Autre découverte intéressante, ce Forth a été désassemblé et commenté il y a 9 ans ! Et ça en fait une bonne base de documentation. Sur CPC, tous (ou presque) les mots spécifiques du BASIC sont disponibles en Forth.

Au démarrage, le Forth indique que c'est une version 464, ce qui explique probablement qu'un seul SCREEN est maintenu en mémoire. Ça rend un peu pénible l'édition en direct sur la machine, qui doit sauver et charger des données au moindre changement de SCREEN, mais au moins, ça existe.

Et tous les buffers sont sérialisés de manière assez direct dans un gros fichier unique. Cela permet de faire de l'injection sur une image virtuelle depuis une machine moderne et lancer facilement sur émulateur.

J'ai apprécié ce Forth, dans la limite de ce petit exercice. J'y reviendrai peut-être.

La théorie et la pratique

Pour rappel, les mots identifiés qui reprenaient le fonctionnement du programme BASIC dans l'article précédent étaient ceux-ci :

  • INIT.GRID ( - grid ) : initialisation du damier (avec ALLOT). Voir pour les couleurs en fonction de la machine.
  • INIT.CHARS ( - ) : si besoin comme pour l'Apple, sinon, rien.
  • INIT.GAME ( - grid ) : appelle les deux INIT. précédents
  • .CSQUARE ( x y c - ) : affiche un carré à la position écran donnée
  • G\>S ( r c - x y ) : transforme une coordonnée (row,column) de la grille en coordonnées (x,y) pour l'écran
  • .DIGIT ( x y n - ) : affiche un caractère n à la position écran donnée
  • T\>S ( r c - x y ) : transforme une coordonnée (row,column) de l'écran en coordonnées (x,y) pour l'écran
  • .SCREEN ( - ) : affichage complet de l'écran
  • PUSH.ROW ( grid n - ) : pousse le rang n de la grille (en mettant à jour l'affichage)
  • PUSH.COL ( grid n - ) : pousse la colonne n de la grille (en mettant à jour l'affichage)
  • PUSH ( grid n - ) : pousse un rang ou une colonne de la grille (en fonction du numéro passé)
  • SHUFFLE.GRID ( grid n - ) : effectue n mouvements dans la grille
  • INPUT.VALID? ( n - b ) : renvoi 0 si l'entrée du joueur n'est pas valide
  • INPUT ( - n ) : demande une entrée valide du joueur
  • GAME : le programme principal

Est-ce que ça a bien résisté au passage au réel ? Oui, plutôt.

Voyons au final le programme au complet, avec des commentaires

Pour démarrer, un mot balise pour marquer le début du dictionnaire. L'intérêt est de pouvoir, pendant le développement, faire un FORGET COLOR.GAME avant de recompiler le contenu des buffers... Bon, COLOR.GAME était bien trop long comme mot...

: COLOR.GAME ; \ marqueur pour le forget

Ensuite, pas vraiment du code mais une note. J'avais initialement une constante nommée SIZE. Cependant, le mot existe dans le Forth et renvoie la taille en octets utilisé par le dictionnaire. J'ai donc renommé en GSIZE (pour Grid Size)

\ Notes CPC :
\ SIZE est un mot déjà défini. Renommage en GSIZE

J'ai dû ajouter quelques mots que j'utilise mais qui n'existent pas sur ce Forth. Soustraire 1, avec 1- par habitude, et < CMOVE pour copier une plage de mémoire en partant de la fin. Ce Forth n'a que CMOVE, qui part du début.

\ N'existent pas
: 1- 1 - ;
\ <CMOVE ( from to len - ) copie n octets en partant de la fin
: <CMOVE
  DUP 0 > IF
    >R                        \ ( from to ) R: len
    R + 1- SWAP R + 1- SWAP   \ ( from-fin to-fin )
    R> 0 DO
      OVER C@ OVER C!         \ copie un octet
      1- SWAP 1- SWAP         \ recule les deux pointeurs
    LOOP
    DROP DROP
  ELSE
    DROP DROP DROP
  ENDIF
;

Ensuite, le générateur aléatoire. Je n'ai pas trouvé de générateur pour le Forth. Pas grave, je n'ai pas besoin de quelque chose de bien forth et des formules se trouvent assez facilement. Donc RANDOM et CHOOSE, qui se basent sur une variable SEED.

Pour l'initialisation de la seed, je récupère le temps pour retrouver le fameux (pour les CPCistes) RANDOMIZE TIMER. Je ne sais pas si ce code pour TIME est portable, il fonctionne sur 6128 en tout cas.

C'était aussi l'occasion d'essayer l'assembleur en ligne.

\ Récupération du temps
HEX
CODE TIME
  BC PUSH
  IX PUSH   \ protection des registres
  BE9B CALL BD0D ,  \ appel BD0D via un appel firmware. TIME dans DEHL
  IX POP
  BC POP    \ récupération des registres
  EXDEHL
  PUSHDE    \ appelle le push DE et HL
C;          \ termine le mot en assembleur
DECIMAL

\ Aléatoire
0 VARIABLE SEED
: RANDOM ( -- u ) SEED @ 31421 * 6927 + DUP SEED ! ;
: CHOOSE ( n -- 0..n-1 ) RANDOM U* SWAP DROP ;
: RANDOMIZE TIME DROP SEED ! ;

Et enfin, après ce préambule, le jeu tel que prévu. Avec quelques constantes pour définir la géométrie de la grille (5 par 5), la taille des carrés, le positionnement à l'écran et une variable GRID qui réserve l'espace pour le contenu des cases de la grilles.

\
5 CONSTANT GSIZE \ Taille d'une dimension de la grille
0 VARIABLE GRID GSIZE GSIZE * ALLOT

56 CONSTANT GRID.X.SCALE
56 CONSTANT GRID.Y.SCALE

160 CONSTANT GRID.X
64 CONSTANT GRID.Y

48 CONSTANT SQUARE.SIZE

Le code d'initialisation est lancé par INIT.GAME, qui appelle INIT.GRID pour remplir la grille avec un contenu de grille résolue, et INIT.CHARS... qui ne fait rien ici. Je l'ai gardé car le programme original sur Apple II, redéfini des caractères pour s'afficher en mode graphique.

L'Amstrad CPC peut afficher ses caractères en mode graphique, donc pas besoin.

\ INIT.GRID ( - )
\ Initialisation des couleurs
: INIT.GRID
  GRID 2+    \ début de la grille
  GSIZE 0 DO  \ compteur sur les lignes
    DUP         \ ( grid grid )
    GSIZE I FILL \ ligne I avec la couleur I
    GSIZE +      \ avance le pointeur sur la grille
  LOOP
  DROP
  ;

\ INIT.CHARS ( - )
\ Si besoin comme pour l'Apple, sinon, rien.
: INIT.CHARS ;

: INIT.GAME ( - )
  INIT.GRID
  INIT.CHARS ;

L'affichage graphique des cases. .SQUAREF était un premier essai de case pleine. C'était beaucoup trop lent. Je suis donc passé à .SQUARE qui affiche un cadre. On peut voir l'utilisation des commandes DRAWR, MOVE, MOVER ou encore GPEN qui sont les mêmes qu'en BASIC CPC, mais qui vont bien entendu chercher leurs paramètres sur la pile.

MOVE déplace le curseur graphique à une adresse écran absolu. MOVER fait de même mais avec des coordonnées relative à l'emplacement du curseur actuel. DRAWR fait comme MOVER en traçant une ligne entre les deux positions. GPEN choisi le crayon d'écriture pour l'affichage graphique.

Je n'initialise absolument pas les couleurs. Dans l'esprit du programme original, il n'y a pas de fioritures, je pars avec l'état de la machine tel quel.

\ .SQUAREF ( n - )
\ SPECIFIQUE CPC
\ Affiche un carré rempli de taille n à l'emplacement actuel et avec la couleur actuelle
: .SQUAREF
  DUP 0 DO
    DUP 0 DRAWR DUP MINUS 1 MOVER
  LOOP DROP
;

\ .SQUARE ( n - )
\ SPECIFIQUE CPC
\ Affiche le contour d'un carré de taille n à l'emplacement actuel et avec la couleur actuelle
: .SQUARE
  DUP 0 DRAWR
  DUP 0 SWAP DRAWR
  DUP MINUS 0 DRAWR
  0 SWAP MINUS DRAWR
;

\ .CSQUARE ( x y c - ) : affiche un carré à la position écran donnée
\ SPECIFIQUE CPC
: .CSQUARE
  GPEN MOVE
  SQUARE.SIZE .SQUARE
;

Ce mot transcrit un couple (ligne, colonne) en coordonnées graphique. L'idée étant de séparer le traitement de la grille de l'affichage spécifique, pour portage sur une autre machine.

\ G>S ( r c - x y )
\ SPECIFIQUE CPC
\ Transforme une coordonnée (row,column) de la grille en coordonnées (x,y) pour l'écran
: G>S
  GRID.X.SCALE * GRID.X +
  SWAP
  GRID.Y.SCALE * GRID.Y +
;

Ah ben... c'est un oublie. Un mot prévu que je redécouvre en écrivant cet article. Ooops.

L'idée là encore était de séparer les fonctions à porter par machine, pour en limiter l'impact. Ce mot ne font donc rien... enfin si, il consomme ses paramètres, c'est déjà ça.

\ .DIGIT ( x y n - )
\ Affiche un caractère n à la position écran donnée
: .DIGIT DROP DROP DROP ;

Ce mot était prévu pour transformer des coordonnées (ligne, colonne) de l'écran en coordonnées graphique. Je ne l'ai pas utilisée, mais c'était une décision consciente ici, contrairement au mot précédent. Possiblement une décision guidée par la flemme.

\ T>S ( r c - x y )
\ Transforme une coordonnées (row,column) de l'écran en coordonnées (x,y) pour l'écran
\ Pas utilisé sur CPC
: T>S
;

.REDRAW affiche toutes les cellules de la grille au complet. Une double boucle qui prend la valeur de la cellule, transforme les coordonnées et appelle .CSQUARE.

À noter le GRID 2+. La manière dont fonctionne ALLOT est que la taille réservée est celle de la taille passée en paramètre. Mais la variable qui tient cette réservation (GRID) existe aussi, et elle consomme une cellule (deux octets dans cette implémentation). On peut s'en servir, ou bien l'ignorer. Dans ce jeu, je l'ignore. Les données de la grille commencent donc deux octets après l'adresse renvoyée par la variable GRID.

Je perds deux octets, mais vu le contexte de ce jeu, c'est acceptable.

\ .REDRAW ( - )
\ SPECIFIQUE CPC
\ Affichage de la grille
: .REDRAW
  GRID 2+     \ début de la grille
  GSIZE 0 DO   \ boucle sur Y
    GSIZE 0 DO \ boucle sur X
      DUP C@  \ valeur de la grille ( grid c )
      J I G>S \ ( grid c s y )
      ROT     \ ( grid x y c )
      .CSQUARE \ ( grid )
      1+
    LOOP
  LOOP
  DROP
;

L'affichage des chiffres qui indiquent les chiffres à utiliser pour pousser une ligne ou une colonne.

À l'horizontal, tous les chiffres sont affichés de la même couleur. En vertical, les chiffres sont affichés de la couleur que doit prendre la ligne entière pour résoudre la grille.

TAG est le mot qui indique au CPC que l'affichage de texte se fait à présent en coordonnées graphiques. TAGOFF revient en mode texte normal, et c'est LOCATE, dans ce mode, qui déplace le curseur texte.

\ .DRAW.COORDS ( - )
\ SPECIFIQUE CPC
: .DRAW.COORDS
  TAG
  5 GPAPER
  GSIZE 0 DO
    4 GPEN
    0 I G>S SWAP 8 + SWAP 8 - MOVE
    I 6 + DUP 10 = IF DROP 0 ENDIF .
    I GPEN
    I 0 G>S SWAP 32 - SWAP 32 + MOVE
    I 1 + .
  LOOP
  TAGOFF
  1 1 LOCATE \ Retour du curseur en haut à gauche
;

Pas de mystère ici. On initialise le mode graphique 0 (pour avoir accès au maximum de couleurs simultanées du CPC), on affiche les coordonnées, puis la grille.

\ .SCREEN ( - )
\ SPECIFIQUE CPC
\ Affichage complet de l'écran
: .SCREEN
  0 MODE 5 PAPER CLS 0 0 BORDER
  .DRAW.COORDS
  .REDRAW
;

PUSH.ROW et PUSH.COL sont probablement les fonctions les plus complexes du programme (et celles sur lesquels j'ai passé le plus de temps, l'arithmétique de pointeur et la manipulation de la pile en Forth, ça fait un peu de nœuds au cerveau parfois, mais c'est ça qui est fun aussi).

Dans ces cas, indiquer en commentaire l'état de la pile au fur et à mesure est un bon moyen de suivre le flow.

Pour la ligne, c'est simple, une copie de mémoire en décalant d'un octet (les cellules sont consécutives en mémoire) et mettre la valeur de la première case sur la dernière.

Pour la colonne, c'est un peu la même chose, mais avec une boucle qui passe de ligne en ligne, puisque les cellules de la grille ne sont pas consécutives en mémoire dans ce cas là.

Le jeu ne permet que de pousser la ligne ou la colonne dans un sens, donc pas besoin de mot qui font « tourner » dans l'autre sens.

\ PUSH.ROW ( n - ) : pousse le rang n de la grille (en mettant à jour l'affichage)
: PUSH.ROW
  GSIZE *       \ décalage pour aller sur la ligne (pas de protection)
  GRID + 2+     \ début de la grille
  DUP           \ ( addr addr )
  GSIZE + 1-    \ dernière case de la rangée
  C@            \ ( addr value )
  OVER          \ ( addr value addr )
  DUP 1+        \ ( addr value addr+1 )
  GSIZE 1-      \ ( addr value addr+1 length )
  <CMOVE        \ la copie en partant de la fin
  SWAP          \ ( value addr )
  C!            \ place la valeur dans la première case
;

\ PUSH.COL ( n - ) : pousse la colonne n de la grille (en mettant à jour l'affichage)
: PUSH.COL
  GRID + 2+     \ aller en haut de la colonne (pas de protection)
  DUP           \ ( addr addr )
  DUP C@        \ get cell value
  GSIZE 1- 0 DO
    \ invariant ( addr cell-addr carried-value )
    SWAP
    GSIZE +     \ advance new row ( addr carried-value cell-addr )
    DUP C@ >R
    SWAP OVER C!    \ ( addr cell-addr )
    R>
  LOOP
  \ ( addr cell-addr carried-value )
  SWAP DROP     \ on enlève le pointeur de cellule
  SWAP C!       \ dernière valeur sur case initiale
;

PUSH décide en fonction de nombre passé si c'est une colonne ou une ligne qui doit être poussée.

De 0 à 4, c'est une ligne. De 5 à 9, c'est une colonne.

\ PUSH ( n - ) : pousse un rang ou une colonne de la grille (en fonction du numéro passé)
: PUSH
    DUP
    GSIZE < IF
      PUSH.ROW
    ELSE GSIZE - DUP
      GSIZE < IF PUSH.COL ELSE DROP ENDIF
    ENDIF
    ;

Et en début de jeu, on effectue un mélange aléatoire de la grille. Grace à CHOOSE et PUSH, ce mot est extrêmement simple.

\ SHUFFLE.GRID ( n - ) : effectue n mouvements dans la grille
: SHUFFLE.GRID
    0 DO
      10 CHOOSE PUSH
    LOOP
;

L'interaction avec le clavier. KEY est bloquant et renvoi le code ASCII de la touche appuyée. Avec INPUT, si la touche était A majuscule (essentiellement car je connais la valeur ASCII par cœur), alors on renvoi une valeur spécifique (255), sinon, on tente de transformer le caractère en nombre en base 10. Si c'est faisable, ce nombre est mis sur la pile, sinon, on attend la touche suivante.

\ CPC
: GET.KEY KEY ;

\ INPUT ( - n )
\ Demande une entrée valide du joueur
: INPUT
  BEGIN
    GET.KEY
    DUP 65 = IF 255 1
    ELSE 10 DIGIT ENDIF
  UNTIL
;

Et enfin le mot principale. Tout d'abord l’initialisation du jeu, puis un mélange de la grille par 20 opérations et affichage du terrain de jeu. Enfin, la boucle qui prend une entrée clavier, ajuste pour que le 0 soit considéré comme 10, puis ajuste encore entre 0 et 9 pour appeler PUSH.

Si la touche était A, et donc la valeur retournée 255, alors on arrête tout brutalement par ABORT.

\ Le programme principal
: GAME
  INIT.GAME
  20 SHUFFLE.GRID
  .SCREEN
  BEGIN
    INPUT \ ( n )
    DUP 255 = IF
      ABORT \ Pas besoin de DROP, ABORT reinitialise la pile
    ELSE
      1- DUP 0 < IF DROP 9 ENDIF
      PUSH
      .REDRAW
    THEN
  AGAIN
;

Il n'y a pas de détection de fin de partie. C'est à vous de crier victoire lorsque toutes les lignes sont de la couleur voulue, tout comme dans le jeu d'origine. L'idée étant un portage quasiment à l'identique, je m'arrête là.

À quoi ça ressemble ?

Et voici le jeu, capturé sur l'émulateur AMSpiriT Lite. Le gros carré jaune est le curseur texte, que j'aurais probablement du faire disparaître en le changeant de couleur. Mais au passage, il fait office d'indicateur lorsque l'on tape sur une touche, puisqu'il clignote alors légèrement.

C'était fun à faire. C'est bien ce qui compte.

Capture du jeu en fonction