Chapitre 1. Développement de jeux

1.1. Lua

Singe utilise le langage de programmation Lua (http://www.lua.org) pour écrire la logique des jeux. Lua est rapide, léger, orienté objet, facile à utiliser, et réellement employé dans l’industrie du jeu vidéo. Ce livre ne l’enseigne pas ; Apprendre à programmer avec Singe, dans le même téléchargement que celui-ci, s’en charge, de zéro jusqu’à un jeu terminé, en trente et une leçons. Des tutoriels vidéo sur Lua se trouvent sur la chaîne YouTube de Kangaroo Punch, et la référence du langage lui-même est sur http://www.lua.org.

1.2. Règles de base

  • Singe est multiplateforme. Des choses dont vous n’avez normalement pas à vous soucier sous Windows deviennent importantes. Les noms de fichiers sont sensibles à la casse — MyScript.singe et myscript.singe ne sont pas le même fichier. Utilisez aussi les séparateurs de chemin UNIX — / plutôt que \. Cela rend votre code plus propre (pas de barres obliques inverses doublées) et fonctionne partout où Singe est pris en charge.

  • Choisissez pour le dossier de votre jeu un nom qui le distingue. N’y mettez pas d’espaces.

  • Utilisez le framework de Singe fourni. Ne copiez pas le framework dans les scripts de votre jeu. En incluant le framework fourni, vous favorisez la compatibilité future à mesure que Singe est mis à jour. Commencez (ou terminez) le script de votre jeu par :

    dofile("Singe/Framework.singe")
  • Gardez votre jeu autonome. Si vous vous appuyez sur un framework tiers ou partagez du code entre vos jeux, copiez-le dans le dossier de votre jeu. Ne faites jamais référence à un dossier situé à côté de votre jeu ; le seul fichier hors de votre jeu qu’un script peut charger est Singe/Framework.singe. Un jeu en un seul fichier (voir Jeux en un seul fichier) empaquette exactement un dossier, et un jeu qui va chercher en dehors ne peut pas être empaqueté.

  • Restez en dehors du dossier Singe/. Il est géré par Singe, et tout ce qui y est ajouté ou modifié risque d’être supprimé à l’avenir.

  • Incluez un games.dat. C’est extrêmement important pour les nouveaux utilisateurs. Même s’il existe d’autres front-ends et des systèmes de menus basés sur Singe, il est vital d’inclure les données destinées au système de menus intégré. Presque tous les problèmes d’assistance viennent de fichiers games.dat manquants ou mal formés.

  • Ne distribuez pas de fichiers non essentiels. Ne livrez jamais les exécutables de Singe ni les scripts fournis par Singe avec votre jeu. Ne livrez pas les fichiers d’index générés à partir des vidéos.

1.3. Recharger pendant que vous travaillez

Lancez le jeu avec --reload (-R) et Singe surveille chaque fichier de script non empaqueté que le jeu a chargé. Enregistrez une modification dans l’un d’eux et le jeu repart de son script un instant plus tard : tout ce que le script a créé disparaît (sprites, sons, polices, vidéos, GUI, la scène 3D, la physique, les émetteurs, l’overlay revient à sa taille par défaut, le volume des effets et la souris reviennent à leur état de démarrage), le moteur reste (la fenêtre, le GPU, les manettes), le disque est de nouveau arrêté sur sa première image comme au démarrage, et le script s’exécute à neuf, si bien qu’un modèle de 52 Mo revient à l’écran dans le temps qu’il faut pour le charger plutôt que dans celui qu’il faut pour démarrer Singe. Une touche ou un bouton maintenu pendant le rechargement est ignoré jusqu’à ce qu’il soit relâché, comme lors d’un démarrage à froid. F5 recharge à la demande, et un script peut le demander avec singeReload(). Les jeux empaquetés n’ont rien à surveiller ; l’option est faite pour un jeu dans un dossier. Une erreur de script au rechargement est affichée et le jeu reste vide jusqu’à ce que le rechargement suivant la corrige ; le fichier reste surveillé, donc enregistrer la correction suffit. Comme le rechargement exécute le même nettoyage que lorsqu’on quitte, toute fuite d’un script se voit ici en premier.

1.4. Déboguer dans ZeroBrane Studio

ZeroBrane Studio est un IDE Lua gratuit, et Singe apporte tout ce qu’il faut pour y lancer et y déboguer un jeu : points d’arrêt, pas à pas, fenêtres Pile d’exécution et Expressions espionnes, un jeu qui reste immobile tant qu’il est arrêté, un arrêt dans l’IDE quand une erreur va mettre fin au jeu, et l’autocomplétion avec des infobulles pour toute l’API, en anglais, en français, en italien, en allemand ou en espagnol. La partie débogueur est MobDebug, intégré à Singe et démarré par --debug, si bien qu’un jeu n’a besoin d’aucune ligne à lui ; tout autre outil qui parle le protocole de MobDebug peut se connecter de la même façon.

1.4.1. Mise en place

Singe décompresse un paquet pour ZeroBrane Studio dans son dossier de support, sous Singe/ZeroBrane/singe.lua, et le tient à jour d’une version à l’autre. Indiquez à ZeroBrane Studio où il se trouve par une seule ligne dans son user.lua (Édition > Préférences > Paramètres : Utilisateur), puis redémarrez-le :

package "/home/me/Singe/Singe/ZeroBrane/singe.lua"

Singe apparaît alors dans Projet > Interpréteur Lua, avec Projet > Déboguer avec Singe et un bouton Singe dans la barre d’outils pour lancer un jeu sous le débogueur en une seule étape. Les fichiers .singe s’ouvrent en Lua, les documents .rml en XML et les feuilles de style .rcss en CSS. Faites du dossier du jeu le projet (Projet > Répertoire de projet > Choisir…​). Le paquet cherche Singe dans ce dossier et dans les trois au-dessus, en prenant la version la plus récente pour votre machine, puis dans le PATH ; s’il n’en trouve aucun, il vous le demande la première fois que vous lancez un jeu, et s’en souvient. Projet > Choisir l’exécutable de Singe…​ en désigne un autre, et path.singe = "/path/to/Singe" dans user.lua l’emporte sur les deux.

1.4.2. Lancer et déboguer

Projet > Exécuter (F6) lance le jeu, et Projet > Lancer le débogage (F5) le lance sous le débogueur. Le script est le point d’entrée du projet s’il y en a un (faites un clic droit dessus dans l’arborescence du projet et choisissez Définir le fichier en tant que point d’entrée), et sinon le fichier en cours d’édition ; quand celui-ci est un des modules du jeu plutôt qu’un fichier .singe, c’est l’unique fichier .singe du projet qui est lancé. Singe démarre dans le dossier qui contient son exécutable, comme le menu le lancerait, si bien que Singe/Framework.singe et tous les noms relatifs à ce dossier se résolvent comme d’habitude, et l’entrée games.dat du jeu fournit sa vidéo et ses réglages. Projet > Paramètres de ligne de commande…​ ajoute vos propres options, dont -v et une vidéo pour un jeu sans entrée.

Cliquez dans la marge pour poser un point d’arrêt. Le jeu s’y arrête avec ses variables locales dans la fenêtre Pile d’exécution, la fenêtre Expressions espionnes évalue des expressions, et Pas à pas détaillé (F10), Pas à pas sommaire (Shift+F10) et Pas à pas sortant (Ctrl+F10) se comportent comme dans n’importe quel programme Lua, à l’intérieur de singeMain aussi. Projet > Interrompre arrête un jeu là où il en est. Tant que le jeu est arrêté, le disque, chaque vidéo et chaque son se mettent en pause exactement comme pour la touche pause, et reprennent ensuite au même endroit.

Quand une erreur va mettre fin au jeu — une erreur Lua, ou un appel du moteur qui reçoit quelque chose dont il ne peut rien faire --, l’IDE s’arrête d’abord, dans le Debugger.singe du dossier Singe, et la fenêtre Sortie dit ce qui ne va pas. La fenêtre Pile d’exécution garde sous ce fichier les propres cadres du script, avec leurs variables locales telles qu’elles étaient. Continuez, et le jeu se termine comme il l’aurait fait, avec l’erreur et une trace de pile dans la fenêtre Sortie ; double-cliquez sur une ligne de la trace pour ouvrir le fichier à cet endroit.

Le jeu tourne avec --reload, si bien qu’enregistrer un script relance le jeu et le débogueur avec lui, points d’arrêt compris. Projet > Relancer Singe quand un script change désactive ce comportement.

1.4.3. Autocomplétion et Référence

L’autocomplétion propose chaque fonction, callback et constante de l’API, et une infobulle en donne les arguments et le premier paragraphe de l’entrée. Projet > Analyser (Shift+F7) connaît l’API lui aussi, si bien qu’il signale un appel mal orthographié plutôt que chaque appel. Le réglage de langue de ZeroBrane Studio choisit la langue des infobulles : language = "fr" dans user.lua donne le français, et il en va de même pour l’italien (it), l’allemand (de) et l’espagnol (es). Faites un clic droit sur un nom et choisissez Chercher dans la Référence de Singe pour ouvrir son entrée dans un navigateur ; Aide > Référence de Singe ouvre le début. Les deux ont besoin du téléchargement de la documentation décompressé à côté de Singe, sous Singe-Docs-v3.00 ou Singe-Docs-v3.00-fr et ainsi de suite, celui dans la langue de ZeroBrane Studio étant pris en premier ; singe = { reference = "/path/to/Reference.html" } dans user.lua en désigne un autre.

1.4.4. Déboguer une borne

Le débogueur fonctionne à travers un réseau. Sur la machine qui a ZeroBrane Studio, ouvrez le dossier du jeu comme projet et choisissez Projet > Lancer le serveur de débogage. Sur la borne, lancez le jeu avec --debug=HOST, où HOST est le nom ou l’adresse de cette machine ; le port est 8172 sauf si --debug=HOST:PORT en donne un autre, et la première machine doit accepter les connexions sur ce port. Une borne qui lance ses jeux depuis le menu peut porter debug = "HOST:PORT" dans son fichier de réglages à la place, et chaque jeu qu’elle lance se connecte, le menu compris. L’IDE arrête chacun sur sa première ligne, où Continuer (F5) le met en route ; debugger.runonstart = true dans user.lua le laisse aller tout droit jusqu’au premier point d’arrêt. La borne annonce ses propres chemins, que ZeroBrane Studio fait correspondre aux fichiers du projet la première fois qu’il s’arrête, si bien que le même dossier de jeu sur les deux machines suffit. Si rien n’écoute, un jeu se joue comme d’habitude une fois que la tentative de connexion abandonne, ce qui ne prend pas plus de deux secondes.

1.4.5. Limites

  • Déboguez un jeu non empaqueté, depuis son dossier. Un .game empaqueté n’a aucun fichier sur le disque que l’IDE puisse ouvrir.

  • Une erreur dans singeMain s’arrête dans Framework.singe, qui exécute singeMain comme une coroutine ; le message donne la ligne de votre script.

  • Tant que l’IDE tient le jeu arrêté, la fenêtre ne se redessine pas, et la fermer attend que vous continuiez. Arrêter le processus (Shift+F5) termine le jeu aussitôt.

  • Singe arrête un script qui ne rend jamais la main quand on ferme sa fenêtre, mais pas sous le débogueur, qui possède le script tant qu’il tourne ; Interrompre trouve où il est bloqué.

1.5. Mode de test déterministe

--deterministic est un outil de test, pas une façon de jouer. Il fait ignorer complètement le temps réel au moteur : au lieu de demander à la machine l’heure qu’il est, le moteur tourne sur une horloge virtuelle qui avance d’un pas fixe — 15 millisecondes par défaut — exactement une fois par image. Tout ce qui est cadencé par le temps suit cette horloge : les pas de la physique, l’animation des sprites et des modèles, les particules, la navigation, les animations et les transitions de la GUI, os.clock(), singeGetTicks() et un os.time() sans argument (un jeu qui initialise son générateur à partir de l’horloge au début d’une partie l’initialise à partir de l’horloge virtuelle, et tire donc les mêmes nombres à chaque exécution ; os.time auquel on donne une table de date la convertit comme Lua l’a toujours fait). Le disque la suit aussi : pendant la lecture, chaque image de la vidéo reste affichée pendant autant d’images du moteur que vaut son temps de présentation sur cette horloge (deux ou trois au pas par défaut pour un disque à trente images par seconde), comme en jeu réel, et un disque en pause ou qui a fait un saut reste là où on l’a mis. Le générateur de Lua et celui du moteur sont initialisés à partir d’un nombre fixe. Rien n’attend rien, donc le jeu tourne aussi vite que la machine le permet.

Tout l’intérêt est qu’une capture d’écran prise à un numéro d’image fixe est la même image à chaque exécution. Sans cela, l’image 40 est un moment différent à chaque fois — la physique a fait un nombre de pas différent et le disque est sur une autre image de la vidéo — si bien que deux exécutions du même jeu inchangé peuvent différer d’un million de pixels, et qu’un vrai changement peut se cacher dans ce bruit.

Ce que cela coûte, c’est tout ce qui dépend du temps réel. Le son est toujours joué sur l’horloge du périphérique, qu’aucune horloge virtuelle n’atteint, donc le son dérive par rapport à l’image et ne veut rien dire — sauf si l’exécution est enregistrée avec --record : le son est alors mixé en mémoire un pas à la fois en même temps que l’image, si bien qu’un enregistrement fait de cette façon est exact image par image et échantillon par échantillon (voir singeRecordStart). La fréquence d’images ne veut rien dire non plus, pas plus que tout ce qu’un jeu mesure en secondes. Ne rapportez jamais un chiffre de performance, un problème de son ou un problème de synchronisation à partir d’une exécution dans ce mode, et ne livrez jamais un lanceur qui l’utilise.

Le nombre que porte l’option, si elle en porte un, est à la fois la taille du pas et la graine dont partent les générateurs, de 1 à 1000 :

Singe --deterministic          le pas par défaut de 15 ms, graine 15
Singe --deterministic=20       un pas de 20 ms, graine 20

Deux exécutions avec le même nombre sont identiques ; deux exécutions avec des nombres différents sont chacune reproductibles mais différentes l’une de l’autre, et c’est ainsi qu’un test demande une exécution différente mais tout aussi reproductible. L’option peut se régler dans un fichier de réglages sous le nom deterministic, comme toute autre option.

1.5.1. Captures d’écran de référence

Les scènes de testScripts prennent chacune une capture d’écran ou deux à un numéro d’image fixe et quittent d’elles-mêmes, si bien que dans ce mode elles produisent un jeu d’images de référence auquel un changement ultérieur peut être comparé pixel par pixel. Pour les enregistrer, lancez chaque scène avec l’option et gardez ce qui arrive dans le dossier de données :

for n in 2 3 4 5 6 7 8 9 10 11 13 14 15 16 18 19 21 22 23 24 25 26 \
         36 37 38 39 40 41 42 43 44 45 48 49 50 51; do
    Singe -w -d data --deterministic -v Singe/menuBackground.mkv \
          testScripts/scene$n.singe
done

Les scènes laissées hors de cette boucle veulent leurs propres options, celles que leur donne le tableau de testScripts/README.md : scene12 se lance sans aucun disque, scene17 avec le disque, et scene20 avec -C 720x480, toutes trois avec SDL_GPU_DRIVER=nothing ; scene27 à scene35 veulent -x 1280 -y 720 -C 1280x720 et pas de disque ; scene46 veut -g '10 5' ; et scene47 veut --bezeldir=testScripts/bezels --bezel=cabinet.png. Copiez les fichiers singe*.png hors de data/testScripts après chaque exécution, puisque l’exécution suivante numérote de nouveau ses captures à partir de zéro.

Pour comparer une version ultérieure, il suffit alors de lancer les mêmes commandes et de demander la différence, qui doit être nulle :

compare -metric AE reference/scene36-singe000.png new/scene36-singe000.png null:

1.6. Où vivent les fichiers

Les chemins dans un script sont relatifs au dossier depuis lequel Singe a été lancé, pas au script. Utilisez la variable globale DIR, que Framework.singe règle sur le dossier du script lui-même, pour qu’un jeu fonctionne où qu’il soit installé :

crosshair = spriteLoad(DIR .. "sprite_Crosshair.png")

Tout ce que Singe écrit va dans le dossier de données (singeGetDataPath()), data/ à côté des jeux sauf si --datadir en décide autrement, si bien qu’un jeu peut vivre sur un support en lecture seule. Singe 2.x écrivait les sauvegardes et les réglages dans le dossier du jeu lui-même ; un jeu qui le fait encore échoue sur une installation en lecture seule, alors gardez chaque io.output sous singeGetDataPath().

1.7. Empaqueter votre jeu

Un jeu terminé se livre sous la forme d’un seul fichier .game, décrit ci-après. Rien d’autre n’est nécessaire : le joueur copie le fichier à côté de l’exécutable de Singe et le menu l’affiche. Singe n’installe plus d’archives.

1.8. Jeux en un seul fichier

Un jeu peut tenir en un seul fichier. singe --pack écrit un dossier de jeu dans une base de données SQLite, et Singe le lance depuis celle-ci : scripts, sprites, sons, polices, framefiles et vidéo se chargent tous directement depuis la base de données, et installer le jeu revient à copier le fichier à côté de l’exécutable. Le menu affiche chaque fichier .game qu’il trouve à côté des dossiers de jeux.

Singe --pack MyGame MyGame.game       Empaquette le dossier MyGame dans MyGame.game
Singe MyGame.game                     Lance la première entrée du games.dat qu'il contient
Singe --entry=2 MyGame.game           Lance sa deuxième entrée
Singe --unpack MyGame.game MyGame     Réécrit les fichiers sur le disque
Singe --patch MyGame.game fixes       Remplace des fichiers depuis un dossier (ou une base de correctif)

Rien dans un jeu n’a besoin de changer pour qu’il soit empaqueté. Chaque nom qu’utilise un script, que ce soit par dofile, require, io.open et ses semblables, spriteLoad, soundLoad, fontLoad, videoLoad, un framefile ou un controls.cfg, passe par une seule et même recherche. Pour un jeu non empaqueté, cette recherche est le simple système de fichiers, relativement au dossier depuis lequel Singe a été lancé, exactement comme avant. Pour un jeu empaqueté, un nom est essayé à trois endroits, dans cet ordre, et le premier trouvé l’emporte :

  1. Un dossier non empaqueté portant le nom de la base de données sans son extension (MyGame/ à côté de MyGame.game). C’est ainsi que vous continuez à modifier un jeu empaqueté, et qu’un joueur en fait un mod : les fichiers déposés là l’emportent sur les copies empaquetées.

  2. Le dossier de données du jeu, sous files/. Tout ce qu’un jeu écrit avec io.output ou io.open(name, "w") arrive ici, si bien qu’un game.cfg enregistré l’emporte sur l’original empaqueté et que la base de données n’est jamais écrite.

  3. La base de données elle-même.

Dans une base de données, les noms sont comparés sans tenir compte de la casse, avec l’un ou l’autre séparateur de chemin, et relativement à la racine du jeu. Un premier composant égal au nom du dossier du jeu lui-même est ignoré, si bien que MyGame/Cfg/game.cfg, Cfg/game.cfg et DIR .. "Cfg/game.cfg" trouvent tous le même fichier. Le nom de la base de données elle-même (MyGame.game, avec ou sans séparateur final) est la racine du jeu, comme l’est . depuis l’intérieur. Les noms commençant par Singe/ ou par le dossier de données restent sur le système de fichiers ; Singe/Framework.singe et singeGetDataPath() fonctionnent comme toujours, et un tel nom peut utiliser .. tant qu’il reste sous ce préfixe (le controls.cfg à la racine du dossier de données est trouvé ainsi). Tout autre nom relatif comportant un composant .. ne mène nulle part dans un jeu empaqueté : io.open renvoie nil avec un message disant que le nom sort du jeu, lfs.attributes renvoie nil, et spriteLoad et ses semblables signalent le fichier comme manquant. La racine du jeu est un dossier, pas un fichier : io.open sur elle renvoie nil, et lfs.mkdir et lfs.rmdir la refusent. lfs.dir sur un dossier empaqueté liste la réunion des trois endroits, triée sans tenir compte de la casse ; quand un fichier non empaqueté et un fichier empaqueté ne diffèrent que par la casse, c’est l’orthographe du fichier non empaqueté qui est listée. lfs.attributes sur un fichier empaqueté répond comme le vrai lfs : la table entière avec un seul argument, un champ par son nom (un nom inconnu lève une erreur), ou une table à vous qu’il remplit ; un fichier manquant renvoie nil, un message et le numéro d’erreur. require("name") trouve name.lua, name/init.lua ou name.singe sous le dossier du script, puis sous la racine du jeu.

io.open, io.lines et io.input sur un nom qui n’existe que dans la base de données renvoient un fichier propre à Singe plutôt qu’un fichier de Lua. Le handle de fichier de Lua est un FILE * du C, et une ligne de base de données n’est pas un fichier, si bien que la lire voulait dire autrefois l’écrire à côté du jeu et ouvrir cette copie ; le handle de Singe lit la ligne là où elle se trouve. Il répond à tout ce à quoi répond celui de Lua — read avec tous les formats ("a", "l", "L", "n" et un nombre d’octets), lines, seek, close, flush et setvbuf — io.type le considère comme un fichier, io.read et io.close l’acceptent, et il se ferme de lui-même quand il est collecté ou quand une variable <close> sort de sa portée. La seule différence est qu’y écrire est une erreur, parce que ce qu’il lit est dans la base de données et que la base de données n’est jamais écrite. Un jeu qui écrit un fichier en obtient un vrai dans son dossier de données exactement comme avant, et il en va de même pour chaque nom qui n’est pas empaqueté. testScripts/packedIo est le test qui confronte tout cela au comportement de Lua lui-même ; son en-tête dit comment le lancer.

L’empaqueteur refuse un dossier qui n’a pas de games.dat, qui contient controls.dat, Framework.singe, un fichier dont l’extension est exe, sh, bat ou cmd, ou un fichier sans extension dont le nom commence par singe, qui a une entrée de premier niveau portant le nom du dossier lui-même (cela rendrait ambiguë la règle du dossier propre au jeu), ou dont les scripts et les fichiers de données sortent du jeu avec .. ; il signale chacun de ces fichiers, avec la ligne. Deux fichiers dont les noms ne diffèrent que par la casse ne peuvent pas être empaquetés tous les deux. Les fichiers .index périmés sont ignorés. --unpack refuse une base de données dont les noms stockés atterriraient hors du dossier cible (un chemin absolu, une lettre de lecteur ou un composant ..). Un jeu qui fait référence au dossier d’un autre jeu (un framework partagé situé à côté de lui) doit d’abord copier ce dossier à l’intérieur. Avant que la base de données soit validée, son games.dat est vérifié : chaque entrée a besoin d’un SCRIPT, et chaque SCRIPT, VIDEO, CABINET, MARQUEE et ATTRACT qu’elle nomme doit être un fichier de la base de données (ou sous Singe/) ; un mauvais chemin est signalé avec le titre de l’entrée et l’empaquetage est refusé. --patch effectue la même vérification sur le jeu corrigé, si bien qu’un correctif ne peut pas non plus laisser derrière lui un chemin qui ne mène nulle part.

--patch prend soit un dossier organisé comme le jeu, dont les fichiers remplacent ceux qui sont empaquetés, soit un fichier .patch créé par --pack à partir d’un tel dossier (Singe --pack fixes MyGame-1.1.patch ; un correctif n’a pas besoin de games.dat). Les fichiers que le correctif ne nomme pas sont laissés tels quels. Dans les deux cas, le changement est une seule transaction : le jeu reste intact s’il est interrompu. Un correctif peut aussi porter une table removed(path) qui nomme des fichiers à supprimer. Un .patch peut être désempaqueté comme un jeu, mais il ne peut pas être lancé et le menu l’ignore.

Un correctif qui remplace un gros fichier par un petit laisse dans la base de données l’espace qu’occupait l’ancien contenu, où SQLite le garde pour la prochaine chose écrite plutôt que de le rendre. C’est sans importance pour un correctif qui change un script, et c’est du gaspillage pour un développeur qui réempaquette une vidéo une dizaine de fois : le .game peut finir par faire plusieurs fois la taille de son contenu. Aussi --patch regarde l’espace libre une fois la transaction validée et, quand il y en a au moins un mégaoctet, compacte la base de données et indique combien il a récupéré :

>>> Recovered 8007680 bytes of space the old contents were using

Le résultat a, à l’octet près, la taille d’un empaquetage neuf des mêmes fichiers. Le compactage réécrit le fichier entier, il est donc sauté quand il y a peu à gagner. Rien d’autre dans Singe n’en a besoin ; un jeu n’est jamais écrit que par l’empaqueteur.

Le dossier de données d’un jeu empaqueté porte le nom de la base de données, puis celui du dossier du script à l’intérieur : MyGame/ pour un MyGame.game dont le script se trouve à la racine, sous le dossier de données (data/MyGame/ par défaut), là même où l’a le MyGame/MyGame.singe non empaqueté, si bien que les sauvegardes et les réglages sont partagés entre une installation non empaquetée et une installation empaquetée ; un script empaqueté dans un sous-dossier (Game/Main.singe) obtient MyGame/Game/. L’index de la vidéo va là aussi.

Ce dossier appartient au jeu, non au nom de son fichier. Un jeu dont le games.dat porte un GAME_ID marque le dossier comme le sien la première fois qu’il y écrit, par un petit fichier package.id qui contient l’identifiant, et le retrouve ensuite grâce à lui : renommez MyGame.game, ou déplacez-le dans un autre dossier, et il utilise toujours MyGame/. Un autre jeu dont le fichier s’appelle lui aussi MyGame.game reçoit son propre dossier, MyGame- suivi des huit premiers caractères de son identifiant. Un dossier antérieur à ce marquage n’en porte aucun et revient au premier jeu de ce nom qui s’exécute. Un jeu sans GAME_ID n’a que le nom de son fichier pour se faire reconnaître : deux jeux de ce genre portant le même nom de fichier partagent donc un dossier, comme ils l’ont toujours fait.

Les versions 3.00 antérieures donnaient à un jeu empaqueté dont le script se trouvait dans un sous-dossier le dossier de données Game/ sous la base, que partageait chaque archive organisée de cette façon. Les sauvegardes d’un tel jeu ont désormais leur place sous MyGame/Game/ ; déplacez-les à la main. Les versions 3.00 antérieures gardaient aussi le dossier propre du jeu, celui sous lequel son games.dat nomme le script, si bien qu’un MyGame.game empaqueté depuis MyGame/ écrivait dans MyGame/MyGame/ ; remontez d’un niveau ce qui s’y trouve.

Quand Singe lance un jeu depuis une base de données, le menu passe CONTAINER dans l’entrée de games.dat qu’il lance ; ce champ est réglé par le menu, jamais à la main.

Pour vos propres données, require("sqlite3") donne aux scripts la liaison lsqlite3 vers le même SQLite que celui qu’utilise le moteur. Gardez les bases de données que le jeu écrit dans singeGetDataPath() :

local sqlite3 = require("sqlite3")
local db = sqlite3.open(singeGetDataPath() .. "scores.db")
db:exec("CREATE TABLE IF NOT EXISTS scores (name TEXT, score INTEGER)")
for row in db:nrows("SELECT name, score FROM scores ORDER BY score DESC LIMIT 10") do
    print(row.name, row.score)
end
db:close()

sqlite3.open trouve un nom comme le fait io.open, si bien qu’une base de données peut être livrée dans le jeu — tables de niveaux, dialogues, listes d’objets — et s’ouvrir quand même quand le jeu est empaqueté. Ouverte en lecture seule, une base de données empaquetée est lue là où elle se trouve, sans rien copier :

local levels = sqlite3.open(DIR .. "levels.db", sqlite3.OPEN_READONLY)

Ouverte en écriture, ce que fait par défaut sqlite3.open, une base de données empaquetée est copiée une fois dans le dossier de données du jeu, sous files/ comme tout ce qu’écrit un jeu empaqueté, et c’est la copie qui est ouverte. À partir de là, le nom désigne la copie, en lecture seule ou non, et l’original empaqueté n’est jamais modifié. La base de données d’un jeu non empaqueté s’ouvre sur place exactement comme avant. testScripts/packedSql est le test ; son en-tête dit comment le lancer.

Le format de fichier, pour qui écrit des outils : trois tables. meta(key, value) contient version (1), gamedir (le nom du dossier empaqueté), chunk (la taille des blocs en octets, 4194304) et packer. assets(path, name, size, data) a une ligne par fichier, path étant la clé en minuscules avec des barres obliques et name l’orthographe de l’auteur ; les fichiers qui ne dépassent pas la taille d’un bloc sont dans data, les plus gros ont data à NULL et vivent dans chunks(path, chunk, data) sous forme de morceaux numérotés consécutifs. Singe ouvre la base de données en lecture seule et immuable, si bien qu’il tourne depuis un support en lecture seule et n’écrit jamais de journal à côté.

1.9. Piloté par les événements…​ ou pas ?

Traditionnellement, Singe utilisait un modèle de programmation piloté par les événements — Singe s’occupe de tout et n’appelle votre code que lorsqu’il a besoin de vous dire quelque chose ou de mettre à jour l’écran. C’est efficace et c’est ainsi que fonctionnent la plupart des moteurs de jeu basés sur Lua, mais cela peut être verbeux. Depuis Singe 2.10, il existe un nouveau modèle à fil d’exécution (« threaded ») qui vous permet d’écrire du code procédural.

1.9.1. Piloté par les événements

Avec le modèle de programmation piloté par les événements, Singe contrôle la boucle principale du programme et décide de l’ordre d’exécution. Singe gère automatiquement tous les détails du décodage et de la présentation de la vidéo et du son. Il gère les manettes, les souris et le clavier. Quand Singe a besoin de quelque chose de propre au jeu, il appelle une partie de votre script. Le script Singe le plus simple qui montre tous les callbacks (fonctions de rappel) existants ressemble à ceci :

-- Squelette de jeu Singe.

-- Charge le framework de Singe.
dofile("Singe/Framework.singe")

-- Déclarez ici les variables globales dont vous avez besoin.

function onControllerMoved(axis, value, which)
    --[[
        Indique quel axe de manette a bougé, ainsi que sa valeur actuelle.
        (Plage : -32768 à 32767.) Sert pour les périphériques analogiques. Les
        entrées numériques sont gérées par onInput et onKey.
    --]]
end

function onInputPressed(what, device)
    --[[
        En MODE_NORMAL du clavier, les événements d'entrée sont signalés ici quand
        la touche ou le bouton est enfoncé. Pour la liste complète des touches,
        boutons et manettes, voir Singe/Framework.singe. En MODE_FULL, cet événement
        est appelé avec le keysym de la touche enfoncée. Quand le contact vient d'une
        souris ou d'un pistolet optique, device est l'index de ce périphérique (0 pour
        le premier), tel que le passe Hypseus, si bien qu'un jeu à deux pistolets peut
        distinguer ses joueurs ; pour une touche ou une manette, il vaut nil.
    --]]
end

function onInputReleased(what, device)
    --[[
        En MODE_NORMAL du clavier, les événements d'entrée sont signalés ici
        quand la touche ou le bouton est relâché. Pour la liste complète des
        touches, boutons et manettes, voir Singe/Framework.singe. En MODE_FULL,
        cet événement est appelé avec le keysym de la touche relâchée. device
        est comme pour onInputPressed.
    --]]
end

function onKeyPressed(key, scancode)
    --[[
        En MODE_FULL du clavier, les événements d'entrée sont signalés ici quand
        la touche est enfoncée. Le keysym et le scancode sont tous deux renvoyés.
        Pour la liste des scancodes disponibles, voir Singe/Framework.singe.
    --]]
end

function onKeyReleased(key, scancode)
    --[[
        En MODE_FULL du clavier, les événements d'entrée sont signalés ici quand
        la touche est relâchée. Le keysym et le scancode sont tous deux renvoyés.
        Pour la liste des scancodes disponibles, voir Singe/Framework.singe.
    --]]
end

function onMouseMoved(x, y, xr, yr, which)
    --[[
        Appelée quand la souris bouge. En mode SINGLE_MOUSE, les valeurs
        absolues de X et Y ainsi que le changement relatif de position sont
        renvoyés. En mode MANY_MOUSE, seul le changement relatif est disponible,
        ainsi que la souris qui a bougé.
    --]]
end

function onOverlayUpdate()
    --[[
        C'est le seul endroit où vous pouvez dessiner sans risque. Si vous
        voulez afficher un curseur de visée, il faut enregistrer la position de
        la souris reçue par onMouseMoved dans des variables globales, puis vous
        en servir ici pour dessiner le curseur.
    --]]

    -- Indique à Singe si l'affichage a changé ou non.
    return(OVERLAY_UPDATED)  -- Ou OVERLAY_NOT_UPDATED si rien n'a été dessiné.
end

function onShutdown()
    -- Appelée quand l'utilisateur quitte votre jeu. Libérez ici les ressources chargées.
end

function onSoundCompleted(channel)
    -- Le son sur « channel » vient de finir de jouer.
end

-- Remarque : il n'y a pas d'événement « onStartup ».
--            Tout code de démarrage nécessaire peut être placé ici.

1.9.2. À fil d’exécution

Depuis Singe 2.10, vous pouvez utiliser le modèle de programmation procédural classique. Pour utiliser ce modèle, déclarez une fonction singeMain() et incluez le framework de Singe à la fin de votre programme plutôt qu’au début. Lua n’est pas vraiment multithread, si bien que ce modèle compte sur le développeur du jeu pour faire du multitâche coopératif en appelant singeYield() partout où le code consomme un temps notable. Comme avec le modèle piloté par les événements, Singe gère toujours toutes les entrées, le décodage de la vidéo et le décodage du son. Un exemple de programme à fil d’exécution ressemble à ceci :

function singeMain()
    local x = 10
    local y = 10

    while true do
        colorBackground(0, 0, 0, 255)
        overlayClear()

        colorForeground(255, 255, 255, 255)
        overlayPrint(x, y, "+")

        if keyboardGetLastUp() == SCANCODE.LEFT.value  then x = x - 1 end
        if keyboardGetLastUp() == SCANCODE.RIGHT.value then x = x + 1 end
        if keyboardGetLastUp() == SCANCODE.UP.value    then y = y - 1 end
        if keyboardGetLastUp() == SCANCODE.DOWN.value  then y = y + 1 end

        singeYield()
    end
end

dofile("Singe/Framework.singe")

1.9.3. Hybride

Les deux modèles se combinent librement. Quand singeMain existe, Framework.singe installe son propre onOverlayUpdate, mais tous les autres callbacks sont toujours appelés : définissez onInputPressed, onSoundCompleted ou onShutdown à côté de singeMain et ils sont appelés entre les suspensions de la coroutine. Un découpage typique garde le déroulement du jeu procédural tout en réagissant aux événements d’entrée et de son :

local fired = false

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        fired = true
    end
end

function onSoundCompleted(channel)
    if channel == gunshotChannel then
        soundPlay(reloadSound)
    end
end

function singeMain()
    while true do
        if fired then
            fired = false
            gunshotChannel = soundPlay(gunshotSound)
        end
        singeYield()
    end
end

dofile("Singe/Framework.singe")

Ne définissez pas onOverlayUpdate vous-même dans ce modèle ; dessinez plutôt depuis singeMain. Une erreur levée dans singeMain termine le jeu avec une trace de pile, et revenir de singeMain quitte proprement.

1.10. La pause

Chaque jeu dispose d’office d’une pause qui fonctionne. Tant que la touche de pause est activée (c’est le cas par défaut), appuyer sur la touche affectée à INPUT_PAUSE fait que le moteur met en pause le disque, chaque vidéo chargée et chaque son, dessine un indicateur PAUSED par-dessus la dernière image et cesse d’exécuter le script : pas de onOverlayUpdate, pas de reprise de singeMain, pas de callbacks d’entrée, de souris, de manette ni de son. Les minuteries construites sur des bibliothèques Lua s’arrêtent avec lui, parce que plus rien ne les fait tourner. Appuyer de nouveau sur la touche reprend tout ce qui était en cours de lecture et le script continue là où il s’était arrêté. Seuls les contacts propres au moteur (pause, quitter, capture d’écran, capture de la souris) fonctionnent encore pendant le gel.

Les entrées restent fidèles à la réalité pendant le gel. Tout ce que le script croit maintenu enfoncé est relâché avec onInputReleased (ou onKeyReleased en MODE_FULL) quand la pause commence, et tout ce qui est encore physiquement maintenu quand la pause se termine est de nouveau enfoncé. Un joystick maintenu pendant une pause ne reste jamais bloqué.

Un jeu qui veut son propre comportement de pause (un menu de pause, un gel de l’histoire que le joueur ne doit pas pouvoir sauter) appelle singeSetPauseKeyEnabled(false). La touche est alors transmise au script sous la forme de SWITCH_PAUSE et le jeu pilote lui-même singeSetPauseFlag, qui met les médias en pause sans geler le script.

En MODE_FULL, le clavier appartient entièrement au jeu, donc les touches affectées aux contacts du moteur n’y font rien (un p tapé dans une saisie de meilleur score doit rester un p). Les boutons de manette et de souris affectés à ces contacts continuent de fonctionner dans les deux modes, puisqu’on ne peut pas les taper.

1.11. games.dat

Le fichier games.dat permet à Singe de trouver automatiquement les nouveaux jeux quand l’utilisateur final les installe. Ce fichier est extrêmement important et doit être inclus avec chaque jeu Singe. Placez games.dat dans le dossier le plus haut de votre jeu. Voici un exemple qui contient plusieurs jeux :

GAMES = {
    {
        TITLE         = "Asteroid Patrol",
        SCRIPT        = "Collection/AsteroidPatrol.singe",
        VIDEO         = "Collection/frame_AsteroidPatrol.txt",
        STRETCH       = false,
        NO_MOUSE      = false,
        RESOLUTION_X  = 720,
        RESOLUTION_Y  = 480,
        SINDEN_GUN    = "",
        GAME_ID       = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10",
        CABINET       = "Collection/cabinet_AsteroidPatrol.png",
        MARQUEE       = "Collection/marquee_Collection.png",
        ATTRACT       = "Collection/video_AsteroidPatrol.mkv",
        ATTRACT_START = 3000,
        ATTRACT_END   = 3500,
        YEAR          = 2026,
        PLATFORM      = "Laserdisc",
        DEVELOPER     = "Your Studio",
        PUBLISHER     = "Your Studio",
        GENRE         = "Shooter",
        DESCRIPTION   = "Keep the asteroids away from the station for as long as you can.",
        CREATOR       = "Scott Duensing",
        SOURCE        = "http://kangaroopunch.com"
    },
    -- ... d'autres entrées ...
}

Les clés SCRIPT, VIDEO, CANVAS_X, CANVAS_Y, STRETCH, NO_MOUSE, RESOLUTION_X, RESOLUTION_Y, SINDEN_GUN, AUDIO_TRACK, AUDIO_DELAY, AUDIO_SUFFIX, GAME_ID, LEGACY_SPRITE_ARGS, REQUIRES et TIER sont lues par le moteur quand le menu (ou votre propre script, par scriptExecute / scriptPush) lance l’entrée ; elles l’emportent sur la ligne de commande. La ligne VIDEO est le disque : une entrée qui en nomme un est un jeu laserdisc, et une entrée qui l’omet ou la laisse vide se lance sans disque et peut régler CANVAS_X / CANVAS_Y (720x480 par défaut) ; voir Jeux sans disque. AUDIO_SUFFIX = "-es" joue <base>-es.ogg, à côté de la vidéo du disque, au lieu du son qu’elle contient, pour une édition dont les autres langues sont livrées dans des fichiers séparés, ce que fait aussi --altaudio. LEGACY_SPRITE_ARGS = true lance un jeu écrit pour Singe 2.10 avec l’ancien ordre des arguments des sprites (voir Migrer depuis Singe 2.10). Les autres clés sont lues par le menu pour l’affichage.

REQUIRES indique ce dont le jeu a besoin de la part d’une machine, sous forme de liste de noms : "SCENE" (la scène 3D), "GUI" (les documents GUI), "SHADOWS", "POST" (le bloom et les autres effets qui veulent des cibles de rendu en virgule flottante), "SKIN" (les modèles avec skinning) et "MORPH" (les morph targets). Sans REQUIRES, le jeu est en 2D. Le menu signale un jeu que cette machine ne peut pas faire tourner et dit pourquoi au lieu de le lancer, et vous écrivez rarement la liste vous-même : le moteur remarque ce qu’un jeu utilise pendant qu’il tourne, signale dans la trace quand le jeu utilise quelque chose que REQUIRES ne liste pas, et --pack écrit la liste dans une entrée qui n’en a pas. TIER (0 à 3) indique la puissance de machine que demande le jeu ; le menu mesure le niveau de cette machine à partir de son propre décor de fond et signale un jeu qui en demande plus comme pouvant tourner lentement. Voir singeCapabilities.

REQUIRES = { "SCENE", "SHADOWS" },
TIER     = 1,

Un script lancé directement, par son nom ou par son dossier, reçoit le même traitement : Singe cherche un games.dat dans le dossier du script et jusqu’à trois dossiers au-dessus, et si le SCRIPT d’une entrée nomme le script lancé (les chemins des entrées partent du dossier situé au-dessus du games.dat, si bien que Collection/games.dat nomme Collection/AsteroidPatrol.singe), les clés de cette entrée s’appliquent. La seule différence avec un lancement depuis le menu est la priorité : une option tapée sur la ligne de commande (--framefile, --disc, --stretch, --nomouse, --xresolution, --yresolution, --sindengun, --audio, --audiodelay, --altaudio, --canvas) garde sa valeur, puisque la personne qui l’a tapée le voulait. Une valeur venue d’un fichier de réglages, non : c’est une valeur par défaut, et l’entrée décrit mieux le jeu (voir Le fichier de réglages). Un games.dat qui ne peut pas s’exécuter est signalé et ignoré lors d’un lancement direct.

1.12. Jeux sans disque

Singe ne suppose plus de laserdisc. Un jeu n’est un jeu laserdisc que lorsqu’il en nomme un : un VIDEO dans son entrée de games.dat, ou --disc (ou un --framefile) sur la ligne de commande. Tout le reste tourne sans disque, et le monde est un canevas au lieu d’une image de la vidéo : CANVAS_X / CANVAS_Y dans games.dat ou --canvas=WxH sur la ligne de commande, 720x480 par défaut, si bien qu’un jeu sans disque ressemble à un jeu laserdisc en définition standard, sauf s’il demande autre chose.

Sans disque, le moteur dessine sur du noir, l’overlay fait par défaut la moitié du canevas comme d’habitude, et les fonctions disc* et vldp* deviennent inoffensives : discGetState renvoie DISC_EJECTED, discGetFrame renvoie 0, discGetWidth / discGetHeight renvoient la taille du canevas, vldpGetPixel renvoie du noir, et les appels de transport écrivent dans la trace et ne font rien. Tout le reste — l’overlay, les sprites, les polices, les sons, les vidéos supplémentaires par videoLoad, les entrées et les deux modèles de programmation — est identique. La variable globale SINGE_DISC indique à un script en tant que quel type de jeu il tourne.

1.13. GUI

Les menus, les pages d’options, les HUD et la saisie des meilleurs scores se construisaient autrefois avec fontPrint, overlayBox et un curseur fait maison. Singe 3 ajoute une GUI : un document écrit en RML (un balisage proche du HTML) et mis en forme par RCSS (une feuille de style proche du CSS), mis en page et dessiné par RmlUi, avec retour à la ligne du texte, flexbox, panneaux en neuf tranches tirés de vos propres illustrations, transitions, animations, contrôles de formulaire et un modèle de focus qu’une manette peut piloter. Une GUI est un contexte RmlUi de taille fixe rendu dans sa propre texture, redessiné chaque fois que son image change (voir guiRefresh), et cette texture va partout où une texture peut aller : composée par-dessus l’overlay avec guiDraw, ou affichée sur un matériau de la scène 3D avec materialSetGui, si bien que la même page d’options fonctionne à plat sur l’écran et sur le moniteur d’une borne d’arcade modélisée. Une GUI a besoin du périphérique GPU qu’utilise la scène 3D, elle n’est donc pas disponible sur une machine qui n’en a pas (voir Performances et configuration requise) ; guiNew met fin au script au lieu de répondre false, alors interrogez d’abord singeHasGpu si votre jeu peut s’en passer. Le menu fourni fait exactement cela, et se dessine à la place dans l’overlay quand la réponse est non (voir Les deux moteurs de rendu). Chaque appel cité ici a une entrée dans la section Gui de la référence.

La référence des langages RML et RCSS est la documentation de RmlUi elle-même, sur https://mikke89.github.io/RmlUiDoc/, et elle mérite d’être lue avant le premier document ; ce chapitre couvre ce que Singe ajoute par-dessus.

1.13.1. Documents et feuilles de style

guiNew(width, height) crée une GUI et renvoie un handle entier ; il peut en exister jusqu’à seize à la fois. guiLoad(gui, name) y charge un document RML, l’affiche et renvoie un handle de document (jusqu’à trente-deux par GUI) ; guiHide, guiShow et guiClose font ce que disent leurs noms, et guiDelete supprime la GUI, ses documents et sa texture. Un document a généralement la taille de sa GUI, et une GUI a généralement la taille de l’overlay pour une page plein écran, ou celle du panneau pour un élément de HUD :

local gui = guiNew(overlayGetWidth(), overlayGetHeight())
local doc = guiLoad(gui, DIR .. "options.rml")

Le nom du document passe par le système de fichiers virtuel comme celui d’un sprite, il peut donc être un fichier non empaqueté sur le disque ou se trouver dans un jeu empaqueté, et il est résolu relativement au dossier depuis lequel Singe a été lancé : ajoutez donc DIR devant pour les fichiers livrés avec votre jeu, exactement comme pour spriteLoad. Les noms à l’intérieur d’un document (le href d’une feuille de style, une image dans un décorateur, le src d’une planche de sprites) sont résolus relativement au fichier qui les nomme, comme le fait RmlUi, puis par la même recherche, si bien qu’un document, sa feuille de style et ses images se trouvent côte à côte dans le dossier du jeu et qu’un jeu empaqueté les trouve tous. Deux sortes de noms sont pris tels quels : les fichiers propres au moteur sous Singe/, et les chemins absolus.

La même règle lue dans l’autre sens permet à un document qui se trouve sous Singe/ d’atteindre les fichiers d’un jeu : un nom relatif est résolu depuis le dossier du document lui-même, donc depuis Singe/Menu.rml le nom ../Collection/cabinet.png est Collection/cabinet.png dans le dossier du jeu, et un nom sous ../MyGame.game/ est un fichier dans ce jeu empaqueté. Le menu fourni fait exactement cela pour les illustrations de borne et de fronton du jeu sélectionné, en réglant depuis Lua un décorateur d’image sur le panneau d’illustration pour que l’image y soit ajustée quelle que soit sa taille :

-- Menu.singe : ajuste l'image d'un jeu dans l'un des panneaux d'illustration.
function menuArt(id, file)
    local path = tostring(file or "")
    if path:sub(1, 6):lower() ~= "singe/" then
        path = "../" .. path
    end
    menuElement(id).style.decorator = 'image("' .. path .. '" contain)'
end

Un document RML est un <head> avec un titre, des liens vers des feuilles de style ou un <style> en ligne, et un <body> d’éléments. En voici un minimal, qui utilise le thème fourni :

<rml>
<head>
	<title>Options</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		.panel { margin: 30dp; }
	</style>
</head>
<body id="options">
	<div class="panel">
		<h1>Options</h1>
		<p class="muted" id="status">Choose a difficulty and press Start.</p>
		<button id="go">Start</button>
	</div>
</body>
</rml>

RmlUi ne dessine rien dont on ne lui a pas donné la taille, et chaque élément est display: inline tant qu’un style ne dit pas autre chose, donc une feuille de style n’est pas facultative. Singe/gui.rcss est le thème que livre le moteur : il donne au corps, aux titres et aux paragraphes une taille et une couleur, fait de div un bloc, et met en forme chaque contrôle de formulaire. Liez-le en premier et redéfinissez ce que vous voulez dans une feuille à vous ou dans un <style> en ligne ; la règle la plus tardive l’emporte, comme en CSS. Les longueurs du thème sont en dp, le pixel indépendant de la densité de RmlUi, qui vaut un pixel à la taille propre de la GUI.

Le texte a besoin d’une police. Le moteur charge Singe/FreeSansBold.ttf pour chaque GUI comme police de secours (la police qui fournit tout glyphe qu’aucune autre police n’a) ; son nom de famille est FreeSans et elle est en gras, ce que demande la règle body du thème. guiLoadFont(name) ajoute l’une des polices propres au jeu pour chaque GUI, et guiLoadFont(name, true) en fait plutôt la police de secours. Un document désigne une police par le nom de famille inscrit dans le fichier, pas par le nom du fichier, donc chargez les polices avant les documents qui les utilisent :

guiLoadFont(DIR .. "fonts/Orbitron-Bold.ttf")
h1 { font-family: Orbitron; font-weight: bold; }

Les effets RCSS de RmlUi sont dessinés en entier. Les enfants d’un élément arrondi ou transformé sont découpés selon sa forme (une liste qui défile avec border-radius rejoint son cadre dans la courbe), filter: opacity() estompe un groupe d’un seul bloc (la propriété opacity estompe chaque morceau séparément, comme le définit RmlUi), mask-image découpe un élément selon l’alpha d’une image, box-shadow projette des ombres dures ou douces, et filter et backdrop-filter acceptent blur, drop-shadow, brightness, contrast, invert, grayscale, sepia, hue-rotate et saturate. Les décorateurs linear-gradient, radial-gradient et conic-gradient (répétés ou non) sont dessinés comme tels ; les panneaux, les boutons et les barres de progression du thème fourni s’en servent. Trois limites : le décorateur personnalisé shader n’est pas pris en charge (il est refusé avec un avertissement), un dégradé porte au plus seize arrêts de couleur (les suivants sont abandonnés), et les effets s’imbriquent sur huit calques au plus (un élément plus profond est dessiné sans son propre calque). Chaque effet est rendu par un calque de la taille de la GUI, et un flou en plusieurs passes, donc sur un Pi limitez-les à quelques éléments et surveillez guiGetStats, qui compte les calques, les passes et les octets qu’une image a coûtés.

1.13.2. Thèmes

Un thème est un dossier de RCSS et d’images, et un jeu livre son propre style comme il livre des sprites. La forme habituelle est une feuille liée après Singe/gui.rcss qui redéfinit le style des classes du thème et ajoute les siennes, avec les illustrations à côté. Le thème fourni définit :

  • .panel — une boîte bordée, arrondie et translucide avec une marge intérieure, le cadre d’une page ou d’une boîte de dialogue.

  • .list — une boîte qui défile, dont les éléments div enfants sont des lignes : ils prennent le focus, sont mis en évidence au survol et au focus, et une ligne qui a la classe selected reste mise en évidence. Une barre de défilement verticale apparaît quand les lignes débordent.

  • .muted — un texte plus terne, pour les indications et les lignes d’état.

  • Les contrôles de formulaire : button et input.submit, input.text, input.password et textarea, input.checkbox et input.radio, input.range avec sa piste et son curseur, select avec sa flèche et sa liste déroulante, et progress avec son remplissage ; chacun avec des états survol, focus et actif, et chacun pouvant recevoir le focus grâce à tab-index: auto, pour qu’une manette puisse l’atteindre.

Un panneau tiré de vos propres illustrations est un décorateur en neuf tranches appliqué à une planche de sprites, et les animations sont des images clés RCSS, si bien qu’une barre de chargement qui se remplit toute seule n’a besoin d’aucun script :

@spritesheet crate {
	src: crate.png;
	crate-outer: 0px 0px 40px 40px;
	crate-inner: 10px 10px 20px 20px;
}

.crate {
	display: block;
	decorator: ninepatch(crate-outer, crate-inner, 1.0);
	padding: 14dp;
}

@keyframes fill {
	from { width: 0%; }
	to   { width: 100%; }
}

.bar fill {
	animation: 3s cubic-in-out infinite alternate fill;
}

1.13.3. Piloter un document par script

Il y a deux API, et il vaut mieux savoir clairement laquelle est laquelle. Les appels gui* à plat, dans le style propre à Singe, créent une GUI, chargent et dessinent des documents, acheminent les entrées et atteignent les éléments par id : guiGetValue(gui, doc, id) lit la valeur d’un contrôle de formulaire, ou le RML intérieur de tout autre élément, sous forme de chaîne ; guiSetValue(gui, doc, id, value) en écrit une ; et guiSetHandler(gui, doc, id, event, function) appelle une fonction Lua quand l’élément déclenche un événement ("click", "change", "submit" ou tout autre nom d’événement RmlUi). La fonction reçoit (gui, document, id, event, value), value étant la valeur de l’élément sous forme de chaîne au moment de l’événement : le texte d’un champ texte, la valeur d’une option de select, un intervalle dans le format propre à RmlUi ("48.000000"), le RML intérieur d’un bouton. Tout ce dont une page a besoin au quotidien est couvert par ces trois appels :

guiSetHandler(gui, doc, "go", "click", function(g, d, id, event, value)
    local name = guiGetValue(g, d, "name")
    local hard = guiGetValue(g, d, "difficulty") == "hard"
    startGame(name, hard)
end)
guiSetHandler(gui, doc, "volume", "change", function(g, d, id, event, value)
    soundSetVolume(math.floor(tonumber(value)))
    guiSetValue(g, d, "status", "Volume " .. math.floor(tonumber(value)))
end)

Tout le reste, dans un document, relève de l’API Lua de RmlUi, qui tourne sur l’état Lua propre au jeu : un bloc <script> dans un document, ainsi que onclick et les autres attributs on*, s’exécutent avec les variables globales du jeu, si bien qu’ils peuvent appeler vos fonctions comme les appels gui*. Côté script, les mêmes objets sont accessibles par la variable globale rmlui : les contextes sont nommés gui0, gui1, …​ d’après leurs handles, et les documents sont indexés par l’identifiant id de leur <body>, si bien que le bouton ci-dessus est rmlui.contexts["gui0"].documents["options"]:GetElementById("go"), et que :DispatchEvent("click", {}) sur lui l’enfonce depuis le script (utile pour les tests qui tournent sans souris). Les éléments, leurs attributs, classes, styles et enfants, les liaisons data-model qui reflètent une table Lua dans un document, et le reste du modèle objet sont documentés avec le plugin Lua de RmlUi sur https://mikke89.github.io/RmlUiDoc/ ; guiSetHandler est le raccourci par id, pas un remplaçant. Un document fermé par cette API (document:Close()) est oublié par le moteur, et son handle lève ensuite une erreur.

1.13.4. Entrées

Une nouvelle GUI ne fait qu’afficher, ce qui convient à un HUD ou à une enseigne ; guiSetInput(gui, true) lui fait prendre les entrées, et guiSetInput(gui, false) les lui retire de nouveau. Pour une GUI qui prend les entrées :

  • La souris et un pistolet optique (qui est une souris) arrivent en coordonnées de l’overlay, transformées par la bordure Sinden et l’échelle d’overscan exactement comme pour onMouseMoved, en mode MOUSE_SINGLE. Le moteur trouve la GUI qui se trouve sous le pointeur — la dernière dessinée à plat à cet endroit pendant cette image est au-dessus, et à défaut une surface de la scène dont le matériau en affiche une (voir plus bas) — et convertit la position en pixels propres à cette GUI. Un appui sur un élément appartient à la GUI ; les boutons gauche, droit et du milieu cliquent, et la molette fait défiler.

  • Les touches vont à chaque GUI qui prend les entrées, et une touche qu’un élément ayant le focus a utilisée (un caractère dans un champ texte, une flèche qui a déplacé le focus, Entrée sur un bouton) est consommée. Tant qu’un champ texte ou mot de passe ou un textarea a le focus, le moteur active la saisie de texte de SDL, si bien que le texte tapé arrive sous forme de texte, en respectant la disposition du clavier et tout clavier à l’écran ou IME.

  • Les contacts de manette et de souris (les affectations SWITCH_* du framework depuis un bouton de manette ou de souris) sont traduits en touches qu’un document comprend : les quatre directions deviennent les touches fléchées, INPUT_ACTION_1 devient Entrée et INPUT_ACTION_2 Échap. Un contact affecté à une touche du clavier atteint déjà la GUI sous la forme de cette touche.

La règle qui rend un HUD sûr est qu'un événement qu’un élément a utilisé n’atteint jamais le jeu : une touche consommée n’arrive pas comme onInputPressed ou onKeyPressed, un clic sur un bouton n’arrive pas comme un contact de souris, une direction traduite qui a déplacé le focus n’arrive pas comme SWITCH_UP. Tout ce qu’un document n’a pas utilisé passe aux callbacks habituels, si bien qu’un HUD qui prend les entrées laisse quand même passer le bouton de tir, et qu’une page où rien n’a le focus laisse passer toutes les touches.

Le focus et la navigation sont l’affaire du document lui-même. Le thème fourni donne à chaque contrôle et à chaque ligne de .list un tab-index: auto, si bien que Tab passe de l’un à l’autre, qu’Entrée active le contrôle qui a le focus, et que les touches fléchées se déplacent entre les contrôles grâce aux propriétés nav de RmlUi (nav-up, nav-down, nav-left, nav-right, ou nav: auto pour les quatre). Une page destinée à une borne avec un stick et deux boutons les veut sur tout ce que le joueur doit pouvoir atteindre :

button, .list div { nav: auto; }

1.13.5. Une GUI dans la scène

materialSetGui(material, gui) affiche la texture d’une GUI comme texture de couleur de base d’un matériau, mise à jour à chaque image, à côté de materialSetVideo et de materialSetView : un moniteur, un tableau de bord de cockpit, une enseigne. Associez-le à materialSetUnlit quand l’image ne doit pas être ombrée, et laissez le matériau éclairé quand elle doit l’être. Rien d’autre ne change ; le matériau est éclairé, mélangé et reflété comme n’importe quel autre, et la même GUI peut être dessinée à plat par-dessus l’overlay pendant la même image.

sceneProbeGui(x, y) indique quelle GUI se trouve sur la surface sous un point de l’overlay, et à quel endroit : un rayon partant de la caméra et passant par le point est lancé contre chaque maillage visible dont le matériau affiche une GUI, et l’appel renvoie le handle et le pixel dans les coordonnées propres à cette GUI, ou nil quand le point n’est sur aucune surface de ce genre. Le moteur lui pose la même question quand la souris ou un pistolet optique vise la scène et que rien de dessiné à plat ne se trouve sous le pointeur, si bien qu’un clic sur le moniteur d’une borne en 3D appuie sur le bouton qui se trouve dessous sans que le script intervienne ; l’appel est là pour un jeu qui veut le savoir par lui-même, pour un viseur laser, un effet de survol ou un test.

local screen = materialNew()
materialSetGui(screen, gui)
materialSetUnlit(screen, true)
nodeSetMesh(monitor, meshPlane(3.0, 2.0), screen)
nodeSetRotation(monitor, 90, 0, 0)

1.13.6. Rechargement, performances et limites

Une GUI appartient au script qui l’a créée. Quitter, scriptPush, scriptExecute et un rechargement (voir Recharger pendant que vous travaillez) détruisent chaque GUI et chaque document avec le reste de l’état du script, et le script les recrée quand il s’exécute ; rien du modèle objet rmlui ne survit, alors ne gardez pas ces objets dans des variables globales qu’un rechargement réutiliserait.

Chaque GUI se met à jour à chaque image, qu’elle soit dessinée quelque part ou non, si bien qu’un document continue de faire tourner ses animations et ses scripts hors de l’écran, et qu’une GUI dont on n’a plus besoin doit être supprimée plutôt que simplement cachée. Elle n’est redessinée dans sa texture que lorsque son image change, si bien qu’une page ou un HUD immobile ne coûte presque rien au GPU (voir guiRefresh). Le coût d’une image qui change, c’est la taille de la texture et la complexité du document : sur un ordinateur de bureau, une page plein écran ne coûte pas cher ; sur un Raspberry Pi, gardez une GUI à la taille de l’overlay ou plus petite, et préférez une GUI avec plusieurs documents à plusieurs GUI. Chaque police coûte un atlas par taille à laquelle elle est utilisée, si bien qu’une page qui utilise une police à trois tailles paie trois atlas ; une douzaine de tailles en coûte une douzaine. Seize GUI peuvent exister à la fois, chacune avec trente-deux documents, et seize appels à guiDraw sont pris en compte par image.

Ce qu’un document peut afficher, et ce qu’il ne peut pas :

  • Les images viennent de fichiers. Les images, les planches de sprites et les décorateurs d’image chargent du PNG et les autres formats que lit Singe, depuis le disque ou depuis un jeu empaqueté. Un document ne peut pas afficher un sprite de Singe, une vidéo, la scène 3D ni rien de ce qui est dessiné pendant que le jeu tourne, et un script ne peut pas lui fournir de pixels. L’inverse fonctionne : la texture d’une GUI va sur un matériau 3D avec materialSetGui.

  • Décorateurs : image, text, tiled-horizontal, tiled-vertical, tiled-box, ninepatch, le gradient à deux couleurs (et ses noms horizontal-gradient et vertical-gradient), et linear-gradient, radial-gradient et conic-gradient avec leurs formes repeating-, avec au plus seize arrêts de couleur. Le décorateur personnalisé shader est refusé.

  • Filtres : opacity, blur, drop-shadow, brightness, contrast, invert, grayscale, sepia, hue-rotate et saturate. Tout autre nom est ignoré, avec un avertissement dans la trace.

  • Calques : les filtres, une opacity inférieure à 1, les images de masque et les ombres de boîte passent chacun par un calque de la taille de la GUI, et huit au plus s’empilent à la fois ; un de plus est dessiné sans son calque, et donc sans son effet.

  • Les images de plus de 64 Mo sont refusées.

  • RML et RCSS sont ceux de RmlUi, proches du HTML et du CSS sans être identiques : il y a flexbox mais pas de grille CSS, et un document est piloté par script en Lua, par guiSetHandler et l’objet rmlui, plutôt qu’en JavaScript. La documentation de RmlUi fait autorité sur ce que contiennent ces langages.

1.13.7. Un exemple complet

Une page d’options par-dessus le disque : un panneau du thème fourni avec un champ de nom, un curseur de volume, une liste de difficulté et deux boutons, dessiné par-dessus l’overlay et piloté par la souris ou le stick. Le document, options.rml, à côté du script :

<rml>
<head>
	<title>Options</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		.panel { margin: 30dp; }
		.field { display: block; margin: 6dp 0; }
		label { display: inline-block; width: 140dp; }
		input.text { width: 300dp; }
		button, input { nav: auto; }
		#status { min-height: 30dp; }
	</style>
</head>
<body id="options">
	<div class="panel">
		<h1>Options</h1>
		<div class="field"><label>Name</label><input type="text" id="name" value="Dirk"/></div>
		<div class="field"><label>Volume</label><input type="range" id="volume" min="0" max="63" step="1" value="48"/></div>
		<div class="field"><label>Difficulty</label>
			<select id="difficulty">
				<option value="easy">Easy</option>
				<option value="normal" selected>Normal</option>
				<option value="hard">Hard</option>
			</select>
		</div>
		<div class="field"><label>Attract</label><input type="checkbox" id="attract" checked/> plays the intro</div>
		<div class="field"><button id="go">Start</button><button id="back">Back</button></div>
		<p id="status" class="muted">Press Start when ready.</p>
	</div>
</body>
</rml>

Le script le charge dans une GUI de la taille de l’overlay, branche les trois éléments qui l’intéressent, et la dessine à chaque image jusqu’à ce que le joueur appuie sur Start ; le disque joue en dessous pendant tout ce temps :

dofile("Singe/Framework.singe")

local gui      = guiNew(overlayGetWidth(), overlayGetHeight())
local doc      = guiLoad(gui, DIR .. "options.rml")
local settings = { name = "Dirk", volume = 48, hard = false }
local inMenu   = true

local function report(text)
    guiSetValue(gui, doc, "status", text)
end

guiSetHandler(gui, doc, "volume", "change", function(g, d, id, event, value)
    settings.volume = math.floor(tonumber(value))
    soundSetVolume(settings.volume)
    report("Volume " .. settings.volume)
end)

guiSetHandler(gui, doc, "difficulty", "change", function(g, d, id, event, value)
    settings.hard = (value == "hard")
    report("Difficulty " .. value)
end)

guiSetHandler(gui, doc, "go", "click", function(g, d)
    settings.name = guiGetValue(g, d, "name")
    guiHide(g, d)
    guiSetInput(g, false)
    inMenu = false
    discPlay()
end)

guiSetHandler(gui, doc, "back", "click", function()
    singeQuit()
end)

function onInputPressed(what)
    -- Seul ce que la page n'a pas utilisé arrive ici : rien tant qu'elle a le
    -- focus, tout une fois qu'elle est cachée.
    if not inMenu and what == SWITCH_BUTTON1 then
        fire()
    end
end

function onOverlayUpdate()
    overlayClear()
    if inMenu then
        guiDraw(gui)
    else
        fontPrint(10, 10, settings.name .. "  " .. (settings.hard and "HARD" or "NORMAL"))
    end
    return OVERLAY_UPDATED
end

La même page sur l’écran d’une borne modélisée, ce sont les cinq lignes de Une GUI dans la scène à la place de guiDraw, et un clic sur le moniteur appuie sur le bouton qui se trouve dessous.

1.14. Sous-titres

Un jeu peut livrer un fichier de sous-titres SubRip et demander à Singe de l’afficher par-dessus le disque pendant la lecture. Trois appels font tout le travail : srtLoad lit le fichier, srtEnable l’active, et srtPosition indique où se placent les lignes. srtClear retire ce qui est affiché. La fonctionnalité vient d’Hypseus Singe, et les quatre appels sont les siens.

if srtLoad("subs/english.srt") then
    srtPosition(80)
    srtEnable(true)
end

1.14.1. Le format de fichier

SubRip (.srt) est un fichier texte brut de sous-titres numérotés :

1
00:00:04,120 --> 00:00:06,880
Stay away from the caves.

2
00:00:07,000 --> 00:00:09,500
I mean it -- the caves
are where they nest.

Chaque sous-titre est un numéro seul sur sa ligne, puis une ligne contenant deux horodatages séparés par -→, puis une ou plusieurs lignes de texte, puis une ligne vide. Un horodatage s’écrit HH:MM:SS,mmm : les heures, les minutes et les secondes séparées par des deux-points, et les millisecondes après une virgule. Le numéro du sous-titre est lu puis jeté, si bien que les numéros n’ont pas besoin d’être dans l’ordre, ni même d’être justes.

L’analyseur est volontairement tolérant aux endroits où un fichier modifié à la main tourne mal. Les retours chariot et les espaces au début et à la fin sont retirés de chaque ligne, si bien qu’un fichier écrit sous Windows se charge tel quel. Un sous-titre dont la ligne de temps n’a pas de -→, ou dont les horodatages ne s’analysent pas, est sauté et le chargement du fichier continue. Un sous-titre sans texte est sauté. Les lignes d’un sous-titre sont jointes par des retours à la ligne et affichées telles qu’elles sont écrites, et <, > et & arrivent à l’écran tels quels au lieu d’être pris pour du balisage.

Ce qui n’est pas pris en charge : les coordonnées de positionnement que certains outils ajoutent à la ligne de temps sont ignorées (srtPosition décide de la hauteur), et les balises <i> et <b> qu’on trouve parfois dans SubRip sont affichées comme du texte au lieu d’être appliquées. Les sous-titres peuvent se chevaucher dans le temps ; le dernier qui a commencé l’emporte.

srtLoad répond false et ne charge rien quand le fichier ne peut pas être lu, quand rien dedans ne s’analyse, ou quand il n’y a pas de disque — si bien qu’un fichier cassé est un false sur lequel un jeu peut agir, et non un plantage. Il affiche dans chaque cas un avertissement qui nomme le fichier.

1.14.2. La synchronisation

Les horodatages sont convertis en numéros d’image du disque au chargement du fichier, d’après la fréquence d’images du disque chargé à ce moment-là, et le moteur compare chaque image dessinée à ces numéros. Il en découle deux choses.

Premièrement, un sous-titre survit à un saut. Envoyer le disque n’importe où — discSearch, discSkipForward, un pas, un framefile qui passe dans un autre segment — affiche le sous-titre qui couvre l’endroit où il a atterri, à la prochaine image dessinée, en avant comme en arrière. Rien n’a besoin d’être rechargé et aucune horloge n’a besoin d’être remise à zéro.

Deuxièmement, le fichier doit être synchronisé sur le disque, pas sur l’horloge. Un .srt découpé pour une vidéo à une autre fréquence d’images tombe au mauvais endroit, et un fichier chargé avant l’ouverture du disque ne se charge pas du tout. Chargez les sous-titres après le disque, ce qui pour un jeu ordinaire veut dire depuis le corps du script.

Un sous-titre est affiché tant que l’image du disque se trouve entre ses deux images, incluses. L’affichage n’est redessiné que lorsque le sous-titre change, si bien que les sous-titres ne coûtent rien tant qu’une ligne reste affichée.

1.14.3. Mise en forme

Les lignes sont un document RmlUi, pas une ligne de texte copiée par blit, si bien qu’elles se mettent en forme comme une GUI. Deux fichiers sont livrés dans le dossier Singe et extraits à côté des autres au premier lancement :

  • Singe/subtitle.rml — le document. Il a un seul élément, #slot, dans lequel le moteur écrit le sous-titre en cours ou le bandeau.

  • Singe/subtitle.rcss — l’apparence. .cue est le bloc qui porte la hauteur demandée par srtPosition, sous forme d’un top en ligne ; .cue .text est la barre de texte qu’il contient, qui par défaut est blanche sur un panneau sombre arrondi qui épouse le texte au lieu de couvrir toute l’image.

Tous deux sont réécrits à chaque démarrage, comme tout ce que contient le dossier Singe, si bien que les modifier ne change rien bien longtemps. Pour changer le style, un jeu fournit ses propres copies : un subtitle.rml à côté de son script, dont le lien renvoie à une feuille à lui (un subtitle.rcss à côté, par exemple), et Singe dessine ce document à la place du sien ; la trace du programme le signale. Le moteur ne règle jamais que le contenu de #slot et le top de .cue, si bien que tout le reste — la police, la taille, les couleurs, le panneau, une bordure, une ombre — relève de la feuille du jeu et survit à une mise à jour du moteur. Le document est dessiné par-dessus l’image, au-dessus de l’overlay et sous les GUI en espace écran, suit le rectangle de la vidéo partout où le placent --scalefactor, --shiftx, une découpe de bezel ou --rotate, et ne prend aucune entrée de souris, si bien qu’un clic le traverse directement.

overlayBanner utilise le même document, si bien qu’un bandeau et un sous-titre se ressemblent, et qu’un jeu qui change le style de l’un change celui des deux.

Sur une machine sans GPU, il n’y a aucune GUI ; srtLoad analyse quand même le fichier et répond honnêtement, et rien n’est dessiné. Un avertissement le signale une fois.

1.15. Scènes 3D

Singe 3 dessine une scène 3D entre la vidéo du laserdisc et l’overlay 2D. Tout ce que vous savez déjà reste valable : les sprites, le texte et l’overlay se placent par-dessus la scène, et la vidéo apparaît partout où le fond de la scène est transparent. Un jeu qui n’appelle jamais de fonction 3D n’est pas concerné, et un jeu sans disque (voir Jeux sans disque) peut être carrément un jeu 3D.

Les sections qui suivent construisent une scène dans l’ordre où vous en écrirez une : les nœuds, puis les maillages et les matériaux, les lumières, la caméra, l’aspect de l’image dans son ensemble, les modèles, et enfin ce qui se place par-dessus tout cela. Chaque appel cité ici a une entrée dans la Référence de l’API Lua.

1.15.1. De quoi est faite une scène

Tout ce qui se trouve dans une scène est un nœud d’un seul et même arbre, et le nœud 0 en est la racine. Un nœud a une position, une rotation et une échelle relatives à son parent, et il peut porter une seule chose : un maillage avec un matériau, une lumière, un sprite ou une ligne de texte. Un modèle chargé devient un sous-arbre de nœuds sous une seule racine, si bien que les mêmes appels déplacent aussi bien un personnage modélisé qu’un cube créé par script.

La scène est en repère direct, +Y vers le haut et -Z vers l’avant, comme glTF et l’export de Blender. Les unités sont celles qu’utilisent vos modèles, et les primitives prennent les mêmes unités ; la physique (voir Physique) suppose des mètres. Les rotations sont en degrés, données sous forme de trois angles d’Euler appliqués comme lacet, tangage et roulis, ou sous forme de quaternion quand la valeur vient d’un modèle. L’avant propre d’un nœud est son -Z : la caméra regarde dans cette direction, les lumières directionnelles et les projecteurs éclairent dans cette direction, et nodeLookAt le tourne vers un point du monde.

Il y a deux façons de remplir une scène, qui se combinent librement :

  • La construire par script avec les maillages primitifs (meshBox, meshSphere, meshPlane, meshCylinder, meshCone, meshTorus, meshHeightmap) ou vos propres données de sommets (meshNew), plus des matériaux, des lumières et une caméra.

  • Charger des modèles au format binaire glTF 2.0 (.glb) avec modelLoad, puis les placer avec modelInstance autant de fois que vous voulez. Blender, Maya, 3ds Max et tous les grands moteurs exportent en .glb.

Une scène minimale, c’est un maillage, une lumière et une caméra :

sceneEnable(true)
sceneSetBackground(0, 0, 0, 0)     -- Transparent : le disque apparaît derrière la scène.

local red = materialNew()
materialSetColor(red, 220, 40, 40)

local cube = nodeNew()
nodeSetMesh(cube, meshBox(1, 1, 1), red)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 2, 4, 3)
nodeLookAt(sun, 0, 0, 0)

local camera = nodeNew()
nodeSetPosition(camera, 0, 1.5, 5)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)

function onOverlayUpdate()
    nodeRotate(cube, 0, 1, 0)      -- Un degré par image autour de son propre Y.
    return OVERLAY_UPDATED
end

sceneEnable(true) est l’appel que fait tout jeu 3D, et sur une machine qui ne sait pas dessiner en 3D, c’est l’appel qui échoue (voir Performances et configuration requise). Sans caméra, la scène est vue depuis (0, 0, 5) en regardant l’origine, et sans appel de fond, le fond de la scène est noir opaque.

1.15.2. Les nœuds

La transformation d’un nœud se règle d’un coup (nodeSetPosition, nodeSetRotation, nodeSetQuaternion, nodeSetScale) ou par petites touches (nodeMove, nodeRotate), toujours dans l’espace de son parent. nodeSetParent raccroche un nœud ailleurs en gardant sa transformation locale ; nodeGetWorldPosition lit où il a fini une fois que chaque parent a eu son mot à dire. nodeSetVisible cache un nœud et tout ce qui se trouve en dessous, et nodeDelete le libère avec ses enfants, ainsi que tout corps, émetteur ou son qui leur est attaché.

Les noms viennent des modèles : nodeFind(name, root) trouve une articulation ou une pièce par le nom qu’elle avait dans le fichier, sous l’instance donnée comme root. Un nœud créé par script peut aussi recevoir un nom (nodeSetName), et c’est là que cherche nodeFind sans racine.

-- Une tourelle sur un char : le canon est un enfant de la tourelle, la tourelle de la caisse,
-- si bien que tourner la tourelle entraîne le canon et que déplacer la caisse entraîne les deux.
local hull   = nodeNew()
local turret = nodeNew()
local barrel = nodeNew()
nodeSetMesh(hull, meshBox(2, 0.8, 3.2), olive)
nodeSetMesh(turret, meshCylinder(0.7, 0.5, 16), olive)
nodeSetMesh(barrel, meshCylinder(0.1, 1.8, 8), steel)
nodeSetParent(turret, hull)
nodeSetParent(barrel, turret)
nodeSetPosition(turret, 0, 0.65, 0)
nodeSetPosition(barrel, 0, 0, -1.2)
nodeSetRotation(barrel, 90, 0, 0)          -- Couche le cylindre le long de -Z.

function onOverlayUpdate()
    local stick = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_X) / 32767   -- De -1 à 1.
    nodeRotate(turret, 0, stick * 2, 0)
    return OVERLAY_NOT_UPDATED
end

Deux appels font le pont entre la scène et l’overlay. sceneProject(x, y, z) transforme un point du monde en coordonnées de l’overlay, si bien qu’une étiquette de nom ou une barre de vie dessinée avec fontPrint peut suivre un objet 3D. sceneUnproject(sx, sy, distance) fait l’inverse : il donne le point du monde situé à cette distance sur le rayon qui passe par un pixel de l’overlay, ce qui, avec physicsRaycast, permet la sélection à la souris.

function onMouseMoved(x, y, dx, dy, which)
    -- La souris pointe le long d'un rayon partant de la caméra ; ce qu'il touche est la cible.
    local cx, cy, cz = nodeGetWorldPosition(camera)
    local fx, fy, fz = sceneUnproject(x, y, 50)
    local hit = physicsRaycast(cx, cy, cz, fx - cx, fy - cy, fz - cz, 50)
    highlighted = hit
end

1.15.3. Maillages et matériaux

Un maillage est une géométrie ; un matériau est son apparence ; un nœud réunit l’un et l’autre (nodeSetMesh(node, mesh, material)). Partagez-les librement : un seul meshBox et un seul matériau peuvent se trouver sur mille nœuds, et c’est ce partage qui rend le moteur de rendu rapide (voir Performances et configuration requise). meshNew construit un maillage à partir de tables de positions, de normales, de coordonnées de texture et d’indices quand les primitives ne suffisent pas.

Un matériau commence par une couleur de base avec alpha (materialSetColor) et l’aspect métal-rugosité de glTF : materialSetMetallic et materialSetRoughness, de 0 à 1. Une rugosité proche de 0 donne un reflet net comme dans un miroir, et 1 une surface mate ; un métal teinte ses reflets et ses réflexions de sa propre couleur et n’a pas de couleur diffuse à lui. Au-delà :

  • materialSetEmissive fait émettre à une surface une lumière de sa propre couleur (un écran, une lampe, du métal chauffé) ; elle n’éclaire pas les autres objets, mais elle produit du bloom (voir L’aspect de l’image).

  • materialSetUnlit affiche la couleur telle quelle, en ignorant toutes les lumières : éléments de HUD dans la scène, lueur propre au verre d’une ampoule.

  • materialSetDoubleSided dessine l’arrière des formes ouvertes, comme un plan vu d’en dessous ou un drapeau.

  • materialSetBlend fait compter l’alpha, pour le verre, les fantômes et l’eau. Les maillages mélangés sont dessinés après tout ce qui est opaque, triés par distance, et ne projettent pas d’ombre.

  • materialSetCutoff ne garde que les texels dont l’alpha atteint le seuil et jette le reste, et c’est ainsi que se dessinent les feuilles, les clôtures, les grilles et le grillage : un seul quad, presque entièrement retiré. Contrairement au mélange, il n’a besoin d’aucun tri et projette quand même une ombre, et l’ombre est découpée elle aussi, si bien qu’un arbre projette des ombres de feuilles plutôt que l’ombre de son quad. Ce qui passe le seuil est opaque : un texel à moitié transparent est soit gardé entier, soit jeté, jamais mélangé, si bien que rien de ce qui se trouve derrière la scène (l’image du disque, surtout) ne teinte une feuille. Un seuil de 0 (la valeur par défaut) désactive le masquage. Un modèle chargé depuis glTF apporte le sien : MASK règle le seuil d’après le fichier, BLEND active le mélange, et OPAQUE ne fait ni l’un ni l’autre.

La texture d’un matériau peut être l’image de n’importe quel sprite chargé (materialSetTexture), le laserdisc lui-même ou une vidéo chargée (materialSetVideo), l’image d’une seconde caméra (materialSetView, voir La caméra et les vues), ou un document GUI (materialSetGui, voir GUI). Une borne d’arcade modélisée peut lire le disque sur son propre écran, ou y afficher sa page d’options. Les coordonnées de texture viennent du maillage ; les primitives appliquent une image une fois sur chaque face, et materialSetTiling la répète, ce que demandent les sols et les murs. Les textures ont des mipmaps et un filtrage anisotrope, si bien qu’un sol reste net jusqu’au loin ; materialSetFilter(material, FILTER_NEAREST) garde au contraire le pixel art bien carré.

local stone = materialNew()
materialSetTexture(stone, spriteLoad(DIR .. "flagstones.png"))
materialSetTiling(stone, 12, 12)             -- Douze répétitions sur le plan.
materialSetRoughness(stone, 0.9)

local floor = nodeNew()
nodeSetMesh(floor, meshPlane(24, 24), stone)

local glass = materialNew()
materialSetColor(glass, 180, 220, 255, 90)   -- Alpha de 90 sur 255.
materialSetBlend(glass, true)
materialSetRoughness(glass, 0.05)

Quatre autres cartes donnent à une surface un détail que sa géométrie n’a pas, et un modèle chargé les apporte avec lui quand son fichier les contient :

  • materialSetNormalMap infléchit l’éclairage avec une carte de normales en espace tangent, si bien que les briques ressortent d’un mur plat. Une intensité supérieure à 1 exagère l’effet.

  • materialSetOcclusionMap assombrit les recoins que la lumière ambiante et le ciel ne peuvent pas atteindre.

  • materialSetMetallicRoughnessMap fait varier le caractère métallique et la rugosité sur la surface, rangés à la manière de glTF (la rugosité dans le vert, le métallique dans le bleu) et multipliés par les facteurs propres du matériau, alors réglez ceux-ci à 1 quand la carte doit décider.

  • materialSetEmissiveMap indique quelles parties brillent, teintées et mises à l’échelle par materialSetEmissive.

local brick = materialNew()
materialSetTexture(brick, spriteLoad(DIR .. "brick.png"))
materialSetNormalMap(brick, spriteLoad(DIR .. "brickNormal.png"), 1.5)
materialSetMetallicRoughnessMap(brick, spriteLoad(DIR .. "brickMetalRough.png"))
materialSetMetallic(brick, 1)
materialSetRoughness(brick, 1)
materialSetEmissiveMap(brick, spriteLoad(DIR .. "brickEmissive.png"))
materialSetEmissive(brick, 180, 100, 40)     -- Le mortier brille en orange.
Textures compressées

Un PNG est décodé à quatre octets par texel sur le GPU, plus encore un tiers pour ses mipmaps ; un niveau de la taille de Sponza contient ainsi 390 Mo de textures, plus qu’un Raspberry Pi 4 n’en partage avec son affichage. Les textures livrées en fichiers KTX2 (Basis Universal, créés par util/compressTextures.py à partir de PNG ou d’un .gltf entier) restent compressées sur le GPU, au quart de la taille ou moins, dans le format de blocs dont dispose la machine : BC7 sur les ordinateurs de bureau, ASTC sur les GPU Apple et le Pi 4, ETC2 sur toute puce OpenGL ES 3 (le Mali de chaque console portable, le Pi sous GLES), BC3 sur les cartes plus anciennes, et du RGBA simple là où rien d’autre n’existe, le tout à partir d’un seul fichier. Donnez un nom .ktx2 à la place d’un sprite à materialSetTexture et aux appels de cartes, et un modèle dont le fichier utilise KHR_texture_basisu les charge de lui-même. sceneGetStats indique la mémoire de textures utilisée, pour que vous puissiez voir la différence.

materialSetTexture(ground, DIR .. "flagstones.ktx2")
local draws, drawn, calls, textureKB = sceneGetStats()
debugPrint("textures: " .. textureKB .. " KB")

1.15.4. Lumières et ombres

Jusqu’à huit lumières éclairent à la fois, et chacune est un nœud, si bien que les lumières se rattachent à un parent et s’animent comme n’importe quoi d’autre :

  • LIGHT_DIRECTIONAL est un soleil : seule sa direction compte, et tout est éclairé de la même façon. Une intensité de 1 éclaire en blanc une surface blanche tournée vers lui.

  • LIGHT_POINT est une ampoule, qui faiblit avec la distance, et lightSetRange l’éteint complètement au-delà d’une distance. Son intensité est sa luminosité à l’ampoule elle-même, la moitié à une unité de distance, si bien qu’une ampoule qui doit éclairer une pièce a besoin d’un nombre de l’ordre de quelques dizaines.

  • LIGHT_SPOT est un cône avec un angle intérieur entièrement éclairé et un angle extérieur où la lumière s’est éteinte (lightSetCone).

sceneSetAmbient ajoute un peu de lumière venant de partout pour que les ombres ne soient pas noires ; un ciel le fait mieux (voir L’aspect de l’image). Les couleurs données de 0 à 255 sont en sRGB, comme tout le reste dans Singe, et sont converties en lumière linéaire à l’entrée, si bien qu’une lumière de 128, 128, 128 est quatre fois moins lumineuse que le blanc, et non deux fois.

Toute lumière peut projeter des ombres aux bords doux à partir de tout ce qui est opaque (lightSetShadow). Les lumières directionnelles et les projecteurs projettent par une carte d’ombres ; les lumières ponctuelles par une carte cubique qui couvre toutes les directions, si bien qu’une ampoule peut se trouver à l’intérieur de ce qu’elle éclaire (une pièce, un abat-jour, la borne) : les maillages fermés projettent aussi depuis leurs faces arrière, et la plage de profondeur de l’ombre est ajustée aux objets qui font de l’ombre autour de la lumière. nodeSetShadow(node, false) dispense un maillage de projeter une ombre : le verre de l’ampoule elle-même, une enseigne lumineuse, une étiquette de nom. sceneSetShadowSize règle la résolution de la carte (256 à 4096, 1024 par défaut) et échange de la netteté contre de la vitesse.

L’ombre d’une lumière directionnelle est découpée en cascades le long de la vue (sceneSetShadowCascades, trois par défaut), chacune étant une carte ajustée à une tranche de ce que voit la caméra, si bien que les ombres restent nettes de près dans un grand niveau et portent quand même jusqu’à sceneSetShadowDistance. Une seule cascade ajuste une carte unique à toute la scène, ce qui convient aux petites scènes et aux caméras orthographiques. Une vue (viewNew) dessine avec les mêmes cartes, en prenant pour chaque point la cascade la plus fine qui le couvre, si bien qu’un moniteur montre les ombres que montre la fenêtre.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 30, 40, 20)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 2.5)
lightSetColor(sun, 255, 240, 220)
lightSetShadow(sun, true)
sceneSetShadowSize(2048)
sceneSetShadowDistance(80)              -- Trois cascades jusqu'à 80 unités.

local lamp = lightNew(LIGHT_POINT)
nodeSetPosition(lamp, 3, 3.1, -2)
lightSetColor(lamp, 255, 230, 190)
lightSetIntensity(lamp, 12)
lightSetRange(lamp, 14)
lightSetShadow(lamp, true)              -- Une carte cubique : six passes par image.
nodeSetShadow(bulbGlass, false)         -- Le verre qui l'entoure ne projette rien.

1.15.5. La caméra et les vues

N’importe quel nœud peut être la caméra (cameraSet) ; elle regarde le long de son propre -Z, si bien que nodeLookAt la vise, et l’accrocher sous un nœud en mouvement donne une caméra de poursuite. cameraSetPerspective(fovDegrees, near, far) est l’objectif par défaut ; cameraSetOrthographic(height, near, far) dessine sans perspective, pour les schémas, les scènes façon HUD et les jeux vus de profil. Gardez near aussi grand que la scène le permet, parce que la précision du tampon de profondeur se répartit entre near et far.

local camera = nodeNew()
nodeSetParent(camera, car)
nodeSetPosition(camera, 0, 2.5, 7)      -- Derrière et au-dessus de la voiture, dans son espace.
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 300)

Une vue est une seconde caméra rendue dans une texture à chaque image et affichée sur un matériau : un moniteur de surveillance, un rétroviseur, un portail, une image dans l’image. viewNew(width, height) en crée une à cette résolution, viewSetCamera lui donne un nœud caméra, et materialSetView met son image sur n’importe quel maillage. Les vues partagent les ombres de l’image et sautent le bloom, et chacune rend de nouveau la scène, alors gardez-les peu nombreuses et petites. Chaque vue tourne les billboards (voir Sprites et texte dans la scène) vers sa propre caméra et dessine les matériaux transparents de l’arrière vers l’avant depuis celle-ci, si bien qu’un moniteur voit les étiquettes de nom de face et le verre dans le bon ordre.

local rearCamera = nodeNew()
nodeSetParent(rearCamera, car)
nodeSetPosition(rearCamera, 0, 1.2, -2)
nodeSetRotation(rearCamera, 0, 180, 0)      -- Regarde vers l'arrière.
local rear = viewNew(384, 256)
viewSetCamera(rear, rearCamera)

local mirror = materialNew()
materialSetView(mirror, rear)
materialSetUnlit(mirror, true)
local panel = nodeNew()
nodeSetParent(panel, car)
nodeSetMesh(panel, meshPlane(0.6, 0.2), mirror)
nodeSetPosition(panel, 0, 1.6, 0.5)
nodeSetRotation(panel, 90, 0, 0)            -- Le plan regarde vers le haut ; on le redresse face au conducteur.

1.15.6. L’aspect de l’image

La scène est éclairée en lumière linéaire. Les couleurs que vous donnez de 0 à 255 sont en sRGB et sont décodées à l’entrée, les textures sont décodées par le GPU au moment où elles sont échantillonnées, les lumières s’additionnent sans écrêtage, et à la fin de l’image une courbe de tons ramène le résultat vers l’écran. Ce que cela veut dire en pratique :

  • sceneSetExposure(stops) éclaircit ou assombrit toute l’image comme l’exposition d’un appareil photo : +1 double la lumière, -1 la divise par deux, si bien qu’une grotte et une plage peuvent partager les mêmes lumières et les mêmes matériaux.

  • sceneSetTonemap choisit la courbe : TONEMAP_NEUTRAL (par défaut, qui garde les couleurs là où les visionneuses glTF les gardent et ne compresse que la lumière la plus vive), TONEMAP_ACES (un rendu cinéma avec plus de contraste), ou TONEMAP_NONE (écrêtage au blanc).

  • sceneSetBloom(threshold, strength) fait briller tout ce qui est plus lumineux que le seuil : le soleil à travers une fenêtre, une ampoule, une enseigne émissive, une flamme. La lueur est prise dans la lumière de la scène avant la courbe de tons, si bien que seul ce qui est vraiment lumineux produit du bloom ; un seuil de 1 correspond au blanc.

Le ciel et sa lumière

sceneSetSky(file) enveloppe la scène dans un panorama équirectangulaire. Un .hdr Radiance garde toute sa plage ; un PNG ou un JPEG fonctionne aussi. Le ciel est dessiné derrière tout le reste et, sauf avec sceneSetEnvironment(false), il éclaire aussi la scène : sa couleur globale, venue de toutes les directions, remplace l’ambiance uniforme, et son reflet apparaît sur les métaux et les surfaces brillantes, net sur un miroir et de plus en plus flou à mesure que la rugosité augmente. Sans ciel, les métaux n’ont rien à refléter, et seules l’ambiance et les lumières les modèlent. sceneSetSkyIntensity règle ensemble le ciel et sa lumière, si bien qu’un seul panorama sert pour midi et pour le crépuscule.

Brouillard

sceneSetFog(r, g, b, near, far) estompe tout, particules comprises, vers une couleur entre deux distances. Le ciel n’est jamais pris dans le brouillard, alors accordez la couleur du brouillard à l’horizon du ciel et le bord lointain de la scène s’y fondra.

sceneSetSky(DIR .. "harbor.hdr")
sceneSetSkyIntensity(0.8)
sceneSetFog(190, 200, 215, 40, 160)        -- La couleur du ciel à l'horizon.
sceneSetExposure(-0.5)                     -- Un peu plus sombre que ne le rendrait le soleil.
sceneSetBloom(1.0, 0.35)                   -- Seul ce qui est plus lumineux que le blanc brille.

1.15.7. Modèles et animation

modelLoad prend un .glb d’après le même nom relatif au jeu que prend spriteLoad, et un .game empaqueté l’emporte avec lui. Le fichier doit être autonome : maillages, skins, animations et textures, tout dans ce seul fichier, ce qui est l’export par défaut de Blender. Un modèle qui fait référence à un .bin ou à une image situés à côté de lui est refusé avec un message qui nomme le fichier, pour la même raison qu’un jeu empaqueté doit être autonome. Les matériaux utilisent le modèle métal-rugosité avec KHR_materials_emissive_strength et KHR_texture_basisu ; une texture adressée par un second jeu de coordonnées de texture lit le premier jeu, et KHR_texture_transform est ignoré, chacun avec une ligne dans la trace du programme. Un skin peut avoir jusqu’à 128 articulations. Le chargement est la partie coûteuse ; modelInstance place ensuite une copie de l’arbre de nœuds du modèle, autant de fois que vous voulez, et chaque instance partage les maillages et les matériaux du fichier. modelDelete libère le modèle ; les instances gardent leurs nœuds, nus.

local foxModel = modelLoad(DIR .. "Fox.glb")
local pack = {}
for i = 1, 6 do
    local fox = modelInstance(foxModel)
    nodeSetScale(fox, 0.02)                -- Le fichier est en centimètres.
    nodeSetPosition(fox, i * 1.5 - 5, 0, 0)
    pack[i] = fox
end

Les animations d’un modèle sont listées par modelGetAnimations et pilotées instance par instance avec animationPlay(node, nameOrIndex, loop, speed, fade) sur le nœud racine de l’instance, plus des appels de pause, de reprise, d’arrêt et de saut. L’animation de nœuds (des objets qui bougent), le skinning (des personnages qui se déforment) et les morph targets (blend shapes : visages, synchronisation labiale, muscles qui gonflent) fonctionnent tous. Les animations avancent en temps réel et s’arrêtent pendant que le jeu est en pause. Un poids de morphing peut aussi être réglé par script avec nodeSetMorph, par nom ou par numéro, sur le nœud qui porte le maillage.

Un fade en secondes fait un fondu enchaîné depuis ce qui jouait, si bien qu’une marche devient une course sans à-coup. Quand rien ne jouait (après animationStop, ou quand un ragdoll vient d’être désactivé), le fondu part de la pose dans laquelle se trouvent les nœuds, si bien qu’un personnage se relève en douceur de là où il est tombé. Jusqu’à quatre clips de plus peuvent jouer en même temps sur des couches au-dessus de la base (animationPlayLayer), chacun mélangé selon animationSetLayerWeight et limité à une partie du squelette par animationSetLayerMask : un regard alentour sur le cou pendant que les jambes marchent, un salut d’un bras pendant une course.

animationPlay(fox, "Walk", true)
animationPlayLayer(fox, 1, "Survey", true, 1, 0.5)           -- La tête tourne, mélangée en une demi-seconde
animationSetLayerMask(fox, 1, nodeFind("b_Neck_04", fox))    -- ... sur le cou et au-dessus seulement.

function onCollision(a, b, x, y, z, speed)
    if (a == fox or b == fox) and speed > 3 then
        animationPlay(fox, "Run", true, 1.2, 0.4)   -- Plus vite, en fondu enchaîné de 0.4 s.
    end
end

1.15.8. Le son dans la scène

Un effet sonore peut être placé dans la scène pour qu’on l’entende depuis l’endroit où il se trouve. soundSetPosition(channel, x, y, z) place un canal en cours de lecture en un point du monde, soundSetNode(channel, node) lui fait plutôt suivre un nœud, et soundSetRange(channel, near, far) indique où il est à plein volume et où il s’est éteint. Les sons sont entendus depuis la caméra sauf si soundSetListener désigne un autre nœud (la tête du joueur, pour un jeu à la troisième personne), et ils se répartissent à gauche et à droite quand l’auditeur tourne. Un canal qui n’est pas placé dans la scène joue comme il l’a toujours fait, avec soundSetPan pour la stéréo.

local crackle = soundPlay(fireSound, -1)          -- Boucle sans fin.
soundSetNode(crackle, brazier)
soundSetRange(crackle, 2, 18)                     -- Plein volume dans un rayon de 2 unités, plus rien à 18.
soundSetListener(hero)

1.15.9. Sprites et texte dans la scène

N’importe quel nœud peut afficher une image au lieu d’un maillage. nodeSetSprite(node, sprite, height) place un sprite chargé (chacune des images d’un sprite animé, au choix de nodeSetSpriteFrame) sur un quad haut d’autant d’unités du monde, éclairé comme le reste et projetant des ombres, sauf si nodeSetShadow en décide autrement. nodeSetText(node, text, height) fait de même avec une ligne de texte dans la police et la couleur sélectionnées, sans éclairage. Pour le reste du moteur, les deux sont des maillages : ils se rattachent à un parent, changent d’échelle et acceptent le mélange d’un matériau.

nodeSetBillboard tourne un nœud face à la caméra à chaque image : BILLBOARD_ALL complètement (étiquettes de nom, lueurs, imposteurs), BILLBOARD_Y autour de son propre axe vertical seulement (arbres, barres de vie, tout ce qui doit rester debout), et BILLBOARD_NONE pour arrêter. Cela fonctionne aussi sur les maillages.

local tag = nodeNew()
nodeSetParent(tag, fox)
nodeSetPosition(tag, 0, 110, 0)         -- Dans les centimètres du Fox, au-dessus de sa tête.
nodeSetScale(tag, 50)                   -- Annule l'échelle de 0.02 de l'instance.
nodeSetText(tag, "FOX", 0.6)
nodeSetBillboard(tag, BILLBOARD_ALL)
nodeSetShadow(tag, false)

local icon = nodeNew()
nodeSetParent(icon, fox)
nodeSetPosition(icon, 0, 150, 0)
nodeSetScale(icon, 50)
nodeSetSprite(icon, spriteLoad(DIR .. "crate.png"), 0.5)
nodeSetBillboard(icon, BILLBOARD_Y)

1.15.10. Devant l’overlay

La scène est normalement dessinée sous l’overlay, si bien que tout ce qui est dessiné sur l’overlay la recouvre. nodeSetLayer(node, LAYER_FRONT) place plutôt un nœud, et tout ce qui lui est rattaché, dans la couche de premier plan : la même caméra le dessine après l’overlay, éclairé par les mêmes lumières et fini par la même exposition, la même courbe de tons et le même bloom, si bien qu’un logo qui tourne, un titre en 3D ou un modèle sur un tableau des meilleurs scores peut se dresser par-dessus des illustrations 2D. La couche de premier plan est une image à part, effacée en transparent, si bien que l’overlay apparaît partout où elle ne dessine rien, et rien dans la scène derrière l’overlay ne peut la cacher. Les GUI et les particules dessinées par-dessus l’overlay passent toujours au-dessus d’elle.

Les nœuds de premier plan projettent toujours des ombres sur la scène. Le ciel, les particules 3D et les lignes de débogage restent dans la scène, et les vues (viewNew) ne dessinent que les nœuds de la scène. La couche coûte une seconde passe de rendu, et seulement pour les images où elle contient quelque chose.

-- Une pièce d'or qui tourne par-dessus l'écran-titre 2D.
local coin = nodeNew()
nodeSetMesh(coin, meshCylinder(1, 0.2, 48), gold)
nodeSetRotation(coin, 90, 0, 0)
nodeSetLayer(coin, LAYER_FRONT)

function onOverlayUpdate()
    overlayClear()
    spriteDraw(titleArt, 0, 0)
    nodeRotate(coin, 0, 2, 0)
    return OVERLAY_UPDATED
end

1.15.11. Le terrain

meshHeightmap(image, sizeX, sizeY, sizeZ) transforme une image en niveaux de gris en terrain vallonné : un sommet par pixel, le noir en bas et le blanc à sizeY de haut, avec des normales tirées des pentes et des coordonnées de texture sur l’ensemble. Donnez à son matériau une texture et materialSetTiling pour la répéter toutes les quelques unités. Les images peuvent faire jusqu’à 1025 pixels dans chaque sens ; une carte de 257 pixels sur 120 unités donne un sommet toutes les demi-unités, ce qui suffit largement pour des collines.

Un corps BODY_STATIC avec SHAPE_MESH sur ce nœud devient un champ de hauteur, bien moins coûteux que ne le seraient les triangles, si bien que les voitures y roulent et que les joueurs y marchent tel quel. terrainGetHeight(node, x, z) indique la hauteur du sol en un point, pour y placer des choses sans lancer de rayon.

local ground = materialNew()
materialSetTexture(ground, DIR .. "grass.ktx2")
materialSetTiling(ground, 24, 24)
local hills = nodeNew()
nodeSetMesh(hills, meshHeightmap(DIR .. "hills.png", 120, 14, 120), ground)
bodyNew(hills, BODY_STATIC, SHAPE_MESH)             -- Un champ de hauteur.

for i = 1, 20 do
    local x, z = math.random(-50, 50), math.random(-50, 50)
    local tree = modelInstance(treeModel)
    nodeSetPosition(tree, x, terrainGetHeight(hills, x, z), z)
end

1.15.12. La navigation

Un maillage de navigation indique aux personnages où ils peuvent marcher. navNew(radius, height, maxSlope, maxStep) en crée un pour une taille d’agent donnée, navAddNode lui fournit la géométrie du niveau (la racine d’une instance de modèle fournit tout le modèle), et navBuild précalcule la surface praticable : les sols, les rampes et les escaliers que l’agent peut gravir, moins une marge autour de chaque mur et de chaque colonne. Précalculer Sponza prend un dixième de seconde sur un ordinateur de bureau ; navSave et navLoad gardent un maillage précalculé dans le dossier de données du jeu pour les machines où cela prend plus longtemps, et un maillage livré avec le jeu se charge de la même façon. navDraw affiche le maillage par-dessus la scène pendant que vous mettez au point les paramètres.

Les requêtes répondent ensuite aux questions que pose un jeu : navPath renvoie les angles du plus court chemin entre deux points, navNearest ramène un point sur le maillage, navRaycast indique si une marche en ligne droite est bloquée, et navRandomPoint choisit un endroit vers lequel errer.

Les agents (navAgentNew) parcourent le maillage pour vous. navAgentMoveTo en envoie un quelque part, et il contourne les autres agents en chemin, en déplaçant son nœud (ou en pilotant un contrôleur de joueur posé dessus, avec navAgentSetPlayer) et en appelant onNavArrived quand il arrive. navAgentGetVelocity vous dit s’il faut jouer la marche ou la course.

local nav = navNew(0.4, 1.6, 45, 0.3)   -- Un agent de 0.8 de large et 1.6 de haut, qui gravit 0.3.
navAddNode(nav, level)
navBuild(nav)

local guards = {}
for i = 1, 6 do
    local guard = modelInstance(guardModel)
    local x, y, z = navRandomPoint(nav)
    nodeSetPosition(guard, x, y, z)
    animationPlay(guard, "Walk", true)
    local agent = navAgentNew(nav, guard, 0.35, 1.6, 1.4)
    navAgentMoveTo(agent, navRandomPoint(nav))
    guards[agent] = guard
end

function onNavArrived(agent)
    navAgentMoveTo(agent, navRandomPoint(nav))   -- En route vers l'endroit suivant.
end

1.15.13. Performances et configuration requise

La scène a besoin d’un GPU qui parle Vulkan (Linux), Direct3D 12 (Windows 10 et versions ultérieures), Metal (macOS) ou OpenGL ES 3.1. Le backend ES est ce qui fait entrer dans le jeu les consoles portables Linux bon marché et le Raspberry Pi, dont les puces Mali et VideoCore ont un pilote GLES mûr et soit pas de Vulkan du tout, soit un Vulkan immature ; il est choisi automatiquement quand aucun des trois autres n’est disponible, et il dessine la même image à partir des mêmes shaders. Le Raspberry Pi 4 reste le Pi minimum pour la 3D : le Pi 3 n’a qu’OpenGL ES 2.0, qui ne peut exprimer ni le skinning ni les morph targets de la scène. Sur une machine qui n’a aucun d’eux, les jeux 2D tournent exactement comme avant (physique 2D comprise) et le premier appel 3D termine le jeu avec une erreur qui nomme le problème.

Les maillages hors du champ de la caméra sont sautés, et les copies d’un même maillage avec le même matériau sont dessinées en un seul appel instancié, si bien qu’une forêt faite d’un seul et même arbre coûte à peu près ce que coûte un arbre. sceneGetStats indique les dessins collectés, combien étaient dans le champ, combien d’appels de dessin cela a pris, et la mémoire de textures utilisée. Pour l’aider :

  • Partagez les maillages et les matériaux entre les nœuds (un seul meshBox, beaucoup de nœuds ; un seul modèle, beaucoup d’appels à modelInstance) plutôt que d’en créer un par objet.

  • Les maillages avec skinning ou morphing et les maillages mélangés sont dessinés un par un ; limitez-les à ce dont la scène a besoin.

  • L’anticrénelage (multiéchantillonnage 4x) est actif partout où le GPU le propose ; sceneSetAntialias(false) fait regagner de la vitesse sur un Pi, tout comme un sceneSetShadowSize plus petit et moins de lumières ponctuelles projetant des ombres, chacune coûtant six passes.

  • Surveillez le nombre de triangles et la taille des textures sur les petites cartes, livrez des textures KTX2, et chargez un modèle une fois plutôt que deux.

function onOverlayUpdate()
    local draws, drawn, calls, textureKB = sceneGetStats()
    overlayClear()
    local text = string.format("%d/%d meshes, %d calls, %d KB", drawn, draws, calls, textureKB)
    fontPrint(10, 10, text)
    return OVERLAY_UPDATED
end

1.16. Physique

Les corps, les articulations, les déclencheurs et les lancers de rayons vivent dans la scène 3D et reposent sur Jolt Physics. Un corps s’attache à un nœud comme un maillage, et dès lors le nœud et le corps ne font qu’un : la forme du corps est dimensionnée en unités du monde et mise à l’échelle par le nœud, et quel que soit celui des deux qui bouge, l’autre suit. Les unités sont les mètres, les kilogrammes et les secondes, et la gravité vaut par défaut 0, -9.81, 0. La physique n’a pas besoin de GPU ; voir Jeux 2D.

1.16.1. Corps

bodyNew(node, type, shape, a, b, c) donne à un nœud un corps de l’un de trois types :

  • Un corps statique (BODY_STATIC) reste là où était le nœud quand le corps a été créé : sols, murs, la borne. Déplacer son nœud ensuite ne déplace pas le corps.

  • Un corps cinématique (BODY_KINEMATIC) suit son nœud partout où le script ou une animation le déplace, et écarte les corps dynamiques de son chemin sans être poussé lui-même : une raquette, une plateforme mobile, la main d’un personnage.

  • Un corps dynamique (BODY_DYNAMIC) est déplacé par la simulation et entraîne son nœud : il tombe, rebondit, glisse et se fait pousser. Ne déplacez pas son nœud vous-même ; donnez-lui plutôt des vitesses, des forces ou des impulsions (bodySetVelocity, bodyApplyForce, bodyApplyImpulse).

La forme est une boîte, une sphère, une capsule ou un cylindre dimensionné par a, b et c (SHAPE_BOX prend la largeur, la hauteur et la profondeur ; SHAPE_SPHERE un rayon ; SHAPE_CAPSULE et SHAPE_CYLINDER un rayon et une hauteur le long de Y), une enveloppe convexe du maillage du nœud (SHAPE_HULL, tout ce qui se trouve sous le nœud, si bien que la racine d’une instance de modèle convient), ou les triangles exacts du maillage (SHAPE_MESH, corps statiques et cinématiques seulement ; sur un maillage de carte de hauteur, c’est un champ de hauteurs, voir Le terrain).

floor = nodeNew()
nodeSetMesh(floor, meshBox(14, 0.2, 14), stone)
nodeSetPosition(floor, 0, -1.9, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 14, 0.2, 14)

for i = 1, 6 do
    local crate = nodeNew()
    nodeSetMesh(crate, meshBox(0.6, 0.6, 0.6), wood)
    nodeSetPosition(crate, -1, -1.5 + (i - 1) * 0.62, 0)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
    bodySetMass(crate, 5)
end

paddle = nodeNew()
nodeSetMesh(paddle, meshBox(0.3, 1.2, 1.6), red)
nodeSetPosition(paddle, -4, -1.2, 0)
bodyNew(paddle, BODY_KINEMATIC, SHAPE_BOX, 0.3, 1.2, 1.6)

function onOverlayUpdate()
    nodeMove(paddle, 0.06, 0, 0)   -- La raquette cinématique balaie la pile.
    return OVERLAY_UPDATED
end
Masse et matériaux

La masse d’un corps dynamique vient du volume de sa forme à la densité de l’eau, si bien qu’une boîte de la taille d’une porte pèse 140 kilogrammes et qu’une légère poussée ne la fera pas bouger. Réglez bodySetMass sur tout ce qui doit paraître léger, et dimensionnez les impulsions selon la masse : une impulsion de mass * speed donne cette vitesse. bodySetFriction et bodySetBounce font la glace et le caoutchouc ; bodySetEnabled retire un corps du monde et l’y remet sans le perdre.

Synchronisation

Le monde avance d’un pas fixe soixante fois par seconde selon l’horloge, après que les animations ont posé leurs nœuds et avant le rendu de la scène, si bien qu’un corps cinématique mû par une animation pousse avec la bonne vitesse. Mettre le jeu en pause met la physique en pause ; physicsSetEnabled(false) la met en pause à elle seule. bodyIsResting indique quand un corps s’est stabilisé, c’est-à-dire quand un objet lancé s’est arrêté et qu’un score peut être compté. Un corps, un joueur, un ragdoll, un corps mou ou un véhicule dont le nœud a été supprimé est libéré au début de l’image suivante, activé ou non et en pause ou non, si bien que son emplacement redevient libre ; un handle de nœud que nodeNew distribue plus tard à nouveau ne porte rien de la physique de l’ancien nœud, et playerExists et ses semblables répondent false pour lui jusqu’à ce qu’il ait la sienne.

1.16.2. Événements et requêtes

Définissez onCollision(nodeA, nodeB, x, y, z, speed) et Singe l’appelle une fois pour chaque nouveau contact, avec le point et la vitesse auxquels les deux corps se sont rencontrés, si bien qu’un petit choc et un fracas peuvent sonner différemment. Un corps devenu déclencheur par bodySetTrigger ne pousse rien mais signale ce qui y entre et en sort par onTrigger(trigger, other, entered) : une ligne d’arrivée, une porte, une zone dangereuse. physicsRaycast trouve le premier corps le long d’un rayon ; avec sceneUnproject pour le rayon, c’est la sélection à la souris (voir Les nœuds). Une liste de nœuds en dernier argument est écartée de la recherche : un tir parti de l’intérieur du corps du joueur ne s’y arrête donc pas.

finish = nodeNew()
nodeSetPosition(finish, 0, 1, -40)
bodyNew(finish, BODY_STATIC, SHAPE_BOX, 12, 2, 0.5)
bodySetTrigger(finish, true)

function onTrigger(trigger, other, entered)
    if trigger == finish and other == car and entered then
        lapDone()
    end
end

function onCollision(a, b, x, y, z, speed)
    if speed > 6 then
        local channel = soundPlay(crashSound)
        soundSetPosition(channel, x, y, z)
    end
end

1.16.3. Articulations

jointHinge, jointBall et jointSlider relient deux corps, ou un corps et le monde quand le second nœud vaut -1 : portes, pendules, tiroirs, les roues d’une voiture vue de profil. L’ancre et l’axe sont donnés dans l’espace du monde, là où se trouvent les corps quand l’articulation est créée. Les charnières et les glissières acceptent des limites (jointSetLimits) : un angle de charnière positif est une rotation du premier nœud autour de l’axe selon la règle de la main droite, et une distance de glissière positive va dans le sens de l’axe.

door = nodeNew()
nodeSetMesh(door, meshBox(0.9, 2.0, 0.05), oak)
nodeSetPosition(door, 0.45, 1.0, 0)
bodyNew(door, BODY_DYNAMIC, SHAPE_BOX, 0.9, 2.0, 0.05)
bodySetMass(door, 20)
local hinge = jointHinge(door, -1, 0, 1.0, 0, 0, 1, 0)   -- Sur le chambranle, autour de Y.
jointSetLimits(hinge, 0, 110)                            -- S'ouvre dans un sens, 110 degrés.

Les corps sur des instances de modèle fonctionnent comme les autres : bodyNew(instanceRoot, BODY_DYNAMIC, SHAPE_HULL) entoure tout le modèle d’une enveloppe convexe. Un personnage skinné est de préférence un joueur (voir plus bas) ou une capsule cinématique qui pousse les choses plutôt que d’être poussée.

1.16.4. Jeux 2D

La physique n’est pas liée à la scène 3D. Les nœuds existent sur toutes les machines, avec ou sans GPU, si bien qu’un jeu 2D peut donner des corps à des nœuds, appeler physicsSet2D(true) pour qu’ils ne se déplacent qu’en X et Y et ne tournent qu’autour de Z, travailler en coordonnées de l’overlay avec une gravité dirigée vers le bas de l’écran, et dessiner des sprites là où sont les nœuds. C’est la forme qui tourne sur un Raspberry Pi 3, qui n’a pas de 3D.

physicsSet2D(true)
physicsSetGravity(0, 900, 0)          -- Pixels par seconde au carré ; le Y de l'overlay descend.

floor = nodeNew()
nodeSetPosition(floor, 360, 470, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 720, 20, 50)

crate = nodeNew()
nodeSetPosition(crate, 200, -40, 0)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 40, 40, 50)
bodySetMass(crate, 1)

function onOverlayUpdate()
    local x, y = nodeGetPosition(crate)
    local _, _, angle = nodeGetRotation(crate)
    spriteRotate(crateArt, angle)
    spriteDraw(crateArt, x, y, true)
    return OVERLAY_UPDATED
end

Donnez à chaque corps 2D une certaine profondeur (la troisième dimension) pour que les formes se chevauchent en Z ; 50 convient. Les cercles sont des SHAPE_SPHERE. Les joueurs et les émetteurs 2D (voir Particules) fonctionnent aussi dans ce monde, et un jeu de plateforme est un joueur avec playerMove(node, vx).

1.16.5. Joueurs

Un corps va là où les forces l’envoient ; un joueur va là où le script le dit. playerNew met un contrôleur de personnage sur un nœud : une capsule par défaut (playerNew(node, radius, height)), ou n’importe quelle forme convexe de bodyNew (playerNew(node, SHAPE_BOX, w, h, d) pour un robot, playerNew(node, SHAPE_SPHERE, r, 0) pour quelque chose qui roule mais monte quand même les marches, SHAPE_HULL pour la silhouette propre du modèle ; trois arguments signifient toujours une capsule, si bien qu’une sphère donne toutes ses dimensions). La forme repose sur l’origine du nœud, qui correspond aux pieds. À chaque image, le script donne à playerMove la vitesse horizontale qu’il veut, et le contrôleur marche sur les sols, monte les marches jusqu’à playerSetStep, glisse le long des murs, refuse les pentes plus raides que playerSetSlope, tombe sous l’effet de la gravité, se laisse porter par les plateformes mobiles et écarte de son chemin les corps dynamiques légers (playerSetPush). playerJump ne fonctionne qu’avec le sol sous les pieds et dit s’il a sauté. La rotation du nœud appartient au script : tournez-le face à la direction où il marche, et accrochez le modèle dessous comme enfant.

hero = nodeNew()
nodeSetPosition(hero, 0, 0, 0)
playerNew(hero, 0.3, 1.0)               -- Une capsule de rayon 0.3, haute de 1, pieds au nœud.
fox = modelInstance(modelLoad(DIR .. "Fox.glb"))
nodeSetParent(fox, hero)

function onInputPressed(switch)
    if switch == SWITCH_BUTTON1 then
        playerJump(hero, 4.5)               -- Il faut le sol sous les pieds.
    end
end

function onOverlayUpdate()
    local vx = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767 * 3
    local vz = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_Y) / 32767 * 3
    playerMove(hero, vx, vz)
    if vx ~= 0 or vz ~= 0 then
        nodeSetRotation(hero, 0, math.deg(math.atan(-vx, -vz)), 0)
    end
    return OVERLAY_NOT_UPDATED
end

Les joueurs signalent onCollision quand ils commencent à toucher un corps et onTrigger quand ils entrent dans un capteur ou en sortent, avec leur nœud à la place qu’occuperait le nœud d’un corps, si bien qu’une porte, un objet à ramasser et une fosse de lave fonctionnent de la même façon pour un joueur que pour une balle. playerIsOnGround et playerGetGround disent sur quoi le joueur se tient, pour les bruits de pas et pour descendre exprès d’une plateforme. Dans un monde 2D, un joueur est un personnage de jeu de plateforme : playerMove(node, vx) court le long de X, la gravité est dirigée vers le bas de l’écran, et tout le reste est identique. Les tolérances du contrôleur s’adaptent à la forme, si bien qu’une capsule de 30 pixels dans un jeu de sprites se comporte comme une capsule de 0,3 mètre dans un jeu 3D.

1.16.6. Véhicules

Un véhicule est un corps dynamique (le châssis, créé avec bodyNew comme tout corps, tourné vers -Z avec Y vers le haut) que Jolt conduit par des roues : vehicleNew(node, VEHICLE_CAR) pour tout ce qui a des essieux, VEHICLE_MOTORCYCLE pour deux roues en ligne qui s’inclinent dans les virages et tiennent en équilibre, ou VEHICLE_TANK pour des roues sur deux chenilles qui tournent sur place. Les roues sont des nœuds : vehicleAddWheel(node, wheelNode, radius, width, suspension) prend la position de la roue d’après l’endroit où se trouve son nœud par rapport au châssis, et dès lors le moteur de jeu pose ce nœud à chaque image (son axe X est l’essieu, si bien qu’une roue en meshCylinder demande un enfant tourné de 90 degrés). Les roues trouvées dans un modèle avec nodeFind("wheelFL", car) fonctionnent de même. Par défaut, les roues avant braquent et toutes sont motrices ; vehicleSetWheel en décide autrement.

À chaque image, le script tient le rôle du conducteur : vehicleDrive(node, forward, right, brake, handBrake). Le moteur, la boîte automatique et les différentiels sont ceux de Jolt, avec les valeurs par défaut d’une voiture de 1500 kg ; vehicleSetEngine, vehicleSetGears, vehicleSetSuspension, vehicleSetSteering, vehicleSetBrakes et vehicleSetAntiRoll les règlent, et toute modification reconstruit le véhicule sur place au pas suivant. vehicleGetSpeed, vehicleGetRpm et vehicleGetGear alimentent un tableau de bord. Un véhicule reste un corps : il saute des tremplins, heurte les murs, bouscule les caisses et signale onCollision.

car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 1, 0)
bodyNew(car, BODY_DYNAMIC, SHAPE_BOX, 1.8, 0.5, 4.0)
bodySetMass(car, 1500)
vehicleNew(car, VEHICLE_CAR)
local corners = {
    { -0.95, -0.2, -1.4 }, { 0.95, -0.2, -1.4 },   -- Avant gauche et droite ...
    { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 },     -- ... arrière gauche et droite.
}
for i, p in ipairs(corners) do
    local wheel = nodeNew()
    nodeSetParent(wheel, car)
    nodeSetPosition(wheel, p[1], p[2], p[3])
    vehicleAddWheel(car, wheel, 0.35, 0.25, 0.4)
end

function onOverlayUpdate()
    local throttle = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER) / 32767
    local brake    = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_TRIGGER) / 32767
    local steer    = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767
    vehicleDrive(car, throttle, steer, brake, 0)
    return OVERLAY_NOT_UPDATED
end

Les chars prennent forward comme accélérateur et right comme virage (sans accélérateur, ils pivotent sur place), et ignorent les réglages de direction, de freins et d’antiroulis, puisque leurs chenilles freinent et tournent d’elles-mêmes. Le ressort d’inclinaison de la moto est proportionné au châssis, si bien qu’une moto légère tient en équilibre aussi bien qu’une lourde. Les véhicules à roues demandent un monde 3D ; une voiture 2D vue de profil est un corps avec deux roues sur charnières, ce que les appels d’articulation savent déjà construire.

1.16.7. Eau

bodySetWater(node, density, linearDrag, angularDrag) remplit d’eau un corps statique : le dessus de sa boîte est la surface, et chaque corps dynamique à l’intérieur flotte, coule ou roule selon la flottabilité de Jolt par rapport à cette surface (la partie immergée de la forme compte, si bien qu’une caisse inclinée se redresse), ralenti par les traînées. bodySetCurrent donne un courant à l’eau. density est un multiplicateur, 1 pour l’eau, et le bodySetBuoyancy propre à chaque corps flottant (par défaut 1.2, qui flotte doucement ; en dessous de 1, il coule) le module. Le volume est un déclencheur, si bien que onTrigger se déclenche à l’entrée et à la sortie, pour les éclaboussures. L’eau n’est pas dessinée : donnez au nœud du volume un matériau en mélange, ou aucun.

Un joueur dans l’eau nage : playerIsSwimming le dit, playerMove(node, vx, vy, vz) dirige alors sur trois axes, il coule lentement sans commande verticale (playerSetSwim règle cette vitesse et la traînée de l’eau), et le courant l’emporte. Un bateau est une coque flottante à laquelle vehicleNew(node, VEHICLE_BOAT) donne une hélice et un gouvernail : vehicleSetThrust dit avec quelle force elle pousse et à quel endroit de la coque, vehicleSetRudder avec quelle force il tourne, et vehicleDrive fonctionne comme pour une voiture, le tout seulement tant que l’hélice est sous une surface.

pool = nodeNew()
nodeSetMesh(pool, meshBox(8, 3, 12), blue)   -- Bleu en mélange, dessiné comme l'eau.
nodeSetPosition(pool, 0, -1.5, 0)            -- Son dessus, à Y = 0, est la surface.
bodyNew(pool, BODY_STATIC, SHAPE_BOX, 8, 3, 12)
bodySetWater(pool, 1.0, 0.6, 0.2)
bodySetCurrent(pool, 0.5, 0, 0)              -- Dérive vers +X.
bodySetBuoyancy(crate, 1.6)                  -- Flotte haut.
bodySetBuoyancy(anchor, 0.3)                 -- Coule.

1.16.8. Ragdolls

ragdollNew(node) cherche le skin sous une instance de modèle et transforme le squelette en recette de ragdoll : chaque articulation qui a une articulation enfant devient une capsule le long de cet os, reliée à l’os le plus proche au-dessus d’elle par une articulation swing-twist aux limites raisonnables, et les articulations terminales (doigts, oreilles, le bout d’une queue) suivent leurs parents. Rien ne bouge avant ragdollActivate : alors l’animation s’arrête, des corps sont créés là où sont les os, et à partir de ce moment la physique pilote les nœuds des articulations, si bien que le maillage skinné s’affaisse, heurte le sol et s’immobilise avec le reste du monde.

ragdollApplyImpulse pousse un os désigné par le nom de son articulation. ragdollSetStrength motorise chaque articulation vers la pose dans laquelle le ragdoll a été activé, ce qui change une chute molle en titubement ou permet à un personnage à terre de ramener ses membres ; cela ne remet pas un corps debout, puisque rien ne prend appui sur le sol. ragdollDeactivate rend le squelette à l’animation là où il gît, et un animationPlay avec un fondu le relève alors en douceur depuis cette position. Réglez un os qui a l’air faux avec ragdollSetJoint avant l’activation.

fox = modelInstance(foxModel)
ragdollNew(fox)                            -- Recette tirée du skin ; toujours animé.
function onCollision(a, b, x, y, z, speed)
    if (a == hero or b == hero) and speed > 3 then
        playerSetEnabled(hero, false)
        ragdollActivate(fox)                 -- La physique pilote désormais le squelette.
        ragdollApplyImpulse(fox, "b_Spine02_03", 40, 30, 0)
    end
end

1.16.9. Corps mous

Le tissu, la corde et la gelée sont des maillages dont les sommets sont simulés. softNew(node, SOFT_CLOTH) transforme le maillage du nœud en tissu, ses sommets (soudés par position) en particules reliées par des contraintes d’étirement, de cisaillement et de flexion, là où le nœud l’a placé dans le monde ; un meshPlane(width, depth, columns, rows) subdivisé est le point de départ habituel. softNew(node, SOFT_BODY) fait de même pour un maillage fermé et softSetPressure le gonfle : un ballon, une gelée. softNew(node, SOFT_ROPE, x, y, z, segments, radius) tend une chaîne de particules de la position du nœud jusqu’à ce point et donne au nœud un maillage tubulaire autour d’elles (réglez son apparence avec nodeSetMaterial).

Les corps mous entrent en collision avec tout ce qui est rigide, tombent sous l’effet de la gravité et sont dessinés par le maillage dont ils sont issus, que le moteur réécrit à chaque image. softPin maintient la particule la plus proche là où elle est ou à un nœud (le bord du drapeau au mât, le haut de la corde à la grue) ; softSetStiffness, softSetMass et softSetDamping règlent le matériau. Un nœud dont le maillage est partagé avec d’autres nœuds les modifie aussi, alors donnez à un corps mou un maillage à lui.

flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), red)
nodeSetPosition(flag, -4.2, 2.4, 0)
nodeSetRotation(flag, 90, 0, 0)                 -- Suspendu à la verticale.
softNew(flag, SOFT_CLOTH)
for _, y in ipairs({ 1.9, 2.15, 2.4, 2.65, 2.9 }) do
    softPin(flag, -5, y, 0)                     -- Le long du mât.
end

Le coût croît avec le nombre de particules : une toile de 20 sur 20 compte 441 particules et passe bien sur un Raspberry Pi 4 ; limitez le tissu à quelques centaines de particules et une corde à une douzaine de segments. Les particules entrent en collision avec les corps rigides, pas avec les faces, si bien qu’un maillage assez fin (des particules plus proches que la plus petite chose qui atterrira dessus) est ce qui empêche une caisse de passer au travers. Il n’y a pas d’autocollision : le tissu peut se traverser lui-même quand il est froissé. Les maillages skinnés ne peuvent pas être mous.

1.16.10. Voir la physique

Quand une caisse passe à travers le sol ou qu’une articulation plie dans le mauvais sens, physicsSetDebug dessine ce que la simulation contient réellement, sous forme de lignes par-dessus la scène, à chaque image :

  • DEBUG_SHAPES : les corps en fil de fer, colorés selon leur état (endormi, en mouvement, statique), avec les joueurs en jaune.

  • DEBUG_CONSTRAINTS : les articulations, les articulations de ragdoll et les contraintes des véhicules, avec leurs limites.

  • DEBUG_CONTACTS : une croix rouge là où des corps se sont rencontrés pendant ce pas.

  • DEBUG_VELOCITIES : une ligne le long de la vitesse de chaque corps en mouvement.

  • DEBUG_STATIC : les formes des corps statiques aussi, qui restent masquées sinon parce qu’un maillage de niveau fait beaucoup de lignes.

Additionnez-les, ou utilisez DEBUG_ALL pour les quatre premiers. DEBUG_NONE le désactive, et il ne coûte rien tant qu’il est désactivé. Un script dessine ses propres lignes de la même façon avec lineDraw (un lancer de rayon, un chemin, une boîte englobante), une image à la fois comme l’overlay, et navDraw montre un maillage de navigation.

if debugging then
    physicsSetDebug(DEBUG_SHAPES + DEBUG_CONTACTS)
end

function onOverlayUpdate()
    local hit, hx, hy, hz = physicsRaycast(gunX, gunY, gunZ, aimX, aimY, aimZ, 60)
    if hit then
        lineDraw(gunX, gunY, gunZ, hx, hy, hz, 255, 255, 0)
    end
    return OVERLAY_NOT_UPDATED
end

1.16.11. Où elle tourne

La physique tourne sur le CPU et n’a pas besoin de GPU, mais la bibliothèque est compilée pour SSE4.1 sur x86 (2008 et après) et NEON sur le Pi ; une machine en deçà obtient une erreur dès le premier bodyNew. La simulation utilise tous les cœurs sauf un, si bien qu’un Pi à quatre cœurs avance ses pas sur trois fils d’exécution ; la trace du programme dit combien.

1.17. Particules

Étincelles, fumée, feu, pluie, poussière, magie : tout ce qui est fait de nombreuses petites choses éphémères est l’affaire d’un émetteur. Un émetteur contient une recette (combien par seconde, combien de temps elles vivent, à quelle vitesse et dans quelle direction elles partent, ce qui les attire, comment elles grandissent, s’estompent et tournent) et une réserve de particules qu’il anime d’après cette recette. Le script règle la recette une fois, puis démarre l’émetteur pour un flux régulier (emitterStart), le fait jaillir d’un coup pour une bouffée ponctuelle (emitterBurst), ou les deux. Le moteur déplace chaque particule vivante à chaque image, et cesse de les déplacer pendant que le jeu est en pause.

Une seule API d’émetteur sert l’overlay et la scène 3D ; seuls les unités et le dessin diffèrent. Tout ce qui est donné sous forme de minimum et de maximum (emitterSetLife, emitterSetSpeed, emitterSetSize) est tiré au hasard entre les deux pour chaque particule.

1.17.1. Émetteurs 2D

emitterNew() sans argument crée un émetteur 2D. Il vit en coordonnées de l’overlay, Y vers le bas, si bien que la gravité d’une fontaine est un Y positif. Déplacez-le avec emitterSetPosition, et dessinez-le depuis onOverlayUpdate avec emitterDraw. L’overlay lui-même est une image que le CPU peint, si bien que les particules n’y sont pas peintes : le GPU les dessine, soit au-dessus de tout l’overlay (PARTICLE_OVER, par défaut), soit en dessous de lui et au-dessus de la vidéo et de la scène 3D (PARTICLE_UNDER, pour de la fumée derrière le score). Les émetteurs 2D tournent sur toutes les machines où tourne Singe, Raspberry Pi 3 compris, et vont bien avec la physique 2D : lisez la position du nœud d’un corps et donnez-la à emitterSetPosition.

sparks = emitterNew()
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetLife(sparks, 0.3, 0.7)
emitterSetSpeed(sparks, 80, 200)
emitterSetDirection(sparks, 0, -1)       -- Vers le haut de l'écran.
emitterSetSpread(sparks, 70)
emitterSetGravity(sparks, 0, 500)
emitterSetSize(sparks, 5, 1)
emitterSetColor(sparks, 255, 255, 200, 255, 255, 120, 0, 0)

function onOverlayUpdate()
    overlayClear()
    emitterSetPosition(sparks, grinderX, grinderY)
    emitterDraw(sparks)
    return OVERLAY_UPDATED
end

1.17.2. Émetteurs 3D

emitterNew(node) crée un émetteur 3D attaché à un nœud. Les particules naissent à la position du nœud dans le monde (réparties sur emitterSetRadius), en unités du monde, et se dessinent dans la scène comme des billboards tournés vers la caméra, après tous les maillages : testées en profondeur contre la géométrie, sans jamais écrire la profondeur, non éclairées sauf demande, sans projeter ni recevoir d’ombres. Par défaut, une particule reste là où elle est née une fois qu’elle quitte l’émetteur (la fumée continue de dériver là où elle a été produite pendant que la torche s’éloigne) ; emitterSetLocal fait plutôt suivre le nœud à tout le nuage. Supprimer le nœud supprime ses émetteurs.

flame = emitterNew(torchTip)
emitterSetBlend(flame, PARTICLE_ADD)
emitterSetRate(flame, 140)
emitterSetLife(flame, 0.4, 0.9)
emitterSetSpeed(flame, 0.6, 1.4)
emitterSetDirection(flame, 0, 1, 0)
emitterSetSpread(flame, 15)
emitterSetSize(flame, 0.35, 0.05, 0.3)
emitterSetColor(flame, 255, 200, 90, 255, 255, 40, 0, 0)
emitterStart(flame)

1.17.3. L’image

Une particule est un quad texturé. Sans texture, c’est un disque aux bords doux fourni par le moteur ; emitterSetTexture lui donne plutôt un sprite chargé (une bouffée, une traînée d’étincelle, un flocon de neige), et pour un sprite animé, emitterSetFrames choisit une image au hasard par particule, si bien qu’un seul atlas de bouffées donne un nuage varié. Le mélange est normal (PARTICLE_ALPHA) ou additif (PARTICLE_ADD, pour tout ce qui brille). emitterSetColor donne la couleur et l’alpha à la naissance et à la mort, et la particule passe de l’un à l’autre au fil de sa vie ; emitterSetSize fait de même pour sa taille, avec une troisième valeur pour la vitesse à laquelle elle tourne.

1.17.4. Traînées, collisions, particules éclairées et particules douces

emitterSetTrail(emitter, length, width) garde les dernières positions de chaque particule et dessine un ruban qui les traverse, en s’estompant vers la queue : étincelles, balles traçantes, comètes, en 2D comme en 3D. emitterSetCollide fait rebondir les particules : sur un sol horizontal à une hauteur que vous donnez (COLLIDE_FLOOR, gratuit), ou sur le monde physique par lancers de rayons (COLLIDE_SCENE, 3D seulement, plafonné par image, si bien qu’un gros émetteur répartit le coût sur quelques images).

Deux autres sont réservés à la 3D. emitterSetLit éclaire chaque particule selon les lumières et le ciel de la scène comme une petite sphère tournée vers la caméra, si bien que la fumée prend la couleur d’un brasero et que la poussière scintille au soleil (les ombres ne sont pas lues). emitterSetSoftness fait disparaître progressivement une particule sur une certaine distance là où elle rencontre la géométrie, si bien que la fumée ne tranche pas dans un sol, ni une fontaine dans son bassin ; cela coûte une passe de profondeur supplémentaire de la scène par image tant qu’un émetteur l’utilise.

smoke = emitterNew(brazier)
emitterSetTexture(smoke, spriteLoad(DIR .. "puff.png"))
emitterSetRate(smoke, 30)
emitterSetLife(smoke, 2, 4)
emitterSetSpeed(smoke, 0.3, 0.6)
emitterSetDirection(smoke, 0, 1, 0)
emitterSetSize(smoke, 0.3, 1.2, 0.2)
emitterSetColor(smoke, 90, 90, 90, 160, 60, 60, 60, 0)
emitterSetLit(smoke, true)                  -- Prend la couleur du feu par en dessous.
emitterSetSoftness(smoke, 0.4)              -- Pas d'arête nette là où elle touche la vasque.
emitterStart(smoke)

embers = emitterNew(brazier)
emitterSetBlend(embers, PARTICLE_ADD)
emitterSetTrail(embers, 6, 0.02)            -- Une courte traînée derrière chaque braise.
emitterSetCollide(embers, COLLIDE_FLOOR, 0.3, 0.8, 0)   -- Rebondit sur le sol à Y = 0.
emitterStart(embers)

1.17.5. Coût

Les particules coûtent peu à simuler et coûtent ce qu’elles couvrent à l’écran. Quelques milliers de petites ne sont rien ; une poignée de grandes particules additives sur tout l’écran, voilà ce qui ralentit un Raspberry Pi 4. La réserve est plafonnée par emitterSetMax (1000 par défaut) ; quand elle est pleine, il n’en naît plus aucune tant que certaines ne sont pas mortes.

1.18. Décrire un jeu au lieu de l’écrire

Un jeu peut être écrit sous forme de description — une table de couches, d’entités et de règles — et compilé en un jeu Singe ordinaire par Forge, l’outil de création. Forge est un projet distinct, avec son propre téléchargement et son propre livre.

1.19. Migrer depuis Singe 2.10

Singe 3.00 a déplacé le handle du sprite vers le premier argument de spriteDraw, spriteLoop, spriteQuality, spriteRotate, spriteRotateAndScale, spriteScale et spriteSetFrame, si bien que chaque appel de sprite correspond désormais à la famille video*. Pour mettre à jour un jeu, déplacez le dernier argument de chacun de ces appels en tête :

spriteDraw(x, y, cursor)          -- 2.10
spriteDraw(cursor, x, y)          -- 3.00
spriteRotate(angle, cursor)       -- 2.10
spriteRotate(cursor, angle)       -- 3.00

Un jeu que vous ne pouvez pas modifier peut choisir l’ancien ordre à la place. Soit vous définissez la variable globale avant de charger le framework :

SINGE_LEGACY_SPRITE_ARGS = true
dofile("Singe/Framework.singe")

soit vous ajoutez LEGACY_SPRITE_ARGS = true à son entrée de games.dat. Rien d’autre n’a changé de forme, mais quelques comportements, si :

  • Les handles et les compteurs sont renvoyés sous forme d’entiers Lua ; videoIsPlaying renvoie un booléen ; mouseSetMode ne renvoie rien.

  • Les erreurs dans les callbacks terminent désormais le jeu avec une trace de la pile d’appels au lieu d’être affichées et ignorées, comme les erreurs d’arguments l’ont toujours fait.

  • Les touches maintenues ne se répètent plus en MODE_NORMAL.

  • Rien n’est écrit à côté du jeu. Sans --datadir, le dossier de données est data/<game>/ sous le dossier du jeu, là où 2.x utilisait le dossier même du jeu ; les sauvegardes, les réglages et les meilleurs scores ont leur place sous singeGetDataPath().

  • math.randomseed accepte une graine fractionnaire, comme sous le Lua de 2.10 ; elle est arrondie à l’entier inférieur avant que le générateur de Lua 5.4 ne la voie. os.clock est le temps d’horloge écoulé depuis le démarrage du moteur, pas le temps processeur.

  • Le disque est placé sur l’image 1 par le moteur avant que votre script ne s’exécute ; Framework.singe ne fait plus de saut quand il est chargé.

  • onMouseMoved en mode MANY_MOUSE transmet le déplacement réel dans ses troisième et quatrième arguments, et onControllerMoved transmet l’indice de la manette (0 à 3) au lieu de l’identifiant d’instance de SDL.

  • mouseEnable / mouseDisable et singeEnablePauseKey / singeDisablePauseKey fonctionnent toujours, comme alias de mouseSetEnabled et singeSetPauseKeyEnabled.

  • Un laserdisc n’est plus supposé d’office. Une entrée de games.dat avec un VIDEO est un jeu laserdisc, comme avant ; une entrée sans tourne plutôt sur un canevas. En ligne de commande, passez --disc (ou --framefile), car une vidéo trouvée à côté du script n’implique plus un disque. Voir Jeux sans disque.

  • La touche pause met désormais en pause tout le jeu, pas seulement les médias : le script est gelé jusqu’à ce que la touche soit de nouveau pressée, et SWITCH_PAUSE n’est transmis au script que lorsque la touche a été désactivée. Elle agit à l’appui de la touche plutôt qu’au relâchement. Voir La pause.

  • fontPrint conserve les chaînes qu’il rend, et overlayClear ne remplit à nouveau que ce qui a été dessiné depuis le dernier effacement, si bien qu’un HUD réimprimé à chaque image coûte peu. Rendre du texte avec fontToSprite pour les performances est déconseillé ; cela fonctionne toujours, et c’est toujours le moyen d’obtenir du texte que l’on peut mesurer, mettre à l’échelle ou faire tourner. Voir fontToSprite.

1.20. Constantes du moteur

Le moteur définit ces variables globales avant l’exécution de tout script, si bien qu’elles sont disponibles pour controls.cfg comme pour Framework.singe :

Constante Signification

SWITCH_UP …​ SWITCH_RECORD

Valeurs passées à onInputPressed / onInputReleased en MODE_NORMAL. SWITCH_MOUSE_DISCONNECT est émis par le moteur lui-même quand une souris ou un pistolet optique est débranché, une fois comme appui et une fois comme relâchement ; aucune touche ni aucun bouton ne le produit. SWITCH_RECORD est le contact d’enregistrement, sur lequel le moteur agit lui-même, comme pour le contact de capture d’écran.

FONT_QUALITY_SOLID, FONT_QUALITY_SHADED, FONT_QUALITY_BLENDED

Arguments de fontQuality.

MODE_NORMAL, MODE_FULL

Arguments de keyboardSetMode.

MOUSE_SINGLE, MOUSE_MANY (aussi SINGLE_MOUSE, MANY_MOUSE)

Arguments de mouseSetMode.

OVERLAY_NOT_UPDATED, OVERLAY_UPDATED

Valeurs de retour de onOverlayUpdate.

RENDER_PIXELATED, RENDER_SMOOTH

Arguments de spriteQuality / videoQuality.

SPRITE_ALPHA, SPRITE_ADD, SPRITE_MULTIPLY

Mélange pour spriteSetBlend.

DISC_STOPPED, DISC_PLAYING, DISC_PAUSED, DISC_EJECTED

Valeurs renvoyées par discGetState.

LIGHT_DIRECTIONAL, LIGHT_POINT, LIGHT_SPOT

Arguments de lightNew.

BODY_STATIC, BODY_DYNAMIC, BODY_KINEMATIC

Types de corps pour bodyNew.

SHAPE_BOX, SHAPE_SPHERE, SHAPE_CAPSULE, SHAPE_CYLINDER, SHAPE_HULL, SHAPE_MESH

Formes de collision pour bodyNew.

JOINT_HINGE, JOINT_BALL, JOINT_SLIDER

Types d’articulation (les appels joint* les nomment directement).

DEBUG_NONE, DEBUG_SHAPES, DEBUG_CONSTRAINTS, DEBUG_CONTACTS, DEBUG_VELOCITIES, DEBUG_STATIC, DEBUG_ALL

Ce que dessine physicsSetDebug ; additionnez-les.

PARTICLE_ALPHA, PARTICLE_ADD

Mélange pour emitterSetBlend.

PARTICLE_OVER, PARTICLE_UNDER

Où se dessinent les particules 2D, pour emitterSetLayer.

COLLIDE_NONE, COLLIDE_FLOOR, COLLIDE_SCENE

Ce sur quoi rebondissent les particules, pour emitterSetCollide.

BILLBOARD_NONE, BILLBOARD_ALL, BILLBOARD_Y

Comment un nœud fait face à la caméra, pour nodeSetBillboard.

LAYER_SCENE, LAYER_FRONT

Si un nœud se dessine sous l’overlay ou devant lui, pour nodeSetLayer.

VEHICLE_CAR, VEHICLE_MOTORCYCLE, VEHICLE_TANK, VEHICLE_BOAT

Sortes de véhicules pour vehicleNew.

SOFT_CLOTH, SOFT_BODY, SOFT_ROPE

Sortes de corps mous pour softNew.

FILTER_LINEAR, FILTER_NEAREST

Échantillonnage des textures pour materialSetFilter.

TONEMAP_NEUTRAL, TONEMAP_ACES, TONEMAP_NONE

Courbes de tonalité pour sceneSetTonemap.

SOUND_ERROR_INVALID, SOUND_REMOVE_HANDLE

-1, ce que renvoie soundPlay quand aucun canal n’est libre.

SINGE_VERSION_MAJOR, SINGE_VERSION_MINOR, SINGE_VERSION_STRING, SINGE_FRAMEWORK_VERSION

La version du moteur, sous forme d’entiers, de chaîne ("v3.00") et du nombre que renvoie singeVersion().

SINGE_DEAD_ZONE

La DEAD_ZONE de controls.cfg, en unités brutes d’axe.

SINGE_TRIGGER_THRESHOLD

Le seuil des gâchettes analogiques dans ces mêmes unités brutes ; 0 quand les gâchettes suivent SINGE_DEAD_ZONE, ce qui est le cas par défaut.

SINGE_LEGACY_SPRITE_ARGS

Vrai quand le jeu a demandé l’ordre des arguments de sprite de 2.10.

SINGE_DISC

Vrai quand le jeu a un laserdisc ; faux quand le canevas est le monde.

SINGE_GAMEPAD_BASE, SINGE_GAMEPAD_STRIDE, SINGE_AXIS_STRIDE, SINGE_GAMEPAD_BUTTON_OFFSET, SINGE_MOUSE_BASE, SINGE_MOUSE_STRIDE, SINGE_MAX_CONTROLLERS, SINGE_MAX_MICE, SINGE_CONTROLLER_AXES, SINGE_CONTROLLER_BUTTONS

Disposition des codes d’entrée des manettes et des souris, et nombre d’axes et de boutons d’une manette ; Framework.singe construit à partir d’eux les tables GAMEPAD_N et MOUSE_N, et un écran de service s’en sert pour parcourir une manette.

SINGE_SCALE_MIN, SINGE_SCALE_MAX, SINGE_SHIFT_MIN, SINGE_SHIFT_MAX, SINGE_ROTATE_STEP

Ce qu’acceptent vldpSetScale, vldpSetShift et vldpSetRotate. Bornez à ces valeurs plutôt qu’à vos propres copies : un décalage hors limites met fin au script.

Framework.singe ajoute les tables SCANCODE et MODIFIER (les valeurs de touches et de modificateurs de SDL), GAMEPAD_0 à GAMEPAD_3, MOUSE_0 à MOUSE_3, les index GAMEPAD_AXIS_* pour controllerGetAxis, et DIR.

1.21. Bibliothèques incluses

En plus des bibliothèques standard de Lua et de l’API Singe, les bibliothèques suivantes sont aussi utilisables dans les programmes Singe sans avoir à installer de logiciel supplémentaire :

Bibliothèque Rôle

Copas

Réseau asynchrone

LuaFileSystem

Prise en charge étendue du système de fichiers

json.lua

Encodage et décodage JSON (JavaScript Object Notation)

binaryheap

Structure de données de tas binaire

timerwheel

Planification efficace de minuteries

LuaSec

Communication TLS / SSL

LuaSocket

TCP et UDP

LuaRS232

Accès au port série RS232

lsqlite3

Bases de données SQLite, require("sqlite3")

md5

require("md5") pour sum, hexsum, exor, crypt et decrypt ; la bibliothèque de PUC-Rio qu’Hypseus embarque, dont elle nomme hexsum la fonction sumhexa

LuaBitOp

require("bit") pour les opérations bit à bit de Lua 5.1, que 5.4 a sous forme d’opérateurs

lrandom

require("random") pour un générateur Mersenne Twister, distinct de math.random

Lua CJSON

require("cjson") pour l’encodage et le décodage JSON, à côté du module json ci-dessus

LPeg

require("lpeg") pour les grammaires d’expressions d’analyse

middleclass

require("middleclass") pour les classes, si vous préférez construire vos entités avec elles plutôt qu’avec des tables

lume

require("lume") pour les petites choses dont tout jeu a besoin : lerp, clamp, round, shuffle, split, serialize, weightedchoice

inspect

require("inspect") pour afficher une table sous une forme qu’un humain peut lire, pour quand debugPrint tient lieu de débogueur

bump

require("bump") pour déplacer des choses qui ne doivent pas se traverser — il répond à la question de savoir où finit un objet qui se déplace, ce que les appels collide ne font délibérément pas

MobDebug

require("mobdebug"), le débogueur auquel parle ZeroBrane Studio ; --debug le démarre, si bien qu’un jeu n’a besoin d’aucune ligne à lui

RmlUi

Le modèle objet propre à l’interface, la variable globale rmlui (voir GUI)

Leur utilisation dépasse le cadre de ce document. Les bibliothèques md5, LuaBitOp, lrandom, Lua CJSON et LPeg sont là parce qu’Hypseus les expose, si bien qu’un jeu écrit pour Hypseus trouve les mêmes modules sous les mêmes noms ; rien dans Singe n’en a besoin.

1.22. Synchronisation audio

Singe présente la vidéo d’après l’horloge audio : une image est affichée quand le son qui va avec elle est entendu. Le moteur mesure son propre chemin audio au démarrage. SDL ne peut pas indiquer combien d’audio est en file d’attente entre le mélangeur et le haut-parleur, alors Singe vide le périphérique une fois, avant que quoi que ce soit d’audible ne joue, et compte la rafale de tampons que SDL utilise pour le remplir de nouveau ; cette rafale est la profondeur de la file, et l’horloge la soustrait. Lancez avec --program pour voir la mesure dans la trace (Audio device queue: …​).

Ce que le moteur ne peut pas voir, c’est tout ce qui se trouve en aval du serveur audio du système d’exploitation : un DAC, un ampli-tuner HDMI, une liaison Bluetooth. Ceux-ci ajoutent un délai fixe qui varie selon la machine. Si les actions à l’écran précèdent visiblement leur son, passez les millisecondes manquantes avec --audiodelay=MS, mettez AUDIO_DELAY = MS dans games.dat, ou laissez le jeu le régler depuis un menu de service avec singeSetAudioDelay. Les valeurs positives signifient que l’audio est en retard ; la vidéo est retenue d’autant. Une valeur négative traite le cas rare d’un audio qui arrive en avance.

Le menu fourni a un écran de calibrage pour ce délai en aval. Appuyez sur la touche affectée à INPUT_SERVICE (la touche 9 par défaut) dans la liste des jeux et choisissez Audio Delay dans les outils de service (voir Les outils de service). L’écran est une page du document du menu : il recouvre le menu de noir, affiche le délai essayé et la file du périphérique que le moteur a mesurée, joue un clic une fois par seconde et devient blanc pendant une image à chaque flash. Réglez avec gauche et droite (10 ms) et haut et bas (1 ms) jusqu’à ce que le flash et le clic se produisent ensemble, puis appuyez sur le bouton 1 pour enregistrer. Start remet à zéro et le bouton 2 (ou de nouveau la touche de service) annule. La valeur est stockée dans machine.cfg à la racine des données et appliquée par le moteur à chaque jeu de cette machine, qu’il soit lancé depuis le menu ou depuis la ligne de commande ; elle s’ajoute à tout AUDIO_DELAY propre à un jeu. Recalibrez après avoir changé de haut-parleurs, de casque ou d’écran.

L’écran fonctionne parce que le clic et l’audio du disque partagent un seul périphérique de mélangeur et une seule file : le flash est programmé, après le clic, à la file mesurée plus la valeur candidate, si bien que lorsque les deux coïncident, la valeur candidate est exactement le délai que le moteur ne peut pas voir. Le retard de l’affichage est compris gratuitement. Un jeu peut lire les valeurs avec singeGetAudioCalibration et singeGetAudioLatency, ou proposer son propre écran avec singeSetAudioCalibration.

Deux propriétés du fichier vidéo lui-même comptent aussi. L’audio AAC porte des échantillons d’amorçage de l’encodeur que le conteneur doit dire aux décodeurs d’ignorer ; les fichiers multiplexés sans cette information (un MP4 sans liste d’édition, un fichier Matroska sans délai de codec) jouent leur audio environ 20 millisecondes en retard, ce que AUDIO_DELAY peut absorber. Et quand la première image vidéo est horodatée plus tard que le premier échantillon audio, Singe respecte la synchronisation du conteneur, si bien que l’audio de tête n’est pas perdu.

1.23. Formats vidéo, audio et de conteneur

Singe décode la vidéo directement avec les bibliothèques de FFmpeg, en utilisant le décodeur matériel de la plateforme quand elle en offre un pour le codec (VA-API ou VDPAU sous Linux, D3D11VA sous Windows, VideoToolbox sous macOS, et sur une carte ARM les décodeurs V4L2 — celui de mémoire à mémoire, qui sur un Pi 4 couvre le H.264, celui de la Request API sans état qu’un Pi 5 utilise pour le HEVC, et celui propre à Rockchip sur un RK3588) et son propre décodeur logiciel sinon ; la trace du programme indique lequel, et --softwarevideo force le logiciel. Tout conteneur et tout codec que le FFmpeg fourni sait démultiplexer et décoder sera lu : MP4, MKV, flux de programme MPEG, AVI, AV1 et les flux élémentaires .m2v classiques de Daphne avec un fichier audio .ogg correspondant à côté. Chaque piste audio du fichier est disponible pour discSetAudioTrack / videoSetAudioTrack ; toutes les pistes doivent partager un même format d’échantillon, un même nombre de canaux et une même fréquence.

Un laserdisc contenait des trames entrelacées, et un rip qui les a conservées présente des effets de peigne sur tout affichage progressif. --deinterlace décide de ce qui se passe : auto, la valeur par défaut, applique bwdif aux images que le fichier marque comme entrelacées et laisse tout le reste tel quel, si bien qu’un disque progressif ne paie rien ; on est pour un fichier dont les indicateurs sont faux ; off ne touche jamais à l’image. Une image sort pour chaque image qui entre — un disque est adressé par numéro d’image, si bien qu’un désentrelaceur qui changerait chaque image en deux trames décalerait chaque image de l’index.

La première fois qu’une vidéo est ouverte, Singe l’indexe et stocke l’index à côté des autres données du jeu (<name>-<hash>.index, le hachage étant fait à partir du nom complet de la vidéo pour que deux vidéos de même nom de base gardent des index séparés). L’indexation est un seul passage sur le fichier sans décodage, quelques secondes même pour un disque de la durée d’un long métrage, et se refait si la vidéo change. Quand une vidéo est chargée, Singe indique l’espacement de ses images clés dans la trace du programme (--program), avec un avertissement si les images clés sont espacées de plus de deux secondes, car un saut doit décoder en avançant depuis l’image clé précédente. Le décodage se fait sur un fil d’exécution séparé, si bien qu’un saut lent montre l’image précédente un peu plus longtemps au lieu de bloquer le jeu.

Les segments d’un framefile sont ouverts à mesure que le disque les atteint, pas tous d’un coup : celui qui joue, celui d’après, et de la place pour qu’un saut passe de l’un à l’autre. Un long framefile peut avoir des centaines de segments — un jeu publié en a 213 — et garder un décodeur ouvert pour chacun d’eux coûte des centaines de fichiers ouverts sans rien y gagner. Un framefile qui nomme un fichier absent le signale toujours au démarrage.

Pour les séquences de laserdisc, les contraintes sont la précision à l’image et la vitesse de saut, pas la compression. Le H.264 en MP4 ou MKV avec un intervalle d’images clés court (une ou deux secondes) saute vite et se lit sur toutes les plateformes prises en charge ; de longs intervalles d’images clés rendent discSearch visiblement lent car le décodeur doit avancer depuis l’image clé précédente. La définition standard (720x480 ou 720x576) est le meilleur compromis. Les sources haute définition fonctionnent mais coûtent proportionnellement plus de CPU sur du matériel de la classe du Raspberry Pi, et l’overlay prend par défaut la moitié de la résolution de la vidéo, si bien qu’une vidéo surdimensionnée n’apporte pas grand-chose.

Les effets sonores et la musique sont lus d’abord par SDL_mixer, puis par FFmpeg pour tout ce qu’il refuse, si bien qu’à eux deux ils couvrent :

  • WAV, AIFF, AU et VOC pour l’audio non compressé. Les fichiers WAV courts non compressés donnent la latence la plus faible, et c’est ce que devrait être un coup de feu.

  • Ogg Vorbis, Opus, MP3, FLAC et WavPack.

  • AAC (.m4a, .aac), ALAC, AC-3, WMA, APE, TTA, Speex et AMR — tout le reste de ce que décode le FFmpeg fourni.

  • Les modules de tracker via libxmp : MOD, S3M, XM et IT, et une cinquantaine d’autres dont 669, AMF, MED, OKT, PTM, STM et ULT.

  • Les chiptunes via game-music-emu : NSF et NSFE, SPC, VGM, GBS, AY, GYM, HES, KSS et SAP. La forme VGZ compressée par gzip n’est pas lue ; décompressez-la d’abord en VGM. Un chiptune qui ne dit pas sa durée joue jusqu’à ce qu’il se taise, ce qui peut ne jamais arriver, si bien qu’il est décodé au fil de la lecture plutôt que d’avance.

  • Le MIDI, synthétisé à partir d’une SoundFont. Voir MIDI.

La ligne Audio: de l’en-tête de la trace (--program ou --trace) liste les décodeurs que la version compilée contient réellement.

Les images fonctionnent de la même façon : SDL_image d’abord, FFmpeg pour le reste. Cela couvre PNG, JPEG, WebP, GIF, BMP, TGA, PCX, PNM, LBM, QOI, XCF, XPM et SVG du côté de SDL_image, et TIFF, OpenEXR, JPEG 2000, DDS, PSD, DPX, AVIF et HEIC du côté de FFmpeg. Un GIF ou un WEBP animé se charge comme une animation de sprite ; voir spriteLoad, qui prend aussi une taille pour rastériser un SVG. Le .hdr de Radiance et OpenEXR fonctionnent tous deux comme ciel (sceneSetSky) et gardent toute leur plage.

Les polices sont lues par FreeType : TrueType, OpenType, WOFF, WOFF2, Type 1, BDF et PCF, avec les glyphes en couleur (bitmap comme vectoriels) et le façonnage HarfBuzz pour l’arabe, l’hébreu et les écritures indiennes.

Chapitre 2. Référence de l’API Lua

Ce chapitre documente l’API Lua exposée par le moteur Singe — chaque fonction que le script de votre jeu peut appeler, et chaque callback que Singe appellera chez vous. Il s’adresse aux développeurs qui écrivent de nouveaux jeux ou qui portent depuis d’autres moteurs des jeux qui reposent beaucoup sur la vidéo.

2.1. Conventions

Chaque entrée de l’API ci-dessous suit la même structure :

  • Signature(s) dans un bloc de code, montrant chaque forme acceptée.

  • Description de ce que fait la fonction et de ses éventuels effets de bord.

  • Paramètres listés en ligne, ou sous forme de tableau quand il y en a plus de deux.

  • Ligne Renvoie décrivant la valeur rendue à Lua (omise quand la fonction ne renvoie rien).

  • Remarques, s’il y a des pièges qui méritent d’être signalés.

  • Depuis — la version de Singe dans laquelle la fonction est apparue.

  • Voir aussi — les fonctions associées que vous utiliserez probablement au même endroit.

  • Exemple — un court extrait réaliste, à la forme d’un vrai code de jeu.

Une entrée qui commence par Extension Hypseus est là pour qu’un jeu écrit pour Hypseus Singe tourne ici sans modification. Il en va de même pour une forme d’argument marquée comme étant celle d’Hypseus sur une fonction qui prend sinon celle de Singe.

N’écrivez pas de nouveaux jeux pour l’API Hypseus. Ces entrées existent pour la compatibilité, pas comme une recommandation. Plusieurs d’entre elles répondent une valeur fixe parce que la chose qu’elles décrivent n’existe pas dans Singe, certaines sont acceptées et ignorées, et d’autres portent des échelles et des ordres d’arguments hérités d’un autre moteur — videoGetVolume() compte jusqu’à 64 là où le reste de Singe compte jusqu’à 100, et les noms spriteAnim prennent le sprite en dernier là où chaque appel de sprite de Singe le prend en premier. Chaque entrée nomme l’équivalent Singe à utiliser à la place. Un nouveau code qui s’en tient à l’API Singe est plus court, cohérent avec lui-même, et ne sera pas surpris quand une réponse de compatibilité reste constante.

Quelques règles s’appliquent à toute l’API :

  • Les couleurs sont sur 8 bits par canal : le rouge, le vert, le bleu et l’opacité sont chacun des entiers de 0 à 255.

  • Les coordonnées de l’overlay sont dans la résolution actuelle de l’overlay (fixée par overlaySetResolution), pas en pixels de l’écran. La résolution par défaut de l’overlay est la moitié de la résolution de la vidéo dans chaque dimension ; appelez overlaySetResolution pour la changer.

  • Les handles renvoyés par les fonctions *Load (sprites, sons, polices, vidéos) sont des entiers opaques. Repassez-les tels quels aux autres fonctions de cet espace de noms. Ne faites pas de calculs avec.

  • Les arguments invalides mettent fin au script. Si une fonction est appelée avec un mauvais nombre d’arguments, de mauvais types, ou un handle qui a déjà été déchargé, Singe met fin au script en cours avec une erreur — elle ne renvoie ni nil ni un code d’échec. Validez les saisies de l’utilisateur dans votre script avant de les confier à l’API.

  • Le dessin doit se faire depuis onOverlayUpdate. Les appels à toute fonction overlay*, spriteDraw, videoDraw ou fontPrint depuis d’autres callbacks ne se verront pas à l’écran et peuvent corrompre l’overlay. C’est la règle qui piège tous les nouveaux développeurs Singe.

2.2. Animation

Ces appels pilotent les animations que porte un modèle, instance par instance. Chacun prend le nœud racine renvoyé par modelInstance ; les autres nœuds lèvent une erreur, sauf avec animationIsPlaying, qui répond false. Les animations sont numérotées à partir de 1 dans l’ordre où modelGetAnimations les liste, ou nommées comme le fichier les nomme. Un clip joue sur la couche de base, et jusqu’à quatre autres peuvent jouer sur les couches 1 à 4 au-dessus d’elle ; les appels de temps, de pause, de reprise et de saut ne visent que la couche de base. Le temps est en secondes, avance avec l’horloge d’au plus un dixième de seconde par image, et s’arrête pendant que le jeu est en pause. L’animation des nœuds, le skinning et les poids des morph targets sont tous pilotés. Voir la partie Animation de Scènes 3D.

2.2.1. animationGetTime

seconds = animationGetTime(node)

Le temps courant dans le clip de la couche de base, en lecture ou en pause, en secondes propres au clip (une speed de 2 le fait avancer deux fois plus vite). Un clip en boucle revient à 0 à sa fin ; un clip sans boucle s’arrête à sa durée. Si rien n’a encore joué, la réponse est 0. Les clips des couches supérieures ne sont pas rapportés. Un nœud qui n’est pas une racine d’instance met fin au script.

Renvoie : Les secondes, sous forme de nombre.

Depuis : 3.00. Voir aussi : animationSetTime, animationIsPlaying

Exemple
-- Jouer le bruit de pas une fois à chaque passage du cycle de marche par ses deux points de contact.
function onOverlayUpdate()
    local t = animationGetTime(hero)
    if (lastStepTime < 0.25 and t >= 0.25) or (lastStepTime < 0.75 and t >= 0.75) then
        soundPlay(footstep)
    end
    lastStepTime = t
    return OVERLAY_NOT_UPDATED
end

2.2.2. animationIsPlaying

playing = animationIsPlaying(node)

Indique si le clip de la couche de base avance sur cette instance. Un clip sans boucle cesse de jouer quand il atteint sa fin, et animationPause comme animationStop rendent cette valeur false ; un clip en boucle reste true jusqu’à ce qu’il soit arrêté. Contrairement aux autres appels de cette section, un nœud qui n’est pas une racine d’instance ne met pas fin au script mais répond false.

Renvoie : Booléen.

Depuis : 3.00. Voir aussi : animationPlay, animationPause

Exemple
-- Retour au repos une fois que l'attaque unique est terminée.
function onOverlayUpdate()
    if attacking and not animationIsPlaying(hero) then
        attacking = false
        animationPlay(hero, "Idle", true, 1, 0.2)
    end
    return OVERLAY_NOT_UPDATED
end

2.2.3. animationPause

animationPause(node)

Fige le clip de la couche de base à son temps courant ; les nœuds gardent cette pose jusqu’à ce que animationResume le reprenne ou qu’un autre clip soit joué. Les clips des couches supérieures continuent de tourner. Mettre en pause une instance sur laquelle rien ne joue est sans danger. Un nœud qui n’est pas une racine d’instance met fin au script.

Depuis : 3.00. Voir aussi : animationResume, animationSetTime

Exemple
-- Une cinématique fige la foule pendant que la caméra bouge.
function beginCutscene()
    for _, npc in ipairs(crowd) do
        animationPause(npc)
    end
    cameraSet(cutsceneCamera)
end

2.2.4. animationPlay

animationPlay(node, nameOrIndex)
animationPlay(node, nameOrIndex, loop)
animationPlay(node, nameOrIndex, loop, speed)
animationPlay(node, nameOrIndex, loop, speed, fade)

Démarre l’un des clips du modèle depuis son début sur la couche de base de cette instance, en remplaçant ce qui y jouait ; la pose se met à jour aussitôt. Avec un fade, l’ancien clip continue de tourner pendant qu’il s’estompe sur ce nombre de secondes, et quand rien ne jouait, le fondu part de la pose où se trouvent les nœuds à présent (un ragdoll qui vient d’être désactivé, une pose fixée par le script), les nœuds que le nouveau clip n’anime pas revenant en douceur à la pose de repos du modèle. Un nœud qui n’est pas une racine d’instance, un nom que le modèle n’a pas, ou un numéro hors de 1 au nombre de clips met fin au script.

Paramètres :

  • node — le nœud racine de l’instance, venant de modelInstance.

  • nameOrIndex — un nom de clip tel que le fichier le stocke, ou son numéro à partir de 1 dans l’ordre de modelGetAnimations.

  • loop — booléen, true par défaut. À false, le clip s’arrête à sa dernière image clé et animationIsPlaying devient false.

  • speed — vitesse de lecture, 1 par défaut. 2 est deux fois plus rapide ; 0.5 deux fois plus lent.

  • fade — durée en secondes du fondu enchaîné depuis ce qui jouait, 0 par défaut (un passage sec).

Exemple
-- Un garde qui reste au repos jusqu'à ce que le joueur soit repéré, puis court.
guardModel = modelLoad(DIR .. "Models/Guard.glb")
guard      = modelInstance(guardModel)
animationPlay(guard, "Idle")

function onSpotted()
    animationPlay(guard, "Run", true, 1.3, 0.4)
end

2.2.5. animationPlayLayer

animationPlayLayer(node, layer, nameOrIndex)
animationPlayLayer(node, layer, nameOrIndex, loop)
animationPlayLayer(node, layer, nameOrIndex, loop, speed)
animationPlayLayer(node, layer, nameOrIndex, loop, speed, fade)

Joue un clip sur l’une des quatre couches au-dessus de la base, mélangé par-dessus ce qui se trouve en dessous selon le poids de la couche (animationSetLayerWeight, 1 par défaut) et limité à une partie du squelette quand un masque est défini (animationSetLayerMask). Les couches supérieures se mélangent par-dessus les inférieures ; chaque couche fait tourner son propre clip, son temps et sa boucle indépendamment de la base. nameOrIndex, loop, speed et fade ont le même sens que dans animationPlay, à une différence près : un fade sur une couche qui était vide fait monter le poids de la couche depuis 0 au lieu de faire un fondu enchaîné depuis une pose. Une couche hors de 1 à 4, un nœud qui n’est pas une racine d’instance, ou un clip que le modèle n’a pas met fin au script.

Paramètres :

  • node — le nœud racine de l’instance.

  • layer — 1 à 4.

  • nameOrIndex — un nom ou un numéro de clip, comme dans animationPlay.

  • loop — true par défaut.

  • speed — 1 par défaut.

  • fade — en secondes, 0 par défaut.

Exemple
-- Marcher avec tout le corps, regarder alentour avec la tête seulement.
animationPlay(fox, "Walk", true)
animationPlayLayer(fox, 1, "Survey", true, 1, 0.5)
animationSetLayerMask(fox, 1, nodeFind("b_Neck_04", fox))

-- Plus tard, saluer d'un bras par-dessus ce que font les jambes.
function onGreet()
    animationPlayLayer(fox, 2, "Wave", false, 1, 0.2)
end

2.2.6. animationResume

animationResume(node)

Reprend le clip de la couche de base là où animationPause l’a figé, ou là où animationSetTime l’a déplacé entre-temps. Reprendre un clip qui joue déjà ne change rien. Une instance sans clip sur sa couche de base (jamais joué, ou arrêté) met fin au script, de même qu’un nœud qui n’est pas une racine d’instance.

Depuis : 3.00. Voir aussi : animationPause, animationSetTime

Exemple
function endCutscene()
    for _, npc in ipairs(crowd) do
        animationResume(npc)
    end
    cameraSet(gameCamera)
end

2.2.7. animationSetLayerMask

animationSetLayerMask(node, layer, maskNode)
animationSetLayerMask(node, layer)

Limite une couche à maskNode et à tout ce qui se trouve sous lui, si bien que le clip de cette couche ne déplace que cette partie du modèle et que le reste continue de suivre les couches en dessous. maskNode doit être l’un des nœuds propres de l’instance, trouvé avec nodeFind(name, node) ; la racine de l’instance elle-même ne compte pas. Omettre maskNode, ou passer nil, lève la limite. Le masque reste sur la couche lors des appels animationPlayLayer suivants. Une couche hors de 1 à 4 met fin au script, tout comme un nœud qui n’est pas une racine d’instance ou un maskNode qui ne fait pas partie de cette instance.

Paramètres :

  • node — le nœud racine de l’instance.

  • layer — 1 à 4.

  • maskNode — une articulation ou un nœud de l’instance ; omis ou nil pour tout le modèle.

Depuis : 3.00. Voir aussi : animationPlayLayer, nodeFind, animationSetLayerWeight

Exemple
-- Pointer le haut du corps vers la cible pendant que les jambes continuent de marcher.
spine = nodeFind("b_Spine02_03", hero)
animationSetLayerMask(hero, 1, spine)
animationPlayLayer(hero, 1, "AimForward", true)

function onHolster()
    animationStop(hero, 1)
    animationSetLayerMask(hero, 1)
end

2.2.8. animationSetLayerWeight

animationSetLayerWeight(node, layer, weight)

Dans quelle mesure le clip d’une couche se voit par-dessus ce qui est en dessous, de 0 (pas du tout) à 1 (entièrement, la valeur par défaut) ; les valeurs hors de cet intervalle sont bornées. Le poids appartient à la couche, pas au clip, si bien qu’il survit à animationPlayLayer et à animationStop sur cette couche. Changez-le un peu à chaque image pour faire apparaître ou disparaître une couche à la main, ou laissez un fade sur animationPlayLayer le faire une fois. Une couche hors de 1 à 4 ou un nœud qui n’est pas une racine d’instance met fin au script.

Depuis : 3.00. Voir aussi : animationPlayLayer, animationSetLayerMask

Exemple
-- La boiterie s'aggrave à mesure que la santé baisse.
function onHealthChanged(health)
    local limp = 1 - health / maxHealth
    animationSetLayerWeight(hero, 1, limp)
end

2.2.9. animationSetTime

animationSetTime(node, seconds)

Fait sauter le clip de la couche de base à un temps exprimé en ses propres secondes ; les valeurs négatives deviennent 0. La pose se met à jour aussitôt, que le clip joue ou non, si bien qu’une instance en pause peut être amenée à une image exacte, et qu’une instance en lecture continue depuis le nouveau temps. Tout fondu enchaîné en cours sur la couche de base est interrompu. Une instance sans clip sur sa couche de base met fin au script, de même qu’un nœud qui n’est pas une racine d’instance.

Depuis : 3.00. Voir aussi : animationGetTime, animationPause, animationResume

Exemple
-- Une porte dont le clip d'ouverture suit un levier que le joueur fait glisser.
animationPlay(door, "Open", false)
animationPause(door)

function onLeverMoved(fraction)
    animationSetTime(door, fraction * doorClipLength)
end

2.2.10. animationStop

animationStop(node)
animationStop(node, layer)

Arrête et oublie tous les clips de l’instance, ou seulement le clip d’une couche au-dessus de la base (1 à 4) ; la couche de base seule ne peut pas être arrêtée sans les couches au-dessus d’elle. Les nœuds gardent leur dernière pose, dont un animationPlay suivant avec un fade les fait sortir en douceur. Après avoir tout arrêté, animationResume et animationSetTime mettent fin au script jusqu’à ce que quelque chose soit de nouveau joué. Les poids et les masques des couches sont conservés. Une couche hors de 1 à 4 ou un nœud qui n’est pas une racine d’instance met fin au script.

Depuis : 3.00. Voir aussi : animationPlay, animationPlayLayer, animationPause

Exemple
-- Confier le corps au ragdoll physique : figer la pose, puis le laisser tomber.
function onKilled()
    animationStop(hero)
    ragdollActivate(hero)
end

-- Le salut sur la couche 2 est fini ; la marche en dessous continue.
function onWaveFinished()
    animationStop(hero, 2)
end

2.3. Bezel

Les illustrations de borne et l’afficheur de scores d’arcade qui va avec. mainBezelLoaded renseigne sur les illustrations que --bezel a chargées ; la famille scoreBezel pilote le panneau des scores, un document RmlUi que le moteur fournit et qu’un jeu peut remplacer par sa propre copie, un scoreBezel.rml à côté de son script. Chaque appel de cette section est une extension d’Hypseus Singe, conservée pour que ses jeux tournent sans modification, et chacun d’eux est décrit du point de vue du joueur dans Bezels.

Le panneau démarre éteint, comme dans Hypseus, et seul un jeu l’allume. Les valeurs qui lui sont données sont mémorisées qu’il soit affiché ou non, si bien qu’un jeu peut les régler avant d’activer le panneau. Chaque afficheur a le nombre de chiffres qu’a l’afficheur de scores d’Hypseus — six pour un score, deux pour les crédits, un pour un nombre de vies — et une valeur y est affichée alignée à droite avec des zéros en tête ; un score de plus de six chiffres montre ses six derniers. Les valeurs négatives d’Hypseus sont comprises aussi : -2 allume un tiret dans chaque chiffre, -4 un H et -5 un A, et -1, -3 et tout autre nombre négatif n’allument rien.

2.3.1. mainBezelLoaded

loaded, id = mainBezelLoaded()

Extension Hypseus. Indique si --bezel a chargé des illustrations de borne, et l’identifiant du fichier chargé. L’identifiant est le hachage FNV-1a sur 64 bits des octets du fichier, écrit sous forme de chaîne décimale, ce que rapporte Hypseus, si bien qu’un jeu qui reconnaît un bezel particulier à son numéro reconnaît ici le même fichier. Sans illustration chargée, les réponses sont false et "0".

Renvoie : booléen, et l’identifiant sous forme de chaîne.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : setOverlayOnTop, Bezels

Exemple
-- Ne dessiner le cadre en sprite que si le joueur n'a pas d'illustrations à lui.
local loaded, id = mainBezelLoaded()
if not loaded then
    spriteDraw(frameSprite, 0, 0)
end

2.3.2. scoreBezelClear

scoreBezelClear()

Extension Hypseus. Vide chaque afficheur du panneau des scores : les crédits, les deux scores et les deux nombres de vies n’affichent plus rien du tout, ne laissant que les chiffres atténués derrière eux. Les valeurs ne sont pas oubliées, mais le prochain scoreBezelCredits, scoreBezelScore ou scoreBezelLives rallume le panneau avec ce qu’il contient alors. Peut être appelé sans risque quand le panneau est éteint.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelEnable

2.3.3. scoreBezelCredits

scoreBezelCredits(credits)

Extension Hypseus. Règle l’afficheur des crédits, qui a deux chiffres. Rallume aussi un panneau que scoreBezelClear a vidé.

Paramètres :

  • credits — entier ; les deux derniers chiffres sont affichés.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelScore

2.3.4. scoreBezelEnable

scoreBezelEnable(enabled)
scoreBezelEnable(enabled, type)

Extension Hypseus. Affiche ou masque le panneau des scores. Le premier true le construit à partir du scoreBezel.rml propre au jeu, à côté de son script, quand il y en a un, ou sinon à partir de Singe/scoreBezel.rml ; le masquer et l’afficher de nouveau ensuite ne coûte rien et conserve ses valeurs. Il démarre masqué, ce qui est aussi le cas d’Hypseus à sa livraison, si bien qu’un jeu qui n’appelle jamais ceci se comporte exactement comme avant — et devrait interroger scoreBezelGetState avant de supposer qu’il en a un.

Le type d’Hypseus choisit parmi ses cinq implémentations d’afficheur de scores. Singe n’en a qu’une, un document RmlUi, si bien que l’argument est vérifié et ignoré. Une machine sans GPU n’a aucune GUI ; le panneau ne peut pas y être construit, scoreBezelGetState continue de répondre false, et un avertissement est affiché une fois. Un premier argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

  • type — entier, accepté et ignoré.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelGetState, Bezels

Exemple
-- Le panneau du moteur quand il y en a un, des sprites sinon.
scoreBezelEnable(true, 0)
if scoreBezelGetState() then
    scoreBezelTwinScoreOn(twoPlayer)
    scoreBezelCredits(credits)
else
    drawSpriteScoreboard()
end

2.3.5. scoreBezelGetState

state = scoreBezelGetState()

Extension Hypseus. Indique si le panneau des scores est affiché. Chaque jeu Hypseus pose cette question avant d’utiliser le panneau et dessine son propre afficheur de scores avec des sprites quand la réponse est false, ce qui est le bon repli et non un échec.

Renvoie : booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelEnable

2.3.6. scoreBezelLives

scoreBezelLives(player, lives)

Extension Hypseus. Règle l’afficheur des vies d’un joueur, qui a un chiffre. player vaut 1 ou 2 ; tout autre nombre est ignoré, et 2 l’est aussi tant que scoreBezelTwinScoreOn(true) n’a pas mis les afficheurs du second joueur sur le panneau. Rallume aussi un panneau que scoreBezelClear a vidé.

Paramètres :

  • player — 1 ou 2.

  • lives — entier ; le dernier chiffre est affiché.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelScore

2.3.7. scoreBezelScore

scoreBezelScore(player, score)

Extension Hypseus. Règle l’afficheur du score d’un joueur, qui a six chiffres. player vaut 1 ou 2, avec la même règle pour 2 que scoreBezelLives. Rallume aussi un panneau que scoreBezelClear a vidé.

Paramètres :

  • player — 1 ou 2.

  • score — entier ; les six derniers chiffres sont affichés.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelLives

Exemple
function addScore(points)
    score = score + points
    if scoreBezelGetState() then
        scoreBezelScore(1, score)
    end
end

2.3.8. scoreBezelTwinScoreOn

scoreBezelTwinScoreOn(enabled)

Extension Hypseus. Met sur le panneau les afficheurs de score et de vies du second joueur, ou les retire et laisse la place aux deux autres. Les désactiver vide aussi le panneau, exactement comme dans Hypseus, alors faites suivre d’une valeur si les afficheurs du premier joueur doivent rester allumés. Tant qu’ils sont désactivés, scoreBezelScore(2, …​) et scoreBezelLives(2, …​) ne font rien. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : scoreBezelScore

2.4. Corps

Un corps donne à un nœud de la scène une place dans le monde physique. Il y a un corps par nœud, désigné par le handle du nœud : un corps statique reste là où était le nœud quand le corps a été créé, un corps cinématique suit son nœud à chaque pas et pousse sans être poussé, et un corps dynamique est déplacé par la simulation et entraîne son nœud. Les tailles, les positions et les vitesses sont en unités du monde (des mètres dans une scène 3D, des pixels de l’overlay dans un monde 2D), les masses en kilogrammes et le temps en secondes. Chaque appel de cette section met fin au script quand le nœud n’a pas de corps ; un appel qui n’a de sens que pour une sorte de corps (une force sur un corps statique, par exemple) est ignoré sur les autres, sauf bodySetMass, qui lève une erreur. Voir Physique dans Développement de jeux pour la façon dont les corps, les nœuds et l’image s’articulent.

2.4.1. bodyNew

bodyNew(node, type, shape)
bodyNew(node, type, shape, a)
bodyNew(node, type, shape, a, b)
bodyNew(node, type, shape, a, b, c)

Donne au nœud un corps du type indiqué, placé là où le nœud se trouve dans le monde à cet instant (ses parents compris), avec une forme de collision dimensionnée par a, b et c en unités du monde et mise à l’échelle par l’échelle du nœud dans le monde. Un second appel sur le même nœud remplace le premier, et un nœud qui avait un joueur le perd. La masse d’un corps dynamique vient du volume de sa forme à la densité de l’eau, alors réglez bodySetMass sur tout ce qui doit paraître léger. Changer l’échelle du nœud plus tard ne redimensionne pas le corps. Met fin au script pour un type ou une forme inconnus, quand la physique n’est pas disponible sur cette machine, quand le monde contient déjà 4096 corps, ou quand la forme ne peut pas être construite (un SHAPE_MESH dynamique, ou une enveloppe sans maillage sous le nœud).

Paramètres :

  • type — BODY_STATIC, BODY_DYNAMIC ou BODY_KINEMATIC.

  • shape — SHAPE_BOX (a, b, c sont la largeur, la hauteur et la profondeur), SHAPE_SPHERE (a est le rayon), SHAPE_CAPSULE ou SHAPE_CYLINDER (a est le rayon, b la hauteur totale le long de Y, extrémités comprises), SHAPE_HULL (une enveloppe convexe du maillage du nœud et de tout ce qui est sous lui, sans tailles), ou SHAPE_MESH (les triangles exacts, corps statiques et cinématiques seulement ; un maillage de carte de hauteur devient un champ de hauteurs).

  • a, b, c — les tailles dont la forme a besoin ; celles qui manquent valent 0 et toute taille est portée à au moins 0.001.

Remarques : Une sphère est mise à l’échelle par le plus grand axe d’échelle du nœud, le rayon d’une capsule ou d’un cylindre par le plus grand de X et de Z. Une capsule plus courte que deux fois son rayon est une sphère avec une fine tranche au milieu.

Depuis : 3.00. Voir aussi : bodySetMass, bodyDelete, physicsSetGravity, playerNew

Exemple
-- Une caisse légère et un modèle de canard en enveloppe, lâchés sur le sol.
crate = nodeNew()
nodeSetMesh(crate, meshBox(0.6, 0.6, 0.6), wood)
nodeSetPosition(crate, -1, 1, 0)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
bodySetMass(crate, 5)
duck = modelInstance(modelLoad(DIR .. "Models/Duck.glb"))
nodeSetPosition(duck, 3, 2, 0)
bodyNew(duck, BODY_DYNAMIC, SHAPE_HULL)

2.4.2. bodyApplyForce

bodyApplyForce(node, fx, fy, fz)
bodyApplyForce(node, fx, fy, fz, px, py, pz)

Ajoute une force, en newtons, à un corps dynamique pour les pas de cette image seulement ; appelez-la à chaque image pour continuer à pousser. Sans point, la force agit par le centre de masse et ne fait que déplacer le corps ; avec un point du monde (px, py, pz), elle fait aussi tourner le corps autour de son centre. Une force accélère de la force divisée par la masse, alors dimensionnez-la selon bodySetMass. Les corps statiques et cinématiques l’ignorent.

Paramètres :

  • fx, fy, fz — la force en newtons le long de chaque axe du monde.

  • px, py, pz — point du monde facultatif où la force s’applique ; omettez-le pour le centre de masse.

Depuis : 3.00. Voir aussi : bodyApplyImpulse, bodySetMass

Exemple
-- Un ventilateur pousse le ballon à travers la pièce tant que l'interrupteur est enclenché.
function onOverlayUpdate()
    if fanOn then
        local bx, by, bz = nodeGetPosition(balloon)
        if bx < fanReach then
            bodyApplyForce(balloon, 2.5, 0.4, 0)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.4.3. bodyApplyImpulse

bodyApplyImpulse(node, ix, iy, iz)
bodyApplyImpulse(node, ix, iy, iz, px, py, pz)

Change d’un coup la quantité de mouvement d’un corps dynamique : une impulsion égale à la masse multipliée par une vitesse ajoute cette vitesse. Sans point, elle agit par le centre de masse ; avec un point du monde (px, py, pz), elle fait aussi tourner le corps, si bien que frapper une caisse près de son sommet la fait basculer. C’est l’appel pour un coup, un coup de pied, une explosion ou un lancement, là où bodyApplyForce sert à une poussée qui dure. Les corps statiques et cinématiques l’ignorent.

Paramètres :

  • ix, iy, iz — l’impulsion en kilogrammes mètres par seconde le long de chaque axe du monde.

  • px, py, pz — point du monde facultatif où l’impulsion s’applique ; omettez-le pour le centre de masse.

Depuis : 3.00. Voir aussi : bodyApplyForce, bodySetVelocity, physicsRaycast

Exemple
-- Projeter droit vers le haut ce qui se trouve sous la souris, au point touché.
local mx, my = mouseGetPosition(0)
local ox, oy, oz = sceneUnproject(mx, my, 0)
local fx, fy, fz = sceneUnproject(mx, my, 10)
local hit, hx, hy, hz = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz)
if hit and hit ~= floor then
    bodyApplyImpulse(hit, 0, 3, 0, hx, hy, hz)
end

2.4.4. bodyDelete

bodyDelete(node)

Retire le corps du monde ; le nœud et son maillage restent où ils sont. Chaque articulation attachée au corps, et tout véhicule construit dessus, disparaissent avec lui. Supprimer le nœud supprime aussi son corps, si bien que ceci ne sert qu’à garder un nœud sans son corps. Met fin au script quand le nœud n’a pas de corps.

Depuis : 3.00. Voir aussi : bodyNew, bodySetEnabled, jointDelete

Exemple
-- Une pièce ramassée cesse d'être solide et s'élève comme un simple nœud.
function onTrigger(trigger, other, entered)
    if trigger == coin and other == hero and entered then
        bodyDelete(coin)
        collected = collected + 1
        coinRising = true
    end
end

2.4.5. bodyGetAngularVelocity

x, y, z = bodyGetAngularVelocity(node)

La vitesse à laquelle le corps tourne autour de chaque axe du monde, en radians par seconde, au dernier pas. Un corps statique renvoie zéro. Utile pour la hauteur du son d’une roue ou un compteur de tours.

Renvoie : Trois nombres, en radians par seconde autour de X, Y et Z.

Depuis : 3.00. Voir aussi : bodySetAngularVelocity, bodyGetVelocity

Exemple
-- La roue de la roulette s'est arrêtée quand elle tourne à peine.
function onOverlayUpdate()
    local _, spin = bodyGetAngularVelocity(wheel)
    if spinning and math.abs(spin) < 0.05 then
        spinning = false
        announceWinner(pocketUnder(ball))
    end
    return OVERLAY_NOT_UPDATED
end

2.4.6. bodyGetVelocity

x, y, z = bodyGetVelocity(node)

La vitesse à laquelle le corps se déplace le long de chaque axe du monde, en unités du monde par seconde, au dernier pas. Un corps statique renvoie zéro ; un corps cinématique renvoie la vitesse qu’impliquait le mouvement de son nœud.

Renvoie : Trois nombres, en unités par seconde le long de X, Y et Z.

Depuis : 3.00. Voir aussi : bodySetVelocity, bodyGetAngularVelocity

Exemple
-- Jouer un bruit de souffle quand la balle va vraiment vite.
function onOverlayUpdate()
    local vx, vy, vz = bodyGetVelocity(ball)
    local speed = math.sqrt(vx * vx + vy * vy + vz * vz)
    if speed > 8 and not whooshing then
        soundPlay(whoosh)
        whooshing = true
    elseif speed < 2 then
        whooshing = false
    end
    return OVERLAY_NOT_UPDATED
end

2.4.7. bodyIsResting

resting = bodyIsResting(node)

Indique si la simulation a mis le corps en sommeil parce qu’il a cessé de bouger. Les corps statiques et les corps retirés du monde avec bodySetEnabled comptent comme au repos. Un corps au repos se réveille de lui-même quand quelque chose le touche ou quand une vitesse, une force ou une impulsion lui est appliquée.

Renvoie : Booléen.

Depuis : 3.00. Voir aussi : bodySetEnabled, bodySetVelocity

Exemple
-- La manche se termine une fois que toutes les quilles se sont stabilisées.
function onOverlayUpdate()
    local settled = true
    for _, pin in ipairs(pins) do
        settled = settled and bodyIsResting(pin)
    end
    if settled then
        scoreFrame()
    end
    return OVERLAY_NOT_UPDATED
end

2.4.8. bodySetAngularVelocity

bodySetAngularVelocity(node, x, y, z)

Règle la rotation autour de chaque axe du monde, en radians par seconde, et réveille le corps. Les corps statiques l’ignorent. La rotation d’un corps cinématique est écrasée à partir de son nœud au pas suivant, si bien que l’appel ne dure que pour les corps dynamiques.

Depuis : 3.00. Voir aussi : bodyGetAngularVelocity, bodySetVelocity

Exemple
-- Lancer la pièce : vers le haut, en tournant sur elle-même.
function tossCoin()
    nodeSetPosition(coin, 0, 1.2, 0)
    bodySetVelocity(coin, 0, 4, 0)
    bodySetAngularVelocity(coin, 25, 0, 0)
    tossed = true
end

2.4.9. bodySetBounce

bodySetBounce(node, bounce)

Règle la restitution du corps, de 0 (s’arrête net) à 1 (rebondit avec tout ce qu’il avait en arrivant) ; les valeurs hors de cet intervalle sont bornées. La valeur par défaut est 0.1. Les valeurs des deux corps en contact se combinent, si bien qu’une balle vive sur un sol mort rebondit quand même.

Depuis : 3.00. Voir aussi : bodySetFriction, bodyNew

Exemple
-- Une balle en caoutchouc lâchée sur la scène.
ball = nodeNew()
nodeSetMesh(ball, meshSphere(0.3, 32), blue)
nodeSetPosition(ball, 0, 3, 0)
bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.3)
bodySetMass(ball, 0.5)
bodySetBounce(ball, 0.7)

2.4.10. bodySetBuoyancy

bodySetBuoyancy(node, factor)

La façon dont le corps flotte quand il est dans un volume d’eau : 1 est neutre, plus flotte plus haut, moins coule, et 0 est une pierre. La valeur par défaut est 1.2, qui flotte doucement. Le facteur multiplie la densité propre de l’eau donnée par bodySetWater, et les valeurs négatives sont ramenées à 0. Seuls les corps dynamiques sont déplacés par l’eau, mais la valeur peut être réglée sur n’importe quel corps.

Depuis : 3.00. Voir aussi : bodySetWater, bodySetCurrent

Exemple
-- Une caisse qui flotte haut, une ancre qui coule, une balle qui danse sur l'eau.
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
bodySetMass(crate, 20)
bodySetBuoyancy(crate, 1.6)
bodyNew(anchor, BODY_DYNAMIC, SHAPE_BOX, 0.5, 0.5, 0.5)
bodySetMass(anchor, 200)
bodySetBuoyancy(anchor, 0.3)
bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.4)
bodySetBuoyancy(ball, 2.0)

2.4.11. bodySetCurrent

bodySetCurrent(node, x, y, z)

Règle le courant à l’intérieur d’un volume d’eau, en unités du monde par seconde le long de chaque axe du monde ; les corps dynamiques qui y flottent dérivent avec le courant et un joueur qui nage est emporté par lui. Par défaut, il n’y a pas de courant. Réglez-le sur le nœud sur lequel bodySetWater a été appelé ; sur tout autre corps, il est stocké et ne fait rien.

Depuis : 3.00. Voir aussi : bodySetWater, bodySetBuoyancy

Exemple
-- Une rivière qui emporte vers l'aval tout ce qu'on y lâche.
river = nodeNew()
nodeSetMesh(river, meshBox(6, 3, 12), water)
nodeSetPosition(river, 10, -1.5, 0)
bodyNew(river, BODY_STATIC, SHAPE_BOX, 6, 3, 12)
bodySetWater(river, 1.0, 0.8, 0.2)
bodySetCurrent(river, 0, 0, 2.5)

2.4.12. bodySetEnabled

bodySetEnabled(node, enabled)

Retire le corps du monde avec false : il cesse d’entrer en collision, cesse de bouger, n’entraîne plus son nœud ni ne le suit, et compte comme au repos. true le remet là où il est, éveillé. Le corps garde sa forme, sa masse et ses réglages, si bien que c’est moins coûteux que de le supprimer et de le recréer pour quelque chose qui va et vient.

Depuis : 3.00. Voir aussi : bodyIsResting, bodyDelete

Exemple
-- Le pont-levis n'est solide que lorsqu'il est baissé.
function lowerBridge()
    animationPlay(bridge, "Lower", false)
    bodySetEnabled(bridgeDeck, true)
end

function raiseBridge()
    animationPlay(bridge, "Raise", false)
    bodySetEnabled(bridgeDeck, false)
end

2.4.13. bodySetFriction

bodySetFriction(node, friction)

Règle le frottement de la surface : 0 est de la glace, 0.5 (la valeur par défaut) est ordinaire, les valeurs plus élevées adhèrent davantage. Les valeurs négatives sont ramenées à 0. Les valeurs des deux corps en contact se combinent, si bien qu’un sol glissant demande une valeur basse sur le sol, pas sur tout ce qui marche dessus.

Depuis : 3.00. Voir aussi : bodySetBounce, bodyNew

Exemple
-- Un étang gelé au milieu du niveau.
pond = nodeNew()
nodeSetMesh(pond, meshBox(6, 0.1, 6), ice)
nodeSetPosition(pond, 8, -1.95, 0)
bodyNew(pond, BODY_STATIC, SHAPE_BOX, 6, 0.1, 6)
bodySetFriction(pond, 0.02)

2.4.14. bodySetMass

bodySetMass(node, kilograms)

Remet à l’échelle la masse d’un corps dynamique et, avec elle, son inertie. Faites-le pour tout ce qui doit paraître léger ou lourd : par défaut, c’est le volume de la forme à la densité de l’eau, si bien qu’une boîte de la taille d’une porte pèse environ 140 kilogrammes et qu’une légère poussée ne la fera pas bouger. Les forces et les impulsions s’échelonnent avec la masse, alors réglez la masse avant de les ajuster. Met fin au script quand le corps n’est pas dynamique ou que la masse n’est pas positive.

Depuis : 3.00. Voir aussi : bodyNew, bodyApplyImpulse, playerSetPush

Exemple
-- Une caisse que le héros peut pousser et une enclume que personne ne peut bouger.
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
bodySetMass(crate, 5)
bodyNew(anvil, BODY_DYNAMIC, SHAPE_BOX, 0.5, 0.3, 0.3)
bodySetMass(anvil, 200)

2.4.15. bodySetTrigger

bodySetTrigger(node, trigger)

Fait du corps un déclencheur avec true : il ne pousse rien et n’arrête rien, mais onTrigger signale chaque corps ou joueur qui y entre et en sort. false le rend de nouveau solide : ce qui était à l’intérieur est oublié sans sortie signalée, tandis qu’un déclencheur dans lequel se trouve le corps lui-même continue de le signaler. Un déclencheur est généralement une boîte ou une sphère statique placée sur une porte, une ligne d’arrivée ou une zone dangereuse. Les rayons de physicsRaycast touchent les déclencheurs comme n’importe quel autre corps.

Remarques : Un joueur est signalé dans un déclencheur quand leurs boîtes englobantes se chevauchent, si bien qu’un déclencheur rond est carré pour les joueurs.

Depuis : 3.00. Voir aussi : onTrigger, bodyNew, bodySetWater

Exemple
-- Une ligne d'arrivée en travers de la piste.
line = nodeNew()
nodeSetPosition(line, 0, 0, -20)
bodyNew(line, BODY_STATIC, SHAPE_BOX, 6, 3, 0.5)
bodySetTrigger(line, true)

function onTrigger(trigger, other, entered)
    if trigger == line and other == car and entered then
        lapDone()
    end
end

2.4.16. bodySetVelocity

bodySetVelocity(node, x, y, z)

Règle la vitesse du corps le long de chaque axe du monde, en unités du monde par seconde, et le réveille. Ceci remplace la vitesse qu’avait le corps, là où bodyApplyImpulse s’y ajoute. Les corps statiques l’ignorent, et la vitesse d’un corps cinématique est écrasée à partir du mouvement de son nœud au pas suivant.

Depuis : 3.00. Voir aussi : bodyGetVelocity, bodyApplyImpulse, bodySetAngularVelocity

Exemple
-- Servir la balle vers le côté qui a perdu le dernier point.
function serve()
    nodeSetPosition(ball, 0, 0.5, 0)
    bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.15)
    bodySetMass(ball, 0.1)
    local dir = (lastWinner == 1) and -1 or 1
    bodySetVelocity(ball, 4 * dir, 2, (math.random() - 0.5) * 2)
end

2.4.17. bodySetWater

bodySetWater(node, density)
bodySetWater(node, density, linearDrag)
bodySetWater(node, density, linearDrag, angularDrag)

Remplit d’eau un corps statique et en fait un déclencheur : le dessus de sa forme est la surface, et chaque corps dynamique à l’intérieur flotte, coule ou roule par flottabilité par rapport à cette surface (la partie immergée de la forme compte, si bien qu’une caisse inclinée se redresse), ralenti par les traînées. Un joueur dont le milieu est sous la surface nage. Comme le volume est un déclencheur, onTrigger se déclenche à l’entrée et à la sortie. L’eau n’est pas dessinée : donnez au nœud un matériau en mélange, ou aucun. Met fin au script quand le corps n’est pas statique.

Paramètres :

  • density — un multiplicateur, 1 pour l’eau ; le bodySetBuoyancy propre à chaque corps le module. Les valeurs négatives sont ramenées à 0.

  • linearDrag — à quelle vitesse l’eau ralentit le mouvement qui la traverse ; 0.5 par défaut.

  • angularDrag — à quelle vitesse elle ralentit la rotation ; 0.1 par défaut.

Remarques : Les joueurs et les bateaux voient au plus huit volumes d’eau ; au-delà, les volumes font encore flotter les corps mais on ne peut pas y nager.

Exemple
-- Une piscine creusée dans le pont ; son dessus, à Y = 0, est la surface.
pool = nodeNew()
nodeSetMesh(pool, meshBox(8, 3, 12), water)
nodeSetPosition(pool, 0, -1.5, 0)
bodyNew(pool, BODY_STATIC, SHAPE_BOX, 8, 3, 12)
bodySetWater(pool, 1.0, 0.6, 0.2)

function onTrigger(trigger, other, entered)
    if trigger == pool and entered then
        soundPlay(splash)
    end
end

2.5. Caméra

La caméra est un nœud comme un autre : placez-la avec nodeSetPosition, orientez-la avec nodeLookAt, rattachez-la à un objet en mouvement pour une vue de poursuite, et désignez-la avec cameraSet. Elle regarde le long de son propre -Z. Sans nœud caméra, la scène est vue depuis (0, 0, 5) en regardant l’origine. La projection est réglée à part et s’applique au nœud, quel qu’il soit, qui est la caméra : perspective avec un champ de vision vertical de 60 degrés de 0.1 à 1000 unités par défaut, ou orthographique avec cameraSetOrthographic. Les vues rendues (viewNew) partagent la projection mais regardent depuis leurs propres nœuds. Voir Scènes 3D.

2.5.1. cameraSet

cameraSet(node)
cameraSet(-1)

Fait d’un nœud la caméra : la scène est dessinée depuis sa position dans le monde en regardant le long de son propre -Z, si bien que le mouvement et la rotation de ses parents comptent. N’importe quel nœud convient, y compris un nœud qui porte aussi un maillage ou une lumière, et changer de caméra ne demande qu’un appel. -1 rétablit la vue par défaut depuis (0, 0, 5) en regardant l’origine. Supprimer le nœud caméra ramène aussi à la vue par défaut. Met fin au script pour un handle de nœud qui n’est pas valide.

Depuis : 3.00. Voir aussi : nodeLookAt, cameraSetPerspective, viewSetCamera, nodeNew

Exemple
-- Une caméra de poursuite derrière la voiture du joueur, et une caméra fixe pour la rediffusion.
chaseCamera = nodeNew(car)
nodeSetPosition(chaseCamera, 0, 2, 6)
nodeLookAt(chaseCamera, nodeGetWorldPosition(car))
cameraSet(chaseCamera)

function onReplayStart()
    replayCamera = nodeNew()
    nodeSetPosition(replayCamera, 30, 12, 30)
    nodeLookAt(replayCamera, 0, 0, 0)
    cameraSet(replayCamera)
end

2.5.2. cameraSetOrthographic

cameraSetOrthographic(height, near, far)

Passe à une projection parallèle montrant height unités du monde de haut en bas, la largeur suivant le format d’image de la couche, de near à far devant la caméra. La distance ne rapetisse pas les choses, ce qui convient aux schémas, aux vues isométriques et de profil, et aux scènes façon HUD. Le réglage s’applique au nœud caméra actuel et à tout nœud caméra ultérieur jusqu’à l’appel de cameraSetPerspective. L’ombre d’une lumière directionnelle utilise une seule carte sous une caméra orthographique, quoi que dise sceneSetShadowCascades.

Paramètres :

  • height — la hauteur visible, en unités du monde.

  • near — la distance la plus proche dessinée, en unités du monde devant la caméra.

  • far — la distance la plus lointaine dessinée.

Depuis : 3.00. Voir aussi : cameraSetPerspective, cameraSet, sceneSetShadowCascades

Exemple
-- Une vue isométrique du plateau : 12 unités de haut, vue de haut et de côté.
boardCamera = nodeNew()
nodeSetPosition(boardCamera, 20, 20, 20)
nodeLookAt(boardCamera, 0, 0, 0)
cameraSet(boardCamera)
cameraSetOrthographic(12, 1, 100)

2.5.3. cameraSetPerspective

cameraSetPerspective(fov, near, far)

Passe à la projection en perspective habituelle, celle par défaut. fov est le champ de vision vertical en degrés (60 par défaut) ; near et far (0.1 et 1000 par défaut) bornent ce qui est dessiné, en unités du monde devant la caméra. La précision de la profondeur est répartie entre les deux, alors gardez near aussi grand que la scène le permet et far pas plus grand que nécessaire : 0.05 à 100 pour une pièce, 0.1 à 400 pour un paysage. Le réglage s’applique au nœud caméra actuel et à tout nœud caméra ultérieur, ainsi qu’aux vues rendues.

Paramètres :

  • fov — champ de vision vertical en degrés ; un large 70 donne une impression de vitesse, un étroit 40 celle d’un téléobjectif.

  • near — la distance la plus proche dessinée.

  • far — la distance la plus lointaine dessinée.

Depuis : 3.00. Voir aussi : cameraSetOrthographic, cameraSet, sceneProject

Exemple
-- Un objectif plus serré pour la vue du cockpit, celui par défaut pour l'extérieur.
function setView(inside)
    if inside then
        cameraSet(cockpitCamera)
        cameraSetPerspective(45, 0.05, 300)
    else
        cameraSet(chaseCamera)
        cameraSetPerspective(60, 0.1, 400)
    end
end

2.6. Collisions

Savoir si deux choses plates se touchent. Jolt y répond en trois dimensions pour les corps (voir Corps) ; ces fonctions y répondent pour l’overlay, là où vivent les hitbox d’un jeu au pistolet optique et absolument tout d’un jeu 2D.

Ce sont de simples fonctions : pas de handle, pas d’état, rien à créer ni à libérer, et rien à mettre à jour à chaque image. Les coordonnées sont celles dans lesquelles vous dessinez déjà — des pixels de l’overlay, en général. Un rectangle est un coin et une taille, comme le prend chaque appel de dessin du moteur. Se toucher exactement sur un bord compte comme se toucher, et un rectangle sans largeur ou sans hauteur ne touche rien du tout.

Aucune ne déplace quoi que ce soit. Quand vous voulez savoir non seulement si deux choses se sont rencontrées, mais où finit ce qui bouge — glisser le long d’un mur plutôt que s’y arrêter net — faites require("bump") et laissez-le s’en charger ; il est fourni exactement pour cette raison.

2.6.1. collideCircles

touching = collideCircles(x1, y1, radius1, x2, y2, radius2)

Indique si deux cercles se chevauchent. Moins coûteux qu’il n’y paraît : rien ne calcule de racine carrée pour répondre à une question par oui ou non.

Paramètres :

  • x1, y1, radius1 — nombres ; le premier cercle.

  • x2, y2, radius2 — nombres ; le second.

Renvoie : true ou false.

Depuis : 3.00. Voir aussi : collideRectCircle

2.6.2. collidePointCircle

inside = collidePointCircle(pointX, pointY, x, y, radius)

Indique si un point tombe dans un cercle. Le bord compte comme l’intérieur.

Paramètres :

  • pointX, pointY — nombres ; le point.

  • x, y, radius — nombres ; le cercle.

Renvoie : true ou false.

Depuis : 3.00.

2.6.3. collidePointPolygon

inside = collidePointPolygon(pointX, pointY, points)

Indique si un point tombe dans un polygone de forme quelconque, concaves compris. La table est une liste plate de x, y, x, y — la forme qu’a déjà une hitbox dans la plupart des jeux — et le sens de parcours n’a pas d’importance. Avec moins de trois sommets, le polygone ne contient rien. 256 sommets au plus.

Paramètres :

  • pointX, pointY — nombres ; le point.

  • points — table ; un nombre pair de nombres, x et y à tour de rôle.

Renvoie : true ou false.

Depuis : 3.00.

Exemple
-- Le tir a-t-il touché le dragon, dont le contour n'est pas un rectangle ?
local dragon = { 120,40, 200,60, 210,140, 150,180, 100,120 }

function onInputPressed(key)
    if key == SWITCH_BUTTON1 then
        local x, y = mouseGetPosition(0)
        if collidePointPolygon(x, y, dragon) then
            hit()
        end
    end
end

2.6.4. collidePointRect

inside = collidePointRect(pointX, pointY, x, y, width, height)

Indique si un point tombe dans un rectangle. Le bord compte comme l’intérieur.

Paramètres :

  • pointX, pointY — nombres ; le point.

  • x, y, width, height — nombres ; le rectangle.

Renvoie : true ou false.

Depuis : 3.00.

Exemple
-- Une hitbox de la taille du sprite auquel elle appartient.
local x, y = mouseGetPosition(0)
if collidePointRect(x, y, enemyX, enemyY, spriteGetWidth(enemy), spriteGetHeight(enemy)) then
    kill(enemy)
end

2.6.5. collideRectCircle

touching = collideRectCircle(x, y, width, height, circleX, circleY, radius)

Indique si un rectangle et un cercle se chevauchent, en cherchant le point du rectangle le plus proche du centre du cercle.

Paramètres :

  • x, y, width, height — nombres ; le rectangle.

  • circleX, circleY, radius — nombres ; le cercle.

Renvoie : true ou false.

Depuis : 3.00.

2.6.6. collideRects

touching = collideRects(x1, y1, width1, height1, x2, y2, width2, height2)

Indique si deux rectangles se chevauchent. Celle dont vous vous servirez le plus.

Paramètres :

  • x1, y1, width1, height1 — nombres ; le premier rectangle.

  • x2, y2, width2, height2 — nombres ; le second.

Renvoie : true ou false.

Depuis : 3.00. Voir aussi : collidePointRect

2.6.7. collideSegments

crossing = collideSegments(ax1, ay1, ax2, ay2, bx1, by1, bx2, by2)

Indique si deux segments se croisent : un tir le long d’une trajectoire contre un mur, ou le pas que veut faire un objet en mouvement contre le bord qu’il ne doit pas franchir. Des segments couchés l’un sur l’autre répondent false, car « où se croisent-ils » n’a alors pas de réponse unique.

Paramètres :

  • ax1, ay1, ax2, ay2 — nombres ; les extrémités du premier segment.

  • bx1, by1, bx2, by2 — nombres ; celles du second.

Renvoie : true ou false.

Depuis : 3.00.

2.7. Couleur

Les couleurs de premier plan et de fond sont des globales du moteur plutôt que des arguments passés à chaque appel : réglez-les avec colorForeground et colorBackground, et chaque appel de dessin qui suit les lit jusqu’à ce qu’elles changent. La couleur de premier plan sert aux primitives de forme overlay* et au texte TrueType de fontPrint et fontToSprite ; la couleur de fond sert à overlayClear et au texte FONT_QUALITY_SHADED. overlayPrint n’utilise ni l’une ni l’autre. Les canaux sont des entiers de 0 à 255, ramenés dans cette plage, et les deux couleurs acceptent un alpha facultatif. Voir les sections Overlay et Police pour les appels qui les utilisent.

2.7.1. colorBackground

colorBackground(r, g, b)
colorBackground(r, g, b, a)

Règle la couleur de fond : celle dont overlayClear remplit l’overlay, et celle que le texte FONT_QUALITY_SHADED de fontPrint et fontToSprite peint derrière ses glyphes. Au démarrage, c’est un noir transparent, et l’alpha vaut 0 par défaut quand il est omis, si bien que colorBackground(0, 0, 0) suivi de overlayClear() rend de nouveau l’overlay invisible. Un alpha partiel sur du noir assombrit la vidéo ; 255 la masque. Les valeurs de canal hors plage sont ramenées dans la plage plutôt que rejetées.

Paramètres :

  • r, g, b — rouge, vert et bleu, de 0 à 255.

  • a — opacité, de 0 (transparent) à 255 (opaque) ; 0 par défaut.

Depuis : 1.x Voir aussi : colorForeground, overlayClear, fontQuality

Exemple
-- Noir plein derrière l'écran de calibrage, transparent pendant la partie.
function onOverlayUpdate()
    if calibrating then
        colorBackground(0, 0, 0, 255)
    else
        colorBackground(0, 0, 0, 0)
    end
    overlayClear()
    drawHud()
    return OVERLAY_UPDATED
end

2.7.2. colorForeground

colorForeground(r, g, b)
colorForeground(r, g, b, a)

Règle la couleur de premier plan qu’utilisent overlayBox, overlayCircle, overlayEllipse, overlayLine et overlayPlot, et la couleur du texte de fontPrint et fontToSprite. Au démarrage, c’est un blanc opaque, et l’alpha vaut 255 par défaut quand il est omis, à l’inverse de colorBackground. Les sprites et overlayPrint sont dessinés avec leurs propres pixels et ne sont pas teintés. Les valeurs de canal hors plage sont ramenées dans la plage plutôt que rejetées.

Paramètres :

  • r, g, b — rouge, vert et bleu, de 0 à 255.

  • a — opacité, de 0 (transparent) à 255 (opaque) ; 255 par défaut.

Depuis : 1.x Voir aussi : colorBackground, overlayBox, fontPrint, fontToSprite

Exemple
-- Le score en blanc, l'alerte de dernière vie en rouge, tous deux avec la même police.
function onOverlayUpdate()
    overlayClear()
    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    fontPrint(8, 8, "Score: " .. score)
    if lives == 1 then
        colorForeground(255, 32, 32)
        fontPrint(8, 32, "LAST LIFE")
    end
    return OVERLAY_UPDATED
end

2.8. Ligne de commande

Trois appels renvoient des nombres que l’utilisateur a choisis au lancement de Singe. Ils existent pour qu’un jeu puisse être réglé depuis le lanceur plutôt qu’en modifiant le jeu. Tous trois sont des extensions d’Hypseus Singe, et Singe ne fait rien lui-même des valeurs : c’est le jeu qui décide de leur sens. Les options sont décrites dans Options de ligne de commande, et elles peuvent aussi être données dans un fichier de réglages (voir Le fichier de réglages).

Aucun des trois ne change en cours d’exécution, alors lisez chacun une fois et gardez sa valeur.

2.8.1. getFValue

value = getFValue()

Extension Hypseus. Renvoie le nombre donné avec --fvalue, ou 0 quand l’option n’a pas été utilisée. C’est un canal d’un seul nombre, de celui qui a lancé Singe vers le jeu, destiné à une valeur qu’un front-end veut faire varier d’un lancement à l’autre — une difficulté, un nombre de crédits de départ, un indice de menu. Le moteur ne fait que la transmettre.

La valeur va de 0 à 100000 et garde trois décimales, comme Hypseus, si bien qu’un jeu qui compare le nombre voit le même que là-bas.

Renvoie : nombre.

Depuis : 3.00 (Hypseus) Voir aussi : ratioGetX, ratioGetY

Exemple
-- Le lanceur passe --fvalue 2 pour la borne réglée en difficile.
local difficulty = getFValue()
if difficulty == 0 then
    difficulty = 1
end

2.8.2. ratioGetX

factor = ratioGetX()

Extension Hypseus. Renvoie le nombre donné avec --xratio, ou 0 quand l’option n’a pas été utilisée. Les jeux au pistolet optique écrits pour Hypseus le lisent et étirent avec lui leurs propres coordonnées de pistolet, pour une borne dont l’écran n’a pas la forme dans laquelle la vidéo a été masterisée — 1.33 fait correspondre une dalle 16:9 à une vidéo 4:3. Singe ne l’applique à rien ; c’est le jeu qui fait le calcul, exactement comme dans Hypseus, et c’est pourquoi chaque jeu qui le lit traite 0 et tout ce qui est inférieur à 1 comme 1.

La valeur va de 0 à 100 et garde deux décimales, comme Hypseus.

Renvoie : nombre.

Depuis : 3.00 (Hypseus) Voir aussi : ratioGetY, getFValue, mouseGetPosition

Exemple
-- La forme des coordonnées de pistolet que veut cette borne.
local ratioX = ratioGetX()
if ratioX <= 1 then
    ratioX = 1
end
local offsetX = (ratioX - 1) * (overlayGetWidth() / 2)

2.8.3. ratioGetY

factor = ratioGetY()

Extension Hypseus. La moitié verticale de la paire : le nombre donné avec --yratio, ou 0 quand l’option n’a pas été utilisée. Voir ratioGetX.

Renvoie : nombre.

Depuis : 3.00 (Hypseus) Voir aussi : ratioGetX, getFValue

Exemple
local ratioY = ratioGetY()
if ratioY <= 1 then
    ratioY = 1
end

2.9. Manette

Singe prend en charge jusqu’à quatre manettes, d’indices 0 à 3, ouvertes automatiquement au démarrage et chaque fois qu’une manette est branchée ou débranchée ; il n’y a pas de controllerLoad. Les axes analogiques sont signalés par onControllerMoved (voir Callbacks du moteur) et interrogés avec controllerGetAxis, dans la plage brute de SDL, de -32768 à 32767. Les boutons numériques, et chaque direction de chaque axe, sont des contacts comme les touches : ils parviennent à onInputPressed et onInputReleased quand controls.cfg affecte un code des tables GAMEPAD_0 à GAMEPAD_3 (par exemple INPUT_ACTION_1 = { GAMEPAD_0.BUTTON_A }), et controllerGetButton interroge l’état réel d’un bouton. SINGE_DEAD_ZONE, tiré de l’entrée DEAD_ZONE de controls.cfg, est le seuil qu’utilise le moteur lui-même avant qu’une direction d’axe compte comme un contact pressé ; traitez les mouvements d’axe en dessous comme du bruit. Chaque axe peut recevoir son propre seuil avec DEAD_ZONES, et les gâchettes analogiques un seuil à elles avec TRIGGER_THRESHOLD (relu sous le nom SINGE_TRIGGER_THRESHOLD) ; voir Zones mortes et gâchettes. Un périphérique que SDL ne reconnaît pas comme manette est tout de même ouvert comme tel, grâce à une affectation que Singe écrit pour lui, si bien qu’un encodeur d’arcade ou un joystick de vol apparaît dans ces emplacements comme n’importe quelle manette — voir Tout périphérique est une manette.

2.9.1. controllerDoRumble

controllerDoRumble(strength, duration)
controllerDoRumble(controller, strength, duration)

Extension Hypseus. Fait vibrer une manette avec ses deux moteurs, à l’une de quatre intensités pendant l’une de quatre durées. La forme à deux arguments s’adresse à la manette 0. Un emplacement sans manette ne fait rien (Hypseus s’interrompt dans ce cas, si bien que ses jeux se protègent avec controllerIsValid) ; une intensité ou une durée hors de 1 à 4, ou un indice hors de 0 à 3, met fin au script. Une manette sans vibration ignore l’appel.

Paramètres :

  • controller — indice de la manette, de 0 à 3.

  • strength — de 1 à 4, d’un quart de la puissance à la pleine puissance.

  • duration — de 1 à 4, soit 150, 300, 600 ou 1200 ms.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : controllerIsValid, controllerGetButton

Exemple
-- Une brève secousse à chaque coup, une longue à pleine puissance quand le joueur meurt.
function onHit()
    if controllerIsValid(0) then
        controllerDoRumble(0, 2, 1)
    end
end

function onPlayerDied()
    if controllerIsValid(0) then
        controllerDoRumble(0, 4, 4)
    end
end

2.9.2. controllerGetAxis

value = controllerGetAxis(controller, axis)

Renvoie la position d’un axe analogique telle que le moteur l’a vue en dernier. La valeur est mise à jour à chaque événement d’axe, y compris les mouvements dans la zone morte, et vaut 0 pour une manette non connectée ou un axe qui n’a jamais bougé. Les sticks vont de -32768 à 32767 ; les gâchettes reposent à 0 et atteignent 32767 enfoncées à fond. Un indice hors de 0 à 3, ou un axe hors de 0 à 5, met fin au script.

Paramètres :

  • controller — indice de la manette, de 0 à 3.

  • axis — GAMEPAD_AXIS_LEFT_X (0), GAMEPAD_AXIS_LEFT_Y (1), GAMEPAD_AXIS_RIGHT_X (2), GAMEPAD_AXIS_RIGHT_Y (3), GAMEPAD_AXIS_LEFT_TRIGGER (4) ou GAMEPAD_AXIS_RIGHT_TRIGGER (5).

Renvoie : entier, de -32768 à 32767.

Depuis : 2.00 Voir aussi : controllerGetButton, onControllerMoved

Exemple
-- Diriger avec le stick gauche, accélérer avec la gâchette droite.
function onOverlayUpdate()
    local steer    = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X)
    local throttle = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER)
    if math.abs(steer) > SINGE_DEAD_ZONE then
        heading = heading + (steer / 32768) * turnRate
    end
    speed = speed + (throttle / 32767) * acceleration
    drawHud()
    return OVERLAY_UPDATED
end

2.9.3. controllerGetButton

pressed = controllerGetButton(controller, button)

Indique si un bouton est maintenu à cet instant, lu directement sur la manette plutôt que dans la file d’événements. Servez-vous-en pour les charges en maintenant le bouton et les cas semblables où onInputPressed et onInputReleased sont malcommodes. Un emplacement sans manette renvoie false. Le code du bouton doit venir de la table GAMEPAD_N du même indice de manette ; un code de la table d’une autre manette, ou un code d’axe, tombe hors de la plage des boutons et met fin au script, tout comme un indice hors de 0 à 3.

Paramètres :

  • controller — indice de la manette, de 0 à 3.

  • button — une valeur BUTTON_* ou DPAD_* de la table correspondante, comme GAMEPAD_0.BUTTON_A.value.

Renvoie : booléen.

Depuis : 2.10 Voir aussi : controllerGetAxis, keyboardIsDown, onInputPressed

Exemple
-- Charger tant que A est maintenu, tirer au relâchement.
function onOverlayUpdate()
    if controllerGetButton(0, GAMEPAD_0.BUTTON_A.value) then
        charge = math.min(charge + 1, chargeMax)
    elseif charge > 0 then
        fireShot(charge)
        charge = 0
    end
    drawChargeBar(charge)
    return OVERLAY_UPDATED
end

2.9.4. controllerGetName

name = controllerGetName(controller)

Le nom du périphérique présent dans un emplacement de manette, tel que SDL le donne, ou nil quand l’emplacement est vide. Un périphérique que SDL ne reconnaissait pas donne son propre nom par l’affectation que Singe a écrite pour lui, si bien qu’un écran de service peut lister un encodeur d’arcade par son nom aussi facilement qu’une manette de marque. Un indice hors de 0 à 3 met fin au script.

Paramètres :

  • controller — indice de la manette, de 0 à 3.

Renvoie : chaîne, ou nil.

Depuis : 3.00 Voir aussi : controllerIsValid, mouseGetName

Exemple
-- Un écran de service qui liste ce qui est branché.
for slot = 0, 3 do
    if controllerIsValid(slot) then
        fontPrint(20, 20 + slot * 18, string.format("Pad %d:  %s", slot + 1, controllerGetName(slot)))
    else
        fontPrint(20, 20 + slot * 18, string.format("Pad %d:  not connected", slot + 1))
    end
end

2.9.5. controllerGetPadding

padding = controllerGetPadding()

Extension Hypseus, toujours 0 dans Singe. Hypseus ajoute ce décalage au code d’un contact venu d’une manette, pour qu’un jeu sache quel périphérique a pressé quoi tout en retrouvant le contact en le soustrayant. Singe livre les entrées des manettes comme des contacts affectés ordinaires qui ne portent aucune marque de ce genre, et répond donc 0 : un jeu qui teste la plage décalée prend son autre branche et lit le contact tel quel.

Renvoie : un entier, toujours 0.

Depuis : 3.00 Voir aussi : controllerSetPadding

2.9.6. controllerHowMany

count = controllerHowMany()

Extension Hypseus. Le nombre de manettes ouvertes, sur les quatre emplacements dont dispose Singe. Comme tout joystick que Singe peut ouvrir devient une manette (voir Tout périphérique est une manette), un encodeur d’arcade ou un spinner est compté ici aussi.

Le compte change à mesure que des périphériques sont branchés et débranchés : lisez-le donc quand vous en avez besoin plutôt qu’une seule fois au démarrage. Il ne dit rien des emplacements occupés : un périphérique peut laisser l’emplacement 0 vide alors que l’emplacement 1 est utilisé, et controllerIsValid reste donc le moyen d’interroger un emplacement précis.

Paramètres : aucun.

Renvoie : nombre, de 0 à 4.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : controllerIsValid, controllerGetName, mouseHowMany

Exemple
-- Ne proposer le mode deux joueurs que si le joueur deux a quelque chose à tenir en main.
local twoPlayer = controllerHowMany() >= 2

2.9.7. controllerIsValid

valid = controllerIsValid(controller)

Extension Hypseus. Indique si une manette est ouverte dans l’emplacement à cet instant ; les manettes vont et viennent au gré des branchements à chaud, alors posez la question avant chaque controllerDoRumble. Un indice hors de 0 à 3 met fin au script.

Paramètres :

  • controller — indice de la manette, de 0 à 3.

Renvoie : booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : controllerDoRumble, controllerGetAxis

Exemple
-- N'afficher les indications pour la manette que s'il y a une manette.
function drawAttract()
    if controllerIsValid(0) then
        fontPrint(HINT_X, HINT_Y, "Press A to start")
    else
        fontPrint(HINT_X, HINT_Y, "Press 1 to start")
    end
end

2.9.8. controllerSetPadding

controllerSetPadding(boolean)

Extension Hypseus, acceptée et ignorée. Voir controllerGetPadding pour savoir pourquoi le décalage qu’elle demande n’existe pas dans Singe. L’activer sans marquer les événements serait pire que de la laisser désactivée, car le jeu soustrairait alors un décalage de codes de contact qui n’en ont jamais porté.

Renvoie : rien.

Depuis : 3.00 Voir aussi : controllerGetPadding

2.10. Débogage

Deux appels pour voir ce que fait un script : debugPrint écrit du texte, et lineDraw trace une ligne par-dessus la scène 3D pendant une image (physicsSetDebug et navDraw dessinent par ces mêmes lignes). La sortie affichée va à la console depuis laquelle Singe a été lancé : elle est donc visible pendant le développement et inoffensive dans une borne, où --noconsole la fait taire. Quand Singe tourne avec --trace, chaque appel de l’API, celui-ci compris, est aussi écrit avec ses arguments dans trace.txt, dans le dossier de données, ce qui est le moyen d’en garder un enregistrement permanent. Les options de ligne de commande sont listées dans le chapitre sur le lancement de Singe. Quand l’affichage ne suffit pas, ZeroBrane Studio arrête le jeu sur un point d’arrêt, montre ce que contiennent ses variables et le fait avancer ligne par ligne.

2.10.1. L’en-tête de la trace

Que ce soit --program ou --trace qui l’ait ouvert, trace.txt commence par un bloc qui décrit la machine et l’exécution, entre deux filets pour qu’on puisse le coller tel quel dans un rapport de bogue :

----------------------------------------------------------------
Singe:     v3.00
Command:   ./Singe -w -p -d data --screen 2 MyGame
OS:        Linux 6.8.0-124-generic (x86_64)
CPU:       Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz, 8 cores, 20177 MB
Renderer:  gpu, GPU driver vulkan
Decoder:   hardware vaapi or vdpau where the codec allows, software otherwise
SDL:       built 3.4.16, linked 3.4.16
Settings:  haptic=0 screen=2 volume_vldp=80
Game:      MyGame/MyGame.singe
----------------------------------------------------------------

Renderer est le moteur de rendu effectivement créé et le backend GPU qu’il a choisi, ou une note indiquant qu’il n’y a pas de périphérique GPU et que la 3D n’est pas disponible. Decoder est ce qui sera essayé pour la vidéo sur cette machine ; le décodeur qu’une vidéo donnée a réellement obtenu est tracé à l’ouverture de cette vidéo, quelques lignes plus bas, car un codec peut n’offrir aucune voie matérielle. Settings liste ce qu’a fourni le fichier de réglages, none quand il n’y en avait pas. Chaque jeu d’une file d’attente a son propre fichier et son propre en-tête.

2.10.2. debugPrint

debugPrint(message)

Affiche une ligne sur la console (sortie standard). Rien n’est affiché quand Singe a été lancé avec --noconsole ; avec --trace, l’appel et son message atterrissent aussi dans trace.txt. L’argument doit être une chaîne ou un nombre ; tout le reste met fin au script : enveloppez donc les valeurs dans tostring ou utilisez string.format. Il coûte assez peu pour rester dans le code livré, mais il n’est pas limité en débit, si bien qu’un affichage dans onOverlayUpdate s’exécute à chaque image.

Paramètres :

  • message — le texte à afficher ; un nombre est converti.

Depuis : 1.x Voir aussi : singeGetTicks

Exemple
-- Noter pourquoi le tir a manqué, avec l'image où c'est arrivé.
function resolveShot(x, y)
    local hit = targetAt(x, y)
    if not hit then
        debugPrint(string.format("miss at %d,%d on frame %d", x, y, discGetFrame()))
        soundPlay(missClip)
        return
    end
    score = score + hit.points
end

2.10.3. lineDraw

lineDraw(x0, y0, z0, x1, y1, z1)
lineDraw(x0, y0, z0, x1, y1, z1, r, g, b)

Trace une ligne droite entre deux points de l’espace du monde, par-dessus la scène, pour l’image en cours seulement, en blanc sauf si une couleur est donnée. Appelez-la à chaque image pour garder une ligne à l’écran, comme avec l’overlay. La ligne subit le test de profondeur contre la scène mais n’écrit pas la profondeur : elle se cache donc derrière les murs comme tout le reste et ne masque jamais rien. Rien n’est dessiné tant que la scène est désactivée. Elle sert à voir ce que fait un script (un lancer de rayon, un chemin, une boîte englobante) ; physicsSetDebug et navDraw dessinent par ces mêmes lignes.

Paramètres :

  • x0, y0, z0 — le point de départ, en unités du monde.

  • x1, y1, z1 — le point d’arrivée, en unités du monde.

  • r, g, b — la couleur de la ligne, de 0 à 255 par canal, ramenée dans la plage ; blanc si elle est omise.

Depuis : 3.00. Voir aussi : physicsSetDebug, navDraw, physicsRaycast

Exemple
-- Montrer où vise la tourelle et si le tir porterait.
function onOverlayUpdate()
    local tx, ty, tz = nodeGetWorldPosition(turret)
    local hit, hx, hy, hz = physicsRaycast(tx, ty, tz, aimX, aimY, aimZ, 40)
    if hit then
        lineDraw(tx, ty, tz, hx, hy, hz, 255, 255, 0)
    else
        lineDraw(tx, ty, tz, tx + aimX * 40, ty + aimY * 40, tz + aimZ * 40, 120, 120, 120)
    end
    return OVERLAY_UPDATED
end

2.11. Disque

Le disque est la vidéo laserdisc principale, celle que Singe a été conçu à l’origine pour émuler. Un jeu a au plus un disque, ouvert au démarrage à partir de la VIDEO nommée dans games.dat ou de --disc / --framefile sur la ligne de commande ; un jeu qui n’en nomme aucune tourne sans disque (voir Jeux sans disque). Toutes les fonctions disc* agissent sur ce disque unique et implicite et ne prennent pas de handle. Les numéros d’image sont des positions comptées à partir de zéro dans le fichier vidéo (ou dans le framefile combiné) et servent de référence temporelle à chaque décision d’embranchement d’un jeu laserdisc. Sans disque, les fonctions d’interrogation renvoient 0, discGetState signale DISC_EJECTED, et les fonctions de transport écrivent une trace et ne font rien. Les clips supplémentaires superposés au disque sont l’affaire de la famille Vidéo.

2.11.1. discAudio

discAudio(channel, enabled)

Active ou coupe l’un des canaux de la bande-son du disque. Le canal est réglé sur le volume laserdisc configuré (--volume_vldp, 100 par défaut) quand enabled vaut true, et sur 0 quand il vaut false ; l’autre canal reste tel quel. Beaucoup de titres d’origine portaient une narration ou une piste de données sur un seul canal, et c’est cet appel qui la fait taire. Un canal autre que 1 ou 2 met fin au script. Sans disque, l’appel ne fait rien.

Paramètres :

  • channel — 1 pour le canal gauche, 2 pour le droit.

  • enabled — booléen. true remet le canal au volume laserdisc configuré, false le rend muet.

Depuis : 1.x Voir aussi : discSetAudioTrack, discGetAudioTracks, videoSetVolume

Exemple
-- Le canal droit de ce disque porte la piste de données de la borne d'arcade.
function startGame()
    discAudio(1, true)
    discAudio(2, false)
    discSkipToFrame(SCENE_FIRST_FRAME)
end

2.11.2. discAudioSuffix

opened = discAudioSuffix(suffix)

Extension Hypseus. Fait passer le disque à un fichier audio séparé placé à côté de sa vidéo : <base><suffix>.ogg, où la base est le nom du fichier vidéo sans son extension ; ainsi movie.m2v avec "-es" joue movie-es.ogg. Le fichier est ouvert à l’image en cours et la lecture se réaligne, comme avec discSetAudioTrack, en gardant le volume, l’état de lecture et l’indice de piste quand le nouveau fichier a autant de pistes. Avec un framefile, tous les segments changent. Un suffixe vide rétablit l’audio par défaut : le .ogg à côté d’un .m2v, ou l’audio contenu dans tout autre conteneur. Renvoie true quand le fichier s’est ouvert ; quand il manque, l’audio précédent continue de jouer, rien n’est mémorisé et false est renvoyé (Hypseus laisse alors le silence). Le suffixe est oublié quand le script est rechargé. Sans disque, l’appel renvoie false. Servez-vous-en pour un menu de langues dont les pistes sont livrées en fichiers séparés ; les pistes contenues dans un même fichier sont l’affaire de discSetAudioTrack.

Paramètres :

  • suffix — chaîne ajoutée au nom de base de la vidéo, comme "-es" ; "" pour l’audio par défaut.

Renvoie : booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : discSetAudioTrack, discGetAudioTracks, discAudio

Exemple
-- Les fichiers de langue sont livrés sous les noms movie.ogg, movie-es.ogg et movie-fr.ogg.
languages = { { "English", "" }, { "Spanish", "-es" }, { "French", "-fr" } }

function applyLanguage(index)
    if not discAudioSuffix(languages[index][2]) then
        discAudioSuffix("")
        index = 1
    end
    settings.language = index
end

2.11.3. discChangeSpeed

discChangeSpeed(...)

Ne fait rien. Les vrais lecteurs de laserdisc pouvaient tourner à une autre vitesse que 1x ; le lecteur logiciel de Singe ne le peut pas, donc l’appel accepte n’importe quels arguments, écrit une ligne de trace et rend la main. Il est conservé pour que les scripts antérieurs à 2.00 se chargent sans modification.

Remarques :

Non implémenté. Conservé uniquement pour la rétrocompatibilité. Il n’y a pas de remplacement ; la vitesse de lecture est fixée à la fréquence d’images du fichier vidéo.

Depuis : 1.x Voir aussi : discPlay, discSkipToFrame

Exemple
-- D'anciens scripts encadraient parfois un ralenti par des changements de vitesse.
-- Ces appels sont inoffensifs aujourd'hui, mais le ralenti passe à vitesse normale.
discChangeSpeed(0.5)
discSkipToFrame(REPLAY_FIRST_FRAME)
discChangeSpeed(1)

2.11.4. discGetAudioTrack

track = discGetAudioTrack()

Renvoie l’indice, compté à partir de zéro, de la piste audio que joue actuellement le disque. Au démarrage, le moteur choisit la piste désignée par --audio ou par l’entrée AUDIO_TRACK de games.dat (0 par défaut) quand le disque a autant de pistes. Renvoie 0 sans disque.

Renvoie : indice de piste entier.

Depuis : 2.10 Voir aussi : discGetAudioTracks, discSetAudioTrack, discGetLanguage

Exemple
-- Passer au doublage suivant chaque fois que le joueur appuie sur la touche de langue.
function onInputPressed(what)
    if what == SWITCH_BUTTON2 then
        local next = (discGetAudioTrack() + 1) % discGetAudioTracks()
        discSetAudioTrack(next)
        languageLabel = discGetLanguageDescription(discGetLanguage(next))
    end
end

2.11.5. discGetAudioTracks

count = discGetAudioTracks()

Renvoie le nombre de flux audio que contient le fichier vidéo du disque. Plusieurs flux sont en général des doublages dans d’autres langues. Une vidéo muette renvoie 0, tout comme un jeu sans disque : protégez donc les boucles et les calculs modulo contre le zéro.

Renvoie : nombre entier, 0 ou plus.

Depuis : 2.10 Voir aussi : discGetAudioTrack, discGetLanguage, discSetAudioTrack

Exemple
-- Construire un menu de choix de langue à partir des pistes audio du disque.
languages = {}
for track = 0, discGetAudioTracks() - 1 do
    local code = discGetLanguage(track)
    local name = discGetLanguageDescription(code)
    table.insert(languages, { track = track, label = name })
end

2.11.6. discGetSubtitleLanguage

language = discGetSubtitleLanguage(track)

La langue indiquée sur une piste de sous-titres contenue dans le conteneur même du disque, sous la forme du code ISO 639 que porte le fichier (eng, fra, spa). Une piste que le fichier n’étiquette pas renvoie une chaîne vide, ce qui n’est pas une erreur — bien des fichiers n’étiquettent rien.

Paramètres :

  • track — nombre ; de 0 à discGetSubtitleTracks() - 1.

Renvoie : une chaîne.

Depuis : 3.00. Voir aussi : discGetSubtitleTracks, srtLoadTrack

2.11.7. discGetSubtitleTracks

count = discGetSubtitleTracks()

Le nombre de pistes de sous-titres que contient le conteneur même du disque. 0 sans disque, et 0 pour un disque dont les sous-titres sont livrés dans un .srt séparé — c’est la disposition habituelle, et ce à quoi sert srtLoad.

Les pistes qui contiennent des images plutôt que des mots (celles des DVD et des Blu-ray, VobSub et PGS) sont comptées ici pour que la numérotation corresponde à ce que montre n’importe quel autre lecteur, mais srtLoadTrack ne peut pas les lire : il n’y a rien à lire, seulement des bitmaps des mots.

Paramètres :

  • Aucun.

Renvoie : un nombre.

Depuis : 3.00. Voir aussi : srtLoadTrack, discGetSubtitleLanguage

Exemple
-- Proposer toutes les langues que porte le disque lui-même.
for track = 0, discGetSubtitleTracks() - 1 do
    languages[#languages + 1] = { track = track, code = discGetSubtitleLanguage(track) }
end

2.11.8. discGetFrame

frame = discGetFrame()

Renvoie l’image que le disque montre en ce moment. Avec un framefile, le numéro est la position dans la séquence combinée, si bien que les limites des segments sont invisibles pour le script. Renvoie 0 tant que le disque est arrêté, et sans disque. Interrogez-la depuis onOverlayUpdate pour réagir quand la vidéo atteint un point de décision.

Renvoie : numéro d’image entier.

Depuis : 1.x Voir aussi : discSearch, discSkipToFrame, discGetState

Exemple
-- Boucler la séquence d'attraction et afficher une invite pendant la fenêtre où il faut se baisser.
function onOverlayUpdate()
    local frame = discGetFrame()
    if frame >= ATTRACT_LAST_FRAME then
        discSkipToFrame(ATTRACT_FIRST_FRAME)
    elseif frame >= DUCK_FIRST_FRAME and frame <= DUCK_LAST_FRAME then
        drawPrompt("DUCK")
    end
    return OVERLAY_UPDATED
end

2.11.9. discGetFrameCount

frames = discGetFrameCount()

Le nombre d’images du disque, soit un de plus que la plus haute image que discSearch trouvera. Un framefile répond pour tout le disque plutôt que pour le segment en cours de lecture : le compte ne change donc pas à mesure que les segments vont et viennent. Sans disque, il répond 0.

Renvoie : nombre d’images entier, 0 sans disque.

Depuis : 3.00. Voir aussi : discGetFrame, discSearch

Exemple
-- Sauter au milieu du disque, où qu'il soit.
discSearch(math.floor(discGetFrameCount() / 2))

2.11.10. discGetHeight

height = discGetHeight()

Renvoie la hauteur de la vidéo du disque, en pixels. Sans disque, elle renvoie la hauteur du canevas (CANVAS_Y dans games.dat ou --canvas, 480 par défaut) : c’est donc toujours la taille du fond sur lequel l’overlay est étiré. Associez-la à discGetWidth pour donner à l’overlay la même résolution que la vidéo.

Renvoie : hauteur entière en pixels.

Depuis : 2.00 Voir aussi : discGetWidth, overlaySetResolution, vldpGetHeight

Exemple
-- Dessiner à la résolution native du disque pour que les tests de pixels et le dessin partagent une même grille.
overlaySetResolution(discGetWidth(), discGetHeight())
crosshairLimitX = discGetWidth() - 1
crosshairLimitY = discGetHeight() - 1

2.11.11. discGetLanguage

code = discGetLanguage(track)

Renvoie l’étiquette de langue stockée dans le fichier vidéo pour l’une des pistes audio du disque. L’étiquette est un code ISO 639 de trois lettres comme "eng" ou "jpn". Les pistes sans étiquette de trois lettres renvoient "unk", comme toutes les pistes quand il n’y a pas de disque. Avec un disque, une piste hors de 0 à discGetAudioTracks() - 1 met fin au script.

Renvoie : code de langue sous forme de chaîne.

Exemple
-- Préférer le doublage japonais quand le disque en porte un.
for track = 0, discGetAudioTracks() - 1 do
    if discGetLanguage(track) == "jpn" then
        discSetAudioTrack(track)
        break
    end
end

2.11.12. discGetState

state = discGetState()

Renvoie l’état de transport du disque sous la forme de l’une des constantes DISC_*. Un jeu sans disque signale DISC_EJECTED ; après discStop, le disque signale DISC_STOPPED jusqu’au prochain discPlay, discSearch ou discSkipToFrame ; sinon l’état est DISC_PLAYING tant que la vidéo avance, et DISC_PAUSED quand elle n’avance pas. Il n’y a pas d’état de recherche distinct ; un disque en cours de saut signale DISC_PAUSED ou DISC_PLAYING selon ce qui a été demandé.

Renvoie : l’une des constantes suivantes, définies par le moteur et accessibles à tous les scripts.

Constante Valeur Signification

DISC_STOPPED

2

Arrêté (discStop a été appelé)

DISC_PLAYING

3

En lecture

DISC_PAUSED

4

En pause

DISC_EJECTED

5

Le jeu n’a pas de disque (voir Jeux sans disque)

Depuis : 1.x (RDG) Voir aussi : discPlay, discPause, discStop

Exemple
-- La touche pause ne doit pas relancer un arrêt sur image demandé par le script de l'histoire.
function onInputPressed(what)
    if what == SWITCH_PAUSE then
        if discGetState() == DISC_PAUSED and not storyPaused then
            discPlay()
        elseif discGetState() == DISC_PLAYING then
            discPause()
        end
    end
end

2.11.13. discGetWidth

width = discGetWidth()

Renvoie la largeur de la vidéo du disque, en pixels. Sans disque, elle renvoie la largeur du canevas (CANVAS_X dans games.dat ou --canvas, 720 par défaut). Avec discGetHeight, c’est la taille sur laquelle l’overlay est mis à l’échelle, et c’est pourquoi le menu fourni passe les deux à overlaySetResolution.

Renvoie : largeur entière en pixels.

Depuis : 2.00 Voir aussi : discGetHeight, overlaySetResolution, vldpGetWidth

Exemple
-- Centrer un sprite de titre, quelle que soit la largeur du disque.
overlaySetResolution(discGetWidth(), discGetHeight())
titleSprite = spriteLoad("graphics/title.png")
titleX = (discGetWidth() - spriteGetWidth(titleSprite)) / 2

2.11.14. discPause

discPause()

Met la lecture en pause sur l’image en cours, qui reste à l’écran. L’audio du disque se met en pause avec elle. L’appel est ignoré tant que le disque est arrêté et ne fait rien sans disque. Reprenez avec discPlay.

Depuis : 1.x Voir aussi : discPlay, discStop, singeSetPauseFlag

Exemple
-- Garder la dernière image de la scène pendant que le joueur choisit une porte.
function onOverlayUpdate()
    if discGetFrame() >= SCENE_LAST_FRAME and not choosing then
        discPause()
        choosing = true
    end
    return OVERLAY_UPDATED
end

2.11.15. discPauseAtFrame

discPauseAtFrame(frame)

Saute à frame, l’affiche et se met en pause. C’est la même fonction que discSearch sous un second nom ; les deux sont interchangeables en tout point, y compris pour les règles de bornage décrites là-bas. Préférez discSearch dans le nouveau code et ne gardez discPauseAtFrame que pour porter d’anciens scripts.

Remarques :

Alias hérité. Utilisez discSearch dans le nouveau code.

Depuis : 1.18 Voir aussi : discSearch, discPlay

Exemple
-- Code 1.x porté : rester sur la première image de la scène jusqu'à ce que le joueur soit prêt.
function onInputPressed(what)
    if what == SWITCH_START1 then
        discPauseAtFrame(SCENE_FIRST_FRAME)
        waitingForPlayer = true
    end
end

2.11.16. discPlay

discPlay()

Lance ou reprend la lecture à partir de l’image en cours et efface l’état d’arrêt posé par discStop. L’audio reprend avec la vidéo, et l’horloge de lecture repart de l’image en cours pour qu’une longue pause ne provoque pas de saut. Sans disque, ne fait rien d’autre qu’effacer l’indicateur d’arrêt.

Depuis : 1.x Voir aussi : discPause, discStop, discSkipToFrame

Exemple
-- Démarrage classique du mode attraction : caler la première image, puis lancer.
function attractBegin()
    discSearch(ATTRACT_FIRST_FRAME)
    overlayClear()
    discPlay()
    attractRunning = true
end

2.11.17. discSearch

discSearch(frame)

Fait sauter le disque à frame, affiche cette image et s’y met en pause, en effaçant l’état d’arrêt si le disque était arrêté. Le disque garde l’image jusqu’à discPlay, discSkipToFrame ou un autre appel de transport. Une image négative est ramenée à la première image et une image au-delà de la fin à la dernière ; avec un framefile, le segment qui contient l’image est sélectionné et la position est bornée à l’intérieur. Ne fait rien sans disque.

Paramètres :

  • frame — numéro de l’image visée, compté à partir de zéro.

Depuis : 1.x Voir aussi : discSkipToFrame, discPlay, discGetFrame

Exemple
-- Le joueur a choisi le couloir de gauche : caler la scène et attendre le départ.
function goLeft()
    discSearch(CORRIDOR_LEFT_FIRST_FRAME)
    soundPlay(SOUND_DOOR)
    waitingForPlayer = true
end

2.11.18. discSearchBlanking

discSearchBlanking(...)

Ne fait rien. Sur le matériel laserdisc, cet appel choisissait si l’écran s’éteignait pendant que le lecteur cherchait une image ; le lecteur logiciel de Singe saute sans éteindre l’écran, donc l’appel accepte n’importe quels arguments, écrit une ligne de trace et rend la main.

Remarques :

Non implémenté. Conservé uniquement pour la rétrocompatibilité. Il n’y a pas de remplacement.

Depuis : 1.x Voir aussi : discSearch, discSkipBlanking

Exemple
-- Les scripts antérieurs à 2.00 réglaient souvent les modes d'extinction une fois au démarrage. Sans danger.
discSearchBlanking(false)
discSkipBlanking(false)
discSearch(TITLE_FRAME)

2.11.19. discSetAudioTrack

discSetAudioTrack(track)

Fait passer le disque à une autre piste audio. L’audio en attente de l’ancienne piste est abandonné et la lecture se réaligne, si bien que le changement s’entend presque aussitôt. Avec un disque, une piste hors de 0 à discGetAudioTracks() - 1 met fin au script ; sans disque, l’appel ne fait rien. Servez-vous-en pour réaliser un menu de langues ou respecter une préférence enregistrée d’une session à l’autre.

Paramètres :

  • track — indice de piste audio, compté à partir de zéro.

Depuis : 2.10 Voir aussi : discGetAudioTrack, discGetAudioTracks, discGetLanguage

Exemple
-- Appliquer la langue que le joueur a choisie dans l'écran des options.
function applyLanguage(choice)
    if choice >= 0 and choice < discGetAudioTracks() then
        discSetAudioTrack(choice)
        settings.language = choice
        saveSettings()
    end
end

2.11.20. discSetFPS

discSetFPS(...)

Ne fait rien. La fréquence d’images vient du fichier vidéo, donc l’appel accepte n’importe quels arguments, écrit une ligne de trace et rend la main. Rien dans le Framework.singe fourni ne l’appelle ; seuls les scripts antérieurs à 2.00 le font.

Remarques :

Non implémenté. Conservé uniquement pour la rétrocompatibilité. La fréquence d’images est lue dans le fichier vidéo et ne peut pas être réglée depuis un script.

Depuis : 1.x Voir aussi : discGetFrame, discSkipToFrame

Exemple
-- Un script 1.x porté. L'appel est ignoré ; le nombre d'images par seconde est une propriété du fichier.
discSetFPS(29.97)
discSearch(TITLE_FRAME)
discPlay()

2.11.21. discSkipBackward

discSkipBackward(frames)

Saute de frames images en arrière à partir de l’image en cours sans changer l’état de lecture ou de pause : un disque en lecture continue de jouer depuis la nouvelle position, un disque en pause y reste en pause. L’appel est ignoré tant que le disque est arrêté, et sans disque. L’écart n’est pas vérifié ; une valeur négative fait sauter en avant, et un écart plus grand que l’image en cours s’arrête à l’image 0. Avec un framefile, l’écart s’applique au numéro d’image que renvoie discGetFrame, si bien qu’un saut peut passer dans un segment antérieur.

Paramètres :

  • frames — nombre d’images à retrancher de l’image en cours.

Depuis : 1.x Voir aussi : discSkipForward, discStepBackward, discGetFrame

Exemple
-- Rejouer la dernière seconde (30 images) quand le joueur rate une invite.
function missedPrompt()
    lives = lives - 1
    discSkipBackward(30)
    promptShown = false
end

2.11.22. discSkipBlanking

discSkipBlanking(...)

Ne fait rien. Il choisissait autrefois si l’écran s’éteignait pendant un saut sur le matériel laserdisc ; le lecteur logiciel de Singe n’éteint jamais l’écran, donc l’appel accepte n’importe quels arguments, écrit une ligne de trace et rend la main.

Remarques :

Non implémenté. Conservé uniquement pour la rétrocompatibilité. Il n’y a pas de remplacement.

Depuis : 1.x Voir aussi : discSearchBlanking, discSkipToFrame

Exemple
-- Les scripts antérieurs à 2.00 réglaient souvent les modes d'extinction une fois au démarrage. Sans danger.
discSearchBlanking(false)
discSkipBlanking(false)
discSearch(TITLE_FRAME)

2.11.23. discSkipForward

discSkipForward(frames)

Saute de frames images en avant à partir de l’image en cours sans changer l’état de lecture ou de pause. Pendant de discSkipBackward : ignoré à l’arrêt et sans disque, l’écart n’est pas vérifié, et une cible au-delà de la dernière image s’arrête à la dernière image. Avec un framefile, l’écart s’applique au numéro d’image que renvoie discGetFrame, si bien qu’un saut peut passer dans un segment ultérieur.

Paramètres :

  • frames — nombre d’images à ajouter à l’image en cours.

Depuis : 1.x Voir aussi : discSkipBackward, discStepForward, discGetFrame

Exemple
-- Laisser un joueur qui revient sauter l'introduction de deux secondes de la scène.
function onInputPressed(what)
    if what == SWITCH_BUTTON1 and inSceneIntro then
        discSkipForward(60)
        inSceneIntro = false
    end
end

2.11.24. discSkipToFrame

discSkipToFrame(frame)

Saute à frame et lance la lecture à partir de là, quel que soit l’état du disque, en effaçant l’état d’arrêt si nécessaire. À comparer avec discSearch, qui saute et se met en pause. Une image avant le début ou au-delà de la fin est ramenée à la première ou à la dernière image ; avec un framefile, le segment qui contient l’image est sélectionné et la position est bornée à l’intérieur. Sans disque, ne fait rien d’autre qu’effacer l’indicateur d’arrêt.

Paramètres :

  • frame — numéro de l’image visée, compté à partir de zéro.

Depuis : 1.x Voir aussi : discSearch, discPlay, discGetFrame

Exemple
-- Sauter l'introduction quand on rejoue.
function startGame()
    if hasPlayedBefore then
        discSkipToFrame(GAMEPLAY_FIRST_FRAME)
    else
        discSkipToFrame(INTRO_FIRST_FRAME)
    end
end

2.11.25. discStepBackward

discStepBackward()

Recule le disque d’exactement une image et s’y met en pause, quel que soit l’état de lecture précédent. Reculer depuis l’image 0 reste sur l’image 0. Ignoré tant que le disque est arrêté, comme discSkipBackward. Destiné au débogage à l’image près et aux écrans de service. Ne fait rien sans disque.

Depuis : 1.x Voir aussi : discStepForward, discSkipBackward, discGetFrame

Exemple
-- Écran de service : gauche et droite déplacent le disque d'une image à la fois.
function onInputPressed(what)
    if what == SWITCH_LEFT then
        discStepBackward()
    elseif what == SWITCH_RIGHT then
        discStepForward()
    end
end

2.11.26. discStepForward

discStepForward()

Avance le disque d’exactement une image et s’y met en pause, quel que soit l’état de lecture précédent. Avancer depuis la dernière image reste sur la dernière image. Comme discStepBackward, il est ignoré tant que le disque est arrêté. Ne fait rien sans disque.

Depuis : 1.x Voir aussi : discStepBackward, discSkipForward, discGetFrame

Exemple
-- Chercheur d'images : parcourir une scène image par image et afficher le numéro d'image.
function onOverlayUpdate()
    overlayClear()
    overlayPrint(8, 8, "Frame " .. discGetFrame())
    if stepping then
        discStepForward()
    end
    return OVERLAY_UPDATED
end

2.11.27. discStop

discStop()

Arrête le disque. La lecture se met en pause, la vidéo est remplacée par l’écran bleu classique, discGetState signale DISC_STOPPED et discGetFrame renvoie 0 jusqu’à ce que le disque soit relancé. À l’arrêt, discPause, discSkipForward, discSkipBackward, discStepForward et discStepBackward sont ignorés. N’importe lequel de discPlay, discSearch ou discSkipToFrame efface l’état d’arrêt. Un second discStop est ignoré.

Depuis : 1.x Voir aussi : discPlay, discPause, discGetState

Exemple
-- Fin de partie : passer à l'écran bleu derrière le tableau des scores.
function gameOver()
    discStop()
    soundPlay(SOUND_GAME_OVER)
    showScores = true
end

2.12. Émetteur

Les émetteurs font naître, déplacent et dessinent des particules ; voir Particules. Les handles sont des entiers. Un émetteur 2D vit dans les coordonnées de l’overlay, Y vers le bas, et se dessine quand emitterDraw le demande depuis onOverlayUpdate ; un émetteur 3D est posé sur un nœud, vit en unités du monde et se dessine lui-même dans la scène. Les appels de recette peuvent se faire dans n’importe quel ordre, avant ou après le démarrage de l’émetteur, et prennent effet sur les prochaines particules qui naissent (quelques-uns, signalés plus bas, agissent aussi sur les particules vivantes). Tout ce qui est donné sous forme de minimum et de maximum est tiré au hasard entre les deux pour chaque particule. Les particules avancent avec l’horloge, d’un dixième de seconde par image au plus, et s’arrêtent tant que le jeu est en pause.

2.12.1. emitterNew

emitter = emitterNew()
emitter = emitterNew(node)

Crée un émetteur. Sans argument, c’est un émetteur 2D placé à la position (0, 0) de l’overlay, que l’on déplace avec emitterSetPosition ; avec un nœud, c’est un émetteur 3D dont les particules naissent à la position du nœud dans le monde, et il a besoin de la scène 3D : sur une machine qui n’en a pas, l’appel met fin au script (les émetteurs 2D fonctionnent partout). Un nouvel émetteur n’émet pas en continu ; appelez emitterStart ou emitterBurst. Supprimer le nœud supprime ses émetteurs. Valeurs par défaut : 50 particules par seconde, vivant une à deux secondes, ouverture de 30 degrés, blanc s’estompant jusqu’au transparent, mélange normal, ni gravité, ni freinage, ni rotation, ni rayon, ni texture, ni traînée, ni collision, une réserve de 1000 ; un émetteur 2D les lance vers le haut de l’écran à 50 à 100 unités de l’overlay par seconde en les réduisant de 16 à 4, un émetteur 3D vers le haut de l’axe Y à 1 à 2 unités du monde par seconde en les réduisant de 0,2 à 0,05.

Renvoie : le handle de l’émetteur.

Depuis : 3.00. Voir aussi : emitterDelete, emitterStart, emitterBurst, emitterDraw

Exemple
-- Les gaz d'échappement du nœud moteur du vaisseau ; la recette est réglée avant le début du flux.
exhaust = emitterNew(nodeFind("Engine", ship))
emitterSetBlend(exhaust, PARTICLE_ADD)
emitterSetRate(exhaust, 120)
emitterSetLife(exhaust, 0.3, 0.6)
emitterSetDirection(exhaust, 0, 0, 1)
emitterSetSpeed(exhaust, 3, 5)
emitterSetSize(exhaust, 0.3, 0.05)
emitterSetColor(exhaust, 120, 180, 255, 255, 30, 60, 255, 0)
emitterStart(exhaust)

2.12.2. emitterDelete

emitterDelete(emitter)

Supprime d’un coup l’émetteur, ses particules vivantes et sa copie de la texture ; rien ne s’estompe. Utilisez plutôt emitterStop pour laisser les dernières particules finir. Un émetteur 3D est aussi supprimé de lui-même quand son nœud est supprimé. Un handle qui n’est pas celui d’un émetteur vivant met fin au script : effacez donc la variable ensuite.

Depuis : 3.00. Voir aussi : emitterNew, emitterStop, emitterIsActive

Exemple
-- L'explosion est finie : libérer son émetteur une fois la dernière étincelle éteinte.
function onOverlayUpdate()
    if explosion ~= nil and not emitterIsActive(explosion) then
        emitterDelete(explosion)
        explosion = nil
    end
    return OVERLAY_NOT_UPDATED
end

2.12.3. emitterSetTexture

emitterSetTexture(emitter, sprite)
emitterSetTexture(emitter)

L’image que porte chaque particule : un sprite chargé, ou aucune (un seul argument, ou nil) pour le disque flou intégré. L’émetteur garde sa propre copie des pixels du sprite, toutes les images d’un sprite animé comprises, si bien que le sprite peut être déchargé ensuite. Régler la texture ramène la plage d’images à l’image 0 et place chaque particule vivante sur l’image 0 : appelez donc emitterSetFrames après, pas avant. Le mélange et la teinte s’appliquent à l’image comme au disque.

Depuis : 3.00. Voir aussi : emitterSetFrames, spriteLoad, emitterSetBlend

Exemple
-- Neige : une planche de six formes de flocons, une tirée au hasard par particule.
flakes = spriteLoadFrames(6, DIR .. "Sprites/flakes.png")
snow   = emitterNew()
emitterSetTexture(snow, flakes)
emitterSetFrames(snow, 0, 5)
emitterSetDirection(snow, 0, 1)
emitterSetSpeed(snow, 20, 40)
emitterSetLife(snow, 6, 9)
emitterSetSize(snow, 6, 6, 0.4)
emitterStart(snow)

2.12.4. emitterSetFrames

emitterSetFrames(emitter, first, last)

Avec un sprite animé comme texture, chaque nouvelle particule prend une image au hasard de first à last et la garde toute sa vie ; les images se comptent à partir de 0. Les valeurs sont bornées aux images que possède la texture, et last est relevé à first quand il est plus petit. Par défaut : l’image 0 seule, qui est aussi ce à quoi emitterSetTexture revient. Avec le disque intégré ou un sprite d’une seule image, la plage n’a aucun effet.

Depuis : 3.00. Voir aussi : emitterSetTexture, spriteLoad

Exemple
-- La planche de bouffées a quatre bouffées floues, puis quatre éclats de débris plus nets.
emitterSetTexture(smoke, puffSheet)
emitterSetFrames(smoke, 0, 3)
emitterSetTexture(debris, puffSheet)
emitterSetFrames(debris, 4, 7)

2.12.5. emitterSetBlend

emitterSetBlend(emitter, mode)

La façon dont les particules se combinent avec ce qui est derrière elles. PARTICLE_ALPHA (par défaut) mélange normalement, pour la fumée, la poussière, la pluie et les débris ; PARTICLE_ADD ajoute de la lumière, pour le feu, les étincelles, les lueurs et la magie, et n’assombrit jamais. Prend effet aussitôt sur les particules vivantes. Toute autre valeur que ces deux constantes met fin au script.

Depuis : 3.00. Voir aussi : emitterSetColor, emitterSetTexture

Exemple
-- Les étincelles brillent ; la fumée au-dessus d'elles, non.
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetColor(sparks, 255, 220, 120, 255, 255, 80, 20, 0)
emitterSetBlend(smoke, PARTICLE_ALPHA)
emitterSetColor(smoke, 160, 160, 170, 120, 120, 120, 130, 0)

2.12.6. emitterSetLayer

emitterSetLayer(emitter, layer)

2D seulement : où emitterDraw place les particules. PARTICLE_OVER (par défaut) dessine au-dessus de tout ce qui est sur l’overlay ; PARTICLE_UNDER dessine sous l’overlay et au-dessus de la vidéo et de la scène 3D, pour de la fumée derrière le score. Sur un émetteur 3D, le réglage est accepté et ignoré. Toute autre valeur que ces deux constantes met fin au script.

Depuis : 3.00. Voir aussi : emitterDraw, emitterSetPosition

Exemple
-- La pluie tombe derrière le HUD, les étincelles d'impact devant.
rain = emitterNew()
emitterSetLayer(rain, PARTICLE_UNDER)
hits = emitterNew()
emitterSetLayer(hits, PARTICLE_OVER)

function onOverlayUpdate()
    overlayClear()
    emitterDraw(rain)
    drawHud()
    emitterDraw(hits)
    return OVERLAY_UPDATED
end

2.12.7. emitterSetRate

emitterSetRate(emitter, perSecond)

Le nombre de particules par seconde que crée un émetteur démarré ; 50 par défaut, les valeurs négatives deviennent 0. Les fractions s’accumulent, si bien que 0.5 en crée une toutes les deux secondes. Changez-le pendant l’émission pour moduler une flamme ou un propulseur. Une réserve pleine (emitterSetMax) n’en crée plus tant que certaines ne sont pas mortes, quel que soit le débit.

Depuis : 3.00. Voir aussi : emitterStart, emitterBurst, emitterSetMax

Exemple
-- Le panache du propulseur suit la manette des gaz.
function onControllerMoved(axis, value, which)
    if axis == GAMEPAD_AXIS_RIGHT_TRIGGER then
        throttle = value / 32767
        emitterSetRate(plume, 30 + 300 * throttle)
    end
end

2.12.8. emitterSetLife

emitterSetLife(emitter, minSeconds, maxSeconds)

La durée de vie de chaque nouvelle particule, tirée au hasard entre les deux ; de 1 à 2 par défaut. Sa taille et sa couleur vont de leur début à leur fin pendant ce temps, si bien que la durée de vie donne le rythme de chaque fondu. Le minimum est maintenu à 0.001 ou plus et le maximum est relevé au minimum quand il est plus petit. Les particules vivantes gardent la durée de vie avec laquelle elles sont nées.

Depuis : 3.00. Voir aussi : emitterSetSize, emitterSetColor, emitterSetRate

Exemple
-- Éclair de bouche : une salve qui disparaît en un dixième de seconde.
flash = emitterNew(muzzle)
emitterSetBlend(flash, PARTICLE_ADD)
emitterSetLife(flash, 0.05, 0.1)
emitterSetSpeed(flash, 2, 6)
emitterSetSize(flash, 0.15, 0.4)

function onFire()
    emitterBurst(flash, 12)
end

2.12.9. emitterSetSoftness

emitterSetSoftness(emitter, distance)

3D seulement : estompe une particule sur distance unités du monde là où elle rencontre la géométrie derrière elle, si bien qu’une bouffée de fumée ne trace pas de ligne nette là où elle traverse un mur et qu’une fontaine s’enfonce dans son bassin au lieu de le trancher. 0 (la valeur par défaut) le désactive ; les valeurs négatives deviennent 0. Tant qu’un émetteur l’utilise, la profondeur de la scène est rendue une fois de plus par image : un Raspberry Pi devrait donc l’utiliser avec parcimonie. Un émetteur 2D garde la valeur et l’ignore.

Depuis : 3.00. Voir aussi : emitterSetLit, emitterSetBlend

Exemple
-- La fumée du brasero s'adoucit contre le poteau qu'elle longe en montant.
smoke = emitterNew(brazierTop)
emitterSetRate(smoke, 25)
emitterSetLife(smoke, 1.5, 2.5)
emitterSetSize(smoke, 0.2, 0.9, 0.2)
emitterSetColor(smoke, 160, 160, 170, 120, 120, 120, 130, 0)
emitterSetLit(smoke, true)
emitterSetSoftness(smoke, 0.3)
emitterStart(smoke)

2.12.10. emitterSetSpeed

emitterSetSpeed(emitter, min, max)

La vitesse de départ de chaque nouvelle particule, tirée au hasard entre les deux, en unités de l’overlay par seconde (2D) ou en unités du monde par seconde (3D) ; par défaut de 50 à 100 en 2D et de 1 à 2 en 3D. Le maximum est relevé au minimum quand il est plus petit. La vitesse décide jusqu’où va une particule avant que le freinage, la gravité et sa durée de vie prennent le relais.

Depuis : 3.00. Voir aussi : emitterSetDirection, emitterSetDrag, emitterSetGravity

Exemple
-- Une fontaine projette ses gouttes fort et droit ; la poussière bouge à peine.
emitterSetSpeed(fountain, 4.0, 5.0)
emitterSetSpread(fountain, 8)
emitterSetSpeed(dust, 0.05, 0.2)
emitterSetSpread(dust, 180)

2.12.11. emitterSetDirection

emitterSetDirection(emitter, x, y)
emitterSetDirection(emitter, x, y, z)

La direction moyenne dans laquelle partent les nouvelles particules ; seule la direction compte, pas la longueur. Par défaut en 2D (0, -1), vers le haut de l’écran puisque le Y de l’overlay croît vers le bas ; par défaut en 3D (0, 1, 0), vers le haut de l’axe Y du monde. Un émetteur 2D ignore z ; un émetteur 3D qui reçoit deux valeurs prend z = 0. Un vecteur nul est traité comme (0, -1, 0). Pour un émetteur 3D, la direction s’exprime dans les axes du monde, pas dans ceux du nœud : tournez-la vous-même quand le nœud tourne.

Depuis : 3.00. Voir aussi : emitterSetSpread, emitterSetSpeed

Exemple
-- Les gaz s'échappent derrière le vaisseau, où qu'il soit tourné.
function onOverlayUpdate()
    local heading = math.rad(shipYaw)
    emitterSetDirection(exhaust, -math.sin(heading), 0, -math.cos(heading))
    return OVERLAY_NOT_UPDATED
end

2.12.12. emitterSetSpread

emitterSetSpread(emitter, degrees)

La moitié de l’angle du cône (3D) ou de l’éventail (2D), autour de la direction, dans lequel les nouvelles particules sont projetées, de 0 à 180 ; 0 est une ligne droite, 180 toutes les directions. 30 par défaut ; les valeurs hors plage sont bornées. En 3D, les directions sont réparties uniformément sur la calotte du cône, si bien qu’un cône large ne se resserre pas vers son axe.

Depuis : 3.00. Voir aussi : emitterSetDirection, emitterSetRadius

Exemple
-- Le feu d'artifice part dans tous les sens ; la flamme de la torche reste une colonne serrée.
emitterSetSpread(fireworks, 180)
emitterSetSpread(flame, 15)

2.12.13. emitterSetGravity

emitterSetGravity(emitter, x, y)
emitterSetGravity(emitter, x, y, z)

Une accélération constante sur chaque particule, en unités de l’overlay (2D) ou en unités du monde (3D) par seconde au carré : (0, 500) tire les étincelles 2D vers le bas de l’écran, (0, -20) laisse monter la fumée 2D, (0, -9.8, 0) est la Terre dans la scène. Aucune par défaut. Elle s’applique aux particules vivantes dès l’image suivante. Les particules ne sont pas des corps physiques ; donnez-leur emitterSetCollide pour qu’elles rebondissent sur un sol ou sur la scène.

Depuis : 3.00. Voir aussi : emitterSetDrag, emitterSetCollide, emitterSetSpeed

Exemple
-- Les étincelles tombent, la fumée monte, toutes deux de la même meuleuse.
emitterSetGravity(sparks, 0, 500)
emitterSetGravity(smoke, 0, -20)

-- Sous l'eau, les bulles filent vers la surface.
emitterSetGravity(bubbles, 0, 3, 0)

2.12.14. emitterSetDrag

emitterSetDrag(emitter, perSecond)

La vitesse à laquelle les particules perdent leur vélocité : à chaque image, la vélocité est multipliée par 1 - perSecond * dt, jamais en dessous de 0, si bien que 1 enlève l’essentiel de la vitesse en une seconde et que 0 (la valeur par défaut) la garde pour toujours. Les valeurs négatives deviennent 0. La fumée, les braises et les feux d’artifice ralentissent ; les étincelles et la pluie, non. S’applique aux particules vivantes dès l’image suivante.

Depuis : 3.00. Voir aussi : emitterSetGravity, emitterSetSpeed

Exemple
-- Une bombe de feu d'artifice : sortie rapide, puis suspendue et retombant.
fireworks = emitterNew()
emitterSetBlend(fireworks, PARTICLE_ADD)
emitterSetSpeed(fireworks, 120, 320)
emitterSetSpread(fireworks, 180)
emitterSetGravity(fireworks, 0, 220)
emitterSetDrag(fireworks, 0.8)
emitterSetLife(fireworks, 0.8, 1.6)

2.12.15. emitterSetSize

emitterSetSize(emitter, start, finish)
emitterSetSize(emitter, start, finish, variation)

La taille à la naissance et à la mort, en unités de l’overlay (2D) ou en unités du monde (3D), qui change régulièrement au fil de la vie de la particule ; par défaut de 16 à 4 en 2D et de 0.2 à 0.05 en 3D. variation (de 0 à 1, 0 par défaut) multiplie les deux tailles de chaque nouvelle particule par un même facteur aléatoire entre 1 - variation et 1 + variation, si bien qu’une bouffée est un peu plus grande ou plus petite toute sa vie. Les tailles négatives deviennent 0 et variation est borné. Une particule texturée est dessinée comme un carré de cette taille ; une image plus large est écrasée.

Depuis : 3.00. Voir aussi : emitterSetLife, emitterSetColor, emitterSetSpin

Exemple
-- La fumée grossit en s'éclaircissant ; les étincelles rétrécissent jusqu'à rien.
emitterSetSize(smoke, 12, 48, 0.2)
emitterSetSize(sparks, 5, 1)

2.12.16. emitterSetCollide

emitterSetCollide(emitter, mode)
emitterSetCollide(emitter, mode, bounce)
emitterSetCollide(emitter, mode, bounce, friction)
emitterSetCollide(emitter, mode, bounce, friction, floor)

Ce sur quoi rebondissent les particules. COLLIDE_NONE (par défaut), c’est rien ; COLLIDE_FLOOR, c’est un plan horizontal à la hauteur floor, sous lequel (Y plus grand en 2D, Y plus petit en 3D) une particule est remise sur le plan et réfléchie ; COLLIDE_SCENE, c’est le monde physique, pour les émetteurs 3D seulement, par un lancer de rayon par particule le long de son mouvement à chaque image, plafonné à 200 lancers par émetteur et par image et repris là où ils s’étaient arrêtés, si bien qu’un gros émetteur répartit le coût sur quelques images. Sur un émetteur 2D, COLLIDE_SCENE est accepté et ne fait rien. Un mode autre que ces trois-là met fin au script.

Paramètres :

  • mode — COLLIDE_NONE, COLLIDE_FLOOR ou COLLIDE_SCENE.

  • bounce — la part de vitesse qui survit à un choc, de 0 à 1, 0.5 par défaut ; bornée.

  • friction — la part de vitesse de glissement perdue à chaque choc, de 0 à 1, 0.2 par défaut ; bornée.

  • floor — hauteur du plan du sol, en unités du monde pour un émetteur 3D ou en unités de l’overlay pour un émetteur 2D, 0 par défaut. Utilisé par COLLIDE_FLOOR seulement.

Depuis : 3.00. Voir aussi : emitterSetGravity, emitterSetTrail, emitterSetSoftness

Exemple
-- Les étincelles rebondissent sur le sol de l'atelier (ligne 440 de l'overlay) et laissent des traînées.
sparks = emitterNew()
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetGravity(sparks, 0, 500)
emitterSetCollide(sparks, COLLIDE_FLOOR, 0.4, 0.2, 440)
emitterSetTrail(sparks, 6, 3)

-- Les braises de la scène rebondissent sur tout ce que contient le monde physique.
emitterSetCollide(embers, COLLIDE_SCENE, 0.3, 0.5)

2.12.17. emitterSetColor

emitterSetColor(emitter, r, g, b, a, r2, g2, b2, a2)

La couleur et l’opacité à la naissance (r, g, b, a) et à la mort (r2, g2, b2, a2), chacune de 0 à 255, qui changent régulièrement au fil de la vie de la particule ; les valeurs hors plage sont bornées. Par défaut, du blanc opaque au blanc transparent. La teinte multiplie la texture ou le disque intégré, si bien qu’une image blanche prend exactement la couleur. Un fondu en entrée et en sortie demande deux émetteurs ou une texture qui contient la forme ; une recette suit une seule rampe droite.

Depuis : 3.00. Voir aussi : emitterSetBlend, emitterSetLife, emitterSetSize

Exemple
-- Flamme : jaune vif à la base, qui meurt en rouge terne et disparaît.
emitterSetColor(flame, 255, 200, 90, 255, 255, 40, 0, 0)
-- Les grains de poussière apparaissent à partir de rien et restent suspendus ; leur durée de vie les achève.
emitterSetColor(dust, 255, 240, 200, 0, 255, 240, 200, 160)

2.12.18. emitterSetSpin

emitterSetSpin(emitter, min, max)

La vitesse de rotation de chaque nouvelle particule en degrés par seconde, tirée au hasard entre les deux ; les valeurs négatives tournent dans l’autre sens, et une plage qui chevauche 0 donne les deux. Chaque particule part d’un angle aléatoire, qu’elle tourne ou non. Aucune par défaut. Le maximum est relevé au minimum quand il est plus petit. La rotation se voit sur une particule texturée ou sur une traînée ; le disque intégré est rond et paraît identique sous tout angle.

Depuis : 3.00. Voir aussi : emitterSetTexture, emitterSetSize

Exemple
-- Les feuilles virevoltent ; les braises tournent à peine.
emitterSetTexture(leaves, leafSprite)
emitterSetSpin(leaves, -180, 180)
emitterSetSpin(embers, -20, 20)

2.12.19. emitterSetRadius

emitterSetRadius(emitter, radius)

Les nouvelles particules naissent n’importe où à cette distance au plus de l’origine de l’émetteur, uniformément sur un disque (2D) ou dans une boule (3D), en unités de l’overlay ou du monde. 0 par défaut, un point ; les valeurs négatives deviennent 0. Un rayon remplit un volume, une tête de torche ou une nappe de poussière dans l’air, là où un point donnerait une aiguille.

Depuis : 3.00. Voir aussi : emitterSetSpread, emitterSetPosition

Exemple
-- De la poussière dans une boule d'air de la taille d'une pièce, presque toute déjà là au début du niveau.
air = nodeNew()
nodeSetPosition(air, 0, 2, 0)
dust = emitterNew(air)
emitterSetRadius(dust, 2.5)
emitterSetSpread(dust, 180)
emitterSetSpeed(dust, 0.05, 0.2)
emitterSetLife(dust, 4, 6)
emitterStart(dust)
emitterBurst(dust, 120)

2.12.20. emitterSetLit

emitterSetLit(emitter, lit)

3D seulement : éclaire chaque particule avec les lumières et le ciel de la scène comme s’il s’agissait d’une petite sphère tournée vers la caméra, si bien que la fumée prend la couleur d’un brasero et que la poussière scintille au soleil. Désactivé par défaut ; les ombres ne sont pas consultées. Avec PARTICLE_ADD, l’éclairage s’applique quand même à la teinte avant qu’elle soit ajoutée. Un émetteur 2D garde la valeur et l’ignore.

Depuis : 3.00. Voir aussi : emitterSetSoftness, emitterSetBlend

Exemple
-- La fumée au-dessus de chaque brasero prend la lueur de son feu.
for _, brazier in ipairs(braziers) do
    local smoke = emitterNew(brazier.top)
    emitterSetRate(smoke, 12)
    emitterSetLife(smoke, 2.5, 4)
    emitterSetColor(smoke, 90, 80, 75, 90, 50, 45, 45, 0)
    emitterSetLit(smoke, true)
    emitterStart(smoke)
end

2.12.21. emitterSetLocal

emitterSetLocal(emitter, local)

Indique si les particules vivantes suivent l’émetteur. false (par défaut) laisse chacune là où elle est née, si bien qu’une torche portée à travers une pièce laisse de la fumée derrière elle ; true garde tout le nuage relatif à l’origine de l’émetteur, si bien que le panache d’un propulseur se déplace avec le vaisseau. Basculer le réglage fait passer les particules vivantes d’un référentiel à l’autre sans saut. Sur un émetteur 3D, l’origine est la position du nœud dans le monde ; sur un émetteur 2D, c’est le point donné par emitterSetPosition, si bien qu’un nuage 2D local glisse lui aussi avec ce point. Les traînées suivent la même règle.

Depuis : 3.00. Voir aussi : emitterSetPosition, emitterSetRadius

Exemple
-- Une aura magique qui reste enroulée autour de la magicienne pendant qu'elle marche.
aura = emitterNew(nodeFind("Chest", wizard))
emitterSetLocal(aura, true)
emitterSetRadius(aura, 0.6)
emitterSetSpeed(aura, 0.05, 0.15)
emitterSetSpread(aura, 180)
emitterSetBlend(aura, PARTICLE_ADD)
emitterStart(aura)

2.12.22. emitterSetMax

emitterSetMax(emitter, count)

La réserve : le nombre de particules qui peuvent être vivantes en même temps, 1000 par défaut. Une réserve pleine n’en crée plus, ni par le flux ni par une salve, tant que certaines ne sont pas mortes. Changer ce nombre reconstruit la réserve et tue chaque particule vivante : réglez-le donc avant de démarrer. Dimensionnez la réserve au débit multiplié par la plus longue durée de vie, plus la plus grosse salve. Un nombre inférieur à 1 met fin au script.

Depuis : 3.00. Voir aussi : emitterSetRate, emitterBurst, emitterGetCount

Exemple
-- 300 gouttes par seconde vivant jusqu'à 1,6 seconde demandent environ 480 ; gardez de la marge.
fountain = emitterNew(spout)
emitterSetRate(fountain, 300)
emitterSetLife(fountain, 1.0, 1.6)
emitterSetMax(fountain, 600)
emitterStart(fountain)

2.12.23. emitterSetPosition

emitterSetPosition(emitter, x, y)

2D seulement : où naissent les nouvelles particules, en coordonnées de l’overlay ; (0, 0) par défaut. Réglez-la à chaque image pour suivre un sprite ou un corps physique 2D. Les particules vivantes restent où elles sont, sauf si emitterSetLocal est activé. Un émetteur 3D suit son nœud et met fin au script ici ; déplacez plutôt le nœud.

Depuis : 3.00. Voir aussi : emitterDraw, emitterSetLocal, emitterSetRadius

Exemple
-- Les étincelles jaillissent de là où se trouve le sprite de la meuleuse à cette image.
function onOverlayUpdate()
    overlayClear()
    spriteDraw(grinder, grinderX, grinderY)
    emitterSetPosition(sparks, grinderX + 24, grinderY + 8)
    emitterDraw(sparks)
    return OVERLAY_UPDATED
end

2.12.24. emitterSetTrail

emitterSetTrail(emitter, length, width)

Un ruban derrière chaque particule, passant par ses length dernières positions, une enregistrée par image (de 2 à 16 ; 0 ou 1 pour aucun, la valeur par défaut), large de width en unités du monde ou de l’overlay, en 2D comme en 3D. Le ruban porte la teinte actuelle de la particule, s’estompe jusqu’au transparent vers sa queue, et prend pour texture la colonne du milieu de l’image de la particule, si bien que le bord flou du disque devient celui du ruban. Les valeurs sont bornées à la plage. Changer la longueur reconstruit le stockage des traînées : les particules vivantes recommencent donc leurs rubans. Étincelles, braises, balles traçantes, comètes.

Depuis : 3.00. Voir aussi : emitterSetCollide, emitterSetSize, emitterSetLocal

Exemple
-- Balles traçantes : minuscules, rapides, et rien que des traînées.
tracers = emitterNew(gunMuzzle)
emitterSetBlend(tracers, PARTICLE_ADD)
emitterSetSpeed(tracers, 40, 50)
emitterSetSpread(tracers, 2)
emitterSetSize(tracers, 0.04, 0.04)
emitterSetLife(tracers, 0.8, 1.0)
emitterSetTrail(tracers, 8, 0.03)

2.12.25. emitterStart

emitterStart(emitter)

Lance le flux continu au débit réglé ; dès lors, l’émetteur crée des particules à chaque image jusqu’à emitterStop. Démarrer un émetteur qui émet déjà ne change rien. Le flux n’a besoin d’aucun appel de dessin pour tourner ; un émetteur 2D qui émet sans être dessiné consomme quand même sa réserve.

Depuis : 3.00. Voir aussi : emitterStop, emitterSetRate, emitterBurst

Exemple
-- Le moteur s'allume quand le joueur met les gaz et s'éteint quand il les coupe.
function onThrottle(open)
    if open then
        emitterStart(exhaust)
    else
        emitterStop(exhaust)
    end
end

2.12.26. emitterStop

emitterStop(emitter)

Met fin au flux ; les particules vivantes finissent leur vie et toute fraction de particule due est abandonnée. emitterBurst fonctionne encore sur un émetteur arrêté, et emitterIsActive reste à true jusqu’à la mort de la dernière particule. Utilisez emitterClear pour supprimer aussi les particules d’un coup.

Depuis : 3.00. Voir aussi : emitterClear, emitterStart, emitterIsActive

Exemple
-- La torche s'éteint : arrêter la flamme, laisser la dernière fumée s'éloigner.
function onTorchDoused()
    emitterStop(flame)
    emitterStop(smoke)
    soundPlay(hiss)
end

2.12.27. emitterBurst

emitterBurst(emitter, count)

Crée d’un coup count particules selon la recette actuelle, flux ou pas : une explosion, une éclaboussure, une bouffée. Seules sont créées celles pour lesquelles la réserve a de la place ; emitterSetMax règle cette place. Un émetteur 2D lâche sa salve à son point emitterSetPosition, un émetteur 3D à son nœud, répartie sur emitterSetRadius.

Depuis : 3.00. Voir aussi : emitterStart, emitterSetMax, emitterSetRadius

Exemple
-- Feu d'artifice : une bombe éclate quelque part au-dessus du disque toutes les secondes environ.
function onOverlayUpdate()
    if frames % 60 == 0 then
        emitterSetPosition(fireworks, 120 + (frames * 7) % (width - 240), 80 + (frames * 13) % 160)
        emitterBurst(fireworks, 260)
    end
    overlayClear()
    emitterDraw(fireworks)
    frames = frames + 1
    return OVERLAY_UPDATED
end

2.12.28. emitterClear

emitterClear(emitter)

Tue sur-le-champ chaque particule vivante et oublie toute fraction de particule due. Le flux n’est pas arrêté : un émetteur démarré continue de créer de nouvelles particules à l’image suivante, alors appelez aussi emitterStop pour le vider pour de bon. Servez-vous-en quand une scène change et que les anciennes étincelles ne doivent pas traîner.

Depuis : 3.00. Voir aussi : emitterStop, emitterDelete

Exemple
-- On recommence le niveau : les émetteurs restent, les anciennes particules s'en vont.
function resetLevel()
    for _, emitter in ipairs(levelEmitters) do
        emitterStop(emitter)
        emitterClear(emitter)
    end
    placePlayer()
end

2.12.29. emitterDraw

emitterDraw(emitter)

2D seulement, depuis onOverlayUpdate : met en file d’attente les particules de l’émetteur pour qu’elles soient dessinées à cette image, au-dessus ou au-dessous de l’overlay selon emitterSetLayer, en coordonnées de l’overlay projetées sur la fenêtre. Les émetteurs d’une même couche se dessinent dans l’ordre où ils ont été mis en file. La file se vide à chaque image : l’appel a donc sa place dans chaque image où les particules doivent se voir ; ne pas dessiner un émetteur ne l’arrête pas. Jusqu’à 64 émetteurs par couche se dessinent dans une image. Un émetteur 3D se dessine lui-même dans la scène et met fin au script ici.

Depuis : 3.00. Voir aussi : emitterSetLayer, emitterSetPosition, onOverlayUpdate

Exemple
function onOverlayUpdate()
    overlayClear()
    emitterSetPosition(smoke, chimneyX, chimneyY)
    emitterDraw(smoke)
    emitterDraw(sparks)
    fontPrint(20, 20, "Score " .. score)
    return OVERLAY_UPDATED
end

2.12.30. emitterGetCount

count = emitterGetCount(emitter)

Le nombre de particules de l’émetteur vivantes à cette image, de 0 à la taille de la réserve. Utile pour régler une réserve, pour un budget à l’écran, ou pour savoir quand une salve s’est éteinte.

Renvoie : le nombre de particules vivantes, un entier.

Depuis : 3.00. Voir aussi : emitterSetMax, emitterIsActive

Exemple
-- Overlay de développement : quelle part de chaque réserve est utilisée.
function onOverlayUpdate()
    overlayClear()
    fontPrint(20, 20, string.format("live %d / %d", emitterGetCount(fireworks), fireworksPool))
    return OVERLAY_UPDATED
end

2.12.31. emitterIsActive

active = emitterIsActive(emitter)

Indique si l’émetteur émet en continu ou a encore des particules vivantes : true depuis emitterStart ou emitterBurst jusqu’à ce que le flux soit arrêté et que la dernière particule soit morte, false une fois l’explosion finie. Un émetteur en émission continue dont la réserve se trouve vide est toujours actif.

Renvoie : booléen.

Depuis : 3.00. Voir aussi : emitterStop, emitterGetCount, emitterDelete

Exemple
-- Les explosions ponctuelles vivent dans une liste et sont libérées quand elles s'éteignent.
function onOverlayUpdate()
    for i = #explosions, 1, -1 do
        if not emitterIsActive(explosions[i]) then
            emitterDelete(explosions[i])
            table.remove(explosions, i)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.13. Police

Singe a deux moteurs de rendu de texte. La police console intégrée est dessinée par overlayPrint et n’a besoin d’aucune ressource ; la famille font* charge des fichiers TrueType à une taille en points fixe et les rend soit directement sur l’overlay avec fontPrint, soit dans un sprite réutilisable avec fontToSprite. Les handles de police sont des entiers renvoyés par fontLoad, et le moteur garde une police sélectionnée globale, que fontLoad règle sur la police qu’il vient de charger et que fontSelect change. Le texte est rendu dans la couleur de premier plan actuelle, à la qualité choisie par fontQuality, et les positions du texte sont des coordonnées de l’overlay. Libérez les polices avec fontUnload ; Singe/FreeSansBold.ttf est fourni avec le moteur et toujours disponible.

2.13.1. fontLoad

result = fontLoad(filename, pointSize)

Ouvre une police TrueType à une taille en points et en fait la police sélectionnée. La taille est fixée pour toute la vie du handle : chargez donc le même fichier une fois par taille dont vous avez besoin. Le nom passe par le système de fichiers virtuel comme toute autre ressource ; préfixez-le de DIR pour les fichiers livrés avec votre jeu, ou utilisez Singe/FreeSansBold.ttf pour la police fournie. Un fichier qui ne peut pas être ouvert met fin au script avec Unable to open et le nom.

Paramètres :

  • filename — chemin d’un fichier .ttf.

  • pointSize — taille en points, entière.

Renvoie : handle de police entier.

Depuis : 1.x Voir aussi : fontSelect, fontUnload, fontQuality

Exemple
-- Deux tailles de la police fournie : grande pour le titre, petite pour le HUD.
fontQuality(FONT_QUALITY_BLENDED)
titleFont = fontLoad("Singe/FreeSansBold.ttf", 32)
hudFont   = fontLoad("Singe/FreeSansBold.ttf", 18)

fontSelect(titleFont)
titleSprite = fontToSprite("GAME OVER")
fontSelect(hudFont)

2.13.2. fontPrint

fontPrint(x, y, text)

Rend une chaîne avec la police sélectionnée, la qualité actuelle et la couleur de premier plan actuelle (plus la couleur de fond pour FONT_QUALITY_SHADED), puis la copie sur l’overlay avec son coin supérieur gauche en (x, y). Appelez-la depuis onOverlayUpdate, à chaque image s’il le faut : le moteur garde chaque chaîne qu’il rend, indexée par la police, la qualité, les couleurs et le texte, et un appel ultérieur qui demande la même ne fait que la copier. Les chaînes qui ne sont pas affichées pendant environ une seconde sont oubliées, et celles d’une police disparaissent quand elle est déchargée : le texte qui change ne coûte donc pas plus qu’avant, et celui qui ne change pas est presque gratuit. Une page entière de meilleurs scores réaffichée à chaque image ne pose aucun problème. Sans police sélectionnée, une erreur met fin au script.

Paramètres :

  • x, y — coin supérieur gauche en coordonnées de l’overlay ; les fractions sont tronquées.

  • text — la chaîne à rendre.

Depuis : 1.x Voir aussi : fontToSprite, fontSelect, colorForeground, overlayPrint

Exemple
-- Affichage en direct du calibrage audio ; le texte change à chaque image, donc on le rend directement.
function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 255, 255, 255)
    fontSelect(hudFont)
    fontPrint(MARGIN_X, MARGIN_Y, "AUDIO DELAY CALIBRATION")
    fontPrint(MARGIN_X, MARGIN_Y + 30, "Delay: " .. calibrationDelay .. " ms")
    fontPrint(MARGIN_X, MARGIN_Y + 60, "Left / Right: 10 ms     Up / Down: 1 ms")
    return OVERLAY_UPDATED
end

2.13.3. fontQuality

fontQuality(mode)

Choisit comment fontPrint et fontToSprite rastérisent le texte à partir de maintenant. Le réglage est global, pas propre à chaque police, et commence à FONT_QUALITY_SOLID. Les sprites déjà créés par fontToSprite gardent la qualité avec laquelle ils ont été rendus. Une valeur autre que les trois constantes met fin au script sur une erreur.

Paramètres :

  • mode — FONT_QUALITY_SOLID (1) : le plus rapide, bords sur un bit, sans anticrénelage. FONT_QUALITY_SHADED (2) : glyphes anticrénelés sur un rectangle plein de la couleur de fond. FONT_QUALITY_BLENDED (3) : glyphes anticrénelés avec un alpha par pixel, qui se mélangent par-dessus n’importe quoi ; le choix habituel.

Depuis : 1.x Voir aussi : fontPrint, fontToSprite, colorBackground

Exemple
-- Texte mélangé sur la vidéo, mais une étiquette sur fond plein pour l'affichage de débogage.
fontQuality(FONT_QUALITY_BLENDED)
titleSprite = fontToSprite("HIGH SCORES")

colorBackground(0, 0, 0, 255)
fontQuality(FONT_QUALITY_SHADED)
debugLabel = fontToSprite("FRAME")
fontQuality(FONT_QUALITY_BLENDED)

2.13.4. fontSelect

fontSelect(id)

Fait d’une police chargée celle qu’utilisent fontPrint et fontToSprite. La sélection persiste jusqu’au prochain fontSelect ou fontLoad, puisque charger sélectionne aussi. Elle peut changer aussi souvent que nécessaire, y compris plusieurs fois dans un même onOverlayUpdate. Un handle inconnu ou déchargé (ou pas de nombre du tout) laisse la police actuelle sélectionnée et affiche un avertissement, car Hypseus Singe le laisse passer.

Depuis : 1.x Voir aussi : fontLoad, fontPrint, fontToSprite

Exemple
-- Le titre dans la grande police, le score dans la petite, à chaque image.
function onOverlayUpdate()
    overlayClear()
    fontSelect(titleFont)
    fontPrint(TITLE_X, 40, "HIGH SCORES")
    fontSelect(hudFont)
    fontPrint(8, 8, "Score: " .. score)
    return OVERLAY_UPDATED
end

2.13.5. fontToSprite

result = fontToSprite(text)

Rend une chaîne avec la police, la qualité et les couleurs sélectionnées dans un nouveau sprite et renvoie son handle. Le sprite est dès lors indépendant de la police : il survit donc à fontUnload, et il fonctionne avec tous les appels sprite* : dessinez-le, mesurez-le, mettez-le à l’échelle ou faites-le tourner, et libérez-le avec spriteUnload. Pour une chaîne qui change, rendez un nouveau sprite et déchargez l’ancien. Sans police sélectionnée, une erreur met fin au script.

Rendre du texte dans un sprite pour les performances est déconseillé. fontPrint garde désormais ce qu’il rend, si bien qu’afficher la même chaîne à chaque image coûte à peu près autant que dessiner un sprite fait à partir d’elle, sans sprite à gérer. Utilisez fontToSprite quand le texte doit être un sprite : pour le mettre à l’échelle, le faire tourner, le retourner ou le mesurer avec spriteGetWidth et spriteGetHeight.

Renvoie : handle de sprite entier.

Depuis : 1.x Voir aussi : fontPrint, spriteDraw, spriteGetWidth, spriteUnload

Exemple
-- Un titre qui tourne et grandit en apparaissant : du texte qui doit être un sprite, pour être tourné et mis à l'échelle.
titleSprite = fontToSprite("GAME OVER")
titleFrames = 0

function onOverlayUpdate()
    titleFrames = titleFrames + 1
    spriteRotate(titleSprite, (titleFrames * 12) % 360)
    spriteScale(titleSprite, math.min(titleFrames / 30, 1))
    spriteDraw(titleSprite, overlayGetWidth() / 2, overlayGetHeight() / 2, true)
    return OVERLAY_UPDATED
end

2.13.6. fontUnload

fontUnload(id)

Ferme une police et invalide son handle. Les sprites faits à partir d’elle avec fontToSprite ne sont pas touchés. Si la police déchargée était la police sélectionnée, aucune police n’est plus sélectionnée ensuite et le prochain fontPrint ou fontToSprite met fin au script sur une erreur, jusqu’à ce que fontSelect ou fontLoad en choisisse une autre.

Depuis : 2.00 Voir aussi : fontLoad, fontSelect, onShutdown

Exemple
-- Libérer les polices et les sprites de texte qu'elles ont produits.
function onShutdown()
    spriteUnload(titleSprite)
    for _, line in ipairs(descriptionLines) do
        spriteUnload(line)
    end
    fontUnload(titleFont)
    fontUnload(hudFont)
end

2.14. Gui

Une GUI est un arbre de documents RmlUi de taille fixe, rendu dans sa propre texture à chaque image : guiNew en crée une et renvoie un handle entier, guiLoad y place un document RML et renvoie un handle de document, guiDraw la compose par-dessus l’overlay et materialSetGui l’affiche sur un matériau de la scène. Les documents sont du RML proche du HTML, mis en forme par du RCSS proche du CSS, et chargés par le système de fichiers virtuel comme les sprites ; Singe/gui.rcss est le thème fourni et Singe/FreeSansBold.ttf la police de repli. Les aides par id guiGetValue, guiSetValue et guiSetHandler atteignent les éléments sans passer par le modèle objet ; tout le reste est l’API Lua de RmlUi sur la globale rmlui, où une GUI est le contexte nommé gui suivi de son handle. Seize GUI au plus existent à la fois, chacune avec trente-deux documents. Une GUI a besoin du périphérique GPU, si bien que guiNew met fin au script sur une machine qui n’en a pas ; un mauvais handle de GUI lève No GUI N, et un mauvais handle de document No document N in GUI G. Voir GUI dans Développement de jeux.

2.14.1. guiClose

guiClose(gui, document)

Décharge le document de la GUI, en abandonnant ses éléments, ses gestionnaires et ses scripts. Le handle du document n’est plus valide ensuite. Un document fermé par son propre script via l’API de RmlUi (document:Close()) est déchargé de la même façon. Lève No document N in GUI G pour un handle non valide.

Depuis : 3.00. Voir aussi : guiLoad, guiHide, guiDelete

Exemple
-- La page de saisie du meilleur score ne sert qu'une fois ; on la ferme une fois le nom saisi.
guiSetHandler(gui, entryPage, "enter", "click", function(g, d)
    scores[#scores + 1] = { name = guiGetValue(g, d, "name"), score = score }
    guiClose(g, d)
    entryPage = nil
end)

2.14.2. guiDelete

guiDelete(gui)

Libère la GUI, tous ses documents et sa texture, et met fin à la mise à jour et au rendu qu’elle coûtait à chaque image. Les matériaux qui l’affichaient par materialSetGui reviennent à leur propre texture. Le handle n’est plus valide ensuite et met fin au script s’il est réutilisé ; comme une GUI continue d’être rendue, qu’elle soit dessinée ou non, supprimez celles dont un jeu n’a plus besoin plutôt que de les masquer.

Depuis : 3.00. Voir aussi : guiNew, guiClose, materialSetGui

Exemple
-- La page des options ne vit que tant que le joueur s'y trouve.
function closeOptions()
    guiDelete(optionsGui)
    optionsGui = nil
    discPlay()
end

2.14.3. guiDraw

guiDraw(gui)
guiDraw(gui, x, y)
guiDraw(gui, x, y, width, height)

Compose la texture de la GUI par-dessus l’overlay pour cette image, en coordonnées de l’overlay, si bien qu’elle respecte la bordure Sinden et l’échelle d’overscan comme tout le reste de l’overlay : sur tout l’overlay avec un seul argument, à sa propre taille avec un coin en x, y, ou mise à l’échelle dans le rectangle de width sur height. La place de l’appel dans le dessin du script décide de ce qui est sous la GUI et de ce qui est dessus : tout ce qui est dessiné sur l’overlay avant lui reste dessous, et tout ce qui est dessiné après lui — jusqu’au prochain guiDraw ou au prochain tour du script — va sur une couche à part, composée par-dessus cette GUI. Un pointeur dessiné après le HUD est dessiné par-dessus le HUD ; un second document dessiné après cela se place par-dessus le pointeur, avec sa propre couche au-dessus. Seize couches de ce genre au plus par image ; un appel au-delà dessine sa GUI sans rien par-dessus. overlayClear efface la couche sur laquelle on est en train de dessiner, et overlaySetMonochrome ne passe en gris que l’overlay de base. L’appel dure une image ; faites-le depuis onOverlayUpdate (ou singeMain) à chaque image où la GUI doit être visible. Les GUI se dessinent au-dessus de l’overlay dans l’ordre des appels (la dernière au-dessus), sous les particules PARTICLE_OVER et l’indicateur de pause, et la dernière GUI dessinée sous le pointeur est celle qui reçoit la souris. Seize appels au plus sont pris en compte par image ; les suivants sont ignorés. Tout autre nombre d’arguments lève Expected 1, 3 or 5 arguments.

Paramètres :

  • x, y — le coin supérieur gauche, en coordonnées de l’overlay.

  • width, height — la taille de dessin, en pixels de l’overlay ; la taille propre de la GUI s’ils sont omis.

Depuis : 3.00. Voir aussi : guiNew, materialSetGui, overlaySetResolution

Exemple
-- Le HUD occupe le coin inférieur droit sur un tiers de la largeur de l'overlay, et le viseur
-- du pistolet est dessiné après lui, si bien que le panneau ne le cache jamais.
function onOverlayUpdate()
    overlayClear()
    guiSetValue(hud, hudPage, "lives", tostring(lives))
    guiDraw(hud, overlayGetWidth() * 0.66, overlayGetHeight() * 0.8, overlayGetWidth() * 0.33, overlayGetHeight() * 0.2)
    local x, y = mouseGetPosition(0)
    spriteDraw(sight, x, y, true)
    return OVERLAY_UPDATED
end

2.14.4. guiDrawScreen

guiDrawScreen(gui)
guiDrawScreen(gui, x, y)
guiDrawScreen(gui, x, y, width, height)

Identique à guiDraw, sauf que le rectangle se mesure sur toute la fenêtre et non sur l’image. Les coordonnées restent des coordonnées de l’overlay — 0, 0 est le coin supérieur gauche de la fenêtre et overlayGetWidth(), overlayGetHeight() le coin inférieur droit — si bien qu’une GUI peut se placer sur l’illustration du bezel, à côté de l’image, au-dessus ou au-dessous. Sans bezel, et sans --scalefactor, --shiftx ni --shifty, l’image occupe toute la fenêtre et cet appel est exactement guiDraw.

Les GUI en espace écran se dessinent après tout le reste, illustration du bezel comprise, et partagent avec guiDraw les seize dessins par image. Un clic les trouve de la même façon : le pointeur est ramené dans l’espace écran avant d’être testé, si bien qu’une GUI en espace écran qui accepte les entrées reçoit la souris où qu’elle ait été dessinée.

Paramètres :

  • x, y — le coin supérieur gauche, en coordonnées de l’overlay mesurées sur la fenêtre.

  • width, height — la taille de dessin ; la taille propre de la GUI s’ils sont omis.

Depuis : 3.00. Voir aussi : guiDraw, Bezels, scoreBezelEnable

Exemple
-- Une carte sur le montant gauche de l'illustration de la borne, hors de l'image.
function onOverlayUpdate()
    overlayClear()
    guiDrawScreen(mapGui, 8, 44, 38, 114)
    return OVERLAY_UPDATED
end

2.14.5. guiGetHeight

height = guiGetHeight(gui)

La hauteur de la GUI dans ses propres pixels, telle que donnée à guiNew. Met fin au script pour un handle non valide.

Renvoie : un entier.

Depuis : 3.00. Voir aussi : guiGetWidth, guiNew

Exemple
-- Centrer une petite boîte de dialogue sur l'overlay.
local x = (overlayGetWidth() - guiGetWidth(dialog)) / 2
local y = (overlayGetHeight() - guiGetHeight(dialog)) / 2
guiDraw(dialog, x, y)

2.14.6. guiGetStats

stats = guiGetStats()

Ce qu’a coûté le rendu de toutes les GUI lors de la dernière image terminée, pour régler les documents qui utilisent des filtres, des masques et des ombres (chacun d’eux dessinant à travers une couche de la taille de la GUI). Les compteurs couvrent toutes les GUI ensemble. Ils valent tous zéro pour une image où aucune GUI n’a changé d’aspect, puisque rien n’a été redessiné (voir guiRefresh).

Renvoie : une table avec les champs drawCalls (dessins indexés, y compris les écritures de masque, les compositions et les passes de filtre), layerPushes (couches ouvertes pour les filtres, les images de masque et les ombres de boîte), filterPasses (passes pleine taille et copies dans les chaînes de filtres ; un flou en coûte plusieurs), maskWrites (dessins dans le masque de découpe du stencil), layerBytes (octets de textures de couche actuellement alloués ; chacune a la taille de sa GUI, à quatre octets par pixel) et passes (passes de rendu commencées ; chaque changement de couche en commence une).

Depuis : 3.00. Voir aussi : guiNew, GUI

Exemple
-- Surveiller ce que coûte un écran rempli d'effets.
local s = guiGetStats()
debugPrint(string.format("gui draws %d layers %d filters %d passes %d, %d KB of layers", s.drawCalls, s.layerPushes, s.filterPasses, s.passes, s.layerBytes // 1024))

2.14.7. guiGetValue

value = guiGetValue(gui, document, id)

La valeur de l’élément qui porte cet id dans le document, sous forme de chaîne : la valeur d’un contrôle de formulaire (le texte d’un champ de texte, la value d’une option de select, un curseur dans le format propre à RmlUi comme "85.000000", l’attribut value d’une case à cocher ou d’un bouton radio, "on" s’il n’en a pas, qu’il soit coché ou non ; son état est son attribut checked, lu par l’API de RmlUi), ou, pour tout autre élément, son RML intérieur. Renvoie nil quand aucun élément n’a cet id, si bien qu’on peut sonder une page sans mettre fin au script ; un mauvais handle de GUI ou de document y met fin. Les valeurs de plus de 4095 caractères sont coupées.

Renvoie : une chaîne, ou nil.

Depuis : 3.00. Voir aussi : guiSetValue, guiSetHandler

Exemple
-- Lire tout le formulaire quand on appuie sur Start.
guiSetHandler(gui, doc, "go", "click", function(g, d)
    player.name  = guiGetValue(g, d, "name")
    player.hard  = guiGetValue(g, d, "difficulty") == "hard"
    player.volume = math.floor(tonumber(guiGetValue(g, d, "volume")))
end)

2.14.8. guiGetWidth

width = guiGetWidth(gui)

La largeur de la GUI dans ses propres pixels, telle que donnée à guiNew. Met fin au script pour un handle non valide.

Renvoie : un entier.

Depuis : 3.00. Voir aussi : guiGetHeight, guiNew

Exemple
-- Le point sondé est-il dans la moitié droite de la page du moniteur ?
local g, px, py = sceneProbeGui(mouseX, mouseY)
if g ~= nil and px > guiGetWidth(g) / 2 then
    showRightTooltip()
end

2.14.9. guiHide

guiHide(gui, document)

Masque le document : il n’est pas dessiné et ne reçoit aucune entrée, mais il garde ses éléments et ses valeurs, et guiShow le fait revenir tel qu’il était. Lève No document N in GUI G pour un handle non valide.

Depuis : 3.00. Voir aussi : guiShow, guiClose

Exemple
-- Deux pages dans une GUI : la page des options se masque pendant que celle des commandes s'affiche.
guiSetHandler(gui, options, "controls", "click", function()
    guiHide(gui, options)
    guiShow(gui, controls)
end)

2.14.10. guiLoad

document = guiLoad(gui, filename)

Charge un document RML dans la GUI, l’affiche et renvoie un handle de document entier pour les autres appels. Le nom passe par le système de fichiers virtuel comme celui d’un sprite, résolu par rapport au dossier depuis lequel Singe a été lancé : préfixez-le donc de DIR pour les fichiers livrés avec votre jeu ; les feuilles de style, les images et les polices nommées dans le document se résolvent par rapport au fichier qui les nomme, puis par la même recherche, si bien qu’un jeu empaqueté les trouve. Les blocs <script> et les attributs on* du document s’exécutent dans l’état Lua du jeu, et le document est accessible sous rmlui.contexts["guiN"].documents["<body id>"]. Un document qui ne peut pas être chargé met fin au script avec le nom et la raison donnée par RmlUi (un fichier manquant, une erreur d’analyse) ; les avertissements propres à RmlUi sur le balisage et le style vont à la console. Chaque GUI contient jusqu’à trente-deux documents.

Renvoie : le handle du document, un entier.

Depuis : 3.00. Voir aussi : guiNew, guiShow, guiHide, guiClose, guiLoadFont

Exemple
-- La page de titre et le HUD partagent une même GUI de la taille de l'overlay.
gui   = guiNew(overlayGetWidth(), overlayGetHeight())
title = guiLoad(gui, DIR .. "gui/title.rml")
hud   = guiLoad(gui, DIR .. "gui/hud.rml")
guiHide(gui, hud)

2.14.11. guiLoadFont

guiLoadFont(filename)
guiLoadFont(filename, fallback)

Charge une police TrueType ou OpenType pour toutes les GUI, si bien que les documents peuvent la nommer dans font-family par le nom de famille contenu dans le fichier (font-weight et font-style choisissant parmi les styles d’une même famille). Avec fallback à true, la police fournit aussi tout glyphe qu’aucune autre police n’a, ce que fait jusque-là la Singe/FreeSansBold.ttf du moteur (famille FreeSans, graisse bold, la police qu’utilise le thème fourni). Chargez les polices avant les documents qui les utilisent. Chaque police coûte un atlas de glyphes par taille à laquelle elle sert. Un fichier qui ne peut pas être ouvert met fin au script avec Unable to load et le nom.

Paramètres :

  • filename — le fichier de police, par le système de fichiers virtuel comme pour fontLoad.

  • fallback — true pour en faire la police de repli ; false (par défaut) pour une police ordinaire.

Depuis : 3.00. Voir aussi : guiLoad, fontLoad

Exemple
-- La police de titrage du jeu pour les titres ; la FreeSans fournie reste pour le texte courant.
guiLoadFont(DIR .. "fonts/Orbitron-Bold.ttf")
gui  = guiNew(overlayGetWidth(), overlayGetHeight())
menu = guiLoad(gui, DIR .. "gui/menu.rml")

2.14.12. guiNew

gui = guiNew(width, height)

Crée une GUI de width sur height pixels, rendue dans sa propre texture à chaque image, qu’elle soit dessinée ou non, et renvoie son handle. La taille est l’espace de coordonnées du document : 100% du body est la texture entière, et un dp est l’un de ses pixels. Une GUI de la taille de l’overlay convient à une page plein écran ; un élément de HUD ou un moniteur dans la scène en demande une plus petite, et un Raspberry Pi demande que tout reste modeste. Une nouvelle GUI ne fait qu’afficher jusqu’à ce que guiSetInput active les entrées. Lève The size must be positive pour une taille nulle ou négative, et No GUI available quand seize sont déjà utilisées ou que la machine n’a pas de périphérique GPU (une GUI a besoin du même périphérique que la scène 3D).

Paramètres :

  • width — la largeur de la texture, en pixels.

  • height — la hauteur de la texture, en pixels.

Renvoie : le handle de la GUI, un entier.

Depuis : 3.00. Voir aussi : guiLoad, guiDraw, guiDelete, materialSetGui

Exemple
-- Une page de la taille de l'overlay, dessinée par-dessus le disque.
overlaySetResolution(discGetWidth(), discGetHeight())
gui = guiNew(overlayGetWidth(), overlayGetHeight())
doc = guiLoad(gui, DIR .. "gui/attract.rml")

function onOverlayUpdate()
    overlayClear()
    guiDraw(gui)
    return OVERLAY_UPDATED
end

2.14.13. guiRefresh

guiRefresh(gui)

Redessine la GUI à l’image suivante même si rien en elle ne semble avoir changé. Une GUI n’est redessinée que quand son aspect change : quand le document d’une image dessine exactement ce que l’image précédente a dessiné, et que rien de nouveau n’a été créé entre-temps, la texture contient déjà ce rendu et elle est gardée, ce qui épargne au GPU l’essentiel du coût d’une GUI sur les images où un HUD ou un menu ne bouge pas. Les changements faits par le RML, le RCSS, l’interface Lua de RmlUi ou les appels gui* sont tous vus. Cet appel est l’échappatoire si l’un d’eux venait à être manqué — une GUI qui cesse de se mettre à jour alors qu’elle devrait le faire — et un jeu ne devrait pas en avoir besoin ; si c’est le cas, cela vaut la peine de le signaler. Une GUI qui n’existe pas met fin au script.

Depuis : 3.00. Voir aussi : guiDraw, guiGetStats

Exemple
-- Un contournement, le temps qu'un changement manqué soit signalé : redessiner le HUD à chaque image.
function onOverlayUpdate()
    guiRefresh(hud)
    guiDraw(hud)
    return OVERLAY_UPDATED
end

2.14.14. guiSetHandler

guiSetHandler(gui, document, id, event, function)
guiSetHandler(gui, document, id, event, nil)

Appelle function(gui, document, id, event, value) chaque fois que l’élément qui porte cet id déclenche l’événement nommé : "click" pour les boutons et les lignes, "change" pour les contrôles de formulaire, "submit" pour un formulaire, ou tout autre nom d’événement RmlUi ("focus", "mouseover", "keydown", …​). value est la valeur de l’élément à ce moment, sous forme de chaîne, telle que la renverrait guiGetValue (un curseur arrive tel que RmlUi le formate, "85.000000" : passez-le donc par tonumber). Une seule fonction est gardée par élément et par événement ; en régler une autre la remplace, et nil la retire. Le gestionnaire appartient à cet id, pas à un élément : quand l’élément est remplacé — une liste reconstruite par inner_rml crée de nouveaux éléments — réglez de nouveau le gestionnaire après la reconstruction et il s’attache à l’élément qui porte l’id à présent. Les gestionnaires s’exécutent au moment où les événements se produisent, entre les callbacks du jeu lui-même, et une erreur dans l’un d’eux met fin au jeu comme une erreur dans n’importe quel callback. Les ids font au plus 63 caractères. Lève No element "id" in document N of GUI G quand l’élément n’existe pas, et Argument 5 must be a function or nil pour toute autre chose à cette place.

Paramètres :

  • id — l’attribut id de l’élément.

  • event — le nom de l’événement RmlUi.

  • function — la fonction Lua à appeler, ou nil pour ne plus en appeler.

Depuis : 3.00. Voir aussi : guiGetValue, guiSetValue, guiSetInput

Exemple
-- Un curseur de volume agit pendant qu'il bouge ; Start lit le reste du formulaire.
guiSetHandler(gui, doc, "volume", "change", function(g, d, id, event, value)
    soundSetVolume(math.floor(tonumber(value)))
end)

guiSetHandler(gui, doc, "go", "click", function(g, d)
    startGame(guiGetValue(g, d, "name"), guiGetValue(g, d, "difficulty"))
end)

2.14.15. guiSetInput

guiSetInput(gui, enabled)

Indique si la souris et le pistolet optique, les touches, le texte tapé et les contacts du framework venus d’une manette ou d’une souris parviennent à la GUI. Une nouvelle GUI ne fait qu’afficher, ce qui convient à un HUD ou à un panneau ; activez les entrées pour un menu ou un formulaire. Tant qu’elles sont activées, le pointeur atteint la GUI partout où elle est dessinée à plat (la dernière dessinée au-dessus) ou montrée sur une surface de la scène, chaque touche lui est transmise sauf Tab, que la GUI ne reçoit que pendant la saisie dans un champ de texte (RmlUi s’en sert pour déplacer le focus et ne la rend jamais, et un jeu dont les touches comprennent Tab la perdrait sinon), un champ de texte qui a le focus active la saisie de texte de SDL, et les directions de la manette arrivent comme des touches fléchées, avec ACTION_1 pour Entrée et ACTION_2 pour Échap. Ce qu’un élément utilise n’atteint jamais onInputPressed, onKeyPressed ni les callbacks de la souris ; ce que rien n’a utilisé leur parvient comme d’habitude. Met fin au script pour un handle non valide.

Depuis : 3.00. Voir aussi : guiSetHandler, guiDraw, sceneProbeGui

Exemple
-- Le HUD ne prend jamais d'entrées ; la page de pause, si, tant qu'elle est affichée.
guiSetInput(hud, false)

function onInputPressed(what)
    if what == SWITCH_START1 then
        guiShow(gui, pausePage)
        guiSetInput(gui, true)
        singeSetPauseFlag(true)
    end
end

2.14.16. guiSetValue

guiSetValue(gui, document, id, value)

Règle la valeur de l’élément qui porte cet id : la valeur d’un contrôle de formulaire (le texte d’un champ de texte, le nombre d’un curseur, la value d’une option de select ; l’état checked d’une case à cocher est un attribut, réglé par l’API de RmlUi), ou, pour tout autre élément, son RML intérieur, si bien qu’un paragraphe ou une div peut être réécrit avec du texte simple ou avec du balisage. Le document refait sa mise en page à l’image suivante. Lève No element "id" in document N of GUI G quand l’élément n’existe pas.

Paramètres :

  • id — l’attribut id de l’élément.

  • value — la nouvelle valeur, une chaîne ; les nombres sont convertis.

Depuis : 3.00. Voir aussi : guiGetValue, guiSetHandler

Exemple
-- La ligne du score et la rangée des vies sont réécrites à chaque image ; la rangée est du balisage.
function onOverlayUpdate()
    guiSetValue(hud, hudPage, "score", string.format("%08d", score))
    guiSetValue(hud, hudPage, "lives", string.rep("<img src=\"ship.png\"/>", lives))
    overlayClear()
    guiDraw(hud)
    return OVERLAY_UPDATED
end

2.14.17. guiShow

guiShow(gui, document)

Affiche un document masqué par guiHide (un document est affiché quand guiLoad rend la main, l’appel n’est donc pas nécessaire à ce moment-là). Un document affiché est dessiné partout où sa GUI l’est et reçoit les entrées quand sa GUI les reçoit. Lève No document N in GUI G pour un handle non valide.

Depuis : 3.00. Voir aussi : guiHide, guiLoad

Exemple
-- La page de fin de partie apparaît quand la dernière vie s'en va.
function onLastLifeLost()
    guiSetValue(gui, gameOver, "final", string.format("%08d", score))
    guiShow(gui, gameOver)
end

2.15. Articulation

Les articulations relient deux corps, ou un corps et le monde quand le second nœud vaut -1, et renvoient un handle d’articulation entier que prennent les autres appels. Les ancres et les axes sont donnés dans l’espace du monde au moment où l’articulation est créée, avec les corps là où ils se trouvent alors : placez donc les nœuds et donnez-leur des corps avant de les articuler. Les distances sont en unités du monde et les angles de charnière en degrés. Supprimer l’un des corps, ou son nœud, supprime l’articulation ; un handle qui a été supprimé met fin au script quand il est repassé. Voir Physique dans Développement de jeux, Articulations.

2.15.1. jointHinge

joint = jointHinge(nodeA, nodeB, ax, ay, az, dx, dy, dz)

Crée une charnière entre les deux corps, passant par le point du monde (ax, ay, az) selon l’axe (dx, dy, dz) : une porte, une roue, un levier, une bascule. Les corps gardent ce point et cet axe en commun et ne peuvent que tourner autour. L’axe est normalisé, sa longueur n’a donc pas d’importance ; un axe nul devient (0, 1, 0). Les deux nœuds doivent porter un corps, ou bien nodeB peut valoir -1 pour attacher nodeA au monde par une charnière. Met fin au script quand un nœud n’a pas de corps ou que l’articulation ne peut pas être créée.

Paramètres :

  • nodeA — le corps dont la rotation est mesurée ; un angle jointSetLimits positif est sa rotation autour de l’axe selon la règle de la main droite.

  • nodeB — l’autre corps, ou -1 pour le monde.

  • ax, ay, az — l’ancre, un point du monde par lequel passe l’axe de la charnière.

  • dx, dy, dz — l’axe de la charnière dans l’espace du monde.

Renvoie : Le handle de l’articulation.

Depuis : 3.00. Voir aussi : jointSetLimits, jointDelete, jointBall

Exemple
-- Une porte attachée au monde par une charnière le long de son bord gauche, qui s'ouvre de 100 degrés dans un sens.
door = nodeNew()
nodeSetMesh(door, meshBox(1.4, 2.2, 0.1), wood)
nodeSetPosition(door, -0.1, -0.62, 1.4)
bodyNew(door, BODY_DYNAMIC, SHAPE_BOX, 1.4, 2.2, 0.1)
bodySetMass(door, 8)
hinge = jointHinge(door, -1, -0.85, -0.62, 1.4, 0, 1, 0)
jointSetLimits(hinge, 0, 100)
-- Plus tard, une poussée près de la poignée l'ouvre en grand.
bodyApplyImpulse(door, 0, 0, -60, 0.5, -0.62, 1.45)

2.15.2. jointBall

joint = jointBall(nodeA, nodeB, ax, ay, az)

Crée une rotule au point du monde (ax, ay, az) : les corps peuvent tourner dans tous les sens autour de lui mais ne peuvent pas se séparer. Un pendule, un maillon de chaîne, une enseigne suspendue, l’épaule d’un ragdoll. Les deux nœuds doivent porter un corps, ou bien nodeB peut valoir -1 pour suspendre nodeA à un point fixe du monde. Une rotule n’a pas de limites, donc jointSetLimits la refuse. Met fin au script quand un nœud n’a pas de corps ou que l’articulation ne peut pas être créée.

Paramètres :

  • nodeA — le premier corps.

  • nodeB — l’autre corps, ou -1 pour le monde.

  • ax, ay, az — l’ancre, le point du monde autour duquel pivotent les corps.

Renvoie : Le handle de l’articulation.

Depuis : 3.00. Voir aussi : jointHinge, jointDelete, bodyApplyImpulse

Exemple
-- Une chaîne de quatre maillons pendue à un crochet, chacun relié par une rotule à celui du dessus.
local above = -1
for i = 1, 4 do
    local link = nodeNew()
    nodeSetMesh(link, meshSphere(0.12, 16), iron)
    nodeSetPosition(link, 2, 3 - i * 0.3, 0)
    bodyNew(link, BODY_DYNAMIC, SHAPE_SPHERE, 0.12)
    bodySetMass(link, 1)
    jointBall(link, above, 2, 3.15 - i * 0.3, 0)
    above = link
end

2.15.3. jointSlider

joint = jointSlider(nodeA, nodeB, ax, ay, az, dx, dy, dz)

Ne laisse les corps glisser l’un par rapport à l’autre que selon l’axe (dx, dy, dz) passant par l’ancre (ax, ay, az), en gardant leur orientation : un tiroir, un piston, un ascenseur, une porte coulissante. L’axe est normalisé, sa longueur n’a donc pas d’importance ; un axe nul devient (0, 1, 0). Les deux nœuds doivent porter un corps, ou bien nodeB peut valoir -1 pour faire courir nodeA le long d’un rail fixé dans le monde. Met fin au script quand un nœud n’a pas de corps ou que l’articulation ne peut pas être créée.

Paramètres :

  • nodeA — le corps dont la course est mesurée ; une distance jointSetLimits positive va dans le sens de l’axe.

  • nodeB — l’autre corps, ou -1 pour le monde.

  • ax, ay, az — un point du monde sur le rail.

  • dx, dy, dz — la direction de la course dans l’espace du monde.

Renvoie : Le handle de l’articulation.

Depuis : 3.00. Voir aussi : jointSetLimits, jointHinge, bodySetVelocity

Exemple
-- Une caisse sur un rail selon X, poussée de côté au départ et arrêtée 2,4 unités plus loin.
crate = nodeNew()
nodeSetMesh(crate, meshBox(0.5, 0.5, 0.5), wood)
nodeSetPosition(crate, -0.6, 0.9, -3.0)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.5, 0.5, 0.5)
slider = jointSlider(crate, -1, -0.6, 0.9, -3.0, 1, 0, 0)
jointSetLimits(slider, 0, 2.4)
bodySetVelocity(crate, 3, 0, 0)

2.15.4. jointSetLimits

jointSetLimits(joint, low, high)

Borne l’angle d’une charnière en degrés, ou la course d’une glissière en unités du monde, de part et d’autre de la position de départ de l’articulation. Un angle de charnière positif est une rotation de nodeA autour de l’axe selon la règle de la main droite ; une distance de glissière positive va dans le sens de l’axe. low est ramené à 0 au plus et high à 0 au moins, si bien que la pose de départ est toujours dans la plage. Rappelez-la pour changer la plage à tout moment. Met fin au script pour une rotule ou un handle qui n’existe plus.

Paramètres :

  • joint — le handle venu de jointHinge ou de jointSlider.

  • low — l’angle ou la distance négatifs les plus éloignés, 0 ou moins.

  • high — l’angle ou la distance positifs les plus éloignés, 0 ou plus.

Remarques : Les deux corps échangent leurs rôles s’ils sont donnés dans l’autre ordre, ce qui inverse le signe de la plage.

Depuis : 3.00. Voir aussi : jointHinge, jointSlider

Exemple
-- Un levier qui bascule de 30 degrés de chaque côté, puis se bloque une fois l'énigme résolue.
lever = nodeNew()
nodeSetMesh(lever, meshBox(0.1, 0.8, 0.1), iron)
nodeSetPosition(lever, 4, 1.2, 0)
bodyNew(lever, BODY_DYNAMIC, SHAPE_BOX, 0.1, 0.8, 0.1)
pivot = jointHinge(lever, -1, 4, 0.8, 0, 0, 0, 1)
jointSetLimits(pivot, -30, 30)

function lockLever()
    jointSetLimits(pivot, 0, 0)
end

2.15.5. jointDelete

jointDelete(joint)

Supprime l’articulation ; les corps sont de nouveau libres l’un de l’autre et gardent la vitesse qu’ils avaient. Les articulations disparaissent aussi avec l’un ou l’autre de leurs corps, donc cet appel ne sert qu’à libérer deux corps qui restent tous les deux. Met fin au script pour un handle qui n’existe pas ou qui a déjà été supprimé.

Depuis : 3.00. Voir aussi : jointHinge, jointBall, bodyDelete

Exemple
-- La corde casse quand la caisse qui y pend est heurtée assez fort.
function onCollision(a, b, x, y, z, speed)
    if (a == crate or b == crate) and speed > 6 and rope then
        jointDelete(rope)
        rope = nil
        soundPlay(snap)
    end
end

2.16. Joystick

Tout périphérique de jeu que Singe ouvre est une manette et se lit par les appels controller* ; un périphérique que SDL ne reconnaît pas leur parvient par une affectation que Singe écrit pour lui, si bien qu’il n’y a rien d’autre à appeler. Voir Tout périphérique est une manette. Les deux appels de cette section servent à laisser un stick tenir lieu de souris.

2.16.1. joyMouseEnable

joyMouseEnable(enabled)

Extension Hypseus. Active ou désactive le pilotage de la souris par le joystick pendant que le jeu tourne. Quand il est actif, le stick gauche de l’emplacement de manette 0 déplace le pointeur que voit le jeu, par le même onMouseMoved qu’atteint une vraie souris, en restant à l’intérieur de l’image ; --js_range est la vitesse et l’axe obéit à sa propre zone morte. C’est ce qui rend un jeu de pistolet optique jouable sur une borne qui a un stick et pas de souris.

Il part de --joymouse, désactivé par défaut, et un singeReload l’y ramène. Singe diffère d’Hypseus sur ce défaut : le controls.cfg fourni lie déjà ce stick aux quatre contacts de direction, et lui faire piloter aussi le curseur sans qu’on le demande surprendrait chaque jeu existant.

Paramètres :

  • enabled — booléen.

Renvoie : rien.

Depuis : 3.00 (Hypseus) Voir aussi : joyMouseIsEnabled, onMouseMoved, mouseGetPosition

Exemple
-- Un jeu de tir qui laisse le joueur viser au stick quand aucune souris n'est branchée.
if mouseHowMany() == 0 then
    joyMouseEnable(true)
end

2.16.2. joyMouseIsEnabled

enabled = joyMouseIsEnabled()

Indique si le stick pilote le curseur de la souris en ce moment, que cela ait été décidé par --joymouse ou par joyMouseEnable.

Renvoie : booléen.

Depuis : 3.00 Voir aussi : joyMouseEnable

2.17. Clavier

Singe lit le clavier dans l’un de deux modes, choisi avec keyboardSetMode. En MODE_NORMAL (le mode par défaut), les touches sont traduites par les affectations de controls.cfg en valeurs SWITCH_* qui atteignent onInputPressed et onInputReleased, et les touches non affectées sont ignorées ; en MODE_FULL, chaque touche atteint le script brute, par onKeyPressed et onKeyReleased ainsi que par onInputPressed et onInputReleased. Quel que soit le mode, keyboardIsDown, keyboardGetLastDown et keyboardGetLastUp interrogent l’état réel du clavier, ce que veut le modèle à fil d’exécution (voir À fil d’exécution). Un scancode désigne la position physique d’une touche (la touche A est le scancode 4 sur toutes les dispositions) alors qu’un keysym est le caractère que produit la touche ; la table SCANCODE de Framework.singe nomme chaque scancode, keyboardIsDown prend des scancodes, et onKeyPressed livre les deux. Les callbacks eux-mêmes sont décrits sous Callbacks du moteur.

2.17.1. keyboardCatchQuit

keyboardCatchQuit(catch)

Extension Hypseus. Confie le contact de sortie au script, exactement comme le fait singeSetQuitKeyEnabled(not catch) : keyboardCatchQuit(true) empêche le moteur de quitter sur INPUT_QUIT, et false le lui rend. C’est une fonction définie dans Framework.singe, conservée pour que les jeux écrits pour Hypseus Singe tournent sans modification.

Remarques : Alias hérité.

Le nouveau code doit appeler singeSetQuitKeyEnabled.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : singeSetQuitKeyEnabled, singeQuit

Exemple
-- Code de jeu Hypseus ; l'écriture moderne est singeSetQuitKeyEnabled(false).
if keyboardCatchQuit ~= nil then
    keyboardCatchQuit(true)
end

function onInputPressed(what)
    if what == SWITCH_QUIT then
        askToQuit()
    end
end

2.17.2. keyboardGetLastDown

scancode = keyboardGetLastDown()

Renvoie le scancode de la touche enfoncée le plus récemment dans l’image en cours, ou 0 quand rien n’a été enfoncé depuis l’image précédente. La valeur est effacée après chaque appel à onOverlayUpdate, ce qui en fait une interrogation ponctuelle « une touche vient-elle d’être enfoncée ? » pour le modèle à fil d’exécution. Les boutons des manettes et de la souris sont aussi enregistrés ici, sous leurs codes GAMEPAD_N et MOUSE_N, puisque le moteur les fait passer par le même chemin que les touches. La valeur est conservée quels que soient le mode du clavier et les affectations de controls.cfg.

Renvoie : scancode entier, ou 0.

Depuis : 2.10 Voir aussi : keyboardGetLastUp, keyboardIsDown

Exemple
-- Modèle à fil d'exécution : réagir à un appui de touche par image.
function singeMain()
    while true do
        local key = keyboardGetLastDown()
        if key == SCANCODE.ESCAPE.value then
            singeQuit()
        elseif key == SCANCODE.SPACE.value then
            jump()
        end
        singeYield()
    end
end

2.17.3. keyboardGetLastUp

scancode = keyboardGetLastUp()

Renvoie le scancode de la touche relâchée le plus récemment dans l’image en cours, ou 0 quand rien n’a été relâché depuis l’image précédente. La valeur est effacée après chaque appel à onOverlayUpdate, comme celle de keyboardGetLastDown, et enregistre de la même façon les codes des boutons des manettes et de la souris.

Renvoie : scancode entier, ou 0.

Depuis : 2.10 Voir aussi : keyboardGetLastDown, keyboardIsDown

Exemple
-- Un tir chargé part quand on lâche la touche de tir.
function singeMain()
    while true do
        if keyboardIsDown(SCANCODE.LCTRL.value) then
            charge = math.min(charge + 1, chargeMax)
        elseif keyboardGetLastUp() == SCANCODE.LCTRL.value then
            fireShot(charge)
            charge = 0
        end
        singeYield()
    end
end

2.17.4. keyboardGetMode

mode = keyboardGetMode()

Renvoie le mode du clavier en vigueur : MODE_NORMAL (0) ou MODE_FULL (1). Chaque script démarre en MODE_NORMAL, y compris après un rechargement.

Renvoie : mode entier.

Depuis : 1.x (RDG) Voir aussi : keyboardSetMode

Exemple
-- Fonction de saisie de texte partagée qui rétablit le mode qu'avait l'appelant.
function promptForName()
    local previous = keyboardGetMode()
    keyboardSetMode(MODE_FULL)
    entering = true
    restoreMode = previous
end

2.17.5. keyboardGetModifiers

modifiers = keyboardGetModifiers()

Renvoie les touches de modification maintenues en ce moment, sous forme de masque de bits KMOD_* de SDL. Testez-le avec un et bit à bit contre les valeurs de la table MODIFIER : les entrées d’une seule touche comme MODIFIER.LSHIFT et les entrées combinées MODIFIER.SHIFT, MODIFIER.CTRL, MODIFIER.ALT et MODIFIER.GUI, qui couvrent l’un ou l’autre côté. La fonction lit l’état réel, donc elle fonctionne dans tous les modes du clavier et depuis n’importe quel callback.

Renvoie : masque de bits entier.

Depuis : 2.10 Voir aussi : keyboardGetLastDown, onKeyPressed

Exemple
-- Maj+Tab affiche ou masque l'overlay des statistiques.
function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.TAB.value then
        if keyboardGetModifiers() & MODIFIER.SHIFT.value ~= 0 then
            showStats = not showStats
        end
    end
end

2.17.6. keyboardIsDown

down = keyboardIsDown(scancode)

Teste si une touche est physiquement maintenue en ce moment, d’après l’état que le moteur garde pour chaque événement de touche qu’il voit. Elle ne dépend ni du mode du clavier ni de controls.cfg, et elle fonctionne depuis n’importe quel callback ; elle convient donc aux déplacements qui doivent continuer tant qu’une touche est maintenue. Les scancodes hors de la plage que définit SDL renvoient false au lieu de mettre fin au script.

Paramètres :

  • scancode — une valeur de la table SCANCODE, comme SCANCODE.LEFT.value.

Renvoie : booléen.

Depuis : 2.10 Voir aussi : keyboardGetLastDown, controllerGetButton

Exemple
-- Déplacement dans huit directions à partir des touches maintenues.
function onOverlayUpdate()
    local dx = 0
    local dy = 0
    if keyboardIsDown(SCANCODE.LEFT.value)  then dx = dx - 1 end
    if keyboardIsDown(SCANCODE.RIGHT.value) then dx = dx + 1 end
    if keyboardIsDown(SCANCODE.UP.value)    then dy = dy - 1 end
    if keyboardIsDown(SCANCODE.DOWN.value)  then dy = dy + 1 end
    playerX = playerX + dx * speed
    playerY = playerY + dy * speed
    drawPlayer()
    return OVERLAY_UPDATED
end

2.17.7. keyboardSetMode

keyboardSetMode(mode)

Bascule entre les deux modèles de clavier. En MODE_NORMAL, seules les touches affectées dans controls.cfg atteignent le script, sous forme de valeurs SWITCH_*, la répétition des touches est supprimée pour que chaque appui n’arrive qu’une fois, et le moteur agit sur ses propres contacts (pause, sortie, capture d’écran, capture de la souris). En MODE_FULL, chaque touche atteint onInputPressed et onInputReleased sous forme de son keysym, et onKeyPressed et onKeyReleased sous forme de keysym et de scancode, le texte que produit un appui atteint onTextInput, la répétition des touches est livrée pour la saisie de texte, et les affectations clavier des contacts propres au moteur sont ignorées pour que le jeu garde toutes les touches ; les affectations des boutons des manettes et de la souris agissent toujours, et ces boutons atteignent toujours le script sous forme de leurs valeurs SWITCH_*, puisqu’on ne peut pas les taper. La plupart des jeux règlent le mode une fois au démarrage ; un jeu avec saisie de texte passe en MODE_FULL le temps de la saisie, puis revient. Toute autre valeur met fin au script. En MODE_FULL, les keysyms de quatre touches sont aussi des numéros de contact — Retour arrière vaut 8 (SWITCH_BUTTON3), Tab 9 (SWITCH_COIN1), Entrée 13 et Échap 27 — si bien qu’un script qui lit onInputPressed pour un contact de manette ou de souris et qui attend aussi ces touches doit vérifier keyboardIsDown pour la touche avant de traiter la valeur comme le contact.

Paramètres :

  • mode — MODE_NORMAL (0) ou MODE_FULL (1).

Depuis : 1.x (RDG) Voir aussi : keyboardGetMode, onInputPressed, onKeyPressed

Exemple
-- La saisie du meilleur score prend les touches brutes, puis le mode de jeu revient.
function beginInitials()
    initials = ""
    keyboardSetMode(MODE_FULL)
end

function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.RETURN.value then
        keyboardSetMode(MODE_NORMAL)
        saveScore(initials, score)
    elseif keysym >= string.byte("a") and keysym <= string.byte("z") and #initials < 3 then
        initials = initials .. string.char(keysym):upper()
    end
end

2.18. Lumière

Les lumières sont des nœuds portant une lumière, créés par lightNew, puis déplacés, rattachés à un parent et animés avec les appels de nœud. Jusqu’à huit lumières visibles éclairent une image, dans l’ordre des nœuds ; sceneSetAmbient et un ciel venu de sceneSetSky ajoutent une lumière venue de partout. Les lumières directionnelles et les projecteurs éclairent le long du -Z du nœud, donc orientez-les avec nodeLookAt ou nodeSetRotation ; les lumières ponctuelles n’ont besoin que d’une position. Les couleurs sont des entiers de 0 à 255, les intensités des multiplicateurs dans la lumière linéaire de la scène, les angles des degrés et les distances des unités du monde. Chaque appel lightSet* met fin au script pour un nœud qui ne porte pas de lumière. Voir Scènes 3D pour l’éclairage, l’exposition et les ombres.

2.18.1. lightNew

node = lightNew(type)
node = lightNew(type, parent)

Crée un nouveau nœud portant une lumière et renvoie le handle du nœud. La lumière démarre blanche, d’intensité 1, sans limite de portée et, pour un projecteur, avec un cône de 20 à 30 degrés. Placez-la et orientez-la avec les appels de nœud : nodeSetPosition pour une lumière ponctuelle ou un projecteur, nodeLookAt pour une lumière directionnelle ou un projecteur. Une lumière rattachée à un nœud qui bouge bouge avec lui, si bien qu’un phare sur une voiture ou une torche dans une main tient en un appel. Met fin au script pour un type inconnu ou quand aucun nœud ne peut être créé.

Paramètres :

  • type — LIGHT_DIRECTIONAL (un soleil ; seule sa direction compte), LIGHT_POINT (une ampoule qui faiblit avec la distance dans toutes les directions) ou LIGHT_SPOT (un cône le long du -Z du nœud).

  • parent — le nœud parent ; la racine s’il est omis.

Renvoie : Le handle du nœud de la lumière, un entier.

Exemple
-- Lumière principale chaude venue d'en haut à gauche, lumière d'appoint froide venue de la droite,
-- et un phare qui suit la voiture.
key = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(key, -3, 4, 3)
nodeLookAt(key, 0, 0, 0)
lightSetColor(key, 255, 235, 200)
lightSetIntensity(key, 1.4)

fill = lightNew(LIGHT_POINT)
nodeSetPosition(fill, 3, 1, 2)
lightSetColor(fill, 150, 190, 255)
lightSetIntensity(fill, 4)
lightSetRange(fill, 10)

headlight = lightNew(LIGHT_SPOT, car)
nodeSetPosition(headlight, 0.6, 0.5, -1.8)
lightSetIntensity(headlight, 30)

2.18.2. lightSetColor

lightSetColor(node, r, g, b)

La couleur de la lumière, de 0 à 255 par canal (les valeurs hors plage sont ramenées dans la plage), traitée comme du sRGB ; blanche par défaut. La luminosité relève de lightSetIntensity, alors gardez la couleur pour la teinte (une ampoule chaude 255, 230, 190, une lune froide 150, 190, 255) et laissez au moins un canal près de 255. Met fin au script quand le nœud ne porte pas de lumière.

Depuis : 3.00. Voir aussi : lightSetIntensity, lightNew

Exemple
-- L'enseigne au néon passe d'une couleur à l'autre.
signLight = lightNew(LIGHT_POINT)
nodeSetPosition(signLight, 2, 3, -1)
lightSetIntensity(signLight, 8)
lightSetRange(signLight, 6)
neon = { { 255, 40, 120 }, { 40, 220, 255 }, { 255, 210, 40 } }

function onOverlayUpdate()
    local phase = math.floor(singeGetTicks() / 700) % #neon + 1
    lightSetColor(signLight, neon[phase][1], neon[phase][2], neon[phase][3])
    return OVERLAY_UPDATED
end

2.18.3. lightSetCone

lightSetCone(node, innerDegrees, outerDegrees)

La forme du cône d’un projecteur, les deux angles étant mesurés depuis l’axe (le -Z du nœud) : pleine luminosité à l’intérieur de innerDegrees, puis un fondu progressif jusqu’à rien à outerDegrees. Les valeurs par défaut sont 20 et 30. Un faible écart entre les deux donne une poursuite de théâtre aux bords nets, un grand écart une flaque de lumière douce. Les valeurs sont enregistrées pour toutes les lumières, mais seul un LIGHT_SPOT s’en sert. Met fin au script quand le nœud ne porte pas de lumière.

Paramètres :

  • node — le nœud de la lumière.

  • innerDegrees — demi-angle de pleine luminosité, en degrés depuis l’axe.

  • outerDegrees — demi-angle où la lumière n’atteint plus rien, en degrés depuis l’axe ; porté à innerDegrees s’il est plus petit.

Depuis : 3.00. Voir aussi : lightNew, lightSetRange, nodeLookAt

Exemple
-- Une poursuite sur le chanteur, aux bords nets, depuis le pont lumière.
spot = lightNew(LIGHT_SPOT)
nodeSetPosition(spot, 0, 8, 4)
nodeLookAt(spot, nodeGetWorldPosition(singer))
lightSetColor(spot, 255, 245, 220)
lightSetIntensity(spot, 80)
lightSetCone(spot, 8, 10)
lightSetShadow(spot, true)

2.18.4. lightSetIntensity

lightSetIntensity(node, intensity)

Le multiplicateur de luminosité de la lumière dans la lumière linéaire de la scène, 1 par défaut. Une lumière directionnelle d’intensité 1 rend blanche une surface blanche tournée vers elle. Une lumière ponctuelle ou un projecteur faiblit avec la distance selon 1 / (1 + d^2), si bien que son intensité est la luminosité à la lumière elle-même, la moitié à une unité de distance et un centième à dix unités ; les ampoules demandent en général des valeurs bien au-dessus de 1, de 10 à 50 pour une pièce, et sceneSetExposure ramène toute la scène dans la plage. Met fin au script quand le nœud ne porte pas de lumière.

Depuis : 3.00. Voir aussi : lightSetRange, sceneSetExposure, lightSetColor

Exemple
-- Une lanterne qui vacille dans le vent.
lantern = lightNew(LIGHT_POINT, lanternNode)
lightSetColor(lantern, 255, 200, 140)
lightSetRange(lantern, 9)

function onOverlayUpdate()
    local flicker = 10 + math.random() * 3
    lightSetIntensity(lantern, flicker)
    return OVERLAY_UPDATED
end

2.18.5. lightSetRange

lightSetRange(node, range)

La portée d’une lumière ponctuelle ou d’un projecteur, en unités du monde ; 0 (la valeur par défaut) signifie aucune limite. La lumière s’éteint exactement à la portée, en plus de son atténuation avec la distance, si bien que les lumières n’apparaissent pas d’un coup quand des objets la franchissent. Une portée borne aussi jusqu’où doit aller la carte d’ombres d’une lumière qui projette des ombres, ce qui garde ses ombres nettes. Les lumières directionnelles l’ignorent. Met fin au script quand le nœud ne porte pas de lumière.

Depuis : 3.00. Voir aussi : lightSetIntensity, lightSetShadow

Exemple
-- Des réverbères le long de la route, chacun éclairant son propre tronçon.
for i = 0, 9 do
    local lamp = lightNew(LIGHT_POINT)
    nodeSetPosition(lamp, 4, 5, -i * 20)
    lightSetColor(lamp, 255, 220, 170)
    lightSetIntensity(lamp, 20)
    lightSetRange(lamp, 14)
end

2.18.6. lightSetShadow

lightSetShadow(node, shadow)

Fait projeter à la lumière des ombres de tout ce qui est opaque dans la scène, ou l’en empêche ; désactivé par défaut. N’importe laquelle des huit lumières peut projeter des ombres, dans n’importe quelle combinaison. Un projecteur reçoit une carte d’ombres ; une lumière directionnelle reçoit une carte par cascade (sceneSetShadowCascades) ; une lumière ponctuelle reçoit une carte cubique de six vues, qui couvre toutes les directions (une ampoule dans une pièce) pour six fois le coût. nodeSetShadow dispense un maillage de projeter des ombres. Met fin au script quand le nœud ne porte pas de lumière.

Remarques : Chaque carte d’ombres coûte une passe supplémentaire sur la scène par image, une carte cubique six, et un soleil en cascades autant qu’il a de cascades ; la taille des cartes est réglée par sceneSetShadowSize. Un GPU intégré moderne gère sans peine huit lumières projetant des ombres ; un Raspberry Pi en veut une ou deux à 512.

Exemple
-- Le soleil projette des ombres ; les lampes ne font qu'éclairer. Le verre de l'ampoule
-- ne doit pas faire d'ombre à sa propre lampe.
sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 3, 6, 4)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)

lamp = lightNew(LIGHT_POINT)
nodeSetPosition(lamp, 3, 3.1, -2)
lightSetIntensity(lamp, 12)
lightSetRange(lamp, 14)
nodeSetShadow(bulbGlass, false)

2.19. Matériau

Un matériau, c’est l’aspect d’un maillage : une couleur de base avec alpha, une texture de base facultative tirée d’un sprite, d’un fichier KTX2, d’une vidéo ou d’une vue rendue, et les paramètres métal-rugosité de glTF avec quatre cartes facultatives. materialNew renvoie un handle entier ; passez-le à nodeSetMesh ou à nodeSetMaterial, et à chaque appel materialSet*. Les matériaux sont partagés : en modifier un modifie donc chaque maillage dessiné avec lui, et un nœud qui n’en a pas se dessine en blanc, à moitié rugueux. Les couleurs sont des entiers de 0 à 255 par canal et sont traitées comme du sRGB ; les facteurs comme la rugosité vont de 0 à 1. Un mauvais handle met fin au script. Voir Scènes 3D pour la façon dont les matériaux sont éclairés.

2.19.1. materialNew

material = materialNew()

Alloue un nouveau matériau et renvoie son handle. Il démarre blanc et opaque (couleur 255, 255, 255, 255), avec une rugosité de 0.5, une métallicité de 0, aucune couleur émissive, une répétition de 1, 1, un filtrage linéaire, une seule face, éclairé, et sans texture ni cartes. Réglez ce qui en diffère et passez le handle à nodeSetMesh. Les modèles chargés apportent leurs propres matériaux : celui-ci sert donc aux maillages construits par le script. Met fin au script sur une machine sans GPU utilisable.

Renvoie : Le handle du matériau, un entier.

Exemple
-- De l'or brossé pour un trophée, du verre bleu translucide pour sa vitrine.
gold = materialNew()
materialSetColor(gold, 255, 200, 60)
materialSetMetallic(gold, 1)
materialSetRoughness(gold, 0.35)

glass = materialNew()
materialSetColor(glass, 80, 160, 255, 90)
materialSetBlend(glass, true)
materialSetRoughness(glass, 0.1)

trophy = nodeNew()
nodeSetMesh(trophy, meshCone(0.3, 0.8, 24), gold)

2.19.2. materialDelete

materialDelete(material)

Libère le matériau et toute texture qu’il a envoyée au GPU. Chaque nœud qui était dessiné avec lui revient à l’aspect par défaut (blanc, à moitié rugueux) : réaffectez donc d’abord ces nœuds avec nodeSetMaterial s’ils doivent garder un aspect. Le handle n’est plus valide ensuite et met fin au script s’il est réutilisé. Le matériau privé qu’un nœud se crée sous nodeSetSprite ou nodeSetText appartient au nœud et ne peut pas être supprimé ; l’appel met fin au script, et c’est en retirant le sprite ou le texte qu’on le libère. Les matériaux ne coûtent pas cher ; les supprimer compte surtout pour ceux qui portaient de grandes textures.

Depuis : 3.00. Voir aussi : materialNew, nodeSetMaterial

Exemple
-- Changer l'aspect du sol du niveau quand la saison change.
function setSeason(texture)
    local look = materialNew()
    materialSetTexture(look, texture)
    materialSetTiling(look, 16, 16)
    nodeSetMaterial(ground, look)
    if groundLook then
        materialDelete(groundLook)
    end
    groundLook = look
end

2.19.3. materialSetBlend

materialSetBlend(material, blend)

Avec true, le matériau est dessiné translucide, mélangé selon l’alpha de la couleur de base multiplié par l’alpha de la texture, après tous les maillages opaques et trié du plus éloigné au plus proche. Les maillages mélangés n’écrivent pas la profondeur : laissez-le donc à false (la valeur par défaut) pour les surfaces pleines, car un maillage opaque avec le mélange activé peut laisser transparaître ce qui est derrière lui. Servez-vous-en avec un alpha inférieur à 255 venu de materialSetColor ou une texture qui a de la transparence.

Depuis : 3.00. Voir aussi : materialSetColor, materialSetTexture

Exemple
-- Un champ de force qui apparaît en fondu quand il est touché.
field = materialNew()
materialSetColor(field, 60, 200, 255, 0)
materialSetBlend(field, true)
materialSetDoubleSided(field, true)
nodeSetMesh(shield, meshSphere(2, 32), field)

function onShieldHit()
    materialSetColor(field, 60, 200, 255, 160)
end

2.19.4. materialSetColor

materialSetColor(material, r, g, b)
materialSetColor(material, r, g, b, a)

Règle la couleur de base, de 0 à 255 par canal (les valeurs hors plage sont ramenées dans la plage), a valant 255 par défaut. La couleur est traitée comme du sRGB et éclairée en lumière linéaire. Quand le matériau a une texture, une vidéo ou une vue, la couleur la multiplie : le blanc laisse donc l’image telle quelle et une couleur plus sombre la teinte. L’alpha ne se voit qu’avec materialSetBlend.

Paramètres :

  • material — le handle du matériau.

  • r, g, b — rouge, vert et bleu, de 0 à 255.

  • a — opacité, de 0 à 255 ; 255 s’il est omis.

Depuis : 3.00. Voir aussi : materialSetTexture, materialSetBlend, materialSetEmissive

Exemple
-- Les couleurs des équipes sur un seul et même maillage de voiture.
teamLooks = {}
for team, rgb in ipairs({ { 220, 40, 40 }, { 40, 90, 220 }, { 240, 200, 30 } }) do
    local look = materialNew()
    materialSetColor(look, rgb[1], rgb[2], rgb[3])
    materialSetMetallic(look, 0.6)
    materialSetRoughness(look, 0.3)
    teamLooks[team] = look
end
nodeSetMesh(playerCar, carMesh, teamLooks[1])

2.19.5. materialSetCutoff

materialSetCutoff(material, cutoff)

Jette chaque texel dont l’alpha est inférieur à cutoff et dessine le reste entièrement opaque, dans la passe éclairée comme dans la passe d’ombre, si bien qu’une carte de feuillage projette l’ombre de ses feuilles plutôt que celle de son quad. C’est le masquage alpha de glTF : contrairement à materialSetBlend, il n’a besoin d’aucun tri, mais un texel est gardé entier ou jeté, jamais mélangé. Le seuil est borné entre 0 et 1, et 0, la valeur par défaut, désactive le masquage. Un modèle chargé depuis glTF arrive avec le seuil que son fichier donne à un matériau MASK.

Paramètres :

  • material — handle de matériau entier.

  • cutoff — nombre ; l’alpha, de 0 à 1, qu’il faut à un texel pour être dessiné.

Exemple
-- Un grillage :  un seul quad texturé, les trous découpés, les deux faces dessinées.
fence = materialNew()
materialSetTexture(fence, spriteLoad(DIR .. "Art/chainLink.png"))
materialSetCutoff(fence, 0.5)
materialSetDoubleSided(fence, true)
panel = nodeNew()
nodeSetMesh(panel, meshPlane(4, 2), fence)
nodeSetPosition(panel, 0, 1, -5)
nodeSetRotation(panel, 90, 0, 0)

2.19.6. materialSetDoubleSided

materialSetDoubleSided(material, doubleSided)

Dessine les deux faces de chaque triangle au lieu d’éliminer la face arrière. Nécessaire pour les formes ouvertes vues de dos, comme un simple meshPlane vu de dessous, un drapeau ou une carte de feuillage. Les formes fermées ont le même aspect dans les deux cas : laissez-le donc à false (la valeur par défaut) pour elles, car un matériau double face coûte du taux de remplissage et les ombres sont alors projetées par les deux faces aussi.

Depuis : 3.00. Voir aussi : meshPlane, materialSetBlend

Exemple
-- Une banderole suspendue au-dessus de la rue, lisible des deux côtés.
cloth = materialNew()
materialSetTexture(cloth, spriteLoad(DIR .. "Art/banner.png"))
materialSetDoubleSided(cloth, true)
materialSetRoughness(cloth, 0.9)
banner = nodeNew()
nodeSetMesh(banner, meshPlane(3, 1), cloth)
nodeSetPosition(banner, 0, 4, -6)
nodeSetRotation(banner, 90, 0, 0)

2.19.7. materialSetEmissive

materialSetEmissive(material, r, g, b)

La lumière que la surface émet d’elle-même, de 0 à 255 par canal (les valeurs hors plage sont ramenées dans la plage), ajoutée par-dessus l’éclairage : écrans, ampoules, néons, tableaux de bord. La valeur par défaut est le noir, aucune lueur. Elle n’éclaire rien d’autre et ne projette aucune lumière ; placez un nœud de lumière au même endroit pour cela. Avec materialSetEmissiveMap, la carte indique à quels endroits de la surface cette couleur s’applique. Les surfaces émissives assez lumineuses pour franchir le seuil de sceneSetBloom rayonnent.

Remarques : Un matériau non éclairé (materialSetUnlit) ne montre que sa couleur de base ; la couleur émissive y est ignorée.

Depuis : 3.00. Voir aussi : materialSetEmissiveMap, materialSetUnlit, sceneSetBloom

Exemple
-- Un voyant d'alerte qui pulse en rouge quand le réacteur surchauffe.
lampLook = materialNew()
materialSetColor(lampLook, 60, 10, 10)
nodeSetMesh(lamp, meshSphere(0.15, 16), lampLook)

function onOverlayUpdate()
    local pulse = (math.sin(singeGetTicks() / 120) + 1) / 2
    if overheating then
        materialSetEmissive(lampLook, math.floor(255 * pulse), 20, 20)
    else
        materialSetEmissive(lampLook, 0, 0, 0)
    end
    return OVERLAY_UPDATED
end

2.19.8. materialSetEmissiveMap

materialSetEmissiveMap(material, sprite)
materialSetEmissiveMap(material, "file.ktx2")
materialSetEmissiveMap(material, nil)
materialSetEmissiveMap(material)

Une texture qui indique quelles parties de la surface luisent. Sa couleur est multipliée par la couleur de materialSetEmissive : réglez donc celle-ci aussi, en blanc pour utiliser les couleurs propres de la carte, ou en une teinte. L’image vient d’un sprite chargé (une copie est envoyée au GPU, si bien que le sprite peut être déchargé ensuite) ou d’un fichier .ktx2 désigné par son nom, gardé compressé sur le GPU. Avec nil ou sans second argument, la carte est retirée. Met fin au script quand la texture ne peut pas être envoyée au GPU ou que le fichier n’est pas une texture KTX2.

Depuis : 3.00. Voir aussi : materialSetEmissive, materialSetTexture, materialSetTiling

Exemple
-- Un pupitre de commande dont les boutons et les afficheurs s'allument.
panel = materialNew()
materialSetTexture(panel, spriteLoad(DIR .. "Art/panel.png"))
materialSetEmissiveMap(panel, spriteLoad(DIR .. "Art/panelLights.png"))
materialSetEmissive(panel, 255, 255, 255)
materialSetRoughness(panel, 0.6)
nodeSetMesh(nodeFind("Panel", cockpit), meshPlane(1.2, 0.4), panel)

function onPowerDown()
    materialSetEmissive(panel, 0, 0, 0)
end

2.19.9. materialSetFilter

materialSetFilter(material, filter)

La façon dont les textures du matériau sont échantillonnées. FILTER_LINEAR (la valeur par défaut) mélange les texels entre eux et les niveaux de mipmap entre eux, avec un filtrage anisotrope sur les surfaces vues sous un angle rasant. FILTER_NEAREST prend le texel le plus proche et le niveau de mipmap le plus proche, si bien que le pixel art reste net sur un quad. Chaque texture porte une chaîne de mipmaps complète, donc une texture vue en petit ne scintille jamais, dans un cas comme dans l’autre. Toute autre valeur met fin au script.

Depuis : 3.00. Voir aussi : materialSetTexture, materialSetUnlit

Exemple
-- Une tuile de 16 pixels sur 16 dessinée sur un bloc sans bavure.
pixelLook = materialNew()
materialSetTexture(pixelLook, spriteLoad(DIR .. "Art/dirt16.png"))
materialSetFilter(pixelLook, FILTER_NEAREST)
materialSetRoughness(pixelLook, 1)
block = nodeNew()
nodeSetMesh(block, meshBox(1, 1, 1), pixelLook)

2.19.10. materialSetGui

materialSetGui(material, gui)
materialSetGui(material, nil)
materialSetGui(material)

Affiche une interface créée par guiNew comme texture de couleur de base du matériau, mise à jour à chaque image : un moniteur, un tableau de bord de cockpit, une enseigne, avec le même document qu’un guiDraw afficherait à plat. Généralement associé à materialSetUnlit pour que la page ne soit pas ombrée par les lumières, et teinté par la couleur de base comme toute texture. Avec nil ou sans second argument, le matériau revient à sa propre texture, conservée en dessous ; supprimer l’interface fait de même. Régler une interface abandonne toute vidéo ou vue que le matériau affichait. Tant que l’interface prend les entrées, la souris ou un pistolet optique pointé sur une surface dessinée avec le matériau l’atteint par le même sondage que sceneProbeGui. Met fin au script pour un handle d’interface qui n’est pas valide.

Exemple
-- La page des options sur l'écran de la borne modélisée.
options = guiNew(720, 480)
page    = guiLoad(options, DIR .. "gui/options.rml")
screen  = materialNew()
materialSetGui(screen, options)
materialSetUnlit(screen, true)
nodeSetMesh(nodeFind("Screen", cabinet), meshPlane(3.0, 2.0), screen)

2.19.11. materialSetMetallic

materialSetMetallic(material, metallic)

À quel point la surface est métallique, de 0 pour les diélectriques (peinture, plastique, bois, peau) à 1 pour les métaux, qui teintent leurs reflets et leurs réflexions de la couleur de base. La valeur par défaut est 0. Les valeurs intermédiaires servent aux mélanges et aux surfaces usées ; la plupart des matériaux veulent l’une ou l’autre extrémité. Avec materialSetMetallicRoughnessMap, le canal bleu de la carte multiplie cette valeur. Un métal a peu de choses à refléter sans un ciel venu de sceneSetSky : associez donc les deux.

Exemple
-- Pare-chocs chromé, carrosserie peinte.
chrome = materialNew()
materialSetColor(chrome, 240, 240, 245)
materialSetMetallic(chrome, 1)
materialSetRoughness(chrome, 0.15)

paint = materialNew()
materialSetColor(paint, 30, 80, 200)
materialSetMetallic(paint, 0)
materialSetRoughness(paint, 0.4)
nodeSetMaterial(nodeFind("Bumper", car), chrome)
nodeSetMaterial(nodeFind("Body", car), paint)

2.19.12. materialSetMetallicRoughnessMap

materialSetMetallicRoughnessMap(material, sprite)
materialSetMetallicRoughnessMap(material, "file.ktx2")
materialSetMetallicRoughnessMap(material, nil)
materialSetMetallicRoughnessMap(material)

Une texture qui fait varier le fini sur la surface : son canal vert multiplie la rugosité de materialSetRoughness et son canal bleu la métallicité de materialSetMetallic, comme glTF les range, si bien qu’une carte produite par un outil glTF fonctionne telle quelle. Réglez les deux facteurs sur 1 pour n’utiliser que les valeurs de la carte. L’image vient d’un sprite ou d’un fichier .ktx2 désigné par son nom ; nil ou l’absence de second argument retire la carte. Met fin au script quand la texture ne peut pas être envoyée au GPU.

Exemple
-- Un blindage métallique rayé : brillant là où la peinture est partie.
plating = materialNew()
materialSetTexture(plating, DIR .. "Textures/plating.ktx2")
materialSetMetallicRoughnessMap(plating, DIR .. "Textures/platingMetalRough.ktx2")
materialSetMetallic(plating, 1)
materialSetRoughness(plating, 1)
materialSetNormalMap(plating, DIR .. "Textures/platingNormal.ktx2")
nodeSetMesh(hullPanel, meshPlane(4, 2), plating)

2.19.13. materialSetNormalMap

materialSetNormalMap(material, sprite)
materialSetNormalMap(material, sprite, strength)
materialSetNormalMap(material, "file.ktx2")
materialSetNormalMap(material, "file.ktx2", strength)
materialSetNormalMap(material, nil)
materialSetNormalMap(material)

Une carte de normales en espace tangent (le genre bleuté habituel, plat à 128, 128, 255) qui incline l’éclairage texel par texel, si bien que briques, rainures et rivets accrochent la lumière sans géométrie supplémentaire. Chaque maillage a des tangentes pour cela : celles du modèle quand le fichier en porte, sinon calculées à partir des UV. L’image vient d’un sprite ou d’un fichier .ktx2 désigné par son nom ; nil ou l’absence de second argument retire la carte. Met fin au script quand la texture ne peut pas être envoyée au GPU.

Paramètres :

  • material — le handle du matériau.

  • sprite ou "file.ktx2" — la carte, tirée d’un sprite chargé ou d’un fichier KTX2 ; nil ou rien la retire.

  • strength — à quel point les reliefs inclinent l’éclairage : 1 (la valeur par défaut) tel que créé, 0 à plat, au-dessus de 1 exagéré.

Exemple
-- Un mur de briques fait d'un plan plat, ses joints de mortier accrochant le soleil rasant.
brick = materialNew()
materialSetTexture(brick, spriteLoad(DIR .. "Art/brick.png"))
materialSetNormalMap(brick, spriteLoad(DIR .. "Art/brickNormal.png"), 1.5)
materialSetRoughness(brick, 0.9)
materialSetTiling(brick, 6, 2)
wall = nodeNew()
nodeSetMesh(wall, meshPlane(12, 4), brick)
nodeSetPosition(wall, 0, 2, -3)
nodeSetRotation(wall, 90, 0, 0)

2.19.14. materialSetOccluder

materialSetOccluder(material, occluder)

Fait écrire au matériau la profondeur et aucune couleur. Tout ce que le maillage couvre est caché comme si le maillage était plein, mais le maillage lui-même ne se voit pas : ce qui a été dessiné derrière lui — un décor peint, le disque — transparaît. C’est la doublure de quelque chose qui est dans une image mais pas dans la scène : un pilier dans une pièce peinte derrière lequel un personnage 3D doit passer, une embrasure de porte, une table. Un occulteur ne projette aucune ombre, puisque la peinture en a déjà une, et ne reçoit aucune lumière. false (la valeur par défaut) rend le matériau de nouveau ordinaire.

Depuis : 3.00. Voir aussi : materialSetBlend, materialSetUnlit

Exemple
-- Un pilier qui est dans la peinture : une boîte invisible là où il se dresse, pour
-- que le héros disparaisse derrière et réapparaisse de l'autre côté.
hidden = materialNew()
materialSetOccluder(hidden, true)
pillar = nodeNew()
nodeSetMesh(pillar, meshBox(0.8, 4, 0.8), hidden)
nodeSetPosition(pillar, 2, 2, -3)

2.19.15. materialSetOcclusionMap

materialSetOcclusionMap(material, sprite)
materialSetOcclusionMap(material, sprite, strength)
materialSetOcclusionMap(material, "file.ktx2")
materialSetOcclusionMap(material, "file.ktx2", strength)
materialSetOcclusionMap(material, nil)
materialSetOcclusionMap(material)

Une carte d’occlusion ambiante, l’occlusion dans le canal rouge (blanc pour le dégagé, sombre pour les recoins), qui assombrit la lumière ambiante et celle du ciel dans les coins et les replis. La lumière directe des nœuds de lumière n’est pas affectée, comme dans glTF. L’image vient d’un sprite ou d’un fichier .ktx2 désigné par son nom ; nil ou l’absence de second argument retire la carte. Met fin au script quand la texture ne peut pas être envoyée au GPU.

Paramètres :

  • material — le handle du matériau.

  • sprite ou "file.ktx2" — la carte, tirée d’un sprite chargé ou d’un fichier KTX2 ; nil ou rien la retire.

  • strength — quelle part de la carte appliquer, de 0 (rien) à 1 (la valeur par défaut, en entier).

Depuis : 3.00. Voir aussi : materialSetNormalMap, sceneSetAmbient, sceneSetEnvironment

Exemple
-- Ombrage précalculé pour les parois de la grotte, à moitié pour que les lampes atteignent encore les coins.
rock = materialNew()
materialSetTexture(rock, DIR .. "Textures/caveRock.ktx2")
materialSetNormalMap(rock, DIR .. "Textures/caveRockNormal.ktx2")
materialSetOcclusionMap(rock, DIR .. "Textures/caveRockAO.ktx2", 0.5)
materialSetRoughness(rock, 1)
nodeSetMaterial(nodeFind("Walls", cave), rock)

2.19.16. materialSetRoughness

materialSetRoughness(material, roughness)

À quel point la surface est rugueuse, de 0 pour un reflet serré comme un miroir à 1 pour une surface mate. La valeur par défaut est 0.5. Les reflets suivent le modèle GGX : les valeurs basses donnent un petit point brillant et des réflexions du ciel nettes, les valeurs hautes un lustre large et doux et des réflexions floues. Avec materialSetMetallicRoughnessMap, le canal vert de la carte multiplie cette valeur.

Depuis : 3.00. Voir aussi : materialSetMetallic, materialSetMetallicRoughnessMap

Exemple
-- Mouiller la route quand il pleut : le même asphalte, des reflets plus serrés.
asphalt = materialNew()
materialSetColor(asphalt, 50, 50, 55)
materialSetRoughness(asphalt, 0.95)
nodeSetMesh(road, meshPlane(8, 200), asphalt)

function onWeatherChange(raining)
    if raining then
        materialSetRoughness(asphalt, 0.25)
    else
        materialSetRoughness(asphalt, 0.95)
    end
end

2.19.17. materialSetTexture

materialSetTexture(material, sprite)
materialSetTexture(material, "file.ktx2")
materialSetTexture(material, nil)
materialSetTexture(material)

Utilise l’image d’un sprite comme texture de couleur de base (une copie est envoyée au GPU, si bien que le sprite peut être déchargé ensuite), ou un fichier KTX2 désigné par son nom, gardé compressé sur le GPU dans le format par blocs dont dispose la machine (voir Textures compressées dans Scènes 3D). Avec nil ou sans second argument, la texture est retirée et le matériau ne montre que sa couleur de base. Régler une texture abandonne aussi toute vidéo ou vue que le matériau affichait. Les coordonnées de texture viennent du maillage ; les primitives plaquent une image une fois sur chaque face, et materialSetTiling la répète. Un nom qui n’est pas un fichier KTX2 met fin au script (chargez les autres images avec spriteLoad), tout comme un envoi au GPU qui échoue.

Exemple
-- Une caisse texturée avec un sprite que le jeu charge déjà pour le menu,
-- et un sol tiré d'une texture compressée livrée avec le jeu.
crateArt  = spriteLoad(DIR .. "Art/crate.png")
crateLook = materialNew()
materialSetTexture(crateLook, crateArt)
crate = nodeNew()
nodeSetMesh(crate, meshBox(1, 1, 1), crateLook)

floorLook = materialNew()
materialSetTexture(floorLook, DIR .. "Textures/tiles.ktx2")
materialSetTiling(floorLook, 10, 10)
nodeSetMesh(floor, meshPlane(20, 20), floorLook)

2.19.18. materialSetTiling

materialSetTiling(material, u, v)

Combien de fois les textures du matériau (la texture de base comme les cartes) se répètent sur la plage UV de 0 à 1 d’une surface, 1 et 1 par défaut. 24, 24 sur une carte de hauteurs de 120 unités de large répète une texture toutes les cinq unités. Les textures se répètent au-delà de leurs bords : l’image doit donc se raccorder proprement. Les valeurs inférieures à 1 montrent une partie de l’image ; les valeurs négatives la retournent en miroir.

Paramètres :

  • material — le handle du matériau.

  • u — répétitions dans la direction U de la surface.

  • v — répétitions dans la direction V de la surface.

Depuis : 3.00. Voir aussi : materialSetTexture, meshHeightmap

Exemple
-- De l'herbe toutes les cinq unités sur les collines.
ground = materialNew()
materialSetTexture(ground, DIR .. "Textures/grass.ktx2")
materialSetTiling(ground, 24, 24)
materialSetRoughness(ground, 0.95)
hills = nodeNew()
nodeSetMesh(hills, meshHeightmap(DIR .. "Art/hills.png", 120, 14, 120), ground)
bodyNew(hills, BODY_STATIC, SHAPE_MESH)

2.19.19. materialSetUnlit

materialSetUnlit(material, unlit)

Montre la couleur de base et la texture exactement telles qu’elles sont, en ignorant toutes les lumières, la lumière ambiante et le ciel : pour les écrans vidéo, les moniteurs qui montrent une vue, les skybox et les rendus en aplat. Le brouillard s’applique toujours. La couleur émissive et les cartes ne servent pas sur un matériau non éclairé. La valeur par défaut est false.

Depuis : 3.00. Voir aussi : materialSetEmissive, materialSetVideo, materialSetView

Exemple
-- Le fronton de la borne d'arcade : une image éclairée de l'intérieur, que les
-- lumières de la pièce ne doivent donc pas ombrer.
marquee = materialNew()
materialSetTexture(marquee, spriteLoad(DIR .. "Art/marquee.png"))
materialSetUnlit(marquee, true)
nodeSetMesh(nodeFind("Marquee", cabinet), meshPlane(0.7, 0.2), marquee)

2.19.20. materialSetView

materialSetView(material, view)
materialSetView(material, nil)
materialSetView(material)

Affiche une vue rendue par viewNew comme texture de couleur de base du matériau, mise à jour à chaque image : un moniteur de surveillance, un rétroviseur, un portail. Généralement associé à materialSetUnlit pour que l’image ne soit pas ombrée par les lumières, et teinté par la couleur de base comme toute texture. Avec nil ou sans second argument, le matériau revient à sa propre texture, conservée en dessous. Régler une vue abandonne toute vidéo que le matériau affichait. Met fin au script pour un handle de vue qui n’est pas valide.

Depuis : 3.00. Voir aussi : viewNew, viewSetCamera, materialSetVideo, materialSetUnlit

Exemple
-- Un rétroviseur sur la voiture du joueur.
rearCamera = nodeNew(car)
nodeSetPosition(rearCamera, 0, 1.2, -0.5)
nodeSetRotation(rearCamera, 0, 180, 0)
rearView = viewNew(384, 256)
viewSetCamera(rearView, rearCamera)
mirror = materialNew()
materialSetView(mirror, rearView)
materialSetUnlit(mirror, true)
nodeSetMesh(nodeFind("Mirror", car), meshPlane(0.3, 0.1), mirror)

2.19.21. materialSetVideo

materialSetVideo(material)
materialSetVideo(material, video)

Utilise le laserdisc (sans video) ou une vidéo chargée avec videoLoad comme texture de couleur de base, mise à jour à chaque image pendant la lecture. Généralement associé à materialSetUnlit pour que l’image ne soit pas teintée par les lumières. La vidéo continue de jouer, qu’elle soit aussi dessinée sur l’overlay ou non, et plusieurs matériaux peuvent montrer la même. Régler une vidéo abandonne toute texture ou vue qu’avait le matériau ; materialSetTexture la retire de nouveau.

Remarques : La forme disque met fin au script dans un jeu sans disque, tout comme un mauvais handle de vidéo.

Depuis : 3.00. Voir aussi : videoLoad, materialSetUnlit, materialSetTexture

Exemple
-- Une borne modélisée dont l'écran montre le laserdisc, et un mur de
-- moniteurs qui passent en boucle un extrait du mode attraction.
cabinet = modelInstance(modelLoad(DIR .. "Models/Cabinet.glb"))
screen  = materialNew()
materialSetVideo(screen)
materialSetUnlit(screen, true)
nodeSetMesh(nodeFind("Screen", cabinet), meshPlane(0.6, 0.45), screen)

attract = videoLoad(DIR .. "Video/attract.mp4")
videoPlay(attract)
monitors = materialNew()
materialSetVideo(monitors, attract)
materialSetUnlit(monitors, true)

2.20. Maillage

Un maillage, c’est de la géométrie sur le GPU : une primitive que construit le moteur, un terrain tiré d’une image, ou des données de sommets venues de votre script. Les handles sont des entiers renvoyés par les constructeurs mesh* ; n’importe quel nombre de nœuds peut partager un même maillage, et les nœuds qui dessinent le même maillage avec le même matériau se dessinent en un seul appel instancié : créez donc un maillage et beaucoup de nœuds. Les tailles sont en unités de la scène et chaque primitive est centrée sur l’origine de son nœud sauf indication contraire, si bien que la transformation du nœud la place, la tourne et la met à l’échelle. Les coordonnées de texture vont de 0 à 1 une fois sur chaque face ou surface. Chaque constructeur a besoin du moteur de rendu 3D décrit dans Scènes 3D et met fin au script quand il n’est pas disponible.

2.20.1. meshBox

mesh = meshBox(width, height, depth)

Une boîte de width selon X, height selon Y et depth selon Z, centrée sur l’origine. Chacune des six faces a ses quatre sommets à elle avec une normale plate, si bien que les arêtes sont ombrées nettement, et la texture est posée une fois sur chaque face. Caisses, murs, sols et carrosseries de voiture sont tous des boîtes.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : nodeSetMesh, meshPlane, bodyNew

Exemple
-- Une dalle de sol en pierre et une pile de caisses qui partagent un même maillage.
local floor = nodeNew()
nodeSetMesh(floor, meshBox(16, 0.2, 10), stone)
nodeSetPosition(floor, 0, -0.1, 0)
local crateMesh = meshBox(0.6, 0.6, 0.6)
for i = 1, 4 do
    local crate = nodeNew()
    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, 0, i * 0.6 - 0.3, -2)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
end

2.20.2. meshCone

mesh = meshCone(radius, height)
mesh = meshCone(radius, height, segments)

Un cône dressé sur Y avec une base fermée : le cercle de base de rayon radius à -height / 2 et la pointe à +height / 2. segments (24 par défaut, au moins 3) est le nombre de facettes qui en font le tour ; les côtés sont ombrés de façon lisse d’une facette à l’autre. La texture s’enroule une fois autour des côtés et est posée une fois sur la base. Au-delà de 1024, segments est ramené à 1024.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : meshCylinder, nodeSetMesh

Exemple
-- Un abat-jour au-dessus de l'ampoule, et une rangée de pins faits chacun d'un cône.
local shade = nodeNew(stand)
nodeSetMesh(shade, meshCone(0.45, 0.5, 24), brass)
nodeSetPosition(shade, 0, 0.9, 0)
local foliage = meshCone(0.8, 2.0, 12)
for i = 1, 5 do
    local tree = nodeNew()
    nodeSetMesh(tree, foliage, pine)
    nodeSetPosition(tree, i * 3 - 9, 1.0, -6)
end

2.20.3. meshCylinder

mesh = meshCylinder(radius, height)
mesh = meshCylinder(radius, height, segments)

Un cylindre selon Y, fermé aux deux bouts, de -height / 2 à +height / 2. segments (24 par défaut, au moins 3) est le nombre de facettes qui en font le tour, ombrées de façon lisse. Pour une roue ou une pièce de monnaie, tournez le nœud de 90 degrés autour de X ou de Z pour que l’axe soit là où il vous le faut. Au-delà de 1024, segments est ramené à 1024.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : meshCone, meshTorus, nodeSetRotation

Exemple
-- Un lampadaire, et un pneu couché sur le flanc pour faire une roue.
local post = nodeNew()
nodeSetMesh(post, meshCylinder(0.08, 3, 10), dark)
nodeSetPosition(post, 3, 1.5, -2)
local tire = nodeNew(wheel)
nodeSetMesh(tire, meshCylinder(0.35, 0.25, 16), rubber)
nodeSetRotation(tire, 0, 0, 90)

2.20.4. meshDelete

meshDelete(mesh)

Libère les tampons GPU du maillage et sa copie côté CPU. Les nœuds qui l’utilisaient se retrouvent sans maillage (et sans poids de morphing) et ne dessinent rien tant qu’on ne leur en donne pas un autre ; le handle devient invalide et peut être réutilisé par un constructeur ultérieur. Les maillages ne sont pas libérés quand un nœud est supprimé : supprimez donc vous-même un maillage quand plus rien ne s’en servira.

Depuis : 3.00. Voir aussi : meshNew, nodeSetMesh, nodeDelete

Exemple
-- Reconstruire la piste à partir d'une nouvelle carte de hauteurs entre deux manches.
function loadTrack(image)
    if trackMesh then
        meshDelete(trackMesh)
    end
    trackMesh = meshHeightmap(image, 200, 20, 200)
    nodeSetMesh(track, trackMesh, tarmac)
    bodyNew(track, BODY_STATIC, SHAPE_MESH)
end

2.20.5. meshHeightmap

mesh = meshHeightmap(image, sizeX, sizeY, sizeZ)

Un maillage de terrain tiré d’une image en niveaux de gris, de 2 à 1025 pixels dans chaque sens : un sommet par pixel, répartis sur sizeX par sizeZ unités centrées sur le nœud, chacun élevé de la valeur du canal rouge du pixel (de 0 pour le noir à 255 pour le blanc) multipliée par sizeY, la ligne du haut de l’image étant au bord lointain (-Z). Les normales sont calculées à partir des pentes et les coordonnées de texture vont de 0 à 1 sur l’ensemble, si bien que materialSetTiling règle la répétition de la texture. Les échantillons de hauteur sont conservés : terrainGetHeight les lit, et un corps SHAPE_MESH sur le nœud devient un champ de hauteurs. Un fichier qui ne peut pas être ouvert ou décodé, une mauvaise taille ou l’absence de moteur de rendu 3D met fin au script.

Paramètres :

  • image — le nom de l’image relatif au jeu, dans n’importe quel format que lit spriteLoad.

  • sizeX — la largeur du terrain selon X, en unités du monde.

  • sizeY — la hauteur d’un pixel blanc au-dessus d’un pixel noir.

  • sizeZ — la profondeur du terrain selon Z, en unités du monde.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : terrainGetHeight, materialSetTiling, bodyNew

Exemple
local ground = materialNew()
materialSetTexture(ground, spriteLoad("grass.png"))
materialSetTiling(ground, 24, 24)
materialSetRoughness(ground, 0.95)
local hills = nodeNew()
nodeSetMesh(hills, meshHeightmap("hills.png", 120, 14, 120), ground)
bodyNew(hills, BODY_STATIC, SHAPE_MESH)
-- Les pieds du dragon sur la pente, où que se trouve le sol à cet endroit.
nodeSetPosition(dragon, -8, terrainGetHeight(hills, -8, 3) or 0, 3)

2.20.6. meshNew

mesh = meshNew(positions, normals, uvs, indices)

Construit une géométrie à partir de tables de nombres. Les tangentes que demandent les cartes de normales sont calculées pour vous, de même que des normales lisses quand normals vaut nil, en faisant la moyenne des triangles qui partagent chaque sommet. Les triangles sont de face quand leurs sommets tournent dans le sens inverse des aiguilles d’une montre, vus de l’extérieur ; donnez au matériau materialSetDoubleSided si la face arrière doit se voir. Une table de mauvaise forme, ou un indice hors de la liste des sommets, met fin au script avec un message qui dit lequel des deux.

Paramètres :

  • positions — x, y, z pour chaque sommet, les uns après les autres ; au moins un sommet.

  • normals — x, y, z par sommet, autant que dans positions, ou nil pour les faire calculer.

  • uvs — u, v par sommet (de 0 à 1, v vers le bas de l’image), ou nil pour aucune (chaque sommet à 0, 0).

  • indices — trois numéros de sommet par triangle, comptés à partir de 1 dans l’ordre où les sommets apparaissent dans positions ; au moins un triangle.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : nodeSetMesh, materialSetDoubleSided, meshDelete

Exemple
-- Une flèche plate pointant selon +X, vue de dessus (double face pour qu'elle marche aussi vue de dessous).
local arrow = meshNew(
    { 0, 0, -0.5,   1, 0, 0,   0, 0, 0.5,   -0.6, 0, -0.5,   -0.6, 0, 0.5 },
    nil,
    nil,
    { 1, 2, 3,   4, 1, 3,   4, 3, 5 })
local marker = materialNew()
materialSetColor(marker, 255, 200, 40)
materialSetDoubleSided(marker, true)
local pointer = nodeNew()
nodeSetMesh(pointer, arrow, marker)
nodeSetPosition(pointer, 0, 0.05, 0)

2.20.7. meshPlane

mesh = meshPlane(width, depth)
mesh = meshPlane(width, depth, columns)
mesh = meshPlane(width, depth, columns, rows)

Un rectangle plat dans le plan XZ tourné vers +Y, de width selon X et depth selon Z, centré sur l’origine, avec la texture posée une fois dessus. Deux arguments donnent un seul quad. columns (et rows, qui vaut columns par défaut) le subdivisent en autant de quads dans chaque sens, ce dont un corps mou (softNew) a besoin pour se plier comme du tissu ; les deux doivent valoir au moins 1. Tournez le nœud de 90 degrés autour de X pour le dresser face à +Z. Il n’a qu’une face, sauf si son matériau est double face.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : materialSetDoubleSided, materialSetVideo, softNew

Exemple
-- Le sol, un écran qui montre le disque, et un drapeau qui deviendra du tissu.
local plain = nodeNew()
nodeSetMesh(plain, meshPlane(60, 60), ground)
local tv = nodeNew()
nodeSetMesh(tv, meshPlane(3.0, 2.2), screen)
nodeSetPosition(tv, 0, 1.6, -4)
nodeSetRotation(tv, 90, 0, 0)
local flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), cloth)
nodeSetPosition(flag, 0.8, 2.5, 0)
nodeSetRotation(flag, 90, 0, 0)

2.20.8. meshSphere

mesh = meshSphere(radius)
mesh = meshSphere(radius, segments)

Une sphère de rayon radius, centrée sur l’origine, construite à partir de bandes de latitude et de longitude : segments (32 par défaut, au moins 3) autour de l’équateur et moitié moins d’un pôle à l’autre. La texture s’enroule une fois autour, v allant du pôle du haut à celui du bas. Moins de segments donnent un maillage plus léger pour des balles vues de loin ; davantage donnent une silhouette plus lisse de près. Au-delà de 1024, segments est ramené à 1024.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : meshTorus, nodeSetMesh, bodyNew

Exemple
-- Une boule de verre sur le sol, et une petite sphère de repère qui partage un aspect.
local ball = nodeNew()
nodeSetMesh(ball, meshSphere(0.7, 48), glass)
nodeSetPosition(ball, -1.5, 0.7, 0)
bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.7)
local dot = nodeNew()
nodeSetMesh(dot, meshSphere(0.08, 16), marker)
nodeSetPosition(dot, 0, 1.2, 0)

2.20.9. meshTorus

mesh = meshTorus(radius, tubeRadius)
mesh = meshTorus(radius, tubeRadius, segments)

Un anneau couché dans le plan XZ autour de Y, centré sur l’origine : radius du centre au milieu du tube et tubeRadius le rayon du tube lui-même. segments (32 par défaut, au moins 3) font le tour de l’anneau et moitié moins (au moins 3) le tour du tube. La texture s’enroule une fois autour de l’anneau en u et une fois autour du tube en v. Au-delà de 1024, segments est ramené à 1024.

Renvoie : Le handle du maillage.

Depuis : 3.00. Voir aussi : meshSphere, meshCylinder

Exemple
-- Un anneau d'or dressé sur la tranche, que la boule doit traverser en roulant.
local gold = materialNew()
materialSetColor(gold, 255, 200, 80)
materialSetMetallic(gold, 1)
materialSetRoughness(gold, 0.25)
local ring = nodeNew()
nodeSetMesh(ring, meshTorus(1.2, 0.25, 40), gold)
nodeSetPosition(ring, 0, 1.2, -2)
nodeSetRotation(ring, 90, 0, 0)

2.21. Microphone

Un microphone, pour un jeu de chant ou pour tout ce qui écoute. Un seul périphérique d’enregistrement est ouvert à la fois, entendu comme un seul canal à 48000 échantillons par seconde quoi que donne le matériel ; SDL convertit. Singe garde les huit dernières secondes de ce qu’il entend, et chaque appel ci-dessous répond à partir de cela, si bien que poser la question ne coûte rien que le jeu n’ait déjà payé.

Ce qu’un jeu veut en général, c’est micPitch — la note chantée — et micLevel. Un jeu qui analyse lui-même le son, ou qui l’envoie quelque part, lit les échantillons avec micRead ; les appels Voix les encodent pour un réseau.

Le microphone se ferme quand le jeu se termine. Rien n’est ouvert tant qu’un script ne le demande pas.

Une note chantée parvient au jeu un peu après avoir été chantée : la carte son, le pilote et les tampons la retiennent chacun un instant. Un jeu de chant qui juge la synchronisation retranche ce délai. micCalibrate le mesure en jouant des clics par les haut-parleurs et en chronométrant leur retour, et la réponse est conservée pour la machine, comme le calibrage audio. Le retour audio et le calibrage n’ont été testés jusqu’ici que sans vrai matériel ; la hauteur, le niveau, la lecture et l’enregistrement ont été testés avec un signal connu.

2.21.1. micCalibrate

started = micCalibrate()

Mesure la latence du microphone : joue cinq clics par les haut-parleurs, à une fraction de seconde d’intervalle, et chronomètre le retour de chacun par le microphone. Cela prend quelques secondes ; micCalibration dit quand c’est fini. La réponse est la médiane des clics entendus, et elle est conservée pour cette machine. Faites-le dans une pièce calme, avec les haut-parleurs assez forts pour que le microphone les entende.

Renvoie : true quand il a démarré ; false sans microphone ouvert ou sans haut-parleur pour jouer les clics.

Depuis : 3.00. Voir aussi : micCalibration, micLatency

2.21.2. micCalibration

state, latency = micCalibration()

Où en est un calibrage.

Renvoie : state, l’un de "idle", "running", "done" ou "failed" (moins de trois des clics ont été entendus en retour), et la latence en millisecondes une fois qu’elle est connue, nil sinon.

Depuis : 3.00. Voir aussi : micCalibrate

Exemple
local state, latency = micCalibration()
if state == "done" then
	message = "Your microphone runs " .. latency .. " ms behind."
elseif state == "failed" then
	message = "I could not hear the clicks.  Turn the speakers up and try again."
end

2.21.3. micClose

micClose()

Arrête d’écouter, et arrête avec lui tout enregistrement et tout retour audio. Le microphone se ferme aussi quand le jeu se termine.

Depuis : 3.00.

2.21.4. micIsOpen

open = micIsOpen()

Renvoie : true tant qu’un microphone est ouvert.

Depuis : 3.00.

2.21.5. micLatency

milliseconds = micLatency()

Renvoie : le temps qui sépare un son produit du moment où le jeu l’entend, tel que mesuré sur cette machine par micCalibrate (à n’importe quel moment, dans n’importe quel jeu), ou réglé par micSetLatency ; nil jusque-là.

Depuis : 3.00.

2.21.6. micLevel

rms, peak = micLevel()

Quelle était l’intensité du dernier instant entendu.

Renvoie : la valeur RMS et la crête du dernier bloc d’échantillons, chacune de 0 à 1. Un son continu à pleine échelle donne environ 0.71 en RMS. Les deux valent 0 sans microphone ouvert.

Depuis : 3.00.

2.21.7. micList

names = micList()

Renvoie : une liste des noms des microphones de cette machine, pour micOpen. Elle est refaite à chaque fois, si bien qu’un microphone branché depuis le dernier appel y apparaît.

Depuis : 3.00.

2.21.8. micMonitor

ok = micMonitor(on [, volume])

Joue ce qu’entend le microphone par les haut-parleurs, pour qu’un chanteur s’entende par-dessus la musique. Désactivé tant qu’on ne le demande pas : sur la plupart des machines, la voix revient avec assez de retard pour être gênante, et sur un portable les haut-parleurs repassent dans le microphone. Tout ce qui attendrait plus d’un dixième de seconde avant d’être joué est abandonné plutôt qu’entendu en retard.

Paramètres :

  • on — booléen.

  • volume — nombre, de 0 à 1 ; 1 s’il n’est pas donné.

Renvoie : true, ou false sans microphone ouvert ou sans haut-parleur où jouer.

Depuis : 3.00.

2.21.9. micOpen

opened = micOpen([name])

Commence à écouter le microphone désigné (pris dans micList) ou celui de la machine par défaut. Un microphone déjà ouvert est d’abord fermé.

Renvoie : true quand il s’est ouvert.

Depuis : 3.00.

Exemple
if not micOpen() then
	message = "No microphone.  This game needs one."
end

2.21.10. micPitch

hz, clarity = micPitch()

La note chantée, trouvée dans les 43 dernières millisecondes entendues. La fonction trouve une fondamentale entre 50 et 2000 Hz, ce qui couvre toutes les voix chantées, et répond à un hertz ou deux près sur un son pur.

Renvoie : la fondamentale en Hz, et à quel point le son est nettement une seule note, de 0 à 1. Sans rien de voisé — silence, souffle, toux, foule — hz vaut 0. Convertissez les Hz en numéro de note avec 69 + 12 * math.log(hz / 440, 2) : 69 est le la au-dessus du do central, et chaque 1 vaut un demi-ton.

Depuis : 3.00.

Exemple
local hz, clarity = micPitch()
if hz > 0 and clarity > 0.8 then
	local note = 69 + 12 * math.log(hz / 440, 2)
	local off  = note - targetNote          -- demi-tons trop haut (positif) ou trop bas
	if math.abs(off) < 0.5 then
		score = score + 1
	end
end

2.21.11. micRead

samples = micRead([max])

Ce qui a été entendu depuis le dernier appel, le plus ancien en premier.

Paramètres :

  • max — nombre, le plus grand nombre d’échantillons à renvoyer ; tout ce qui attend s’il n’est pas donné.

Renvoie : une chaîne d’échantillons de 16 bits, deux octets chacun, little-endian, un canal à 48000 par seconde : il y en a #samples / 2. Lisez-en un avec string.unpack("<i2", samples, n * 2 - 1). Un jeu qui ne lit rien pendant plus de huit secondes perd les plus anciens.

Depuis : 3.00.

2.21.12. micRecordStart

started = micRecordStart(name)

Écrit tout ce qui est entendu à partir de maintenant dans un fichier WAV (un canal, 16 bits, 48000 par seconde) jusqu’à micRecordStop. Le nom est celui de n’importe quel fichier que le jeu a le droit d’écrire, et il va là où vont les autres fichiers écrits par le jeu.

Renvoie : true quand le fichier a été ouvert.

Depuis : 3.00.

2.21.13. micRecordStop

micRecordStop()

Termine l’enregistrement.

Depuis : 3.00.

2.21.14. micSetLatency

micSetLatency(milliseconds | nil)

Règle la latence du microphone de cette machine, comme le fait un menu de service à partir d’une mesure prise d’une autre façon ; nil l’oublie. Elle est conservée avec les autres réglages de la machine.

Paramètres :

  • milliseconds — nombre, de 0 à 1000, ou nil.

Depuis : 3.00.

2.22. MIDI

Deux choses sans rapport partagent ce nom, et il vaut la peine de les distinguer.

Un fichier MIDI, c’est de la musique, et il se joue comme toute autre musique : passez le .mid à musicLoad. Singe le synthétise à partir d’une SoundFont, parce qu’un fichier MIDI contient des notes plutôt que du son. Singe n’est livré avec aucune SoundFont — une bonne pèse des dizaines de mégaoctets, pour un format que presque aucun jeu n’utilise — alors désignez-en une avec --soundfont, placez-en une en Singe/soundfont.sf2 pour qu’un jeu empaqueté porte la sienne, ou laissez Singe trouver celle que votre distribution a installée. La ligne SoundFont: de l’en-tête de la trace dit laquelle a été utilisée. Sans SoundFont nulle part, le chargement d’un .mid échoue et le signale.

Les ports MIDI, ce sont les appels ci-dessous. Ils envoient et reçoivent des messages en direct sur un vrai port : une borne qui pilote un module de sons externe, ou un clavier, un boîtier de faders ou une surface de contrôle lus comme un périphérique d’entrée de plus. Rien ici ne synthétise quoi que ce soit, et rien ici ne touche à un fichier MIDI.

Les ports sont numérotés à partir de 0. Rien n’est ouvert avant la première demande d’un script — un port MIDI coûte un descripteur de fichier et une passe de configuration du pilote, et un jeu qui ne parle jamais de MIDI ne le paie jamais — si bien que le premier de ces appels est celui qui fait l’inventaire de la machine, et midiRescan cherche de nouveau un périphérique branché depuis. Un port d’entrée et un port de sortie peuvent être ouverts à la fois. Les canaux vont de 1 à 16, comme on les compte, et non de 0 à 15 comme sur le fil, et toutes les autres valeurs vont de 0 à 127. Sur une machine sans aucun MIDI — pas de ports, ou pas de bibliothèque MIDI installée — les nombres de ports valent 0, les appels d’ouverture répondent false et les appels d’envoi répondent false ; rien n’échoue.

Linux atteint chaque port par le séquenceur ALSA, qui comprend à la fois les interfaces matérielles et tout synthétiseur ou autre programme qui y déclare le sien. macOS utilise CoreMIDI et Windows les appels MIDI multimédia, où le périphérique de sortie 0 est en général le synthétiseur que fournit le système lui-même.

2.22.1. midiCloseInput

midiCloseInput()

Cesse d’écouter le port d’entrée. onMidiMessage n’est plus appelé. Fermer un port qui n’est pas ouvert ne fait rien.

Paramètres :

  • Aucun.

Renvoie : rien.

Depuis : 3.00. Voir aussi : midiOpenInput

2.22.2. midiCloseOutput

midiCloseOutput()

Libère le port de sortie. Les appels d’envoi répondent false à partir de là. Fermer un port qui n’est pas ouvert ne fait rien.

Paramètres :

  • Aucun.

Renvoie : rien.

Depuis : 3.00. Voir aussi : midiOpenOutput

2.22.3. midiControlChange

sent = midiControlChange(channel, control, value)

Déplace un contrôleur sur le port de sortie ouvert : le volume est le contrôleur 7, le panoramique le 10, la pédale de sustain le 64.

Paramètres :

  • channel — nombre ; de 1 à 16.

  • control — nombre ; de 0 à 127.

  • value — nombre ; de 0 à 127.

Renvoie : true quand le message est parti.

Depuis : 3.00. Voir aussi : midiSend

Exemple
-- Baisser le volume du module pendant qu'un personnage parle.
midiControlChange(1, 7, 40)

2.22.4. midiInputCount

count = midiInputCount()

Combien de ports d’entrée MIDI a cette machine. 0 quand il n’y en a aucun, ou quand la plateforme n’a pas de MIDI du tout.

Paramètres :

  • Aucun.

Renvoie : un nombre.

Depuis : 3.00. Voir aussi : midiInputName

2.22.5. midiInputName

name = midiInputName(index)

Le nom d’un port d’entrée, pour un écran de réglages qui laisse un joueur en choisir un.

Paramètres :

  • index — nombre ; de 0 à midiInputCount() - 1.

Renvoie : une chaîne, ou nil quand l’indice ne désigne aucun port.

Depuis : 3.00. Voir aussi : midiInputCount

Exemple
-- Un écran de réglages qui liste les ports d'entrée, un par ligne.
function onOverlayUpdate()
    overlayClear()
    for i = 0, midiInputCount() - 1 do
        overlayPrint(1, i + 1, midiInputName(i))
    end
    return OVERLAY_UPDATED
end

2.22.6. midiIsInputOpen

open = midiIsInputOpen()

Indique si un port d’entrée est ouvert.

Paramètres :

  • Aucun.

Renvoie : true ou false.

Depuis : 3.00. Voir aussi : midiOpenInput

2.22.7. midiIsOutputOpen

open = midiIsOutputOpen()

Indique si un port de sortie est ouvert. Bon à demander avant une rafale de messages, car sinon chacun répondrait false séparément.

Paramètres :

  • Aucun.

Renvoie : true ou false.

Depuis : 3.00. Voir aussi : midiOpenOutput

2.22.8. midiNoteOff

sent = midiNoteOff(channel, key)

Relâche une note sur le port de sortie ouvert. Une note laissée enfoncée sonne jusqu’à ce que quelque chose l’arrête, donc chaque midiNoteOn a besoin de l’un de ces appels.

Paramètres :

  • channel — nombre ; de 1 à 16.

  • key — nombre ; de 0 à 127, où 60 est le do central.

Renvoie : true quand le message est parti.

Depuis : 3.00. Voir aussi : midiNoteOn

2.22.9. midiNoteOn

sent = midiNoteOn(channel, key, velocity)

Fait sonner une note sur le port de sortie ouvert.

Paramètres :

  • channel — nombre ; de 1 à 16. Le canal 10 est celui des percussions sur un périphérique General MIDI.

  • key — nombre ; de 0 à 127, où 60 est le do central.

  • velocity — nombre ; de 0 à 127, la force avec laquelle la touche a été frappée.

Renvoie : true quand le message est parti.

Depuis : 3.00. Voir aussi : midiNoteOff

Exemple
-- Une ponctuation sonore sur un module externe quand le joueur est touché.
midiNoteOn(10, 49, 110)
midiNoteOff(10, 49)

2.22.10. midiOpenInput

opened = midiOpenInput(index)

Écoute un port d’entrée. onMidiMessage est alors appelé pour chaque message qui arrive. Le port d’entrée qui était ouvert, quel qu’il soit, est d’abord fermé.

Paramètres :

  • index — nombre ; de 0 à midiInputCount() - 1.

Renvoie : true quand le port s’est ouvert.

Depuis : 3.00. Voir aussi : midiCloseInput, onMidiMessage

Exemple
if midiInputCount() > 0 then
	midiOpenInput(0)
end

2.22.11. midiOpenOutput

opened = midiOpenOutput(index)

Prend un port de sortie pour les appels d’envoi. Le port de sortie qui était ouvert, quel qu’il soit, est d’abord fermé.

Paramètres :

  • index — nombre ; de 0 à midiOutputCount() - 1.

Renvoie : true quand le port s’est ouvert.

Depuis : 3.00. Voir aussi : midiCloseOutput

2.22.12. midiOutputCount

count = midiOutputCount()

Combien de ports de sortie MIDI a cette machine.

Paramètres :

  • Aucun.

Renvoie : un nombre.

Depuis : 3.00. Voir aussi : midiOutputName

2.22.13. midiOutputName

name = midiOutputName(index)

Le nom d’un port de sortie.

Paramètres :

  • index — nombre ; de 0 à midiOutputCount() - 1.

Renvoie : une chaîne, ou nil quand l’indice ne désigne aucun port.

Depuis : 3.00. Voir aussi : midiOutputCount

2.22.14. midiPitchBend

sent = midiPitchBend(channel, value)

Infléchit la hauteur d’un canal. 8192 est le milieu, c’est-à-dire aucune inflexion ; jusqu’où vont 0 et 16383 dépend d’un réglage propre au périphérique récepteur, en général deux demi-tons.

Paramètres :

  • channel — nombre ; de 1 à 16.

  • value — nombre ; de 0 à 16383.

Renvoie : true quand le message est parti.

Depuis : 3.00.

2.22.15. midiProgramChange

sent = midiProgramChange(channel, program)

Choisit le son que joue un canal. Les numéros sont ceux du périphérique récepteur ; sur un périphérique General MIDI, 0 est un piano à queue.

Paramètres :

  • channel — nombre ; de 1 à 16.

  • program — nombre ; de 0 à 127.

Renvoie : true quand le message est parti.

Depuis : 3.00.

2.22.16. midiRescan

midiRescan()

Cherche de nouveau les ports, pour un périphérique branché pendant que le jeu tourne. Un port ouvert reste ouvert. Les indices ne sont pas plus stables que la liste : relisez donc les noms après cet appel plutôt que de supposer que le port 2 est toujours ce qu’il était.

Paramètres :

  • Aucun.

Renvoie : rien.

Depuis : 3.00. Voir aussi : midiInputCount, midiOutputCount

2.22.17. midiSend

sent = midiSend(byte [, byte [, byte]])
sent = midiSend(string)

N’importe quel message, pour ceux que les appels nommés ne couvrent pas. Avec des nombres, il les envoie tels quels, c’est-à-dire un octet de statut et jusqu’à deux octets de données — et notez que l’octet de statut porte le canal dans ses quatre bits de poids faible, compté à partir de 0, contrairement à tous les autres appels de cette section. Avec une chaîne, il envoie la chaîne entière, et c’est ainsi que part un message système exclusif.

Paramètres :

  • byte — nombre ; de 0 à 255, d’un à trois.

  • string — une chaîne d’octets, envoyée telle quelle.

Renvoie : true quand le message est parti.

Depuis : 3.00. Voir aussi : midiNoteOn, midiControlChange

Exemple
-- Toutes les notes coupées sur le canal 1, ce qui n'a pas d'appel nommé.
midiSend(0xB0, 123, 0)

-- Un message système exclusif, octets compris.
midiSend(string.char(0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7))

2.23. Modèle

Les modèles sont des fichiers glTF 2.0 binaires (.glb), chargés une fois et placés autant de fois qu’on veut. Un modèle doit être autonome (tampons et images à l’intérieur du fichier) ; un modèle qui renvoie à un fichier placé à côté de lui est refusé. Le chargement donne un handle entier ; modelInstance construit les nœuds du modèle dans la scène et renvoie leur racine, que prennent ensuite tous les appels node* et animation*. Les positions et les tailles à l’intérieur d’un modèle sont en unités du monde, telles que le fichier les stocke ; le nœud racine met à l’échelle toute l’instance. Voir Scènes 3D.

2.23.1. modelLoad

model = modelLoad(name)

Lit un .glb par la même recherche que toute autre ressource (dossier du jeu, dossier de données, base de données empaquetée), envoie une fois ses maillages et ses matériaux au GPU, et garde son arbre de nœuds, ses skins et ses animations pour l’instanciation. Appelez-la une fois au démarrage et instanciez le handle autant de fois qu’il le faut ; charger deux fois le même fichier en fait deux copies sur le GPU. Elle a besoin de la scène 3D, donc sur une machine sans GPU adapté elle échoue comme tout autre appel 3D. Un mauvais fichier met fin au script avec un message qui nomme le problème : le fichier n’a pas pu être lu, n’est pas du glTF, renvoie à un tampon ou à une image externe, échoue à la validation, contient une primitive qui n’a pas pu être envoyée au GPU, a un skin de plus de 128 articulations, ou a un maillage skinné qui nomme une articulation numérotée 128 ou plus. Un maillage skinné qui nomme une articulation au-delà des skins qui l’utilisent se charge, de même qu’une animation dont les images clés ne peuvent pas être lues (cet échantillonneur est ignoré) ; l’un et l’autre cas sont notés dans la trace du programme. Une texture qui ne peut pas être décodée, ou une image KTX2 manquante, ne fait pas échouer le chargement ; le matériau se passe de cette carte et la trace du programme (--program) dit laquelle.

Renvoie : Le handle du modèle, un entier.

Depuis : 3.00. Voir aussi : modelInstance, modelGetAnimations, modelDelete

Exemple
-- Charger une fois, placer trois fois.
treeModel = modelLoad(DIR .. "Models/Tree.glb")
for i = 1, 3 do
    local tree = modelInstance(treeModel)
    nodeSetPosition(tree, i * 3 - 6, 0, -4)
    nodeSetRotation(tree, 0, i * 70, 0)
end

2.23.2. modelDelete

modelDelete(model)

Libère les maillages, les matériaux et les données analysées du modèle. Chaque instance qui en a été faite est oubliée en même temps : ses nœuds restent dans la scène (position, parent et enfants intacts) mais ne dessinent rien, ses animations s’arrêtent là où elles en sont, et un appel animation* ultérieur sur sa racine met fin au script, parce que le nœud n’est plus une instance de modèle. Supprimez les racines des instances avec nodeDelete quand vous ne voulez pas non plus des nœuds. Un handle qui n’est pas un modèle chargé met fin au script.

Depuis : 3.00. Voir aussi : modelLoad, modelInstance, nodeDelete

Exemple
-- En quittant le niveau du hangar : se débarrasser de ses accessoires et du modèle qui les fournit.
function unloadHangar()
    for _, crate in ipairs(hangarCrates) do
        nodeDelete(crate)
    end
    hangarCrates = {}
    modelDelete(crateModel)
    crateModel = nil
end

2.23.3. modelGetAnimations

names = modelGetAnimations(model)

Liste les clips d’animation du modèle dans l’ordre du fichier, sous forme de table de chaînes, si bien que names[3] est le clip que joue animationPlay(node, 3). Un clip que l’exportateur a laissé sans nom donne une chaîne vide ; on peut quand même le jouer par son numéro. Un modèle sans animations donne une table vide. Un handle qui n’est pas un modèle chargé met fin au script.

Renvoie : Une table de chaînes indicée à partir de 1.

Depuis : 3.00. Voir aussi : animationPlay, modelLoad

Exemple
-- Trouver les clips par leur nom une seule fois, pour que le reste du jeu utilise des numéros.
guardModel = modelLoad(DIR .. "Models/Guard.glb")
guardClips = {}
for index, name in ipairs(modelGetAnimations(guardModel)) do
    guardClips[name] = index
end
if guardClips["Idle"] == nil then
    debugPrint("Guard.glb has no Idle clip")
end

2.23.4. modelInstance

node = modelInstance(model)
node = modelInstance(model, parent)

Construit l’arbre de nœuds du modèle sous un nouveau nœud racine, lui-même placé sous parent ou sous la racine de la scène. La racine est un nœud ordinaire : placez-la, tournez-la, mettez-la à l’échelle ou donnez-lui un parent comme à n’importe quel autre, et supprimez-la avec nodeDelete pour retirer toute l’instance. Les nœuds propres au modèle prennent leurs noms glTF (ou le nom de leur maillage quand le nœud n’a pas de nom), si bien que nodeFind(name, node) les atteint ; un maillage à plusieurs matériaux devient un nœud enfant par partie ; les lumières du fichier deviennent des lumières de la scène avec la couleur, l’intensité, la portée et le cône du fichier ; les skins sont attachés et les poids de morphing réglés. Les nœuds gardent la pose du fichier jusqu’à ce qu’une animation joue. Un handle qui n’est pas un modèle chargé ou un parent qui n’est pas un nœud met fin au script, tout comme le manque de nœuds disponibles.

Renvoie : Le handle du nœud racine de l’instance.

Depuis : 3.00. Voir aussi : modelLoad, nodeFind, animationPlay, nodeDelete

Exemple
-- Une tourelle sur la caisse du char, pour qu'elle tourne avec la caisse et pivote d'elle-même.
tank   = modelInstance(hullModel)
turret = modelInstance(turretModel, tank)
nodeSetPosition(turret, 0, 1.1, -0.3)
barrel = nodeFind("Barrel", turret)

function onOverlayUpdate()
    nodeSetRotation(turret, 0, aimYaw, 0)
    nodeSetRotation(barrel, aimPitch, 0, 0)
    return OVERLAY_UPDATED
end

2.24. Souris

Singe lit jusqu’à quatre souris, et traite les pistolets optiques comme des souris. Dans le mode à une seule souris, celui par défaut, chaque dispositif de pointage pilote un curseur unique signalé comme souris 0 ; mouseSetMode(MOUSE_MANY) distingue les périphériques, ce dont a besoin une borne à deux pistolets optiques pour deux joueurs. Les positions arrivent en coordonnées de l’overlay, pas en pixels de l’écran, par onMouseMoved (voir Callbacks du moteur) et à la demande par mouseGetPosition. Les boutons et la molette de la souris sont des contacts comme les touches : ils atteignent onInputPressed et onInputReleased quand controls.cfg affecte un code des tables MOUSE_0 à MOUSE_3, et les valeurs par défaut fournies affectent le bouton gauche à SWITCH_BUTTON3, le droit à SWITCH_BUTTON1 et celui du milieu à SWITCH_BUTTON2. Le moteur démarre avec la souris capturée, et activée sauf si --nomouse a été donné ou si aucune souris n’a été trouvée.

2.24.1. mouseDisable

mouseDisable()

Désactive l’entrée de la souris, exactement comme le fait mouseSetEnabled(false). C’est une fonction définie dans Framework.singe, conservée pour que les anciens jeux tournent sans modification.

Remarques : Alias hérité.

Le nouveau code doit appeler mouseSetEnabled avec false.

Depuis : 1.18 (RDG) Voir aussi : mouseSetEnabled, mouseEnable

Exemple
-- Code d'un ancien jeu ; l'écriture moderne est mouseSetEnabled(false).
function cutsceneBegin()
    mouseDisable()
    discSearch(CUTSCENE_START)
end

2.24.2. mouseEnable

mouseEnable()

Active l’entrée de la souris, exactement comme le fait mouseSetEnabled(true), et, comme elle, la laisse désactivée quand Singe a été lancé avec --nomouse. C’est une fonction définie dans Framework.singe, conservée pour que les anciens jeux tournent sans modification.

Remarques : Alias hérité.

Le nouveau code doit appeler mouseSetEnabled avec true.

Depuis : 1.18 (RDG) Voir aussi : mouseSetEnabled, mouseDisable

Exemple
-- Code d'un ancien jeu ; l'écriture moderne est mouseSetEnabled(true).
function cutsceneEnd()
    mouseEnable()
    discSearch(LEVEL_START)
end

2.24.3. mouseGetName

name = mouseGetName(mouse)

Le nom que le pilote de souris donne à un périphérique, ou nil quand aucun périphérique ne porte cet indice. C’est grâce à lui qu’on distingue deux pistolets d’une borne sur un écran de service, ce qui sinon relève de la devinette quand les deux se signalent comme souris 0 et 1. Un indice hors de 0 à 3 met fin au script.

Paramètres :

  • mouse — indice du périphérique, de 0 à 3.

Renvoie : chaîne, ou nil.

Depuis : 3.00 Voir aussi : mouseHowMany, mouseSetMode, controllerGetName

Exemple
-- Nommer les pistolets sur l'écran de calibrage.
mouseSetMode(MOUSE_MANY)
for device = 0, mouseHowMany() - 1 do
    fontPrint(20, 20 + device * 18, string.format("Gun %d:  %s", device + 1, mouseGetName(device)))
end

2.24.4. mouseGetPadding

padding = mouseGetPadding()

Extension Hypseus, toujours 0, pour la raison que donne controllerGetPadding. Hypseus ajoute ce décalage aux codes d’entrée que ses souris signalent en mode relatif ; les codes de Singe ne portent aucun décalage de ce genre, il n’y a donc rien à soustraire.

Renvoie : un entier, toujours 0.

Depuis : 3.00 Voir aussi : controllerGetPadding

2.24.5. mouseGetPosition

x, y = mouseGetPosition(index)

Renvoie la dernière position signalée d’une souris en coordonnées de l’overlay, les mêmes valeurs que portait le dernier onMouseMoved de ce périphérique. En mode à une seule souris, seule la souris 0 bouge ; en mode multi-souris, chaque périphérique a sa propre position, qui part du centre de la vidéo. La position cesse d’être mise à jour tant que l’entrée de la souris est désactivée. Interrogez-la depuis onOverlayUpdate ou singeMain quand c’est plus simple que de suivre le callback. Un indice hors de 0 à 3 met fin au script.

Paramètres :

  • index — indice de la souris, de 0 à 3.

Renvoie : deux entiers, x et y, en coordonnées de l’overlay.

Depuis : 2.00 Voir aussi : mouseHowMany, onMouseMoved, singeWantsCrosshairs

Exemple
-- Dessiner le réticule là où vise le pistolet.
function onOverlayUpdate()
    overlayClear()
    drawTargets()
    if singeWantsCrosshairs() then
        local x, y = mouseGetPosition(0)
        spriteDraw(crosshair, x, y, true)
    end
    return OVERLAY_UPDATED
end

2.24.6. mouseHowMany

count = mouseHowMany()

Renvoie le nombre de souris que le moteur a trouvées au démarrage, de 0 à 4. Les périphériques branchés plus tard ne sont pas comptés. Quand aucune n’a été trouvée, la souris reste désactivée. Servez-vous-en pour décider s’il faut proposer un second joueur au pistolet optique.

Renvoie : entier, de 0 à 4.

Depuis : 1.18 (RDG) Voir aussi : mouseSetMode, mouseGetPosition

Exemple
-- Deux pistolets présents : donner un curseur à chaque joueur.
if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
    players = 2
else
    players = 1
end

2.24.7. mouseSetCaptured

mouseSetCaptured(captured)

Capture la souris, en la confinant à la fenêtre de Singe et en masquant le curseur, ou la libère et montre de nouveau le curseur. Le moteur capture la souris au démarrage, si bien que la plupart des jeux n’appellent jamais cette fonction ; un éditeur de niveaux en fenêtre ou un jeu qui veut que le curseur du bureau reste visible la libère. Le contact affecté à INPUT_GRAB dans controls.cfg bascule le même état depuis le clavier.

Paramètres :

  • captured — booléen ; true capture et masque, false libère et montre.

Depuis : 2.00 Voir aussi : mouseSetEnabled, mouseGetPosition

Exemple
-- L'éditeur de niveaux veut le curseur du bureau ; le jeu le masque de nouveau.
function editorToggle()
    editing = not editing
    mouseSetCaptured(not editing)
end

2.24.8. mouseSetEnabled

mouseSetEnabled(enabled)

Active ou désactive l’entrée de la souris. Quand elle est désactivée, les événements de mouvement, de bouton et de molette sont écartés avant d’atteindre le script : onMouseMoved n’est plus appelé, les boutons de la souris ne produisent plus de contacts, et mouseGetPosition continue de renvoyer la dernière position qu’il avait. Le curseur lui-même bouge toujours. L’activation respecte --nomouse : quand Singe a été lancé avec cette option, la souris reste désactivée. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Depuis : 3.00 Voir aussi : mouseSetCaptured, mouseSetMode, mouseEnable

Exemple
-- Ignorer le pistolet pendant que tourne la boucle du mode attraction.
function attractBegin()
    mouseSetEnabled(false)
    discSearch(ATTRACT_START)
end

function attractEnd()
    mouseSetEnabled(true)
end

2.24.9. mouseSetMode

mouseSetMode(mode)

Choisit la façon dont les souris sont lues. En MOUSE_SINGLE (par défaut), les événements de pointeur de la fenêtre pilotent un curseur unique signalé comme périphérique 0, les positions absolues comme les mouvements relatifs étant convertis en coordonnées de l’overlay. En MOUSE_MANY, chaque périphérique physique est lu séparément : les mouvements relatifs sont intégrés en une position propre à chaque périphérique, ramenée dans la zone de la vidéo, les périphériques absolus comme les tablettes et certains pistolets optiques sont projetés sur la vidéo, et onMouseMoved signale l’indice du périphérique. Les deux modes livrent les mêmes cinq boutons et la molette verticale sous forme de contacts. SINGLE_MOUSE et MANY_MOUSE sont acceptés comme anciennes écritures ; toute autre valeur met fin au script. --manymouse est la décision de l’utilisateur lui-même et passe avant cet appel : quand il est donné, le mode est MOUSE_MANY dès le départ et mouseSetMode(MOUSE_SINGLE) ne le désactive pas, si bien qu’on peut faire fonctionner une borne à deux pistolets de l’extérieur d’un jeu qui ne le demande jamais.

Paramètres :

  • mode — MOUSE_SINGLE (100) ou MOUSE_MANY (200).

Depuis : 1.18 (RDG) Voir aussi : mouseHowMany, onMouseMoved, mouseGetPosition

Exemple
-- Jeu coopératif au pistolet optique : chaque pistolet dirige son propre curseur.
mouseSetMode(MOUSE_MANY)

function onMouseMoved(x, y, xr, yr, which)
    if which < 2 then
        cursorX[which + 1] = x
        cursorY[which + 1] = y
    end
end

2.25. Musique

Musique de fond, chargée et jouée à part des effets sonores, avec son propre volume. Hypseus fait tourner la musique sur un second mélangeur exactement pour cette raison, et Singe lui donne plutôt son propre gain : musicSetVolume ne touche jamais un effet sonore et soundSetVolume ne touche jamais la musique.

Un handle de musique est un type de handle à part, ni un handle de son ni un canal : un handle est une piste, et elle se joue, se met en pause, reprend et s’arrête indépendamment des autres. Il n’y a pas de limite de canaux, contrairement aux seize canaux d’effets sonores.

L’échelle de volume est celle d’Hypseus, de 0 à 128, presque le double des 0 à 63 qu’utilise la famille sound, si bien qu’un jeu écrit pour Hypseus garde ses propres nombres. La musique démarre aussi fort que les effets sonores, au niveau qu’a réglé --volume_nonvldp ; Hypseus, lui, démarre son mélangeur de musique au tiers, ce que chaque jeu Hypseus écrase aussitôt avec musicSetVolume(soundGetVolume() * 2).

Tous les formats que lit la famille sound sont lus ici : WAV, Ogg Vorbis, Opus, FLAC, MP3, WavPack et les autres. L’en-tête de trace écrit par --program et --trace liste exactement quels décodeurs contient la compilation, sur sa ligne Audio:.

Mettre le moteur en pause (la touche de pause, ou singeSetPauseFlag) met la musique en pause avec lui, et la reprise la relance ; un rechargement arrête et libère toutes les pistes.

2.25.1. musicGetPosition

seconds = musicGetPosition(id)

Où en est l’auditeur dans une piste en cours de lecture, en secondes : la position propre du mélangeur, moins ce qui est encore en route vers les haut-parleurs — la file du périphérique, le calibrage audio de la machine et le retard audio du jeu — si bien qu’une image calée dessus tombe avec le son. C’est l’horloge sur laquelle animer quand la musique mène, comme dans une démo ou un jeu de rythme, et elle reste avec le morceau quelle que soit sa durée, là où compter les images ou les ticks dérive. Le mélangeur avance sa position d’un tampon à la fois, si bien qu’entre deux avancées la réponse continue avec l’horloge, jamais de plus de 50 ms, et elle avance en douceur à chaque image. Une piste en pause reste immobile. Une piste qui ne joue pas répond -1.

Paramètres :

  • id — nombre ; un handle de musique.

Renvoie : nombre ; les secondes écoulées dans la piste, ou -1.

Exemple
-- Un flash à chaque temps d'un morceau à 120 battements par minute, sur le temps tel qu'on l'entend.
function onOverlayUpdate()
    colorBackground(0, 0, 0)
    overlayClear()
    local t = musicGetPosition(song)
    if t >= 0 and (t * 2) % 1 < 0.1 then
        colorBackground(255, 255, 255, 120)
        overlayClear()
    end
    return OVERLAY_UPDATED
end

2.25.2. musicIsPlaying

playing = musicIsPlaying([id])

Extension Hypseus. Indique si cette piste joue, ou — sans handle — si une musique quelconque joue. Une piste en pause ne joue pas.

Paramètres :

  • id — nombre facultatif ; un handle de musique.

Renvoie : booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicPlay, musicPause

Exemple
if not musicIsPlaying(theme) then
    musicPlay(theme, -1)
end

2.25.3. musicLoad

id = musicLoad(filename)

Extension Hypseus. Charge une piste de musique par le système de fichiers virtuel et renvoie son handle. Le fichier entier est décodé d’avance, comme pour un son, si bien qu’une longue piste coûte de la mémoire, sauf un chiptune qui ne dit pas sa durée ou ce qui ferait plus de 512 Mo une fois décodé, l’un comme l’autre décodé au fil de la lecture ; le handle est valide jusqu’à musicUnload ou jusqu’à un rechargement.

Un fichier absent, ou qu’aucun décodeur compilé ne sait lire, met fin au script, comme le fait soundLoad.

Paramètres :

  • filename — chaîne ; un chemin que le système de fichiers virtuel peut atteindre.

Renvoie : nombre, le handle de musique.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicPlay, musicUnload, soundLoad

Exemple
local theme = musicLoad("music/attract.mp3")
musicSetVolume(96)
musicPlay(theme, -1)

2.25.4. musicPause

musicPause([id])

Extension Hypseus. Met cette piste en pause là où elle en est, ou toute la musique quand aucun handle n’est donné. musicResume la relance.

Paramètres :

  • id — nombre facultatif ; un handle de musique.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicResume, musicStop

Exemple
-- Le joueur a ouvert la carte ; suspendre la musique plutôt que la reprendre au début.
musicPause()

2.25.5. musicPlay

id = musicPlay(id [, loops])

Extension Hypseus. Joue une piste depuis son début et répond son handle, et c’est ainsi que les jeux d’Hypseus le gardent (sndHandle = musicPlay(music)) pour arrêter le morceau plus tard. loops a le même sens que celui de soundPlay : 0, la valeur par défaut, joue une fois, -1 joue indéfiniment, et N répète N fois de plus. Le nombre est ramené entre -1 et 64, comme le fait Hypseus, si bien qu’un jeu qui en demande davantage obtient ce qu’il aurait obtenu là-bas.

Jouer une piste qui joue déjà la relance depuis le début.

Paramètres :

  • id — nombre ; un handle de musique.

  • loops — nombre facultatif ; de -1 à 64. 0 par défaut.

Renvoie : nombre ; le handle qu’il a reçu.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicStop, musicSetVolume

Exemple
musicPlay(theme, -1)     -- Encore et encore, jusqu'à ce que quelque chose l'arrête.

2.25.6. musicResume

musicResume([id])

Extension Hypseus. Reprend une piste en pause, ou toute la musique en pause quand aucun handle n’est donné.

La forme sans argument d’Hypseus ne fait rien du tout ; celle de Singe reprend tout, ce qui va de pair avec musicPause.

Paramètres :

  • id — nombre facultatif ; un handle de musique.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicPause

Exemple
musicResume()

2.25.7. musicSetVolume

volume = musicSetVolume(volume)

Extension Hypseus. Règle le gain de toute la musique à la fois, sur l’échelle de 0 à 128 d’Hypseus, et répond le niveau retenu. Elle ne touche à rien d’autre que la musique : les effets sonores gardent ce que leur a donné soundSetVolume, et soundSetVolume laisse la musique tranquille.

Un niveau hors de 0 à 128 met fin au script. Le niveau s’applique aux pistes déjà en cours de lecture et à toutes celles chargées ensuite, et revient au niveau de départ lors d’un rechargement.

Paramètres :

  • volume — nombre ; de 0 à 128.

Renvoie : nombre, le niveau qui a été réglé.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : soundSetVolume, musicPlay

Exemple
-- Ce qu'écrit un jeu Hypseus : le niveau du son, doublé pour l'échelle de la musique.
musicSetVolume(soundGetVolume() * 2)

2.25.8. musicStop

musicStop([id [, fadeMs]])

Extension Hypseus. Arrête cette piste, ou toute la musique quand aucun handle n’est donné (un handle nil compte comme aucun). fadeMs la fait disparaître en fondu sur ce nombre de millisecondes au lieu de la couper ; 0, la valeur par défaut, l’arrête aussitôt. Un fondu négatif met fin au script.

Paramètres :

  • id — nombre facultatif ; un handle de musique.

  • fadeMs — nombre facultatif ; la durée du fondu de sortie, en millisecondes. 0 par défaut.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicPlay, musicPause

Exemple
musicStop(theme, 1500)   -- Partie en une seconde et demie.

2.25.9. musicUnload

musicUnload(id)

Extension Hypseus. Arrête la piste et la libère. Le handle n’est plus valide ensuite et l’utiliser met fin au script.

Paramètres :

  • id — nombre ; un handle de musique.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : musicLoad

Exemple
musicUnload(theme)

Les maillages de navigation précalculés à partir de la géométrie de la scène, et les agents de foule qui y marchent (voir Scènes 3D, Navigation). navNew et navLoad renvoient un handle de maillage et navAgentNew un handle d’agent ; ce sont tous deux des entiers, vérifiés à chaque appel, et un handle invalide met fin au script. Les positions sont en unités du monde, les vitesses en unités par seconde et les pentes en degrés. Jusqu’à huit maillages à la fois, 128 agents sur chacun et 256 en tout. Les requêtes et les agents ont besoin d’un maillage que navBuild a précalculé ou que navLoad a lu ; avant cela, les requêtes renvoient nil, navDraw ne dessine rien et navAgentNew met fin au script.

navAddNode(nav, node)

Ajoute le maillage du nœud, et celui de chaque nœud situé sous lui, à la géométrie à partir de laquelle le maillage de navigation sera précalculé, tels qu’ils se trouvent dans le monde à cet instant : placez-les donc d’abord. Le nœud racine d’une instance de modèle ajoute le modèle entier, et un niveau construit à partir de primitives peut être ajouté nœud par nœud. Seule la géométrie des maillages compte : les corps, les sprites et le texte n’ajoutent rien. Met fin au script une fois que le maillage a été construit.

Depuis : 3.00. Voir aussi : navNew, navBuild, modelInstance

Exemple
-- Le sol et les murs sont de la géométrie praticable ; les caisses non, elles bougent.
local nav = navNew(0.4, 1.8, 45, 0.4)
navAddNode(nav, ground)
for _, wall in ipairs(walls) do
    navAddNode(nav, wall)
end
navAddNode(nav, modelInstance(towerModel))
navBuild(nav)
navAgentDelete(agent)

Retire l’agent du maillage et libère son handle ; le nœud reste où il est et n’est plus déplacé. Supprimer le maillage avec navDelete fait de même pour chaque agent qui s’y trouve. Un handle invalide met fin au script.

Depuis : 3.00. Voir aussi : navAgentNew, navDelete

Exemple
-- Un garde qui meurt cesse de naviguer ; le ragdoll prend le modèle en charge à partir de là.
function killGuard(guard)
    navAgentDelete(guard.agent)
    guard.agent = nil
    ragdollActivate(guard.model)
    ragdollApplyImpulse(guard.model, "b_Spine02_03", 0, 20, -30)
end
x, y, z = navAgentGetVelocity(agent)

La façon dont la foule déplace l’agent à cette image, en unités du monde par seconde sur chaque axe ; sa longueur va jusqu’à la vitesse de l’agent et tombe à zéro quand il s’arrête. Pour choisir entre une animation d’attente, de marche ou de course, ou pour adapter le cycle de marche au terrain parcouru.

Renvoie : Trois nombres.

Depuis : 3.00. Voir aussi : navAgentMoveTo, animationPlay

Exemple
function onOverlayUpdate()
    for agent, fox in pairs(foxes) do
        local vx, vy, vz = navAgentGetVelocity(agent)
        local speed      = math.sqrt(vx * vx + vz * vz)
        local clip       = (speed < 0.1) and "Survey" or ((speed < 2.5) and "Walk" or "Run")
        if fox.clip ~= clip then
            animationPlay(fox.node, clip, true, 1, 0.2)
            fox.clip = clip
        end
    end
    return OVERLAY_NOT_UPDATED
end
arrived = navAgentIsArrived(agent)

Indique si l’agent a atteint la dernière cible que lui a donnée navAgentMoveTo : à moins d’une fois et demie son rayon de la cible et presque arrêté. Il passe à true au moment où onNavArrived est déclenché et reste true jusqu’au prochain navAgentMoveTo ; il vaut false pour un agent qui n’a jamais été envoyé nulle part ou qui a été arrêté en chemin.

Renvoie : Vrai ou faux.

Depuis : 3.00. Voir aussi : onNavArrived, navAgentMoveTo, navAgentStop

Exemple
-- La patrouille attend un moment à chaque poste avant de repartir.
function onOverlayUpdate()
    if navAgentIsArrived(patrol) then
        waitFrames = waitFrames + 1
        if waitFrames > 180 then
            post       = post % #posts + 1
            waitFrames = 0
            navAgentMoveTo(patrol, posts[post][1], posts[post][2], posts[post][3])
        end
    end
    return OVERLAY_NOT_UPDATED
end
ok = navAgentMoveTo(agent, x, y, z)

Envoie l’agent marcher jusqu’au point du maillage le plus proche de x, y, z, en en cherchant un jusqu’à 2 unités sur les côtés et 4 vers le haut ou vers le bas. La foule planifie l’itinéraire au fil des images suivantes et guide l’agent autour des autres agents en chemin ; onNavArrived est déclenché une fois qu’il y est arrivé. Renvoie false, et laisse l’agent tel qu’il était, quand aucun point du maillage n’est assez proche ou que la foule refuse la demande. Une nouvelle cible remplace l’ancienne à tout moment.

Paramètres :

  • agent — le handle venant de navAgentNew.

  • x, y, z — la destination en unités du monde ; elle est ramenée sur le maillage.

Renvoie : Vrai quand l’agent s’est mis en route.

Depuis : 3.00. Voir aussi : navAgentStop, navNearest, navPath

Exemple
-- L'acolyte suit le héros, réorienté deux fois par seconde.
function onOverlayUpdate()
    ticks = ticks + 1
    if ticks % 30 == 0 then
        local hx, hy, hz = nodeGetWorldPosition(hero)
        if not navAgentMoveTo(sidekickAgent, hx, hy, hz) then
            navAgentStop(sidekickAgent)       -- Le héros est hors du maillage : il saute, il nage
        end
    end
    return OVERLAY_NOT_UPDATED
end
agent = navAgentNew(nav, node, radius, height, speed)

Place sur le maillage un agent de cette taille, au point le plus proche de la position du nœud dans le monde (la position brute quand rien ne se trouve à moins de 2 unités sur les côtés et de 4 vers le haut ou vers le bas), marchant à speed unités par seconde et accélérant à 8 unités par seconde au carré. Le rayon et la hauteur sont maintenus à 0.01 ou plus, comme navNew le fait pour les siens. Dès lors, le moteur déplace le nœud le long du maillage à chaque image, dans le repère de son parent, et le fait tourner autour de Y pour qu’il regarde dans la direction où il va chaque fois qu’il se déplace à plus de 0.05 unité par seconde ; les nœuds regardent vers -Z, comme les modèles. La foule guide les agents les uns autour des autres, anticipe les virages et les tient à distance. Pour piloter un contrôleur de joueur sur le nœud au lieu de placer le nœud, voir navAgentSetPlayer. Met fin au script quand le maillage n’est pas construit ou que 128 agents s’y trouvent déjà.

Paramètres :

  • nav — un maillage construit venant de navNew ou de navLoad.

  • node — le nœud à déplacer ; en général la racine d’une instance de modèle.

  • radius — le rayon de l’agent pour se tenir à l’écart des autres, en unités du monde ; le rayon du maillage lui-même ou moins.

  • height — la hauteur de l’agent, en unités du monde.

  • speed — la vitesse de marche maximale, en unités du monde par seconde.

Renvoie : Le handle de l’agent, un entier.

Exemple
for i = 1, 6 do
    local fox = modelInstance(foxModel)
    nodeSetScale(fox, 0.01)
    nodeSetPosition(fox, navRandomPoint(nav))
    animationPlay(fox, "Walk", true)
    local agent = navAgentNew(nav, fox, 0.35, 1.0, 1.4)
    navAgentMoveTo(agent, navRandomPoint(nav))
end

function onNavArrived(agent)
    navAgentMoveTo(agent, navRandomPoint(nav))
end
navAgentSetPlayer(agent, player)

Avec true, l’agent cesse de placer son nœud et transmet à la place sa vitesse, à chaque image, au contrôleur de joueur du nœud sous forme d’un playerMove (horizontal seulement), si bien que les escaliers, les pentes, les poussées et les collisions continuent de fonctionner ; avant chaque mise à jour de la foule, la position du contrôleur dans le monde est relue comme celle de l’agent, si bien qu’être bousculé hors de sa route est pris en compte par la planification. Le nœud se tourne toujours dans le sens de sa marche. Le nœud a besoin d’un contrôleur venant de playerNew, sinon rien ne bouge. Avec false, l’agent recommence à placer le nœud lui-même.

Depuis : 3.00. Voir aussi : playerNew, playerMove, navAgentNew

Exemple
-- Un compagnon qui suit le héros à travers le niveau et peut être bousculé.
local companion = nodeNew()
nodeSetPosition(companion, 2, 0.05, 0)
playerNew(companion, 0.3, 1.0)
local companionFox = modelInstance(foxModel)
nodeSetParent(companionFox, companion)
nodeSetScale(companionFox, 0.01)
local companionAgent = navAgentNew(nav, companion, 0.3, 1.0, 2.0)
navAgentSetPlayer(companionAgent, true)
navAgentStop(agent)

Oublie la cible de l’agent : la foule cesse de le guider vers quoi que ce soit, il ralentit jusqu’à s’immobiliser là où il est, et onNavArrived n’est pas déclenché. Les autres agents le contournent toujours. Envoyez-le quelque part avec navAgentMoveTo pour qu’il reparte.

Depuis : 3.00. Voir aussi : navAgentMoveTo, navAgentIsArrived

Exemple
-- Les gardes se figent quand l'alarme sonne et se tournent vers le bruit.
function raiseAlarm(x, y, z)
    for _, guard in ipairs(guards) do
        navAgentStop(guard.agent)
        nodeLookAt(guard.node, x, y, z)
        animationPlay(guard.node, "Survey", true, 1, 0.3)
    end
    soundPlay(alarm)
end
navBuild(nav)

Précalcule le maillage praticable à partir de tout ce que navAddNode a ajouté : les sols et les pentes jusqu’à l’angle du maillage, les marches jusqu’à sa hauteur, le rayon de l’agent étant retranché autour de chaque mur et de chaque à-pic, et tout ce qui a moins que la hauteur de l’agent au-dessus de lui étant laissé de côté. Le précalcul travaille sur des cellules larges d’un tiers du rayon de l’agent et en couvre au plus 4096 sur 4096 : un petit rayon sur un grand niveau est donc lent et peut échouer ; un dixième de seconde pour Sponza sur un ordinateur de bureau, quelques secondes sur un Raspberry Pi. La géométrie ajoutée est libérée ensuite, et plus rien ne peut être ajouté ; précalculez plutôt un autre maillage. navSave conserve le résultat. Met fin au script quand rien n’a été ajouté, que le maillage est déjà construit ou que le précalcul échoue.

Depuis : 3.00. Voir aussi : navNew, navAddNode, navSave, navDraw

Exemple
-- Le précalcul a lieu une fois, pendant que l'écran titre est affiché, et il est conservé pour la fois suivante.
local sponza = modelInstance(modelLoad("Models/Sponza.glb"))
local nav    = navNew(0.4, 1.6, 45, 0.3)
navAddNode(nav, sponza)
navBuild(nav)
navSave(nav, "sponza.nav")
if debugging then
    navDraw(nav)                              -- Une image, pour juger le précalcul à l'œil
end
navDelete(nav)

Libère le maillage et chaque agent qui s’y trouve ; leurs nœuds restent où ils sont. Le handle du maillage et ceux des agents sont ensuite invalides et mettent fin au script s’ils sont utilisés. L’emplacement est libre pour un nouveau navNew ou navLoad.

Depuis : 3.00. Voir aussi : navNew, navAgentDelete

Exemple
function loadLevel(index)
    if levelNav then
        navDelete(levelNav)                   -- Emporte avec lui les agents de l'ancien niveau
    end
    nodeDelete(levelRoot)
    levelRoot = modelInstance(levels[index].model)
    levelNav  = navNew(0.4, 1.6, 45, 0.3)
    navAddNode(levelNav, levelRoot)
    navBuild(levelNav)
end
navDraw(nav)
navDraw(nav, r, g, b)

Dessine les polygones du maillage précalculé sous forme de lignes par-dessus la scène pour cette image, en cyan sauf autre couleur, chaque polygone en éventail de triangles, si bien qu’un polygone de plus de trois côtés montre ses diagonales. Appelez-le à chaque image tant que vous regardez ; il coûte trois lignes par triangle, et un maillage qui n’est pas encore construit ne dessine rien. Pour vérifier qu’un précalcul couvre le sol et évite les meubles, avec physicsSetDebug.

Paramètres :

  • nav — le maillage.

  • r, g, b — la couleur des lignes, de 0 à 255 chacune ; par défaut 0, 255, 255.

Depuis : 3.00. Voir aussi : lineDraw, navBuild, physicsSetDebug

Exemple
function onOverlayUpdate()
    if showNavMesh then
        navDraw(nav)                          -- En cyan par-dessus le sol
        local path = navPath(nav, heroX, heroY, heroZ, goalX, goalY, goalZ)
        if path then
            for i = 2, #path do
                lineDraw(path[i - 1][1], path[i - 1][2], path[i - 1][3], path[i][1], path[i][2], path[i][3], 255, 60, 40)
            end
        end
    end
    return OVERLAY_NOT_UPDATED
end
nav = navLoad(name, agentRadius, agentHeight)

Charge un maillage écrit par navSave, cherché d’abord parmi les fichiers du jeu (si bien qu’un maillage précalculé peut être livré avec le jeu, empaqueté ou non) puis dans le dossier de données du jeu. Le maillage revient construit, prêt pour les agents et les requêtes, et n’accepte plus de navAddNode. La pente et la marche avec lesquelles il a été précalculé sont dans le fichier ; le rayon et la hauteur de l’agent sont ceux avec lesquels la foule guide les agents, donnez donc les valeurs pour lesquelles il a été précalculé. Met fin au script quand le fichier ne peut pas être lu, n’est pas un maillage de navigation, est plus court que le maillage que décrit son en-tête (tronqué, ou modifié à la main) ou qu’aucun emplacement de maillage n’est libre.

Paramètres :

  • name — le nom du fichier, relatif au dossier du jeu ou au dossier de données.

  • agentRadius — le rayon d’agent pour lequel le maillage a été précalculé, en unités du monde.

  • agentHeight — la hauteur d’agent pour laquelle il a été précalculé, en unités du monde.

Renvoie : Le handle du maillage, un entier.

Depuis : 3.00. Voir aussi : navSave, navNew

Exemple
-- Le précalcul livré pour le musée ; des agents larges de 0,8 et hauts de 1,7.
local museum = modelInstance(modelLoad("museum.glb"))
local nav    = navLoad("museum.nav", 0.4, 1.7)
for _, visitor in ipairs(visitors) do
    visitor.agent = navAgentNew(nav, visitor.node, 0.35, 1.7, 1.2)
    navAgentMoveTo(visitor.agent, navRandomPoint(nav))
end
x, y, z = navNearest(nav, x, y, z)

Le point du maillage le plus proche d’un point donné, cherché jusqu’à 2 unités sur les côtés et 4 vers le haut ou vers le bas, ou nil quand rien n’est aussi proche. Pour ramener sur le sol un point d’apparition, un point de chute ou un clic avant de le confier à un agent, et pour trouver la hauteur du sol sous un point.

Paramètres :

  • nav — le maillage.

  • x, y, z — le point à ramener, en unités du monde.

Renvoie : Trois nombres, ou nil.

Depuis : 3.00. Voir aussi : navPath, navAgentMoveTo, sceneUnproject

Exemple
-- Faire apparaître l'ennemi sur le sol le plus proche du générateur, ou pas du tout.
function spawnEnemy(spawner)
    local sx, sy, sz = nodeGetWorldPosition(spawner)
    local x, y, z    = navNearest(nav, sx, sy, sz)
    if x then
        local enemy = modelInstance(enemyModel)
        nodeSetPosition(enemy, x, y, z)
        enemies[#enemies + 1] = { node = enemy, agent = navAgentNew(nav, enemy, 0.4, 1.8, 2.5) }
    end
end
nav = navNew(agentRadius, agentHeight, maxSlope, maxStep)

Commence un maillage de navigation pour des agents de ce rayon et de cette hauteur, capables de monter des marches jusqu’à maxStep unités et des pentes jusqu’à maxSlope degrés. Le rayon et la hauteur sont maintenus à 0.01 ou plus, la pente entre 0 et 89 et la marche à 0 ou plus. Le rayon fixe aussi la résolution du précalcul, une cellule en faisant le tiers : il décide donc du temps que prend navBuild et de la taille du niveau qu’il peut couvrir. Ajoutez la géométrie avec navAddNode, puis navBuild. Met fin au script quand huit maillages existent déjà.

Paramètres :

  • agentRadius — le rayon des agents, en unités du monde ; les murs sont élargis d’autant.

  • agentHeight — leur hauteur ; les plafonds plus bas ne sont pas praticables.

  • maxSlope — la pente praticable la plus raide, en degrés.

  • maxStep — la plus haute marche qu’ils montent, en unités du monde.

Renvoie : Le handle du maillage, un entier.

Depuis : 3.00. Voir aussi : navAddNode, navBuild, navLoad

Exemple
-- Sponza pour un agent large de 0,8 et haut de 1,6 qui monte 0,3 et marche sur des pentes jusqu'à 45 degrés.
local sponza = modelInstance(modelLoad("Models/Sponza.glb"))
local nav    = navNew(0.4, 1.6, 45, 0.3)
navAddNode(nav, sponza)
navBuild(nav)
points = navPath(nav, x0, y0, z0, x1, y1, z1)

Les coins du plus court chemin à pied d’un point à un autre, tous deux d’abord ramenés sur le maillage, sous forme d’une table de tables { x, y, z }, la première au départ et la dernière à l’arrivée ; jusqu’à 256 coins. Quand l’arrivée ne peut pas être atteinte, le chemin s’arrête au point accessible le plus proche en chemin, si bien que le dernier coin est toujours un endroit où un agent peut se tenir. nil quand l’une des extrémités est loin du maillage ou qu’aucun chemin n’est trouvé. Pour dessiner un itinéraire, mesurer à quelle distance se trouve quelque chose à pied, ou déplacer vous-même quelque chose le long du chemin ; les agents le font d’eux-mêmes.

Paramètres :

  • nav — le maillage.

  • x0, y0, z0 — où le chemin commence.

  • x1, y1, z1 — où il finit.

Renvoie : Une table de tables { x, y, z }, ou nil.

Depuis : 3.00. Voir aussi : navAgentMoveTo, navRaycast, navNearest

Exemple
-- La distance à pied jusqu'à la sortie, pour l'affichage des distances de la carte.
function walkingDistance(fromX, fromY, fromZ, toX, toY, toZ)
    local path  = navPath(nav, fromX, fromY, fromZ, toX, toY, toZ)
    local total = 0
    for i = 2, #(path or {}) do
        local dx = path[i][1] - path[i - 1][1]
        local dz = path[i][3] - path[i - 1][3]
        total    = total + math.sqrt(dx * dx + dz * dz)
    end
    return path and total or nil
end
x, y, z = navRandomPoint(nav)

Un point au hasard sur le maillage praticable, partout où il s’étend, pour errer, éparpiller des objets à ramasser ou placer un point d’apparition. nil seulement quand le maillage n’est pas construit.

Renvoie : Trois nombres, ou nil.

Depuis : 3.00. Voir aussi : navAgentMoveTo, navNearest

Exemple
-- Éparpiller vingt pièces sur le sol, chacune un peu au-dessus.
for i = 1, 20 do
    local x, y, z = navRandomPoint(nav)
    local coin    = nodeNew()
    nodeSetMesh(coin, coinMesh, gold)
    nodeSetPosition(coin, x, y + 0.3, z)
    coins[#coins + 1] = coin
end
blocked, x, y, z = navRaycast(nav, x0, y0, z0, x1, y1, z1)

Indique si une marche en ligne droite d’un point à un autre quitte le maillage, contre un mur ou à un à-pic, et à quel endroit. Le départ est ramené sur le maillage ; false seul signifie que la voie est libre, ou que le départ est loin du maillage. En cas de blocage, le point est celui où la ligne franchit le bord du maillage, sa hauteur étant interpolée entre les deux extrémités. Une vérification peu coûteuse de l’existence d’un raccourci avant de demander navPath.

Paramètres :

  • nav — le maillage.

  • x0, y0, z0 — où la marche commence.

  • x1, y1, z1 — où elle finirait.

Renvoie : false, ou true et le point où la marche quitte le maillage.

Depuis : 3.00. Voir aussi : navPath, physicsRaycast

Exemple
-- Une grenade lancée ne roule que jusqu'où le sol le lui permet.
function landingSpot(fromX, fromY, fromZ, toX, toY, toZ)
    local blocked, hx, hy, hz = navRaycast(nav, fromX, fromY, fromZ, toX, toY, toZ)
    if blocked then
        return hx, hy, hz
    end
    return toX, toY, toZ
end
navSave(nav, name)

Écrit le maillage précalculé dans le dossier de données du jeu sous le nom name, pour navLoad la fois suivante, ou pour le copier dans le dossier du jeu afin de le livrer. Le maillage doit être construit. Met fin au script quand il ne l’est pas, ou quand le fichier ne peut pas être écrit.

Depuis : 3.00. Voir aussi : navLoad, navBuild

Exemple
-- Précalculé une fois sur cette machine, puis chargé depuis le dossier de données aux lancements suivants.
local nav = navNew(0.4, 1.6, 45, 0.3)
navAddNode(nav, level)
navBuild(nav)
navSave(nav, "level1.nav")
debugPrint("Navigation mesh baked and saved.")

2.27. Réseau

Ce que le moteur ajoute sous Singe/Net.singe, le client HTTP du menu. La plupart des jeux n’y touchent jamais : publier un score ou récupérer un catalogue passe par Net.singe, qui l’appelle pour vous.

2.27.1. netTrustHost

ok = netTrustHost(connection, host)

Fait refuser à une connexion cliente LuaSec un certificat qui n’est pas celui de host. À appeler après ssl.wrap et avant la négociation. Un contexte créé avec verify = "peer" vérifie que le certificat du serveur remonte à une racine de confiance, ce qui dit que le certificat est authentique mais pas à qui il appartient : sans cet appel, un certificat authentique pour n’importe quel autre nom est accepté, et connection:sni(host) n’y change rien, puisqu’il indique seulement au serveur quel certificat présenter. Avec lui, la négociation échoue sauf si le certificat cite host parmi ses noms, ou parmi ses adresses quand host est une adresse IP. Un caractère générique dans un certificat vaut pour un label entier.

Paramètres :

  • connection — une connexion issue de ssl.wrap. Toute autre valeur met fin au script.

  • host — chaîne, le nom ou l’adresse auquel on se connecte.

Renvoie : true, ou false quand le nom n’a pas pu être fixé.

Depuis : 3.00. Voir aussi : netTrustSystem

Exemple
-- Le certificat doit être celui du serveur demandé.
local wrapped = ssl.wrap(sock, context)
wrapped:sni("scores.example.com")
netTrustHost(wrapped, "scores.example.com")

2.27.2. netTrustSystem

lists, report = netTrustSystem(context)

Ajoute les certificats racines de confiance propres à la machine à un contexte client LuaSec, en plus de ce que le contexte contient déjà (normalement le Singe/cacerts.pem fourni). Une connexion établie avec ce contexte est alors vérifiée dès que l’une ou l’autre des listes connaît la racine du serveur. La liste de la machine est, dans l’ordre : le fichier ou le répertoire que désigne SSL_CERT_FILE ou SSL_CERT_DIR quand ils sont définis ; sinon, le bundle de la distribution sous Linux (le premier des six emplacements habituels qui existe), le magasin système racine sous Windows, ou les ancres système sous macOS. cacerts.local.pem, dans le dossier de données, est ajouté lui aussi quand il existe ; le moteur ne l’écrit jamais.

lists est le nombre de listes qui ont ajouté quelque chose. report nomme ce qui a été consulté, un what path par ligne (what vaut system ou local), pour un message d’erreur sur lequel une personne peut agir.

Depuis : 3.00. Voir aussi : utilSha256

Exemple
-- Un seul contexte pour toutes les requêtes : le bundle fourni, puis par-dessus les racines de cette machine.
local ssl     = require("ssl")
local context = ssl.newcontext({ mode = "client", protocol = "any", verify = "peer", cafile = "Singe/cacerts.pem" })
local lists, report = netTrustSystem(context)

debugPrint("Trusting the shipped bundle and " .. lists .. " more:\n" .. report)

2.28. Nœud

Chaque objet d’une scène est un nœud d’un seul et même arbre : le nœud 0 est la racine, et tous les autres nœuds sont suspendus sous un parent. Un nœud porte une position, une rotation et une échelle relatives à ce parent, et peut dessiner un maillage avec un matériau, montrer un sprite ou une ligne de texte, ou briller comme une lumière ; les enfants héritent de la transformation de tout ce qui se trouve au-dessus d’eux. Les handles sont des entiers renvoyés par nodeNew, modelInstance et lightNew ; un handle dont le nœud a été supprimé met fin au script quand il est repassé, et un handle libéré peut être réutilisé par un nodeNew ultérieur. Les positions et les tailles sont en unités de scène et les rotations en degrés, avec +Y vers le haut et -Z vers l’avant, comme le décrit Scènes 3D.

2.28.1. nodeNew

node = nodeNew()
node = nodeNew(parent)

Crée un nœud vide à l’origine de son parent, sans rotation, à l’échelle 1, visible, projetant des ombres, sans maillage ni matériau. Sans parent, le nœud va sous la racine ; avec un parent, il devient le dernier enfant de ce nœud et se déplace désormais avec lui. Les nœuds vides servent de pivots et de groupes : placez-en un, suspendez-y des maillages, des lumières ou une caméra, puis déplacez le groupe d’un seul bloc.

Renvoie : Le handle du nœud.

Depuis : 3.00. Voir aussi : nodeSetMesh, nodeSetParent, nodeDelete, lightNew

Exemple
-- Une tourelle dont le canon pivote sur la tourelle, qui tourne sur la base.
local steel  = materialNew()
materialSetColor(steel, 140, 145, 150)
local base   = nodeNew()
local turret = nodeNew(base)
local barrel = nodeNew(turret)
nodeSetMesh(base,   meshCylinder(1, 0.3), steel)
nodeSetMesh(turret, meshSphere(0.6), steel)
nodeSetMesh(barrel, meshCylinder(0.1, 1.2), steel)
nodeSetPosition(barrel, 0, 0, -0.8)
nodeSetRotation(barrel, 90, 0, 0)

2.28.2. nodeDelete

nodeDelete(node)

Supprime le nœud et tout ce qui se trouve sous lui, en libérant chaque handle de ce sous-arbre ; un sprite ou un texte posé sur l’un d’eux est libéré aussi. Les maillages et les matériaux que dessinaient les nœuds ne sont pas touchés, puisque d’autres nœuds peuvent les partager. Si le nœud supprimé était la caméra, la scène revient à la vue par défaut. Le nœud racine ne peut pas être supprimé ; le demander met fin au script.

Depuis : 3.00. Voir aussi : nodeNew, nodeSetVisible, meshDelete

Exemple
-- Les tirs vivent deux secondes, puis leurs nœuds disparaissent.
function fireShot(ship)
    local shot = nodeNew()
    nodeSetMesh(shot, shotMesh, tracer)
    nodeSetPosition(shot, nodeGetWorldPosition(ship))
    shots[#shots + 1] = { node = shot, born = os.clock() }
end

function reapShots()
    for i = #shots, 1, -1 do
        if os.clock() - shots[i].born > 2 then
            nodeDelete(shots[i].node)
            table.remove(shots, i)
        end
    end
end

2.28.3. nodeFind

node = nodeFind(name)
node = nodeFind(name, root)

Cherche, en profondeur d’abord, le premier nœud nommé name, en partant de root (la racine de la scène quand il est omis) et en examinant root lui-même avant ses enfants, puis le sous-arbre de chaque enfant à son tour. Renvoie nil quand rien ne correspond. Les nœuds d’un modèle portent les noms de leur fichier glTF, si bien qu’un os, un maillage ou un objet vide servant de repère placé dans Blender peut être trouvé par ce nom sous la racine de l’instance. Les noms donnés avec nodeSetName se trouvent de la même façon.

Renvoie : Un handle de nœud, ou nil.

Depuis : 3.00. Voir aussi : nodeSetName, nodeGetName, modelInstance, nodeGetChildren

Exemple
-- Accrocher une torche à la main droite du héros, trouvée par le nom de son os.
local hero = modelInstance(heroModel)
local hand = nodeFind("hand_R", hero)
if hand then
    local torch = modelInstance(torchModel)
    nodeSetParent(torch, hand)
    nodeSetPosition(torch, 0, 0.05, 0)
    nodeSetRotation(torch, 0, 0, -90)
end

2.28.4. nodeGetChildren

children = nodeGetChildren(node)

Les enfants directs du nœud sous forme d’une table de handles, dans l’ordre où ils ont été attachés ; changer le parent d’un nœud le place à la fin de la liste de son nouveau parent. Les petits-enfants ne sont pas inclus ; procédez récursivement pour parcourir un sous-arbre entier. Une table vide signifie que le nœud n’a pas d’enfants.

Renvoie : Une table de handles de nœuds.

Depuis : 3.00. Voir aussi : nodeGetParent, nodeFind, nodeSetParent

Exemple
-- Donner à chaque partie d'un accessoire chargé le même matériau usé.
local function paint(node, material)
    nodeSetMaterial(node, material)
    for _, child in ipairs(nodeGetChildren(node)) do
        paint(child, material)
    end
end

local crate = modelInstance(crateModel)
paint(crate, wornWood)

2.28.5. nodeGetMorph

weight = nodeGetMorph(node, nameOrIndex)

Le poids actuel d’une cible de morphing du maillage du nœud, désignée par son nom ou par son numéro à partir de 1, dans l’ordre où nodeGetMorphs les liste. Le nœud est celui qui porte le maillage, pas la racine d’une instance de modèle. Un nom ou un numéro que le maillage n’a pas met fin au script.

Renvoie : Un nombre, 0 tant que rien n’a réglé la cible.

Depuis : 3.00. Voir aussi : nodeSetMorph, nodeGetMorphs

Exemple
-- Faire venir le sourire en douceur sur plusieurs images au lieu de l'afficher d'un coup.
function onOverlayUpdate()
    local now    = nodeGetMorph(face, "smile")
    local target = happy and 1 or 0
    nodeSetMorph(face, "smile", now + (target - now) * 0.1)
    return OVERLAY_UPDATED
end

2.28.6. nodeGetMorphs

names = nodeGetMorphs(node)

Les cibles de morphing du maillage du nœud sous forme d’une table de noms, dans l’ordre où le fichier les stocke ; cet ordre est la numérotation qu’acceptent nodeSetMorph et nodeGetMorph. Les exportateurs qui n’écrivent pas de noms donnent des chaînes vides, et ces cibles peuvent toujours être réglées par numéro. Un nœud sans maillage, ou un maillage sans cibles, donne une table vide.

Renvoie : Une table de chaînes.

Depuis : 3.00. Voir aussi : nodeSetMorph, nodeGetMorph, modelLoad

Exemple
-- Associer une fois les noms des cibles du visage à des numéros, pour que la synchronisation labiale puisse les indexer.
local head    = nodeFind("Head", hero)
local visemes = {}
for index, name in ipairs(nodeGetMorphs(head)) do
    if name ~= "" then
        visemes[name] = index
    end
end
debugPrint(string.format("%d morph targets on the head", #nodeGetMorphs(head)))

2.28.7. nodeGetName

name = nodeGetName(node)

Le nom du nœud : celui que lui a donné nodeSetName, ou son nom glTF pour un nœud de modèle, une chaîne vide quand il n’a ni l’un ni l’autre. Le nœud racine s’appelle root.

Renvoie : Une chaîne.

Depuis : 3.00. Voir aussi : nodeSetName, nodeFind

Exemple
-- Afficher l'arbre des nœuds d'un modèle dans la console pour trouver les noms des os.
local function dump(node, depth)
    debugPrint(string.rep("  ", depth) .. nodeGetName(node) .. " (" .. node .. ")")
    for _, child in ipairs(nodeGetChildren(node)) do
        dump(child, depth + 1)
    end
end

dump(modelInstance(heroModel), 0)

2.28.8. nodeGetParent

parent = nodeGetParent(node)

Le handle du parent du nœud, ou nil pour la racine. Tout autre nœud a un parent, ne serait-ce que la racine.

Renvoie : Un handle de nœud, ou nil.

Depuis : 3.00. Voir aussi : nodeSetParent, nodeGetChildren

Exemple
-- Remonter d'un nœud de maillage choisi jusqu'au sommet de son instance de modèle.
local function instanceRoot(node)
    local parent = nodeGetParent(node)
    while parent and parent ~= 0 do
        node   = parent
        parent = nodeGetParent(node)
    end
    return node
end

2.28.9. nodeGetPosition

x, y, z = nodeGetPosition(node)

La position du nœud relative à son parent, telle que l’ont réglée en dernier nodeSetPosition, nodeMove ou le moteur (un corps, un véhicule ou une animation qui le déplace). Pour savoir où se trouve le nœud dans le monde, utilisez nodeGetWorldPosition.

Renvoie : Trois nombres.

Depuis : 3.00. Voir aussi : nodeSetPosition, nodeGetWorldPosition, nodeMove

Exemple
-- La caméra suit la voiture, trois unités au-dessus, trois à droite et neuf derrière.
function onOverlayUpdate()
    local cx, cy, cz = nodeGetPosition(car)
    nodeSetPosition(camera, cx + 3, cy + 3, cz + 9)
    nodeLookAt(camera, cx, cy, cz - 3)
    return OVERLAY_UPDATED
end

2.28.10. nodeGetQuaternion

x, y, z, w = nodeGetQuaternion(node)

La rotation du nœud relative à son parent sous forme de quaternion unitaire, la forme que stockent les modèles et les animations. Servez-vous-en pour copier une rotation d’un nœud à l’autre ou pour garder une pose sans l’ambiguïté des angles d’Euler.

Renvoie : Quatre nombres.

Depuis : 3.00. Voir aussi : nodeSetQuaternion, nodeGetRotation

Exemple
-- Retenir la pose de la porte avant le test du ragdoll, puis la remettre.
local px, py, pz     = nodeGetPosition(door)
local qx, qy, qz, qw = nodeGetQuaternion(door)

function resetDoor()
    nodeSetPosition(door, px, py, pz)
    nodeSetQuaternion(door, qx, qy, qz, qw)
end

2.28.11. nodeGetRotation

x, y, z = nodeGetRotation(node)

La rotation du nœud relative à son parent sous forme d’angles d’Euler en degrés, décomposée de la même façon que nodeSetRotation la compose : tournée autour de Y, puis inclinée autour de X, puis mise en roulis autour de Z. Les angles décrivent la même rotation que celle qui a été réglée, mais pas forcément avec les mêmes nombres : X revient entre -90 et 90, et quand il atteint 90 ou -90, la torsion est donnée à Y et Z est renvoyé à 0.

Renvoie : Trois nombres.

Depuis : 3.00. Voir aussi : nodeSetRotation, nodeGetQuaternion

Exemple
-- Une boussole dans l'overlay, d'après le cap du vaisseau.
function onOverlayUpdate()
    local _, heading = nodeGetRotation(ship)
    overlayClear()
    fontPrint(20, 20, string.format("Heading %03d", (360 - heading) % 360))
    return OVERLAY_UPDATED
end

2.28.12. nodeGetScale

x, y, z = nodeGetScale(node)

L’échelle propre du nœud sur chaque axe, telle que l’a réglée nodeSetScale (1, 1, 1 pour un nouveau nœud). Les échelles des parents n’y sont pas intégrées.

Renvoie : Trois nombres.

Depuis : 3.00. Voir aussi : nodeSetScale

Exemple
-- Faire grandir le bonus jusqu'à sa taille normale, un peu à chaque image.
function onOverlayUpdate()
    local size = nodeGetScale(powerUp)
    if size < 1 then
        nodeSetScale(powerUp, math.min(1, size + 0.05))
    end
    return OVERLAY_UPDATED
end

2.28.13. nodeGetWorldPosition

x, y, z = nodeGetWorldPosition(node)

L’endroit où se trouve l’origine du nœud dans l’espace du monde, avec la transformation de chaque parent appliquée, tel qu’à la dernière image rendue. Les changements faits à cette image (les vôtres, ou ceux d’un corps) se voient après le rendu suivant, et un nœud créé à cette image renvoie 0, 0, 0 jusque-là. C’est la position à donner à sceneProject ou à un test de distance.

Renvoie : Trois nombres.

Depuis : 3.00. Voir aussi : sceneProject, nodeLookAt, nodeGetPosition

Exemple
-- Une étiquette de nom dans l'overlay au-dessus du canard, où que la physique l'ait emmené.
function onOverlayUpdate()
    local dx, dy, dz = nodeGetWorldPosition(duck)
    local sx, sy     = sceneProject(dx, dy + 0.8, dz)
    overlayClear()
    if sx then
        fontPrint(sx - 20, sy, "DUCK")
    end
    return OVERLAY_UPDATED
end

2.28.14. nodeLookAt

nodeLookAt(node, x, y, z)

Tourne le nœud pour que son propre -Z pointe vers une position du monde, en gardant son +Y aussi proche du haut du monde que la direction le permet. C’est ce que veulent les caméras et les lumières, et cela convient aussi à une tourelle ou à une tête qui suit une cible. Seule la rotation du nœud change ; sa position reste. Si la cible coïncide avec la position du nœud, rien ne change.

Remarques : Le point du monde est converti dans l’espace du parent à l’aide de la transformation du parent à la dernière image rendue ; un nœud dont le parent a bougé à cette même image vise depuis l’endroit où se trouvait le parent.

Depuis : 3.00. Voir aussi : cameraSet, lightNew, nodeSetRotation

Exemple
local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -8, 3, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 2.2, 7)
nodeLookAt(camera, 0, 1.3, 0)
cameraSet(camera)

2.28.15. nodeMove

nodeMove(node, dx, dy, dz)

Déplace le nœud selon ses propres axes : le décalage est tourné par la rotation actuelle du nœud et ajouté à sa position, si bien que nodeMove(ship, 0, 0, -0.1) fait avancer le vaisseau dans la direction où il pointe, quelle qu’elle soit, et que nodeMove(ship, 0.1, 0, 0) le fait glisser latéralement vers la droite. Utilisez nodeSetPosition pour un emplacement absolu dans l’espace du parent.

Depuis : 3.00. Voir aussi : nodeSetPosition, nodeRotate

Exemple
-- Commandes de char : tourner avec gauche et droite, avancer avec haut et bas.
function onOverlayUpdate()
    if keyboardIsDown(SCANCODE_LEFT)  then nodeRotate(tank, 0,  2, 0) end
    if keyboardIsDown(SCANCODE_RIGHT) then nodeRotate(tank, 0, -2, 0) end
    if keyboardIsDown(SCANCODE_UP)    then nodeMove(tank, 0, 0, -0.08) end
    if keyboardIsDown(SCANCODE_DOWN)  then nodeMove(tank, 0, 0,  0.04) end
    return OVERLAY_UPDATED
end

2.28.16. nodeRotate

nodeRotate(node, dx, dy, dz)

Tourne le nœud du nombre de degrés donné autour de ses propres axes, en plus de sa rotation actuelle : nodeRotate(wheel, 5, 0, 0) à chaque image fait tourner la roue sur son propre X, quelle que soit l’inclinaison de l’essieu. Les trois angles sont combinés comme nodeSetRotation les combine (Y, puis X, puis Z) avant d’être appliqués. Les angles positifs tournent dans le sens inverse des aiguilles d’une montre quand on regarde le long de l’axe vers l’origine.

Depuis : 3.00. Voir aussi : nodeSetRotation, nodeMove, nodeSetQuaternion

Exemple
-- Le logo tourne d'un demi-degré par image autour de son propre axe vertical.
local logo = modelInstance(logoModel)
nodeSetPosition(logo, 0, -2.5, 0)
nodeSetRotation(logo, 0, -30, 0)

function onOverlayUpdate()
    nodeRotate(logo, 0, 0.5, 0)
    return OVERLAY_UPDATED
end

2.28.17. nodeSetBillboard

nodeSetBillboard(node, mode)

Tourne le nœud face à la caméra à chaque image. BILLBOARD_ALL lui fait face de plein front, en prenant les trois axes de la caméra ; BILLBOARD_Y tourne autour du haut du monde seulement, si bien que le nœud reste debout (arbres, barres de vie) ; BILLBOARD_NONE, la valeur par défaut, ne tourne pas du tout. La position et l’échelle du nœud dans le monde sont conservées, et sa propre rotation est ignorée tant qu’un mode est réglé. Toute autre valeur met fin au script. Cela fonctionne sur les maillages aussi bien que sur les sprites et le texte, et se tourne vers la caméra qui dessine, quelle qu’elle soit : une vue voit elle aussi le billboard de face, tandis que son ombre suit la caméra de la fenêtre.

Depuis : 3.00. Voir aussi : nodeSetSprite, nodeSetText, cameraSet

Exemple
-- Un nom au-dessus du renard, face à la caméra de plein front, et une icône de caisse
-- qui ne tourne qu'autour de son propre axe vertical.
local tag = nodeNew()
nodeSetParent(tag, fox)
nodeSetPosition(tag, 0, 110, 0)
nodeSetScale(tag, 50)
nodeSetText(tag, "FOX", 0.6)
nodeSetBillboard(tag, BILLBOARD_ALL)
nodeSetShadow(tag, false)
local icon = nodeNew()
nodeSetParent(icon, fox)
nodeSetPosition(icon, 0, 150, 0)
nodeSetScale(icon, 50)
nodeSetSprite(icon, spriteLoad("crate.png"), 0.5)
nodeSetBillboard(icon, BILLBOARD_Y)

2.28.18. nodeSetLayer

nodeSetLayer(node, layer)

Choisit où, dans la fenêtre, le nœud est dessiné. LAYER_SCENE, la valeur par défaut, le dessine dans la scène sous l’overlay ; LAYER_FRONT le dessine après l’overlay, par la même caméra avec les mêmes lumières, dans une couche transparente qui lui est propre. Un nœud de la couche avant emmène ses enfants avec lui, quel que soit leur propre réglage. Toute autre valeur met fin au script. Voir Devant l’overlay.

Depuis : 3.00. Voir aussi : sceneEnable, nodeSetVisible, emitterSetLayer

Exemple
-- Le vaisseau du joueur se tient sur l'écran de carte 2D tant qu'il est ouvert, et
-- retourne dans le monde quand il se ferme.
function showMap(open)
    nodeSetLayer(ship, open and LAYER_FRONT or LAYER_SCENE)
end

2.28.19. nodeSetMaterial

nodeSetMaterial(node, material)
nodeSetMaterial(node, nil)

Pose un matériau sur le maillage du nœud, quel qu’il soit, en gardant le maillage. nil le retire, ce qui laisse l’aspect par défaut : blanc, à moitié rugueux, sans texture. Servez-vous-en pour changer le style d’une partie d’un modèle, pour mettre et retirer un matériau de surbrillance, ou pour habiller un maillage que le moteur a fait pour vous, comme le tube d’une corde venant de softNew. Un handle de matériau qui n’existe pas met fin au script.

Depuis : 3.00. Voir aussi : nodeSetMesh, materialNew, softNew

Exemple
-- La corde pend de la grue ; le moteur fait son tube, nous l'habillons.
local hemp = materialNew()
materialSetColor(hemp, 170, 140, 90)
materialSetRoughness(hemp, 1)
local rope = nodeNew()
nodeSetPosition(rope, 4, 4, -1)
softNew(rope, SOFT_ROPE, 6.5, 4, -1, 16, 0.04)
nodeSetMaterial(rope, hemp)
softSetMass(rope, 1.5)
softPin(rope, 4, 4, -1, crane)

2.28.20. nodeSetMesh

nodeSetMesh(node, mesh)
nodeSetMesh(node, mesh, material)

Donne au nœud un maillage à dessiner, avec un matériau ou, en son absence, l’aspect par défaut (blanc, à moitié rugueux). Les deux arguments doivent être des handles valides ; un maillage ou un matériau manquant met fin au script. Tout nœud peut dessiner, y compris un nœud à l’intérieur d’une instance de modèle, et un nombre quelconque de nœuds peuvent partager un même maillage. Les poids de morphing du nœud sont dimensionnés selon les cibles du nouveau maillage et commencent à 0.

Depuis : 3.00. Voir aussi : meshBox, materialNew, nodeSetMaterial, nodeSetVisible

Exemple
-- Une carrosserie avec quatre roues, chacune un cylindre tourné pour que son X soit l'essieu.
local car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 0.9, 0)
local tireMesh = meshCylinder(0.35, 0.25, 16)
for _, p in ipairs({ { -0.95, -0.2, -1.4 }, { 0.95, -0.2, -1.4 }, { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 } }) do
    local wheel = nodeNew(car)
    nodeSetPosition(wheel, p[1], p[2], p[3])
    local tire = nodeNew(wheel)
    nodeSetMesh(tire, tireMesh, rubber)
    nodeSetRotation(tire, 0, 0, 90)
end

2.28.21. nodeSetMorph

nodeSetMorph(node, nameOrIndex, weight)

Règle dans quelle mesure le maillage du nœud montre une cible de morphing (blend shape), désignée par son nom ou par son numéro à partir de 1 ; les poids vont en général de 0 à 1 et plusieurs cibles s’additionnent. Le nœud est celui qui porte le maillage, c’est-à-dire, pour un modèle, un enfant de la racine de l’instance (nodeFind par le nom du maillage, ou nodeGetChildren). Une cible que le maillage n’a pas met fin au script. Une animation dotée d’un canal de poids écrit les poids à chaque image tant qu’elle joue, ce qui écrase ce que vous avez réglé.

Remarques : Jusqu’à huit cibles de poids non nul s’appliquent par maillage et par image ; au-delà, ce sont les huit plus fortes en valeur absolue qui sont utilisées.

Depuis : 3.00. Voir aussi : nodeGetMorph, nodeGetMorphs, animationPlay

Exemple
-- Synchronisation labiale d'après une table d'ouvertures de bouche par image du disque.
local face = nodeFind("Head", hero)

function onOverlayUpdate()
    nodeSetMorph(face, "mouthOpen", mouthByFrame[discGetFrame()] or 0)
    return OVERLAY_UPDATED
end

2.28.22. nodeSetName

nodeSetName(node, name)

Nomme le nœud pour que nodeFind puisse le trouver plus tard, en remplaçant le nom qu’il avait (y compris le nom glTF d’un nœud de modèle). Les noms n’ont pas besoin d’être uniques ; nodeFind renvoie la première correspondance dans l’ordre en profondeur d’abord.

Depuis : 3.00. Voir aussi : nodeFind, nodeGetName

Exemple
-- Les caisses créées sont nommées pour que le script du niveau puisse les trouver par emplacement.
for slot = 1, 6 do
    local crate = nodeNew()
    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, slot * 1.5 - 5, 0.5, -3)
    nodeSetName(crate, "crate" .. slot)
end
nodeSetVisible(nodeFind("crate4"), false)

2.28.23. nodeSetParent

nodeSetParent(node, parent)

Déplace le nœud, avec tout son sous-arbre, sous un autre parent, dont il devient le dernier enfant. La position, la rotation et l’échelle locales du nœud sont gardées telles quelles, si bien qu’il se trouve maintenant à ce décalage du nouveau parent et se déplace avec lui ; passez 0 pour le ramener à la racine. La racine ne peut pas être déplacée, et un nœud ne peut aller ni sous lui-même ni sous l’un de ses propres descendants ; l’un comme l’autre met fin au script.

Depuis : 3.00. Voir aussi : nodeGetParent, nodeNew, nodeSetPosition

Exemple
-- Ramasser une caisse : elle voyage dans la main à partir de maintenant, elle sera posée plus tard.
function pickUp(crate)
    nodeSetParent(crate, nodeFind("hand_R", hero))
    nodeSetPosition(crate, 0, 0.3, 0)
    nodeSetRotation(crate, 0, 0, 0)
end

function putDown(crate, x, y, z)
    nodeSetParent(crate, 0)
    nodeSetPosition(crate, x, y, z)
end

2.28.24. nodeSetPosition

nodeSetPosition(node, x, y, z)

Place le nœud en x, y, z dans l’espace de son parent ; pour un nœud sous la racine, c’est l’espace du monde. Les enfants suivent. Un nœud portant un corps dynamique est ensuite déplacé par la physique ; réglez sa position avant bodyNew, ou téléportez-le au moyen des appels de corps.

Depuis : 3.00. Voir aussi : nodeMove, nodeGetPosition, nodeSetRotation

Exemple
-- Des caisses lâchées le long d'une crête, chacune six unités au-dessus du sol à cet endroit.
for i = 1, 10 do
    local crate  = nodeNew()
    local x, z   = -20 + i * 4, -12
    nodeSetMesh(crate, meshBox(1, 1, 1), wood)
    nodeSetPosition(crate, x, (terrainGetHeight(hills, x, z) or 0) + 6, z)
    nodeSetRotation(crate, i * 17, i * 31, 0)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 1, 1, 1)
end

2.28.25. nodeSetQuaternion

nodeSetQuaternion(node, x, y, z, w)

Règle la rotation du nœud relative à son parent sous forme de quaternion, pour des valeurs venant de nodeGetQuaternion, d’un modèle ou de vos propres calculs. Le quaternion est normalisé à l’entrée, si bien qu’il n’a pas besoin d’être de longueur unité.

Depuis : 3.00. Voir aussi : nodeSetRotation, nodeGetQuaternion

Exemple
-- Le fantôme copie exactement la pose du héros, avec un temps de retard.
local qx, qy, qz, qw = nodeGetQuaternion(hero)
local px, py, pz     = nodeGetPosition(hero)
history[#history + 1] = { px, py, pz, qx, qy, qz, qw }
if #history > 30 then
    local old = table.remove(history, 1)
    nodeSetPosition(ghost, old[1], old[2], old[3])
    nodeSetQuaternion(ghost, old[4], old[5], old[6], old[7])
end

2.28.26. nodeSetRotation

nodeSetRotation(node, x, y, z)

Règle la rotation du nœud relative à son parent sous forme d’angles d’Euler en degrés, en remplaçant celle qu’il avait : le nœud est d’abord tourné autour de son Y (lacet), puis incliné autour de son X (tangage), puis mis en roulis autour de son Z. Les angles positifs tournent dans le sens inverse des aiguilles d’une montre quand on regarde le long de l’axe vers l’origine, si bien que nodeSetRotation(plane, 90, 0, 0) relève un plan de sol pour qu’il fasse face à +Z.

Depuis : 3.00. Voir aussi : nodeRotate, nodeSetQuaternion, nodeLookAt

Exemple
-- Un écran de moniteur posé sur un pied, face à la caméra en +Z.
local monitor = nodeNew()
nodeSetMesh(monitor, meshPlane(2.0, 1.5), screen)
nodeSetPosition(monitor, -3, 2.1, 1.06)
nodeSetRotation(monitor, 90, 0, 0)
-- Une rampe inclinée de 25 degrés autour de Z.
local ramp = nodeNew()
nodeSetMesh(ramp, meshBox(6, 0.2, 3), asphalt)
nodeSetRotation(ramp, 0, 0, 25)

2.28.27. nodeSetScale

nodeSetScale(node, scale)
nodeSetScale(node, x, y, z)

Met à l’échelle le nœud et tout ce qui se trouve sous lui, uniformément avec un seul facteur ou par axe avec trois. Les modèles chargés sont souvent en centimètres ou en mètres ; mettez une fois à l’échelle la racine de l’instance pour l’adapter à votre scène, et placez les choses sous elle dans les unités propres au modèle. Les sprites et le texte du nœud sont mis à l’échelle eux aussi, en plus de leur height.

Depuis : 3.00. Voir aussi : nodeGetScale, modelInstance

Exemple
-- Le renard est modélisé en centimètres : un centième le ramène en mètres.
local fox = modelInstance(foxModel)
nodeSetParent(fox, player)
nodeSetScale(fox, 0.01)
nodeSetRotation(fox, 0, 90, 0)
-- Une sphère aplatie pour une flaque.
local puddle = nodeNew()
nodeSetMesh(puddle, meshSphere(0.5, 24), water)
nodeSetScale(puddle, 1.5, 0.05, 1.2)

2.28.28. nodeSetShadow

nodeSetShadow(node, casts)

Indique si le maillage du nœud est dessiné dans les cartes d’ombres ; true pour tout nouveau nœud. Désactivez-le pour le maillage qui entoure une lumière (une ampoule, une flamme), afin qu’il ne fasse pas d’ombre à sa propre lumière, et pour tout ce qui brille. Le nœud se dessine toujours et reçoit toujours les ombres des autres. Cela ne s’applique qu’au nœud, pas à ses enfants.

Depuis : 3.00. Voir aussi : lightSetShadow, nodeSetVisible, materialSetUnlit

Exemple
-- Une ampoule dans son abat-jour : le verre ne projette rien, l'abat-jour, si.
local shade = nodeNew(stand)
nodeSetMesh(shade, meshCone(0.45, 0.5, 24), brass)
nodeSetPosition(shade, 0, 0.9, 0)
local bulbMesh = nodeNew(stand)
nodeSetMesh(bulbMesh, meshSphere(0.08, 12), glow)
nodeSetPosition(bulbMesh, 0, 0.8, 0)
nodeSetShadow(bulbMesh, false)
local bulb = lightNew(LIGHT_POINT)
nodeSetParent(bulb, bulbMesh)
lightSetShadow(bulb, true)

2.28.29. nodeSetSprite

nodeSetSprite(node, sprite)
nodeSetSprite(node, sprite, height)
nodeSetSprite(node, sprite, height, lit)
nodeSetSprite(node, nil)
nodeSetSprite(node)

Montre un sprite chargé sur le nœud : un quad haut de height unités du monde (1 par défaut) et aussi large que le format de l’image le veut, mélangé selon l’alpha de l’image, dessiné des deux côtés, et éclairé par la scène sauf si lit vaut false. Chaque image d’un sprite animé est envoyée et la première s’affiche ; nodeSetSpriteFrame en choisit une autre. Le quad devient le maillage du nœud, avec un matériau privé, et remplace tout maillage, sprite ou texte qu’il avait ; nil ou l’absence de second argument retire l’image et laisse le nœud vide. Met fin au script quand le moteur de rendu 3D n’est pas disponible.

Paramètres :

  • sprite — un handle venant de spriteLoad, ou nil pour effacer.

  • height — la hauteur du quad en unités du monde, 1 par défaut ; l’échelle du nœud la multiplie.

  • lit — true (par défaut) applique à l’image les lumières et les ombres de la scène ; false la montre telle quelle.

Depuis : 3.00. Voir aussi : nodeSetSpriteFrame, nodeSetBillboard, spriteLoad, nodeSetText

Exemple
-- Une icône de caisse qui flotte au-dessus du renard et se tourne face au joueur.
local icon = nodeNew()
nodeSetParent(icon, fox)
nodeSetPosition(icon, 0, 150, 0)
nodeSetScale(icon, 50)
nodeSetSprite(icon, spriteLoad("crate.png"), 0.5)
nodeSetBillboard(icon, BILLBOARD_Y)
-- Une lueur non éclairée qui se lit de la même façon dans l'ombre.
local flare = nodeNew(torchTip)
nodeSetSprite(flare, spriteLoad("flare.png"), 0.3, false)
nodeSetBillboard(flare, BILLBOARD_ALL)

2.28.30. nodeSetSpriteFrame

nodeSetSpriteFrame(node, frame)

Quelle image du sprite animé du nœud s’affiche, comptée à partir de 0. Le sprite du nœud n’avance pas tout seul ; pilotez-le depuis onOverlayUpdate. Un nœud sans sprite, ou une image qu’il n’a pas, met fin au script ; un texte et un sprite fixe n’ont que l’image 0.

Depuis : 3.00. Voir aussi : nodeSetSprite, spriteLoad

Exemple
-- Un sprite de feu de camp qui fait défiler ses images à dix par seconde.
local fire = nodeNew()
nodeSetPosition(fire, 2, 0.4, -1)
nodeSetSprite(fire, spriteLoad("campfire.gif"), 0.8, false)
nodeSetBillboard(fire, BILLBOARD_Y)

function onOverlayUpdate()
    nodeSetSpriteFrame(fire, math.floor(os.clock() * 10) % fireFrames)
    return OVERLAY_UPDATED
end

2.28.31. nodeSetText

nodeSetText(node, text)
nodeSetText(node, text, height)
nodeSetText(node, nil)
nodeSetText(node)

Montre une ligne de texte sur le nœud, rendue dans la police sélectionnée (fontSelect), à la qualité courante (fontQuality), dans la couleur de premier plan (colorForeground), sur un quad haut de height unités du monde (1 par défaut) et aussi large que le texte rendu le veut. Il est non éclairé, mélangé et dessiné des deux côtés : étiquettes de nom, panneaux, un score au-dessus d’une table. Comme un sprite, il devient le maillage du nœud et remplace tout maillage, sprite ou texte qui s’y trouvait ; appelez-le de nouveau pour changer le texte, avec nil ou sans second argument pour le retirer. Sans police sélectionnée, ou sans le moteur de rendu 3D, il met fin au script.

Depuis : 3.00. Voir aussi : nodeSetSprite, nodeSetBillboard, fontSelect, colorForeground

Exemple
-- Un panneau fixe près de la lampe, et un score qui se met à jour quand il change.
fontSelect(signFont)
colorForeground(255, 240, 200)
local sign = nodeNew()
nodeSetPosition(sign, 4.2, 1.2, -1.2)
nodeSetRotation(sign, 0, -30, 0)
nodeSetText(sign, "LAMP", 0.5)

function setScore(points)
    nodeSetText(scoreboard, string.format("%06d", points), 0.4)
end

2.28.32. nodeSetVisible

nodeSetVisible(node, visible)

Cache ou montre le nœud et tout ce qui se trouve sous lui ; l’indicateur propre d’un enfant s’applique toujours quand son parent est de nouveau montré. Les maillages cachés ne sont pas dessinés et les lumières cachées cessent de briller. Servez-vous-en pour garder prêt un marqueur ou un accessoire de rechange sans avoir à le supprimer puis le reconstruire.

Depuis : 3.00. Voir aussi : nodeSetMesh, nodeDelete

Exemple
-- Un marqueur qui apparaît là où la balle a touché la raquette pour la dernière fois.
local mark = nodeNew()
nodeSetMesh(mark, meshSphere(0.08, 12), markLook)
nodeSetVisible(mark, false)

function onCollision(a, b, x, y, z)
    if (a == ball and b == paddle) or (a == paddle and b == ball) then
        nodeSetPosition(mark, x, y, z)
        nodeSetVisible(mark, true)
    end
end

2.29. Overlay

L’overlay est une surface RGBA 32 bits composée par-dessus la vidéo à chaque image ; tout le dessin 2D y aboutit. Ses coordonnées suivent la résolution de l’overlay réglée par overlaySetResolution, qui vaut par défaut la moitié de la largeur et de la hauteur de la vidéo, et sont mises à l’échelle de la fenêtre au moment de l’affichage. Dessinez depuis onOverlayUpdate (ou depuis singeMain dans le modèle À fil d’exécution) et renvoyez OVERLAY_UPDATED quand quelque chose a changé. Les primitives overlay* dessinent des contours d’un pixel dans la couleur de premier plan actuelle et découpent sans rien dire tout ce qui tombe hors de la surface. overlayPrint fait exception : il prend des coordonnées en cellules de caractères et copie telle quelle la police de console intégrée, sans tenir compte des réglages de couleur.

2.29.1. overlayBanner

overlayBanner(text [, height])

Extension Hypseus. Affiche un court message par-dessus l’image pendant une trentaine d’images dessinées, puis le retire. height est l’endroit où il se place, en pourcentage de la hauteur de l’image en partant du haut, de 1 à 95 ; la valeur par défaut est 47, celle d’Hypseus lui-même, et un nombre hors de cet intervalle est remplacé par la valeur par défaut au lieu d’être refusé.

Un message de plus de 60 caractères est ignoré, exactement comme Hypseus l’ignore. Le bandeau est dessiné par le même document fourni que celui qu’utilisent les sous-titres (Singe/subtitle.rml, mis en forme par Singe/subtitle.rcss), si bien qu’il ressemble à un sous-titre et se met en forme avec eux ; tant qu’il est affiché, il prend la place de tout sous-titre, et le sous-titre revient quand le bandeau expire. Le texte est dessiné comme du texte, si bien que <, > et & arrivent à l’écran tels quels.

Paramètres :

  • text — chaîne ; jusqu’à 60 caractères.

  • height — nombre facultatif ; de 1 à 95, en pourcentage de la hauteur de l’image en partant du haut. Par défaut 47.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : srtLoad, Sous-titres, overlayPrint

Exemple
-- Dire au joueur ce qui vient de se passer sans construire de HUD pour cela.
overlayBanner("Extra life!", 20)

2.29.2. overlayBox

overlayBox(x1, y1, x2, y2)

Dessine le contour du rectangle aligné sur les axes dont les coins opposés sont (x1, y1) et (x2, y2), sous forme de quatre lignes d’un pixel dans la couleur de premier plan. Les deux coins sont inclus et peuvent être donnés dans n’importe quel ordre. Il n’existe pas de variante pleine ; remplissez tout l’overlay avec overlayClear sur une couleur de fond, ou une zone avec un sprite étiré.

Depuis : 2.00 Voir aussi : overlayLine, colorForeground, overlayClear

Exemple
-- Encadrer l'overlay en rouge et tracer le contour de chaque bloc de plateforme.
function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 0, 0, 255)
    overlayBox(0, 0, overlayGetWidth() - 1, overlayGetHeight() - 1)
    colorForeground(90, 90, 110, 255)
    for _, b in ipairs(blocks) do
        overlayBox(b.x - b.w / 2, b.y - b.h / 2, b.x + b.w / 2, b.y + b.h / 2)
    end
    return OVERLAY_UPDATED
end

2.29.3. overlayCircle

overlayCircle(x, y, radius)

Dessine le contour d’un cercle d’un pixel dans la couleur de premier plan, centré sur (x, y), avec l’algorithme du point milieu. Un rayon de 0 ou moins ne dessine rien. Les coordonnées et le rayon sont des entiers en unités de l’overlay ; les fractions sont tronquées.

Paramètres :

  • x, y — le centre en coordonnées de l’overlay.

  • radius — le rayon en unités de l’overlay.

Depuis : 2.00 Voir aussi : overlayEllipse, overlayPlot, colorForeground

Exemple
-- Un réticule de viseur qui devient rouge tant que le joueur est touché.
function onOverlayUpdate()
    if hitTimer > 0 then
        colorForeground(255, 0, 0, 255)
        hitTimer = hitTimer - 1
    else
        colorForeground(255, 255, 255, 255)
    end
    overlayCircle(aimX, aimY, 8)
    overlayLine(aimX - 12, aimY, aimX + 12, aimY)
    overlayLine(aimX, aimY - 12, aimX, aimY + 12)
    return OVERLAY_UPDATED
end

2.29.4. overlayClear

overlayClear()

Remplit tout l’overlay avec la couleur de fond actuelle. Quand la couleur est la même que lors du dernier effacement, seul ce qui a été dessiné depuis est rempli de nouveau, si bien qu’effacer un overlay qui contient quelques lignes de texte ne coûte presque rien, quelle que soit sa taille. Le fond est au départ noir transparent : sans appel à colorBackground, cela efface donc l’overlay pour le rendre de nouveau invisible, et la vidéo apparaît au travers. Un fond partiellement opaque assombrit la vidéo ; un fond entièrement opaque la cache. La plupart des jeux l’appellent en tout premier dans onOverlayUpdate. Les arguments éventuels sont ignorés.

Depuis : 1.x Voir aussi : colorBackground, onOverlayUpdate

Exemple
-- Assombrir de moitié la vidéo en pause derrière le menu de service.
function onOverlayUpdate()
    colorBackground(0, 0, 0, 127)
    overlayClear()
    spriteDraw(serviceTitle, (overlayGetWidth() - spriteGetWidth(serviceTitle)) / 2, 25)
    return OVERLAY_UPDATED
end

2.29.5. overlayEllipse

overlayEllipse(x1, y1, x2, y2)

Dessine le contour d’une ellipse d’un pixel dans la couleur de premier plan, inscrite dans le rectangle aligné sur les axes dont les coins opposés sont (x1, y1) et (x2, y2). Les coins peuvent être donnés dans n’importe quel ordre. Un rectangle de largeur et de hauteur égales donne un cercle : c’est donc aussi le moyen de dessiner un cercle à partir de son rectangle englobant plutôt que de son centre.

Depuis : 2.00 Voir aussi : overlayCircle, overlayBox

Exemple
-- Mettre en évidence la borne sélectionnée avec un ovale ajusté à son panneau.
function onOverlayUpdate()
    spriteDraw(cabinetSprite, CABINET_X, CABINET_Y)
    if selected == CABINET then
        colorForeground(255, 220, 0, 255)
        overlayEllipse(CABINET_X - 6, CABINET_Y - 6, CABINET_X + CABINET_W + 6, CABINET_Y + CABINET_H + 6)
    end
    return OVERLAY_UPDATED
end

2.29.6. overlayGetFontHeight

result = overlayGetFontHeight()

Renvoie la hauteur en pixels d’une cellule de caractère de la police de console intégrée, l’unité dans laquelle compte overlayPrint. La police de console est une seule image intégrée de 256 glyphes, chargée une fois avant l’exécution de tout script : cette valeur ne change donc jamais pendant que le programme tourne. Les arguments éventuels sont ignorés.

Renvoie : hauteur entière d’une cellule en pixels.

Depuis : 3.00 Voir aussi : overlayGetFontWidth, overlayPrint, overlayGetHeight

Exemple
-- Combien de lignes de texte de console tiennent, quelle que soit la taille de l'overlay.
ROWS = overlayGetHeight() // overlayGetFontHeight()
overlayPrint(0, ROWS - 1, "along the bottom")

2.29.7. overlayGetFontWidth

result = overlayGetFontWidth()

Renvoie la largeur en pixels d’une cellule de caractère de la police de console intégrée, l’unité dans laquelle compte overlayPrint. Utilisez-la avec overlayGetWidth pour calculer combien de colonnes tiennent, ou pour placer du texte de console par rapport à quelque chose dessiné en pixels. Divisez avec // plutôt qu’avec / : la division ordinaire de Lua donne un nombre fractionnaire, et une position de cellule doit être entière. Les arguments éventuels sont ignorés.

Renvoie : largeur entière d’une cellule en pixels.

Depuis : 3.00 Voir aussi : overlayGetFontHeight, overlayPrint, overlayGetWidth

Exemple
-- Centrer une ligne de texte de console sans coder en dur le nombre de colonnes.
local columns = overlayGetWidth() // overlayGetFontWidth()
local text    = "GAME OVER"

overlayPrint((columns - #text) // 2, 10, text)

2.29.8. overlayGetHeight

result = overlayGetHeight()

Renvoie la hauteur de la surface de l’overlay en unités de l’overlay : la dernière valeur donnée à overlaySetResolution, ou la moitié de la hauteur de la vidéo avant tout appel. Lisez-la au démarrage, après avoir réglé la résolution, pour disposer les positions en fonction de la zone de dessin réelle. Les arguments éventuels sont ignorés.

Renvoie : hauteur entière.

Depuis : 1.x Voir aussi : overlayGetWidth, overlaySetResolution

Exemple
-- Ancrer le panneau de texte à la marge du bas, quelle que soit la taille de l'overlay.
overlaySetResolution(discGetWidth(), discGetHeight())
TEXT_Y = 200
TEXT_H = overlayGetHeight() - MARGIN_Y - TEXT_Y
TEXT_LINE_LIMIT = math.floor(TEXT_H / LINE_HEIGHT)

2.29.9. overlayGetWidth

result = overlayGetWidth()

Renvoie la largeur de la surface de l’overlay en unités de l’overlay : la dernière valeur donnée à overlaySetResolution, ou la moitié de la largeur de la vidéo avant tout appel. Servez-vous-en pour aligner à droite ou centrer des éléments au lieu de coder une largeur en dur. Les arguments éventuels sont ignorés.

Renvoie : largeur entière.

Depuis : 1.x Voir aussi : overlayGetHeight, overlaySetResolution

Exemple
-- Aligner le fronton à droite et centrer le titre, indépendamment de la résolution.
function onOverlayUpdate()
    local marqueeX = overlayGetWidth() - MARGIN_X - spriteGetWidth(marqueeSprite)
    spriteDraw(marqueeSprite, marqueeX, MARGIN_Y)
    spriteDraw(titleSprite, (overlayGetWidth() - spriteGetWidth(titleSprite)) / 2, 25)
    return OVERLAY_UPDATED
end

2.29.10. overlayLine

overlayLine(x1, y1, x2, y2)

Dessine une ligne de Bresenham d’un pixel dans la couleur de premier plan, de (x1, y1) à (x2, y2), les deux extrémités comprises. Les pixels hors de l’overlay sont abandonnés, si bien que les extrémités peuvent se trouver hors de la surface. Les coordonnées sont tronquées en entiers.

Depuis : 2.00 Voir aussi : overlayPlot, overlayBox, colorForeground

Exemple
-- Dessiner le laser du pistolet jusqu'au point visé, et un simple réticule de visée.
function onOverlayUpdate()
    overlayClear()
    if firing then
        colorForeground(255, 64, 64, 255)
        overlayLine(GUN_X, GUN_Y, aimX, aimY)
    end
    colorForeground(255, 255, 255, 255)
    overlayCircle(aimX, aimY, 6)
    return OVERLAY_UPDATED
end

2.29.11. overlayPlot

overlayPlot(x, y)

Donne la couleur de premier plan à un pixel de l’overlay. Un point hors de la surface est ignoré. Chaque appel verrouille puis déverrouille l’overlay : tracer des milliers de points par image depuis Lua est donc lent ; utilisez un sprite pour tout ce qui a une structure et gardez ceci pour les étoiles, les étincelles et les marques de débogage.

Depuis : 2.00 Voir aussi : overlayLine, colorForeground

Exemple
-- Un champ d'étoiles qui scintillent lentement derrière le titre.
function onOverlayUpdate()
    overlayClear()
    for _, star in ipairs(stars) do
        local shade = 128 + math.floor(127 * math.sin(frameCount * star.speed))
        colorForeground(shade, shade, shade, 255)
        overlayPlot(star.x, star.y)
    end
    frameCount = frameCount + 1
    return OVERLAY_UPDATED
end

2.29.12. overlayPrint

overlayPrint(column, row, text)

Affiche une chaîne avec la police de console à chasse fixe intégrée au moteur. Contrairement à tous les autres appels de dessin, la position est une cellule de caractère : le moteur multiplie column et row par la largeur et la hauteur d’un glyphe, si bien que (0, 0) est la cellule en haut à gauche et que (1, 0) se trouve un glyphe plus à droite. Les glyphes sont copiés tels quels depuis l’image de la police ; les couleurs de premier plan et de fond actuelles ne sont pas appliquées, et seul le fond propre de la police est transparent. Chaque octet de la chaîne choisit l’un des 256 glyphes de la police : le texte est donc traité comme des octets, pas comme de l’UTF-8. Les caractères qui dépasseraient le bord droit de l’overlay sont abandonnés, et un texte qui commence au-delà du bord ne dessine rien.

Paramètres :

  • column, row — la cellule de caractère, 0 en haut à gauche.

  • text — la chaîne à afficher.

Remarques : La police de console est destinée aux diagnostics et aux écrans de service. Utilisez fontPrint ou fontToSprite pour du texte en couleur ou proportionnel. La taille d’une cellule en pixels est overlayGetFontWidth sur overlayGetFontHeight, si bien que overlayGetWidth() // overlayGetFontWidth() donne le nombre de colonnes qui tiennent.

Depuis : 1.x Voir aussi : fontPrint, overlayClear, colorBackground

Exemple
-- Des diagnostics dans le coin pendant qu'un téléchargement se termine.
function onOverlayUpdate()
    colorBackground(0, 0, 0, 127)
    overlayClear()
    overlayPrint(1, 1, "FRAME " .. discGetFrame())
    overlayPrint(1, 2, download.url .. " " .. tostring(download.finished))
    if download.finished then
        overlayPrint(1, 3, download.result)
    end
    return OVERLAY_UPDATED
end

2.29.13. overlaySetMonochrome

overlaySetMonochrome(enabled)

Extension Hypseus. Montre l’overlay en gris : avant chaque envoi, le moteur convertit une copie de l’overlay en luminance avec les coefficients BT.601, en gardant le canal alpha tel quel (Hypseus le seuille). Les pixels propres de l’overlay restent en couleur, si bien que rien de ce que le script relit ne change, et le dessin continue comme d’habitude. Associez-le à vldpSetMonochrome pour un mode noir et blanc. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpSetMonochrome, overlayClear

Exemple
-- Un seul réglage pilote à la fois le disque et l'overlay.
function applyChroma(color)
    vldpSetMonochrome(not color)
    overlaySetMonochrome(not color)
end

2.29.14. overlaySetResolution

overlaySetResolution(width, height)

Remplace l’overlay par une nouvelle surface de la taille donnée et abandonne tout ce qui a été dessiné jusque-là. Dès lors, chaque coordonnée de l’overlay, chaque position de sprite et chaque résultat de overlayGetWidth ou de overlayGetHeight est dans le nouvel espace, que le moteur met à l’échelle de la fenêtre au moment de l’affichage. Appelez-la une fois au démarrage, avant de dessiner ; la valeur par défaut est la moitié de la résolution de la vidéo dans chaque dimension. Une largeur ou une hauteur de 0 ou moins met fin au script avec une erreur. Une résolution plus élevée donne un placement plus fin et un texte plus net, au prix de plus de travail de composition par image ; la taille native du disque, donnée par discGetWidth et discGetHeight, est le choix courant.

Paramètres :

  • width — la nouvelle largeur de l’overlay en pixels, supérieure à 0.

  • height — la nouvelle hauteur de l’overlay en pixels, supérieure à 0.

Depuis : 2.00 Voir aussi : overlayGetWidth, overlayGetHeight, discGetWidth

Exemple
-- S'aligner sur le disque, puis disposer le menu dans cet espace de coordonnées.
overlaySetResolution(discGetWidth(), discGetHeight())
MARGIN_X  = 16
MARGIN_Y  = 16
MARQUEE_W = 200
MARQUEE_X = overlayGetWidth() - MARGIN_X - MARQUEE_W
CABINET_H = overlayGetHeight() - MARGIN_Y - CABINET_Y

2.29.15. setOverlayFullAlpha

setOverlayFullAlpha()

Extension Hypseus, acceptée et ignorée. Hypseus copie son overlay avec le canal alpha seuillé à 128, si bien qu’un pixel à moitié transparent est soit entièrement opaque, soit absent, et cet appel lui demande d’envoyer plutôt la surface telle qu’elle est et de la mélanger correctement. L’overlay de Singe a toujours été en RGBA complet avec un véritable alpha par pixel : ce que cet appel demande est donc déjà en vigueur.

Renvoie : rien.

Depuis : 3.00

2.29.16. setOverlayLinearScale

setOverlayLinearScale(enabled)

Extension Hypseus. Choisit comment l’overlay est filtré sur son chemin vers la fenêtre. Avec true, la valeur par défaut et celle que rétablit un rechargement, il est échantillonné linéairement, si bien qu’un overlay de basse résolution s’adoucit au lieu de faire apparaître des blocs ; avec false, c’est le pixel le plus proche qui est pris, ce qui garde nets le pixel art, les contours d’un pixel et le petit texte. Le linéaire est la valeur par défaut parce que c’est ainsi que toutes les versions de Singe ont dessiné l’overlay ; Hypseus prend par défaut le pixel le plus proche, si bien qu’un jeu venu d’Hypseus qui n’appelle jamais ceci paraîtra un peu plus doux jusqu’à ce qu’il le fasse. Rien ne change dans le dessin, seulement la mise à l’échelle finale de la résolution de l’overlay vers la fenêtre, si bien que tout ce qui se trouve sur l’overlay — les primitives, les polices, les sprites et la couche 3D — passe ensemble par ce seul filtre, et que l’image du disque, derrière, n’est pas touchée. Le réglage survit à overlaySetResolution, qui remplace l’overlay. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : overlaySetResolution, spriteQuality

Exemple
-- Un overlay de 320x240 sur un écran 4K ; l'écran-titre peint adouci, le pixel art du jeu net.
overlaySetResolution(320, 240)

function showTitle()
    setOverlayLinearScale(true)
    mode = "title"
end

function startGame()
    setOverlayLinearScale(false)
    mode = "play"
end

2.29.17. setOverlayOnTop

loaded, id = setOverlayOnTop(enabled)

Extension Hypseus. Choisit si l’overlay et les GUI dessinées par-dessus l’image sont au-dessus ou en dessous des illustrations du bezel. Seules les illustrations dessinées devant l’image (--bezelflip) peuvent se trouver au-dessus d’elles ; avec les illustrations derrière — ce qui est le cas par défaut — cela ne change donc rien. false est le réglage avec lequel un jeu démarre, et la valeur par défaut d’Hypseus lui-même. Il est conservé jusqu’au rechargement du script.

Le réglage n’est enregistré que lorsque des illustrations sont chargées ; sans elles, l’appel ne fait rien et répond false et "0", exactement comme Hypseus. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen ; true place l’overlay et les GUI au-dessus des illustrations.

Renvoie : booléen, indiquant si des illustrations sont chargées, et leur identifiant sous forme de chaîne ("0" quand il n’y en a pas).

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : mainBezelLoaded, guiDrawScreen, Bezels

Exemple
-- Le cadre de la borne chevauche l'image, mais la ligne de score doit rester lisible.
if mainBezelLoaded() then
    setOverlayOnTop(true)
end

2.29.18. setOverlayOpacity

setOverlayOpacity(alpha)

Extension Hypseus. Le degré d’opacité de l’overlay entier, de 0 (invisible) à 255 (tel que le jeu l’a dessiné). Il multiplie l’alpha que portent déjà les pixels propres de l’overlay, si bien qu’un sprite à moitié transparent reste deux fois moins opaque que le reste ; il ne change pas le contenu de l’overlay, et rien n’a besoin d’être redessiné.

Le niveau est borné entre 0 et 255 au lieu d’être refusé, et un script démarre à 255. Il est conservé jusqu’au rechargement du script, et il survit à un changement de résolution de l’overlay.

Les GUI, la scène 3D et les illustrations du bezel sont dessinées à part et ne sont pas affectées.

Paramètres :

  • alpha — nombre ; de 0 à 255.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : setOverlayLinearScale, overlaySetResolution

Exemple
-- Faire disparaître en fondu tout l'affichage tête haute en une demi-seconde.
local fade = 255
function onOverlayUpdate()
    fade = math.max(0, fade - 8)
    setOverlayOpacity(fade)
    return OVERLAY_UPDATED
end

2.30. Physique

Les appels au niveau du monde : la requête de rayon, la gravité, le mode 2D, la pause et le dessin de débogage. La physique est initialisée avec le moteur : il n’y a donc rien à activer avant le premier bodyNew ; le monde avance soixante fois par seconde d’après l’horloge, après les animations et avant le rendu de la scène. Les positions et les distances sont en unités du monde, et la gravité en unités par seconde au carré. Voir Physique dans Développement de jeux pour la façon dont les corps, les nœuds et l’image s’articulent.

2.30.1. physicsRaycast

node, hx, hy, hz, nx, ny, nz = physicsRaycast(x, y, z, dx, dy, dz)
node, hx, hy, hz, nx, ny, nz = physicsRaycast(x, y, z, dx, dy, dz, maxDistance)
node, hx, hy, hz, nx, ny, nz = physicsRaycast(x, y, z, dx, dy, dz, maxDistance, ignoredNodes)

Trouve le premier corps le long d’un rayon partant de (x, y, z) dans la direction (dx, dy, dz), à moins de maxDistance unités du monde. La direction est normalisée, si bien que n’importe quelle longueur convient, mais une direction nulle ne touche rien. Les déclencheurs et les joueurs sont touchés comme n’importe quel autre corps ; un joueur est signalé par son nœud. Avec sceneUnproject qui fournit deux points le long de la souris, c’est de la sélection ; tout droit vers le bas depuis un point, c’est une sonde de hauteur.

Paramètres :

  • x, y, z — le départ du rayon dans l’espace du monde.

  • dx, dy, dz — sa direction ; seule la direction compte.

  • maxDistance — jusqu’où chercher ; 1000 par défaut, et 0 ou moins, ou nil, signifie la valeur par défaut.

  • ignoredNodes — liste facultative d’au plus 4096 handles de nœud non négatifs exclus de cette requête. L’exclusion porte sur le nœud exact que renvoie un rayon : ajoutez donc les nœuds des corps enfants au besoin. Les corps gardent leur état activé et leurs contacts. Un rayon qui part de l’intérieur d’un corps ignoré peut toucher normalement le corps suivant. Une liste vide, ou nil, laisse la requête sans filtre ; les handles périmés n’ont aucun effet.

Renvoie : Le nœud du corps, le point d’impact et la normale de la surface à cet endroit, ou un seul nil quand rien n’est touché.

Depuis : 3.00. Voir aussi : sceneUnproject, bodyApplyImpulse, lineDraw

Exemple
-- Poser le marqueur sur le sol plat qui se trouve sous le curseur, quel qu'il soit.
function onOverlayUpdate()
    local mx, my = mouseGetPosition(0)
    local ox, oy, oz = sceneUnproject(mx, my, 0)
    local fx, fy, fz = sceneUnproject(mx, my, 10)
    local hit, hx, hy, hz, nx, ny, nz = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz, 60)
    nodeSetVisible(marker, hit ~= nil and ny > 0.7)
    if hit then
        nodeSetPosition(marker, hx, hy + 0.05, hz)
    end
    return OVERLAY_NOT_UPDATED
end
Exemple
-- Un tir depuis la poitrine du joueur.  Le rayon part de l'intérieur du corps du joueur et
-- traverse le bouclier qu'il porte : les deux sont donc écartés, sans que rien ne change pour eux.
function fire()
    local px, py, pz = nodeGetPosition(player)
    local hit, hx, hy, hz = physicsRaycast(px, py + 1.4, pz, aimX, aimY, aimZ, 80, { player, shield })
    nodeSetVisible(spark, hit ~= nil)
    if hit then
        nodeSetPosition(spark, hx, hy, hz)
    end
end

2.30.2. physicsSet2D

physicsSet2D(planar)

Avec true, les corps créés à partir de maintenant ne se déplacent qu’en X et en Y et ne tournent qu’autour de Z : le monde d’un jeu 2D, généralement en coordonnées de l’overlay, avec une gravité dirigée vers +Y pour que les choses tombent vers le bas de l’écran. Les corps déjà créés gardent leur liberté : appelez-le donc avant tout bodyNew ; false revient à la 3D complète pour les corps créés ensuite. Les joueurs sont différents : tant que le mode est actif, chaque joueur, quel que soit le moment où il a été créé, se déplace le long de X avec son Z maintenu à 0, et playerMove prend une seule valeur. Le monde 2D fonctionne sans GPU, Raspberry Pi 3 compris.

Depuis : 3.00. Voir aussi : physicsSetGravity, bodyNew, playerMove

Exemple
-- Un monde de jeu de plateformes en pixels de l'overlay : la gravité vers le bas de l'écran, un sol et des murs.
physicsSet2D(true)
physicsSetGravity(0, 900, 0)
local width, height = overlayGetWidth(), overlayGetHeight()
floor = nodeNew()
nodeSetPosition(floor, width / 2, height - 10, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, width, 20, 50)
leftWall = nodeNew()
nodeSetPosition(leftWall, -10, height / 2, 0)
bodyNew(leftWall, BODY_STATIC, SHAPE_BOX, 20, height, 50)

2.30.3. physicsSetDebug

physicsSetDebug(mask)

Dessine ce que contient la simulation sous forme de lignes par-dessus la scène à chaque image, tant que le masque est réglé : DEBUG_SHAPES pour la forme de chaque corps mobile en fil de fer (corps mous compris, et joueurs activés en jaune), DEBUG_CONSTRAINTS pour les articulations, les articulations de ragdoll et les contraintes de véhicule avec leurs limites, DEBUG_CONTACTS pour une croix rouge là où des corps se sont rencontrés à ce pas, et DEBUG_VELOCITIES pour une ligne le long de la vitesse de chaque corps mobile. Additionnez les indicateurs ; DEBUG_ALL vaut les quatre. Les formes des corps statiques restent masquées sauf si DEBUG_STATIC est ajouté, parce qu’un maillage de niveau fait beaucoup de lignes. DEBUG_NONE le désactive, et rien n’est dessiné ni ne coûte quoi que ce soit tant qu’il est désactivé.

Remarques : Une version de Singe compilée sans le moteur de rendu de débogage de Jolt affiche un message dans la console et ne dessine rien.

Depuis : 3.00. Voir aussi : lineDraw, navDraw, physicsSetEnabled

Exemple
-- Basculer l'affichage de la physique avec une touche de débogage ; les formes statiques aussi, puisque le niveau est petit.
function onInputPressed(switch)
    if switch == SWITCH_BUTTON3 then
        showPhysics = not showPhysics
        if showPhysics then
            physicsSetDebug(DEBUG_ALL + DEBUG_STATIC)
        else
            physicsSetDebug(DEBUG_NONE)
        end
    end
end

2.30.4. physicsSetEnabled

physicsSetEnabled(enabled)

Met la simulation en pause avec false et la reprend avec true. Pendant la pause, aucun pas ne s’exécute : les corps dynamiques restent immobiles et gardent leurs vitesses, les corps cinématiques cessent de suivre leurs nœuds, les joueurs cessent de bouger, et aucun onCollision ni onTrigger n’est déclenché. Le temps ne s’accumule pas pendant la pause : la reprise ne rejoue donc pas les pas manqués. La pause propre du jeu fait la même chose sans cet appel ; servez-vous de celui-ci pour un menu, une cinématique ou un arrêt sur image qui laisse tourner le reste du jeu.

Depuis : 3.00. Voir aussi : physicsSetGravity, bodyIsResting

Exemple
-- Figer le monde tant que l'inventaire est ouvert.
function openInventory()
    inventoryOpen = true
    physicsSetEnabled(false)
end

function closeInventory()
    inventoryOpen = false
    physicsSetEnabled(true)
end

2.30.5. physicsSetGravity

physicsSetGravity(x, y, z)

Règle l’accélération que ressentent tous les corps dynamiques et tous les joueurs, en unités du monde par seconde au carré selon chaque axe du monde. La valeur par défaut est 0, -9.81, 0, la gravité terrestre en mètres ; 0, 0, 0 est l’espace, et un jeu 2D en pixels de l’overlay veut quelque chose comme 0, 900, 0, puisque le Y de l’overlay va vers le bas de l’écran. La direction opposée à la gravité est « le haut » pour les joueurs : le sens dans lequel ils se tiennent debout, sautent et montent les marches.

Un changement de gravité réveille tous les corps, corps mous compris, si bien qu’une caisse qui s’était immobilisée tombe quand la gravité tourne sur le côté, et qu’un tissu flotte quand change un vent fait de gravité. Régler de nouveau la même gravité ne réveille rien.

Depuis : 3.00. Voir aussi : bodyNew, physicsSet2D, playerSetGravityScale

Exemple
-- Le niveau lunaire : un sixième de l'attraction terrestre, et un saut plus long en conséquence.
function startLevel(name)
    if name == "moon" then
        physicsSetGravity(0, -1.62, 0)
        jumpSpeed = 3.0
    else
        physicsSetGravity(0, -9.81, 0)
        jumpSpeed = 4.5
    end
end

2.31. Joueur

Un joueur est un contrôleur de personnage posé sur un nœud : là où un corps va où les forces l’envoient, un joueur va où le script le dit, en marchant sur les sols, en montant les marches, en glissant le long des murs, en se laissant porter par les plateformes et en écartant les corps légers. Les joueurs sont désignés par leur nœud, et un nœud porte un corps ou un joueur, pas les deux. Les tailles et les vitesses sont en unités du monde (des mètres dans une scène 3D, des pixels de l’overlay dans un monde 2D) et les tolérances du contrôleur s’adaptent à la forme, si bien qu’une capsule de 30 pixels se comporte comme une capsule de 0,3 mètre. Le joueur pilote la position de son nœud à chaque pas et laisse la rotation au script. Chaque appel de cette section met fin au script quand le nœud n’a pas de joueur. Voir Physique dans Développement de jeux, Joueurs.

2.31.1. playerNew

playerNew(node, radius, height)
playerNew(node, SHAPE_CAPSULE, radius, height)
playerNew(node, SHAPE_CYLINDER, radius, height)
playerNew(node, SHAPE_SPHERE, radius, 0)
playerNew(node, SHAPE_BOX, width, height, depth)
playerNew(node, SHAPE_HULL)

Place un joueur sur le nœud, là où le nœud se trouve dans le monde à cet instant : une capsule de ce rayon et de cette hauteur totale, ou n’importe quelle forme convexe de bodyNew avec ses tailles, mise à l’échelle par l’échelle du nœud dans le monde. La forme repose sur l’origine du nœud, si bien que le nœud correspond aux pieds. Il commence avec une masse de 70 kilogrammes, une poussée de 300 newtons, une limite de pente de 45 degrés, une hauteur de marche de 0.3 mise à l’échelle de la forme, une échelle de gravité de 1 et les taux de nage par défaut. Remplace tout corps ou joueur qu’avait le nœud. Met fin au script pour SHAPE_MESH (un joueur a besoin d’une forme convexe ; utilisez SHAPE_HULL), quand la physique n’est pas disponible sur cette machine, ou quand le joueur ne peut pas être créé (une enveloppe avec trop peu de maillage, ou seize joueurs déjà présents).

Paramètres :

  • radius, height — une capsule : son rayon et sa hauteur totale selon la verticale, calottes comprises.

  • SHAPE_* — une constante de forme suivie de ses tailles de bodyNew ; SHAPE_HULL n’en prend aucune et enveloppe le maillage du nœud et tout ce qui se trouve sous lui.

Remarques : Un appel avec exactement trois arguments est toujours une capsule : une sphère a donc besoin d’un quatrième argument (n’importe quel nombre) après son rayon pour être lue comme SHAPE_SPHERE.

Depuis : 3.00. Voir aussi : playerMove, playerDelete, bodyNew, nodeSetParent

Exemple
-- Le héros : une capsule avec le modèle Fox accroché au nœud, les pieds au sol.
hero = nodeNew()
nodeSetPosition(hero, 0, 0.05, 0)
playerNew(hero, 0.3, 1.0)
playerSetStep(hero, 0.35)
fox = modelInstance(modelLoad(DIR .. "Models/Fox.glb"))
nodeSetParent(fox, hero)
nodeSetScale(fox, 0.01)
animationPlay(fox, "Walk", true)
-- Un robot est une boîte ; il prend les virages à angle droit et ne peut pas rouler.
robot = nodeNew()
playerNew(robot, SHAPE_BOX, 0.8, 1.6, 0.6)

2.31.2. playerDelete

playerDelete(node)

Retire le joueur ; le nœud et tout ce qui est suspendu sous lui restent où ils sont. Supprimer le nœud retire aussi son joueur, tout comme donner au nœud un corps avec bodyNew. Met fin au script quand le nœud n’a pas de joueur.

Depuis : 3.00. Voir aussi : playerNew, playerSetEnabled

Exemple
-- Le héros monte dans la voiture : le contrôleur disparaît, le modèle est du voyage.
function boardCar()
    playerDelete(hero)
    nodeSetParent(hero, car)
    nodeSetPosition(hero, 0, 0.4, 0)
    driving = true
end

2.31.3. playerMove

playerMove(node, vx, vz)
playerMove(node, vx, vy, vz)
playerMove(node, vx)

Indique au joueur la vitesse qu’il veut à cette image, en unités du monde par seconde. Au sol ou en l’air, les deux valeurs horizontales sont utilisées telles quelles, en plus de celle de la plateforme sur laquelle il se tient ; la composante verticale vient de la gravité, du sol et de playerJump, et vy est ignoré. Quand le joueur nage, les trois valeurs le dirigent, et l’eau amène progressivement sa vitesse vers elles selon la traînée de playerSetSwim, en coulant à la vitesse de descente quand vy vaut 0. Dans un monde 2D, un vx seul le fait avancer le long de X et tout vz est ignoré. Appelez-le à chaque image depuis onOverlayUpdate : la demande est consommée par les pas de cette image, et à une image sans demande, le joueur reste immobile.

Paramètres :

  • vx, vz — la vitesse horizontale voulue, en unités du monde par seconde (en 2D : pixels de l’overlay le long de X).

  • vy — la vitesse verticale voulue pendant la nage ; positive vers le haut.

Depuis : 3.00. Voir aussi : playerJump, playerSetVelocity, playerIsSwimming, physicsSet2D

Exemple
-- Marcher avec le stick gauche, remonter à la nage tant que le bouton est maintenu, regarder dans le sens de la marche.
function onOverlayUpdate()
    local vx = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767 * 3
    local vz = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_Y) / 32767 * 3
    if playerIsSwimming(hero) then
        playerMove(hero, vx, surfacing and 1.5 or 0, vz)
    else
        playerMove(hero, vx, vz)
    end
    nodeSetRotation(hero, 0, math.deg(math.atan(-vz, vx)), 0)
    return OVERLAY_NOT_UPDATED
end

2.31.4. playerIsSwimming

swimming = playerIsSwimming(node)

Indique si le joueur était dans l’eau au dernier pas : le milieu de sa forme sous la surface d’un volume bodySetWater. Pendant la nage, playerMove dirige selon trois axes, la gravité laisse la place à la vitesse de descente, et le courant de l’eau emporte le joueur.

Renvoie : Booléen.

Depuis : 3.00. Voir aussi : playerSetSwim, bodySetWater, playerMove

Exemple
-- Changer l'animation quand le héros entre dans l'eau.
function onOverlayUpdate()
    local swimming = playerIsSwimming(hero)
    if swimming ~= wasSwimming then
        animationPlay(fox, swimming and "Swim" or "Walk", true)
        wasSwimming = swimming
    end
    return OVERLAY_NOT_UPDATED
end

2.31.5. playerJump

jumped = playerJump(node, speed)

Demande au joueur de quitter le sol à cette vitesse vers le haut, en unités du monde par seconde, au pas suivant. Ce n’est accordé que s’il y a, à cet instant, un sol praticable sous ses pieds : maintenir un bouton enfoncé ne fait donc pas rebondir le joueur, et un saut en plein air ne fait rien. Une vitesse négative est traitée comme 0. Le joueur garde sa vitesse horizontale pendant le saut, et playerMove le dirige toujours en l’air.

Renvoie : true quand le saut a été accordé.

Depuis : 3.00. Voir aussi : playerIsOnGround, playerMove, playerSetGravityScale

Exemple
-- Sauter avec le bouton d'action, avec un son seulement quand le saut a vraiment eu lieu.
function onInputPressed(switch)
    if switch == SWITCH_BUTTON1 then
        if playerJump(hero, 4.5) then
            soundPlay(jumpSound)
        end
    end
end

2.31.6. playerSetSwim

playerSetSwim(node, sinkSpeed, drag)

Règle le comportement du joueur dans l’eau : à quelle vitesse il coule, en unités du monde par seconde, quand playerMove ne demande aucun mouvement vertical (0.3 par défaut), et à quelle rapidité l’eau amène sa vitesse vers ce que demande playerMove, sous forme de taux par seconde (2 par défaut, si bien que l’essentiel de l’écart a disparu en une seconde ; 0 ne change jamais la vitesse). Les deux valeurs sont ramenées à 0 au minimum. Un plongeur lourd coule vite avec une forte traînée ; un bouchon ne coule pas du tout.

Paramètres :

  • sinkSpeed — la dérive vers le bas sans commande verticale, en unités par seconde.

  • drag — le taux auquel l’eau amène la vitesse vers la demande, par seconde.

Depuis : 3.00. Voir aussi : playerIsSwimming, playerMove, bodySetWater

Exemple
-- L'armure entraîne le héros vers le fond ; il faut l'enlever pour flotter.
function wearArmor(on)
    armored = on
    if on then
        playerSetSwim(hero, 1.2, 4)
    else
        playerSetSwim(hero, 0.3, 2)
    end
end

2.31.7. playerSetVelocity

playerSetVelocity(node, x, y, z)

Règle la vitesse entière du joueur, en unités du monde par seconde selon chaque axe du monde, et abandonne toute demande playerMove faite à cette image. C’est la composante verticale qui dure : une vitesse vers le haut décolle le joueur du sol et il retombe sous l’effet de la gravité, ce qui donne un tremplin ou un rebond. La composante horizontale ne tient que jusqu’au pas suivant, où elle est remplacée par ce que demande playerMove (rien, quand il n’est pas appelé), parce qu’un joueur n’a pas d’élan horizontal propre. Un recul ou une ruée se fait donc ici avec une poussée vers le haut plus une vitesse playerMove fournie au fil des images suivantes.

Depuis : 3.00. Voir aussi : playerGetVelocity, playerMove, playerJump

Exemple
-- Un coup de l'ogre projette le héros en l'air et, au fil des images suivantes, loin de lui.
function onCollision(a, b, x, y, z, speed)
    if (a == hero and b == ogre) or (a == ogre and b == hero) then
        local hx, hy, hz = nodeGetPosition(hero)
        local ox, oy, oz = nodeGetPosition(ogre)
        local dx, dz = hx - ox, hz - oz
        local len = math.sqrt(dx * dx + dz * dz)
        playerSetVelocity(hero, 0, 3, 0)
        knockX, knockZ, knockFrames = dx / len * 6, dz / len * 6, 20
        health = health - 10
    end
end

2.31.8. playerGetVelocity

x, y, z = playerGetVelocity(node)

La vitesse du joueur après le dernier pas, en unités du monde par seconde selon chaque axe du monde, y compris ce que lui a donné le sol qui le porte. Lisez la composante verticale pour distinguer une montée d’une chute, ou le tout pour un bruit sourd à l’atterrissage.

Renvoie : Trois nombres.

Depuis : 3.00. Voir aussi : playerSetVelocity, playerIsOnGround

Exemple
-- Dégâts de chute d'après la vitesse à laquelle le héros a touché le sol.
function onOverlayUpdate()
    local _, vy = playerGetVelocity(hero)
    local onGround = playerIsOnGround(hero)
    if onGround and not wasOnGround and lastVy < -8 then
        health = health - math.floor((-lastVy - 8) * 5)
    end
    wasOnGround = onGround
    lastVy = vy
    return OVERLAY_NOT_UPDATED
end

2.31.9. playerIsOnGround

onGround = playerIsOnGround(node)

Indique si le joueur se tient sur un sol praticable au dernier pas : une surface pas plus raide que playerSetSlope. En l’air, ou sur une pente trop raide pour être gravie, la valeur est false. C’est le même test que fait playerJump.

Renvoie : Booléen.

Depuis : 3.00. Voir aussi : playerGetGround, playerJump, playerSetSlope

Exemple
-- Coyote time : un saut est encore permis quelques images après avoir quitté un rebord.
function onOverlayUpdate()
    if playerIsOnGround(hero) then
        framesSinceGround = 0
    else
        framesSinceGround = framesSinceGround + 1
    end
    if jumpPressed and framesSinceGround < 6 then
        playerSetVelocity(hero, vx, 4.5, vz)
    end
    return OVERLAY_NOT_UPDATED
end

2.31.10. playerGetGround

ground, nx, ny, nz = playerGetGround(node)

Ce sur quoi se tient le joueur, et la normale de la surface du sol à cet endroit. Le nœud est le corps sous ses pieds, praticable ou non ; il vaut nil en l’air, et la normale est alors 0, 1, 0. Servez-vous du nœud pour distinguer du sol une plateforme mobile, de la glace ou une plaque de pression, et de la normale pour pencher un modèle dans une pente.

Renvoie : Le nœud sur lequel il se tient, ou nil, puis la normale.

Depuis : 3.00. Voir aussi : playerIsOnGround, bodySetFriction

Exemple
-- Les pas sonnent différemment sur le pont de bois, et la plaque ouvre la grille.
function onOverlayUpdate()
    local ground = playerGetGround(hero)
    if ground == bridge then
        footstep = woodStep
    elseif ground == plate then
        openGate()
    else
        footstep = stoneStep
    end
    return OVERLAY_NOT_UPDATED
end

2.31.11. playerSetStep

playerSetStep(node, height)

La plus haute marche que le joueur monte sans sauter, en unités du monde ; tout ce qui est plus haut est un mur le long duquel il glisse. La valeur par défaut est 0.3 pour une forme dont la plus petite demi-taille est 0.3 (une capsule de rayon 0.3), et elle s’adapte à la forme, si bien qu’un joueur de 30 pixels dans un monde 2D commence à 30 pixels. La même distance est celle jusqu’à laquelle le joueur reste collé au sol en passant le rebord d’une marche, si bien qu’une marche plus haute le garde aussi collé au sol dans les descentes. Les valeurs négatives sont ramenées à 0.

Depuis : 3.00. Voir aussi : playerSetSlope, playerNew

Exemple
-- Les marches de ce niveau montent de 0,35 chacune ; s'assurer que le héros les gravit.
playerNew(hero, 0.3, 1.0)
playerSetStep(hero, 0.4)
-- Les rebords du jeu de plateformes 2D font 26 pixels.
playerNew(runner, 16, 48)
playerSetStep(runner, 26)

2.31.12. playerSetSlope

playerSetSlope(node, degrees)

La pente la plus raide que le joueur gravit, en degrés depuis l’horizontale ; un sol plus raide ne compte pas comme un appui, si bien que le joueur glisse dessus et ne peut pas en sauter. La valeur par défaut est 45, et la valeur est bornée entre 0 et 89. Une valeur basse fait des collines des obstacles, une valeur élevée laisse le joueur gravir presque tout ce qui n’est pas un mur.

Depuis : 3.00. Voir aussi : playerSetStep, playerIsOnGround

Exemple
-- La chèvre des montagnes grimpe là où le héros glisse.
playerNew(goat, 0.25, 0.8)
playerSetSlope(goat, 70)
playerNew(hero, 0.3, 1.0)
playerSetSlope(hero, 40)

2.31.13. playerSetMass

playerSetMass(node, kilograms)

La masse du joueur, utilisée quand il bouscule des corps dynamiques et comme son poids sur ceux sur lesquels il se tient. La valeur par défaut est 70 kilogrammes ; les valeurs inférieures à 0.001 sont relevées à ce minimum. La masse n’a aucun effet sur la façon dont le joueur tombe ou marche, seulement sur les bousculades : associez-la donc à playerSetPush.

Depuis : 3.00. Voir aussi : playerSetPush, bodySetMass

Exemple
-- Le troll fonce à travers ce que le héros doit contourner.
troll = nodeNew()
nodeSetPosition(troll, 6, 0, -3)
playerNew(troll, 0.6, 2.4)
playerSetMass(troll, 400)
playerSetPush(troll, 2000)
playerSetStep(troll, 0.8)

2.31.14. playerSetPush

playerSetPush(node, strength)

La force avec laquelle le joueur bouscule les corps dynamiques qu’il heurte en marchant, en newtons. La valeur par défaut, 300, déplace les caisses et les ballons mais pas les armoires ; 0 contourne tout comme si c’était statique. Les valeurs négatives sont ramenées à 0. Le bodySetMass propre d’un corps décide de ce qu’une force donnée peut déplacer.

Depuis : 3.00. Voir aussi : playerSetMass, bodySetMass

Exemple
-- La potion de force permet au héros de déplacer le rocher pendant dix secondes.
function drinkStrength()
    playerSetPush(hero, 3000)
    strengthUntil = frames + 600
end
function onOverlayUpdate()
    if strengthUntil and frames > strengthUntil then
        playerSetPush(hero, 300)
        strengthUntil = nil
    end
    return OVERLAY_NOT_UPDATED
end

2.31.15. playerSetGravityScale

playerSetGravityScale(node, scale)

Multiplie la gravité du monde pour ce seul joueur : 1 (la valeur par défaut) tombe comme tout le reste, 0 flotte sur place (une échelle, une salle en apesanteur, une monture volante), une valeur plus grande fait tomber plus vite pour une sensation de lourdeur, et une valeur plus petite donne un saut flottant. Cela ne change pas ce que fait playerJump au décollage, seulement la vitesse à laquelle le joueur redescend. Pendant la nage, la vitesse de descente de l’eau prend la place de la gravité.

Depuis : 3.00. Voir aussi : physicsSetGravity, playerJump, playerSetSwim

Exemple
-- Sur l'échelle, le héros grimpe avec le stick au lieu de tomber.
function onTrigger(trigger, other, entered)
    if trigger == ladder and other == hero then
        onLadder = entered
        playerSetGravityScale(hero, entered and 0 or 1)
    end
end

2.31.16. playerSetPosition

playerSetPosition(node, x, y, z)

Téléporte le joueur à une position du monde, sans rien toucher en chemin, et l’arrête net. Le nœud se déplace avec lui et garde sa rotation. Servez-vous-en pour l’apparition, la réapparition et les transitions de niveau ; déplacer plutôt le nœud avec nodeSetPosition laisse le joueur où il était, et le nœud est ramené au pas suivant.

Depuis : 3.00. Voir aussi : playerSetVelocity, nodeSetPosition

Exemple
-- Retour au dernier point de contrôle après une chute dans la fosse.
function onTrigger(trigger, other, entered)
    if trigger == pit and other == hero and entered then
        lives = lives - 1
        playerSetPosition(hero, checkpointX, checkpointY, checkpointZ)
    end
end

2.31.17. playerSetEnabled

playerSetEnabled(node, enabled)

Avec false, le joueur quitte la simulation : son corps est retiré du monde, si bien qu’il ne bouge plus, ne tombe plus, ne pilote plus son nœud et ne bloque plus rien, onTrigger signale qu’il quitte chaque déclencheur dans lequel il se trouvait, et il est exclu du dessin de débogage. true remet le corps en place et le reprend là où se trouve le nœud. Désactivez un joueur tant qu’un ragdoll, une cinématique ou un véhicule a la main sur le personnage.

Depuis : 3.00. Voir aussi : playerDelete, ragdollNew, bodySetEnabled

Exemple
-- Un coup violent confie le squelette du héros au ragdoll.
function onCollision(a, b, x, y, z, speed)
    if (a == hero or b == hero) and speed > 6 then
        playerSetEnabled(hero, false)
        ragdollActivate(fox)
    end
end

2.32. Ragdoll

Le squelette d’un modèle skinné confié à la physique (voir Physique, Ragdolls). Un ragdoll est désigné par le nœud donné à ragdollNew, généralement la racine d’une instance de modèle, et un nœud sans ragdoll met fin au script dans chaque appel après ragdollNew. Les os sont nommés d’après les nœuds de leurs articulations, les noms que voit nodeFind, comparés sans tenir compte de la casse ; les distances sont en unités du monde, les angles en degrés, les impulsions en newtons-secondes et la force des moteurs en newtons-mètres. Jusqu’à huit ragdolls à la fois, de 48 os au plus chacun.

2.32.1. ragdollNew

ragdollNew(node)

Cherche dans le nœud et sous lui le premier maillage skinné et construit une recette de ragdoll à partir de son squelette : chaque articulation qui a une articulation enfant devient un os, une capsule allant de l’articulation vers ses enfants, reliée à l’os le plus proche au-dessus d’elle par une articulation swing-twist limitée à 45 degrés de balancement et à 30 de torsion. Les articulations sans articulation enfant, comme le bout des doigts et le bout d’une queue, suivent leur os parent et ne peuvent pas être nommées dans les autres appels. Rien n’est encore simulé : le modèle continue de s’animer jusqu’à ragdollActivate. L’appeler de nouveau sur le même nœud abandonne d’abord l’ancien ragdoll. Met fin au script quand la physique n’est pas disponible, quand aucun maillage skinné doté d’os ne se trouve sous le nœud, ou quand huit ragdolls existent déjà.

Depuis : 3.00. Voir aussi : ragdollActivate, ragdollSetJoint, modelInstance

Exemple
-- Un garde qui fonce sur le joueur ; le ragdoll est prêt avant le plaquage.
local guard = nodeNew()
nodeSetPosition(guard, -1, 0.05, -1)
playerNew(guard, 0.3, 0.9)
local guardFox = modelInstance(foxModel)
nodeSetParent(guardFox, guard)
nodeSetScale(guardFox, 0.01)
nodeSetRotation(guardFox, 0, 90, 0)
animationPlay(guardFox, "Run", true)
ragdollNew(guardFox)                          -- Recette seulement ; il court toujours

2.32.2. ragdollDelete

ragdollDelete(node)

Supprime le ragdoll : ses corps et ses articulations s’il est actif, puis la recette. Les nœuds des articulations restent là où la physique les a laissés, si bien que le modèle reste couché tel qu’il est tombé jusqu’à ce qu’une animation le déplace, et le nœud est libre pour un nouveau ragdollNew. Un nœud sans ragdoll met fin au script.

Depuis : 3.00. Voir aussi : ragdollNew, ragdollDeactivate, nodeDelete

Exemple
function onOverlayUpdate()
    for i = #fallen, 1, -1 do
        local body = fallen[i]
        body.restingFrames = ragdollIsResting(body.node) and body.restingFrames + 1 or 0
        if body.restingFrames > 300 then
            ragdollDelete(body.node)              -- Immobile depuis cinq secondes : on fait le ménage
            nodeDelete(body.node)
            table.remove(fallen, i)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.32.3. ragdollSetJoint

ragdollSetJoint(node, jointName, radius, swingDegrees, twistDegrees)

Règle la recette d’un os. Les valeurs sont lues quand les corps sont créés : appelez-le donc avant ragdollActivate ; un ragdoll déjà actif garde ses corps jusqu’à ce qu’il soit désactivé puis activé de nouveau. Le rayon 0 demande la capsule automatique, 0,22 fois la longueur de l’os et jamais plus fine que 0.02 unité. Le balancement est le demi-angle du cône dans lequel l’os peut se déplacer par rapport à son parent, la torsion jusqu’où il peut tourner autour de son propre axe ; les deux sont bornés entre 0 et 179. Seuls les os peuvent être nommés, pas les articulations terminales ; le nom est comparé sans tenir compte de la casse, et un nom qui ne correspond à aucun os met fin au script.

Paramètres :

  • node — le nœud du ragdoll.

  • jointName — le nom du nœud de l’articulation, tel qu’il est dans le modèle.

  • radius — le rayon de la capsule en unités du monde, ou 0 pour l’automatique.

  • swingDegrees — jusqu’où l’os peut se balancer par rapport à son parent ; 45 par défaut.

  • twistDegrees — jusqu’où il peut se tordre autour de son propre axe ; 30 par défaut.

Depuis : 3.00. Voir aussi : ragdollNew, ragdollActivate, nodeFind

Exemple
ragdollNew(fox)
ragdollSetJoint(fox, "b_Neck_04", 0, 30, 20)          -- Un cou plus raide
ragdollSetJoint(fox, "b_Tail01_012", 0.03, 80, 60)    -- Une queue souple comme un fouet
for _, leg in ipairs({ "b_LeftLeg01_015", "b_RightLeg01_019" }) do
    ragdollSetJoint(fox, leg, 0, 60, 15)              -- Les hanches se balancent largement, se tordent à peine
end
ragdollActivate(fox)

2.32.4. ragdollActivate

ragdollActivate(node)

Confie le squelette à la physique à partir de sa pose actuelle : chaque couche d’animation du nœud s’arrête, une capsule dynamique est créée pour chaque os là où se trouve son articulation à cet instant, les articulations swing-twist sont créées entre elles, et dès lors chaque pas de physique pilote les nœuds des articulations à partir des corps, si bien que le maillage skinné suit. Les os entrent en collision avec le monde et entre eux, sauf chaque os avec son parent. La pose à ce moment-là est celle vers laquelle tire ragdollSetStrength. Un ragdoll déjà actif est laissé tel quel. Met fin au script quand le corps d’un os ne peut pas être créé.

Depuis : 3.00. Voir aussi : ragdollDeactivate, ragdollApplyImpulse, ragdollSetStrength

Exemple
local crashed = false

function onCollision(a, b, x, y, z, speed)
    if not crashed and (a == guard or b == guard) and speed > 1.5 then
        crashed = true
        playerSetEnabled(guard, false)        -- Le contrôleur lâche prise
        ragdollActivate(guardFox)             -- La physique prend le squelette en charge à partir d'ici
        ragdollApplyImpulse(guardFox, "b_Spine02_03", 40, 30, 0)
    end
end

2.32.5. ragdollDeactivate

ragdollDeactivate(node)

Supprime les corps et les articulations et rend le squelette. Les nœuds des articulations gardent la pose dans laquelle le ragdoll les a laissés, et rien ne les déplace tant qu’aucune animation ne joue ; un animationPlay avec un fondu part de cette pose en mélangeant, si bien qu’un personnage à terre peut se relever. La recette reste, si bien que ragdollActivate peut reprendre la main plus tard à partir de l’endroit où l’animation a amené le squelette. Ne fait rien à un ragdoll qui n’est pas actif.

Depuis : 3.00. Voir aussi : ragdollActivate, animationPlay

Exemple
-- Une fois le corps immobilisé, le héros se relève en une demi-seconde.
function onOverlayUpdate()
    if downed and ragdollIsResting(hero) then
        downed = false
        ragdollDeactivate(hero)
        animationPlay(hero, "GetUp", false, 1, 0.5)
        playerSetEnabled(heroController, true)
    end
    return OVERLAY_NOT_UPDATED
end

2.32.6. ragdollSetStrength

ragdollSetStrength(node, strength)

Motorise chaque articulation avec un moteur qui tire vers la pose dans laquelle le ragdoll a été activé, limité à ce nombre de newtons-mètres ; 0 (par défaut) coupe les moteurs et le corps devient mou. Les moteurs sont des ressorts à 4 Hz, à amortissement critique. La valeur peut être réglée avant l’activation ou pendant que le ragdoll bouge, et prend effet au pas suivant. Cela ne remet pas un corps debout, puisque rien ne prend appui sur le sol : quelques dizaines de newtons-mètres changent une chute en titubement et permettent à un personnage à terre de ramener ses membres.

Depuis : 3.00. Voir aussi : ragdollActivate, ragdollIsResting

Exemple
-- Mis à terre, tout mou ; un instant plus tard, le combattant se raidit et se recroqueville.
ragdollActivate(fighter)
ragdollSetStrength(fighter, 0)
downFrames = 0

function onOverlayUpdate()
    downFrames = downFrames + 1
    if downFrames == 60 then
        ragdollSetStrength(fighter, 60)
    end
    return OVERLAY_NOT_UPDATED
end

2.32.7. ragdollApplyImpulse

hit = ragdollApplyImpulse(node, jointName, x, y, z)

Ajoute une impulsion en newtons-secondes, selon les axes du monde, au corps de l’os qui commence à l’articulation nommée : le coup de poing, le tir, l’explosion. Le ragdoll doit être actif : appelez donc d’abord ragdollActivate, puis poussez. Renvoie false, et ne fait rien, quand le ragdoll n’est pas actif ou quand aucun os ne porte ce nom (les articulations terminales ne sont pas des os) ; le nom est comparé sans tenir compte de la casse.

Paramètres :

  • node — le nœud du ragdoll.

  • jointName — le nom du nœud de l’articulation, tel qu’il est dans le modèle.

  • x, y, z — l’impulsion en newtons-secondes, selon les axes du monde.

Renvoie : Vrai quand l’os a été trouvé et que le ragdoll était actif.

Depuis : 3.00. Voir aussi : ragdollActivate, bodyApplyImpulse, nodeFind

Exemple
-- Un impact depuis la position du tireur : l'impulsion s'éloigne de l'arme.
function shoot(target, gunX, gunY, gunZ, boneName)
    local tx, ty, tz = nodeGetWorldPosition(target)
    local dx         = tx - gunX
    local dz         = tz - gunZ
    local length     = math.sqrt(dx * dx + dz * dz)
    if not ragdollIsActive(target) then
        ragdollActivate(target)
    end
    ragdollApplyImpulse(target, boneName, dx / length * 30, 10, dz / length * 30)
end

2.32.8. ragdollIsActive

active = ragdollIsActive(node)

Indique si la physique pilote le squelette en ce moment : true de ragdollActivate jusqu’à ragdollDeactivate ou ragdollDelete. Un nœud sans ragdoll met fin au script.

Renvoie : Vrai ou faux.

Depuis : 3.00. Voir aussi : ragdollActivate, ragdollIsResting

Exemple
-- La barre de vie flotte au-dessus du modèle seulement tant qu'il est debout.
function onOverlayUpdate()
    overlayClear()
    for _, enemy in ipairs(enemies) do
        if not ragdollIsActive(enemy.node) then
            local x, y, z = nodeGetWorldPosition(enemy.node)
            local sx, sy  = sceneProject(x, y + 1.2, z)
            drawHealthBar(sx, sy, enemy.health)
        end
    end
    return OVERLAY_UPDATED
end

2.32.9. ragdollIsResting

resting = ragdollIsResting(node)

Indique si le corps de chaque os s’est mis en sommeil, ce que fait la physique quand un corps est resté immobile un moment. false tant que le ragdoll n’est pas actif : cela ne permet donc pas de distinguer un modèle inactif d’un modèle qui s’est immobilisé ; vérifiez aussi ragdollIsActive.

Renvoie : Vrai ou faux.

Depuis : 3.00. Voir aussi : ragdollIsActive, ragdollDeactivate

Exemple
-- La manche se termine une fois que le perdant a cessé de bouger.
function onOverlayUpdate()
    if roundOver and ragdollIsResting(loser) then
        restingFrames = restingFrames + 1
        if restingFrames == 90 then
            showResults()
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.33. Sauvegarde

Tout ce que le jeu doit encore savoir la prochaine fois qu’il démarre : les meilleurs scores, les options du joueur, jusqu’où il est allé. Une table par jeu, gardée en JSON dans le dossier de données propre au jeu (voir singeGetDataPath), si bien qu’un .game empaqueté reste en lecture seule et que deux jeux ne se marchent jamais sur les pieds.

Les clés sont à vous. Les valeurs peuvent être des nombres, des chaînes, des booléens ou des tables de ceux-ci, imbriquées aussi profondément que vous le voulez — toute une table des meilleurs scores entre comme une seule valeur. Une fonction, ou un handle vers quelque chose qui appartient au moteur, n’y entre pas : ni l’une ni l’autre ne veut rien dire à l’exécution suivante, et en sauvegarder une est une erreur plutôt qu’une surprise plus tard.

Ce que vous réglez est ce qui est sauvegardé, et ce que vous récupérez est à vous. Les tables sont copiées à l’entrée et à la sortie : modifier une table que vous avez relue ne change donc rien tant que vous ne la sauvegardez pas de nouveau, et modifier une table que vous avez sauvegardée n’atteint pas la sauvegarde après coup. Pour garder un aperçu que le joueur annule ensuite, il suffit par conséquent de ne pas le sauvegarder.

L’écriture a lieu une fois à la fin de toute image qui a changé quelque chose, quel que soit le nombre de clés que vous y avez réglées, et de nouveau quand le jeu s’arrête — y compris tout ce qui est réglé dans onShutdown. Pour une borne qui peut perdre le courant à tout moment, saveFlush écrit immédiatement. Le fichier est écrit à côté de l’ancien puis renommé par-dessus : une coupure de courant pendant une écriture laisse donc la sauvegarde précédente plutôt que la moitié d’une nouvelle.

Les nombres entiers reviennent sous forme d’entiers. JSON n’a qu’une sorte de nombre et Lua en a deux : sans cela, un score sauvegardé comme 100 reviendrait en 100.0 et s’afficherait avec un point décimal.

2.33.1. saveClear

saveClear()

Oublie tout et écrit la sauvegarde vide. Pour la « remise à zéro des meilleurs scores » d’un menu de service.

Paramètres :

  • Aucun.

Renvoie : rien.

Depuis : 3.00.

2.33.2. saveDelete

saveDelete(key)

Retire une clé. Supprimer une clé qui n’a jamais existé n’est pas une erreur.

Paramètres :

  • key — la clé à retirer.

Renvoie : rien.

Depuis : 3.00.

2.33.3. saveFlush

saveFlush()

Écrit la sauvegarde tout de suite plutôt qu’à la fin de l’image. Utilisez-la après quelque chose que vous seriez désolé de perdre — un nouveau meilleur score sur une borne qu’on éteint à la prise.

Paramètres :

  • Aucun.

Renvoie : rien.

Depuis : 3.00. Voir aussi : saveSet

2.33.4. saveGet

value = saveGet(key [, default])

Ce qui a été sauvegardé sous cette clé. Quand rien ne l’a été, c’est la valeur par défaut qui revient, ou nil quand il n’y en a pas — c’est ainsi qu’on distingue un premier lancement des suivants.

Paramètres :

  • key — la clé à lire.

  • default — facultatif ; ce qu’il faut répondre quand la clé n’existe pas.

Renvoie : la valeur sauvegardée, la valeur par défaut ou nil.

Depuis : 3.00. Voir aussi : saveSet

Exemple
-- Compter les lancements, et retenir les dix meilleurs scores.
local runs = saveGet("runs", 0) + 1
saveSet("runs", runs)

local best = saveGet("highScores", {})
best[#best + 1] = { name = initials, score = score }
table.sort(best, function(a, b) return a.score > b.score end)
while #best > 10 do table.remove(best) end
saveSet("highScores", best)
saveFlush()

2.33.5. saveGetAll

everything = saveGetAll()

Une copie de toute la sauvegarde, pour la lecture : l’afficher en entier pendant le débogage, ou parcourir des clés dont le jeu ne connaît pas les noms d’avance. Modifier ce qui revient ne change rien — c’est saveSetAll qui écrit une table entière.

Paramètres :

  • Aucun.

Renvoie : une table ; vide quand rien n’a été sauvegardé.

Depuis : 3.00. Voir aussi : saveSetAll, saveGet

Exemple
-- Qu'y a-t-il dedans ?  inspect est fourni justement pour cela.
debugPrint(require("inspect")(saveGetAll()))

2.33.6. saveSet

saveSet(key, value)

Garde une valeur jusqu’à ce que le jeu soit désinstallé. L’écriture a lieu à la fin de l’image : régler vingt clés dans une boucle n’écrit donc qu’un seul fichier.

Paramètres :

  • key — la clé à écrire.

  • value — un nombre, une chaîne, un booléen ou une table de ceux-ci.

Renvoie : rien.

Depuis : 3.00. Voir aussi : saveGet, saveFlush

2.33.7. saveSetAll

saveSetAll(everything)

Remplace toute la sauvegarde par cette table, en une seule étape. Les clés qui existaient et ne sont pas dans la table que vous donnez disparaissent.

Elle existe pour faire passer une ancienne sauvegarde à une nouvelle organisation. Le faire avec saveClear et une boucle de saveSet laisse un moment où la sauvegarde est vide, et une machine éteinte à ce moment-là perd tout ; cette fonction n’a pas ce moment, car le fichier est écrit une seule fois à la fin de l’image à partir de la table terminée.

Paramètres :

  • everything — table ; ce que la sauvegarde doit désormais contenir. Les mêmes valeurs que prend saveSet.

Renvoie : rien.

Depuis : 3.00. Voir aussi : saveGetAll, saveClear

Exemple
-- La version 1 gardait un score dans deux clés ; la version 2 en garde une table.
if saveGet("version", 1) < 2 then
    local old = saveGetAll()
    saveSetAll({
        version = 2,
        scores  = { { name = old.hiName, score = old.hiScore } },
        runs    = old.runs,
    })
    saveFlush()
end

2.34. Scène

La scène est la couche 3D dessinée entre la vidéo du disque et l’overlay ; les nœuds placés dans la couche de premier plan avec nodeSetLayer sont dessinés après l’overlay à la place. Elle est désactivée jusqu’à sceneEnable(true), a la taille de l’overlay et est effacée à la couleur de sceneSetBackground à chaque image. Les appels sceneSet* règlent l’aspect de toute la couche : lumière ambiante, ciel, brouillard, exposition et courbe de tons, bloom, anticrénelage et qualité des ombres ; les couleurs sont des entiers de 0 à 255 et les distances sont en unités du monde. sceneProject et sceneUnproject font le lien entre l’espace du monde et les coordonnées de l’overlay, et sceneGetStats rend compte du travail de la dernière image. Voir Scènes 3D.

2.34.1. sceneEnable

sceneEnable(enabled)

Active ou désactive la couche 3D. Les nœuds, les maillages et les matériaux peuvent être construits avant qu’elle soit active et survivent à sa désactivation ; seul le dessin s’arrête. Met fin au script quand on l’active sans GPU utilisable (voir Scènes 3D) : un jeu qui a une solution de repli en 2D interroge donc d’abord singeCapabilities().SCENE. Dans les deux cas, l’affichage se rafraîchit à l’image suivante.

Depuis : 3.00. Voir aussi : sceneSetBackground, sceneSetAntialias

Exemple
-- Se rabattre sur le simple overlay quand la 3D n'est pas disponible.
has3d = singeCapabilities().SCENE
if has3d then
    sceneEnable(true)
    buildArena()
else
    debugPrint("No 3D here; using the 2D attract mode.")
end

function onPause()
    sceneEnable(false)
end

2.34.2. sceneGetSize

width, height = sceneGetSize()

La taille de la couche, qui est la résolution de l’overlay : l’espace dans lequel travaillent sceneProject et sceneUnproject, et la taille à laquelle la scène est rendue. Changez-la avec overlaySetResolution. Avant que la couche ait reçu une taille, les deux valeurs valent 0.

Renvoie : Deux entiers, la largeur et la hauteur en coordonnées de l’overlay.

Depuis : 3.00. Voir aussi : overlaySetResolution, sceneUnproject

Exemple
-- Un réticule au centre de la vue, et ce qui se trouve dessous.
function onOverlayUpdate()
    local width, height = sceneGetSize()
    local cx = width / 2
    local cy = height / 2
    local ox, oy, oz = sceneUnproject(cx, cy, 0)
    local fx, fy, fz = sceneUnproject(cx, cy, 50)
    target = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz)
    fontPrint(cx - 4, cy - 8, "+")
    return OVERLAY_UPDATED
end

2.34.3. sceneGetStats

total, drawn, calls, textureKB = sceneGetStats()

Les chiffres de la dernière image pour la caméra de la fenêtre : les maillages rassemblés pour le dessin, combien d’entre eux étaient dans le champ de la caméra, les appels de dessin qu’ils sont devenus après instanciation, et la mémoire de textures que tient la scène, en kilo-octets. Pour la mise au point : une scène avec des centaines de drawn mais une poignée de calls partage bien ses maillages, et un textureKB qui ne tiendra pas dans la mémoire d’un Raspberry Pi réclame des textures KTX2. Les vues rendues ne comptent pas.

Renvoie : Quatre entiers.

Depuis : 3.00. Voir aussi : sceneEnable, modelInstance, materialSetTexture

Exemple
-- Un afficheur de débogage dans le coin pendant la mise au point du niveau.
function onOverlayUpdate()
    if showStats then
        local total, drawn, calls, textureKB = sceneGetStats()
        fontPrint(10, 10, string.format("%d meshes, %d in view, %d calls, %d MB textures", total, drawn, calls, math.floor(textureKB / 1024)))
    end
    return OVERLAY_UPDATED
end

2.34.4. sceneMeasure

sceneMeasure(on)
ms = sceneMeasure(false)

Chronomètre la scène 3D. sceneMeasure(true) démarre : chaque image qui suit attend que le GPU ait fini la scène et additionne ce temps, si bien que ce qui est mesuré est le travail plutôt que la cadence de l’affichage. sceneMeasure(false) arrête et renvoie le nombre moyen de millisecondes par image, ou nil quand aucune image n’a été dessinée. L’attente coûte de la fréquence d’images : chronométrez donc quelques secondes, pas une partie entière.

Renvoie : rien au démarrage ; un nombre ou nil à l’arrêt.

Depuis : 3.00. Voir aussi : singeSaveTier, sceneGetStats

Exemple
-- Deux secondes de l'écran titre disent si tous les effets passent.
sceneMeasure(true)
-- ... deux secondes plus tard :
local ms = sceneMeasure(false)

if ms and (ms > 8) then
	sceneSetBloom(1.0, 0.0)
end

2.34.5. sceneProbeGui

gui, x, y = sceneProbeGui(sx, sy)

Quelle GUI se trouve sur la surface sous un point de l’overlay, et à quel endroit de celle-ci : un rayon qui part de la caméra et passe par le point, avec la caméra de la dernière image rendue, lancé contre les triangles de chaque nœud visible dont le matériau affiche une GUI (materialSetGui), les coordonnées de texture de l’impact le plus proche donnant l’endroit sur la GUI. Renvoie le handle de la GUI et le pixel dans les coordonnées propres à cette GUI (0, 0 en haut à gauche, guiGetWidth, guiGetHeight en bas à droite), ou nil seul quand le point n’est sur aucune de ces surfaces, que la scène est désactivée ou que rien n’a encore été rendu. Le moteur pose la même question quand la souris ou un pistolet optique vise la scène alors qu’une GUI qui accepte les entrées est sur une surface et que rien de dessiné à plat ne se trouve sous le pointeur : les clics sur un moniteur dans la scène n’ont donc besoin d’aucun script ; l’appel sert au jeu qui veut la réponse lui-même, pour une visée laser, un effet de survol ou un test.

Paramètres :

  • sx, sy — le point, en coordonnées de l’overlay (une position de souris ou de pistolet optique).

Renvoie : Un entier et deux entiers, ou nil.

Depuis : 3.00. Voir aussi : materialSetGui, guiSetInput, sceneProject, sceneUnproject

Exemple
-- Le point d'un pistolet optique brille là où il tombe sur l'écran du cockpit.
function onMouseMoved(x, y)
    local g, px, py = sceneProbeGui(x, y)
    if g == screenGui then
        guiSetValue(g, screenPage, "dot", string.format("%d,%d", px, py))
    end
end

2.34.6. sceneProject

x, y, depth, inFront = sceneProject(wx, wy, wz)

Où tombe un point du monde en coordonnées de l’overlay, avec la caméra de la dernière image rendue. depth vaut 0 au plan proche et 1 au plan lointain, pour trier des étiquettes ou les estomper avec la distance. inFront vaut false quand le point est derrière la caméra, et x et y n’ont alors aucun sens ; avant que la première image ait été rendue, il n’y a rien contre quoi projeter, et toutes les valeurs reviennent à 0 avec inFront à false. Les points situés devant mais hors de la vue reviennent avec des coordonnées au-delà des bords de l’overlay : vérifiez-les donc avec sceneGetSize avant de dessiner. L’usage habituel est une étiquette de nom ou une barre de vie dessinée avec fontPrint ou spriteDraw au-dessus d’un objet 3D.

Paramètres :

  • wx, wy, wz — le point du monde, en unités du monde.

Renvoie : Deux nombres, un nombre et un booléen.

Depuis : 3.00. Voir aussi : sceneUnproject, nodeGetWorldPosition, sceneGetSize

Exemple
-- Un nom et une barre de vie qui flottent au-dessus de chaque personnage.
function onOverlayUpdate()
    for _, enemy in ipairs(enemies) do
        local x, y, depth, visible = sceneProject(nodeGetWorldPosition(enemy.node))
        if visible then
            fontPrint(x - 30, y - 80, enemy.name)
            overlayBox(x - 30, y - 60, x - 30 + enemy.health * 0.6, y - 54)
        end
    end
    return OVERLAY_UPDATED
end

2.34.7. sceneUnproject

x, y, z = sceneUnproject(sx, sy, distance)

Le point du monde situé à distance unités le long du rayon qui passe par un pixel de l’overlay, avec la caméra de la dernière image rendue. Deux distances donnent un rayon pour désigner un objet avec physicsRaycast ; une seule place un objet « là où le joueur a cliqué ». Avant que la première image ait été dessinée, elle renvoie l’origine.

Paramètres :

  • sx, sy — le pixel de l’overlay, en coordonnées de l’overlay.

  • distance — la distance le long du rayon, en unités du monde ; 0 est le plan proche.

Renvoie : Trois nombres, le point du monde.

Depuis : 3.00. Voir aussi : sceneProject, mouseGetPosition, physicsRaycast

Exemple
-- Poser un repère sur ce que le joueur a cliqué, ou à 8 unités s'il n'y a rien.
function onMouseDown(button)
    local mx, my = mouseGetPosition(0)
    local ox, oy, oz = sceneUnproject(mx, my, 0)
    local fx, fy, fz = sceneUnproject(mx, my, 100)
    local hit, hx, hy, hz = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz)
    if hit then
        nodeSetPosition(marker, hx, hy, hz)
    else
        nodeSetPosition(marker, sceneUnproject(mx, my, 8))
    end
end

2.34.8. sceneSetAmbient

sceneSetAmbient(r, g, b)

De la lumière venue de partout, de 0 à 255 par canal, traitée comme du sRGB ; par défaut, un gris sombre de 26, 26, 26. Elle éclaircit les faces qu’aucune lumière n’atteint pour qu’elles ne soient pas noires, et materialSetOcclusionMap l’assombrit dans les creux. Quand un ciel est réglé et que sceneSetEnvironment est actif, la lumière du ciel remplace cette valeur.

Depuis : 3.00. Voir aussi : lightNew, sceneSetEnvironment, sceneSetSky

Exemple
-- Une cour au clair de lune :  un bleu léger partout, une lune directionnelle froide.
sceneSetAmbient(20, 25, 45)
moon = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(moon, -5, 10, 3)
nodeLookAt(moon, 0, 0, 0)
lightSetColor(moon, 170, 190, 255)
lightSetIntensity(moon, 0.4)

2.34.9. sceneSetAntialias

sceneSetAntialias(antialias)

Active ou désactive le multiéchantillonnage 4x ; il est actif par défaut partout où le GPU le propose pour les formats de la couche, et absent sans bruit là où il ne le propose pas. Le désactiver fait gagner de la vitesse sur un Raspberry Pi. Les cibles de rendu sont reconstruites aussitôt : appelez-la donc pendant la mise en place plutôt qu’à chaque image.

Depuis : 3.00. Voir aussi : sceneEnable, sceneSetShadowSize

Exemple
-- Un réglage de qualité venu de l'écran d'options du jeu.
function applyQuality(level)
    if level == "low" then
        sceneSetAntialias(false)
        sceneSetShadowSize(512)
        sceneSetShadowCascades(2)
    else
        sceneSetAntialias(true)
        sceneSetShadowSize(2048)
        sceneSetShadowCascades(3)
    end
end

2.34.10. sceneSetBackground

sceneSetBackground(r, g, b)
sceneSetBackground(r, g, b, a)

La couleur à laquelle la couche est effacée à chaque image, de 0 à 255 par canal. a vaut 255 quand il est omis, une toile de fond opaque ; en dessous de 255, la vidéo transparaît, et 0 (le choix habituel pour un jeu avec un disque) rend le fond entièrement transparent. Tant qu’elle n’est pas appelée, la couche est effacée en noir transparent. Un ciel de sceneSetSky est dessiné par-dessus le fond : la vidéo ne transparaît donc plus tant qu’un ciel est réglé.

Paramètres :

  • r, g, b — la couleur d’effacement.

  • a — l’alpha d’effacement ; 255 quand il est omis.

Depuis : 3.00. Voir aussi : sceneEnable, sceneSetSky, sceneSetFog

Exemple
-- Le disque se voit derrière le cockpit 3D ; un ciel nocturne uni pour le menu.
function showCockpit()
    sceneSetBackground(0, 0, 0, 0)
    discPlay()
end

function showMenu()
    discPause()
    sceneSetBackground(10, 12, 30)
end

2.34.11. sceneSetBloom

sceneSetBloom(threshold, strength)

Un halo autour de tout ce qui est plus lumineux que threshold, pris dans la lumière linéaire de la scène avant l’exposition et la courbe de tons (où 1 est le blanc), puis rajouté avec la force strength. Par défaut, le seuil vaut 1 et la force 0, donc pas de bloom ; de 0.2 à 0.4, c’est discret, 1 fait une brume. Le halo est flouté sur une chaîne de passes à demi-taille, si bien qu’il coûte peu, et seule la caméra de la fenêtre en bénéficie : les vues rendues s’en passent. Les valeurs négatives sont ramenées à 0.

Paramètres :

  • threshold — la luminosité linéaire au-dessus de laquelle un pixel brille ; 1 est le blanc avant la courbe de tons.

  • strength — la part du halo qui est rajoutée ; 0 pour aucune.

Depuis : 3.00. Voir aussi : sceneSetExposure, materialSetEmissive, sceneSetTonemap

Exemple
-- Les néons et les phares brillent ; la chaussée, non.
sceneSetBloom(1.0, 0.35)
neonLook = materialNew()
materialSetColor(neonLook, 255, 40, 120)
materialSetEmissive(neonLook, 255, 40, 120)
nodeSetMesh(sign, meshBox(2, 0.3, 0.05), neonLook)

2.34.12. sceneSetEnvironment

sceneSetEnvironment(lit)

Indique si le ciel réglé par sceneSetSky éclaire la scène : sa lumière diffuse venue de toutes les directions à la place de sceneSetAmbient, et ses reflets sur les métaux et les surfaces brillantes, nets sur un miroir et de plus en plus flous à mesure que la rugosité augmente. Actif par défaut, si bien qu’un ciel éclaire la scène dès qu’il est réglé ; false ne garde le ciel que comme toile de fond, et la lumière ambiante uniforme revient. Sans ciel, cela n’a aucun effet.

Depuis : 3.00. Voir aussi : sceneSetSky, sceneSetAmbient, sceneSetSkyIntensity

Exemple
-- Une toile de fond peinte qui ne doit pas teinter le chrome.
sceneSetSky(DIR .. "Skies/matteBackdrop.png")
sceneSetEnvironment(false)
sceneSetAmbient(40, 40, 45)

2.34.13. sceneSetExposure

sceneSetExposure(stops)

Éclaircit ou assombrit toute la scène en diaphragmes photographiques, de -10 à 10 (les valeurs hors plage sont ramenées dans la plage) : +1 double la lumière, -1 la divise par deux. La valeur par défaut est 0. Elle est appliquée après le bloom et avant la courbe de tons : une scène lumineuse à +2 se tasse donc vers le blanc au lieu d’être écrêtée, et une grotte et une plage peuvent partager les mêmes lumières. Animez-la pour une adaptation lente quand on passe de l’intérieur à la lumière du jour.

Depuis : 3.00. Voir aussi : sceneSetTonemap, lightSetIntensity, sceneSetSkyIntensity

Exemple
-- Les yeux s'adaptent :  rapprocher en douceur l'exposition de la cible de la zone à chaque image.
targetStops  = 0
currentStops = 0

function onEnterArea(area)
    targetStops = area.indoors and 1.5 or -0.5
end

function onOverlayUpdate()
    currentStops = currentStops + (targetStops - currentStops) * 0.05
    sceneSetExposure(currentStops)
    return OVERLAY_UPDATED
end

2.34.14. sceneSetFog

sceneSetFog(r, g, b, near, far)
sceneSetFog()

Un brouillard de distance : dégagé jusqu’à near unités de la caméra, entièrement de la couleur du brouillard à far et au-delà, sur les maillages (y compris ceux qui ne sont pas éclairés) comme sur les particules ; les particules additives s’estompent au lieu de virer au gris. Sans argument, ou avec un far qui n’est pas plus grand que near, il n’y a pas de brouillard. Le ciel n’est pas embrumé : choisissez donc une couleur proche de son horizon, ou du fond quand il n’y a pas de ciel. Tout autre nombre d’arguments met fin au script.

Paramètres :

  • r, g, b — la couleur du brouillard, de 0 à 255.

  • near — la distance où commence le brouillard, en unités du monde depuis la caméra.

  • far — la distance où il ne reste plus que le brouillard.

Depuis : 3.00. Voir aussi : sceneSetSky, sceneSetBackground, cameraSetPerspective

Exemple
-- Une brume matinale sur les collines, qui se dissipe à mesure que le niveau avance.
sceneSetSky(DIR .. "Skies/dawn.hdr")
sceneSetFog(190, 200, 215, 40, 160)

function onOverlayUpdate()
    if levelTime > 60 then
        sceneSetFog()
    end
    return OVERLAY_UPDATED
end

2.34.15. sceneSetShadowCascades

sceneSetShadowCascades(count)

En combien de cartes l’ombre d’une lumière directionnelle est découpée le long de la vue, de 1 à 4 (les valeurs hors plage sont ramenées dans la plage ; la valeur par défaut est 3). Chaque cascade couvre une tranche de la vue de la caméra jusqu’à sceneSetShadowDistance, la tranche la plus proche étant la plus petite, si bien que les ombres proches de la caméra sont nettes quelle que soit la taille du niveau. 1 ajuste une seule carte à toute la scène, ce qui convient aux petites scènes, et c’est toujours ce qui sert avec une caméra orthographique. Chaque cascade ajoute une passe d’ombre pour chaque lumière directionnelle qui projette des ombres ; 2 est un choix raisonnable sur un Raspberry Pi.

Depuis : 3.00. Voir aussi : sceneSetShadowDistance, sceneSetShadowSize, lightSetShadow

Exemple
-- Un grand niveau en extérieur :  des ombres nettes près du joueur, qui portent loin.
sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 30, 40, 20)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)
sceneSetShadowCascades(4)
sceneSetShadowDistance(120)
sceneSetShadowSize(2048)

2.34.16. sceneSetShadowDistance

sceneSetShadowDistance(distance)

Jusqu’où les ombres en cascades portent depuis la caméra, en unités du monde ; la valeur par défaut est 60 et les valeurs inférieures à 1 sont ramenées à 1. Au-delà, une lumière directionnelle ne projette aucune ombre. Des distances plus courtes rendent chaque cascade plus nette, puisque les mêmes cartes couvrent moins de terrain : réglez-la donc à peu près à la distance où le joueur peut encore distinguer une ombre. Elle ne compte qu’avec plus d’une cascade sous une caméra en perspective.

Depuis : 3.00. Voir aussi : sceneSetShadowCascades, sceneSetShadowSize

Exemple
-- Les ombres n'ont besoin d'atteindre que le mur du fond de l'arène.
sceneSetShadowCascades(2)
sceneSetShadowDistance(35)
sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 10, 20, 8)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)

2.34.17. sceneSetShadowSize

sceneSetShadowSize(size)

Le nombre de texels par côté de chaque carte d’ombres, cascade et face de cube, de 256 à 4096 (les valeurs hors plage sont ramenées dans la plage ; la valeur par défaut est 1024). Plus c’est grand, plus c’est net et lent, en mémoire comme en temps, puisque chaque lumière qui projette des ombres a ses propres cartes à cette taille. 2048 convient à un ordinateur de bureau, 512 à un Raspberry Pi. Les cartes sont reconstruites à l’image suivante.

Depuis : 3.00. Voir aussi : lightSetShadow, sceneSetShadowCascades, sceneSetAntialias

Exemple
-- Dimensionner les cartes d'ombres selon la machine.
if singeGetPlatform() == "raspberrypi" then
    sceneSetShadowSize(512)
else
    sceneSetShadowSize(2048)
end

2.34.18. sceneSetSky

sceneSetSky(file)
sceneSetSky(nil)
sceneSetSky()

Enveloppe la scène dans un panorama équirectangulaire : un .hdr Radiance (tel que le fournissent les sites HDRI, en gardant sa plage), ou un PNG, un JPEG ou toute autre image que lit SDL_image, décodée depuis le sRGB. Le nom est relatif au jeu, comme pour spriteLoad. Le ciel est dessiné derrière tout le reste à la place de la couleur de fond (la vidéo ne transparaît donc plus) et éclaire la scène sauf avec sceneSetEnvironment(false). Son centre fait face à -Z et son haut est en haut. Il est rééchantillonné dans un cube d’au plus 1024 texels par face : une image de 2048 sur 1024 suffit donc largement, et les plus grandes prennent un moment à préparer sur un Raspberry Pi. Sans argument, ou avec nil, le ciel est retiré. Met fin au script quand le fichier ne peut pas être lu ou que la 3D n’est pas disponible.

Exemple
-- Un ciel couvert pour le niveau des docks, avec un brouillard assorti à son horizon.
sceneEnable(true)
sceneSetSky(DIR .. "Skies/overcastHarbor.hdr")
sceneSetSkyIntensity(0.8)
sceneSetFog(190, 200, 215, 25, 90)

function onLevelEnd()
    sceneSetSky()
    sceneSetBackground(0, 0, 0, 0)
end

2.34.19. sceneSetSkyIntensity

sceneSetSkyIntensity(scale)

La luminosité du ciel et de la lumière qu’il répand, 1 tel qu’il a été chargé ; les valeurs négatives sont ramenées à 0. Utile pour atténuer un ciel PNG trop lumineux, pour faire d’un ciel .hdr la lumière principale de la scène, ou pour faire apparaître et disparaître le ciel en fondu. Elle multiplie le ciel lui-même, contrairement à sceneSetExposure, qui met tout à l’échelle.

Depuis : 3.00. Voir aussi : sceneSetSky, sceneSetExposure, sceneSetEnvironment

Exemple
-- Le crépuscule :  le ciel et sa lumière baissent en dix secondes.
sceneSetSky(DIR .. "Skies/sunset.hdr")
duskStart = singeGetTicks()

function onOverlayUpdate()
    local t = math.min((singeGetTicks() - duskStart) / 10000, 1)
    sceneSetSkyIntensity(1 - 0.8 * t)
    return OVERLAY_UPDATED
end

2.34.20. sceneSetTonemap

sceneSetTonemap(curve)

La courbe qui fait passer la lumière linéaire de la scène à l’écran, appliquée après l’exposition. TONEMAP_NEUTRAL (la valeur par défaut) garde des couleurs fidèles et ne tasse que la lumière la plus vive ; TONEMAP_ACES est la courbe cinématographique, avec plus de contraste et une transition plus chaude vers le blanc ; TONEMAP_NONE écrête au blanc. Les matériaux vidéo, les surfaces non éclairées et le ciel passent par la même courbe : un jeu dont le disque doit apparaître exactement tel qu’il a été filmé veut donc TONEMAP_NONE avec une exposition de 0. Toute autre valeur met fin au script.

Depuis : 3.00. Voir aussi : sceneSetExposure, sceneSetBloom

Exemple
-- Un rendu cinéma pour la cinématique, des couleurs fidèles pour le jeu.
function onCutsceneStart()
    sceneSetTonemap(TONEMAP_ACES)
    sceneSetExposure(0.5)
end

function onCutsceneEnd()
    sceneSetTonemap(TONEMAP_NEUTRAL)
    sceneSetExposure(0)
end

2.35. Script

Ces fonctions permettent à un script Singe de passer la main à un autre script Singe : c’est le mécanisme derrière le lanceur intégré Menu.singe. Les développeurs de jeux ne devraient pas s’en servir ; construisez votre jeu comme un seul script et laissez le système de menus gérer l’enchaînement. Elles sont documentées ici par souci d’exhaustivité et pour quiconque maintient le menu lui-même.

Les deux appels prennent une table de la forme d’une entrée GAMES[] de games.dat et la mettent dans la file de l’exécuteur de scripts du moteur. La nouvelle configuration part de celle en cours : les options de ligne de commande comme le dossier de données et la trace sont donc reprises, mais jamais le disque, la vidéo ni le conteneur, car chaque entrée apporte les siens. Le script en cours se termine à la fin de l’image, onShutdown est appelé, et le script mis en file démarre avec un état Lua neuf (voir Callbacks du moteur). Le dossier de données du nouveau script suit la même règle qu’un lancement en ligne de commande (voir singeGetDataPath) ; quand il ne peut pas être créé, l’appel met fin au script appelant.

2.35.1. scriptExecute

scriptExecute(config)

Remplace le script en cours par celui que décrit la table. Le script en cours s’arrête à la fin de cette image et onShutdown s’exécute ; la main ne lui revient jamais, et quand le nouveau script quitte, le moteur passe à ce qui reste dans la file ou se ferme. Les clés chaînes que connaît le moteur sont SCRIPT, CONTAINER, VIDEO, STRETCH, NO_MOUSE, RESOLUTION_X, RESOLUTION_Y, SINDEN_GUN, AUDIO_TRACK, AUDIO_DELAY, LEGACY_SPRITE_ARGS, CANVAS_X et CANVAS_Y ; les autres clés sont ignorées et les clés qui ne sont pas des chaînes sont sautées. Une valeur SCRIPT, CONTAINER ou VIDEO qui n’est pas une chaîne met fin au script, de même qu’un argument qui n’est pas une table.

Paramètres :

  • config — une table de champs de games.dat, avec au minimum SCRIPT ou CONTAINER.

Depuis : 2.00 Voir aussi : scriptPush, singeQuit

Exemple
-- Un lanceur qui ne revient jamais à lui-même.
function onInputPressed(what)
    if what == SWITCH_START1 then
        scriptExecute({
            SCRIPT = DIR .. "../MyGame/MyGame.singe",
            VIDEO  = DIR .. "../MyGame/MyGame.mp4",
        })
    end
end

2.35.2. scriptPush

scriptPush(config)

Démarre le script que décrit la table et met la configuration en cours dans la file derrière lui : quand le nouveau script quitte, le script en cours repart donc du début. Rien n’est conservé en place : le onShutdown du script en cours s’exécute maintenant, son état Lua est jeté, et l’exécution suivante repart de zéro, ce qui explique pourquoi Menu.singe sauvegarde sa sélection dans un fichier avant d’empiler. La table prend les mêmes clés que scriptExecute.

Paramètres :

  • config — une table de champs de games.dat, comme pour scriptExecute.

Depuis : 2.00 Voir aussi : scriptExecute, singeQuit, onShutdown

Exemple
-- Menu.singe : lancer le jeu sélectionné et revenir ensuite.
function onInputPressed(what)
    if what == SWITCH_START1 or what == SWITCH_BUTTON1 then
        SHUTDOWN_FROM_PUSH = true
        scriptPush(GAME_LIST[GAME_SELECTED])
    end
end

2.36. Singe

Les fonctions de l’espace de noms singe* pilotent le moteur lui-même : la fenêtre, les captures d’écran, le système de pause, la sortie et le rechargement, le retard audio qui sert à la synchronisation labiale, et quelques chemins et indicateurs qui viennent de la ligne de commande et de games.dat. Rien ici ne prend de handle. Le comportement de la pause est décrit dans La pause et les valeurs de retard audio dans Synchronisation audio.

2.36.1. allowSocketCall

allowed = allowSocketCall()

Extension Hypseus, toujours false dans Singe. Hypseus répond si l’utilisateur l’a autorisé à envoyer des données à un serveur de statistiques, ce que son -noserversend désactive ; l’envoi lui-même y est mis en commentaire. Singe n’envoie rien nulle part : rien n’est donc permis et la réponse ne change jamais. Elle existe pour qu’un jeu qui pose la question ne s’arrête pas sur une fonction manquante.

Renvoie : un booléen, toujours false.

Depuis : 3.00

2.36.2. getUserString

id = getUserString()

Extension Hypseus, toujours une chaîne vide. Malgré son nom, ce n’est pas une chaîne que l’utilisateur a réglée : Hypseus répond l’identifiant d’installation de la machine qu’il envoie avec les statistiques réseau, tiré du MachineGuid de Windows ou de l’identifiant de machine de Linux. Singe n’envoie rien nulle part et ne donnera pas à un jeu une empreinte de la machine sur laquelle il tourne.

Renvoie : une chaîne, toujours vide.

Depuis : 3.00 Voir aussi : allowSocketCall

2.36.3. singeDisablePauseKey

singeDisablePauseKey()

Donne la touche pause au script, exactement comme le fait singeSetPauseKeyEnabled(false). C’est une fonction définie dans Framework.singe, conservée pour que les anciens jeux tournent sans modification.

Remarques : Alias hérité.

Le nouveau code doit appeler singeSetPauseKeyEnabled avec false.

Depuis : 1.18 (RDG) Voir aussi : singeSetPauseKeyEnabled, singeEnablePauseKey

Exemple
-- Code d'un ancien jeu ; l'écriture moderne est singeSetPauseKeyEnabled(false).
singeDisablePauseKey()

function onInputPressed(what)
    if what == SWITCH_PAUSE then
        togglePauseMenu()
    end
end

2.36.4. singeEnablePauseKey

singeEnablePauseKey()

Rend la touche pause au moteur, exactement comme le fait singeSetPauseKeyEnabled(true). C’est une fonction définie dans Framework.singe, conservée pour que les anciens jeux tournent sans modification.

Remarques : Alias hérité.

Le nouveau code doit appeler singeSetPauseKeyEnabled avec true.

Depuis : 1.18 (RDG) Voir aussi : singeSetPauseKeyEnabled, singeDisablePauseKey

Exemple
-- Code d'un ancien jeu ; l'écriture moderne est singeSetPauseKeyEnabled(true).
function pauseMenuClose()
    singeSetPauseFlag(false)
    singeEnablePauseKey()
end

2.36.5. utilFileMove

ok = utilFileMove(from, to)

Déplace le fichier from vers to, en remplaçant ce qui s’y trouve en une seule étape : à tout instant to est soit le fichier qu’il était, soit le nouveau en entier, jamais absent ni à moitié écrit, ce que os.rename ne promet pas sous Windows et qu’écrire par-dessus un fichier ne promet nulle part. from est d’abord mis sur le disque. Quand les deux sont sur des disques différents, le fichier est copié à côté de to sous un nom temporaire, chaque écriture vérifiée, et ne prend le nom qu’une fois la copie complète. Pour mettre un téléchargement ou un fichier fraîchement écrit à la place d’un fichier qui fonctionne. Les deux sont des chemins sur le disque, tels que io.open les prend.

Paramètres :

  • from — chaîne, le fichier à déplacer.

  • to — chaîne, sa destination.

Renvoie : true, ou false quand cela n’a pas pu se faire : to est alors tel qu’il était et from est toujours là.

Depuis : 3.00. Voir aussi : utilFilePart, utilSha256File

Exemple
-- Écrire les nouveaux réglages à côté des anciens, puis les mettre en place.
local path = singeGetDataPath() .. "settings.json"
local part = utilFilePart(path)
local file = io.open(part, "wb")
file:write(text)
file:close()
if not utilFileMove(part, path) then
    debugPrint("The settings could not be kept.")
end

2.36.6. utilFilePart

name = utilFilePart(path)

Le nom sous lequel écrire un fichier avant que utilFileMove ne le mette à path : path suivi d’un nombre propre à ce Singe en cours d’exécution et de .part. Deux Singe qui écrivent le même fichier en même temps, le même jeu lancé deux fois par exemple, écrivent alors chacun son propre fichier au lieu d’un seul à eux deux, et c’est le dernier à finir qui est gardé. La demande supprime aussi ce qu’un Singe arrêté en cours de route a laissé pour le même path, si bien que rien ne s’accumule.

Paramètres :

  • path — chaîne, la destination du fichier une fois terminé.

Renvoie : Le nom sous lequel écrire, une chaîne. Il est le même chaque fois que ce Singe le demande pour le même path.

Depuis : 3.00. Voir aussi : utilFileMove

Exemple
-- Garder le fantôme du meilleur tour, sans qu'un fichier à moitié écrit ne prenne jamais sa place.
local path = singeGetDataPath() .. "ghost.dat"
local part = utilFilePart(path)
local file = io.open(part, "wb")
if file and file:write(ghostData) and file:close() then
    utilFileMove(part, path)
end

2.36.7. utilSha256

digest = utilSha256(data)

Le SHA-256 d’une chaîne, sous forme de 64 caractères hexadécimaux en minuscules. Sûr pour le binaire : il fonctionne donc aussi bien sur les octets d’un fichier que sur du texte.

Pour décider si les octets que vous avez sont ceux qu’on vous a promis : un jeu téléchargé comparé à l’empreinte que porte son entrée du catalogue, ou la clé publique d’un serveur comparée à une valeur épinglée. Le module md5 inclus est toujours là pour une somme de contrôle, mais une empreinte qui sert à décider si l’on peut faire confiance à quelque chose doit être une empreinte qui mérite encore la confiance.

Paramètres :

  • data — une chaîne d’octets. Vide, elle met fin au script.

Renvoie : chaîne, 64 caractères hexadécimaux en minuscules.

Depuis : 3.00.

Exemple
-- Refuser un téléchargement qui n'est pas arrivé intact.
local file = io.open("game.part", "rb")
local bytes = file:read("*a")
file:close()
if utilSha256(bytes) ~= expected then
    os.remove("game.part")
end

2.36.8. utilSha256File

digest = utilSha256File(path)

Le SHA-256 du contenu d’un fichier, tel que utilSha256 le donne pour une chaîne, lu bloc par bloc pour que le fichier ne soit jamais tenu en mémoire en entier : un jeu peut peser plusieurs gigaoctets. path est un chemin sur le disque, tel que io.open le prend.

Paramètres :

  • path — chaîne, le fichier à lire.

Renvoie : chaîne, 64 caractères hexadécimaux en minuscules, ou nil quand le fichier ne peut pas être lu.

Depuis : 3.00. Voir aussi : utilSha256, utilFileMove

Exemple
-- Refuser un téléchargement qui n'est pas arrivé intact, quelle que soit sa taille.
if utilSha256File("game.part") ~= expected then
    os.remove("game.part")
end

2.36.9. singeCapabilities

capabilities = singeCapabilities()

Ce que cette machine peut faire tourner. La table a une entrée par nom de capacité que peut utiliser une liste REQUIRES de games.dat (SCENE, GUI, SHADOWS, POST, SKIN, MORPH), chacune true ou false, plus tier : la classe de performances mesurée de la machine, de 0 (pas de 3D) à 3 (un GPU de bureau), ou nil avant que le menu l’ait mesurée. Un jeu pose la question pour pouvoir se passer de quelque chose plutôt que d’être refusé faute de l’avoir.

Renvoie : une table.

Depuis : 3.00. Voir aussi : singeHasGpu, singeSaveTier, sceneMeasure

Exemple
-- Des ombres là où la machine les a, un simple soleil là où elle ne les a pas.
local machine = singeCapabilities()

lightSetShadow(sun, machine.SHADOWS)
if (machine.tier or 0) < 2 then
	sceneSetBloom(1.0, 0.0)
end

2.36.10. singeGetAudioCalibration

milliseconds = singeGetAudioCalibration()

Renvoie le retard audio propre à la machine en vigueur, en millisecondes : la valeur que l’écran de calibrage du menu a sauvegardée dans machine.cfg à la racine des données, ou celle réglée depuis par singeSetAudioCalibration. Zéro quand la machine n’a jamais été calibrée. Il s’applique à chaque jeu de la machine, en plus du retard propre au jeu que donne singeGetAudioDelay.

Renvoie : un entier, en millisecondes.

Exemple
-- Menu.singe : démarrer l'écran de calibrage à partir de la valeur sauvegardée.
function calibrationBegin()
    CALIBRATING  = true
    CAL_ORIGINAL = singeGetAudioCalibration()
    CAL_VALUE    = CAL_ORIGINAL
    CAL_LATENCY  = singeGetAudioLatency()
    CAL_BEAT     = singeGetTicks() - CAL_PERIOD
end

2.36.11. singeGetAudioDelay

milliseconds = singeGetAudioDelay()

Renvoie le retard audio propre au jeu en vigueur, en millisecondes, qu’il vienne de --audiodelay, de la clé AUDIO_DELAY de l’entrée du jeu dans games.dat ou de singeSetAudioDelay. Zéro quand aucun n’a été réglé. Il s’ajoute au calibrage de la machine et à la latence mesurée du périphérique quand le moteur décide quand montrer chaque image de la vidéo.

Renvoie : un entier, en millisecondes.

Depuis : 3.00 Voir aussi : singeSetAudioDelay, singeGetAudioCalibration

Exemple
-- Menu de service : afficher le décalage de synchronisation actuel à côté de son curseur.
function drawSyncSetting(y)
    local delay = singeGetAudioDelay()
    fontPrint(40, y, string.format("A/V offset: %+d ms", delay))
end

2.36.12. singeGetAudioLatency

milliseconds = singeGetAudioLatency()

Renvoie la file du périphérique audio que le moteur a mesurée à l’ouverture du mélangeur, en millisecondes : le temps entre la remise des échantillons au mélangeur et leur arrivée au périphérique, avant tout calibrage ou retard propre au jeu. Le moteur la compense déjà ; un écran de calibrage en a besoin pour programmer son clic et son flash, et elle mérite d’être affichée dans une vue de diagnostic.

Renvoie : un entier, en millisecondes.

Depuis : 3.00 Voir aussi : singeGetAudioCalibration, singeGetAudioDelay

Exemple
-- Menu.singe : le flash suit le clic de la file du périphérique plus la valeur candidate.
function calibrationUpdate()
    local now = singeGetTicks()
    local gap = CAL_LATENCY + CAL_VALUE
    if now - CAL_BEAT >= CAL_PERIOD then
        CAL_BEAT     = now
        CAL_CLICK_AT = now + math.max(0, -gap)
        CAL_FLASH_AT = now + math.max(0, gap)
    end
end

2.36.13. singeGetDataPath

path = singeGetDataPath()

Renvoie le dossier dans lequel Singe écrit pour ce jeu, avec un séparateur de chemin final pour qu’un nom de fichier puisse y être ajouté directement. C’est un sous-dossier de la base --datadir qui porte le nom du jeu (pour un jeu empaqueté, le nom de la base de données puis le dossier du script à l’intérieur) ; sans --datadir, la base est data dans le dossier du jeu. Les captures d’écran, les index vidéo et trace.txt y vont, et les sauvegardes, les meilleurs scores et les réglages devraient y aller aussi ; Singe 2.x les écrivait à côté du jeu, qui peut être en lecture seule.

Renvoie : chemin (chaîne) terminé par un séparateur.

Depuis : 2.00 Voir aussi : singeGetScriptPath, singeScreenshot

Exemple
-- Menu.singe garde sa dernière sélection d'un lancement à l'autre.
CONFIG_FILE = singeGetDataPath() .. "menu.dat"

function saveConfig()
    local cfg = io.open(CONFIG_FILE, "w")
    if cfg then
        cfg:write("GAME_SELECTED = " .. GAME_SELECTED .. "\n")
        cfg:close()
    else
        debugPrint("Unable to write " .. CONFIG_FILE)
    end
end

2.36.14. singeGetGameId

id = singeGetGameId()

Le GAME_ID de l’entrée de ce jeu dans games.dat, ou nil quand elle n’en a pas. C’est l’identifiant sous lequel le service en ligne connaît le jeu, et la clé sous laquelle est tenu un tableau des scores.

Le format est un UUID, sous la forme canonique de 36 caractères — huit chiffres hexadécimaux, trois groupes de quatre, puis douze, séparés par des traits d’union :

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

Rien d’autre n’est accepté. L’identifiant est un segment de chemin dans les URL du service : un identifiant contenant une barre oblique ou un point d’interrogation serait publié puis ne serait jamais joignable, et deux identifiants qui ne diffèrent que par la casse feraient deux jeux pour la base de données et un seul pour quiconque les lit. La comparaison ignore la casse et le stockage se fait en minuscules : un identifiant tapé en majuscules désigne donc le même jeu.

N’importe quel UUID fera l’affaire — générez-en un comme bon vous semble, ou laissez publish.lua en afficher un. Un jeu qui n’en a pas peut être joué mais pas classé : il n’y aurait rien de stable sur quoi indexer un tableau des scores, et un identifiant inventé à l’exécution créerait un tableau différent chaque fois que les fichiers seraient déplacés.

Un .game, un identifiant. Un .game dont le games.dat a plusieurs entrées — une compilation, ou un même jeu en deux langues — est un seul téléchargement, et chacune de ses entrées porte le même GAME_ID. Le service en ligne présente chaque entrée comme un jeu à part entière, et n’accepte pas un .game dont les entrées ne s’accordent pas sur leur identifiant ou dont l’une ne l’a pas. Leurs scores restent tout de même séparés : voir Meilleurs scores en ligne.

Renvoie : chaîne, ou nil.

Depuis : 3.00. Voir aussi : Meilleurs scores en ligne, games.dat

Exemple
-- Ne proposer le tableau des scores que si ce jeu a une identité sous laquelle être classé.
if singeGetGameId() then
    showLeaderboardButton()
end

2.36.15. singeGetHeight

height = singeGetHeight()

Renvoie la hauteur de la fenêtre de Singe en pixels d’écran, et non en unités de l’overlay, telle qu’est la fenêtre au moment de l’appel. Utilisez overlayGetHeight pour dessiner ; celle-ci sert à un écran de réglages qui décrit l’affichage, ou à décider combien de détails une scène peut se permettre.

Renvoie : un entier, en pixels.

Depuis : 1.x Voir aussi : singeGetWidth, overlayGetHeight

Exemple
-- Décrire l'affichage dans le menu de service.
function drawDisplayInfo(y)
    fontPrint(40, y, string.format("Window %dx%d, overlay %dx%d", singeGetWidth(), singeGetHeight(), overlayGetWidth(), overlayGetHeight()))
end

2.36.16. singeGetPauseFlag

paused = singeGetPauseFlag()

Renvoie l’indicateur de pause du moteur : true tant que le jeu est mis en pause par la touche pause ou par singeSetPauseFlag. C’est indépendant du fait que le disque soit arrêté sur une image en pause (discGetState) ; lisez-le pour savoir si une pause a été demandée délibérément. Tant que la touche pause tient le jeu figé, aucun callback ne s’exécute : depuis un callback, l’indicateur ne peut donc être vu à true qu’après un singeSetPauseFlag(true) du script lui-même.

Renvoie : booléen.

Depuis : 1.x (RDG) Voir aussi : singeSetPauseFlag, singeSetPauseKeyEnabled

Exemple
-- Les minuteries restent immobiles tant que la pause propre au jeu est affichée.
function onOverlayUpdate()
    if not singeGetPauseFlag() then
        elapsed = elapsed + 1
        updateEnemies()
    end
    drawFrame()
    return OVERLAY_UPDATED
end

2.36.17. singeGetScriptPath

path = singeGetScriptPath()

Renvoie le chemin du fichier de script en cours tel que le moteur l’a résolu. Framework.singe tire de cette valeur la globale DIR, le dossier du script avec son séparateur final, et c’est de DIR que se servent la plupart des jeux pour construire les chemins de leurs ressources.

Renvoie : chemin (chaîne).

Depuis : 1.15 (RDG) Voir aussi : singeGetDataPath

Exemple
-- Framework.singe tire DIR ainsi ; les jeux chargent ensuite relativement à lui.
DIR = singeGetScriptPath():match("(.*[/\\])") or "./"
titleSprite = spriteLoad(DIR .. "images/title.png")

2.36.18. singeGetSystemInfo

info = singeGetSystemInfo()

Tout ce que l’en-tête de la trace sait de cette machine et de cette exécution, dans une seule table. Elle est destinée à un écran de service et aux rapports de bogue : la réponse à « sur quoi est-ce que ça tournait » sans demander au joueur de trouver un journal.

Renvoie : une table avec ces champs, tous des chaînes sauf les quatre tailles :

  • version — la version du moteur, comme SINGE_VERSION_STRING.

  • os — le nom et la version du système d’exploitation, et l’architecture.

  • cpu — le processeur, son nombre de cœurs et la mémoire en mégaoctets.

  • renderer — le nom du moteur de rendu 2D de SDL utilisé.

  • gpu — le pilote SDL_GPU derrière la scène 3D, ou une mention indiquant que la 3D n’est pas disponible.

  • decoder — les décodeurs vidéo matériels que cette compilation essaiera, en toutes lettres.

  • audio — les formats audio intégrés à la compilation, séparés par des virgules.

  • soundFont — la SoundFont qu’utilise la lecture MIDI, ou la raison pour laquelle il n’y en a pas.

  • midi — les ports MIDI ouverts, ou une mention indiquant qu’aucun n’a été demandé.

  • dataPath — le dossier de données de ce jeu.

  • dataRoot — le dossier de données donné au moteur, un niveau au-dessus de dataPath, sous lequel écrit chaque jeu de la machine.

  • platform — la partie plateforme du nom de publication, comme Linux-x86_64 : de quelle publication cet exécutable fait partie, et celle à demander au service.

  • executable — le chemin absolu de l’exécutable en cours.

  • windowWidth, windowHeight — des entiers, la fenêtre en pixels.

  • canvasWidth, canvasHeight — des entiers, le canevas en pixels.

Depuis : 3.00. Voir aussi : singeGetDataPath, Les outils de service

Exemple
-- Un écran de diagnostic à une touche.
local info = singeGetSystemInfo()
fontPrint(10, 10, "Singe " .. info.version .. " on " .. info.os)
fontPrint(10, 30, info.cpu)
fontPrint(10, 50, info.renderer .. " / " .. info.gpu)

2.36.19. singeGetTicks

milliseconds = singeGetTicks()

Renvoie l’horloge, en millisecondes depuis le démarrage du moteur. C’est l’horloge des minuteries, des anti-rebonds et de l’animation, et elle continue de tourner tant que le jeu est figé par la touche pause : une minuterie qui ne doit pas compter le temps de pause doit donc lire singeGetPauseFlag ou mesurer à partir du moment du dégel. Le os.clock() de Lua mesure normalement le temps processeur, qui s’arrête pendant que le moteur est inactif ; Singe le remplace par les secondes d’horloge écoulées depuis le démarrage du moteur, si bien que les jeux existants qui s’en servaient comme d’une horloge continuent de fonctionner.

Renvoie : un entier, en millisecondes.

Depuis : 3.00 Voir aussi : singeGetPauseFlag, debugPrint

Exemple
-- Faire clignoter l'invite « insert coin » deux fois par seconde.
function drawAttractPrompt()
    local phase = (singeGetTicks() // 250) % 2
    if phase == 0 then
        fontPrint(120, 200, "INSERT COIN")
    end
end

2.36.20. singeGetWidth

width = singeGetWidth()

Renvoie la largeur de la fenêtre de Singe en pixels d’écran, le pendant de singeGetHeight. Le dessin sur l’overlay utilise plutôt overlayGetWidth.

Renvoie : un entier, en pixels.

Depuis : 1.x Voir aussi : singeGetHeight, overlayGetWidth

Exemple
-- Choisir un budget de textures d'après la taille de la fenêtre.
local pixels = singeGetWidth() * singeGetHeight()
if pixels > 1920 * 1080 then
    textureSet = "high"
else
    textureSet = "low"
end

2.36.21. singeHasGpu

present = singeHasGpu()

Indique si le périphérique GPU a démarré. Tout ce qui est dessiné par lui est indisponible sans lui : la scène 3D, les particules 3D et chaque document de GUI. Les particules 2D sont dessinées avec l’overlay et n’ont besoin d’aucun périphérique. Posez cette question avant de demander l’un d’eux, car guiNew et les appels de scène mettent fin au script au lieu de répondre false — il n’y a aucun moyen d’essayer puis de se rattraper.

Une machine peut en être dépourvue parce qu’elle n’a aucun pilote Vulkan, Direct3D 12 ou Metal, ou parce que --nogpu a été donné. Le menu inclus l’appelle au démarrage et choisit un moteur de rendu d’après la réponse (voir Les deux moteurs de rendu).

Renvoie : booléen, vrai quand un périphérique GPU est présent.

Exemple
-- Un jeu avec un écran titre en 3D et un écran plat sur lequel se rabattre.
if singeHasGpu() then
    buildSceneTitle()
else
    buildSpriteTitle()
end

2.36.22. singeIsRecording

recording = singeIsRecording()

Indique si un enregistrement est en cours, ou s’il a été demandé et commence avec la prochaine image dessinée. Voir singeRecordStart.

Renvoie : booléen.

Depuis : 3.00 Voir aussi : singeRecordStart, singeRecordStop

Exemple
-- Un point rouge dans le coin de l'écran de pause propre au jeu pendant qu'il est enregistré.
if singeIsRecording() then
    overlayCircle(overlayGetWidth() - 12, 12, 5)
end

2.36.23. singePack

result = singePack(directory, database)

Empaquette le jeu de directory dans la base de données en un seul fichier database, exactement comme le fait singe --pack en ligne de commande, et renvoie true quand cela a réussi. Le dossier doit être le dossier propre d’un jeu : un dossier qui ne contient ni dossier de support Singe/, ni lanceur, ni rien d’autre que l’empaqueteur refuse, et les raisons d’un refus sont affichées dans la console comme pour la ligne de commande. C’est ce qui permet à un outil de création de publier un jeu sans quitter le moteur.

Paramètres :

  • directory — le dossier du jeu, tel que le prend l’empaqueteur.

  • database — le fichier .game à écrire, remplacé s’il existe.

Renvoie : true en cas de réussite, false sinon.

Depuis : 3.00 Voir aussi : Jeux en un seul fichier

Exemple
-- Publier le jeu à côté de son dossier et le signaler.
if singePack(singeGetDataPath() .. "CoinRun", singeGetDataPath() .. "CoinRun.game") then
    debugPrint("packed")
end

2.36.24. singeQuit

singeQuit()

Met fin au script en cours à la fin de cette image : la boucle de jeu s’arrête, onShutdown s’exécute, et le moteur passe au script suivant dans la file ou se ferme quand il n’y en a pas. Un jeu lancé depuis le menu avec scriptPush revient donc au menu, qui redémarre du début. Dans le modèle à fil d’exécution, revenir de singeMain l’appelle pour vous. Le contact affecté à INPUT_QUIT dans controls.cfg et la fermeture de la fenêtre mettent fin au script de la même façon. Ne l’appelez pas depuis onShutdown, qui est déjà le chemin de sortie.

Depuis : 1.x (RDG) Voir aussi : onShutdown, singeReload, scriptPush

Exemple
function onInputPressed(what)
    if what == SWITCH_QUIT then
        singeQuit()
    elseif what == SWITCH_START1 and gameOver then
        startGame()
    end
end

2.36.25. singeRelaunch

result = singeRelaunch(path)

Arrête le moteur comme le fait singeQuit et, une fois que tout a été démonté, démarre l’exécutable situé à path à la place de celui-ci avec les mêmes arguments. C’est ainsi que l’outil Engine Update du menu fait passer une borne à un Singe plus récent qu’il a placé à côté de celui qui tourne : le nouveau fichier est rendu exécutable et démarré, et sous Windows, qui ne remplace pas un exécutable en cours d’exécution, il est démarré à côté de celui-ci sous son propre nom. Le fichier doit déjà exister ; quand ce n’est pas le cas, l’appel répond false sans rien faire. Rien n’est décompressé ni copié ici : le nouveau Singe décompresse ses propres fichiers de support à son premier lancement.

Quand path n’est pas l’exécutable en cours, celui-ci est mis de côté à côté de lui-même sous le nom old-<name> juste avant le démarrage du nouveau, un nom qu’aucun lanceur ne cherche. Si le nouveau ne peut pas démarrer, l’ancien reprend son nom et le fichier qui n’a pas voulu démarrer est renommé failed-<name>, de sorte que le lanceur trouve toujours un Singe qui fonctionne.

Paramètres :

  • path — l’exécutable à démarrer.

Renvoie : true quand la relance a été préparée, false quand le fichier n’est pas là.

Depuis : 3.00 Voir aussi : singeQuit, singeGetSystemInfo

Exemple
-- Un Singe plus récent a été téléchargé et vérifié ;  lui passer la main.
local folder = singeGetSystemInfo().executable:match("^(.*[/\\])")
singeRelaunch(folder .. "Singe-v3.01-Linux-x86_64")

2.36.26. singeRecordStart

singeRecordStart([name])

Commence à enregistrer le jeu, image et son ensemble, dans un MP4 placé dans le dossier de données du jeu (voir singeGetDataPath), à partir de la prochaine image dessinée. Sans nom, les fichiers sont nommés à partir de singe000.mp4 en montant, comme les captures d’écran ; avec un nom, l’enregistrement va dans ce fichier, .mp4 étant ajouté quand le nom n’a pas d’extension, en remplaçant tout fichier de ce nom, et un nom qui contient un dossier met fin au script. Un appel pendant qu’un enregistrement est en cours est ignoré. Le contact affecté à INPUT_RECORD dans controls.cfg, F10 par défaut, démarre et arrête les mêmes enregistrements.

L’image est la fenêtre entière telle qu’elle est affichée, bandes noires comprises, à la taille de la fenêtre, exactement ce que prend une capture d’écran ; le son est le mixage final, musique, effets et bandes-son des vidéos ensemble. Les deux sont encodés sur un fil d’exécution à eux, si bien que le jeu paie la recopie de chaque image depuis le GPU et peu de chose d’autre. L’image est en H.264 là où la machine a un encodeur matériel que Singe peut utiliser — VA-API sous Linux, VideoToolbox sous macOS, Media Foundation sous Windows, V4L2 sur les cartes ARM qui en ont un — et en MPEG-4 avec l’encodeur propre de FFmpeg partout ailleurs ; le son est en AAC. La trace nomme l’encodeur quand l’enregistrement démarre, et compte les images perdues quand il s’arrête.

En jeu, l’enregistrement tourne à 60 images par seconde sur l’horloge réelle. Une image qui arrive alors que l’encodeur est encore occupé est retirée de l’enregistrement plutôt que de faire attendre le jeu, et le son est décalé plus tard de la durée de la file du périphérique audio, si bien que les deux concordent comme à l’écran. Sous --deterministic, l’enregistrement tourne plutôt à une image par pas d’horloge, et le moteur attend l’encodeur au lieu de perdre quoi que ce soit ; lancée par --record, une exécution déterministe mixe aussi son son en mémoire un pas à la fois, si bien que l’enregistrement est exact image par image et échantillon par échantillon.

Paramètres :

  • name — chaîne facultative ; un nom de fichier, pas un chemin.

Renvoie : rien.

Exemple
-- Le mode attraction enregistre sa propre bande-annonce :  une boucle, puis arrêt.
function attractBegin()
    singeRecordStart("trailer")
end

function attractEnd()
    singeRecordStop()
end

2.36.27. singeRecordStop

singeRecordStop()

Termine l’enregistrement à la prochaine image dessinée : ce qui attend encore est encodé et le fichier est fermé, si bien qu’il se lit du début à la fin. Ignoré quand rien n’est en cours d’enregistrement. Un enregistrement encore en cours quand le jeu se termine est terminé de la même façon.

Renvoie : rien.

Depuis : 3.00 Voir aussi : singeRecordStart, singeIsRecording

Exemple
-- Enregistrer une partie :  de la première pièce à la fin de partie.
function onGameOver()
    singeRecordStop()
end

2.36.28. singeReload

singeReload()

Relance le jeu depuis son script à la fin de cette image, comme le font F5 et un fichier modifié sous --reload ; cet appel fonctionne sans l’option. Tous les sons s’arrêtent, l’état Lua est jeté sans appeler onShutdown, tout ce que le script a chargé est libéré, la scène, la physique (son dessin de débogage compris), les particules et la navigation sont réinitialisées, l’overlay revient à sa résolution par défaut, et le volume des effets sonores, le mode souris, la capture de la souris, le mode clavier, la touche pause, l’auditeur sonore et l’indicateur de pause reviennent à leurs valeurs par défaut. Les touches et boutons maintenus pendant le rechargement sont ignorés jusqu’à ce qu’ils soient relâchés, comme à un démarrage à neuf, et le disque est garé sur sa première image, en pause, avec la piste audio par défaut sélectionnée, comme au démarrage. Le moteur lui-même (la fenêtre, les manettes, les souris) reste tel quel. Il convient à l’entrée « redémarrer » d’un menu de débogage ou à un éditeur de niveaux qui recharge ce qu’il vient de sauvegarder.

Depuis : 3.00. Voir aussi : singeQuit

Exemple
-- Éditeur : sauvegarder le niveau, puis relancer le jeu dessus.
function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.F9.value then
        saveLevel(singeGetDataPath() .. "level.lua")
        singeReload()
    end
end

2.36.29. singeSaveGeometry

singeSaveGeometry()

Garde pour cette machine l’échelle, le décalage et la rotation actuels de l’image. Ils vont dans machine.cfg à la racine des données, à côté du retard audio, et le moteur les applique à chaque jeu qu’il démarre ensuite, depuis le menu ou depuis la ligne de commande, et à travers singeReload. Une option réellement tapée sur la ligne de commande l’emporte : --scalefactor remplace l’échelle sauvegardée, --shiftx ou --shifty le décalage sauvegardé, --rotate la rotation sauvegardée. Le fichier est écrit en entier : le retard audio est donc gardé tel qu’il est.

C’est un réglage de la borne, pas d’un jeu : c’est ainsi qu’on cale un moniteur une fois pour toutes plutôt qu’une fois par jeu. L’outil Display du menu inclus n’est rien d’autre que cet appel derrière le bouton 1.

Renvoie : rien.

Exemple
-- L'exploitant est content de l'image :  la garder pour la borne.
function onInputPressed(input)
    if input == SWITCH_BUTTON1 then
        singeSaveGeometry()
    end
end

2.36.30. singeSaveTier

singeSaveTier(tier)

Garde la classe de performances de cette machine, de 0 à 3, dans machine.cfg à côté du retard audio et de la géométrie, où singeCapabilities la rapporte et où le menu la compare au TIER de chaque jeu. Le menu inclus mesure lui-même le niveau, d’après le temps que met son décor de fond 3D à se dessiner (sceneMeasure), et ne le sauvegarde que quand il change ; rien ne le demande au joueur.

Renvoie : rien.

Depuis : 3.00. Voir aussi : singeCapabilities, singeSaveGeometry

Exemple
-- Une machine sans aucune 3D est de niveau 0.
if not singeHasGpu() then
	singeSaveTier(0)
end

2.36.31. singeScreenshot

singeScreenshot()
singeScreenshot(name)

Demande une capture d’écran de la fenêtre entière, bandes noires comprises, prise après que la prochaine image a été dessinée et sauvegardée en PNG dans le dossier de données du jeu (voir singeGetDataPath). Sans nom, les fichiers sont nommés à partir de singe000.png en montant ; chaque exécution du script cherche depuis zéro le premier nom libre, et les captures suivantes continuent après la dernière sauvegardée. Avec un nom, la capture va dans ce fichier, .png étant ajouté quand le nom n’a pas d’extension, en remplaçant tout fichier de ce nom ; un nom qui contient un dossier met fin au script. Nommer la capture sert aux scripts qui produisent des images exprès, comme ceux qui illustrent les tutoriels d’un livre : une nouvelle exécution remplace alors l’image au lieu d’en ajouter une. L’appel force un redessin pour que la capture soit prise même quand l’affichage est au repos. Le contact affecté à INPUT_SCREENSHOT dans controls.cfg fait la même chose.

Depuis : 1.x Voir aussi : singeGetDataPath

Exemple
-- Un script de test capture quelques images en survolant la scène.
function onOverlayUpdate()
    frames = frames + 1
    if frames == 40 or frames == 85 or frames == 130 then
        singeScreenshot()
    end
    if frames == 180 then
        singeQuit()
    end
end

2.36.32. singeSetAudioCalibration

singeSetAudioCalibration(milliseconds)

Règle le retard audio propre à la machine, l’applique aussitôt et l’écrit dans machine.cfg à la racine des données pour que chaque jeu de la machine le prenne en compte. L’écran de calibrage du menu l’appelle ; un jeu qui a son propre menu de service peut aussi le faire. La valeur est positive quand l’audio est entendu plus tard que ne l’indique le périphérique ; le moteur retarde d’autant la présentation de la vidéo. Les valeurs hors de -1000 à 1000 mettent fin au script. Si machine.cfg ne peut pas être écrit, la valeur s’applique quand même pour cette exécution et un message part sur la console.

Paramètres :

  • milliseconds — entier, de -1000 à 1000, positif quand l’audio est en retard.

Depuis : 3.00 Voir aussi : singeGetAudioCalibration, singeSetAudioDelay

Exemple
-- Menu.singe : garder ou abandonner le calibrage que le joueur a réglé.
function calibrationEnd(save)
    if save then
        singeSetAudioCalibration(CAL_VALUE)
    end
    CALIBRATING = false
end

2.36.33. singeSetAudioDelay

singeSetAudioDelay(milliseconds)

Règle le retard audio propre au jeu pour cette exécution : de combien l’audio est entendu plus tard (positif) ou plus tôt (négatif) que ce que le moteur peut mesurer, pour que la présentation de la vidéo se décale en conséquence. Il s’applique au disque et à chaque vidéo que lit le script, en plus du calibrage de la machine. Rien n’est sauvegardé ; un jeu qui propose ce réglage dans un menu de service range la valeur avec ses autres réglages et rappelle cette fonction au démarrage. Les valeurs hors de -1000 à 1000 mettent fin au script.

Paramètres :

  • milliseconds — entier, de -1000 à 1000, positif quand l’audio est en retard.

Depuis : 3.00 Voir aussi : singeGetAudioDelay, singeSetAudioCalibration

Exemple
-- Menu de service : ajuster un peu le décalage et le retenir.
function onInputPressed(what)
    if what == SWITCH_LEFT then
        settings.audioDelay = math.max(-1000, settings.audioDelay - 10)
    elseif what == SWITCH_RIGHT then
        settings.audioDelay = math.min(1000, settings.audioDelay + 10)
    end
    singeSetAudioDelay(settings.audioDelay)
    saveSettings()
end

2.36.34. singeSetGameName

singeSetGameName(title)

Règle le titre de la fenêtre de Singe. Appelez-la une fois au démarrage avec le nom d’affichage du jeu ; rien d’autre n’utilise cette valeur. L’argument doit être une chaîne ou un nombre.

Paramètres :

  • title — le titre de la fenêtre.

Depuis : 1.15 (RDG) Voir aussi : singeVersion

Exemple
singeSetGameName("Asteroid Patrol")
keyboardSetMode(MODE_NORMAL)
hudFont = fontLoad(DIR .. "fonts/FreeSansBold.ttf", 18)

2.36.35. singeSetPauseFlag

singeSetPauseFlag(paused)

Règle l’indicateur de pause du moteur depuis le script. true met en pause le disque s’il est en lecture, chaque vidéo chargée et chaque canal d’effets sonores, en retenant lesquels tournaient ; false reprend exactement ceux-là. Contrairement à la touche pause, cela ne fige pas le script : les callbacks continuent d’être appelés pour que le script puisse dessiner son menu de pause et décider quand effacer l’indicateur. Les jeux qui gèrent leur propre pause devraient aussi prendre la touche pause avec singeSetPauseKeyEnabled(false), car la touche du moteur bascule le même indicateur et lutterait sinon contre le script. Un argument qui n’est pas un booléen met fin au script.

Paramètres :

  • paused — booléen.

Depuis : 1.x (RDG) Voir aussi : singeGetPauseFlag, singeSetPauseKeyEnabled

Exemple
singeSetPauseKeyEnabled(false)

function onInputPressed(what)
    if what == SWITCH_PAUSE then
        menuOpen = not menuOpen
        singeSetPauseFlag(menuOpen)
    elseif menuOpen and what == SWITCH_QUIT then
        singeQuit()
    end
end

2.36.36. singeSetPauseKeyEnabled

singeSetPauseKeyEnabled(enabled)

Choisit à qui appartient la touche pause affectée à INPUT_PAUSE dans controls.cfg. Quand elle est activée (par défaut, et rétablie à chaque rechargement), elle appartient au moteur : appuyer sur la touche fige complètement le jeu (voir La pause), et en MODE_NORMAL le script ne reçoit jamais SWITCH_PAUSE. Quand elle est désactivée, le moteur ignore la touche et SWITCH_PAUSE arrive à onInputPressed et onInputReleased comme n’importe quel autre contact, si bien que le jeu peut gérer sa propre pause avec singeSetPauseFlag. Un argument qui n’est pas un booléen met fin au script.

Paramètres :

  • enabled — booléen.

Exemple
-- Le moteur peut mettre en pause pendant la partie, mais pas pendant que le joueur saisit ses initiales.
function beginInitials()
    singeSetPauseKeyEnabled(false)
    keyboardSetMode(MODE_FULL)
end

function endInitials()
    keyboardSetMode(MODE_NORMAL)
    singeSetPauseKeyEnabled(true)
end

2.36.37. singeSetQuitKeyEnabled

singeSetQuitKeyEnabled(enabled)

Extension Hypseus. Choisit si le moteur quitte sur le contact affecté à INPUT_QUIT dans controls.cfg, depuis le clavier ou une manette. Quand c’est activé (par défaut, et rétabli à chaque rechargement), appuyer dessus termine le jeu. Quand c’est désactivé, le moteur l’ignore, si bien qu’un jeu peut d’abord demander confirmation ou sauvegarder ; le script reçoit SWITCH_QUIT par onInputPressed et onInputReleased dans les deux cas, et singeQuit termine toujours le jeu. Le bouton de fermeture de la fenêtre quitte toujours. Framework.singe définit keyboardCatchQuit(catch), le nom que donne Hypseus Singe au même réglage, avec le sens inverse. Un argument qui n’est pas un booléen met fin au script.

Paramètres :

  • enabled — booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : keyboardCatchQuit, singeSetPauseKeyEnabled, singeQuit

Exemple
-- Demander avant de quitter une partie en cours.
singeSetQuitKeyEnabled(false)

function onInputPressed(what)
    if what == SWITCH_QUIT then
        if confirmQuit() then
            singeQuit()
        end
    end
end

2.36.38. singeVersion

version = singeVersion()

Renvoie la version du moteur sous forme de nombre, le numéro majeur plus le mineur en fraction : 3.00 revient donc comme 3. Comparez-la avec < et >= pour refuser un moteur trop ancien ou pour contourner des fonctionnalités ; SINGE_VERSION_MAJOR, SINGE_VERSION_MINOR et SINGE_VERSION_STRING sont aussi définies comme globales pour les scripts qui veulent les parties ou le texte.

Renvoie : nombre.

Depuis : 1.x (RDG) Voir aussi : singeSetGameName

Exemple
if singeVersion() < 3 then
    error("This game needs Singe 3.00 or newer, found " .. SINGE_VERSION_STRING)
end

2.36.39. singeWantsCrosshairs

wanted = singeWantsCrosshairs()

Renvoie true sauf si Singe a été démarré avec --nocrosshair. Ne dessinez le réticule de visée logiciel que quand elle renvoie true ; les joueurs dont les pistolets optiques affichent leur propre réticule à l’écran désactivent le réticule logiciel avec cette option. La valeur ne change pas pendant une exécution : lisez-la donc une seule fois.

Renvoie : booléen.

Depuis : 2.00 Voir aussi : mouseGetPosition, onMouseMoved

Exemple
drawCrosshair = singeWantsCrosshairs()

function onOverlayUpdate()
    overlayClear()
    drawTargets()
    if drawCrosshair then
        spriteDraw(reticle, cursorX, cursorY, true)
    end
    return OVERLAY_UPDATED
end

2.37. Corps mou

Tissus, corps à pression et cordes : des maillages dont les sommets sont simulés comme des particules (voir Physique, Corps mous). Un corps mou est désigné par son nœud, et un nœud qui n’en a pas met fin au script dans chaque appel qui suit softNew. Les positions sont en unités du monde, la masse en kilogrammes, et les valeurs de raideur vont de 0 à 1. Le moteur réécrit le maillage du nœud à partir des particules après chaque pas, et la simulation se termine d’elle-même quand le nœud est supprimé ou reçoit un autre maillage. Jusqu’à 16 corps mous à la fois, avec jusqu’à 32 épingles chacun.

2.37.1. softNew

softNew(node, SOFT_CLOTH)
softNew(node, SOFT_BODY)
softNew(node, SOFT_ROPE, x, y, z, segments, radius)

Pour SOFT_CLOTH et SOFT_BODY, le maillage du nœud, de trois sommets ou plus, devient les particules : les sommets à la même position (à 0.0001 unité près) sont soudés en un seul, placés là où la transformation du nœud les met dans le monde, et les triangles donnent les contraintes d’étirement, de cisaillement et de flexion. Un tissu entre en collision par ses deux faces et convient à une feuille ouverte ; un corps est un maillage fermé que softSetPressure peut gonfler. Pour SOFT_ROPE, le nœud n’a besoin d’aucun maillage : segments + 1 particules s’alignent de la position du nœud dans le monde jusqu’au point du monde donné, le nœud reçoit un nouveau maillage de tube à six pans de ce rayon autour d’elles (en gardant le matériau qu’il avait), et les particules entrent en collision comme des sphères de ce rayon, alors que les particules de tissu et de corps sont des sphères de rayon 0.03. Chaque type commence avec un étirement de 0.9, une flexion de 0.2, une masse de 1 kilogramme, un amortissement de 0.1 et une pression de 0. Un corps mou déjà présent sur le nœud est retiré avant que le nouveau soit créé : un appel qui échoue laisse donc le nœud sans aucun ; le maillage de tube d’une corde s’en va avec lui, ce qui explique pourquoi le nœud d’une corde ne peut pas devenir un tissu ou un corps (l’appel échoue faute de maillage). Met fin au script quand la physique n’est pas disponible, que le type est inconnu, que le nombre d’arguments ne correspond pas au type, que le maillage manque, qu’une corde n’a pas de segments ou pas de rayon, ou que 16 corps mous existent déjà.

Paramètres :

  • node — le nœud qui porte le maillage (tissu, corps), ou le point de départ de la corde.

  • x, y, z — l’autre bout de la corde, en unités du monde.

  • segments — le nombre de maillons de la corde, 1 ou plus ; une douzaine suffit largement.

  • radius — le rayon de la corde, en unités du monde ; c’est aussi la taille avec laquelle ses particules entrent en collision.

Remarques : Un maillage partagé par plusieurs nœuds est réécrit pour tous : donnez donc à un corps mou un maillage à lui. Les maillages skinnés ne peuvent pas être mous.

Depuis : 3.00. Voir aussi : softPin, softSetStiffness, softSetPressure, meshPlane

Exemple
-- Un drapeau accroché au mât :  une grille dressée, épinglée tout le long de son bord gauche.
local flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), cloth)
nodeSetPosition(flag, -4.16, 2.4, 0)
nodeSetRotation(flag, 90, 0, 0)
softNew(flag, SOFT_CLOTH)
softSetStiffness(flag, 0.95, 0.1)
softSetMass(flag, 0.5)
for _, y in ipairs({ 1.9, 2.15, 2.4, 2.65, 2.9 }) do
    softPin(flag, -4.96, y, 0)                -- Le long du mât
end

2.37.2. softDelete

softDelete(node)

Termine la simulation et libère son corps. Le nœud garde son maillage dans la forme où il a été écrit en dernier : un drap tombé reste drapé sur la caisse et une corde garde son tube ; la forme d’origine du maillage n’est pas rétablie. Un nœud sans corps mou met fin au script.

Depuis : 3.00. Voir aussi : softNew, nodeDelete

Exemple
-- Une fois que le drap s'est posé sur la statue, le figer et cesser d'en payer le coût.
function onOverlayUpdate()
    if covering then
        settleFrames = settleFrames + 1
        if settleFrames > 240 then
            softDelete(sheet)                 -- Le drapé reste tel quel
            covering = false
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.37.3. softPin

softPin(node, x, y, z)
softPin(node, x, y, z, otherNode)

Trouve la particule la plus proche du point du monde, où que se trouvent les particules à cet instant, et la fixe. Seule, la particule est maintenue là où elle est ; avec otherNode, elle est déplacée à la position de ce nœud dans le monde avant chaque pas, si bien qu’une corde pend d’une grue qui pivote et qu’une cape suit les épaules. Le point n’a pas besoin d’être sur le maillage, puisque c’est la particule la plus proche qui l’emporte, et épingler de nouveau la même particule ne change que ce qu’elle suit. Au-delà de 32 épingles, l’appel ne fait rien.

Paramètres :

  • node — le nœud du corps mou.

  • x, y, z — un point du monde ; la particule la plus proche est épinglée.

  • otherNode — un nœud que la particule suivra désormais.

Depuis : 3.00. Voir aussi : softUnpin, softNew, nodeGetWorldPosition

Exemple
-- Une corde qui part du crochet de la grue et descend, en se balançant avec la grue.
local crane = nodeNew()
nodeSetPosition(crane, 4, 4, -1)
local rope = nodeNew()
nodeSetPosition(rope, 4, 4, -1)
softNew(rope, SOFT_ROPE, 6.5, 4, -1, 16, 0.04)
nodeSetMaterial(rope, hemp)
softSetMass(rope, 1.5)
softPin(rope, 4, 4, -1, crane)               -- Le bout du haut suit le crochet

2.37.4. softUnpin

softUnpin(node, x, y, z)

Libère la particule épinglée la plus proche du point du monde. Rien ne se passe quand cette particule n’est pas épinglée. Le corps est refait autour de la forme actuelle, ce qui arrête aussi net chaque particule : un drapeau qu’on lâche commence donc à tomber depuis le repos.

Depuis : 3.00. Voir aussi : softPin

Exemple
-- Le coin de la bannière se déchire et se libère quand la rafale frappe.
function onOverlayUpdate()
    gustFrames = gustFrames + 1
    if gustFrames == 200 then
        softUnpin(banner, 3.0, 4.5, 0)
        soundPlay(ripSound)
    end
    return OVERLAY_NOT_UPDATED
end

2.37.5. softSetStiffness

softSetStiffness(node, stretch, bend)

À quel point le matériau résiste à l’étirement (et, pour un tissu, au cisaillement) et au pliage, de 0 à 1 ; les valeurs hors plage sont ramenées dans la plage. 1 est rigide, 0 le plus lâche que permet le solveur. Par défaut 0.9 et 0.2. Le corps est refait autour de la forme actuelle : les longueurs au repos deviennent les longueurs de cet instant, et chaque particule s’arrête ; réglez donc le matériau avant que le tissu commence à bouger. Une corde n’a que l’étirement.

Paramètres :

  • node — le nœud du corps mou.

  • stretch — la résistance à l’étirement, de 0 à 1 ; 0.9 par défaut.

  • bend — la résistance au pliage, de 0 à 1 ; 0.2 par défaut.

Depuis : 3.00. Voir aussi : softSetMass, softSetDamping

Exemple
-- De la soie, de la toile et une feuille de caoutchouc tirées de la même grille.
local silk = clothNode(silkMaterial)
softNew(silk, SOFT_CLOTH)
softSetStiffness(silk, 0.7, 0.02)
local canvas = clothNode(canvasMaterial)
softNew(canvas, SOFT_CLOTH)
softSetStiffness(canvas, 1.0, 0.4)
local rubber = clothNode(rubberMaterial)
softNew(rubber, SOFT_CLOTH)
softSetStiffness(rubber, 0.3, 0.1)

2.37.6. softSetPressure

softSetPressure(node, pressure)

Gonfle un SOFT_BODY : 0 (par défaut) donne un sac dégonflé, et quelques unités un ballon bien ferme ; une valeur négative devient 0. Elle modifie le corps en cours de simulation sans le refaire et le réveille, si bien qu’un ballon peut être gonflé ou dégonflé pendant qu’il rebondit. Les tissus et les cordes n’ont pas de volume à gonfler.

Depuis : 3.00. Voir aussi : softNew, softSetStiffness, meshSphere

Exemple
softNew(balloon, SOFT_BODY)                  -- Un meshSphere de 0.5
softSetMass(balloon, 0.6)
softSetPressure(balloon, 8)                  -- Un ballon bien ferme

function onOverlayUpdate()
    if punctured then
        pressure = math.max(pressure - 0.1, 0)
        softSetPressure(balloon, pressure)   -- Se dégonfle en sifflant en deux ou trois secondes
    end
    return OVERLAY_NOT_UPDATED
end

2.37.7. softSetMass

softSetMass(node, kilograms)

La masse du corps entier, répartie également entre ses particules ; 1 par défaut, maintenue à 0.001 ou plus. Les particules épinglées ne pèsent rien quoi qu’il en soit. Le corps est refait autour de la forme actuelle et chaque particule s’arrête : réglez-la donc dès le départ.

Depuis : 3.00. Voir aussi : softSetStiffness, softSetDamping

Exemple
-- Un drap épinglé par ses quatre coins rattrape une caisse qu'on laisse tomber dessus.
local sheet = nodeNew()
nodeSetMesh(sheet, meshPlane(3, 3, 20, 20), linen)
nodeSetPosition(sheet, 0, 1.6, 0)
softNew(sheet, SOFT_CLOTH)
softSetStiffness(sheet, 1.0, 0.05)
softSetMass(sheet, 4)                        -- Assez lourd pour ne pas voleter
for _, c in ipairs({ { -1.5, -1.5 }, { 1.5, -1.5 }, { -1.5, 1.5 }, { 1.5, 1.5 } }) do
    softPin(sheet, c[1], 1.6, c[2])
end

2.37.8. softSetDamping

softSetDamping(node, damping)

À quelle vitesse le mouvement des particules s’éteint, de 0 en montant ; 0.1 par défaut, et une valeur négative devient 0. Des valeurs plus élevées calment un drapeau qui n’arrête pas d’onduler ou une corde qui se balance sans fin. Le corps est refait autour de la forme actuelle et chaque particule s’arrête.

Depuis : 3.00. Voir aussi : softSetMass, softSetStiffness

Exemple
-- Un rideau dans l'air immobile se calme vite ; le même rideau près de la fenêtre ouverte continue de bouger.
local curtain = nodeNew()
nodeSetMesh(curtain, meshPlane(1.2, 2.4, 12, 24), velvet)
nodeSetPosition(curtain, 2, 2.4, -3)
nodeSetRotation(curtain, 90, 0, 0)
softNew(curtain, SOFT_CLOTH)
softSetDamping(curtain, windowOpen and 0.05 or 0.4)
for x = -0.6, 0.6, 0.1 do
    softPin(curtain, 2 + x, 3.6, -3)
end

2.38. Son

Les effets sonores sont des clips audio (le WAV est le choix sûr) chargés en mémoire et mélangés par SDL_mixer, à part de l’audio du disque lui-même et de l’audio des ressources video*. soundLoad renvoie un handle de son qui identifie les données du clip ; soundPlay démarre ce clip sur l’un des seize canaux du mélangeur et renvoie le numéro du canal, de 0 à 15, que prennent soundPause, soundResume, soundStop, soundIsPlaying et chaque appel soundSet*. Un même clip peut jouer sur plusieurs canaux à la fois, et un numéro de canal est réutilisé dès que le canal est libre : ne confondez donc pas les deux sortes de numéros. Un volume général des effets (soundSetVolume, de 0 à 63) met chaque canal à l’échelle. Un canal en cours de lecture peut aussi se trouver dans la scène 3D, en suivant un nœud ou fixé en un point en unités du monde, où il est réparti en stéréo et atténué selon sa distance à l’auditeur (voir Scènes 3D) ; pour les jeux en 2D, soundSetPan répartit un canal sans scène.

2.38.1. soundFullStop

soundFullStop()

Arrête d’un coup tous les canaux d’effets, y compris ceux en pause, et les libère pour qu’ils soient réutilisés. Aucun clip n’est déchargé ; les handles de soundLoad restent valides. Chaque canal qui jouait ou était en pause le signale par onSoundCompleted, exactement comme après soundStop. Appelez-la lors d’un changement de scène ou avant une cinématique plutôt que de suivre chaque canal que vous avez démarré.

Depuis : 1.16 Voir aussi : soundStop, onSoundCompleted

Exemple
function enterAttractMode()
    soundFullStop()
    ambientChannel = -1
    engineChannel  = -1
    discPlay()
end

2.38.2. soundGetPosition

x, y, z, gain = soundGetPosition(channel)

Indique où se trouve un canal placé par rapport à l’auditeur, sous forme d’une direction de longueur unité dans le repère de l’auditeur (x positif vers la droite, y positif vers le haut, z positif derrière l’auditeur), et le facteur de volume que lui donne actuellement sa distance, de 0 à 1. Les valeurs sont rafraîchies une fois par image à partir de l’auditeur et du nœud ou du point du canal. Un canal qui n’a pas été placé dans la scène depuis son démarrage renvoie 0, 0, 0, 1. Destiné aux indicateurs façon radar et à la vérification d’un mixage depuis un script de test ; un canal hors de 0 à 15 met fin au script.

Renvoie : trois nombres pour la direction et un pour le gain dû à la distance.

Depuis : 3.00. Voir aussi : soundSetNode, soundSetPosition, soundSetRange

Exemple
-- Pointer une flèche du HUD vers l'ennemi audible le plus proche.
function onOverlayUpdate()
    overlayClear()
    local x, y, z, gain = soundGetPosition(growlChannel)
    if gain > 0 then
        local angle = math.atan(x, -z)
        drawThreatArrow(angle, gain)
    end
    return OVERLAY_UPDATED
end

2.38.3. soundGetVolume

volume = soundGetVolume()

Renvoie le volume général des effets, de 0 à 63. Au démarrage, il reflète le volume des effets donné en ligne de commande : un jeu qui affiche un réglage de volume doit donc le lire plutôt que de supposer le maximum.

Renvoie : entier, de 0 à 63.

Depuis : 1.16 Voir aussi : soundSetVolume

Exemple
-- Baisser les effets pendant que le narrateur parle, puis les remettre.
function narratorBegin()
    savedVolume = soundGetVolume()
    soundSetVolume(math.floor(savedVolume / 3))
    narratorChannel = soundPlay(narratorClip)
end

2.38.4. soundIsPlaying

playing = soundIsPlaying(channel)

Teste si un canal joue en ce moment. Un canal en pause répond false, tout comme un canal dont le clip est terminé. Un canal hors de 0 à 15 met fin au script ; un canal simplement devenu silencieux, non.

Renvoie : booléen.

Depuis : 1.16 (RDG) Voir aussi : soundPlay, soundPause

Exemple
-- Ne pas relancer l'alarme tant qu'elle sonne encore.
function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

2.38.5. soundLoad

id = soundLoad(filename)

Charge un clip audio en mémoire et renvoie son handle. Le chemin passe par le système de fichiers virtuel du jeu : il fonctionne donc de la même façon depuis un dossier ordinaire et depuis un jeu empaqueté. Chargez les clips une fois au démarrage, pas dans un callback appelé à chaque image. Un fichier qui ne peut pas être ouvert ou décodé met fin au script.

Renvoie : handle de son entier. C’est un handle de données, pas un numéro de canal.

Depuis : 1.x Voir aussi : soundPlay, soundUnload

Exemple
-- Des handles de clips, chargés une fois et déchargés dans onShutdown.
shotClip    = soundLoad(DIR .. "sounds/shot.wav")
missClip    = soundLoad(DIR .. "sounds/miss.wav")
coinClip    = soundLoad(DIR .. "sounds/coin.wav")
ambientClip = soundLoad(DIR .. "sounds/wind.wav")

2.38.6. soundLoadData

id = soundLoadData(data)

Extension Hypseus. Construit un son à partir d’octets contenus dans une chaîne Lua au lieu d’un fichier. Tous les formats que lit soundLoad sont lus ici, et le handle renvoyé s’utilise avec le reste de la famille sound exactement de la même façon.

La chaîne peut contenir des octets nuls ; c’est sa longueur, et non son premier zéro, qui décide de ce qui est lu. Les octets sont décodés pendant l’appel et la chaîne n’est pas conservée : elle peut donc être jetée ensuite. Des octets qui ne sont pas de l’audio, ou une chaîne vide, mettent fin au script, comme un fichier illisible dans soundLoad.

Servez-vous-en pour l’audio qu’un jeu génère, décompresse ou déchiffre lui-même. L’audio que le système de fichiers virtuel peut atteindre par son nom — y compris l’audio contenu dans un .game empaqueté — se charge mieux avec soundLoad, qui ne garde pas le fichier entier dans une chaîne Lua.

Paramètres :

  • data — chaîne d’octets.

Renvoie : nombre, le handle du son.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : soundLoad, spriteLoadData, soundPlay

Exemple
-- Un effet sonore que le jeu extrait de sa propre archive.
local bytes = myArchive:extract("beep.wav")
local beep  = soundLoadData(bytes)
soundPlay(beep)

2.38.7. soundPause

wasPlaying = soundPause(channel)

Met un canal en pause sur place ; soundResume le reprend au même point. Un canal en pause compte toujours comme occupé : soundPlay ne le donnera donc pas à un autre clip, et soundIsPlaying répond false pour lui. Mettre en pause un canal qui ne joue pas ne fait rien. Un canal hors de 0 à 15 met fin au script.

Renvoie : booléen, true quand le canal jouait au moment de l’appel.

Depuis : 1.16 (RDG) Voir aussi : soundResume, soundIsPlaying

Exemple
-- Suspendre le bruit du moteur pendant que le message radio passe.
function radioBegin(messageClip)
    engineWasRunning = soundPause(engineChannel)
    radioChannel     = soundPlay(messageClip)
end

2.38.8. soundPlay

channel = soundPlay(id)
channel = soundPlay(id, loops)
channel = soundPlay(id, loops, volume)

Démarre un clip chargé sur le premier canal libre et renvoie le numéro de ce canal. Un canal compte comme libre quand il ne joue pas et n’est pas en pause. Le nouveau canal démarre au volume général (ou à volume en dessous), centré, sans position dans la scène et avec la portée par défaut, quoi qu’ait réglé l’usage précédent du canal. Quand les seize canaux sont occupés, rien ne joue et c’est -1 (SOUND_ERROR_INVALID) qui revient ; un jeu qui déclenche beaucoup de sons qui se chevauchent doit le vérifier. Un handle qui n’est pas chargé met fin au script.

Paramètres :

  • id — handle de son venant de soundLoad.

  • loops — 0 (par défaut) joue le clip une fois, un nombre positif le répète autant de fois en plus, -1 le fait boucler jusqu’à ce qu’il soit arrêté. Toute valeur inférieure à -1 met fin au script.

  • volume — le volume propre du canal, de 0 à 63, sous le volume général ; par défaut 63, le clip aussi fort que le permet le volume général. Une valeur hors de cette plage met fin au script. soundSetChannelVolume le change pendant que le clip joue.

Renvoie : numéro de canal entier, de 0 à 15, ou -1 quand aucun canal n’est libre.

Depuis : 1.x ; volume depuis 3.00. Voir aussi : soundLoad, soundStop, soundSetChannelVolume, soundSetNode

Exemple
function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        local channel = soundPlay(shotClip)
        if channel < 0 then
            debugPrint("All sound channels busy; shot dropped")
        end
    elseif what == SWITCH_COIN1 then
        soundPlay(coinClip)
        credits = credits + 1
    end
end

2.38.9. soundResume

wasPaused = soundResume(channel)

Reprend un canal que soundPause a arrêté, là où il s’était interrompu. Reprendre un canal qui n’est pas en pause ne fait rien. Un canal hors de 0 à 15 met fin au script.

Renvoie : booléen, true quand le canal était en pause au moment de l’appel.

Depuis : 1.16 (RDG) Voir aussi : soundPause

Exemple
function onSoundCompleted(channel)
    if channel == radioChannel then
        radioChannel = -1
        if engineWasRunning then
            soundResume(engineChannel)
        end
    end
end

2.38.10. soundSetChannelVolume

soundSetChannelVolume(channel, volume)

Règle le volume propre d’un canal, en plus du volume général de soundSetVolume : le canal joue au volume général multiplié par celui-ci, multiplié encore par son atténuation due à la distance quand il est dans la scène. Chaque canal démarre à plein quand soundPlay le prend, sauf si un volume a été donné à soundPlay : un pas discret et un coup de feu bruyant peuvent ainsi partager un même volume général. Les valeurs hors de 0 à 63 mettent fin au script, tout comme un canal hors de 0 à 15.

Paramètres :

  • channel — numéro de canal venant de soundPlay.

  • volume — entier, de 0 (muet) à 63 (aussi fort que le volume général).

Depuis : 3.00 Voir aussi : soundPlay, soundSetVolume

Exemple
-- Un moteur qui gronde plus fort avec l'accélérateur :  un clip en boucle, le volume de son canal
-- suivant la pédale à chaque image.
engine = soundPlay(engineClip, -1, 20)

function onOverlayUpdate()
    soundSetChannelVolume(engine, math.floor(20 + throttle * 43))
end

2.38.11. soundSetListener

soundSetListener(node)
soundSetListener()

Choisit le nœud depuis lequel on entend les canaux placés, tourné dans le même sens que lui. Sans argument, ou avec nil, l’auditeur est la caméra de la scène, ce qui convient à un jeu à la première personne ou à caméra fixe ; un jeu à la troisième personne préfère généralement le nœud du joueur, pour que les sons se répartissent autour du personnage plutôt que de la caméra. Un nœud supprimé plus tard fait revenir l’auditeur à la caméra. Un handle de nœud qui n’existe pas met fin au script.

Depuis : 3.00. Voir aussi : soundSetNode, soundSetPosition, cameraSet

Exemple
-- Caméra de poursuite, mais entendre le monde depuis la voiture.
local car = modelInstance(carModel)
local chaseCamera = nodeNew(car)
nodeSetPosition(chaseCamera, 0, 2, 6)
cameraSet(chaseCamera)
soundSetListener(car)

2.38.12. soundSetNode

soundSetNode(channel, node)
soundSetNode(channel)

Attache un canal en cours de lecture à un nœud de la scène pour qu’on l’entende de l’endroit où se trouve le nœud à chaque image : le canal est réparti vers la direction du nœud vue depuis l’auditeur et atténué selon sa distance d’après soundSetRange. L’appeler sans nœud, ou avec nil, ressort le canal de la scène, au plein volume général. Un canal dont le nœud est supprimé revient de lui-même à une lecture ordinaire. L’attache dure jusqu’à ce que le canal soit arrêté ou réutilisé par soundPlay. Un canal hors de 0 à 15, ou un nœud qui n’existe pas, met fin au script.

Depuis : 3.00. Voir aussi : soundSetPosition, soundSetRange, soundSetListener

Exemple
-- Chaque brasero crépite depuis l'endroit où il se trouve.
for i, brazier in ipairs(braziers) do
    local channel = soundPlay(crackleClip, -1)
    if channel >= 0 then
        soundSetNode(channel, brazier)
        soundSetRange(channel, 1.5, 14)
    end
end

2.38.13. soundSetPan

soundSetPan(channel, pan)

Répartit un canal entre les deux voies stéréo, pour les jeux sans scène : -1 est tout à gauche, 1 tout à droite, 0 au centre, et les valeurs hors de cette plage sont ramenées dans la plage. S’éloigner du centre ne baisse que le haut-parleur opposé ; à pan = 0.5, le haut-parleur gauche joue à mi-gain et le droit à plein. L’appel ressort le canal de la scène si soundSetNode ou soundSetPosition l’y avait placé. Un canal hors de 0 à 15 met fin au script.

Depuis : 3.00. Voir aussi : soundPlay, soundSetNode

Exemple
-- Répartir une voiture qui passe selon sa place sur l'overlay.
function carPassBy(x)
    local channel = soundPlay(carClip)
    if channel >= 0 then
        soundSetPan(channel, (x / overlayGetWidth()) * 2 - 1)
    end
end

2.38.14. soundSetPosition

soundSetPosition(channel, x, y, z)

Place un canal en cours de lecture en un point fixe de la scène, en unités du monde, en remplaçant tout nœud qu’il suivait. Il est ensuite réparti et atténué par rapport à l’auditeur comme un canal attaché à un nœud. Convient à un son qui ne bouge pas, comme une cascade ou un téléphone qui sonne ; une source en mouvement est plus simple avec soundSetNode. Un canal hors de 0 à 15 met fin au script.

Depuis : 3.00. Voir aussi : soundSetNode, soundSetRange, soundGetPosition

Exemple
-- La cascade ne bouge jamais : pas besoin de nœud.
waterfallChannel = soundPlay(waterfallClip, -1)
if waterfallChannel >= 0 then
    soundSetPosition(waterfallChannel, 42, 3, -18)
    soundSetRange(waterfallChannel, 6, 80)
end

2.38.15. soundSetRange

soundSetRange(channel, near, far)

Règle la façon dont un canal placé s’atténue avec la distance à l’auditeur. En deçà de near, il joue à plein volume ; au-delà, son gain est near divisé par la distance ; sur le dernier cinquième de far, il s’atténue en plus de façon linéaire, jusqu’au silence à far. Les valeurs par défaut sont 1 et 30 unités du monde, rétablies chaque fois que soundPlay réutilise le canal. Un murmure veut un petit far, une cascade un grand.

Paramètres :

  • channel — numéro de canal venant de soundPlay.

  • near — la distance en deçà de laquelle le canal est à plein volume, supérieure à 0.

  • far — la distance à laquelle il devient muet, supérieure à near. Toute autre paire met fin au script.

Depuis : 3.00. Voir aussi : soundSetNode, soundSetPosition, soundGetPosition

Exemple
-- Les pas d'un garde ne s'entendent que de près ; la sirène porte loin.
local steps = soundPlay(footstepClip, -1)
soundSetNode(steps, guard)
soundSetRange(steps, 0.5, 8)
local siren = soundPlay(sirenClip, -1)
soundSetNode(siren, tower)
soundSetRange(siren, 10, 200)

2.38.16. soundSetVolume

soundSetVolume(volume)

Règle le volume général des effets et l’applique aussitôt à chaque canal, en lecture ou en pause. Le volume propre de chaque canal donné par soundSetChannelVolume et, pour les canaux placés, l’atténuation due à la distance continuent de s’y ajouter. Les valeurs hors de 0 à 63 mettent fin au script.

Paramètres :

  • volume — entier, de 0 (muet) à 63 (le plus fort).

Depuis : 1.16 Voir aussi : soundGetVolume, soundSetChannelVolume

Exemple
-- Curseur de volume du menu de service piloté par les contacts gauche et droit.
function onInputPressed(what)
    local volume = soundGetVolume()
    if what == SWITCH_LEFT then
        soundSetVolume(math.max(0, volume - 4))
    elseif what == SWITCH_RIGHT then
        soundSetVolume(math.min(63, volume + 4))
    end
    soundPlay(clickClip)
end

2.38.17. soundStop

wasPlaying = soundStop(channel)

Arrête immédiatement un canal, qu’il soit en lecture ou en pause, et le libère pour qu’il soit réutilisé. Le canal le signale par onSoundCompleted exactement comme quand le clip se termine de lui-même : un script qui enchaîne des sons depuis ce callback doit donc vérifier s’il a arrêté le canal lui-même. Le soundPlay suivant peut redonner le même numéro : oubliez donc ce numéro côté Lua. Un canal hors de 0 à 15 met fin au script.

Renvoie : booléen, true quand le canal jouait au moment de l’appel. Un canal en pause renvoie false mais est bien arrêté.

Depuis : 1.x (RDG) Voir aussi : soundFullStop, onSoundCompleted

Exemple
function playerDied()
    if engineChannel >= 0 then
        soundStop(engineChannel)
        engineChannel = -1
    end
    soundPlay(explosionClip)
    lives = lives - 1
end

2.38.18. soundUnload

soundUnload(id)

Libère un clip chargé et invalide son handle. Le mélangeur garde les données du clip en vie jusqu’à ce que chaque canal qui le joue encore se soit arrêté : décharger ne coupe donc pas court un canal en lecture. Tout usage ultérieur du handle, y compris un autre soundUnload, met fin au script. Sa place habituelle est onShutdown.

Paramètres :

  • id — handle de son venant de soundLoad, pas un numéro de canal.

Depuis : 2.00 Voir aussi : soundLoad, onShutdown

Exemple
function onShutdown()
    soundUnload(shotClip)
    soundUnload(missClip)
    soundUnload(coinClip)
    soundUnload(ambientClip)
    fontUnload(hudFont)
end

2.39. Sprite

Les sprites sont des images bitmap 2D chargées depuis le disque avec spriteLoad, ou rendues à partir de texte avec fontToSprite, et dessinées sur l’overlay en coordonnées de l’overlay. Chaque appel sprite* prend le handle entier comme premier argument (Singe 2.10 le mettait en dernier ; voir Migrer depuis Singe 2.10), et un handle déchargé met fin au script avec une erreur. Tout format que lit SDL_image est accepté ; un GIF ou un WEBP animé de deux images ou plus se charge comme une animation qui reste sur l’image 0, arrêtée et sans boucle, jusqu’à ce que spritePlay et spriteLoop en décident autrement. La couleur 0 est dessinée transparente, comme dans Hypseus : l’indice de palette 0, ou le noir pur, y compris le noir opaque d’une image qui a un canal alpha, dont l’alpha est respecté lui aussi. Pour garder le noir opaque d’une image, chargez-la après drawTransparent(true). Libérez chaque sprite avec spriteUnload, en général depuis onShutdown.

Planches de sprites. Hypseus Singe étend la famille avec les planches de sprites : spriteLoadFrames découpe une bande d’images égales, sur une seule rangée, en une animation qui ne joue pas, et spriteDrawFrame dessine une image choisie (comptée à partir de 1) sans toucher à la lecture. Pour le reste, une planche est une animation ordinaire, si bien que spriteSetFrame (compté à partir de 0), spritePlay, spriteDraw, nodeSetSprite et emitterSetTexture l’acceptent tous, et que spriteFrameWidth et spriteFrameHeight donnent la taille d’une image avant mise à l’échelle. Les entrées marquées « Extension Hypseus » existent pour que les jeux écrits pour Hypseus Singe tournent sans modification.

2.39.1. drawTransparent

drawTransparent(boolean)

Extension Hypseus. Décide si la couleur 0 est dessinée transparente sur les sprites chargés, et sur le texte rendu, après l’appel. false, la valeur par défaut, rend la couleur 0 transparente comme le fait Hypseus : l’indice de palette 0, ou le noir pur, y compris le noir opaque d’une image qui a un canal alpha, si bien qu’un lettrage noir ou un contour noir disparaît. true les dessine d’après leur seul canal alpha, si bien que le noir opaque reste noir. Les sprites déjà chargés gardent le réglage avec lequel ils ont été chargés, et chaque script commence à false.

Renvoie : rien.

Depuis : 3.00

Exemple
-- Le lettrage du logo est noir opaque : chargez-le d'après son seul alpha, puis revenez
-- à la transparence habituelle pour les illustrations propres au jeu.
drawTransparent(true)
logo = spriteLoad("art/logo.png")
drawTransparent(false)

2.39.2. spriteBlend

spriteBlend(boolean, sprite)

Extension Hypseus, acceptée et ignorée. C’est un contournement propre à ce moteur : Hypseus charge les sprites avec le mode de mélange de SDL désactivé, et cet appel le réactive pour un sprite. Singe dessine déjà chaque sprite avec son canal alpha, si bien que le mélange n’est jamais désactivé au départ. Le handle du sprite est tout de même vérifié, si bien qu’un mauvais handle reste une erreur. Pour ajouter plutôt la lumière d’un sprite, ou multiplier par lui, voir spriteSetBlend.

Renvoie : rien.

Depuis : 3.00

2.39.3. spriteDraw

spriteDraw(id, x, y)
spriteDraw(id, x, y, centered)
spriteDraw(id, x, y, x2, y2)
spriteDraw(id, x, y, x2, y2, centered)

Copie le sprite sur l’overlay, avec sa rotation et son échelle actuelles. Appelez-la depuis onOverlayUpdate. Les deux premières formes dessinent à la taille que donnent spriteGetWidth et spriteGetHeight, avec (x, y) comme coin supérieur gauche ; les deux dernières étirent cette image dans le rectangle qui va de (x, y) à (x2, y2) inclus, toujours avec un échantillonnage au plus proche voisin, quoi que dise spriteQuality. Si le sprite est une animation en cours de lecture, le dessin la fait d’abord avancer du temps réel écoulé depuis le dessin précédent (ou depuis spritePlay), en passant autant d’images que ce temps en couvre, et montre chaque image au moins 10 ms, même quand le fichier en demande moins. Quand la dernière image est passée, la lecture revient à l’image 0 si spriteLoop est activé ; sinon elle reste sur la dernière image et s’arrête. Les parties qui sortent de l’overlay sont coupées.

Paramètres :

  • id — handle de sprite venu de spriteLoad ou de fontToSprite.

  • x, y — point d’ancrage en coordonnées de l’overlay ; les fractions sont tronquées.

  • x2, y2 — coin opposé du rectangle cible, inclus, pour les formes étirées.

  • centered — booléen. Avec true, l’image (ou le rectangle étiré) est décalée pour que (x, y) soit son centre au lieu de son coin supérieur gauche.

Remarques : Une animation en cours de lecture qui n’est pas dessinée pendant un moment rattrape son retard au dessin suivant ; appelez spritePause si elle doit plutôt garder son image. Servez-vous de la forme centrée pour les sprites tournés, car la rotation change la boîte englobante et un ancrage au coin supérieur gauche semble dériver.

Depuis : 1.x. Formes centrée et étirée centrée ajoutées en 2.10. Voir aussi : spriteLoad, spriteRotate, spriteGetWidth, videoDraw

Exemple
-- L'illustration de la borne à sa taille naturelle, l'image fixe d'attraction serrée dans sa boîte,
-- et un curseur ancré sur son centre.
function onOverlayUpdate()
    overlayClear()
    spriteDraw(cabinetSprite, CABINET_X, CABINET_Y)
    spriteDraw(attractStill, THUMB_X, THUMB_Y, THUMB_X + THUMB_W - 1, THUMB_Y + THUMB_H - 1)
    spriteDraw(cursorSprite, cursorX, cursorY, true)
    return OVERLAY_UPDATED
end

2.39.4. spriteDrawFrame

spriteDrawFrame(id, x, y, frame)
spriteDrawFrame(id, x, y, frame, scale)
spriteDrawFrame(id, x, y, frame, scaleX, scaleY)

Extension Hypseus. Copie une image d’une planche de sprites (ou de toute animation) sur l’overlay avec (x, y) comme coin supérieur gauche, sans changer l’image sur laquelle le sprite est arrêté ni son état de lecture. Les images sont numérotées à partir de 1, comme Hypseus les compte ; une image hors de 1 au nombre d’images dessine l’image 1. Une image fixe se dessine elle-même et ignore frame. Un miroir réglé par spriteFlip s’applique. La rotation et l’échelle propres au sprite, venues de spriteRotate et de spriteScale, sont ignorées : la première forme dessine l’image à sa taille naturelle, les autres multiplient sa largeur par scaleX (ou scale) et sa hauteur par scaleY (ou scale), avec un échantillonnage au plus proche voisin. Appelez-la depuis onOverlayUpdate.

Paramètres :

  • id — handle de sprite venu de spriteLoadFrames ou de spriteLoad.

  • x, y — coin supérieur gauche en coordonnées de l’overlay ; les fractions sont tronquées.

  • frame — numéro d’image, de 1 au nombre d’images ; les fractions sont tronquées.

  • scale, scaleX, scaleY — multiplicateurs de taille, 1 pour la taille naturelle.

Remarques : spriteSetFrame compte les images à partir de 0 ; spriteDrawFrame à partir de 1.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteLoadFrames, spriteDraw, spriteSetFrame, spriteFrameWidth

Exemple
-- Une bande de dix chiffres dessine le score, un chiffre par image.
digits = spriteLoadFrames(10, DIR .. "digits.png")

function drawScore(x, y, score)
    local text = tostring(score)
    for i = 1, #text do
        spriteDrawFrame(digits, x + (i - 1) * spriteFrameWidth(digits), y, tonumber(text:sub(i, i)) + 1)
    end
end

2.39.5. spriteDrawGrid

spriteDrawGrid(id, x, y, sourceX, sourceY, width, height)
spriteDrawGrid(id, x, y, sourceX, sourceY, width, height, x2, y2)

Extension Hypseus. Dessine un rectangle pris dans un sprite, avec son coin supérieur gauche en x, y : à sa propre taille ou, si x2 et y2 sont donnés, étiré pour remplir la boîte jusqu’à ce coin, comme spriteDraw étire un sprite entier. C’est le seul appel qui prend un rectangle source : spriteDraw prend le sprite entier et spriteDrawFrame une image entière d’une planche, alors que celui-ci prend n’importe quel rectangle. C’est ainsi qu’un jeu découpe une tuile, un chiffre ou une lettre dans une seule image sans la charger maintes fois.

La forme étirée est propre à Singe, et c’est sur elle que repose un jeu de course sur route. Chaque rangée de l’écran sous l’horizon est une tranche de route à une certaine distance : le jeu découpe donc une rangée dans une image de la route vue en coupe et l’étire à la largeur de la route à cette distance, centrée là où les virages l’ont menée. Une centaine d’appels par image dessinent toute la route, virages et collines compris, et rien n’est reconstruit. La même forme dessine un sprite en partie caché derrière le sommet d’une colline : découpez-en le haut et étirez-le à ce qui en reste visible. spriteScale ne sait faire ni l’un ni l’autre, puisqu’il reconstruit toute l’image chaque fois que la taille change.

Le rectangle est en pixels du sprite et doit tenir à l’intérieur ; un rectangle qui n’y tient pas, ou dont la largeur ou la hauteur est nulle, met fin au script en donnant la taille du sprite, de même qu’un x2 sans y2. Un étirement dont la boîte n’a pas de largeur ou pas de hauteur, parce que x2 est à gauche de x ou y2 au-dessus de y, ne dessine rien. L’étirement prend le pixel le plus proche au lieu de mélanger, ce qui garde les couleurs d’une rangée d’un pixel exactement telles qu’elles ont été dessinées. Le sprite d’où l’on dessine est le sprite tel qu’il est dessiné en ce moment, si bien qu’un spriteRotate ou un spriteScale change le sens des coordonnées.

Avec LEGACY_SPRITE_ARGS, le handle est en troisième position, spriteDrawGrid(x, y, spr, sourceX, sourceY, width, height), là où Hypseus le place, et x2, y2 suivent à la fin comme ici.

Paramètres :

  • id — nombre ; un handle de sprite.

  • x, y — nombres ; où arrive le coin supérieur gauche du rectangle, en coordonnées de l’overlay.

  • sourceX, sourceY — nombres ; le coin supérieur gauche du rectangle dans le sprite.

  • width, height — nombres ; sa taille, au moins 1.

  • x2, y2 — nombres, facultatifs mais ensemble ; le coin inférieur droit, inclus, de la boîte dans laquelle l’étirer.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe ; la forme étirée est nouvelle en 3.00 et propre à Singe. Voir aussi : spriteDraw, spriteDrawFrame

Exemple
-- Un nombre dessiné à partir d'une bande de dix chiffres, de 16 sur 24 chacun.
local function drawNumber(sheet, x, y, value)
    local text = tostring(value)
    for i = 1, #text do
        local digit = tonumber(text:sub(i, i))
        spriteDrawGrid(sheet, x + (i - 1) * 16, y, digit * 16, 0, 16, 24)
    end
end
Exemple
-- Une route droite jusqu'à l'horizon, une rangée de l'écran à la fois. road.png fait 256 pixels de large et deux
-- rangées de haut : une coupe de route claire et une sombre, qui alternent le long de la route pour montrer
-- qu'elle défile. La rangée y de l'écran est le sol situé à EYE * FOCAL / (y - HORIZON) de distance.
local EYE     = 60
local FOCAL   = 160
local HORIZON = 110
local HALF    = 100

local function drawRoad(road, traveled)
    for y = HORIZON + 1, 239 do
        local z     = EYE * FOCAL / (y - HORIZON)
        local half  = HALF * FOCAL / z
        local light = math.floor((z + traveled) / 60) % 2
        spriteDrawGrid(road, 160 - half, y, 0, light, 256, 1, 160 + half, y)
    end
end

2.39.6. spriteDrawRotatedFrame

spriteDrawRotatedFrame(id, x, y)
spriteDrawRotatedFrame(id, x, y, scale)
spriteDrawRotatedFrame(id, x, y, scaleX, scaleY)

Extension Hypseus. Dessine l’image que spriteRotateFrame a tournée en dernier, centrée sur x, y. C’est le pendant de cet appel et la raison d’être des deux : spriteDrawFrame ignore délibérément la rotation et l’échelle d’un sprite, si bien qu’un jeu qui veut tourner une image d’une planche se sert plutôt de ces deux-là.

Si une échelle est donnée, l’image tournée est étirée d’autant au moment du dessin — en plus de l’échelle avec laquelle elle a été tournée — et le résultat reste centré sur x, y. scaleX seul met les deux axes à l’échelle.

Dessiner avant tout spriteRotateFrame met fin au script, puisqu’il n’y a aucune image tournée à dessiner.

Avec LEGACY_SPRITE_ARGS, le handle est en dernier, comme l’écrit Hypseus.

Paramètres :

  • id — nombre ; un handle de sprite.

  • x, y — nombres ; le centre de l’image dessinée, en coordonnées de l’overlay.

  • scale ou scaleX, scaleY — nombres facultatifs ; une échelle supplémentaire au moment du dessin.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteRotateFrame, spriteDrawFrame

Exemple
-- Une aiguille de boussole : une image de la planche, pointée là où va le joueur.
spriteRotateFrame(needle, heading, 1)
spriteDrawRotatedFrame(needle, 320, 240)

2.39.7. spriteFlip

spriteFlip(id, horizontal, vertical)

Retourne le sprite en miroir de gauche à droite, de haut en bas, ou les deux, jusqu’à ce qu’il soit rappelé avec false, false. Le miroir s’applique à chaque dessin du sprite : spriteDraw, chaque image de spriteDrawFrame et l’image tournée de spriteDrawRotatedFrame. Il est appliqué après la rotation et l’échelle de spriteRotate et de spriteScale, si bien qu’un sprite tourné est retourné tel qu’il apparaît à l’écran, et qu’une image tournée est simplement retournée dans l’autre sens au lieu d’être tournée à nouveau. L’image retournée n’est reconstruite que lorsque les indicateurs changent ; une image dessinée par spriteDrawFrame est retournée une fois et gardée jusqu’à ce qu’une autre image soit demandée. spriteDrawGrid ignore le miroir, puisque son rectangle est découpé dans l’image non retournée.

Un personnage qui marche dans les deux sens n’a besoin que d’illustrations tournées d’un seul côté : retournez le sprite quand il fait demi-tour.

Paramètres :

  • id — handle de sprite.

  • horizontal — true retourne de gauche à droite.

  • vertical — true retourne de haut en bas.

Renvoie : rien.

Depuis : 3.00 Voir aussi : spriteRotate, spriteDrawFrame, spriteDrawRotatedFrame

Exemple
-- La planche du héros regarde vers la droite ; vers la gauche, ce sont les mêmes images, en miroir.
function onOverlayUpdate()
    overlayClear()
    spriteFlip(hero, heroVx < 0, false)
    spriteDrawFrame(hero, heroX, heroY, walkFrame)
    return OVERLAY_UPDATED
end

2.39.8. spriteFrameHeight

height = spriteFrameHeight(id)

Extension Hypseus. Renvoie la hauteur d’une image du sprite avant toute mise à l’échelle ou rotation : la hauteur de la bande pour une planche de spriteLoadFrames, la hauteur d’une image pour une animation, et la hauteur de l’image pour une image fixe (Hypseus renvoie ici la surface dessinée). spriteGetHeight donne plutôt la taille telle qu’elle est dessinée.

Renvoie : entier.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteFrameWidth, spriteGetHeight, spriteLoadFrames

Exemple
-- Centrer une image sur un point.
function drawCentered(sheet, frame, x, y)
    spriteDrawFrame(sheet, x - spriteFrameWidth(sheet) / 2, y - spriteFrameHeight(sheet) / 2, frame)
end

2.39.9. spriteFrameWidth

width = spriteFrameWidth(id)

Extension Hypseus. Renvoie la largeur d’une image du sprite avant toute mise à l’échelle ou rotation : la largeur de la bande divisée par le nombre d’images pour une planche de spriteLoadFrames, la largeur d’une image pour une animation, et la largeur de l’image pour une image fixe (Hypseus renvoie 0 dans ce cas). spriteGetWidth donne plutôt la taille telle qu’elle est dessinée.

Renvoie : entier.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteFrameHeight, spriteGetWidth, spriteLoadFrames

Exemple
-- Disposer côte à côte les images d'une bande.
function drawStrip(sheet, count, x, y)
    for frame = 1, count do
        spriteDrawFrame(sheet, x + (frame - 1) * spriteFrameWidth(sheet), y, frame)
    end
end

2.39.10. spriteGetFrame

result = spriteGetFrame(id)

Renvoie l’indice, compté à partir de zéro, de l’image que le sprite montre en ce moment. Les images fixes et les animations qui n’ont pas avancé renvoient 0. Les images n’avancent qu’à l’intérieur de spriteDraw, si bien que la valeur change d’un dessin à l’autre, et non entre deux appels quelconques. Servez-vous-en pour caler un son ou la logique du jeu sur une image particulière d’une animation.

Renvoie : indice d’image entier, 0 pour une image fixe.

Depuis : 2.10 Voir aussi : spriteSetFrame, spriteIsPlaying, spriteDraw

Exemple
-- Déclencher le coup de feu sur l'image où apparaît l'éclair de bouche.
function onOverlayUpdate()
    spriteDraw(muzzleFlash, gunX, gunY, true)
    local frame = spriteGetFrame(muzzleFlash)
    if frame == FLASH_FRAME and frame ~= lastFlashFrame then
        soundPlay(gunshot)
    end
    lastFlashFrame = frame
    return OVERLAY_UPDATED
end

2.39.11. spriteGetFrames

count = spriteGetFrames(id)

Extension Hypseus. Le nombre d’images d’un sprite : le nombre d’images d’une planche chargée par spriteLoadFrames ou d’un GIF ou WEBP animé, et 0 pour une image fixe. C’est le nombre jusqu’auquel va le numéro d’image, compté à partir de zéro, de spriteSetFrame, et un de plus que le plus grand qu’il accepte.

Paramètres :

  • id — nombre ; un handle de sprite.

Renvoie : nombre ; 0 pour une image fixe.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteLoadFrames, spriteGetFrame, spriteSetFrame

Exemple
-- Passer à l'image suivante, quelle que soit la planche obtenue.
local frames = spriteGetFrames(walk)
if frames > 0 then
    spriteSetFrame(walk, (spriteGetFrame(walk) + 1) % frames)
end

2.39.12. spriteGetHeight

result = spriteGetHeight(id)

Renvoie la hauteur du sprite tel qu’il serait dessiné à cet instant, en coordonnées de l’overlay. La mise à l’échelle et la rotation appliquées avec spriteScale, spriteRotate ou spriteRotateAndScale sont comprises, si bien qu’un sprite tourné renvoie la hauteur de sa boîte englobante tournée, et non celle de l’image source. Pour une animation, c’est l’image en cours qui est mesurée. Les formes étirées de spriteDraw n’influent pas sur la valeur.

Renvoie : hauteur entière.

Depuis : 2.00 Voir aussi : spriteGetWidth, spriteScale, spriteRotate

Exemple
-- Empiler des lignes de description pré-rendues, espacées de la hauteur des sprites de texte.
function onOverlayUpdate()
    local y = TEXT_Y
    for _, line in ipairs(descriptionLines) do
        spriteDraw(line, TEXT_X, y)
        y = y + spriteGetHeight(line) + 1
    end
    return OVERLAY_UPDATED
end

2.39.13. spriteGetWidth

result = spriteGetWidth(id)

Renvoie la largeur du sprite tel qu’il serait dessiné à cet instant, en coordonnées de l’overlay, y compris toute mise à l’échelle et toute rotation appliquées en ce moment. Pour une animation, c’est l’image en cours qui est mesurée. Avec spriteGetHeight, c’est la façon habituelle de centrer un sprite dans une boîte ou de mesurer un texte rendu par fontToSprite.

Renvoie : largeur entière.

Depuis : 2.00 Voir aussi : spriteGetHeight, spriteScale, fontToSprite

Exemple
-- Centrer l'image de la borne dans son panneau, et le titre sur la largeur de l'overlay.
function onOverlayUpdate()
    local x = CABINET_X + (CABINET_W - spriteGetWidth(cabinetSprite)) * 0.5
    local y = CABINET_Y + (CABINET_H - spriteGetHeight(cabinetSprite)) * 0.5
    spriteDraw(cabinetSprite, x, y)
    spriteDraw(titleSprite, (overlayGetWidth() - spriteGetWidth(titleSprite)) / 2, 25)
    return OVERLAY_UPDATED
end

2.39.14. spriteIsPlaying

result = spriteIsPlaying(id)

Indique si l’animation du sprite avance en ce moment. Un sprite tout juste chargé renvoie false ; spritePlay la met en marche, et spritePause ou la fin d’une animation sans boucle l’arrête. Interrogez-la pour savoir quand une animation jouée une seule fois est terminée.

Renvoie : booléen, true tant que l’animation joue.

Remarques : spritePlay et spritePause ne vérifient pas la présence de données d’animation, si bien qu’une image fixe renvoie ce que ces appels ont réglé en dernier.

Depuis : 2.10 Voir aussi : spritePlay, spritePause, spriteLoop

Exemple
-- Retenir le menu jusqu'à ce que l'animation du logo, jouée une seule fois, soit terminée.
function onOverlayUpdate()
    overlayClear()
    spriteDraw(logoReveal, overlayGetWidth() / 2, overlayGetHeight() / 2, true)
    if not spriteIsPlaying(logoReveal) then
        drawMenu()
    end
    return OVERLAY_UPDATED
end

2.39.15. spriteLoad

result = spriteLoad(filename)
result = spriteLoad(filename, width, height)

Charge une image et renvoie un handle entier pour les autres appels sprite*. Le nom passe par le système de fichiers virtuel du moteur, si bien que le fichier peut se trouver tel quel sur le disque ou dans un jeu empaqueté ; il est résolu par rapport au dossier dans lequel Singe a été lancé : ajoutez donc DIR devant pour les fichiers livrés avec votre jeu. Tous les formats de Formats vidéo, audio et de conteneur sont lus. Un GIF ou un WEBP animé de deux images ou plus se charge comme une animation, arrêtée sur l’image 0, sans lecture ni boucle ; tout autre fichier, y compris un GIF d’une seule image, se charge comme une image fixe. Une image de plus de 8 bits par canal, ou à pixels en virgule flottante, est convertie en RGBA 8 bits au chargement et traitée comme telle ensuite. Les pixels dont la valeur brute est 0 dans le format de pixel propre au fichier deviennent transparents. Le chargement est synchrone, et un fichier qui ne peut être ni ouvert ni décodé met fin au script avec le message d’erreur du chargeur au lieu de renvoyer nil.

La taille facultative sert à une image vectorielle — un SVG — qui n’a pas de taille propre digne de ce nom : l’image est rastérisée pour tenir dans cette boîte, en gardant ses propres proportions, au lieu d’être rastérisée à la taille du fichier puis agrandie. Demandez à spriteGetWidth et à spriteGetHeight ce qu’elle a donné, car faire tenir un dessin carré dans une boîte large laisse de la largeur inutilisée. Tous les autres formats ignorent la taille.

Paramètres :

  • filename — chaîne ; l’image à charger.

  • width — nombre facultatif ; la largeur dans laquelle faire tenir un SVG, 1 ou plus.

  • height — nombre facultatif ; la hauteur dans laquelle faire tenir un SVG, 1 ou plus. Les deux doivent être donnés ensemble.

Renvoie : handle de sprite entier.

Remarques : Les animations ne démarrent pas d’elles-mêmes. Appelez spriteLoop(id, true) et spritePlay(id) après le chargement si l’animation doit jouer et se répéter.

Depuis : 1.x. Prise en charge des GIF/WEBP animés ajoutée en 2.10 ; la taille vectorielle en 3.00. Voir aussi : spriteUnload, spritePlay, spriteLoop, fontToSprite

Exemple
-- Charger les illustrations du menu une fois au démarrage ; la boucle d'attraction est un WEBP animé.
cabinetSprite = spriteLoad(DIR .. "cabinet.png")
marqueeSprite = spriteLoad(DIR .. "marquee.png")
attractLoop   = spriteLoad(DIR .. "attract.webp")
spriteQuality(attractLoop, RENDER_SMOOTH)
spriteLoop(attractLoop, true)
spritePlay(attractLoop)

2.39.16. spriteLoadData

id = spriteLoadData(data)

Extension Hypseus. Construit un sprite à partir d’une image contenue dans une chaîne Lua au lieu d’un fichier. Tous les formats que lit spriteLoad sont lus ici, GIF et WEBP animés compris, et une animation chargée ainsi se comporte exactement comme une animation chargée depuis un fichier.

La chaîne peut contenir des octets nuls ; c’est sa longueur, et non son premier zéro, qui décide de ce qui est lu. L’image est décodée pendant l’appel et la chaîne n’est pas conservée. Des octets qui ne forment pas une image, ou une chaîne vide, mettent fin au script, comme le fait un fichier illisible dans spriteLoad.

Servez-vous-en pour des illustrations qu’un jeu génère, décompresse ou déchiffre lui-même. Les illustrations que le système de fichiers virtuel peut atteindre par leur nom — y compris celles d’un .game empaqueté — se chargent mieux avec spriteLoad, qui ne garde pas tout le fichier dans une chaîne Lua.

Paramètres :

  • data — chaîne d’octets.

Renvoie : nombre, le handle du sprite.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteLoad, soundLoadData

Exemple
-- Une image que le jeu garde dans son propre fichier de données.
local bytes = myArchive:extract("logo.png")
local logo  = spriteLoadData(bytes)
spriteDraw(logo, 10, 10)

2.39.17. spriteLoadFrames

result = spriteLoadFrames(count, filename)

Extension Hypseus. Charge un fichier image qui contient count images de même taille sur une seule rangée et renvoie un handle de sprite. La largeur d’une image est la largeur du fichier divisée par count (division entière ; les colonnes restantes à droite sont abandonnées) et sa hauteur est celle du fichier. La planche devient une animation ordinaire arrêtée sur l’image 0, sans lecture ni boucle, si bien que spriteDraw montre l’image en cours plutôt que toute la bande (comme Hypseus la dessine), et que spriteDrawFrame choisit directement n’importe quelle image. Le nom passe par le système de fichiers virtuel, comme pour spriteLoad, et les pixels de valeur brute 0 deviennent transparents dans chaque image. Un nombre hors de 2 à 512, un fichier image de moins de count pixels de large ou un fichier illisible met fin au script avec une erreur.

Paramètres :

  • count — nombre d’images sur la largeur du fichier, de 2 à 512.

  • filename — le fichier image de la bande.

Renvoie : handle de sprite entier.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteDrawFrame, spriteFrameWidth, spriteLoad, spriteUnload

Exemple
-- Une bande de cinq images de voiture ; l'image 3 est la voiture qui pointe droit devant.
carSprite = spriteLoadFrames(5, DIR .. "car.png")
carWidth  = spriteFrameWidth(carSprite)

function onOverlayUpdate()
    overlayClear()
    spriteDrawFrame(carSprite, (overlayGetWidth() - carWidth) / 2, CAR_Y, carFrame)
    return OVERLAY_UPDATED
end

2.39.18. spriteLoop

spriteLoop(id, loop)

Indique si l’animation reprend à l’image 0 après sa dernière image ou s’y arrête. Les nouveaux sprites ne bouclent pas. Le réglage est consulté chaque fois que spriteDraw dépasse la dernière image, si bien qu’on peut le changer pendant que l’animation joue. Le régler sur un sprite déjà arrêté ne relance pas la lecture ; appelez spritePlay pour cela. L’argument doit être un booléen Lua.

Paramètres :

  • id — handle de sprite.

  • loop — booléen. true revient à l’image 0 ; false (la valeur par défaut) s’arrête sur la dernière image, et spriteIsPlaying se met à renvoyer false.

Depuis : 2.10 Voir aussi : spritePlay, spriteIsPlaying, spriteSetFrame

Exemple
-- La torche vacille sans fin ; l'explosion joue une fois par coup.
torchFlame = spriteLoad(DIR .. "torch.gif")
explosion  = spriteLoad(DIR .. "explosion.gif")
spriteLoop(torchFlame, true)
spriteLoop(explosion, false)
spritePlay(torchFlame)

2.39.19. spriteNew

id = spriteNew(width, height)

Crée un sprite vierge, chaque pixel transparent, que spriteSetPixels remplira : une image que le script fabrique lui-même au lieu de la charger. Chaque côté fait de 1 à 4096 pixels ; toute autre valeur met fin au script. Le sprite est une image fixe et fait tout ce que fait n’importe quelle autre image fixe : il se dessine, tourne, change d’échelle, s’étire et se teinte, et il peut servir de texture à un matériau.

Paramètres :

  • width, height — nombres ; sa taille en pixels.

Renvoie : nombre, le handle du sprite.

Depuis : 3.00 Voir aussi : spriteSetPixels, spriteLoadData

Exemple
local minimap = spriteNew(64, 64)

2.39.20. spritePause

spritePause(id)

Arrête l’animation sur son image en cours. L’image continue d’être dessinée par spriteDraw, et le temps passé en pause n’est pas compté quand spritePlay reprend, si bien que l’image ne saute pas en avant. Mettre en pause un sprite qui ne joue pas ne change rien.

Depuis : 2.10 Voir aussi : spritePlay, spriteIsPlaying

Exemple
-- Figer l'ennemi en pleine foulée pendant que joue l'éclair de l'impact.
function onOverlayUpdate()
    if playerHit and spriteIsPlaying(enemyWalk) then
        spritePause(enemyWalk)
    end
    spriteDraw(enemyWalk, enemyX, enemyY, true)
    return OVERLAY_UPDATED
end

2.39.21. spritePlay

spritePlay(id)

Démarre ou reprend l’animation à partir de son image en cours, en comptant le premier pas à partir du moment de l’appel. Un sprite qui joue déjà est laissé tel quel, si bien que le minuteur d’image n’est pas remis à zéro. Un nouveau sprite doit être démarré avec cet appel ; le chargement seul ne l’anime pas.

Remarques : Une animation sans boucle qui a atteint sa dernière image reste sur cette image quand on la rejoue. Pour la rejouer, appelez d’abord spriteSetFrame(id, 0).

Depuis : 2.10 Voir aussi : spritePause, spriteSetFrame, spriteLoop

Exemple
-- Relancer l'explosion, jouée une seule fois, au point d'impact.
function onCollision(a, b, x, y, z, speed)
    if speed > IMPACT_SPEED then
        blastX = x
        blastY = y
        spriteSetFrame(explosion, 0)
        spritePlay(explosion)
        soundPlay(boom)
    end
end

2.39.22. spriteQuality

spriteQuality(id, mode)

Choisit l’échantillonnage employé quand le sprite est reconstruit pour une rotation ou une mise à l’échelle. RENDER_PIXELATED garde des bords de pixels nets, RENDER_SMOOTH interpole. Les nouveaux sprites sont pixelisés. Le réglage ne compte que tant qu’une rotation ou une échelle autre que 1.0 est en vigueur ; un sprite non transformé est dessiné directement depuis son image source, et les formes étirées de spriteDraw emploient toujours l’échantillonnage au plus proche voisin. Changer de mode reconstruit aussitôt l’image transformée : réglez-le donc une fois après le chargement plutôt qu’à chaque image.

Paramètres :

  • id — handle de sprite.

  • mode — RENDER_PIXELATED (0) ou RENDER_SMOOTH (1). Tout nombre non nul choisit le lissage.

Depuis : 2.10 Voir aussi : spriteScale, spriteRotate, spriteRotateAndScale

Exemple
-- Les illustrations photographiques du fronton doivent être interpolées ; le pixel art doit rester net.
marqueeSprite = spriteLoad(DIR .. "marquee.jpg")
playerSprite  = spriteLoad(DIR .. "player.png")
spriteQuality(marqueeSprite, RENDER_SMOOTH)
spriteQuality(playerSprite, RENDER_PIXELATED)
spriteScale(marqueeSprite, 0.5)
spriteScale(playerSprite, 3)

2.39.23. spriteResetColorKey

spriteResetColorKey(id, enabled)

Extension Hypseus. Acceptée pour la compatibilité, elle ne fait rien. Dans Hypseus, l’indicateur réapplique la couleur transparente aux copies que produisent spriteRotate et spriteScale, qui dessineraient sinon leur fond opaque ; les copies transformées de Singe portent la transparence dans leur canal alpha, si bien qu’il n’y a rien à réappliquer. Un mauvais handle ou un argument non booléen met fin au script, comme pour tout autre appel de sprite.

Paramètres :

  • id — handle de sprite.

  • enabled — booléen, ignoré.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteRotate, spriteScale, spriteLoad

Exemple
-- Code d'un jeu Hypseus ; sans effet dans Singe.
badge = spriteLoad(DIR .. "badge.png")
spriteResetColorKey(badge, true)

2.39.24. spriteRotate

spriteRotate(id, degrees)

Fait tourner le sprite dans le sens des aiguilles d’une montre autour de son centre. L’angle est ramené modulo 360 et peut être fractionnaire ou négatif. L’échelle actuelle est conservée. L’image tournée n’est reconstruite que lorsque l’angle change vraiment : répéter le même angle à chaque image ne coûte rien, alors qu’un nouvel angle à chaque image reconstruit à chaque image. La rotation agrandit la boîte englobante, si bien que spriteGetWidth et spriteGetHeight changent et que la forme centrée de spriteDraw est celle à employer.

Depuis : 2.10 Voir aussi : spriteRotateAndScale, spriteDraw, spriteQuality

Exemple
-- Des caisses d'une scène physique 2D, dessinées à l'angle de leurs corps.
function onOverlayUpdate()
    overlayClear()
    for _, crate in ipairs(crates) do
        local x, y = nodeGetPosition(crate)
        local _, _, angle = nodeGetRotation(crate)
        spriteRotate(crateSprite, angle)
        spriteDraw(crateSprite, x, y, true)
    end
    return OVERLAY_UPDATED
end

2.39.25. spriteRotateAndScale

spriteRotateAndScale(id, degrees, scale)
spriteRotateAndScale(id, degrees, scaleX, scaleY)

Règle ensemble la rotation et l’échelle. Le résultat est le même que spriteRotate suivi de spriteScale, mais l’image transformée est reconstruite une fois au lieu de deux, et pas du tout quand rien n’a changé. Les facteurs d’échelle devraient être supérieurs à 0 ; un facteur négatif est pris sans son signe, et un facteur qui ne laisserait aucun pixel, zéro compris, en laisse un à la place.

Paramètres :

  • id — handle de sprite.

  • degrees — rotation dans le sens des aiguilles d’une montre, ramenée modulo 360.

  • scale — facteur uniforme, 1.0 pour la taille naturelle.

  • scaleX, scaleY — facteurs horizontal et vertical séparés.

Depuis : 2.10 Voir aussi : spriteRotate, spriteScale, spriteQuality

Exemple
-- Une pièce qui tourne et rétrécit en volant vers le compteur de score.
function onOverlayUpdate()
    if coinFlying then
        coinT = math.min(coinT + 0.02, 1)
        spriteRotateAndScale(coinSprite, coinT * 720, 1 - coinT * 0.75)
        spriteDraw(coinSprite, coinX + (SCORE_X - coinX) * coinT, coinY + (SCORE_Y - coinY) * coinT, true)
        coinFlying = coinT < 1
    end
    return OVERLAY_UPDATED
end

2.39.26. spriteRotateFrame

spriteRotateFrame(id, degrees, frame)

Extension Hypseus. Prend une image dans une planche de sprites, la fait tourner de degrees dans le sens des aiguilles d’une montre, la met à l’échelle du spriteScale propre au sprite, et garde le résultat pour spriteDrawRotatedFrame. La surface dessinée propre au sprite n’est pas touchée, si bien que spriteDraw et spriteDrawFrame continuent de montrer ce qu’ils montraient.

Les images sont numérotées à partir de 1, comme les numérote spriteDrawFrame (et contrairement à spriteGetFrame et à spriteSetFrame, qui comptent à partir de 0) ; une image hors de la planche devient l’image 1 au lieu d’une erreur. Avec une image fixe, c’est toute l’image qui tourne.

Tourner n’est pas gratuit : l’image est redessinée pixel par pixel à chaque fois, alors tournez-la quand l’angle change plutôt qu’à chaque image. L’angle est pris modulo 360, et spriteQuality décide si les bords tournés sont lissés.

Avec LEGACY_SPRITE_ARGS, le handle est en dernier, spriteRotateFrame(degrees, frame, spr), comme l’écrit Hypseus.

Paramètres :

  • id — nombre ; un handle de sprite.

  • degrees — nombre ; dans le sens des aiguilles d’une montre.

  • frame — nombre ; de 1 au nombre d’images.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : spriteDrawRotatedFrame, spriteRotate, spriteScale

Exemple
-- Un sprite de vaisseau dont la coque est l'image 1 et la poussée l'image 2.
spriteRotateFrame(ship, angle, thrusting and 2 or 1)
spriteDrawRotatedFrame(ship, shipX, shipY)

2.39.27. spriteScale

spriteScale(id, scale)
spriteScale(id, scaleX, scaleY)

Met le sprite à l’échelle autour de son centre, uniformément ou par axe, en gardant la rotation actuelle. Les facteurs doivent être supérieurs à 0 ; 1.0 est la taille naturelle, et un facteur d’exactement 1.0 sur les deux axes sans rotation dessine directement l’image source. L’image mise à l’échelle n’est reconstruite que lorsqu’un facteur change, avec l’échantillonnage choisi par spriteQuality. Préférez la forme étirée de spriteDraw quand la taille cible change à chaque image, puisqu’elle ne reconstruit rien.

Paramètres :

  • id — handle de sprite.

  • scale — facteur uniforme.

  • scaleX, scaleY — facteurs horizontal et vertical séparés.

Depuis : 2.10 Voir aussi : spriteRotateAndScale, spriteQuality, spriteDraw

Exemple
-- Agrandir l'entrée de menu en surbrillance ; la reconstruction n'a lieu que lorsque la sélection bouge.
function onOverlayUpdate()
    for i, label in ipairs(menuLabels) do
        if i == selected then
            spriteScale(label, 1.25)
        else
            spriteScale(label, 1)
        end
        spriteDraw(label, MENU_X, MENU_Y + i * LINE_HEIGHT, true)
    end
    return OVERLAY_UPDATED
end

2.39.28. spriteSetAlpha

spriteSetAlpha(id, alpha)

Multiplie l’alpha de chaque pixel par alpha / 255 à chaque dessin du sprite, sous toutes ses formes : spriteDraw, spriteDrawFrame, spriteDrawGrid et spriteDrawRotatedFrame, tourné ou non. 255, la valeur par défaut, le dessine tel quel et 0 pas du tout, si bien qu’un logo apparaît et disparaît en fondu sans seconde image. Les valeurs hors limites sont ramenées dans la plage.

Paramètres :

  • id — nombre ; un handle de sprite.

  • alpha — nombre ; de 0 à 255.

Renvoie : rien.

Depuis : 3.00 Voir aussi : spriteSetBlend, spriteSetTint

Exemple
-- Le titre apparaît en fondu en deux secondes.
spriteSetAlpha(title, math.floor(255 * math.min(1, elapsed / 2)))
spriteDraw(title, 120, 80)

2.39.29. spriteSetBlend

spriteSetBlend(id, SPRITE_ALPHA | SPRITE_ADD | SPRITE_MULTIPLY)

La façon dont chaque dessin du sprite le pose sur ce qui est déjà sur l’overlay. SPRITE_ALPHA, la valeur par défaut, le dessine par-dessus selon son alpha. SPRITE_ADD ajoute sa couleur, pondérée par son alpha, à ce qui s’y trouve, si bien qu’il ne peut qu’éclaircir : halos, lumière, étincelles, et les shadebobs des vieilles démos, où une boule dessinée sur elle-même encore et encore finit par brûler jusqu’au blanc. SPRITE_MULTIPLY assombrit ce qui s’y trouve par sa couleur, pour les ombres et le verre teinté.

Les pixels ajoutés et multipliés gardent l’alpha propre de l’overlay, si bien qu’ils ne se voient que là où quelque chose est déjà dessiné sur l’overlay : sur un overlay transparent, au-dessus d’une vidéo ou de la scène 3D, ils ne changent rien. Dessinez d’abord quelque chose d’opaque, ou servez-vous de emitterSetBlend avec PARTICLE_ADD, qui ajoute par-dessus tout. Toute autre valeur que ces trois constantes met fin au script.

Paramètres :

  • id — nombre ; un handle de sprite.

  • blend — SPRITE_ALPHA, SPRITE_ADD ou SPRITE_MULTIPLY.

Renvoie : rien.

Depuis : 3.00 Voir aussi : spriteSetAlpha, spriteSetTint, emitterSetBlend

Exemple
-- Shadebobs : une boule blanche douce ajoutée le long d'un trajet, jamais effacée, si bien que la traînée monte jusqu'au blanc.
spriteSetBlend(ball, SPRITE_ADD)
spriteSetAlpha(ball, 40)
for i = 0, 15 do
    local a = t * 2 + i * 0.4
    spriteDraw(ball, 320 + math.cos(a) * 200, 240 + math.sin(a * 1.3) * 150, true)
end

2.39.30. spriteSetFrame

spriteSetFrame(id, frame)

Fait sauter une animation à l’image donnée et relance le minuteur de délai de cette image, si bien que l’image est montrée pendant toute sa durée avant la suivante. L’état de lecture ne change pas : un sprite en pause reste en pause sur la nouvelle image et un sprite qui joue continue à partir d’elle. L’appel est ignoré pour les images fixes, pour les images hors de 0 à la dernière image, et quand le sprite montre déjà cette image.

Remarques : Les images sont numérotées ici à partir de 0 ; spriteDrawFrame, l’extension Hypseus, les numérote à partir de 1.

Depuis : 2.10 Voir aussi : spriteGetFrame, spritePlay, spriteDrawFrame

Exemple
-- Montrer la porte dans l'état que lui donne la logique du jeu.
function onOverlayUpdate()
    if doorOpen then
        spriteSetFrame(doorSprite, DOOR_OPEN_FRAME)
    else
        spriteSetFrame(doorSprite, DOOR_CLOSED_FRAME)
    end
    spriteDraw(doorSprite, DOOR_X, DOOR_Y)
    return OVERLAY_UPDATED
end

2.39.31. spriteSetPixels

spriteSetPixels(id, pixels)
spriteSetPixels(id, pixels, palette)

Remplace chaque pixel d’un sprite fixe à partir d’une chaîne, une rangée à la fois depuis le haut. Sans palette, la chaîne compte quatre octets par pixel : rouge, vert, bleu et alpha. Avec une palette, c’est un octet par pixel, chacun le numéro d’une couleur de la palette, qui compte 256 couleurs de trois octets (rouge, vert et bleu, toutes opaques) ou de quatre (avec l’alpha). Une chaîne de mauvaise longueur, une palette de mauvaise longueur ou un sprite animé met fin au script.

C’est ainsi qu’un script dessine une image pixel par pixel, assez vite pour le faire à chaque image : les plasmas, tunnels, feux et eaux des vieilles démos, une mini-carte, ou une carte de hauteurs en cours d’édition. Construire la chaîne est le travail du script : gardez donc l’image petite et étirez-la au moment de la dessiner. Une boucle Lua remplit une image de 320 sur 240 en quelques millisecondes sur un ordinateur de bureau. Le mode palette est la vieille façon d’animer à peu de frais : remettez les mêmes pixels avec la palette décalée d’une couleur, et tout change de couleur sans que rien soit recalculé. Un sprite tourné ou mis à l’échelle est de nouveau tourné et mis à l’échelle avec ses nouveaux pixels ; un matériau qui montre le sprite ne voit le changement que lorsque materialSetTexture est rappelé avec le sprite, ce qui l’envoie de nouveau au GPU.

Une image chargée peut aussi recevoir de nouveaux pixels ; elle a la taille qu’elle avait au chargement.

Paramètres :

  • id — nombre ; un sprite fixe.

  • pixels — chaîne ; width * height * 4 octets, ou width * height avec une palette.

  • palette — chaîne facultative ; 768 ou 1024 octets.

Renvoie : rien.

Depuis : 3.00 Voir aussi : spriteNew, materialSetTexture

Exemple
-- Feu : chaque pixel est la moyenne de ceux du dessous et refroidit en montant, à travers une palette
-- qui va du noir au blanc en passant par le rouge et le jaune. Étiré sur le bas de l'écran à chaque image.
local W      = 160
local H      = 60
local fire   = spriteNew(W, H)
local heat   = {}
local color  = {}
for i = 0, 255 do
    color[#color + 1] = string.char(math.min(255, i * 3), math.max(0, math.min(255, i * 3 - 255)), math.max(0, i * 3 - 510))
end
local palette = table.concat(color)
for i = 0, W * (H + 1) - 1 do
    heat[i] = 0
end

function onOverlayUpdate()
    for x = 0, W - 1 do
        heat[H * W + x] = math.random(0, 255)
    end
    local rows = {}
    for y = 0, H - 1 do
        local row = {}
        for x = 0, W - 1 do
            local below = (y + 1) * W
            local v = (heat[below + (x - 1) % W] + heat[below + x] + heat[below + (x + 1) % W] + heat[y * W + x]) // 4
            heat[y * W + x] = math.max(0, v - 1)
            row[x + 1] = heat[y * W + x]
        end
        rows[y + 1] = string.char(table.unpack(row))
    end
    spriteSetPixels(fire, table.concat(rows), palette)
    overlayClear()
    spriteDraw(fire, 0, 240, 639, 479)
    return OVERLAY_UPDATED
end

2.39.32. spriteSetTint

spriteSetTint(id, r, g, b)

Multiplie la couleur de chaque pixel par r, g, b / 255 à chaque dessin du sprite, sous toutes ses formes. Un sprite blanc se dessine dans n’importe quelle couleur, et tout sprite peut être assombri ou tiré vers une couleur, sans seconde image : une seule boule blanche devient tout un arc-en-ciel de boules, et un sprite blanc d’un pixel étiré avec spriteDraw devient un rectangle plein de n’importe quelle couleur. 255, 255, 255, la valeur par défaut, le dessine tel quel. Les valeurs hors limites sont ramenées dans la plage.

Paramètres :

  • id — nombre ; un handle de sprite.

  • r, g, b — nombres ; de 0 à 255.

Renvoie : rien.

Depuis : 3.00 Voir aussi : spriteSetAlpha, spriteSetBlend

Exemple
-- Un anneau de boules, chacune de sa propre couleur, à partir d'une seule image blanche.
for i = 1, 12 do
    local hue = i / 12
    spriteSetTint(ball, 128 + 127 * math.sin(hue * 6.28), 128 + 127 * math.sin(hue * 6.28 + 2.1), 128 + 127 * math.sin(hue * 6.28 + 4.2))
    spriteDraw(ball, 320 + math.cos(hue * 6.28) * 150, 240 + math.sin(hue * 6.28) * 150, true)
end
spriteSetTint(ball, 255, 255, 255)

2.39.33. spriteUnload

spriteUnload(id)

Libère le sprite : l’image source, la copie transformée s’il y en a une, et toutes les images de l’animation. Le handle n’est plus valide ensuite et tout nouvel usage met fin au script avec une erreur. Les sprites créés par fontToSprite se libèrent de la même façon. Les sprites encore chargés à la fin du jeu sont libérés par le moteur, mais les jeux qui créent des sprites en cours de partie (du texte rendu à nouveau quand les scores changent, par exemple) doivent décharger les anciens, sans quoi la mémoire croît sans limite.

Depuis : 2.00 Voir aussi : spriteLoad, fontToSprite, onShutdown

Exemple
-- Refaire le rendu du score seulement quand il change, en libérant le sprite précédent.
function updateScoreSprite()
    if scoreSprite ~= nil then
        spriteUnload(scoreSprite)
    end
    scoreSprite = fontToSprite("SCORE " .. score)
end

function onShutdown()
    spriteUnload(scoreSprite)
    spriteUnload(cabinetSprite)
end

2.40. Sous-titre

Des sous-titres SubRip par-dessus l’image du disque. Un jeu charge un .srt avec srtLoad, l’active avec srtEnable, et le moteur affiche chaque sous-titre puis le retire à mesure que le disque l’atteint. Voir Sous-titres pour le format du fichier, la synchronisation et la façon de changer leur mise en forme.

Les sous-titres et overlayBanner partagent un même document livré, Singe/subtitle.rml, mis en forme par Singe/subtitle.rcss ; un jeu qui veut un autre aspect fournit son propre subtitle.rml à côté de son script, et Singe utilise celui-ci à la place (voir Sous-titres). Tous deux sont dessinés par-dessus l’image, au-dessus de l’overlay et sous les GUI en espace écran, et ils ne reçoivent pas la souris.

2.40.1. srtClear

srtClear()

Extension Hypseus. Retire aussitôt ce qui est à l’écran — un sous-titre ou un bandeau — et laisse tels quels les sous-titres chargés et l’état d’activation. Le sous-titre qui était affiché reste masqué jusqu’à ce que le disque atteigne le suivant ; il n’y a rien à recharger ni rien à réactiver.

Paramètres : aucun.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : srtEnable, overlayBanner

Exemple
-- Une cinématique se termine plus tôt ; retirer la ligne encore affichée.
srtClear()

2.40.2. srtEnable

srtEnable(enabled)

Extension Hypseus. Indique si les sous-titres chargés s’affichent pendant la lecture du disque. Désactiver l’affichage retire avec lui le sous-titre affiché ; le réactiver affiche le sous-titre qui couvre l’image où se trouve le disque. Un script commence avec les sous-titres désactivés : un jeu qui les charge doit donc les activer.

Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : srtLoad, srtClear

Exemple
srtEnable(SETTINGS.subtitles)

2.40.3. srtLoad

loaded = srtLoad(filename)

Extension Hypseus. Lit un fichier SubRip par le système de fichiers virtuel et convertit ses horodatages en images du disque, à la fréquence d’images propre au disque. Le chargement remplace ce qui était chargé avant ; srtEnable l’affiche ensuite.

Il répond false, sans rien avoir chargé, quand le fichier est illisible, quand il ne contient aucun sous-titre analysable, ou quand il n’y a pas de disque sur lequel le caler — un fichier mal formé donne donc un false, pas un plantage. Un avertissement qui nomme le fichier est écrit dans chacun de ces cas. Les sous-titres non analysables dans un fichier par ailleurs correct sont sautés, comme Hypseus les saute.

Comme les horodatages deviennent des numéros d’image au chargement du fichier, et que c’est le numéro d’image que le moteur compare, un sous-titre est retrouvé où que le disque soit envoyé : une recherche, un saut ou un pas d’une image tombe aussitôt sur la bonne ligne.

Paramètres :

  • filename — chaîne ; un chemin que le système de fichiers virtuel peut atteindre.

Renvoie : booléen, qui indique si au moins un sous-titre a été chargé.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : srtEnable, srtPosition, Sous-titres

Exemple
if srtLoad("subs/" .. language .. ".srt") then
    srtEnable(true)
end

2.40.4. srtLoadTrack

loaded = srtLoadTrack(track)

Comme srtLoad, sauf que les sous-titres viennent de l’intérieur du conteneur même du disque plutôt que d’un fichier .srt placé à côté. Tout ce qui suit le chargement est identique : les sous-titres deviennent des numéros d’image du disque à la fréquence d’images du disque, si bien qu’ils sont retrouvés après n’importe quel saut, et srtEnable, srtPosition et srtClear fonctionnent de même.

Le fichier entier est parcouru une fois pour recueillir la piste, sans décoder aucune image, si bien qu’un long disque prend un moment — faites-le pendant que quelque chose d’autre est à l’écran plutôt qu’entre deux images de jeu.

Une piste qui contient des images plutôt que des mots (VobSub ou PGS) ne peut pas être lue : l’appel répond false, comme pour un .srt illisible, et laisse les sous-titres vidés. Il en va de même pour un numéro de piste qui ne désigne rien, et pour un jeu sans disque.

Paramètres :

  • track — nombre ; de 0 à discGetSubtitleTracks() - 1.

Renvoie : true quand au moins un sous-titre a été lu.

Depuis : 3.00. Voir aussi : srtLoad, discGetSubtitleTracks, srtEnable

Exemple
-- Les sous-titres que portait la copie, avec un .srt à côté du jeu comme solution de repli.
if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

2.40.5. srtPosition

srtPosition(percent)

Extension Hypseus. La position d’un sous-titre, en pourcentage de la hauteur de l’image à partir du haut, de 1 à 95. La valeur par défaut est 80. Un nombre hors de cette plage est ignoré, comme Hypseus l’ignore, au lieu d’être ramené dans la plage ou refusé.

La hauteur s’applique aussitôt au sous-titre à l’écran et à chaque sous-titre suivant. overlayBanner a sa propre hauteur et n’est pas concerné.

Paramètres :

  • percent — nombre ; de 1 à 95.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : srtLoad, Sous-titres

Exemple
-- Garder les lignes à l'écart de l'afficheur de scores, en bas de l'écran.
srtPosition(70)

2.41. Meilleurs scores en ligne

Un jeu envoie un score en une ligne :

scoreSubmit(playerScore)

Tout le reste a été réglé une fois pour toutes, dans le menu : quel service, quel compte, et sous quel nom le joueur apparaît (voir En ligne : comptes, jeux et scores). Un jeu n’a besoin que d’un GAME_ID dans son entrée de games.dat — un UUID, sous lequel le tableau des scores est conservé. Voir singeGetGameId pour le format.

Appel Ce qu’il fait

scoreBegin()

Annonce qu’une partie commence. Facultatif, mais utile : voir plus bas.

scoreSubmit(value [, board [, meta]])

Met un score en file d’attente. Renvoie false si la borne n’est pas connectée ou si le jeu n’a pas de GAME_ID.

scoreLowestWins([board])

Annonce qu’un tableau classe le score le plus bas en premier. Appelez-le avant le premier score du tableau.

scoreBoard(onDone [, board])

Récupère le tableau. onDone(ok, result) avec result.top (une liste de {name, value}), result.standing (la value de ce joueur, son rank et le nombre de joueurs, players), et result.order, "highest" ou "lowest", le sens dans lequel le tableau classe. Une borne qui n’est pas connectée peut aussi le récupérer : voir plus bas.

scorePlayerName()

Le nom sous lequel cette borne envoie ses scores, ou nil si aucun n’a été choisi.

scoreSignedIn()

Indique si cette borne est connectée à un compte en ligne.

scoreWaiting()

Combien de scores sont en file d’attente et pas encore envoyés.

scoreUpdate()

Une fois par image, depuis onOverlayUpdate. Rien n’avance sans lui.

scoreGameId()

Le GAME_ID du jeu, tiré de son entrée games.dat, ou nil s’il n’en a pas. Un jeu qui n’en a pas peut être joué, mais pas classé.

Un score est mis en file d’attente, pas envoyé. Il est écrit sur le disque et remis au service quand il y a une connexion, car une borne est souvent hors ligne et un jeu ne doit jamais rester bloqué sur le réseau pour afficher son propre tableau. Un score en file d’attente survit à l’extinction de la machine.

Tout le monde peut lire un tableau. Une borne qui n’est pas connectée récupère tout de même le tableau d’un jeu que le service propose à tous, sans standing puisqu’il n’y a aucun joueur à classer, si bien qu’un jeu peut montrer le tableau auquel il enverrait ses scores et demander au joueur de se connecter. scoreSignedIn() distingue les deux cas : une borne connectée qui n’a pas encore choisi de nom n’a pas non plus de scorePlayerName(), et lui demander de se connecter serait une erreur. Un jeu que le service réserve à certains comptes n’a pas de tableau pour une borne qui n’est connectée à aucun d’eux ; la récupération échoue comme pour un jeu que le service ne connaît pas. Envoyer un score demande toujours un compte.

Un jeu peut avoir plusieurs tableaux. Passez un nom de tableau pour séparer chaque mode de jeu — un contre-la-montre à part d’un total de points, le facile à part du difficile — et relisez-le avec le même nom. Les tableaux sont aussi séparés selon le script en cours d’exécution : sans nom, un score va au tableau qui porte le nom du script, c’est-à-dire son nom de fichier sans l’extension, si bien que Collection/Raid.singe envoie à raid ; avec un nom, celui du script vient en premier, si bien que scoreSubmit(points, "hard") depuis ce script envoie à raid.hard. Chaque titre d’un .game porte le même GAME_ID, et c’est ce qui garde les jeux d’une collection sur des tableaux bien à eux même quand deux d’entre eux nomment leurs modes de la même façon, alors qu’un même jeu listé deux fois (en deux langues, par exemple : deux entrées de games.dat, un seul script) garde un seul ensemble de tableaux. Les noms de tableau sont en minuscules et contiennent des lettres, des chiffres, -, _ et . ; tout autre caractère devient -. Le nom complet fait au plus 32 caractères, et la partie du script est raccourcie en premier pour que le nom du mode survive.

Un tableau peut classer le score le plus bas en premier. Coups, morts, secondes : certains jeux comptent ce dont le joueur veut le moins. Appelez scoreLowestWins avec le nom du tableau, tel que le prend scoreSubmit, avant le premier score du tableau, et chaque score envoyé à ce tableau et chaque récupération de celui-ci suivent ce sens. Le premier score d’un tableau fixe son sens pour de bon, si bien qu’aucun tableau n’est jamais classé dans les deux sens : un score envoyé ensuite dans l’autre sens est refusé, et la file d’attente l’abandonne au lieu de le réessayer. Sur un tel tableau, zéro est un score, tout comme un nombre inférieur à zéro, un parcours sous le par.

Exemple
-- Un jeu de golf : le moins de coups gagne, et le par a son propre tableau.
scoreLowestWins("strokes")
scoreLowestWins("par")

function roundOver(strokes, coursePar)
    scoreSubmit(strokes, "strokes")
    scoreSubmit(strokes - coursePar, "par")    -- -2, c'est deux sous le par
end

Le nom affiché sur un tableau est un pseudo, jamais une adresse. Il est choisi dans l’outil Online Account, séparé du compte, et c’est la seule chose qu’un joueur montre aux autres joueurs. De trois à vingt caractères parmi les lettres, les chiffres, les traits d’union et les tirets bas, commençant et finissant par une lettre ou un chiffre — pas d’espaces, pas de points et pas de @, si bien qu’un pseudo ne peut même pas ressembler à une adresse e-mail. La casse est ignorée pour l’unicité : Ann et ANN sont un seul et même nom.

Un pseudo se choisit une fois. Si l’on pouvait en changer librement, l’historique d’un tableau des scores n’appartiendrait vraiment à personne : un joueur ne peut donc pas le changer ensuite, et une adresse e-mail ne peut pas être changée du tout.

Un pseudo que personne ne devrait revendiquer (admin, staff), ou qui contient des mots qui n’ont pas leur place sur un écran dans une salle publique, est refusé au moment du choix. Un score est refusé tant qu’aucun nom n’a été choisi, car un score qui ne porte le nom de personne ne figure sur un tableau en aucun sens utile.

Ce que vaut un score. La borne est la machine du joueur : un score envoyé est donc une affirmation — rien de ce que le client peut faire n’en fait davantage, et le signer avec un secret livré dans le client n’aurait que l’apparence de la sécurité. Rien ici ne prétend donc en vérifier un, et un jeu ne doit pas être écrit comme si quelque chose d’autre allait le faire.

scoreBegin() vaut la peine d’être appelé pour la seule chose qui n’est pas une affirmation. Appelez-le quand une partie commence ; le score qui suit porte la durée de la partie, chronométrée à l’autre bout plutôt que sur cette machine. Ce nombre n’est pas passé par la machine du joueur, et c’est ce qui lui donne sa valeur.

Rien n’est rejeté sur cette base : l’appeler coûte donc une ligne à un jeu et ne peut jamais écarter un score légitime. Une borne hors ligne au début d’une partie n’enregistre simplement aucune durée, ce qui est honnête, pas défaillant.

Exemple
function startLevel()
    scoreBegin()          -- le chronométrage commence maintenant, à l'autre bout
    ...
end
Exemple
-- À la fin d'une partie, envoyer le score puis montrer où il s'est placé.
function gameOver(points)
    scoreSubmit(points)
    scoreBoard(function(ok, board)
        if not ok then
            showMessage("Not signed in; score kept for later.")
            return
        end
        for place, row in ipairs(board.top) do
            showLine(place .. ". " .. row.name .. "  " .. row.value)
        end
    end)
end

function onOverlayUpdate()
    scoreUpdate()
    return OVERLAY_UPDATED
end

2.42. Statistiques

L’overlay du développeur, dans le coin supérieur gauche : combien de temps l’image a pris et son pire temps sur les deux dernières secondes, la fréquence d’images, la mémoire de Lua, combien de sprites, de sons et de minuteurs sont vivants, combien de nœuds de la scène ont été dessinés et en combien de lots, combien de mémoire de texture elle occupe, et ce que fait le disque.

Il est dessiné avec la police de débogage propre à SDL : il ne demande donc ni fichier de police, ni ressource, ni document GUI, et il apparaît même sur une machine où le périphérique 3D n’a jamais démarré. Il est dessiné après que singeScreenshot a pris son image, si bien qu’il n’apparaît jamais dans une capture d’écran.

Laissez-le désactivé dans un jeu livré. Rien ne vous empêche de le mettre derrière une touche dans votre propre menu de service.

2.42.1. statsEnable

statsEnable(enabled)

Affiche ou masque l’overlay. Tant qu’il est affiché, l’écran est redessiné à chaque image, si bien que les nombres continuent de bouger même quand rien d’autre ne bouge à l’écran.

Paramètres :

  • enabled — booléen.

Renvoie : rien.

Depuis : 3.00. Voir aussi : statsIsEnabled

Exemple
-- Une touche de développeur, derrière un indicateur, pour que le jeu livré n'ait pas de telle touche.
function onInputPressed(key)
    if DEVELOPER and key == SWITCH_SERVICE then
        statsEnable(not statsIsEnabled())
    end
end

2.42.2. statsIsEnabled

shown = statsIsEnabled()

Indique si l’overlay est affiché.

Paramètres :

  • Aucun.

Renvoie : true ou false.

Depuis : 3.00.

2.43. Terrain

Un sol en carte de hauteurs créé avec meshHeightmap, qui transforme une image en niveaux de gris en un maillage d’un sommet par pixel ; terrainGetHeight relit ce maillage par le nœud qui le porte. Les positions et les hauteurs sont en unités du monde, et la position et l’échelle du nœud sont prises en compte. Voir « Le terrain » dans Scènes 3D.

2.43.1. terrainGetHeight

height = terrainGetHeight(node, x, z)

La hauteur, dans le monde, du maillage de carte de hauteurs porté par node au point x, z du monde, interpolée entre les quatre échantillons les plus proches, ou nil au-delà de ses bords ou quand le maillage du nœud n’est pas une carte de hauteurs. La position et l’échelle du nœud dans le monde comptent ; sa rotation est ignorée, puisque les terrains sont à plat. Servez-vous-en pour placer des arbres, faire apparaître des choses sur le sol, ou pour une caméra qui suit la surface, sans le coût d’un lancer de rayon. Met fin au script pour un handle de nœud non valide.

Paramètres :

  • node — le nœud dont le maillage vient de meshHeightmap.

  • x, z — la position du monde à échantillonner.

Renvoie : Un nombre, ou nil hors du terrain.

Depuis : 3.00. Voir aussi : meshHeightmap, physicsRaycast, nodeSetPosition

Exemple
-- Des arbres sur les collines, et une caméra qui ne descend jamais sous le sol.
for i = 1, 40 do
    local x = math.random(-50, 50)
    local z = math.random(-50, 50)
    local tree = modelInstance(treeModel)
    nodeSetPosition(tree, x, terrainGetHeight(hills, x, z) or 0, z)
end

function onOverlayUpdate()
    local cx, cy, cz = nodeGetWorldPosition(camera)
    local ground = terrainGetHeight(hills, cx, cz)
    if ground and cy < ground + 1.5 then
        nodeSetPosition(camera, cx, ground + 1.5, cz)
    end
    return OVERLAY_UPDATED
end

2.44. Minuteur

Faire arriver quelque chose plus tard, sans compter les images vous-même. Les minuteurs tournent sur l’horloge du moteur, qui est l’horloge virtuelle avec --deterministic, si bien qu’un jeu minuté se répète exactement d’une exécution à l’autre. Ils se déclenchent avec les autres callbacks de l’image, sur le même fil d’exécution que tout le reste — il n’y a rien à verrouiller, et rien ne peut se déclencher pendant que votre script est au milieu de quelque chose.

Un minuteur qui a pris du retard — un long chargement, un point d’arrêt — se déclenche une fois quand le jeu rattrape son retard, au lieu de se déclencher les vingt fois qu’il a manquées.

Tout est oublié quand le script se recharge, si bien qu’un minuteur de l’exécution précédente ne se déclenche jamais dans la suivante.

2.44.1. timerAfter

id = timerAfter(milliseconds, function)

Appelle la fonction une fois, plus tard. La fonction reçoit l’identifiant du minuteur, si bien qu’une même fonction peut servir à plusieurs minuteurs.

Paramètres :

  • milliseconds — nombre ; zéro ou moins déclenche à l’image suivante.

  • function — appelée sous la forme function(id).

Renvoie : un nombre ; l’identifiant du minuteur.

Depuis : 3.00. Voir aussi : timerCancel, timerEvery

Exemple
-- Laisser l'explosion se terminer avant l'écran de fin de partie.
soundPlay(bang)
timerAfter(1500, function()
    showGameOver()
end)

2.44.2. timerCancel

timerCancel(id)

Arrête un minuteur. Annuler un minuteur qui s’est déjà déclenché n’est pas une erreur, si bien que rien n’a besoin de vérifier avant.

Paramètres :

  • id — nombre ; venu de timerAfter ou de timerEvery.

Renvoie : rien.

Depuis : 3.00.

2.44.3. timerEvery

id = timerEvery(milliseconds, function)

Appelle la fonction encore et encore jusqu’à son annulation.

Paramètres :

  • milliseconds — nombre ; l’intervalle entre deux appels.

  • function — appelée sous la forme function(id).

Renvoie : un nombre ; l’identifiant du minuteur.

Depuis : 3.00. Voir aussi : timerCancel

Exemple
-- Faire avancer le compte à rebours une fois par seconde, et l'arrêter quand il arrive à zéro.
local left = 30
local clock
clock = timerEvery(1000, function()
    left = left - 1
    if left <= 0 then
        timerCancel(clock)
        outOfTime()
    end
end)

2.44.4. timerIsActive

running = timerIsActive(id)

Indique si le minuteur se déclenchera encore : true pour un minuteur répétitif jusqu’à son annulation, false pour un minuteur à un coup qui s’est déjà déclenché.

Paramètres :

  • id — nombre.

Renvoie : true ou false.

Depuis : 3.00.

2.45. Tween

Faire passer un nombre d’une valeur à une autre au fil du temps, selon une courbe. Fondus, glissements, mouvements de caméra, une barre de vie qui se vide, un menu qui glisse à l’écran — c’est toujours la même chose.

tweenValue vous donne le nombre et vous laisse décider de ce qu’il signifie. C’est voulu : le moteur a des nœuds, des sprites, des éléments de GUI, des matériaux et des lumières, et un tween qui connaîtrait chacun d’eux ferait cinq jeux d’appels à garder en phase. Un tween qui donne un nombre n’en fait aucun, et il fonctionne sur des choses dont le moteur n’a jamais entendu parler.

Les courbes d’accélération sont les courbes habituelles. EASE_LINEAR n’est pas une courbe du tout ; EASE_QUAD_*, EASE_CUBIC_*, EASE_SINE_* et EASE_EXPO_* vont de la plus douce à la plus raide ; EASE_BACK_* dépasse puis revient ; EASE_ELASTIC_* oscille comme un ressort ; EASE_BOUNCE_* tombe et rebondit. Chacune existe en _IN (lente au début), _OUT (lente à la fin) et _IN_OUT (les deux).

2.45.1. tweenCancel

tweenCancel(id)

Arrête un tween là où il en est. Aucune des deux fonctions n’est plus appelée, et la valeur reste là où elle était arrivée.

Paramètres :

  • id — nombre ; venu de tweenValue.

Renvoie : rien.

Depuis : 3.00.

2.45.2. tweenIsActive

running = tweenIsActive(id)

Indique si le tween est encore en cours.

Paramètres :

  • id — nombre.

Renvoie : true ou false.

Depuis : 3.00.

2.45.3. tweenValue

id = tweenValue(from, to, milliseconds, easing, onUpdate [, onDone])

Fait passer un nombre de from à to en milliseconds, en appelant onUpdate(value, progress) à chaque image — progress va de 0 à 1 et ignore la courbe — et onDone() une fois à la fin. Le dernier onUpdate tombe toujours exactement sur to, si bien que rien ne s’arrête un pixel trop tôt.

Paramètres :

  • from, to — nombres.

  • milliseconds — nombre ; zéro ou moins arrive à l’image suivante.

  • easing — l’une des valeurs EASE_.

  • onUpdate — appelée sous la forme function(value, progress).

  • onDone — facultative ; appelée sans argument à la fin.

Renvoie : un nombre ; l’identifiant du tween.

Depuis : 3.00. Voir aussi : tweenCancel

Exemple
-- Faire glisser le titre à l'écran et faire monter l'overlay en fondu en même temps.
tweenValue(-200, 40, 600, EASE_BACK_OUT, function(x)
    titleX = x
end)

tweenValue(0, 255, 600, EASE_SINE_OUT, function(alpha)
    setOverlayOpacity(math.floor(alpha))
end, function()
    startAttractLoop()
end)

2.46. Véhicule

Voitures, motos, chars et bateaux construits sur un corps de châssis (voir Physique, « Véhicules » et « Eau »). Un véhicule n’a pas de handle propre : on le désigne par le nœud de son châssis, qui doit déjà porter un corps BODY_DYNAMIC créé par bodyNew, et un nœud sans véhicule met fin au script dans tous les appels qui suivent vehicleNew. Le châssis est tourné vers -Z, avec Y vers le haut ; les distances sont en unités du monde, les forces en newtons, les couples en newtons-mètres et les régimes du moteur en tours par minute. Chaque appel de réglage marque le véhicule pour une reconstruction au pas de physique suivant, autour des positions de roues enregistrées quand les roues ont été ajoutées. Jusqu’à 16 véhicules à la fois, chacun avec jusqu’à 16 roues.

2.46.1. vehicleNew

vehicleNew(node, kind)

Fait du corps dynamique de node le châssis d’un véhicule. Une voiture, une moto ou un char a besoin d’au moins deux roues ajoutées par vehicleAddWheel avant que le pas de physique suivant le construise ; un bateau n’a pas de roues et il est poussé par une hélice qui ne fonctionne que sous une surface créée avec bodySetWater. Le nouveau véhicule part des valeurs par défaut : un moteur de 500 Nm qui culmine à 6000 tr/min et tourne au ralenti à 1000, la boîte automatique à cinq rapports de Jolt, 35 degrés de braquage, des freins de 1500 Nm et un frein à main de 4000 Nm, une suspension de 1,5 Hz avec un amortissement de 0,5, et aucune barre antiroulis. L’appeler de nouveau sur le même nœud supprime d’abord l’ancien véhicule et ses roues. Met fin au script pour un type inconnu, un nœud dont le corps n’est pas dynamique, un type à roues dans un monde 2D, ou quand 16 véhicules existent déjà.

Paramètres :

  • node — le nœud du châssis, qui porte un corps BODY_DYNAMIC.

  • kind — VEHICLE_CAR (n’importe quel nombre d’essieux), VEHICLE_MOTORCYCLE (deux roues en ligne, qui s’incline dans les virages), VEHICLE_TANK (des roues sur deux chenilles, qui tourne sur place) ou VEHICLE_BOAT (une coque flottante avec une hélice et un gouvernail).

Depuis : 3.00. Voir aussi : vehicleAddWheel, vehicleDrive, vehicleSetThrust, bodyNew

Exemple
local car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 0.9, 0)
bodyNew(car, BODY_DYNAMIC, SHAPE_BOX, 1.8, 0.5, 4.0)
bodySetMass(car, 1500)
vehicleNew(car, VEHICLE_CAR)
for _, p in ipairs({ { -0.95, -0.2, -1.4 }, { 0.95, -0.2, -1.4 }, { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 } }) do
    local hub = nodeNew()
    nodeSetParent(hub, car)
    nodeSetPosition(hub, p[1], p[2], p[3])
    vehicleAddWheel(car, hub, 0.35, 0.25, 0.4)
end

2.46.2. vehicleDelete

vehicleDelete(node)

Retire le véhicule de son châssis : la contrainte des roues, les commandes du conducteur et tous les réglages. Le corps reste un corps dynamique ordinaire, si bien qu’une épave continue de glisser et de culbuter, et les nœuds des roues restent là où le dernier pas les a posés ; plus rien ne les déplace, sauf si le script le fait. Un nœud sans véhicule met fin au script.

Depuis : 3.00. Voir aussi : vehicleNew, bodyDelete

Exemple
function onCollision(a, b, x, y, z, speed)
    if (a == car or b == car) and speed > 25 and not wrecked then
        wrecked = true
        vehicleDelete(car)                    -- Le châssis continue de culbuter comme un corps
        soundPlay(crashSound)
        emitterStart(smoke)
    end
end

2.46.3. vehicleAddWheel

index = vehicleAddWheel(node, wheelNode, radius, width, suspension)

Ajoute au véhicule une roue placée là où se trouve wheelNode par rapport au châssis lors de la prochaine construction du véhicule. Sans charge, la suspension tient la roue suspension unités sous ce point, et elle se comprime jusqu’à la moitié de cette longueur. Dès lors, le moteur de jeu écrit la transformation du nœud de la roue dans le monde après chaque pas, avec X comme essieu et Y vers le haut, si bien que le pneu visible a sa place sur un nœud enfant : un meshCylinder tourné de 90 degrés autour de Z. Les roues situées devant la position moyenne des roues, le long de l’axe avant, comptent comme roues avant : elles braquent par défaut et n’ont pas de frein à main. Un char répartit ses roues sur la chenille gauche ou droite selon le côté du châssis où elles se trouvent, et il lui en faut au moins une de chaque côté. Les valeurs inférieures à 0.001 sont relevées à cette valeur. Met fin au script à la 17e roue.

Paramètres :

  • node — le nœud du châssis.

  • wheelNode — le nœud auquel la roue est suspendue ; sa position par rapport au châssis est le point d’attache, et le moteur de jeu le pose désormais.

  • radius — le rayon de la roue, en unités du monde.

  • width — la largeur de la roue, en unités du monde.

  • suspension — la longueur de la suspension à pleine extension, en unités du monde ; elle se comprime jusqu’à la moitié.

Renvoie : L’indice de la roue, à partir de 0, pour vehicleSetWheel, vehicleIsWheelOnGround et vehicleGetWheelSlip.

Remarques : Un véhicule n’est construit qu’une fois qu’il a deux roues, et une voiture ou une moto a aussi besoin d’une roue motrice ; d’ici là, il reste un simple corps et les appels de conduite ne font rien.

Depuis : 3.00. Voir aussi : vehicleSetWheel, vehicleSetSuspension, nodeFind

Exemple
-- Le modèle du camion porte des nœuds vides nommés d'après ses roues.
local truck  = modelInstance(truckModel)
local wheels = {}
nodeSetPosition(truck, 0, 1.2, -8)
bodyNew(truck, BODY_DYNAMIC, SHAPE_BOX, 2.4, 1.4, 6.0)
bodySetMass(truck, 4000)
vehicleNew(truck, VEHICLE_CAR)
for i, name in ipairs({ "wheelFL", "wheelFR", "wheelRL", "wheelRR" }) do
    wheels[i] = vehicleAddWheel(truck, nodeFind(name, truck), 0.5, 0.35, 0.45)
end

2.46.4. vehicleSetThrust

vehicleSetThrust(node, maxForce, x, y, z)

Règle l’hélice d’un bateau : la force avec laquelle elle pousse à plein gaz, 2000 newtons par défaut, et le point du repère de la coque où elle pousse, 0, -0.2, 1 par défaut, juste sous le pont à la poupe. La poussée suit l’axe avant de la coque et n’a lieu que tant que ce point est sous une surface d’eau ; le même point décide si le gouvernail et le frein agissent. Une force négative devient 0. Les types à roues gardent les valeurs et les ignorent.

Paramètres :

  • node — le nœud de la coque.

  • maxForce — la poussée à plein gaz, en newtons.

  • x, y, z — l’emplacement de l’hélice, dans le repère de la coque ; la poupe est vers +Z.

Depuis : 3.00. Voir aussi : vehicleSetRudder, bodySetWater, bodySetBuoyancy

Exemple
local raft = nodeNew()
nodeSetMesh(raft, meshBox(1.6, 0.3, 2.4), wood)
nodeSetPosition(raft, 1, 0.3, 4)
bodyNew(raft, BODY_DYNAMIC, SHAPE_BOX, 1.6, 0.3, 2.4)
bodySetMass(raft, 120)
bodySetBuoyancy(raft, 3.0)                    -- Flotte haut sur le bassin
vehicleNew(raft, VEHICLE_BOAT)
vehicleSetThrust(raft, 600, 0, -0.1, 1.2)     -- Un hors-bord accroché à la poupe
vehicleSetRudder(raft, 300)

2.46.5. vehicleSetWheel

vehicleSetWheel(node, index, steered, driven)

Indique si une roue tourne avec la direction et si le moteur l’entraîne, en remplaçant les valeurs par défaut pour cette roue : les roues avant braquent, et toutes les roues sont motrices sauf la roue avant d’une moto. Les roues motrices s’apparient d’un côté à l’autre du châssis en différentiels, un par essieu, et le couple du moteur est partagé à parts égales entre les essieux ; une roue motrice sans partenaire forme un essieu à elle seule. Un char ignore les deux indicateurs, puisque ses chenilles entraînent toutes les roues et font tourner la coque. Prend effet à la reconstruction du pas suivant. Met fin au script pour un indice auquel ne correspond aucune roue du véhicule.

Paramètres :

  • node — le nœud du châssis.

  • index — l’indice de la roue venu de vehicleAddWheel.

  • steered — true pour que la roue tourne jusqu’à vehicleSetSteering au braquage maximal.

  • driven — true pour que le moteur l’entraîne.

Depuis : 3.00. Voir aussi : vehicleAddWheel, vehicleSetSteering, vehicleSetAntiRoll

Exemple
-- Une voiture de sport à propulsion : les roues avant ne font que braquer.
vehicleSetWheel(car, wheels[1], true, false)
vehicleSetWheel(car, wheels[2], true, false)
vehicleSetWheel(car, wheels[3], false, true)
vehicleSetWheel(car, wheels[4], false, true)
if fourWheelSteer then
    vehicleSetWheel(car, wheels[3], true, true)
    vehicleSetWheel(car, wheels[4], true, true)
end

2.46.6. vehicleSetEngine

vehicleSetEngine(node, maxTorque, maxRpm)
vehicleSetEngine(node, maxTorque, maxRpm, minRpm)

Règle le moteur : le couple maximal en newtons-mètres, le régime maximal et le régime de ralenti en tours par minute. Les valeurs par défaut sont 500, 6000 et 1000, et le ralenti revient à 1000 quand il est omis. Le couple est maintenu à 1 ou plus, le régime maximal à 100 ou plus, et le ralenti entre 1 et le régime maximal. Un bateau n’a pas de moteur et ignore l’appel. Prend effet à la reconstruction du pas suivant.

Paramètres :

  • node — le nœud du châssis.

  • maxTorque — le couple maximal, en newtons-mètres.

  • maxRpm — le régime maximal, en tours par minute.

  • minRpm — le régime de ralenti, en tours par minute ; 1000 par défaut.

Depuis : 3.00. Voir aussi : vehicleSetGears, vehicleGetRpm

Exemple
vehicleSetEngine(tank, 1500, 4000, 800)       -- Un diesel : du couple à bas régime
vehicleSetEngine(bike, 150, 9000, 1200)       -- Un moteur qui hurle dans les tours

function onOverlayUpdate()
    local rpm = vehicleGetRpm(bike)
    overlayClear()
    fontPrint(20, 20, string.format("%5.0f rpm", rpm))
    if rpm > 8500 then
        spriteDraw(shiftLight, 200, 20)       -- Il est temps de passer le rapport supérieur
    end
    return OVERLAY_UPDATED
end

2.46.7. vehicleSetGears

vehicleSetGears(node, { ratio, ... })
vehicleSetGears(node, { ratio, ... }, reverseRatio)
vehicleSetGears(node, { ratio, ... }, reverseRatio, automatic)

Règle la boîte de vitesses : d’un à huit rapports de marche avant, le premier en premier, le rapport de marche arrière (2.9 par défaut, donné comme un nombre positif) et si la boîte passe les rapports d’elle-même (true par défaut). Un véhicule qui ne reçoit jamais cet appel utilise la boîte à cinq rapports de Jolt, 2.66, 1.78, 1.3, 1.0 et 0.74, avec la même marche arrière. Quand automatic est faux, la boîte ne passe plus les rapports d’elle-même, et aucun appel ne permet de les passer depuis le script. Un bateau n’a pas de boîte de vitesses et ignore l’appel. Prend effet à la reconstruction du pas suivant. Met fin au script quand la table est vide ou contient plus de huit rapports.

Paramètres :

  • node — le nœud du châssis.

  • { ratio, …​ } — les rapports de marche avant, en tours du moteur par tour de sortie de boîte, le premier en premier ; d’un à huit.

  • reverseRatio — le rapport de la marche arrière ; 2.9 par défaut.

  • automatic — true (par défaut) pour que la boîte passe les rapports d’elle-même.

Depuis : 3.00. Voir aussi : vehicleGetGear, vehicleSetEngine

Exemple
-- Une boîte six rapports à rapports rapprochés pour la voiture de course, une boîte trois rapports longue pour le bus.
vehicleSetGears(raceCar, { 3.2, 2.3, 1.8, 1.4, 1.1, 0.9 }, 3.0)
vehicleSetGears(bus, { 2.4, 1.3, 0.8 })

function onOverlayUpdate()
    overlayClear()
    fontPrint(20, 20, string.format("Gear %d  %.0f rpm", vehicleGetGear(raceCar), vehicleGetRpm(raceCar)))
    return OVERLAY_UPDATED
end

2.46.8. vehicleSetRudder

vehicleSetRudder(node, maxTorque)

Règle le gouvernail d’un bateau : le couple autour de l’axe vertical de la coque quand la direction est à fond, 800 newtons-mètres par défaut. Le gouvernail mord avec la vitesse, un cinquième du couple à l’arrêt et la totalité à partir de 3 unités du monde par seconde, et il tourne dans l’autre sens quand le bateau recule. Il n’agit que tant que le point de l’hélice est sous l’eau. Un couple négatif devient 0 ; les types à roues ignorent l’appel.

Depuis : 3.00. Voir aussi : vehicleSetThrust, vehicleDrive

Exemple
vehicleNew(patrolBoat, VEHICLE_BOAT)
vehicleSetThrust(patrolBoat, 4000, 0, -0.4, 3.5)
vehicleSetRudder(patrolBoat, 2500)            -- Coque lourde, grand gouvernail

function onOverlayUpdate()
    local helm = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767
    local gas  = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER) / 32767
    vehicleDrive(patrolBoat, gas, helm, 0)
    return OVERLAY_NOT_UPDATED
end

2.46.9. vehicleSetSuspension

vehicleSetSuspension(node, frequency, damping)

Règle le ressort de chaque roue : sa fréquence propre en hertz (1.5 par défaut, maintenue à 0.1 ou plus ; plus elle est haute, plus le ressort est raide) et son taux d’amortissement (0.5 par défaut ; 0 rebondit, 1 se stabilise sans dépassement). Prend effet à la reconstruction du pas suivant, sur toutes les roues à la fois ; il n’y a pas de ressort par roue. Un bateau n’a pas de suspension et ignore l’appel.

Paramètres :

  • node — le nœud du châssis.

  • frequency — la fréquence propre du ressort, en hertz.

  • damping — le taux d’amortissement, à partir de 0.

Depuis : 3.00. Voir aussi : vehicleAddWheel, vehicleSetAntiRoll

Exemple
-- Le buggy flotte sur les dunes ; la voiture de course bouge à peine sur ses ressorts.
vehicleSetSuspension(buggy, 1.0, 0.3)
vehicleSetSuspension(raceCar, 3.0, 0.7)
if surface == "gravel" then
    vehicleSetSuspension(raceCar, 2.0, 0.5)
end

2.46.10. vehicleSetSteering

vehicleSetSteering(node, maxDegrees)

Règle de combien les roues directrices tournent au braquage maximal, en degrés ; 35 par défaut, ramené entre 0 et 89. Une commande de direction de -1 ou 1 venue de vehicleDrive atteint cet angle, et des commandes plus petites une part proportionnelle de celui-ci. Prend effet à la reconstruction du pas suivant. Un char tourne par ses chenilles et un bateau par son gouvernail, si bien que tous deux ignorent l’appel.

Depuis : 3.00. Voir aussi : vehicleSetWheel, vehicleDrive

Exemple
-- Le kart tourne dans un mouchoir de poche ; le camion a besoin d'un large arc.
vehicleSetSteering(kart, 45)
vehicleSetSteering(truck, 25)
vehicleSetSteering(bus, 20)
if difficulty == "arcade" then
    vehicleSetSteering(truck, 35)             -- Une conduite indulgente
end

2.46.11. vehicleSetBrakes

vehicleSetBrakes(node, brakeTorque, handBrakeTorque)

Règle le couple de freinage que chaque roue peut appliquer pédale au plancher, 1500 newtons-mètres par défaut, et le couple du frein à main sur les roues arrière, 4000 par défaut ; les roues avant, celles qui sont devant la position moyenne des roues, n’ont pas de frein à main. Les valeurs négatives deviennent 0. Un char freine ses chenilles avec les valeurs par défaut des chenilles de Jolt et ignore l’appel, et un bateau freine par une traînée contre sa propre vitesse, si bien qu’il ignore aussi l’appel. Prend effet à la reconstruction du pas suivant.

Paramètres :

  • node — le nœud du châssis.

  • brakeTorque — le couple du frein au pied sur chaque roue, en newtons-mètres.

  • handBrakeTorque — le couple du frein à main sur les roues arrière, en newtons-mètres.

Depuis : 3.00. Voir aussi : vehicleDrive, vehicleGetWheelSlip

Exemple
vehicleSetBrakes(car, 2200, 6000)             -- Plaquettes de course et frein à main prêt pour la dérive

function onOverlayUpdate()
    local brake     = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_TRIGGER) / 32767
    local handBrake = controllerGetButton(0, GAMEPAD_0.BUTTON_B.value) and 1 or 0
    vehicleDrive(car, throttle(), steering(), brake, handBrake)
    return OVERLAY_NOT_UPDATED
end

2.46.12. vehicleSetAntiRoll

vehicleSetAntiRoll(node, stiffness)

Ajoute une barre antiroulis sur chaque essieu, en newtons par mètre ; 0 (par défaut) n’en monte aucune, et une valeur négative devient 0. Une barre relie les deux roues motrices d’un essieu, si bien qu’un essieu dont les roues ne sont pas motrices n’a pas de barre, et qu’une moto n’en a aucune. Quelques centaines gardent une voiture à plat dans les virages ; trop soulève les roues intérieures. Un char ignore l’appel. Prend effet à la reconstruction du pas suivant.

Depuis : 3.00. Voir aussi : vehicleSetSuspension, vehicleSetWheel

Exemple
local car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 0.9, 0)
bodyNew(car, BODY_DYNAMIC, SHAPE_BOX, 1.8, 0.5, 4.0)
bodySetMass(car, 1500)
vehicleNew(car, VEHICLE_CAR)
addFourWheels(car)
vehicleSetEngine(car, 600, 6500, 1000)
vehicleSetAntiRoll(car, 800)                  -- Reste à plat dans la chicane

2.46.13. vehicleDrive

vehicleDrive(node, forward, right)
vehicleDrive(node, forward, right, brake)
vehicleDrive(node, forward, right, brake, handBrake)

Règle les commandes du conducteur, qui restent valables jusqu’à l’appel suivant : appelez-la donc à chaque image depuis onOverlayUpdate. L’accélérateur et la direction vont de -1 à 1, le frein et le frein à main de 0 à 1 ; les valeurs hors limites sont ramenées dans la plage, et les commandes omises valent 0. Une voiture ou une moto reçoit les quatre comme commandes de conducteur de Jolt, un accélérateur négatif faisant reculer par la marche arrière. Un char prend forward comme accélérateur, et right ralentit la chenille intérieure ; sans accélérateur, les chenilles tournent en sens inverse l’une de l’autre, si bien que la coque pivote sur place, et le frein à main est ignoré. Un bateau prend forward comme accélérateur de l’hélice, right comme gouvernail et brake comme une traînée contre la vitesse de la coque, ignore le frein à main, et ne fait rien du tout tant que l’hélice est hors de l’eau. Toute commande non nulle réveille un châssis qui s’est mis en sommeil.

Paramètres :

  • node — le nœud du châssis.

  • forward — accélérateur, de -1 à 1 ; une valeur négative fait reculer.

  • right — direction, de -1 (gauche) à 1 (droite).

  • brake — frein au pied, de 0 à 1 ; 0 par défaut.

  • handBrake — frein à main, de 0 à 1 ; 0 par défaut.

Depuis : 3.00. Voir aussi : vehicleGetSpeed, vehicleSetBrakes, controllerGetAxis

Exemple
function onOverlayUpdate()
    local stick     = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X)
    local steer     = (math.abs(stick) > SINGE_DEAD_ZONE) and stick / 32767 or 0
    local gas       = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER) / 32767
    local brake     = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_TRIGGER) / 32767
    local handBrake = controllerGetButton(0, GAMEPAD_0.BUTTON_B.value) and 1 or 0
    if controllerGetButton(0, GAMEPAD_0.BUTTON_A.value) then
        gas = -gas                             -- Marche arrière tant que A est maintenu
    end
    vehicleDrive(car, gas, steer, brake, handBrake)
    return OVERLAY_NOT_UPDATED
end

2.46.14. vehicleGetSpeed

speed = vehicleGetSpeed(node)

La vitesse du corps du châssis le long de son axe avant, en unités du monde par seconde, négative quand il recule ; le mouvement latéral d’une dérive ne compte pas. Fonctionne pour tous les types, bateaux compris, dès l’appel à vehicleNew.

Renvoie : Un nombre.

Depuis : 3.00. Voir aussi : vehicleGetRpm, vehicleGetGear, bodyGetVelocity

Exemple
function onOverlayUpdate()
    local speed = vehicleGetSpeed(car)
    overlayClear()
    fontPrint(20, 20, string.format("%3.0f km/h", math.abs(speed) * 3.6))
    if speed < -1 then
        spriteDraw(reversingLamp, 300, 20)
    end
    return OVERLAY_UPDATED
end

2.46.15. vehicleGetRpm

rpm = vehicleGetRpm(node)

Le régime du moteur en tours par minute, entre le ralenti et le régime maximal de vehicleSetEngine, pour un compte-tours ou la hauteur d’une boucle sonore de moteur. 0 pour un bateau, qui n’a pas de moteur, et pour un véhicule qui n’a pas encore été construit faute de roues.

Renvoie : Un nombre.

Depuis : 3.00. Voir aussi : vehicleSetEngine, vehicleGetGear

Exemple
-- Une barre de compte-tours qui devient rouge au-delà de 6000.
function onOverlayUpdate()
    local rpm = vehicleGetRpm(car)
    overlayClear()
    if rpm > 6000 then
        colorForeground(255, 40, 40)
    else
        colorForeground(60, 220, 60)
    end
    overlayBox(20, 20, 20 + math.floor(rpm / 6500 * 200), 32)
    return OVERLAY_UPDATED
end

2.46.16. vehicleGetGear

gear = vehicleGetGear(node)

Le rapport que la boîte a engagé : 0 au point mort, -1 en marche arrière, 1 et plus pour les rapports de marche avant, dans l’ordre où vehicleSetGears les a donnés. 0 pour un bateau et pour un véhicule qui n’a pas encore été construit.

Renvoie : Un entier.

Depuis : 3.00. Voir aussi : vehicleSetGears, vehicleGetRpm

Exemple
local lastGear = 0

function onOverlayUpdate()
    local gear = vehicleGetGear(car)
    if gear ~= lastGear then
        soundPlay(gearChange)
        lastGear = gear
    end
    overlayClear()
    fontPrint(20, 20, (gear == -1) and "R" or ((gear == 0) and "N" or tostring(gear)))
    return OVERLAY_UPDATED
end

2.46.17. vehicleIsWheelOnGround

touching = vehicleIsWheelOnGround(node, index)

Indique si le lancer de la suspension de cette roue a trouvé quelque chose contre quoi appuyer pendant ce pas. false pour un indice auquel ne correspond aucune roue du véhicule et pour un véhicule qui n’a pas encore été construit ; aucune erreur n’est levée dans un cas comme dans l’autre.

Renvoie : Vrai ou faux.

Depuis : 3.00. Voir aussi : vehicleAddWheel, vehicleGetWheelSlip

Exemple
-- En l'air quand aucune roue ne touche ; un atterrissage après un saut secoue la caméra.
function onOverlayUpdate()
    local airborne = true
    for i = 0, 3 do
        airborne = airborne and not vehicleIsWheelOnGround(car, i)
    end
    if wasAirborne and not airborne then
        cameraShake = 12
    end
    wasAirborne = airborne
    return OVERLAY_NOT_UPDATED
end

2.46.18. vehicleGetWheelSlip

slip = vehicleGetWheelSlip(node, index)

Combien la roue patine ou glisse dans son sens de roulement, de 0 (adhérence) à 1 (patinage ou blocage), pour le crissement des pneus, la fumée et les traces de dérapage. Toujours 0 pour les roues d’un char, pour un indice auquel ne correspond aucune roue du véhicule, et pour un véhicule qui n’a pas encore été construit.

Renvoie : Un nombre.

Depuis : 3.00. Voir aussi : vehicleIsWheelOnGround, vehicleGetSpeed

Exemple
function onOverlayUpdate()
    local slip = math.max(vehicleGetWheelSlip(car, 2), vehicleGetWheelSlip(car, 3))
    if slip > 0.4 and vehicleIsWheelOnGround(car, 2) then
        emitterStart(tireSmoke)
        if not soundIsPlaying(squealChannel) then
            squealChannel = soundPlay(squeal)
        end
    else
        emitterStop(tireSmoke)
    end
    return OVERLAY_NOT_UPDATED
end

2.47. Vue

Une vue est une seconde caméra rendue dans une texture à chaque image, pour un écran, un miroir ou un portail dans la scène : viewNew en crée une et renvoie un handle entier, viewSetCamera l’attache à un nœud, et materialSetView l’affiche sur un matériau. Il peut en exister jusqu’à quatre à la fois ; chacune rend de nouveau toute la scène à sa propre taille, en pixels indépendants de l’overlay, avec la projection de la caméra principale, les ombres de l’image (cascades d’une lumière directionnelle comprises : chaque point prend la cascade la plus fine qui le couvre) et sans bloom : gardez-les donc peu nombreuses et petites. Chaque vue tourne les billboards (nodeSetBillboard) vers sa propre caméra et trie les dessins mélangés de l’arrière vers l’avant depuis celle-ci, si bien qu’une vue dont la caméra regarde d’ailleurs voit quand même les billboards de face et les objets transparents dans le bon ordre. Un mauvais handle met fin au script. Voir Scènes 3D.

2.47.1. viewDelete

viewDelete(view)

Libère la vue et ses textures, et arrête la passe de rendu supplémentaire qu’elle coûtait. Les matériaux qui l’affichaient reviennent à leur propre texture. Le handle n’est plus valide ensuite et met fin au script s’il est réutilisé ; comme il ne peut exister que quatre vues à la fois, supprimez celles dont un niveau n’a plus besoin.

Depuis : 3.00. Voir aussi : viewNew, materialSetView

Exemple
-- Les écrans de la salle de sécurité ne sont rendus que pendant que le joueur s'y trouve.
function onEnterSecurityRoom()
    feed = viewNew(512, 384)
    viewSetCamera(feed, hallwayCamera)
    materialSetView(monitorLook, feed)
end

function onLeaveSecurityRoom()
    viewDelete(feed)
    feed = nil
end

2.47.2. viewNew

view = viewNew(width, height)

Crée une caméra rendue à chaque image dans une texture de width sur height (chacune ramenée entre 1 et 4096), depuis la vue par défaut jusqu’à ce que viewSetCamera désigne un nœud, et renvoie le handle de la vue pour materialSetView. La vue utilise la projection de cameraSetPerspective ou de cameraSetOrthographic à son propre format d’image. La scène est rendue une fois de plus par vue : 512 sur 384 suffit donc largement pour un écran, et un Raspberry Pi demande plus petit. Met fin au script quand la 3D n’est pas disponible ou que quatre vues sont déjà utilisées.

Paramètres :

  • width — la largeur de la texture en pixels.

  • height — la hauteur de la texture en pixels.

Renvoie : Le handle de la vue, un entier.

Depuis : 3.00. Voir aussi : viewSetCamera, materialSetView, viewDelete

Exemple
-- Un écran de surveillance qui montre une caméra placée derrière le joueur.
eye = nodeNew()
nodeSetPosition(eye, 0, 2.2, -5)
nodeLookAt(eye, 0, 0.6, 0)
feed = viewNew(512, 384)
viewSetCamera(feed, eye)
screen = materialNew()
materialSetView(screen, feed)
materialSetUnlit(screen, true)
nodeSetMesh(monitor, meshPlane(2, 1.5), screen)
nodeSetRotation(monitor, 90, 0, 0)

2.47.3. viewSetCamera

viewSetCamera(view, node)
viewSetCamera(view, nil)
viewSetCamera(view)

Le nœud depuis lequel regarde la vue, le long de son propre -Z comme la caméra principale, si bien que le mouvement de ses parents compte. Avec nil ou sans second argument, la vue revient à la vue par défaut, depuis (0, 0, 5) en regardant l’origine. Donnez au nœud une voiture pour parent pour un rétroviseur, ou reflétez la position de la caméra principale par rapport à un mur pour un miroir dans ce mur. Met fin au script pour un handle de nœud non valide.

Depuis : 3.00. Voir aussi : viewNew, cameraSet, nodeLookAt

Exemple
-- L'écran du hall passe en revue trois caméras de sécurité.
cameras = { lobbyCamera, garageCamera, roofCamera }
current = 1

function onOverlayUpdate()
    if singeGetTicks() - lastSwitch > 4000 then
        current    = current % #cameras + 1
        lastSwitch = singeGetTicks()
        viewSetCamera(feed, cameras[current])
    end
    return OVERLAY_UPDATED
end

2.48. Vidéo

La famille video* gère des clips vidéo supplémentaires par-dessus le disque : un personnage qui parle dans un coin, une animation précalculée à un moment clé de l’histoire, plusieurs séquences simultanées. On peut charger autant de vidéos qu’on veut avec videoLoad, et chacune renvoie un handle entier opaque que toutes les autres fonctions video* prennent comme premier argument ; un handle qui a été déchargé met fin au script. Les vidéos sont dessinées sur l’overlay avec videoDraw, en coordonnées de l’overlay, et se composent comme des sprites, et une vidéo n’avance que pendant qu’elle est dessinée (ou utilisée comme matériau via materialSetVideo). Chaque vidéo a sa propre sélection de piste audio et son propre volume stéréo, indépendants du disque. Comme les sprites, les vidéos doivent être dessinées depuis onOverlayUpdate et finalement libérées avec videoUnload ; les règles de dessin sont dans Overlay.

2.48.1. videoDraw

videoDraw(id, x, y, x2, y2)
videoDraw(id, x, y, centered)

Fait avancer une vidéo jusqu’à l’image que demande son horloge et dessine cette image sur l’overlay. L’horloge suit l’audio de la vidéo quand elle en a, et le temps de l’horloge sinon, si bien qu’un appel peut avancer de zéro, une ou plusieurs images ; une vidéo qui atteint sa fin reboucle sur l’image 0. La forme à cinq arguments étire l’image dans le rectangle allant de (x, y) à (x2, y2) inclus, toujours avec un échantillonnage au plus proche voisin et sans tenir compte de videoScale, videoRotate et videoQuality. La forme à quatre arguments dessine l’image à sa taille native transformée par videoScale et videoRotate, ancrée par son coin supérieur gauche ou, quand centered vaut true, par son centre ; l’image transformée n’est reconstruite que lorsque l’image ou la transformation change, et les coins laissés par la rotation sont transparents. Si le décodeur n’a pas encore produit d’image, rien n’est dessiné.

Une image qui n’est ni mise à l’échelle ni tournée par videoScale ou videoRotate, dessinée sur l’overlay là où rien n’a été dessiné depuis un overlayClear avec une couleur transparente — une vidéo de fond dessinée en premier, par exemple — est dessinée par le GPU à la place, sous l’overlay, et ne coûte presque rien ; tout ce qui est dessiné ensuite passe toujours par-dessus. Elle est alors mise à l’échelle de l’écran comme l’overlay, au lieu d’être d’abord copiée au plus proche voisin dans l’overlay. Partout ailleurs, l’image est copiée dans l’overlay par le CPU, ce qui coûte plusieurs millisecondes par image sur une petite machine : dessinez donc une vidéo avant ce qui passe par-dessus plutôt qu’après.

Paramètres :

  • id — handle de vidéo venant de videoLoad.

  • x, y — point d’ancrage en coordonnées de l’overlay.

  • x2, y2 — coin opposé du rectangle de destination, inclus.

  • centered — booléen. true place le centre de l’image dessinée en (x, y), false son coin supérieur gauche. Utilisez true pour les vidéos tournées.

Remarques : Une vidéo qui n’est pas dessinée n’avance pas : la pause est donc implicite tant qu’un clip est caché. Ne dessinez que depuis onOverlayUpdate.

Depuis : 2.00. La forme mise à l’échelle et tournée, avec l’indicateur centered, a été ajoutée en 2.10. Voir aussi : videoLoad, videoScale, videoRotate, spriteDraw

Exemple
-- Clip du mode attraction dans un cadre fixe, qui boucle entre ses propres images de début et de fin.
function onOverlayUpdate()
    overlayClear()
    videoDraw(attractVideo, VIDEO_X, VIDEO_Y, VIDEO_X + VIDEO_W - 1, VIDEO_Y + VIDEO_H - 1)
    if videoGetFrame(attractVideo) > ATTRACT_END then
        videoSeek(attractVideo, ATTRACT_START)
    end
    return OVERLAY_UPDATED
end

2.48.2. videoGetAudioTrack

track = videoGetAudioTrack(id)

Renvoie l’indice, à partir de zéro, de la piste audio que joue une vidéo chargée. videoLoad choisit la piste désignée par --audio ou par l’entrée AUDIO_TRACK de games.dat (par défaut 0) quand le fichier a autant de pistes ; une vidéo sans aucun audio renvoie -1.

Renvoie : indice de piste entier.

Exemple
-- Afficher dans l'overlay des options quel doublage la cinématique utilise.
function drawAudioOption()
    local track = videoGetAudioTrack(cutscene)
    local label = "None"
    if track >= 0 then
        label = videoGetLanguageDescription(videoGetLanguage(cutscene, track))
    end
    overlayPrint(OPTION_X, OPTION_Y, "Cutscene audio: " .. label)
end

2.48.3. videoGetAudioTracks

count = videoGetAudioTracks(id)

Renvoie le nombre de flux audio que contient une vidéo chargée. Un clip muet renvoie 0 ; protégez-en les boucles et l’arithmétique modulo.

Renvoie : nombre entier, 0 ou plus.

Depuis : 2.10 Voir aussi : videoGetLanguage, videoSetAudioTrack, videoGetAudioTrack

Exemple
-- N'offrir le menu des langues que si la cinématique propose vraiment un choix.
cutscene = videoLoad("videos/briefing.mkv")
if videoGetAudioTracks(cutscene) > 1 then
    buildLanguageMenu(cutscene)
else
    languageMenuEnabled = false
end

2.48.4. videoGetFrame

frame = videoGetFrame(id)

Renvoie l’image sur laquelle une vidéo chargée est positionnée, à partir de zéro. La position ne change que pendant que la vidéo joue et est dessinée, et elle revient à 0 quand le clip boucle. Comparez-la à vos propres repères de début et de fin pour faire boucler une section, ou à videoGetFrameCount pour détecter la fin d’un clip joué une seule fois.

Renvoie : numéro d’image entier.

Depuis : 2.00 Voir aussi : videoSeek, videoGetFrameCount, videoDraw

Exemple
-- Rendre la main au joueur quand le briefing a été joué une fois en entier.
function onOverlayUpdate()
    if briefingRunning then
        videoDraw(briefing, 0, 0, false)
        if videoGetFrame(briefing) >= videoGetFrameCount(briefing) - 1 then
            briefingRunning = false
            videoPause(briefing)
        end
    end
    return OVERLAY_UPDATED
end

2.48.5. videoGetFrameCount

count = videoGetFrameCount(id)

Renvoie le nombre total d’images d’une vidéo chargée, tel que compté dans la table des images du fichier lors de son indexation. Les images vont de 0 à count - 1. Servez-vous-en pour des barres de progression, pour reboucler, ou pour détecter qu’un clip joué une seule fois est presque fini.

Renvoie : nombre d’images entier.

Depuis : 2.00 Voir aussi : videoGetFrame, videoSeek, videoIsPlaying

Exemple
-- Ligne de progression sous un clip de chargement : un cadre en contour et un remplissage qui s'allonge.
function drawProgress()
    local total = videoGetFrameCount(loadingClip)
    local done  = videoGetFrame(loadingClip) / (total - 1)
    colorForeground(255, 255, 255, 255)
    overlayBox(BAR_X - 1, BAR_Y - 1, BAR_X + BAR_W + 1, BAR_Y + 1)
    overlayLine(BAR_X, BAR_Y, BAR_X + BAR_W * done, BAR_Y)
end

2.48.6. videoGetHeight

height = videoGetHeight(id)

Renvoie la hauteur des images d’une vidéo chargée en pixels : la taille native du fichier, et non la taille à laquelle elle est dessinée. Combinez-la avec videoScale pour faire tenir un clip dans un cadre en gardant son format d’image.

Renvoie : hauteur entière en pixels.

Depuis : 2.00 Voir aussi : videoGetWidth, videoScale

Exemple
-- Faire tenir le clip dans une fenêtre de 320x240 sans le déformer.
local fitX = 320 / videoGetWidth(clip)
local fitY = 240 / videoGetHeight(clip)
local fit  = math.min(fitX, fitY)
videoScale(clip, fit)

2.48.7. videoGetLanguage

code = videoGetLanguage(id, track)

Renvoie l’étiquette de langue stockée dans le fichier pour une piste audio d’une vidéo chargée. L’étiquette est un code ISO 639 de trois lettres comme "eng" ou "jpn" ; une piste sans étiquette de trois lettres renvoie "unk". Une piste hors de 0 à videoGetAudioTracks(id) - 1 met fin au script.

Paramètres :

  • id — handle de vidéo.

  • track — indice de piste audio, à partir de zéro.

Renvoie : code de langue, une chaîne.

Exemple
-- Accorder le doublage de la cinématique à la langue choisie pour le disque.
local wanted = discGetLanguage(discGetAudioTrack())
for track = 0, videoGetAudioTracks(cutscene) - 1 do
    if videoGetLanguage(cutscene, track) == wanted then
        videoSetAudioTrack(cutscene, track)
        break
    end
end

2.48.8. videoGetLanguageDescription

name = videoGetLanguageDescription(code)

Cherche le nom anglais d’un code de langue. Contrairement aux autres fonctions video*, elle ne prend pas de handle ; c’est une simple consultation de table qui accepte les codes ISO 639-1 à deux lettres et les codes ISO 639-2 à trois lettres (les formes T comme B), comparés sans tenir compte de la casse. Les codes inconnus, y compris le "unk" renvoyé pour les pistes sans étiquette, donnent "Unknown". Framework.singe lui donne l’alias discGetLanguageDescription, par symétrie avec l’API du disque.

Paramètres :

  • code — code de langue comme "en", "eng" ou "jpn".

Renvoie : nom de la langue, une chaîne, ou "Unknown".

Depuis : 2.10 Voir aussi : videoGetLanguage, discGetLanguage

Exemple
-- Construire un menu de choix de la langue à partir des pistes d'une vidéo.
options = {}
for track = 0, videoGetAudioTracks(cutscene) - 1 do
    local code = videoGetLanguage(cutscene, track)
    local name = videoGetLanguageDescription(code)
    table.insert(options, { track = track, label = name })
end

2.48.9. videoGetVolume

left, right = videoGetVolume(id)
volume = videoGetVolume()

Renvoie le volume stéréo d’une vidéo chargée sous forme de deux pourcentages. Une vidéo qui vient d’être chargée est au niveau de --volume_nonvldp sur les deux canaux (par défaut 100). Notez que deux valeurs sont renvoyées, la gauche d’abord.

Appelée sans argument, c’est une extension d’Hypseus qui donne à la place le volume du laserdisc lui-même, sous la forme d’un seul nombre sur l’échelle de 0 à 64 d’Hypseus plutôt qu’en pourcentage. Ses jeux le doublent pour musicSetVolume, dont la plage va de 0 à 128. Le niveau suit --volume_vldp.

Renvoie : deux entiers, gauche et droite, chacun de 0 à 100 ; ou, sans argument, un seul entier, de 0 à 64.

Depuis : 2.00 ; la forme sans argument, pour le disque, 3.00 Voir aussi : videoSetVolume, videoLoad

Exemple
-- Baisser la cinématique pendant une réplique, puis la rétablir.
function playVoiceOver(sound)
    savedLeft, savedRight = videoGetVolume(cutscene)
    videoSetVolume(cutscene, savedLeft / 4, savedRight / 4)
    soundPlay(sound)
    duckingCutscene = true
end

2.48.10. videoGetWidth

width = videoGetWidth(id)

Renvoie la largeur des images d’une vidéo chargée en pixels : la taille native du fichier, et non la taille à laquelle elle est dessinée.

Renvoie : largeur entière en pixels.

Depuis : 2.00 Voir aussi : videoGetHeight, videoScale

Exemple
-- Centrer en haut de l'overlay un clip dessiné à sa taille native.
local x = (overlayGetWidth() - videoGetWidth(clip)) / 2
function onOverlayUpdate()
    videoDraw(clip, x, 16, false)
    return OVERLAY_UPDATED
end

2.48.11. videoIsPlaying

playing = videoIsPlaying(id)

Indique si une vidéo chargée est à l’état de lecture, c’est-à-dire si videoPlay a été appelé depuis le dernier videoPause. Une vidéo en lecture n’avance toujours que pendant qu’elle est dessinée. Les vidéos démarrent en pause après videoLoad.

Renvoie : booléen.

Depuis : 2.00 Voir aussi : videoPlay, videoPause, videoGetFrame

Exemple
-- Une seule touche met en pause ou relance le clip incrusté.
function onInputPressed(what)
    if what == SWITCH_BUTTON2 then
        if videoIsPlaying(pipVideo) then
            videoPause(pipVideo)
        else
            videoPlay(pipVideo)
        end
    end
end

2.48.12. videoLoad

id = videoLoad(filename)

Ouvre un fichier vidéo et renvoie son handle. Tout conteneur et tout codec que le FFmpeg fourni sait décoder est accepté. Le moteur construit ou lit un index des images dans un dossier de données nommé d’après l’emplacement de la vidéo sous la racine des données de Singe, si bien que le premier chargement d’un gros fichier peut prendre un moment ; ne pas réussir à créer ce dossier met fin au script. La vidéo démarre en pause sur l’image 0, avec sa piste audio choisie d’après --audio ou l’entrée AUDIO_TRACK de games.dat (par défaut 0) quand le fichier a autant de pistes, et les deux canaux au niveau de --volume_nonvldp. Les images sont décodées en RVB pour pouvoir être dessinées sur l’overlay.

Paramètres :

  • filename — chemin du fichier vidéo, relatif au dossier du jeu ou à l’intérieur d’un jeu empaqueté.

Renvoie : handle de vidéo entier.

Depuis : 2.00 Voir aussi : videoPlay, videoDraw, videoUnload

Exemple
-- Charger le clip d'attraction du jeu choisi et le placer au début de sa boucle.
function loadGameAssets()
    attractVideo = videoLoad(GAME_LIST[GAME_SELECTED].ATTRACT)
    if GAME_LIST[GAME_SELECTED].AUDIO_TRACK then
        videoSetAudioTrack(attractVideo, GAME_LIST[GAME_SELECTED].AUDIO_TRACK)
    end
    videoPlay(attractVideo)
    videoSeek(attractVideo, GAME_LIST[GAME_SELECTED].ATTRACT_START)
end

2.48.13. videoPause

videoPause(id)

Met en pause une vidéo chargée. Son horloge s’arrête, sa piste audio se met en pause et videoDraw continue de dessiner l’image sur laquelle elle s’est arrêtée. Mettre en pause une vidéo déjà en pause est sans danger.

Depuis : 2.00 Voir aussi : videoPlay, videoIsPlaying

Exemple
-- Figer le clip d'attraction pendant que l'écran de calibrage est affiché.
function calibrationBegin()
    calibrating = true
    if attractVideo then
        videoPause(attractVideo)
    end
end

2.48.14. videoPlay

videoPlay(id)

Démarre ou reprend une vidéo chargée à partir de son image actuelle. L’horloge repart de cette image, si bien qu’une vidéo reprise après une longue pause continue là où elle s’était arrêtée au lieu de sauter en avant, et la piste audio reprend avec elle. La vidéo n’avance que pendant qu’elle est dessinée avec videoDraw ou utilisée comme matériau.

Depuis : 2.00 Voir aussi : videoPause, videoSeek, videoDraw

Exemple
-- Lancer le briefing par-dessus le disque en pause.
function startBriefing()
    discPause()
    videoSeek(briefing, 0)
    videoPlay(briefing)
    briefingRunning = true
end

2.48.15. videoQuality

videoQuality(id, smooth)

Choisit le filtrage utilisé quand la forme à quatre arguments de videoDraw met la vidéo à l’échelle ou la fait tourner. Toute valeur non nulle choisit RENDER_SMOOTH (bilinéaire), zéro choisit RENDER_PIXELATED (au plus proche voisin), la valeur par défaut. Un changement marque l’image transformée pour qu’elle soit reconstruite au prochain dessin. Il n’a aucun effet sur la forme étirée à cinq arguments, qui utilise toujours le plus proche voisin, ni sur une vidéo non transformée.

Paramètres :

  • id — handle de vidéo.

  • smooth — RENDER_PIXELATED (0) ou RENDER_SMOOTH (1).

Depuis : 2.10 Voir aussi : videoScale, videoRotate, videoDraw

Exemple
-- Un clip photographique réduit dans un coin rend mieux filtré.
pipVideo = videoLoad("videos/copilot.mkv")
videoScale(pipVideo, 0.4)
videoQuality(pipVideo, RENDER_SMOOTH)
videoPlay(pipVideo)

2.48.16. videoRotate

videoRotate(id, degrees)

Règle la rotation qu’applique la forme à quatre arguments de videoDraw, en degrés dans le sens horaire, selon la même convention que spriteRotate. L’angle est réduit modulo 360 et garde son signe : 450 et 90 sont donc identiques et -90 fait tourner d’un quart de tour dans le sens antihoraire. L’échelle réglée par videoScale est conservée. La rotation se fait autour du centre de l’image : dessinez donc les vidéos tournées avec centered à true. Un angle modifié marque l’image transformée pour qu’elle soit reconstruite au prochain dessin.

Paramètres :

  • id — handle de vidéo.

  • degrees — rotation en degrés, dans le sens horaire.

Depuis : 2.10 Voir aussi : videoRotateAndScale, videoScale, videoDraw

Exemple
-- Faire tourner lentement l'image du radar pendant qu'elle joue.
function onOverlayUpdate()
    radarAngle = radarAngle + 0.5
    videoRotate(radarVideo, radarAngle)
    videoDraw(radarVideo, RADAR_CENTER_X, RADAR_CENTER_Y, true)
    return OVERLAY_UPDATED
end

2.48.17. videoRotateAndScale

videoRotateAndScale(id, degrees, scale)
videoRotateAndScale(id, degrees, scaleX, scaleY)

Règle la rotation et l’échelle en un seul appel, avec les mêmes règles que videoRotate et videoScale : des degrés dans le sens horaire réduits modulo 360, et des facteurs d’échelle qui doivent être supérieurs à 0. Utilisez-la quand les deux changent à chaque image, pour que l’image transformée soit reconstruite une fois plutôt que deux.

Paramètres :

  • id — handle de vidéo.

  • degrees — rotation en degrés, dans le sens horaire.

  • scale — facteur d’échelle uniforme, 1.0 pour la taille native.

  • scaleX, scaleY — facteurs horizontal et vertical séparés.

Depuis : 2.10 Voir aussi : videoRotate, videoScale, videoDraw

Exemple
-- Un clip qu'on congédie s'en va en culbutant et en rapetissant.
function onOverlayUpdate()
    if dismissing then
        dismissTime = dismissTime + 1
        videoRotateAndScale(popupVideo, dismissTime * 6, 1.0 - dismissTime / 60)
        videoDraw(popupVideo, POPUP_CENTER_X, POPUP_CENTER_Y, true)
    end
    return OVERLAY_UPDATED
end

2.48.18. videoScale

videoScale(id, scale)
videoScale(id, scaleX, scaleY)

Règle l’échelle qu’applique la forme à quatre arguments de videoDraw, comme facteur de la taille native ; 1.0 laisse la taille inchangée. La rotation réglée par videoRotate est conservée. Une échelle modifiée marque l’image transformée pour qu’elle soit reconstruite au prochain dessin. Des facteurs de 0 ou moins ne peuvent pas être rendus et interrompent le moteur au prochain videoDraw : maintenez donc les échelles animées au-dessus de zéro. La forme étirée à cinq arguments de videoDraw ignore ce réglage.

Paramètres :

  • id — handle de vidéo.

  • scale — facteur d’échelle uniforme, supérieur à 0.

  • scaleX, scaleY — facteurs horizontal et vertical séparés, chacun supérieur à 0.

Depuis : 2.10 Voir aussi : videoRotateAndScale, videoQuality, videoGetWidth

Exemple
-- Montrer la cinématique au quart de sa taille dans le coin pendant que la partie continue.
pipVideo = videoLoad("videos/copilot.mkv")
videoScale(pipVideo, 0.25)
videoPlay(pipVideo)
function onOverlayUpdate()
    videoDraw(pipVideo, PIP_X, PIP_Y, false)
    return OVERLAY_UPDATED
end

2.48.19. videoSeek

videoSeek(id, frame)

Place une vidéo chargée sur frame et y fait repartir son horloge. L’état de lecture ou de pause ne change pas : une vidéo en lecture continue à partir de la nouvelle image à son prochain dessin, une vidéo en pause l’affiche. Le numéro d’image est ramené modulo le nombre d’images : -1 est donc la dernière image, et une valeur au-delà de la fin retombe dans le clip.

Paramètres :

  • id — handle de vidéo.

  • frame — image cible, à partir de zéro.

Depuis : 2.00 Voir aussi : videoGetFrame, videoGetFrameCount, videoPlay

Exemple
-- Faire boucler le clip d'attraction entre les deux repères de games.dat.
function onOverlayUpdate()
    videoDraw(attractVideo, VIDEO_X, VIDEO_Y, VIDEO_X + VIDEO_W - 1, VIDEO_Y + VIDEO_H - 1)
    if videoGetFrame(attractVideo) > GAME_LIST[GAME_SELECTED].ATTRACT_END then
        videoSeek(attractVideo, GAME_LIST[GAME_SELECTED].ATTRACT_START)
    end
    return OVERLAY_UPDATED
end

2.48.20. videoSetAudioTrack

videoSetAudioTrack(id, track)

Fait passer une vidéo chargée sur une autre de ses pistes audio. L’audio en attente de l’ancienne piste est abandonné et la lecture se réaligne, si bien que le changement s’entend presque aussitôt. Choisir la piste déjà utilisée ne fait rien. Une piste hors de 0 à videoGetAudioTracks(id) - 1 met fin au script, ce qui, pour un clip muet, veut dire n’importe quelle valeur.

Paramètres :

  • id — handle de vidéo.

  • track — indice de piste audio, à partir de zéro.

Exemple
-- Le menu enregistre une piste audio par jeu pour son clip d'attraction.
attractVideo = videoLoad(GAME_LIST[GAME_SELECTED].ATTRACT)
local wanted = GAME_LIST[GAME_SELECTED].AUDIO_TRACK
if wanted and wanted < videoGetAudioTracks(attractVideo) then
    videoSetAudioTrack(attractVideo, wanted)
end
videoPlay(attractVideo)

2.48.21. videoSetVolume

videoSetVolume(id, left, right)
videoSetVolume(volume)

Règle le volume stéréo d’une vidéo chargée en pourcentages. Les valeurs sont ramenées entre 0 et 100 sans protester. Le réglage est mémorisé même pour un clip muet, et videoGetVolume le renvoie.

Appelée avec un seul argument, c’est une extension d’Hypseus qui règle à la place le volume du laserdisc lui-même, sur l’échelle de 0 à 64 d’Hypseus plutôt qu’en pourcentage : le pendant de videoGetVolume() sans argument. Un niveau hors de 0 à 64 est ignoré au lieu d’être fatal, comme le fait Hypseus.

Paramètres :

  • id — handle de vidéo.

  • left, right — volumes des canaux, de 0 (muet) à 100 (plein).

  • volume — le volume du laserdisc, de 0 (muet) à 64 (plein).

Depuis : 2.00 Voir aussi : videoGetVolume, discAudio

Exemple
-- Éteindre l'audio de la cinématique en moins d'une demi-seconde quand la main revient au joueur.
function onOverlayUpdate()
    if fadingOut then
        fadeLevel = fadeLevel - 4
        videoSetVolume(cutscene, fadeLevel, fadeLevel)
        if fadeLevel <= 0 then
            fadingOut = false
            videoPause(cutscene)
        end
    end
    return OVERLAY_UPDATED
end

2.48.22. videoUnload

videoUnload(id)

Arrête le décodeur et libère tout ce que détient une vidéo chargée : décodeur, piste audio, images en cache et surface transformée. Le handle n’est plus valide ensuite, et le passer à une fonction video* met fin au script : effacez donc la variable qui le contenait. Les vidéos encore chargées quand le script se termine sont libérées par le moteur.

Paramètres :

  • id — handle de vidéo.

Depuis : 2.00 Voir aussi : videoLoad, videoPause

Exemple
-- Abandonner les ressources du jeu choisi avant de charger le suivant.
function unloadGameAssets()
    if attractVideo then
        videoUnload(attractVideo)
        attractVideo = nil
    end
end

2.49. VLDP

L’espace de noms vldp* est antérieur à Singe 2.00 et existe pour que les anciens scripts continuent de tourner. vldpGetHeight et vldpGetWidth sont les mêmes liaisons que discGetHeight et discGetWidth, vldpSetVerbose ne fait rien, et vldpGetPixel est le seul membre sans équivalent moderne : il lit un pixel de l’image actuelle du disque en coordonnées de l’overlay et reste la façon habituelle de détecter les impacts sur de la vidéo préenregistrée. Sans disque, il renvoie du noir (voir Jeux sans disque).

Hérité. Préférez discGetHeight et discGetWidth dans le nouveau code. vldpGetPixel reste d’actualité.

Hypseus Singe a ajouté onze autres membres, gardés sous ce préfixe pour que ses jeux tournent sans modification : vldpFocusArea et vldpResetFocus recadrent l’image du disque, vldpGetScale et vldpSetScale donnent et changent le facteur d’échelle de l’affichage, vldpGetRotate et vldpSetRotate font de même pour la rotation de la présentation, vldpGetYUVPixel lit les échantillons bruts, et vldpFlash, vldpSetBlend, vldpSetLuma et vldpSetMonochrome changent l’aspect de l’image elle-même. Chacun est marqué « Extension Hypseus » ci-dessous. L’échelle et la rotation sont deux des données qu’utilise Le rectangle vidéo.

Les quatre réglages de l’image agissent sur l’image décodée, sur ses plans de luminance et de chrominance, avant qu’elle n’atteigne l’écran : vldpSetBlend et vldpSetLuma sont appliqués l’un après l’autre à mesure que chaque image est transférée, vldpSetMonochrome remplace la chrominance, et vldpFlash remplace carrément l’image le temps d’une image. Ils coûtent un passage sur le plan de luminance par image tant qu’ils sont actifs et rien du tout quand ils sont désactivés, ils laissent vldpGetPixel et vldpGetYUVPixel lire l’image telle qu’elle a été décodée, et avec un framefile ils suivent la lecture d’un segment à l’autre. Tous quatre se désactivent quand le script se recharge (sauf le monochrome, qui revient à ce que demandait --monochrome), et aucun ne touche une vidéo dessinée avec videoDraw.

2.49.1. vldpFlash

vldpFlash()

Extension Hypseus. Met une image blanche sur le disque, comme le flash d’un vrai lecteur de laserdisc pendant une recherche. Elle apparaît aussitôt et la mise à jour suivante du disque la retire, si bien qu’elle dure une image dessinée, que le disque soit en lecture, en pause ou arrêté.

Ce blanc est la valeur que flashe Hypseus, 90 % de luminance avec une chrominance neutre, et non un blanc pur : c’est ce qu’est réellement le blanc d’un signal vidéo. L’overlay, les GUI et l’illustration du bezel sont dessinés par-dessus comme d’habitude, si bien qu’un affichage tête haute reste lisible à travers le flash.

Sans disque, ou sur un disque dont la première image n’a pas encore été décodée, l’appel ne fait rien.

Paramètres : aucun.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : discSearch, vldpSetLuma

Exemple
-- Souligner un coup au but.
vldpFlash()

2.49.2. vldpFocusArea

vldpFocusArea(x, y, width, height)
vldpFocusArea()

Extension Hypseus. N’affiche qu’un rectangle de l’image du disque, donné en pixels du disque, étiré dans l’espace qu’occupe normalement l’image entière, avec la mise à l’échelle lissée habituelle du moteur de rendu ; les proportions suivent ce que donnent width et height. Le rectangle est maintenu à l’intérieur de l’image, et un rectangle entièrement hors de celle-ci met fin au script. Sans arguments, l’image entière est de nouveau affichée (Hypseus ignore cet appel et utilise vldpResetFocus ; Singe accepte les deux). Le recadrage n’est qu’un effet d’affichage : vldpGetPixel, vldpGetYUVPixel, la projection de la souris et le disque sur un matériau 3D gardent tous les coordonnées non recadrées, si bien que la détection des impacts sur une image agrandie doit être mise à l’échelle par l’appelant. Sans disque, l’appel ne fait rien. Remis à zéro quand le script se recharge.

Paramètres :

  • x, y — coin supérieur gauche en pixels du disque.

  • width, height — taille du rectangle en pixels du disque.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpResetFocus, vldpGetWidth, vldpGetPixel

Exemple
-- Zoomer sur les 80 % centraux de l'image pendant la poursuite.
local w, h = vldpGetWidth(), vldpGetHeight()
vldpFocusArea(w * 0.1, h * 0.1, w * 0.8, h * 0.8)

function onChaseEnded()
    vldpFocusArea()
end

2.49.3. vldpGetHeight

height = vldpGetHeight()

Renvoie la hauteur de la vidéo du disque en pixels, ou la hauteur du canevas sans disque. C’est la même liaison que discGetHeight, enregistrée sous son nom d’avant 2.00.

Renvoie : hauteur entière en pixels.

Remarques :

Alias hérité. Utilisez discGetHeight dans le nouveau code.

Depuis : 1.x Voir aussi : discGetHeight, vldpGetWidth

Exemple
-- Un script 1.x qui dimensionne son overlay d'après le disque.
overlaySetResolution(vldpGetWidth(), vldpGetHeight())
centerX = vldpGetWidth() / 2
centerY = vldpGetHeight() / 2

2.49.4. vldpGetPixel

r, g, b = vldpGetPixel(x, y)

Lit la couleur d’un pixel de l’image du disque actuellement à l’écran. Les coordonnées sont des coordonnées de l’overlay : le moteur les divise par le rapport d’échelle entre l’overlay et la vidéo et les tronque, si bien que vous passez les mêmes nombres que ceux avec lesquels vous dessinez. Renvoie 0, 0, 0 quand il n’y a pas de disque, quand aucune image n’a encore été décodée, ou quand les coordonnées mises à l’échelle tombent hors de la vidéo. Les jeux qui s’en servent marquent en général les cibles dans la vidéo source d’une couleur distinctive et testent le pixel sous le réticule quand on appuie sur la gâchette, au lieu de créer des boîtes de collision pour chaque image.

Paramètres :

  • x, y — coordonnées de l’overlay ; les valeurs fractionnaires sont acceptées.

Renvoie : trois entiers, rouge, vert et bleu, chacun de 0 à 255.

Depuis : 1.x Voir aussi : discGetFrame, mouseGetPosition, overlaySetResolution

Exemple
-- Détection d'un tir au pistolet optique : les cibles sont peintes en magenta pur sur les images des ennemis.
function onInputPressed(what)
    if what == SWITCH_BUTTON3 then
        local x, y = mouseGetPosition(0)
        local r, g, b = vldpGetPixel(x, y)
        if r > 200 and g < 50 and b > 200 then
            scoreHit()
        else
            scoreMiss()
        end
    end
end

2.49.5. vldpGetRotate

degrees = vldpGetRotate()

Extension Hypseus. Renvoie la rotation de la présentation en degrés dans le sens horaire : l’option --rotate, ou ce que vldpSetRotate a réglé en dernier, et 0 quand ni l’une ni l’autre ne l’a fait. Seuls 0, 90, 180 et 270 peuvent être renvoyés, car ce sont les seuls angles selon lesquels Singe tourne.

Renvoie : entier, 0, 90, 180 ou 270.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpSetRotate, vldpGetScale

Exemple
-- Une borne en mode portrait veut son panneau des scores le long du grand côté.
if vldpGetRotate() == 90 or vldpGetRotate() == 270 then
    layoutPanel(PANEL_TALL)
else
    layoutPanel(PANEL_WIDE)
end

2.49.6. vldpGetScale

scale = vldpGetScale()

Extension Hypseus. Renvoie le facteur d’échelle de l’affichage en pourcentage : l’option --scalefactor, ou ce que vldpSetScale a appliqué en dernier, et 100 quand rien n’a été donné. Les jeux Hypseus divisent 100 par cette valeur pour adapter la géométrie de leur overlay à l’image réduite. Elle n’a rien à voir avec vldpFocusArea ni avec la résolution de l’overlay.

Renvoie : entier, de 25 à 100.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpSetScale, vldpFocusArea, overlayGetWidth

Exemple
-- Code d'un jeu Hypseus : les viseurs suivent l'échelle de l'image.
if vldpGetScale ~= nil then
    gunScale = 100 / vldpGetScale()
else
    gunScale = 1
end

2.49.7. vldpGetShift

x, y = vldpGetShift()

Le décalage de l’image dans la fenêtre, en pourcentages : les options --shiftx et --shifty, ou ce que vldpSetShift a appliqué en dernier, et 0, 0 quand rien n’a été donné. À l’extrême, un décalage remplit exactement la place qu’a laissée --scalefactor, si bien que 100 avec l’échelle à 100 ne déplace rien.

Renvoie : deux entiers, chacun de -100 à 100.

Depuis : 3.00. Voir aussi : vldpSetShift, vldpGetScale

Exemple
-- Indiquer où l'exploitant a placé l'image.
local x, y = vldpGetShift()
fontPrint(10, 10, string.format("shift %d, %d", x, y))

2.49.8. vldpGetWidth

width = vldpGetWidth()

Renvoie la largeur de la vidéo du disque en pixels, ou la largeur du canevas sans disque. C’est la même liaison que discGetWidth, enregistrée sous son nom d’avant 2.00.

Renvoie : largeur entière en pixels.

Remarques :

Alias hérité. Utilisez discGetWidth dans le nouveau code.

Depuis : 1.x Voir aussi : discGetWidth, vldpGetHeight

Exemple
-- Un script 1.x qui dimensionne son overlay d'après le disque.
overlaySetResolution(vldpGetWidth(), vldpGetHeight())
centerX = vldpGetWidth() / 2
centerY = vldpGetHeight() / 2

2.49.9. vldpGetYUVPixel

y, u, v = vldpGetYUVPixel(x, y)

Extension Hypseus. Lit les échantillons bruts d’un pixel de l’image du disque actuellement affichée, avant toute conversion de couleur : la luminance et les deux échantillons de chrominance, chacun de 0 à 255, la chrominance étant à la résolution 4:2:0 de l’image décodée (le neutre est 128). Les coordonnées sont des coordonnées de l’overlay, mises à l’échelle et tronquées exactement comme le fait vldpGetPixel. Renvoie -1, -1, -1 quand il n’y a pas de disque, quand aucune image n’a encore été décodée, ou quand les coordonnées mises à l’échelle tombent hors de la vidéo. Insensible à vldpFocusArea et à vldpSetMonochrome. Moins coûteux que vldpGetPixel quand seule la luminosité compte.

Paramètres :

  • x, y — coordonnées de l’overlay ; les valeurs fractionnaires sont acceptées.

Renvoie : trois entiers, Y, U et V, chacun de 0 à 255, ou -1, -1, -1.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpGetPixel, discGetFrame

Exemple
-- La route est sombre ; tout ce qui est clair sous la voiture est un obstacle.
function carHitsSomething()
    local y = vldpGetYUVPixel(carX + carWidth / 2, carY + carHeight)
    return y >= 120
end

2.49.10. vldpResetFocus

vldpResetFocus()

Extension Hypseus. Affiche de nouveau l’image entière du disque après vldpFocusArea, exactement comme le fait vldpFocusArea() sans arguments. C’est le nom qu’Hypseus donne lui-même à cette remise à zéro, conservé pour que ses jeux tournent sans modification.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpFocusArea

Exemple
function onChaseEnded()
    vldpResetFocus()
end

2.49.11. vldpSetBlend

vldpSetBlend(enabled)

Extension Hypseus. Lisse l’image du disque verticalement : chaque échantillon de luminance devient la moyenne de lui-même et des échantillons situés juste au-dessus et juste au-dessous. C’est le filtre de mélange à trois coefficients propre à Hypseus, et il existe pour adoucir les bords durs d’un transfert entrelacé sans adoucir l’image horizontalement.

Les plans de chrominance sont laissés tels quels, si bien que le lissage change le détail de la luminosité et non la couleur. Le désactiver remet l’image exactement telle qu’elle a été décodée.

Sans disque, l’appel ne fait rien mais il est mémorisé, et prend donc effet si un disque est chargé plus tard. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpSetLuma, vldpSetMonochrome

Exemple
-- Une option de l'écran de service pour un transfert bruité.
vldpSetBlend(SETTINGS.softenVideo)

2.49.12. vldpSetLuma

vldpSetLuma(enabled [, level])

Extension Hypseus. Éclaircit ou assombrit l’image du disque. level va de 0 à 8, et 4, la valeur par défaut, ne change rien : l’écart à 4 est ajouté à chaque échantillon de luminance en huitièmes, si bien que 0 divise la luminosité par deux, que 8 l’augmente de moitié, et que les crans intermédiaires sont réguliers. Un niveau hors de 0 à 8 met fin au script.

Comme seule la luminance change, la couleur reste où elle est : monter le niveau éclaircit l’image sans délaver la couleur, ce que fait le réglage d’image d’un vrai lecteur et ce que ne ferait pas un multiplicateur de couleur. Le désactiver, ou demander le niveau 4, remet l’image exactement telle qu’elle a été décodée.

vldpSetLuma(true) sans niveau ne produit donc aucun effet visible, ce qui est aussi le comportement d’Hypseus.

Sans disque, l’appel ne fait rien mais il est mémorisé, et prend donc effet si un disque est chargé plus tard.

Paramètres :

  • enabled — booléen.

  • level — nombre facultatif ; de 0 à 8, 4 étant neutre. Par défaut 4.

Renvoie : rien.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpSetBlend, vldpSetMonochrome, vldpFlash

Exemple
-- Une scène de nuit que le joueur ne distingue pas ; laissez-le l'éclaircir.
vldpSetLuma(true, 6)

2.49.13. vldpSetMonochrome

vldpSetMonochrome(enabled)

Extension Hypseus. N’affiche le disque qu’en luminance : les plans de chrominance sont remplacés par des échantillons neutres au moment où chaque image est transférée, si bien qu’un disque en pause change aussitôt. Avec un framefile, le réglage suit la lecture d’un segment à l’autre. vldpGetPixel et vldpGetYUVPixel continuent de renvoyer les échantillons de couleur, et les vidéos supplémentaires dessinées avec videoDraw ne sont pas touchées. Associez-le à overlaySetMonochrome pour un mode noir et blanc. Sans disque, l’appel ne fait rien ; remis à zéro quand le script se recharge. Un argument non booléen met fin au script.

Paramètres :

  • enabled — booléen.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : overlaySetMonochrome, vldpGetPixel

Exemple
-- Un commutateur DIP choisit entre la couleur et le noir et blanc.
vldpSetMonochrome(not dipChroma)
overlaySetMonochrome(not dipChroma)

2.49.14. vldpSetRotate

applied = vldpSetRotate(degrees)

Extension Hypseus. Fait tourner toute la présentation dans le sens horaire : le disque, l’overlay, les GUI, la scène 3D et les particules tournent ensemble, et les positions de la souris et des pistolets optiques sont tournées en sens inverse pour qu’un clic tombe toujours là où il est dessiné. Un quart de tour échange la forme de la zone présentée, si bien qu’une fenêtre en portrait est remplie au lieu de recevoir une bande cernée de noir.

Hypseus accepte n’importe quel angle de 0 à 359 ; Singe n’accepte que 0, 90, 180 et 270, et répond false pour toute autre valeur au lieu de mettre fin au script. Un angle quelconque laisserait la projection de la souris et la bordure Sinden sans signification raisonnable, et aucun jeu de la bibliothèque Hypseus n’en demande.

La rotation coûte une cible de rendu de la taille de l’écran et une copie (blit) supplémentaire par image tant qu’elle n’est pas nulle, et rien du tout quand elle l’est. Remise à la valeur de --rotate quand le script se recharge.

Paramètres :

  • degrees — entier, 0, 90, 180 ou 270.

Renvoie : booléen, vrai quand la rotation a été appliquée.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpGetRotate, vldpSetScale

Exemple
-- Une section de shoot vertical sur un moniteur pivotant.
if not vldpSetRotate(90) then
    debugPrint("This build will not turn the screen.")
end

2.49.15. vldpSetScale

applied = vldpSetScale(percent)

Extension Hypseus. Réduit l’image autour de son centre à percent de la fenêtre, l’équivalent en cours de jeu de --scalefactor, et reconstruit le rectangle vidéo pour que le disque, l’overlay, les GUI, la scène 3D, les particules, l’éventuelle bordure Sinden et la projection de la souris le suivent tous. Les valeurs hors de 25 à 100 répondent false et ne changent rien, au lieu de mettre fin au script.

Les changements sont limités à un toutes les 15 millisecondes, comme Hypseus limite son propre zoom par touche maintenue ; un appel pendant cet intervalle répond false, si bien qu’un script qui pilote l’échelle depuis une touche maintenue doit continuer d’appeler jusqu’à ce que ça prenne. Remis à la valeur de --scalefactor quand le script se recharge.

Paramètres :

  • percent — entier, de 25 à 100.

Renvoie : booléen, vrai quand l’échelle a été appliquée.

Depuis : 3.00, comme extension d’Hypseus Singe. Voir aussi : vldpGetScale, vldpSetRotate

Exemple
-- Dézoomer d'un cran chaque fois que le joueur appuie sur la touche de réglage.
function onInputPressed(input)
    if input == SWITCH_BUTTON3 then
        vldpSetScale(vldpGetScale() - 5)
    end
end

2.49.16. vldpSetShift

vldpSetShift(x, y)

Déplace l’image dans la fenêtre, l’équivalent en cours de jeu de --shiftx et --shifty, et reconstruit le rectangle vidéo pour que le disque, l’overlay, les GUI, la scène 3D, les particules, l’éventuelle bordure Sinden et la projection de la souris le suivent tous. Les valeurs sont des pourcentages de la place qu’a laissée --scalefactor, si bien qu’avec l’échelle à 100 il n’y a nulle part où aller. Une valeur hors de -100 à 100 met fin au script, contrairement à vldpSetScale, qui répond false.

Paramètres :

  • x — entier, de -100 à 100.

  • y — entier, de -100 à 100.

Renvoie : rien.

Depuis : 3.00. Voir aussi : vldpGetShift, vldpSetScale, singeSaveGeometry

Exemple
-- Décaler l'image vers la gauche chaque fois que l'exploitant appuie sur la touche.
function onInputPressed(input)
    if input == SWITCH_LEFT then
        local x, y = vldpGetShift()
        vldpSetShift(math.max(-100, x - 1), y)
    end
end

2.49.17. vldpSetVerbose

vldpSetVerbose(...)

Ne fait rien. Elle activait autrefois la journalisation dans le lecteur vidéo d’origine ; l’appel accepte n’importe quels arguments, écrit une ligne de trace et rend la main. La trace du moteur et celle du script sont désormais des options de ligne de commande (--program et --trace).

Remarques :

Non implémenté. Conservé uniquement pour la rétrocompatibilité. Utilisez --trace sur la ligne de commande pour tracer les appels à l’API.

Depuis : 1.x Voir aussi : debugPrint, discGetState

Exemple
-- Code de démarrage 1.x porté.  L'appel est ignoré ; lancez plutôt Singe avec --trace.
vldpSetVerbose(true)
overlaySetResolution(discGetWidth(), discGetHeight())
discSearch(TITLE_FRAME)

2.50. Voix

Les éléments à partir desquels se construit une discussion vocale, sans le réseau : Opus pour rendre une voix assez petite pour être envoyée, puis la restituer, un processeur qui nettoie le son d’un microphone avant l’envoi, et un tampon de gigue pour jouer dans le bon ordre ce qui arrive en retard et dans le désordre. Envoyer les paquets et trouver les autres joueurs est l’affaire du jeu lui-même, ou d’une future version de Singe.

Les échantillons sont des chaînes de valeurs 16 bits, deux octets chacune, en little-endian, telles que les donne micRead ; avec deux canaux, elles alternent gauche et droite. Une trame est une tranche de temps fixe : 20 millisecondes, soit 960 échantillons à 48000, est la trame habituelle pour une voix.

Chaque objet ici est un handle. voiceFree en libère un ; tous sont libérés quand le jeu se termine.

Un microphone, nettoyé, encodé, puis décodé à nouveau
micOpen()
local processor = voiceProcessorNew()
local encoder   = opusEncoderNew()
local decoder   = opusDecoderNew()
local pending   = ""

function onOverlayUpdate()
	pending = pending .. micRead()
	while #pending >= 960 * 2 do
		local frame = pending:sub(1, 960 * 2)
		pending = pending:sub(960 * 2 + 1)
		local cleaned, voiced = voiceProcess(processor, frame)
		if voiced then
			local packet = opusEncode(encoder, cleaned)    -- voilà ce que vous envoyez
			local heard  = opusDecode(decoder, packet)     -- et voilà ce que l'autre bout joue
		end
	end
	return OVERLAY_UPDATED
end

2.50.1. jitterGet

packet, status = jitterGet(jitter [, span])

Le paquet qui doit être joué maintenant, et le tampon avancé d’un pas. Appelez-le une fois par durée de trame, quoi qu’il soit arrivé.

Paramètres :

  • span — nombre, les échantillons à prendre ; le pas s’il n’est pas donné.

Renvoie : le paquet, ou nil, et un état : "ok", "missing" (rien n’est dû : passez nil à opusDecode pour combler le trou), ou "insertion" (le tampon grandit pour absorber les paquets en retard : jouez un peu de silence).

Depuis : 3.00.

2.50.2. jitterNew

jitter = jitterNew([step])

Un tampon de gigue : les paquets y entrent selon leur horodatage à mesure qu’ils arrivent, et en ressortent dans l’ordre, un pas à la fois, avec un léger retard pour qu’un paquet en retard passe encore.

Paramètres :

  • step — nombre, les échantillons dont avance chaque jitterGet ; 960 s’il n’est pas donné.

Renvoie : le handle du tampon de gigue.

Depuis : 3.00.

2.50.3. jitterPut

jitterPut(jitter, packet, timestamp [, span])

Un paquet qui est arrivé. Le tampon en garde sa propre copie.

Paramètres :

  • packet — chaîne, de 1 à 4000 octets.

  • timestamp — nombre, où commence le paquet, en échantillons : l’expéditeur les compte, 0, 960, 1920, et ainsi de suite.

  • span — nombre, les échantillons que couvre le paquet ; le pas s’il n’est pas donné.

Depuis : 3.00.

2.50.4. opusDecode

samples = opusDecode(decoder, packet | nil)

Un paquet reconverti en échantillons. nil pour un paquet jamais arrivé demande à Opus de combler le trou avec quelque chose de plausible, de la durée du dernier paquet.

Renvoie : les échantillons.

Depuis : 3.00.

2.50.5. opusDecoderNew

decoder = opusDecoderNew([rate [, channels]])

Paramètres :

  • rate — nombre : 8000, 12000, 16000, 24000 ou 48000 ; 48000 s’il n’est pas donné.

  • channels — nombre, 1 ou 2 ; 1 s’il n’est pas donné.

Renvoie : le handle du décodeur.

Depuis : 3.00.

2.50.6. opusEncode

packet = opusEncode(encoder, samples)

Une trame d’échantillons en un paquet. Une trame représente 2,5 ; 5 ; 10 ; 20 ; 40 ou 60 millisecondes d’échantillons. Tout le reste est refusé.

Renvoie : le paquet, une chaîne.

Depuis : 3.00.

2.50.7. opusEncoderNew

encoder = opusEncoderNew([rate [, channels [, application]]])

Paramètres :

  • rate — nombre : 8000, 12000, 16000, 24000 ou 48000 ; 48000 s’il n’est pas donné.

  • channels — nombre, 1 ou 2 ; 1 s’il n’est pas donné.

  • application — chaîne : "voip" pour la parole, réglé pour être compris ; "audio" pour la musique ; "lowdelay" pour le moins de retard possible, au prix d’un peu de qualité. "voip" s’il n’est pas donné.

Renvoie : le handle de l’encodeur.

Depuis : 3.00.

2.50.8. opusEncoderSet

opusEncoderSet(encoder, bitrate [, complexity])

Paramètres :

  • bitrate — nombre, en bits par seconde ; 0 le laisse tel quel. Une voix est claire de 16000 à 24000.

  • complexity — nombre, de 0 à 10 : la quantité de travail à consacrer à la qualité.

Depuis : 3.00.

2.50.9. voiceFree

voiceFree(handle)

Libère un encodeur ou un décodeur Opus, un processeur de voix ou un tampon de gigue.

Depuis : 3.00.

2.50.10. voiceProcess

cleaned, voiced = voiceProcess(processor, mic [, speaker])

Une trame du microphone, nettoyée : l’écho de ce que jouaient les haut-parleurs retiré, le bruit de fond atténué, et le niveau égalisé.

Paramètres :

  • mic — chaîne, une trame d’échantillons venant du microphone.

  • speaker — chaîne, la même trame de ce qu’ont joué les haut-parleurs, s’il y a lieu : les voix des autres joueurs, par exemple. C’est son écho qui est retiré.

Renvoie : la trame nettoyée, et true quand elle ressemble à une voix — le moyen de ne rien envoyer tant que personne ne parle.

Depuis : 3.00.

2.50.11. voiceProcessorNew

processor = voiceProcessorNew([frame [, rate [, tailMs]]])

Paramètres :

  • frame — nombre, les échantillons par appel ; 960 s’il n’est pas donné.

  • rate — nombre ; 48000 s’il n’est pas donné.

  • tailMs — nombre, l’écho le plus long à annuler, en millisecondes : combien de temps un son résonne dans la pièce. 200 s’il n’est pas donné. De 1 à 2000.

Renvoie : le handle du processeur.

Depuis : 3.00.

2.51. Fonctions utilitaires du framework

Framework.singe définit cinq petites fonctions utilitaires à lui, globales comme le reste de l’API, dont se servent des jeux écrits pour des versions antérieures. Du code nouveau peut leur préférer lume et inspect, parmi les bibliothèques incluses.

Fonction Ce qu’elle fait

utilDeepCopy(value)

Une copie de value jusqu’au bout : une table est copiée clé par clé, ses clés, ses valeurs et sa métatable copiées à leur tour ; tout le reste revient tel quel.

utilDump(value)

value sous forme de texte à afficher. Une table devient { ["key"] = value,}, les tables imbriquées entre leurs propres accolades ; tout le reste passe par tostring. Pour une table qui mérite d’être lue, require("inspect") fait mieux.

utilGetTableSize(t)

Combien de clés contient t, toutes, pas seulement la séquence que mesure #t.

utilOffsetTable(source, offset)

Une copie profonde d’une table de la forme de SCANCODE, { NAME = { name = NAME, value = N } }, avec offset ajouté à chaque value.

utilTrim(s)

s sans les blancs à ses deux extrémités.

2.52. Callbacks du moteur

Ce sont des fonctions que le script définit et que Singe appelle quand l’événement correspondant se produit ; toutes sont facultatives, et une fonction non définie est ignorée. Les callbacks d’entrée sont déclenchés à mesure que les événements sont lus, onOverlayUpdate s’exécute au plus une fois toutes les 15 millisecondes, et aucun d’eux ne s’exécute pendant que la touche pause tient le jeu figé (voir La pause). Une erreur dans un callback arrête le jeu avec une trace de la pile d’appels. Dans le modèle à fil d’exécution, singeMain remplace la plus grande partie de la logique par image (voir À fil d’exécution) : les autres callbacks sont toujours déclenchés, mais Framework.singe installe son propre onOverlayUpdate pour piloter la coroutine singeMain, si bien qu’un jeu à fil d’exécution définit singeMain, onShutdown et les callbacks d’entrée qu’il veut.

2.52.1. onControllerMoved

function onControllerMoved(axis, value, which)
end

Appelé pour chaque événement de mouvement d’axe d’une manette connectée, y compris les mouvements dans la zone morte, si bien qu’un stick sous un pouce le déclenche de nombreuses fois par seconde. Les directions au-delà de SINGE_DEAD_ZONE agissent aussi comme des contacts quand controls.cfg les affecte, si bien qu’un jeu qui n’a besoin que d’une direction tout ou rien peut affecter GAMEPAD_0.AXIS_LEFT_X_L et GAMEPAD_0.AXIS_LEFT_X_R et ignorer ce callback. La valeur est enregistrée pour controllerGetAxis avant que le callback ne s’exécute.

Paramètres :

  • axis — de 0 à 5, selon les constantes GAMEPAD_AXIS_*.

  • value — position brute, de -32768 à 32767 ; les gâchettes reposent à 0.

  • which — indice de la manette, de 0 à 3, l’indice qu’utilisent controllerGetAxis et les tables GAMEPAD_N.

Exemple
-- Direction analogique à partir du stick gauche de la première manette seulement.
function onControllerMoved(axis, value, which)
    if which ~= 0 or axis ~= GAMEPAD_AXIS_LEFT_X then
        return
    end
    if math.abs(value) < SINGE_DEAD_ZONE then
        steering = 0
    else
        steering = value / 32768
    end
end

2.52.2. onInputPressed / onInputReleased

function onInputPressed(what)
end

function onInputReleased(what)
end

Appelés quand une entrée logique s’enfonce ou se relâche. Ce qui arrive dépend du mode du clavier. En MODE_NORMAL, what est une valeur SWITCH_* : les touches, les boutons de manette, les directions d’axe au-delà de la zone morte, les boutons de la souris et la molette arrivent tous ainsi, traduits par controls.cfg, chaque appui une seule fois sans répétition des touches, et les entrées qui ne sont affectées à aucun contact sont ignorées. SWITCH_PAUSE n’arrive qu’après singeSetPauseKeyEnabled(false) ; sinon, le moteur fige le jeu sur cette touche et le script ne la voit jamais. En MODE_FULL, what est le keysym de la touche (la valeur du caractère, pas le scancode), les répétitions sont transmises, et les boutons de manette et de souris passent 0 ; chaque événement atteint aussi onKeyPressed et onKeyReleased, qui portent le scancode ou le code du bouton. Quand la touche pause fige le jeu, chaque contact que tient le script est d’abord relâché via onInputReleased, et au dégel tout ce qui est encore physiquement enfoncé est de nouveau appuyé, si bien qu’un jeu ne voit jamais l’état périmé d’un bouton. Les appuis dans la première seconde après le démarrage du script, ou après que la fenêtre a repris le focus, sont considérés comme hérités d’avant et avalés avec leur relâchement. Un contact n’arrive d’aucune commande : SWITCH_MOUSE_DISCONNECT est levé par le moteur quand une souris ou un pistolet optique est débranché, une fois comme un appui puis aussitôt une fois comme un relâchement, si bien qu’un jeu de tir au pistolet peut remarquer que son pistolet s’en va (voir Souris, pistolets, et qui décide).

Exemple
function onInputPressed(what)
    if what == SWITCH_COIN1 then
        credits = credits + 1
        soundPlay(coinClip)
    elseif what == SWITCH_START1 and credits > 0 then
        startGame()
    elseif what == SWITCH_BUTTON3 then
        fireShot(cursorX, cursorY)
    elseif what == SWITCH_QUIT then
        singeQuit()
    end
end

function onInputReleased(what)
    if what == SWITCH_BUTTON1 then
        thrusting = false
    end
end

2.52.3. onKeyPressed / onKeyReleased

function onKeyPressed(keysym, scancode)
end

function onKeyReleased(keysym, scancode)
end

Appelés en MODE_FULL seulement, pour chaque touche qui s’enfonce ou se relâche, avec à la fois le keysym logique (le caractère que produit la touche dans la disposition actuelle) et le scancode physique (la position de la touche, à comparer avec la table SCANCODE). Les touches maintenues se répètent dans ce mode, ce que veut la saisie de texte. Les boutons de manette et de souris arrivent aussi, avec keysym à 0 et leur code GAMEPAD_N ou MOUSE_N comme scancode. Pour du texte, utilisez keysym ; pour des commandes où une touche sert de bouton, utilisez scancode, pour que l’affectation soit la même dans toutes les dispositions. Les affectations clavier des propres contacts du moteur n’agissent pas dans ce mode : un jeu en MODE_FULL doit donc fournir sa propre façon d’en sortir.

2.52.4. onTextInput

function onTextInput(text)
end

Appelé en MODE_FULL seulement, avec le texte qu’a produit un appui de touche — un caractère ou quelques-uns, en UTF-8 — après application de l’état de Maj et de la disposition du clavier, si bien qu’une majuscule, un guillemet ou une lettre d’une disposition non anglaise arrive tel que la personne l’a tapé. onKeyPressed donne le même appui sous forme de son keysym sans Maj et de son scancode, et c’est lui qu’il faut utiliser pour les touches qui sont des commandes ; celui-ci est celui qu’il faut utiliser pour les touches qui sont du texte. Une GUI dont un champ de texte a le focus prend le texte en premier, et le script n’en entend rien.

Depuis : 3.00. Voir aussi : onKeyPressed, keyboardSetMode

Exemple
-- Initiales du meilleur score : les lettres comme texte ; Entrée et Retour arrière par position.
function onTextInput(text)
    if text:match("^%a$") and #initials < 3 then
        initials = initials .. text:upper()
    end
end

function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.RETURN.value then
        finishInitials()
    elseif scancode == SCANCODE.BACKSPACE.value then
        initials = initials:sub(1, -2)
    end
end

2.52.5. onMidiMessage

function onMidiMessage(status, data1, data2, bytes)
end

Appelé pour chaque message qui arrive sur le port d’entrée MIDI qu’a ouvert midiOpenInput, une fois par message, avec le reste des entrées de l’image. Les trois nombres sont le message tel qu’un appareil l’envoie : status porte le type dans ses quatre bits de poids fort et le canal dans ses quatre bits de poids faible, en comptant à partir de 0, si bien qu’une note sur le premier canal arrive sous la forme 0x90. bytes est le message entier sous forme de chaîne, ce dont a besoin un message système exclusif et ce qu’il faut lire pour un message de plus de trois octets.

Les messages qui arrivent quand aucun port n’est ouvert ne sont pas mis en file ; rien de ce qui précède l’ouverture du port n’est transmis.

Paramètres :

  • status — nombre ; l’octet d’état, de 0x80 à 0xFF.

  • data1 — nombre ; le premier octet de données, ou 0 quand le message n’en a pas.

  • data2 — nombre ; le second octet de données, ou 0 quand le message n’en a pas.

  • bytes — chaîne ; le message entier, quelle que soit sa longueur.

Depuis : 3.00. Voir aussi : midiOpenInput, midiSend

Exemple
-- Un clavier MIDI joue au jeu : le do central et les notes au-dessus sont les quatre boutons de tir.
local MIDI_NOTE_ON = 0x90

function onMidiMessage(status, data1, data2, bytes)
    -- Le type est dans les quatre bits du haut ; le canal, dans les quatre du bas, est ignoré ici.
    if (status & 0xF0) == MIDI_NOTE_ON and data2 > 0 then
        local button = data1 - 60
        if button >= 0 and button <= 3 then
            fire(button)
        end
    end
end

2.52.6. onMouseMoved

function onMouseMoved(x, y, xRelative, yRelative, which)
end

Appelé pour chaque événement de mouvement de la souris, avec la position et le déplacement depuis l’événement précédent en coordonnées de l’overlay. En mode MOUSE_SINGLE, la position du pointeur de la fenêtre est convertie en coordonnées de l’overlay et which vaut toujours 0. En mode MOUSE_MANY, le déplacement relatif de chaque périphérique est intégré en une position qui lui est propre, ramenée dans la zone de la vidéo, et which est l’indice du périphérique ; un périphérique absolu comme une tablette signale sa position projetée avec xRelative et yRelative à 0. La position est enregistrée pour mouseGetPosition avant que le callback ne s’exécute, si bien qu’un jeu peut ignorer ce callback et interroger la souris à la place. Le dessin doit quand même attendre onOverlayUpdate : gardez ici la dernière position dans des variables globales et dessinez le curseur là-bas.

Paramètres :

  • x, y — position en coordonnées de l’overlay.

  • xRelative, yRelative — déplacement depuis l’événement précédent, en coordonnées de l’overlay.

  • which — indice de la souris, de 0 à 3.

Exemple
cursorX = overlayGetWidth() // 2
cursorY = overlayGetHeight() // 2

function onMouseMoved(x, y, xRelative, yRelative, which)
    cursorX = x
    cursorY = y
end

function onOverlayUpdate()
    overlayClear()
    spriteDraw(reticle, cursorX, cursorY, true)
    return OVERLAY_UPDATED
end

2.52.7. onCollision

function onCollision(nodeA, nodeB, x, y, z, speed)
end

Appelé une fois pour chaque nouveau contact entre deux corps après un pas de la physique, et plus jamais pour une paire qui reste en contact. Une caisse qui atterrit, une balle qui heurte la borne, la voiture du joueur qui accroche un mur. Les contacts avec des déclencheurs sont signalés par onTrigger à la place. Les événements d’un pas sont transmis ensemble après celui-ci, avant que l’image ne soit dessinée.

Paramètres :

  • nodeA, nodeB — les nœuds des deux corps.

  • x, y, z — où ils se sont touchés, en unités du monde.

  • speed — la vitesse à laquelle ils se sont rencontrés, en unités du monde par seconde.

Depuis : 3.00. Voir aussi : onTrigger, bodyNew

Exemple
-- Les atterrissages brutaux font du bruit là où ils se produisent.
function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 and (nodeA == crate or nodeB == crate) then
        local channel = soundPlay(thudClip)
        if channel >= 0 then
            soundSetPosition(channel, x, y, z)
        end
    end
end

2.52.8. onTrigger

function onTrigger(trigger, other, entered)
end

Appelé quand un corps entre dans un déclencheur créé avec bodySetTrigger ou en sort, une fois à l’entrée et une fois à la sortie, quelles que soient les formes en jeu (un maillage ou une forme composée qui touche en plusieurs endroits compte toujours pour un seul corps). Les déclencheurs ne poussent jamais rien : c’est donc la façon de remarquer qu’un corps franchit une porte, atteint un point de contrôle ou tombe dans une zone mortelle.

Paramètres :

  • trigger — le nœud du corps déclencheur.

  • other — le nœud qui y est entré ou en est sorti.

  • entered — true à l’entrée, false à la sortie.

Depuis : 3.00. Voir aussi : bodySetTrigger, onCollision

Exemple
function onTrigger(trigger, other, entered)
    if trigger == finishLine and other == playerCar and entered then
        lap = lap + 1
        soundPlay(lapClip)
    elseif trigger == pit and entered then
        respawn(other)
    end
end

2.52.9. onNavArrived

function onNavArrived(agent)
end

Appelé quand un agent de navigation atteint la cible que lui a donnée navAgentMoveTo, une fois par arrivée, après la mise à jour de la navigation de l’image. Envoyez l’agent ailleurs, ou jouez son animation d’attente. Un script qui préfère interroger peut appeler navAgentIsArrived à la place.

Paramètres :

  • agent — le handle venant de navAgentNew.

Depuis : 3.00. Voir aussi : navAgentMoveTo, navAgentIsArrived

Exemple
-- Patrouiller entre des points de passage, indéfiniment.
function onNavArrived(agent)
    local guard = guards[agent]
    if guard then
        guard.waypoint = guard.waypoint % #guard.route + 1
        local next = guard.route[guard.waypoint]
        navAgentMoveTo(agent, next.x, next.y, next.z)
    end
end

2.52.10. onOverlayUpdate

function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Le seul callback où le dessin est permis. Singe l’appelle au plus une fois toutes les 15 millisecondes tant que le jeu n’est pas figé, en comptant à partir du début de l’appel précédent, si bien que le temps que prend le script lui-même est compris dans ces 15 millisecondes au lieu de s’y ajouter ; tout appel overlay*, spriteDraw, videoDraw, fontPrint ou similaire fait ailleurs n’apparaîtra pas à l’écran et risque de corrompre l’overlay. Renvoyez OVERLAY_UPDATED (1) quand l’overlay a changé, pour que Singe le compose de nouveau sur la vidéo, ou OVERLAY_NOT_UPDATED (0) quand rien n’a changé, pour que la composition précédente soit réutilisée ; ne rien renvoyer compte comme OVERLAY_NOT_UPDATED. L’affichage est de toute façon redessiné chaque fois qu’une nouvelle image vidéo arrive ou qu’une scène 3D est activée : la valeur renvoyée est donc une optimisation pour les écrans statiques. Après son retour, le moteur efface les valeurs derrière keyboardGetLastDown et keyboardGetLastUp. Dans le modèle à fil d’exécution, Framework.singe définit lui-même cette fonction pour reprendre singeMain et renvoie toujours OVERLAY_UPDATED ; ne la définissez pas en plus.

Renvoie : OVERLAY_UPDATED ou OVERLAY_NOT_UPDATED.

Exemple
function onOverlayUpdate()
    if not hudDirty then
        return OVERLAY_NOT_UPDATED
    end
    overlayClear()
    fontPrint(20, 20, "SCORE " .. score)
    fontPrint(20, 44, "LIVES " .. lives)
    spriteDraw(reticle, cursorX, cursorY, true)
    hudDirty = false
    return OVERLAY_UPDATED
end

2.52.11. onShutdown

function onShutdown()
end

Appelé une fois quand le script se termine, que ce soit par singeQuit, le contact de sortie, la fermeture de la fenêtre, scriptExecute ou scriptPush, après la dernière image et avant que l’état Lua ne soit abandonné. Il n’est pas appelé par singeReload. Enregistrez ici les réglages et libérez les sprites, les sons, les polices et les vidéos que le script a chargés ; le moteur arrête ensuite chaque son et libère ce qui reste, si bien qu’un handle oublié n’est pas une fuite, mais un déchargement explicite garde l’ordre d’arrêt sous le contrôle du script. N’appelez pas singeQuit depuis ici.

Voir aussi : singeQuit, soundUnload, scriptPush

Exemple
function onShutdown()
    saveHighScores()
    spriteUnload(reticle)
    fontUnload(hudFont)
    soundUnload(shotClip)
    soundUnload(coinClip)
end

2.52.12. onSoundCompleted

function onSoundCompleted(channel)
end

Appelé avec le numéro du canal chaque fois qu’un canal s’arrête : quand son clip se termine, quand la dernière boucle finit, et quand soundStop ou soundFullStop l’interrompt, si bien qu’un script qui enchaîne des sons depuis ici doit savoir quels canaux il a arrêtés lui-même. Le mélangeur note l’arrêt sur son propre fil d’exécution et le moteur transmet le callback sur le fil d’exécution du jeu entre deux images ; pendant que la touche pause tient le jeu figé, les avis attendent, et ils sont abandonnés quand un script se termine ou se recharge. Jusqu’à 64 fins sont mises en file entre deux images ; au-delà, celles d’une même image sont perdues.

Paramètres :

  • channel — le numéro de canal qu’a renvoyé l’appel à soundPlay.

Exemple
-- Jouer la liste de lecture musicale dans l'ordre, indéfiniment.
function onSoundCompleted(channel)
    if channel == musicChannel and not musicStopped then
        track = track % #playlist + 1
        musicChannel = soundPlay(playlist[track])
    end
end

2.52.13. singeMain

function singeMain()
    while true do
        singeYield()
    end
end

Le point d’entrée du modèle à fil d’exécution. Quand un script la définit, Framework.singe l’enveloppe dans une coroutine et installe un onOverlayUpdate qui reprend la coroutine une fois par image, si bien que la fonction se déroule comme une ligne droite de logique de jeu qui appelle singeYield() (un alias de coroutine.yield) partout où elle veut laisser passer une image. Tout ce qui est dessiné avant de céder la main atterrit sur l’overlay de cette image. Revenir de singeMain appelle singeQuit ; une erreur à l’intérieur arrête le jeu avec une trace de la pile d’appels. Les callbacks d’entrée, de son, de physique et de navigation sont toujours déclenchés entre les reprises, si bien qu’un jeu à fil d’exécution peut les mélanger avec de l’interrogation.

Exemple
function singeMain()
    showTitle()
    while credits == 0 do
        singeYield()
    end
    for level = 1, #levels do
        playLevel(levels[level])
        if lives == 0 then
            break
        end
    end
    showGameOver()
end

2.53. Compatibilité avec Hypseus

Tout ce qui se trouve dans cette section existe pour qu’un jeu écrit pour Hypseus Singe tourne sans modification. Rien de tout cela n’est recommandé pour un nouveau jeu. Préférez l’appel Singe que nomme chaque entrée : c’est celui qui continuera de gagner des fonctionnalités, et il ne traîne ni les échelles, ni les ordres d’arguments, ni les réponses figées d’un autre moteur.

Hypseus Singe enregistre dans son moteur quelques noms auxquels Singe répond plutôt depuis Singe/Framework.singe, pour qu’un jeu écrit pour Hypseus tourne sans modification. Chacun n’est défini que si le moteur ne le fournit pas déjà, si bien qu’une future implémentation dans le moteur l’emporte. keyboardCatchQuit est documenté sous Clavier ; setOverlayLinearScale et setOverlayOnTop sont de vrais appels du moteur sous Overlay ; mainBezelLoaded et les sept appels scoreBezel sont de vrais appels du moteur sous Bezel ; getFValue, ratioGetX et ratioGetY sont de vrais appels du moteur sous Ligne de commande ; joyMouseEnable est un vrai appel du moteur sous Joystick ; allowSocketCall et getUserString sont de vrais appels du moteur sous Singe, et drawTransparent sous Sprite ; et toute la famille music est désormais un ensemble de vrais appels du moteur sous Musique. Les six noms spriteAnim ci-dessous sont de simples alias posés après l’enveloppement hérité des fonctions de sprite, si bien qu’ils prennent l’ordre d’arguments qu’adopte le reste de la famille des sprites : celui d’Hypseus (handle en dernier) avec LEGACY_SPRITE_ARGS, et celui de Singe 3.00 (handle en premier) sans.

Fonction Fournie par Framework.singe sous la forme

setOverlaySize(preset [, width, height])

overlaySetResolution avec une taille choisie : 1 est la taille de la vidéo du disque, 3 est 360x240, 4 est la taille donnée (ignorée quand elle manque, comme dans Hypseus) et toute autre valeur, 2 compris, est la moitié du disque sur les deux axes. Sans disque, discGetWidth et discGetHeight donnent la taille du canevas, qui est ce dans quoi dessine un jeu sans disque.

setOverlayResolution(width, height)

Un alias de overlaySetResolution. Hypseus enregistre une même fonction sous les deux noms.

rewriteStatus()

Fonction bouchon qui renvoie false. Dans Hypseus, elle indique si les chemins des ressources sont réécrits pour une installation -espath ; le système de fichiers virtuel de Singe trouve les fichiers d’un jeu là où ils ont été installés, si bien que rien n’est réécrit et que le jeu garde son propre dossier de ressources.

hypseusGetHeight()

Un alias de singeGetHeight.

hypseusGetWidth()

Un alias de singeGetWidth.

takeScreenshot()

Un alias de singeScreenshot. Hypseus refuse une deuxième capture d’écran dans les cinq secondes ; Singe n’a pas une telle limite.

mouseHowManyReal()

Un alias de mouseHowMany. Hypseus compte les vraies souris à part de celles qu’il dérive d’une manette ; Singe n’a pas de souris dérivées, si bien que son compte est déjà celui des vraies.

spriteAnimGetFrame(spr)

Un alias de spriteGetFrame.

spriteAnimIsPlaying(spr)

Un alias de spriteIsPlaying.

spriteAnimLoop(loop, spr)

Un alias de spriteLoop.

spriteAnimPause(spr)

Un alias de spritePause.

spriteAnimPlay(spr)

Un alias de spritePlay.

spriteAnimSetFrame(frame, spr)

Un alias de spriteSetFrame.

2.54. Non implémenté et hérité

Une poignée de fonctions de l’API sont conservées pour la compatibilité des scripts, et celles marquées « Sans effet » ne font rien. On peut les appeler sans danger ; elles écrivent simplement un message de trace et rendent la main. Préférez les remplacements indiqués pour le nouveau code.

Fonction État Remplacement

discChangeSpeed

Sans effet

 — (servait à la lecture à vitesse variable sur un vrai matériel LD)

discSearchBlanking

Sans effet

 — (servait à masquer l’écran pendant un saut sur un vrai matériel LD)

discSkipBlanking

Sans effet

 — (même raison)

discSetFPS

Sans effet

La fréquence d’images est lue dans le fichier vidéo.

vldpGetHeight

Fonctionne

discGetHeight

vldpGetWidth

Fonctionne

discGetWidth

vldpSetVerbose

Sans effet

 — 

colorBackground(r,g,b)

Fonctionne

Préférez la forme à 4 arguments, colorBackground(r, g, b, a).

colorForeground(r,g,b)

Fonctionne

Préférez la forme à 4 arguments, colorForeground(r, g, b, a).

daphneGetWidth / daphneGetHeight / daphneScreenshot

Alias dans Framework.singe

Préférez les équivalents singe*.

discPauseAtFrame

Fonctionne (alias)

discSearch.

En outre, Framework.singe redéfinit random = { new = math.random } pour que les scripts d’avant 2.00 qui utilisent random.new() fonctionnent toujours. Le nouveau code doit utiliser math.random directement.