Avant de commencer

Ce livre vous apprend à programmer. Il part du principe que vous n’avez jamais écrit une ligne de code de votre vie, et il ne suppose pas que vous voulez devenir programmeur — seulement que vous voulez faire un jeu.

Chaque leçon se termine par quelque chose que vous pouvez lancer et avec quoi vous pouvez jouer. Rien n’est gardé pour plus tard : il n’y a pas de chapitres de théorie avant que la première image apparaisse à l’écran. Vous écrirez votre premier programme qui marche en une dizaine de minutes, et il fera cinq lignes.

Singe est un moteur de jeu. Vous pouvez faire avec lui tout ce que vous pouvez faire avec n’importe quel autre moteur, en deux dimensions ou en trois, et l’essentiel de ce livre consiste à faire exactement cela. Ce qui le distingue, c’est qu’il sait aussi lire de la vidéo FMV (« full motion video ») comme monde dans lequel se déroule le jeu ; c’est ainsi que fonctionnaient les jeux laserdisc des salles d’arcade, et presque rien d’autre ne le fait bien. C’est une possibilité, pas une obligation : un jeu ne lit de la vidéo que s’il le demande, et rien de ce que vous écrirez pendant les treize premières leçons ne s’en approchera.

Le langage est Lua, que Singe utilise pour tout. Lua a été choisi par des gens qui devaient l’enseigner à des artistes et à des designers, et ça se voit. Il n’y a pas de points-virgules à oublier, pas de types à déclarer, et pas de compilateur contre lequel se battre. Quand vous faites une erreur, Singe vous dit le fichier, la ligne, et ce qu’il n’a pas compris.

Ce qu’il vous faut

  • Singe. Un seul fichier. Mettez-le dans un dossier, quelque part où vous saurez le retrouver.

  • Un éditeur de texte. Bloc-notes, TextEdit en mode texte brut, Notepad++, VS Code, ou n’importe quoi d’autre qui enregistre du texte brut. Un traitement de texte ne fera pas l’affaire : il enregistre une mise en forme que vous ne voyez pas, et Singe ne sait pas la lire.

  • Rien d’autre. Vous n’avez besoin ni d’un laserdisc, ni d’un fichier vidéo, ni d’un logiciel de dessin, ni d’aucune illustration. Toute la première partie dessine tout elle-même, et à partir de la deuxième partie, les images, les sons, la vidéo et les modèles dont vous avez besoin sont tous fournis avec le livre ou avec le moteur. Ce dont vous avez besoin est listé plus bas.

Comment lire ce livre

Tapez le code. Ne le copiez-collez pas. Le taper est plus lent, et c’est tout l’intérêt : vous ferez de petites erreurs, et c’est en les corrigeant que vous apprendrez à lire ce que l’ordinateur vous dit. Chaque leçon a une section Essayez avec des modifications à faire, et elles comptent autant que la leçon.

Si une leçon tourne mal et que vous ne voyez pas pourquoi, le script terminé de chaque leçon se trouve dans le dossier learn fourni avec ce livre, nommé d’après sa leçon : 01-hello.singe, et ainsi de suite. Ne le lisez qu’après avoir essayé.

Comment vos dossiers sont organisés

La leçon un met cela en place et toutes les leçons suivantes le supposent ; cela vaut donc la peine de le voir une fois dès maintenant.

Vous gardez un dossier de travail, avec votre copie de Singe dedans. Chaque leçon crée un nouveau dossier à l’intérieur, nommé d’après le script qu’il contient.

singe/                 <- votre dossier de travail, avec Singe dedans
    Singe/             <- le moteur y met ses propres fichiers
    data/              <- et tout ce que vos jeux enregistrent
    hello/
        hello.singe
    rocks/
        rocks.singe
        art/

Vous lancez une leçon depuis le dossier de travail en nommant son dossier : Singe rocks lance donc rocks/rocks.singe. Cette forme courte marche parce que le dossier et le script portent le même nom. C’est la même forme qu’a un vrai jeu installé, et c’est pourquoi le livre l’utilise dès la première leçon au lieu de faire le ménage plus tard.

Ce qui est fourni avec ce livre

À partir de la deuxième partie, les leçons utilisent des images et des sons. Ils se trouvent dans le dossier art fourni avec le livre, et vous copiez ce dossier dans le dossier de la leçon sur laquelle vous travaillez, en gardant son nom. Il y a un vaisseau, un rocher, un tir, une étoile, quatre images de quelqu’un qui marche, et deux bruits. art/README.txt les liste avec leurs tailles.

Singe lui-même fournit le reste. La première fois que vous lancez quoi que ce soit, le moteur déballe un dossier appelé Singe dans votre dossier de travail, et on y trouve une vidéo, une police, deux modèles 3D et un clic. Les leçons qui en ont besoin utilisent ceux qui sont déjà sur votre disque ; il n’y a donc rien à chercher et rien à acheter. Rien de tout cela n’est joli. Tout est réel, et pour mettre quelque chose de mieux à la place, il suffit en général de changer un nom de fichier.

Ce n’est pas le livre de Forge

Forge, un outil séparé qui a son propre livre, fait un jeu à partir d’une description au lieu de le programmer. C’est une autre route qui mène ailleurs, pour quelqu’un qui ne veut pas du tout écrire de code. Si vous êtes venu ici pour apprendre à programmer, vous êtes au bon endroit. Vous n’avez besoin ni de Forge ni de son livre, et celui-ci ne s’appuie pas dessus.

La Référence de Singe est la référence : chaque fonction, chaque argument, chaque valeur de retour, et le modèle de programmation qui est derrière. Ce n’est pas un tutoriel et elle n’essaie pas d’en être un. Vous commencerez à vous y reporter vers la leçon six, et à la fin de ce livre vous vous en servirez plus que de ce livre-ci. Elle vient dans le même téléchargement que celui-ci.

La série

Trente et une leçons en quatre parties. Chacune a besoin de la précédente, et de rien d’autre.

Première partie : les idées. Pas d’illustrations, pas de vidéo, rien à installer. Vous dessinez avec les formes et le texte que le moteur a déjà, et vous apprenez de quoi est fait un programme.

  1. Bonjour — un script, une fonction, une chaîne, et quelque chose à l’écran.

  2. Des nombres qui changent — les variables, l’arithmétique, et faire bouger les choses.

  3. Prendre des décisions — if, les comparaisons, et lire les commandes.

  4. Recommencer — for et while, et dessiner cent fois la même chose.

  5. Vos propres fonctions — les arguments, les valeurs de retour, et pourquoi s’en donner la peine.

  6. Des listes de choses — les tables, ipairs, ajouter et retirer.

  7. Un jeu — tout ce qui précède, jouable, en cent vingt lignes environ.

  8. Quand ça tourne mal — lire les erreurs, debugPrint, et recharger avec F5.

Deuxième partie : un vrai jeu. Des illustrations, du son, et la forme que prend un jeu terminé.

  1. Des images — les sprites, le chargement, le dessin et les images d’animation.

  2. Le son — les effets, la musique, et quand charger quoi.

  3. Toucher des choses — les collisions, le kit de jeu, et les boîtes de collision.

  4. Score, vies et fin de partie — l’état, la sauvegarde, et recommencer.

  5. Un dossier de jeu — games.dat, des illustrations pour le menu, et lancer le jeu depuis celui-ci.

Troisième partie : la vidéo. Lire du film comme monde du jeu, et les conventions d’arcade qui ont grandi autour. Sautez cette partie si votre jeu n’a pas besoin de vidéo ; rien de ce qui suit ne dépend d’elle.

  1. Lire de la vidéo — le disque, les images, les sauts, et l’attente.

  2. L’autre façon de l’écrire — le modèle à fil d’exécution (« threaded »), et pourquoi il convient à la vidéo.

  3. Les embranchements — les choix, les chemins, et la forme d’un jeu vidéo à embranchements.

  4. Les pistolets optiques — viser, tirer, et le calibrage dont une borne a besoin.

  5. Les quick-time events — les invites, les fenêtres de temps, et noter la synchronisation du joueur.

Quatrième partie : tout le reste. Chaque leçon tient debout seule ; prenez-les dans l’ordre que vous voulez.

  1. Du texte qui a de l’allure — les polices, la qualité, et les mesures.

  2. Menus et écrans — la GUI, les documents, et la mise en forme.

  3. Les sous-titres — et pourquoi ils ont leur propre système.

  4. Passer à la 3D — les scènes, les caméras, et les coordonnées.

  5. Modèles et lumière — glTF, les matériaux, et l’animation.

  6. La physique — les corps, les forces, les articulations, et quand ne pas s’en servir.

  7. Les particules — les émetteurs, et faire une explosion.

  8. Des personnages qui se déplacent seuls — la navigation et la recherche de chemin.

  9. Musique et MIDI — les pistes, les SoundFonts, et les instruments.

  10. En ligne — les comptes, les tableaux des meilleurs scores, et le catalogue.

  11. Garder des données — les bases de données, les tables, et les questions que vous leur posez.

  12. Le publier — l’empaquetage, les correctifs, les licences, et la sortie.

  13. Dans une borne — les commandes, les menus de service, les bezels, et les choses qui ne comptent que sur du vrai matériel.

Leçon 1 : Bonjour

La leçon terminée

Voilà ce que vous aurez à la fin de cette leçon. Ça ne paie pas de mine. C’est aussi un programme que vous avez écrit, qui tourne sur un vrai moteur de jeu, et tout le reste de ce livre repose sur les cinq lignes qui l’ont produit.

Préparez votre dossier de travail

Créez un dossier pour tout y ranger, appelé singe ou comme il vous plaira, et mettez-y votre copie de Singe. C’est votre dossier de travail, et chaque leçon de ce livre y ajoute un nouveau dossier. Vous le créerez une fois et n’y penserez plus jamais.

Dans le dossier de travail, créez un dossier appelé hello, et dans celui-ci un fichier appelé hello.singe.

singe/                 <- votre dossier de travail, avec Singe dedans
    hello/
        hello.singe

Cette imbrication n’est pas une lubie. Singe considère le dossier depuis lequel vous le lancez comme l’endroit où vivent les jeux, un dossier par jeu, et il y range aussi ses propres fichiers. Votre jeu va dans son propre dossier, un niveau plus bas. À partir de la leçon deux, chaque leçon est un autre dossier à côté de hello.

Deux choses à propos des noms. La partie après le point, .singe, est ce qui indique à Singe qu’il s’agit d’un script. Et sur la plupart des ordinateurs qui ne sont pas sous Windows, les majuscules comptent : Hello.singe et hello.singe sont deux fichiers différents. Prenez dès maintenant l’habitude de taper les noms exactement.

Donner le même nom au dossier et au script compte aussi, et vous allez voir pourquoi dans un instant.

Ouvrez hello.singe dans votre éditeur de texte. Il est vide. C’est bien comme ça.

Tapez ceci

function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    return OVERLAY_UPDATED
end

Enregistrez-le.

Ne vous souciez pas encore de ce que tout cela veut dire. Deux choses méritent d’être remarquées avant de le lancer, parce qu’elles seront vraies de chaque programme que vous écrirez.

La première, c’est que les espaces au début des trois lignes du milieu sont là exprès. Ils ne changent rien du tout au programme — Singe le lancerait exactement pareil sans eux — mais ils vous montrent d’un coup d’œil que ces trois lignes sont à l’intérieur de ce qui commence par function et finit par end. Tous les programmeurs font ça. Faites-le dès le premier jour et vous n’aurez jamais à l’apprendre plus tard.

La seconde, c’est l’ordre des lignes. Elles s’exécutent de haut en bas, l’une après l’autre, comme les étapes d’une recette. C’est la chose la plus importante à savoir sur un programme, et presque tout ce qui embrouille un débutant vient de ce qu’il l’oublie.

Lancez-le

Ouvrez un terminal, allez dans votre dossier de travail — pas dans le dossier hello qu’il contient — et donnez le nom du dossier que vous voulez lancer :

Singe hello

Sous Windows, c’est Singe.exe hello. Si votre copie de Singe se trouve ailleurs, tapez le chemin qui y mène, par exemple ../Singe hello.

Voilà pourquoi le dossier et le script portent le même nom. Quand on lui donne un dossier, Singe y cherche un script qui s’appelle pareil. Nommez-les différemment et vous obtenez Error: Unable to locate the game., c’est-à-dire le moteur qui vous dit qu’il a cherché et n’a rien trouvé qu’il reconnaisse. Vous pouvez toujours être explicite à la place et écrire Singe hello/hello.singe, qui fait la même chose.

Une fenêtre noire s’ouvre avec le mot Hello! près du coin supérieur gauche. Appuyez sur Échap ou Q pour quitter.

Deux choses se seront produites sans que vous les ayez demandées, et elles sont toutes les deux normales. Des dossiers appelés Singe et data sont apparus dans votre dossier de travail, à côté de hello : le premier, c’est le moteur qui extrait les fichiers dont il a besoin, le second, c’est là qu’ira tout ce que vos jeux sauvegardent. Laissez-les tous les deux tranquilles. Et la fenêtre est presque entièrement noire, parce que vous n’avez rien dessiné à part six caractères.

Ce qui vient de se passer

Maintenant, les cinq lignes, une par une.

function onOverlayUpdate()

function commence un groupe d’instructions et lui donne un nom. Tout ce qui se trouve d’ici jusqu’au end correspondant en fait partie. Cette fonction s’appelle onOverlayUpdate, et les parenthèses vides après le nom prendront leur sens à la leçon cinq.

Ce nom, ce n’est pas à vous de le choisir. Singe cherche une fonction qui porte exactement ce nom et l’appelle une soixantaine de fois par seconde, sans fin, pour vous donner l’occasion de dessiner. Si vous l’écrivez onoverlayupdate ou onOverlayUpdated, Singe ne la trouvera pas, votre fenêtre restera noire, et rien ne vous dira que vous vous êtes trompé. C’est la première vraie leçon : l’ordinateur fait ce que vous avez écrit, pas ce que vous vouliez dire.

Une fonction que vous écrivez et que le moteur appelle est un callback (une fonction de rappel). Vous ne l’appelez pas vous-même, et vous ne pouvez pas dire quand elle s’exécute ; vous l’écrivez, et Singe vous rappelle quand il y a quelque chose à faire. Chaque nom de ce livre qui commence par on est un callback, et il y en a un pour presque tout ce qui peut arriver : un bouton enfoncé, une touche tapée, un son qui se termine, le disque qui atteint une image. onOverlayUpdate est celui du dessin, et c’est le seul endroit où dessiner est permis.

    overlayClear()

C’est aussi une fonction, mais pas une que vous devez écrire : Singe la fournit, avec plusieurs centaines d’autres, et vous êtes en train de l’appeler. Appeler une fonction, c’est dire son nom suivi de parenthèses. Celle-ci efface l’écran.

Elle vient en premier parce que dessiner ne remplace pas ce qui était là avant, ça dessine par-dessus. Effacer, puis dessiner, à chaque fois.

    overlayPrint(2, 2, "Hello!")

Un autre appel, et celui-ci a besoin qu’on lui dise trois choses, qui vont entre les parenthèses, séparées par des virgules. Les choses que vous passez ainsi à une fonction s’appellent des arguments.

Les deux premières sont des nombres : à quelle distance vers la droite et à quelle distance vers le bas. La troisième est le texte à afficher, et il est entre guillemets doubles parce que c’est ainsi qu’on indique à l’ordinateur que Hello! est un morceau de texte et non le nom de quelque chose. Un texte entre guillemets s’appelle une chaîne (de caractères), et vous vous servirez de chaînes sans arrêt.

Tôt ou tard, vous voudrez mettre un guillemet double à l’intérieur d’une chaîne, et la manière évidente ne marche pas : le deuxième guillemet termine la chaîne trop tôt, et vous obtenez la même erreur unfinished string que celle que vous rencontrerez à la fin de cette leçon. Il y a deux façons de la contourner, et elles valent toutes les deux d’être connues.

    overlayPrint(2, 2, "She said \"hello\" to me.")
    overlayPrint(2, 4, 'She said "hello" to me.')

La première met une barre oblique inverse devant chaque guillemet qui fait partie du texte. La barre oblique inverse dit « le caractère suivant fait partie de la chaîne, ce n’est pas sa fin », et la paire s’appelle une séquence d’échappement. La seconde utilise des guillemets simples pour marquer les bouts de la chaîne, ce qui laisse les guillemets doubles libres d’être du texte ordinaire. Lua accepte les deux sortes de guillemets, du moment que la chaîne finit par la même sorte que celle par laquelle elle a commencé.

Ces deux lignes affichent exactement la même chose. Utilisez celle qui se lit le plus facilement, et c’est en général celle aux guillemets simples quand le texte est plein de guillemets doubles.

Les deux nombres ne sont pas des pixels. overlayPrint est le texte simple propre au moteur, et il compte en cellules de caractère : (0, 0) est le coin tout en haut à gauche, (1, 0) est une lettre plus à droite, et (0, 1) une ligne plus bas. Donc (2, 2), c’est deux lettres vers la droite et deux lignes vers le bas. D’autres manières de dessiner du texte comptent bien en pixels, et vous les rencontrerez à la leçon dix-neuf.

    return OVERLAY_UPDATED

return renvoie une réponse à celui qui a appelé la fonction. Singe pose une seule question à votre onOverlayUpdate chaque fois qu’il l’appelle : avez-vous changé quelque chose ? OVERLAY_UPDATED veut dire oui, il faut donc l’afficher.

OVERLAY_UPDATED n’a pas de guillemets autour parce que ce n’est pas du texte. C’est un nom que Singe a déjà donné à une valeur, pour que vous puissiez écrire quelque chose que vous savez lire au lieu d’un nombre qu’il vous faudrait retenir.

end

La fin qui va avec le function. Chaque function en a exactement une, et l’oublier est l’erreur la plus courante qui soit.

Essayez

Changez une chose à la fois, enregistrez, et relancez. Cette boucle — changer, lancer, regarder — c’est tout le métier.

  1. Déplacez le texte. Changez overlayPrint(2, 2, "Hello!") en overlayPrint(10, 5, "Hello!"). Puis essayez (0, 0). Puis essayez (200, 2), et trouvez pourquoi il a disparu.

  2. Dites autre chose. Mettez votre propre nom entre les guillemets.

  3. Dites deux choses. Ajoutez une deuxième ligne overlayPrint sous la première, avec un autre numéro de ligne et un autre texte. Rien ne vous empêche d’en avoir autant que vous voulez.

  4. Retirez l’effacement. Supprimez la ligne overlayClear() et lancez. Rien ne change, parce que rien ne bouge encore sur votre écran. Remettez-la quand même. À la leçon deux, elle comptera énormément, et c’est le bon moment pour voir que certaines erreurs attendent avant de mordre.

Cassez-le exprès

Les débutants passent plus de temps à lire des messages d’erreur que des livres de programmation, alors débarrassons-nous du premier tout de suite.

Supprimez le guillemet fermant après Hello!, pour que la ligne devienne overlayPrint(2, 2, "Hello!), et lancez. Singe refuse de démarrer et dit :

Error running script:  hello/hello.singe:3: unfinished string near '"Hello!)'

Lisez-le à partir de la gauche. hello/hello.singe, c’est le fichier : le dossier, puis le script qu’il contient. 3, c’est la ligne. Le reste, c’est ce qui n’a pas marché, ici un morceau de texte qui a été ouvert et jamais fermé. Allez à la ligne trois, remettez le guillemet, et ça tourne.

Presque toutes les erreurs que vous verrez ont cette forme : un fichier, une ligne et une plainte. La plainte est parfois écrite pour quelqu’un qui connaît déjà Lua, mais le fichier et la ligne sont toujours justes, et neuf fois sur dix la ligne suffit.

Arrêtez de le relancer

Vous avez maintenant démarré Singe à la main cinq ou six fois. Arrêtez. Lancez-le plutôt comme ceci :

Singe -R hello

-R dit à Singe de surveiller votre script. Enregistrez une modification dans votre éditeur, et le jeu redémarre de lui-même un instant plus tard avec votre modification, sans fermer la fenêtre. Si vous enregistrez une erreur, l’erreur est affichée et la fenêtre reste vide jusqu’à ce que vous enregistriez une correction.

Utilisez -R pour tout le reste de ce livre.

Ce que vous avez appris

  • Un programme est un fichier d’instructions qui s’exécutent dans l’ordre, de haut en bas.

  • Une function regroupe des instructions sous un nom et s’arrête à son end.

  • onOverlayUpdate est un nom que Singe cherche et appelle de nombreuses fois par seconde, et c’est là que va tout votre dessin.

  • Appeler une fonction, c’est écrire son nom et des parenthèses. Tout ce qui est entre les parenthèses est un argument.

  • Une fonction que le moteur appelle pour vous, plutôt qu’une que vous appelez vous-même, est un callback. onOverlayUpdate en est un.

  • Un texte entre guillemets doubles est une chaîne.

  • Effacez l’écran avant de dessiner dessus.

  • Une erreur vous donne le fichier et la ligne. Commencez par là.

La prochaine fois

Votre Hello! reste là où vous l’avez mis et ne bouge jamais. Pour le faire bouger, il vous faut un endroit où garder un nombre qui change — une variable — et c’est tout le sujet de la leçon deux.

Leçon 2 : Des nombres qui changent

La leçon terminée

À la leçon un, vous avez mis un mot à l’écran et il est resté là. À la fin de cette leçon, le même mot glissera dans toute la fenêtre, fera demi-tour quand il atteindra un bord, et il le fera grâce à quatre nombres que le programme change soixante fois par seconde.

En chemin, vous rencontrerez l’idée qui fait trébucher plus de débutants que toute autre : l’endroit où vous mettez une chose décide de combien de temps elle vit.

Créez un nouveau dossier

Créez un dossier appelé numbers à côté de votre dossier hello, et dans celui-ci un fichier appelé numbers.singe. Tapez-y le programme de la leçon un, ou copiez hello.singe et renommez-le — les deux conviennent, et le retaper n’est pas du temps perdu.

function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R numbers et laissez-le tourner. Grâce au -R de la fin de la leçon un, vous n’aurez plus à le relancer de toute cette leçon ; enregistrez le fichier et la fenêtre se met à jour toute seule.

Comptez les images

La leçon un disait que Singe appelle onOverlayUpdate une soixantaine de fois par seconde. C’est facile à dire et difficile à croire, alors comptez-les.

function onOverlayUpdate()
    frames = 0
    frames = frames + 1
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Enregistrez-le. Dans le coin supérieur gauche, vous obtenez frame 1, et il reste à frame 1 pour toujours.

C’est décevant, et c’est aussi ce qu’il y a de plus utile dans cette leçon, alors ne le corrigez pas encore. Regardez ce que vous avez écrit et pensez à l’ordre des lignes, dont la leçon un disait que c’était la chose la plus importante à savoir sur un programme.

Singe appelle onOverlayUpdate. La première ligne met frames à zéro. La deuxième y ajoute un, ce qui fait un. Vous l’affichez, vous renvoyez la réponse, et la fonction est terminée. Puis Singe l’appelle de nouveau, et la première chose qui se passe, c’est que frames est remis à zéro.

Vous ne comptez pas les images. Vous comptez jusqu’à un, soixante fois par seconde.

Sortez la ligne

Retirez la ligne frames = 0 de la fonction et mettez-la au-dessus, toute seule, avant le mot function.

frames = 0


function onOverlayUpdate()
    frames = frames + 1
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Enregistrez-le. Le nombre grimpe, vite, et ne s’arrête pas.

Rien d’autre n’a changé. La seule différence, c’est où se trouve la ligne, et toute l’idée est là. Les lignes à l’intérieur d’une fonction s’exécutent chaque fois que la fonction est appelée, sans exception. Les lignes en dehors de toute fonction s’exécutent une seule fois, quand Singe lit votre fichier, avant que le jeu commence.

frames = 0 devait s’exécuter une fois. Il s’exécutait soixante fois par seconde, et il effaçait le travail de la ligne du dessous.

Tout ce qui bouge dans ce que vous écrirez aura cette forme. Préparez le nombre dehors, changez-le dedans.

Ce qui vient de se passer

Il y a là trois nouveaux morceaux de code. Les voici, chacun à part.

frames = 0

Ceci invente un nom, frames, et met le nombre zéro derrière. Un nom avec une valeur derrière est une variable, et elle s’appelle ainsi parce que la valeur a le droit de varier — de changer pendant que le programme tourne.

Le = n’est pas le signe égal de l’école. Il ne dit pas que frames est égal à zéro ; il dit mettez zéro dans frames, et il marche toujours dans ce sens-là, de droite à gauche. Les programmeurs appellent ça une affectation, et ça vaut la peine de dire la ligne à voix haute de cette façon en l’écrivant : « frames reçoit zéro ».

C’est vous qui choisissez le nom. Ce peut être presque n’importe quoi qui commence par une lettre et ne contient pas d’espace, et il devrait dire ce qu’est la chose. frames est un bon nom. f en est un mauvais, et vous ne vous en remercierez pas dans une semaine.

    frames = frames + 1

C’est la ligne qui fait s’arrêter les gens, les yeux écarquillés, parce qu’en tant qu’énoncé d’arithmétique, elle n’a aucun sens : rien n’est égal à lui-même plus un.

Ce n’est pas un énoncé d’arithmétique. Souvenez-vous que = met le côté droit dans le nom de gauche, et lisez-la dans cet ordre, la droite d’abord. Calculez frames + 1 avec ce qu’il y a dans frames en ce moment. Puis remettez la réponse dans frames. Si frames contenait six, le côté droit donne sept, et sept va dans frames.

Ajouter un à une variable de cette façon, vous l’écrirez des milliers de fois.

Le + fait ce que vous attendez, et les trois autres aussi : - soustrait, * multiplie et / divise. Il n’y a pas de touche x pour la multiplication, c’est pour ça que l’étoile fait ce travail.

    overlayPrint(0, 0, "frame " .. frames)

overlayPrint veut du texte, et frames est un nombre, pas du texte. Les deux points collent les deux ensemble et transmettent le résultat comme une seule chaîne : les cinq caractères frame, un espace, puis autant de chiffres qu’il en faut au nombre.

Ces deux points sont l’opérateur de jonction, et son vrai nom vaut la peine d’être connu, parce que les messages d’erreur l’emploient : joindre des chaînes s’appelle la concaténation.

Remarquez l’espace entre les guillemets, avant celui qui ferme. Sans lui, vous obtenez frame6. Lua joint exactement ce que vous lui donnez et n’ajoute rien de lui-même.

Lua transforme un nombre en texte pour vous quand vous le joignez à une chaîne de cette façon, c’est pourquoi vous n’avez rien eu à faire de spécial. Il ne le fait pas pour tout. Si un jour vous essayez de joindre quelque chose qui n’est ni du texte ni un nombre, Lua s’arrête sur une erreur, et le moyen de la contourner, c’est tostring, qui transforme absolument n’importe quoi en texte :

    overlayPrint(0, 0, "frame " .. tostring(frames))

Cette ligne fait exactement la même chose que celle d’avant. Vous n’avez pas besoin de tostring pour les nombres. Vous en aurez besoin à la leçon trois.

Faites-le bouger

Vous avez maintenant tout ce qu’il faut pour déplacer le mot. Le mot est dessiné là où vous le dites, vous avez un moyen de garder un nombre d’une image à l’autre, et vous avez un moyen de le changer.

Donnez à la colonne sa propre variable en dehors de la fonction, et ajoutez-y quelque chose à l’intérieur.

frames = 0
wordX  = 0


function onOverlayUpdate()
    frames = frames + 1
    wordX = wordX + 1
    overlayClear()
    overlayPrint(wordX, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Enregistrez-le. Le mot file par le côté droit et ne revient jamais.

Il avançait d’une colonne à chaque image, soixante fois par seconde, il a donc traversé toute la fenêtre en une seconde environ. Ralentissez-le en ajoutant moins d’une colonne entière :

    wordX = wordX + 0.25

Maintenant, il lui faut quatre images pour avancer d’une colonne, et le mot se traîne. wordX est la plupart du temps un nombre comme 12.75, qui n’est pas du tout une colonne, et Singe s’en arrange en jetant tout ce qui suit le point quand il dessine : 12.75 se dessine dans la colonne douze. Garder la fraction dans la variable, c’est justement ce qui vous permet d’aller moins vite qu’une colonne par image. Le nombre est plus fin que l’écran.

Où est le bord ?

Le mot s’en va toujours. Pour lui faire faire demi-tour, il faut savoir où est le bord droit, et vous pourriez le trouver en comptant : un jeu sans vidéo reçoit par défaut un monde de 720 sur 480, l’overlay sur lequel vous dessinez en fait la moitié, 360 sur 240, et les lettres de la police de console intégrée font six pixels de large, il y a donc soixante colonnes.

Ne faites pas ça. Demandez au moteur.

lastColumn = overlayGetWidth() // CELL_WIDTH - string.len(word)

overlayGetWidth et overlayGetHeight sont deux autres fonctions que Singe fournit, comme overlayPrint. Elles ne prennent rien et renvoient un nombre : la largeur et la hauteur de la surface de dessin. Vous avez vu return renvoyer une valeur à la leçon un, et ceci en est l’autre bout — une fonction que vous appelez peut vous donner quelque chose, et ici vous faites de l’arithmétique avec ce qu’elle vous a donné.

Les nombres qu’elles vous donnent sont en pixels, et overlayPrint compte en cellules de caractère, il faut donc diviser. overlayGetFontWidth vous dit combien de pixels fait une cellule en largeur, et overlayGetFontHeight en hauteur, si bien que vous n’avez jamais à connaître la réponse vous-même. Les deux barres obliques veulent dire divisez et jetez la fraction, parce qu’un tiers de cellule de caractère n’est pas un endroit où l’on peut afficher quelque chose. La barre oblique simple vous donnerait une fraction, et une fraction de cellule n’est pas un endroit non plus.

string.len compte les caractères d’une chaîne, et il est là pour que le mot fasse demi-tour quand sa dernière lettre atteint le bord, et non sa première. Essayez sans, et vous verrez six caractères glisser dans le néant.

Les majuscules de CELL_WIDTH, qui contient ce que vous donne overlayGetFontWidth, sont une habitude plutôt qu’une règle. Lua s’en moque, mais un nom en majuscules, c’est la façon dont les programmeurs disent « ceci est un nombre que je règle une fois en haut et auquel je ne touche plus jamais », et ça vaut mieux qu’un 6 tout nu au milieu d’un fichier, que personne ne saura expliquer un mois plus tard.

Faites-lui faire demi-tour

Aller dans l’autre sens ne demande aucun effort : au lieu d’ajouter 0.25 à chaque image, ajoutez -0.25. Gardez donc la quantité dans une variable à elle et inversez son signe quand le mot arrive à un bord.

    if wordX > lastColumn then
        wordX = lastColumn
        speedX = -speedX
    end

C’est une décision, et les décisions sont tout le sujet de la leçon trois, alors croyez-moi sur parole pendant une leçon. Lisez-la à voix haute : si wordX a dépassé lastColumn, alors exécutez les deux lignes indentées ; sinon, sautez-les. Le end la ferme, de la même façon que end ferme une fonction.

La première ligne cale le mot exactement sur le bord, pour qu’un mot rapide ne puisse pas filer au-delà. La seconde est l’inversion. -speedX, c’est moins ce que contient speedX, donc s’il contenait 0.25, il contient maintenant -0.25, et ajouter -0.25 à chaque image ramène le mot par où il est venu. Quand il atteint le bord gauche, le if correspondant l’inverse de nouveau, et il repasse à 0.25.

Deux de plus pour les bords du haut et du bas, et le mot rebondit dans toute la fenêtre.

Le tout

CELL_WIDTH  = overlayGetFontWidth()
CELL_HEIGHT = overlayGetFontHeight()
TOP_ROW     = 2

word   = "Hello!"
wordX  = 0
wordY  = TOP_ROW
speedX = 0.25
speedY = 0.125
frames = 0

lastColumn = overlayGetWidth() // CELL_WIDTH - string.len(word)
lastRow    = overlayGetHeight() // CELL_HEIGHT - 1


function onOverlayUpdate()
    frames = frames + 1
    wordX = wordX + speedX
    wordY = wordY + speedY

    if wordX < 0 then
        wordX = 0
        speedX = -speedX
    end

    if wordX > lastColumn then
        wordX = lastColumn
        speedX = -speedX
    end

    if wordY < TOP_ROW then
        wordY = TOP_ROW
        speedY = -speedY
    end

    if wordY > lastRow then
        wordY = lastRow
        speedY = -speedY
    end

    overlayClear()
    overlayPrint(0, 0, "frame " .. frames)
    overlayPrint(wordX, wordY, word)
    return OVERLAY_UPDATED
end

TOP_ROW tient le mot à l’écart des deux lignes du haut, pour qu’il ne gribouille jamais par-dessus le compteur d’images. lastRow contient un - 1 plutôt qu’un string.len, parce qu’un mot fait plusieurs caractères de large mais toujours une seule ligne de haut.

Remarquez que toute la moitié haute du fichier s’exécute une fois et que toute la moitié basse s’exécute soixante fois par seconde, et que vous pouvez distinguer l’une de l’autre en regardant l’indentation. C’est à ça que servaient les espaces.

Essayez

  1. Changez les vitesses. Essayez speedX = 1 et speedY = 1. Puis essayez 0.05 pour les deux. Puis rendez l’une beaucoup plus grande que l’autre.

  2. Changez le mot. Mettez un mot beaucoup plus long entre les guillemets — assez long pour remplir un tiers de la fenêtre — et regardez le rebond à droite se faire toujours au bon endroit. C’est string.len qui fait son travail.

  3. Retirez l’effacement. Supprimez la ligne overlayClear(). La leçon un promettait que ça compterait un jour, et ce jour est arrivé : le mot laisse une traînée à travers la fenêtre et n’en efface jamais rien, parce que dessiner a toujours dessiné par-dessus ce qui était là. Remettez-la.

  4. Empêchez-le d’aller de côté. Mettez speedX = 0 et lancez. Trouvez pourquoi le mot ne quitte plus jamais la colonne zéro, et pourquoi le if du bord gauche ne se déclenche jamais.

  5. Cassez le compteur d’images exprès. Remettez la ligne frames = 0 dans la fonction, au-dessus de frames = frames + 1. Regardez le compteur rester bloqué à un pendant que le mot continue de bouger parfaitement. Puis trouvez pourquoi le mot n’est pas touché.

Cassez-le exprès

Remplacez les deux points de la ligne du compteur d’images par un signe plus, pour qu’elle devienne :

    overlayPrint(0, 0, "frame " + frames)

Enregistrez-le. La fenêtre se ferme, Singe s’arrête, et le terminal affiche :

Error executing function 'onOverlayUpdate':  numbers/numbers.singe:42: attempt to add a 'string' with a 'number'

suivi de plusieurs lignes commençant par stack traceback:, que vous pouvez ignorer pour l’instant.

Lisez-le comme la leçon un vous l’a appris : le fichier, la ligne, puis la plainte. La ligne 42 est celle que vous avez changée. La plainte dit qu’on a demandé à Lua de faire une addition entre une chaîne et un nombre, et l’addition, c’est pour les nombres. + et .. se ressemblent sur la page et font des travaux complètement différents : le plus, c’est de l’arithmétique, .., c’est de la colle.

Celle-ci vaut la peine d’être rencontrée à cause de l’endroit où elle est apparue. L’erreur de la leçon un arrêtait Singe avant même que votre jeu démarre, parce que Lua ne pouvait pas du tout lire le fichier. Celle-ci est une ligne parfaitement lisible qui ne tourne mal que lorsqu’elle s’exécute, donc la fenêtre s’est ouverte, le jeu a tourné, et il est mort à la première image. Les deux sortes vous donnent le fichier et la ligne. Commencez par là dans les deux cas.

Ce que vous avez appris

  • Une variable est un nom avec une valeur derrière, et la valeur peut changer.

  • = veut dire « mettez le côté droit dans le nom de gauche », pas « est égal à ».

  • frames = frames + 1 calcule d’abord le côté droit, puis le range.

  • +, -, * et / font l’arithmétique que vous attendez ; // divise et jette la fraction.

  • .. colle du texte ensemble, et transforme un nombre en texte au passage.

  • Une ligne à l’intérieur de onOverlayUpdate s’exécute à chaque image. Une ligne en dehors de toute fonction s’exécute une fois, avant que le jeu commence.

  • Tout ce qui doit se souvenir de quelque chose d’une image à l’autre doit vivre dehors.

  • overlayGetWidth et overlayGetHeight vous donnent la taille de la surface de dessin, si bien que vous n’avez jamais à la deviner.

  • overlayClear compte dès que quelque chose bouge.

La prochaine fois

Le mot bouge, mais il bouge tout seul, et rien de ce que vous faites n’y change quoi que ce soit. À la leçon trois, vous reprenez les quatre blocs if que vous avez utilisés sur parole, vous apprenez ce qu’ils disent vraiment, et vous les branchez sur les touches fléchées au lieu des bords de l’écran. La boîte que vous pilotez dans la fenêtre à la fin de cette leçon est le joueur du jeu que vous construirez à la leçon sept.

Leçon 3 : Prendre des décisions

La leçon terminée

Tout ce que vous avez écrit jusqu’ici fait la même chose à chaque image. Le mot de la leçon deux bougeait, que vous le vouliez ou non, et la seule raison pour laquelle il faisait demi-tour, c’étaient quatre blocs de code qu’on vous avait demandé de croire sur parole.

Cette leçon, ce sont ces quatre blocs, expliqués pour de bon. À la fin, votre programme posera des questions, agira selon les réponses, et — parce que la question la plus intéressante qu’un jeu puisse poser est « que fait le joueur ? » — vous piloterez une boîte dans la fenêtre avec les touches fléchées. Gardez cette boîte. C’est le joueur du jeu que vous construirez à la leçon sept.

Créez un nouveau dossier

Un dossier appelé decisions, dedans un fichier appelé decisions.singe, et Singe -R decisions qui tourne dans un terminal. Comme la dernière fois.

Ce que dit vraiment un if

Voici le bloc de la leçon deux, tout seul.

if wordX > lastColumn then
    wordX = lastColumn
end

Quatre parties. Le mot if. Une question. Le mot then. Et un corps de lignes qui ne s’exécutent que lorsque la réponse à la question est oui, fermé par end.

La question est wordX > lastColumn, et c’est le > qui fait le vrai travail. Il compare les deux nombres de part et d’autre et produit une réponse qui est soit vrai, soit faux. Ces deux mots ne sont ni du texte ni des nombres ; ce sont des valeurs à part entière, appelées booléens, et un booléen est la seule chose qui intéresse un if.

L’indentation, c’est la même idée qu’à la leçon un : les lignes à l’intérieur sont indentées pour que vous voyiez d’un coup d’œil ce qui appartient au if, et le end s’aligne sur le if qui l’a ouvert. Lua l’exécuterait sans les espaces. Vous, vous ne pourriez pas le lire.

Il y a six de ces comparaisons, et vous les utiliserez toutes.

a < b

a est plus petit que b

a > b

a est plus grand que b

a ⇐ b

a est plus petit que b ou égal à b

a >= b

a est plus grand que b ou égal à b

a == b

a est la même chose que b

a ~= b

a n’est pas la même chose que b

Ce sont les deux dernières qui demandent de la prudence, pour des raisons différentes.

~= veut dire « n’est pas égal à ». La plupart des langages l’écrivent !=, et si vous avez déjà vu un programme, vos doigts taperont != et Lua le refusera. Le tortillon se trouve sur votre clavier à côté du 1 ou sous le #, selon l’endroit où vous vivez.

==, ce sont deux signes égal, et ce n’est pas une faute de frappe pour un seul. C’est l’une des erreurs les plus courantes en programmation, et elle mérite qu’on s’y arrête un instant.

À la leçon deux, vous avez appris qu’un seul signe égal veut dire mettez le côté droit dans le nom de gauche. C’est une chose que vous faites. Ça change quelque chose.

Deux signes égal veulent dire ces deux-là sont-ils les mêmes ? C’est une question que vous posez. Ça ne change rien, et ça renvoie vrai ou faux.

lives = 3
if lives == 3 then

La première ligne met lives à trois. La seconde demande s’il vaut trois. Des travaux différents, des symboles différents, à un caractère près. Lua vous attrapera si vous les confondez, et vous rencontrerez l’erreur qu’il emploie à la fin de cette leçon.

Quand la réponse est non

Un if tout seul ne fait rien du tout quand la réponse est fausse. Très souvent, vous voulez que l’autre chose se produise à la place, et c’est else.

if lives > 0 then
    message = "Ready"
else
    message = "Game Over"
end

Exactement un de ces deux corps s’exécute, jamais les deux, jamais aucun, donc message finit toujours par contenir l’une des deux chaînes, et jamais rien.

Quand il y a plus de deux possibilités, elseif les enchaîne.

if score >= 10000 then
    rank = "ace"
elseif score >= 5000 then
    rank = "pilot"
elseif score >= 1000 then
    rank = "rookie"
else
    rank = "passenger"
end

Lua essaie les questions en partant du haut et s’arrête à la première qui est vraie. Un score de 6000 n’est pas plus grand que 10000, donc il essaie la suivante, qui est vraie, donc rank devient pilot et les deux autres questions ne sont jamais posées. Ce dernier point compte : le elseif pour 1000 est vrai aussi pour un score de 6000, et il n’est jamais atteint, c’est pourquoi l’ordre va du plus grand au plus petit.

Toute la chaîne n’a besoin que d’un seul end, quel que soit le nombre de parties elseif qu’elle contient. C’est une seule décision, pas quatre.

Vrai, faux et rien du tout

Pas besoin de comparer deux choses pour obtenir un booléen. Vous pouvez en garder un.

paused = false

C’est une variable comme une autre, et la valeur qu’elle contient est le booléen false lui-même, écrit sans guillemets parce que ce n’est pas le mot « false », c’est l’idée. Il en va de même pour true. Une variable qui contient l’un des deux peut aller directement dans un if, sans aucune comparaison :

if paused then

Lisez-le « si paused ». Ça se lit mieux que if paused == true, qui fait la même chose par le chemin le plus long, et les programmeurs expérimentés vous regarderont bizarrement si vous l’écrivez.

Trois mots combinent et inversent ces réponses.

if alive and not shielded then
if coins > 0 or freePlay then

and est vrai quand les deux côtés le sont. or est vrai quand l’un des côtés l’est, ou les deux. not change vrai en faux et faux en vrai. Ils se lisent comme de l’anglais et, chose rare en programmation, ils veulent dire ce qu’ils veulent dire en anglais.

Il reste une valeur à connaître, et c’est celle qui produit les erreurs les plus déroutantes de votre première année.

overlayPrint(0, 0, "lives " .. tostring(lives))

Si vous n’avez jamais rien mis dans lives, ça affiche lives nil. Lua ne se plaint pas d’un nom qu’il n’a jamais vu ; il vous donne nil, qui est son mot pour rien ici. Ce n’est pas zéro et ce n’est pas une chaîne vide. Zéro est un nombre que vous avez voulu ranger. nil, c’est l’absence de valeur.

Vous avez déjà rencontré nil deux fois sans qu’on vous le dise. frames = frames + 1 sans la ligne frames = 0 au-dessus échoue parce que vous avez demandé à Lua d’ajouter un à rien. Et un callback mal orthographié est nil lui aussi, c’est pourquoi un onOverlayUpdate mal écrit vous donne une fenêtre noire et aucune erreur : Singe cherche le nom, n’y trouve rien, et poursuit tranquillement sa journée.

tostring est dans cette ligne parce que .. ne joint un booléen ou un nil à rien du tout. Les nombres, il les convertit pour vous ; ceux-là, non. C’était la promesse de la fin de la leçon deux, et maintenant vous en avez l’usage.

Enfin, la règle qui relie toute cette partie, parce que if accepte tout ce que vous lui donnez, pas seulement vrai et faux :

Tout est vrai en Lua, sauf false et nil.

Zéro est vrai. Une chaîne vide est vraie. Seuls ces deux-là ne le sont pas, et une fois que vous le savez, if movingLeft then se lit parfaitement, que movingLeft contienne true, false, ou n’ait jamais été rempli du tout.

Lire les commandes

Il est temps de demander quelque chose au joueur. Il faut pour ça un nouveau callback.

function onInputPressed(what)
    if what == SWITCH_RIGHT then
        boxX = boxX + 10
    end
end

onInputPressed est le deuxième callback que vous écrivez, et il marche exactement comme la leçon un l’a décrit : vous l’écrivez, Singe l’appelle. onOverlayUpdate est appelé à intervalles réguliers. Celui-ci est appelé quand quelque chose se passe — quand le joueur appuie sur n’importe quoi que le moteur reconnaît.

La différence avec onOverlayUpdate, c’est le mot entre les parenthèses. Singe doit vous dire quelle commande a été enfoncée, alors il passe une valeur à la fonction, et what est le nom sous lequel vous avez choisi de la recevoir. La leçon un appelait arguments les choses que vous passez à une fonction ; vu de l’intérieur, le nom qui en attrape un est un paramètre. Le nom est à vous : appelez-le what, appelez-le button, appelez-le k. Singe le remplit dans tous les cas.

SWITCH_RIGHT est un nom que le moteur a déjà donné à une valeur, comme OVERLAY_UPDATED à la leçon un. Vous n’avez rien à charger pour vous en servir ; Singe les définit tous avant que votre script s’exécute. Il y en a un pour tout ce qu’a une borne : SWITCH_LEFT, SWITCH_RIGHT, SWITCH_UP, SWITCH_DOWN, de SWITCH_BUTTON1 à SWITCH_BUTTON4, SWITCH_START1, SWITCH_COIN1, et d’autres encore. Le tableau Constantes du moteur de la référence couvre toute la famille, qui va de SWITCH_UP à SWITCH_RECORD. Ils ne s’appellent pas « la flèche droite », et c’est voulu, parce que le même SWITCH_RIGHT arrive, que le joueur ait poussé une touche fléchée, un joystick ou le stick d’une manette. Vous écrivez le jeu une fois et il marche sur les trois.

Ajoutez ce callback, donnez à boxX une valeur de départ en dehors des fonctions, et dessinez quelque chose à boxX. Appuyez sur la flèche droite. La boîte saute de dix pixels à chaque appui.

C’est arrivé, et c’est en train d’arriver

Gardez la touche fléchée enfoncée. Il ne se passe rien de plus.

onInputPressed est appelé une fois, quand la touche descend, et pas une seconde fois avant que vous l’ayez lâchée et enfoncée de nouveau. Il n’y a pas de répétition automatique. C’est exactement ce qu’il faut pour certaines choses — tirer, insérer une pièce, choisir un élément de menu — et exactement ce qu’il ne faut pas pour marcher, qui doit continuer tant que la touche est tenue.

Ce sont deux questions vraiment différentes. C’est arrivé, c’est un événement, et vous l’apprenez une fois. C’est en train d’arriver, c’est un état, et ça dure. Singe vous informe des événements, et la façon de transformer des événements en état, c’est de vous en souvenir vous-même.

Deux callbacks, une variable entre eux.

movingRight = false


function onInputPressed(what)
    if what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_RIGHT then
        movingRight = false
    end
end

onInputReleased est le troisième callback, et c’est le miroir du deuxième : Singe l’appelle quand la touche remonte, avec la même valeur SWITCH_. À eux deux, ils font que movingRight dit la vérité sur ce que fait le doigt du joueur à cet instant.

Rien n’a encore bougé, et c’est voulu. Appuyer et bouger sont maintenant deux travaux séparés. Le mouvement va là où va tout le travail de chaque image.

function onOverlayUpdate()
    if movingRight then
        boxX = boxX + BOX_SPEED
    end
    ...

La boîte glisse maintenant en douceur tant que la touche est enfoncée, à une vitesse que vous choisissez, et l’arithmétique est revenue dans la fonction qui s’exécute soixante fois par seconde, là où est sa place. Cette forme — les événements lèvent des drapeaux, l’image agit selon les drapeaux — est la façon dont presque tous les jeux gèrent leurs commandes, et vous vous en servirez de nouveau dans chaque leçon où il y a un joueur.

Dessiner une boîte

overlayBox prend deux coins : la gauche et le haut du rectangle, puis la droite et le bas.

colorForeground(255, 220, 0)
overlayBox(boxX, boxY, boxX + BOX_SIZE, boxY + BOX_SIZE)

Elle dessine un contour, quatre traits d’un pixel d’épaisseur, et non un rectangle plein. Il n’y a aucun rectangle plein parmi les appels de dessin de l’overlay. Quand vous voudrez un bloc plein plus tard, il y a des façons d’en obtenir un, et la leçon neuf présente la façon habituelle.

Ses nombres sont des pixels, pas des cellules de caractère. Ça piège du monde, parce que overlayPrint, à la leçon deux, comptait en cellules de six pixels sur treize, et tout le reste de Singe compte en pixels. C’est overlayPrint l’exception ; les autres appels de dessin — overlayBox, overlayLine, overlayCircle, overlayEllipse et overlayPlot — travaillent tous dans les mêmes pixels que ceux qu’indique overlayGetWidth.

colorForeground règle la couleur, avec trois nombres de 0 à 255 : combien de rouge, combien de vert, combien de bleu. Les trois à 255, c’est du blanc, tous à 0, c’est du noir, et (255, 220, 0) est un jaune chaud. Remarquez que ce n’est pas un argument passé à overlayBox. C’est un réglage : vous le changez, et tout ce que vous dessinez ensuite sort dans la nouvelle couleur jusqu’à ce que vous le changiez de nouveau. overlayPrint fait encore exception — la police de console arrive avec ses propres couleurs intégrées et ne vous écoute pas.

Le tout

BOX_SIZE  = 20
BOX_SPEED = 2

width  = overlayGetWidth()
height = overlayGetHeight()
maxX   = width - BOX_SIZE - 1
maxY   = height - BOX_SIZE - 1

boxX = width // 2
boxY = height // 2

movingLeft  = false
movingRight = false
movingUp    = false
movingDown  = false


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    elseif what == SWITCH_UP then
        movingUp = true
    elseif what == SWITCH_DOWN then
        movingDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    elseif what == SWITCH_UP then
        movingUp = false
    elseif what == SWITCH_DOWN then
        movingDown = false
    end
end


function onOverlayUpdate()
    if movingLeft and not movingRight then
        boxX = boxX - BOX_SPEED
    elseif movingRight and not movingLeft then
        boxX = boxX + BOX_SPEED
    end

    if movingUp and not movingDown then
        boxY = boxY - BOX_SPEED
    elseif movingDown and not movingUp then
        boxY = boxY + BOX_SPEED
    end

    if boxX < 0 then
        boxX = 0
    elseif boxX > maxX then
        boxX = maxX
    end

    if boxY < 0 then
        boxY = 0
    elseif boxY > maxY then
        boxY = maxY
    end

    overlayClear()

    if movingLeft or movingRight or movingUp or movingDown then
        colorForeground(255, 220, 0)
    else
        colorForeground(80, 160, 255)
    end

    overlayBox(boxX, boxY, boxX + BOX_SIZE, boxY + BOX_SIZE)
    overlayPrint(0, 0, "x " .. boxX .. "  y " .. boxY)
    return OVERLAY_UPDATED
end

Quatre choses là-dedans méritent un second regard.

movingLeft and not movingRight est là parce qu’un joueur peut tenir les deux flèches à la fois. Sans le not, les deux se battraient et la boîte tremblerait ou dériverait ; avec, tenir les deux veut dire qu’aucune ne gagne et que la boîte reste immobile, ce qu’un joueur attend.

maxX est calculé une fois en haut, avec overlayGetWidth comme à la leçon deux, et le - 1 est là parce que le dernier pixel de la surface vaut un de moins que sa largeur. Enlevez le - 1 et le bord droit de la boîte tombe hors de la surface et disparaît, parce que Singe jette sans se plaindre tout ce que vous dessinez en dehors de l’overlay.

Les blocs de limitation utilisent elseif plutôt que deux blocs if séparés. La boîte ne peut pas dépasser le bord gauche et le bord droit en même temps, donc poser la deuxième question quand la première était vraie, c’est du travail perdu.

Et la décision de couleur est un if dont le seul travail est de choisir une valeur. Jaune quand le joueur fait quelque chose, bleu quand il ne fait rien, ce qui est un moyen gratuit de voir que votre gestion des commandes marche vraiment.

Essayez

  1. Changez la vitesse. BOX_SPEED = 1 et BOX_SPEED = 8. À huit, regardez ce que fait la limitation quand vous poussez la boîte dans un coin.

  2. Affichez vos drapeaux. Ajoutez une ligne à onOverlayUpdate : overlayPrint(0, 1, "left " .. tostring(movingLeft)). Tenez puis relâchez la flèche gauche et regardez-le basculer. Puis enlevez le tostring et lisez l’erreur que Lua vous donne.

  3. Accélérez quand un bouton est enfoncé. Ajoutez un drapeau running piloté par SWITCH_BUTTON1 dans les deux callbacks d’entrée, et utilisez un if dans onOverlayUpdate pour avancer de deux fois BOX_SPEED tant qu’il est vrai.

  4. Marquez le milieu. Dessinez une deuxième boîte, petite, au centre de la fenêtre, qui change de couleur quand la boîte du joueur la chevauche. Il vous faudra and pour combiner quatre comparaisons, et c’est plus difficile qu’il n’y paraît. Se tromper un peu est normal ; la leçon onze le fait correctement.

  5. Retirez les relâchements. Supprimez toute la fonction onInputReleased et lancez. La boîte fait un pas et ne s’arrête plus jamais. Trouvez quelle ligne n’est maintenant jamais atteinte.

Cassez-le exprès

Trouvez le bloc de limitation et remplacez le < de sa première comparaison par un seul signe égal, pour qu’elle devienne :

    if boxX = 0 then

Enregistrez-le. La fenêtre reste vide et le terminal affiche :

Error running script:  decisions/decisions.singe:57: 'then' expected near '='

C’est l’erreur contre laquelle tout le passage sur == vous mettait en garde, et le message est un bon exemple d’erreur parfaitement exacte et parfaitement inutile si vous la prenez au pied de la lettre. Lua ne vous demande pas d’ajouter le mot then. Lua est allé jusqu’à if boxX, attendait ensuite une comparaison ou un then, et a trouvé =, qui ne peut être ni l’un ni l’autre.

Chaque fois que vous voyez 'then' expected après un if, cherchez un = simple qui devrait être double. C’est presque toujours ça.

Remarquez où celle-ci est apparue : le jeu n’a jamais démarré, comme pour la chaîne non terminée de la leçon un, parce que Lua ne pouvait pas lire le fichier. L’erreur du compteur d’images de la leçon deux s’est produite pendant l’exécution. Les erreurs dans la forme de votre code vous arrêtent avant que le jeu démarre. Les erreurs dans ce que fait votre code attendent qu’il tourne.

Ce que vous avez appris

  • if question then …​ end n’exécute un corps que quand la réponse est vraie.

  • else donne l’autre cas, et elseif en enchaîne d’autres ; la première question vraie gagne et les autres ne sont jamais posées.

  • Les comparaisons sont <, >, ⇐, >=, == et ~=.

  • = met une valeur dans un nom. == demande si deux choses sont les mêmes.

  • true et false sont des valeurs, et vous pouvez les garder dans des variables.

  • and, or et not combinent et inversent ces réponses.

  • nil est ce que vous obtenez d’un nom que vous n’avez jamais rempli, et ce n’est pas zéro.

  • Tout est vrai, sauf false et nil.

  • onInputPressed et onInputReleased sont des callbacks que Singe appelle avec une valeur SWITCH_ quand le joueur appuie sur une commande ou la relâche.

  • Un appui est un événement et n’arrive qu’une fois ; gardez l’état dans une variable et agissez selon lui à chaque image.

  • overlayBox dessine un contour en pixels, et colorForeground est un réglage, pas un argument.

La prochaine fois

Une boîte, c’est facile. Cent étoiles, non, du moins pas de la façon dont vous avez écrit les choses jusqu’ici, parce que taper cent lignes overlayPlot n’est pour personne l’idée d’une bonne soirée. La leçon quatre, c’est la boucle : dire à l’ordinateur de faire la même chose de nombreuses fois, avec quelque chose de différent à chaque tour, et c’est ce qui rend possible un écran rempli de n’importe quoi.

Leçon 4 : Recommencer

La leçon terminée

Vous avez dessiné un mot et une boîte. Un jeu a besoin de cent choses : des étoiles, des briques, des balles, les lignes d’un menu. Taper cent lignes n’est pas la réponse, et si ça l’était, il vous faudrait en taper cent autres le jour où vous en voudriez cent une.

Cette leçon est la réponse. À la fin, un champ d’étoiles descendra lentement dans votre fenêtre, chacune dessinée par les cinq mêmes lignes de code.

Créez un nouveau dossier

Un dossier appelé repeating, dedans un fichier appelé repeating.singe, et Singe -R repeating qui tourne dans un terminal.

Quarante points

Tapez ceci et lancez-le.

function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 255, 255)

    for star = 1, 40 do
        overlayPlot(star * 8, 100)
    end

    return OVERLAY_UPDATED
end

Une rangée de quarante points blancs en travers du milieu de la fenêtre.

overlayPlot est l’appel de dessin le plus simple qui soit : il met un pixel à la couleur de premier plan actuelle, et c’est exactement ce qu’il faut à une étoile. Tout ce qui est intéressant ici, ce sont les trois lignes autour.

    for star = 1, 40 do

Ça dit : faites ce qui suit quarante fois, et à chaque tour, star contient un nombre différent — un la première fois, deux la deuxième, quarante la dernière. Les deux bouts sont compris, donc 1, 40 fait vraiment quarante tours et pas trente-neuf. Cette forme est une boucle, et celle-ci en particulier est une boucle for numérique.

star est un nom que vous inventez, comme vous avez inventé frames à la leçon deux, et la boucle le remplit pour vous. Vous ne le réglez pas, et vous ne devriez pas le changer dans la boucle. Il n’existe qu’entre le for et son end ; demandez-le après et vous obtenez nil.

Le do est obligatoire et facile à oublier. Omettez-le et Lua dit 'do' expected near, suivi de ce qu’il a trouvé à la place, qui sera la première chose de la ligne suivante.

        overlayPlot(star * 8, 100)

Le corps. C’est ce qui s’exécute quarante fois, et c’est la même ligne à chaque fois — ce qui change, c’est star, donc le premier point tombe à un x de 8, le deuxième à 16, et le dernier à 320. Une boucle n’est utile que si le corps fait quelque chose avec le numéro de la boucle, et la première chose que vous chercherez à faire à chaque fois, c’est de l’arithmétique avec.

Le corps est indenté d’un cran de plus que le for, pour la même raison que tout ce qui a été indenté jusqu’ici.

    end

Ferme la boucle. Vous avez maintenant rencontré trois choses qui ont besoin d’un end : function, if et for. Elles marchent toutes de la même façon, elles s’emboîtent les unes dans les autres, et c’est grâce à l’indentation que vous savez à quoi appartient chaque end.

Compter de plus d’un à la fois

La boucle compte de un en un, sauf si vous lui dites autre chose. Ajoutez un troisième nombre et elle avance de ce nombre-là à la place.

    for x = 0, overlayGetWidth() - 1, 10 do
        overlayPlot(x, 100)
    end

Lisez-le de, à, par pas de. Celle-ci fait 0, 10, 20, et ainsi de suite, et s’arrête au dernier pixel de la surface ou avant, ce qui dessine une ligne pointillée tout du long, quelle que soit la taille de la fenêtre. C’est la même rangée de points qu’avant, décrite par l’endroit où ils vont plutôt que par leur nombre.

Le pas peut être négatif, ce qui compte à rebours.

    for countdown = 10, 1, -1 do

Dix, neuf, huit, jusqu’à un. Avec un pas négatif, le deuxième nombre est le plancher plutôt que le plafond, ce qui est bien ce que vous attendez, et se tromper de signe donne une boucle qui ne s’exécute jamais : for i = 10, 1 do sans pas compte en montant de dix vers un, a déjà dépassé la fin avant de commencer, et ne fait rien. Pas d’erreur, rien à l’écran. Si une de vos boucles semble ne jamais s’exécuter, vérifiez d’abord le sens.

Le pas peut aussi être une fraction, même si vous en aurez besoin moins souvent que vous ne le pensez.

Une boucle dans une autre

Le corps d’une boucle est du code ordinaire, et du code ordinaire peut contenir une boucle.

    for row = 0, overlayGetHeight() - 1, 20 do
        for column = 0, overlayGetWidth() - 1, 20 do
            overlayPlot(column, row)
        end
    end

Ça dessine une grille de points sur toute la fenêtre. Mettez-la dans votre onOverlayUpdate à la place de la rangée et regardez-la, parce que la façon dont elle s’exécute vaut la peine d’être bien comprise maintenant plutôt qu’à la leçon onze, quand quelque chose en dépendra.

La boucle extérieure s’exécute une fois avec row à 0. À l’intérieur, toute la boucle intérieure s’exécute du début à la fin — dix-huit colonnes, dix-huit points, une rangée de la grille. Ce n’est qu’une fois la boucle intérieure terminée que la boucle extérieure passe à row à 20 et exécute de nouveau toute la boucle intérieure.

Le corps de la boucle intérieure s’exécute donc dix-huit fois douze fois, soit deux cent seize fois, pour douze tours de la boucle extérieure. C’est cette multiplication qui fait des boucles imbriquées le moyen de remplir un rectangle de n’importe quoi, et c’est aussi pourquoi vous devriez jeter un œil aux nombres avant d’en imbriquer trois.

Remarquez que la position de chaque point a besoin des deux variables de boucle : column pour le sens horizontal et row pour le sens vertical. C’est ça, le modèle. Si le corps intérieur n’utilise que la variable intérieure, la boucle intérieure dessine la même chose encore et encore au même endroit, et vous avez écrit une façon lente de le faire une seule fois.

Quand vous ne savez pas combien

Une boucle for a besoin de savoir combien de fois avant de commencer. Parfois vous ne le savez pas, et il vous faut alors l’autre sorte.

    x = 0
    while x < overlayGetWidth() do
        overlayPlot(x, 100)
        x = x + 10
    end

Une boucle while vérifie une question avant chaque tour, exactement le genre de question que poserait un if, et continue tant que la réponse est vraie. Quand la réponse est fausse, elle s’arrête et le programme reprend à la ligne après le end. Si la réponse est fausse dès la toute première fois, le corps ne s’exécute jamais.

Cet exemple dessine la même ligne pointillée que le for avec un pas de dix, et il lui faut trois lignes pour faire ce que for faisait en une, alors utilisez for pour ça. Voici la différence qui tranche :

  • Utilisez for quand le nombre de tours est connu avant de commencer. Quarante étoiles. Un pixel sur dix en largeur. Chaque rangée d’une grille.

  • Utilisez while quand vous attendez que quelque chose devienne vrai et ne pouvez pas dire à l’avance combien de temps ça prendra. Distribuer des cartes jusqu’à ce que le paquet soit vide. Redemander jusqu’à ce que le joueur tape quelque chose de valable. Parcourir une liste jusqu’à trouver ce que vous cherchiez.

Un while a trois parties, et vous devez écrire les trois vous-même : préparer la variable avant la boucle, la tester dans le while, et la changer dans le corps. La boucle for fait les trois pour vous, c’est pourquoi c’est elle qu’il faut prendre quand elle convient. Oubliez la troisième partie d’un while et la question ne cesse jamais d’être vraie, ce que vous ferez exprès à la fin de cette leçon.

Une étoile faite de son propre numéro

Maintenant, le champ d’étoiles, et un problème qui façonne le reste de la première partie.

Chaque étoile a besoin de son propre x et de son propre y, et vous n’avez aucun moyen de garder cent variables séparées — écrire star1X, star2X et ainsi de suite jusqu’à cent est pire que de taper les cent lignes que vous vouliez éviter. Alors ne les rangez pas. Calculez chacune à partir de la seule chose qui distingue une étoile de ses voisines : son numéro.

        starX = (star * 37) % width

Le % est le dernier des opérateurs arithmétiques, et c’est le reste : ce qui reste après une division. Quinze divisé par quatre fait trois, et il reste trois, donc 15 % 4 vaut 3. Sa propriété utile, c’est que la réponse ne peut jamais être aussi grande que le nombre de droite, donc un reste par width est toujours une position quelque part sur l’écran, quelle que soit la taille du côté gauche.

L’étoile 1 va à 37, l’étoile 5 à 185, l’étoile 10 à 10 — 370 a fait le tour au-delà de 360 et est revenu par la gauche. Trente-sept est choisi parce qu’il n’a aucun facteur commun avec 360, et c’est ce qui empêche les étoiles de tomber en bandes bien nettes ; essayez 36 à la place et vous verrez le problème tout de suite.

La dérive vers le bas, c’est le même truc avec un nombre qui grandit avec le temps.

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    ...
        starY = (star * 61 + math.floor(drift * layer * 0.5)) % height

drift vit en dehors de la fonction et grimpe à chaque image, exactement comme frames à la leçon deux. L’ajouter au y de chaque étoile fait descendre tout le champ d’un bloc, et le % ramène en haut une étoile qui tombe par le bas, pour toujours, gratuitement.

math.floor jette la fraction d’un nombre et renvoie la partie entière en dessous : math.floor(7.9) vaut 7. La leçon deux faisait remarquer que Singe le fait pour vous quand il dessine, et c’est vrai, mais le faire vous-même veut dire que le nombre avec lequel vous travaillez est le nombre qui apparaît à l’écran. Ça comptera à la leçon sept, quand deux choses devront être d’accord pour savoir si elles se touchent.

Remarquez que layer, là-dedans, est une deuxième variable de boucle. Les étoiles sont dessinées par une boucle dans une boucle, et l’extérieure n’est pas une rangée de grille mais une distance : trois couches d’étoiles, chacune dérivant à sa propre vitesse et avec sa propre luminosité, et c’est ce qui donne de la profondeur à un champ de points tout plat.

Le hasard

Les étoiles scintillent. Scintiller, c’est avoir une luminosité un peu différente à chaque image, et « un peu différente », c’est math.random.

        shade = math.random(60, 90) + layer * 55
        colorForeground(shade, shade, shade)

math.random(60, 90) renvoie un nombre entier de 60 à 90, les deux compris, choisi de nouveau à chaque appel. Appelez-la sans aucun argument et vous obtenez à la place une fraction entre 0 et 1, et c’est la forme à utiliser quand vous voulez que quelque chose arrive une fois sur cinq. Vous n’avez pas à préparer le générateur ; Lua s’en charge quand Singe démarre.

Ajouter layer * 55 sort les couches proches de la plage sombre, si bien que les étoiles lointaines restent pâles et que les proches sont presque blanches. Autant de rouge, de vert et de bleu, comme la leçon trois l’a expliqué, donne un gris.

Comme shade est tiré de nouveau à chaque image pour chaque étoile, chaque étoile clignote de son côté, ce qui, à soixante images par seconde, passe pour un scintillement plutôt que pour un défaut.

Le tout

LAYERS          = 3
STARS_PER_LAYER = 40
ACROSS_STEP     = 37
DOWN_STEP       = 61
LAYER_SHIFT     = 13
LAYER_SPEED     = 0.5
LAYER_BRIGHT    = 55

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()

    for layer = 1, LAYERS do
        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            colorForeground(shade, shade, shade)
            overlayPlot(starX, starY)
        end
    end

    return OVERLAY_UPDATED
end

Cent vingt étoiles, dessinées par cinq lignes, et le fichier est plus court que celui de la leçon trois.

C’est aussi le bout de ce que cette approche peut faire, et ça vaut la peine d’être honnête sur la raison pendant que vous l’avez sous les yeux. Chaque étoile, là-dedans, est une formule. Rien d’une étoile n’est mémorisé : vous ne pouvez pas en rendre une plus brillante que sa voisine et qu’elle le reste, vous ne pouvez pas en faire tomber une du ciel, et vous ne pouvez pas laisser le joueur en ramasser une, parce qu’il n’y a nulle part où noter qu’il lui est arrivé quelque chose. L’étoile dix-sept n’est pas une chose. C’est un nombre qui passe brièvement par une variable appelée star.

Dès que vous voulez cent choses qui se souviennent chacune de quelque chose qui leur est propre, il vous faut un endroit où ranger cent ensembles de faits. C’est la leçon six, et le champ d’étoiles est la raison pour laquelle elle existe.

Essayez

  1. Plus et moins. Essayez STARS_PER_LAYER = 200, puis 4. Puis LAYERS = 8, et regardez ce que layer * LAYER_BRIGHT fait à shade quand le numéro de couche devient grand. Les nombres que prend colorForeground s’arrêtent à 255.

  2. Changez l’espacement. Mettez ACROSS_STEP à 36 et lancez. Les étoiles se rangent en bandes, parce que 36 tient exactement dix fois dans 360. Remettez-le à 37 et essayez 71 et 90.

  3. Arrêtez le scintillement. Remplacez la ligne math.random par un simple shade = layer * 70 et comparez. Décidez ce que vous préférez ; il n’y a pas de bonne réponse, et remarquer que vous avez une préférence fait partie du métier.

  4. Faites-les tomber vers le haut. Un seul caractère.

  5. Dessinez aussi la grille. Remettez la boucle de grille imbriquée de tout à l’heure, après les étoiles, dans une couleur sombre. Deux boucles imbriquées dans une seule fonction, qui dessinent deux choses différentes, et la seconde ne dérange pas la première.

Cassez-le exprès

Jusqu’ici, chaque erreur était un message. Celle-ci n’en est pas un, et c’est justement pour ça que vous devriez la rencontrer pendant que vous vous y attendez.

Mettez ceci dans votre onOverlayUpdate, juste sous overlayClear(), lancez-le, et lisez le paragraphe suivant avant de faire quoi que ce soit d’autre.

    x = 0
    while x < width do
        overlayPlot(x, 100)
    end

La ligne qui fait avancer x manque, donc x reste à zéro, donc x < width ne cesse jamais d’être vrai. La boucle tourne pour toujours, en dessinant le même pixel, et elle est dans onOverlayUpdate, donc onOverlayUpdate ne se termine jamais. Singe attend votre fonction. Il ne peut pas dessiner, il ne peut pas lire le clavier, et il ne peut pas quitter.

Ce que vous voyez, c’est une fenêtre qui ne bouge plus. Échap ne fait rien. Q ne fait rien. Rien n’est écrit non plus.

Allez dans le terminal où vous avez lancé Singe et appuyez sur Ctrl et C en même temps. Singe arrête votre boucle et vous dit où elle en était :

Stopped:  the script did not return, and Singe was asked to quit.
stack traceback:
	repeating/repeating.singe:20: in function 'onOverlayUpdate'

Il peut le dire deux fois, à quelques secondes d’intervalle, avant de quitter. Une fois suffit largement. La ligne 20 est le end de votre while, c’est là que la boucle tournait quand vous l’avez arrêtée. Retirez la boucle, enregistrez, et relancez Singe.

C’est un rapport, pas une erreur. Rien ne s’est plaint avant que vous le demandiez, parce que rien ne s’est mal passé, du point de vue de l’ordinateur. Vous avez demandé une boucle qui tourne tant que x est plus petit que la largeur, et c’est précisément ce que vous avez obtenu. C’est la seule sorte d’erreur pour laquelle les messages d’erreur ne peuvent rien pour vous, et le remède est une habitude : chaque fois que vous écrivez un while, écrivez la ligne qui change la variable avant d’écrire quoi que ce soit d’autre dans le corps.

Ce que vous avez appris

  • for name = first, last do …​ end exécute son corps une fois pour chaque nombre du premier au dernier, les deux compris.

  • Un troisième nombre est le pas, et il peut être négatif pour compter à rebours.

  • La variable de boucle n’existe qu’à l’intérieur de la boucle, et le corps devrait s’en servir.

  • for a besoin d’un do, et chaque boucle a besoin d’un end.

  • Une boucle dans une boucle exécute toute la boucle intérieure à chaque tour de l’extérieure, et c’est comme ça qu’on remplit un rectangle.

  • while question do …​ end recommence tant que la question est vraie, et c’est à vous de changer quelque chose dans le corps.

  • Utilisez for quand vous savez combien de fois, et while quand vous attendez que quelque chose devienne vrai.

  • % est le reste, et il garde un nombre qui grandit à l’intérieur d’une plage.

  • math.random(a, b) donne un nombre entier de a à b ; math.floor jette la fraction.

  • Une boucle qui ne finit jamais fige tout le jeu sans message d’erreur, et Ctrl et C dans le terminal, c’est comme ça qu’on en sort.

La prochaine fois

Regardez encore ce onOverlayUpdate. Il dessine des étoiles, il calcule des positions, il choisit des couleurs, et il commence à être une fonction qui fait quatre travaux au lieu d’un. À la leçon cinq, vous écrivez vos propres fonctions, vous leur donnez des arguments comme les fonctions de Singe en prennent, et vous en obtenez des réponses — et le champ d’étoiles devient une seule ligne qui dit drawStars().

Leçon 5 : Vos propres fonctions

La leçon terminée

La leçon quatre s’est terminée sur un avertissement à propos de votre propre programme : onOverlayUpdate calcule où vont cent vingt étoiles, décide de la luminosité de chacune, les dessine et compte la dérive, et c’est une seule fonction qui fait quatre travaux. On est sur le point de lui en demander un cinquième, parce qu’un champ d’étoiles sans rien devant n’est pas un jeu.

Dans cette leçon, vous le démontez. Vous allez écrire vos propres fonctions — des fonctions dont Singe n’a jamais entendu parler et qu’il n’appellera jamais — et leur confier le travail. À la fin, tout le champ d’étoiles tient en une ligne qui dit drawStars(), un vaisseau est revenu en bas de l’écran, et le programme est plus facile à lire que lorsqu’il en faisait moins.

Créez un nouveau dossier

Un dossier appelé functions, dedans un fichier appelé functions.singe, et Singe -R functions qui tourne dans un terminal.

Copiez-y le programme terminé de la leçon quatre. Le voici, inchangé, et ça vaut la peine de le lancer une fois avant de toucher à quoi que ce soit :

LAYERS          = 3
STARS_PER_LAYER = 40
ACROSS_STEP     = 37
DOWN_STEP       = 61
LAYER_SHIFT     = 13
LAYER_SPEED     = 0.5
LAYER_BRIGHT    = 55

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()

    for layer = 1, LAYERS do
        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            colorForeground(shade, shade, shade)
            overlayPlot(starX, starY)
        end
    end

    return OVERLAY_UPDATED
end

Trois couches d’étoiles qui descendent dans la fenêtre à trois vitesses. Rien dans la première moitié de cette leçon ne change ce que vous voyez. Tout ce qu’elle contient change la façon dont le programme se lit.

Un travail, un nom

Commencez par les deux lignes qui mettent une étoile à l’écran. Au-dessus de onOverlayUpdate, ajoutez ceci :

function drawStar(x, y, shade)
    colorForeground(shade, shade, shade)
    overlayPlot(x, y)
end

Puis, dans la boucle intérieure, supprimez ces deux lignes et appelez-la à la place :

        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            drawStar(starX, starY, shade)
        end

Enregistrez. Rien ne change à l’écran.

Vous avez déjà écrit des fonctions — onOverlayUpdate en est une, et onInputPressed et onInputReleased de la leçon trois aussi — mais ce sont des callbacks. Vous les écrivez et Singe les appelle. drawStar est différente. Singe n’en a jamais entendu parler. Elle s’exécute parce que vous avez écrit son nom et des parenthèses, de la même façon que vous appelez overlayPlot, et rien au monde ne l’exécutera si vous ne le faites pas.

Tout le truc est là. Désormais, quand vous vous surprenez à penser « et maintenant, dessiner une étoile », vous pouvez écrire « dessiner une étoile », et c’est bien ce que ça voudra dire.

Un paramètre est un nom, pas une chose

Regardez de nouveau la première ligne de drawStar.

function drawStar(x, y, shade)

Les trois noms entre les parenthèses sont des paramètres. Un paramètre est un nom que la fonction utilise pour ce que l’appelant lui a passé, quoi que ce soit. Quand vous écrivez drawStar(starX, starY, shade), Lua met dans x ce qu’il y a dans starX, dans y ce qu’il y a dans starY, dans shade ce qu’il y a dans shade, puis exécute la fonction.

Les noms n’ont rien à voir entre eux. Le nombre de l’appelant s’appelle starX là-bas et x ici, et ça marcherait exactement pareil si vous l’appeliez across ou banana. À l’intérieur de la fonction, seuls les noms entre les parenthèses existent, et ils contiennent des copies de ce qui est entré.

C’est ici que les parenthèses vides de la leçon un prennent enfin leur sens.

function onOverlayUpdate()

Rien entre les parenthèses veut dire aucun paramètre : le moteur n’a rien à dire à cette fonction, donc il n’y a rien à nommer. Comparez avec le callback que vous avez écrit à la leçon trois.

function onInputPressed(what)

Un paramètre, appelé what. Le moteur a quelque chose à dire à celui-ci — quelle commande a été enfoncée — donc il y a un nom pour l’attraper. Vous vous servez d’un paramètre depuis la leçon trois.

Un paramètre est vraiment la copie personnelle de la fonction, et ça vaut la peine de vous le prouver une fois. Tapez ceci, appelez-la depuis onOverlayUpdate, et retirez-la ensuite :

function half(number)
    number = number // 2
    return number
end

Appelez-la sous la forme half(drift). La fonction divise son number par deux et renvoie la réponse, et drift, là-bas dans onOverlayUpdate, continue de compter comme si de rien n’était. Une fonction ne peut pas aller changer les variables de l’appelant à travers un paramètre. Elle reçoit une copie, et ce qu’elle fait de la copie ne regarde qu’elle.

Renvoyer une réponse

half a fait quelque chose que les fonctions que vous avez écrites jusqu’ici ne faisaient pas : elle a donné une réponse. C’est la dernière ligne.

    return number

return renvoie une valeur à celui qui a appelé la fonction, et l’appel se transforme en cette valeur. Écrivez smaller = half(drift) et Lua exécute half, prend ce que half a renvoyé et le met dans smaller. Vous avez rencontré return à la leçon un, où onOverlayUpdate renvoie OVERLAY_UPDATED pour répondre à la question de Singe : est-ce que quelque chose a changé ? C’est le même mot qui fait le même travail, sauf que maintenant, c’est vous qui posez la question.

La ligne de la luminosité ne demande qu’à devenir une fonction qui donne une réponse. Ajoutez celle-ci :

function shadeFor(layer)
    return math.random(60, 90) + layer * LAYER_BRIGHT
end

Tout le corps est un return, ce qui est normal pour une petite fonction. Maintenant, la boucle intérieure peut passer la réponse directement à drawStar, sans nom entre les deux :

            drawStar(starX, starY, shadeFor(layer))

Un appel dans un appel. Lua calcule d’abord celui de l’intérieur, reçoit un nombre de shadeFor, et passe ce nombre à drawStar comme troisième argument. Vous avez déjà écrit quelque chose de ce genre sans le remarquer : le math.floor(drift * layer * LAYER_SPEED) de la leçon quatre est un appel dont la réponse est utilisée sur place, au milieu d’un calcul plus grand.

Deux réponses à la fois

Les deux lignes de position sont plus difficiles, parce que ce sont deux nombres calculés ensemble et qu’il faudrait en choisir un à renvoyer. Dans la plupart des langages, une fonction peut renvoyer une valeur, et en obtenir deux est une corvée. Lua vous laisse en renvoyer autant que vous voulez.

function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end

Vous attrapez les réponses en mettant deux noms à gauche, séparés par une virgule :

            local x, y = starAt(star, layer)

La première valeur dans le premier nom, la deuxième dans le deuxième. Si vous demandez moins de noms que la fonction ne renvoie de valeurs, les valeurs en trop sont jetées : local x = starAt(star, layer) vous donne le nombre horizontal et perd le vertical, sans se plaindre. Si vous demandez plus de noms qu’il n’y a de valeurs, les noms en trop valent nil.

Ignorez le mot local dans ces deux blocs encore une minute. Il aura bientôt sa propre partie, et c’est la plus importante.

Le champ d’étoiles en une ligne

La boucle intérieure tient maintenant en trois lignes courtes, qui parlent toutes d’une couche d’étoiles. C’est un travail qui a un nom.

function drawLayer(layer)
    for star = 1, STARS_PER_LAYER do
        local x, y = starAt(star, layer)
        drawStar(x, y, shadeFor(layer))
    end
end

Et la boucle extérieure est elle aussi un travail qui a un nom :

function drawStars()
    for layer = 1, LAYERS do
        drawLayer(layer)
    end
end

Des fonctions qui appellent des fonctions qui appellent des fonctions, sur trois niveaux, et chacune fait trois ou quatre lignes que vous pouvez garder en tête d’un seul coup. onOverlayUpdate peut maintenant dire ce qu'est une image :

function onOverlayUpdate()
    drift = drift + 1
    overlayClear()
    drawStars()
    return OVERLAY_UPDATED
end

Voilà la promesse faite à la fin de la leçon quatre, tenue.

Remettez le vaisseau

Maintenant, le cinquième travail, celui qui aurait mis le désordre dans l’ancien onOverlayUpdate. Ramenez la boîte que vous pilotiez à la leçon trois, cette fois sous la forme d’un vaisseau posé près du bas de l’écran, qui ne bouge que vers la gauche et la droite.

Il lui faut quelques valeurs à lui, en haut avec les autres, et les deux callbacks d’entrée de la leçon trois, sans les branches pour le haut et le bas :

PLAYER_WIDTH  = 20
PLAYER_HEIGHT = 6
PLAYER_SPEED  = 3
PLAYER_MARGIN = 6

playerX     = width // 2
playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
movingLeft  = false
movingRight = false
function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end

Le dessiner prend deux lignes, donc c’est une fonction :

function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end

C’est en le déplaçant que la leçon porte ses fruits. À la leçon trois, garder la boîte à l’écran prenait quatre lignes de if et de elseif pour chaque direction. Cette idée — tenir un nombre entre un plancher et un plafond — a un nom, et ce nom, c’est clamp :

function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end

Trois sorties, et une seule au plus se produit, parce que return ne fait pas que renvoyer une réponse : il arrête net la fonction. Rien de ce qui suit ne s’exécute. Si la valeur est sous le plancher, renvoyez le plancher et arrêtez. Si elle dépasse le plafond, renvoyez le plafond et arrêtez. Sinon, renvoyez ce qui est entré.

function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end

Une fonction qui se termine sans return ne renvoie rien, c’est-à-dire nil. C’est ce qu’il faut pour drawPlayer et movePlayer, qu’on appelle pour faire quelque chose plutôt que pour répondre à quelque chose. C’est un bug dans une fonction comme clamp : oubliez ce dernier return value et chaque position au milieu de la plage revient sous la forme nil.

Où vivent les noms

Chaque nom que vous avez créé depuis la leçon deux était un nom global. Un nom global appartient à tout le programme : drift, playerX et LAYERS peuvent être lus et écrits par n’importe quelle fonction du fichier, à tout moment, et ils restent là tant que le jeu tourne.

Ça a l’air pratique, et pour six noms, ça l’est. Les ennuis commencent à soixante. Chaque nom global est un nom que tout le programme s’est engagé à réserver, donc quand une autre fonction veut un endroit où garder une position horizontale et l’appelle starX elle aussi, les deux sont la même boîte, et chacune écrit par-dessus le nombre de l’autre. Quand un nom global contient quelque chose de faux, n’importe quoi dans le fichier a pu l’y mettre, et trouver quoi veut dire tout relire.

Un nom local est le remède. Mettez le mot local devant un nom la première fois que vous l’utilisez, et le nom n’existe qu’à l’intérieur de la function, de la boucle ou du if où il a été écrit.

function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end

Ici, x et y ne regardent personne d’autre. Une autre fonction peut avoir son propre x, et les deux ne se rencontrent jamais. Quand le x de starAt est faux, les trois lignes ci-dessus sont les trois seules qui ont pu le provoquer. Sans le mot local, ces deux lignes créeraient discrètement deux noms globaux de plus, et c’est exactement ce que starX et starY étaient depuis le début.

Maintenant, la partie qui surprend tout le monde. Tapez cette fonction, et mettez dans onOverlayUpdate une ligne qui vous montre ce qu’elle renvoie :

function countUp()
    local counted = 0
    counted = counted + 1
    return counted
end
    overlayPrint(0, 0, "Count: " .. countUp())

Count: 1, et ça reste Count: 1 tant que le jeu tourne, alors que la fonction est appelée soixante fois par seconde et ajoute un à chaque fois. Un nom local est créé tout neuf quand la fonction commence et disparaît quand elle se termine, donc counted naît à 0, devient 1 et meurt, soixante fois par seconde, pour toujours. Un nom local ne se souvient pas. Retirez les deux une fois que vous avez regardé.

Ce n’est pas un défaut, c’est le but : un nom local ne peut pas être empoisonné par l’appel précédent, parce qu’il ne reste rien de l’appel précédent. Quand vous avez vraiment besoin de vous souvenir de quelque chose d’un appel à l’autre — drift et playerX doivent se souvenir — le nom doit vivre en dehors de toute fonction. Mettez-le en haut du fichier, avec local devant :

local drift   = 0
local playerX = width // 2

Un local écrit en haut du fichier, en dehors de toutes les fonctions, vit aussi longtemps que le script et peut être vu par toutes les fonctions en dessous. Ce dernier mot compte : en dessous. Un nom local existe à partir de sa propre ligne et vers le bas, donc une fonction écrite au-dessus de la ligne qui le crée ne peut pas le voir. C’est vrai aussi des fonctions elles-mêmes, une fois que vous les marquez local, et c’est pourquoi le script terminé est dans cet ordre : les valeurs d’abord, puis vos propres fonctions, puis les callbacks, en dernier.

Parcourez maintenant tout le fichier et mettez local devant chaque nom que vous avez créé — les constantes en majuscules, width et height, drift, les quatre valeurs du joueur et chacune de vos propres fonctions. Trois noms n’y ont pas droit : onInputPressed, onInputReleased et onOverlayUpdate doivent rester globaux, parce que Singe les trouve par leur nom et qu’un nom local est invisible depuis l’extérieur du fichier.

Soyons honnêtes sur ce que les noms locaux ne règlent pas. Si vous faites une faute de frappe dans un nom auquel vous affectez une valeur — movinLeft = true au lieu de movingLeft = true — Lua ne se plaint pas. Il crée un tout nouveau nom global avec votre faute de frappe pour nom, le remplit, et laisse le vrai tranquille. Rien ne bouge, aucune erreur, et vous fixez l’écran pendant dix minutes. Les noms locaux ne vous sauveront pas de celle-là. Relire le nom deux fois, si.

Le tout

Voici le programme terminé, avec chaque morceau de la leçon dedans.

local LAYERS          = 3
local STARS_PER_LAYER = 40
local ACROSS_STEP     = 37
local DOWN_STEP       = 61
local LAYER_SHIFT     = 13
local LAYER_SPEED     = 0.5
local LAYER_BRIGHT    = 55

local PLAYER_WIDTH  = 20
local PLAYER_HEIGHT = 6
local PLAYER_SPEED  = 3
local PLAYER_MARGIN = 6

local width  = overlayGetWidth()
local height = overlayGetHeight()

local drift       = 0
local playerX     = width // 2
local playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
local movingLeft  = false
local movingRight = false


local function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end


local function shadeFor(layer)
    return math.random(60, 90) + layer * LAYER_BRIGHT
end


local function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end


local function drawStar(x, y, shade)
    colorForeground(shade, shade, shade)
    overlayPlot(x, y)
end


local function drawLayer(layer)
    for star = 1, STARS_PER_LAYER do
        local x, y = starAt(star, layer)
        drawStar(x, y, shadeFor(layer))
    end
end


local function drawStars()
    for layer = 1, LAYERS do
        drawLayer(layer)
    end
end


local function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end


local function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()
    movePlayer()
    drawStars()
    drawPlayer()
    return OVERLAY_UPDATED
end

Deux choses méritent d’être montrées du doigt avant de passer à la suite.

local function drawStar(x, y, shade) marque la fonction elle-même comme locale. Vos propres fonctions sont des noms comme les autres, et elles n’appartiennent qu’à ce fichier. Les trois callbacks restent globaux pour que Singe puisse les trouver.

Et onOverlayUpdate fait maintenant six lignes qui disent ce qu’est une image : compter la dérive, effacer l’écran, déplacer le joueur, dessiner le ciel, dessiner le joueur, terminé. Il fait cinq travaux en nommant cinq choses qui font chacune un travail, et c’est la forme de toutes les boucles de jeu que vous écrirez jamais.

Une fonction est le nom d’une idée

clamp n’est appelée qu’une fois. La sortir n’a économisé aucune frappe — quatre lignes en sont sorties, une seule y est entrée, et une fonction de neuf lignes est apparue ailleurs. Ça valait quand même la peine.

Une fonction n’est pas seulement un moyen d’éviter de vous répéter. C’est un moyen de donner un nom à une idée, pour que le code qui se sert de l’idée puisse dire le nom et passer à autre chose. « Garder le joueur entre le bord gauche et le bord droit » est une pensée que vous avez eue une fois. clamp(playerX, 0, width - PLAYER_WIDTH - 1), c’est cette pensée, écrite. Quatre instructions if, c’est la même pensée démontée en morceaux que vous devez remonter dans votre tête chaque fois que vous les lisez.

Quand vous vous demandez si quelque chose mérite d’être une fonction, ne vous demandez pas combien de fois vous l’appellerez. Demandez-vous si ça a un nom.

Essayez

  1. Renommez un paramètre. Dans drawStar, changez x et y en across et down, partout dans la fonction. Ne touchez à rien en dehors. Lancez. Trouvez pourquoi rien n’a cassé.

  2. Dessinez-les dans l’autre ordre. Échangez drawStars() et drawPlayer() dans onOverlayUpdate et regardez le vaisseau. Puis remettez-les. Chacune de ces cinq lignes est un travail, et leur ordre à l’écran est leur ordre dans la fonction.

  3. Utilisez clamp sur une nuance. Changez shadeFor en return clamp(math.random(60, 90) + layer * 90, 0, 200) et regardez les trois couches. Puis retirez le clamp et regardez encore : colorForeground retenait discrètement les nombres pour vous depuis le début, et maintenant vous voyez où.

  4. Appelez drawStar avec deux arguments. Écrivez drawStar(100, 100) quelque part dans drawLayer et lancez. L’erreur nomme exactement ce qui manquait. Lisez-la avant de remettre le troisième argument.

  5. Déplacez un nom local. Prenez la ligne local drift = 0 et déplacez-la à la fin du fichier, en dessous de tout. Lancez, lisez l’erreur, et pensez aux mots « en dessous » dans la partie ci-dessus.

Cassez-le exprès

L’ordre d’un fichier qui contient des noms locaux compte, et l’erreur que vous obtenez quand vous cassez cet ordre n’est pas celle que vous attendez.

Prenez toute la fonction drawStar et déplacez-la tout en bas du script, sous onOverlayUpdate. Tout est encore là, écrit pareil. Lancez :

Error executing function 'onOverlayUpdate':  functions/functions.singe:50: attempt to call a nil value (global 'drawStar')
stack traceback:
	functions/functions.singe:50: in upvalue 'drawLayer'
	functions/functions.singe:57: in upvalue 'drawStars'
	functions/functions.singe:101: in function 'onOverlayUpdate'

Elle n’a pas la même allure que l’erreur de la leçon un, parce que c’est une autre sorte d’erreur. L’erreur de la leçon un a été attrapée avant que le script s’exécute. Celle-ci a été attrapée pendant qu’il s’exécutait, c’est pourquoi Singe nomme la fonction dans laquelle il était, et pourquoi il y a un traceback dessous : la liste de qui a appelé qui, le plus récent en premier. La ligne 50 est dans drawLayer, qui a été appelée depuis la ligne 57, dans drawStars, qui a été appelée depuis la ligne 101, dans onOverlayUpdate. Vos numéros de ligne seront différents si votre fichier ne correspond pas exactement à celui ci-dessus, et le moteur peut ajouter une ligne ou deux de son cru sous celles-ci. Le mot upvalue est le nom que Lua donne à un nom local qu’une fonction a emprunté au fichier qui l’entoure ; passez dessus pour l’instant.

La plainte elle-même vaut la peine d’être apprise par cœur. « Attempt to call a nil value » veut dire que vous avez mis des parenthèses après un nom qui ne contenait rien. Le mot global devant drawStar, c’est la partie qui vend la mèche : vous avez marqué drawStar comme locale, donc quand Lua a lu drawLayer et n’a trouvé aucun nom local qui s’appelle ainsi nulle part au-dessus, il ne restait plus qu’à essayer un nom global — et il n’y a pas non plus de nom global appelé drawStar. Remettez la fonction au-dessus du code qui l’appelle, et l’erreur s’en va avec.

Ce que vous avez appris

  • Vous pouvez écrire vos propres fonctions, et rien ne les exécute à part vos propres appels.

  • Les noms entre les parenthèses d’une fonction sont des paramètres, et ce sont les copies, propres à la fonction, de ce que l’appelant a passé.

  • return renvoie une valeur et arrête la fonction sur-le-champ, et une fonction qui se termine sans en avoir un renvoie nil.

  • Un appel peut être l’argument d’un autre appel, et celui de l’intérieur se fait en premier.

  • Lua peut renvoyer plus d’une valeur, et vous les attrapez avec plusieurs noms séparés par des virgules.

  • local crée un nom qui n’existe que là où il a été écrit.

  • Un nom local dans une fonction est créé tout neuf à chaque appel et ne se souvient de rien de l’appel précédent.

  • Un nom local ne peut être vu que sous la ligne qui le crée, donc les valeurs et vos propres fonctions vont au-dessus des callbacks qui s’en servent.

  • Les callbacks restent globaux, parce que Singe les trouve par leur nom.

  • Une fonction vaut la peine d’être écrite quand ce qu’elle fait a un nom, même si vous ne l’appelez qu’une fois.

La prochaine fois

Vos cent vingt étoiles sont toujours cent vingt copies de trois idées. Rien dans le programme n’est une étoile : il y a un nombre, et un peu d’arithmétique qui transforme ce nombre en position. Vous ne pouvez pas dire « celle-ci est plus proche, donc elle tombe plus vite et brille plus fort », parce qu’il n’y a pas de « celle-ci » dont le dire, et vous ne pouvez pas laisser une étoile tomber par le bas et être remplacée par une nouvelle, parce qu’il n’y a rien là à retirer.

La leçon six vous donne la chose qui contient une étoile, puis un moyen d’en contenir cent vingt et d’en ajouter une cent vingt et unième pendant que le jeu tourne. C’est la leçon la plus utile de cette partie du livre.

Leçon 6 : Des listes de choses

La leçon terminée

Vous avez cent vingt étoiles et pas une seule n’existe. Il n’y a d’étoile nulle part dans votre programme : il y a une boucle qui tourne cent vingt fois, et à chaque tour elle calcule deux nombres à partir du numéro de l’étoile et de sa couche, allume un pixel, et oublie tout. Les trois couches sont là pour simuler la seule chose que cet arrangement ne sait pas faire, c’est-à-dire laisser une étoile être différente de sa voisine.

Cette leçon vous donne ce qui manque. Vous allez apprendre à garder une liste d’éléments, à fabriquer un élément qui contient plusieurs valeurs nommées à la fois, puis à réunir les deux en une liste d’éléments qui se souviennent chacun de leur position, de leur vitesse et de leur luminosité. C’est la plus longue leçon de cette partie du livre, et celle sur laquelle s’appuie tout ce qui suit. Prenez votre temps.

Créez un nouveau dossier

Un dossier appelé tables, dedans un fichier appelé tables.singe, et Singe -R tables qui tourne dans un terminal. Copiez-y le programme terminé de la leçon cinq : le champ d’étoiles, le vaisseau, et tout le reste.

Une liste

Ajoutez cette ligne en haut de tables.singe, sous les autres valeurs, et les trois appels à overlayPrint dans onOverlayUpdate, au-dessus du return.

local names = { "Ada", "Grace", "Alan" }
    overlayPrint(2, 2, names[1])
    overlayPrint(2, 3, names[3])
    overlayPrint(2, 4, "There are " .. #names .. " names.")

Lancez-le. Ada sur une ligne, Alan sur la suivante, et There are 3 names. en dessous.

Les accolades de la première ligne fabriquent une table. Une table est le seul conteneur qu’ait Lua, et tout ce dont vous voudrez un jour garder plus d’un exemplaire va dans une table. Ici, elle contient trois chaînes à la suite, ce qui est la forme qu’on appelle une liste.

Les crochets des lignes suivantes en sortent un élément. names[1] est le premier élément, names[3] le troisième, et le nombre entre les crochets s’appelle l'indice.

Ce nombre, c’est là que Lua se sépare de presque tous les autres langages que vous rencontrerez. Lua compte à partir de un. C, Java, Python, JavaScript et la plupart des autres comptent à partir de zéro, si bien que leur premier élément est l’élément zéro et que leur troisième élément est à l’indice deux. Le premier élément de Lua est l’élément un, et c’est la seule chose qui fait trébucher les programmeurs venus d’ailleurs. Vous ne venez de nulle part, alors votre tâche est plus facile : le premier est le numéro un.

names[0] n’est pas une erreur, au passage. C’est nil — la valeur « rien » de la leçon trois — parce que rien n’y est rangé. Lire un indice qui n’a jamais été rempli donne toujours nil, ce qui est bien aimable jusqu’au moment où vous essayez de vous en servir.

Le # devant le nom d’une table est la dernière ponctuation nouvelle avant un bon moment. Il vous donne le nombre d’éléments de la liste, donc #names vaut 3. Comme le nombre d’éléments et le dernier indice sont le même nombre, names[#names] est toujours le dernier élément, quelle que soit la longueur de la liste.

Ajouter et retirer

Une liste qu’il faut écrire en entier ne sert pas à grand-chose dans un jeu. Ces deux appels sont la manière dont une liste change pendant que le programme tourne.

    table.insert(names, "Katherine")

Ça met Katherine au bout, et #names vaut maintenant 4. table.insert est une fonction comme une autre, et le point au milieu de son nom veut dire qu’elle vit dans une table appelée table que Lua fournit — une table de fonctions pour travailler sur les tables. Vous n’avez pas à la créer ni à la charger. Elle est là.

Donnez trois arguments à table.insert et celui du milieu dit où mettre le nouvel élément.

    table.insert(names, 1, "Edsger")

Edsger entre en tête, et tout ce qui était déjà là se décale pour lui faire de la place : Ada était l’élément un et devient l’élément deux. Rien n’est écrasé et rien n’est perdu.

Retirer un élément, c’est l’image inverse.

    table.remove(names, 2)

L’élément deux s’en va, et tout ce qui le suivait recule d’un cran pour combler le vide, si bien que la liste n’a jamais de trou au milieu. table.remove vous rend aussi l’élément qu’il a retiré, donc local gone = table.remove(names, 2) s’en débarrasse et vous dit ce que c’était en une seule ligne. Ne mettez pas de nombre du tout — table.remove(names) — et il prend le dernier élément, ce qui est le moyen le plus rapide de se servir d’une liste comme d’une pile.

Mettez ces trois appels dans votre script, un à la fois, lancez-le après chacun, et regardez changer le nombre sur la troisième ligne.

Parcourir une liste

Vous connaissez déjà une manière de visiter chaque élément, parce que vous vous en servez depuis la leçon quatre :

    for i = 1, #names do
        overlayPrint(2, i + 1, names[i])
    end

Ça marche. Commencer à un, s’arrêter au nombre d’éléments, se servir du compteur comme indice. Il y a une meilleure manière, et c’est celle que vous écrirez désormais :

    for i, name in ipairs(names) do
        overlayPrint(2, i + 1, name)
    end

ipairs parcourt une liste depuis l’élément un jusqu’à ce qu’il n’y en ait plus, et donne deux choses à votre boucle à chaque tour : l’indice et l’élément lui-même. C’est le deuxième qui compte. Avec le for numérique, vous obtenez un nombre et vous devez retourner à la table avec names[i] pour savoir ce que c’est ; avec ipairs, l’élément est déjà dans votre main, sous le nom que vous avez mis en second.

C’est aussi plus difficile de se tromper. for i = 1, #names est une belle occasion de se tromper d’une unité — commencez à zéro et vous affichez un nil, arrêtez-vous à #names - 1 et vous perdez le dernier — et ipairs ne contient aucun nombre sur lequel se tromper.

La plupart du temps, vous ne voulez pas l’indice, seulement l’élément. Écrivez l’indice sous la forme d’un simple tiret bas, et n’en parlons plus :

    for _, name in ipairs(names) do

_ est un nom parfaitement ordinaire, et rien dans Lua ne le traite à part. C’est une habitude que partagent les programmeurs pour dire « quelque chose arrive ici et je ne vais pas m’en servir ». Quiconque lit votre boucle sait au premier coup d’œil que l’indice n’y compte pas.

Supprimez maintenant vos essais avec names, et les lignes overlayPrint avec. Vous savez ce qu’est une liste. Il est temps d’y ranger quelque chose de mieux qu’une chaîne.

Une table peut aussi être un enregistrement

Une étoile doit se souvenir de quatre choses : où elle se trouve de gauche à droite, où elle se trouve de haut en bas, à quelle vitesse elle tombe, et à quel point elle brille. Quatre listes séparées, toutes tenues à jour ensemble à la main, ce serait l’enfer. Fabriquez plutôt une table et mettez-y des noms.

    local star = {}
    star.x = 40
    star.y = 0
    star.speed = 2
    star.shade = 180

Les accolades vides fabriquent une table vide. Les quatre lignes suivantes y mettent des valeurs sous des noms au lieu de numéros, et le point est la manière de dire quel nom vous voulez. star.x se lit le x de star, et ça se comporte exactement comme n’importe quelle autre variable : on peut le lire, lui donner une valeur, lui ajouter quelque chose.

    star.y = star.y + star.speed

Une table utilisée de cette manière — un ensemble fixe de valeurs nommées qui décrivent une seule chose — est un enregistrement, et les noms qu’elle contient sont ses champs. C’est le même genre de table que la liste ci-dessus. La seule différence, c’est qu’on trouve les éléments d’une liste par numéro et les champs d’un enregistrement par nom, et qu’une même table peut faire les deux à la fois si un jour vous le voulez.

Le point est un raccourci. star.x et star["x"] veulent dire exactement la même chose, et ça vaut la peine de le voir une fois : les crochets acceptent un nom aussi volontiers qu’un nombre, donc une liste et un enregistrement sont vraiment une seule idée sous deux casquettes. Utilisez le point. Ça se lit mieux.

Un champ que vous n’avez jamais rempli vaut nil, comme un indice jamais rempli. Il n’existe nulle part de liste des noms de champ autorisés, et rien ne vérifie votre orthographe, donc star.sped n’est pas une erreur — c’est nil, et vous verrez ce qui arrive ensuite à la fin de cette leçon.

Écrire quatre lignes pour remplir quatre champs, on s’en lasse. Vous pouvez mettre les champs à l’intérieur des accolades quand vous fabriquez la table :

    local star = {
        x     = 40,
        y     = 0,
        speed = 2,
        shade = 180
    }

La même table, en une seule instruction. Les virgules séparent les champs, le dernier n’a pas besoin de virgule après lui, et les lignes ne sont étalées que pour se lire facilement.

Une liste d’enregistrements

Voici toute l’idée de cette leçon en deux lignes :

    local stars = {}
    table.insert(stars, star)

Une liste peut contenir n’importe quoi, y compris une table. Une liste d’enregistrements est donc une liste de choses qui se souviennent chacune de tout ce qui les concerne. stars[1] est une étoile entière, et stars[1].y est la distance de cette étoile depuis le haut de l’écran. Presque tous les jeux que vous écrirez sont une poignée de listes comme celle-ci : les ennemis, les balles, les bonus et les blocs qui tombent.

Il y a une chose à savoir sur les tables avant d’écrire le code, et elle piège tout le monde une fois. Donner une table à une fonction ne la copie pas. Un nombre est copié — c’est pour ça que half pouvait découper son number à la leçon cinq sans déranger drift — mais une table est partagée. Les deux noms désignent la même table, et un changement fait par l’un se voit par l’autre.

    local star = stars[3]
    star.y = star.y + 1

Ça déplace la troisième étoile de la liste. Pas une copie d’elle : elle. C’est exactement ce que vous voulez ici, et c’est ce qui fait marcher la section suivante, mais souvenez-vous-en le jour où une fonction que vous avez écrite change quelque chose que vous ne vous attendiez pas à la voir changer.

Reconstruisez le champ d’étoiles

Dehors, l’arithmétique. Une étoile va devenir une chose.

Supprimez starAt, shadeFor, drawLayer et l’ancien drawStar, et avec eux les constantes qu’ils utilisaient : LAYERS, STARS_PER_LAYER, ACROSS_STEP, DOWN_STEP, LAYER_SHIFT et LAYER_SPEED. La variable drift s’en va aussi, tout comme la ligne de drift en haut de onOverlayUpdate. LAYER_BRIGHT reste, sous un nom qui ne parle plus de couches, et deux valeurs le rejoignent :

local STAR_COUNT  = 120
local STAR_SHADE  = 55
local BURST_COUNT = 10
local stars = {}

Cent vingt, c’est ce que vous aviez : trois couches de quarante. La liste commence vide, et voici ce qui la remplit :

local function newStar(y)
    local speed = math.random(1, 3)
    local star  = {
        x     = math.random(0, width - 1),
        y     = y,
        speed = speed,
        shade = math.random(60, 90) + speed * STAR_SHADE
    }
    return star
end

newStar fabrique une étoile et vous la rend. Regardez le dernier champ et comparez-le avec shadeFor à la leçon cinq : le même calcul, avec la vitesse de l’étoile là où se trouvait le numéro de couche. Les couches n’ont pas tant disparu que fondu. Chaque étoile choisit maintenant sa propre vitesse, un, deux ou trois pixels par image, et une étoile qui tombe plus vite est plus brillante, ce qui fait toute l’illusion de profondeur et coûte une ligne.

Le y de départ est un paramètre parce que les deux appelants veulent des choses différentes. Les étoiles fabriquées au démarrage du jeu doivent être éparpillées sur tout l’écran ; celles fabriquées plus tard arrivent par le haut.

local function makeStars()
    for number = 1, STAR_COUNT do
        table.insert(stars, newStar(math.random(0, height - 1)))
    end
end

Rien n’appelle encore makeStars. Ajoutez une ligne tout en bas du fichier, après tout le reste et en dehors de toute fonction :

makeStars()

Il y a plus à dire sur cette ligne, et ça attendra la fin de la leçon. Passons au dessin, qui raccourcit chaque fois que vous y touchez :

local function drawStar(star)
    colorForeground(star.shade, star.shade, star.shade)
    overlayPlot(star.x, star.y)
end


local function drawStars()
    for _, star in ipairs(stars) do
        drawStar(star)
    end
end

drawStar prenait trois nombres à la leçon cinq et prend maintenant une étoile. Tout ce qu’elle a besoin de savoir est dans l’étoile, et c’est toute la raison d’être des enregistrements : une seule chose à faire passer au lieu de quatre, et aucun risque de les donner dans le mauvais ordre. Et drawStars a perdu sa boucle sur les couches, ainsi que tout intérêt pour le nombre d’étoiles ou leur provenance.

Des étoiles qui vont et viennent

Maintenant, la partie que l’ancien champ d’étoiles ne savait pas faire du tout. Les étoiles tombent chacune à sa vitesse, sortent par le bas, et sont remplacées en haut.

local function moveStars()
    for i = #stars, 1, -1 do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end
    while #stars < STAR_COUNT do
        table.insert(stars, newStar(0))
    end
end

Appelez-la depuis onOverlayUpdate, sur la ligne où se trouvait drift = drift + 1.

Chaque étoile descend de sa propre speed, et c’est la ligne que la leçon cinq ne pouvait pas écrire. Le while du bas, c’est le réapprovisionnement : tant qu’il y a moins de cent vingt étoiles, en fabriquer une autre en haut de l’écran. Il tourne autant de fois qu’il le faut puis s’arrête, et c’est le bon outil quand vous ne savez pas combien il en manque.

La ligne for du haut compte à rebours, avec le pas que vous avez rencontré à la leçon quatre. for i = #stars, 1, -1 visite le dernier élément en premier et remonte jusqu’à l’élément un. Ce n’est pas une fioriture. C’est la seule manière sûre de faire ce que fait cette boucle, et la section suivante explique pourquoi.

Ne retirez jamais en avançant

Écrivez la même boucle dans l’autre sens et elle est cassée :

    for i = 1, #stars do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end

Suivez-la à la main avec quatre étoiles, et supposez que les étoiles deux et trois aient toutes les deux atteint le bas.

  • i vaut 1. L’étoile un va bien.

  • i vaut 2. L’étoile deux est sortie par le bas, alors elle s’en va. Tout recule d’un cran : l’étoile qui était la trois est maintenant la deux, et celle qui était la quatre est maintenant la trois.

  • i vaut 3. C’est l’étoile qui était la quatre. L’étoile trois n’a jamais été examinée. Retirer l’élément deux l’a fait reculer dans la case deux, et la boucle était déjà passée par la case deux.

  • i vaut 4. Il n’y a plus d’élément quatre. stars[4] vaut nil.

Deux défauts distincts pour une seule petite erreur. Des éléments sont sautés, si bien qu’une étoile qui avait atteint le bas n’est même pas examinée à ce tour-ci. Une étoile qui survit une image de plus ne fait pas de mal, mais la même boucle sur une liste d’ennemis, où c’est l’examen qui les tue, est un bug que vous chercheriez pendant une heure. Le second défaut fait plus de bruit. La liste est maintenant plus courte que le nombre avec lequel la boucle a commencé, parce que #stars a été calculé une seule fois, avant tout retrait, alors les derniers tours de la boucle vont au-delà de la fin de la liste :

Error executing function 'onOverlayUpdate':  tables/tables.singe:60: attempt to index a nil value (local 'star')
stack traceback:
	tables/tables.singe:60: in upvalue 'moveStars'
	tables/tables.singe:124: in function 'onOverlayUpdate'

« Attempt to index a nil value » veut dire que vous avez mis un point après quelque chose qui ne contenait rien. Le (local 'star') à la fin le nomme : star valait nil, donc star.y n’avait nulle part où chercher.

Aller à rebours corrige les deux défauts à la fois, et ça vaut la peine de voir pourquoi plutôt que de le croire sur parole. Quand vous retirez l’élément i, tout ce qui suit i recule d’une case — et en allant à rebours, tout ce qui suit i, c’est tout ce que vous avez déjà visité. Ce qui reste à venir, les éléments i - 1 jusqu’à 1, n’a pas bougé du tout. La liste qui rétrécit derrière vous ne peut pas vous faire de mal non plus, parce que vous marchez vers l’élément un et que l’élément un est toujours là.

La règle, qui vous servira toute votre vie : quand une boucle risque de retirer des éléments de la liste qu’elle parcourt, parcourez-la à rebours.

ipairs n’est pas une exception. Retirer des éléments au milieu d’une boucle ipairs tourne mal de la même façon. ipairs sert à regarder, et le for à rebours sert à changer.

Ajoutez-en vous-même

Une branche de plus dans onInputPressed et vous pouvez regarder la liste grandir pendant que le jeu tourne. Elle va avec les deux autres :

    elseif what == SWITCH_BUTTON1 then
        addBurst()
local function addBurst()
    for number = 1, BURST_COUNT do
        table.insert(stars, newStar(0))
    end
end

addBurst va au-dessus des callbacks, avec vos autres fonctions. Et pour que vous puissiez voir changer la longueur de la liste, affichez le nombre d’étoiles dans onOverlayUpdate :

    overlayPrint(0, 0, "Stars: " .. #stars)

Appuyez sur le bouton — la barre d’espace, sauf si vous avez changé ce qui produit SWITCH_BUTTON1 — une douzaine de fois. Le nombre monte de dix à chaque appui et le ciel s’épaissit, et rien ne se répète tant que vous le gardez enfoncé : onInputPressed n’est prévenu qu’une fois, quand le bouton s’enfonce. Puis regardez le nombre redescendre tout seul à cent vingt à mesure que les étoiles en trop atteignent le bas et sont retirées, parce que le réapprovisionnement ne fait jamais que compléter la liste jusqu’à STAR_COUNT et ne la raccourcit jamais.

Rien dans le dessin, le déplacement ou le retrait n’a eu besoin d’être prévenu que le nombre d’étoiles avait changé. Tout fonctionne à partir de la liste.

Le tout

local STAR_COUNT  = 120
local STAR_SHADE  = 55
local BURST_COUNT = 10

local PLAYER_WIDTH  = 20
local PLAYER_HEIGHT = 6
local PLAYER_SPEED  = 3
local PLAYER_MARGIN = 6

local width  = overlayGetWidth()
local height = overlayGetHeight()

local stars       = {}
local playerX     = width // 2
local playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
local movingLeft  = false
local movingRight = false


local function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end


local function newStar(y)
    local speed = math.random(1, 3)
    local star  = {
        x     = math.random(0, width - 1),
        y     = y,
        speed = speed,
        shade = math.random(60, 90) + speed * STAR_SHADE
    }
    return star
end


local function makeStars()
    for number = 1, STAR_COUNT do
        table.insert(stars, newStar(math.random(0, height - 1)))
    end
end


local function addBurst()
    for number = 1, BURST_COUNT do
        table.insert(stars, newStar(0))
    end
end


local function moveStars()
    for i = #stars, 1, -1 do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end
    while #stars < STAR_COUNT do
        table.insert(stars, newStar(0))
    end
end


local function drawStar(star)
    colorForeground(star.shade, star.shade, star.shade)
    overlayPlot(star.x, star.y)
end


local function drawStars()
    for _, star in ipairs(stars) do
        drawStar(star)
    end
end


local function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end


local function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    elseif what == SWITCH_BUTTON1 then
        addBurst()
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    movePlayer()
    moveStars()
    drawStars()
    drawPlayer()
    overlayPrint(0, 0, "Stars: " .. #stars)
    return OVERLAY_UPDATED
end


makeStars()

Ce qui vient de se passer

Le programme est plus court que celui de la leçon cinq, et il fait quelque chose que la leçon cinq ne pouvait même pas commencer à faire. Trois morceaux méritent un second regard.

makeStars()

Cette unique ligne tout en bas du fichier n’est à l’intérieur d’aucune fonction, et on la rate facilement. Lua lit votre fichier de haut en bas quand Singe le charge, et une ligne au niveau extérieur du fichier s’exécute sur-le-champ, une fois, avant que le moteur ait appelé quoi que ce soit. Tout ce qui est au-dessus n’est que définitions — voici une valeur, voici une fonction — et c’est la seule instruction qui s’exécute au chargement. Elle doit être en bas, parce que makeStars n’existe pas tant que la ligne qui la crée n’a pas été lue.

        local star = stars[i]
        star.y = star.y + star.speed

star est une variable locale créée à neuf à chaque tour de la boucle, et elle contient la même table que celle qui se trouve dans la liste — pas une copie. Changer star.y déplace l’étoile qui est dans la liste. Si les tables étaient copiées, cette boucle déplacerait cent vingt copies par image et rien ne changerait jamais à l’écran.

    for _, star in ipairs(stars) do
        drawStar(star)
    end

Comparez avec la leçon quatre : deux boucles imbriquées, deux calculs par étoile, un reste pour garder chacune à l’écran, et trois couches pour simuler la variété que vous obtenez maintenant gratuitement. Le dessin ne sait plus et ne se soucie plus de savoir comment les étoiles sont arrivées là où elles sont, combien il y en a, ni ce qui va leur arriver. Chaque partie du programme fait un seul travail, et la liste est ce sur quoi elles sont toutes d’accord.

Essayez

  1. Rendez-le plus profond. Changez math.random(1, 3) en math.random(1, 6) et STAR_SHADE en 25. Plus de vitesses, plus de nuances, un ciel plus profond.

  2. Moins d’étoiles, plus grosse salve. Mettez STAR_COUNT à 10 et BURST_COUNT à 100, puis appuyez trois ou quatre fois sur le bouton. Regardez le nombre monter à l’écran, et chronométrez le temps qu’il met à redescendre.

  3. Donnez un autre champ à une étoile. Ajoutez age = 0 dans newStar, ajoutez un à star.age dans moveStars, et affichez stars[1].age à côté du nombre d’étoiles. Rien d’autre dans le programme n’a besoin de changer pour porter un fait nouveau sur chaque étoile.

  4. Arrêtez de les retirer. Supprimez les trois lignes du bloc if star.y >= height dans moveStars et lancez. Attendez dix secondes, puis lisez le nombre à l’écran et regardez le ciel. Trouvez comment les deux peuvent être vrais à la fois.

  5. Faites-le dans l’autre sens. Changez for i = #stars, 1, -1 en for i = 1, #stars et lancez jusqu’à ce que ça plante. Puis relisez la section ci-dessus avec la vraie erreur sous les yeux.

Cassez-le exprès

Faites une faute dans un nom de champ. Dans moveStars, changez star.speed en star.sped :

        star.y = star.y + star.sped

Lancez-le :

Error executing function 'onOverlayUpdate':  tables/tables.singe:60: attempt to perform arithmetic on a nil value (field 'sped')
stack traceback:
	tables/tables.singe:60: in upvalue 'moveStars'
	tables/tables.singe:124: in function 'onOverlayUpdate'

Vos numéros de ligne ne seront pas exactement ceux-là, sauf si votre fichier correspond ligne pour ligne à celui d’au-dessus. Le nom du fichier, le nombre qui le suit et la plainte, voilà ce que vous lisez.

Lisez d’abord la fin de la première ligne. field 'sped', c’est Lua qui vous dit quel nom est revenu vide, et il vous dit que c’était un champ — quelque chose après un point — plutôt qu’une variable à vous. « Attempt to perform arithmetic on a nil value », c’est ce qu’il était en train de faire quand il s’en est aperçu : ajouter nil à un nombre, ce qui est impossible.

Il n’y a eu aucune plainte quand la table a été fabriquée sans champ sped, et aucune au moment où vous l’avez demandé. Une table donne nil pour tout nom qu’elle n’a pas, sans commentaire. L’erreur vient plus tard, à la première ligne qui essaie d'utiliser le rien qu’on vous a donné, et qui peut être très loin de la faute de frappe. Quand vous voyez nil value (field 'something'), cherchez l’endroit où ce nom a été écrit autrement.

Ce que vous avez appris

  • Les accolades fabriquent une table, le seul conteneur qu’ait Lua. Une table utilisée comme liste contient des éléments à la suite, et des crochets avec un indice en sortent un.

  • Lua compte à partir de un. La plupart des autres langages comptent à partir de zéro.

  • #list est le nombre d’éléments qu’elle contient, et list[#list] est le dernier.

  • table.insert ajoute un élément, au bout ou à la position que vous indiquez ; table.remove en retire un et comble le vide.

  • Un indice ou un champ jamais rempli vaut nil, et rien ne vous prévient tant que vous ne vous en servez pas.

  • ipairs parcourt une liste et vous donne l’indice et l’élément ; _ est l’habitude pour un indice dont vous ne voulez pas.

  • Une table utilisée comme enregistrement contient des champs nommés, qu’on atteint avec un point.

  • Une liste d’enregistrements, c’est la manière dont un jeu garde ses ennemis, ses balles, et tout ce dont il a plus d’un exemplaire.

  • Les tables sont partagées, pas copiées, quand vous les faites passer.

  • Quand une boucle risque de retirer des éléments de la liste qu’elle parcourt, parcourez-la à rebours.

La prochaine fois

Vous avez maintenant toutes les pièces d’un jeu : des choses qui bougent, un vaisseau qui répond aux commandes, des décisions, des boucles, des fonctions, et une liste que des choses peuvent rejoindre et quitter pendant que le jeu tourne.

La leçon sept les assemble en un jeu que vous pouvez perdre. Vous vous dirigez le long du bas de l’écran, des blocs tombent du haut, et vous restez hors de leur chemin — et les blocs qui tombent sont une liste d’enregistrements, fabriqués, déplacés et retirés exactement comme vos étoiles.

Leçon 7 : Un jeu

La leçon terminée

Il y a six leçons, vous avez mis un mot sur un écran noir. Depuis, vous avez appris toutes les idées dont est fait un petit jeu : les variables, les décisions, les boucles, vos propres fonctions, et les listes de choses. Cette leçon n’enseigne aucune idée nouvelle. Elle dépense celles que vous avez.

Vous allez construire un jeu appelé Dodge. Des blocs tombent du ciel, vous faites glisser une barre le long du bas de l’écran pour les esquiver, et chaque bloc qui vous rate vaut un point. Prenez-en trois et c’est fini. Vous le construirez en six étapes, et chacune d’elles tourne : vous n’aurez jamais à taper cent lignes en croisant les doigts.

Créez le dossier

Créez un dossier appelé dodge, et dedans un fichier appelé dodge.singe. Lancez-le comme vous lancez tout depuis la leçon un :

Singe -R dodge

Laissez-le tourner dans un terminal pendant toute la leçon. Chaque fois que vous enregistrez, le jeu redémarre avec votre modification.

Première étape : quelque chose à diriger

Tapez ceci, enregistrez, et dirigez-le avec les touches fléchées gauche et droite.

dofile("Singe/Framework.singe")

local PLAYER_WIDTH  = 40
local PLAYER_HEIGHT = 8
local PLAYER_SPEED  = 4
local PLAYER_MARGIN = 4

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local playerY      = screenHeight - PLAYER_HEIGHT - PLAYER_MARGIN

local playerX    = (screenWidth - PLAYER_WIDTH) / 2
local goingLeft  = false
local goingRight = false


function onInputPressed(what)
    if what == SWITCH_LEFT then
        goingLeft = true
    elseif what == SWITCH_RIGHT then
        goingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goingLeft = false
    elseif what == SWITCH_RIGHT then
        goingRight = false
    end
end


function onOverlayUpdate()
    if goingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if goingRight then
        playerX = playerX + PLAYER_SPEED
    end
    if playerX < 0 then
        playerX = 0
    elseif playerX > screenWidth - PLAYER_WIDTH then
        playerX = screenWidth - PLAYER_WIDTH
    end

    overlayClear()
    colorForeground(80, 255, 160)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH - 1, playerY + PLAYER_HEIGHT - 1)
    return OVERLAY_UPDATED
end

Cinquante lignes, et presque rien de nouveau. Il y a deux choses nouvelles, alors commençons par la première ligne.

dofile("Singe/Framework.singe")

dofile appartient à Lua plutôt qu’à Singe, et ça veut dire « va exécuter ce fichier, puis reviens continuer ici ». Le fichier qu’il exécute est Singe/Framework.singe, l’un des fichiers que le moteur a extraits dans votre dossier de travail la première fois que vous avez lancé quoi que ce soit, à la leçon un. Ouvrez-le dans votre éditeur de texte et regardez : c’est du Lua ordinaire, de la même nature que ce que vous écrivez depuis la leçon deux, et il n’a rien de magique.

L’exécuter donne à votre script une série de noms dont il peut ensuite se servir. Ceux auxquels ce livre fait appel sont les suivants :

  • DIR, qui contient le dossier où se trouve votre propre script. La leçon neuf en a besoin dès qu’un jeu charge une image, et c’est la vraie raison pour laquelle cette ligne est là.

  • SCANCODE et MODIFIER, des noms pour chaque touche d’un clavier, pour un jeu qui lit ce qu’on tape plutôt qu’un joystick.

  • GAMEPAD_0 à GAMEPAD_3 et MOUSE_0 à MOUSE_3, pour une borne sur laquelle on a branché plus d’un exemplaire de quelque chose.

  • Quelques fonctions utilitaires dont le nom commence par util, et les six appels qui envoient un score à un tableau des scores, ce qui est l’objet de la leçon vingt-huit.

  • Une seconde façon d’écrire un jeu, tout entière, qui est l’objet de la leçon quinze.

Une chose qu’il ne vous donne pas, parce que c’est ce qu’on croirait naturellement. SWITCH_LEFT, et tous les autres noms qui commencent par SWITCH_, viennent du moteur lui-même, avant même qu’un script ne s’exécute. C’est pourquoi les leçons trois à six pouvaient lire les touches fléchées sans rien charger. Le framework ajoute à ce qui est déjà là ; il ne le fournit pas.

Ce jeu-ci n’utilise rien du framework. La ligne est là parce que chaque jeu de la leçon neuf jusqu’à la fin du livre en a besoin, et parce que c’est ainsi que commence presque chaque vrai jeu Singe. Elle est lue une fois, au démarrage, puis on n’y pense plus.

La deuxième chose nouvelle, c’est la façon dont les touches fléchées sont gérées, parce que c’est la première chose sur laquelle les débutants se trompent.

onInputPressed ne déplace pas le joueur. Il met goingLeft à true, et onInputReleased le remet à false. Le déplacement se fait dans onOverlayUpdate, qui demande « le joueur garde-t-il la gauche enfoncée ? » soixante fois par seconde. Si vous déplaciez plutôt le joueur dans onInputPressed, vous obtiendriez un pas par appui : Singe envoie un appui exactement une fois, quand la touche s’enfonce, et ne le répète jamais, ce que l’entrée de onInputPressed dans la Référence dit clairement. Garder la touche enfoncée ne ferait rien du tout.

Le gestionnaire d’appui note donc ce qui est vrai dans le monde, et la mise à jour décide quoi en faire. Gardez cette séparation, et votre code de lecture des commandes fera cinq lignes pour toujours.

Les quatre noms en majuscules sont des variables ordinaires. Écrire PLAYER_SPEED en majuscules est un message à vous-même et à quiconque vous lit : celui-là est fixé une fois en haut et ne change jamais. Rien dans Lua ne l’impose. Ça compte parce que dans une minute il y en aura dix, et quand le jeu sera trop difficile, vous voudrez un endroit évident où aller baisser un nombre.

screenWidth et screenHeight viennent du moteur au lieu d’être tapés à la main, si bien que le jeu se met en page tout seul, quelle que soit la taille de l’overlay. playerY est calculé une fois à partir de la hauteur : la barre se tient à PLAYER_MARGIN pixels du bas et ne monte ni ne descend jamais, alors il n’y a aucune raison de le recalculer à chaque image.

Le - 1 de la ligne overlayBox n’est pas une faute de frappe. overlayBox dessine en incluant les deux coins que vous lui donnez, donc une boîte de playerX à playerX + 40 fait quarante et un pixels de large. Retirer un donne une barre visible d’exactement quarante de large, ce qui comptera à la quatrième étape, quand quelque chose devra décider si elle vous a touché.

Deuxième étape : quelque chose à éviter

Un bloc, qui tombe. Ajoutez deux constantes à la liste du haut :

local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5

Deux variables de plus sous goingRight :

local blockX     = math.random(0, screenWidth - BLOCK_SIZE)
local blockY     = -BLOCK_SIZE

Dans onOverlayUpdate, juste au-dessus de la ligne overlayClear(), faites-le tomber :

    blockY = blockY + BLOCK_SPEED
    if blockY > screenHeight then
        blockX = math.random(0, screenWidth - BLOCK_SIZE)
        blockY = -BLOCK_SIZE
    end

Et sous la ligne qui dessine le joueur, dessinez-le :

    colorForeground(255, 90, 90)
    overlayBox(blockX, blockY, blockX + BLOCK_SIZE - 1, blockY + BLOCK_SIZE - 1)

Enregistrez. Un carré rouge tombe, atteint le bas, et réapparaît en haut à un nouvel endroit.

Il démarre à -BLOCK_SIZE, c’est-à-dire au-dessus du bord supérieur de l’écran. Une position négative n’a rien d’anormal : le moteur dessine la partie de la boîte qui est sur l’overlay et jette sans rien dire la partie qui n’y est pas. Le bloc glisse dans le champ au lieu de surgir de nulle part.

BLOCK_SPEED vaut 1.5, pas un nombre entier, donc blockY passe la plus grande partie de sa vie à valoir quelque chose comme 83.5. Ça aussi, c’est normal. Le dessin laisse tomber la partie fractionnaire, et la garder dans la variable est ce qui permet au bloc d’avancer de moins d’un pixel par image.

Troisième étape : le ciel en est plein

Un bloc, ce n’est pas un jeu. À la leçon six, vous avez appris à garder beaucoup d’exemplaires de quelque chose dans une liste, et c’est à ça que ça servait.

Supprimez blockX et blockY, et mettez ceci à leur place :

local blocks     = {}
local spawnTimer = 0

Ajoutez une constante de plus en haut :

local SPAWN_FRAMES  = 40

Maintenant, une fonction qui fabrique un bloc et le met dans la liste. Mettez-la au-dessus de onInputPressed :

function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    block.y = -BLOCK_SIZE
    table.insert(blocks, block)
end

Remplacez le code de chute de la deuxième étape par ceci :

    spawnTimer = spawnTimer - 1
    if spawnTimer <= 0 then
        spawnBlock()
        spawnTimer = SPAWN_FRAMES
    end

    for i = #blocks, 1, -1 do
        local block = blocks[i]
        block.y = block.y + BLOCK_SPEED
        if block.y > screenHeight then
            table.remove(blocks, i)
        end
    end

Et remplacez la ligne qui dessinait le bloc par une boucle sur tous les blocs :

    for i, block in ipairs(blocks) do
        overlayBox(block.x, block.y, block.x + BLOCK_SIZE - 1, block.y + BLOCK_SIZE - 1)
    end

Enregistrez. Il pleut des blocs.

Un bloc est un enregistrement : une petite table avec un x et un y dedans, ce qui est la manière d’empêcher deux nombres qui vont ensemble de se séparer. blocks est une liste de ces enregistrements, et c’est la forme qu’a le monde de presque tous les jeux.

spawnTimer décompte d’un par image, et quand il atteint zéro, un bloc naît et le minuteur est remonté. Quarante images, c’est environ deux tiers de seconde. Il n’y a pas d’horloge dans ce jeu, et il n’en faut pas : onOverlayUpdate est le battement de cœur, et compter les battements est une très bonne manière de mesurer le temps.

La boucle de chute tourne à rebours — de #blocks jusqu’à 1, un pas à la fois — parce qu’elle retire des choses en chemin. C’est la règle de la leçon six, et c’est la première fois que vous avez une vraie raison de la suivre. Retirez l’élément trois en avançant et tout recule d’un cran, si bien que le bloc qui était l’élément quatre devient l’élément trois et que la boucle ne le regarde jamais. En allant à rebours, tout ce qui bouge a déjà été traité.

La boucle de dessin utilise ipairs à la place, parce qu’elle ne retire rien et veut seulement chaque bloc à tour de rôle.

Quatrième étape : se faire toucher

Les blocs vous traversent. Il est temps de s’en apercevoir.

Le moteur a une fonction pour exactement cette question. Changez le test à l’intérieur de la boucle de chute, de ceci :

        if block.y > screenHeight then
            table.remove(blocks, i)
        end

à ceci :

        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) or block.y > screenHeight then
            table.remove(blocks, i)
        end

Enregistrez, et lancez la barre contre un bloc qui tombe. Il disparaît.

collideRects prend deux rectangles et répond true s’ils se chevauchent. Chaque rectangle fait quatre nombres : un coin, puis une largeur et une hauteur — pas deux coins, ce qui est l’autre manière raisonnable de décrire un rectangle et celle qu’utilise overlayBox. L’entrée de collideRects dans la Référence donne l’ordre, et ça vaut la peine d’y jeter un œil maintenant, parce que mettre les huit arguments dans le mauvais ordre est le genre d’erreur qui ne produit aucun message, juste un jeu où rien ne touche jamais rien.

Vous pourriez l’écrire vous-même. C’est quatre comparaisons, et ce n’est vraiment pas difficile. Servez-vous quand même de celle du moteur, pour trois raisons. Elle est juste, y compris dans les cas délicats : un rectangle sans largeur, deux rectangles qui ne se touchent que par un bord. Elle dit ce qu’elle veut dire, donc la ligne se lit « ces deux-là se sont-ils chevauchés » au lieu de quatre comparaisons reliées par and qu’il faut déchiffrer chaque fois que vous y revenez. Et quand vous arriverez à la leçon onze, où les choses se heurtent sans arrêt, vous connaîtrez déjà la famille : collidePointRect pour un clic de souris, collideCircles pour deux choses rondes, et collideSegments pour un tir contre un mur. La Référence les présente ensemble.

La seule chose que le moteur ne peut pas faire pour vous, c’est décider ce qu’un rectangle veut dire. Ici, le rectangle du bloc est le bloc entier. Dans un vrai jeu, vous voulez souvent que le rectangle de collision soit un peu plus petit que l’image, pour qu’un frôlement ressemble à un frôlement. C’est une décision de conception, et c’est à la leçon onze que vous la prendrez.

Cinquième étape : score et vies

Se faire toucher devrait coûter quelque chose, et survivre devrait rapporter quelque chose.

Deux constantes de plus en haut :

local BLOCK_FASTER  = 0.05
local START_LIVES   = 3

Trois variables de plus, à côté de spawnTimer :

local blockSpeed = BLOCK_SPEED
local score      = 0
local lives      = START_LIVES

BLOCK_SPEED est maintenant la vitesse à laquelle le jeu démarre, et blockSpeed la vitesse à laquelle il va en ce moment. Changez la ligne de chute pour qu’elle utilise la variable :

        block.y = block.y + blockSpeed

Puis séparez les deux cas, parce qu’ils font maintenant des choses différentes :

        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) then
            table.remove(blocks, i)
            lives = lives - 1
        elseif block.y > screenHeight then
            table.remove(blocks, i)
            score      = score + 1
            blockSpeed = blockSpeed + BLOCK_FASTER
        end

Et affichez les nombres. Mettez ceci juste avant le return :

    overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)

Enregistrez, et jouez une minute. Ça devient plus difficile, et c’est tout le truc : chaque bloc que vous esquivez fait tomber les suivants plus vite, d’un vingtième de pixel par image. Au bout de vingt points, ils sont nettement plus rapides. Vous n’avez pas eu à écrire un seul mot sur les niveaux de difficulté.

Vous verrez aussi LIVES descendre à -4, parce que rien n’arrête encore le jeu. C’est l’étape suivante, et c’est celle qui compte le plus.

Sixième étape : fin de partie, et on recommence

Voici le piège. La manière évidente d’ajouter un écran de fin de partie, c’est une variable appelée gameOver, mise à true quand il n’y a plus de vies. Puis vous voulez un écran titre avant la première partie, alors vous ajoutez started. Puis vous voulez une touche de pause, alors vous ajoutez paused. Vous avez maintenant trois variables vrai-ou-faux, huit combinaisons entre elles, et cinq de ces combinaisons sont des absurdités que votre code doit prendre soin de ne jamais produire. Chaque débutant écrit ce jeu au moins une fois, et c’est là que les petits jeux vont mourir.

Faites plutôt ceci. Une seule variable contient ce que fait le jeu, sous forme de mot :

local state      = "waiting"

Elle vaut "waiting" avant la première partie, "playing" pendant une partie, et "over" quand les vies sont épuisées. Trois états, une variable, et rien qui ressemble à une combinaison impossible. Ces chaînes n’ont rien de magique ; ce sont des mots que vous avez choisis, et vous devez les écrire de la même façon à chaque fois.

Maintenant, la fonction qui commence une partie. Chaque variable qui appartient à une partie revient ici à sa valeur de départ, en un seul endroit :

function startGame()
    playerX    = (screenWidth - PLAYER_WIDTH) / 2
    blocks     = {}
    blockSpeed = BLOCK_SPEED
    spawnTimer = 0
    score      = 0
    lives      = START_LIVES
    state      = "playing"
end

Perdre la dernière vie y met fin. Dans la branche de la collision, sous lives = lives - 1 :

            if lives == 0 then
                state = "over"
            end

La barre d’espace lance une partie, mais seulement quand il n’y en a pas déjà une en cours. Ajoutez une branche à onInputPressed :

    elseif what == SWITCH_BUTTON1 and state ~= "playing" then
        startGame()

~= veut dire « n’est pas égal à ». state ~= "playing" est vrai pendant l’attente et vrai après la fin, ce qui correspond exactement aux deux moments où Espace doit lancer une partie. SWITCH_BUTTON1 est la barre d’espace par défaut, et aussi le bouton A d’une manette.

Deux petites fonctions mettent les mots à l’écran. printCentered fait le calcul une fois, pour que l’écran de titre et celui de fin de partie ne le fassent pas chacun de travers :

function drawOverText()
    printCentered(7, "GAME OVER")
    printCentered(9, "PRESS SPACE TO PLAY AGAIN")
end


function drawWaitingText()
    printCentered(6, "DODGE THE BLOCKS")
    printCentered(8, "ARROW KEYS TO MOVE")
    printCentered(10, "PRESS SPACE TO START")
end


function printCentered(row, text)
    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)
end

avec une constante de plus en haut :

local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

Enfin, la partie importante. Déplacez tout ce qui dessine hors de onOverlayUpdate, dans une fonction appelée drawGame, déplacez tout ce qui bouge dans une fonction appelée updatePlaying — toutes les deux sont dans le code complet ci-dessous — et laissez onOverlayUpdate ainsi :

function onOverlayUpdate()
    if state == "playing" then
        updatePlaying()
    end

    overlayClear()
    drawGame()
    if state == "waiting" then
        drawWaitingText()
    elseif state == "over" then
        drawOverText()
    end

    return OVERLAY_UPDATED
end

Enregistrez. Vous avez un jeu : un écran titre, une partie, une fin de partie, et un moyen de recommencer.

Relisez ces treize lignes, parce qu’elles ont la forme de tous les jeux que vous écrirez. Le monde ne bouge que tant que l’état vaut "playing", donc l’écran de fin de partie se fige avec les derniers blocs suspendus exactement là où ils étaient. Le monde est dessiné à chaque image quel que soit l’état, parce que l’image est la même dans les trois ; l’état décide seulement quels mots vont par-dessus. Et il y a exactement un endroit qui prend cette décision.

C’est ce que vous a acheté la variable state. Quand vous ajouterez une pause, vous ajouterez une branche à ce if et une ligne à onInputPressed, et rien d’autre dans le jeu n’aura besoin d’en savoir quoi que ce soit.

Le tout

Le voici, terminé. Si le vôtre ne correspond pas, la différence vaut la peine d’être trouvée.

dofile("Singe/Framework.singe")

local PLAYER_WIDTH  = 40
local PLAYER_HEIGHT = 8
local PLAYER_SPEED  = 4
local PLAYER_MARGIN = 4
local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5
local BLOCK_FASTER  = 0.05
local SPAWN_FRAMES  = 40
local START_LIVES   = 3
local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local playerY      = screenHeight - PLAYER_HEIGHT - PLAYER_MARGIN

local playerX    = (screenWidth - PLAYER_WIDTH) / 2
local goingLeft  = false
local goingRight = false
local blocks     = {}
local blockSpeed = BLOCK_SPEED
local spawnTimer = 0
local score      = 0
local lives      = START_LIVES
local state      = "waiting"


function drawGame()
    colorForeground(80, 255, 160)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH - 1, playerY + PLAYER_HEIGHT - 1)
    colorForeground(255, 90, 90)
    for i, block in ipairs(blocks) do
        overlayBox(block.x, block.y, block.x + BLOCK_SIZE - 1, block.y + BLOCK_SIZE - 1)
    end
    overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)
end


function drawOverText()
    printCentered(7, "GAME OVER")
    printCentered(9, "PRESS SPACE TO PLAY AGAIN")
end


function drawWaitingText()
    printCentered(6, "DODGE THE BLOCKS")
    printCentered(8, "ARROW KEYS TO MOVE")
    printCentered(10, "PRESS SPACE TO START")
end


function printCentered(row, text)
    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)
end


function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    block.y = -BLOCK_SIZE
    table.insert(blocks, block)
end


function startGame()
    playerX    = (screenWidth - PLAYER_WIDTH) / 2
    blocks     = {}
    blockSpeed = BLOCK_SPEED
    spawnTimer = 0
    score      = 0
    lives      = START_LIVES
    state      = "playing"
end


function updatePlaying()
    if goingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if goingRight then
        playerX = playerX + PLAYER_SPEED
    end
    if playerX < 0 then
        playerX = 0
    elseif playerX > screenWidth - PLAYER_WIDTH then
        playerX = screenWidth - PLAYER_WIDTH
    end

    spawnTimer = spawnTimer - 1
    if spawnTimer <= 0 then
        spawnBlock()
        spawnTimer = SPAWN_FRAMES
    end

    for i = #blocks, 1, -1 do
        local block = blocks[i]
        block.y = block.y + blockSpeed
        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) then
            table.remove(blocks, i)
            lives = lives - 1
            if lives == 0 then
                state = "over"
            end
        elseif block.y > screenHeight then
            table.remove(blocks, i)
            score      = score + 1
            blockSpeed = blockSpeed + BLOCK_FASTER
        end
    end
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        goingLeft = true
    elseif what == SWITCH_RIGHT then
        goingRight = true
    elseif what == SWITCH_BUTTON1 and state ~= "playing" then
        startGame()
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goingLeft = false
    elseif what == SWITCH_RIGHT then
        goingRight = false
    end
end


function onOverlayUpdate()
    if state == "playing" then
        updatePlaying()
    end

    overlayClear()
    drawGame()
    if state == "waiting" then
        drawWaitingText()
    elseif state == "over" then
        drawOverText()
    end

    return OVERLAY_UPDATED
end

Environ cent vingt lignes de code, et vous les avez toutes écrites quelques-unes à la fois.

Ce qui vient de se passer

Quelques morceaux méritent un second regard.

local blocks     = {}
local score      = 0


function startGame()
    score = 0
end

Les données sont local et les fonctions ne le sont pas. Ce sont deux choix délibérés, et opposés.

Les données sont local pour qu’elles appartiennent à ce fichier et que rien à l’extérieur ne puisse y mettre la main et les changer. Les fonctions sont globales pour qu’elles puissent s’appeler les unes les autres dans n’importe quel ordre : drawOverText est défini avant printCentered et l’appelle quand même, parce qu’un nom global est cherché au moment de l’appel, et qu’à ce moment-là le fichier entier a été lu. Rendez ces fonctions local et le fichier devra être trié pour que rien ne soit utilisé avant d’apparaître, et c’est une règle sur laquelle vous trébucheriez pendant tout le reste du livre. Trois des noms d’ici n’ont pas le choix du tout : onOverlayUpdate et les deux callbacks des commandes doivent être globaux, parce que c’est ainsi que Singe les trouve.

Dans le fichier, l’ordre est alphabétique, avec les trois callbacks à la fin. Ce n’est pas une règle de Lua. C’est pour que dans six mois vous puissiez trouver spawnBlock sans rien lire.

    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)

#text est la longueur d’une chaîne, en caractères. Vous avez rencontré # à la leçon six, pour compter les éléments d’une liste, et il fait le même travail ici. "GAME OVER" fait neuf caractères, donc sur un écran de soixante colonnes il commence à la colonne vingt-cinq, ce qui laisse vingt-cinq cellules d’espace à sa gauche et vingt-six à sa droite. math.floor jette la partie fractionnaire, parce que la colonne vingt-cinq et demie n’existe pas.

TEXT_COLUMNS calcule combien de cellules de caractère tiennent sur la largeur de l’écran. overlayPrint compte en cellules alors que tout le reste compte en pixels, donc la largeur de l’overlay est divisée par la largeur d’une cellule, et c’est overlayGetFontWidth qui vous la donne. Deux barres obliques plutôt qu’une, parce qu’une fraction de colonne n’est pas un endroit où afficher. Calculez-le de cette façon et le centrage reste juste quelle que soit la taille de l’overlay, ce qui est le quatrième point de la section Essayez.

    colorForeground(255, 90, 90)

colorForeground règle une couleur qui reste réglée. Ce n’est pas un argument passé à overlayBox ; c’est un interrupteur que vous basculez, et tout ce qui est dessiné ensuite sort dans cette couleur jusqu’à ce que vous le basculiez de nouveau. C’est pourquoi drawGame règle le vert, dessine le joueur, règle le rouge, puis dessine tous les blocs sans plus parler de couleur.

Ça n’affecte pas overlayPrint. La police de la console est copiée sur l’overlay telle quelle, dans ses propres couleurs, ce que l’entrée de overlayPrint dans la Référence dit en toutes lettres. Du texte en couleur demande une police chargée, et c’est la leçon dix-neuf.

Essayez

  1. Rendez-le plus facile, puis injuste. Changez PLAYER_WIDTH en 80 et jouez une partie. Puis changez-le en 12, la taille d’un bloc. Remarquez que vous n’avez eu à toucher ni au dessin ni à la collision, ni pour l’un ni pour l’autre.

  2. Accélérez plus vite. Changez BLOCK_FASTER de 0.05 à 0.5 et voyez combien de points vous arrivez à marquer. Puis essayez 0, et demandez-vous si le jeu vaut encore la peine d’être joué.

  3. Une vie en plus. Rendez une vie au joueur tous les dix points. Tout ce dont vous avez besoin est déjà dans updatePlaying, dans la branche qui ajoute au score.

  4. Jouez en plus grand. Lancez-le avec Singe -R --canvas=1280x720 dodge. Le jeu se met en page correctement, texte centré compris, parce qu’il a demandé au moteur la taille de l’écran. TEXT_COLUMNS l’a demandée aussi.

  5. Mettez-le en pause. Ajoutez un quatrième état, "paused". SWITCH_BUTTON2 doit faire passer de "playing" à "paused" et inversement, et rien ne doit bouger pendant la pause. Bien fait, ça tient en trois lignes et vous n’avez pas du tout à toucher à updatePlaying.

Cassez-le exprès

Allez dans spawnBlock et supprimez la ligne qui règle block.y, pour que la fonction se lise ainsi :

function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    table.insert(blocks, block)
end

Enregistrez, appuyez sur Espace, et Singe s’arrête avec ceci :

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:97: attempt to perform arithmetic on a nil value (field 'y')
stack traceback:
	dodge/dodge.singe:97: in function 'updatePlaying'
	dodge/dodge.singe:135: in function 'onOverlayUpdate'

La ligne 97, c’est block.y = block.y + blockSpeed. La plainte, c’est que quelque chose dans ce calcul n’est pas un nombre, et la partie entre parenthèses vous dit lequel : field 'y', c’est-à-dire le y à l’intérieur d’une table. Il n’a pas de valeur, parce que vous ne lui en avez jamais donné, et une chose sans valeur, en Lua, c’est nil.

Remarquez où est l’erreur et où est la faute. L’erreur est dans updatePlaying, à quarante lignes de spawnBlock, là où rien ne cloche du tout. updatePlaying est seulement le premier morceau de code assez malchanceux pour toucher aux dégâts. C’est le cas normal, pas l’exception, et remonter cette piste est un savoir-faire.

Remettez la ligne. Puis tournez la page, parce que la leçon suivante ne parle que de ça.

Ce que vous avez appris

  • Un jeu, c’est un monde qui change, un monde qu’on dessine, et une décision sur ce qu’on fait des deux — et ce sont trois morceaux de code séparés.

  • Les gestionnaires de commandes doivent noter ce qui est enfoncé ; la mise à jour doit décider ce que ça veut dire.

  • Une liste d’enregistrements est la forme de presque tous les mondes de jeu.

  • Retirez des choses d’une liste en la parcourant à rebours.

  • collideRects répond à la question de savoir si deux rectangles se chevauchent, et la version du moteur vaut mieux que la vôtre parce qu’elle est juste, qu’elle se lit bien, et qu’elle a une famille que vous reverrez.

  • Une seule variable state qui contient un mot vaut mieux que trois indicateurs vrai-ou-faux, et continue de mieux valoir à mesure que le jeu grandit.

  • Lancez une partie depuis une seule fonction qui remet tout à zéro, pour que la deuxième partie soit exactement comme la première.

  • Les nombres que vous voudrez peut-être régler ont leur place dans des constantes nommées en haut du fichier.

  • Construisez un jeu par étapes qui tournent chacune. Un programme qui n’a jamais marché est bien plus difficile à réparer qu’un programme qui marchait il y a cinq minutes.

La prochaine fois

Vous avez maintenant écrit assez de code pour faire des erreurs intéressantes. La leçon suivante est celle dont aucun livre pour débutants ne s’embarrasse : ce que disent vraiment les messages d’erreur de Singe, comment découvrir ce que contient réellement une variable au lieu de deviner, et comment couper un problème en deux jusqu’à ce qu’il n’ait plus nulle part où se cacher.

Leçon 8 : Quand ça tourne mal

La leçon terminée

Vous avez écrit un jeu. À partir de maintenant, vous passerez plus de temps à réparer des programmes qu’à en écrire, et ce n’est pas le signe que quelque chose ne va pas chez vous. C’est le métier. La différence entre quelqu’un qui aime programmer et quelqu’un qui abandonne n’est presque jamais le talent ; c’est de savoir s’il a appris à lire ce que l’ordinateur lui dit.

Cette leçon n’a donc rien de nouveau à construire. Ce sont les cinq messages que vous verrez le plus souvent pour le reste de votre vie, ce que chacun veut vraiment dire, et quatre manières de traquer l’erreur qui se cache derrière. Gardez ouvert dodge.singe de la leçon sept, parce que vous allez le casser exprès plusieurs fois.

Deux sortes d’arrêt

Singe s’arrête pour deux raisons différentes, et il le dit de deux manières différentes.

Quand le script ne veut même pas démarrer, vous obtenez cette forme :

Error running script:  dodge/dodge.singe:92: 'then' expected near 'spawnBlock'

Lua lit votre fichier entier avant d’en exécuter un seul mot, et ceci veut dire qu’il n’a pas pu comprendre ce qu’il a lu. Rien ne s’est exécuté du tout.

Quand le script a bien démarré mais que quelque chose a mal tourné plus tard, vous obtenez plutôt cette forme :

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:98: attempt to perform arithmetic on a nil value (global 'blockSped')
stack traceback:
	dodge/dodge.singe:98: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Le jeu tournait. Singe a appelé votre onOverlayUpdate, comme il le fait soixante fois par seconde, et cette fois l’appel n’est pas revenu.

Les deux formes contiennent les trois mêmes choses, et ce sont les trois choses que vous voulez : un fichier, une ligne et une plainte. Lisez-les dans cet ordre, à chaque fois.

Les numéros de ligne de cette leçon viennent du script terminé de la leçon sept. Si les vôtres sont décalés d’une ligne ou deux, votre fichier l’est aussi, et rien dans la lecture d’une erreur ne dépend de ce que le numéro corresponde.

Celles qui l’arrêtent avant qu’il démarre

Ce sont les faciles, et ce sont aussi celles qui font le plus mauvais effet, parce que l’écran reste noir et qu’il n’y a rien à regarder.

Allez dans updatePlaying et supprimez le mot then de la ligne if spawnTimer ⇐ 0 then. Enregistrez :

Error running script:  dodge/dodge.singe:92: 'then' expected near 'spawnBlock'

Lua est arrivé au bout de la ligne du if, voulait le mot then, et a trouvé à la place le début de la ligne suivante — qui est spawnBlock(), et c’est la partie near 'spawnBlock'. « Near » veut dire « c’est là que je m’en suis aperçu », et c’est en général la première chose après ce que vous avez oublié.

Maintenant, une plus méchante. Remettez then, et supprimez plutôt le end de la dernière ligne de spawnBlock. Enregistrez :

Error running script:  dodge/dodge.singe:148: 'end' expected (to close 'function' at line 58) near <eof>

La ligne 148 est la fin du fichier, juste après sa dernière ligne. La ligne 148 n’a rien qui cloche. Lua a lu jusqu’au bout — <eof> est son nom pour la fin d’un fichier — en attendant toujours un end qui n’est jamais venu, et à ce moment-là il avait avalé toutes les fonctions qui suivent spawnBlock comme si elles en faisaient partie.

La moitié utile de ce message, c’est (to close 'function' at line 58), qui est l’endroit où commence spawnBlock. Quand un message montre la fin du fichier, croyez ce qu’il dit entre parenthèses, pas le numéro de ligne. C’est aussi pour ça que l’indentation compte tant : un end manquant est presque invisible dans une suite de lignes, et saute aux yeux dès que tout ce qui est en dessous est décalé d’un cran de trop.

Deux autres à savoir reconnaître, parce que vous les rencontrerez toutes les deux cette semaine :

Error running script:  dodge/dodge.singe:41: unfinished string near '"GAME OVER)'

Un guillemet ouvert et jamais fermé, que vous avez rencontré à la leçon un.

Error running script:  dodge/dodge.singe:135: 'then' expected near '='

Celle-là, c’est if state = "playing" then. Un seul = donne une valeur à une variable, deux == posent une question, et Lua ne vous laisse pas donner une valeur à l’intérieur d’un if. La plainte a l’air étrange, et elle veut toujours dire la même chose.

Attempt to index a nil value

C’est celle que vous verrez le plus, et de loin.

Allez dans spawnBlock et faites une faute dans block sur la première ligne qui l’utilise, pour qu’elle se lise blocl.x = math.random(0, screenWidth - BLOCK_SIZE). Enregistrez, appuyez sur Espace :

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:60: attempt to index a nil value (global 'blocl')
stack traceback:
	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Indexer, c’est ce que fait le point. blocl.x veut dire « va dans la chose appelée blocl et trouve le x qui s’y trouve ». On ne peut faire ça qu’avec une table.

Nil, c’est ainsi que Lua appelle un nom derrière lequel il n’y a rien. Vous ne l’avez pas beaucoup vu parce que vous avez pris soin de donner une valeur à tout, mais chaque nom dont vous ne vous êtes jamais servi vaut déjà nil, et taper un nom de travers en invente un tout neuf.

Le message entier dit donc : vous avez utilisé un point sur quelque chose qui n’existe pas.

La partie entre parenthèses est le cadeau. global 'blocl' est le nom exact de la chose qui était vide. Cherchez-le dans votre fichier. S’il n’apparaît qu’une fois, c’est une faute d’orthographe, et vous l’avez trouvée en dix secondes.

Le mot avant le nom vous dit où Lua l’a cherché :

  • global — un nom qui n’a de local devant lui nulle part.

  • local — un nom que vous avez déclaré avec local dans la fonction où vous êtes.

  • field — un nom après un point, comme le y de block.y.

  • upvalue — un local venu de plus loin, que cette fonction peut voir, et c’est ce que sont toutes les variables de dodge.singe, puisqu’elles sont déclarées en haut du fichier et utilisées à l’intérieur des fonctions.

field est l’autre cause courante, et ce n’est pas du tout une faute d’orthographe. Si vous avez écrit block.hit.when sans jamais avoir rempli block.hit, vous obtenez attempt to index a nil value (field 'hit'). Le point qui échoue, c’est le deuxième. Lua vous dit lequel en le nommant.

Attempt to call a nil value

Remettez blocl comme il faut. Maintenant, faites une faute dans une fonction du moteur : dans drawGame, changez overlayPrint en overlayPirnt. Enregistrez :

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:36: attempt to call a nil value (global 'overlayPirnt')
stack traceback:
	dodge/dodge.singe:36: in function 'drawGame'
	dodge/dodge.singe:140: in function 'onOverlayUpdate'

Même nil, autre crime. Appeler, c’est ce que font les parenthèses, et on ne peut faire ça qu’avec une fonction. Il n’y a pas de fonction appelée overlayPirnt, donc overlayPirnt vaut nil, donc les parenthèses n’ont rien à appeler.

Ça arrive pour quatre raisons, de la plus fréquente à la plus rare :

  1. Vous avez fait une faute dans le nom d’une de vos propres fonctions.

  2. Vous avez fait une faute dans le nom d’une de celles de Singe. Rien dans le moteur ne vérifie votre orthographe au chargement du fichier, donc un nom du moteur mal écrit n’est qu’un nom de plus qui se trouve être vide, et ça ne vous coûte rien tant que la ligne ne s’exécute pas.

  3. La fonction n’existe pas du tout dans Singe — c’était une supposition raisonnable, et les suppositions raisonnables sont fausses à peu près une fois sur deux. La liste des fonctions de la Référence est le seul moyen d’en être sûr.

  4. Vous l’avez rendue local et vous l’avez appelée depuis un endroit situé au-dessus de sa déclaration. C’est exactement pour ça que les fonctions de dodge.singe sont globales.

Il existe une version bien pire de cette erreur, et vous l’avez rencontrée à la leçon un sans le savoir : écrivez mal le nom d’un callback et vous n’obtenez aucun message du tout. onOverlayUpdated n’est pas une erreur. C’est une fonction parfaitement correcte dont Singe n’a jamais entendu parler et qu’il n’appellera jamais, alors l’écran reste noir et rien ne se plaint. Quand toute une fonctionnalité ne fait absolument rien, soupçonnez le nom.

Attempt to perform arithmetic on a nil value

Remettez overlayPrint. Dans updatePlaying, faites une faute dans blockSpeed sur la ligne de chute, pour qu’elle se lise block.y = block.y + blockSped :

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:98: attempt to perform arithmetic on a nil value (global 'blockSped')
stack traceback:
	dodge/dodge.singe:98: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

L’arithmétique, c’est +, -, * et /. On ne peut pas ajouter rien à un nombre. Là encore, les parenthèses nomment la chose vide, et là encore la cause la plus courante est une faute de frappe — mais celle-ci a une seconde cause qu’il vaut la peine de connaître, parce qu’elle est plus difficile à voir.

Une variable à laquelle vous n’avez jamais donné de nombre vaut nil, pas zéro. Si vous ajoutez un meilleur score au jeu et écrivez local hiScore en haut sans = 0, elle contient nil jusqu’à ce que quelque chose la remplisse, et le premier hiScore + score arrête le jeu. Lua ne fait pas partir les nombres de zéro pour vous. C’est vous qui les faites partir de zéro.

Deux proches parents, avec la même cause et le même remède :

dodge/dodge.singe:37: attempt to concatenate a nil value (upvalue 'hiScore')

.. qui joint une chaîne à quelque chose qui n’est pas là. Vous verrez celle-là chaque fois que vous afficherez un score que vous avez oublié de remplir — ici, hiScore ajouté à la ligne du score dans drawGame, qui est la ligne 37 maintenant que local hiScore se trouve au-dessus.

dodge/dodge.singe:105: attempt to compare nil with number

Ça, c’est if score > hiScore then, placé sous state = "over" pour garder le meilleur score à la fin d’une partie, sans rien dans hiScore. Remarquez que ce message ne nomme rien entre parenthèses. Quand Lua ne peut pas vous dire quel côté était vide, la section après la suivante vous montre comment le découvrir.

Un argument du mauvais type

Tous les messages jusqu’ici venaient de Lua. Celui-ci vient de Singe, et il a l’air complètement différent, alors ça vaut la peine de le rencontrer exprès.

Supposez que vous vouliez voir ce que contient blocks, et que vous essayiez de l’afficher. Ajoutez cette ligne dans drawGame, sous le score :

    overlayPrint(1, 3, blocks)
37:overlayPrint:  Argument 3 must be a string.

Pas de nom de fichier, pas de trace de pile, aucun attempt to quoi que ce soit. Une plainte du moteur commence par le numéro de ligne, puis le nom de la fonction qui a refusé, puis ce qu’elle voulait. Ici, on a donné à overlayPrint une table là où il lui faut du texte, et elle s’est arrêtée plutôt que de dessiner quelque chose qui n’a pas de sens.

Le message cousin compte au lieu de vérifier :

34:overlayBox:  Expected 4 argument(s), got 3.

C’est un overlayBox auquel il manque un coin. Le curieux argument(s) est celui du moteur, pas une faute de frappe de votre part.

Quand vous obtenez l’un de ces messages, l’entrée de cette fonction dans la Référence est la réponse, et ça vous prendra une minute. Chaque entrée donne les arguments dans l’ordre, avec ce que chacun doit être. Singe les vérifie parce que l’autre possibilité, c’est un jeu qui tourne dix minutes puis dessine n’importe quoi.

Découvrir ce qu’il y a vraiment dedans

La moitié du débogage, ce n’est pas du tout lire des erreurs. C’est le cas où rien ne plante et où rien ne marche : des blocs qui n’apparaissent jamais, un joueur qui refuse de bouger, un score coincé à zéro. Pour ça, il vous faut voir à l’intérieur du jeu en marche, et il y a deux manières de le faire.

La première, c’est debugPrint, qui écrit une ligne dans le terminal depuis lequel vous avez lancé Singe. Prenez la ligne à laquelle vous ne comprenez rien et mettez-en un au-dessus :

    debugPrint("blocks " .. #blocks .. ", timer " .. spawnTimer)

Vous regardez maintenant ce qui est réellement là au lieu de ce que vous êtes sûr d’y trouver, et c’est dans cet écart que vivent les bugs. Affichez playerX de la même façon et vous verrez aussi la vérité à son sujet : il s’affiche 160.0, pas 160, parce qu’une division avec / donne toujours en Lua un nombre avec une partie fractionnaire, même quand cette partie vaut zéro.

Deux choses vont vous mordre. La première, c’est que debugPrint exige du texte ou un nombre ; donnez-lui autre chose et il arrête le jeu comme l’a fait overlayPrint. debugPrint(blocks) ne vous montrera pas une liste, et debugPrint("left " .. goingLeft) tout en haut de la fonction updatePlaying ne vous montrera pas non plus un true ou un false :

dodge/dodge.singe:78: attempt to concatenate a boolean value (upvalue 'goingLeft')

tostring est le remède. Il prend absolument n’importe quoi et vous en donne du texte, donc tostring(goingLeft) vaut "true" ou "false", et la ligne marche.

La seconde, c’est que onOverlayUpdate tourne soixante fois par seconde, donc un debugPrint à l’intérieur affiche soixante lignes par seconde et vous ne pouvez en lire aucune. La Référence le dit dans son entrée : l’appel ne coûte pas cher, mais rien ne le freine.

Avant toute chose, mettez un interrupteur devant chaque ligne de débogage que vous ajoutez, pour pouvoir couper le bruit sans avoir à les traquer de nouveau :

local DEBUG = true


function debugLog(text)
    if DEBUG then
        debugPrint(text)
    end
end

Chaque debugLog du jeu obéit à ce seul true. Changez-le en false et le jeu se tait ; remettez-le et tout revient.

Ensuite, affichez quelque chose quand il se passe quelque chose plutôt qu’à chaque image :

            debugLog("hit at y " .. math.floor(block.y) .. ", lives now " .. lives)

Ou affichez avec un minuteur, décompté exactement comme l’apparition des blocs :

    reportTimer = reportTimer - 1
    if reportTimer <= 0 then
        debugReport()
        reportTimer = REPORT_FRAMES
    end

Le dossier learn contient le tout sous le nom 08-when-it-goes-wrong.singe : c’est le jeu de la leçon sept avec un rapport environ toutes les deux secondes, une ligne quand vous êtes touché, et une ligne quand la partie se termine.

La seconde manière de voir à l’intérieur, c’est de le mettre à l’écran, ce qui vaut mieux pour tout ce qui change à chaque image, parce que soixante lignes par seconde dans un terminal, ça ne sert à rien, alors qu’un nombre qui défile dans le coin se surveille facilement :

    if DEBUG then
        overlayPrint(1, 3, "BLOCKS " .. #blocks .. "   PLAYER " .. playerX)
    end

Couper le problème en deux

Quand vous n’arrivez pas à voir laquelle de vingt lignes est fausse, arrêtez de regarder et commencez à retirer.

Mettez deux tirets au début d’une ligne et Lua ignore tout le reste de la ligne. C’est un commentaire, et on s’en sert d’habitude pour se laisser des notes, mais le meilleur usage est celui-ci :

    -- overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)

Mettez en commentaire la moitié de drawGame et lancez. Si le problème est toujours là, il est dans la moitié que vous avez gardée. S’il a disparu, il est dans la moitié que vous avez retirée. Remettez cette moitié et coupez-la en deux. Vingt lignes demandent cinq tours de ce petit jeu, et chaque tour, c’est un enregistrement et un coup d’œil.

Ça marche pour autre chose que des lignes. Mettez en commentaire le corps de updatePlaying et les blocs arrêtent de bouger, ce qui vous dit si ce que vous traquez est dans le déplacement ou dans le dessin. Mettez en commentaire la branche de collideRects et voyez si le jeu arrête de planter. Vous n’essayez de rien réparer pendant que vous faites ça. Vous essayez de découvrir où le problème n’est pas.

Faire le tour plus vite

Tout ceci repose sur la possibilité d’essayer quelque chose en deux secondes, et c’est à ça que sert -R. Vous vous en servez depuis la leçon un ; voici ce qu’il fait vraiment, et ça vaut la peine de le savoir maintenant que vous allez vous appuyer dessus.

Singe surveille chaque fichier de script que votre jeu a chargé. Quand vous en enregistrez un, le jeu repart du début : tout ce que le script a fabriqué est jeté et votre fichier est exécuté à neuf, dans le temps qu’il faut pour lire le fichier plutôt que dans celui qu’il faut pour démarrer le moteur. F5 fait la même chose à la demande, sans rien enregistrer.

Une touche que vous gardez enfoncée pendant un rechargement est ignorée jusqu’à ce que vous la relâchiez, donc le joueur ne partira pas tout seul après un rechargement.

Les deux sortes d’arrêt se comportent différemment ici, et c’est utile de savoir laquelle vous avez sous les yeux sans lire le message. Un script qui ne compile pas est signalé, et Singe y survit : la fenêtre reste ouverte et vide, le fichier reste surveillé, et enregistrer la correction ramène le jeu. Un plantage à l’intérieur d’un callback — tous les messages attempt to, et les plaintes du moteur sur les arguments — fait tomber Singe, et vous le relancez à la main.

Lire une trace de pile

Les lignes sous stack traceback: sont la liste des fonctions qui étaient en cours quand tout s’est arrêté, la plus intérieure en premier. Voici de nouveau celle de blocl :

	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Lisez-la de bas en haut et c’est une phrase. Singe a appelé onOverlayUpdate. À la ligne 136, onOverlayUpdate a appelé updatePlaying. À la ligne 92, updatePlaying a appelé spawnBlock. À la ligne 60, spawnBlock a abandonné.

La ligne du haut, c’est l’endroit où ça a cassé. Les lignes en dessous, c’est le chemin pour y arriver, et c’est ce qu’il vous faut quand la ligne du haut a l’air innocente. Une fonction qui ajoute un nombre à block.y n’a rien de faux ; une fonction qui a mis un bloc dans la liste sans y, si. Seule la piste relie les deux, et la piste est affichée pour vous à chaque fois, sans exception.

L’habitude

Tout ce qui précède, c’est de la technique. Voici l’habitude, et elle compte davantage :

Changez une chose. Lancez. Regardez ce qui s’est passé.

Quand quelque chose refuse de marcher, la tentation est de changer quatre choses à la fois, parce que l’une d’elles sera forcément la bonne. Faites ça et ça arrête de marcher d’une nouvelle façon, et vous ne savez plus laquelle des quatre en est responsable, ni si deux d’entre elles s’annulent. Vous avez agrandi le problème et vous l’avez mieux caché.

Un changement. Lancez. Regardez. Ça a l’air plus lent. C’est la méthode la plus rapide qui existe, et tous les programmeurs expérimentés que vous rencontrerez font comme ça, exactement pour la raison que vous êtes sur le point de découvrir.

Essayez

  1. Rencontrez-les toutes. Faites exprès chacune des cinq erreurs de cette leçon dans dodge.singe, une à la fois, et lisez le message avant de corriger. Elles ne vous feront plus jamais peur.

  2. Surveillez les apparitions. Mettez dans spawnBlock un debugPrint qui affiche le x du nouveau bloc. Jouez trente secondes, puis regardez les nombres. Sont-ils répartis sur tout l’écran, ou préfèrent-ils un côté ?

  3. Coupez-le. Changez DEBUG en false dans le script de la leçon, et vérifiez par vous-même que rien ne s’affiche et que le jeu n’a pas changé.

  4. Un bug sans erreur. Dans updatePlaying, changez if spawnTimer ⇐ 0 then en if spawnTimer == 0 then, qui a l’air de vouloir dire la même chose. Lancez et commencez une partie. Il n’y a pas d’erreur, rien ne plante, et pas un seul bloc ne tombe, si bien que vous ne pouvez même pas perdre. Mettez un debugLog dans spawnBlock, ajoutez spawnTimer à la première ligne qu’affiche debugReport, et rejouez. Déduisez de ce qu’ils disent, et de ce que l’un d’eux ne dit jamais, pourquoi == était la mauvaise question à poser.

  5. Cassez le nom d’un callback. Renommez onInputPressed en onInputPress et lancez. Aucune erreur ne s’affiche, rien ne plante, le joueur refuse de bouger, et Espace ne lance pas de partie. Puis expliquez-vous pourquoi c’est l’erreur la plus dangereuse de cette leçon.

Ce que vous avez appris

  • Les erreurs ont un fichier, une ligne et une plainte. Lisez-les dans cet ordre.

  • Error running script veut dire que rien ne s’est exécuté ; la forme avec une trace de pile veut dire que ça tournait et que ça s’est arrêté.

  • nil est un nom derrière lequel il n’y a rien, et il est derrière la plupart des messages d’erreur que vous verrez jamais.

  • Le mot entre parenthèses nomme la chose vide, et dit si c’était une variable globale, une variable locale, un champ ou une upvalue.

  • Un end manquant est signalé à la fin du fichier, et les parenthèses vous disent où est vraiment l’erreur.

  • Les plaintes du moteur ont un autre air : un numéro de ligne, un nom de fonction, et ce qu’elle voulait à la place.

  • debugPrint vous montre ce que contient vraiment une variable. tostring rend n’importe quoi affichable, et un interrupteur comme DEBUG coupe le bruit.

  • Mettez une moitié en commentaire avec -- pour découvrir dans quelle moitié est le problème.

  • Un callback mal nommé ne produit aucune erreur, ce qui le rend pire qu’un callback qui en produit une.

  • Changez une chose, lancez, regardez.

La prochaine fois

C’est la fin de la première partie. Vous savez écrire un jeu, et maintenant vous savez en réparer un, ce qui veut dire que tout ce qui suit est un ajout et non une fondation. La deuxième partie commence par remplacer ces boîtes de couleur par de vraies images, et à partir de là, le jeu que vous construisez commence à ressembler à un jeu auquel quelqu’un d’autre aurait envie de jouer.

Leçon 9 : Des images

La leçon terminée

Tout ce que vous avez dessiné jusqu’ici, vous l’avez dessiné avec des boîtes, des lignes et le texte tout simple du moteur. C’était voulu : huit leçons sans graphismes, c’étaient huit leçons où rien ne pouvait mal tourner à part votre programme. Maintenant, les boîtes deviennent un vaisseau et des rochers.

Une image que le moteur dessine sur l’overlay s’appelle un sprite. Cette leçon les charge, les dessine, les mesure, les met dans le bon ordre, et fait défiler une image qui contient plusieurs images d’une animation. À la fin, le jeu de la leçon sept ressemble à un jeu.

Le kit graphique

Vous n’avez rien à dessiner. Ce livre est livré avec un petit dossier de graphismes, et tout ce qui se trouve dans cette leçon et la suivante s’en sert.

Trouvez le dossier art fourni avec le livre et copiez le dossier entier dans le dossier de cette leçon, à côté de votre script. Vous devriez obtenir ceci :

singe/                 <- votre dossier de travail
    Singe/
    data/
    rocks/
        rocks.singe
        art/
            spaceship.png
            asteroid.png
            bullet.png
            star.png
            walk.png
            shoot.wav
            boom.wav

Vos graphismes vont dans le dossier propre à votre jeu, et le dossier Singe du moteur reste où il est, dehors, dans le dossier de travail. Ça compte dans un instant, parce que c’est ce qui décide de la manière dont vous nommez un fichier quand vous le chargez.

Le dossier Singe est celui que le moteur a extrait pour vous lors de votre tout premier lancement, à la leçon un. Ça vaut la peine de savoir ce qu’il contient, parce que ces fichiers sont à vous aussi, et que tous les lecteurs de ce livre les ont :

  • Singe/click.wav — un clic bref, dont le menu du moteur se sert pour son test du son.

  • Singe/FreeSansBold.ttf — une police TrueType, pour la leçon dix-neuf.

  • Singe/menuIntro.flac — la musique que joue le menu du moteur. Vous vous en servirez à la leçon dix.

  • Singe/menuBackground.mkv — une vidéo, pour la leçon quatorze.

  • Singe/DragonModel.glb et Singe/SingeText.glb — deux modèles 3D, pour la leçon vingt-trois.

  • Singe/missing.png — l’image que dessine le moteur quand un jeu en demande une qu’il ne trouve pas.

Les images du kit sont petites exprès. Le vaisseau fait 32 pixels de large et 24 de haut, un rocher fait 24 sur 24, un tir 4 sur 10, et une étoile 8 sur 8. Ça a l’air minuscule jusqu’à ce que vous vous rappeliez la taille réelle de l’écran, et c’est la prochaine chose à mettre au clair.

La taille de l’écran

Sans vidéo à lire, Singe donne à votre jeu un canevas de 720 pixels de large et 480 de haut, et la surface sur laquelle vous dessinez — l'overlay — en fait la moitié dans chaque direction : 360 sur 240. Singe l’étire pour remplir la fenêtre à votre place, si bien qu’un vaisseau de 32 pixels fait environ un dixième de la largeur de l’écran, ce qui est à peu près l’allure d’un vaisseau dans un jeu d’arcade.

N’écrivez jamais 360 et 240 dans votre programme. Demandez :

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()

Ces deux-là donnent la taille de l’overlay, et un jeu qui demande est un jeu qui marche encore quand quelqu’un le lance à une autre taille.

Il y a une chose qui ne compte pas dans ces pixels : overlayPrint, de la leçon un, compte en cellules de caractère. Chaque cellule fait 6 pixels de large et 13 de haut, donc un overlay de 360 sur 240 fait 60 colonnes sur 18 lignes de texte. Les sprites sont en pixels, overlayPrint est en cellules, et confondre les deux vaut bien un après-midi de perplexité si vous le laissez faire.

Une image à l’écran

Commencez un nouveau fichier à côté de votre dossier art et tapez ceci.

dofile("Singe/Framework.singe")

local ship = spriteLoad(DIR .. "art/spaceship.png")


function onOverlayUpdate()
    overlayClear()
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(ship)
end

Lancez-le. Un petit vaisseau bleu se tient près du milieu d’un écran noir, la pointe vers le haut.

Ce qui vient de se passer

Quatre choses nouvelles, une par une.

local ship = spriteLoad(DIR .. "art/spaceship.png")

spriteLoad lit un fichier image sur le disque, le décode, et garde l’image en mémoire. Ce qu’il vous rend n’est pas l’image. C’est un handle : un simple nombre, un ticket d’entrée, la manière qu’a le moteur de dire « celle-là ». Vous redonnez ce nombre au moteur chaque fois que vous voulez faire quelque chose avec l’image, et vous n’avez jamais besoin de savoir ce qu’est ce nombre, ni de vous en soucier.

Affichez-le si ça vous chante — debugPrint(ship), de la leçon huit, vous montrera un petit nombre — mais vous n’avez pas à raisonner sur le nombre lui-même, et rien dans votre programme ne doit jamais dépendre de ce qu’il se trouve être. La seule règle, c’est de le garder quelque part où vous pourrez le retrouver, et c’est exactement à ça que sert une variable.

DIR est nouveau aussi, et il règle un problème que crée la disposition dont vous vous servez depuis la leçon un. Singe cherche les fichiers par rapport au dossier où vous vous trouviez quand vous l’avez lancé, pas par rapport à votre script. Vous le lancez depuis votre dossier de travail, donc un simple art/spaceship.png envoie le moteur chercher singe/art/spaceship.png, dehors, à côté du dossier Singe. Vos graphismes ne sont pas là. Ils sont un niveau plus bas, dans rocks/art/spaceship.png, avec votre script.

DIR comble cet écart. C’est un morceau de texte qui contient le dossier où se trouve votre script, avec la barre oblique déjà au bout, donc DIR .. "art/spaceship.png" — deux morceaux de texte joints avec .., ce que vous faites depuis la première partie — nomme l’image correctement quelle que soit la manière dont le jeu a été lancé, et continue de la nommer correctement quand vous déplacez le dossier entier ailleurs.

DIR est l’un des noms que définit Singe/Framework.singe, et c’est à ça que sert la ligne dofile en haut de votre script. Vous avez rencontré cette ligne, et ce qu’elle contient, à la leçon sept, et c’est le moment où elle gagne sa place : sans elle, pas de DIR, et sans DIR, le moteur ne trouve pas votre vaisseau.

Utilisez DIR pour chaque fichier que charge votre jeu, d’ici à la fin du livre.

    spriteDraw(ship, 160, 100)

Ça dessine le sprite qui a ce handle, à cette position. Comme tous les appels de dessin, ça ne marche qu’à l’intérieur de onOverlayUpdate.

La position est le coin supérieur gauche de l’image, pas son milieu. Demandez (160, 100) et le pixel le plus en haut à gauche du vaisseau atterrit là, et le reste pend vers le bas et vers la droite. Ça piège tout le monde une fois, en général en essayant de centrer quelque chose qui sort trop bas et trop à droite, de la moitié de sa propre taille.

Si vous préférez donner le milieu, dites-le :

    spriteDraw(ship, 160, 100, true)

Un quatrième argument true veut dire « prends ce point comme centre ». Les deux formes sont dans l’entrée de spriteDraw dans la Référence, avec deux autres qui étirent l’image dans un rectangle.

function onShutdown()
    spriteUnload(ship)
end

onShutdown est un callback, comme onOverlayUpdate et les deux callbacks des commandes de la leçon trois. Le moteur l’appelle une fois, quand votre jeu se termine. C’est là que vous rendez ce que vous avez pris : spriteUnload libère l’image et jette le handle.

À strictement parler, vous pourriez vous en passer. Le moteur libère tout ce que votre script a chargé quand le jeu se termine, donc un spriteUnload oublié n’est pas une fuite. Écrivez-le quand même. Ça coûte une ligne, ça dit ce que possède votre programme, et dans une minute vous verrez le cas où oublier de décharger compte vraiment.

Un avertissement à propos de ce handle : une fois que vous avez déchargé un sprite, le nombre est mort. Dessiner avec ne dessine pas rien, ça termine votre jeu sur une erreur.

La transparence, et pourquoi c’est un PNG

Le vaisseau est un triangle avec deux ailerons. Le fichier où il vit est un rectangle, 32 sur 24, parce que tout fichier image est un rectangle. Alors, qu’est-il arrivé aux coins ?

Ils sont transparents. Un PNG peut dire, pour chaque pixel, à quel point il est opaque, et les images du kit disent « pas là du tout » pour chaque pixel en dehors de la forme. Singe le respecte, donc le fond noir se voit à travers les coins, et le vaisseau a un contour au lieu d’une boîte autour de lui.

C’est la raison pour laquelle le kit est en PNG et pas en JPEG. Un JPEG ne peut pas du tout stocker de transparence — il vous donnerait le vaisseau dans une boîte grise — et il bave aussi sur les bords nets, ce dont de petits graphismes ont le moins besoin. Pour les graphismes d’un jeu, PNG. Pour une photo qui remplit tout l’écran et n’a aucune partie transparente, le JPEG convient et pèse bien moins lourd. L’entrée de spriteLoad dans la Référence liste tous les formats que Singe sait lire, et il y en a beaucoup.

Essayez vous-même : changez le noir en autre chose en dessinant une boîte derrière le vaisseau avant de dessiner le vaisseau. Les coins montreront ce qu’il y a derrière eux, et c’est tout l’intérêt.

Ne chargez pas pendant que vous dessinez

Voici l’erreur que cette section existe pour empêcher. Elle a l’air parfaitement raisonnable :

function onOverlayUpdate()
    overlayClear()
    local ship = spriteLoad(DIR .. "art/spaceship.png")
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end

Lancez ça et ça marche. Ça dessine le vaisseau. Rien ne se plaint. Vous n’auriez aucune raison de penser que quelque chose cloche.

onOverlayUpdate tourne environ soixante fois par seconde. Ça fait soixante nouvelles copies du vaisseau chargées en mémoire chaque seconde, trois mille six cents par minute, et pas une seule jamais déchargée. Le jeu tourne magnifiquement pendant deux minutes, ralentit, puis la machine manque de mémoire et il meurt. Pire, il meurt pendant la démo et pas pendant que vous testiez.

La règle : chargez une fois, dessinez souvent. Charger est lent et prend de la mémoire. Dessiner est rapide et n’en prend pas. Donc spriteLoad va en haut de votre fichier, en dehors de toute fonction, où il s’exécute une seule fois, au démarrage du script.

Ça ne concerne pas que les sprites. Chaque somethingLoad du moteur fonctionne ainsi — les sons à la leçon dix, les polices à la leçon dix-neuf, les modèles à la leçon vingt-trois. Si vous vous surprenez à taper Load dans une fonction qui s’exécute à chaque image, arrêtez-vous et sortez-le de là.

Quelle taille fait-il ?

Vous savez que le vaisseau fait 32 sur 24 parce que ce livre vous l’a dit. Votre programme, lui, ne le sait pas, et il ne devrait pas avoir à le savoir. Demandez :

local shipWidth  = spriteGetWidth(ship)
local shipHeight = spriteGetHeight(ship)

Vous pouvez maintenant garder le vaisseau à l’écran, parce que la position la plus à droite où il peut se tenir est screenWidth - shipWidth, et le mettre au milieu, parce que le milieu est (screenWidth - shipWidth) / 2. Aucune de ces lignes ne contient de nombre qui devrait changer si quelqu’un redessinait le vaisseau un peu plus grand.

Ces deux fonctions donnent la taille telle que le sprite serait dessiné en ce moment. Si un jour vous mettez un sprite à l’échelle ou le faites tourner, avec spriteScale ou spriteRotate, la réponse change en conséquence. C’est en général ce que vous voulez, et ça vous surprendra exactement une fois.

L’ordre de dessin

Les sprites ne se mélangent pas. Ce qui vient après couvre ce qui vient avant, pixel par pixel, exactement comme des découpes de papier collées sur un mur. L’ordre de vos appels à spriteDraw est donc l’ordre de l’arrière vers l’avant :

    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()

Les étoiles sont tout au fond, donc elles sont posées en premier. Le vaisseau est devant tout ce qui se trouve sur l’aire de jeu. Le score est par-dessus tout ça. Faites-le à l’envers et votre vaisseau si soigneusement dessiné passe la partie caché derrière le champ d’étoiles, et aucune erreur ne vous le dit — juste un vaisseau que vous ne voyez pas.

overlayClear vient toujours en premier, avant tout ça. Dessiner ne remplace jamais, ça ne fait que couvrir, donc l’image commence vide à chaque fois.

Les images d’une animation

Ouvrez art/walk.png dans n’importe quelle visionneuse d’images. Ce n’est pas l’image d’une personne. C’est l’image de quatre personnes, côte à côte : la même silhouette à quatre moments d’une marche, chacune large de 24 pixels, dans une bande de 96 de large.

Une seule image qui contient plusieurs images d’une animation, c’est une planche de sprites (« sprite sheet »), et c’est ainsi que presque toute l’animation 2D est stockée. Un fichier, un chargement, un handle, et le jeu choisit quelle tranche dessiner.

Créez un second fichier, walk.singe, à côté du premier :

dofile("Singe/Framework.singe")

local walk      = spriteLoadFrames(4, DIR .. "art/walk.png")
local walkFrame = 1
local walkTick  = 0
local walkX     = 0


function onOverlayUpdate()
    overlayClear()
    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end
    walkX = walkX + 1
    if walkX > overlayGetWidth() then
        walkX = -spriteFrameWidth(walk)
    end
    spriteDrawFrame(walk, walkX, 100, walkFrame)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(walk)
end

Lancez-le avec Singe rocks/walk.singe. Une petite silhouette traverse l’écran d’un pas régulier, disparaît par le bord droit, et revient par la gauche.

spriteLoadFrames, c’est spriteLoad avec une chose de plus à dire : combien d’images contient la bande. Le nombre vient en premier, avant le nom du fichier, ce qui est le contraire de ce que devinent la plupart des gens. Il divise la largeur de l’image par ce nombre et retient les tranches. Quatre images dans une bande de 96 pixels, ça fait quatre images de 24 pixels de large. Trompez-vous de nombre — disons 3 — et vous obtenez trois tranches de 32 pixels, qui montrent chacune des morceaux de deux silhouettes, ce qui est une manière mémorablement ridicule de découvrir que vous avez tapé le mauvais nombre.

spriteDrawFrame dessine une tranche. Il prend le handle, l’endroit où la mettre, et quelle image, dans cet ordre, et les images sont numérotées à partir de 1 : l’image 1 est la silhouette la plus à gauche et l’image 4 la plus à droite.

Méfiez-vous de ce 1. Ailleurs dans la famille des sprites — spriteSetFrame et spriteGetFrame — les images sont numérotées à partir de 0. C’est un accident de l’histoire, les deux sont dans la Référence, et ce livre utilise spriteDrawFrame et compte à partir de 1.

spriteFrameWidth donne la largeur d’une image, 24 ici, plutôt que les 96 de la bande entière. spriteFrameHeight est son partenaire. Quand vous voulez savoir quelle largeur fait une tranche d’une planche, ce sont ces deux-là qu’il faut interroger, et pas spriteGetWidth.

Le numéro d’image est un nombre dans une variable comme un autre, donc la marche, c’est de l’arithmétique :

    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end

Comptez les images du jeu qui passent. Toutes les huit, passez à l’image suivante de la bande, et après la quatrième, revenez à la première. Soixante images par seconde divisées par huit, ça fait entre sept et huit pas par seconde, ce qui, pour un cycle de quatre images, donne une marche vive mais crédible. Changez le 8 et vous changez la vitesse : plus grand, c’est plus lent.

Vous vous demandez peut-être pourquoi compter, alors que le moteur a spritePlay pour jouer une animation à votre place. Il l’a, et pour un GIF animé c’est la bonne réponse, parce qu’un GIF porte dans le fichier la durée de chacune de ses images. Une simple bande comme walk.png ne porte aucune durée, alors le moteur la joue aussi vite qu’il en a le droit — cent images par seconde, vingt-cinq cycles de marche complets chaque seconde, un flou. Quand les images viennent d’une bande, faites le compte vous-même.

Le jeu reçoit ses graphismes

Maintenant, assemblez le tout. Le jeu de la leçon sept dirigeait une boîte le long du bas de l’écran et faisait tomber d’autres boîtes dessus. Chaque boîte devient une image, et pendant que vous y êtes, le vaisseau reçoit de quoi tirer.

Les changements forment un tout, alors voici le script complet. Il est plus long que tout ce que vous avez écrit, et il ne contient rien que vous n’ayez déjà rencontré.

dofile("Singe/Framework.singe")

local SHIP_SPEED  = 3
local SHOT_SPEED  = 6
local ROCK_COUNT  = 6
local STAR_COUNT  = 40
local START_LIVES = 3
local HIT_SCORE   = 10

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")
local rockSprite = spriteLoad(DIR .. "art/asteroid.png")
local shotSprite = spriteLoad(DIR .. "art/bullet.png")
local starSprite = spriteLoad(DIR .. "art/star.png")

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local shipWidth    = spriteGetWidth(shipSprite)
local shipHeight   = spriteGetHeight(shipSprite)
local rockWidth    = spriteGetWidth(rockSprite)
local rockHeight   = spriteGetHeight(rockSprite)
local shotWidth    = spriteGetWidth(shotSprite)
local shotHeight   = spriteGetHeight(shotSprite)

local shipX   = (screenWidth - shipWidth) / 2
local shipY   = screenHeight - shipHeight - 4
local goLeft  = false
local goRight = false
local rocks   = {}
local shots   = {}
local stars   = {}
local score   = 0
local lives   = START_LIVES
local over    = false


function drawHud()
    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(50, 1, "LIVES " .. lives)
    if over then
        overlayPrint(25, 8, "GAME OVER")
        overlayPrint(17, 10, "PRESS 1 TO PLAY AGAIN")
    end
end


function drawRocks()
    for _, rock in ipairs(rocks) do
        spriteDraw(rockSprite, rock.x, rock.y)
    end
end


function drawShots()
    for _, shot in ipairs(shots) do
        spriteDraw(shotSprite, shot.x, shot.y)
    end
end


function drawStars()
    for _, star in ipairs(stars) do
        spriteDraw(starSprite, star.x, star.y)
    end
end


function newRock(rock)
    rock.x     = math.random(0, screenWidth - rockWidth)
    rock.y     = -rockHeight - math.random(0, 160)
    rock.speed = math.random(8, 20) / 10
end


function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goLeft = false
    elseif what == SWITCH_RIGHT then
        goRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    updateStars()
    if not over then
        updateShip()
        updateShots()
        updateRocks()
    end
    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
end


function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end


function startGame()
    shipX = (screenWidth - shipWidth) / 2
    score = 0
    lives = START_LIVES
    over  = false
    shots = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
end


function updateRocks()
    for _, rock in ipairs(rocks) do
        rock.y = rock.y + rock.speed
        if rock.y > screenHeight then
            newRock(rock)
        end
        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                over = true
            end
        end
    end
end


function updateShip()
    if goLeft then
        shipX = shipX - SHIP_SPEED
    end
    if goRight then
        shipX = shipX + SHIP_SPEED
    end
    if shipX < 0 then
        shipX = 0
    end
    if shipX > screenWidth - shipWidth then
        shipX = screenWidth - shipWidth
    end
end


function updateShots()
    for i = #shots, 1, -1 do
        local shot = shots[i]
        local gone = false

        shot.y = shot.y - SHOT_SPEED
        if shot.y + shotHeight < 0 then
            gone = true
        end
        for _, rock in ipairs(rocks) do
            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
            end
        end
        if gone then
            table.remove(shots, i)
        end
    end
end


function updateStars()
    for _, star in ipairs(stars) do
        star.y = star.y + star.speed
        if star.y > screenHeight then
            star.y = 0
            star.x = math.random(0, screenWidth - 1)
        end
    end
end


for i = 1, STAR_COUNT do
    stars[i] = { x = math.random(0, screenWidth - 1), y = math.random(0, screenHeight - 1), speed = math.random(1, 3) / 4 }
end

startGame()

Les flèches gauche et droite dirigent. Espace tire. Quand les rochers vous ont pris votre dernière vie, 1 lance une nouvelle partie.

Quelques éléments méritent qu’on les montre du doigt.

Les quatre appels à spriteLoad et les huit mesures sont en haut, en dehors de toute fonction, donc ils ont lieu une fois. Tout ce qui suit est écrit en fonction de screenWidth, de shipWidth et de leurs amis, et il n’y a pas un seul nombre de pixels brut dans tout le code du jeu.

Les fonctions sont dans l’ordre alphabétique, et c’est une habitude qui vaut la peine d’être prise dès maintenant. Ça n’a pas la moindre importance pour Lua — c’est pour vous, dans six mois, quand vous chercherez updateShots dans un fichier qui contient quarante fonctions.

Les deux dernières choses du fichier ne sont pas du tout des fonctions. Ce sont de simples instructions en bas du script : construire le champ d’étoiles, puis appeler startGame pour mettre en place les rochers et remettre le score à zéro. Elles s’exécutent une fois, dans l’ordre, pendant le chargement du script, et elles doivent venir après les fonctions dont elles se servent.

overlapping, ce sont les quatre comparaisons dont la leçon sept disait que vous pouviez les écrire vous-même au lieu d’appeler collideRects, écrites sous forme de fonction avec les mêmes huit arguments. Deux rectangles se ratent si l’un est entièrement à gauche, à droite, au-dessus ou au-dessous de l’autre ; si aucune de ces quatre conditions n’est vraie, ils se chevauchent. La leçon onze la remplace par quelque chose que fournit le moteur, et explique pourquoi le rectangle n’a pas la bonne forme pour un vaisseau.

Une dernière remarque pour le jour où vous lirez le code Singe d’autres gens. Chaque appel de sprite de ce livre prend le handle en premier. Singe 2.10 le mettait en dernier, et un jeu peut demander au moteur de continuer à faire ainsi, donc le code que vous trouverez en ligne peut se lire spriteDraw(x, y, ship). Ne le copiez pas. Le handle en premier, c’est l’ordre actuel, et celui que documente la Référence.

Essayez

  1. Centrez le vaisseau sur sa position. Ajoutez true comme quatrième argument au spriteDraw du vaisseau. Regardez où le vaisseau saute, et déduisez de la distance qu’il a parcourue ce qu’a vraiment fait le quatrième argument.

  2. Plus de rochers. Changez ROCK_COUNT en 20. Puis en 200. Quelque part entre les deux, le jeu cesse d’être jouable, et quelque part bien au-delà, le jeu commence à ralentir. Trouvez les deux.

  3. Faites grandir le vaisseau. Ajoutez spriteScale(shipSprite, 2) tout en bas du fichier, sur la ligne au-dessus de startGame(). Lancez et foncez vers le bord droit : le vaisseau est deux fois plus grand mais il s’arrête toujours là où s’arrêtait le petit, et il dépasse du bord droit et du bas. Trouvez pourquoi, puis remontez cette ligne au-dessus des appels à spriteGetWidth et regardez tout rentrer dans l’ordre. L’entrée de spriteScale dans la Référence explique ce que la mise à l’échelle fait aux mesures.

  4. Ajoutez le marcheur. Chargez walk.png dans le jeu, et dessinez la silhouette qui marche en haut de l’écran, comme décor. Il vous faudra le comptage des images du script de marche, et vous devrez décider à quel endroit de onOverlayUpdate va le dessin — devant les étoiles, derrière les rochers.

  5. Déchargez quelque chose dont vous vous servez encore. Ajoutez spriteUnload(starSprite) en bas du fichier, après startGame(), et lancez. Lisez ce que vous obtenez.

Cassez-le exprès

Les majuscules comptent, et c’est avec les graphismes qu’elles mordent le plus fort. Changez le chargement du vaisseau pour qu’il utilise un S majuscule :

local shipSprite = spriteLoad(DIR .. "art/Spaceship.png")

Le jeu refuse de démarrer :

10:spriteLoad:  Couldn't open rocks/art/Spaceship.png: No such file or directory

Lisez-le de la même façon que l’erreur de la leçon un, mais remarquez que la forme est un peu différente. 10, c’est la ligne. spriteLoad, c’est la fonction du moteur qui a abandonné, à la place d’un nom de fichier — quand la plainte vient de Singe plutôt que de Lua, c’est ce que vous obtenez. Puis la raison, qui est ici formulée par votre propre système d’exploitation et variera légèrement d’une machine à l’autre.

No such file or directory, c’est l’ordinateur qui est précis plutôt que méchant. Il n’y a vraiment aucun fichier appelé Spaceship.png ; il y en a un appelé spaceship.png, et pour une machine Linux, ce sont deux noms différents. Sous Windows, et sur la plupart des Mac, ça aurait marché, ce qui est pire, parce que ça veut dire que le bug voyage jusqu’à la machine de quelqu’un d’autre et apparaît là-bas pour la première fois.

L’autre moitié de cette erreur, celle que vous rencontrerez aussi, c’est le dossier. Si vous avez mis le kit graphique au mauvais endroit, ou lancé Singe depuis le mauvais dossier, le message est exactement le même, et le remède ne l’est pas. Le chemin du message vous aide : c’est le nom complet que Singe a essayé, compté à partir du dossier où vous l’avez lancé, et le rocks/ du début est la partie qu’a ajoutée DIR. Vérifiez trois choses, dans cet ordre : le fichier porte-t-il exactement le nom que vous avez tapé, est-il dans le dossier art, et ce dossier art est-il à côté de votre script ?

Ce que vous avez appris

  • Une image dessinée sur l’overlay est un sprite, chargé avec spriteLoad.

  • spriteLoad vous rend un handle : un nombre qui veut dire « cette image-là » pour le moteur, et que vous gardez dans une variable.

  • DIR est le dossier où se trouve votre script, et chaque fichier que charge votre jeu doit être nommé avec.

  • spriteDraw(handle, x, y) le dessine, à partir de son coin supérieur gauche, et seulement à l’intérieur de onOverlayUpdate. Un quatrième argument true désigne plutôt le centre.

  • Chargez une fois, en haut du fichier. Charger à l’intérieur de onOverlayUpdate dévore la mémoire jusqu’à ce que le jeu meure.

  • spriteUnload rend une image, en général depuis onShutdown, et le handle est mort ensuite.

  • Le PNG porte la transparence, et c’est pourquoi les coins du vaisseau ne sont pas des boîtes noires.

  • spriteGetWidth et spriteGetHeight mesurent un sprite tel qu’il serait dessiné maintenant, pour que vous n’ayez jamais à taper sa taille dans votre programme.

  • Les sprites se couvrent les uns les autres. Vous dessinez dans l’ordre, de l’arrière vers l’avant.

  • spriteLoadFrames(count, file) découpe une bande en images, et spriteDrawFrame(handle, x, y, frame) en dessine une, en comptant à partir de 1.

La prochaine fois

Le jeu a fière allure et ne fait pas le moindre bruit. À la leçon dix, les tirs reçoivent un son, les rochers une explosion, et quelque chose joue sous le tout — et vous rencontrez votre cinquième callback, celui dont le moteur se sert pour vous dire qu’un son est terminé.

Leçon 10 : Le son

La leçon terminée

Un jeu sans son a l’air cassé, d’une façon difficile à cerner. Les tirs partent et rien ne se passe. Les rochers éclatent et rien ne se passe. Mettez un bruit d’une demi-seconde sur chacun de ces moments et, tout à coup, le même jeu semble fait de quelque chose.

Cette leçon donne à votre jeu un tir, une explosion et de la musique en dessous. En chemin, elle vous présente votre cinquième callback : celui dont le moteur se sert pour vous dire qu’un son a fini de jouer.

Un bruit

Le kit d’illustrations que vous avez copié à la leçon neuf contient deux sons, shoot.wav et boom.wav, et l’explosion est le plus facile des deux à entendre. Créez un nouveau fichier à côté de votre dossier art et tapez ceci.

dofile("Singe/Framework.singe")

local boom = soundLoad(DIR .. "art/boom.wav")


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(boom)
    end
end


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Press space.")
    return OVERLAY_UPDATED
end


function onShutdown()
    soundUnload(boom)
end

Lancez-le et tapez rapidement trois ou quatre fois sur la barre d’espace. Les détonations s’empilent les unes sur les autres au lieu de se couper la parole.

Garder la barre d’espace enfoncée vous donne exactement une détonation, pas une rafale. C’est le même comportement que celui que vous avez rencontré à la leçon trois : une touche tenue, c’est un seul appui, signalé une fois, et le moteur jette les répétitions que votre clavier envoie. C’est pour ça que diriger le vaisseau demande onInputReleased et une variable, plutôt que de compter les appuis.

Ce qui vient de se passer

La forme est la même qu’à la leçon neuf : chargez une fois en haut, servez-vous du handle, rendez-le à la fin.

local boom = soundLoad(DIR .. "art/boom.wav")

soundLoad lit un fichier audio, le garde en mémoire et vous renvoie un handle — la même idée qu’un handle de sprite, un nombre qui veut dire « ce son-là » pour le moteur. DIR est là pour la même raison qu’à la leçon neuf : le son se trouve dans le dossier de votre jeu, et le jeu doit pouvoir le trouver, d’où que Singe ait été lancé.

Tout ce que la leçon neuf a dit du chargement s’applique ici mot pour mot. Chargez en haut du fichier, une fois. Un soundLoad dans onOverlayUpdate charge le son soixante fois par seconde sans jamais en rendre un seul, et le jeu en meurt quelques minutes plus tard.

        soundPlay(boom)

Jouez-le. C’est tout ce qu’il faut pour jouer un effet sonore, et le moteur s’occupe du reste : le son démarre, il se termine, et il ne gêne jamais votre programme.

Mais soundPlay renvoie quelque chose, lui aussi, et ce n’est pas le nombre que vous lui avez donné. Changez la ligne et regardez :

        local channel = soundPlay(boom)
        debugPrint("clip " .. boom .. " on channel " .. channel)

Tapez rapidement une demi-douzaine de fois sur la barre d’espace et observez les deux nombres. Le numéro du son ne change jamais. Le numéro de canal grimpe — 0, puis 1, puis 2 — et une fois que les premières détonations sont finies, il redescend et se remet à réutiliser les petits numéros.

C’est la chose qui piège tout le monde avec le son, alors elle mérite d’être dite lentement. Deux sortes de nombres différentes sont en jeu.

Le handle du son, celui que donne soundLoad, c’est l’enregistrement. Il n’y en a qu’un. Il ne change pas, il n’est ni en train de jouer ni arrêté, c’est le son posé en mémoire, qui attend qu’on s’en serve.

Le canal que donne soundPlay, c’est une lecture de cet enregistrement. Singe en a seize, numérotés de 0 à 15, et chaque son qu’on entend en ce moment en utilise un. Voilà pourquoi les détonations se chevauchent : le deuxième appui n’a pas interrompu le premier, il a lancé une deuxième lecture sur le canal libre suivant.

Tout ce qui agit sur un son que vous entendez prend un canal : soundStop, soundIsPlaying, soundPause, soundResume. Tout ce qui agit sur l'enregistrement prend le handle : soundPlay et soundUnload. Donnez l’un là où l’autre est attendu et vous n’aurez pas toujours une erreur, parce que 3 est un numéro de canal valable et aussi un handle de son tout à fait correct — vous aurez du silence, ou le mauvais son qui s’arrête, ce qui est bien plus difficile à trouver.

Seize, c’est beaucoup, mais ce n’est pas infini. Quand tous les canaux sont occupés, rien ne joue et soundPlay renvoie -1 au lieu d’un numéro de canal. Un jeu qui lance énormément de sons à la fois doit s’y attendre, et vous allez en écrire un dans une minute.

Le volume

Il y a trois volumes, et ils se multiplient entre eux.

Le volume général des effets couvre tout. soundGetVolume le lit et soundSetVolume le règle, sur une échelle de 0 à 63.

    soundSetVolume(40)

Résistez. Ce nombre appartient au joueur, pas à vous : il part de ce que le joueur a demandé en lançant le jeu, et un jeu qui l’écrase est un jeu trop fort dans la pièce tranquille de quelqu’un. Ne changez le volume général que si le joueur vous le demande, depuis un écran d’options. soundGetVolume est là pour qu’un écran d’options puisse afficher sa valeur actuelle au lieu de la deviner.

Ce dont vous devriez vous servir, c’est le volume du canal, qui se place sous le volume général. Donnez un troisième argument à soundPlay et cette lecture-là est plus douce :

    soundPlay(shootClip, 0, 35)

Le 0 du milieu est le nombre de répétitions, que vous devez donner parce que le volume vient après. 0 veut dire jouer une fois. -1 veut dire boucler jusqu’à ce que quelque chose l’arrête, et c’est comme ça que vous feriez le ronronnement d’un moteur ou le vent. L’entrée de la Référence pour soundPlay donne les trois arguments.

Le troisième volume, c’est la distance, pour les sons placés dans un monde en 3D. Ce sera pour la quatrième partie, quand le jeu passera en trois dimensions.

La musique a son propre volume, et il est sur une autre échelle. On y revient dans un instant.

Arrêter, et ne pas arrêter

soundStop prend un canal et le coupe là où il en est :

    soundStop(engineChannel)
    engineChannel = -1

Remarquez la deuxième ligne. Dès qu’un canal s’arrête, le moteur est libre de donner ce même numéro au soundPlay suivant, si bien qu’un numéro de canal que vous gardez encore peut maintenant appartenir à un tout autre son. Jetez-le dès que vous l’arrêtez. -1 est la bonne chose à mettre à sa place, parce que c’est la même valeur que celle que vous donne soundPlay quand il n’a rien pu jouer du tout, et un seul test couvre les deux cas : if channel >= 0 then.

soundStop, c’est pour un son qui n’a plus lieu d’être — le bruit du moteur quand le moteur meurt, l’alarme quand quelqu’un a répondu à l’alarme. Ce n’est pas le bon outil pour un effet court. Une explosion d’une demi-seconde coupée au bout d’un dixième de seconde sonne comme une erreur, parce que c’en est une.

Alors, la plupart du temps, ne faites rien du tout. Laissez-le finir. Un effet sonore que vous lancez et auquel vous ne pensez plus se termine tout seul et libère son canal tout seul, et c’est exactement ce que vous voulez.

C’est vrai même à la fin. soundUnload ne coupe pas un son qui est encore en train de jouer : le moteur garde l’audio en vie jusqu’à ce que le dernier canal qui s’en sert se soit arrêté. Vous pouvez décharger dans onShutdown sans craindre d’avoir fait taire quelque chose.

soundIsPlaying(channel) répond à la question : ce canal fait-il du bruit en ce moment ? Son usage principal n’est pas la curiosité mais la retenue : une alarme qui doit sonner une fois, et ne pas redémarrer chaque fois que le jeu remarque que le danger est toujours là.

function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

Lisez la condition à voix haute : jouez l’alarme s’il n’y a pas de canal d’alarme, ou si celui que vous avez s’est arrêté. Sinon, laissez-la tranquille.

Le son qui bégaie

Voici l’erreur. Tout le monde l’écrit, en général dans la semaine qui suit sa découverte du son.

Supposons que vous vouliez que le vaisseau continue de tirer tant que le bouton est enfoncé, plutôt qu’une fois par appui. Vous le feriez comme pour diriger : une variable firing mise à true dans onInputPressed et remise à false dans onInputReleased, et le tir créé dans onOverlayUpdate tant qu’elle est vraie. C’est une envie parfaitement sensée, et le bruit a tout l’air d’avoir sa place juste là, avec le tir :

function onOverlayUpdate()
    if firing then
        shots[#shots + 1] = { x = shipX, y = shipY }
        soundPlay(shootClip)
    end
    ...

Ce qui en sort n’est pas un tir. C’est un crépitement qui bourdonne, ou une note dure et plate, ou le bruit d’une petite machine en train de casser.

onOverlayUpdate s’exécute environ soixante fois par seconde. Tenez le bouton une seconde et vous avez demandé soixante lectures d’un son qui dure environ un cinquième de seconde, chacune démarrant par-dessus la précédente. Environ onze d’entre elles jouent à chaque instant, chacune une image derrière la précédente, et ce que vous entendez, ce sont soixante copies de la même attaque empilées les unes sur les autres.

La solution n’est pas un son plus malin. C’est de jouer le son là où l'événement se produit plutôt que là où l'état est vrai :

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(shootClip, 0, 35)
    end
end

onInputPressed se produit une fois, quand le bouton s’enfonce. Un appui, un tir, un bruit.

Si vous voulez vraiment un tir continu, la réponse est la même sous une autre forme : faites du tir lui-même un événement. Comptez les images, exactement comme le cycle de marche les comptait à la leçon neuf, et ne créez un tir qu’une image sur huit. Le bruit va avec le tir, donc il joue sept ou huit fois par seconde au lieu de soixante, et ça, c’est une mitrailleuse plutôt qu’un crépitement.

Voilà la règle, et elle mérite de sortir de cette leçon avec vous : les sons vont avec les événements, pas avec les conditions. Un appui, un coup, une mort, un objet ramassé — chacun arrive une fois et mérite un son. « Le bouton est enfoncé » et « le vaisseau bouge » ne sont pas des événements ; ils sont vrais pendant des centaines d’images d’affilée, et tout ce que vous jouez à partir d’eux joue des centaines de fois.

Quand un son appartient vraiment à un état qui dure — un moteur, le vent, une sirène — lancez-le une fois avec -1 comme nombre de répétitions, gardez le canal, et arrêtez-le quand l’état prend fin.

Le cinquième callback

Parfois, vous avez vraiment besoin de savoir quand un son est fini. Écrivez cette fonction et le moteur l’appellera :

function onSoundCompleted(channel)
end

C’est votre cinquième callback, après onOverlayUpdate à la leçon un, les deux callbacks des commandes à la leçon trois et onShutdown à la leçon neuf, et il marche comme tous les autres : vous l’écrivez, vous ne l’appelez jamais, c’est le moteur qui vous appelle. Le channel qu’il vous passe est le canal qui vient de se taire — le numéro que soundPlay vous a donné quand vous l’avez lancé.

Il est appelé quand un son arrive au bout, quand la dernière répétition d’une boucle se termine, et quand vous arrêtez un canal vous-même avec soundStop. Ce dernier cas surprend ceux qui se servent du callback pour enchaîner un son sur le suivant : arrêter un canal exprès le signale quand même comme terminé, et si vous n’y prenez pas garde, le son suivant de la chaîne démarre malgré tout.

Le jeu va s’en servir pour quelque chose qui en vaut la peine. Quand la dernière vie s’en va, l’explosion du vaisseau joue, et le jeu reste immobile — pas de GAME OVER, pas de musique qui s’éteint — jusqu’à ce que cette explosion soit vraiment finie. Ensuite, tout s’arrête d’un coup. Ça tient en une poignée de lignes, et c’est la différence entre une fin et une coupure.

La musique n’est pas un effet sonore

Vous pourriez charger un air de trois minutes avec soundLoad et le jouer avec soundPlay. Ne le faites pas. La musique a sa propre famille d’appels, pour des raisons qui comptent :

  • La musique a son propre volume, séparé de celui des effets, si bien qu’un joueur peut baisser la musique et entendre encore les tirs.

  • Il n’y a pas de limite de seize canaux, ni de numéro de canal. Un handle, c’est un morceau de musique, et c’est par ce handle que vous l’arrêtez, le mettez en pause et le reprenez.

  • musicStop peut faire disparaître un morceau en fondu sur une seconde ou deux au lieu de le couper.

Les appels sont le reflet de ceux que vous connaissez déjà :

local theme = musicLoad("Singe/menuIntro.flac")

musicSetVolume(50)
musicPlay(theme, -1)

musicLoad donne un handle. musicPlay le lance, avec le même nombre de répétitions que soundPlay : -1 pour toujours. musicStop(theme) l’arrête, et musicStop(theme, 1500) prend une seconde et demie pour le faire disparaître en fondu. musicUnload le rend.

Maintenant, le piège. Le volume de la musique va de 0 à 128, pas de 0 à 63. Les effets sonores utilisent une échelle et la musique une autre, deux fois plus longue, pour des raisons historiques qui ne consolent de rien quand votre musique sort à la moitié du volume que vous vouliez. Quand vous travaillez avec la musique, doublez le nombre que vous auriez choisi pour un effet.

Le morceau chargé ici est la musique de menu du moteur lui-même, tirée du dossier Singe que le moteur a déballé dans votre dossier de travail lors de votre premier lancement. Il dure dix secondes et il a été écrit pour s’éteindre en fondu à la fin, donc en boucle il sonne exactement comme une boucle de dix secondes qui n’arrête pas de s’éteindre. C’est très bien pour apprendre les appels et ça ne vaut rien du tout pour un jeu fini, qui embarque un morceau plus long bien à lui. N’importe lequel des formats habituels fera l’affaire : la section Musique de la Référence les donne, et Ogg Vorbis ou MP3 sont les choix raisonnables, parce que quelques minutes de musique en WAV font un fichier énorme.

Le jeu reçoit une bande-son

Ouvrez le jeu de la leçon neuf. Tout ce qui suit s’y ajoute ; rien n’en est retiré.

Quatre choses à charger, en haut, avec les sprites :

local shootClip = soundLoad(DIR .. "art/shoot.wav")
local boomClip  = soundLoad(DIR .. "art/boom.wav")
local clickClip = soundLoad("Singe/click.wav")
local theme     = musicLoad("Singe/menuIntro.flac")

Les deux premières portent DIR et les deux dernières non, et c’est voulu. DIR veut dire le dossier de votre jeu. Un nom qui commence par Singe/ veut dire à la place le dossier du moteur lui-même, où qu’il soit — c’est pourquoi dofile("Singe/Framework.singe") marche depuis la leçon sept sans DIR lui non plus. Vos propres fichiers ont besoin de DIR ; ceux du moteur, jamais.

Deux nouvelles variables, à côté des autres :

local dying        = false
local deathChannel = -1

dying, c’est le moment entre la perte de la dernière vie et la fin de la partie : l’explosion résonne encore, et rien ne bouge à l’écran.

Le tir reçoit son bruit dans onInputPressed, à l’endroit même où le tir est créé, et le redémarrage reçoit un clic, pour qu’appuyer sur 1 donne l’impression d’avoir fait quelque chose :

function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            soundPlay(clickClip)
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    end
end

Un rocher abattu fait boum, et un rocher qui vous percute aussi. Dans updateShots, à côté du score :

                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)

Et dans updateRocks, là où la vie est perdue, la partie intéressante :

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

Quand la dernière vie s’en va, l’explosion joue et son canal est mémorisé. Le jeu est maintenant dying, ce qui arrête tout mouvement mais n’affiche pas encore GAME OVER.

Le if channel < 0, c’est la limite des seize canaux, prise en compte. Si tous les canaux se trouvaient occupés à cet instant précis, il n’y a ni explosion ni canal à attendre, et sans ces deux lignes le jeu resterait dans dying pour toujours, à attendre un son qui n’a jamais joué. Attendre quelque chose qui ne peut pas arriver est l’une des façons les plus simples de bloquer un programme, et le garde-fou coûte toujours moins cher que le bogue.

Maintenant, le nouveau callback, et la petite fonction qu’il partage avec ce garde-fou :

function endGame()
    dying        = false
    deathChannel = -1
    over         = true
    musicStop(theme, 1500)
end


function onSoundCompleted(channel)
    if channel == deathChannel then
        endGame()
    end
end

Le moteur appelle onSoundCompleted pour chaque canal qui s’arrête, alors la première chose que fait la fonction, c’est vérifier si celui-ci est le canal qui l’intéresse. Tout le reste — chaque tir, chaque rocher — passe et est ignoré.

onOverlayUpdate doit rester immobile pendant l’explosion, et ça tient en un mot :

    if not over and not dying then
        updateShip()
        updateShots()
        updateRocks()
    end

startGame remet à zéro les deux nouvelles variables et relance la musique depuis le début :

    dying        = false
    deathChannel = -1
    musicSetVolume(50)
    musicPlay(theme, -1)

Et onShutdown rend ce qui a été chargé :

function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
    soundUnload(shootClip)
    soundUnload(boomClip)
    soundUnload(clickClip)
    musicUnload(theme)
end

Lancez-le. Tirez sur les rochers, laissez-vous toucher trois fois, et écoutez la fin : la dernière détonation joue jusqu’au bout, et c’est seulement quand elle s’est tue que la musique commence à s’éteindre et que les mots apparaissent.

Le script terminé se trouve dans le dossier learn sous le nom 10-sound.singe, si vous voulez comparer.

Essayez

  1. Rendez le tir encore plus discret. Changez le 35 du soundPlay du tir en 10, puis en 63. Trouvez le nombre où il passe sous les explosions au lieu de passer par-dessus.

  2. Baissez la musique sans toucher aux effets. Changez musicSetVolume(50) en musicSetVolume(15). Vérifiez que les détonations sont exactement aussi fortes qu’avant, ce qui est toute la raison pour laquelle la musique est un système à part.

  3. Coupez la fin. Dans endGame, changez musicStop(theme, 1500) en musicStop(theme). Écoutez les deux fins deux fois. La différence tient à un nombre dans un argument, et ce n’est pas une petite différence.

  4. Donnez un moteur au vaisseau. Lancez soundPlay(clickClip, -1, 12) dans startGame, gardez le canal qu’il vous donne dans une variable à lui, et arrêtez-le dans endGame. Le clic dure un cinquantième de seconde, donc en boucle c’est un bourdonnement, ce qui est ce que ce kit a de plus proche d’un moteur. Puis retirez de nouveau le soundStop, jouez trois parties d’affilée, et écoutez ce que vous avez construit.

  5. Comptez les canaux. Affichez le numéro de canal chaque fois qu’un rocher explose. Puis augmentez ROCK_COUNT jusqu’à ce que plusieurs explosent en même temps, et continuez de l’augmenter jusqu’à voir passer un -1.

Cassez-le exprès

Vous avez maintenant deux échelles de volume en tête, et tôt ou tard la mauvaise sortira de vos doigts. Ajoutez cette ligne toute seule, juste sous les quatre lignes soundLoad et musicLoad :

soundSetVolume(100)

Le jeu refuse de démarrer :

20:soundSetVolume:  Invalid sound volume value:  100

Le numéro de ligne que vous obtenez est celui de la ligne où vous l’avez vraiment tapée, donc le vôtre n’est peut-être pas 20. Ensuite vient la fonction qui a protesté, puis la valeur contre laquelle elle a protesté. Le message ne vous dit pas quelle est la plage permise — c’est à ça que sert l’entrée de la Référence pour soundSetVolume — mais il vous dit bien le nombre qu’elle a refusé, et une fois que vous savez que les effets s’arrêtent à 63, la correction tient en un nombre.

100 est un nombre suspect à trouver dans un volume, et ça vaut la peine de savoir pourquoi vous l’avez tapé. Presque à coup sûr, vous avez pensé au volume comme à un pourcentage, parce que tous les curseurs de volume dont vous vous êtes jamais servi vont jusqu’à 100. Celui de Singe, non. Les effets vont de 0 à 63 et la musique de 0 à 128, et ni l’un ni l’autre n’est un pourcentage de quoi que ce soit.

Voilà la forme générale d’une erreur du moteur, par opposition aux erreurs Lua de la leçon un : un numéro de ligne, le nom de la fonction du moteur que vous avez appelée, et une plainte au sujet des valeurs que vous lui avez passées. Quand vous en voyez une, l’entrée de la Référence pour cette fonction est la prochaine chose à lire.

Ce que vous avez appris

  • soundLoad lit un son et renvoie un handle. Chargez une fois, en haut du fichier.

  • soundPlay lance un son et renvoie un canal, qui est une autre sorte de nombre que le handle.

  • Singe mélange seize canaux. Quand ils sont tous occupés, soundPlay renvoie -1 et rien ne joue.

  • Les numéros de canal sont réutilisés. Oubliez-en un dès que vous l’avez arrêté.

  • Laissez les effets courts finir tranquillement ; soundStop est pour les sons qui n’ont plus lieu d’être.

  • soundUnload ne coupe pas un son qui est encore en train de jouer.

  • Jouez un son là où l’événement se produit, pas là où une condition est vraie, sinon il joue soixante fois par seconde.

  • onSoundCompleted(channel) est un callback que le moteur appelle chaque fois qu’un canal se tait, quelle qu’en soit la raison.

  • La musique est un système à part, avec ses propres handles, son propre volume, et pas de limite de canaux.

  • Le volume des effets va de 0 à 63. Celui de la musique va de 0 à 128. Ce ne sont pas des pourcentages.

La prochaine fois

Vos rochers sont touchés quand leurs rectangles se chevauchent, et c’est pourquoi un tir qui passe à travers un coin de ciel compte quand même. À la leçon onze, vous aurez les tests de collision du moteur lui-même, vous apprendrez ce qu’est une boîte de collision, et vous découvrirez pourquoi le rectangle autour d’un rocher rond n’a pas la bonne forme.

Leçon 11 : Toucher des choses

La leçon terminée

Votre jeu de la leçon dix marche. Les tirs font éclater les rochers, les rochers coûtent des vies, et les explosions tombent aux bons endroits. Regardez-le de près, pourtant, et vous verrez qu’il triche, dans les deux sens. Un rocher qui frôle le bout d’une aile coûte une vie. Un tir qui traverse le ciel vide à côté d’un rocher le fait éclater quand même.

Dans un jeu, deux choses se touchent quand les nombres le disent. Personne ne regarde les images. Cette leçon met les nombres d’accord avec ce que voit le joueur : elle remplace le test que vous avez écrit à la main par celui du moteur, réduit les boîtes testées pour qu’elles collent aux choses qu’elles contiennent, et vous donne un interrupteur qui vous montre ces boîtes. L’image ci-dessus, c’est le jeu avec cet interrupteur allumé.

Où vous en êtes

Le jeu pose la question « ces deux-là se touchent-ils ? » à exactement deux endroits, et les deux se servent de overlapping, la fonction que vous avez tapée à la leçon neuf. L’un est dans updateRocks, là où un rocher rencontre le vaisseau :

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then

L’autre est dans updateShots, là où un tir rencontre un rocher :

            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Tout ce que contient cette leçon change ces deux lignes et ajoute quelques petites fonctions pour les nourrir. Rien d’autre ne bouge dans le jeu. Le script terminé se trouve tout entier dans learn/11-hitting-things.singe si vous vous perdez en route.

Relisez-la une fois de plus

La leçon neuf a déjà fait cette partie : overlapping, c’est la collision de rectangles écrite à la main. Relisez-la une dernière fois avant de la jeter, parce qu’elle contient toute l’idée :

function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end

Il est difficile de répondre directement à la question « ces deux-là se touchent-ils ? », et facile d’y répondre à l’envers. Deux rectangles ne se touchent pas quand l’un d’eux est entièrement à gauche de l’autre, ou entièrement à droite, ou entièrement au-dessus, ou entièrement en dessous. Il n’y a pas de cinquième façon de se rater. Si aucune des quatre n’est vraie, ils se touchent.

Chaque if est l’une des quatre façons de se rater. ax + aw est le bord droit du premier rectangle, donc ax + aw ⇐ bx se lit « le premier finit avant que le second commence », et c’est ce que « entièrement à gauche » veut dire en nombres. La même forme encore trois fois, pour la droite, le dessus et le dessous, avec y et les hauteurs à la place de x et des largeurs, et la seule chose qui reste, c’est true.

Ce sont les huit nombres dont tout test de collision a besoin : un coin et une taille pour chacune des deux choses. Gardez cette forme en tête, parce que vous êtes sur le point de la supprimer.

Le moteur l’a déjà

Vous avez rencontré collideRects à la leçon sept, où il attrapait les blocs qui tombaient dans Dodge. La leçon neuf a écrit le même test à la main pour que vous puissiez voir ce qu’il y a dedans. Vous l’avez vu. Supprimez overlapping, et changez les deux lignes de Où vous en êtes pour qu’elles appellent le moteur à la place :

        if collideRects(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            if not gone and collideRects(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Les mêmes huit nombres, dans le même ordre : le coin et la taille du premier rectangle, puis ceux du second. Lancez-le, et le jeu se joue exactement comme avant, et c’est bien le but. La seule différence est tout au bord. Votre ⇐ disait que deux rectangles qui se rejoignent le long d’un bord ne se touchent pas. collideRects dit qu’ils se touchent, et un rectangle sans largeur ou sans hauteur ne touche rien du tout. C’est dans ces cas délicats que les versions écrites à la main se trompent sans bruit, et c’est une des raisons de se servir de celle du moteur.

collideRects fait partie d’une famille de tests de collision, et cette famille est une partie de ce que ce livre appelle le kit de jeu : une poignée de fonctions simples pour les choses que presque tous les jeux écrivaient autrefois eux-mêmes. Tester si deux choses se touchent en est une. Garder un nombre pour la prochaine fois en est une autre, et c’est la leçon douze. Attendre un moment, faire glisser un nombre en douceur d’une valeur à une autre, et montrer combien de temps chaque image a pris, voilà le reste. La Référence donne à chaque partie sa propre section : Collisions, Sauvegarde, Minuteur, Tween et Statistiques.

Les tests de collision sont les plus simples du lot : de simples questions, sans handle à garder et sans rien à préparer ni à libérer. Et aucun d’eux ne déplace quoi que ce soit. collideRects vous dit que le vaisseau et le rocher sont au même endroit ; c’est à vous de décider quoi en faire, et tout ce qui est intéressant dans un jeu se passe dans cette décision.

L’image n’est pas la boîte de collision

La leçon dix a promis d’expliquer pourquoi le rectangle autour d’un rocher rond n’a pas la bonne forme. Le rectangle autour du vaisseau n’a pas la bonne forme non plus, et pour la même raison.

Dessinez sur papier le rectangle de 32 sur 24 du vaisseau et coloriez le vaisseau. C’est un triangle avec deux ailerons, donc il reste du ciel vide dans les deux coins du haut et entre les ailerons. Le rocher est rond, donc il reste du ciel vide dans les quatre coins de son carré. Un rocher qui frôle le coin supérieur du rectangle du vaisseau n’a pas touché le vaisseau. Il est passé à côté de l’aile, et un joueur qui perd une vie pour ça dira que le jeu a triché — et il aura raison.

Donc la boîte que vous testez n’est pas l’image que vous dessinez. Elle est plus petite, et elle se trouve à l’intérieur de l’image. Ajoutez trois nombres aux constantes en haut de votre fichier :

local SHIP_PAD_X  = 6
local SHIP_PAD_Y  = 5
local ROCK_PAD    = 4

La marge, c’est la distance entre chaque bord et l’endroit où commence la vraie chose. Six pixels de moins de chaque côté du vaisseau, et cinq en haut et en bas, laissent une boîte de 20 sur 14 au milieu d’une image de 32 sur 24, ce qui correspond à peu près à la coque. Quatre de moins de chaque côté du rocher laissent 16 sur 16, et c’est presque entièrement du rocher.

Les deux boîtes sont un peu plus petites que les choses qu’elles représentent, et c’est voulu. Une boîte un peu trop petite donne au joueur des passages de justesse qui ressemblent à de l’adresse. Une boîte un peu trop grande lui donne des coups qui ressemblent à de la triche. Les joueurs pardonnent le premier cas, jamais le second.

Plutôt que d’écrire ce calcul à chaque test, écrivez-le une fois pour chaque sorte de chose :

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end


function shipBox()
    return shipX + SHIP_PAD_X, shipY + SHIP_PAD_Y, shipWidth - SHIP_PAD_X * 2, shipHeight - SHIP_PAD_Y * 2
end

Les tailles viennent de rockWidth, de shipWidth et de leurs amis, les mesures que la leçon neuf a prises sur les images, donc il n’y a toujours pas un seul nombre de pixels brut dans le code du jeu. Redessinez le vaisseau plus grand et la boîte grandit avec lui.

Chacune de ces fonctions renvoie quatre nombres à la fois, séparés par des virgules. Une fonction peut renvoyer autant de valeurs qu’elle veut, et la façon de les attraper est une liste de noms à gauche du = :

function shipHitsRock(rock)
    local sx, sy, sw, sh = shipBox()
    local rx, ry, rw, rh = rockBox(rock)

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)
end

Maintenant, le test de updateRocks se lit comme la question qu’il pose :

        if shipHitsRock(rock) then

Le calcul de la marge se trouve à exactement deux endroits, et les nombres qu’il utilise sont en haut du fichier : vous pouvez donc régler l’équité du jeu en changeant un nombre plutôt qu’en fouillant dans vos tests.

Rangez les nouvelles fonctions à leur place dans l’ordre alphabétique, comme l’a demandé la leçon neuf : rockBox après onSoundCompleted, puis shipBox et shipHitsRock.

Riposter

Voilà pour le côté du vaisseau. L’autre collision du jeu, c’est celle avec laquelle vous ripostez : chaque tir contre chaque rocher, dans updateShots. Elle a le même problème que le vaisseau, en plus petit. Un tir est un rectangle de 4 sur 10 testé contre le carré entier de 24 sur 24 du rocher, donc un tir qui ne fait que traverser le coin vide à côté d’un rocher le fait éclater quand même.

Vous pourriez donner au tir sa propre boîte avec une marge. Regardez d’abord les nombres, pourtant. Retirez une marge à un tir de quatre pixels de large et il ne reste presque rien, et tester un rectangle entier pour savoir si un filet de lumière a touché quelque chose, c’est plus de machinerie que la question n’en mérite.

Un tir est presque un point

Testez plutôt la pointe. collidePointRect demande si un point tombe à l’intérieur d’un rectangle — deux nombres pour le point, puis le coin et la taille du rectangle :

function shotHitsRock(shot, rock)
    local rx, ry, rw, rh = rockBox(rock)

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)
end

shot.y est le haut du tir et shot.x + shotWidth / 2 est le milieu de sa largeur, donc le point testé est le milieu du nez du tir. C’est là qu’un joueur pense que se trouve un tir. Le côté rocher de la question se sert du même rockBox que le vaisseau, donc un rocher a la même taille, quoi qui le touche.

Elle va après shipHitsRock, et le test de updateShots devient :

            if not gone and shotHitsRock(shot, rock) then

Décider de ce qui s’est passé

Aucun des tests de collision ne fait quoi que ce soit. Ils répondent, et c’est votre code qui décide. Voici les deux endroits qui décident, avec leurs nouvelles questions dedans. D’abord updateRocks :

        if shipHitsRock(rock) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

Et la boucle à l’intérieur de updateShots :

        for _, rock in ipairs(rocks) do
            if not gone and shotHitsRock(shot, rock) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)
            end
        end

Tout ce qui se trouve sous les questions est exactement ce que la leçon dix y a laissé. Un rocher qui touche le vaisseau fait boum, retourne en haut et coûte une vie. Un rocher abattu fait boum, retourne en haut et rapporte des points. Le tir disparaît aussi, et le not gone empêche un seul tir de faire éclater deux rochers. Changez quoi que ce soit là-dedans et vous changez le jeu, sans toucher à un seul test de collision, et c’est la raison pour laquelle les questions et les réponses sont gardées à part.

Lancez-le. Passez tout près d’un rocher et laissez-le effleurer un aileron : vous gardez la vie. Tirez juste à côté d’un rocher et le tir passe sans le toucher. Tirez en plein milieu d’un rocher et il éclate, comme toujours.

Voir les boîtes

Les boîtes de collision sont invisibles, ce qui rend invisible aussi toute erreur qui s’y cache. Dessinez-les pendant que vous travaillez. Une constante de plus en haut :

local SHOW_BOXES  = false

Deux fonctions de plus, qui vont tout en haut de l’ordre alphabétique :

function drawBox(x, y, width, height)
    overlayBox(x, y, x + width - 1, y + height - 1)
end


function drawBoxes()
    colorForeground(0, 255, 0)
    drawBox(shipBox())
    for _, rock in ipairs(rocks) do
        drawBox(rockBox(rock))
    end
end

Et dans onOverlayUpdate, après le dessin du vaisseau et avant que le score vienne par-dessus :

    spriteDraw(shipSprite, shipX, shipY)
    if SHOW_BOXES then
        drawBoxes()
    end
    drawHud()

Passez SHOW_BOXES à true et des contours verts apparaissent par-dessus les graphismes, comme sur l’image en haut de cette leçon. Remettez-le comme avant quand vous avez fini. Un interrupteur comme celui-ci, un mot en haut d’un fichier qui allume une image de ce que croit le programme, vaut mieux que des heures à fixer l’écran.

Ce qui vient de se passer

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end

Quatre valeurs pour un seul return, séparées par des virgules. Lua renvoie volontiers autant de valeurs que vous voulez, et c’est l’appelant qui décide combien il en garde. Quand un appel comme celui-ci est la dernière chose entre les parenthèses d’un autre appel, les quatre sont transmises, et c’est pourquoi drawBox(rockBox(rock)) marche et donne à drawBox ses quatre arguments. Partout ailleurs dans une liste d’arguments, seule la première valeur survit. Cette règle mord exactement une fois, et elle mord à la fin de cette leçon.

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)

collideRects veut huit nombres : un coin et une taille, un coin et une taille. Il renvoie true ou false et ne change rien. Comme la réponse ressort directement de la fonction avec return, shipHitsRock(rock) se lit comme une question partout où on s’en sert.

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)

collidePointRect en veut six : un point, puis un rectangle. Le bord compte comme l’intérieur, donc un tir pile sur la limite touche. Servez-vous-en chaque fois qu’un côté de la question est assez petit pour que sa taille n’ait pas d’importance.

    colorForeground(0, 255, 0)
    overlayBox(x, y, x + width - 1, y + height - 1)

Ces deux appels viennent de la leçon sept. overlayBox prend deux coins, pas un coin et une taille — le seul endroit de cette leçon où les nombres changent de forme — et le - 1 est là parce que les deux coins sont inclus. colorForeground est un interrupteur qui reste basculé, donc tout ce que dessine drawBoxes sort en vert. Les sprites et overlayPrint n’en tiennent pas compte, donc le reste du jeu garde le même aspect.

Le reste de la famille

collideRects et collidePointRect suffiront à la plupart des jeux 2D. Les autres sont là pour les formes que les rectangles décrivent mal, et chacun est le même genre de question simple :

  • collideCircles et collidePointCircle, pour tout ce qui est rond. Un cercle, c’est un centre et un rayon.

  • collideRectCircle, pour une chose ronde contre une chose carrée.

  • collidePointPolygon, pour une forme qui a ses propres coins — un dragon, un continent, un bouton à la forme bizarre. Vous lui donnez une simple liste de nombres x, y, x, y.

  • collideSegments, pour deux segments qui se croisent.

Soyons honnêtes : votre rocher est rond, et les tests de cercle lui vont mieux que n’importe quelle boîte. La marge, c’est la réponse bon marché, et elle suffit à la plupart des jeux, et c’est pourquoi elle vient en premier. La réponse exacte fait partie des choses à essayer plus bas.

collideSegments compte plus qu’on ne le croirait. Votre tir avance de six pixels par image et les rochers ont seize pixels de boîte de collision, donc un tir ne peut pas en dépasser un sans être testé à l’intérieur. Rendez le tir assez rapide — quarante pixels par image — et il saute d’en dessous d’un rocher à au-dessus, sans se trouver une seule fois au même endroit que lui, et il ne touche jamais rien. Tracer la ligne entre l’endroit où était le tir et celui où il est maintenant, et demander à collideSegments si cette ligne croise un bord, voilà le remède. Les choses lentes n’en ont pas besoin.

Il y a un seul callback de collision dans Singe, onCollision, et il n’est pas fait pour ça. Il appartient au moteur physique 3D : des corps qui ont une masse, qui tombent et rebondissent les uns sur les autres en trois dimensions, et qui vous disent où ils se sont touchés et avec quelle force. Vous le rencontrerez à la leçon vingt-quatre. Rien sur l’overlay ne se signale tout seul, et rien n’en a besoin. Vos rochers sont dans une liste, vous savez combien il y en a, et demander ne coûte pas cher.

Et quand vous voulez savoir non seulement si deux choses se sont rencontrées, mais aussi où celle qui bouge devrait finir — en glissant le long d’un mur au lieu de s’arrêter net dedans — les appels collide ne répondent pas à cette question, et c’est voulu. Une bibliothèque appelée bump est fournie avec Singe exactement pour ce travail, et la section Bibliothèques incluses de la Référence explique comment y accéder.

Essayez

  1. Retirez la marge. Mettez ROCK_PAD à 0 et jouez une minute. Puis mettez-le à 8 et rejouez. Avec l’un des deux, on a l’impression que le jeu vous ment.

  2. Regardez ce que vous testez. Mettez SHOW_BOXES à true et observez les contours verts pendant qu’un rocher passe près du vaisseau. Maintenant, mettez SHIP_PAD_X à 16, jouez, et remarquez que plus rien ne peut vous toucher. Trouvez pourquoi à partir du calcul de shipBox.

  3. Rendez le tir trop rapide. Mettez SHOT_SPEED à 40. Comptez combien de rochers vous touchez sur dix. Trouvez avec les nombres pourquoi ça arrive avant de le remettre comme avant.

  4. Servez-vous du tir entier. Réécrivez shotHitsRock pour qu’il utilise collideRects avec le rectangle complet du tir au lieu de collidePointRect avec son nez. Jouez avec les deux et décidez lequel vous préférez ; il n’y a pas de bonne réponse, et c’est bon à savoir.

  5. Rendez le rocher rond. Donnez au rocher un cercle au lieu d’une boîte : son centre est à rock.x + rockWidth / 2 vers la droite et à rock.y + rockHeight / 2 vers le bas, et un rayon de 10 convient à peu près. Servez-vous de collideRectCircle pour le vaisseau et de collidePointCircle pour le tir, et dessinez le cercle dans drawBoxes avec overlayCircle, qui prend un centre et un rayon.

Cassez-le exprès

Les deux boîtes font déjà quatre valeurs chacune, alors on est tenté de les passer directement et de se passer des huit noms locaux :

function shipHitsRock(rock)
    return collideRects(shipBox(), rockBox(rock))
end

Ça a l’air juste, et c’est faux. Lancez-le et le jeu s’arrête avant d’avoir dessiné quoi que ce soit :

186:collideRects:  Expected 8 argument(s), got 5.

La ligne est celle que vous venez de taper, donc la vôtre n’est peut-être pas la 186. Cinq, par contre. rockBox(rock) est la dernière chose entre les parenthèses, donc ses quatre valeurs sont toutes entrées. shipBox() ne l’est pas, donc il a été réduit à une seule. Un plus quatre font cinq, et collideRects ne va pas deviner les trois autres.

Cette erreur vient du moteur et non de Lua, donc elle a la même forme que celles des leçons neuf et dix : le nombre au début est la ligne, puis vient le nom de la fonction qui a refusé, puis la plainte. Remettez les huit noms locaux.

Ce que vous avez appris

  • La collision, c’est de l’arithmétique sur des rectangles, et vous pouvez l’écrire vous-même.

  • Deux rectangles se ratent d’exactement quatre façons ; si aucune n’est vraie, ils se touchent.

  • collideRects prend un coin et une taille pour chacun de deux rectangles et répond true ou false. Pour lui, des bords qui ne font que se toucher se touchent.

  • Les tests de collision font partie du kit de jeu : de simples fonctions, sans rien à préparer. Sauvegarde, Minuteur, Tween et Statistiques en sont le reste.

  • collidePointRect demande si un point est à l’intérieur d’un rectangle, ce qui est la bonne question pour tout ce qui est petit.

  • La boîte que vous testez est plus petite que l’image que vous dessinez, sinon le jeu semble injuste.

  • Une fonction peut renvoyer plusieurs valeurs, et seul le dernier appel d’une liste d’arguments les transmet toutes.

  • Les tests de collision ne font que répondre. Ce qui se passe ensuite, c’est votre code, et garder les deux à part vous permet de changer l’un sans l’autre.

  • Dessiner vos boîtes de collision à l’écran transforme un bogue invisible en bogue visible.

  • onCollision est pour les corps de la physique 3D, pas pour les sprites de l’overlay.

La prochaine fois

Le jeu compte votre score et vous prend vos vies, et dès que vous quittez, le meilleur score jamais obtenu disparaît. Il démarre au milieu de l’action à l’instant où il se charge. Et il garde la trace de ce qu’il fait avec deux variables vrai-ou-faux, over et dying, ce qui est exactement le piège dont la leçon sept vous a prévenu. La leçon douze lui donne un écran titre, une seule variable à la place de ces deux-là, et un meilleur score qui est toujours là le lendemain.

Leçon 12 : Score, vies et fin de partie

La leçon terminée

Votre jeu tient le score, retire des vies et affiche GAME OVER. C’est presque un jeu. Il manque encore trois choses. Il n’a pas de porte d’entrée : il est au milieu de l’action à l’instant où il se charge. Il oublie : quittez-le, et le meilleur score jamais obtenu part avec. Et il garde la trace de ce qu’il fait avec deux variables vrai-ou-faux, over et dying, ce qui est le piège dont la leçon sept vous a prévenu.

Cette leçon règle les trois. Une seule variable pour ce que fait le jeu, un écran titre d’où partir, un meilleur score qui est toujours là le lendemain, et une deuxième partie qui commence exactement comme la première.

Un jeu est toujours dans exactement un état

Regardez n’importe quelle borne d’arcade pendant deux minutes. Elle affiche un titre et attend quelqu’un. Quelqu’un appuie sur start et elle joue. Le joueur n’a plus de vies et elle le dit, puis elle se remet à attendre. La machine fait toujours exactement une de ces choses.

Dodge, à la leçon sept, gardait cela dans une seule variable qui contenait un mot : "waiting", "playing" ou "over". Le jeu de la leçon neuf est revenu à un over vrai-ou-faux, et la leçon dix a ajouté dying à côté. Comptez ce que deux de ces variables peuvent dire. Chacune vaut true ou false, donc ensemble elles font quatre combinaisons. Trois veulent dire quelque chose : la partie en cours, la mort du vaisseau et la fin de partie. La quatrième, les deux à la fois, est absurde, et votre code doit prendre soin de ne jamais la produire. Il en prend soin : regardez endGame, qui remet dying à false avant de mettre over à true. Ajoutez maintenant un écran titre. Ça fait un troisième drapeau, huit combinaisons, dont quatre absurdes. C’est exactement le piège de la leçon sept, et c’est là que les petits jeux vont mourir.

Alors faites comme Dodge. Quatre états, une seule variable. Mettez les noms des états sous vos autres constantes :

local TITLE   = "title"
local PLAYING = "playing"
local DYING   = "dying"
local OVER    = "over"

Puis retirez over et dying de vos variables, et mettez une seule ligne à leur place :

local state        = TITLE

Dodge se servait des mots eux-mêmes. Des noms en majuscules ne sont pas plus malins, et ils ne rattrapent pas une faute de frappe : Lua traite un nom mal tapé comme nil et un mot mal tapé comme un mot qui ne correspond à rien, et l’un comme l’autre vous donne un jeu qui cesse sans bruit de répondre. Ce que les noms vous apportent, c’est une liste. Chaque état dans lequel le jeu peut se trouver est écrit une fois, en haut du fichier, là où vous voyez les quatre d’un coup d’œil.

Partout où le jeu levait un drapeau, il règle maintenant l’état. Dans updateRocks, là où la dernière vie s’en va :

            if lives <= 0 then
                state        = DYING
                deathChannel = channel

Dans endGame, deux lignes n’en font plus qu’une, et la combinaison absurde a disparu parce qu’il ne reste plus rien à combiner :

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
end

Et dans startGame, les deux lignes qui baissaient les deux drapeaux deviennent state = PLAYING.

Un seul endroit qui décide

À chaque image, onOverlayUpdate prend les deux décisions qui comptent : ce qui bouge, et quels mots vont par-dessus. Ce qui bouge tient en un seul test :

    if state == PLAYING then
        updateShip()
        updateShots()
        updateRocks()
    end

Ça remplace if not over and not dying then, et ça dit ce que ça veut dire. Sur l’écran titre, pendant que joue la dernière explosion, et une fois la partie finie, rien ne bouge. Vous l’obtenez en n’appelant pas les fonctions qui font bouger les choses. Arrêter un jeu n’est pas une fonctionnalité spéciale ; c’est laisser des choses de côté.

Le monde est toujours dessiné à chaque image, quel que soit l’état, exactement comme Dodge le dessinait. Seuls les mots changent. Remplacez la ligne drawHud() par ceci :

    if state == TITLE then
        drawTitle()
    else
        drawHud()
    end

drawTitle est une nouvelle fonction, et elle va après drawStars :

function drawTitle()
    overlayPrint(25, 6, "R O C K S")
    overlayPrint(25, 9, "BEST " .. best)
    overlayPrint(22, 12, "PRESS 1 TO PLAY")
end

best est le meilleur score jusqu’ici, et il arrive à la section suivante ; le jeu ne tournera pas tant qu’il ne sera pas là. Avant la première partie, la liste des rochers est vide, donc ce que montre l’écran titre, ce sont les étoiles qui défilent et le vaisseau qui attend en bas, et c’est tout ce dont un écran titre a besoin.

Une ligne doit partir, sinon vous ne verrez jamais l’écran titre. Supprimez le startGame() tout en bas du fichier. Le jeu commence maintenant sur son écran titre, et Recommencer une partie explique pourquoi cette ligne compte.

drawHud pose lui-même une question. Changez son if over then en :

    if state == OVER then

Le callback des commandes demande le même genre de réflexion. Le voici en entier :

function onInputPressed(what)
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 and state == PLAYING then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then
        soundPlay(clickClip)
        startGame()
    end
end

Lisez-le depuis le haut. Les touches fléchées sont notées quel que soit l’état, parce qu’elles disent seulement quelles touches sont enfoncées, et rien ne fait bouger le vaisseau tant que l’état n’est pas PLAYING. Le tir ne veut dire quelque chose que pendant la partie. Et 1 lance une partie depuis l’écran titre ou depuis l’écran de fin de partie, mais pas pendant que la dernière explosion résonne encore : la partie n’est pas finie tant qu’elle ne l’a pas dit. Les parenthèses marchent comme en arithmétique. Le or qu’elles contiennent est calculé d’abord, puis le and le relie à la touche.

Score et vies

Vous avez les deux depuis la leçon neuf, et ils ne changent presque pas. Ce qui est nouveau, c’est le meilleur score, qui commence sa vie comme une variable ordinaire. Mettez-le avec les autres, sous lives :

local best         = 0

Affichez-le sur la ligne du haut, entre les deux autres. Dans drawHud :

    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(25, 1, "BEST " .. best)
    overlayPrint(50, 1, "LIVES " .. lives)

Et donnez à endGame la tâche de remarquer un record :

    if score > best then
        best = score
    end

Lancez-le. L’écran titre affiche BEST 0. Appuyez sur 1, tirez sur quelque chose, perdez, et l’écran de fin de partie montre votre score comme meilleur score. Appuyez de nouveau sur 1 : le meilleur score reste, et le score repart de zéro. Maintenant, quittez, relancez, et regardez l’écran titre : BEST 0. Le record a vécu exactement aussi longtemps que le programme. C’est la deuxième moitié de cette leçon.

Pendant que vous regardez les vies, remarquez que la leçon neuf a écrit le test lives ⇐ 0, et non lives == 0, et gardez-le ainsi. Aujourd’hui, rien ne peut retirer deux vies à la fois, donc les deux tests donnent forcément la même réponse. Le jour où vous ajouterez un rocher qui en coûte deux, == 0 enjambera zéro et le joueur continuera de jouer avec moins une vie, alors que ⇐ 0 continuera de marcher. Demandez ce que vous voulez dire.

Recommencer une partie

Vous avez déjà supprimé le startGame() du bas du fichier. À la leçon dix, la première partie était lancée par cette ligne et toutes les suivantes par un appui sur 1, ce qui faisait deux entrées. Maintenant, il n’y en a plus qu’une. Chaque partie, la première comprise, commence quand quelqu’un appuie sur 1 et que startGame s’exécute, donc la première partie et la cinquième commencent exactement de la même façon.

startGame doit remettre en place tout ce qu’une partie change :

function startGame()
    shipX        = (screenWidth - shipWidth) / 2
    score        = 0
    lives        = START_LIVES
    state        = PLAYING
    deathChannel = -1
    shots        = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
    musicSetVolume(50)
    musicPlay(theme, -1)
end

Il est tout aussi important de savoir ce qu’il laisse tranquille, et pourquoi. best survit à toutes les parties ; c’est tout son travail. Les étoiles sont du décor. Et goLeft et goRight n’appartiennent pas du tout au jeu. Elles représentent le clavier, et seul le clavier doit les changer.

Ce dernier point est un bogue que vous venez de corriger sans le remarquer. Le callback des commandes de la leçon dix commençait par if over then, et tant que la partie était finie, il jetait toutes les touches sauf 1. Appuyez sur la flèche droite pendant que GAME OVER est affiché, gardez-la enfoncée, et appuyez sur 1. Le nouveau vaisseau reste immobile : l’appui sur la flèche droite a été jeté, le relâchement n’a pas encore eu lieu, et donc goRight vaut false alors que la touche est de toute évidence enfoncée. Le vaisseau ne bouge pas tant que vous ne lâchez pas la touche pour appuyer de nouveau. Le nouveau callback note les touches fléchées dans tous les états, donc la touche tenue est toujours tenue quand la partie commence.

Les bogues de redémarrage sont les bogues les plus courants de tous les jeux, et ils donnent tous la même impression quand on joue : la deuxième partie est subtilement fausse alors que la première allait bien. Quand ça arrive, lisez startGame et posez-vous deux questions. Qu’est-ce que la partie précédente a changé et que celle-ci ne remet pas en place ? Et qu’est-ce que celle-ci remet en place alors que ce n’était pas au jeu d’y toucher ?

Un nombre qui survit au programme

Tout ce que votre jeu a gardé jusqu’ici — score, lives, la liste des rochers — vit en mémoire, et la mémoire disparaît à l’instant où le programme s’arrête.

Singe donne à chaque jeu une sauvegarde bien à lui : un ensemble de noms avec des valeurs rangées dessous, écrit sur le disque pour vous. C’est une autre partie du kit de jeu de la leçon onze, donc c’est le même genre de chose que collideRects : de simples appels, rien à charger ni à libérer.

saveSet("highScore", 4200)

saveSet prend un nom — la clé — et une valeur. La clé, c’est vous qui la choisissez, et elle ne change jamais ; la valeur, c’est ce dont vous voulez vous souvenir. Les nombres, les chaînes, true et false, et des tables entières de tout cela peuvent y aller. Ce qui n’a de sens que pendant que le programme tourne, non. Un handle de sprite n’est qu’un nombre, donc il se sauvegarde, et demain c’est un nombre qui ne veut plus rien dire. Une fonction ne peut pas du tout s’écrire sur le disque, et essayer d’en sauvegarder une arrête le jeu sur une erreur plutôt que de vous laisser le découvrir la semaine prochaine.

Relire la valeur, c’est l’autre moitié. Changez la ligne que vous avez ajoutée pour best :

local best         = saveGet("highScore", 0)

Elle s’exécute une fois, au démarrage du jeu. Le second argument est la valeur par défaut : ce qu’il faut répondre quand rien n’a jamais été sauvegardé sous cette clé. On y revient dans un instant, parce que c’est toute l’erreur de cette leçon.

Et faites en sorte que endGame note le record quand il tombe :

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
    if score > best then
        best = score
        saveSet("highScore", best)
        saveFlush()
    end
end

Vous n’avez pas à demander à Singe d’écrire le fichier. Il l’écrit une fois à la fin de chaque image où quelque chose a changé, quel que soit le nombre de clés que vous avez réglées, et de nouveau quand le jeu s’arrête. saveFlush, lui, l’écrit immédiatement : un nouveau meilleur score mérite une écriture de fichier rien qu’à lui, parce qu’on coupe une borne d’arcade à la prise et qu’une image, c’est long.

Lancez-le, établissez un score, quittez, et relancez-le. L’écran titre s’en souvient.

La section Sauvegarde de la Référence donne le reste de la famille. saveDelete oublie une clé, saveClear oublie tout — c’est le « remettre à zéro les meilleurs scores » d’un menu de service — et saveGetAll vous donne une copie de l’ensemble, ce qui est utile quand vous voulez afficher toute la sauvegarde pendant que vous traquez quelque chose.

Où va vraiment le fichier

Il ne va pas à côté de votre script, et ce n’est pas un hasard.

Un jeu fini peut se trouver sur un disque, sur un partage réseau, ou dans un seul fichier empaqueté (leçon trente), et on ne peut écrire dans aucun d’eux. Un jeu qui sauvegarde à côté de son propre script marche parfaitement sur la machine où vous l’avez écrit et échoue sur la moitié des machines où il est installé. Singe 2 faisait comme ça, et c’était une erreur.

Donc tout ce que Singe écrit pour un jeu — la sauvegarde, les captures d’écran, son journal — va au même endroit, et singeGetDataPath vous dira où :

debugPrint(singeGetDataPath())

Mettez ça juste sous la ligne dofile un instant et lancez-le. Il affiche data/rocks/ : le dossier data qui est apparu dans votre dossier de travail la première fois que vous avez lancé quoi que ce soit, à la leçon un, et dedans un dossier qui porte le nom du dossier de votre jeu. Vous y trouverez save.json. Ouvrez-le dans votre éditeur de texte : c’est du texte simple, et votre meilleur score s’y trouve, sous le nom que vous lui avez donné.

C’est aussi la réponse chaque fois que vous avez besoin d’un fichier à vous. Construisez son nom à partir de singeGetDataPath() et il atterrit dans un endroit où l’on peut écrire ; écrivez sous un nom de votre invention et tôt ou tard ce ne sera plus le cas.

La première fois, il n’y a rien

La toute première fois que quelqu’un lance votre jeu, aucun meilleur score n’a jamais été sauvegardé. saveGet n’a rien à renvoyer, alors il renvoie la valeur par défaut que vous lui avez donnée :

local best         = saveGet("highScore", 0)

Rien n’est sauvegardé, donc best vaut 0, l’écran titre affiche BEST 0, et la première partie que quelqu’un joue établit un record. C’est exactement ce que vous voulez, et ça coûte un argument de plus.

Oubliez le 0 et saveGet n’a pas de valeur par défaut sur laquelle se rabattre, alors il répond nil — la valeur dont Lua se sert pour dire « il n’y a rien ici », que vous avez rencontrée à la leçon trois. nil n’est pas zéro. Vous ne pouvez rien y ajouter, vous ne pouvez pas le comparer à un nombre, et vous ne pouvez pas le coller à une chaîne. Ça tourne mal dès la première image, à chaque fois, sur chaque machine où le jeu n’a jamais été joué — c’est-à-dire sur chaque machine où vos joueurs s’apprêtent à l’installer, et pas sur celle où vous testez.

Donnez une valeur par défaut à chaque saveGet. C’est l’habitude la moins chère de ce livre.

Ce qui vient de se passer

local TITLE   = "title"

Une constante : un nom que vous réglez une fois et ne changez jamais, en majuscules pour que vous voyiez d’un coup d’œil que c’en est une, comme à la leçon sept. Lua ne l’impose pas — rien ne vous empêche d’affecter une valeur à TITLE — alors les majuscules sont un message pour la prochaine personne qui lira le code, c’est-à-dire vous dans quinze jours.

    if state == PLAYING then

La question qui décide si le monde bouge. Quand vous ajouterez un cinquième état plus tard — une pause, ou un tour bonus — la première chose à vous demander sera si le monde bouge dans cet état, et c’est ici que va la réponse.

    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then

Sans les parenthèses, Lua relierait d’abord le and et lirait ceci comme « la touche est 1 et l’état est le titre, ou l’état est la fin de partie ». Alors n’importe quelle touche que les branches du dessus n’ont pas attrapée lancerait une partie depuis l’écran de fin de partie, le tir compris, et un joueur qui martèle encore le bouton de tir quand le dernier rocher le touche serait jeté dans une nouvelle partie dès l’apparition de GAME OVER. Les parenthèses font passer le or en premier. Quand vous mélangez and et or, mettez les parenthèses même si vous croyez connaître l’ordre. La prochaine personne qui lira la ligne n’aura pas besoin de le connaître.

        saveSet("highScore", best)
        saveFlush()

saveSet met le nombre dans la sauvegarde ; saveFlush met la sauvegarde sur le disque tout de suite plutôt qu’à la fin de l’image. Les deux sont dans le if, donc le fichier n’est écrit que quand le record est vraiment battu, ce qui arrive quelques fois par session plutôt que soixante fois par seconde.

local best         = saveGet("highScore", 0)

Lu une fois, au démarrage, dans une variable ordinaire. Le reste du jeu lit best au lieu de rappeler saveGet, parce que la sauvegarde est un fichier et qu’une variable est une variable. Écrivez dans les deux quand le record tombe.

Essayez

  1. Revenez à l’écran titre. Une borne d’arcade ne reste pas sur GAME OVER pour toujours. Cherchez timerAfter dans la section Minuteur de la Référence, une autre partie du kit de jeu, et servez-vous-en dans endGame pour remettre l’état à TITLE cinq secondes après la fin de la partie. Puis appuyez vite sur 1 après la fin d’une partie et vérifiez que le minuteur ne renvoie pas votre nouvelle partie à l’écran titre au bout de trois secondes.

  2. Montrez les vies sous forme de vaisseaux. Dessinez shipSprite une fois par vie dans le coin supérieur droit avec spriteDraw au lieu d’afficher le nombre. Une boucle for de la leçon quatre, et shipWidth vous dit à quelle distance les espacer.

  3. Sauvegardez plus qu’un nombre. Ajoutez saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1) à startGame, et affichez-le sur l’écran titre. Quittez, relancez, et regardez-le se souvenir.

  4. Trouvez le fichier et cassez-le. Ouvrez data/rocks/save.json dans votre éditeur, remplacez le meilleur score par quelque chose d’absurde, et lancez le jeu. Puis supprimez complètement le fichier et relancez-le. Ces deux choses arriveront à vos joueurs.

  5. Remettez-le à zéro depuis le jeu. Faites qu’une touche sur laquelle vous n’appuieriez jamais par accident appelle saveClear(), et regardez l’écran titre ensuite. Attention : best est toujours en mémoire, et saveClear n’y touche pas. Trouvez ce qui doit se passer d’autre.

Cassez-le exprès

Retirez la valeur par défaut, pour que la ligne devienne :

local best         = saveGet("highScore")

Si vous avez déjà établi un meilleur score, il ne se passe rien du tout, et c’est là le piège : la sauvegarde a la clé, donc saveGet la renvoie. Supprimez d’abord data/rocks/save.json, puis lancez-le. L’écran titre n’apparaît jamais, et vous obtenez ceci :

Error executing function 'onOverlayUpdate':  rocks/rocks.singe:101: attempt to concatenate a nil value (upvalue 'best')
stack traceback:
	rocks/rocks.singe:101: in function 'drawTitle'
	rocks/rocks.singe:165: in function 'onOverlayUpdate'

Lisez-le comme la leçon huit vous l’a appris. Le fichier et la ligne vous mènent à overlayPrint(25, 9, "BEST " .. best) dans drawTitle, et la plainte dit que quelque chose qui valait nil a été collé à une chaîne. .. joint deux chaînes, et nil n’en est pas une. Si vos lignes sont disposées autrement, vos numéros le seront aussi.

La ligne qu’elle nomme n’est pas celle où se trouve l’erreur. La ligne 101 est l’endroit où le jeu a fini par trébucher dessus ; l’erreur a été commise près du haut du fichier, là où on a demandé best et où il n’y avait rien. Cet écart entre l’endroit où une mauvaise valeur est fabriquée et celui où on la remarque est ce qu’il y a de plus difficile avec nil, et c’est la raison pour laquelle une valeur par défaut coûte un argument et épargne une soirée.

Remettez le 0.

Ce que vous avez appris

  • Un jeu est dans exactement un état à la fois, et les drapeaux vrai-ou-faux qui essaient de dire lequel engendrent des combinaisons qui ne veulent rien dire.

  • Gardez l’état dans une seule variable, avec ses valeurs possibles nommées une fois en haut du fichier.

  • onOverlayUpdate décide de ce qui bouge et de ce qui est dit, en interrogeant l’état.

  • Arrêter un jeu, c’est simplement ne pas appeler ce qui le fait bouger.

  • Faites commencer chaque partie, la première comprise, par une seule fonction, et faites-lui remettre en place tout ce qu’une partie change — et rien d’autre.

  • Les touches appartiennent au clavier. Notez-les dans tous les états.

  • saveSet range une valeur sous une clé, et saveGet la relit lors d’un lancement ultérieur.

  • saveFlush écrit le fichier tout de suite, pour les choses que vous détesteriez perdre.

  • La sauvegarde va dans le dossier de données propre au jeu, que nomme singeGetDataPath. N’écrivez jamais à côté de votre script.

  • saveGet sans valeur par défaut répond nil quand rien n’a été sauvegardé, et nil casse la première image sur une machine qui n’a jamais lancé votre jeu.

  • Quand vous mélangez and et or, mettez des parenthèses.

La prochaine fois

Votre jeu est maintenant un jeu, et c’est un dossier que vous seul savez lancer. La leçon treize lui donne un games.dat, pour que le menu du moteur lui-même le liste avec un titre et une image, et qu’un joueur qui n’a jamais entendu parler de vous puisse le lancer sans rien taper.

Leçon 13 : Un dossier de jeu

La leçon terminée

Votre jeu est un script dans un dossier dont vous vous rappelez le nom, et vous le lancez en tapant son nom dans un terminal. C’est très bien pour vous et inutile pour n’importe qui d’autre. Un joueur devrait pouvoir copier un dossier à côté de Singe, lancer le menu, voir votre jeu dans la liste avec son titre et ses illustrations, et appuyer sur un bouton. L’image ci-dessus, c’est ce menu, avec votre jeu dedans.

Il faut pour cela un nouveau fichier, d’environ six lignes, et deux images que vous pouvez prendre avec une seule touche. Votre script ne change pas du tout.

Donnez un nom au jeu

Un jeu a deux noms, un pour l’ordinateur et un pour les gens.

Celui de l’ordinateur, c’est le dossier, et vous l’avez choisi à la leçon neuf : rocks, avec rocks.singe dedans. Le dossier et le script portent le même nom, comme dans chaque leçon depuis la leçon un, et c’est pourquoi Singe rocks trouve le script à partir du dossier seul. Gardez ce nom simple. Pas d’espaces, qu’un terminal lit comme l’écart entre deux noms. Et les mêmes majuscules partout où vous le tapez : sur la plupart des ordinateurs qui ne sont pas sous Windows, rocks et Rocks sont deux dossiers différents, et un jeu qui ne tourne que sur votre machine n’est pas un jeu que quelqu’un d’autre peut avoir.

Le nom pour les gens peut être tout ce que vous voulez, majuscules, espaces et tout le reste, et il ne vit pas dans le nom du dossier. Il vit dans le fichier dont parle cette leçon, pour que renommer le jeu dans le menu ne veuille jamais dire renommer un dossier.

Ce qui va dans le dossier

Tout ce dont votre jeu a besoin, et rien d’autre. À la fin de cette leçon, il ressemble à ceci :

rocks/
    games.dat       Ce que lit le menu
    rocks.singe     Le jeu
    art/            Le kit graphique de la leçon neuf
        spaceship.png
        asteroid.png
        bullet.png
        star.png
        shoot.wav
        boom.wav
        ...
    cabinet.png     Une image que le menu montre à côté de la liste
    marquee.png     Une image que le menu montre au-dessus

Tout ce qui a pu atterrir là pendant que vous appreniez — walk.singe de la leçon neuf, le petit test du son de la leçon dix — ne fait pas partie du jeu. Déplacez-les dans un dossier à eux, à côté de rocks. Le kit graphique contient aussi quelques fichiers que ce jeu ne charge jamais, et ils ne font aucun mal pour l’instant. C’est à la leçon trente que vous passerez un dossier de jeu en revue pour en retirer tout ce qui n’est pas le jeu.

La règle derrière cette organisation, c’est qu’un jeu ne va jamais rien chercher hors de son propre dossier. Ni une illustration, ni un son, ni une bibliothèque dont vous vous servez aussi dans un autre jeu — si vous partagez du code entre deux jeux, chacun garde sa propre copie. Il y a exactement un endroit hors du dossier où un jeu a le droit de charger quelque chose, et vous y chargez déjà : le dossier Singe du moteur lui-même, où se trouve Singe/Framework.singe, et, depuis la leçon dix, le clic et la musique.

Le dossier du jeu se trouve dans votre dossier de travail, à côté du moteur :

singe/                 Votre dossier de travail
    Singe-v3.00-...    Le moteur lui-même, quel que soit le nom du vôtre
    Menu.sh            Lance le menu.  Menu.bat sous Windows
    Singe/             Fichiers de support.  Pas à vous ; n'y touchez pas
    data/              Tout ce qui s'écrit, votre sauvegarde comprise
    rocks/             Votre jeu

C’est aussi la forme qu’a la machine d’un joueur. Le moteur a écrit Singe, data et Menu.sh (Menu.bat sous Windows) la première fois que vous avez lancé quoi que ce soit, à la leçon un. La leçon un a parlé des deux premiers. Le troisième est nouveau pour vous, et cette leçon le met au travail.

Les chemins partent de l’endroit où Singe a démarré

Vous faites ça depuis la leçon neuf, donc c’est un rappel, pas un changement.

Chaque nom que votre jeu charge — art/spaceship.png, art/boom.wav — est cherché à partir du dossier dans lequel Singe a été lancé, et non du dossier où se trouve votre script. Vous lancez Singe dans votre dossier de travail, donc un simple art/spaceship.png serait cherché dans singe/art, qui n’existe pas. DIR est le dossier de votre script lui-même, avec la barre oblique déjà au bout, donc un nom qu’on y colle désigne votre fichier, d’où que Singe ait été lancé :

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

Le menu lance Singe dans le dossier où se trouve Menu.sh, c’est-à-dire de nouveau votre dossier de travail, donc DIR y fait exactement ce qu’il fait pour vous. Il continue de le faire quand le jeu est empaqueté dans un seul fichier à la leçon trente, quand le dossier de travail de quelqu’un d’autre s’appelle tout autrement, et sur une machine que vous ne verrez jamais. Un nom qui commence par Singe/ désigne le dossier du moteur et n’a jamais besoin de DIR ; chaque nom qui est à vous en a besoin.

games.dat

games.dat, c’est la façon dont un jeu se présente. Le menu lit le games.dat de chaque dossier de jeu qui se trouve à côté de lui, et liste ce qu’il trouve. Pas de games.dat, pas de place dans la liste : votre dossier est invisible, aussi bon que soit le jeu qu’il contient.

Créez un nouveau fichier appelé games.dat dans votre dossier rocks. Voici le plus petit qui marche :

GAMES = {
    {
        TITLE  = "Rocks",
        SCRIPT = "rocks/rocks.singe"
    }
}

C’est du Lua, et c’est une table du genre de celles que vous avez rencontrées à la leçon six : GAMES est une liste, et chaque élément de la liste est un enregistrement qui décrit un jeu. Un dossier peut contenir plusieurs jeux — c’est pour ça que c’est une liste — mais le vôtre n’en contient qu’un.

SCRIPT est le champ dont le moteur a besoin pour lancer le jeu, et TITLE celui dont le menu a besoin pour le lister. Le chemin du script part du dossier au-dessus du games.dat, et non du dossier où se trouve le games.dat. Donc un games.dat placé dans rocks désigne son propre script par rocks/rocks.singe. On dirait que ça dit rocks deux fois, et c’est correct. Tous les autres chemins du fichier marchent de la même façon. Trompez-vous, et rien ne proteste quand vous tapez le nom : l’entrée ne correspond simplement jamais au script que vous avez lancé.

TITLE, c’est le nom pour les gens du début de cette leçon. C’est ce qu’affiche le menu, et les jeux sont listés dans l’ordre de leurs titres, donc le titre décide aussi de la place de votre jeu dans la liste.

En dire plus au menu

Le menu a tout un panneau à remplir à côté de la liste, et il le remplit avec le reste de l’entrée :

GAMES = {
    {
        TITLE       = "Rocks",
        SCRIPT      = "rocks/rocks.singe",
        CANVAS_X    = 720,
        CANVAS_Y    = 480,
        YEAR        = 2026,
        GENRE       = "Shooter",
        DEVELOPER   = "Your Name Here",
        PUBLISHER   = "Your Name Here",
        DESCRIPTION = "Shoot the rocks before they reach your ship.",
        CABINET     = "rocks/cabinet.png",
        MARQUEE     = "rocks/marquee.png"
    }
}

CABINET et MARQUEE sont des fichiers d’image ordinaires dans le dossier de votre jeu, dans n’importe quel format que Singe sait lire. L’illustration de borne est la grande image à côté de la liste, et le fronton est la bande au-dessus. Donnez-leur la taille que vous voulez ; le menu les ajuste à leurs panneaux.

Vous n’avez pas besoin d’un logiciel de dessin pour les faire, parce que votre jeu peut prendre sa propre photo. Lancez-le, et quand l’écran ressemble à ce que vous voulez montrer au monde, appuyez sur F12 (ou F11, parce que certains bureaux gardent F12 pour eux). Singe enregistre une image de la fenêtre dans le dossier de données de votre jeu, data/rocks, sous le nom singe000.png, puis singe001.png, et ainsi de suite. Prenez-en une de l’écran titre et une au milieu d’un combat. Copiez-les dans votre dossier rocks et renommez-les : le combat devient cabinet.png, le titre marquee.png.

Un vrai fronton est une large bande avec le nom du jeu en grosses lettres, et un écran entier tassé dedans ressemble à un timbre-poste. Ça fera l’affaire en attendant mieux. Laissez de côté MARQUEE et le menu met à la place l’image manquante du moteur lui-même, un damier rose qui dit MISSING, ce qui est pire.

YEAR, GENRE, DEVELOPER, PUBLISHER et DESCRIPTION sont le texte en dessous, et le moteur ne les regarde jamais. Ils sont là pour la personne qui lit le menu, et c’est bien le but.

CANVAS_X et CANVAS_Y sont la taille du monde de votre jeu, et 720 sur 480 est la valeur par défaut — le même monde que celui où vous dessinez depuis la leçon un. Ne les réglez que si votre jeu veut une autre forme. Un jeu sans champ VIDEO est un jeu sans vidéo, ce qui est le cas du vôtre ; c’est à la leçon quatorze que ce champ commence à compter.

La section games.dat de la Référence donne tous les champs qui existent, dont plusieurs pour du matériel que vous n’avez pas encore. Quelques autres méritent que vous connaissiez leur nom dès maintenant.

REQUIRES dit ce dont un jeu a besoin de la part de la machine au-delà de la simple 2D : "GUI" pour les menus et les pages de la leçon vingt, "SCENE" pour la 3D qui commence à la leçon vingt-deux, et quelques autres. Le menu le lit pour pouvoir dire à un joueur « cette machine ne peut pas faire tourner ce jeu » au lieu de laisser le jeu échouer en plein milieu. Rocks, c’est de la 2D toute simple, et laisser de côté REQUIRES veut dire exactement ça, donc laissez-le de côté. Vous aurez rarement à dresser la liste vous-même, parce que Singe remarque ce dont un jeu se sert pendant qu’il tourne, et le dit quand l’entrée ne le liste pas. À partir de la leçon vingt, vous verrez des lignes comme celle-ci, que le jeu ait un games.dat ou non :

Warning:  this game uses GUI, which its games.dat does not list in REQUIRES.

C’est un conseil, pas une erreur ; le jeu tourne dans les deux cas. Le remède tient en une ligne dans l’entrée, REQUIRES = { "GUI" },, et empaqueter un jeu à la leçon trente écrit la liste pour vous si l’entrée n’en a pas. Son partenaire TIER, un nombre de 0 à 3, dit quelle puissance de machine un jeu demande, et peut attendre que vous écriviez un jeu assez lourd pour que ça compte.

GAME_ID est une identité unique pour votre jeu, dont les tableaux des scores en ligne de la leçon vingt-huit ont besoin, et rien d’autre. Et RESOLUTION_X et RESOLUTION_Y demandent une taille de fenêtre précise. Ignorez le reste jusqu’à ce que quelque chose vous envoie le chercher.

Le lancer depuis le menu

Lancez Menu.sh — Menu.bat sous Windows — depuis votre dossier de travail. Il trouve le Singe le plus récent à côté de lui et lance le menu.

Votre jeu est dans la liste, avec ses illustrations à côté et sa description en dessous. C’est la seule chose dans la liste, parce que rocks est le seul dossier auquel vous avez donné un games.dat ; hello, dodge et les autres ne sont pas des jeux, pour autant que le menu puisse en juger. Haut et bas avancent d’un jeu, gauche et droite d’une page, et start ou un bouton de tir lance celui qui est sélectionné. Quittez le jeu avec Échap et vous voilà de retour au menu, sur le même jeu, prêt à repartir. Le menu se souvient aussi du jeu sur lequel vous étiez d’un lancement à l’autre.

C’est tout ce qu’il faut pour publier un jeu, du point de vue du moteur. Un joueur copie votre dossier à côté de Singe, et le jeu apparaît.

Taper le nom marche toujours, et marche de la même façon :

Singe rocks

Quand vous lancez un script à la main comme ça, Singe cherche un games.dat à côté de lui — et jusqu’à trois dossiers au-dessus — et si une entrée nomme le script que vous avez lancé, les réglages de cette entrée s’y appliquent. Un jeu se comporte donc de la même façon depuis un terminal que depuis le menu, ce qui veut dire que vous pouvez continuer à travailler comme avant, avec -R et un éditeur de texte, tout en vous fiant à ce qu’un joueur obtiendra. Il écrit aussi au même endroit : quelle que soit la façon dont votre jeu est lancé, sa sauvegarde est celle de data/rocks.

Plus tard : un seul fichier

Un dossier, c’est facile pour travailler et un peu malcommode à donner : une douzaine de fichiers, un dossier dans un dossier, et un joueur qui le décompresse au mauvais endroit. Un jeu Singe terminé peut être empaqueté dans un seul fichier .game que le moteur lance directement, illustrations, sons et tout le reste compris, et qu’un joueur copie à côté de Singe, un point c’est tout.

Rien dans votre jeu n’a besoin de changer pour ça. C’est la leçon trente, et ça vaut la peine d’attendre : empaquetez un jeu qui n’est pas fini et vous l’empaquetterez de nouveau demain.

Ce qui vient de se passer

GAMES = {
    {

Deux accolades, parce que c’est une liste d’enregistrements. L’extérieure, c’est la liste. L’intérieure, c’est le premier élément de la liste, c’est-à-dire l’enregistrement d’un jeu. Se tromper sur l’une des deux est l’erreur habituelle, et Lua vous donnera la ligne.

        SCRIPT      = "rocks/rocks.singe",

Compté à partir du dossier au-dessus du games.dat, c’est-à-dire votre dossier de travail. C’est le même nom que celui que vous taperiez après Singe pour lancer le script à la main, et c’est la façon la plus simple de vous en souvenir.

La virgule au bout de la ligne sépare un champ du suivant, exactement comme à la leçon six. Le dernier champ d’un enregistrement n’a pas de virgule après lui — Lua ne s’en offusque pas s’il en a une, mais laissez-la de côté et votre fichier ressemblera à celui de tout le monde. Une virgule qui manque au milieu, c’est une autre affaire, et c’est l’erreur de cette leçon.

        CABINET     = "rocks/cabinet.png",

Une image que charge le menu, pas votre jeu, donc elle est nommée comme SCRIPT, à partir du dossier du dessus, et pas avec DIR. DIR appartient à votre script pendant qu’il tourne, et le menu et le moteur lisent games.dat avant que votre script ait démarré.

Essayez

  1. Faites de meilleures illustrations. Si vous avez un logiciel de dessin, faites un vrai marquee.png : une large bande avec ROCKS écrit en travers en grosses lettres. Mettez-le à la place de la capture d’écran et regardez de nouveau le menu.

  2. Donnez un games.dat à Dodge. Écrivez un games.dat dans votre dossier dodge de la leçon sept et lancez le menu. Deux jeux maintenant, dans l’ordre des titres. Puis changez le TITLE de Rocks en Asteroid Field et regardez-le passer au-dessus de Dodge : la liste est triée par titre, pas par dossier.

  3. Cassez games.dat pour le menu. Supprimez l’une des accolades fermantes du games.dat de rocks et lancez le menu. Votre jeu a disparu de la liste, et le terminal dit pourquoi. Remettez-la.

  4. Trompez-vous de SCRIPT. Mettez CANVAS_X à 1280 et CANVAS_Y à 720, et lancez Singe rocks. L’aire de jeu est plus large. Changez maintenant SCRIPT en rocks.singe et relancez-le. Le jeu a retrouvé son ancienne taille, et rien ne vous l’a dit : l’entrée ne nomme plus le script que vous avez lancé, donc elle ne s’applique pas. Remettez les deux comme avant.

  5. Trouvez votre sauvegarde. Lancez le jeu depuis le menu, établissez un meilleur score, quittez pour revenir au menu, et quittez le menu. Lancez Singe rocks et regardez l’écran titre. Puis cherchez dans data/rocks le fichier qui s’en est souvenu.

Cassez-le exprès

Retirez la virgule au bout de la ligne TITLE, pour que le haut du fichier devienne :

GAMES = {
    {
        TITLE       = "Rocks"
        SCRIPT      = "rocks/rocks.singe",

Lancez Singe rocks. Le jeu démarre, et le terminal dit ceci :

Note:  rocks/games.dat ignored:  [string "rocks/games.dat"]:4: '}' expected (to close '{' at line 2) near 'SCRIPT'

Votre jeu tourne quand même, parce qu’un jeu lancé par son nom n’a pas besoin de son entrée. Il tourne simplement sans elle. Lancez le menu, en revanche, et votre jeu a disparu. Si c’était le seul, la liste affiche No games yet, et le terminal dit la même chose autrement :

rocks/games.dat:  rocks/games.dat:4: '}' expected (to close '{' at line 2) near 'SCRIPT'  Skipped.

Lisez-le comme n’importe quelle autre erreur Lua. Le fichier est rocks/games.dat et la ligne est la 4. Mais la ligne 4 est la ligne SCRIPT, et elle n’a rien de faux. L’erreur est au bout de la ligne 3. Après TITLE = "Rocks", Lua attendait soit une virgule et un autre champ, soit le } qui ferme l’enregistrement commencé à la ligne 2. Il a trouvé SCRIPT à la place, donc c’est à la ligne 4 qu’il s’en est aperçu. Sa proposition de correction — un } — est fausse ; sa ligne est décalée d’une. Quand une erreur désigne le début d’une ligne, regardez la fin de la ligne d’avant.

Remettez la virgule, et relancez le menu.

Ce que vous avez appris

  • Un jeu est un dossier : le script, ses illustrations et un games.dat, et rien qui vienne de l’extérieur, sauf le dossier Singe du moteur lui-même.

  • Le nom du dossier est pour l’ordinateur, donc gardez-le simple. Le nom pour les gens, c’est TITLE.

  • Les noms que charge votre script partent de l’endroit où Singe a été lancé, et c’est pourquoi chacun d’eux est construit à partir de DIR.

  • games.dat est un fichier Lua qui contient une liste GAMES, et chaque entrée est un jeu.

  • Une entrée a besoin de TITLE et de SCRIPT et de rien d’autre ; ses chemins partent du dossier au-dessus du games.dat.

  • CABINET, MARQUEE, YEAR, GENRE, DEVELOPER, PUBLISHER et DESCRIPTION sont ce que le menu montre au joueur, et F12 prend une image dont vous pouvez vous servir pour les deux premiers.

  • REQUIRES dit au menu ce dont un jeu a besoin au-delà de la 2D, et Singe vous prévient quand un jeu se sert de quelque chose que son entrée ne liste pas.

  • Menu.sh ou Menu.bat lance le menu fourni, qui liste chaque dossier de jeu à côté de lui, trié par titre.

  • Un jeu lancé par son nom reçoit lui aussi son entrée de games.dat, donc il se comporte de la même façon dans les deux cas, et un games.dat qui ne se charge pas est signalé, puis ignoré.

  • Un jeu terminé peut être empaqueté dans un seul fichier plus tard, à la leçon trente.

La prochaine fois

Voilà la deuxième partie terminée : vous avez un jeu, avec des illustrations, du son, des collisions, un score, et un moyen pour quelqu’un d’autre de le lancer. La troisième partie porte sur ce que presque aucun autre moteur ne fait — lire du film comme le monde où se déroule le jeu — et la leçon quatorze commence par le disque, l’image et l’attente.

Leçon 14 : Lire de la vidéo

La leçon terminée

Singe peut lire un film et faire tourner votre jeu à l’intérieur. L’image devient le monde, et l’overlay sur lequel vous dessinez depuis la leçon un est posé par-dessus. Dans cette leçon, vous allez lancer une vidéo, découvrir quelle image est affichée, l’arrêter, et sauter à n’importe quel moment de votre choix.

Avant tout cela, une chose doit être dite clairement, parce qu’elle décide si vous devez lire cette partie du livre ou non.

Un jeu ne lit de la vidéo que s’il le demande

Singe est un moteur de jeu. Tout ce que vous avez construit dans les première et deuxième parties — les sprites, le son, les collisions, le score, le dossier du jeu — c’est Singe tout entier, et rien de tout cela ne fait intervenir la vidéo. Ce qu’ajoute la troisième partie est un supplément : un jeu peut demander qu’un film soit lu derrière lui, et alors le film est le monde, au lieu d’un canevas noir.

Rien d’autre ne change. onOverlayUpdate est toujours appelé soixante fois par seconde. overlayPrint compte toujours en cellules de caractère. Vos sprites se dessinent là où ils se dessinaient avant. Un jeu avec vidéo et un jeu sans vidéo s’écrivent de la même façon, avec les mêmes fonctions, et partagent le même livre.

Donc, si le jeu que vous voulez faire ne contient pas de vidéo, vous pouvez refermer cette partie maintenant et passer à la quatrième. Rien dans la quatrième partie ne dépend de quoi que ce soit dans la troisième, et les seules leçons qui ont besoin de celle-ci sont les quatre qui la suivent.

Toujours là ? Bien.

Vous avez déjà une vidéo

Vous n’avez pas besoin d’en trouver une, d’en acheter une ou d’en fabriquer une. La première fois que vous avez lancé Singe, à la leçon un, un dossier appelé Singe est apparu dans votre dossier de travail. Ouvrez-le et regardez : parmi les fichiers que le moteur y a déballés, il y a menuBackground.mkv. C’est la toile de fond dont se sert le propre menu du moteur, elle fait 720 sur 480 pixels, et elle dure 420 images — environ quatorze secondes.

C’est la vidéo de cette leçon et des deux suivantes.

Créez un dossier appelé movie dans votre dossier de travail, à côté des dossiers des autres leçons, et dedans un fichier appelé movie.singe. C’est toute la préparation qu’il y a à faire. Vous lancez Singe depuis le dossier de travail, comme vous le faites depuis la leçon un, donc le dossier Singe, vidéo comprise, est juste là à côté de votre jeu, et Singe/menuBackground.mkv est le nom que vous donnerez au moteur dans un instant. Il n’y a rien à copier.

Tapez ceci

dofile("Singe/Framework.singe")


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    return OVERLAY_UPDATED
end


discPlay()

Enregistrez-le.

Lancez-le

La vidéo ne fait pas partie de votre script, donc vous ne la chargez pas dans votre script. Vous la donnez au moteur sur la ligne de commande, avec -v :

Singe -R -v Singe/menuBackground.mkv movie

-v est la forme courte de --framefile, et il nomme la vidéo que le jeu doit lire. Le nom de votre script vient en dernier, comme toujours. -R est le même -R que celui dont vous vous servez depuis la leçon un, et il relance toujours le jeu quand vous enregistrez.

Demander, c’est tout l’intérêt de -v. Si vous déposez un fichier vidéo à côté de votre script sans rien dire, le moteur le remarque, le dit dans la console, et lance votre jeu sans lui. Un jeu n’est un jeu vidéo que lorsque quelqu’un le dit.

Une fenêtre s’ouvre. Une boule de feu orange la remplit, un dragon se forme à partir du feu, le mot SINGE apparaît en dessous, puis une grille magenta s’éloigne en défilant sous un soleil orange. Dans le coin supérieur gauche, par-dessus tout ça, un nombre compte.

Regardez-la jusqu’au bout. Puis regardez ce qui se passe à la fin.

Ce qui vient de se passer

discPlay()

Singe appelle la vidéo le disque, et chaque fonction qui la pilote commence par disc. Le nom est historique : le moteur a commencé sa vie en faisant tourner des jeux qui gardaient leur film sur un laserdisc, et le nom est resté attaché à l’idée. C’est un fichier vidéo sur votre disque dur, et rien de plus.

Un jeu a au plus un disque, donc aucune des fonctions disc ne prend d’argument pour dire lequel. Il n’y en a qu’un.

Cette ligne n’est dans aucune fonction. Elle est en bas du fichier, toute seule, et elle s’exécute une fois quand Singe charge votre script — avant le premier onOverlayUpdate, avant tout le reste. Singe n’a pas de callback onStartup parce qu’il n’en a pas besoin : un script Lua est une liste d’instructions, et tout ce que vous écrivez hors d’une fonction se produit pendant la lecture du fichier. Par convention, le code de démarrage va en bas, sous les fonctions.

Il vous faut discPlay() parce que le disque ne démarre pas tout seul. Quand le jeu commence, le moteur gare le disque sur l’image un et le met en pause là. Rien ne bouge tant que vous ne le demandez pas.

    overlayPrint(2, 2, "Frame " .. discGetFrame())

discGetFrame répond à une seule question : quelle image est affichée en ce moment ? Il ne prend pas d’argument et renvoie un nombre.

Remarquez où ce nombre est dessiné. Colonne 2, ligne 2 — exactement là où Hello! est allé à la leçon un, et il tombe au même endroit à l’écran. L’overlay sur lequel vous dessinez fait la moitié de la taille de la vidéo dans chaque sens, ce qui, pour une vidéo de 720 sur 480, donne 360 sur 240, c’est-à-dire exactement la taille à laquelle vous dessinez depuis treize leçons. Vos coordonnées n’ont pas bougé. Si un jour vous lisez une vidéo d’une autre taille, l’overlay change de taille avec elle, et overlaySetResolution le règle à la taille que vous voulez ; l’entrée de la Référence donne les détails.

C’est toute l’idée de l’overlay. La vidéo est en dessous. Votre dessin est par-dessus, et partout où vous n’avez pas dessiné, le film transparaît. C’est pourquoi overlayClear compte encore plus maintenant qu’avant : effacez l’overlay et c’est le film que vous regardez.

Une image est une adresse

Le nombre que renvoie discGetFrame est un numéro d'image. Une image, c’est une seule vue fixe. Cette vidéo en contient 420 et en montre environ trente par seconde, donc elle dure environ quatorze secondes.

Les images sont comptées à partir de zéro, donc cette vidéo a les images 0 à 419. Le nombre d’images et le dernier numéro ne sont pas les mêmes, ce qui piège tout le monde une fois. discGetFrameCount vous donne le nombre — 420 — et l’image la plus haute que vous pouvez demander est un de moins.

Ce qui compte avec un numéro d’image, c’est qu’il ne change jamais et ne dérive jamais. L’image 110 est le moment où le dragon crache du feu, dans cette copie du fichier, sur cette machine, aujourd’hui comme l’an prochain. Les secondes dérivent, parce qu’une vidéo ne se lit pas toujours exactement à la cadence que vous croyez. Un numéro d’image est l’adresse d’un moment, et les adresses sont ce dont est fait un jeu vidéo : vous notez l’image où le dragon apparaît, et à partir de là vous pouvez envoyer le film à cet endroit quand vous voulez.

Trouver ces numéros est un travail que vous faites une fois par vidéo, et le script que vous avez écrit est l’outil qu’il faut : lancez le film, regardez le compteur, notez les images où il se passe quelque chose. Tout ce que contient la leçon seize repose sur une liste de numéros trouvés exactement de cette façon.

Ce qui s’est passé à la fin

Le compteur a atteint 419, puis il est revenu à 0 et le feu était de retour.

Quand le disque arrive au bout, le moteur le relance depuis l’image zéro. Il ne s’arrête pas, et il ne vous prévient pas. Un vrai jeu ne le laisse jamais arriver là : il surveille le numéro d’image et envoie le disque ailleurs avant que la fin n’arrive. Oublier de le faire, voilà pourquoi un jeu vidéo à moitié fini se met soudain à jouer sa propre séquence de titre au milieu d’un combat.

Arrêter, sauter et demander

Ajoutez cette fonction au-dessus de onOverlayUpdate :

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
    end
end

Enregistrez, et essayez chacune. Espace lit et met en pause. Gauche revient au début. Droite saute environ une seconde plus loin. La touche 1 arrête complètement le disque, et ce que vous obtenez est un écran bleu — la couleur qu’affichait un lecteur de laserdisc à l’arrêt, conservée parce qu’énormément de jeux dessinaient leur tableau des scores dessus.

Cinq nouveaux appels, et ils se divisent en deux sortes.

Demander. discGetState renvoie l’un de quatre noms que le moteur a déjà définis pour vous : DISC_PLAYING, DISC_PAUSED, DISC_STOPPED et DISC_EJECTED. Ils sont comme OVERLAY_UPDATED — pas de guillemets, parce que ce sont des noms de valeurs et non du texte. Comparez avec ==, comme vous avez comparé des nombres à la leçon trois.

Ordonner. discPlay démarre ou reprend. discPause fige l’image affichée et la laisse à l’écran. discStop est le plus lourd : l’image est remplacée par l’écran bleu, discGetFrame répond 0 jusqu’à ce que le disque reparte, et discPause et les appels de saut sont ignorés tant qu’il est arrêté. N’importe lequel de discPlay, discSearch ou discSkipToFrame le fait repartir.

Deux appels envoient le disque à une image, et la différence entre eux est la seule chose de cette leçon qui mérite d’être apprise par cœur :

  • discSearch(frame) y va et s’y met en pause.

  • discSkipToFrame(frame) y va et lit à partir de là.

Search, c’est pour vous garer sur une image et attendre. Skip, c’est pour qu’une scène commence. discSkipForward(30) et discSkipBackward(30) sont la même idée, mesurée depuis l’endroit où vous êtes plutôt que depuis le début, et ils laissent le disque en lecture s’il lisait et en pause s’il était en pause.

Il existe aussi discPauseAtFrame, qui fait exactement ce que fait discSearch, sous un nom plus ancien. La Référence le marque comme alias hérité. Vous le verrez dans les scripts des autres ; écrivez discSearch dans les vôtres.

Attendre est plus difficile qu’il n’y paraît

Voici la phrase dont est fait chaque jeu vidéo :

Lire de l’image 0 à l’image 120, puis poser une question au joueur.

Essayez de l’écrire. Vous ne pouvez pas écrire « lire, puis attendre, puis demander », parce que vous n’avez nulle part où l’écrire. Vous avez onOverlayUpdate, que Singe appelle soixante fois par seconde et qui doit rendre la main immédiatement, à chaque fois. Une fonction qui resterait là à attendre arrêterait net le moteur : plus de dessin, plus de commandes, plus de vidéo.

Donc vous ne pouvez pas dire « puis ». Vous devez transformer « puis » en une variable qui se souvient d’où vous en êtes, et la vérifier à chacun de ces soixante appels :

local asking = false


function onOverlayUpdate()
    overlayClear()
    if not asking and discGetFrame() >= 120 then
        discPause()
        asking = true
    end
    if asking then
        overlayPrint(2, 4, "Left or right?")
    end
    return OVERLAY_UPDATED
end

Ça marche. Lisez-le et vous voyez que ça marche. Mais remarquez ce que ça a coûté : une variable, dont le seul travail est de se souvenir de l’endroit de la phrase où vous en êtes, et deux instructions if pour la garder honnête.

Maintenant, ajoutez le reste de la scène. Le joueur répond, donc l’une de deux choses se joue ensuite. Chacune finit quelque part et pose une autre question. Un modeste jeu à embranchements a quarante de ces moments, et chacun veut sa propre variable et son propre if. Vous finissez avec un script où l’histoire n’est écrite nulle part — elle est éparpillée entre une douzaine de drapeaux, et pour savoir ce qui se passe après le dragon, il faut tous les lire.

Gardez cette idée en tête. La leçon quinze n’est rien d’autre que le remède.

Quand il n’y a pas de vidéo

Relancez votre script de la façon simple, sans -v :

Singe -R movie

Rien ne plante. Vous obtenez une fenêtre noire avec Frame 0 dans le coin.

Ça vaut la peine de le comprendre, parce que c’est la moitié rassurante de la promesse faite au début de cette leçon. Un jeu sans disque exécute quand même chaque appel disc que vous faites ; ils ne font simplement rien d’utile. Le moteur documente exactement ce qu’ils répondent, et ça ne change jamais : discGetFrame et discGetFrameCount renvoient 0, discGetState renvoie DISC_EJECTED, discGetWidth et discGetHeight renvoient la taille du canevas, et discPlay, discPause, discSearch et les autres sont notés dans le journal et, pour le reste, ignorés.

Vous ne pouvez pas casser un script en appelant une fonction du disque quand il n’y a pas de disque.

Quand un script a besoin de savoir, il interroge SINGE_DISC. C’est un autre nom que le moteur définit avant que votre script s’exécute, et il vaut true quand le jeu a une vidéo et false quand le monde est un simple canevas. C’est la bonne façon d’écrire un jeu qui peut tourner dans les deux cas :

    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

not retourne une valeur vraie ou fausse, comme à la leçon trois.

Le tout

Mis bout à bout, avec une petite fonction qui transforme l’état en mots et une image à laquelle s’arrêter, voici le script terminé. C’est un chercheur d’images : l’outil dont vous vous servirez chaque fois que vous rencontrerez une nouvelle vidéo.

dofile("Singe/Framework.singe")

local stopAt = 400
local held   = false


local function stateName()
    local state = discGetState()

    if state == DISC_PLAYING then
        return "playing"
    elseif state == DISC_PAUSED then
        return "paused"
    elseif state == DISC_STOPPED then
        return "stopped"
    end
    return "not there"
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
        held = false
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
        held = false
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

    if not held and frame >= stopAt then
        discPause()
        held = true
    end

    overlayPrint(2, 2, "Frame " .. frame .. " of " .. discGetFrameCount())
    overlayPrint(2, 4, "The disc is " .. stateName() .. ".")
    overlayPrint(2, 6, "Space plays and pauses.  Left rewinds.")
    overlayPrint(2, 7, "Right jumps on a second.  1 stops the disc.")
    if held then
        overlayPrint(2, 9, "Holding at frame " .. stopAt .. ".")
    end

    return OVERLAY_UPDATED
end


discPlay()

held est le même genre de variable que asking plus haut, et il est là pour une raison que vous pouvez vérifier : retirez-le, laissez if frame >= stopAt then discPause() end, puis essayez d’appuyer sur espace pour continuer au-delà de l’image 400. Impossible. Le disque reprend pendant un soixantième de seconde et le onOverlayUpdate suivant le remet en pause, pour toujours. held, c’est la façon de dire « j’ai déjà fait ça une fois ».

Essayez

  1. Trouvez le dragon. Lancez-le, regardez le compteur, et notez l’image où le dragon apparaît pour la première fois, l’image où il crache du feu, et l’image où la grille envahit l’écran. Vous voudrez ces trois numéros à la leçon seize.

  2. Avancez pas à pas. Changez discSkipForward(30) en discSkipForward(1) et gardez la flèche droite enfoncée. Changez maintenant stopAt pour une image au milieu du dragon, et servez-vous de discSearch et de la touche fléchée pour tomber exactement dessus.

  3. Faites-le boucler. Changez l’arrêt pour qu’au lieu de mettre en pause à l’image 400, il appelle discSkipToFrame(0). Vous avez construit un mode attraction : une scène qui se joue sans fin jusqu’à ce que quelqu’un appuie sur un bouton.

  4. Demandez une image qui n’existe pas. Changez la ligne SWITCH_RIGHT en discSkipToFrame(100000). Ça ne plante pas. Lisez l’entrée de la Référence pour discSkipToFrame et trouvez la phrase qui dit pourquoi.

  5. Jouez-le sans la vidéo. Lancez Singe -R movie puis appuyez sur toutes les touches. Rien de ce que vous pressez ne peut le casser.

Cassez-le exprès

L’erreur qui coûte le plus de temps ici n’est pas une erreur de Lua. Lancez ceci :

Singe -R -v menuBackground.mkv movie

Le chemin est faux — il part du dossier de travail, et la vidéo y est dans le dossier Singe, pas en vrac — et Singe refuse de démarrer. Au lieu de ça, il affiche toute sa liste d’options de ligne de commande, ce qui est alarmant la première fois, puis ceci, tout à la fin :

Error:  Unable to locate video.

Un mur d’options comme celui-là veut toujours dire la même chose : le moteur n’est jamais allé jusqu’à votre jeu. Ignorez le mur et lisez la dernière ligne.

Celle-là est facile. Sa version la moins utile, c’est de lancer sans aucun -v et d’oublier que vous l’avez fait. Il n’y a pas d’erreur, parce qu’un jeu sans vidéo est un jeu parfaitement valable. Vous obtenez un écran noir et un compteur bloqué sur 0, et vous cherchez le bogue dans votre script pendant vingt minutes.

C’est à ça que sert le bloc SINGE_DISC du script terminé. Trois lignes, et le jeu vous dit ce qui ne va pas au lieu de bouder. Mettez une vérification comme celle-là dans chaque script que vous écrivez qui a besoin d’une vidéo.

Ce que vous avez appris

  • Un jeu ne lit de la vidéo que s’il le demande, et tout le reste de Singe marche de la même façon dans les deux cas.

  • Singe appelle la vidéo le disque. Un jeu en a un, et les fonctions disc ne prennent pas de handle parce qu’il n’y a rien à choisir.

  • La vidéo se donne sur la ligne de commande avec -v, pas dans le script.

  • L’overlay est dessiné par-dessus l’image, et le film transparaît partout où vous n’avez pas dessiné.

  • Une image est une vue fixe, comptée à partir de zéro, et un numéro d’image est l’adresse d’un moment.

  • discGetFrame demande où en est le disque ; discGetFrameCount dit combien il y a d’images ; discGetState dit ce que fait le disque.

  • discPlay, discPause et discStop le pilotent. discSearch va à une image et se met en pause ; discSkipToFrame va à une image et lit.

  • Un disque qui arrive au bout repart de l’image zéro sans vous prévenir.

  • Sans disque, chaque appel disc est inoffensif, et SINGE_DISC est la façon dont un script sait dans quel genre de jeu il se trouve.

  • Vous ne pouvez pas attendre dans onOverlayUpdate, donc « puis » doit s’écrire sous la forme d’une variable.

La prochaine fois

Ce dernier point est le point sensible. Un jeu vidéo est une liste d’étapes — lis ceci, demande cela, lis l’autre — et vous venez de voir que le modèle à callbacks ne sait pas dire « puis » sans un drapeau et un if pour chaque étape. La leçon quinze vous montre l’autre façon dont Singe vous laisse écrire un script, où « puis » est une nouvelle ligne.

Leçon 15 : L’autre façon de l’écrire

La leçon terminée

Toutes les leçons jusqu’ici ont été écrites de la même façon. Vous écrivez des fonctions dont le nom commence par on, Singe les appelle quand bon lui semble, et vous ne dites jamais dans quel ordre les choses se passent. C’est le modèle piloté par les événements, et c’est ainsi que fonctionnent la plupart des moteurs de jeu.

Singe a un second modèle. Dans celui-ci, vous écrivez votre jeu comme une liste d’étapes, de la première ligne à la dernière, et vous avez le droit d’attendre. Dans cette leçon, vous allez écrire la même petite séquence vidéo des deux façons et voir la différence de vos propres yeux.

La séquence

Voici ce que fait le jeu, en français :

  1. Démarrer le film au début et le lire jusqu’à l’image 120.

  2. S’arrêter là et demander au joueur d’appuyer sur la barre d’espace.

  3. Quand il appuie, continuer la lecture jusqu’à l’image 300.

  4. S’arrêter là, dire « The end. », attendre quatre secondes, et quitter.

Quatre étapes. Relisez-les et remarquez que chacune d’elles contient le mot « puis », dit ou sous-entendu.

La façon que vous connaissez

Créez un fichier appelé events.singe dans le dossier movie de la leçon quatorze, et tapez ceci :

dofile("Singe/Framework.singe")

local step    = 1
local endedAt = 0


function onInputPressed(what)
    if what == SWITCH_BUTTON1 and step == 2 then
        step = 3
        discPlay()
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    overlayPrint(2, 2, "Frame " .. frame)

    if step == 1 then
        if frame >= 120 then
            discPause()
            step = 2
        end
    elseif step == 2 then
        overlayPrint(2, 4, "Press the space bar to go on.")
    elseif step == 3 then
        if frame >= 300 then
            discPause()
            endedAt = singeGetTicks()
            step = 4
        end
    elseif step == 4 then
        overlayPrint(2, 4, "The end.")
        if singeGetTicks() - endedAt > 4000 then
            singeQuit()
        end
    end

    return OVERLAY_UPDATED
end


discSearch(0)
discPlay()

Lancez-le. Nommer le dossier lancerait movie.singe, alors nommez plutôt le script, comme la leçon un vous l’a montré :

Singe -R -v Singe/menuBackground.mkv movie/events.singe

Ça marche. Ça fait exactement les quatre étapes. singeGetTicks est nouveau — il renvoie le nombre de millisecondes écoulées depuis le démarrage du moteur, ce qui est la façon ordinaire de mesurer une durée — et singeQuit termine le jeu, ce que le moteur fait pour vous quand vous appuyez sur Échap.

Maintenant, lisez le script et essayez d’y trouver les quatre étapes. Elles y sont, mais retournées comme un gant. L’ordre de l’histoire est écrit dans les valeurs de step, pas dans l’ordre des lignes, et step est modifié dans une fonction et lu dans une autre. Pour répondre à « que se passe-t-il une fois que le joueur a appuyé sur Espace ? », il vous faut tenir tout le script dans votre tête d’un seul coup.

Et ceci est la version facile. Il y a deux décisions dedans.

L’autre façon

Commencez un nouveau fichier, steps.singe, et tapez ceci :

local message = ""
local pressed = false


local function drawFrame()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    overlayPrint(2, 4, message)
end


local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end


local function waitForButton()
    pressed = false
    while not pressed do
        drawFrame()
        singeYield()
    end
end


local function waitSeconds(seconds)
    local stopTime = singeGetTicks() + seconds * 1000

    while singeGetTicks() < stopTime do
        drawFrame()
        singeYield()
    end
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end


function singeMain()
    discSearch(0)
    discPlay()
    playTo(120)
    discPause()

    message = "Press the space bar to go on."
    waitForButton()

    message = ""
    discPlay()
    playTo(300)
    discPause()

    message = "The end."
    waitSeconds(4)
end


dofile("Singe/Framework.singe")

Lancez-le de la même façon, en terminant par movie/steps.singe. Il fait les quatre mêmes choses.

Maintenant, lisez singeMain. Les quatre étapes sont les quatre paragraphes, dans l’ordre, de haut en bas, et il n’y a de variable step nulle part, parce que la position dans l’histoire est la position dans la fonction. C’est tout l’intérêt de cette leçon.

Ce qui vient de se passer

function singeMain()

singeMain est un nom que Singe cherche, comme onOverlayUpdate. Si votre script définit cette fonction, le framework fait tourner votre jeu à partir d’elle : elle est appelée une fois, au début, et votre jeu dure aussi longtemps qu’elle. Quand elle se termine, le jeu s’arrête.

        singeYield()

Voici l’appel qui rend tout cela possible, et il veut dire « laisse passer une image ».

Singe ne fait pas deux choses à la fois — rien ici ne tourne en parallèle, quoi que suggère l’expression à fil d’exécution (« threaded »). Ce qui se passe, c’est que singeYield arrête votre fonction là où elle en est, rend la main au moteur, et se souvient de l’endroit exact. Le moteur dessine l’image, lit les entrées, fait avancer la vidéo, puis relance votre fonction à partir de la ligne qui suit le singeYield, avec chaque variable exactement comme vous l’avez laissée.

Une boucle while qui contient un singeYield est donc une façon d’attendre. C’est la seule façon d’attendre, et vous devez en mettre un dans chaque boucle qui attend quelque chose. C’est un marché que vous passez avec le moteur : vous pouvez rester là à attendre, du moment que vous lui cédez l’image soixante fois par seconde.

local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end

Singe n’a pas de fonction « attendre que la vidéo atteigne l’image 120 ». Il n’en a pas besoin, parce que vous pouvez l’écrire en quatre lignes, et c’est ce que vous venez de faire. Continuez tant que le disque n’est pas arrivé à l’image voulue ; cédez une image à chaque tour.

waitForButton a la même forme avec une autre question, et waitSeconds a encore la même forme, avec une horloge. Trois petites fonctions, écrites une fois, et grâce à elles singeMain se lit comme les phrases en français du début de la leçon. C’est exactement ce à quoi servent vos propres fonctions, comme le disait la leçon cinq.

        drawFrame()
        singeYield()

Chaque boucle d’attente dessine avant de céder, et c’est ce qui surprend les gens. Dans le modèle à fil d’exécution, vous n’avez pas de onOverlayUpdate à vous, donc rien n’est dessiné si vous ne le dessinez pas. Ce que vous dessinez avant un singeYield est ce qui apparaît sur cette image. Arrêtez de dessiner et l’overlay arrête de changer.

C’est pour cela que message existe. singeMain le remplit, drawFrame l’affiche, et les trois boucles d’attente appellent toutes drawFrame. C’est un petit prix à payer pour remettre l’histoire dans l’ordre.

dofile("Singe/Framework.singe")

En bas. Ceci compte plus que tout le reste de la leçon, alors ça vaut la peine de savoir pourquoi.

dofile exécute un autre script à l’intérieur du vôtre, et l’une des choses que fait le framework pendant qu’il s’exécute, c’est chercher une fonction appelée singeMain. S’il en trouve une, il bâtit votre jeu autour d’elle et écrit son propre onOverlayUpdate, dont le seul travail est de relancer votre singeMain une fois par image. S’il n’en trouve pas, il ne fait rien de tel, et votre jeu est un jeu ordinaire piloté par les événements.

Le framework doit donc être chargé après que singeMain existe. Chargez-le en haut, comme vous le faites depuis la septième leçon, et au moment où il regarde, il n’y a pas encore de singeMain, et vous obtenez un jeu sans jeu dedans.

Les règles

Il y en a quatre, et à elles toutes elles couvrent toutes les erreurs que vous pouvez faire ici.

Le framework vient en dernier. Pour la raison ci-dessus.

N’écrivez pas votre propre onOverlayUpdate. Le framework en a écrit un, et il ne peut y en avoir qu’un : celui des deux qui est écrit en dernier gagne, et l’autre est jeté sans un mot. Au-dessus du dofile, c’est le vôtre qui saute et votre dessin n’apparaît jamais. En dessous, c’est celui du framework qui saute et votre singeMain ne tourne plus jamais. Dessinez plutôt depuis l’intérieur de singeMain.

Chaque boucle qui attend a besoin d’un singeYield. Une boucle sans lui ne cède jamais l’image. La fenêtre arrête de se redessiner, arrête de répondre, et le jeu est perdu ; vous fermez le terminal pour en sortir. Il n’y a pas de message d’erreur, parce que du point de vue du moteur, votre fonction n’a pas encore fini.

Quand singeMain se termine, le jeu s’arrête. Ce qui est propre quand vous le voulez, et une surprise quand vous ne le voulez pas. Un jeu qui doit continuer pour toujours se termine par une boucle dont il ne sort jamais :

    while true do
        drawFrame()
        singeYield()
    end

Les entrées arrivent toujours

Regardez de nouveau l’endroit où pressed reçoit sa valeur :

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end

C’est un callback, dans un script écrit comme une liste d’étapes. Les deux modèles tournent en même temps, et c’est voulu.

Quand singeMain existe, seul onOverlayUpdate vous est retiré. Tout le reste — onInputPressed, onInputReleased, onKeyPressed, onSoundCompleted, onShutdown, tous — se déclenche exactement comme avant, dans les intervalles où vous avez cédé la main. La façon habituelle d’écrire un jeu dans ce modèle est donc celle que vous venez d’employer : l’histoire dans singeMain, et un petit callback qui attrape un événement et laisse un mot que l’histoire trouvera.

waitForButton met pressed à false avant de commencer à attendre, ce qui jette tout ce que le joueur a martelé avant. Oubliez cette ligne et un bouton enfoncé pendant la vidéo compte comme la réponse à une question qui n’a pas encore été posée.

Laquelle utiliser

Aucun des deux modèles n’est le meilleur. Ils conviennent à des tâches différentes, et un vrai jeu prend celui qui va.

Le modèle à fil d’exécution convient à tout ce qui est une séquence. Lire ceci, puis demander, puis lire cela. Une introduction. Une cinématique. Un tutoriel. Un combat de boss en trois phases. Tout ce que vous décririez naturellement comme une liste numérotée est un singeMain qui attend d’être écrit, et la vidéo est la chose la plus séquentielle qui soit, c’est pourquoi la troisième partie y arrive ici.

Le modèle piloté par les événements convient à tout ce qui est une situation. Dix ennemis et un joueur, qui bougent tous, se heurtent tous, sans aucun ordre. Le jeu que vous avez écrit à la leçon sept ne contient aucune séquence : chaque image est la même question posée à nouveau, ce qui est exactement la forme de onOverlayUpdate. Écrivez-le comme une liste d’étapes et vous ne gagnez rien et perdez la clarté.

Quand un jeu est les deux — et c’est le cas de la plupart — il s’écrit des deux façons. singeMain parcourt les niveaux dans l’ordre, et dans chaque niveau, une boucle fait le travail de la leçon sept soixante fois par seconde jusqu’à la fin du niveau.

Essayez

  1. Ajoutez une étape. Après waitForButton, faites plutôt sauter le film en arrière : discSkipToFrame(0), puis playTo(60), puis continuez comme avant. Deux nouvelles lignes à un seul endroit, et rien d’autre dans le script n’a besoin de le savoir.

  2. Ajoutez la même étape à l’autre. Faites-le maintenant dans events.singe. Comptez combien d’endroits vous avez dû toucher.

  3. Écrivez waitFrames. Une quatrième fonction utilitaire, à côté des trois autres, qui attend un nombre donné d’images de vidéo plutôt qu’un nombre donné de secondes. Utilisez discGetFrame et retenez d’où vous êtes parti.

  4. Ne cédez plus la main. Supprimez le singeYield() à l’intérieur de playTo et lancez. Soyez prêt à fermer le terminal, parce que rien d’autre ne l’arrête. Puis remettez-le et supprimez plutôt drawFrame(), et déduisez de ce que vous voyez pourquoi le compteur d’images s’arrête mais pas le film.

  5. Faites-en une boucle. Mettez tout le contenu de singeMain dans while true do …​ end pour que la séquence recommence au lieu de quitter. Échap vous permet toujours de sortir, parce que ça n’a jamais été votre travail.

Cassez-le exprès

Déplacez la ligne dofile("Singe/Framework.singe") du bas de steps.singe vers le haut, et lancez.

Il n’y a pas d’erreur. Rien n’est affiché. La fenêtre s’ouvre, la première image du film reste là, et c’est tout ce qui se passera jamais.

C’est la pire sorte de bug, et c’est pour ça qu’il vaut la peine de le rencontrer exprès. Rien ne s’est mal passé, du point de vue du moteur : votre script s’est chargé, le framework s’est chargé, et aucun des deux n’a défini de onOverlayUpdate, donc le moteur n’a rien à appeler. Le disque est garé sur l’image un, en pause, exactement comme le moteur l’a laissé, parce que le discPlay qui l’aurait démarré est à l’intérieur d’un singeMain que personne ne lance jamais.

Quand un jeu à fil d’exécution ne fait rien du tout, regardez d’abord la dernière ligne du fichier. C’est presque toujours ça.

Ce que vous avez appris

  • Singe a deux façons d’écrire un script, et vous choisissez en définissant singeMain ou non.

  • Dans le modèle à fil d’exécution, votre jeu est une liste d’étapes et s’exécute de haut en bas.

  • singeYield() cède une image au moteur et reprend à la ligne suivante.

  • Attendre, c’est une boucle while avec un singeYield dedans. Vous écrivez la fonction d’attente dont vous avez besoin ; le moteur n’en fournit pas.

  • Rien n’est dessiné si vous ne le dessinez pas, avant de céder, à chaque image.

  • dofile("Singe/Framework.singe") va à la fin d’un script à fil d’exécution.

  • N’écrivez pas votre propre onOverlayUpdate quand singeMain existe.

  • Tous les autres callbacks se déclenchent toujours, donc événements et étapes se mélangent librement.

  • Quand singeMain se termine, le jeu s’arrête.

  • Les séquences veulent le modèle à fil d’exécution ; les situations veulent le modèle piloté par les événements.

La prochaine fois

Vous savez maintenant écrire « lire ceci, puis demander, puis lire cela » en trois lignes. Un jeu vidéo à embranchements n’est rien d’autre que cette phrase, quelques centaines de fois, avec les réponses qui décident quelle ligne vient ensuite. La leçon seize en construit un, et la partie intéressante se révèle ne pas être la vidéo du tout. C’est de garder la carte de ce qui mène où sous une forme que vous pouvez encore lire quand le jeu compte quarante scènes.

Leçon 16 : Les embranchements

La leçon terminée

Un jeu vidéo à embranchements est un film avec des bifurcations. Une scène se joue, le joueur choisit, et c’est une autre scène qui se joue ensuite. Faites ça vingt ou trente fois et vous avez un jeu auquel les gens rejoueront pendant des années pour essayer de trouver la fin qu’ils n’ont pas encore vue.

Dans cette leçon, vous allez en construire un. Il a quatre scènes, deux choix, un minuteur sur chaque choix, une mort, et trois vies. Le code qui le fait tourner fait une trentaine de lignes, et il en ferait toujours une trentaine si le jeu avait deux cents scènes — parce que le jeu lui-même ne sera pas du tout écrit en code.

Imaginez que c’est un dragon

La vidéo que tout le monde a, c’est Singe/menuBackground.mkv, les mêmes 420 images que vous pilotez depuis la leçon quatorze. C’est une boule de feu, un dragon en papier, le mot SINGE, puis une grille magenta qui défile au loin sous un soleil orange, pour toujours.

Ce n’est pas un drame. Il n’y a personne dedans qui soit en danger, et le coucher de soleil se moque bien de ce que vous décidez.

Jouez le jeu quand même. Le dragon est assez réel pour deux minutes, et tout ce que vous allez écrire marche exactement pareil quand les images sont celles d’un cascadeur qui tombe d’une falaise. Voici la carte, et les numéros d’image sont ceux que vous avez trouvés vous-même à la leçon quatorze :

Scène Images Ce qui se passe

arrive

0 à 119

Du feu, et le dragon se pose. Gauche ou droite ?

sunset

120 à 259

Il crache du feu. Se baisser à gauche ou courir à droite ?

pit

260 à 339

Vous êtes dévoré. Vous perdez une vie.

escape

340 à 410

La grille s’éloigne et vous vous en êtes sorti.

À gauche, c’est toujours le droit chemin, pour ainsi dire : à gauche depuis arrive, on va à sunset, à gauche depuis sunset, on arrive à escape. À droite, c’est le pit les deux fois, et pareil si vous mettez trop de temps.

La carte, ce sont des données, pas du code

Voici le jeu tout entier, et c’est une table.

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

Une table avec des noms sur la gauche au lieu de numéros, exactement comme à la leçon six, et chaque valeur dedans est une autre table. Chacune de ces tables intérieures est un enregistrement : une scène, décrite champ par champ.

scenes.arrive est la première scène. scenes.arrive.first vaut 0. scenes.arrive.left est la chaîne "sunset", qui est le nom d’une autre scène de la même table — et c’est ainsi que les bifurcations sont notées. Une scène ne contient pas la scène qui la suit. Elle contient le nom de la scène qui la suit, et ce nom est cherché le moment venu.

Les champs veulent dire ceci :

first et last

Les images entre lesquelles la scène se déroule.

ask

L’image sur laquelle la question apparaît. Le joueur a de ask à last pour répondre, et c’est ça, le minuteur.

prompt

Ce que dit la question.

left et right

La scène à laquelle mène chaque réponse.

goesTo

Où va la scène quand personne n’a choisi — parce que le joueur n’a plus eu de temps, ou parce qu’il n’y avait pas de question au départ. Pour pit, qui est une mort, c’est là que repart la nouvelle tentative.

death

Présent, et à true, seulement dans une scène qui coûte une vie.

Trois choses méritent d’être remarquées à propos de cette table.

La première, c’est que c’est le document de conception. Vous pouvez la donner à quelqu’un qui n’a jamais écrit une ligne de Lua, et il saura y lire le jeu. Quand vous voulez que le dragon offre trois chemins, vous ajoutez un champ. Quand vous voulez une autre scène, vous ajoutez un autre enregistrement. Vous n’allez pas chercher le code qui joue les scènes, parce que vous n’y touchez pas.

La deuxième, c’est que les enregistrements n’ont pas tous la même forme. pit n’a ni ask, ni prompt, ni left — il n’y a rien à y choisir. escape n’a pas de goesTo, parce que c’est la fin et qu’elle ne mène nulle part. Un champ qui n’est pas dans une table se lit comme nil, le mot que vous avez rencontré à la leçon trois pour « il n’y a rien », et demander scenes.escape.goesTo n’est pas une erreur. C’est nil, et nil est une réponse. Le code qui lit ces enregistrements doit s’y attendre, et dans une minute vous verrez la seule ligne qui s’y attend.

La troisième, c’est ce que la table ne contient pas : rien dedans ne dessine, ne joue, ni n’attend. C’est une description. Cette séparation, c’est tout le secret de cette leçon.

Une fonction qui joue n’importe quelle scène

Voici la moitié code, et il n’y a qu’une seule fonction d’une taille notable. Elle est écrite dans le modèle à fil d’exécution de la leçon quinze, parce qu’un jeu à embranchements est la chose la plus séquentielle qui soit.

local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end

Elle prend le nom d’une scène, la joue, et renvoie le nom de la scène qui vient ensuite. C’est tout son contrat, et le jeu tient alors en trois lignes :

function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end

Commencez à arrive. Jouez la scène que vous tenez, quelle qu’elle soit, et gardez ce qu’elle vous rend. Quand elle rend nil, il n’y a pas de scène suivante, la boucle s’arrête, et la partie est finie.

Le tout

Créez dragon.singe dans votre dossier movie et tapez ceci. C’est le plus long script du livre jusqu’ici, et chacun de ses morceaux a été expliqué, sauf les deux petites fonctions utilitaires, qui viennent après.

local FPS = 30

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

local answer = nil
local ending = "You got out alive."
local lives  = 3


local function drawScene(scene, frame, asking)
    overlayClear()
    overlayPrint(2, 2, "Lives: " .. lives)
    if scene.death then
        overlayPrint(2, 4, "That did not go well.")
    elseif asking then
        overlayPrint(2, 4, scene.prompt)
        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")
    end
end


local function waitForGo(text)
    answer = nil
    while answer ~= "go" do
        overlayClear()
        overlayPrint(2, 2, "Lives: " .. lives)
        overlayPrint(2, 4, text)
        singeYield()
    end
end


local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        answer = "left"
    elseif what == SWITCH_RIGHT then
        answer = "right"
    elseif what == SWITCH_BUTTON1 then
        answer = "go"
    end
end


function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end


dofile("Singe/Framework.singe")

Lancez-le :

Singe -R -v Singe/menuBackground.mkv movie/dragon.singe

Jouez quatre ou cinq fois. Allez deux fois à gauche et sortez-vous-en. Allez à droite et faites-vous dévorer. Restez les bras croisés et faites-vous dévorer quand même. Perdez vos trois vies.

Ce qui vient de se passer

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do

Une scène, c’est un saut suivi d’une attente, c’est-à-dire le schéma de la leçon quinze, avec les nombres qui sortent de l’enregistrement au lieu d’être tapés. discSkipToFrame va à une image et lit à partir de là, et c’est exactement ce qu’est un changement de scène.

Le numéro d’image est juste dès l’instant où l’appel se termine, donc le while ne croit jamais qu’il est encore dans la scène que vous venez de quitter.

        local asking = scene.ask ~= nil and frame >= scene.ask

La seule ligne qui est prête pour un champ manquant, et la raison pour laquelle la scène de mort peut se passer de ask.

and veut dire que les deux moitiés doivent être vraies, comme à la leçon trois, et Lua vérifie d’abord la moitié gauche. Si scene.ask vaut nil, la moitié gauche est fausse, Lua s’arrête là, et la comparaison de droite n’a jamais lieu. Et c’est tant mieux, parce que comparer nil à un nombre est une erreur, et vous la rencontrerez à la fin de cette leçon.

asking est la réponse à « la question est-elle à l’écran en ce moment ? », calculée une fois par image et utilisée trois fois.

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end

Tant que la question n’est pas affichée, tout ce sur quoi le joueur appuie est jeté. Il le faut, sinon un joueur qui reste appuyé sur la flèche gauche pendant le film répond à une question qu’il n’a pas lue.

Une fois la question affichée, une réponse termine aussitôt la scène. return scene[answer] mérite qu’on s’y arrête : answer contient la chaîne "left" ou "right", et scene["left"] est la même chose que scene.left. Mettre le nom entre crochets au lieu de l’écrire après un point vous permet de chercher un champ dont le nom se trouve dans une variable. Deux lignes de code pour les deux réponses, et pour cinq réponses, ce serait toujours deux lignes.

Le elseif explique aussi pourquoi seuls "left" et "right" passent. La barre d’espace met answer à "go", et scene["go"] vaut nil, donc un appui égaré sur la barre d’espace pendant une question terminerait la partie en silence. Dites ce que vous acceptez.

    discPause()

Juste après la boucle, et facile à oublier. La scène a atteint sa dernière image mais le disque n’a aucune idée que la scène est finie — il continue tout droit dans les images qui se trouvent venir ensuite dans le fichier, ce qui, dans un vrai jeu, est le milieu d’une scène venue de tout à fait ailleurs. Arrêtez-le dès que vous n’en voulez plus.

    if scene.death then
        lives = lives - 1

scene.death vaut nil pour toutes les scènes sauf pit, et nil compte comme faux dans un if, donc ceci se lit « si cette scène était une mort ». Vous n’avez pas à écrire death = false dans les trois autres enregistrements, et vous ne devriez pas le faire : l’absence du champ le dit tout aussi bien, et il n’y a alors qu’un seul endroit qui décide quelles scènes sont mortelles.

La nouvelle tentative, ce sont les deux lignes en dessous. Retirez une vie, et s’il en reste, restez sur l’image et attendez la barre d’espace. Ensuite, return scene.goesTo renvoie le joueur à arrive, et c’est l’enregistrement qui le sait. Changez goesTo en "sunset" et la nouvelle tentative devient un point de contrôle au lieu d’un recommencement — un mot, et la difficulté du jeu change.

        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")

Le minuteur. scene.last - frame est le nombre d’images qui restent, et diviser par le nombre d’images dans une seconde le transforme en secondes. math.ceil arrondit un nombre à l’entier supérieur, donc le compte à rebours affiche 3, 2, 1 et jamais 0.4 ni 2.966666.

FPS vaut 30 parce que cette vidéo tourne à un peu plus de trente images par seconde. C’est le seul nombre du script qui soit une estimation, et c’est une estimation nommée, en haut du fichier, plutôt qu’un 30 enfoui au milieu d’une ligne, pour que, quand vous changez de vidéo, il y ait exactement une chose à changer.

Remarquez par rapport à quoi le minuteur est mesuré : le film. Le joueur fait la course contre la vidéo, pas contre une horloge, donc la question ne peut jamais durer plus longtemps que le plan auquel elle appartient. C’est pour ça que les jeux à embranchements comptent en images.

Pourquoi ne pas tout écrire à la main

Vous pourriez écrire ce jeu comme une seule longue fonction. Lire les images 0 à 119 ; si gauche, lire 120 à 259 ; si encore gauche, lire 340 à 410 ; sinon lire 260 à 339, retirer une vie, revenir au début. Pour quatre scènes, ce serait plus court que ce que vous avez.

Pour quarante scènes, ce serait une catastrophe, et ça vaut la peine de dire précisément pourquoi.

Les numéros d’image seraient éparpillés dans le code, chacun écrit une fois et jamais nommé, donc changer l’endroit où commence une scène voudrait dire retrouver chaque endroit où elle est mentionnée. La forme de l’histoire serait enfouie dans la forme des instructions if, donc personne ne pourrait voir le jeu sans tout lire. Et ajouter une scène voudrait dire modifier le code qui joue, c’est-à-dire le code qui marche déjà — chaque nouvelle scène, une occasion de plus d’en casser une ancienne.

La version que vous avez écrite a un morceau de code qui joue les scènes et un morceau de données qui dit ce que sont les scènes. Ajouter une scène ne touche que les données. Ça vaut bien la demi-heure de plus que ça vous a coûté, et c’est la même idée que celle qu’il y a sous le fichier games.dat de la leçon treize : décrivez la chose, puis écrivez un seul morceau de code qui lit la description.

Essayez

  1. Ajoutez une fin. Donnez à escape une question et une deuxième scène de fin qui réutilise des images prises quelque part dans le film. Seule la table change.

  2. Rendez-le équitable. Baissez ask dans les deux scènes pour que le joueur ait cinq secondes au lieu de trois, puis montez-le pour qu’il n’en ait qu’une. Trouvez le nombre que vous publieriez vraiment.

  3. Déplacez le point de contrôle. Changez le goesTo de pit en "sunset" et jouez. Puis réfléchissez à ce qui se passe si un joueur meurt dans arrive — et demandez-vous si la scène de mort devrait savoir d’où elle vient plutôt que de se le faire dire.

  4. Comptez ce que le joueur a vu. Ajoutez à côté de scenes une table qui note quels noms de scène ont été joués, et affichez leur nombre dans le coin. Vous avez maintenant un jeu qui peut dire « vous avez trouvé trois des cinq fins ».

  5. Cassez la carte. Changez le left de arrive en "cave", une scène qui n’existe pas. Lancez, allez à gauche, et lisez ce que dit Lua. Cette erreur est la plus courante dans un jeu piloté par les données, et connaître sa forme fait gagner une heure.

Cassez-le exprès

Retirez le garde-fou de la ligne asking, pour qu’elle devienne :

        local asking = frame >= scene.ask

Lancez et allez à droite. La scène arrive se joue très bien, parce que arrive a un ask. Puis la scène pit commence, qui n’en a pas, et le jeu s’arrête avec ceci :

Error executing function 'onOverlayUpdate':  movie/dragon.singe:68: attempt to compare nil with number
stack traceback:
	[C]: in function 'error'
	Singe/Framework.singe:603: in function 'onOverlayUpdate'

Lisez-le comme la leçon un vous l’a appris. Le fichier et la ligne viennent en premier, et ils sont parfaitement justes : la ligne 68 est celle que vous venez de modifier. La plainte, c’est le reste : vous avez demandé à Lua si un nombre était plus grand que nil, et Lua n’en a aucune idée. scene.ask vaut nil parce que l’enregistrement pit n’a pas de champ ask, et un champ qui n’est pas là vaut nil.

Une partie de ce message mérite une explication, parce que c’est un mensonge par omission. La fonction nommée est onOverlayUpdate, que vous n’avez pas écrite. C’est celle du framework, celle dont la leçon quinze disait qu’elle était installée pour faire tourner votre singeMain. L’erreur est passée par elle, donc c’est le nom que le moteur avait sous la main, et le traceback en dessous — la liste des fonctions qui étaient en train de s’exécuter, la plus intérieure en premier — ne peut montrer que le framework qui fait suivre votre erreur. Ignorez les deux. Le fichier et la ligne du haut sont à vous, et ce sont eux qui disent vrai.

Ce que vous avez appris

  • Un jeu à embranchements est un ensemble de scènes, dont chacune nomme les scènes qui viennent après elle.

  • Gardez les scènes sous forme de données — une table d’enregistrements — et le code qui les joue reste une seule fonction, quelle que soit la taille du jeu.

  • Un enregistrement contient le nom de la scène suivante, pas la scène, et ce nom est cherché quand on en a besoin.

  • Un champ qui n’est pas dans un enregistrement vaut nil, ce qui n’est pas une erreur, et le code qui lit des enregistrements doit s’y attendre.

  • scene[answer] cherche le champ dont le nom est dans une variable ; scene.left et scene["left"] sont le même champ.

  • Réglez le minuteur sur la vidéo : un choix dure d’une image à une autre, donc il ne peut jamais durer plus longtemps que son propre plan.

  • Jetez tout ce sur quoi le joueur a appuyé avant que la question apparaisse.

  • Mettez le disque en pause dès qu’une scène se termine, sinon il continue dans les images de la scène suivante.

  • Un champ absent qui tient lieu de faux — death dans trois enregistrements sur quatre — garde la description courte et honnête.

  • Comparer nil avec un nombre est une erreur, et and est la façon de l’éviter.

La prochaine fois

Votre jeu demande gauche ou droite. Les machines d’arcade où ce genre de jeu a grandi demandaient quelque chose de plus difficile : visez la chose à l’écran et tirez-lui dessus. La leçon dix-sept parle des pistolets optiques — l’endroit où le joueur vise, ce que le jeu en fait, et le calibrage dont une vraie borne ne peut pas se passer.

Leçon 17 : Les pistolets optiques

La leçon terminée

Vous allez faire un stand de tir. Des cibles apparaissent par-dessus la vidéo aux images que vous choisissez, vous visez l’écran et vous appuyez sur une gâchette, et celles que vous touchez rapportent des points.

Vous n’avez pas besoin d’un pistolet optique pour écrire ceci. Il vous faut une souris, parce que pour Singe, un pistolet optique est une souris : il signale une position dans les mêmes coordonnées, par les mêmes appels, et sa gâchette arrive comme le même contact qu’un bouton de souris. Écrivez le jeu pour la souris qui est sur votre bureau et il marche sur une borne où un pistolet est boulonné, et c’est la seule façon raisonnable de s’y prendre. Un pistolet n’est pas une autre sorte d’entrée. C’est une souris que quelqu’un a pointée.

Ce que vous visez

Commencez comme à la leçon quatorze, avec la vidéo que le moteur a déballée pour vous :

Singe -R -v Singe/menuBackground.mkv gallery

Ces images, c’est une grille violette et un coucher de soleil. Ce n’est pas un braquage de banque. Chaque numéro d’image de cette leçon s’y rapporte, pour que le code tourne le jour même où vous le tapez, et le clip entier fait 720 sur 480 et environ 420 images, ce qui, à une trentaine d’images par seconde, fait quatorze secondes. Imaginez de meilleures images. Le code se moque de ce qu’il y a dans l’image.

Accordez l’overlay à la vidéo

Mettez ceci en haut de gallery.singe, sous la ligne dofile :

overlaySetResolution(discGetWidth(), discGetHeight())

Sans cet appel, l’overlay fait la moitié de la vidéo dans chaque direction — 360 sur 240 ici — et chaque coordonnée avec laquelle vous dessinez, et chaque position de souris qu’on vous donne, est dans cet espace plus petit. Le petit overlay n’a rien de mal, mais c’est une conversion de plus à garder en tête pendant que vous cherchez où un tir est tombé. Accorder l’overlay à la vidéo veut dire qu’une cible à x = 80 est à quatre-vingts pixels du bord gauche de l’image, et un tir à x = 80 aussi. L’entrée de la Référence consacrée à overlaySetResolution explique ce que ça coûte.

Où vise le pistolet

Un seul appel y répond :

local x, y = mouseGetPosition(0)

mouseGetPosition renvoie deux nombres, ce que vous n’avez encore jamais vu une fonction faire et qui ne pose aucun problème à Lua : une fonction peut renvoyer autant de valeurs qu’elle veut, et vous les attrapez en écrivant autant de noms à gauche du =. Le 0 indique quel appareil de pointage vous interrogez, en comptant à partir de zéro. Avec une seule souris, ou un seul pistolet, la réponse est toujours l’appareil 0.

Les nombres sont en coordonnées de l’overlay, pas en pixels du bureau, et c’est pourquoi l’appel ci-dessus valait la peine. La position est la dernière que l’appareil a signalée, donc vous pouvez la demander quand vous voulez, aussi souvent que vous voulez. Demandez-la dans onOverlayUpdate et dessinez avec la réponse.

Il y a une autre façon d’obtenir les mêmes nombres. onMouseMoved est un callback, comme onOverlayUpdate, et le moteur l’appelle chaque fois qu’un pointeur bouge, en lui donnant la nouvelle position. C’est le bon choix quand vous voulez réagir au mouvement. Pour dessiner un réticule, ce n’est pas le cas : vous voulez savoir où se trouve la chose en ce moment, et mouseGetPosition vous le dit sans que vous ayez à en garder une copie.

Dessiner un réticule

Le moteur n’en dessinera pas pour vous. Un réticule, c’est quatre traits et un cercle :

local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end

Les vides comptent plus que les traits. Arrêter les quatre branches avant le cercle vous laisse un trou au milieu pour voir la cible à travers, ce qui est tout l’intérêt d’un réticule et la première chose que les débutants recouvrent.

Il y a une chose à demander avant de le dessiner :

local drawAim = singeWantsCrosshairs()

Cet appel renvoie false quand le joueur a lancé Singe avec --nocrosshair. Certains pistolets optiques affichent leur propre point à l’écran, et deux réticules à quelques pixels l’un de l’autre, c’est pire qu’aucun. La réponse ne peut pas changer pendant que le jeu tourne, alors lisez-la une fois en haut et gardez-la dans une variable.

Vous n’avez pas à cacher le pointeur du système, parce que Singe l’a déjà fait. Il capture la souris au démarrage, ce qui la confine à la fenêtre et cache la flèche du bureau. Si vous voulez un jour la récupérer — pour un éditeur de niveaux, par exemple — mouseSetCaptured(false) la libère, et la touche affectée à INPUT_GRAB, qui est G dans les commandes fournies, bascule la même chose pendant que vous jouez.

La gâchette

Une gâchette est un bouton, et les boutons arrivent dans onInputPressed, que vous avez rencontré pour la première fois à la leçon trois :

function onInputPressed(what, device)
    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    -- ...
end

SWITCH_BUTTON3 est le bouton gauche de la souris, et sur un pistolet, c’est la gâchette. Le controls.cfg fourni affecte le bouton gauche à SWITCH_BUTTON3, le droit à SWITCH_BUTTON1, et celui du milieu à SWITCH_BUTTON2. Ces numéros ont l’air mélangés parce qu’ils le sont : les contacts sont les boutons du panneau d’arcade, et savoir quelle commande physique est câblée à quel contact, c’est l’affaire de la borne, pas du jeu. Maj gauche est aussi affectée à SWITCH_BUTTON3, pour que vous puissiez tirer sans souris pendant vos tests.

Le second argument est la partie nouvelle. Quand le contact vient d’une souris ou d’un pistolet optique, device est l’indice de cet appareil — 0 pour le premier, 1 pour le second, et ainsi de suite. Quand il vient d’une touche ou d’une manette, il vaut nil, parce qu’aucun appareil de pointage n’était en jeu. C’est pourquoi l’appel ci-dessus dit device or 0 : si device vaut nil, utilisez 0 à la place. Vous utiliserez or comme ça sans arrêt, et ça se lit exactement comme ça sonne en anglais — « device, ou rien, auquel cas zéro ».

C’est ce seul argument de plus qui rend possible une borne à deux pistolets. Le pistolet du joueur un est l’appareil 0 et celui du joueur deux est l’appareil 1, et le même onInputPressed les distingue sans que vous ayez à deviner.

Est-ce que ça a touché quelque chose

Vous savez déjà répondre à ça. C’est la leçon onze :

if collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then

Un tir est un point. Une cible est un rectangle. collidePointRect demande si le point est à l’intérieur du rectangle, et le bord compte comme l’intérieur. Tirer n’a rien de spécial. Le test d’impact d’un jeu de tir est le même que celui qu’utilise un jeu de plateforme pour savoir si vous avez atterri sur un bloc, et la famille collide de la Référence a le reste des formes.

Des cibles qui vont et viennent

La seule chose que la vidéo change, c’est quand une cible existe. À la leçon onze, un rocher restait là jusqu’à ce que vous tiriez dessus. Ici, une cible est à l’écran pendant que le film montre la partie de la scène à laquelle elle appartient, et ensuite elle disparaît, que vous l’ayez touchée ou non.

Ce sont deux champs de plus dans l’enregistrement, et la leçon six vous a fabriqué l’outil :

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

Quatre enregistrements, chacun avec l’image où la cible apparaît, l’image où elle s’en va, et l’endroit où elle se trouve. Ajouter une cinquième cible, c’est ajouter une ligne. C’est la forme à adopter chaque fois que vous vous surprenez sur le point d’écrire les quatre mêmes lignes de code avec des nombres différents dedans.

Savoir si une cible compte est alors une petite fonction à part entière :

local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end

Le dessin lui pose la question, et le tir aussi, et c’est tout l’intérêt de la mettre à un seul endroit : une cible que vous voyez et une cible que vous pouvez toucher ne peuvent jamais être en désaccord.

Le tout

-- Apprendre à programmer avec Singe -- Leçon 17 : Les pistolets optiques

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local LAST_FRAME  = 400
local TARGET_SIZE = 96
local HIT_SCORE   = 100
local FLASH_TIME  = 12

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

local aimX    = overlayGetWidth() / 2
local aimY    = overlayGetHeight() / 2
local score   = 0
local shots   = 0
local hits    = 0
local flash   = 0
local flashX  = 0
local flashY  = 0
local drawAim = singeWantsCrosshairs()


local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end


local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end


local function startRound()
    score = 0
    shots = 0
    hits  = 0
    flash = 0
    for _, target in ipairs(targets) do
        target.hit = false
    end
    discSkipToFrame(FIRST_FRAME)
end


function onInputPressed(what, device)
    if what == SWITCH_START1 then
        startRound()
        return
    end

    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    local frame = discGetFrame()

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then
            target.hit = true
            hits       = hits + 1
            score      = score + HIT_SCORE
            flash      = FLASH_TIME
            flashX     = x
            flashY     = y
            return
        end
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if frame >= LAST_FRAME then
        startRound()
        frame = FIRST_FRAME
    end

    aimX, aimY = mouseGetPosition(0)

    overlayClear()

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) then
            colorForeground(255, 200, 0, 255)
            overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)
            overlayCircle(target.x + TARGET_SIZE / 2, target.y + TARGET_SIZE / 2, TARGET_SIZE / 3)
        end
    end

    if flash > 0 then
        colorForeground(255, 255, 255, 255)
        overlayCircle(flashX, flashY, 30 - flash * 2)
        flash = flash - 1
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   HITS " .. hits .. "/" .. shots .. "   FRAME " .. frame)

    if drawAim then
        drawCrosshair(aimX, aimY)
    end

    return OVERLAY_UPDATED
end


startRound()

Visez une boîte jaune et cliquez. Le compteur dans le coin augmente, un anneau blanc s’ouvre là où vous avez touché, et la boîte disparaît. Ratez, et seul le compteur de tirs augmente, ce qui est l’afficheur de scores le moins cher qui soit et en dit plus à un joueur sur sa forme que le score. La manche recommence d’elle-même quand le film arrive au bout, et 1 la relance quand vous voulez.

Ce qui vient de se passer

local frame = discGetFrame()

if frame >= LAST_FRAME then
    startRound()
    frame = FIRST_FRAME
end

La vidéo est l’horloge, comme à la leçon quatorze, et discGetFrame est la façon de la lire. Tout le reste de l’image est décidé à partir de ce seul nombre. Quand le film dépasse la fin de la dernière cible, la manche recommence : startRound remet le score à zéro, marque chaque cible comme non touchée, et renvoie le disque au début avec discSkipToFrame. La ligne en dessous règle aussi la copie locale de frame, parce qu’elle a été lue avant le saut et contient encore l’ancien nombre. Sans elle, le dessin plus bas passerait une image à travailler avec un nombre qui n’est plus vrai.

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(...) then

Comptez le tir avant de chercher une touche, pour qu’un tir raté compte aussi. Puis parcourez la liste. Le return dans la boucle s’arrête à la première cible touchée, ce qui veut dire qu’une balle ne peut pas abattre deux cibles qui se chevauchent — une règle que vous devez trancher dans un sens ou dans l’autre, et c’est cette ligne qui la tranche.

overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)

overlayBox veut deux coins opposés, pas un coin et une taille, donc le coin éloigné est le coin proche plus la taille. Le - 1 est là parce que les deux coins sont inclus : une boîte de 80 à 175 fait quatre-vingt-seize pixels de large. collidePointRect veut au contraire un coin et une taille, c’est pourquoi TARGET_SIZE y entre tout seul et qu’ici il est ajouté au coin. Confondre les deux est un bug vraiment courant, et il se voit sous forme de cibles que vous pouvez toucher un peu en dehors de l’endroit où elles sont dessinées.

if flash > 0 then
    colorForeground(255, 255, 255, 255)
    overlayCircle(flashX, flashY, 30 - flash * 2)
    flash = flash - 1
end

flash est un compte à rebours en images, mis à douze quand un tir fait mouche et diminué de un chaque fois que l’écran est dessiné. Comme le rayon est calculé à partir du compte à rebours, l’anneau grandit à mesure que le nombre diminue. Douze images, c’est moins d’une demi-seconde. Un retour visuel qui dure plus longtemps que ça cesse de ressembler à une conséquence de la gâchette et commence à ressembler à la météo.

Deux pistolets

Vous n’êtes qu’à deux changements d’une borne à deux joueurs, et aucun des deux n’est dans la boucle du jeu.

Le premier est mouseSetMode(MOUSE_MANY), qui dit à Singe de lire chaque appareil séparément au lieu de les réunir en un seul curseur. mouseHowMany() dit combien il en a trouvé au démarrage, donc un jeu demande normalement avant de s’engager :

if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
end

Après ça, mouseGetPosition(1) est le second pistolet, et l’argument device de onInputPressed dit quel pistolet a tiré. Gardez deux réticules, deux scores, et une seule liste de cibles, et vous avez un jeu coopératif.

Le second changement n’est pas du tout dans votre script. Le controls.cfg fourni n’affecte que les boutons de la première souris, donc la gâchette du second pistolet n’atteint rien. Une borne à deux pistolets a besoin dans ce fichier de sa propre ligne, qui nomme les deux :

INPUT_ACTION_3 = { SCANCODE.LSHIFT, GAMEPAD_0.BUTTON_X, MOUSE_0.BUTTON_LEFT, MOUSE_1.BUTTON_LEFT }

Dites-le dans vos instructions. Un joueur dont le second pistolet ne fait rien accusera votre jeu, et il aura à moitié raison.

L’autre façon de tester un tir

Il y a une seconde façon de répondre à « ce tir a-t-il touché quelque chose ? », et elle vaut d’être connue même si vous n’allez pas vous en servir aujourd’hui. vldpGetPixel(x, y) lit la couleur d’un pixel de l’image vidéo actuellement à l’écran. Des jeux s’en servent depuis la toute première version de Singe : peignez chaque cible, dans les images, d’une couleur qui n’apparaît nulle part ailleurs, et à chaque pression sur la gâchette, demandez quelle couleur se trouve sous le réticule.

Ça vous offre des zones d’impact qui suivent exactement l’action, gratuitement, sans aucun rectangle à définir. Ça vous coûte des images qu’il faut préparer de cette façon, et un test d’impact que vous ne pouvez ni voir ni déboguer. L’entrée de la Référence consacrée à vldpGetPixel donne les détails. Les rectangles sont le bon choix par défaut ; gardez ceci sous le coude.

Ce qui ne compte que pour une borne

Tout ce qui précède marche sur votre bureau. Plusieurs choses n’existent pas du tout sur votre bureau, et c’est le bon moment pour les nommer, pour qu’elles ne soient pas une surprise plus tard.

Le calibrage. Il faut dire à un vrai pistolet optique où se trouve l’écran, parce que c’est une caméra qui regarde un moniteur depuis l’endroit où se tient le joueur. Les outils de service de Singe ont un écran Light Gun qui place des cibles au milieu et à chaque coin et marque l’endroit que le pistolet a vraiment visé, pour que vous voyiez dans quel sens il est décalé. Votre jeu ne fait pas le calibrage et ne devrait pas essayer.

La bordure Sinden. Une famille de pistolets répandue trouve l’écran en cherchant un cadre lumineux dessiné autour de l’image. --sindengun dessine ce cadre, et le moteur ramène les positions dans l’image plus petite qui se trouve à l’intérieur, pour que votre jeu continue de recevoir des coordonnées qui veulent dire ce qu’elles voulaient dire avant.

Les écrans qui n’ont pas la forme du film. ratioGetX() et ratioGetY() vous donnent les nombres qu’un joueur a passés en ligne de commande pour un écran dont les proportions ne correspondent pas aux images. Singe ne les applique pas ; un jeu qui en veut fait le calcul lui-même.

Les pistolets qui s’en vont. SWITCH_MOUSE_DISCONNECT arrive dans onInputPressed quand un pistolet est débranché. Aucun bouton ne le produit ; c’est le moteur qui le déclenche. Un jeu qui le guette peut afficher « PLAYER 2 GUN DISCONNECTED » à l’écran au lieu d’avoir l’air d’être mort.

Pas de souris du tout. Une borne avec un joystick et sans appareil de pointage peut piloter le curseur depuis le stick, ce que joyMouseEnable active.

Rien de tout ça ne change le jeu que vous avez écrit. Tout ça, c’est la leçon trente et un.

Essayez

  1. Déplacez une cible. Changez le x de la troisième cible en 680 et lancez. Elle déborde maintenant en bonne partie du bord droit, parce que l’overlay fait 720 de large et la cible 96. Vous pouvez toujours tirer sur le petit bout qui reste. Décidez de ce que vous voulez qu’il se passe sur les bords.

  2. Rendez les cibles plus faciles. Changez TARGET_SIZE en 140. Remarquez que le dessin et le test d’impact changent tous les deux, et que vous n’avez modifié qu’un seul nombre. C’est à ça que sert une constante nommée.

  3. Comptez la précision. Ajoutez une ligne qui affiche hits en pourcentage de shots. Protégez-vous contre une division par zéro avant le premier tir, et découvrez ce que Lua affiche si vous ne le faites pas.

  4. Faites qu’une cible vous punisse. Ajoutez un champ penalty = true à un enregistrement et retirez des points quand cette cible est touchée. Remarquez que vous ajoutez un champ à un seul enregistrement, pas aux quatre, et que ceux qui ne l’ont pas y ont nil.

  5. Retirez le return de la boucle dans onInputPressed, puis faites se chevaucher deux cibles en leur donnant les mêmes images et presque la même position. Un seul tir les abat maintenant toutes les deux. Décidez du comportement que veut votre jeu.

Cassez-le exprès

Changez le test de tir pour qu’il utilise SWITCH_BUTTON1 au lieu de SWITCH_BUTTON3 et lancez. Rien ne casse. Aucune erreur n’apparaît. Le bouton gauche ne fait plus rien, et c’est le bouton droit qui tire maintenant.

C’est la pire sorte de bug, et la plus courante dans le code des entrées : le programme n’est pas faux, il est juste branché sur la mauvaise chose. Il n’y a pas de message d’erreur à lire, parce que vous avez posé une question sensée sur un contact qui existe, et il a répondu honnêtement.

Deux choses permettent de le trouver. La première est debugPrint, de la leçon huit :

function onInputPressed(what, device)
    debugPrint("switch " .. what .. " from device " .. tostring(device))

Maintenant, chaque appui affiche une ligne, et vous pouvez voir ce que la gâchette envoie vraiment. Remarquez tostring(device) : device vaut nil pour un appui sur une touche, et coller nil à une chaîne avec .. est une erreur. tostring le transforme en mot nil et la ligne s’affiche.

La seconde est l’Input Test du moteur, dans les outils de service, qui montre chaque appareil qu’il voit et le dernier contact que le jeu aurait reçu. Quand un bouton ne fait rien, cet écran vous dit quelle moitié du problème vous avez : soit le contact arrive et votre jeu l’ignore, soit il n’arrive pas du tout.

Ce que vous avez appris

  • Un pistolet optique se présente comme une souris, donc un jeu écrit pour la souris marche avec un pistolet.

  • mouseGetPosition(device) renvoie deux valeurs, la position du pointeur en coordonnées de l’overlay.

  • Une fonction Lua peut renvoyer plus d’une valeur, et vous les attrapez en écrivant autant de noms.

  • singeWantsCrosshairs() dit s’il faut dessiner votre propre réticule. Lisez-le une fois.

  • Singe capture et cache le pointeur du système au démarrage ; vous n’avez pas à le faire.

  • onInputPressed reçoit un second argument qui indique quelle souris ou quel pistolet a tiré, et nil quand c’était une touche ou une manette.

  • Un test d’impact contre un rectangle, c’est collidePointRect, la même collision que celle que vous avez apprise à la leçon onze.

  • La fenêtre d’images d’une cible, ce ne sont que deux champs de plus dans son enregistrement.

  • a or b vous donne b quand a vaut nil.

  • Le calibrage, la bordure Sinden et le câblage à deux pistolets vivent en dehors de votre script.

La prochaine fois

Votre stand de tir demande une seule chose : touchez ça, là. L’autre convention d’arcade sur laquelle reposent les jeux en vidéo demande quelque chose de plus difficile — appuyez sur ceci, maintenant, et vous avez une demi-seconde. La leçon dix-huit construit un quick-time event, avec une invite, une fenêtre mesurée en images, et trois fins différentes selon que vous avez eu raison, que vous avez eu tort, ou que vous avez été trop lent.

Leçon 18 : Les quick-time events

La leçon terminée

Une invite apparaît. Vous avez une demi-seconde. Appuyez sur la bonne chose et l’histoire continue ; appuyez sur la mauvaise, ou sur rien du tout, et elle part ailleurs.

C’est toute l’idée, et un nombre surprenant de jeux en vidéo ne sont faits de presque rien d’autre. Vous avez déjà toutes les pièces : la leçon quatorze vous a donné les images, la leçon six une liste d’enregistrements, la leçon trois les entrées, et la leçon seize les embranchements. Cette leçon les assemble et ajoute une chose vraiment nouvelle — une fenêtre de temps, et ce qui se passe quand elle se ferme.

L’horloge, c’est le film

Tout ici se mesure en images, pas en secondes, et ça vaut la peine de s’y arrêter, parce que c’est la décision qui, à elle seule, fait que tout ça marche.

La leçon quatorze disait qu’une image est l’adresse d’un moment du film. L’invite doit apparaître quand l’acteur commence à frapper, et la fenêtre doit se fermer quand le poing arrive. Ce ne sont pas des instants, ce sont des endroits dans les images, et vous les avez trouvés en les parcourant pas à pas. Si vous écrivez la fenêtre en secondes, vous devez lancer un chronomètre quand l’invite apparaît, et alors les deux horloges — la vôtre et celle du film — peuvent se décaler. Si la vidéo saccade sur une machine lente, votre chronomètre continue de tourner et le joueur est puni pour son matériel.

Les images ne peuvent pas se décaler, parce qu’il n’y a qu’une seule horloge. discGetFrame() est l’heure, toujours. Une fenêtre, c’est deux numéros d’image, et « combien de temps reste-t-il », c’est une soustraction.

Lancez avec la même vidéo qu’avant :

Singe -R -v Singe/menuBackground.mkv moves

Toujours la grille violette et le coucher de soleil. Imaginez un combat.

Un mouvement est un enregistrement

Voici la table sur laquelle repose toute la leçon :

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

Quatre mouvements. Chacun dit quand la fenêtre s’ouvre, quand elle se ferme, quel contact y répond, et quoi mettre à l’écran. Quarante-cinq images, c’est environ une seconde et demie à la fréquence d’images de cette vidéo, ce qui est généreux ; les vrais jeux vous en donnent souvent moins de la moitié.

Tout ce qui fait qu’un mouvement est un mouvement se trouve dans cette table. Il n’y a de code nulle part plus bas qui sache qu’il y a quatre mouvements, ou que le deuxième est vers le haut, ou que la première fenêtre s’ouvre à l’image soixante. Ajouter un cinquième mouvement, c’est ajouter une ligne. Changer le rythme de tous les mouvements, c’est modifier des nombres. Personne n’a besoin de lire une fonction pour changer le combat.

Ce n’est pas une astuce propre à cette leçon. C’est la différence entre un jeu que vous pouvez régler et un jeu que vous ne pouvez pas régler, et ça ne coûte rien de le faire dès le début. Quand vous vous surprenez sur le point d’écrire if frame == 60 then pour la quatrième fois, arrêtez-vous et faites plutôt une table.

Ce qui se passe, et quand

Trois choses peuvent arriver à un mouvement, et ce sont trois issues différentes, pas deux :

  • Le joueur appuie sur le bon contact pendant la fenêtre. Comptez les points et continuez.

  • Le joueur appuie sur un mauvais contact pendant la fenêtre. Il a essayé et il a échoué.

  • La fenêtre se ferme sans aucune réponse. Il est resté figé.

Le code paresseux traite les deux derniers cas de la même façon. Les jeux ne le font presque jamais, parce qu’à jouer, ils font un effet complètement différent : se tromper est une erreur, rester figé en est une autre, et le film part généralement ailleurs pour chacune. Ici, la mauvaise réponse envoie le disque à l’image 362 et l’absence de réponse l’envoie à l’image 388, ce qui, avec ces images-là, veut dire deux quantités de coucher de soleil un peu différentes. Avec de vraies images, ce seraient deux plans différents de vous en train de perdre.

Chaque enregistrement gagne donc un cinquième champ pendant la partie — answer — qui vaut nil jusqu’à ce qu’il arrive quelque chose au mouvement, puis l’une de trois chaînes :

move.answer = "right"
move.answer = "wrong"
move.answer = "late"

nil est la valeur que Lua vous donne pour un champ que personne n’a rempli. Vous l’avez rencontré à la leçon trois. Ici, il mérite sa place : « pas encore de réponse » est vraiment un état différent de chacune des trois réponses, et nil le dit sans que vous ayez à inventer un mot pour ça.

Trouver le mouvement demandé

Tout le reste a besoin de savoir une chose : quel mouvement, s’il y en a un, est ouvert en ce moment ?

local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end

Parcourez la liste, et répondez avec le premier mouvement dont la fenêtre couvre cette image et qui n’a pas encore reçu de réponse. Si rien ne correspond, répondez nil.

Renvoyer nil exprès, ça mérite d’être remarqué. Une fonction qui parfois n’a pas de réponse devrait le dire, et « aucun mouvement n’est ouvert » est une très bonne réponse. Le code qui l’appelle écrit alors if move ~= nil then, et le code qui dessine l’invite ne s’exécute jamais quand il n’y a rien à demander.

Le test move.answer == nil est ce qui empêche qu’un mouvement soit demandé deux fois. Dès que le joueur a la bonne réponse, l’invite disparaît même si la fenêtre est encore ouverte — et c’est exactement ce qu’elle doit faire, puisqu’il a répondu.

Lire la réponse

function onInputPressed(what)
    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end

Lisez-le de haut en bas. Si le contact n’est pas l’une des quatre directions, ça ne nous regarde pas — on s’en va. Si aucun mouvement n’est ouvert, un appui sur une direction ne veut rien dire — on s’en va. Sinon, il y a exactement un mouvement auquel comparer, et une seule comparaison à faire.

Ces deux lignes return du début sont des garde-fous : elles écartent les cas qui ne vous intéressent pas, pour que le code en dessous ne s’exécute jamais que dans la seule situation pour laquelle il a été écrit. L’écrire dans l’autre sens, avec le vrai travail imbriqué sur trois niveaux à l’intérieur de trois blocs if, dit la même chose et se lit beaucoup plus difficilement.

isDirection est une toute petite fonction qui ne fait rien d’autre que garder cette première ligne courte :

local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end

Remarquez qu’elle renvoie la comparaison elle-même au lieu de dire if …​ then return true else return false end. Une comparaison vaut déjà true ou false. Tester si quelque chose est vrai pour pouvoir dire que c’est vrai, c’est une habitude qu’il vaut mieux perdre tôt.

La fenêtre qui se ferme

Personne n’appuie sur rien, et les images continuent de défiler. Quelque chose doit le remarquer. Ce quelque chose, c’est onOverlayUpdate, parce qu’il s’exécute à chaque image, que le joueur fasse quelque chose ou non :

if not runOver then
    for _, move in ipairs(moves) do
        if move.answer == nil and frame > move.last then
            move.answer = "late"
            endRun("TOO SLOW", LATE_FRAME)
            break
        end
    end
end

Un mouvement sans réponse dont la dernière image est passée a été manqué. break quitte la boucle immédiatement, parce qu’une fois la partie finie, ça ne sert à rien de regarder le reste.

endRun est l’embranchement, et c’est le même embranchement que celui que vous avez écrit à la leçon seize :

local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end

Trois lignes. Retenir quoi dire, retenir que la partie est finie, et envoyer le film ailleurs. Un quick-time event manqué n’est pas un mécanisme spécial. C’est un choix que le joueur a fait en n’en faisant pas, et le film bifurque dessus exactement comme il bifurque sur une porte qu’il a choisie.

Une jauge qui se vide

Le joueur ne peut pas voir les numéros d’image. Il a besoin de voir le temps s’écouler, et de le voir sans quitter l’action des yeux, ce qui veut dire une forme qui change plutôt qu’un nombre qui compte.

Deux nombres vous donnent tout :

local left = move.last - frame
local span = move.last - move.first

span est la longueur de la fenêtre. left est ce qu’il en reste. La barre fait left sur span de la largeur totale :

fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)

// est une division qui jette la partie fractionnaire, ce que vous voulez ici, parce qu’une barre de cent trente-trois pixels et un tiers de large, ça n’existe pas. Multipliez avant de diviser — GAUGE_W * left // span et non GAUGE_W * (left // span) — sinon la fraction est jetée alors qu’elle est encore la seule information que vous avez, et la barre saute de pleine à vide sans rien entre les deux.

Il n’y a pas de rectangle plein dans l’overlay. overlayBox dessine un contour, ce qui est ce que vous voulez pour le cadre autour de la jauge, et le remplissage est à votre charge :

local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end

Dix-huit traits horizontaux empilés les uns sur les autres. Le garde-fou du début compte : à la toute dernière image de la fenêtre, left vaut zéro, la largeur vaut zéro, et sans lui, x + width - 1 est un pixel à gauche de x et vous dessinez un petit trait à l’envers au lieu de rien.

La touche finale, c’est un changement de couleur quand ça devient désespéré :

if left * 3 < span then
    colorForeground(255, 60, 60, 255)
else
    colorForeground(255, 200, 0, 255)
end

La barre devient rouge dans son dernier tiers. Écrit comme ça — en multipliant le temps restant plutôt qu’en divisant la durée — tout reste en nombres entiers et ça marche pour une fenêtre de n’importe quelle longueur.

Le tout

-- Apprendre à programmer avec Singe -- Leçon 18 : Les quick-time events

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local WRONG_FRAME = 362
local LATE_FRAME  = 388
local LAST_FRAME  = 415

local PROMPT_COL  = 54
local PROMPT_ROW  = 22
local GAUGE_X     = 210
local GAUGE_Y     = 330
local GAUGE_W     = 300
local GAUGE_H     = 18

local RIGHT_SCORE = 100

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

local score   = 0
local runOver = false
local verdict = ""


local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end


local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end


local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end


local function startRun()
    score   = 0
    runOver = false
    verdict = ""
    for _, move in ipairs(moves) do
        move.answer = nil
    end
    discSkipToFrame(FIRST_FRAME)
end


local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end


function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if not runOver then
        for _, move in ipairs(moves) do
            if move.answer == nil and frame > move.last then
                move.answer = "late"
                endRun("TOO SLOW", LATE_FRAME)
                break
            end
        end
    end

    if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then
        if not runOver then
            verdict = "CLEAR"
            runOver = true
        end
        discSearch(LAST_FRAME)
    end

    overlayClear()

    local move = nil
    if not runOver then
        move = moveAt(frame)
    end

    if move ~= nil then
        local left = move.last - frame
        local span = move.last - move.first

        overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

        colorForeground(255, 255, 255, 255)
        overlayBox(GAUGE_X - 2, GAUGE_Y - 2, GAUGE_X + GAUGE_W + 1, GAUGE_Y + GAUGE_H + 1)

        if left * 3 < span then
            colorForeground(255, 60, 60, 255)
        else
            colorForeground(255, 200, 0, 255)
        end
        fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   FRAME " .. frame)

    if runOver then
        overlayPrint(2, 3, verdict)
        overlayPrint(2, 4, "PRESS 1 TO RUN IT AGAIN")
    end

    return OVERLAY_UPDATED
end


startRun()

Les touches fléchées répondent aux invites. Réussissez les quatre et le film va jusqu’au bout et s’y arrête sur CLEAR. Ratez-en une, ou restez les bras croisés, et il saute à une autre image avec un autre mot à l’écran. 1 relance le tout.

Ce qui vient de se passer

Vous en avez déjà lu presque tout. Quatre morceaux méritent qu’on y revienne.

if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then

La fin du film doit être attrapée, sinon il dépasse la fin et il n’y a plus rien à voir. discSearch va à une image et s’y met en pause, ce qui est exactement ce que veut un plan final. La moitié discGetState() empêche que ça se reproduise à chacune des images suivantes : une fois le disque en pause, il n’est plus DISC_PLAYING, donc la condition est fausse et le saut n’est pas répété soixante fois par seconde. discGetState et les constantes DISC_* sont dans la Référence, à l’entrée discGetState.

local move = nil
if not runOver then
    move = moveAt(frame)
end

onOverlayUpdate redemande le mouvement ouvert, au lieu que onInputPressed le lui dise. C’est voulu. Il y a exactement une fonction qui sait quel mouvement est ouvert, et tout le monde lui pose la question. Si l’invite venait d’une variable que le code des entrées tient à jour, alors deux morceaux de code retiendraient le même fait, et tôt ou tard l’un d’eux se tromperait. Quand vous avez le choix entre demander et retenir, demandez.

overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

overlayPrint compte en cellules de caractère, comme depuis la leçon un, donc l’invite est placée à l’œil : la colonne cinquante-quatre est à peu près au milieu pour des mots de cette longueur. C’est à peu près, pas juste, et « PRESS RIGHT » finit trois caractères plus à droite que « PRESS UP ». La leçon dix-neuf charge une vraie police, et avec elle la possibilité de mesurer une chaîne en pixels et de la centrer correctement.

function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

Un seul callback, deux tâches complètement différentes, choisies par runOver. Pendant la partie, les directions veulent dire des mouvements ; une fois qu’elle est finie, la seule touche qui veut dire quelque chose, c’est Start. Une variable qui décide quelles règles s’appliquent est un état, le nom que lui a donné la leçon douze, et un jeu n’est en grande partie qu’un petit nombre d’états.

Essayez

  1. Rendez-le plus difficile. Changez le last du premier mouvement de 105 en 75. Quinze images, c’est une demi-seconde. Jouez et voyez si vous y arrivez.

  2. Ajoutez un mouvement. Mettez une cinquième ligne dans la table avec une fenêtre entre les images 370 et 400, et montez LAST_FRAME à 418. Vous ne devriez avoir aucune autre ligne à toucher. Si vous devez le faire, quelque chose dans le code en sait trop sur la table.

  3. Notez la vitesse. Donnez plus de points pour une réponse rapide. Dans onInputPressed, là où la bonne réponse est comptée, calculez left et span à partir de move et de discGetFrame() de la même façon que la jauge, et ajoutez RIGHT_SCORE * left // span au lieu de RIGHT_SCORE. Décidez si ça rend le jeu meilleur ou seulement plus agité.

  4. Donnez à une mauvaise réponse sa propre conséquence. Au lieu de terminer la partie, faites qu’un mauvais appui coûte cinquante points et laissez la fenêtre ouverte pour réessayer. Vous devrez arrêter de remplir move.answer, et vous découvrirez pourquoi on le remplissait au départ.

  5. Deux invites à la fois. Faites se chevaucher les fenêtres de deux mouvements et voyez ce qui se passe. moveAt renvoie la première correspondance, donc un seul mouvement est demandé à la fois. Décidez de ce que vous voudriez, et de ce qu’il faudrait pour y arriver.

Cassez-le exprès

Supprimez le break de la boucle qui trouve les mouvements manqués, et manquez exprès le premier. La partie se termine, le disque saute, et tout a l’air correct.

Maintenant, mettez debugPrint(move.name .. " missed") à côté de move.answer = "late" et recommencez. La console affiche une ligne, comme vous vous y attendez.

Puis retirez aussi le if not runOver then autour de la boucle, et manquez de nouveau le premier mouvement :

LEFT missed
UP missed
RIGHT missed
DOWN missed

La première ligne arrive quand la fenêtre se ferme, comme avant. Les trois autres arrivent ensemble dès l’image suivante, à l’instant où le disque atterrit à 388 : chaque fenêtre restante est maintenant dans le passé, donc chaque mouvement sans réponse est manqué d’un coup, et chacun appelle endRun et refait un saut. Le jeu marche encore plus ou moins, et c’est ce qui le rend dangereux. Trois sauts de trop en une seule image, trois réécritures du verdict, et rien à l’écran ne le dit.

Il n’y a pas de message d’erreur ici non plus. La leçon, c’est que ce break et ce garde-fou ne sont pas de la coquetterie. Ce sont les deux lignes qui disent « c’est déjà décidé », et du code qui continue de décider quelque chose qu’il a déjà décidé est l’une des sources de bugs les plus fiables que vous écrirez jamais.

Ce que vous avez appris

  • Un quick-time event, c’est une invite, une fenêtre, et une conséquence.

  • Mesurez la fenêtre en images, parce que le film est l’horloge et qu’il ne doit jamais y avoir qu’une seule horloge.

  • Gardez les mouvements dans une table d’enregistrements, pour qu’ajouter un mouvement, ce soit ajouter une ligne.

  • Juste, faux et pas de réponse sont trois issues, et elles mènent généralement à trois endroits différents.

  • nil dans un champ d’enregistrement est un vrai état : personne n’a encore répondu.

  • Une seule fonction répond à « quel mouvement est ouvert », et tout le monde lui pose la question plutôt que d’en garder une copie.

  • Les garde-fous — un return précoce pour les cas qui ne vous intéressent pas — évitent d’imbriquer le vrai travail.

  • // divise et jette la partie fractionnaire ; multipliez avant de diviser.

  • overlayBox dessine un contour, donc une barre pleine est une pile d’appels à overlayLine.

  • Un mouvement manqué est un embranchement, et discSkipToFrame le prend, exactement comme à la leçon seize.

La prochaine fois

La troisième partie est terminée. Vous savez lire du film, l’attendre, bifurquer dessus, viser dedans, et chronométrer le joueur contre lui. Ce que vous avez écrit par-dessus tout ça, c’est la police de console du moteur, qui fait six pixels de large et qui est faite pour le diagnostic. La leçon dix-neuf charge une vraie police, la mesure, et donne aux mots à l’écran l’air de faire partie du jeu.

Leçon 19 : Du texte qui a de l’allure

La leçon terminée

Chaque mot que vous avez mis à l’écran depuis la leçon un est sorti de overlayPrint, et overlayPrint a exactement une police : un bloc de pixels à chasse fixe intégré au moteur, toujours de la même taille, dans la couleur qu’il se trouve avoir. C’est parfait pour un compteur d’images. C’est mauvais pour un titre, un score, un menu, ou tout ce qu’un joueur est censé regarder plutôt que survoler.

Cette leçon charge une vraie police depuis le disque, affiche du texte avec, le colore, le mesure pour que vous puissiez centrer les choses, et vous montre ce que coûte vraiment l’affichage de texte. À la fin, vous aurez un écran titre qui a l’air voulu plutôt qu’accidentel.

Donnez à l’overlay une taille qui vous parle

Commencez un nouveau fichier appelé text.singe avec deux lignes :

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

Vous avez écrit la première ligne de nombreuses fois ; elle charge le framework, qui définit DIR, les noms SWITCH_*, et les noms FONT_QUALITY_* dont vous allez vous servir.

La seconde compte plus qu’elle n’en a l’air. L’overlay — la surface sur laquelle atterrit tout ce que vous dessinez — commence à la moitié de la taille du monde. Un jeu sans vidéo a un canevas de 720 sur 480, donc l’overlay commence à 360 sur 240, et une police de 36 points sur un overlay de 360 pixels de large est énorme. overlaySetResolution remplace l’overlay par un overlay de la taille que vous demandez, et à partir de là, chaque coordonnée que vous donnez, et tout ce que vous disent overlayGetWidth et overlayGetHeight, est dans cet espace.

discGetWidth() et discGetHeight() donnent la taille de la vidéo quand il y en a une et la taille du canevas quand il n’y en a pas, donc cette seule ligne vous donne un overlay accordé au monde, quel que soit le genre de jeu. Appelez-la une fois, au début, avant de dessiner quoi que ce soit.

Chargez une police

En dessous, ajoutez :

fontQuality(FONT_QUALITY_BLENDED)

local titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)

fontLoad ouvre un fichier de police TrueType et vous renvoie un nombre — un handle — dont vous vous servez chaque fois que vous voulez cette police. Le second argument est la taille en points, et elle est fixée pour toute la vie du handle. Il n’y a aucun moyen de changer ensuite la taille d’une police chargée. Si vous voulez la même police en trois tailles, vous appelez fontLoad trois fois et vous gardez trois handles.

Singe/FreeSansBold.ttf est la police que le moteur a déballée dans le dossier Singe de votre dossier de travail la première fois que vous avez lancé quoi que ce soit. Chaque copie de Singe l’a, donc vous pouvez compter dessus. N’importe quel autre fichier .ttf marche de la même façon ; mettez-le à côté de votre script et chargez-le avec DIR .. "myfont.ttf".

Maintenant, affichez du texte avec :

function onOverlayUpdate()
    overlayClear()
    fontPrint(24, 60, "ASTEROID PATROL")
    return OVERLAY_UPDATED
end

Lancez-le. De grandes lettres blanches près du coin supérieur gauche.

Remarquez ce que vous n’avez pas fait : vous n’avez jamais dit à fontPrint quelle police utiliser. fontLoad fait de la police qu’il vient de charger la police sélectionnée, et fontPrint dessine toujours avec celle qui est sélectionnée. Avec plus d’une police chargée, vous choisissez entre elles avec fontSelect, ce que vous allez faire dans un instant.

Remarquez aussi que 24 et 60 sont des pixels, pas des cellules de caractère. C’est la différence entre fontPrint et overlayPrint qui fait trébucher les gens : overlayPrint(2, 2, …​) veut dire deux lettres vers la droite et deux lignes vers le bas, alors que fontPrint(2, 2, …​) veut dire deux pixels vers la droite et deux pixels vers le bas, c’est-à-dire coincé dans le coin. Le y que vous donnez est le haut du texte, pas la ligne de base sur laquelle il repose.

La couleur

fontPrint prend trois arguments et aucun n’est une couleur. La couleur vient d’ailleurs :

    colorForeground(255, 211, 90)
    fontPrint(24, 60, "ASTEROID PATROL")

colorForeground règle le rouge, le vert et le bleu de 0 à 255, avec un quatrième nombre facultatif pour l’opacité. Ce n’est l’argument de rien du tout ; c’est un réglage dont le moteur se souvient. Tout ce qui est dessiné après sort dans cette couleur jusqu’à ce que vous la changiez de nouveau, exactement comme ça marche déjà pour overlayBox et overlayLine. Le schéma est donc toujours le même : réglez la couleur, puis dessinez.

C’est la première chose que les gens font de travers avec les polices, et la deuxième arrive dans quelques pages.

La qualité

fontQuality décide comment les lettres sont rastérisées — comment les courbes d’une lettre sont transformées en pixels — et il y a trois choix. Essayez chacun en le mettant au-dessus de la ligne fontLoad et en regardant le résultat de près.

FONT_QUALITY_SOLID est le plus rapide. Chaque pixel fait partie de la lettre ou n’en fait pas partie, donc les diagonales et les courbes sortent avec des marches d’escalier visibles. En 48 points, ça fait bon marché. En 12 points sur un petit overlay, ça peut paraître plus net que les autres choix, et c’est parfois ce que vous voulez.

FONT_QUALITY_SHADED lisse les bords, mais il le fait en les mélangeant avec la couleur de fond actuelle, et il dessine ce fond comme un rectangle plein derrière toute la chaîne. Vous obtenez une étiquette entourée d’une boîte, que vous en vouliez une ou non. C’est la bonne réponse pour un afficheur de débogage par-dessus une image chargée, et la mauvaise pour presque tout le reste.

FONT_QUALITY_BLENDED lisse les bords et les garde transparents, donc les lettres se posent sur ce qu’il y a derrière elles. C’est le plus coûteux et c’est ce que vous voulez presque tout le temps. Utilisez-le à moins d’avoir une raison de ne pas le faire.

Le réglage est global, pas propre à chaque police, et il s’applique à partir du moment où vous l’appelez. Les sprites que vous avez déjà faits gardent la qualité avec laquelle ils ont été faits. L’entrée de la Référence consacrée à fontQuality liste les trois noms et leurs valeurs.

Mesurer, pour pouvoir centrer

Tôt ou tard — en général au bout d’une dizaine de minutes — vous voulez le titre au milieu de l’écran. Vous savez que l’écran fait overlayGetWidth() de large. Vous ne savez pas quelle largeur fait le texte, et il n’y a pas d’appel fontMeasure pour le demander.

Ce qu’il y a à la place, c’est fontToSprite. Il fait le rendu d’une chaîne avec la police sélectionnée, la qualité actuelle et la couleur actuelle, et au lieu de la mettre à l’écran, il vous renvoie un sprite : le même genre de handle que celui que vous donne spriteLoad, ce qui veut dire que chaque appel sprite* que vous avez appris à la leçon neuf marche dessus. Y compris les deux qui le mesurent.

fontSelect(titleFont)
colorForeground(255, 211, 90)
local titleImage = fontToSprite("ASTEROID PATROL")

Puis, dans onOverlayUpdate :

    local x = (overlayGetWidth() - spriteGetWidth(titleImage)) / 2
    spriteDraw(titleImage, x, 60)

C’est ça, centrer, et c’est tout le secret. Prenez la largeur de l’espace, retirez la largeur de la chose, et la moitié de ce qui reste est l’écart de chaque côté.

L’alignement à droite, c’est la même idée avec moins de calcul. Pour mettre du texte contre la marge de droite :

    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), y)

spriteGetHeight mesure l’autre direction, pour empiler des lignes ou centrer verticalement.

Il y a un piège dans le premier bloc de code, et c’est la deuxième chose que tout le monde fait de travers. La couleur est figée quand le sprite est fabriqué, pas quand il est dessiné. Un colorForeground au-dessus de fontToSprite change le texte. Le mettre plutôt au-dessus de spriteDraw ne fait rien du tout, parce que colorForeground est un réglage pour dessiner du texte et des traits, et qu’un sprite est dessiné avec ses propres pixels. Si votre titre soigneusement coloré sort en blanc, voilà pourquoi.

On peut recolorer un sprite après l’avoir fabriqué, mais avec un appel de sprite, pas avec colorForeground. spriteSetTint(image, red, green, blue) multiplie chaque pixel du sprite par cette couleur chaque fois qu’il est dessiné, donc un texte rendu en blanc peut être dessiné en jaune aujourd’hui et en rouge demain sans être refait. Le blanc est la couleur dans laquelle faire le rendu quand vous comptez teinter : tout ce qui est multiplié par le blanc reste ce qu’il était, donc la teinte est exactement la couleur que vous demandez.

Ce que coûte l’affichage

La première fois que fontPrint voit une chaîne, il fait un vrai travail : il rastérise chaque lettre à partir des contours de la police et construit une image de toute la chaîne. Puis il garde cette image. La fois suivante où vous affichez la même chaîne, avec la même police, la même qualité et les mêmes couleurs, il saute tout ça et copie l’image qu’il a déjà, ce qui coûte à peu près autant que dessiner un sprite. Une chaîne que vous arrêtez d’afficher est lâchée une seconde plus tard, donc rien ne s’accumule.

Ça veut dire que la façon évidente d’écrire un écran titre est aussi la plus rapide. Afficher "ASTEROID PATROL" soixante fois par seconde n’en fait le rendu qu’une fois. Un score qui change deux fois par seconde est rendu deux fois par seconde, tout seul, sans aucune comptabilité de votre part.

Le seul cas qui coûte, c’est du texte qui est différent à chaque image — un minuteur en millisecondes, un compteur d’images — parce que chaque image est une chaîne que fontPrint n’a jamais vue. Sur un ordinateur de bureau, ça n’a pas d’importance. Sur un Raspberry Pi ou une console portable, un plein écran de ce genre de texte en aura. Le remède est de changer le texte moins souvent : un minuteur en secondes entières est une nouvelle chaîne une fois par seconde, pas soixante.

Alors pourquoi cette leçon a-t-elle utilisé fontToSprite ? Parce qu’un sprite peut faire des choses que le texte affiché ne peut pas faire :

  • On peut le mesurer, et c’est la seule façon de centrer du texte ou de l’aligner contre le côté droit.

  • On peut le redimensionner et le faire tourner avec les appels sprite* de la leçon neuf.

  • Il peut survivre à sa police, ce qui va compter dans un instant.

Utilisez fontPrint pour le texte, et fontToSprite quand vous avez besoin de l’une de ces choses.

Le score de cette leçon a besoin de l’une d’elles : il est placé contre la marge de droite, donc il doit être mesuré, donc il doit être un sprite. Et un sprite de score n’est juste que jusqu’à ce que le score change. Quand il change, faites le rendu d’un nouveau sprite et déchargez l’ancien — l’oublier laisse fuir un sprite à chaque changement :

local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end

scoreShown retient quel score ce sprite affiche, pour que le code de dessin puisse savoir s’il est encore juste :

    if score ~= scoreShown then
        renderScore()
    end

string.format("%06d", score) est du Lua tout simple, pas du Singe. Il transforme un nombre en chaîne, et %06d veut dire « en nombre entier, au moins six chiffres, complété par des zéros », c’est pourquoi les scores d’arcade ont des zéros devant. Changez-le en %d et les zéros disparaissent.

Ranger les polices

fontUnload ferme une police et rend son handle invalide. Les sprites que vous avez faits avec fontToSprite ne sont pas touchés — une fois rendu, un sprite n’a plus rien à voir avec la police — donc vous pouvez décharger une police et continuer de dessiner le texte fait avec elle.

Un point délicat : si vous déchargez la police qui était sélectionnée, aucune police n’est sélectionnée ensuite, et le fontPrint suivant termine votre jeu avec une erreur. Sélectionnez-en d’abord une autre si vous comptez continuer d’afficher du texte.

L’endroit bien rangé pour tout ça, c’est onShutdown, un callback que le moteur appelle une fois quand le jeu se ferme :

function onShutdown()
    spriteUnload(titleImage)
    fontUnload(titleFont)
end

Singe fait le ménage derrière vous quand le jeu se termine, donc rien ne prend feu si vous sautez cette étape. Écrivez-la quand même. Un jeu qui libère ce qu’il a chargé est un jeu qu’on peut charger deux fois.

Le script complet

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local MARGIN  = 24
local TITLE_Y = 60
local SCORE_Y = 170
local LABEL_Y = 186
local HINT_Y  = 300
local CLOCK_Y = 430

local score      = 0
local titleFont  = nil
local scoreFont  = nil
local smallFont  = nil
local titleImage = nil
local hintImage  = nil
local scoreImage = nil
local scoreShown = nil


local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end


local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end


fontQuality(FONT_QUALITY_BLENDED)

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

fontSelect(titleFont)
colorForeground(255, 211, 90)
titleImage = fontToSprite("ASTEROID PATROL")

fontSelect(smallFont)
colorForeground(140, 200, 255)
hintImage = fontToSprite("Press the fire button to score")

renderScore()


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        score = score + 125
    end
end


function onOverlayUpdate()
    overlayClear()

    spriteDraw(titleImage, centered(titleImage), TITLE_Y)

    if score ~= scoreShown then
        renderScore()
    end
    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), SCORE_Y)

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")
    fontPrint(MARGIN, CLOCK_Y, "Running for " .. (singeGetTicks() // 1000) .. " seconds")

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(titleImage)
    spriteUnload(hintImage)
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontUnload(titleFont)
    fontUnload(scoreFont)
    fontUnload(smallFont)
end

Lancez-le et maintenez le bouton de tir. Le titre et l’indication sont centrés, le score grimpe contre la marge de droite et n’est rendu de nouveau que lorsqu’il change, l’indication clignote, et l’étiquette et l’horloge sont affichées avec fontPrint à chaque image — l’horloge en secondes entières, donc ce n’est une nouvelle chaîne qu’une fois par seconde.

Ce qui vient de se passer

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

Un fichier, trois tailles, trois handles. Chacun coûte de la mémoire pour son propre jeu de glyphes rendus, donc chargez les tailles dont vous vous servez et pas plus. Trois, c’est normal. Une douzaine, ça sent mauvais.

Après ces trois lignes, la police sélectionnée est smallFont, parce que charger sélectionne. C’est pourquoi le code appelle fontSelect(titleFont) avant de faire le rendu du titre : la dernière chose chargée n’est pas celle que vous voulez en premier.

local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end

Écrite une fois comme fonction parce qu’elle sert deux fois, et parce que la prochaine fois que vous voudrez centrer quelque chose, vous en aurez de nouveau besoin. Donnez un nom au calcul et vous n’aurez plus jamais à le relire.

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

singeGetTicks() est le nombre de millisecondes écoulées depuis le démarrage du moteur. // est la division qui jette le reste, donc singeGetTicks() // 500 compte des demi-secondes, et % 2 est le reste de la division par deux, qui vaut 0, 1, 0, 1…​ Donc l’indication est dessinée pendant une demi-seconde et sautée pendant une demi-seconde. Ne rien dessiner, c’est comme ça qu’on fait clignoter quelque chose.

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")

Les deux réglages sont nécessaires ici, et ça vaut la peine de dire clairement pourquoi. Dessiner un sprite ne change ni la police sélectionnée ni la couleur, donc les deux appels spriteDraw au-dessus les laissent exactement comme ils les ont trouvées. Mais le code de mise en place a sélectionné trois polices différentes à tour de rôle, et renderScore en sélectionne une autre chaque fois que le score bouge, donc la sélection au moment où cette ligne s’exécute est celle qui s’est trouvée choisie en dernier. N’essayez pas de la suivre. Sélectionnez la police et réglez la couleur juste avant d’afficher, à chaque fois. Ça fait deux lignes, et ça supprime toute une catégorie de soirées perplexes.

Essayez

  1. Changez la qualité. Mettez FONT_QUALITY_SOLID dans la ligne fontQuality et regardez la courbe du S dans ASTEROID. Puis essayez FONT_QUALITY_SHADED et regardez ce qui se passe derrière chaque chaîne.

  2. Mettez l’indication en jaune. Déplacez la ligne colorForeground(140, 200, 255) d’au-dessus de fontToSprite à juste au-dessus du spriteDraw qui dessine hintImage, et changez les nombres. Trouvez pourquoi rien ne se passe. Puis remettez-la, faites plutôt l’indication en blanc, et rendez-la jaune avec spriteSetTint juste avant qu’elle soit dessinée.

  3. Alignez l’horloge à droite. L’horloge est dessinée avec fontPrint, qu’on ne peut pas mesurer. Mettez-la quand même contre la marge de droite. Il n’y a qu’une seule façon de le faire, et la trouver, c’est tout l’intérêt.

  4. Retirez la vérification de scoreShown, pour que renderScore() s’exécute plutôt à chaque image. Ça aura exactement la même allure, mais ça fait maintenant le rendu du score soixante fois par seconde au lieu de le faire quand il change — exactement le travail que fontPrint vous épargne quand vous le laissez faire. Puis retirez aussi le spriteUnload de renderScore, laissez tourner une minute, et surveillez la mémoire qu’utilise votre jeu.

  5. Affichez une horloge en millisecondes. Changez la ligne de l’horloge pour qu’elle affiche singeGetTicks() sans le // 1000. Ça marche toujours ; c’est maintenant une chaîne que fontPrint n’a jamais vue, à chaque image. Sur une machine lente, c’est ce genre de texte qui coûte.

  6. Utilisez votre propre police. Trouvez un .ttf sur votre machine, copiez-le à côté de votre script, et chargez-le avec DIR .. "thatfont.ttf". Certaines polices sont affreuses en 18 points et très bien en 48. C’est la faute de la police, pas la vôtre.

Cassez-le exprès

Ajoutez une ligne fontPrint(24, 60, "SCORE") juste sous overlaySetResolution(discGetWidth(), discGetHeight()), pour qu’elle s’exécute avant tout fontLoad. Singe démarre et meurt aussitôt :

4:fontPrint:  No font selected.

Lisez-le comme n’importe quelle autre erreur. 4 est la ligne. fontPrint est l’appel du moteur qui s’est plaint — un message de cette forme vient de l’intérieur du moteur plutôt que de Lua, donc il nomme la fonction au lieu du fichier. Le reste, c’est la plainte, et ici elle est exacte : vous lui avez demandé d’afficher du texte et il n’y avait pas de police pour le faire.

Vous rencontrerez celle-ci pour de vrai, d’une façon moins évidente. Déchargez la police sélectionnée pendant que le jeu tourne, et le fontPrint suivant dit exactement la même chose, à plusieurs centaines de lignes du fontUnload qui l’a causée.

Ce que vous avez appris

  • fontLoad ouvre un fichier TrueType à une taille en points fixe et renvoie un handle. Une taille, un handle.

  • Charger une police la sélectionne ; fontSelect choisit entre les polices chargées.

  • fontPrint compte en pixels et overlayPrint compte en cellules de caractère.

  • La couleur n’est pas un argument. colorForeground est un réglage ; réglez-le, puis dessinez.

  • fontQuality choisit comment les lettres sont rastérisées, et FONT_QUALITY_BLENDED est la réponse habituelle.

  • fontPrint garde ce dont il a fait le rendu, donc afficher le même texte à chaque image coûte peu ; c’est le texte différent à chaque image qui coûte.

  • fontToSprite fait le rendu dans un sprite, que spriteGetWidth mesure et que les appels sprite* peuvent redimensionner et faire tourner. Utilisez-le pour ça, pas pour la vitesse.

  • Mesurer est la façon de centrer ou d’aligner du texte à droite, parce que rien d’autre ne peut vous dire quelle largeur fera une chaîne.

  • colorForeground atteint le texte quand il est fabriqué, jamais un sprite quand il est dessiné ; spriteSetTint est la façon de recolorer un sprite après coup.

  • fontUnload libère une police ; les sprites qu’elle a servi à faire lui survivent.

La prochaine fois

Du texte qui a de l’allure, c’est encore loin d’un menu qui marche. Une page avec un titre, une liste dans laquelle on déplace un curseur, une glissière, et un bouton, c’est une centaine de lignes de dessin et de calculs de curseur si vous la construisez avec les appels de cette leçon. La leçon vingt ne la construit pas du tout avec ces appels.

Leçon 20 : Menus et écrans

La leçon terminée

Vous pouvez construire un menu avec ce que vous savez déjà. Une boîte, un peu de texte, un curseur qui bouge quand le stick bouge, un if pour chaque choix, et de l’arithmétique pour garder tout ça aligné quand vous ajoutez une quatrième option. Ça marche. C’est aussi une centaine de lignes pour une page avec trois boutons, et chacune de ces lignes, c’est à vous de l’entretenir.

Singe contient tout un moteur de documents — RmlUi — et un menu écrit pour lui est une page, comme une page web, avec une feuille de style. Elle fait passer son texte à la ligne toute seule. Elle se met en page d’elle-même quand vous ajoutez une option. Elle sait ce qu’est un bouton, ce qu’est un curseur, et quel contrôle le joueur est en train de viser. Cette leçon s’en sert pour construire un menu de pause, par-dessus un jeu qui continue de tourner derrière.

Deux fichiers

Une page de GUI, c’est deux choses : un document qui dit ce qu’il y a sur la page, et du Lua qui dit ce que fait la page. Ils vivent dans des fichiers séparés, et c’est tout l’intérêt de l’exercice — la mise en page cesse d’être du code.

Commencez par un script appelé menu.singe et un jeu si petit qu’il tient en un paragraphe : un vaisseau qui traverse l’écran, et un score qui augmente chaque fois qu’il arrive de l’autre côté. Vous écrivez ce genre de chose depuis la leçon sept.

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local ship  = spriteLoad(DIR .. "art/spaceship.png")
local shipX = 0
local speed = 2
local score = 0


function onOverlayUpdate()
    overlayClear()
    shipX = shipX + speed
    if shipX > overlayGetWidth() then
        shipX = -spriteGetWidth(ship)
        score = score + 10
    end
    spriteDraw(ship, shipX, 300)
    return OVERLAY_UPDATED
end

Ça tourne. Maintenant, le document. À côté de votre script, créez un fichier appelé pause.rml :

<rml>
<head>
	<title>Pause</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		#frame { width: 380dp; margin: 80dp auto; }
		.row { display: block; margin: 8dp 0; }
		label { display: inline-block; width: 100dp; }
		button { nav: auto; }
		input.range { nav: auto; width: 200dp; }
		#status { min-height: 28dp; }
	</style>
</head>
<body id="pause">
	<div id="frame" class="panel">
		<h1>Paused</h1>
		<p class="row">Score <span id="score">000000</span></p>
		<div class="row"><label>Speed</label><input type="range" id="speed" min="1" max="8" step="1" value="2"/></div>
		<div class="row">
			<button id="resume" autofocus>Resume</button>
			<button id="restart">Restart</button>
			<button id="quit">Quit</button>
		</div>
		<p id="status" class="muted">Arrow keys move, Return chooses.</p>
	</div>
</body>
</rml>

Si vous avez déjà vu le code source d’une page web, ça vous dira quelque chose. Sinon, voici tout ce qu’il vous faut pour le lire.

Un document est fait d'éléments. Un élément commence par un nom entre chevrons, <h1>, finit par le même nom avec une barre oblique, </h1>, et tout ce qui se trouve entre les deux est à l’intérieur. Certains éléments n’ont rien à l’intérieur et se ferment eux-mêmes avec une barre oblique à la fin, comme le <input …​/> ci-dessus. Les éléments s’imbriquent, et l’indentation montre l’imbrication de la même façon qu’en Lua.

Les mots à l’intérieur de la balise ouvrante sont des attributs, écrits name="value". Deux d’entre eux vous concernent plus que les autres. id donne à un élément un nom grâce auquel votre script peut le trouver, et c’est ainsi que Lua et le document se parlent. class met l’élément dans un groupe que la feuille de style peut viser ; panel, muted et list sont des groupes que la feuille de style du moteur connaît déjà.

Le langage de balisage s’appelle RML et le langage de style s’appelle RCSS. Ce sont ceux de RmlUi, pas ceux de Singe. Le chapitre GUI de la Référence renvoie à la documentation de RmlUi pour la liste complète de ce que vous pouvez écrire, et vous en aurez besoin un jour. Tout ce qui est dans cette leçon fonctionne sans.

Affichez-la

Retour au script. Au-dessus de onOverlayUpdate, ajoutez :

local gui  = guiNew(overlayGetWidth(), overlayGetHeight())
local page = guiLoad(gui, DIR .. "pause.rml")

guiNew crée une GUI : un rectangle de taille fixe dans lequel des documents sont mis en page et dessinés. L’appel renvoie un handle, comme le font fontLoad et spriteLoad. La faire de la taille de l’overlay veut dire qu’un pixel du document est un pixel de votre overlay, ce qui garde simple l’arithmétique que vous faites de tête.

guiLoad lit un document dans cette GUI et renvoie un second handle, pour le document lui-même. Presque tous les autres appels prennent les deux : la GUI et le document qu’elle contient. Une GUI peut contenir jusqu’à trente-deux documents — une page de titre, une page d’options et une page de fin de partie peuvent en partager une — et il peut exister jusqu’à seize GUI à la fois.

Rien n’est encore à l’écran, parce que charger un document ne le dessine pas. Ajoutez une ligne à onOverlayUpdate, juste avant le return :

    guiDraw(gui)

Lancez-le. Le panneau est là, par-dessus le vaisseau, avec son titre, ses trois boutons et son curseur, et vous n’avez écrit aucun code de dessin.

guiDraw superpose la GUI à l’overlay pour cette image seulement, comme tous les autres appels de dessin, donc sa place est dans onOverlayUpdate et il faut l’appeler de nouveau à l’image suivante. L’endroit où vous la mettez décide de ce qui est au-dessus : tout ce que vous avez dessiné avant est en dessous, et tout ce que vous dessinez après passe par-dessus. Un réticule dessiné après guiDraw n’est jamais caché par le menu.

Laissez le joueur s’en servir

Cliquez sur un bouton. Il ne se passe rien, et le bouton ne s’allume même pas.

Une nouvelle GUI est une image, pas un tableau de commandes. C’est voulu : un HUD ou une pancarte ne doit pas avaler le bouton de tir. Pour qu’une page accepte les entrées :

guiSetInput(gui, true)

Maintenant la souris fonctionne, les boutons s’allument sous le pointeur, et les touches fléchées passent d’un contrôle à l’autre, parce que le document l’a demandé avec nav: auto. Sur une manette ou un stick, les quatre directions arrivent comme les touches fléchées, le premier bouton d’action arrive comme Entrée, et le second comme Échap. Une borne avec un joystick et deux boutons pilote cette page sans savoir que c’est un document.

On dit que le contrôle sur lequel agissent les touches a le focus, et un bouton qui a le focus porte une bordure dorée. Le focus démarre sur Resume parce que ce bouton porte autofocus : chaque fois que la page s’affiche, le focus va au contrôle marqué ainsi. Retirez-le et les touches fléchées n’ont aucun point de départ tant que le joueur n’a pas cliqué quelque part, ce qui, sur une borne sans souris, n’arrive jamais.

Pourtant, cliquer ne fait toujours rien, parce que personne n’écoute.

Parlez-lui

Trois appels relient le document à votre script, et à eux trois ils font presque tout.

guiSetHandler(gui, page, "resume", "click", function()
    closeMenu()
end)

guiSetHandler dit : quand l’élément qui porte cet id fait telle chose, appelle cette fonction. Cet id est celui du document. Le nom de l’événement est celui de RmlUi : "click" pour les boutons, "change" pour tout ce que le joueur règle, et une longue liste d’autres que vous pourrez chercher quand vous en aurez besoin. Une seule fonction est gardée par élément et par événement, donc en régler une autre la remplace, et passer nil au lieu d’une fonction la retire.

Votre fonction est appelée avec cinq arguments — la GUI, le document, l’id, l’événement, et la valeur actuelle de l’élément sous forme de chaîne. Prenez-en autant que vous voulez et ignorez le reste, comme vous ignorez déjà des arguments en Lua.

guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
    speed = math.floor(tonumber(value))
end)

Le curseur transmet sa valeur sous forme de chaîne, et RmlUi formate les nombres à sa façon, donc 4 arrive sous la forme "4.000000". tonumber transforme la chaîne en nombre et math.floor jette la partie décimale. Sauter cette étape et utiliser la chaîne comme un nombre est une erreur que vous ferez une fois.

guiSetValue(gui, page, "score", string.format("%06d", score))

guiSetValue écrit dans un élément. Pour un contrôle de formulaire, elle règle la valeur du contrôle ; pour tout le reste — un paragraphe, une div, le <span id="score"> de votre document — elle remplace ce qu’il y a dans l’élément, et la page refait sa mise en page à l’image suivante. guiGetValue est le même appel à l’envers, et elle répond nil pour un id que rien ne porte, si bien que vous pouvez demander des nouvelles d’un élément qui n’est peut-être pas là sans que tout plante.

Voilà toute l’API de tous les jours : guiSetHandler, guiSetValue, guiGetValue. Il y a bien plus à disposition à travers les objets Lua propres à RmlUi, accessibles par la globale rmlui, et le chapitre GUI de la référence montre comment. Vous irez loin avant d’en avoir besoin.

Cachez-la de nouveau

Un menu de pause n’est pas affiché tout le temps. guiHide retire un document de l’écran et guiShow le remet, en gardant tout ce que le joueur a tapé ou choisi.

La pause elle-même, c’est singeSetPauseFlag(true), qui arrête le disque, les vidéos et les sons mais continue d’appeler vos callbacks, si bien que vous pouvez encore dessiner. Le moteur a sa propre touche de pause, qui fige complètement le script, et les deux se battraient ; singeSetPauseKeyEnabled(false) retire cette touche au moteur pour que SWITCH_PAUSE arrive à onInputPressed comme n’importe quel autre contact. Sur un clavier, cette touche est P.

local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    guiHide(gui, page)
    guiSetInput(gui, false)
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    guiSetValue(gui, page, "score", string.format("%06d", score))
    guiShow(gui, page)
    guiSetInput(gui, true)
end

Couper les entrées en même temps que la page n’est pas de la décoration. Une page cachée qui accepte encore les entrées mange les touches fléchées du joueur pour le reste de la partie.

Ce que la page n’utilise pas, vous le recevez quand même

C’est la règle qui permet de laisser une GUI affichée pendant le jeu sans danger, et elle mérite d’être dite clairement : un événement qu’un élément a utilisé n’atteint jamais vos callbacks. Un appui sur Entrée qui a actionné le bouton qui a le focus n’arrive pas comme onInputPressed. Une flèche qui a déplacé le focus n’arrive pas comme SWITCH_LEFT. Un clic sur un bouton n’est pas un contact de souris.

Tout ce que la page n’a pas utilisé passe tout droit, comme d’habitude. C’est pour ça que P ferme ce menu : aucun élément du document n’utilise P, donc la touche arrive à onInputPressed exactement comme quand le menu n’est pas affiché. C’est aussi pour ça qu’un HUD qui accepte les entrées laisse quand même passer le bouton de tir.

Une touche ne suit pas la règle. RmlUi utilise Tab pour déplacer le focus et ne rend jamais la touche, donc Singe ne donne Tab à une GUI que pendant qu’on est réellement en train de taper dans un champ de texte. Un jeu qui affecte Tab à quelque chose le garde.

Mettez-la en forme

Revenez au <head> du document. Une ligne fait l’essentiel du travail :

	<link type="text/rcss" href="Singe/gui.rcss"/>

C’est le thème que le moteur fournit, et c’est pour ça que votre panneau a une bordure, un dégradé et un titre doré sans que vous ayez rien choisi. Sans feuille de style, RmlUi ne dessine presque rien, parce que chaque élément part en ligne et à la taille de son contenu ; alors lier celle-ci en premier et redéfinir ce qui vous déplaît est le chemin le plus rapide vers une page qui ressemble à quelque chose.

Le thème vous donne .panel (une boîte arrondie avec une bordure), .list (une boîte qui défile et dont les lignes div enfants sont mises en évidence et prennent le focus), .muted (un texte plus pâle pour les indications), des titres, et tous les contrôles de formulaire avec leurs états survol, focus et enfoncé. Le chapitre GUI de la Référence les liste.

Tout ce qui vient après le lien est à vous. Le bloc <style> de pause.rml redéfinit le thème pour cette page, les règles qui viennent après l’emportant sur celles d’avant, et une règle qui vise un id bat une règle qui vise une class. Pour un vrai jeu, mettez vos propres règles dans un fichier .rcss à côté du document et liez-le en second, pour que votre style tienne en un seul fichier pour toutes les pages.

L’unité dp est un pixel de la GUI, à sa propre taille — votre GUI fait la taille de l’overlay, donc 380dp font 380 pixels de l’overlay. margin: 80dp auto est l’astuce qui centre un bloc de largeur connue : auto partage à égalité entre les deux côtés tout ce qui reste. Il n’y a rien à mesurer ni à calculer, ce qui, après la leçon dix-neuf, vous agacera peut-être un peu.

Pour utiliser votre propre police dans un document, chargez-la avec guiLoadFont avant les documents qui s’en servent, et nommez-la en RCSS par le nom de famille inscrit dans le fichier de police, pas par son nom de fichier.

Quand ne rien utiliser de tout ça

Une GUI est une page. C’est la bonne réponse pour un menu, un écran d’options, un tableau des meilleurs scores, un écran de fin de partie, ou un HUD avec une vraie mise en page.

C’est la mauvaise réponse pour un score dans le coin. Ça, c’est deux lignes de fontPrint de la leçon dix-neuf, et l’emballer dans un document ne vous rapporte rien et vous coûte une texture. Il en va de même pour un réticule, une barre de vie que vous avez dessinée avec overlayBox, et une ligne de texte de débogage.

Trois faits tranchent pour vous.

Une GUI a besoin d’un GPU. Sur une machine qui n’en a pas — un vieux PC, un petit Pi, une machine sans aucun pilote Vulkan, Direct3D 12 ou Metal — il n’y a pas de GUI, et guiNew ne répond pas poliment false, elle met fin à votre jeu. La scène 3D de la leçon vingt-deux suit le même chemin, donc ce n’est pas la dernière fois que vous poserez la question. Demandez d’abord singeHasGpu() si votre jeu doit tourner aux deux endroits, et prévoyez une version simple à l’overlay sur laquelle vous rabattre. Le menu du moteur lui-même fait exactement ça.

Une GUI coûte une texture et une passe de mise en page à chaque image, que vous la dessiniez ou non. Une GUI dont vous avez fini de vous servir doit être supprimée avec guiDelete, pas simplement cachée. Cacher, c’est pour une page que vous montrerez de nouveau dans une minute.

Et une GUI est détruite par un rechargement. F5, -R et tout ce qui relance le script emportent toutes les GUI avec eux, et le script les refait quand il s’exécute. Ce n’est pas grave, tant que vous les construisez dans le corps de votre script et pas dans un coin qui ne s’exécute qu’une fois.

Le script complet

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())
singeSetPauseKeyEnabled(false)

local SHIP_Y = 300

local ship    = spriteLoad(DIR .. "art/spaceship.png")
local hudFont = fontLoad("Singe/FreeSansBold.ttf", 20)
local shipX   = 0
local speed   = 2
local score   = 0
local paused  = false
local gui     = nil
local page    = nil


local function say(text)
    if gui ~= nil then
        guiSetValue(gui, page, "status", text)
    end
end


local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    if gui ~= nil then
        guiHide(gui, page)
        guiSetInput(gui, false)
    end
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    if gui ~= nil then
        guiSetValue(gui, page, "score", string.format("%06d", score))
        guiShow(gui, page)
        guiSetInput(gui, true)
    end
end


if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")
    guiHide(gui, page)
    guiSetInput(gui, false)

    guiSetHandler(gui, page, "resume", "click", function()
        closeMenu()
    end)

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

    guiSetHandler(gui, page, "quit", "click", function()
        singeQuit()
    end)

    guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
        speed = math.floor(tonumber(value))
        say("Speed " .. speed)
    end)
end


function onInputPressed(what)
    if what == SWITCH_PAUSE then
        if paused then
            closeMenu()
        else
            openMenu()
        end
    end
end


function onOverlayUpdate()
    overlayClear()

    if not paused then
        shipX = shipX + speed
        if shipX > overlayGetWidth() then
            shipX = -spriteGetWidth(ship)
            score = score + 10
        end
    end
    spriteDraw(ship, shipX, SHIP_Y)

    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    fontPrint(16, 16, string.format("SCORE %06d", score))
    fontPrint(16, 40, "P pauses")

    if paused then
        if gui ~= nil then
            guiDraw(gui)
        else
            colorForeground(255, 211, 90)
            fontPrint(16, 70, "PAUSED -- no GPU, so no menu")
        end
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    if gui ~= nil then
        guiDelete(gui)
    end
    spriteUnload(ship)
    fontUnload(hudFont)
end

Ce qui vient de se passer

if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")

Toute la GUI est construite à l’intérieur de ce if, et gui reste nil sur une machine sans GPU. Chaque appel qui touche à la GUI est protégé par if gui ~= nil, et la pause marche toujours sans menu. Ça fait quatre lignes de plus, et c’est la différence entre « n’a pas de menu sur cette machine » et « ne démarre pas sur cette machine ».

    guiHide(gui, page)
    guiSetInput(gui, false)

guiLoad affiche le document qu’elle a chargé, donc une page qui doit démarrer cachée doit être cachée immédiatement. Les entrées sont déjà coupées pour une nouvelle GUI, mais les couper ici fait de openMenu et closeMenu le reflet exact l’une de l’autre, et des paires en miroir sont bien plus difficiles à rater.

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

Le gestionnaire est une fonction sans nom, écrite là où on s’en sert. Lua vous laisse écrire function(…​) …​ end partout où une valeur est attendue, et puisque guiSetHandler attend une fonction, vous pouvez lui en donner une sur-le-champ au lieu de la nommer d’abord et de passer le nom. Elle atteint score, shipX et closeMenu parce qu’ils sont déclarés au-dessus d’elle dans le même fichier, et c’est toute la raison pour laquelle les gestionnaires sont mis en place sous les choses qu’ils touchent.

    if not paused then
        shipX = shipX + speed

Le drapeau de pause arrête le disque et les sons, pas votre arithmétique. onOverlayUpdate continue d’être appelée — c’est tout l’intérêt, sinon le menu ne pourrait pas être dessiné — donc tout ce qui est à vous et qui doit s’arrêter pendant la pause, c’est à vous de l’arrêter.

Essayez

  1. Ajoutez un quatrième bouton. Copiez la ligne <button id="quit">, donnez-lui un nouvel id et un nouveau texte, et ajoutez-lui un gestionnaire. Remarquez que rien n’a eu besoin d’être remesuré ni décalé.

  2. Changez son style. Dans le bloc <style>, changez #frame en width: 260dp; margin: 20dp; et regardez le panneau se déplacer et le texte se remettre à la ligne tout seul.

  3. Retirez le guiSetInput(gui, true) de openMenu. La page apparaît toujours. Trouvez, rien qu’en regardant l’écran, ce que vous avez perdu.

  4. Laissez la page affichée tout le temps. Supprimez les appels à guiHide, changez les deux appels guiSetInput(gui, false) en true, et dessinez la GUI à chaque image au lieu de seulement pendant la pause. Puis appuyez sur les touches fléchées et sur Entrée pendant que le vaisseau vole. La page les prend pour elle : le focus se déplace, le curseur change la vitesse, et Entrée appuie sur le bouton qui a le focus. Un jeu qui se piloterait avec ces touches ne les entendrait jamais. Voilà pourquoi un HUD, c’est guiSetInput(gui, false).

  5. Mettez le score sur la page plutôt que dans le HUD. Appelez guiSetValue pour score à chaque image plutôt que seulement dans openMenu, et supprimez la ligne fontPrint. Puis décidez laquelle des deux vous préférez vraiment, et pourquoi.

Cassez-le exprès

Changez un id dans pause.rml, de id="resume" en id="continue", et ne touchez pas au script. Singe démarre et plante :

52:guiSetHandler:  No element "resume" in document 0 of GUI 0.

Lisez-le comme n’importe quelle erreur du moteur. La ligne, l’appel qui s’est plaint, puis la plainte — et cette plainte est précise. Elle ne dit pas que le document est cassé ; le document s’est chargé parfaitement. Elle dit que vous avez demandé un élément par un nom que rien en lui ne porte.

guiSetHandler et guiSetValue plantent toutes les deux sur un id manquant, parce qu’un gestionnaire que vous vouliez attacher et que vous n’avez pas attaché est un bug dont vous voulez entendre parler tout de suite. guiGetValue est l’exception : elle répond nil à la place, pour que vous puissiez demander si quelque chose est là.

L’autre erreur qui vaut d’être rencontrée est celle que vous obtenez quand le document lui-même ne se charge pas. Renommez pause.rml et lancez. Cette fois, Singe nomme le fichier et cite la raison donnée par RmlUi, et les ronchonnements de RmlUi à propos de votre balisage et de vos styles vont à la console, que le chargement réussisse ou non. Lisez cette console la première fois qu’une page sort vide ; elle aura en général dit pourquoi.

Ce que vous avez appris

  • Une GUI est un rectangle de taille fixe dans lequel des documents sont mis en page et dessinés ; guiNew en crée une et guiDelete la libère.

  • guiLoad met un document RML dans une GUI et l’affiche ; guiHide, guiShow et guiClose le gèrent ensuite.

  • guiDraw superpose la GUI à l’overlay pour une image, donc sa place est dans onOverlayUpdate comme tous les autres appels de dessin.

  • Une nouvelle GUI ne fait qu’afficher ; c’est guiSetInput qui la rend utilisable.

  • guiSetHandler exécute votre fonction quand on clique sur un élément ou qu’on le modifie, guiSetValue écrit dans un élément, et guiGetValue en lit un.

  • Un événement qu’un élément a utilisé n’atteint jamais vos propres callbacks ; tout le reste passe comme d’habitude.

  • Singe/gui.rcss est le thème fourni ; liez-le en premier et redéfinissez-le dans un bloc <style> ou dans une feuille à vous.

  • Une GUI a besoin d’un GPU, alors demandez singeHasGpu() si votre jeu doit tourner sans.

  • Chaque GUI fait son rendu à chaque image, que vous la dessiniez ou non, alors supprimez celles dont vous avez fini de vous servir.

  • Un score dans le coin, c’est deux lignes de fontPrint, pas un document.

La prochaine fois

Il reste une autre sorte de texte à l’écran, et elle a son propre système pour une raison qui n’a rien à voir avec son apparence. La leçon vingt et un parle des sous-titres, et des joueurs qui ne peuvent pas jouer à votre jeu sans eux.

Leçon 21 : Les sous-titres

La leçon terminée

Quelqu’un qui n’entend pas va jouer à votre jeu.

Si votre jeu a des paroles et pas de sous-titres, cette personne ne le pourra pas. Pas « ce sera plus difficile pour elle » — elle arrivera à la première scène où un personnage dit ce qui explique au joueur quoi faire, et elle s’arrêtera là. C’est tout, et c’est la raison pour laquelle cette leçon existe au lieu d’être un paragraphe de la leçon dix-neuf.

L’autre raison est pratique. Ajouter des sous-titres après coup à un jeu terminé est une misère. Il faut retrouver chaque réplique, déterminer sur quelle image elle tombe, et découvrir que la moitié de vos synchronisations sont fausses parce que votre vidéo a été réencodée au milieu du projet. Fait pendant que vous écrivez le jeu, c’est un après-midi. Singe vous donne un système qui fait la partie difficile, et cette leçon explique comment vous en servir.

Ce n’est pas du texte ordinaire

Vous pourriez faire les sous-titres vous-même. Garder une liste de lignes avec leurs heures de début et de fin, regarder l’horloge dans onOverlayUpdate, et dessiner la ligne du moment avec fontToSprite. Certains l’ont fait. Voici pourquoi vous ne devriez pas.

Les sous-titres sont synchronisés sur le disque, pas sur une horloge. Quand srtLoad lit votre fichier, elle convertit chaque horodatage en numéro d’image du disque, sur-le-champ, en utilisant la fréquence d’images du disque chargé. À partir de là, le moteur ne regarde plus du tout une horloge ; à chaque image dessinée, il demande quel sous-titre couvre l’image sur laquelle se trouve le disque.

Cette seule décision vous offre ce qu’un système fait maison ne réussit jamais : un sous-titre survit à un saut. Envoyez le disque n’importe où — discSearch, discSkipForward, un pas, un embranchement vers un autre segment — et la bonne ligne est affichée à l’image dessinée suivante, en avant comme en arrière, sans rien recharger ni remettre aucune horloge à zéro. Dans un jeu à embranchements de la leçon seize, où les choix du joueur font sauter le disque sans arrêt, c’est la différence entre ce qui marche et ce qui marche presque.

Le système dessine aussi au bon endroit. Le document des sous-titres se place par-dessus l’image, au-dessus de votre overlay, en dessous de toute GUI en espace écran, et il suit l’image partout où les réglages du joueur la mettent — une image réduite, une image décalée, une borne tournée, un trou dans un bezel. Il ne prend aucune entrée de la souris, donc un tir de pistolet optique le traverse sans s’arrêter. Réussir tout ça vous-même, c’est une semaine que vous n’aviez pas prévue.

Écrivez le fichier

Les sous-titres vont dans un fichier SubRip, qui se termine par .srt et qui est du texte brut que vous pouvez taper dans n’importe quel éditeur. C’est l’un des formats les plus simples qui existent. Créez un fichier appelé subtitles.srt à côté de votre script :

1
00:00:01,000 --> 00:00:04,000
They told us the cave was empty.

2
00:00:04,200 --> 00:00:08,000
They were wrong about
a great many things.

3
00:00:08,500 --> 00:00:13,000
Keep your light on the floor.

Un sous-titre, c’est quatre choses. Un numéro seul sur sa ligne. Une ligne avec deux horodatages et, entre eux, une flèche faite de deux traits d’union et d’un signe supérieur. Une ou plusieurs lignes de texte. Une ligne vide pour finir.

Un horodatage s’écrit HH:MM:SS,mmm — les heures, les minutes et les secondes séparées par des deux-points, puis une virgule, puis les millisecondes. La virgule n’est pas une faute de frappe, et un point ne fera pas l’affaire. 00:00:04,200, c’est quatre secondes et un cinquième après le début.

Les numéros des sous-titres sont lus puis jetés, donc ils n’ont pas besoin d’être dans l’ordre, ni même d’être justes. Numérotez-les quand même ; un jour, vous chercherez le sous-titre quarante et un.

Le sous-titre deux montre à quoi ressemble un sous-titre de deux lignes. Les lignes sont affichées comme vous les avez écrites, donc c’est vous qui décidez où une longue ligne se coupe, ce qui compte plus que vous ne le croiriez et qui est expliqué plus bas.

L’analyseur est volontairement tolérant envers ce qui tourne mal dans un fichier modifié à la main. Les fins de ligne Windows se chargent telles quelles, et les espaces au début et à la fin de chaque ligne sont retirés. Un sous-titre dont les horodatages ne s’analysent pas est sauté et le reste du fichier continue de se charger, ce qui est sympathique jusqu’au moment où vous vous demandez où est passée la ligne douze. Quelques choses ne sont pas prises en charge : les balises <i> et <b> que certains outils écrivent sont affichées comme du texte au lieu d’être appliquées, et les coordonnées de positionnement que certains outils ajoutent à la ligne de temps sont ignorées. La section Sous-titres de la Référence en donne la liste complète.

Chargez-les et allumez-les

Trois appels, et l’ordre compte.

if srtLoad(DIR .. "subtitles.srt") then
    srtPosition(80)
    srtEnable(true)
end

srtLoad lit le fichier et répond true ou false. Elle répond false, sans rien avoir chargé, dans trois cas : le fichier ne peut pas être lu, rien dedans ne s’analyse, ou il n’y a pas de disque. Dans les trois cas, elle affiche à la console un avertissement qui nomme le fichier. C’est une bonne conception et vous devriez vous en servir : un fichier de sous-titres manquant ne vaut pas qu’on tue un jeu pour ça, mais livrer sans s’en apercevoir un jeu sans sous-titres vaut qu’on le remarque.

Le cas « pas de disque » est celui qui vous attrapera. Les horodatages doivent devenir des numéros d’image à la fréquence d’images du disque, et tant qu’aucun disque n’est ouvert, il n’y a pas de fréquence d’images à utiliser. Chargez donc les sous-titres après le disque, ce qui, dans un script ordinaire, veut dire depuis le corps du script, là où s’exécute tout ce que vous avez écrit au niveau principal. Il s’ensuit qu’un .srt découpé pour une vidéo à une certaine fréquence d’images tombe au mauvais endroit sur une vidéo à une autre. Synchronisez votre fichier sur la vidéo que vous allez vraiment livrer.

srtEnable(true) allume les sous-titres chargés. Un script démarre toujours avec les sous-titres éteints, donc un jeu qui les charge doit les allumer. Les éteindre de nouveau retire ce qui est affiché, et les rallumer affiche ce qui couvre l’image sur laquelle se trouve le disque à cet instant — rien à chercher, aucun état à garder.

Laisser les sous-titres allumés est un réglage, pas une décision que vous prenez à la place du joueur. Mettez-le dans votre page d’options de la leçon vingt, enregistrez-le avec saveSet de la leçon douze, et passez à srtEnable ce que le joueur a choisi en dernier.

Où ils se placent

srtPosition(70)

srtPosition est un pourcentage de la hauteur de l’image, compté depuis le haut, de 1 à 95, et la valeur par défaut est 80. Il s’applique au sous-titre affiché à cet instant et à tous ceux qui suivent. Un nombre hors de cette plage est ignoré au lieu d’être ramené dans les limites, ce qui veut dire qu’une faute de frappe laisse la position exactement où elle était, sans rien dire, alors vérifiez les vôtres.

Quatre-vingts pour cent, c’est bas, et c’est bas exprès : le bas de l’image est en général la partie la moins intéressante du plan. Remontez-les quand le bas n’est pas ennuyeux — quand votre jeu dessine les scores le long du bord inférieur, ou quand le réticule du pistolet optique du joueur vit par là.

En retirer un

srtClear()

srtClear retire immédiatement ce qui est à l’écran, et laisse tranquilles les sous-titres chargés et l’état allumé. La ligne qui était affichée reste retirée jusqu’à ce que le disque atteigne le sous-titre suivant. Servez-vous-en quand une scène se termine plus tôt et que vous ne voulez pas que la dernière réplique traîne sur le plan suivant.

Un autre appel partage la mécanique des sous-titres, et vous vous en êtes peut-être déjà servi :

overlayBanner("Extra life!", 20)

overlayBanner affiche un court message par-dessus l’image pendant une trentaine d’images dessinées, puis le retire. Il est dessiné par le même document que les sous-titres, donc un bandeau ressemble à un sous-titre, et tant qu’il est affiché il prend la place de tout sous-titre, qui revient quand le bandeau expire. Son propre argument de hauteur est distinct de srtPosition et vaut 47 par défaut, le milieu de l’image. Les messages de plus de soixante caractères sont purement et simplement ignorés, donc un message long a l’air de ne pas marcher du tout.

Des sous-titres déjà dans la vidéo

Certains fichiers vidéo transportent leurs propres pistes de sous-titres. Si c’est le cas du vôtre, vous n’avez pas du tout besoin d’un .srt :

if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

srtLoadTrack prend un numéro de piste de 0 à discGetSubtitleTracks() - 1 et, une fois le chargement fait, tout est identique. discGetSubtitleLanguage(track) vous dit dans quelle langue une piste est étiquetée, sous la forme d’un code de trois lettres comme eng ou fra, pour qu’un jeu puisse proposer au joueur ce que sa vidéo se trouve transporter.

Deux mises en garde. Lire une piste parcourt une fois tout le fichier vidéo, sans décoder aucune image, donc un disque de la longueur d’un long métrage prend un moment : faites-le pendant que quelque chose d’autre est à l’écran, pas entre deux images de jeu. Et les pistes de sous-titres qui contiennent des images des mots au lieu des mots — le genre qu’utilisent les DVD et les Blu-ray — ne peuvent pas être lues. Elles sont comptées, pour que la numérotation corresponde à ce que montrent les autres lecteurs, mais srtLoadTrack répond false pour elles.

Le script complet

Celui-ci a besoin d’une vidéo. Vous en avez une : Singe/menuBackground.mkv, que le moteur a extraite dans votre dossier de travail la première fois que vous avez lancé quoi que ce soit. Dites à Singe de s’en servir comme disque avec --framefile, qui allume aussi le disque :

Singe --framefile=Singe/menuBackground.mkv subtitles
dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local HUD_X     = 16
local STEP      = 5
local TOP_LIMIT = 10
local LOW_LIMIT = 95

local hudFont = fontLoad("Singe/FreeSansBold.ttf", 18)
local loaded  = false
local showing = false
local height  = 80


if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

if loaded then
    srtPosition(height)
    showing = true
    srtEnable(true)
end

discPlay()


function onInputPressed(what)
    if not loaded then
        return
    end
    if what == SWITCH_BUTTON1 then
        showing = not showing
        srtEnable(showing)
        if showing then
            overlayBanner("Subtitles on", 20)
        else
            overlayBanner("Subtitles off", 20)
        end
    elseif what == SWITCH_UP then
        height = math.max(TOP_LIMIT, height - STEP)
        srtPosition(height)
    elseif what == SWITCH_DOWN then
        height = math.min(LOW_LIMIT, height + STEP)
        srtPosition(height)
    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()
    end
end


function onOverlayUpdate()
    overlayClear()
    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    if loaded then
        if showing then
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles ON at " .. height .. "%")
        else
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles OFF")
        end
        fontPrint(HUD_X, 40, "Fire toggles them, up and down move them, left rewinds")
    else
        fontPrint(HUD_X, 16, "No subtitles loaded.")
        fontPrint(HUD_X, 40, "Run with --framefile and check subtitles.srt is beside the script.")
    end
    return OVERLAY_UPDATED
end


function onShutdown()
    fontUnload(hudFont)
end

Appuyez sur tir pour les allumer ou les éteindre, sur haut et bas pour déplacer les lignes, et sur gauche pour revenir au début. C’est le retour au début qu’il faut regarder : le disque saute à l’image zéro et le bon sous-titre est affiché dès l’image suivante, sans que vous ayez rien fait pour ça.

Ce qui vient de se passer

if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

Prenez les sous-titres de la vidéo elle-même quand elle en a, rabattez-vous sur le fichier à côté du script quand elle n’en a pas, et finissez en sachant lequel des deux a marché — si l’un des deux a marché. Les deux appels répondent par un booléen, donc le repli tient en deux instructions if, sans cas particulier. menuBackground.mkv ne transporte aucune piste de sous-titres, donc ce que vous obtiendrez réellement, c’est le fichier que vous avez tapé.

function onInputPressed(what)
    if not loaded then
        return
    end

Un return sans rien après quitte la fonction immédiatement. Sans sous-titres chargés, aucune de ces touches n’a rien à faire, et partir tôt est plus clair que d’envelopper tout le corps dans un if. Appeler srtEnable sans rien de chargé est sans danger, mais écrire du code qui n’a de sens que lorsqu’il ne fait rien est une habitude qu’il vaut mieux ne pas prendre.

    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()

Le srtClear n’est pas nécessaire. Le moteur affichera de toute façon le bon sous-titre pour l’image zéro à l’image dessinée suivante. Il est là pour que vous puissiez le supprimer et regarder ce qui se passe : l’ancienne ligne reste affichée une fraction de seconde pendant que le disque arrive là où il va. Sur un saut lent, ce flash de la mauvaise ligne se voit, et effacer d’abord est la façon de l’éviter.

Rendre le texte lisible sur une image qui bouge

Le système met les mots à l’écran. Que quelqu’un arrive à les lire, c’est votre problème, et ça vaut pour chaque ligne de texte que vous dessinez par-dessus de la vidéo — une consigne de la leçon dix-huit, un score, un choix d’embranchement — pas seulement pour les sous-titres.

Restez loin des bords. Les téléviseurs coupent les bords des images depuis soixante-dix ans, et les moniteurs d’arcade sont pires, pas meilleurs. Partez du principe que les cinq pour cent extérieurs de l’image, de chaque côté, peuvent ne pas exister du tout sur l’écran de quelqu’un. Gardez à l’intérieur tout ce qu’un joueur doit lire. C’est pour ça que srtPosition s’arrête à 95 et pas à 100.

Le contraste n’est pas un choix de couleur, c’est une garantie. Du texte blanc sur une image, c’est du texte blanc sur ce que l’image est en train de montrer, et dans deux secondes ce sera peut-être un champ de neige. Le style de sous-titres fourni règle ça comme le font les sous-titres de cinéma : un panneau sombre qui épouse le texte, plus une ombre d’un pixel. Si vous dessinez votre propre texte sur de la vidéo, faites l’un ou l’autre — un overlayBox derrière, ou une copie sombre du texte décalée d’un pixel. Ne comptez pas sur l’image.

Coupez vos lignes vous-même. Deux lignes courtes se lisent plus vite qu’une longue, et une ligne qui passe à la ligne là où vous ne l’avez pas choisi se coupe en général au mauvais endroit. Visez une quarantaine de caractères par ligne et pas plus de deux lignes à la fois. Coupez à une pause naturelle : They were wrong about / a great many things se lit bien ; They were wrong / about a great many things trébuche.

Laissez-les assez longtemps. Une vitesse de lecture confortable tourne autour de quinze caractères par seconde, donc une ligne de quarante caractères demande environ trois secondes. Regardez le sous-titre un dans le fichier ci-dessus : trente-deux caractères, trois secondes. Si une réplique est courte et rapide, garder le sous-titre affiché un temps de plus après la fin de la parole est plus gentil que de le faire disparaître d’un coup.

Mettez-les là où l’action n’est pas. Si ce qui compte dans le plan se trouve en bas de l’image, remontez les sous-titres pour cette scène avec srtPosition. Vous pouvez l’appeler aussi souvent que vous voulez, et le joueur ne remarquera jamais que vous l’avez fait.

Leur mise en forme

Les lignes sont dessinées par un document, du même genre que ceux de la leçon vingt, et deux fichiers de votre dossier Singe décident de leur apparence :

  • Singe/subtitle.rml — le document. Il contient un seul élément, #slot, dans lequel le moteur écrit le sous-titre ou le bandeau du moment.

  • Singe/subtitle.rcss — le style. .cue est le bloc qui porte la hauteur demandée par srtPosition, et .cue .text est la barre de texte à l’intérieur : blanc, gras, sur un panneau sombre arrondi qui épouse le texte, avec une ombre.

Ouvrez subtitle.rcss et lisez-le — il fait une quarantaine de lignes. Puis laissez-le tranquille, parce qu’une modification faite là ne dure pas. À chaque démarrage, Singe remet sa propre copie de tout ce qui a été modifié dans le dossier Singe, et le dit :

>>> Updated File:  Singe/subtitle.rcss

Ce dossier appartient au moteur. Votre jeu apporte plutôt sa propre copie. Copiez les deux fichiers depuis Singe dans votre dossier subtitles, à côté du script. Puis ouvrez votre copie de subtitle.rml et changez la seule ligne de son <head> qui relie le style, pour qu’elle se lise :

	<link type="text/rcss" href="subtitle.rcss"/>

Un nom à l’intérieur d’un document part du dossier du document lui-même, sauf un nom qui commence par Singe/, qui désigne toujours le dossier du moteur. Le lien tel que vous l’avez copié, Singe/subtitle.rcss, va toujours chercher le style du moteur. Le nouveau va chercher le vôtre.

Quand Singe trouve un subtitle.rml à côté de votre script, il dessine les sous-titres avec celui-ci au lieu du sien. Ajoutez -p à la commande et Singe décrit ce qu’il fait au fur et à mesure, une ligne à la fois :

Singe -p --framefile=Singe/menuBackground.mkv subtitles

Quand le premier sous-titre apparaît, l’une de ces lignes est celle-ci :

Using the game's own subtitles/subtitle.rml

Changez maintenant la font-size, la color, la background-color, le border-radius ou le font-effect dans votre subtitle.rcss, enregistrez, et relancez. Le moteur ne touche jamais qu’au contenu de #slot et à la hauteur de .cue, donc tout le reste de vos deux fichiers est à vous, et rien de ce que fait Singe à son démarrage n’y touchera. Si -p dit qu’il utilise les vôtres et que l’apparence n’a pas changé, relisez le lien : une copie qui dit encore Singe/ utilise en silence le style du moteur.

Comme overlayBanner utilise le même document, changer le style des sous-titres change aussi celui de vos bandeaux, ce qui est en général ce que vous voulez et qui vaut d’être su avant que vous vous demandiez pourquoi.

Une limite : le document des sous-titres est un document, et les documents ont besoin d’un GPU. Sur une machine qui n’en a pas, srtLoad lit quand même votre fichier et répond quand même honnêtement, et rien n’est dessiné. Un avertissement le dit une fois.

Essayez

  1. Ajoutez un quatrième sous-titre à subtitles.srt, entre onze et treize secondes. Enregistrez et lancez. Puis mettez-le dans le désordre, en tant que sous-titre 99, en premier dans le fichier, et vérifiez qu’il marche toujours.

  2. Donnez à un sous-titre un mauvais horodatage — écrivez 00:00:05.500 avec un point au lieu d’une virgule — et lancez. Regardez quelle ligne disparaît, et remarquez que rien du tout n’est dit à ce sujet. Un fichier qui se charge n’est pas un fichier juste.

  3. Changez leur style. Dans votre propre subtitle.rcss — la copie qui est à côté de votre script, pas celle de Singe — changez .cue .text pour avoir du texte jaune sur un fond complètement transparent, puis ajoutez une ombre plus marquée. Ensuite, regardez-le par-dessus la vidéo et décidez honnêtement s’il est encore lisible.

  4. Cassez la synchronisation exprès. Changez chaque horodatage du fichier pour qu’il soit en retard de deux secondes, et regardez un système qui marche parfaitement livrer des sous-titres inutiles. Voilà ce que vous fait une vidéo réencodée.

  5. Mettez l’interrupteur dans un menu. Reprenez la page de pause de la leçon vingt, ajoutez une case à cocher, et branchez-la sur srtEnable. Puis enregistrez le choix avec saveSet pour qu’il soit encore allumé la fois suivante. C’est la version que vos joueurs veulent vraiment.

Cassez-le exprès

Lancez le script sans l’option --framefile :

Singe subtitles

La fenêtre s’ouvre, noire, avec votre message de repli dessus, et la console dit :

Warning:  No subtitles were loaded from subtitles/subtitles.srt.

Pas de plantage et pas de boîte de dialogue d’erreur, parce que srtLoad a répondu false et que votre script s’en est occupé.

C’est l’échec le plus précieux de cette leçon, parce que c’est celui qui arrive sans que personne ne le remarque. Il n’y a pas de disque, donc pas de fréquence d’images, donc rien en quoi transformer les horodatages, donc rien ne se charge. Si vous aviez écrit srtLoad(…​) tout seul en jetant la réponse, votre jeu aurait tourné parfaitement sans montrer aucun sous-titre, et vous l’auriez découvert quand quelqu’un vous l’aurait dit.

Servez-vous de la réponse. À chaque fois.

Ce que vous avez appris

  • Un jeu avec des paroles et sans sous-titres est un jeu auquel certaines personnes ne peuvent pas jouer du tout.

  • Mettre les sous-titres au fur et à mesure, c’est un après-midi ; les ajouter après coup, non.

  • Les sous-titres sont un fichier .srt : un numéro, deux horodatages avec -→ entre eux, le texte, et une ligne vide.

  • srtLoad transforme les horodatages en numéros d’image du disque au chargement, et c’est pour ça qu’un sous-titre survit à n’importe quel saut.

  • Il faut charger les sous-titres après le disque, et l’appel répond false quand il ne peut pas charger, y compris quand il n’y a pas de disque. Vérifiez la réponse.

  • srtEnable les allume, et un script démarre toujours avec les sous-titres éteints.

  • srtPosition les place à un pourcentage de la hauteur de l’image, de 1 à 95.

  • srtClear retire ce qui est affiché, et overlayBanner partage le même document.

  • srtLoadTrack lit les sous-titres dans le fichier vidéo lui-même quand il en contient.

  • Singe réécrit son dossier Singe à chaque démarrage, donc pour changer le style des sous-titres, vous copiez subtitle.rml et subtitle.rcss à côté de votre script, vous faites pointer le lien de la copie vers votre propre feuille, et c’est celle-ci que vous modifiez.

  • Du texte sur une image qui bouge a besoin d’une marge de sécurité, de son propre contraste, de lignes coupées par vous, et de temps pour être lu.

La prochaine fois

C’en est fini du texte. La quatrième partie continue sans que vous ayez à la lire dans l’ordre, et la prochaine leçon ouvre une porte restée fermée pendant vingt leçons : overlayGetWidth et overlayGetHeight sont deux nombres, et une scène en a trois. La leçon vingt-deux parle du troisième.

Leçon 22 : Passer à la 3D

La leçon terminée

Tout ce que vous avez dessiné jusqu’ici était plat. Les sprites, le texte, les boîtes et les lignes vivent tous sur l’overlay, qui est une plaque de verre à l’avant de la fenêtre, avec les mêmes coordonnées qu’à la leçon un. Cette leçon met un monde derrière ce verre : un endroit qui a de la profondeur, où une chose peut être plus près ou plus loin, et où une caméra décide de ce que vous en voyez.

À la fin, vous aurez une boîte qui flotte dans l’espace et que vous pouvez tourner avec les touches fléchées, avec les nombres de ses angles affichés dans le coin par le même overlayPrint que celui de votre tout premier jour. Ce dernier point compte plus qu’il n’en a l’air, et une section lui est consacrée.

Une scène, une boîte et une lumière

Créez un dossier, mettez-y un fichier appelé spin.singe, et tapez ceci.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)


function onOverlayUpdate()
    nodeRotate(box, 0, 0.5, 0)
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R spin. Une boîte orange tourne lentement sur un fond bleu foncé, éclairée d’en haut et de la droite, avec une face claire et les autres qui s’enfoncent dans l’ombre.

Il n’y a pas de caméra dans ce script. Singe vous a placé en (0, 0, 5), à regarder le milieu du monde, parce qu’une scène sans caméra doit bien être vue de quelque part. Vous allez remplacer ça par votre propre caméra dans un instant.

Si la fenêtre reste noire, lisez la console. Sur une machine dont la carte graphique ne sait pas dessiner une scène 3D, sceneEnable arrête le jeu avec un message qui le dit, et il n’y a rien d’autre à faire que de suivre la leçon ailleurs. Les jeux 2D continuent de marcher sur une telle machine ; la 3D, non.

Ce qui vient de se passer

Les trois appels du haut mettent en place le monde dans son ensemble.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

sceneEnable(true) allume la couche 3D. C’est le seul appel que fait chaque jeu en 3D, et tant que vous ne l’avez pas fait, rien de ce que vous construisez dans la scène n’est dessiné.

sceneSetBackground est la couleur avec laquelle la scène est effacée à chaque image, rouge, vert et bleu de 0 à 255, comme les couleurs marchent depuis la leçon neuf. Il y a un quatrième nombre que vous pouvez lui donner pour la transparence, et c’est ainsi qu’un jeu qui lit de la vidéo met un objet 3D devant le film. Laissez-le de côté et le fond est opaque.

sceneSetAmbient est un peu de lumière qui vient de toutes les directions à la fois. Son travail est d’empêcher les côtés qu’aucune lampe n’atteint d’être complètement noirs. Baissez-la plus tard à 0, 0, 0 et voyez à quel point l’image devient dure.

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

Un matériau, c’est l’aspect d’une surface : sa couleur, à quel point elle brille, si elle porte une image. materialNew en crée un et renvoie un nombre qui le représente, le même genre de handle que celui que spriteLoad vous a donné à la leçon neuf. Gardez-le dans une variable, parce que tous les appels suivants en ont besoin.

materialSetRoughness va de 0, un miroir avec un petit reflet dur, à 1, une surface mate comme de la craie sans aucun reflet. 0.6, c’est de la peinture sur du bois. Il existe une douzaine d’autres appels materialSet, et la prochaine leçon en utilise quelques-uns ; la section Matériau de la référence les liste tous.

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

C’est le plus important. Un nœud est un endroit dans le monde. Il a une position, une rotation et une échelle, et à lui seul il ne dessine rien du tout : c’est un point auquel on peut attacher des choses. Tout dans une scène 3D est un nœud, y compris les lumières et la caméra.

nodeNew en crée un vide au milieu du monde. nodeSetMesh y accroche deux choses : un maillage, qui est la forme, et le matériau, qui est l’aspect de cette forme. meshBox(2, 2, 2) construit une boîte de deux unités de large, deux de haut et deux de profondeur, et renvoie un handle vers elle, comme materialNew.

Les maillages et les matériaux gagnent à être partagés. Un seul handle de meshBox peut servir à cent nœuds, et c’est comme ça qu’on dessine cent caisses à peu de frais. Fabriquer cent boîtes séparées qui se trouvent avoir la même taille, c’est la façon débutante de rendre une scène lente.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)

lightNew crée aussi un nœud — un nœud qui porte une lumière — et renvoie son handle de nœud, si bien que vous le placez et l’orientez avec les mêmes appels que pour tout le reste. LIGHT_DIRECTIONAL est un soleil : il est si loin que seule compte la direction dans laquelle il brille, et c’est pour ça que la position ne compte ici que parce que nodeLookAt s’en sert pour calculer la direction.

Retirez ces trois lignes et relancez. La boîte devient presque noire, parce que la seule lumière qui reste est la faible lumière ambiante. La lumière, c’est toute la leçon vingt-trois, et voici un premier avant-goût de la déception la plus courante en 3D : le modèle s’est bien chargé, et la scène est noire parce que rien ne l’éclaire.

    nodeRotate(box, 0, 0.5, 0)

nodeRotate tourne un nœud d’un certain nombre de degrés autour de chacun de ses trois axes à lui, en plus de la rotation qu’il avait déjà. Un demi-degré par image, à une soixantaine d’images par seconde, ça fait un tour toutes les douze secondes. C’est le même truc qu’à la leçon deux : un petit changement, appliqué à chaque image, se voit comme un mouvement.

Quel axe va où

Trois nombres décrivent un endroit dans la scène, et vous devez savoir ce que chacun veut dire avant de pouvoir mettre quoi que ce soit où que ce soit.

  • X va vers la droite. Un X plus grand est plus à droite.

  • Y va vers le haut. Un Y plus grand est plus haut. Le sol d’une scène est en général à y = 0.

  • Z vient vers vous, en sortant de l’écran. Un Z plus grand est plus près de la caméra par défaut, et le Z négatif est la direction dans laquelle regarde la caméra.

Ce dernier point piège tout le monde. Ce que vous voulez devant la caméra va en Z négatif. Ce n’est pas une bizarrerie de Singe : glTF et Blender utilisent la même disposition, donc un modèle exporté depuis Blender arrive tourné dans le sens qu’attend Singe.

Ne me croyez pas sur parole. Ajoutez cette ligne après la ligne nodeSetMesh, enregistrez, et regardez :

nodeSetPosition(box, 3, 1, 0)

La boîte saute vers la droite et vers le haut. nodeSetPosition place un nœud à un endroit exact, et remplace la position qu’avait le nœud. Il existe un nodeMove(node, dx, dy, dz) qui va avec et qui déplace plutôt un nœud d’une certaine quantité, le long de ses propres axes, si bien que nodeMove(ship, 0, 0, -0.1) fait avancer un vaisseau dans la direction où il se trouve pointé, quelle qu’elle soit.

Essayez ensuite nodeSetPosition(box, 0, 0, -20). La boîte rapetisse au loin : c’est le Z négatif qui fait son travail. Puis essayez (0, 0, 20) : la boîte disparaît, parce que vous l’avez mise derrière la caméra.

Deux appels de plus complètent la série.

nodeSetRotation(box, 0, 45, 0)
nodeSetScale(box, 0.5)

nodeSetRotation règle directement la rotation en degrés, là où nodeRotate y ajoute. Les trois nombres sont autour de X, autour de Y et autour de Z : tourner autour de Y, c’est ce que fait une personne debout sur le sol quand elle se tourne pour regarder ailleurs, et c’est la rotation dont vous vous servirez le plus. nodeSetScale rend le nœud plus grand ou plus petit, soit avec un seul nombre pour les trois axes, soit avec trois, un pour chacun.

Retirez ces deux expériences avant de continuer. La suite de la leçon part du script tel que vous l’avez tapé au début.

Votre propre caméra

La vue par défaut est une politesse, pas une fonctionnalité. Mettez une caméra.

local camera = nodeNew()
nodeSetPosition(camera, 0, 2, 7)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(60, 0.1, 100)

Mettez ça sous la lumière, avant votre onOverlayUpdate, et lancez. Vous regardez maintenant la boîte légèrement de haut, depuis deux unités plus haut et sept unités en arrière.

Une caméra est un nœud comme les autres. cameraSet indique au moteur depuis quel nœud regarder, et la scène est dessinée depuis la position de ce nœud, en regardant le long de son propre Z négatif. Orienter une caméra à la main avec nodeSetRotation serait une torture, alors nodeLookAt le fait pour vous : donnez-lui un point du monde et elle tourne le nœud pour lui faire face.

cameraSetPerspective, c’est l’objectif. Le premier nombre est le champ de vision en degrés, de haut en bas : la quantité de monde qui est tassée dans la hauteur de la fenêtre. Un petit nombre comme 35 donne un téléobjectif qui aplatit tout ; un grand comme 90 donne un grand-angle qui fait paraître la pièce immense et bomber les coins. 60 est une valeur par défaut confortable. Les deux autres nombres sont la distance la plus proche et la plus lointaine qui sont dessinées, et ce qui se trouve hors de cette plage n’est pas dessiné du tout.

Comme la caméra est un nœud ordinaire, tout ce que vous avez appris sur les nœuds marche avec elle. Plus tard, vous accrocherez une caméra sous une voiture qui roule et vous aurez une caméra de poursuite pour rien.

La tourner avec les touches fléchées

Lire le système de coordonnées sur une page est une mauvaise façon de l’apprendre. Y déplacer quelque chose en est une bonne. Remplacez votre onOverlayUpdate par ceci, et ajoutez les deux nouveaux callbacks et les quatre variables au-dessus.

local turnLeft  = false
local turnRight = false
local tiltUp    = false
local tiltDown  = false

Celles-ci vont tout en haut du fichier, au-dessus de tout le reste.

function onInputPressed(what)
    if what == SWITCH_LEFT then
        turnLeft = true
    elseif what == SWITCH_RIGHT then
        turnRight = true
    elseif what == SWITCH_UP then
        tiltUp = true
    elseif what == SWITCH_DOWN then
        tiltDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        turnLeft = false
    elseif what == SWITCH_RIGHT then
        turnRight = false
    elseif what == SWITCH_UP then
        tiltUp = false
    elseif what == SWITCH_DOWN then
        tiltDown = false
    end
end


function onOverlayUpdate()
    if turnLeft then
        nodeRotate(box, 0, -1.5, 0)
    end
    if turnRight then
        nodeRotate(box, 0, 1.5, 0)
    end
    if tiltUp then
        nodeRotate(box, -1.5, 0, 0)
    end
    if tiltDown then
        nodeRotate(box, 1.5, 0, 0)
    end

    return OVERLAY_UPDATED
end

onInputPressed et onInputReleased sont des callbacks, comme onOverlayUpdate : vous les écrivez, et Singe les appelle quand une commande s’enfonce ou remonte. Un appui arrive une fois, pas en boucle tant que la touche est tenue, et c’est pour ça que chacun règle une variable et que le callback de dessin fait le travail. Ce schéma — l’appui lève un drapeau, l’image lit le drapeau — est la façon d’obtenir « tant que la touche est tenue » d’un moteur qui ne vous parle que des changements.

Les noms en SWITCH_ viennent du moteur lui-même, donc il n’y a rien à charger pour s’en servir. Ce ne sont pas non plus des touches. Ils sont ce qu’une commande veut dire, et controls.cfg décide quelle touche, quel bouton ou quelle direction de stick produit chacun d’eux. Aujourd’hui, vos touches fléchées envoient SWITCH_LEFT et compagnie ; le stick d’une manette envoie la même chose, et votre script ne voit jamais la différence.

Les signes sont choisis pour que chaque flèche déplace la face que vous regardez dans la direction où vous avez appuyé. Tourner autour de Y d’un angle positif fait pivoter cette face proche vers la droite, donc la flèche gauche demande un angle négatif. Si vous trouvez ça à l’envers, inversez les signes ; ce sont vos commandes, pas celles du moteur.

L’overlay est toujours au-dessus

Ajoutez ces lignes à onOverlayUpdate, au-dessus du return.

    local pitch, yaw = nodeGetRotation(box)

    overlayClear()
    overlayPrint(2, 2, "Arrow keys turn the box.")
    overlayPrint(2, 4, "yaw " .. math.floor(yaw) .. "  pitch " .. math.floor(pitch))

Rien là-dedans n’est nouveau, sauf ce par-dessus quoi c’est affiché. overlayPrint est l’appel de la leçon un, qui compte en cellules de caractère et n’a besoin d’aucune police chargée, et il dessine par-dessus une scène 3D sans qu’on lui en ait rien dit.

C’est ainsi que les choses sont disposées, et ça mérite d’être dit clairement : Singe dessine d’abord la vidéo, puis la scène 3D par-dessus, puis l’overlay par-dessus le tout. Votre score, vos vies, votre minuterie, votre réticule et vos sous-titres relèvent tous de l’overlay, exactement comme dans la deuxième partie. Un jeu en 3D garde son score dans le coin avec les mêmes cinq lignes qu’un jeu en 2D.

nodeGetRotation renvoie trois nombres, les angles autour de X, de Y et de Z, et cette ligne garde les deux premiers dans pitch et yaw. Ce sont leurs noms habituels en anglais : pitch, le tangage, c’est le nez qui monte et qui descend ; yaw, le lacet, c’est tourner à gauche et à droite. math.floor jette la partie décimale pour que les nombres arrêtent de clignoter.

Regardez le yaw pendant que vous tenez la flèche gauche. Il descend au-delà de -180 et revient par 180, parce que les angles sont donnés comme le plus petit tour qui mène là et non comme un total cumulé. Si votre jeu a besoin de savoir combien de fois le joueur a tourné sur lui-même, comptez-le vous-même.

Essayez

  1. Déplacez la caméra. Changez nodeSetPosition(camera, 0, 2, 7) en (0, 8, 7), puis en (7, 2, 7), puis en (0, 0.2, 7). À chaque fois, le nodeLookAt garde la boîte au centre, si bien que vous obtenez un autre angle sur la même scène pour un seul nombre.

  2. Changez l’objectif. Essayez cameraSetPerspective(30, 0.1, 100), puis (90, 0.1, 100), sans bouger la caméra. Un jeu paraît rapide avec un champ de vision large et majestueux avec un champ étroit, et c’est le réglage d’ambiance le moins cher qui soit.

  3. Ajoutez une deuxième boîte. Copiez les deux lignes qui ont créé la boîte, renommez la variable en mark, et donnez-lui nodeSetPosition(mark, 3, 0, 0) et nodeSetScale(mark, 0.3). Vous avez maintenant un repère pour juger la première boîte. Mettez-la tour à tour en (0, 3, 0) et en (0, 0, -3) et dites à voix haute quel axe est lequel.

  4. Partagez le maillage. Au lieu d’appeler meshBox deux fois, gardez le premier dans une variable et donnez le même handle aux deux nœuds. Rien n’a l’air différent. C’est tout l’intérêt : une forme, deux endroits.

  5. Accrochez la caméra à la boîte. Gardez la deuxième boîte de l’étape précédente, sinon il ne restera rien par rapport à quoi bouger. Puis cherchez nodeSetParent dans la référence et accrochez la caméra sous la première boîte. Tenez une touche fléchée : la caméra suit la rotation de la boîte, donc la boîte reste immobile et le reste de la scène défile. Vous êtes à une ligne d’une vue à la première personne, et c’est aussi comme ça que vous découvrez qu’une caméra de poursuite demande un parent plutôt que de l’arithmétique.

Cassez-le exprès

Faites une faute de frappe dans le nom du matériau. Changez la ligne nodeSetMesh pour qu’elle utilise pain au lieu de paint :

nodeSetMesh(box, meshBox(2, 2, 2), pain)

Singe s’arrête avant que le jeu démarre et affiche quelque chose comme :

15:nodeSetMesh:  Argument 3 must be a number.

C’est une erreur d’une autre forme que celle de la leçon un, et elle vient du moteur plutôt que de Lua. Le nombre au début, c’est la ligne. Le nom qui suit, c’est l’appel qui s’est plaint. La plainte elle-même, c’est que la troisième chose que vous lui avez passée n’était pas un nombre.

La raison mérite d’être suivie, parce qu’elle explique toute une famille d’erreurs. pain est une variable à laquelle on n’a jamais donné de valeur, et en Lua une variable vide vaut nil — la valeur qui veut dire « rien ici ». Passer nil à un appel qui attend un handle de matériau donne exactement ça. Quand vous voyez « must be a number » venant d’un appel du moteur, cherchez un nom de variable mal orthographié sur cette ligne, ou un handle que vous avez oublié de garder.

Ce que vous avez appris

  • sceneEnable(true) allume la couche 3D, et rien n’est dessiné en 3D tant que vous ne l’avez pas appelé.

  • Un nœud est un endroit dans le monde, avec une position, une rotation et une échelle. Les maillages, les lumières et les caméras s’accrochent tous à des nœuds.

  • Un maillage est la forme et un matériau est l’aspect, et chacun peut être partagé par autant de nœuds que vous voulez.

  • X va à droite, Y va en haut, et le Z négatif est la direction où regarde la caméra.

  • nodeSetPosition et nodeSetRotation règlent une valeur directement ; nodeMove et nodeRotate la changent d’une certaine quantité.

  • N’importe quel nœud peut être la caméra. nodeLookAt l’oriente et cameraSet la choisit.

  • Le champ de vision de cameraSetPerspective change la sensation que donne la scène sans rien déplacer.

  • Une scène sans lumière est noire, et c’est la première chose à vérifier quand rien n’apparaît.

  • L’overlay est toujours là, toujours au-dessus, et c’est toujours là que va votre score.

La prochaine fois

Une boîte fait un piètre dragon. La prochaine leçon charge un vrai modèle — un modèle que le moteur a déjà extrait dans votre dossier de travail, donc il n’y a rien à télécharger ni rien à dessiner — le pose sur le sol, et l’éclaire correctement. C’est la leçon vingt-trois.

Leçon 23 : Modèles et lumière

La leçon terminée

Les boîtes et les sphères vous mèneront loin, mais tôt ou tard le jeu voudra un dragon. Un modèle est une forme que quelqu’un d’autre a construite dans un logiciel de modélisation : des centaines de triangles, ses propres couleurs et surfaces, parfois un squelette et des mouvements qui vont avec, le tout dans un seul fichier. En charger un, c’est deux lignes. Lui donner l’air de quelque chose, c’est de la lumière, et la lumière occupe l’essentiel de cette leçon.

Vous n’avez besoin d’aucun graphisme et d’aucun téléchargement. La toute première fois que vous avez lancé Singe, il a extrait un dossier appelé Singe dans votre dossier de travail, et deux modèles s’y trouvent : DragonModel.glb, le dragon de l’écran titre du moteur lui-même, et SingeText.glb, le lettrage en dessous. Cette leçon se sert du dragon.

La scène autour

Un modèle a besoin d’un endroit où se tenir. Créez un dossier, créez-y dragon.singe, et commencez par un sol et une caméra. Si vous avez fait la leçon vingt-deux, rien de tout ça n’est nouveau ; sinon, c’est une scène allumée, une dalle plate où se tenir, et un point d’où regarder.

sceneEnable(true)
sceneSetBackground(10, 12, 20)
sceneSetAmbient(28, 30, 38)

local stone = materialNew()
materialSetColor(stone, 105, 105, 115)
materialSetRoughness(stone, 0.9)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(24, 0.4, 24), stone)
nodeSetPosition(floor, 0, -0.2, 0)

local camera = nodeNew()
nodeSetPosition(camera, 0, 2.6, 9)
nodeLookAt(camera, 0, 1.7, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 200)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R dragon. Une dalle grise, vue légèrement de haut, sur un fond bleu foncé. La dalle fait vingt-quatre unités de côté et un peu moins d’une demi-unité d’épaisseur, et la poser à y = -0.2 met sa surface du dessus exactement à y = 0, ce qui rend facile de raisonner sur tout ce que vous placerez ensuite : le sol, c’est zéro.

Charger le dragon

Deux lignes.

local dragonModel = modelLoad("Singe/DragonModel.glb")
local dragon      = modelInstance(dragonModel)

Mettez-les après le sol et enregistrez. Un dragon apparaît, et il est bien trop grand pour l’image — vous regardez le milieu de son corps.

Ce qui vient de se passer

Les deux lignes font des travaux différents, et la différence compte.

modelLoad lit le fichier, confie les formes et leurs surfaces à la carte graphique, et garde le tout prêt. C’est l’appel lent. Faites-le une fois, quand le jeu démarre, et jamais en pleine partie.

modelInstance place une copie dans la scène et vous renvoie un nœud — un nœud ordinaire, du même genre que ce que vous donne nodeNew, que vous placez, tournez, mettez à l’échelle et supprimez avec les appels que vous connaissez déjà. Instancier, c’est l’appel bon marché. Chargez un arbre, instanciez-le quarante fois, et vous avez un bois, avec une seule copie des formes sur la carte graphique et quarante endroits où elles sont dessinées.

Ce qui vient avec le modèle, c’est tout ce que contenait le fichier : les formes, les surfaces et leurs couleurs, la façon dont les parties sont agencées, l’éventuel squelette et les éventuels mouvements. Vous ne construisez pas de matériaux pour un modèle chargé ; il a apporté les siens.

L’échelle, et le premier problème

Le dragon mesure environ sept unités et demie de haut. Votre caméra est à neuf unités en arrière. Voilà pourquoi il remplit la fenêtre.

nodeSetScale(dragon, 0.5)

Ajoutez ça sous la ligne modelInstance. Maintenant il mesure moins de quatre unités, il se tient sur le sol, et il tient dans le cadre.

Ce n’est pas un détail ; c’est le premier problème le plus courant avec un modèle, et il a deux visages. Un modèle construit en centimètres arrive cent fois trop grand et vous voyez une seule surface énorme qui remplit l’écran, ce qui se lit en général comme « ma scène est cassée » plutôt que comme « je suis dans le cou du dragon ». Un modèle construit dans une autre unité arrive si petit que c’est un point, ou qu’il est invisible sur le fond, et vous supposez que le fichier ne s’est pas chargé.

La solution est toujours la même : une échelle sur le nœud de l’instance. Pas sur les parties, pas dans le logiciel de modélisation si vous pouvez l’éviter, mais un seul nodeSetScale sur le nœud que modelInstance vous a donné, choisi en essayant un nombre et en regardant. 0.01 et 100 sont des réponses tout à fait ordinaires.

Quand vous n’arrivez pas à savoir quelle taille fait une chose, donnez-vous une règle. Mettez une boîte d’une unité à côté :

local ruler = nodeNew()
nodeSetMesh(ruler, meshBox(1, 1, 1), stone)
nodeSetPosition(ruler, 3, 0.5, 0)

Un objet de la taille d’une caisse à côté du modèle vous dit d’un coup d’œil si le modèle est un dragon ou une montagne. Retirez la règle quand vous avez fini.

Pendant que vous le placez, tournez-le vers vous :

nodeSetRotation(dragon, 0, -60, 0)

Le dragon a été modélisé tourné vers les X positifs, c’est-à-dire vers la droite, donc il commence de profil. Le tourner autour de Y le ramène vers la caméra. L'« avant » d’un modèle, c’est la direction qu’a choisie la personne qui l’a construit, et pour le savoir il faut le tourner et regarder.

La lumière

Lancez ce que vous avez maintenant. Le dragon est là, et il est morne : une forme plate et terne, sans reflets et sans ombre. C’est parce que la seule lumière de votre scène est la lumière ambiante, la faible lueur venue de partout que règle sceneSetAmbient.

C’est la déception la plus courante en 3D, et elle arrive à tout le monde : le modèle s’est chargé parfaitement et la scène est noire, ou presque, parce que rien ne l’éclaire. Avant de soupçonner le fichier, mettez une lumière.

Il y en a trois sortes, et chacune est un nœud, donc vous les placez et les orientez avec nodeSetPosition et nodeLookAt comme n’importe quoi d’autre.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -6, 9, 7)
nodeLookAt(sun, 0, 1.5, 0)
lightSetColor(sun, 255, 244, 224)
lightSetIntensity(sun, 1.8)
lightSetShadow(sun, true)

LIGHT_DIRECTIONAL est un soleil. Il est traité comme s’il était infiniment loin, donc seule compte la direction dans laquelle il brille, et tout dans la scène en reçoit la même quantité. Sa position est là pour que nodeLookAt puisse l’orienter. C’est la lumière qui donne à une scène sa forme principale, et la plupart des scènes en veulent exactement une.

lightSetIntensity, c’est la luminosité. Pour une lumière directionnelle, 1 éclaire une surface blanche qui lui fait face jusqu’au blanc, donc 1.8, c’est une journée lumineuse. lightSetColor la teinte : un blanc légèrement chaud pour le soleil, un bleu froid pour le clair de lune, et la section Lumière de la référence pour le reste.

lightSetShadow(sun, true) est ce qui fait que le dragon est posé sur le sol au lieu de flotter au-dessus. Les ombres sont éteintes par défaut parce que chaque lumière qui projette des ombres coûte une passe de plus sur toute la scène à chaque image. Allumez-les pour la seule lumière qui compte et laissez-les éteintes pour les autres ; une petite machine vous remerciera.

local torch = lightNew(LIGHT_POINT)
nodeSetPosition(torch, 3.5, 1.2, 3.0)
lightSetColor(torch, 255, 150, 70)
lightSetIntensity(torch, 14)
lightSetRange(torch, 12)

LIGHT_POINT est une ampoule. Elle se trouve à un endroit, brille dans toutes les directions, et faiblit avec la distance. C’est à cause de cet affaiblissement que le nombre est 14 et pas 1 : l’intensité d’une lumière ponctuelle est sa luminosité à l’endroit même de la lumière, et une fois qu’elle a traversé quelques unités, il n’en reste plus grand-chose. Une ampoule qui éclaire une pièce demande en général quelque chose dans les dizaines. Si une lumière ponctuelle semble ne rien faire, c’est presque toujours pour cette raison.

lightSetRange dit jusqu’où elle porte avant de s’arrêter complètement, ce qui empêche une lampe d’une pièce d’éclairer faiblement la suivante, et ça ne coûte rien à régler.

La troisième sorte est LIGHT_SPOT, un cône pointé le long du Z négatif du nœud lui-même, avec lightSetCone pour l’angle du milieu brillant et du bord adouci : une lampe torche, un phare, un projecteur. Jusqu’à huit lumières brillent à la fois, ce qui est plus qu’il n’en faut à la plupart des scènes. Si vous en voulez plus, c’est que vous en voulez moins.

Lancez-le maintenant. Un soleil presque blanc venu de la gauche, une lueur orange et chaude venue de la droite, une ombre sur la dalle, et un dragon qui a un devant et un derrière.

Les matériaux, juste ce qu’il vous faut aujourd’hui

Le dragon a apporté ses propres matériaux, et il y en a trois : un métal sombre, un métal plus pâle couleur champagne, et un verre pâle dans lequel on voit un peu en profondeur. La plupart de ses parties sont taillées dans plus d’un. Vous n’avez à toucher à rien de tout ça, et la plupart du temps, vous ne devriez pas.

Quand vous voulez vraiment changer l’aspect d’une partie d’un modèle, vous créez un matériau comme dans la leçon vingt-deux et vous le mettez sur la partie :

local red = materialNew()
materialSetColor(red, 220, 50, 40)
materialSetRoughness(red, 0.4)
nodeSetMaterial(nodeFind("crest", dragon), red)

nodeFind(name, root) cherche dans une instance de modèle une partie d’après le nom qu’elle avait dans le fichier et renvoie son nœud, ou nil quand ce nom n’existe pas. C’est comme ça qu’on atteint l’intérieur d’un modèle : une tourelle, une roue, une main où accrocher une torche, ou la crête du dragon.

La crête est d’une seule pièce et d’un seul matériau, donc son nœud porte la forme elle-même et la ligne ci-dessus la repeint. Une partie faite de plusieurs matériaux est gardée sous forme d’un nœud avec un enfant par pièce, et mettre un matériau sur le parent ne change rien de visible. Quand un nodeSetMaterial semble ne rien faire, c’est pour ça, et nodeGetChildren vous montrera ce qu’il y a en dessous.

Quatre nombres décrivent la plupart des surfaces. La couleur, avec materialSetColor. materialSetRoughness, de 0 pour un miroir à 1 pour de la craie. materialSetMetallic, qui vaut 0 pour presque tout — la peinture, le bois, le plastique, la peau — et 1 pour du vrai métal, les valeurs intermédiaires servant peu. Et materialSetEmissive, qui fait briller une surface de sa propre couleur pour les écrans, les lampes et le fer chauffé au rouge, sans rien éclairer autour.

Une chose à savoir sur le métal : une surface métallique vous montre ses reflets plutôt qu’une couleur à elle, donc dans une scène où il n’y a rien à refléter, elle paraît sombre et terne. C’est pour ça que le métal sombre du dragon a besoin du soleil pour prendre vie. La vraie solution est un ciel (sceneSetSky), qui enveloppe la scène dans un panorama qui à la fois s’affiche derrière tout et l’éclaire ; la section « L’aspect de l’image » de la référence en parle.

Les mouvements que le modèle apporte

Beaucoup de modèles transportent des animations : une marche, une course, une attente, une porte qui s’ouvre. Elles sont stockées dans le fichier, et en jouer une se fait en un seul appel sur le nœud racine de l’instance.

animationPlay(dragon, "Walk", true)

Le deuxième argument est le nom du clip tel que le fichier le stocke, ou son numéro. true veut dire le jouer en boucle pour toujours. Deux nombres facultatifs de plus règlent la vitesse et le fondu enchaîné : animationPlay(hero, "Run", true, 1.2, 0.4) joue la course un cinquième plus vite et passe en fondu vers elle en quatre dixièmes de seconde, si bien qu’une marche devient une course sans à-coup. animationStop, animationPause et animationIsPlaying font ce que dit leur nom.

Vous ne pouvez pas encore lancer cette ligne, et voici la raison honnête : le dragon de votre dossier Singe ne contient aucune animation. C’est un modèle, pas une performance d’acteur. Demander un clip qui n’existe pas arrête le jeu avec une erreur, donc ne supposez jamais — demandez :

local clips = modelGetAnimations(dragonModel)

if #clips > 0 then
    animationPlay(dragon, 1, true)
else
    debugPrint("DragonModel.glb carries no animation clips.  The wings are turned by hand.")
end

modelGetAnimations renvoie une table des noms de clips du fichier, dans l’ordre, donc clips[1] est le premier et #clips est leur nombre — les appels de table de la leçon six, sur une table que le moteur a remplie. Lancez-le et regardez la console : le message apparaît, parce que ce nombre vaut zéro.

Prenez l’habitude de cette vérification avec tout modèle que vous n’avez pas fait vous-même. Elle coûte trois lignes et elle transforme « le jeu est mort au démarrage » en une phrase dans le journal.

Bouger les parties vous-même

Un modèle sans animations n’est pas une statue. Ses parties sont des nœuds, et les nœuds tournent.

local wingLeft  = nodeFind("wingL", dragon)
local wingRight = nodeFind("wingR", dragon)
function onOverlayUpdate()
    local flap = math.sin(singeGetTicks() / 260) * 22

    nodeSetRotation(wingLeft, flap, 0, 0)
    nodeSetRotation(wingRight, -flap, 0, 0)
    nodeRotate(dragon, 0, 0.25, 0)

    overlayClear()
    overlayPrint(2, 2, "Singe/DragonModel.glb")
    overlayPrint(2, 4, "animation clips in the file: " .. #clips)
    return OVERLAY_UPDATED
end

Enregistrez. Les ailes battent, le dragon tourne lentement sur place, et l’ombre sur le sol bat avec elles.

singeGetTicks est le nombre de millisecondes depuis le démarrage du moteur, donc il grimpe régulièrement, sans fin. math.sin prend ce nombre qui grimpe et renvoie une valeur qui glisse en douceur de -1 à 1 et retour, un battement complet environ toutes les secondes et demie avec ce diviseur. Multiplier par 22 en fait un angle de vingt-deux degrés de chaque côté. Diviser par un nombre plus grand ralentit le battement ; multiplier par un nombre plus grand l’élargit. Cette seule ligne est l’animation la moins chère qui existe, et elle vaut la peine d’être gardée sous le coude.

Les ailes tournent autour de leur propre axe X, et elles tournent autour de l’épaule plutôt qu’autour du milieu de l’animal, parce que la personne qui a construit le fichier a mis le nœud de chaque partie là où se trouve l’articulation. Un modèle qui n’a pas été construit ainsi fera tourner ses parties autour du centre du modèle, et la solution est de déplacer le nœud de la partie, ce dont parle la section Nœud de la référence.

Remarquez que le dragon entier qui tourne ne gêne pas les ailes qui tournent. Les parties sont accrochées sous la racine de l’instance, donc tourner la racine emporte tout avec elle, et la rotation propre de chaque aile s’ajoute par-dessus. Cette disposition — une chose dans une chose dans une chose, chacune bougeant dans le monde de son parent — est ce à quoi sert un arbre de scène.

Vos propres modèles

Quand vous faites les vôtres, exportez depuis Blender — ou Maya, ou 3ds Max, ou n’importe quel autre logiciel moderne — en glTF 2.0 binaire, c’est-à-dire un fichier .glb. C’est le choix par défaut de Blender, et c’est le seul format de modèle que Singe lit.

La seule règle est que le fichier doit se suffire à lui-même : les formes, les images posées dessus et les mouvements, tous à l’intérieur de l’unique .glb. Un fichier qui renvoie à un .bin ou à un .png posé à côté de lui est refusé, avec un message qui nomme ce qu’il voulait. L’exportateur de Blender fait ce qu’il faut avec ses réglages par défaut.

Tout ce que vous pouvez construire ne survit pas au voyage. La section « Modèles et animation » de la Référence, dans le chapitre « Scènes 3D », en donne la liste : ce qui est lu, ce qui est ignoré sans bruit, et les limites (un squelette peut avoir jusqu’à cent vingt-huit articulations, par exemple). Lisez-la une fois avant de passer un week-end sur un modèle, pas après.

Essayez

  1. Éteignez les lumières. Mettez tout le bloc sun en commentaire en ajoutant -- au début de chaque ligne, et lancez. Puis faites de même avec sceneSetAmbient. Retenez à quoi ça ressemble, parce qu’un jour ça vous arrivera sans que vous l’ayez voulu.

  2. Déplacez le soleil. Changez nodeLookAt(sun, 0, 1.5, 0) en nodeLookAt(sun, 0, 20, 0) pour que le soleil vise au-dessus de la tête du dragon. Regardez l’ombre et les reflets s’en aller. Orienter une lumière n’est pas de la décoration.

  3. Réchauffez la torche. Montez l’intensité de la lumière ponctuelle de 14 à 60 et baissez sa portée à 4. Puis mettez-la en (0, 6, 0), au-dessus du dragon. Une lumière ponctuelle est une ampoule, et c’est vous qui choisissez où l’ampoule est suspendue.

  4. Instanciez-le deux fois. Appelez modelInstance(dragonModel) une deuxième fois, gardez le résultat dans une autre variable, mettez-le à l’échelle, et placez-le en (-4, 0, -3). Un chargement, deux dragons. Puis essayez plutôt de charger le modèle deux fois et comprenez pourquoi il ne faut pas.

  5. Trouvez une autre partie. Les parties du dragon s’appellent head, jaw, neck, tail, body, crest, hornL, hornR, wingL, wingR, foreLegL, foreLegR, hindLegL et hindLegR. Faites onduler la queue avec son propre math.sin à une autre vitesse que les ailes. Puis essayez nodeFind("wings", dragon) et voyez ce que fait un mauvais nom quand vous passez directement le nil à nodeSetRotation.

Cassez-le exprès

Changez le nom du fichier en Singe/Dragonmodel.glb — une seule majuscule — et lancez. Singe s’arrête avant que le jeu démarre :

13:modelLoad:  Unable to read Singe/Dragonmodel.glb.

La ligne, l’appel et la plainte, dans cet ordre. « Unable to read » veut dire que le moteur a cherché et n’a rien trouvé, ce qui est presque toujours l’une de trois choses : le nom est mal orthographié, les majuscules sont fausses, ou le fichier n’est pas là où vous l’avez dit. Sous Windows, les majuscules vous auraient été pardonnées, et votre jeu aurait ensuite échoué pour tout le monde sous Linux, ce qui est un bug pire que celui-ci. Tapez les noms exactement.

Le même message avec un vrai nom de fichier veut dire que le fichier n’est pas là où le moteur a regardé. Le dossier Singe est créé dans le dossier depuis lequel vous lancez le moteur, donc si vous avez démarré Singe depuis ailleurs, Singe/DragonModel.glb pointe ailleurs aussi.

Ce que vous avez appris

  • modelLoad lit un .glb une fois ; modelInstance en place des copies aussi souvent que vous voulez.

  • La racine d’une instance est un nœud ordinaire : placez-la, tournez-la, mettez-la à l’échelle et supprimez-la comme n’importe quel autre.

  • Un modèle apporte avec lui ses propres formes et ses propres matériaux.

  • Un modèle arrive à la taille qu’a utilisée son auteur, et c’est pour ça qu’un nodeSetScale sur l’instance fait partie de sa mise en place.

  • Une scène sans lumière est noire ou presque, et c’est la première chose à vérifier quand un modèle a l’air faux.

  • Une lumière directionnelle est un soleil, une lumière ponctuelle est une ampoule qui faiblit avec la distance et demande une intensité bien plus grande, et un spot est un cône.

  • Les ombres sont éteintes tant que lightSetShadow ne les allume pas, et chacune a un coût.

  • nodeFind atteint une partie d’un modèle par le nom qu’elle a dans le fichier.

  • modelGetAnimations dit ce qu’un modèle peut jouer, et demander un clip qui n’existe pas est une erreur.

  • Un modèle sans animations peut quand même être bougé une partie à la fois.

La prochaine fois

Tout dans cette scène bouge parce que vous le lui avez dit, image par image. La prochaine leçon confie ce travail à un moteur physique : des caisses qui tombent, roulent, s’empilent et se renversent les unes les autres sans que vous écriviez une ligne d’arithmétique — et la question plus difficile de savoir quand il faut le laisser faire. C’est la leçon vingt-quatre.

Leçon 24 : La physique

La leçon terminée

Jusqu’ici, tout ce qui bougeait dans vos jeux bougeait parce que vous faisiez l’arithmétique. Un nombre augmentait de deux à chaque image ; s’il dépassait un bord, vous le faisiez repartir dans l’autre sens. C’est la façon honnête de faire bouger un jeu, et la plupart des jeux sont faits de ça.

Cette leçon confie l’arithmétique à quelqu’un d’autre. Un moteur physique simule le monde — la gravité, les chutes, les glissades, les empilements, les rebonds, les roulades, et les choses qui se cognent — et déplace vos nœuds à votre place. À la fin, vous aurez un plateau de caisses et un canon qui les renverse. La dernière section explique quand ne rien faire de tout ça, et c’est la partie à lire deux fois.

Ce qu’elle fait, et ce qu’elle ne fait pas

Donnez un corps à un nœud et la simulation le prend en charge. À partir de là, il tombe sous l’effet de la gravité, atterrit sur ce qui se trouve en dessous, bascule quand on le frappe hors de son centre, repose dans une pile, glisse jusqu’à s’arrêter, et le nœud suit partout où la simulation le met. Vous arrêtez de régler sa position. C’est le marché : vous cédez la position et la rotation de ce nœud, et en échange vous obtenez un comportement que vous n’avez pas eu à écrire.

Ce qu’elle ne fait pas, c’est quoi que ce soit qui concerne votre jeu. Elle ne sait pas ce qu’est un score, ni que la caisse rouge est celle qui rapporte des points, ni que tomber du bord coûte une vie. Elle n’anime pas un personnage qui marche, elle ne sait pas quelle sensation doit donner un saut, et elle ne fera pas bouger un objet d’une façon que vous pouvez prévoir exactement. La physique est une machine à produire un désordre plausible.

Les unités sont les mètres, les kilogrammes et les secondes. La gravité vaut 0, -9.81, 0 sauf si vous en décidez autrement, ce qui est celle de la Terre, vers le bas, en mètres par seconde au carré. Une caisse d’une unité de large fait un mètre de large, et elle tombe comme telle. Si votre scène est construite à une autre échelle, tout aura l’air de tomber dans du sirop ou dans un dessin animé, et la solution est de construire en mètres.

Un sol et une caisse

Créez un dossier, créez crates.singe, et tapez ceci. C’est une scène, une dalle, une caisse au-dessus de la dalle, et trois lignes de physique.

sceneEnable(true)
sceneSetBackground(16, 18, 26)
sceneSetAmbient(40, 42, 50)

local stone = materialNew()
materialSetColor(stone, 110, 110, 120)
materialSetRoughness(stone, 0.9)

local wood = materialNew()
materialSetColor(wood, 190, 140, 80)
materialSetRoughness(wood, 0.8)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(16, 0.4, 16), stone)
nodeSetPosition(floor, 0, -0.2, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

local crate = nodeNew()
nodeSetMesh(crate, meshBox(0.8, 0.8, 0.8), wood)
nodeSetPosition(crate, 0.3, 4, 0)
nodeSetRotation(crate, 20, 0, 15)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
bodySetMass(crate, 4)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -5, 9, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 1.7)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 4, 11)
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R crates. La caisse tombe de quatre mètres de haut, atterrit sur un coin parce que vous l’avez inclinée, bascule sur une face, et s’arrête. Appuyez sur F5 pour la relancer et regardez-la encore une fois.

Rien dans onOverlayUpdate ne déplace quoi que ce soit. Les deux appels à bodyNew ont tout fait.

Ce qui vient de se passer

bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

bodyNew donne un corps à un nœud. Elle prend le nœud, la sorte de corps dont il s’agit, la forme que la simulation doit utiliser pour lui, et les dimensions de cette forme.

Il y a trois sortes, et choisir la bonne, c’est l’essentiel du savoir-faire.

  • BODY_STATIC ne bouge jamais. Il est placé là où se trouve le nœud quand vous créez le corps, et il y reste pour toujours. Les sols, les murs, le terrain, la borne, le niveau. Déplacer son nœud après coup ne déplace pas le corps, et c’est un piège à retenir : statique veut dire statique.

  • BODY_DYNAMIC est déplacé par la simulation. Il tombe, rebondit, glisse, se fait pousser, et entraîne son nœud avec lui. C’est une caisse, un tonneau, une balle, un débris.

  • BODY_KINEMATIC va là où vous mettez son nœud, et écarte de son chemin les corps dynamiques sans jamais être poussé lui-même. Une plateforme mobile, une raquette, une porte sur un rail, le poing d’un personnage qui frappe. C’est le pont entre votre arithmétique et la simulation : vous le pilotez, il les pilote.

La forme n’est pas le maillage. C’est une doublure grossière que la simulation utilise parce qu’elle peut répondre à des questions sur une boîte bien plus vite que sur neuf cents triangles. SHAPE_BOX prend une largeur, une hauteur et une profondeur ; SHAPE_SPHERE prend un rayon ; SHAPE_CAPSULE et SHAPE_CYLINDER prennent un rayon et une hauteur. Il y a SHAPE_HULL, qui enveloppe au plus près le maillage qui se trouve sous le nœud — la réponse habituelle pour un modèle — et SHAPE_MESH, les triangles exacts, que le décor statique peut utiliser et qu’un objet qui tombe ne peut pas utiliser.

C’est à vous de donner les bonnes dimensions. Rien ne vérifie que le corps que vous avez décrit correspond au maillage que vous avez dessiné, et une caisse dessinée à 0.8 avec un corps créé à 2 flottera au-dessus du sol et renversera des choses à distance. Quand quelque chose se comporte comme s’il avait une autre taille, c’est qu’il l’a.

bodySetMass(crate, 4)

La masse d’un corps dynamique vient de sa forme, à la densité de l’eau, ce qui rend les choses bien plus lourdes que vous ne l’attendez : une boîte de la taille d’une porte pèse environ cent quarante kilogrammes, et rien de ce que vous pourrez lui lancer ne la fera bouger. Réglez la masse de tout ce qui doit paraître léger. Quatre kilogrammes, c’est une caisse qu’on peut soulever.

La masse compte parce que les forces se répartissent selon elle. La même poussée envoie plus loin une chose légère, et une impulsion égale à la masse multipliée par la vitesse est ce qu’il faut pour mettre quelque chose en mouvement à cette vitesse. Réglez d’abord la masse et les forces ensuite, sinon vous tournerez en rond.

Faire bouger les choses

Trois appels poussent un corps dynamique, et ils ne sont pas interchangeables.

bodySetVelocity(node, x, y, z) dit « tu te déplaces maintenant à cette vitesse », en remplaçant ce que le corps faisait. C’est un service, un lancement, une apparition avec déjà un peu de vitesse.

bodyApplyImpulse(node, ix, iy, iz) est un coup : un coup de pied, une explosion, une batte qui rencontre une balle. Elle s’ajoute à ce que le corps faisait déjà. Donnez-lui un point du monde sous la forme de trois nombres de plus et elle frappe là au lieu du milieu, si bien qu’une caisse frappée près du haut bascule au lieu de glisser.

bodyApplyForce(node, fx, fy, fz) est une poussée qui dure : une fusée, un ventilateur, un tapis roulant. Une force appliquée pendant une seule image ne fait presque rien, ce qui surprend ceux qui s’attendaient à une impulsion.

La gravité elle-même, c’est physicsSetGravity(x, y, z), et elle s’applique au monde entier. La Lune, c’est physicsSetGravity(0, -1.62, 0), l’espace, que des zéros, et un jeu avec la gravité de côté est à une ligne de là.

Deux réglages de plus complètent le ressenti d’un objet. bodySetBounce(node, amount) va de 0, qui s’arrête net, à 1, qui repart avec tout ce qu’il avait en arrivant ; la valeur par défaut est un 0.1 à peine perceptible. bodySetFriction(node, amount) vaut 0 pour la glace et 0.5 par défaut. Les deux se combinent entre les deux choses qui se touchent, donc un sol glacé demande le petit nombre sur le sol, pas sur tout ce qui marche dessus.

Savoir quand les choses se touchent

function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 then
        knocks = knocks + 1
    end
end

Ici, knocks est une variable à vous, qui attend en haut du fichier avec local knocks = 0, et le jouet plus bas l’affiche.

onCollision est un callback, comme onOverlayUpdate : vous l’écrivez, le moteur l’appelle. Il arrive une fois pour chaque nouveau contact — deux corps qui restent en contact ne le signalent pas de nouveau — avec les deux nœuds, le point du monde où ils se sont rencontrés, et la vitesse à laquelle ils se sont rencontrés. C’est la vitesse qui permet à un petit choc et à un fracas de ne pas sonner pareil, et c’est pour ça que le test ci-dessus ignore le doux tassement d’une pile.

L’autre moitié de la paire, c’est onTrigger. Faites d’un corps un déclencheur avec bodySetTrigger(node, true) et il arrête de pousser les choses : il devient une zone qui signale ce qui y entre et en sort, par onTrigger(trigger, other, entered). Une ligne d’arrivée, une porte, une fosse, un objet à ramasser. C’est le descendant en 3D des tests de collision de la leçon onze, et pour tout ce qui ressemble à « le joueur est-il arrivé ici », c’est l’appel qu’il vous faut plutôt qu’un corps solide.

Le jouet

Maintenant, le tout. Partez du script ci-dessus et transformez-le en ceci : un plateau avec quatre murs, six caisses en pyramide, et une boule d’acier que vous pouvez viser et tirer. Les morceaux sont tous des choses que vous avez déjà rencontrées.

Tout ce dont le nouveau code se souvient va en haut du fichier, au-dessus de la scène :

local crates     = {}
local balls      = {}
local aimX       = 0
local aimLeft    = false
local aimRight   = false
local knocks     = 0
local showShapes = false

Deux handles partagés de plus vont avec les matériaux : un métal poli pour la boule et le repère de visée, et un seul maillage de caisse pour les six caisses.

local steel = materialNew()
materialSetColor(steel, 200, 205, 215)
materialSetMetallic(steel, 1)
materialSetRoughness(steel, 0.25)

local crateMesh = meshBox(0.8, 0.8, 0.8)

Les murs du plateau sont quatre boîtes statiques, créées dans une boucle à partir d’une table d’emplacements, et c’est la leçon six qui fait un travail honnête :

local wallMesh = meshBox(16, 1, 0.4)

for _, side in ipairs({ { 0, -8, 0 }, { 0, 8, 0 }, { -8, 0, 90 }, { 8, 0, 90 } }) do
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, stone)
    nodeSetPosition(wall, side[1], 0.5, side[2])
    nodeSetRotation(wall, 0, side[3], 0)
    bodyNew(wall, BODY_STATIC, SHAPE_BOX, 16, 1, 0.4)
end

Chaque entrée est un X, un Z et une rotation autour de Y. Deux murs sont couchés en travers, au fond et devant ; deux sont tournés de quatre-vingt-dix degrés pour faire les côtés. Un seul maillage sert aux quatre, et le corps est créé après que le nœud a été placé et tourné, parce qu’un corps statique prend la position et la rotation du nœud au moment où il est créé.

Les caisses viennent d’une fonction, pour que six caisses fassent six lignes :

local function crateAt(x, y)
    local crate = nodeNew()

    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, x, y, -2)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
    bodySetMass(crate, 4)
    crates[#crates + 1] = crate
end

Elle garde chaque caisse qu’elle crée dans la table crates, et c’est comme ça que le callback de dessin peut plus tard leur poser une question à toutes. Six appels construisent la pyramide, trois sur le sol, deux sur celles-ci, et une au sommet :

crateAt(-0.9, 0.4)
crateAt(0, 0.4)
crateAt(0.9, 0.4)
crateAt(-0.45, 1.25)
crateAt(0.45, 1.25)
crateAt(0, 2.1)

Les rangées du haut se trouvent à un doigt au-dessus de celles du dessous et tombent en place dès que le jeu démarre. Laisser un petit écart est plus facile que d’empiler exactement, et c’est plus gentil pour la simulation que de lui donner une pile déjà tassée.

Tirer crée une nouvelle boule à chaque fois :

local function fire()
    local ball = nodeNew()

    nodeSetMesh(ball, meshSphere(0.35, 24), steel)
    nodeSetPosition(ball, aimX, 1.2, 6)
    bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.35)
    bodySetMass(ball, 3)
    bodySetBounce(ball, 0.3)
    bodySetVelocity(ball, 0, 2, -14)
    balls[#balls + 1] = ball
    if #balls > 5 then
        nodeDelete(balls[1])
        table.remove(balls, 1)
    end
end

Regardez l’ordre. Le nœud est créé, reçoit une forme à dessiner, est placé, et ce n’est qu’ensuite qu’il reçoit un corps. Un corps dynamique commence là où se trouve son nœud, et après ça la circulation se fait dans l’autre sens : le corps déplace le nœud. Régler vous-même ensuite la position d’un nœud dynamique, c’est se battre contre la simulation, et la simulation gagne. Quand quelque chose doit être déplacé, donnez-lui une vitesse, frappez-le avec une impulsion, ou faites comme ici — créez-en un nouveau et laissez partir l’ancien.

Laisser partir l’ancien, c’est nodeDelete, qui libère le nœud, tout ce qui se trouve sous lui, et le corps qu’il portait. Sans ces trois lignes, chaque tir resterait dans le monde pour toujours, et quelques centaines de boules plus tard, la simulation ferait énormément de travail sur des choses que personne ne voit. Faire le ménage fait partie de l’usage de la physique.

Les commandes et l’affichage forment le reste :

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        fire()
    elseif what == SWITCH_BUTTON3 then
        showShapes = not showShapes
        if showShapes then
            physicsSetDebug(DEBUG_SHAPES + DEBUG_CONTACTS)
        else
            physicsSetDebug(DEBUG_NONE)
        end
    elseif what == SWITCH_LEFT then
        aimLeft = true
    elseif what == SWITCH_RIGHT then
        aimRight = true
    end
end

Espace tire, Maj allume et éteint la vue de la physique, et les flèches, tenues enfoncées, font glisser le point de lancement. Une plaque de métal plate sans corps, déplacée à chaque image en aimX, montre d’où partira la prochaine boule. Le script complet, avec le callback de relâchement et le reste de la mise en place, est 24-physics.singe dans le dossier learn.

physicsSetDebug est l’appel le plus utile de cette leçon. Il dessine ce que la simulation contient réellement — les vraies formes en fil de fer, et une croix rouge partout où deux corps se sont touchés pendant ce pas de la simulation — par-dessus votre scène. La première fois qu’une caisse flotte à une main au-dessus du sol, ou passe au travers, ou renverse quelque chose à deux mètres de distance, allumez-le et la réponse sera à l’écran. Ajoutez DEBUG_STATIC pour voir aussi le sol et les murs. Il ne coûte rien tant qu’il est éteint.

Enfin, le comptage :

function onOverlayUpdate()
    local over    = 0
    local settled = true

    if aimLeft then
        aimX = math.max(aimX - 0.08, -5)
    end
    if aimRight then
        aimX = math.min(aimX + 0.08, 5)
    end
    nodeSetPosition(marker, aimX, 0.05, 6)

    for _, crate in ipairs(crates) do
        local pitch, _, roll = nodeGetRotation(crate)

        if math.abs(pitch) > 30 or math.abs(roll) > 30 then
            over = over + 1
        end
        if not bodyIsResting(crate) then
            settled = false
        end
    end

    overlayClear()
    overlayPrint(2, 2, "Arrows aim.  Space fires.  Shift shows the shapes.")
    overlayPrint(2, 4, "knocked over " .. over .. " of " .. #crates .. "   hard hits " .. knocks)
    if settled then
        overlayPrint(2, 6, "everything has settled")
    end
    return OVERLAY_UPDATED
end

Une caisse compte comme renversée quand elle penche de plus de trente degrés, ce qui est une règle de jeu écrite en une ligne d’arithmétique par-dessus ce que la simulation a fait. nodeGetRotation donne trois angles et ce code veut le premier et le troisième, donc celui du milieu est attrapé dans une variable appelée _. Ce tiret bas est un nom ordinaire qui n’a rien de spécial, utilisé par convention pour dire « celui-là, je l’ignore ».

bodyIsResting dit si la simulation a mis un corps en sommeil parce qu’il a cessé de bouger. C’est comme ça que vous savez qu’un tir est terminé : pas avec une minuterie, pas au jugé, mais quand toutes les caisses dorment. Un jeu de bowling compte les points de son tour exactement à ce moment-là.

Quand ne pas s’en servir

La physique est l’outil le plus tentant de n’importe quel moteur, et celui qui gâche le plus de week-ends. Trois choses sont vraies à son sujet, et aucune n’est la faute du moteur.

Elle coûte cher. Chaque corps dynamique demande du travail à chaque pas, soixante fois par seconde, que quelqu’un le regarde ou non. Quarante caisses, ça va. Quatre mille, non, et sur une petite machine, quatre cents non plus.

Elle est imprévisible. Lancez votre jouet deux fois et les caisses atterrissent autrement. C’est ce qui lui donne l’air vivant, et c’est aussi pour ça qu’un jeu ne peut pas compter sur elle pour quoi que ce soit qui doit se passer pareil à chaque fois. Une porte qui doit s’ouvrir, une plateforme qui doit arriver, un saut que le joueur doit pouvoir réussir : tout ça, c’est de l’arithmétique, ou un tween, ou un corps cinématique sur un trajet que vous avez écrit. Ne confiez jamais une chose que le joueur doit faire à une simulation qui peut la laisser tomber derrière une caisse.

Elle est difficile à régler. La masse, le frottement, le rebond, la forme et la taille tirent tous les uns sur les autres, et « ça ne fait pas le bon effet » a rarement une seule cause. Chaque heure que vous passez à donner un bon ressenti à une caisse physique est une heure que vous n’avez pas passée sur le jeu.

Sortez-la donc quand le désordre est le but : des choses qui basculent, des débris qui volent, une pile qui se tasse, une boule qui cogne partout dans une pièce, un véhicule qui roule sur un terrain accidenté, un ragdoll qui dégringole un escalier. Personne ne peut écrire ça à la main, et personne ne peut vous dire exactement à quoi ça doit ressembler.

Ne la sortez pas quand vous savez ce qui doit se passer. Une balle qui vole en ligne droite, c’est deux lignes de la leçon deux. Une plateforme qui monte et descend, c’est math.sin. Un joueur qui marche et saute comme les joueurs s’y attendent demande un contrôleur de personnage (playerNew, dans la référence), parce qu’une personne n’est pas une boîte et ne se comporte jamais comme une boîte. Un ennemi qui patrouille demande un trajet. Un menu qui glisse à l’écran demande un tween.

La règle qui sert le mieux : la physique pour les choses que le joueur regarde, et l’arithmétique pour les choses que le joueur fait.

Essayez

  1. Changez le monde. Ajoutez physicsSetGravity(0, -1.62, 0) vers le haut du fichier et tirez de nouveau. Puis essayez 0, -30, 0. Les mêmes caisses, une autre planète, une ligne.

  2. Changez la boule. Rendez la boule dix fois plus lourde avec bodySetMass(ball, 30), puis dix fois plus légère avec 0.3, en gardant la même vitesse. Puis remettez la masse et changez plutôt le -14. Deux façons de frapper plus fort, et elles ne donnent pas la même sensation.

  3. Changez les caisses en glace. Ajoutez bodySetFriction(crate, 0.02) dans crateAt, et ajoutez une ligne qui donne aussi au sol un faible frottement. Regardez la pile refuser de tenir debout dès le départ.

  4. Faussez la forme exprès. Dans crateAt, changez les dimensions du corps en 2, 2, 2 pendant que le maillage reste à 0.8. Lancez, regardez les caisses flotter et se bousculer de nulle part, puis appuyez sur Maj et regardez la vue de débogage l’expliquer en une seule image.

  5. Comptez les points comme il faut. Utilisez bodyIsResting sur chaque caisse pour remarquer quand le tir est terminé, et seulement alors comptez combien sont renversées et ajoutez-le à un score. C’est la partie d’un jeu de bowling qui compte les points.

Cassez-le exprès

Ajoutez sous le bodyNew du sol une ligne qui rend le sol lourd, ce qu’il est raisonnable de croire que vous voulez :

bodySetMass(floor, 200)

Singe arrête le jeu avec quelque chose comme :

32:bodySetMass:  Node 1 is not a dynamic body, or the mass is not positive.

Le premier nombre est la ligne dans votre propre fichier, donc le vôtre sera différent.

Le nombre après Node est le handle du nœud, le nombre que nodeNew a renvoyé. La plainte est exacte : la masse appartient aux choses que la simulation déplace, et un corps statique n’est déplacé par rien, donc il n’a pas de masse à régler. Le demander est le signe que le corps n’est pas du bon type pour ce que vous aviez en tête — et si vous voulez vraiment un sol lourd qu’on puisse déplacer, ce qu’il vous faut, c’est un corps dynamique avec une grande masse, ou un corps cinématique que vous déplacez vous-même.

Le même message apparaît pour une masse de 0, que l’on écrit en pensant « sans poids ». « Sans poids » n’est pas une masse. C’est un monde sans gravité, ou playerSetGravityScale sur un contrôleur de personnage.

Ce que vous avez appris

  • Un corps s’attache à un nœud, et à partir de là, le nœud et le corps ne font qu’un.

  • Un corps statique ne bouge jamais, un corps dynamique est déplacé par la simulation, et un corps cinématique est déplacé par vous et pousse tout le reste de côté.

  • La forme de collision est une doublure du maillage, et c’est à vous de faire en sorte que ses dimensions correspondent à ce que vous avez dessiné.

  • Par défaut, la masse est le volume de la forme à la densité de l’eau, donc réglez-la sur tout ce qui doit paraître léger.

  • bodySetVelocity remplace le mouvement d’un corps, bodyApplyImpulse est un coup, et bodyApplyForce est une poussée qui dure.

  • Ne réglez pas la position d’un nœud dynamique ; supprimez-le et créez-en un nouveau quand vous devez le faire repartir de zéro.

  • onCollision signale chaque nouveau contact avec son point et sa vitesse, et un corps déclencheur signale les arrivées et les départs par onTrigger.

  • bodyIsResting vous dit quand tout s’est arrêté, ce qui est en général le moment où un tour est fini.

  • physicsSetDebug dessine la vue de la simulation elle-même, et elle répond à la plupart des questions de physique plus vite que la lecture du code.

  • La physique coûte cher, ne se répète pas, et demande beaucoup de réglages. Servez-vous-en pour le désordre, pas pour les choses dont le jeu dépend.

La prochaine fois

Des caisses qui tombent, c’est une sorte de spectacle. L’autre sorte est faite de mille petites choses qui vivent une demi-seconde : des étincelles, de la fumée, du feu, de la pluie et de la poussière. La prochaine leçon parle des émetteurs, et elle finit par une explosion. C’est la leçon vingt-cinq.

Leçon 25 : Les particules

La leçon terminée

À la fin de cette leçon, un vaisseau traversera le bas de l’écran en traînant du feu derrière son réacteur, et un bouton le fera exploser en cent quarante étincelles tournoyantes qui rebondissent sur le sol. Vous n’écrirez pas une seule ligne qui dessine une étincelle.

C’est toute l’idée de cette leçon. Vous décrivez le feu ; le moteur le fabrique.

Pourquoi vous ne dessinez pas les étincelles

Vous pourriez faire autrement. Vous en savez assez : une table d’étincelles, comme à la leçon six, chacune avec un x, un y et une vitesse ; une boucle dans onOverlayUpdate qui les déplace toutes, les estompe, retire celles qui meurent et les dessine. Ça marche. Ce sont aussi deux cents lignes de comptabilité que chaque jeu réécrit, et ça tourne en Lua, une étincelle à la fois, soixante fois par seconde.

Singe le fait pour vous à la place. Vous lui donnez une recette — combien d’étincelles par seconde, combien de temps vit chacune, à quelle vitesse et dans quelle direction elles partent, ce qui les attire, à quoi elles ressemblent et vers quelle couleur elles s’estompent — et il s’occupe lui-même des étincelles. Ce qui contient la recette et l’exécute s’appelle un émetteur.

Un émetteur n’est pas une image, et ce n’est pas un objet de votre jeu. C’est la description d’une sorte de feu, rangée quelque part où vous pouvez la désigner, et il peut produire ce feu partout où vous le demandez.

Commencez par quelque chose qui bouge

Les particules sont plus convaincantes quand elles sortent de quelque chose, alors commencez par un vaisseau. Créez un dossier, copiez-y le dossier art du livre, et mettez ceci dans particles.singe :

dofile("Singe/Framework.singe")

local SHIP_WIDTH  = 32
local SHIP_HEIGHT = 24
local SHIP_SPEED  = 120

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

local shipX = (overlayGetWidth() - SHIP_WIDTH) / 2
local shipY = overlayGetHeight() - 56

local movingLeft  = false
local movingRight = false
local lastTicks   = singeGetTicks()


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    local now     = singeGetTicks()
    local seconds = (now - lastTicks) / 1000
    lastTicks     = now

    if movingLeft then
        shipX = shipX - SHIP_SPEED * seconds
    end
    if movingRight then
        shipX = shipX + SHIP_SPEED * seconds
    end

    overlayClear()
    spriteDraw(shipSprite, shipX, shipY)
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R particles et pilotez avec les touches fléchées gauche et droite. Rien de nouveau ici : un sprite de la leçon neuf, les contacts de la leçon trois, et singeGetTicks pour que le vaisseau avance à la même vitesse quelle que soit la fréquence d’images.

La seule ligne qui mérite d’être signalée est dofile("Singe/Framework.singe"). C’est elle qui définit DIR, le dossier où se trouve votre script, si bien que DIR .. "art/spaceship.png" trouve l’image quel que soit le dossier depuis lequel vous avez lancé Singe.

Donnez-lui un échappement

Maintenant, le feu. Ajoutez ceci au-dessus des callbacks, après les variables du vaisseau :

local exhaust = emitterNew()
emitterSetBlend(exhaust, PARTICLE_ADD)
emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)
emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)
emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)
emitterSetMax(exhaust, 120)
emitterStart(exhaust)

Et deux lignes dans onOverlayUpdate. La première va juste avant overlayClear, la seconde juste après spriteDraw :

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)
    emitterDraw(exhaust)

Enregistrez. Le vaisseau repose maintenant sur une courte langue de flamme jaune, et la flamme le suit quand vous le pilotez.

Faites-le exploser

Un échappement tourne indéfiniment. Une explosion n’arrive qu’une fois, ce que le moteur traite comme une autre sorte de demande faite au même émetteur.

D’abord, deux fichiers de plus et un nombre de plus. Ceux-ci vont à côté du sprite du vaisseau, en haut :

local sparkSprite = spriteLoad(DIR .. "art/star.png")
local boomSound   = soundLoad(DIR .. "art/boom.wav")

et celui-ci va à côté de shipX et shipY, vingt unités au-dessus du bas de l’écran :

local ground = overlayGetHeight() - 20

Maintenant, la deuxième recette, sous la première :

local boom = emitterNew()
emitterSetTexture(boom, sparkSprite)
emitterSetBlend(boom, PARTICLE_ADD)
emitterSetLife(boom, 0.4, 1.1)
emitterSetSpeed(boom, 40, 220)
emitterSetSpread(boom, 180)
emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)
emitterSetSize(boom, 10, 2, 0.4)
emitterSetSpin(boom, -240, 240)
emitterSetColor(boom, 255, 255, 220, 255, 255, 70, 20, 0)
emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)
emitterSetMax(boom, 400)

Remarquez qu’il manque emitterStart. Celui-ci ne va jamais émettre en continu.

Ajoutez une fonction pour le déclencher, au-dessus de onInputPressed :

function explode()
    if not flying then
        return
    end
    flying = false
    emitterStop(exhaust)
    emitterSetPosition(boom, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT / 2)
    emitterBurst(boom, 140)
    soundPlay(boomSound)
    timerAfter(RESPAWN_MS, function()
        flying = true
        emitterStart(exhaust)
    end)
end

Il faut encore trois choses : local RESPAWN_MS = 1400 avec les autres constantes, local flying = true avec les autres variables, et une branche dans onInputPressed :

    elseif what == SWITCH_BUTTON1 then
        explode()

Enfin, le vaisseau ne doit pas être là pendant qu’il est en morceaux. Entourez le pilotage et le dessin de onOverlayUpdate d’un if flying then …​ end, et ajoutez emitterDraw(boom) à côté de l’autre appel de dessin. Le script terminé est learn/25-particles.singe.

Appuyez sur la barre d’espace — le bouton un, par défaut — et le vaisseau se disloque en un nuage d’étoiles qui culbutent, retombent en arc, heurtent le sol et rebondissent.

Ce qui vient de se passer

Il y a énormément de nouveaux appels dans cette leçon, et ils ont tous la même forme : l’émetteur d’abord, puis ce que vous réglez. Prenez-les par groupes.

local exhaust = emitterNew()

Crée un émetteur et renvoie un handle : un nombre dont le moteur se sert pour le retrouver, exactement comme le nombre que vous donne spriteLoad. Sans argument, vous obtenez un émetteur en deux dimensions, qui vit dans les coordonnées de l’overlay et que l’on dessine depuis onOverlayUpdate. Donnez plutôt un nœud à emitterNew et vous en obtenez un en trois dimensions, qui vit dans la scène et se dessine tout seul ; tout le reste de cette leçon est pareil pour les deux.

Un nouvel émetteur a déjà une recette complète — cinquante particules par seconde, blanches, une ou deux secondes de vie, qui dérivent vers le haut de l’écran — alors chaque appel qui suit, c’est vous qui n’êtes pas d’accord avec une valeur par défaut. L’entrée de la Référence pour emitterNew les donne toutes.

emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)

Quatre-vingt-dix particules par seconde, chacune vivant entre quinze centièmes et quatre dixièmes de seconde. Ces deux nombres décident ensemble de la quantité de feu : quatre-vingt-dix par seconde qui vivent un tiers de seconde, cela fait environ trente à l’écran à tout moment.

Partout où un appel d’émetteur prend un minimum et un maximum, chaque particule reçoit sa propre valeur, tirée au hasard entre les deux. C’est de là que vient l’irrégularité. Un feu où chaque flamme vivrait exactement aussi longtemps que toutes les autres aurait l’air d’une machine.

emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)

Dans quelle direction elles partent, quelle est la largeur de l’éventail, et à quelle vitesse. Le Y de l’overlay croît vers le bas, comme depuis la leçon un, donc (0, 1) va vers le bas de l’écran — par l’arrière d’un vaisseau qui pointe vers le haut. emitterSetSpread est la moitié de l’angle de l’éventail : douze degrés font un jet serré, quatre-vingt-dix l’ouvrent sur la moitié du cercle, et cent quatre-vingts, c’est toutes les directions à la fois.

emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)

C’est grâce à ces deux-là que la flamme ressemble à une flamme. Une particule n’a pas une taille et une couleur ; elle a une taille et une couleur à sa naissance et d’autres à sa mort, et elle glisse régulièrement des unes aux autres pendant la durée de vie qu’elle a tirée. Ainsi, chaque étincelle commence large de sept unités de l’overlay et jaune pâle, et finit large d’une unité et rouge orangé, avec un alpha de zéro, c’est-à-dire invisible. Elle rétrécit et s’efface parce que vous avez dit où elle finit, pas parce que quelque chose l’a estompée.

emitterSetColor prend huit nombres, ce qui fait beaucoup à lire : rouge, vert, bleu et alpha au départ, puis rouge, vert, bleu et alpha à la fin.

emitterSetBlend(exhaust, PARTICLE_ADD)

La façon dont une particule se combine avec ce qui est derrière elle. PARTICLE_ALPHA est la peinture normale, et c’est la valeur par défaut : servez-vous-en pour la fumée, la poussière, la pluie et les gravats. PARTICLE_ADD ajoute plutôt sa lumière à l’image, si bien que deux étincelles l’une sur l’autre brillent plus qu’une seule et que rien ne devient jamais plus sombre. Le feu, les étincelles, les lasers et la magie sont additifs. La fumée ne l’est pas, et une fumée dessinée en mode additif ressemble à de la vapeur éclairée de l’intérieur.

emitterSetMax(exhaust, 120)
emitterStart(exhaust)

emitterSetMax est la taille de la réserve : combien de particules de cet émetteur peuvent exister à la fois. Quand la réserve est pleine, rien de nouveau ne naît tant que quelque chose n’est pas mort. Quatre-vingt-dix par seconde qui vivent jusqu’à quatre dixièmes de seconde demandent environ trente-six places, donc cent vingt, c’est confortable. Réglez-la avant de démarrer, parce que la changer ensuite jette toutes les particules vivantes.

emitterStart ouvre le robinet. À partir de là, l’émetteur fabrique des particules à chaque image, que vous le dessiniez ou non, jusqu’à ce que emitterStop le referme. Notez ce que emitterStop ne fait pas : il arrête les nouvelles particules, et celles qui sont déjà en vie finissent leur vie et s’effacent normalement. C’est pour cela que l’échappement s’étiole au lieu de disparaître quand le vaisseau explose. Si vous voulez qu’elles disparaissent à l’instant même, emitterClear les tue.

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)

C’est ainsi qu’un émetteur suit quelque chose. Un émetteur en deux dimensions émet depuis un seul point, et ce point est là où vous l’avez mis en dernier, alors vous le réglez à chaque image d’après ce qui bouge : la position d’un sprite, le nœud d’un corps physique, la souris. Les nouvelles particules apparaissent au nouvel endroit ; celles qui sont déjà en l’air restent là où elles sont nées, ce qui est exactement ce qu’il faut pour un échappement, parce qu’un échappement, ça reste derrière.

Un émetteur en trois dimensions est créé sur un nœud et suit ce nœud tout seul, sans aucun appel dans votre mise à jour. Et quand vous voulez vraiment que tout le nuage se déplace avec la chose — un bouclier, une aura, le panache d’un propulseur vu de l’extérieur — emitterSetLocal active cela.

    emitterDraw(exhaust)

Les émetteurs en deux dimensions sont dessinés quand vous le demandez, une fois par image, depuis onOverlayUpdate. L’ordre de vos appels à emitterDraw est l’ordre dans lequel ils s’empilent. Oublier cet appel est l’erreur que tout le monde fait une fois : l’émetteur continue de tourner, continue de puiser dans sa réserve, et n’affiche rien.

Maintenant, les appels propres à l’explosion.

emitterSetTexture(boom, sparkSprite)

Sans texture, chaque particule est une tache ronde et floue que le moteur dessine lui-même ; c’est ce qu’utilise l’échappement, et c’est ce qu’il faut pour une flamme. Avec une texture, chaque particule porte cette image — ici star.png, huit pixels sur huit. L’émetteur garde sa propre copie des pixels, si bien que vous pouvez décharger le sprite ensuite et que les particules continuent de marcher.

emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)

La gravité est une attraction constante, en unités de l’overlay par seconde et par seconde, et elle est positive vers le bas pour la même raison que l’échappement part avec un Y positif. Le freinage, c’est l’inverse : il retire de la vitesse, un peu à chaque image, si bien que les étincelles partent fort puis restent suspendues. Des étincelles avec de la gravité et sans freinage retombent tout droit en pluie comme un feu d’artifice ; c’est le freinage qui leur donne l’air de traverser de l’air.

emitterSetSpin(boom, -240, 240)
emitterSetSize(boom, 10, 2, 0.4)

La rotation se compte en degrés par seconde, et une plage qui passe par zéro vous donne des particules qui tournent dans chaque sens. Elle se voit sur une texture et ne fait absolument rien à la tache intégrée, qui est ronde.

Le troisième nombre de emitterSetSize est la variation. Il multiplie les deux tailles de chaque particule par un même facteur aléatoire — ici n’importe où entre six dixièmes et un et quatre dixièmes — pour que les étincelles ne soient pas toutes la même étoile à la même taille.

emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)

COLLIDE_FLOOR pose un sol plat et invisible à travers le monde, à la hauteur que vous indiquez, et les particules rebondissent dessus. Les deux nombres qui précèdent la hauteur sont la part de vitesse qui survit à un rebond et la part de vitesse latérale qui est gommée. Cela ne coûte rien, parce que c’est une seule comparaison par particule, et cela donne aux débris l’air d’avoir atterri quelque part plutôt que de traverser le monde en tombant. Dans un jeu en trois dimensions, COLLIDE_SCENE fait plutôt rebondir les particules sur la vraie géométrie, ce qui coûte beaucoup plus cher.

Une traînée garde les quelques dernières positions d’une particule et trace à travers elles un ruban qui s’estompe. Quatre positions et deux unités de large font de chaque étoile un court trait lumineux.

    emitterBurst(boom, 140)

Et voici l’autre façon de faire des particules. emitterStart est un robinet ; emitterBurst est une poignée lancée d’un coup. L’émetteur n’a pas besoin d’émettre en continu, et celui-ci ne le fait jamais. Tout le reste — la recette, la réserve, la position — marche de la même façon.

Cette distinction vaut la peine d’être retenue. Tout ce qui est continu est un flux que vous démarrez et arrêtez : un échappement, de la fumée, de la pluie, une torche, une cascade. Tout ce qui arrive à un instant précis est une salve : une explosion, une éclaboussure, un pas dans la poussière, un impact de balle, un éclair de bouche. Bien des effets sont les deux, avec un émetteur ou deux : un obus éclate, puis fume.

Combien, c’est trop

La réponse honnête, c’est que les particules coûtent peu à déplacer et cher à regarder.

Déplacer dix mille particules, c’est de l’arithmétique, et un ordinateur capable de faire tourner un jeu, quel qu’il soit, le fait sans s’en apercevoir. Ce qui coûte, c’est le dessin, et ce que coûte le dessin, c’est à peu près le nombre de pixels de l’écran que couvrent les particules, chevauchements compris. Deux cents étincelles de huit pixels de large couvrent moins d’écran qu’une seule bouffée de fumée qui le remplit. Voilà la règle : petites et nombreuses, c’est presque gratuit ; grandes et superposées, ça ne l’est pas.

Le mélange additif est la sorte coûteuse, parce que rien de ce qu’il dessine ne peut être sauté — chaque couche s’ajoute à ce qui est dessous, alors la machine les peint toutes. Une douzaine d’éclairs additifs plein écran les uns sur les autres font ramper un Raspberry Pi 4, alors que dix mille minuscules étincelles qui rebondissent ne le dérangent pas.

Donc : quelques milliers de petites particules, il n’y a pas de quoi s’inquiéter. Avant d’aller au-delà, affichez le compte à l’écran et surveillez-le.

    overlayPrint(2, 4, "Particles alive: " .. (emitterGetCount(exhaust) + emitterGetCount(boom)))

emitterGetCount, c’est ce qui vous permet de dimensionner une réserve honnêtement plutôt qu’au jugé. Si le nombre reste pile à votre emitterSetMax, votre réserve est pleine et le moteur refuse en silence de fabriquer des particules que vous avez demandées. S’il n’en approche jamais, vous réservez de la mémoire pour rien.

Essayez

  1. Transformez l’échappement en fumée. Changez emitterSetBlend(exhaust, PARTICLE_ADD) en PARTICLE_ALPHA, réglez la couleur sur un gris qui s’estompe jusqu’à un gris transparent, et faites-la grossir au lieu de rétrécir avec emitterSetSize(exhaust, 3, 14). Trois lignes ont fait une tout autre machine.

  2. Enlevez le freinage de l’explosion. Supprimez la ligne emitterSetDrag et comparez. Puis remettez le freinage et enlevez plutôt la gravité. L’un des deux ressemble à un feu d’artifice et l’autre à un accident.

  3. Élargissez l’échappement. Mettez emitterSetSpread(exhaust, 180). Le vaisseau n’a plus l’air d’avoir un réacteur. L’ouverture travaille plus que vous ne le pensez.

  4. Lâchez-en mille d’un coup. Changez emitterBurst(boom, 140) en emitterBurst(boom, 1000) et regardez le compte à l’écran. Il n’atteindra pas mille. Trouvez pourquoi à partir de emitterSetMax, puis agrandissez la réserve et rendez les étincelles quatre fois plus grosses, et voyez ce que cela fait à la fréquence d’images.

  5. Déclenchez l’explosion là où le vaisseau n’est pas. Mettez emitterSetPosition(boom, 40, 60) dans explode à la place de la position du vaisseau. Un émetteur est la description d’un feu, pas une chose qui vit quelque part, et vous pouvez faire éclater le même en dix endroits dans la même image.

Cassez-le exprès

Les constantes — PARTICLE_ADD, COLLIDE_FLOOR, OVERLAY_UPDATED — sont des noms que Singe a donnés à des nombres. Écrivez-en une un peu de travers et Lua ne se plaint pas, parce qu’en Lua un nom qui n’a jamais reçu de valeur n’est pas une erreur : c’est nil, la valeur qui veut dire « rien ici ».

Changez la ligne de mélange de l’échappement pour un nom qui a l’air tout aussi plausible :

emitterSetBlend(exhaust, PARTICLE_ADDITIVE)

Singe s’arrête avant que le jeu démarre, en donnant la ligne de votre fichier où se trouve cet appel :

22:emitterSetBlend:  Argument 2 must be a number.

Cette erreur n’a pas la même forme que les erreurs Lua de la leçon huit, parce qu’elle vient du moteur et pas de Lua. C’est le numéro de ligne, puis l’appel qui a protesté, puis la plainte. L’argument deux de emitterSetBlend est le mode de mélange, et ce qui est arrivé, c’est nil, parce que PARTICLE_ADDITIVE n’est pas un nom que quoi que ce soit ait jamais défini.

« Must be a number » veut presque toujours dire ceci : une constante mal orthographiée, ou une variable que vous pensiez avoir réglée. Le remède, c’est de vérifier le nom dans la Référence, qui l’écrit PARTICLE_ADD.

Ce que vous avez appris

  • Un émetteur contient la recette d’une sorte de particule et s’occupe lui-même des particules, si bien que votre script n’en dessine jamais une seule.

  • emitterNew sans argument crée un émetteur en deux dimensions, dans les coordonnées de l’overlay ; avec un nœud, il en crée un en trois dimensions, dans la scène.

  • Chaque émetteur commence avec une recette complète, et chaque appel emitterSet…​ en change une partie.

  • Partout où un appel prend un minimum et un maximum, chaque particule tire sa propre valeur au hasard entre les deux, et c’est de là que vient l’irrégularité.

  • La taille et la couleur se règlent à la naissance et à la mort, et la particule glisse de l’une à l’autre au cours de sa vie.

  • emitterStart émet en continu jusqu’à emitterStop ; emitterBurst lance une poignée d’un coup. Les effets continus sont des flux, les effets ponctuels sont des salves.

  • emitterStop laisse les particules vivantes finir ; emitterClear les tue tout de suite.

  • Un émetteur en deux dimensions se déplace avec emitterSetPosition à chaque image et se dessine avec emitterDraw à chaque image. Un émetteur en trois dimensions suit son nœud et se dessine tout seul.

  • Les particules coûtent ce qu’elles couvrent à l’écran, pas ce qu’elles coûtent à déplacer, et le mélange additif est la sorte coûteuse.

  • emitterSetMax plafonne la réserve, et emitterGetCount vous dit si vous en avez deviné la bonne taille.

La prochaine fois

L’explosion a déplacé cent quarante choses sans qu’on lui dise où aucune devait aller, mais c’étaient des étincelles, et les étincelles se moquent de ce qu’elles percutent. La leçon vingt-six parle de quelque chose qui ne s’en moque pas : un personnage qui doit aller d’ici à là-bas, avec un mur sur le chemin.

Leçon 26 : Des personnages qui se déplacent seuls

La leçon terminée

Dans cette leçon, vous construisez une pièce coupée en deux par un mur, et vous y mettez deux personnages. L’un, vous l’envoyez dans un coin d’un appui sur un bouton. L’autre choisit un endroit au hasard, y marche, et quand il arrive en choisit un autre, indéfiniment.

Aucun des deux ne se cogne dans le mur, et vous n’écrivez jamais une ligne qui dit comment le contourner. C’est nouveau. Jusqu’ici, chaque leçon a déplacé les choses là où vous leur disiez d’aller. C’est la première leçon où le jeu trouve quelque chose tout seul.

Le problème quand on marche vers quelque chose

Voici la façon évidente de faire marcher un personnage jusqu’à un point, et c’est celle que tout le monde écrit en premier. Prenez la cible, soustrayez l’endroit où vous êtes, et avancez un peu le long de la ligne qui les relie, à chaque image, jusqu’à y arriver.

Ça marche à merveille dans une pièce vide.

Mettez un mur dans la pièce et ça ne marche plus, et ça ne marche plus d’une façon qui a l’air bête plutôt que cassée : le personnage marche droit dans le mur et reste là à frotter contre lui, à un mètre d’une porte qu’il ne voit pas, parce que rien dans « avancer vers la cible » n’a la moindre idée que le monde contient des formes.

Vous ne vous en sortirez pas à coups de rustines. Faire un écart quand on touche un mur coince votre personnage dans le premier coin qu’il trouve. Et il ne suffit pas non plus de savoir où sont les murs, parce que le chemin qui contourne un mur peut être long, peut s’éloigner de la cible avant d’y revenir, et peut ne pas exister du tout.

Ce qu’il faut, c’est un moyen de poser une vraie question : comment aller à pied d’ici à là-bas ? Pour y répondre, il faut quelque chose qui connaît la forme du sol.

Ce qu’est un maillage de navigation

Tenez-vous dans une pièce et regardez le sol. Sur une partie, vous pourriez marcher. Sur une autre, non : elle est sous une table, dans un mur, au-delà du bord d’un balcon, ou en haut d’une marche trop haute pour être gravie. Imaginez maintenant que vous peignez la partie où vous pourriez marcher, et que vous jetez tout le reste — les murs, les meubles, le plafond, le décor. Il vous reste une forme plate, ou plusieurs, avec des trous là où sont les piliers et des vides là où sont les à-pics.

Cette forme peinte est un maillage de navigation, et c’est tout ce dont un personnage a besoin pour prévoir un trajet. Ce n’est pas le niveau. C’est une carte simplifiée des parties du niveau où une personne peut se tenir debout, et parce qu’elle est simple, on peut répondre vite aux questions qui la concernent.

Singe le fabrique pour vous à partir du niveau que vous avez déjà. Vous dites quelle taille font les personnages, vous lui donnez la géométrie, et il détermine ce qui est praticable : les sols et les rampes dans la limite de la pente que vous autorisez, les marches pas plus hautes que vous ne l’autorisez, avec une marge retirée autour de chaque mur et de chaque à-pic pour qu’un personnage qui a une largeur n’accroche pas un coin. Cela s’appelle le précalcul, ça se fait une fois, et le résultat peut être enregistré dans un fichier et chargé la fois suivante.

Une pièce avec un mur dedans

Créez un dossier appelé navigation et commencez dedans un fichier appelé navigation.singe. Cette partie est une scène en trois dimensions, le sujet de la leçon vingt-deux : une scène est un monde dessiné en trois dimensions, et tout ce qu’elle contient est accroché à un nœud, c’est-à-dire une position, une rotation et une échelle auxquelles vous pouvez attacher une forme.

Si vous avez sauté cette leçon, vous pouvez quand même suivre celle-ci. Prenez les deux blocs suivants pour « un sol gris de vingt unités de côté, trois murs beiges posés dessus, et une caméra qui regarde le tout d’en haut ».

local ROOM         = 20
local WALL_HEIGHT  = 2
local AGENT_RADIUS = 0.4
local AGENT_HEIGHT = 1.8
local WALK_SPEED   = 2.2

sceneEnable(true)
sceneSetBackground(28, 32, 42, 255)
sceneSetAmbient(80, 86, 100)

local floorLook = materialNew()
materialSetColor(floorLook, 96, 102, 110)
materialSetRoughness(floorLook, 0.9)

local wallLook = materialNew()
materialSetColor(wallLook, 150, 128, 104)
materialSetRoughness(wallLook, 0.8)

local ground = nodeNew()
nodeSetMesh(ground, meshPlane(ROOM, ROOM), floorLook)

local wallMesh = meshBox(1, WALL_HEIGHT, 1)
local walls    = {}


function addWall(x, z, width, depth)
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, wallLook)
    nodeSetScale(wall, width, 1, depth)
    nodeSetPosition(wall, x, WALL_HEIGHT / 2, z)
    walls[#walls + 1] = wall
end


addWall(-4, 0, 12, 0.6)
addWall(7.5, 0, 5, 0.6)
addWall(-3, -6, 0.6, 8)

Les unités sont ici des mètres, parce que c’est ce que suppose le monde en trois dimensions de Singe. Les deux premiers murs traversent le milieu de la pièce avec un espace de trois mètres entre eux : une porte. Le troisième est un bout de mur qui avance dans la moitié du fond, pour que les personnages aient quelque chose à contourner une fois passés.

Ajoutez une lumière et une caméra pour qu’il y ait quelque chose à voir :

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 8, 14, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 3.5)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 17, 19)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 120)


function onOverlayUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R navigation. Un sol gris, un mur avec une ouverture, et un bout de mur, vus d’en haut et de derrière.

Précalculez le sol

Six lignes font de cette pièce une carte :

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)
navAddNode(nav, ground)
for _, wall in ipairs(walls) do
    navAddNode(nav, wall)
end
navBuild(nav)

Mettez-les après les murs et avant la lumière. Puis ajoutez une ligne à onOverlayUpdate, sous overlayClear, pour voir ce que vous avez obtenu :

    navDraw(nav, 0, 170, 190)

Relancez-le. Une toile de triangles bleu-vert est posée sur le sol, et elle s’arrête avant les murs. L’espace qu’elle laisse n’est pas décoratif : ce sont les 0,4 mètre de marge dont un personnage d’un rayon de 0,4 mètre a besoin pour que ses épaules ne traversent pas la pierre. La porte est toujours une porte dans le maillage, parce que trois mètres, c’est assez large pour passer ; réduisez l’ouverture à un demi-mètre et le bleu se refermerait dessus, et pour tous les personnages de votre jeu, il n’y aurait plus de porte du tout.

Regardez-le un instant, parce que navDraw est l’outil que vous prendrez chaque fois qu’un personnage fera quelque chose d’inexplicable. Neuf fois sur dix, la réponse est sur le sol, sous vos yeux.

Quelqu’un pour y marcher

Un personnage est un nœud. Son apparence ne regarde pas la navigation, alors construisez la chose la plus simple qui montre de quel côté il est tourné : une boîte avec un nez.

function makeWalker(x, z, look)
    local walker = nodeNew()
    nodeSetPosition(walker, x, 0, z)
    local body = nodeNew()
    nodeSetParent(body, walker)
    nodeSetMesh(body, meshBox(0.7, AGENT_HEIGHT, 0.7), look)
    nodeSetPosition(body, 0, AGENT_HEIGHT / 2, 0)
    local nose = nodeNew()
    nodeSetParent(nose, body)
    nodeSetMesh(nose, meshSphere(0.22, 16), look)
    nodeSetPosition(nose, 0, 0.4, -0.45)
    return walker
end

Cela va avec addWall. Il lui faut une couleur, alors ajoutez-en une à côté des autres matériaux :

local walkerLook = materialNew()
materialSetColor(walkerLook, 225, 85, 60)
materialSetEmissive(walkerLook, 70, 18, 10)

Et maintenant, la ligne pour laquelle cette leçon existe. Après navBuild :

local walker      = makeWalker(-7, 7, walkerLook)
local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

navAgentNew pose le nœud sur le maillage et renvoie un agent : le mot du moteur pour quelque chose qu’il veut bien faire marcher pour vous. À partir de ce moment, la position de ce nœud appartient au moteur. À chaque image, il le déplace et le tourne face à la direction où il va, et il continuera ainsi jusqu’à ce que vous lui disiez où aller ou que vous retiriez l’agent.

Lancez-le. Une boîte rouge avec un nez apparaît dans le coin le plus proche et ne fait absolument rien, parce que vous n’avez encore rien demandé.

L’envoyer quelque part

Donnez-lui une liste d’endroits et un bouton.

local posts = {
    {  7, 0,  7 },
    {  7, 0, -7 },
    { -7, 0, -7 },
    { -7, 0,  7 },
    { 30, 0, 30 }
}
local post    = 0
local message = "Button 1 sends the red one somewhere."


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    post = post % #posts + 1
    local target = posts[post]
    if navAgentMoveTo(walkerAgent, target[1], target[2], target[3]) then
        message = string.format("Walking to post %d.", post)
    else
        message = string.format("No path to post %d.  Staying put.", post)
    end
end

Affichez le message pour voir ce qui se passe. Dans onOverlayUpdate, après navDraw :

    overlayPrint(2, 2, message)

Lancez-le et appuyez sur le bouton un — la barre d’espace, par défaut. La boîte se tourne, marche jusqu’au coin opposé de sa moitié de la pièce, et s’arrête. Appuyez encore. Elle longe le mur, trouve la porte, la franchit, ressort de l’autre côté, et s’arrête dans le coin du fond. Appuyez une troisième fois et elle contourne le bout de mur jusqu’au quatrième coin. Vous ne lui avez pas parlé de la porte. Rien dans votre script ne mentionne la porte. Elle l’a trouvée, parce que la porte est un trou dans une forme et que contourner les trous, c’est à ça que sert le maillage.

Chaque entrée de posts est faite de trois nombres, un x, un y et un z, parce qu’un point dans un monde en trois dimensions en demande trois. Y va vers le haut, et les vôtres valent tous zéro parce que tout ici est au sol. La table posts est une table de tables, comme à la leçon six, et posts[post] est l’une des tables intérieures.

Savoir quand il arrive

La boîte s’arrête quand elle arrive, mais votre script ne sait pas qu’elle est arrivée. Demandez à être prévenu :

function onNavArrived(agent)
    message = string.format("Arrived at post %d.", post)
end

C’est un callback, la même idée que onOverlayUpdate à la leçon un : vous l’écrivez, le moteur l’appelle. Celui-ci s’exécute une fois, au moment où un agent atteint la cible qu’on lui a donnée. Pas quand il en est près, et pas à chaque image ensuite — une fois, à l’arrivée.

Il reçoit l’agent, parce qu’un jeu en a plus d’un. Cet argument est le nombre que navAgentNew a renvoyé, et c’est en le comparant que vous savez lequel de vos personnages vient d’arriver là où il allait.

Quand il n’y a pas de chemin

Appuyez une cinquième fois sur le bouton et le message affiche No path to post 5. Staying put., et la boîte ne bouge pas.

Le poste cinq est en { 30, 0, 30 }, soit vingt mètres en dehors d’une pièce de vingt mètres de large. Il n’y a pas de sol praticable là-bas, aucun chemin pour y aller, et rien de sensé qu’un personnage puisse y faire. navAgentMoveTo le dit en renvoyant false, et laisse l’agent exactement comme il était.

C’est la partie que les débutants sautent, et c’est celle qui mord. Les vrais jeux demandent sans cesse des trajets impossibles, parce que la cible est en général le joueur et que le joueur va partout : debout sur une caisse, en plein saut, dans l’eau, derrière une porte qui s’est fermée, ou de l’autre côté d’un passage que le maillage de navigation a retiré parce qu’il était trop étroit. Chacun de ces cas fait renvoyer false à un navAgentMoveTo parfaitement raisonnable.

C’est votre script qui décide de ce que cela veut dire. Un garde qui ne peut pas vous atteindre devrait reprendre sa ronde, ou marcher jusqu’au point le plus proche qu’il peut atteindre et y attendre, ou crier. Ce qu’il ne doit pas faire, c’est rien, pendant que votre code ignore en silence un false renvoyé et que vous vous demandez pendant une heure pourquoi un ennemi sur vingt reste figé.

Deux autres appels aident ici, et ils valent d’être connus avant que vous en ayez besoin. navNearest prend n’importe quel point et renvoie l’endroit le plus proche sur le maillage, ou nil s’il n’y a rien près de lui ; c’est ainsi que vous transformez « là où est le joueur » en « un endroit où un personnage peut vraiment se tenir ». Et navPath pose la même question que navAgentMoveTo sans faire bouger personne : il renvoie les angles du trajet sous forme de table de points, ou nil quand il n’y a pas de trajet. Vous pouvez le mesurer, le dessiner, ou décider que le trajet est trop long pour s’en donner la peine.

Le dessiner, c’est l’astuce utile. Ajoutez ceci à onOverlayUpdate :

    local target = posts[post]
    if target ~= nil then
        local x, y, z = nodeGetWorldPosition(walker)
        local route   = navPath(nav, x, y, z, target[1], target[2], target[3])
        if route ~= nil then
            for i = 2, #route do
                local a = route[i - 1]
                local b = route[i]
                lineDraw(a[1], a[2] + 0.1, a[3], b[1], b[2] + 0.1, b[3], 255, 215, 60)
            end
        end
    end

Maintenant, une ligne jaune va de la boîte jusqu’à l’endroit où elle se rend, en s’infléchissant par la porte et en raccourcissant à mesure qu’elle avance. Envoyez-la au poste cinq et la ligne n’est pas dessinée du tout, parce que navPath a renvoyé nil et que le if l’a intercepté. Vous regardez la décision que prend l’agent, dessinée sur le sol.

Un deuxième marcheur

Un personnage qui évite les murs, c’est de la navigation. Deux personnages qui évitent les murs et s’évitent entre eux, c’est ce que le moteur vous donne vraiment, et cela coûte quatre lignes de plus.

Ajoutez un matériau bleu à côté du rouge, puis ceci sous le premier agent :

local wanderer      = makeWalker(6, -6, wandererLook)
local wandererAgent = navAgentNew(nav, wanderer, AGENT_RADIUS, AGENT_HEIGHT, 1.4)

Envoyez-le quelque part pour le mettre en route, après la caméra :

navAgentMoveTo(wandererAgent, navRandomPoint(nav))

Et apprenez à onNavArrived à distinguer les deux :

function onNavArrived(agent)
    if agent == wandererAgent then
        navAgentMoveTo(agent, navRandomPoint(nav))
    else
        message = string.format("Arrived at post %d.", post)
    end
end

navRandomPoint choisit un endroit sur le maillage praticable — n’importe où dessus, jamais dans un mur — et renvoie trois nombres, ce qui est exactement ce que navAgentMoveTo attend ensuite. Comme le callback se déclenche à l’arrivée et que sa réponse est un autre trajet, la boîte bleue erre maintenant dans la pièce tant que le jeu tourne, avec quatre lignes et aucun état.

Regardez-les se croiser dans la porte. Aucun ne s’arrête net et aucun ne passe à travers l’autre : tous deux s’écartent un peu, à temps, et se croisent. Ce sont les agents qui se contournent l’un l’autre, et c’est la différence entre des personnages et des meubles.

Le script terminé est learn/26-navigation.singe.

Ce qui vient de se passer

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)

Commence un maillage de navigation, et les quatre nombres décrivent la personne à qui il est destiné : 0,8 mètre de large, 1,8 mètre de haut, capable de monter une pente jusqu’à quarante-cinq degrés, et de gravir une marche jusqu’à 0,3 mètre.

Chacun de ces nombres change la forme qui en sort. Un personnage plus large perd plus de sol dans la marge autour des murs et peut trouver une porte fermée. Un plus grand ne peut pas passer sous une poutre basse. Autorisez une pente plus raide et une rampe devient une route ; autorisez-en moins et elle devient une falaise.

Le rayon décide aussi de la finesse avec laquelle le sol est mesuré, si bien qu’un très petit rayon sur un très grand niveau prend longtemps à précalculer. L’entrée de la Référence pour navNew mérite d’être lue avant de choisir vos nombres.

navAddNode(nav, ground)
navBuild(nav)

navAddNode transmet de la géométrie — un nœud et tout ce qui est accroché en dessous, tel qu’il se trouve dans le monde à cet instant, alors placez les choses avant de les ajouter. Un seul appel prend tout un modèle chargé. Seules comptent les vraies formes : une lumière, un son ou un corps physique seul n’ajoute rien.

navBuild fait le précalcul, et c’est l’appel lent de cette leçon : rien que vous remarqueriez pour une pièce comme celle-ci, un dixième de seconde pour une cathédrale sur un ordinateur de bureau, plusieurs secondes sur un Raspberry Pi. Faites-le pendant qu’un écran titre est affiché, pas pendant que le joueur attend.

Ensuite, la géométrie est jetée et le maillage est fermé. Vous ne pouvez plus rien ajouter. Si votre niveau change de forme — une porte s’ouvre, un pont s’effondre — vous précalculez un autre maillage, et navDelete libère l’ancien.

Sur une machine lente, vous préféreriez ne pas précalculer du tout, alors navSave écrit le maillage terminé dans un fichier et navLoad le relit, construit et prêt. Précalculez une fois sur votre propre machine, livrez le fichier avec le jeu, et le joueur n’attend jamais.

local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

Un agent est un nœud que le moteur a accepté de faire marcher pour vous. Le rayon et la hauteur servent ici à le tenir à l’écart des autres agents, et le dernier nombre est sa vitesse maximale en mètres par seconde — 2,2 est une marche vive, 1,4 une flânerie, 6 un sprint.

À partir de là, ne réglez plus vous-même la position de ce nœud. Deux choses qui déplacent un même nœud se battent, et la bagarre ressemble à des saccades. Si votre personnage doit être bousculé par la physique en plus de marcher, il y a un appel pour cela — navAgentSetPlayer confie plutôt le pilotage à un contrôleur physique — et son entrée dans la Référence explique quand vous en avez besoin.

local ok = navAgentMoveTo(walkerAgent, x, y, z)

Règle la cible. Il n’y marche pas ; il dit où est « là-bas », et le moteur s’en occupe au fil des images suivantes. Vous pouvez le rappeler à tout moment et la nouvelle cible remplace l’ancienne ; c’est ainsi qu’un garde suit un joueur qui court : réorientez-le une ou deux fois par seconde, pas soixante.

Et il renvoie true ou false, et vous devez regarder.

navAgentStop(walkerAgent)

Pas utilisé plus haut, mais c’est l’autre moitié de la paire : il oublie la cible, et l’agent ralentit jusqu’à s’arrêter là où il est. onNavArrived ne se déclenche pas, puisqu’il n’est pas arrivé. Servez-vous-en quand la raison du trajet a disparu.

Aller vite n’est pas le but

Encore un appel, parce que c’est lui qui transforme cette démonstration en quelque chose qui ressemble à un jeu.

    local vx, vy, vz = navAgentGetVelocity(walkerAgent)
    local speed      = math.sqrt(vx * vx + vz * vz)
    overlayPrint(2, 4, string.format("Speed %.2f", speed))

navAgentGetVelocity vous dit comment l’agent se déplace en ce moment : pas où il va, mais à quelle vitesse et dans quelle direction il avance réellement à cette image. Regardez le nombre quand la boîte se met en route et quand elle s’arrête. Il monte en douceur et redescend en douceur.

C’est à ce nombre que vous accrochez une animation. Un personnage dont les jambes bougent à la vitesse à laquelle il avance vraiment a l’air vivant ; un personnage dont le cycle de marche tourne à un rythme fixe pendant qu’il accélère a l’air de patiner. Avec un vrai modèle à la place de la boîte, vous compareriez cette vitesse à deux ou trois seuils et joueriez une animation d’attente, de marche ou de course — c’est le sujet de la leçon vingt-trois, et l’exemple de la Référence sous navAgentGetVelocity est écrit exactement pour cela.

Et c’est là le vrai sujet de cette leçon. Un personnage qui prend la ligne droite rapide et frotte le long d’un mur fait pire qu’un autre qui part une seconde plus tard, se tourne correctement, fait le tour par la porte et ralentit en arrivant. Personne, en regardant un jeu, ne mesure à quelle vitesse un ennemi l’a atteint. On remarque, tout de suite et sans pouvoir dire pourquoi, quand quelque chose bouge d’une façon dont un être vivant ne bougerait pas.

Essayez

  1. Fermez la porte. Changez les deux premiers murs pour que l’espace entre eux fasse un demi-mètre au lieu de trois : addWall(-4, 0, 13, 0.6) et addWall(6.5, 0, 7, 0.6). Lancez-le et regardez ce que montre navDraw avant d’appuyer sur quoi que ce soit. Puis envoyez la boîte de l’autre côté et voyez ce qu’elle fait.

  2. Rendez tout le monde gros. Mettez AGENT_RADIUS à 2.0 et lancez-le. La porte fait toujours trois mètres de large et les triangles bleus en ont disparu. Rien n’est cassé ; le maillage répond maintenant à une autre question.

  3. Envoyez-la vers la souris. Prenez le point sous le pointeur de la souris avec sceneUnproject, ramenez-le sur le maillage avec navNearest, et envoyez-y la boîte quand le bouton est enfoncé. navNearest qui renvoie nil, c’est le cas que vous devez gérer, et il se produit chaque fois que le pointeur n’est pas sur le sol.

  4. Ajoutez quatre autres promeneurs. Mettez les quatre lignes du marcheur bleu dans une boucle for, comme à la leçon quatre, gardez les agents dans une table, et laissez-les tous errer. Regardez la porte quand trois d’entre eux la veulent en même temps.

  5. Précalculez-le une fois. Appelez navSave(nav, "room.nav") après navBuild, puis remplacez navNew, les appels à navAddNode et navBuild par un seul navLoad("room.nav", AGENT_RADIUS, AGENT_HEIGHT). Changez maintenant la position d’un mur et relancez. Ce que vous voyez est le piège qui va avec les maillages précalculés, et il vaut la peine de le rencontrer une fois exprès.

Cassez-le exprès

Le précalcul ferme le maillage. Essayez d’ajouter une chose de plus après coup — une caisse placée trop tard, ou un mur oublié — en mettant cette ligne juste après navBuild(nav) :

navAddNode(nav, ground)

Singe s’arrête avant que le jeu démarre, en donnant la ligne de votre fichier où se trouve cet appel :

68:navAddNode:  The mesh is already built.

Une erreur du moteur a toujours la même forme : la ligne, l’appel qui a protesté, et la plainte, et cette plainte veut dire ce qu’elle dit : navBuild a consommé la géométrie qu’on lui avait donnée et il n’y a plus rien à quoi ajouter.

Le remède, ce n’est jamais de déplacer l’appel à navAddNode. C’est de remarquer que vous avez la géométrie de deux niveaux et qu’il vous faut deux maillages, ou que vous avez précalculé trop tôt. Ajoutez tout, puis construisez, et construisez en dernier.

Ce que vous avez appris

  • Avancer vers une cible marche dans une pièce vide et échoue dès qu’il y a un mur, et aucune rustine n’y change rien.

  • Un maillage de navigation est une carte simplifiée du sol où un personnage peut se tenir, dont on a retiré les murs, les à-pics et la marge autour d’eux.

  • navNew décrit le personnage auquel le maillage est destiné, navAddNode transmet la géométrie du niveau, et navBuild la précalcule. Après le précalcul, on ne peut plus rien ajouter.

  • navSave et navLoad gardent un maillage précalculé dans un fichier pour que le joueur ne l’attende jamais.

  • navDraw vous montre le maillage, et c’est la première chose à regarder quand un personnage se conduit bizarrement.

  • navAgentNew confie un nœud au moteur pour qu’il le fasse marcher ; à partir de là, ne déplacez plus ce nœud vous-même.

  • navAgentMoveTo règle une cible et renvoie false quand il n’y a aucun moyen d’y arriver. Gérer ce cas, c’est votre travail, et cela arrive souvent.

  • onNavArrived est appelé une fois quand un agent atteint sa cible, et on lui dit quel agent.

  • navPath répond à la même question sans faire bouger personne, et nil veut dire pas de trajet.

  • Les agents se contournent entre eux en plus de contourner le niveau.

  • navAgentGetVelocity permet d’accorder un cycle de marche au terrain parcouru.

La prochaine fois

Vos deux boîtes se promènent maintenant dans une pièce en silence. La leçon vingt-sept parle de ce que vous mettez derrière elles : de la musique qui boucle proprement et reste au pas de la vidéo, et le MIDI, qui permet à un jeu de jouer d’un instrument — ou à un vrai instrument de jouer au jeu.

Leçon 27 : Musique et MIDI

La leçon terminée

Cette leçon, ce sont deux leçons qui se trouvent vivre ensemble.

La première moitié, c’est la musique : comment un jeu joue correctement un morceau de musique, pourquoi ce n’est pas la même chose que jouer un effet sonore, et que faire quand la musique doit rester au pas de la vidéo.

La seconde moitié, c’est le MIDI, que la plupart des gens n’ont jamais croisé et qui donne à un jeu quelque chose que rien d’autre ne donne. À la fin, un clavier musical branché sur votre ordinateur jouera à votre jeu.

Un effet sonore et un morceau de musique sont deux choses différentes

Vous savez déjà jouer un son. La leçon dix a chargé un .wav avec soundLoad et l’a déclenché avec soundPlay, et si vous donnez à ces deux appels une chanson de quatre minutes, ils la joueront.

Ne le faites pas. Singe sépare les effets sonores et la musique, et cette séparation vaut la peine pour quatre raisons.

  • Ils ont chacun leur volume. soundSetVolume ne touche jamais à la musique et musicSetVolume ne touche jamais aux coups de feu. Tous les jeux jamais sortis en ont eu besoin, parce que les joueurs baissent la musique et montent les effets.

  • La musique n’a pas de limite de canaux. Les effets sonores se partagent seize canaux, et quand les seize sont occupés, le dix-septième ne joue pas. Un morceau de musique n’est pas sur un canal, alors rien ne peut l’évincer.

  • Un handle, c’est un morceau, et il se met en pause, reprend, s’arrête et s’estompe tout seul sans rien déranger d’autre.

  • La musique se met en pause avec le jeu. Appuyez sur la touche de pause et elle reste là où elle en est. Revenez et elle repart. Vous n’écrivez rien pour cela.

Une chose qui n’est pas différente mérite d’être connue, parce qu’on suppose souvent le contraire : Singe décode un fichier de musique en mémoire dès le départ, exactement comme un effet sonore. Un long morceau coûte de la mémoire. Il n’est pas lu sur le disque petit à petit. Cinq minutes de musique, ce sont quelques dizaines de mégaoctets de mémoire tant qu’elles sont chargées, alors chargez le morceau du niveau où vous êtes et déchargez-le avec musicUnload quand vous en sortez.

Jouer un morceau

Chaque lecteur de ce livre a déjà un morceau de musique, parce que le moteur en a extrait un dans votre dossier de travail la première fois que vous avez lancé quoi que ce soit. Commencez un fichier avec ces trois lignes :

local theme = musicLoad("Singe/menuIntro.flac")
musicSetVolume(64)
musicPlay(theme, -1)


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Music: " .. (musicIsPlaying(theme) and "playing" or "stopped"))
    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R music. Dix secondes de musique, puis elle recommence, et elle n’arrête pas de recommencer.

C’est ce que fait le -1. musicPlay prend un nombre de boucles : omettez-le ou passez 0 et le morceau joue une fois, passez 3 et il joue quatre fois en tout, et passez -1 et il se répète jusqu’à ce que quelque chose l’arrête. Un menu, un écran titre ou le fond sonore d’un niveau, c’est presque toujours -1.

Deux détails de ce petit script méritent qu’on s’y arrête. musicLoad prend un chemin, et pas un chemin en DIR .., parce que Singe/menuIntro.flac est l’un des fichiers du moteur lui-même et se trouve dans le dossier que le moteur a extrait dans votre dossier de travail. musicIsPlaying répond true ou false, et le and …​ or …​ au milieu de cet overlayPrint est le raccourci Lua de la leçon trois pour choisir entre deux valeurs.

L’échelle de volume n’est pas celle que vous connaissez

musicSetVolume(64) le règle à peu près à la moitié. Les effets sonores vont de 0 à 63 ; la musique va de 0 à 128, soit deux fois plus loin.

Ce n’est pas une erreur, et ce n’est pas une blague. Singe sait faire tourner des jeux écrits pour Hypseus, un moteur dont le volume de la musique a toujours été sur une échelle de 0 à 128, et changer les nombres rendrait, sans prévenir, la musique de ces jeux deux fois plus forte que ne le voulaient leurs auteurs. Alors Singe garde les deux échelles, chacune attachée à la famille d’appels à laquelle elle appartient. Effets : de 0 à 63. Musique : de 0 à 128. Donnez à musicSetVolume un nombre hors de sa plage et le script s’arrête, ce que vous verrez par vous-même à la fin de cette leçon.

Ce que Singe sait jouer

Presque tout. WAV, Ogg Vorbis, Opus, MP3, FLAC, WavPack, AAC, et une longue liste au-delà, tous par le même musicLoad.

Deux familles sont plus intéressantes que les formats ordinaires, et toutes deux existent parce qu’elles sont minuscules.

Les modules de tracker — .mod, .s3m, .xm, .it, et une cinquantaine de cousins — contiennent une poignée de courts instruments enregistrés et la liste des notes auxquelles les jouer. Un air de quatre minutes peut tenir en moins de cent kilo-octets.

Les chiptunes — .nsf, .spc, .vgm, .gbs, et leur famille — vont plus loin : elles contiennent les écritures de registres destinées à la vraie puce sonore d’une Nintendo, d’une Mega Drive ou d’un Spectrum, et Singe émule la puce pour les jouer. Si vous voulez qu’un jeu sonne comme 1989 plutôt que comme un enregistrement de 1989, c’est comme ça.

Les uns comme les autres se chargent avec musicLoad, comme tout le reste. La section Formats vidéo, audio et de conteneur de la Référence donne la liste complète, y compris quel conteneur va avec quel codec.

Arrêter, mettre en pause, estomper

musicPause(theme)
musicResume(theme)
musicStop(theme)
musicStop(theme, 2000)

musicPause immobilise le morceau là où il en est et musicResume repart de cet endroit. musicStop le termine, et le morceau revient à son début la prochaine fois que vous le jouez. Avec un second nombre, musicStop fait disparaître le morceau en fondu pendant ce nombre de millisecondes au lieu de le couper net — deux secondes ici. Ce fondu est la chose la plus facile que vous puissiez faire pour qu’un jeu ait l’air fini. Une musique qui s’arrête au milieu d’une mesure quand le joueur franchit une porte ressemble à un bug, même pour quelqu’un qui ne saurait pas dire pourquoi.

Appelez l’un des quatre sans aucun handle et il agit sur toute la musique à la fois, ce qui est exactement ce qu’il faut à un écran de pause.

Maintenant, la limite, en toute honnêteté, parce que vous allez la chercher et qu’elle n’est pas là : Singe ne sait pas faire de fondu enchaîné entre deux morceaux. musicSetVolume est un seul gain pour toute la musique, pas un volume par morceau, alors il n’y a aucun moyen de faire monter un morceau pendant qu’un autre descend. Ce que vous pouvez faire, c’est estomper l’ancien et démarrer le nouveau pendant qu’il s’éteint, ce qui suffit pour un changement de niveau et ne donne pas du tout le même résultat, à l’oreille, pour un thème de combat qui se glisse sous un thème d’exploration. S’il vous faut aujourd’hui un vrai fondu enchaîné, le moyen de l’obtenir est de faire des deux morceaux un seul fichier et de sauter à l’intérieur, ou d’accepter le chevauchement.

La musique, la vidéo et la synchronisation

Si votre jeu lit de la vidéo — le sujet de la troisième partie — il y a une chose à savoir sur le son, et ce n’est pas du tout un appel de musique.

Singe affiche une image de la vidéo quand on entend le son qui va avec, pas d’après un minuteur. Le son est l’horloge, et l’image le suit. C’est le bon sens, parce qu’une oreille remarque un décalage d’un cinquième de seconde dans une voix alors qu’un œil ne remarque pas le même décalage sur une bouche.

Le moteur mesure son propre chemin audio au démarrage. Ce qu’il ne peut pas mesurer, c’est tout ce qui vient après que le système d’exploitation a laissé partir le son : un amplificateur, un téléviseur, un récepteur HDMI, un casque Bluetooth. Chacun ajoute son propre retard, il est différent sur chaque machine, et il se manifeste par un son qui arrive un peu après la chose qui l’a produit.

Le remède tient en un nombre :

singeSetAudioDelay(45)

Quarante-cinq millisecondes de « le son est en retard ; retiens l’image d’autant ». Vous pouvez aussi le passer en ligne de commande avec --audiodelay=45, ou le mettre dans l’entrée du jeu dans games.dat. singeGetAudioDelay relit la valeur en vigueur, ce qu’un menu de service affiche à côté de son curseur.

Vous n’avez pas à deviner ce nombre. Le menu de Singe lui-même a un écran de calibrage : il joue un clic une fois par seconde et fait clignoter l’écran en blanc, vous réglez jusqu’à ce que l’éclair et le clic arrivent ensemble, et il enregistre le résultat pour tous les jeux de cette machine. La section Synchronisation audio de la Référence le décrit et explique pourquoi ça marche. Si vous construisez une borne, lancez-le une fois après avoir câblé les haut-parleurs, et n’y pensez plus jamais.

L’autre chose qui s’appelle MIDI

Le MIDI, ce sont deux choses sans rapport sous un seul nom, et les distinguer, c’est déjà presque tout comprendre.

Voici la première, en un paragraphe. Un enregistrement — un .wav, un .mp3 — est une mesure d’un son, prise quarante-quatre mille fois par seconde. Le MIDI, ce n’est pas ça. Un fichier MIDI contient ce qui a été joué : à ce moment, sur ce canal, enfoncez la touche soixante avec cette force ; un peu plus tard, relâchez-la. C’est plus proche d’une partition, ou du rouleau perforé d’un piano mécanique, que d’un enregistrement. C’est pour cela qu’un fichier MIDI fait quelques kilo-octets quand la même musique en audio fait quelques mégaoctets, et c’est aussi pour cela qu’un fichier MIDI ne contient aucun son. Il faut que quelque chose joue les notes.

Un fichier MIDI est de la musique, alors il se joue comme de la musique :

local tune = musicLoad("music/overworld.mid")
musicPlay(tune, -1)

Mais ce qui joue les notes doit bien venir de quelque part, et cette chose, c’est une SoundFont : un fichier plein d’instruments enregistrés — un piano, une trompette, une caisse claire — avec les notes et les points de boucle marqués, pour que le moteur puisse en tirer n’importe quelle note de n’importe quel instrument.

Singe n’en fournit pas. Une bonne SoundFont pèse des dizaines de mégaoctets, et ce seraient des dizaines de mégaoctets transportés par chaque copie du moteur pour un format que la plupart des jeux n’utilisent jamais. Alors vous en désignez une avec --soundfont, ou vous en mettez une en Singe/soundfont.sf2 pour qu’un jeu empaqueté porte la sienne, ou vous laissez Singe trouver celle que votre distribution Linux a installée. Sans SoundFont nulle part, le chargement d’un .mid échoue et le dit.

Voilà pourquoi le même fichier MIDI sonne différemment sur deux machines, et pourquoi il sonnait si mal sur les ordinateurs des années quatre-vingt-dix. Le fichier est une liste de notes. Ce que vous entendez, c’est la SoundFont qui s’est trouvée les jouer : une bonne, c’est une salle pleine d’instruments, une mauvaise, une salle pleine de jouets, et les notes sont identiques dans les deux. Si un fichier MIDI va dans votre jeu, livrez la SoundFont avec. Sinon, vous n’avez pas choisi le son de votre musique ; vous l’avez laissé à ce qui est installé sur la machine du joueur.

Le MIDI comme un câble

Maintenant, la deuxième chose, qui est la plus intéressante.

Le MIDI, c’est aussi un câble, et des messages qui circulent dessus. Branchez un clavier musical sur votre ordinateur et chaque touche que vous enfoncez envoie un message : note on, canal 1, touche 60, vélocité 90. Tournez un bouton sur une surface de contrôle et elle envoie le contrôleur 7 du canal 1 vaut maintenant 40. Ces messages existent, que quelque chose joue de la musique ou non. C’est un périphérique d’entrée de plus, comme un joystick à quatre-vingt-huit boutons qui savent avec quelle force vous les frappez.

Et ça marche dans l’autre sens. Votre jeu peut envoyer ces messages, vers un synthétiseur, un module de sons, un contrôleur d’éclairage de scène, ou n’importe quoi d’autre sur le câble.

Les ports sont numérotés à partir de zéro, et Singe n’ouvre rien tant que vous ne le demandez pas — un jeu qui ne parle jamais de MIDI ne paie jamais pour le MIDI. Un port d’entrée et un port de sortie peuvent être ouverts à la fois. Faites l’inventaire de la machine comme ceci :

local inPort  = "none"
local outPort = "none"

if midiInputCount() > 0 and midiOpenInput(0) then
    inPort = midiInputName(0)
end
if midiOutputCount() > 0 and midiOpenOutput(0) then
    outPort = midiOutputName(0)
end

Sur une machine sans aucun MIDI, les nombres valent zéro, les appels d’ouverture répondent false, et rien n’échoue. C’est important : cela veut dire que vous pouvez écrire ce code dans un vrai jeu et le publier, et les quatre-vingt-dix-neuf joueurs sur cent qui n’ont pas de clavier MIDI ne sauront jamais qu’il est là. Les noms servent à un écran de réglages qui laisse le joueur choisir le port, parce que le port zéro est rarement celui qu’il veut. midiRescan cherche à nouveau ce qui a été branché pendant que le jeu tourne.

Écouter

Chaque message qui arrive va à un callback, de la même façon que chaque appui sur une touche va à onInputPressed :

local MIDI_NOTE_ON = 0x90


function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
end

La plupart des messages MIDI font trois octets, et les trois nombres qu’on vous donne sont ces octets, exactement tels que l’appareil les a envoyés. Un message plus court vous donne un 0 à la place de chaque octet qu’il n’a pas.

status dit de quelle sorte de message il s’agit et de quel canal il vient, les deux mélangés : la sorte est dans les quatre bits du haut et le canal dans les quatre du bas. 0x90, c’est note on, et une note sur le canal 1 arrive comme 0x90 alors que la même note sur le canal 5 arrive comme 0x94. status & 0xF0 garde la moitié du haut et jette le canal, ce que vous voulez, sauf si le canal vous importe. (& est le « et » bit à bit de Lua, et 0x90 est un nombre écrit en hexadécimal — en base seize — parce que c’est ainsi que tous les documents MIDI du monde les écrivent.)

data1 et data2 sont les deux autres octets, et leur sens dépend de la sorte. Pour un note on, ce sont la touche et la vélocité : la touche 60 est le do central, et la vélocité, c’est la force avec laquelle elle a été frappée, de 1 à 127.

Le test de data2 == 0 n’est pas de la maniaquerie. Un note on avec une vélocité de zéro veut dire note off : c’est ainsi que presque tous les claviers jamais fabriqués disent « j’ai lâché », et si vous ne le filtrez pas, votre jeu réagira deux fois pour chaque touche.

bytes est le message entier sous forme de chaîne ; c’est ainsi que vous lisez un message de plus de trois octets.

Jouer

Envoyer est plus facile que recevoir.

midiNoteOn(1, 60, 100)
midiNoteOff(1, 60)

Le do central sur le canal 1, frappé à cent, puis relâché. Ici, les canaux vont de 1 à 16, comme les compte une personne, et non de 0 à 15 comme le câble ; c’est Singe qui est gentil avec vous.

Chaque midiNoteOn a besoin d’un midiNoteOff. Une note jamais relâchée sonne jusqu’à ce que quelque chose l’arrête, et le premier bug MIDI classique, c’est un jeu qui plante ou qui quitte avec trois notes enfoncées et laisse un accord suspendu dans la pièce. Alors associez-les par paires, et faites-le avec un minuteur plutôt qu’à la main :

function playTarget()
    if not midiIsOutputOpen() then
        return
    end
    local key = target
    midiNoteOn(1, key, 100)
    timerAfter(HOLD_MS, function()
        midiNoteOff(1, key)
    end)
end

local key = target fait un vrai travail. timerAfter exécute sa fonction quatre dixièmes de seconde plus tard, et d’ici là target a pu changer pour une autre note ; la copier dans une variable locale garantit que le minuteur relâche la note qui a vraiment été enfoncée. Copiez tout ce dont un minuteur aura besoin plus tard.

Les autres appels d’envoi font le reste de ce qu’est le MIDI : midiProgramChange choisit l’instrument que joue un canal, midiControlChange bouge un contrôleur (le volume, c’est 7, le panoramique 10, la pédale de sustain 64), midiPitchBend infléchit la hauteur d’un canal, et midiSend envoie n’importe quel message sous forme d’octets bruts, pour ce que les appels nommés ne couvrent pas.

Une raison de s’y intéresser

Tout cela, c’est de la mécanique. Voici à quoi ça sert.

Réunissez les deux moitiés et le jeu demande une note, le joueur la joue sur un vrai instrument, et le jeu sait s’il a juste :

function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
    if data1 == target then
        score = score + 1
        pickTarget()
        playTarget()
    end
end

Onze lignes, et vous avez le squelette d’un jeu pour apprendre la musique. Ajoutez une horloge et vous avez un jeu de rythme qui note un vrai jeu d’instrument plutôt que quatre boutons en plastique. Ajoutez data2 au test et il tient compte de la force avec laquelle vous frappez la note. Comparez le moment où la note est arrivée au moment où elle était attendue et vous notez la précision rythmique à la milliseconde près.

Et comme le MIDI sort autant qu’il entre, une borne peut faire des choses que rien d’autre ne peut. Un vrai instrument câblé à la machine. Un module de sons externe qui joue la partition, pour que l’air ait une profondeur qu’aucune banque d’échantillons ne lui donne. Des lumières de scène sur la borne qui clignotent en rythme parce que le jeu leur a envoyé le rythme. Si vous êtes du genre à construire des bornes d’arcade, c’est l’appel qui permet à la borne d’être une vraie chose plutôt qu’une boîte autour d’un ordinateur.

Le script terminé est learn/27-midi.singe : les commandes de la musique, la liste des ports et le jeu de devinette, en une centaine de lignes. La barre d’espace envoie la note, Alt gauche met la musique en pause, Maj gauche la fait s’estomper, et les flèches haut et bas règlent le volume. Lancez-le sans matériel MIDI : la moitié musique marche et la moitié MIDI dit deux fois none, et c’est ainsi qu’il doit se comporter sur la machine d’un joueur.

Faire le ménage

function onShutdown()
    midiCloseInput()
    midiCloseOutput()
    musicUnload(theme)
end

onShutdown est appelé une fois quand le jeu se termine, et c’est là qu’un script rend ce qu’il a emprunté. Fermer un port qui n’est pas ouvert ne fait rien, alors il n’y a rien à vérifier avant.

Essayez

  1. Faites-la boucler quatre fois au lieu d’indéfiniment. Changez musicPlay(theme, -1) en musicPlay(theme, 3) et comptez. Le nombre dit combien de fois elle se répète, pas combien de fois elle joue.

  2. Estompez plus longtemps. Changez le fondu du bouton qui arrête la musique pour musicStop(theme, 4000) et écoutez la différence que font quatre secondes. Puis essayez musicStop(theme, 100).

  3. Affichez le canal. Dans onMidiMessage, calculez le canal avec (status & 0x0F) + 1 et affichez-le. Jouez sur votre clavier et voyez sur quel canal il est — puis trouvez ses réglages et changez ce canal, pour vous prouver que le nombre est réel.

  4. Notez la vélocité. Donnez un point pour la bonne note, et trois points si data2 dépasse cent, pour que le jeu récompense ceux qui jouent avec conviction.

  5. Jouez la réponse. Quand le joueur trouve la bonne note, faites jouer au jeu un petit accord en retour, avec trois appels à midiNoteOn espacés de quelques notes et trois minuteurs pour les relâcher. Il vous faudra pour cela un vrai port de sortie ou un synthétiseur logiciel, et sous Linux, c’est n’importe quel programme qui s’enregistre auprès d’ALSA.

Cassez-le exprès

Les deux échelles de volume sont faciles à confondre, et Singe préfère s’arrêter plutôt que de jouer votre musique à un niveau que vous ne vouliez pas. Ajoutez une ligne sous musicPlay(theme, -1), avec le nombre qui serait le plein volume d’un effet sonore si vous le doubliez de tête en vous trompant :

musicSetVolume(200)

Singe s’arrête avant que le jeu démarre, en donnant la ligne de votre fichier où se trouve cet appel :

107:musicSetVolume:  Invalid music volume value:  200

La ligne, l’appel qui a protesté, et la plainte, qui vous renvoie ici le nombre pour qu’il n’y ait pas de discussion sur ce qui est arrivé. La musique, c’est de 0 à 128. Les effets sonores, de 0 à 63. Quand un appel de volume arrête votre jeu, la question à se poser, c’est à laquelle des deux familles vous parlez.

Ce que vous avez appris

  • La musique et les effets sonores sont séparés dans Singe : chacun son volume, pas de limite de canaux pour la musique, et une pause qui suit celle du jeu.

  • Un fichier de musique est décodé en mémoire dès le départ, si bien qu’un long morceau coûte de la mémoire et doit être déchargé quand vous quittez le niveau.

  • musicPlay(track, -1) boucle indéfiniment ; un nombre positif dit combien de fois il se répète.

  • Le volume de la musique va de 0 à 128 et celui des effets de 0 à 63, et cette différence vient de la compatibilité avec Hypseus ; ce n’est pas une erreur.

  • musicStop(track, milliseconds) fait un fondu de sortie, et un fondu est la finition la moins chère qui soit. Il n’y a pas de fondu enchaîné, parce qu’un seul gain couvre toute la musique.

  • Singe présente la vidéo d’après l’horloge audio, et singeSetAudioDelay corrige le retard de ce par quoi sort le son.

  • Un fichier MIDI contient des notes, pas du son, et il lui faut une SoundFont pour qu’on l’entende. Singe n’en fournit aucune, alors livrez la vôtre, sinon votre musique sera ce que la machine du joueur se trouve avoir.

  • Les ports MIDI sont tout autre chose : des messages en direct, qui entrent et sortent, sur un câble, sans rapport avec les fichiers MIDI.

  • onMidiMessage vous donne les octets bruts. Les quatre bits du haut de status sont la sorte, les quatre du bas sont le canal, et un note on de vélocité zéro veut dire note off.

  • Chaque midiNoteOn a besoin d’un midiNoteOff, et c’est un minuteur qui les associe.

  • Sur une machine sans MIDI, chaque appel répond false ou zéro et rien n’échoue, alors la prise en charge du MIDI peut être publiée sans risque.

La prochaine fois

Votre jeu a de la musique, et un score qu’un clavier MIDI peut faire grimper. La leçon vingt-huit emmène ce score hors de la machine : les comptes, des tableaux de meilleurs scores que d’autres peuvent voir, et le catalogue qui présente votre jeu au monde entier.

Leçon 28 : En ligne

La leçon terminée

À la leçon douze, vous avez sauvegardé un meilleur score. Il est toujours là le lendemain matin, ce qui est l’essentiel de ce à quoi sert un meilleur score, mais c’est un meilleur score sur une seule machine. Cette leçon met un score sur un tableau que d’autres peuvent voir.

C’est aussi la leçon sur l’échec. Tout ce que vous avez écrit jusqu’ici échoue pour des raisons que vous pouvez trouver : un fichier manque, un nombre est faux, une fonction est mal orthographiée. Le réseau échoue pour des raisons que personne dans la pièce ne peut voir. Un câble a été débranché dans un bâtiment où vous n’avez jamais mis les pieds, et votre jeu doit continuer à tourner. L’essentiel de ce qui suit parle de cela.

Ce qu’est le service

Singe peut parler à un service maître, un serveur qui détient trois choses :

  • un compte, qui appartient à la machine et non à un jeu en particulier ;

  • un catalogue de jeux à télécharger et à mettre à jour ;

  • des tableaux des meilleurs scores, un ou plusieurs par jeu.

Le service par défaut est master.singeengine.com, et un exploitant qui fait tourner le sien fait pointer la machine ailleurs. La section du manuel sur le service en ligne décrit les deux côtés.

Maintenant, la partie que les gens sautent. Le service n’est pas du multijoueur : deux joueurs n’ont aucun moyen d’être dans la même partie. Ce n’est pas un nuage de sauvegardes ; la sauvegarde de la leçon douze reste sur la machine. Ce n’est pas une protection contre la copie, et rien en lui n’empêche qui que ce soit de jouer à votre jeu. Il n’est pas obligatoire : un jeu qui ne se connecte jamais tourne exactement comme il l’a toujours fait, et c’est le seul comportement par défaut raisonnable pour quelque chose qui a besoin d’une connexion qui marche.

Le tableau est donc un bonus. Gardez le meilleur score local de la leçon douze, continuez à l’afficher, et laissez le tableau en ligne être la chose qui est là de temps en temps.

On se connecte une fois, et pas dans votre jeu

Le compte appartient à la machine. On le crée et on s’y connecte depuis le menu fourni, derrière la touche affectée à INPUT_SERVICE, dans l’outil appelé Online Account. Le jeton qu’il obtient est écrit dans master.dat à la racine des données, un niveau au-dessus du dossier de données propre à chaque jeu, si bien que tous les jeux de la machine envoient leurs scores sous la même connexion.

Votre jeu ne demande jamais d’adresse e-mail et ne demande jamais de mot de passe. Il n’existe aucune fonction pour le faire, et c’est voulu : un joueur qui tape un mot de passe dans un jeu qu’il a téléchargé n’a aucun moyen de savoir où il part.

Ce sous quoi un joueur apparaît sur un tableau est un nom de joueur : de trois à vingt caractères, lettres, chiffres, traits d’union et tirets bas, qui commencent et finissent par une lettre ou un chiffre. Pas d’espaces, pas de points, et pas de @, si bien qu’un nom de joueur ne peut même pas ressembler à une adresse e-mail. Il est séparé du compte, c’est la seule chose d’un joueur que les autres joueurs voient, et il est choisi une fois pour toutes — un exploitant peut en changer un, un joueur ne le peut pas, parce qu’un tableau dont les noms bougent sans cesse n’est vraiment l’histoire de personne. Tant qu’aucun nom de joueur n’a été choisi, les scores sont refusés, puisqu’un score qui ne porte le nom de personne n’est sur un tableau dans aucun sens utile.

L’outil Online Account montre le nom sous lequel cette machine envoie ses scores, et votre jeu le lit avec scorePlayerName(), qui répond nil quand il n’y en a pas. Bon à savoir avant que cela ne vous intrigue : un score envoyé sans nom de joueur derrière lui est refusé par le service, pas par scoreSubmit, si bien que votre jeu n’en est pas informé. Si scorePlayerName() vaut nil, dites-le à l’écran tant qu’il y a encore quelqu’un pour le lire.

Votre jeu a besoin d’un identifiant

Un tableau doit être rangé sous quelque chose. Ce quelque chose, c’est GAME_ID, dans l’entrée de votre jeu dans games.dat, le fichier que vous avez créé à la leçon treize :

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

C’est un UUID, exactement de cette forme : huit chiffres hexadécimaux, trois groupes de quatre, puis douze, séparés par des traits d’union. Générez-en un comme vous voulez et collez-le ; peu importe lequel vous obtenez, l’important est qu’il ne change plus jamais. L’entrée de la Référence pour singeGetGameId explique pourquoi rien d’autre n’est accepté.

singeGetGameId() le renvoie, ou nil quand l’entrée n’en a pas. Un jeu sans identifiant peut être joué mais pas classé, et demander d’abord vous évite de proposer un tableau des scores qui ne pourra jamais marcher :

if singeGetGameId() then
    -- showLeaderboardButton est votre propre fonction, pas une de celles de Singe.
    showLeaderboardButton()
end

Les six appels

Tout ce qu’un jeu fait avec le service tient en six fonctions, et elles viennent de Singe/Framework.singe, alors le dofile en haut de votre script n’est pas facultatif ici :

dofile("Singe/Framework.singe")

scoreBegin() dit qu’une partie commence. scoreSubmit(value) met un score en file d’attente. scoreBoard(onDone) récupère le tableau. scorePlayerName() est le nom de joueur. scoreWaiting() est le nombre de scores qui ne sont pas encore partis. Et scoreUpdate() doit s’exécuter une fois par image, depuis onOverlayUpdate, sinon aucun des autres ne se termine jamais.

Ce dernier est toute l’astuce de cette leçon, alors il est dit deux fois. Rien ici ne parle au réseau quand vous l’appelez. scoreSubmit écrit dans une file d’attente et rend la main aussitôt. scoreBoard retient ce que vous voulez et rend la main aussitôt. Le vrai travail se fait par petites tranches dans scoreUpdate, entre vos images, et c’est pour cela que votre jeu ne saccade jamais quand la ligne est lente. Oubliez scoreUpdate et rien ne casse, aucune erreur ne s’affiche, et il ne se passe jamais rien.

function onOverlayUpdate()
    scoreUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Envoyer un score

À la fin d’une partie :

if scoreSubmit(score) then
    fetchBoard()
else
    saying = "Kept here only:  " .. whyNotPosted()
end

scoreSubmit répond false quand il n’y a pas de compte ou que le jeu n’a pas de GAME_ID, et true quand le score est entré dans la file d’attente. Remarquez ce que le else ne fait pas : il ne jette pas le score, il ne s’excuse pas longuement, et il n’empêche pas le joueur de commencer une autre partie. Il dit une courte ligne, parce que le joueur n’a rien fait de mal et ne peut rien y corriger d’ici.

C’est la file d’attente qui rend cela sûr. Un score en file d’attente est écrit sur le disque, il survit donc à l’extinction de la machine, et il est remis au service la prochaine fois qu’il y a une connexion — une heure plus tard, ou mardi prochain. Voilà pourquoi une borne dans une salle au wifi médiocre finit quand même sur le tableau.

Soyez honnête avec vous-même sur la limite de cette promesse : la file d’attente garde les scores d’une machine qui a un compte. Si personne ne s’est jamais connecté, scoreSubmit répond false et le score n’est pas gardé pour plus tard, parce qu’il n’y a personne pour qui le garder. scoreWaiting() vous dit combien il en reste dans la file d’attente, et afficher ce nombre quelque part est une gentillesse : c’est la différence entre « le service est en panne » et « trois de vos scores attendent le retour d’Internet ».

scoreBegin() mérite un paragraphe à lui seul. Appelez-le quand une partie commence, et le service note le moment d’après sa propre horloge. Le score qui suit porte la durée de la partie, mesurée sur le serveur, et c’est le seul nombre d’un envoi qui n’est pas passé par la machine du joueur. Rien n’est rejeté sur cette base : la durée est montrée à celui qui fait tourner le service, à côté du score, et c’est une personne qui décide. Une machine qui était hors ligne quand la partie a commencé n’enregistre aucune durée, ce qui est honnête plutôt que cassé.

Et puisque nous sommes dans l’honnêteté : un score envoyé est une déclaration. Le jeu tourne sur l’ordinateur du joueur, alors rien de ce que peut faire le client n’en fait davantage, et une clé secrète livrée dans votre jeu n’aurait que l’apparence de la sécurité. Le service enregistre qui a déclaré quoi, limite la vitesse à laquelle les scores peuvent arriver, et signale les scores aberrants pour qu’une personne les examine. Concevez votre tableau en le sachant.

Relire le tableau

scoreBoard est la première fonction de ce livre qui prend une fonction comme argument.

scoreBoard(function(ok, result)
    ...
end)

Vous avez écrit des fonctions à la leçon cinq et vous leur avez donné des noms. Celle-ci n’a pas de nom : elle est écrite là où elle sert, passée directement à scoreBoard, et appelée plus tard — peut-être plusieurs secondes plus tard — quand la réponse arrive. C’est encore un callback, la même idée que onOverlayUpdate, sauf que cette fois, c’est vous qui choisissez qui l’appelle.

ok vaut true ou false. Quand il vaut false, result est une courte chaîne qui dit pourquoi. Quand il vaut true, result est une table en deux parties :

  • result.top, une liste de lignes, chacune avec un name et une value ;

  • result.standing, la propre value de ce joueur, son rank, et le nombre de players sur le tableau — qui peut manquer, si ce joueur n’a rien dessus.

Entre l’appel et le callback, votre jeu continue de tourner et de dessiner. Ce délai est réel et le joueur le voit, alors mettez-y quelque chose. Le script ci-dessous règle une ligne de texte sur "Asking the service…​" avant l’appel, et le callback remplace cette ligne soit par le tableau, soit par la raison pour laquelle il n’y en a pas. Un écran qui ne dit rien pendant quatre secondes a l’air cassé ; un écran qui dit ce qu’il fait est juste lent.

Le catalogue

La troisième chose que fait le service, c’est lister des jeux. L’outil Get Games du menu montre tout ce que le service propose, marque ce qui est déjà installé sur cette machine, et le télécharge, le met à jour ou le supprime. Un téléchargement est vérifié d’après l’empreinte publiée par le catalogue avant de remplacer quoi que ce soit, si bien qu’un transfert qui arrive abîmé échoue au lieu d’installer un jeu qui ne tournera pas. Un jeu que le service a retiré continue de marcher et apparaît comme installé mais plus proposé : la seule chose qui s’arrête, ce sont les mises à jour, parce que quelqu’un qui a un jeu l’a.

Votre jeu n’appelle rien de tout cela, et ne doit pas le faire. Le catalogue vous concerne en tant qu’auteur d’un jeu plutôt qu’en tant que rédacteur d’un script : c’est là que va votre fichier .game quand vous le publiez, ce qui est le sujet de la leçon trente, et c’est une raison de plus pour que votre games.dat ait un GAME_ID qui ne change jamais. Si un jour vous voulez la liste depuis un script, Singe/Master.singe est le module qui se trouve sous tout cela, et il vaut la peine d’être lu une fois.

Ce que le service sait d’un joueur

Si vous publiez un jeu qui envoie des scores, vous confiez les données de quelqu’un d’autre à un serveur, et c’est votre responsabilité même si vous n’avez pas écrit le serveur. Alors dites-le clairement, dans l’écran « À propos » de votre jeu ou dans son fichier lisez-moi :

  • Le service détient une adresse e-mail et un mot de passe pour le compte. L’adresse sert à récupérer un mot de passe perdu, et à rien d’autre. Elle n’est jamais montrée aux autres joueurs et ne peut pas être changée ensuite.

  • Le nom de joueur est ce qui apparaît sur les tableaux. Il est volontairement séparé du compte pour qu’une adresse ne soit jamais ce que voient les autres joueurs, et il est vérifié d’après une liste de noms que personne ne devrait prendre et de mots qui n’ont pas leur place sur un écran dans une salle publique.

  • Un score porte sa valeur, le tableau où il se trouve, l’heure qu’a enregistrée le service, et le nom de joueur. C’est tout.

  • Le catalogue sait quels jeux sont installés sur la machine, et en quelle version, parce que c’est ainsi qu’il vous propose une mise à jour.

Ce que rien de tout cela ne fait, c’est suivre un joueur d’un jeu à l’autre, vendre quoi que ce soit, ou aller chercher dans la machine quoi que ce soit que vous n’avez pas envoyé. Votre jeu ne doit rien ajouter à la liste. Si vous joignez des informations supplémentaires à un score — scoreSubmit prend pour cela un troisième argument facultatif — qu’elles concernent le jeu.

Le script

Un test de réflexes : attendez le mot, appuyez sur le bouton, marquez ce qui reste de mille. C’est un petit jeu, et tout le reste, c’est la partie en ligne.

Créez un dossier appelé reaction et mettez ceci dans un fichier reaction.singe, dedans. Donnez au dossier un games.dat comme celui de la leçon treize, qui désigne reaction/reaction.singe, avec dans son entrée la ligne GAME_ID vue plus haut.

dofile("Singe/Framework.singe")

local WAIT_MIN = 1000
local WAIT_MAX = 3000
local PERFECT  = 1000

local state    = "attract"
local goAt     = 0
local score    = 0
local best     = saveGet("best", 0)
local saying   = "Button 1 to play."
local top      = nil
local standing = nil


local function whyNotPosted()
    if not singeGetGameId() then
        return "this game has no GAME_ID."
    end
    return "this machine is not signed in."
end


local function fetchBoard()
    top      = nil
    standing = nil
    saying   = "Asking the service..."
    scoreBoard(function(ok, result)
        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end
        top      = result.top
        standing = result.standing
        if #top == 0 then
            saying = "The board is empty.  You could be first."
        else
            saying = ""
        end
    end)
end


local function finish(reaction)
    score = PERFECT - reaction
    if score < 0 then
        score = 0
    end
    if score > best then
        best = score
        saveSet("best", best)
    end
    state = "result"
    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end
end


local function play()
    state    = "waiting"
    goAt     = singeGetTicks() + math.random(WAIT_MIN, WAIT_MAX)
    score    = 0
    top      = nil
    standing = nil
    saying   = ""
    scoreBegin()
end


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state  = "result"
        score  = 0
        saying = "Too soon.  Nothing posted."
    elseif state == "go" then
        finish(singeGetTicks() - goAt)
    else
        play()
    end
end


function onOverlayUpdate()
    scoreUpdate()

    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST")

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Best on this machine:  " .. best)
    overlayPrint(2, 5, "Posting as:  " .. (scorePlayerName() or "nobody yet"))
    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())
    overlayPrint(2, 8, saying)

    if top then
        for place, row in ipairs(top) do
            if place > 5 then
                break
            end
            overlayPrint(2, 9 + place, place .. ".  " .. row.name .. "  " .. row.value)
        end
    end
    if standing then
        overlayPrint(2, 16, "You are " .. standing.rank .. " of " .. standing.players .. ".")
    end

    return OVERLAY_UPDATED
end

Lancez-le avec Singe -R reaction. Sur une machine qui ne s’est jamais connectée, il se joue, il garde votre meilleur score, et il dit Kept here only: this machine is not signed in. C’est l’exécution importante, et c’est celle qu’auront la plupart de vos joueurs.

Ce qui vient de se passer

local top      = nil
local standing = nil

Deux variables qui valent nil la plupart du temps. nil veut dire « rien ici », et c’est ce que contient une variable avant qu’on y mette quoi que ce soit. Celles-ci contiennent le tableau quand il y en a un, et nil quand il n’y en a pas : pendant que la requête est en route, après un échec, et avant la première partie. Le code de dessin demande if top then et ne dessine rien quand il n’y a rien, ce qui est la forme de presque tout le code réseau que vous écrirez.

    saying   = "Asking the service..."
    scoreBoard(function(ok, result)

L’ordre compte. La ligne de texte est réglée avant l’appel, parce que l’appel rend la main aussitôt et que le callback peut ne s’exécuter que des secondes plus tard. Si vous ne réglez le texte que dans le callback, l’écran montre le message de la partie précédente jusqu’à ce que la réponse arrive, ce qui est exactement le mauvais message au mauvais moment.

        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end

L’échec vient en premier, et il est court. tostring transforme ce qui est revenu en texte, pour que le joindre avec .. ne puisse pas échouer ; result est une chaîne quand ok vaut false, mais une ligne de code de dessin qui fait confiance au type de quelque chose reçu d’un serveur est une ligne qui attend de planter. Le joueur voit une phrase, et le jeu continue.

    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end

Que scoreSubmit réponde false n’est pas une erreur. C’est un fait concernant cette machine, et les deux faits qu’il peut signifier valent d’être distingués, ce que fait whyNotPosted : un GAME_ID manquant est votre erreur, et une machine non connectée n’est l’erreur de personne. Le meilleur score local a déjà été sauvegardé, deux lignes plus haut, avant toute tentative. Sauvegardez d’abord, envoyez ensuite, toujours.

    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())

La file d’attente, à l’écran. Sur une machine qui a une connexion, cela affiche 0 pour toujours et personne ne le remarque. Sur une machine qui n’en a pas, le nombre monte, et le joueur sait que le jeu garde ses scores au lieu de les avaler.

function onOverlayUpdate()
    scoreUpdate()

Première ligne de l’image, avant tout le reste. Mettez-la à un endroit où aucun if ne peut la sauter, parce qu’un scoreUpdate qui ne s’exécute que sur l’écran de fin de partie, c’est une file d’attente qui ne se vide que sur l’écran de fin de partie.

Essayez

  1. Débranchez la prise. Déconnectez la machine du réseau, jouez quelques parties, et regardez le nombre Waiting to send. Rebranchez-la et regardez-le descendre sans que vous fassiez quoi que ce soit.

  2. Supprimez l’identifiant. Retirez GAME_ID de votre games.dat et relancez. Le message change. Remettez-le.

  3. Montrez plus du tableau. La boucle s’arrête à cinq lignes. L’overlay fait par défaut dix-huit lignes de caractères de haut, alors calculez combien vous pouvez vraiment en faire tenir, et déplacez la ligne standing s’il le faut.

  4. Nommez le tableau. scoreSubmit(score, "reaction") et scoreBoard(onDone, "reaction") utilisent un tableau de ce nom au lieu de celui qui porte le nom de votre script. Envoyez vers deux tableaux depuis le même jeu — par exemple un pour le score et un pour la réaction la plus rapide — et laissez le bouton 2 choisir lequel est affiché.

  5. Rendez l’attente visible. Entre l’appel à scoreBoard et l’exécution du callback, dessinez un point qui bouge. Puis découvrez combien de temps cela dure vraiment sur votre connexion, et si ça valait la peine de le dessiner.

Cassez-le exprès

Retirez la première ligne de onOverlayUpdate, pour que l’appel à scoreUpdate() disparaisse, et jouez une partie.

Il ne se passe rien. Pas d’erreur, pas de message, pas de tableau, et le nombre Waiting to send monte et reste en haut pour toujours. Le jeu se joue parfaitement.

C’est la pire sorte de bug, et elle vaut la peine d’être rencontrée une fois exprès : une étape manquante qui produit du silence plutôt qu’une plainte. Il n’y a aucun numéro de ligne à regarder, parce que rien ne s’est mal passé — vous avez demandé du travail et ne lui avez jamais laissé l’occasion de se faire. Quand quelque chose dans Singe qui prend un callback ne vous rappelle jamais, la première question est toujours de savoir si ce qui le fait avancer s’exécute à chaque image.

L’autre, que vous rencontrerez aussi, est plus bruyant. Remettez scoreUpdate(), supprimez la ligne dofile en haut, et lancez :

Error executing function 'onOverlayUpdate':  reaction/reaction.singe:89: attempt to call a nil value (global 'scoreUpdate')
stack traceback:
	reaction/reaction.singe:89: in function 'onOverlayUpdate'

La ligne 89 est le scoreUpdate() que vous avez remis, une ligne plus haut maintenant que le dofile a disparu. Lisez la première ligne, comme toujours : la fonction que le moteur appelait, le fichier, la ligne et la plainte. Encore nil — le nom scoreUpdate ne contient rien, parce que le fichier qui le définit n’a jamais été chargé. Les six appels vivent tous dans Singe/Framework.singe.

Ce que vous avez appris

  • Le service détient un compte, un catalogue et des tableaux des meilleurs scores. Ce n’est pas du multijoueur, ni un nuage de sauvegardes, et il n’est jamais obligatoire.

  • Le compte appartient à la machine, et on s’y connecte depuis les outils de service du menu. Un jeu ne demande jamais de mot de passe.

  • Un tableau est rangé sous GAME_ID dans games.dat, un UUID qui ne doit jamais changer. singeGetGameId() le lit.

  • scoreSubmit met un score en file d’attente sur le disque et rend la main aussitôt ; la file d’attente survit à l’extinction de la machine.

  • scoreUpdate() doit s’exécuter à chaque image, sinon rien de ce que fait le service ne se termine jamais.

  • scoreBoard donne sa réponse à une fonction que vous écrivez, et qui s’exécute plus tard. Dessinez quelque chose en attendant.

  • Chaque appel réseau peut échouer, et échouer n’est pas une erreur. Dites une courte ligne et continuez à jouer.

  • Un score envoyé est une déclaration, et le service le traite comme tel.

  • Gardez le meilleur score local. C’est celui qui marche toujours.

La prochaine fois

Un meilleur score, c’est un nombre, et la sauvegarde de la leçon douze est le bon endroit pour lui. La leçon vingt-neuf est pour tout le reste de ce qu’un jeu veut garder : chaque manche jouée par qui que ce soit, les niveaux que vous livrez, et les questions que vous voulez poser aux deux. Elle reprend ce test de réflexes et lui donne une base de données.

Leçon 29 : Garder des données

La leçon terminée

La leçon douze sauvegardait un meilleur score : un nombre, sous un nom, toujours là le lendemain matin. C’est exactement ce qu’il faut pour un meilleur score, et ce qu’il ne faut pas pour presque tout le reste de ce qu’un jeu veut garder. Une liste de toutes les parties que quelqu’un a jouées. Le meilleur temps sur chacun de vingt circuits. Quarante niveaux que quelqu’un a conçus dans un tableur. La question « quel est mon meilleur score sur l’épreuve difficile ? », à laquelle une pile de nombres sauvegardés ne peut pas répondre sans que vous écriviez la réponse à la main.

C’est à ça que sert une base de données, et Singe en a une intégrée. Cette leçon reprend le test de réaction de la leçon vingt-huit, lui donne des épreuves livrées avec le jeu, et lui fait garder chaque partie jouée par qui que ce soit et répondre à des questions à leur sujet.

Ce qu’est une base de données

Une base de données est un fichier de tables. Une table, ce sont des lignes et des colonnes, comme un tableur dont les noms de colonnes sont décidés à l’avance : une table de parties pourrait avoir une épreuve, un score et une heure pour chaque ligne. Vous y mettez des lignes et vous posez des questions pour en faire sortir, et les questions s’écrivent en SQL, un petit langage qui fait ce travail depuis avant la plupart des langages de programmation dont vous avez entendu parler.

La base de données que Singe emporte avec lui est SQLite. Ce n’est pas un serveur qu’on installe ni un service auquel on s’inscrit. C’est une bibliothèque, la base de données est un fichier ordinaire, et le même SQLite se trouve dans votre téléphone, dans votre navigateur et probablement dans votre voiture. Vous n’avez pas besoin de connaître le SQL pour suivre cette leçon ; chaque instruction y est expliquée au passage, et les trois dont vous vous servirez le plus — CREATE TABLE, INSERT et SELECT — sont toutes là.

En ouvrir une

local sqlite3 = require("sqlite3")

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

require("sqlite3") charge une bibliothèque fournie avec Singe et vous la rend sous forme de table, si bien que tout ce que SQLite sait faire s’écrit sqlite3. quelque chose. sqlite3.open ouvre un fichier de base de données et le crée s’il n’existe pas encore : le premier lancement de votre jeu en crée un vide, et chaque lancement suivant le retrouve.

Le fichier va dans singeGetDataPath(), pour la même raison que la sauvegarde de la leçon douze : le dossier d’un jeu peut se trouver sur un disque, sur un partage réseau, ou être empaqueté dans un seul fichier, et on ne peut écrire dans aucun d’eux. Tout ce qu’un jeu écrit va dans son dossier de données.

Créer une table

Une base de données vide n’a aucune table. Vous en créez une en la décrivant :

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

exec exécute du SQL qui ne renvoie rien. Les doubles crochets sont la chaîne longue de Lua : tout ce qui se trouve entre eux, retours à la ligne compris, forme une seule chaîne, et c’est comme ça qu’on garde le SQL lisible.

CREATE TABLE nomme la table et ses colonnes, chacune avec un type : TEXT pour les mots et INTEGER pour les nombres entiers. NOT NULL veut dire que chaque ligne doit avoir une valeur à cet endroit. INTEGER PRIMARY KEY est spécial : SQLite le remplit tout seul, en comptant, si bien que chaque ligne reçoit son propre numéro sans que vous ayez à y penser.

IF NOT EXISTS est ce qui permet de l’exécuter sans risque à chaque démarrage du jeu. La première fois, il crée la table. Toutes les fois suivantes, la table est déjà là et la ligne ne fait rien. Sans ces trois mots, le deuxième lancement de votre jeu s’arrêterait sur une erreur disant que la table existe déjà.

Ajouter une ligne

Vous pourriez construire le SQL d’une nouvelle ligne en collant des chaînes bout à bout :

runs:exec("INSERT INTO runs (stage, score, at) VALUES ('" .. stage .. "', " .. score .. ", " .. os.time() .. ")")

Ne le faites pas. Ça marche jusqu’au jour où un nom contient une apostrophe : l’apostrophe termine alors la chaîne trop tôt et l’instruction n’a plus aucun sens. Dans un jeu qui laisse les joueurs taper, c’est pire : tout ce qu’ils tapent devient un morceau de votre SQL.

La bonne manière consiste à écrire l’instruction une fois, avec des points d’interrogation à la place des valeurs, et à passer les valeurs à part :

local addRun = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")

local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
end

prepare transforme le SQL en une instruction qu’on peut utiliser encore et encore. bind_values met une valeur dans chaque point d’interrogation, dans l’ordre. Quoi qu’une valeur contienne, apostrophes comprises, c’est une valeur et jamais un morceau du SQL. step exécute l’instruction, et reset la remet en état d’être exécutée de nouveau. os.time() est du Lua tout simple : l’heure actuelle sous forme de nombre de secondes, ce qui est la façon la plus facile de stocker « quand ».

Préparer une fois et réutiliser l’instruction est aussi plus rapide, parce que SQLite ne calcule qu’une seule fois comment l’exécuter. Pour un jeu qui écrit une ligne par minute, ça ne compte pas. Pour un éditeur de niveaux qui en écrit mille, si.

Poser des questions

Les lignes ressortent avec nrows, qui exécute un SELECT et vous rend chaque ligne sous forme de table, avec les noms des colonnes comme clés :

for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC LIMIT 5") do
    debugPrint(row.stage .. "  " .. row.score)
end

Lisez le SQL de gauche à droite. SELECT stage, score dit quelles colonnes vous voulez. FROM runs dit quelle table. ORDER BY score DESC trie les lignes par score, le plus haut d’abord, et LIMIT 5 s’arrête après cinq. C’est un tableau des meilleurs scores, et il n’a jamais eu besoin de code de tri de votre part.

Les questions peuvent être plus astucieuses que celles que vous auriez envie d’écrire à la main :

for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
    debugPrint(row.stage .. ":  best " .. row.top .. " of " .. row.tries)
end

GROUP BY stage rassemble les lignes en un groupe par épreuve, et MAX(score) et COUNT(*) sont calculés pour chaque groupe : le meilleur score sur cette épreuve et le nombre de fois qu’elle a été jouée. AS top donne un nom à la réponse, et c’est la clé avec laquelle vous la relisez.

Quand une question n’a qu’une réponse, urows vous rend les colonnes elles-mêmes plutôt qu’une table, ce qui est plus net pour un comptage :

for count in runs:urows("SELECT COUNT(*) FROM runs") do
    played = count
end

Demandez quand ça change

Aucune de ces questions n’a sa place dans onOverlayUpdate. Une requête est rapide, mais soixante par seconde, pour obtenir des réponses qui changent une fois par minute, c’est le jeu qui pose la même question et obtient la même réponse cinquante-neuf fois sur soixante.

Alors le jeu demande quand la réponse a pu changer — une fois au début, et de nouveau chaque fois qu’une partie est enregistrée — et garde ce qui est revenu dans des tables ordinaires :

local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    -- et pareil pour les deux autres questions
end

onOverlayUpdate dessine à partir de best, ce qui ne coûte rien. record appelle refresh après chaque nouvelle ligne, donc le tableau à l’écran n’est jamais périmé.

Les données livrées avec le jeu

L’autre moitié des données d’un jeu, c’est la partie que vous écrivez avant que quiconque y joue : les épreuves, les niveaux, les objets, les répliques des dialogues. Ça aussi, ça peut être une base de données, créée avec n’importe quel outil SQLite — le programme sqlite3 en ligne de commande, ou un programme avec des fenêtres comme DB Browser for SQLite — et rangée dans le dossier de votre jeu à côté de ses images. Le kit graphique en a une, stages.db, avec un nom et l’attente la plus courte et la plus longue de chaque épreuve.

Un jeu ouvre celle-là autrement :

local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

DIR est le dossier de votre jeu, là où sont les images. sqlite3.OPEN_READONLY dit que vous comptez seulement la lire, et ça compte pour le jour où vous publierez. Quand vous empaquetterez votre jeu dans un seul fichier à la leçon suivante, une base de données ouverte en lecture seule sera lue directement dans ce fichier, sans rien dépaqueter. Une base ouverte en écriture est copiée, une fois, dans le dossier de données du jeu, et c’est la copie que vous modifiez à partir de là ; le fichier que vous avez publié n’est jamais écrit.

Alors gardez les deux sortes à part. Ce que vous avez fait va dans votre dossier et s’ouvre en lecture seule. Ce que le jeu fait va dans le dossier de données. Ici, les épreuves sont lues une seule fois au début dans une table ordinaire et la base de données est fermée, parce qu’une liste de quatre épreuves ne vaut pas la peine de garder un fichier ouvert.

Tout fermer

Les instructions et les bases de données gardent de la mémoire et un fichier ouvert jusqu’à ce que vous disiez que vous avez fini, et l’endroit propre pour le dire, c’est onShutdown :

function onShutdown()
    addRun:finalize()
    runs:close()
end

finalize, c’est le close d’une instruction. Une base de données ne se ferme pas tant qu’une instruction créée à partir d’elle existe encore, donc les instructions passent en premier.

Le script complet

Créez un dossier appelé runs, copiez-y le dossier art du livre pour stages.db, et mettez ceci dans runs.singe :

dofile("Singe/Framework.singe")

local sqlite3 = require("sqlite3")

local PERFECT = 1000

-- Ce qui est livré avec le jeu : les épreuves, lues une fois puis fermées.
local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

-- Ce que le jeu écrit : chaque partie jouée, gardée dans le dossier de données.
local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

local addRun   = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")
local stageAt  = 1
local state    = "attract"
local goAt     = 0
local score    = 0
local best     = {}
local perStage = {}
local played   = 0


-- Les questions, posées quand une partie est ajoutée plutôt qu'à chaque image.
local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    perStage = {}
    for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
        perStage[#perStage + 1] = row
    end
    for count in runs:urows("SELECT COUNT(*) FROM runs") do
        played = count
    end
end


local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
    refresh()
end


local function play()
    local stage = stages[stageAt]

    state = "waiting"
    goAt  = singeGetTicks() + math.random(stage.waitMin, stage.waitMax)
    score = 0
end


function onInputPressed(what)
    if what == SWITCH_BUTTON2 and state ~= "waiting" and state ~= "go" then
        stageAt = stageAt % #stages + 1
        return
    end
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)
    elseif state == "go" then
        score = math.max(0, PERFECT - (singeGetTicks() - goAt))
        state = "result"
        record(stages[stageAt].name, score)
    else
        play()
    end
end


function onOverlayUpdate()
    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST:  " .. stages[stageAt].name)

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play, button 2 for another stage.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Runs kept:  " .. played)
    overlayPrint(2, 6, "BEST RUNS")
    for place, row in ipairs(best) do
        overlayPrint(2, 6 + place, string.format("%d.  %-8s %4d", place, row.stage, row.score))
    end
    overlayPrint(24, 6, "BY STAGE")
    for line, row in ipairs(perStage) do
        overlayPrint(24, 6 + line, string.format("%-8s best %4d of %d", row.stage, row.top, row.tries))
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    addRun:finalize()
    runs:close()
end


refresh()

Lancez-le avec Singe -R runs. Le bouton 1 lance une manche et l’arrête, comme à la leçon vingt-huit, et le bouton 2, entre les manches, passe à l’épreuve suivante. Jouez-en quelques-unes sur chaque épreuve. Puis quittez et relancez : chaque partie est toujours là, les cinq meilleures à gauche et le meilleur score de chaque épreuve à droite.

Ce qui vient de se passer

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

Deux fichiers sont en jeu, et ils ne se ressemblent pas. art/stages.db est à vous : vous l’avez écrit, il est livré avec le jeu, et le jeu ne fait que le lire. runs.db est au jeu : il n’existait pas avant que le premier lancement le crée, il vit dans le dossier de données, et personne ne le publie.

    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)

Un bouton pressé trop tôt enregistre quand même une partie, avec un score de rien du tout. La base de données garde la trace de ce qui s’est passé, et un faux départ a bien eu lieu. Montrer ou non ces lignes, c’est une question pour le SELECT, pas quelque chose à cacher en ne les écrivant jamais.

    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do

ORDER BY score DESC, id trie par score et, quand deux scores sont égaux, par id — l’ordre dans lequel les parties ont été jouées. Sans la seconde clé, deux scores égaux reviennent dans l’ordre qui arrange SQLite, et cet ordre peut changer d’un lancement à l’autre. Un tableau qui se remélange sans raison visible a l’air cassé, même quand il ne l’est pas.

Essayez

  1. Affichez la date. os.date("%Y-%m-%d", row.at) retransforme une heure stockée en quelque chose qu’une personne peut lire. Ajoutez la date à chacune des meilleures parties.

  2. Ignorez les faux départs. Ajoutez WHERE score > 0 à la question des meilleures parties, entre FROM runs et ORDER BY. Puis comptez les faux départs sur chaque épreuve avec une question de votre cru.

  3. Ajoutez une épreuve. Ouvrez stages.db dans un outil SQLite, ajoutez une ligne, et lancez le jeu. Rien ne change dans le script. C’est tout l’intérêt de garder les données hors du script.

  4. Remettez l’historique à zéro. runs:exec("DELETE FROM runs") vide la table. Mettez-le sur un bouton, appelez refresh juste après, et regardez tout retomber à rien. C’est le « remettre à zéro les meilleurs scores » d’un menu de service.

  5. Écrivez mille lignes. Appelez record mille fois dans une boucle et chronométrez avec singeGetTicks. Puis mettez runs:exec("BEGIN") avant la boucle et runs:exec("COMMIT") après, et chronométrez de nouveau. Une transaction fait de nombreuses écritures une seule, et la différence est assez grande pour mériter qu’on s’en souvienne.

Cassez-le exprès

Retirez addRun:reset() de record et jouez trois manches sur trois épreuves différentes.

Aucune erreur. Le jeu tourne parfaitement. Mais le tableau de droite dit que vous avez joué la première épreuve trois fois, et les meilleures parties sont trois copies de votre premier score. bind_values n’a pas pu mettre de nouvelles valeurs dans une instruction déjà exécutée et pas remise à zéro, alors il a abandonné — en silence, en renvoyant un nombre que vous ne vérifiiez pas — et step a exécuté l’instruction de nouveau avec les valeurs qu’elle avait déjà.

C’est le bogue qui compte dans cette leçon, parce qu’il n’en a pas l’air. Une requête qui échoue fait du bruit. Une écriture qui écrit la mauvaise chose est silencieuse, et vous la découvrez une semaine plus tard dans les données. Quand les lignes d’une base de données ne sont pas celles que vous attendez, regardez le code qui les y a mises avant le code qui les lit.

Remettez reset, et cassez-le de la manière bruyante : changez score en scroe dans le premier SELECT de refresh.

Error running script:  no such column: scroe
stack traceback:
	[C]: in method 'nrows'
	runs/runs.singe:42: in local 'refresh'
	runs/runs.singe:132: in main chunk

SQLite lit les noms de colonnes quand il prépare la question, donc un nom mal orthographié arrête le jeu tout de suite, et le message le nomme exactement. La trace de pile se lit de l’intérieur vers l’extérieur : nrows s’est plaint, refresh l’a appelé à la ligne 42, et le script lui-même a appelé refresh à la ligne 132, la dernière, au démarrage du jeu. C’est pour ça que le message dit running script au lieu de nommer une fonction que le moteur a appelée : le jeu n’est jamais arrivé jusqu’à la première image.

Ce que vous avez appris

  • Une base de données est un fichier de tables ; une table, ce sont des lignes avec des colonnes qui ont un nom.

  • require("sqlite3") vous donne SQLite. sqlite3.open ouvre un fichier et le crée s’il manque.

  • Ce que le jeu écrit va dans singeGetDataPath(). Ce que vous publiez va dans votre dossier, ouvert avec sqlite3.OPEN_READONLY.

  • CREATE TABLE IF NOT EXISTS s’exécute sans risque à chaque démarrage du jeu.

  • Les valeurs entrent par prepare, bind_values, step et reset, jamais en collant des chaînes dans le SQL.

  • nrows rend les lignes sous forme de tables ; urows rend les colonnes elles-mêmes.

  • ORDER BY, LIMIT, GROUP BY, MAX et COUNT répondent aux questions pour lesquelles vous écririez sinon des boucles.

  • Demandez quand la réponse peut changer, pas à chaque image.

  • Dans onShutdown, on finalise les instructions, puis on ferme la base de données.

La prochaine fois

Votre jeu a maintenant un dossier plein de choses : un script, des images, des sons, et une base de données ou deux. La leçon trente transforme ce dossier en un seul fichier qu’un inconnu peut copier sur sa propre machine et jouer — et votre base de données en lecture seule part avec, et s’ouvre toujours exactement comme maintenant.

Leçon 30 : Le publier

La leçon terminée

Vous avez un dossier. Il contient un script, quelques images, quelques sons, et le games.dat que vous avez écrit à la leçon treize. Il tourne, parce que tout ce dont il a besoin est là où vous l’avez laissé et que vous savez où c’est.

Cette leçon transforme ce dossier en un seul fichier que quelqu’un qui ne vous a jamais rencontré peut copier sur sa machine et jouer. L’essentiel tient en deux lignes de commande. Le reste, c’est la partie que personne n’enseigne : ce qui a sa place dans le fichier, le travail de qui s’y trouve à part le vôtre, et comment savoir s’il marche ailleurs qu’ici.

Un seul fichier

Un jeu Singe fini se publie sous la forme d’un seul fichier .game. En empaqueter un, c’est :

Singe --pack MyGame MyGame.game

Le premier nom est le dossier de votre jeu, le second est le fichier à écrire. Singe lit chaque fichier du dossier dans une base de données et dit ce qu’il a fait :

>>> Packed 42 files (3819204 bytes) from MyGame into MyGame.game

Lancez-le de la même façon que vous lancez n’importe quoi :

Singe MyGame.game

Ça lance la première entrée du games.dat qu’il contient ; --entry=2 lance la deuxième, pour un fichier qui contient plus d’un jeu. Pour l’installer, le joueur copie MyGame.game à côté du programme Singe. Le menu fourni le trouve et l’affiche dans sa liste. Il n’y a rien d’autre : pas d’installateur, pas d’archive à décompresser, pas de dossier à mettre au bon endroit.

Ce que l’empaquetage fait à chaque nom de fichier

Rien dans votre jeu n’a besoin de changer pour être empaqueté, et ça vaut la peine de savoir pourquoi, parce que c’est ce qui risque le plus de vous surprendre.

Chaque nom qu’utilise votre jeu — dofile, require, io.open, spriteLoad, soundLoad, fontLoad, videoLoad, un framefile, un controls.cfg — passe par une seule et même recherche. Pour un dossier non empaqueté, cette recherche est le simple système de fichiers. Pour un jeu empaqueté, le nom est essayé à trois endroits et le premier trouvé l’emporte :

  1. un dossier non empaqueté qui porte le nom du fichier sans son extension — MyGame/ à côté de MyGame.game ;

  2. le dossier de données du jeu, sous files/, qui est l’endroit où atterrit tout ce que le jeu écrit ;

  3. la base de données elle-même.

Dans la base de données, les noms sont comparés sans tenir compte des majuscules, avec l’une ou l’autre sorte de barre oblique, et relativement à la racine du jeu. Un nom de dossier en tête égal à celui du jeu lui-même est ignoré, si bien que MyGame/art/spaceship.png, art/spaceship.png et DIR .. "art/spaceship.png" trouvent tous le même fichier.

Deux règles en découlent, et si vous avez suivi le livre, vous obéissez déjà aux deux. Utilisez DIR pour tout ce que vous chargez, pour qu’un nom ne dépende jamais de l’endroit d’où Singe a été lancé. Et n’écrivez que sous singeGetDataPath(), là où saveSet range déjà les choses — un jeu empaqueté est ouvert en lecture seule et n’est jamais écrit, si bien qu’un jeu qui sauvegarde à côté de lui-même marche non empaqueté et échoue empaqueté.

Deux sortes de noms vont ailleurs exprès. Tout ce qui commence par Singe/ reste sur le vrai système de fichiers, si bien que dofile("Singe/Framework.singe") continue de marcher, et le dossier de données aussi. Et un nom contenant .. qui essaie de sortir du jeu ne mène nulle part : io.open renvoie nil et un message disant que le nom sort du jeu, et spriteLoad et ses semblables signalent le fichier comme manquant.

Le dossier non empaqueté l’emporte toujours

Cette première place dans la liste est celle dont vous vous servirez tous les jours. Un dossier qui porte le nom du fichier empaqueté, posé à côté de lui, l’emporte sur les copies empaquetées, fichier par fichier.

MyGame.game        le jeu empaqueté
MyGame/            un dossier avec un seul fichier modifié dedans

Déposez-y un seul art/spaceship.png corrigé et le jeu empaqueté tourne avec votre nouvelle image et tout le reste tiré de la base de données. Rien n’a besoin d’être réempaqueté pour essayer une modification, et vous pouvez garder là tout votre dossier de travail pendant que vous finissez le jeu. C’est aussi comme ça qu’un joueur en fait un mod, ce que vous considérerez ou non comme une fonctionnalité.

Deux choses en découlent. Vérifiez votre jeu une fois avec ce dossier renommé, sinon vous publierez un fichier qui ne marche que sur la machine qui a le dossier. Et sachez que l’empaquetage ne cache rien : --unpack est une option documentée et n’importe qui peut s’en servir. Empaquetez votre jeu parce qu’il tient en un seul fichier, pas parce qu’il serait verrouillé.

Corriger un jeu publié

Quelqu’un a votre jeu, il y a un bogue dans un script, et vous n’avez pas envie de lui renvoyer quarante mégaoctets.

Singe --patch MyGame.game fixes

fixes est un dossier organisé comme le jeu — les mêmes noms aux mêmes endroits — qui ne contient que les fichiers qui ont changé. Les fichiers que le correctif ne nomme pas sont laissés tels quels. Tout le changement est une seule transaction, si bien qu’un correctif interrompu laisse le jeu exactement comme il était, plutôt qu’à moitié remplacé.

Un correctif peut voyager dans un fichier à lui, créé avec l’empaqueteur :

Singe --pack fixes MyGame-1.0.2.patch
Singe --patch MyGame.game MyGame-1.0.2.patch

Un .patch n’a pas besoin de games.dat, ne peut pas être lancé, et le menu l’ignore. Il peut aussi porter une table removed(path) qui nomme des fichiers à supprimer, pour les images que vous avez remplacées par quelque chose qui porte un autre nom. Dans tous les cas, Singe vérifie ensuite le jeu corrigé de la même manière qu’il vérifie un nouveau jeu, si bien qu’un correctif ne peut pas laisser votre games.dat pointer vers un fichier qui n’est plus là.

Et pour tout ressortir :

Singe --unpack MyGame.game MyGameUnpacked

Ce que l’empaqueteur refuse

L’empaqueteur ne construit pas un jeu à partir de n’importe quoi, et chaque refus concerne quelque chose qui casserait plus tard. Il refuse un dossier sans games.dat à sa racine. Il refuse un Framework.singe, un controls.dat, tout ce qui se termine par exe, sh, bat ou cmd, et un fichier sans extension dont le nom commence par singe — autrement dit, une copie du moteur ou de ses fichiers de support qui s’est égarée dans le dossier de votre jeu. Il refuse deux fichiers dont les noms ne diffèrent que par les majuscules, puisque la recherche ne peut pas les distinguer. Il refuse une entrée de premier niveau qui porte le nom du dossier lui-même. Et il vérifie votre games.dat avant de valider : chaque entrée a besoin d’un SCRIPT, et chaque SCRIPT, VIDEO, CABINET, MARQUEE et ATTRACT qu’elle nomme doit être un fichier qui s’y trouve vraiment. Un mauvais chemin est signalé avec le titre de l’entrée et rien n’est écrit.

Chaque plainte nomme le fichier, et vous en avez la liste complète plutôt que la première seulement, si bien qu’un seul passage vous dit tout ce qu’il faut corriger.

Ce qu’il faut inclure et ce qu’il faut laisser de côté

Regardez dans le dossier de votre jeu. Une partie de ce qu’il contient est le jeu, et une autre partie, c’est la façon dont le jeu a été fait.

À publier : le script et tout ce qu’il charge, le games.dat, les images que montre le menu (CABINET, MARQUEE et le clip ATTRACT), vos fichiers de crédits et de licence, et un lisez-moi si vous en avez un.

À laisser de côté : les dessins dont vous avez exporté les images, les prises de son que vous n’avez pas utilisées, vos notes, les scripts de test, les captures d’écran, tout ce qui s’appelle old ou backup, le dossier data avec vos propres sauvegardes et vos propres meilleurs scores dedans, et tout ce que vous ne voudriez pas qu’un inconnu lise. Tout cela s’empaquette parfaitement bien, et c’est justement le problème : ça part avec le jeu, et n’importe qui y a accès en un --unpack.

La façon fiable de savoir ce que vous avez vraiment publié, c’est de le désempaqueter dans un dossier vide et de regarder. Faites-le une fois pour chaque version publiée. Ça prend une minute, et c’est la seule vérification qui voit ce que vous avez oublié plutôt que ce dont vous vous souvenez.

Crédits et licences

Si des images, des sons, de la musique ou une police de votre jeu ont été faits par quelqu’un d’autre, vous publiez son travail, et les conditions auxquelles il l’a donné sont une obligation plutôt qu’une politesse. Ce n’est pas une formalité et ce n’est pas une affaire d’avocats : une personne a fait cette chose et a demandé une seule chose précise en retour, en général son nom.

Tenez un registre pendant que vous travaillez, pas à la fin. Un simple fichier texte dans le dossier du jeu, avec une ligne par élément : ce qu’est le fichier, d’où il vient, qui l’a fait, quelle licence, et ce que cette licence exige. L’écrire au fur et à mesure prend quelques secondes. Le reconstituer la veille d’une sortie, à partir d’un historique de navigateur, c’est comme ça que des crédits se perdent.

Quelques choses à savoir avant d’en avoir besoin. « Téléchargement gratuit » n’est pas une licence ; cherchez les vraies conditions. Creative Commons BY veut dire que vous devez donner le crédit indiqué, et il n’y a pas d’exception pour les jeux. CC0 et le domaine public ne demandent rien, et créditer quand même vous coûte une ligne. Les polices ont leurs propres licences, et certaines permettent de les embarquer alors que d’autres non. Vous n’avez presque jamais le droit d’utiliser la musique d’une vidéo. Tout ce qu’un outil a généré n’est pas plus propre que les conditions de cet outil.

Ensuite, mettez les crédits quelque part où un joueur peut les atteindre, dans le jeu. Pas seulement dans un fichier texte à côté — un jeu empaqueté est un seul fichier, et le fichier texte est dedans, là où personne ne regardera. Le script à la fin de cette leçon est cet écran-là.

Le Singe/LICENSES de Singe lui-même est la forme à copier : une ligne par bibliothèque, avec sa version, sa licence et sa provenance. La liste de votre jeu sera plus courte, et le travail est le même.

Un numéro de version qui veut dire quelque chose

Votre jeu aura une deuxième version. La première circulera aussi longtemps qu’internet existera, et quelqu’un vous enverra un rapport de bogue à son sujet sans avoir la moindre idée de la version qu’il a.

Alors choisissez un numéro, mettez-le là où un joueur peut le lire, et n’en réutilisez jamais un. Trois parties, c’est la forme courante — 1.0.2 — et ce que veulent dire les parties compte moins que le fait qu’elles ne font que monter. Augmentez la dernière pour une correction, celle du milieu pour quelque chose de nouveau, la première quand vous avez fait un autre jeu. Quoi que vous choisissiez, notez-le dans votre lisez-moi, pour que le vous du futur s’y tienne aussi.

games.dat n’a pas de clé de version, alors c’est à vous de porter le numéro. Mettez-le dans le script sous forme de constante, affichez-le sur l’écran des crédits, et mettez-le dans le nom de ce que vous envoyez (MyGame-1.0.2.game, MyGame-1.0.2.patch). Le rapport de bogue donne alors la version affichée à l’écran, et vous savez de quels fichiers il parle.

Tester sur une machine qui n’est pas la vôtre

Votre machine est le pire endroit possible pour tester une version. Elle a les polices que vous avez installées, le dossier que vous étiez en train de modifier, le fichier de sauvegarde avec vos réglages dedans, et le moteur dans l’état où un mois de travail l’a laissé.

Le test minimum, dans l’ordre :

  1. Désempaquetez la version dans un dossier vide et lisez la liste des fichiers.

  2. Copiez uniquement le fichier .game dans un autre dossier, avec une copie neuve de Singe et rien d’autre, et lancez-le depuis le menu comme le fera un joueur.

  3. Supprimez le dossier data de ce dossier et relancez. C’est un premier lancement sur une machine neuve : pas de réglages sauvegardés, pas de meilleurs scores, pas de compte connecté. Un jeu qui ne marche qu’à son deuxième lancement est un bogue courant, et c’est comme ça qu’on le trouve.

  4. Donnez-le à une personne qui ne l’a jamais vu, et regardez sans l’aider.

Puis testez la machine autant que le jeu. Elle aura un écran d’une autre forme, alors regardez votre jeu en fenêtre et en plein écran. Elle n’aura peut-être aucun périphérique 3D, et c’est pour ça que le menu propose un second moteur de rendu. La page System Information des outils de service affiche sur un seul écran la version du moteur, le système d’exploitation, le processeur, le moteur de rendu, les décodeurs et le dossier de données ; une photo de cette page répond à presque tout un rapport de bogue, et le dire à vos joueurs dans votre lisez-moi vous épargnera une semaine de devinettes.

Le script

Un écran de crédits et de version. C’est peu de chose à écrire, et c’est la partie de la publication que la plupart des jeux ratent.

dofile("Singe/Framework.singe")

local GAME_NAME    = "Rock Dodger"
local GAME_VERSION = "1.0.2"

local CREDITS = {
    "Written and drawn by   <your name here>",
    "",
    "Music                  \"Night Drive\" by A. Composer",
    "                       Creative Commons BY 4.0",
    "                       example.org/night-drive",
    "",
    "Explosion              freesound.org user \"thud\"",
    "                       Creative Commons CC0",
    "",
    "Font                   FreeSansBold",
    "                       GPL with the font exception",
    "",
    "Engine                 Singe " .. SINGE_VERSION_STRING,
    "                       GPL version 3",
    "                       See Singe/LICENSES for the",
    "                       libraries Singe is built on.",
    "",
    "Thank you for playing.",
}

local FIRST_ROW = 4
local ROWS      = 10

local scroll = 0


local function scrollBy(lines)
    local most = #CREDITS - ROWS

    if most < 0 then
        most = 0
    end
    scroll = scroll + lines
    if scroll < 0 then
        scroll = 0
    end
    if scroll > most then
        scroll = most
    end
end


function onInputPressed(what)
    if what == SWITCH_UP then
        scrollBy(-1)
    elseif what == SWITCH_DOWN then
        scrollBy(1)
    elseif what == SWITCH_BUTTON1 then
        scroll = 0
    end
end


function onOverlayUpdate()
    local line = nil

    overlayClear()
    overlayPrint(2, 0, GAME_NAME .. "  version " .. GAME_VERSION)
    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then
            overlayPrint(2, FIRST_ROW + row, line)
        end
    end

    overlayPrint(2, FIRST_ROW + ROWS + 1, "Saves go to:")
    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())
    overlayPrint(2, 17, "Up and down scroll.  Button 1 goes back to the top.")

    return OVERLAY_UPDATED
end

Remplacez chaque ligne de CREDITS par la vérité sur votre propre jeu. Les textes provisoires sont là pour montrer la forme : ce que c’est, qui l’a fait, quelle licence, et d’où ça vient.

Ce qui vient de se passer

local GAME_VERSION = "1.0.2"

Un seul endroit, en haut, en majuscules parce que la valeur ne change jamais pendant que le jeu tourne. Tout ce qui affiche la version lit ceci, si bien que l’augmenter demande une seule modification plutôt qu’une recherche.

    "Music                  \"Night Drive\" by A. Composer",

Ces barres obliques inverses sont la séquence d’échappement que vous avez rencontrée à la leçon un : un guillemet double qui fait partie du texte au lieu de terminer la chaîne. Les titres contiennent des guillemets, et c’est pour ça qu’une liste de crédits tombe dessus dès sa première ligne.

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then

Dix lignes d’écran qui montrent dix lignes d’une liste plus longue que dix. scroll indique jusqu’où la fenêtre est descendue dans la liste. Le + 1 est là parce que Lua compte une liste à partir de un et que les lignes de l’écran comptent à partir de zéro, et le if line then est là parce que la fin de la liste vaut nil — lire au-delà de la fin d’une table n’est pas une erreur en Lua, ça ne vous donne simplement rien, mais afficher ce rien en serait une.

    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

Trois faits dont un rapport de bogue a besoin et qu’un joueur ne peut pas trouver autrement : votre version sur la ligne du dessus, la version du moteur, et l’identifiant du jeu. SINGE_VERSION_STRING est une globale que le moteur définit avant que votre script tourne. or "none" couvre le cas où le jeu n’a pas d’entrée dans games.dat, pour que la ligne s’affiche au lieu de planter sur un nil.

    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())

L’endroit où ce jeu écrit. Pour un jeu empaqueté, c’est le seul endroit où quoi que ce soit est écrit, et c’est le dossier qu’un joueur supprime pour repartir de zéro. L’afficher transforme « où sont mes sauvegardes ? » en une question à laquelle vous n’aurez jamais à répondre.

Si ce chemin dépasse à droite de l’écran, ce n’est pas cassé : overlayPrint laisse tomber les caractères qui dépasseraient du bord. L’overlay par défaut fait soixante cellules de caractère de large.

Essayez

  1. Empaquetez-le. Mettez ce script dans le dossier de votre jeu, lancez --pack, et lancez le fichier .game. Puis désempaquetez-le dans un dossier vide et lisez la liste de ce qui en est sorti.

  2. Remplacez un fichier. À côté du fichier empaqueté, créez un dossier qui porte son nom sans l’extension, et mettez-y un fichier modifié. Lancez le jeu empaqueté et regardez votre fichier non empaqueté l’emporter.

  3. Faites un correctif. Passez la version à 1.0.3, mettez seulement le script dans un dossier fixes, empaquetez-le en .patch, et appliquez-le au jeu que vous avez déjà fait. Vérifiez la version à l’écran.

  4. Cassez l’empaqueteur. Renommez votre games.dat un instant et essayez d’empaqueter. Puis remettez-le, faites pointer l’un de ses noms SCRIPT vers un fichier qui n’existe pas, et réessayez. Deux refus différents, tous les deux avant que quoi que ce soit soit écrit.

  5. Écrivez les vrais crédits. Parcourez le dossier de votre jeu fichier par fichier et écrivez une ligne pour chacun de ceux que vous n’avez pas faits. Si vous ne vous rappelez plus d’où vient quelque chose, vous savez maintenant si vous devriez le publier.

Cassez-le exprès

Lancez Singe une fois depuis l'intérieur du dossier de votre jeu, pour que le moteur y extraie ses fichiers de support, puis empaquetez-le :

Singe --pack MyGame MyGame.game
!!! MyGame has Framework.singe:  Singe/Framework.singe
!!! MyGame has sh file:  Menu.sh

Rien n’est écrit. Chaque ligne donne un fichier qu’il refuse et la raison, et vous pouvez les recevoir dans n’importe quel ordre, ou en avoir d’autres en plus. Il y a une copie du dossier de support du moteur lui-même dans votre jeu, et le script de lancement que le moteur a écrit à côté, parce que vous avez lancé Singe depuis là à un moment donné. Un jeu ne doit jamais emporter ni l’un ni l’autre : les fichiers de support appartiennent au Singe que lance le joueur, quel qu’il soit, pas à votre jeu, et un Framework.singe empaqueté serait chargé à la place du sien. Sous Windows, la seconde ligne nomme Menu.bat à la place.

Supprimez le dossier Singe et Menu.sh (ou Menu.bat) de l’intérieur de votre jeu, gardez le dossier de votre jeu comme un dossier à côté du programme Singe plutôt qu’autour de lui, et empaquetez de nouveau. C’est la même organisation que celle que décrivait la leçon treize, et cette erreur est ce qui arrive quand elle se dérègle.

Ce que vous avez appris

  • Singe --pack folder name.game transforme un dossier de jeu en un seul fichier, et copier ce fichier à côté du programme Singe l’installe.

  • Chaque nom de fichier d’un jeu empaqueté est cherché d’abord dans un dossier non empaqueté, puis dans le dossier de données, puis dans la base de données.

  • Un dossier non empaqueté qui porte le nom du fichier empaqueté l’emporte sur lui fichier par fichier, et c’est comme ça que vous continuez à travailler — et comme ça que vous publiez une version cassée si vous oubliez qu’il est là.

  • Chargez avec DIR et n’écrivez que sous singeGetDataPath(), sinon votre jeu marchera non empaqueté et échouera empaqueté.

  • --patch remplace des fichiers d’un jeu publié en une seule transaction ; --unpack ressort tout.

  • L’empaqueteur refuse les fichiers du moteur, les conflits de noms, et un games.dat qui pointe vers des fichiers qu’il n’a pas.

  • Désempaquetez votre propre version et lisez ce qu’elle contient avant de l’envoyer où que ce soit.

  • Les images et les sons de quelqu’un d’autre viennent avec des conditions, et les respecter veut dire un écran de crédits dans le jeu.

  • Un numéro de version ne fait que monter, et sa place est à l’écran.

  • Testez sur une machine qui n’est pas la vôtre, en commençant sans aucun dossier data.

La prochaine fois

Un seul fichier, installé, crédité et numéroté. La dernière leçon le met dans une caisse en bois avec une fente à pièces et sans clavier, ce qui change plus de choses dans votre jeu que vous ne le pensez.

Leçon 31 : Dans une borne

La leçon terminée

Il y a une différence entre un jeu et une machine d’arcade, et ce n’est pas le bois. Une machine s’allume toute seule le matin, joue pour une salle vide, prend une pièce à quelqu’un qui n’a jamais lu un mot à son sujet, et tourne encore à minuit sans que personne ait touché un clavier, parce qu’il n’y a pas de clavier. Tout ce qui se trouve dans cette leçon en découle.

Vous n’avez pas besoin d’une borne pour faire quoi que ce soit de tout ça. Un stick et deux boutons sur un bureau, ou une manette, suffisent pour trouver chaque erreur de cette leçon, et presque tout ce que vous apprenez ici rend aussi un jeu meilleur sur un ordinateur de bureau.

Il n’y a pas de clavier

Commencez par ce qui manque, parce que c’est ce qui casse les jeux.

Une borne a un stick, quelques boutons, une porte de monnayeur, un bouton start, et quelque part à l’intérieur un petit bouton que l’exploitant peut atteindre. C’est tout. Pas d’Échap, pas de lettres, pas de souris, aucun moyen de taper. Donc :

  • Chaque menu de votre jeu doit pouvoir être atteint avec haut, bas et un bouton. Si un écran de votre jeu dit « appuyez sur Y pour continuer », il ne marche pas dans une borne.

  • Entrer ses initiales, c’est trois boutons et une lettre qui défile, pas un champ de texte. C’est pour ça que les jeux d’arcade ont des noms de trois lettres.

  • Un message qui nomme une touche par sa lettre a tort. Dites « bouton 1 », ou dessinez le bouton.

  • Il n’y a pas de sortie. Un joueur ne peut pas quitter, et ne doit pas pouvoir le faire.

Parcourez votre jeu une fois, écran par écran, et demandez-vous pour chacun : est-ce que quelqu’un pourrait s’en sortir avec un stick et un seul bouton ? Ce passage sur votre propre jeu vaut plus que tout le reste de cette leçon.

controls.cfg

Depuis la leçon trois, vous lisez les entrées sous la forme SWITCH_UP, SWITCH_BUTTON1, SWITCH_COIN1 et le reste, et vous n’avez pas dit une seule fois de quelles touches il s’agit. C’est tout leur intérêt. Quelque part entre le microrupteur de la borne et votre onInputPressed, il y a un fichier qui décide, et votre jeu ne prend pas part à cette conversation.

Ce fichier, c’est controls.cfg. C’est du Lua, comme votre script, et c’est une liste de tables — une par contact — qui nomment tout ce qui peut le produire :

INPUT_1P_START = { SCANCODE.MAIN_1, GAMEPAD_0.BUTTON_START }
INPUT_1P_COIN  = { SCANCODE.MAIN_5, GAMEPAD_0.BUTTON_LEFT_BUMPER }
INPUT_ACTION_1 = { SCANCODE.LCTRL, GAMEPAD_0.BUTTON_A }
INPUT_UP       = { SCANCODE.UP, GAMEPAD_0.DPAD_UP, GAMEPAD_0.AXIS_LEFT_Y_U }

Chaque nom INPUT_ du fichier devient la valeur SWITCH_ correspondante dans votre jeu : INPUT_ACTION_1 est le SWITCH_BUTTON1 que vous testez depuis le début, et INPUT_1P_COIN est SWITCH_COIN1. Chaque élément d’une table produit le même contact, donc un jeu ne se soucie pas de savoir si le joueur a appuyé sur la touche, sur le bouton de la manette, ou poussé le stick.

Vous n’avez pas à écrire tout le fichier. Singe part de ses propres valeurs par défaut et lit controls.cfg à quatre endroits tour à tour — le dossier du script du jeu, le dossier depuis lequel Singe a été lancé, le dossier au-dessus du dossier de données du jeu, et le dossier de données du jeu — et chaque fichier qu’il trouve remplace ce qui précède, clé par clé. Ainsi, une borne a un seul fichier en haut pour toute la machine, et un jeu qui a besoin d’un bouton de plus a son propre fichier de quatre lignes. Il y a un controls.cfg.example dans le dossier Singe, à copier.

DEAD_ZONE est là aussi : de combien un stick doit bouger avant de compter comme enfoncé, dans les unités brutes que signale le matériel, où un stick poussé à fond donne 32767. La valeur par défaut est 15000. Un stick usé qui dérive a besoin d’un nombre plus grand, et DEAD_ZONES règle un axe à la fois pour le seul stick qui est fatigué. La section du manuel sur la personnalisation des commandes couvre tout cela.

Chaque périphérique est une manette

Les boutons d’une borne d’arcade sont câblés sur une carte d’encodeur, que l’ordinateur voit comme une sorte de joystick, et ça ne ressemble en rien à une manette Xbox. Singe écrit lui-même une affectation pour un périphérique de ce genre, puis l’ouvre comme GAMEPAD_0, si bien qu’il arrive à controls.cfg et à votre jeu exactement comme une manette reconnue. Il y a une seule famille de périphériques et pas de second vocabulaire à apprendre.

L’affectation qu’il invente est toute simple : les boutons de la carte, dans l’ordre, deviennent BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y et ainsi de suite. Si les boutons de votre borne ne sont pas câblés dans cet ordre, ils sortiront aux mauvais endroits, et la correction n’est pas dans votre jeu : --program écrit dans la trace l’affectation que Singe a créée, sous une forme que vous pouvez modifier et mettre dans un gamecontrollerdb.txt à côté du jeu.

Quand un bouton « ne fait rien », l’outil Input Test du menu répond à la question en cinq secondes. Il montre chaque périphérique que le moteur voit, et le dernier contact qu’un jeu aurait reçu. Soit le contact arrive et votre jeu l’ignore, soit il n’arrive jamais et le problème vient de l’affectation ou du fil.

Quatre contacts ne sont pas à vous

La plupart des contacts vont directement à votre jeu. Quatre, non : le moteur gère lui-même la pause, la sortie, la capture d’écran et le verrouillage de la souris.

La pause est vraiment utile, et gratuite. Tant que le moteur la garde pour lui, la touche affectée à INPUT_PAUSE gèle tout — le disque, chaque vidéo, chaque son et votre script — et affiche son propre indicateur, puis tout repart à l’appui suivant. Tout ce que votre jeu croyait maintenu enfoncé est relâché proprement, puis appuyé de nouveau après, si bien qu’un stick tenu pendant une pause ne reste jamais coincé.

La sortie est celle qu’il faut lui retirer, ce que fait une section plus loin.

Pièces, crédits et départ

Une machine d’arcade a une forme plus ancienne que chacun d’entre nous, et les joueurs la connaissent sans qu’on la leur explique :

  1. Mode attraction. Personne n’est là. La machine montre ce qu’elle est, fait clignoter INSERT COIN, et ne demande rien.

  2. Crédit. Une pièce arrive sous la forme de SWITCH_COIN1. Les pièces deviennent des crédits au tarif que l’exploitant a réglé — pas toujours une pour un.

  3. Partie. SWITCH_START1 dépense un crédit et lance la partie.

  4. Fin de partie. Le score, brièvement, puis retour au mode attraction tout seul. Personne n’appuie sur rien pour en sortir ; le joueur est parti.

Deux détails que les gens ratent. Les pièces sont comptées, pas dépensées : à deux pièces par crédit, une pièce doit rester là à attendre sa partenaire, et un joueur qui en a mis une puis est parti l’a laissée à la personne suivante. Et la machine doit retrouver d’elle-même le chemin du mode attraction, parce que la dernière chose que fait un joueur, c’est d’arrêter de jouer.

Derrière le bouton service

Derrière la porte du monnayeur, il y a un bouton que le joueur ne voit jamais et dont l’exploitant se sert sans arrêt. C’est SWITCH_SERVICE, et le moteur vous le passe directement.

Un exploitant qui ouvre votre menu de service s’attend à y trouver, à peu près dans cet ordre :

  • le prix — pièces par crédit, et un réglage de jeu gratuit pour une machine à la maison ou dans un salon ;

  • la difficulté, parce qu’une machine dans un bar et une machine dans une salle d’arcade ne veulent pas les mêmes réponses ;

  • un moyen d’effacer le tableau des meilleurs scores, la chose la plus demandée de toute cette liste ;

  • ce qu’est la machine — la version du moteur, l’écran, l’endroit où vivent les données — pour qu’un signalement de panne contienne des faits ;

  • une sortie, sans rien éteindre.

Tout ce que change un exploitant doit survivre à une coupure de courant, ce qui, dans une salle d’arcade, veut dire une coupure en pleine partie, sans prévenir, par quelqu’un qui tire sur une prise. saveSet écrit à la fin de l’image, ce qui est assez tôt pour un score et pas assez tôt pour un réglage que quelqu’un vient d’ajuster. saveFlush() écrit immédiatement, et un menu de service est exactement ce à quoi il sert.

Les outils de service du menu fourni, derrière le même bouton, valent la peine d’être connus puisqu’ils sont sur chaque machine où votre jeu tournera : le test des entrées, les tests du son et du pistolet optique, la géométrie de l’affichage, le délai audio, le compte en ligne, et une page qui supprime les données sauvegardées de n’importe quel jeu. Votre menu n’a pas à les refaire.

Une machine qui démarre toute seule et ne quitte jamais

La borne est mise sous tension à la prise. Personne ne se connecte. Un jeu doit être à l’écran au bout d’une minute environ, et y rester.

Faire démarrer Singe à la mise sous tension, c’est le travail de votre système d’exploitation plutôt que celui de Singe — la machine lance le Menu.sh ou le Menu.bat que le moteur écrit à côté de vos jeux, ou bien votre jeu directement. Ce qui est votre travail, c’est ce qui se passe pendant le reste de la journée.

Retirez la touche de sortie :

singeSetQuitKeyEnabled(false)

Le moteur ignore alors le contact affecté à INPUT_QUIT et vous le livre sous la forme de SWITCH_QUIT, comme n’importe quel autre, si bien que vous pouvez demander d’abord, sauvegarder d’abord, ou ne rien faire du tout. Le bouton de fermeture de la fenêtre quitte toujours, quoi que vous régliez, et ça comptera dans une minute.

Ensuite, une poignée d’options appartiennent à la machine plutôt qu’à votre script, et vont dans un settings.cfg à côté des jeux — les mêmes noms que les options de ligne de commande, sans les tirets :

fullscreen  = true
screen      = 2
idleexit    = 900
startsilent = true

idleexit quitte au bout de ce nombre de secondes sans aucune entrée d’aucune sorte, pour une borne qui doit rendre l’écran à un menu ou à un front-end. startsilent démarre en sourdine jusqu’à ce que quelqu’un touche quelque chose, et c’est ce qui rend supportable une salle pleine de machines. Il y en a d’autres ; les sections du manuel sur les réglages et la ligne de commande les listent toutes.

Une illustration autour de l’image

Une vraie borne a un bezel (un habillage d’écran) imprimé autour de l’écran : une illustration percée d’un trou à travers lequel on voit le jeu. Singe en dessine un pour vous.

Singe --bezel cabinet.png MyGame.game

Le fichier est cherché dans un dossier bezels à l’intérieur du jeu — un jeu empaqueté peut emporter le sien — puis dans un dossier bezels du dossier de données, si bien qu’un joueur peut mettre sa propre illustration sur un jeu sans toucher au jeu. À côté de l’image, et nommé d’après elle, un petit fichier Lua dit où va l’image du jeu, en pixels de l’illustration elle-même :

-- bezels/cabinet.cfg
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }

Comme ces nombres sont ceux de l’illustration, ils restent justes à n’importe quelle taille de fenêtre : l’illustration et le trou changent d’échelle ensemble. Sans un tel fichier, l’image du jeu garde toute la fenêtre, comme toujours.

Par défaut, l’illustration est derrière tout et votre jeu couvre le trou. --bezelflip la met devant à la place, si bien que seule sa transparence laisse passer le jeu, ce qu’il vous faut pour des bords adoucis ou découpés — et alors votre overlay est dessous lui aussi, sauf si vous dites le contraire :

if mainBezelLoaded() then
    setOverlayOnTop(true)
end

mainBezelLoaded() vous dit aussi s’il y a une illustration ou non, et c’est comme ça qu’un jeu décide de dessiner son propre cadre quand il n’y en a pas.

Un moniteur sur le côté

Beaucoup de moniteurs d’arcade sont montés à la verticale. Faites tourner toute la présentation :

Singe --rotate=90 MyGame.game

L’image, l’overlay, toute interface, une scène 3D et les particules tournent tous ensemble, et les positions de la souris et du pistolet optique sont tournées en sens inverse, si bien qu’un clic tombe toujours là où le joueur le voit. Un quart de tour échange aussi la forme de la zone, si bien qu’une fenêtre haute est remplie au lieu de n’en occuper qu’une bande entre deux barres noires.

Seuls 0, 90, 180 et 270 sont acceptés. Un script peut la changer en cours de route avec vldpSetRotate, qui répond false pour toute autre valeur plutôt que de mettre fin à votre jeu, et vldpGetRotate() la relit — ce qui vaut la peine d’être mis sur un écran de service, puisque « l’image est sur le côté » et « le moniteur est sur le côté » sont deux pannes différentes.

Ce que la rotation ne fait pas, c’est réécrire votre jeu. Un jeu dessiné pour un écran large, tourné de quatre-vingt-dix degrés, est un jeu large couché sur le côté. Concevoir pour un écran haut, c’est concevoir pour un écran haut.

Le script

Toute la forme : mode attraction, pièce, crédit, partie, fin de partie, service, et une sortie qui demande confirmation. Le jeu au milieu, c’est un bouton et un minuteur de quinze secondes, parce que le jeu n’est pas le sujet cette fois — c’est la machine autour qui l’est.

dofile("Singe/Framework.singe")

local ROUND_MS  = 15000
local MENU      = { "Coins per credit", "Difficulty", "Free play", "Clear high score", "Exit service" }
local HARDNESS  = { "Easy", "Normal", "Hard" }

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)
local best           = saveGet("best", 0)

local state    = "attract"
local goBackTo = "attract"
local coins    = 0
local credits  = 0
local score    = 0
local endsAt   = 0
local item     = 1
local saying   = ""
local hasBezel = false


local function wrap(value, low, high)
    if value < low then
        return high
    end
    if value > high then
        return low
    end
    return value
end


local function canStart()
    return freePlay or credits > 0
end


local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end


local function startGame()
    if not freePlay then
        credits = credits - 1
    end
    score  = 0
    endsAt = singeGetTicks() + ROUND_MS
    state  = "play"
end


local function endGame()
    if score > best then
        best = score
        saveSet("best", best)
    end
    saveFlush()
    endsAt = singeGetTicks() + 5000
    state  = "over"
end


local function settingOf(which)
    if which == 1 then
        return tostring(coinsPerCredit)
    elseif which == 2 then
        return HARDNESS[difficulty]
    elseif which == 3 then
        if freePlay then
            return "on"
        end
        return "off"
    elseif which == 4 then
        return tostring(best)
    end
    return ""
end


local function adjust(step)
    if item == 1 then
        coinsPerCredit = wrap(coinsPerCredit + step, 1, 4)
        saveSet("coinsPerCredit", coinsPerCredit)
    elseif item == 2 then
        difficulty = wrap(difficulty + step, 1, #HARDNESS)
        saveSet("difficulty", difficulty)
    elseif item == 3 then
        freePlay = not freePlay
        saveSet("freePlay", freePlay)
    end
    saveFlush()
end


local function serviceInput(what)
    if what == SWITCH_UP then
        item = wrap(item - 1, 1, #MENU)
    elseif what == SWITCH_DOWN then
        item = wrap(item + 1, 1, #MENU)
    elseif what == SWITCH_LEFT then
        adjust(-1)
    elseif what == SWITCH_RIGHT then
        adjust(1)
    elseif what == SWITCH_BUTTON1 then
        if item == 4 then
            best = 0
            saveSet("best", 0)
            saveFlush()
            saying = "High score cleared."
        elseif item == 5 then
            state = goBackTo
        end
    elseif what == SWITCH_BUTTON2 or what == SWITCH_SERVICE then
        state = goBackTo
    end
end


function onInputPressed(what)
    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

    if state == "confirm" then
        if what == SWITCH_BUTTON2 then
            state = goBackTo
        end
        return
    end

    if state == "service" then
        serviceInput(what)
        return
    end

    if what == SWITCH_SERVICE then
        goBackTo = state
        saying   = ""
        state    = "service"
        return
    end

    if what == SWITCH_COIN1 then
        insertCoin()
        return
    end

    if state == "play" then
        if what == SWITCH_BUTTON1 then
            score = score + 10 * difficulty
        end
        return
    end

    if what == SWITCH_START1 and canStart() then
        startGame()
    end
end


local function drawAttract()
    overlayPrint(2, 2, "ROCK DODGER")
    if canStart() then
        overlayPrint(2, 4, "PRESS START")
    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end
    overlayPrint(2, 6, "High score  " .. best)
end


local function drawService()
    overlayPrint(2, 0, "SERVICE MENU")
    for row, name in ipairs(MENU) do
        if row == item then
            overlayPrint(1, row + 1, ">")
        end
        overlayPrint(3, row + 1, name)
        overlayPrint(24, row + 1, settingOf(row))
    end
    overlayPrint(2, 8, saying)
    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())
    if hasBezel then
        overlayPrint(2, 11, "Bezel artwork loaded.")
    else
        overlayPrint(2, 11, "No bezel artwork.")
    end
    overlayPrint(2, 12, singeGetDataPath())
    overlayPrint(2, 16, "Up/Down choose.  Left/Right change.  Button 1 does it.")
    overlayPrint(2, 17, "Button 2 or the service switch leaves.")
end


function onOverlayUpdate()
    overlayClear()

    if state == "play" and singeGetTicks() >= endsAt then
        endGame()
    elseif state == "over" and singeGetTicks() >= endsAt then
        state = "attract"
    end

    if state == "service" then
        drawService()
    elseif state == "confirm" then
        overlayPrint(2, 2, "QUIT THIS GAME?")
        overlayPrint(2, 4, "Quit again to quit.  Button 2 stays.")
    elseif state == "play" then
        overlayPrint(2, 2, "SCORE  " .. score)
        overlayPrint(2, 3, "TIME   " .. ((endsAt - singeGetTicks()) // 1000))
        overlayPrint(2, 5, "Button 1 scores.  " .. HARDNESS[difficulty] .. ".")
    elseif state == "over" then
        overlayPrint(2, 2, "GAME OVER")
        overlayPrint(2, 4, "You scored " .. score .. ".")
        overlayPrint(2, 6, "High score  " .. best)
    else
        drawAttract()
    end

    if state ~= "service" then
        overlayPrint(2, 17, "CREDITS " .. credits .. "   COINS " .. coins .. "/" .. coinsPerCredit)
    end

    return OVERLAY_UPDATED
end


singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()
if hasBezel then
    setOverlayOnTop(true)
end

Lancez-le et appuyez sur 5 pour une pièce, 1 pour start, et 9 pour le bouton service — ce sont les valeurs par défaut du controls.cfg fourni. Puis appuyez sur Échap, et lisez ce qui s’affiche avant d’appuyer de nouveau.

Ce qui vient de se passer

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)

Les réglages de l’exploitant sont lus une fois, en haut, avec une valeur raisonnable pour une machine qui n’a jamais été réglée. saveGet avec un second argument renvoie cette valeur quand rien n’a été sauvegardé, et c’est comme ça qu’on distingue un premier lancement des suivants.

local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end

Des pièces qui entrent, des crédits qui sortent, au tarif que l’exploitant a réglé. Le while plutôt qu’un if, ce n’est pas de la prudence face à une entrée impossible — c’est l’exploitant qui baisse le prix de quatre pièces à une alors que trois pièces attendent dedans.

    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

Le contact de sortie n’arrive à votre jeu que grâce au singeSetQuitKeyEnabled(false) tout en bas du script. Un premier appui pose la question ; au second appui, depuis l’écran de la question, c’est vous qui appelez singeQuit(). goBackTo retient où était le joueur, si bien que répondre non le remet dans sa partie plutôt que sur l’écran d’attraction.

Ce bloc est le premier de la fonction et il se termine par return, donc rien d’autre ne peut avaler le contact. Tous les autres états du jeu sont traités en dessous.

    if state == "service" then
        serviceInput(what)
        return
    end

La même forme, encore. Tant que le menu de service est ouvert, chaque contact lui appartient — le stick ne dirige pas le jeu en dessous, une pièce ne tombe pas au milieu d’un réglage. Un if, tôt, avec un return. Tout écran posé par-dessus un autre en a besoin, et un jeu qui en accumule trois sans ça produit des bogues presque impossibles à décrire.

        saveSet("coinsPerCredit", coinsPerCredit)
    ...
    saveFlush()

D’abord enregistrer, puis forcer l’écriture. Sans cette écriture forcée, elle a lieu à la fin de l’image, ce qui est rapide mais pas immédiat. Un exploitant ajuste un réglage et débranche la prise dix secondes plus tard, et c’est le seul endroit d’un jeu où ça arrive vraiment.

    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end

Le clignotement. singeGetTicks() donne les millisecondes écoulées depuis le démarrage du moteur, // divise et jette le reste, si bien que le nombre change toutes les quatre cents millisecondes, et % 2 le fait alterner entre zéro et un. Pas de variable, pas de minuteur, rien à remettre à zéro : l’horloge comptait déjà.

    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())

La moitié de la page de service qui est pour l’exploitant. Une version, une rotation, la présence ou non d’une illustration, et l’endroit où vivent les données. Rien de tout cela n’est pour le joueur, et c’est exactement ce que vous regretterez de ne pas avoir quand quelqu’un vous téléphonera à propos d’une machine à cinq cents kilomètres de là.

singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()

En bas, hors de toute fonction, pour que ça s’exécute une seule fois au chargement du script. Aucune des deux lignes n’est à faire à chaque image, et mainBezelLoaded ne peut pas changer pendant que le jeu tourne.

Essayez

  1. Changez le prix. Ouvrez le menu de service, réglez les pièces par crédit sur deux, et mettez une pièce. Regardez le crédit ne pas apparaître, et regardez le compteur de pièces sur la ligne du bas. Puis quittez, relancez, et constatez que le prix est resté.

  2. Jouez gratuitement. Activez le jeu gratuit et vérifiez que start marche sans pièces et que les crédits ne deviennent pas négatifs.

  3. Ajoutez une page. Mettez une seconde page d’informations de service derrière le bouton 3 — les champs de singeGetSystemInfo() sont un bon début, et son entrée dans la Référence les liste tous.

  4. Tournez l’écran. Lancez-le avec --rotate=90 et regardez votre mise en page. Puis rendez la page de service lisible avec cette rotation, ce qui est plus dur qu’il n’y paraît et correspond exactement au travail que demande une borne verticale.

  5. Retirez le clavier. Débranchez-le, ou promettez-vous de ne pas y toucher, et parcourez chaque écran avec une manette. Tout ce que vous ne pouvez pas atteindre est un bogue.

Cassez-le exprès

Supprimez le bloc SWITCH_QUIT de onInputPressed, en laissant singeSetQuitKeyEnabled(false) là où il est, et lancez.

Maintenant, plus rien ne quitte. Échap ne fait rien, Q ne fait rien, et votre jeu n’a aucune sortie, ce qui est précisément ce que vous avez demandé. Ce n’est pas un plantage et il n’y a aucun message ; le moteur a fait exactement ce qu’on lui a dit.

Fermez la fenêtre avec son bouton de fermeture. Ça marche toujours, quoi qu’en dise un script, et c’est la porte que vous vous êtes laissée. En plein écran, Alt-Enter vous remet d’abord dans une fenêtre.

Ça vaut la peine de le sentir, celui-là. Désactiver la touche de sortie est la seule chose de ce livre qui puisse vous laisser avec un programme dont vous ne pouvez pas sortir, et l’habitude qui l’évite est simple : écrivez la sortie dans la même séance que celle où vous désactivez la touche de sortie, jamais plus tard.

Ce que vous avez appris

  • Une borne n’a pas de clavier, donc chaque écran du jeu doit marcher avec un stick et un bouton.

  • controls.cfg affecte les touches, les boutons de manette et les directions du stick aux noms SWITCH_ que votre jeu utilise déjà, et votre jeu ne sait jamais lequel a été pressé.

  • Quatre fichiers d’affectations sont lus tour à tour, chacun remplaçant le précédent, si bien qu’un fichier pour toute la machine et un fichier par jeu peuvent coexister.

  • Chaque périphérique qu’ouvre Singe est une manette, y compris une carte d’encodeur d’arcade, et l’outil Input Test dit ce qui arrive.

  • Le moteur garde pour lui la pause, la sortie, la capture d’écran et le verrouillage de la souris ; le reste est à vous.

  • Les pièces sont converties en crédits au tarif de l’exploitant, et une machine revient d’elle-même au mode attraction.

  • SWITCH_SERVICE est le bouton de l’exploitant, et derrière lui se trouvent le prix, la difficulté, un moyen d’effacer les scores, et ce qu’est la machine.

  • saveFlush() écrit un réglage tout de suite, parce qu’une borne perd le courant sans prévenir.

  • singeSetQuitKeyEnabled(false) donne le contact de sortie à votre jeu. Écrivez la sortie au même moment.

  • Un bezel est une illustration percée d’un trou, et --rotate fait tourner toute la présentation pour un moniteur vertical.

La fin

Ça fait trente et une leçons, et vous savez écrire un jeu.

Pas un jeu parfait, et pas encore un gros, mais ce qui vous sépare de l’un ou de l’autre, c’est du temps et de la pratique plutôt qu’un autre livre. Vous avez commencé avec cinq lignes qui mettaient un mot sur un écran noir. Vous savez maintenant ce qu’est une variable, à quoi sert une fonction, comment dessiner, comment faire du bruit, comment savoir quand deux choses se sont touchées, comment garder un score quelque part où il survit, comment faire d’un film un monde, comment mettre un modèle dans une pièce avec une lumière dessus, et comment confier le tout à un inconnu.

Ce dont vous avez besoin maintenant, c’est de la Référence de Singe, pas de ce livre. C’est la référence de chaque fonction, de chaque argument et de chaque valeur renvoyée, et c’est elle que vous aurez vraiment ouverte pendant que vous travaillez. Elle accompagne ce livre, sous les noms Reference.pdf et Reference.html. Lisez l’entrée avant d’utiliser l’appel ; la plupart contiennent une remarque sur l’erreur que les gens font avec.

Lisez aussi les scripts fournis avec Singe. Singe/Menu.singe, Singe/Tools.singe et Singe/Framework.singe ne sont pas des démonstrations écrites pour être lues — ce sont le menu et les outils de service dont vous vous servez depuis le début, qui font un vrai travail avec les mêmes fonctions que vous. Comprendre comment le programme de quelqu’un d’autre fait quelque chose est une compétence à part entière, et ces scripts sont un endroit bienveillant pour s’y exercer.

Et il y a Forge, un outil séparé avec son propre livre, pour décrire un jeu plutôt que l’écrire. C’est une autre route. Vous n’en avez pas besoin, mais elle est là.

Le prochain jeu est le vôtre. Faites d’abord le petit, finissez-le, et mettez-le devant quelqu’un. Finir, c’est la partie dont personne ne vous dit que c’est la plus dure, et c’est la seule qui transforme un dossier plein de scripts en un jeu auquel quelqu’un a joué.

Allez le construire.