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.
-
Bonjour — un script, une fonction, une chaîne, et quelque chose à l’écran.
-
Des nombres qui changent — les variables, l’arithmétique, et faire bouger les choses.
-
Prendre des décisions —
if, les comparaisons, et lire les commandes. -
Recommencer —
foretwhile, et dessiner cent fois la même chose. -
Vos propres fonctions — les arguments, les valeurs de retour, et pourquoi s’en donner la peine.
-
Des listes de choses — les tables,
ipairs, ajouter et retirer. -
Un jeu — tout ce qui précède, jouable, en cent vingt lignes environ.
-
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é.
-
Des images — les sprites, le chargement, le dessin et les images d’animation.
-
Le son — les effets, la musique, et quand charger quoi.
-
Toucher des choses — les collisions, le kit de jeu, et les boîtes de collision.
-
Score, vies et fin de partie — l’état, la sauvegarde, et recommencer.
-
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.
-
Lire de la vidéo — le disque, les images, les sauts, et l’attente.
-
L’autre façon de l’écrire — le modèle à fil d’exécution (« threaded »), et pourquoi il convient à la vidéo.
-
Les embranchements — les choix, les chemins, et la forme d’un jeu vidéo à embranchements.
-
Les pistolets optiques — viser, tirer, et le calibrage dont une borne a besoin.
-
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.
-
Du texte qui a de l’allure — les polices, la qualité, et les mesures.
-
Menus et écrans — la GUI, les documents, et la mise en forme.
-
Les sous-titres — et pourquoi ils ont leur propre système.
-
Passer à la 3D — les scènes, les caméras, et les coordonnées.
-
Modèles et lumière — glTF, les matériaux, et l’animation.
-
La physique — les corps, les forces, les articulations, et quand ne pas s’en servir.
-
Les particules — les émetteurs, et faire une explosion.
-
Des personnages qui se déplacent seuls — la navigation et la recherche de chemin.
-
Musique et MIDI — les pistes, les SoundFonts, et les instruments.
-
En ligne — les comptes, les tableaux des meilleurs scores, et le catalogue.
-
Garder des données — les bases de données, les tables, et les questions que vous leur posez.
-
Le publier — l’empaquetage, les correctifs, les licences, et la sortie.
-
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
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.
-
Déplacez le texte. Changez
overlayPrint(2, 2, "Hello!")enoverlayPrint(10, 5, "Hello!"). Puis essayez(0, 0). Puis essayez(200, 2), et trouvez pourquoi il a disparu. -
Dites autre chose. Mettez votre propre nom entre les guillemets.
-
Dites deux choses. Ajoutez une deuxième ligne
overlayPrintsous 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. -
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
functionregroupe des instructions sous un nom et s’arrête à sonend. -
onOverlayUpdateest 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.
onOverlayUpdateen 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 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
-
Changez les vitesses. Essayez
speedX = 1etspeedY = 1. Puis essayez0.05pour les deux. Puis rendez l’une beaucoup plus grande que l’autre. -
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.lenqui fait son travail. -
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. -
Empêchez-le d’aller de côté. Mettez
speedX = 0et lancez. Trouvez pourquoi le mot ne quitte plus jamais la colonne zéro, et pourquoi leifdu bord gauche ne se déclenche jamais. -
Cassez le compteur d’images exprès. Remettez la ligne
frames = 0dans la fonction, au-dessus deframes = 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 + 1calcule 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
onOverlayUpdates’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.
-
overlayGetWidthetoverlayGetHeightvous donnent la taille de la surface de dessin, si bien que vous n’avez jamais à la deviner. -
overlayClearcompte 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
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 est plus petit que b |
|
a est plus grand que b |
|
a est plus petit que b ou égal à b |
|
a est plus grand que b ou égal à b |
|
a est la même chose que 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, sauffalseetnil.
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
-
Changez la vitesse.
BOX_SPEED = 1etBOX_SPEED = 8. À huit, regardez ce que fait la limitation quand vous poussez la boîte dans un coin. -
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 letostringet lisez l’erreur que Lua vous donne. -
Accélérez quand un bouton est enfoncé. Ajoutez un drapeau
runningpiloté parSWITCH_BUTTON1dans les deux callbacks d’entrée, et utilisez unifdansonOverlayUpdatepour avancer de deux foisBOX_SPEEDtant qu’il est vrai. -
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
andpour 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. -
Retirez les relâchements. Supprimez toute la fonction
onInputReleasedet 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 … endn’exécute un corps que quand la réponse est vraie. -
elsedonne l’autre cas, etelseifen 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. -
trueetfalsesont des valeurs, et vous pouvez les garder dans des variables. -
and,oretnotcombinent et inversent ces réponses. -
nilest ce que vous obtenez d’un nom que vous n’avez jamais rempli, et ce n’est pas zéro. -
Tout est vrai, sauf
falseetnil. -
onInputPressedetonInputReleasedsont des callbacks que Singe appelle avec une valeurSWITCH_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.
-
overlayBoxdessine un contour en pixels, etcolorForegroundest 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
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
forquand le nombre de tours est connu avant de commencer. Quarante étoiles. Un pixel sur dix en largeur. Chaque rangée d’une grille. -
Utilisez
whilequand 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
-
Plus et moins. Essayez
STARS_PER_LAYER = 200, puis4. PuisLAYERS = 8, et regardez ce quelayer * LAYER_BRIGHTfait àshadequand le numéro de couche devient grand. Les nombres que prendcolorForegrounds’arrêtent à 255. -
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. -
Arrêtez le scintillement. Remplacez la ligne
math.randompar un simpleshade = layer * 70et 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. -
Faites-les tomber vers le haut. Un seul caractère.
-
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 … endexé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.
-
fora besoin d’undo, et chaque boucle a besoin d’unend. -
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 … endrecommence tant que la question est vraie, et c’est à vous de changer quelque chose dans le corps. -
Utilisez
forquand vous savez combien de fois, etwhilequand 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.floorjette 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 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
-
Renommez un paramètre. Dans
drawStar, changezxetyenacrossetdown, partout dans la fonction. Ne touchez à rien en dehors. Lancez. Trouvez pourquoi rien n’a cassé. -
Dessinez-les dans l’autre ordre. Échangez
drawStars()etdrawPlayer()dansonOverlayUpdateet 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. -
Utilisez
clampsur une nuance. ChangezshadeForenreturn clamp(math.random(60, 90) + layer * 90, 0, 200)et regardez les trois couches. Puis retirez leclampet regardez encore :colorForegroundretenait discrètement les nombres pour vous depuis le début, et maintenant vous voyez où. -
Appelez
drawStaravec deux arguments. ÉcrivezdrawStar(100, 100)quelque part dansdrawLayeret lancez. L’erreur nomme exactement ce qui manquait. Lisez-la avant de remettre le troisième argument. -
Déplacez un nom local. Prenez la ligne
local drift = 0et 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é.
-
returnrenvoie une valeur et arrête la fonction sur-le-champ, et une fonction qui se termine sans en avoir un renvoienil. -
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.
-
localcré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
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.
-
ivaut1. L’étoile un va bien. -
ivaut2. 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. -
ivaut3. 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. -
ivaut4. Il n’y a plus d’élément quatre.stars[4]vautnil.
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
-
Rendez-le plus profond. Changez
math.random(1, 3)enmath.random(1, 6)etSTAR_SHADEen25. Plus de vitesses, plus de nuances, un ciel plus profond. -
Moins d’étoiles, plus grosse salve. Mettez
STAR_COUNTà10etBURST_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. -
Donnez un autre champ à une étoile. Ajoutez
age = 0dansnewStar, ajoutez un àstar.agedansmoveStars, et affichezstars[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. -
Arrêtez de les retirer. Supprimez les trois lignes du bloc
if star.y >= heightdansmoveStarset lancez. Attendez dix secondes, puis lisez le nombre à l’écran et regardez le ciel. Trouvez comment les deux peuvent être vrais à la fois. -
Faites-le dans l’autre sens. Changez
for i = #stars, 1, -1enfor i = 1, #starset 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.
-
#listest le nombre d’éléments qu’elle contient, etlist[#list]est le dernier. -
table.insertajoute un élément, au bout ou à la position que vous indiquez ;table.removeen 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. -
ipairsparcourt 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
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à. -
SCANCODEetMODIFIER, 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_3etMOUSE_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
-
Rendez-le plus facile, puis injuste. Changez
PLAYER_WIDTHen80et jouez une partie. Puis changez-le en12, 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. -
Accélérez plus vite. Changez
BLOCK_FASTERde0.05à0.5et voyez combien de points vous arrivez à marquer. Puis essayez0, et demandez-vous si le jeu vaut encore la peine d’être joué. -
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. -
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_COLUMNSl’a demandée aussi. -
Mettez-le en pause. Ajoutez un quatrième état,
"paused".SWITCH_BUTTON2doit 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.
-
collideRectsré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
statequi 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
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 delocaldevant lui nulle part. -
local— un nom que vous avez déclaré aveclocaldans la fonction où vous êtes. -
field— un nom après un point, comme leydeblock.y. -
upvalue— unlocalvenu de plus loin, que cette fonction peut voir, et c’est ce que sont toutes les variables dedodge.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 :
-
Vous avez fait une faute dans le nom d’une de vos propres fonctions.
-
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.
-
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.
-
Vous l’avez rendue
localet vous l’avez appelée depuis un endroit situé au-dessus de sa déclaration. C’est exactement pour ça que les fonctions dedodge.singesont 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
-
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. -
Surveillez les apparitions. Mettez dans
spawnBlockundebugPrintqui affiche lexdu 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é ? -
Coupez-le. Changez
DEBUGenfalsedans 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é. -
Un bug sans erreur. Dans
updatePlaying, changezif spawnTimer ⇐ 0 thenenif 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 undebugLogdansspawnBlock, ajoutezspawnTimerà la première ligne qu’affichedebugReport, 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. -
Cassez le nom d’un callback. Renommez
onInputPressedenonInputPresset 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 scriptveut 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é. -
nilest 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
endmanquant 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.
-
debugPrintvous montre ce que contient vraiment une variable.tostringrend n’importe quoi affichable, et un interrupteur commeDEBUGcoupe 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
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.glbetSinge/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
-
Centrez le vaisseau sur sa position. Ajoutez
truecomme quatrième argument auspriteDrawdu 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. -
Plus de rochers. Changez
ROCK_COUNTen 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. -
Faites grandir le vaisseau. Ajoutez
spriteScale(shipSprite, 2)tout en bas du fichier, sur la ligne au-dessus destartGame(). 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 àspriteGetWidthet regardez tout rentrer dans l’ordre. L’entrée despriteScaledans la Référence explique ce que la mise à l’échelle fait aux mesures. -
Ajoutez le marcheur. Chargez
walk.pngdans 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 deonOverlayUpdateva le dessin — devant les étoiles, derrière les rochers. -
Déchargez quelque chose dont vous vous servez encore. Ajoutez
spriteUnload(starSprite)en bas du fichier, aprèsstartGame(), 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. -
spriteLoadvous rend un handle : un nombre qui veut dire « cette image-là » pour le moteur, et que vous gardez dans une variable. -
DIRest 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 deonOverlayUpdate. Un quatrième argumenttruedésigne plutôt le centre. -
Chargez une fois, en haut du fichier. Charger à l’intérieur de
onOverlayUpdatedévore la mémoire jusqu’à ce que le jeu meure. -
spriteUnloadrend une image, en général depuisonShutdown, 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.
-
spriteGetWidthetspriteGetHeightmesurent 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, etspriteDrawFrame(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
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.
-
musicStoppeut 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
-
Rendez le tir encore plus discret. Changez le
35dusoundPlaydu tir en10, puis en63. Trouvez le nombre où il passe sous les explosions au lieu de passer par-dessus. -
Baissez la musique sans toucher aux effets. Changez
musicSetVolume(50)enmusicSetVolume(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. -
Coupez la fin. Dans
endGame, changezmusicStop(theme, 1500)enmusicStop(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. -
Donnez un moteur au vaisseau. Lancez
soundPlay(clickClip, -1, 12)dansstartGame, gardez le canal qu’il vous donne dans une variable à lui, et arrêtez-le dansendGame. 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 lesoundStop, jouez trois parties d’affilée, et écoutez ce que vous avez construit. -
Comptez les canaux. Affichez le numéro de canal chaque fois qu’un rocher explose. Puis augmentez
ROCK_COUNTjusqu’à 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
-
soundLoadlit un son et renvoie un handle. Chargez une fois, en haut du fichier. -
soundPlaylance 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,
soundPlayrenvoie-1et 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 ;
soundStopest pour les sons qui n’ont plus lieu d’être. -
soundUnloadne 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 de0à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
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 :
-
collideCirclesetcollidePointCircle, 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 nombresx,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
-
Retirez la marge. Mettez
ROCK_PADà0et jouez une minute. Puis mettez-le à8et rejouez. Avec l’un des deux, on a l’impression que le jeu vous ment. -
Regardez ce que vous testez. Mettez
SHOW_BOXESàtrueet observez les contours verts pendant qu’un rocher passe près du vaisseau. Maintenant, mettezSHIP_PAD_Xà16, jouez, et remarquez que plus rien ne peut vous toucher. Trouvez pourquoi à partir du calcul deshipBox. -
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. -
Servez-vous du tir entier. Réécrivez
shotHitsRockpour qu’il utilisecollideRectsavec le rectangle complet du tir au lieu decollidePointRectavec 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. -
Rendez le rocher rond. Donnez au rocher un cercle au lieu d’une boîte : son centre est à
rock.x + rockWidth / 2vers la droite et àrock.y + rockHeight / 2vers le bas, et un rayon de10convient à peu près. Servez-vous decollideRectCirclepour le vaisseau et decollidePointCirclepour le tir, et dessinez le cercle dansdrawBoxesavecoverlayCircle, 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.
-
collideRectsprend un coin et une taille pour chacun de deux rectangles et répondtrueoufalse. 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.
-
collidePointRectdemande 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.
-
onCollisionest 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
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
-
Revenez à l’écran titre. Une borne d’arcade ne reste pas sur GAME OVER pour toujours. Cherchez
timerAfterdans la section Minuteur de la Référence, une autre partie du kit de jeu, et servez-vous-en dansendGamepour remettre l’état àTITLEcinq secondes après la fin de la partie. Puis appuyez vite sur1aprè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. -
Montrez les vies sous forme de vaisseaux. Dessinez
shipSpriteune fois par vie dans le coin supérieur droit avecspriteDrawau lieu d’afficher le nombre. Une boucleforde la leçon quatre, etshipWidthvous dit à quelle distance les espacer. -
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. -
Trouvez le fichier et cassez-le. Ouvrez
data/rocks/save.jsondans 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. -
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 :bestest toujours en mémoire, etsaveClearn’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.
-
onOverlayUpdatedé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.
-
saveSetrange une valeur sous une clé, etsaveGetla 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. -
saveGetsans valeur par défaut répondnilquand rien n’a été sauvegardé, etnilcasse la première image sur une machine qui n’a jamais lancé votre jeu. -
Quand vous mélangez
andetor, 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
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
-
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. -
Donnez un games.dat à Dodge. Écrivez un
games.datdans votre dossierdodgede la leçon sept et lancez le menu. Deux jeux maintenant, dans l’ordre des titres. Puis changez leTITLEde Rocks enAsteroid Fieldet regardez-le passer au-dessus de Dodge : la liste est triée par titre, pas par dossier. -
Cassez games.dat pour le menu. Supprimez l’une des accolades fermantes du
games.datderockset lancez le menu. Votre jeu a disparu de la liste, et le terminal dit pourquoi. Remettez-la. -
Trompez-vous de SCRIPT. Mettez
CANVAS_Xà1280etCANVAS_Yà720, et lancezSinge rocks. L’aire de jeu est plus large. Changez maintenantSCRIPTenrocks.singeet 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. -
Trouvez votre sauvegarde. Lancez le jeu depuis le menu, établissez un meilleur score, quittez pour revenir au menu, et quittez le menu. Lancez
Singe rockset regardez l’écran titre. Puis cherchez dansdata/rocksle 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 dossierSingedu 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.datest un fichier Lua qui contient une listeGAMES, et chaque entrée est un jeu. -
Une entrée a besoin de
TITLEet deSCRIPTet de rien d’autre ; ses chemins partent du dossier au-dessus dugames.dat. -
CABINET,MARQUEE,YEAR,GENRE,DEVELOPER,PUBLISHERetDESCRIPTIONsont ce que le menu montre au joueur, et F12 prend une image dont vous pouvez vous servir pour les deux premiers. -
REQUIRESdit 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.shouMenu.batlance 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 ungames.datqui 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
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
-
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.
-
Avancez pas à pas. Changez
discSkipForward(30)endiscSkipForward(1)et gardez la flèche droite enfoncée. Changez maintenantstopAtpour une image au milieu du dragon, et servez-vous dediscSearchet de la touche fléchée pour tomber exactement dessus. -
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. -
Demandez une image qui n’existe pas. Changez la ligne
SWITCH_RIGHTendiscSkipToFrame(100000). Ça ne plante pas. Lisez l’entrée de la Référence pourdiscSkipToFrameet trouvez la phrase qui dit pourquoi. -
Jouez-le sans la vidéo. Lancez
Singe -R moviepuis 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
discne 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.
-
discGetFramedemande où en est le disque ;discGetFrameCountdit combien il y a d’images ;discGetStatedit ce que fait le disque. -
discPlay,discPauseetdiscStople pilotent.discSearchva à une image et se met en pause ;discSkipToFrameva à une image et lit. -
Un disque qui arrive au bout repart de l’image zéro sans vous prévenir.
-
Sans disque, chaque appel
discest inoffensif, etSINGE_DISCest 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
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 :
-
Démarrer le film au début et le lire jusqu’à l’image 120.
-
S’arrêter là et demander au joueur d’appuyer sur la barre d’espace.
-
Quand il appuie, continuer la lecture jusqu’à l’image 300.
-
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
-
Ajoutez une étape. Après
waitForButton, faites plutôt sauter le film en arrière :discSkipToFrame(0), puisplayTo(60), puis continuez comme avant. Deux nouvelles lignes à un seul endroit, et rien d’autre dans le script n’a besoin de le savoir. -
Ajoutez la même étape à l’autre. Faites-le maintenant dans
events.singe. Comptez combien d’endroits vous avez dû toucher. -
É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. UtilisezdiscGetFrameet retenez d’où vous êtes parti. -
Ne cédez plus la main. Supprimez le
singeYield()à l’intérieur deplayToet lancez. Soyez prêt à fermer le terminal, parce que rien d’autre ne l’arrête. Puis remettez-le et supprimez plutôtdrawFrame(), et déduisez de ce que vous voyez pourquoi le compteur d’images s’arrête mais pas le film. -
Faites-en une boucle. Mettez tout le contenu de
singeMaindanswhile true do … endpour 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
singeMainou 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
whileavec unsingeYielddedans. 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
onOverlayUpdatequandsingeMainexiste. -
Tous les autres callbacks se déclenchent toujours, donc événements et étapes se mélangent librement.
-
Quand
singeMainse 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
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 |
|---|---|---|
|
0 à 119 |
Du feu, et le dragon se pose. Gauche ou droite ? |
|
120 à 259 |
Il crache du feu. Se baisser à gauche ou courir à droite ? |
|
260 à 339 |
Vous êtes dévoré. Vous perdez une vie. |
|
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 :
firstetlast-
Les images entre lesquelles la scène se déroule.
ask-
L’image sur laquelle la question apparaît. Le joueur a de
askàlastpour répondre, et c’est ça, le minuteur. prompt-
Ce que dit la question.
leftetright-
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
-
Ajoutez une fin. Donnez à
escapeune question et une deuxième scène de fin qui réutilise des images prises quelque part dans le film. Seule la table change. -
Rendez-le équitable. Baissez
askdans 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. -
Déplacez le point de contrôle. Changez le
goesTodepiten"sunset"et jouez. Puis réfléchissez à ce qui se passe si un joueur meurt dansarrive— et demandez-vous si la scène de mort devrait savoir d’où elle vient plutôt que de se le faire dire. -
Comptez ce que le joueur a vu. Ajoutez à côté de
scenesune 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 ». -
Cassez la carte. Changez le
leftdearriveen"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.leftetscene["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 —
deathdans trois enregistrements sur quatre — garde la description courte et honnête. -
Comparer
nilavec un nombre est une erreur, etandest 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
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
-
Déplacez une cible. Changez le
xde la troisième cible en680et 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. -
Rendez les cibles plus faciles. Changez
TARGET_SIZEen140. 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. -
Comptez la précision. Ajoutez une ligne qui affiche
hitsen pourcentage deshots. 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. -
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 ontnil. -
Retirez le
returnde la boucle dansonInputPressed, 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.
-
onInputPressedreçoit un second argument qui indique quelle souris ou quel pistolet a tiré, etnilquand 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 bvous donnebquandavautnil. -
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
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
-
Rendez-le plus difficile. Changez le
lastdu premier mouvement de105en75. Quinze images, c’est une demi-seconde. Jouez et voyez si vous y arrivez. -
Ajoutez un mouvement. Mettez une cinquième ligne dans la table avec une fenêtre entre les images
370et400, et montezLAST_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. -
Notez la vitesse. Donnez plus de points pour une réponse rapide. Dans
onInputPressed, là où la bonne réponse est comptée, calculezleftetspanà partir demoveet dediscGetFrame()de la même façon que la jauge, et ajoutezRIGHT_SCORE * left // spanau lieu deRIGHT_SCORE. Décidez si ça rend le jeu meilleur ou seulement plus agité. -
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. -
Deux invites à la fois. Faites se chevaucher les fenêtres de deux mouvements et voyez ce qui se passe.
moveAtrenvoie 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.
-
nildans 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
returnpré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. -
overlayBoxdessine un contour, donc une barre pleine est une pile d’appels àoverlayLine. -
Un mouvement manqué est un embranchement, et
discSkipToFramele 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
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
-
Changez la qualité. Mettez
FONT_QUALITY_SOLIDdans la lignefontQualityet regardez la courbe duSdansASTEROID. Puis essayezFONT_QUALITY_SHADEDet regardez ce qui se passe derrière chaque chaîne. -
Mettez l’indication en jaune. Déplacez la ligne
colorForeground(140, 200, 255)d’au-dessus defontToSpriteà juste au-dessus duspriteDrawqui dessinehintImage, et changez les nombres. Trouvez pourquoi rien ne se passe. Puis remettez-la, faites plutôt l’indication en blanc, et rendez-la jaune avecspriteSetTintjuste avant qu’elle soit dessinée. -
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. -
Retirez la vérification de
scoreShown, pour querenderScore()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 quefontPrintvous épargne quand vous le laissez faire. Puis retirez aussi lespriteUnloadderenderScore, laissez tourner une minute, et surveillez la mémoire qu’utilise votre jeu. -
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 quefontPrintn’a jamais vue, à chaque image. Sur une machine lente, c’est ce genre de texte qui coûte. -
Utilisez votre propre police. Trouvez un
.ttfsur votre machine, copiez-le à côté de votre script, et chargez-le avecDIR .. "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
-
fontLoadouvre un fichier TrueType à une taille en points fixe et renvoie un handle. Une taille, un handle. -
Charger une police la sélectionne ;
fontSelectchoisit entre les polices chargées. -
fontPrintcompte en pixels etoverlayPrintcompte en cellules de caractère. -
La couleur n’est pas un argument.
colorForegroundest un réglage ; réglez-le, puis dessinez. -
fontQualitychoisit comment les lettres sont rastérisées, etFONT_QUALITY_BLENDEDest la réponse habituelle. -
fontPrintgarde 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. -
fontToSpritefait le rendu dans un sprite, quespriteGetWidthmesure et que les appelssprite*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.
-
colorForegroundatteint le texte quand il est fabriqué, jamais un sprite quand il est dessiné ;spriteSetTintest la façon de recolorer un sprite après coup. -
fontUnloadlibè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
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
-
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é. -
Changez son style. Dans le bloc
<style>, changez#frameenwidth: 260dp; margin: 20dp;et regardez le panneau se déplacer et le texte se remettre à la ligne tout seul. -
Retirez le
guiSetInput(gui, true)deopenMenu. La page apparaît toujours. Trouvez, rien qu’en regardant l’écran, ce que vous avez perdu. -
Laissez la page affichée tout le temps. Supprimez les appels à
guiHide, changez les deux appelsguiSetInput(gui, false)entrue, 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’estguiSetInput(gui, false). -
Mettez le score sur la page plutôt que dans le HUD. Appelez
guiSetValuepourscoreà chaque image plutôt que seulement dansopenMenu, et supprimez la lignefontPrint. 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 ;
guiNewen crée une etguiDeletela libère. -
guiLoadmet un document RML dans une GUI et l’affiche ;guiHide,guiShowetguiClosele gèrent ensuite. -
guiDrawsuperpose la GUI à l’overlay pour une image, donc sa place est dansonOverlayUpdatecomme tous les autres appels de dessin. -
Une nouvelle GUI ne fait qu’afficher ; c’est
guiSetInputqui la rend utilisable. -
guiSetHandlerexécute votre fonction quand on clique sur un élément ou qu’on le modifie,guiSetValueécrit dans un élément, etguiGetValueen 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.rcssest 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
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..cueest le bloc qui porte la hauteur demandée parsrtPosition, et.cue .textest 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
-
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-titre99, en premier dans le fichier, et vérifiez qu’il marche toujours. -
Donnez à un sous-titre un mauvais horodatage — écrivez
00:00:05.500avec 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. -
Changez leur style. Dans votre propre
subtitle.rcss— la copie qui est à côté de votre script, pas celle deSinge— changez.cue .textpour 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. -
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.
-
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 avecsaveSetpour 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. -
srtLoadtransforme 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
falsequand il ne peut pas charger, y compris quand il n’y a pas de disque. Vérifiez la réponse. -
srtEnableles allume, et un script démarre toujours avec les sous-titres éteints. -
srtPositionles place à un pourcentage de la hauteur de l’image, de1à95. -
srtClearretire ce qui est affiché, etoverlayBannerpartage le même document. -
srtLoadTracklit 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 copiezsubtitle.rmletsubtitle.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
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
-
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, lenodeLookAtgarde la boîte au centre, si bien que vous obtenez un autre angle sur la même scène pour un seul nombre. -
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. -
Ajoutez une deuxième boîte. Copiez les deux lignes qui ont créé la boîte, renommez la variable en
mark, et donnez-luinodeSetPosition(mark, 3, 0, 0)etnodeSetScale(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. -
Partagez le maillage. Au lieu d’appeler
meshBoxdeux 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. -
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
nodeSetParentdans 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.
-
nodeSetPositionetnodeSetRotationrèglent une valeur directement ;nodeMoveetnodeRotatela changent d’une certaine quantité. -
N’importe quel nœud peut être la caméra.
nodeLookAtl’oriente etcameraSetla choisit. -
Le champ de vision de
cameraSetPerspectivechange 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
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
-
Éteignez les lumières. Mettez tout le bloc
sunen commentaire en ajoutant--au début de chaque ligne, et lancez. Puis faites de même avecsceneSetAmbient. Retenez à quoi ça ressemble, parce qu’un jour ça vous arrivera sans que vous l’ayez voulu. -
Déplacez le soleil. Changez
nodeLookAt(sun, 0, 1.5, 0)ennodeLookAt(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. -
Réchauffez la torche. Montez l’intensité de la lumière ponctuelle de
14à60et 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. -
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. -
Trouvez une autre partie. Les parties du dragon s’appellent
head,jaw,neck,tail,body,crest,hornL,hornR,wingL,wingR,foreLegL,foreLegR,hindLegLethindLegR. Faites onduler la queue avec son propremath.sinà une autre vitesse que les ailes. Puis essayeznodeFind("wings", dragon)et voyez ce que fait un mauvais nom quand vous passez directement lenilà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
-
modelLoadlit un.glbune fois ;modelInstanceen 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
nodeSetScalesur 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
lightSetShadowne les allume pas, et chacune a un coût. -
nodeFindatteint une partie d’un modèle par le nom qu’elle a dans le fichier. -
modelGetAnimationsdit 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
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_STATICne 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_DYNAMICest 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_KINEMATICva 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
-
Changez le monde. Ajoutez
physicsSetGravity(0, -1.62, 0)vers le haut du fichier et tirez de nouveau. Puis essayez0, -30, 0. Les mêmes caisses, une autre planète, une ligne. -
Changez la boule. Rendez la boule dix fois plus lourde avec
bodySetMass(ball, 30), puis dix fois plus légère avec0.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. -
Changez les caisses en glace. Ajoutez
bodySetFriction(crate, 0.02)danscrateAt, et ajoutez une ligne qui donne aussi au sol un faible frottement. Regardez la pile refuser de tenir debout dès le départ. -
Faussez la forme exprès. Dans
crateAt, changez les dimensions du corps en2, 2, 2pendant 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. -
Comptez les points comme il faut. Utilisez
bodyIsRestingsur 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.
-
bodySetVelocityremplace le mouvement d’un corps,bodyApplyImpulseest un coup, etbodyApplyForceest 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.
-
onCollisionsignale chaque nouveau contact avec son point et sa vitesse, et un corps déclencheur signale les arrivées et les départs paronTrigger. -
bodyIsRestingvous dit quand tout s’est arrêté, ce qui est en général le moment où un tour est fini. -
physicsSetDebugdessine 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 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
-
Transformez l’échappement en fumée. Changez
emitterSetBlend(exhaust, PARTICLE_ADD)enPARTICLE_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 avecemitterSetSize(exhaust, 3, 14). Trois lignes ont fait une tout autre machine. -
Enlevez le freinage de l’explosion. Supprimez la ligne
emitterSetDraget 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. -
É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. -
Lâchez-en mille d’un coup. Changez
emitterBurst(boom, 140)enemitterBurst(boom, 1000)et regardez le compte à l’écran. Il n’atteindra pas mille. Trouvez pourquoi à partir deemitterSetMax, puis agrandissez la réserve et rendez les étincelles quatre fois plus grosses, et voyez ce que cela fait à la fréquence d’images. -
Déclenchez l’explosion là où le vaisseau n’est pas. Mettez
emitterSetPosition(boom, 40, 60)dansexplodeà 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.
-
emitterNewsans 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;emitterBurstlance une poignée d’un coup. Les effets continus sont des flux, les effets ponctuels sont des salves. -
emitterStoplaisse les particules vivantes finir ;emitterClearles tue tout de suite. -
Un émetteur en deux dimensions se déplace avec
emitterSetPositionà chaque image et se dessine avecemitterDrawà 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.
-
emitterSetMaxplafonne la réserve, etemitterGetCountvous 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
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
-
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)etaddWall(6.5, 0, 7, 0.6). Lancez-le et regardez ce que montrenavDrawavant d’appuyer sur quoi que ce soit. Puis envoyez la boîte de l’autre côté et voyez ce qu’elle fait. -
Rendez tout le monde gros. Mettez
AGENT_RADIUSà2.0et 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. -
Envoyez-la vers la souris. Prenez le point sous le pointeur de la souris avec
sceneUnproject, ramenez-le sur le maillage avecnavNearest, et envoyez-y la boîte quand le bouton est enfoncé.navNearestqui renvoienil, c’est le cas que vous devez gérer, et il se produit chaque fois que le pointeur n’est pas sur le sol. -
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. -
Précalculez-le une fois. Appelez
navSave(nav, "room.nav")aprèsnavBuild, puis remplaceznavNew, les appels ànavAddNodeetnavBuildpar un seulnavLoad("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.
-
navNewdécrit le personnage auquel le maillage est destiné,navAddNodetransmet la géométrie du niveau, etnavBuildla précalcule. Après le précalcul, on ne peut plus rien ajouter. -
navSaveetnavLoadgardent un maillage précalculé dans un fichier pour que le joueur ne l’attende jamais. -
navDrawvous montre le maillage, et c’est la première chose à regarder quand un personnage se conduit bizarrement. -
navAgentNewconfie un nœud au moteur pour qu’il le fasse marcher ; à partir de là, ne déplacez plus ce nœud vous-même. -
navAgentMoveTorègle une cible et renvoiefalsequand il n’y a aucun moyen d’y arriver. Gérer ce cas, c’est votre travail, et cela arrive souvent. -
onNavArrivedest appelé une fois quand un agent atteint sa cible, et on lui dit quel agent. -
navPathrépond à la même question sans faire bouger personne, etnilveut dire pas de trajet. -
Les agents se contournent entre eux en plus de contourner le niveau.
-
navAgentGetVelocitypermet 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
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.
soundSetVolumene touche jamais à la musique etmusicSetVolumene 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
-
Faites-la boucler quatre fois au lieu d’indéfiniment. Changez
musicPlay(theme, -1)enmusicPlay(theme, 3)et comptez. Le nombre dit combien de fois elle se répète, pas combien de fois elle joue. -
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 essayezmusicStop(theme, 100). -
Affichez le canal. Dans
onMidiMessage, calculez le canal avec(status & 0x0F) + 1et 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. -
Notez la vélocité. Donnez un point pour la bonne note, et trois points si
data2dépasse cent, pour que le jeu récompense ceux qui jouent avec conviction. -
Jouez la réponse. Quand le joueur trouve la bonne note, faites jouer au jeu un petit accord en retour, avec trois appels à
midiNoteOnespacé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à128et celui des effets de0à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
singeSetAudioDelaycorrige 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.
-
onMidiMessagevous donne les octets bruts. Les quatre bits du haut destatussont la sorte, les quatre du bas sont le canal, et un note on de vélocité zéro veut dire note off. -
Chaque
midiNoteOna besoin d’unmidiNoteOff, et c’est un minuteur qui les associe. -
Sur une machine sans MIDI, chaque appel répond
falseou 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 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 unnameet unevalue; -
result.standing, la proprevaluede ce joueur, sonrank, et le nombre deplayerssur 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
-
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. -
Supprimez l’identifiant. Retirez
GAME_IDde votregames.datet relancez. Le message change. Remettez-le. -
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
standings’il le faut. -
Nommez le tableau.
scoreSubmit(score, "reaction")etscoreBoard(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é. -
Rendez l’attente visible. Entre l’appel à
scoreBoardet 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_IDdansgames.dat, un UUID qui ne doit jamais changer.singeGetGameId()le lit. -
scoreSubmitmet 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. -
scoreBoarddonne 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 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
-
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. -
Ignorez les faux départs. Ajoutez
WHERE score > 0à la question des meilleures parties, entreFROM runsetORDER BY. Puis comptez les faux départs sur chaque épreuve avec une question de votre cru. -
Ajoutez une épreuve. Ouvrez
stages.dbdans 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. -
Remettez l’historique à zéro.
runs:exec("DELETE FROM runs")vide la table. Mettez-le sur un bouton, appelezrefreshjuste après, et regardez tout retomber à rien. C’est le « remettre à zéro les meilleurs scores » d’un menu de service. -
Écrivez mille lignes. Appelez
recordmille fois dans une boucle et chronométrez avecsingeGetTicks. Puis mettezruns:exec("BEGIN")avant la boucle etruns: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.openouvre 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 avecsqlite3.OPEN_READONLY. -
CREATE TABLE IF NOT EXISTSs’exécute sans risque à chaque démarrage du jeu. -
Les valeurs entrent par
prepare,bind_values,stepetreset, jamais en collant des chaînes dans le SQL. -
nrowsrend les lignes sous forme de tables ;urowsrend les colonnes elles-mêmes. -
ORDER BY,LIMIT,GROUP BY,MAXetCOUNTré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
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 :
-
un dossier non empaqueté qui porte le nom du fichier sans son extension —
MyGame/à côté deMyGame.game; -
le dossier de données du jeu, sous
files/, qui est l’endroit où atterrit tout ce que le jeu écrit ; -
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 :
-
Désempaquetez la version dans un dossier vide et lisez la liste des fichiers.
-
Copiez uniquement le fichier
.gamedans un autre dossier, avec une copie neuve de Singe et rien d’autre, et lancez-le depuis le menu comme le fera un joueur. -
Supprimez le dossier
datade 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. -
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
-
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. -
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.
-
Faites un correctif. Passez la version à
1.0.3, mettez seulement le script dans un dossierfixes, empaquetez-le en.patch, et appliquez-le au jeu que vous avez déjà fait. Vérifiez la version à l’écran. -
Cassez l’empaqueteur. Renommez votre
games.datun instant et essayez d’empaqueter. Puis remettez-le, faites pointer l’un de ses nomsSCRIPTvers un fichier qui n’existe pas, et réessayez. Deux refus différents, tous les deux avant que quoi que ce soit soit écrit. -
É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.gametransforme 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
DIRet n’écrivez que soussingeGetDataPath(), sinon votre jeu marchera non empaqueté et échouera empaqueté. -
--patchremplace des fichiers d’un jeu publié en une seule transaction ;--unpackressort tout. -
L’empaqueteur refuse les fichiers du moteur, les conflits de noms, et un
games.datqui 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
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 :
-
Mode attraction. Personne n’est là. La machine montre ce qu’elle est, fait clignoter
INSERT COIN, et ne demande rien. -
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. -
Partie.
SWITCH_START1dépense un crédit et lance la partie. -
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
-
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é.
-
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.
-
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. -
Tournez l’écran. Lancez-le avec
--rotate=90et 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. -
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.cfgaffecte les touches, les boutons de manette et les directions du stick aux nomsSWITCH_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_SERVICEest 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
--rotatefait 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.