Kapitel 1. Spieleentwicklung

1.1. Lua

Singe verwendet die Programmiersprache Lua (http://www.lua.org), um die Spiellogik zu skripten. Lua ist schnell, schlank, objektorientiert, einfach zu benutzen und wird in der Spielebranche tatsächlich eingesetzt. Dieses Buch bringt dir Lua nicht bei; Programmieren lernen mit Singe, im selben Download wie dieses, tut es, von null bis zu einem fertigen Spiel in einunddreißig Lektionen. Video-Tutorials zu Lua gibt es auf dem YouTube-Kanal von Kangaroo Punch, und die Referenz der Sprache selbst steht unter http://www.lua.org.

1.2. Grundregeln

  • Singe ist plattformübergreifend. Dinge, um die du dich unter Windows normalerweise nicht kümmern musst, sind wichtig. Dateinamen unterscheiden zwischen Groß- und Kleinschreibung — MyScript.singe und myscript.singe sind nicht dieselbe Datei. Verwende außerdem UNIX-Pfadtrenner — / statt \. Das macht deinen Code sauberer (keine doppelt maskierten Backslashes) und funktioniert überall, wo Singe unterstützt wird.

  • Wähle einen unverwechselbaren Namen für deinen Spielordner. Verwende keine Leerzeichen.

  • Verwende das mitgelieferte Singe-Framework. Kopiere das Framework nicht in deine Spielskripte. Indem du das mitgelieferte Framework einbindest, hilfst du der künftigen Kompatibilität, wenn Singe aktualisiert wird. Beginne (oder beende) dein Spielskript mit:

    dofile("Singe/Framework.singe")
  • Halte dein Spiel in sich abgeschlossen. Wenn du auf einem Framework eines Drittanbieters aufbaust oder Code zwischen deinen Spielen teilst, kopiere ihn in deinen Spielordner. Verweise nie auf einen Ordner neben deinem Spiel; die einzige Datei außerhalb deines Spiels, die ein Skript laden darf, ist Singe/Framework.singe. Ein Spiel in einer Datei (siehe Spiele in einer Datei) packt genau einen Ordner, und ein Spiel, das über ihn hinausgreift, lässt sich nicht packen.

  • Halte dich aus dem Ordner Singe/ heraus. Er wird von Singe verwaltet, und alles, was dort hinzugefügt oder geändert wird, kann künftig gelöscht werden.

  • Liefere eine games.dat mit. Das ist für neue Benutzer äußerst wichtig. Es gibt zwar andere Frontends und auf Singe basierende Menüsysteme, aber es ist unerlässlich, dass du Daten für das eingebaute Menüsystem mitlieferst. Fast alle Supportanfragen gehen auf fehlende oder fehlerhafte games.dat-Dateien zurück.

  • Verteile keine unnötigen Dateien. Liefere nie Singe-Programmdateien oder von Singe mitgelieferte Skripte mit deinem Spiel aus. Liefere keine aus den Videos erzeugten Indexdateien mit.

1.3. Neu laden während der Arbeit

Starte das Spiel mit --reload (-R), und Singe überwacht jede ungepackte Skriptdatei, die das Spiel geladen hat. Speichere eine Änderung an einer davon, und das Spiel beginnt einen Moment später wieder bei seinem Skript: Alles, was das Skript angelegt hat, verschwindet (Sprites, Sounds, Schriftarten, Videos, GUIs, die 3D-Szene, die Physik, Emitter, das Overlay kehrt zu seiner Standardgröße zurück, die Effektlautstärke und die Maus zu ihrem Zustand beim Start), die Engine bleibt (das Fenster, die GPU, die Controller), die Disc steht wie beim Start wieder auf ihrem ersten Frame, und das Skript läuft von vorn, sodass ein 52-MB-Modell in der Zeit wieder auf dem Bildschirm ist, die sein Laden dauert, statt in der Zeit, die der Start von Singe dauert. Eine Taste oder ein Knopf, die über das Neuladen hinweg gedrückt bleiben, werden ignoriert, bis sie losgelassen werden, wie bei einem frischen Start. F5 lädt auf Wunsch neu, und ein Skript kann es mit singeReload() anfordern. Gepackte Spiele haben nichts, was sich überwachen ließe; die Option ist für ein Spiel in einem Ordner. Ein Skriptfehler beim Neuladen wird ausgegeben, und das Spiel bleibt leer, bis das nächste Neuladen ihn behebt; die Datei bleibt überwacht, das Speichern der Korrektur genügt also. Weil das Neuladen denselben Abbau durchläuft wie das Beenden, zeigt sich jedes Leck eines Skripts zuerst hier.

1.4. Debuggen in ZeroBrane Studio

ZeroBrane Studio ist eine kostenlose Lua-IDE, und Singe bringt mit, was es braucht, um ein Spiel darin zu starten und zu debuggen: Haltepunkte, Einzelschritte, die Fenster Stack und Beobachtungspunkte, ein Spiel, das stillhält, solange es angehalten ist, einen Halt in der IDE, wenn ein Fehler das Spiel gleich beenden würde, und Autovervollständigung mit Tooltips für die ganze API, auf Englisch, Französisch, Italienisch, Deutsch oder Spanisch. Die Debugger-Hälfte ist MobDebug, in Singe eingebaut und von --debug gestartet, sodass ein Spiel keine eigene Zeile dafür braucht; alles andere, was das Protokoll von MobDebug spricht, kann sich auf dieselbe Weise verbinden.

1.4.1. Einrichten

Singe entpackt ein Paket für ZeroBrane Studio in seinen Support-Ordner, als Singe/ZeroBrane/singe.lua, und hält es von einer Version zur nächsten aktuell. Sag ZeroBrane Studio mit einer einzigen Zeile in dessen user.lua (Bearbeiten > Einstellungen > Einstellungen: Nutzer), wo es liegt, und starte es dann neu:

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

Singe erscheint dann unter Projekt > Lua Interpreter, dazu Projekt > Mit Singe debuggen und ein Singe-Knopf in der Werkzeugleiste, die ein Spiel in einem Schritt unter dem Debugger starten. .singe-Dateien öffnen sich als Lua, .rml-Dokumente als XML und .rcss-Stylesheets als CSS. Mach den Ordner des Spiels zum Projekt (Projekt > Projektverzeichnis > Wählen…​). Das Paket sucht Singe in diesem Ordner und den drei darüber, nimmt den neuesten Build für deinen Rechner und sucht danach im PATH; findet es keinen, fragt es beim ersten Start eines Spiels und merkt sich die Antwort. Projekt > Singe-Programm wählen…​ nimmt ein anderes, und path.singe = "/path/to/Singe" in user.lua geht beidem vor.

1.4.2. Starten und debuggen

Projekt > Starten (F6) startet das Spiel, und Projekt > Debugging starten (F5) startet es unter dem Debugger. Das Skript ist die Startdatei des Projekts, wenn eine festgelegt ist (klick sie im Projektbaum mit rechts an und wähl Als Startdatei definieren), und sonst die gerade bearbeitete Datei; ist das eines der Module des Spiels statt einer .singe-Datei, startet stattdessen die einzige .singe-Datei des Projekts. Singe startet in dem Ordner, in dem sein Programm liegt, so wie das Menü es starten würde, sodass Singe/Framework.singe und jeder Name relativ zu diesem Ordner sich auflösen wie immer, und der Eintrag des Spiels in games.dat liefert sein Video und seine Einstellungen. Projekt > Kommandozeilenparameter…​ fügt eigene Optionen hinzu, darunter -v und ein Video für ein Spiel ohne Eintrag.

Klick in den Rand, um einen Haltepunkt zu setzen. Das Spiel hält dort an, seine lokalen Variablen im Fenster Stack, das Fenster Beobachtungspunkte wertet Ausdrücke aus, und Schritt hinein (F10), Überspringen (Shift+F10) und Schritt raus (Ctrl+F10) verhalten sich wie in jedem Lua-Programm, auch innerhalb von singeMain. Projekt > Unterbrechung hält ein Spiel an, wo immer es gerade ist. Solange das Spiel angehalten ist, pausieren die Disc, jedes Video und jeder Sound genau wie bei der Pause-Taste und laufen danach an derselben Stelle weiter.

Wenn ein Fehler das Spiel gleich beenden würde — ein Lua-Fehler, oder ein Engine-Aufruf, der etwas bekommt, womit er nichts anfangen kann --, hält die IDE vorher an, in der Debugger.singe des Singe-Ordners, und das Fenster Ausgabe sagt, was schiefgegangen ist. Das Fenster Stack behält unter dieser Datei die eigenen Frames des Skripts, mit ihren lokalen Variablen, wie sie waren. Mach weiter, und das Spiel endet, wie es geendet hätte, mit dem Fehler und einem Traceback im Fenster Ausgabe; ein Doppelklick auf eine Zeile des Tracebacks öffnet die Datei an dieser Stelle.

Das Spiel läuft mit --reload, sodass das Speichern eines Skripts das Spiel neu startet und den Debugger mit ihm, Haltepunkte und alles. Projekt > Singe neu laden, wenn sich ein Skript ändert schaltet das ab.

1.4.3. Autovervollständigung und die Referenz

Die Autovervollständigung bietet jede Funktion, jeden Callback und jede Konstante der API an, und ein Tooltip zeigt die Argumente und den ersten Absatz des Eintrags. Projekt > Analyseroutine (Shift+F7) kennt die API ebenfalls und meldet deshalb einen falsch geschriebenen Aufruf statt jedes Aufrufs. Die Spracheinstellung von ZeroBrane Studio wählt die Sprache der Tooltips: language = "fr" in user.lua ergibt Französisch, und ebenso geht es mit Italienisch (it), Deutsch (de) und Spanisch (es). Klick einen Namen mit rechts an und wähl In der Singe-Referenz nachschlagen, um seinen Eintrag in einem Browser zu öffnen; Hilfe > Singe-Referenz öffnet den Anfang. Beides braucht den Dokumentations-Download neben Singe entpackt, als Singe-Docs-v3.00 oder Singe-Docs-v3.00-fr und so weiter, wobei der in der Sprache von ZeroBrane Studio zuerst genommen wird; singe = { reference = "/path/to/Reference.html" } in user.lua nennt einen anderen.

1.4.4. Einen Automaten debuggen

Der Debugger arbeitet über ein Netzwerk hinweg. Öffne auf dem Rechner mit ZeroBrane Studio den Ordner des Spiels als Projekt und wähl Projekt > Debugserver starten. Starte auf dem Automaten das Spiel mit --debug=HOST, wobei HOST der Name oder die Adresse dieses Rechners ist; der Port ist 8172, sofern --debug=HOST:PORT nichts anderes sagt, und der erste Rechner muss Verbindungen auf ihm annehmen. Ein Automat, der seine Spiele aus dem Menü startet, kann stattdessen debug = "HOST:PORT" in seiner Einstellungsdatei tragen, und jedes Spiel, das er startet, verbindet sich, das Menü eingeschlossen. Die IDE hält jedes an seiner ersten Zeile an, wo Fortsetzen (F5) es loslaufen lässt; debugger.runonstart = true in user.lua lässt es gleich bis zum ersten Haltepunkt laufen. Der Automat meldet seine eigenen Pfade, die ZeroBrane Studio beim ersten Halt den Dateien des Projekts zuordnet, sodass derselbe Spielordner auf beiden Rechnern alles ist, was es braucht. Hört niemand zu, spielt sich ein Spiel wie gewohnt, sobald der Verbindungsversuch aufgibt, was nicht länger als zwei Sekunden dauert.

1.4.5. Grenzen

  • Debugge ein Spiel ungepackt, aus seinem Ordner. Ein gepacktes .game hat keine Dateien auf der Platte, die die IDE öffnen könnte.

  • Ein Fehler in singeMain hält in Framework.singe an, das singeMain als Koroutine ausführt; die Meldung nennt die Zeile deines Skripts.

  • Solange die IDE das Spiel angehalten hält, zeichnet sich das Fenster nicht neu, und das Schließen wartet, bis du weitermachst. Prozess anhalten (Shift+F5) beendet das Spiel sofort.

  • Singe hält ein Skript, das nie zurückkehrt, an, wenn sein Fenster geschlossen wird, aber nicht unter dem Debugger, dem das Skript gehört, solange es läuft; Unterbrechung findet heraus, wo es festhängt.

1.5. Deterministischer Testmodus

--deterministic ist eine Testhilfe, keine Art zu spielen. Die Option lässt die Engine die echte Zeit ganz ignorieren: Statt den Rechner zu fragen, wie spät es ist, läuft die Engine auf einer virtuellen Uhr, die sich um einen festen Schritt — standardmäßig 15 Millisekunden — genau einmal pro Frame weiterbewegt. Alles, was nach der Zeit getaktet ist, folgt dieser Uhr: Physikschritte, Sprite- und Modellanimation, Partikel, Navigation, die Animationen und Übergänge der GUI, os.clock(), singeGetTicks() und ein bloßes os.time() (ein Spiel, das seinen Zufallsgenerator beim Spielstart nach der Uhr initialisiert, initialisiert ihn nach der virtuellen und zieht also bei jedem Lauf dieselben Zahlen; os.time mit einer Datumstabelle rechnet diese um, wie Lua es immer getan hat). Auch die Disc folgt ihr: Während sie läuft, bleibt jeder Videoframe so viele Engine-Frames lang stehen, wie seine Darstellungszeit auf dieser Uhr wert ist (zwei oder drei beim Standardschritt für eine Disc mit dreißig Frames pro Sekunde), wie im echten Spiel, und eine pausierte oder per Sprung versetzte Disc bleibt, wo sie hingestellt wurde. Der Zufallsgenerator von Lua und der eigene der Engine werden mit einer festen Zahl initialisiert. Nichts wartet auf irgendetwas, das Spiel läuft also so schnell, wie der Rechner es zulässt.

Der Sinn des Ganzen ist, dass ein Screenshot, der bei einer festen Frame-Nummer aufgenommen wird, in jedem Lauf dasselbe Bild ist. Ohne diesen Modus ist Frame 40 jedes Mal ein anderer Moment — die Physik hat eine andere Zahl von Schritten gemacht und die Disc steht auf einem anderen Videoframe — und so können sich zwei Läufe desselben unveränderten Spiels um eine Million Pixel unterscheiden, und eine echte Änderung kann sich in diesem Rauschen verstecken.

Der Preis ist alles, was von der echten Zeit abhängt. Audio spielt weiterhin nach der eigenen Uhr des Geräts, die keine virtuelle Uhr erreicht, der Ton driftet also vom Bild weg und sagt nichts aus — es sei denn, der Lauf wird mit --record aufgezeichnet; dann wird der Ton zusammen mit dem Bild Schritt für Schritt in den Speicher gemischt, sodass eine so gemachte Aufnahme Frame für Frame und Sample für Sample exakt ist (siehe singeRecordStart). Auch die Bildrate sagt nichts aus, und ebenso wenig alles, was ein Spiel in Sekunden misst. Melde nie eine Leistungszahl, ein Audioproblem oder ein Problem mit der Zeitsteuerung aus einem Lauf in diesem Modus, und liefere nie einen Launcher aus, der ihn verwendet.

Die Zahl, die die Option trägt, wenn sie eine trägt, ist sowohl die Größe des Schritts als auch der Startwert der Zufallsgeneratoren, 1 bis 1000:

Singe --deterministic          der Standardschritt von 15 ms, Startwert 15
Singe --deterministic=20       ein Schritt von 20 ms, Startwert 20

Zwei Läufe mit derselben Zahl sind identisch; zwei Läufe mit verschiedenen Zahlen sind jeder für sich wiederholbar, aber nicht gleich, und so verlangt ein Test einen anderen, aber ebenso reproduzierbaren Lauf. Die Option lässt sich wie jede andere als deterministic in einer Einstellungsdatei setzen.

1.5.1. Referenz-Screenshots

Die Szenen in testScripts machen jeweils einen oder zwei Screenshots bei einer festen Frame-Nummer und beenden sich selbst, in diesem Modus ergeben sie also einen Satz Referenzbilder, mit dem sich eine spätere Änderung Pixel für Pixel vergleichen lässt. Um sie aufzunehmen, starte jede Szene mit der Option und behalte, was im Datenordner landet:

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

Die Szenen, die diese Schleife auslässt, wollen eigene Optionen, dieselben, die ihnen die Tabelle in testScripts/README.md gibt: scene12 läuft ganz ohne Disc, scene17 mit der Disc und scene20 mit -C 720x480, alle drei mit SDL_GPU_DRIVER=nothing; scene27 bis scene35 wollen -x 1280 -y 720 -C 1280x720 und keine Disc; scene46 will -g '10 5'; und scene47 will --bezeldir=testScripts/bezels --bezel=cabinet.png. Kopiere nach jedem Lauf die singe*.png-Dateien aus data/testScripts heraus, denn der nächste Lauf nummeriert seine Screenshots wieder ab null.

Einen späteren Build zu vergleichen heißt dann, dieselben Befehle auszuführen und nach dem Unterschied zu fragen, der null sein muss:

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

1.6. Wo Dateien liegen

Pfade in einem Skript sind relativ zu dem Ordner, aus dem Singe gestartet wurde, nicht zum Skript. Verwende die globale Variable DIR, die Framework.singe auf den eigenen Ordner des Skripts setzt, damit ein Spiel funktioniert, egal wo es installiert ist:

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

Alles, was Singe schreibt, landet im Datenordner (singeGetDataPath()), data/ neben den Spielen, sofern --datadir nichts anderes sagt, damit ein Spiel auch auf schreibgeschützten Medien liegen kann. Singe 2.x schrieb Spielstände und Einstellungen in den eigenen Ordner des Spiels; ein Spiel, das das noch tut, scheitert an einer schreibgeschützten Installation, halte also jedes io.output unter singeGetDataPath().

1.7. Dein Spiel verpacken

Ein fertiges Spiel wird als eine einzige .game-Datei ausgeliefert, die als Nächstes beschrieben wird. Mehr ist nicht nötig: Der Spieler kopiert die Datei neben die Singe-Programmdatei, und das Menü listet sie auf. Singe installiert keine Archive mehr.

1.8. Spiele in einer Datei

Ein Spiel kann eine einzige Datei sein. singe --pack schreibt einen Spielordner in eine SQLite-Datenbank, und Singe startet das Spiel von dort: Skripte, Sprites, Sounds, Schriftarten, Frame-Dateien und Video werden alle direkt aus der Datenbank geladen, und das Spiel zu installieren heißt, die Datei neben die ausführbare Datei zu kopieren. Das Menü listet jede .game-Datei auf, die es neben den Spielordnern findet.

Singe --pack MyGame MyGame.game       Den Ordner MyGame in MyGame.game packen
Singe MyGame.game                     Den ersten games.dat-Eintrag darin starten
Singe --entry=2 MyGame.game           Seinen zweiten Eintrag starten
Singe --unpack MyGame.game MyGame     Die Dateien wieder herausschreiben
Singe --patch MyGame.game fixes       Dateien aus einem Ordner (oder einer Patch-Datenbank) ersetzen

Nichts an einem Spiel muss sich ändern, damit es gepackt werden kann. Jeder Name, den ein Skript verwendet, ob über dofile, require, io.open und seine Verwandten, spriteLoad, soundLoad, fontLoad, videoLoad, eine Frame-Datei oder eine controls.cfg, geht durch ein und dieselbe Suche. Bei einem ungepackten Spiel ist diese Suche das gewöhnliche Dateisystem, relativ zu dem Ordner, aus dem Singe gestartet wurde, genau wie zuvor. Bei einem gepackten Spiel wird ein Name an drei Stellen versucht, in dieser Reihenfolge, und der erste Treffer gewinnt:

  1. Ein ungepackter Ordner, der wie die Datenbank ohne ihre Endung heißt (MyGame/ neben MyGame.game). So bearbeitest du ein gepacktes Spiel weiter, und so moddet ein Spieler eines: Dateien, die dort abgelegt werden, haben Vorrang vor den gepackten Kopien.

  2. Der Datenordner des Spiels, unter files/. Alles, was ein Spiel mit io.output oder io.open(name, "w") schreibt, landet hier, sodass eine gespeicherte game.cfg Vorrang vor dem gepackten Original hat und die Datenbank nie beschrieben wird.

  3. Die Datenbank selbst.

Innerhalb einer Datenbank werden Namen ohne Rücksicht auf Groß- und Kleinschreibung abgeglichen, mit beiden Pfadtrennern und relativ zur Wurzel des Spiels. Eine führende Komponente, die dem eigenen Ordnernamen des Spiels gleicht, wird ignoriert, sodass MyGame/Cfg/game.cfg, Cfg/game.cfg und DIR .. "Cfg/game.cfg" alle dieselbe Datei finden. Der Name der Datenbank selbst (MyGame.game, mit oder ohne nachgestellten Trenner) ist die Wurzel des Spiels, so wie . von innen. Namen, die mit Singe/ oder mit dem Datenordner beginnen, bleiben im Dateisystem; Singe/Framework.singe und singeGetDataPath() funktionieren wie immer, und ein solcher Name darf .. verwenden, solange er unterhalb dieses Präfixes bleibt (die controls.cfg im obersten Datenordner wird so gefunden). Jeder andere relative Name mit einer ..-Komponente führt innerhalb eines gepackten Spiels nirgendwohin: io.open gibt nil mit einer Meldung zurück, dass der Name aus dem Spiel hinausreicht, lfs.attributes gibt nil zurück, und spriteLoad und seinesgleichen melden die Datei als fehlend. Die Wurzel des Spiels ist ein Ordner, keine Datei: io.open darauf gibt nil zurück, und lfs.mkdir und lfs.rmdir lehnen sie ab. lfs.dir auf einem gepackten Ordner listet die Vereinigung der drei Stellen auf, ohne Rücksicht auf Groß- und Kleinschreibung sortiert; wenn sich eine ungepackte und eine gepackte Datei nur in der Schreibweise unterscheiden, wird die Schreibweise der ungepackten aufgelistet. lfs.attributes auf einer gepackten Datei antwortet so wie das echte lfs: mit der ganzen Tabelle bei einem Argument, mit einem Feld nach Namen (ein unbekannter Name löst einen Fehler aus) oder indem es eine Tabelle von dir ausfüllt; eine fehlende Datei gibt nil, eine Meldung und die Fehlernummer zurück. require("name") findet name.lua, name/init.lua oder name.singe unter dem Ordner des Skripts, dann unter der Wurzel des Spiels.

io.open, io.lines und io.input geben bei einem Namen, der nur in der Datenbank liegt, eine Datei von Singe selbst zurück statt einer von Lua. Das Datei-Handle von Lua ist ein FILE * von C, und eine Datenbankzeile ist keine Datei, deshalb hieß das Lesen einer solchen Zeile früher, sie neben das Spiel zu schreiben und diese Kopie zu öffnen; das Handle von Singe liest die Zeile dort, wo sie liegt. Es versteht alles, was das von Lua versteht — read mit jedem Format ("a", "l", "L", "n" und einer Byteanzahl), lines, seek, close, flush und setvbuf — io.type nennt es eine Datei, io.read und io.close nehmen es an, und es schließt sich selbst, wenn es vom Garbage Collector eingesammelt wird oder wenn eine <close>-Variable ihren Gültigkeitsbereich verlässt. Der einzige Unterschied ist, dass Schreiben darauf ein Fehler ist, denn was es liest, liegt in der Datenbank, und die Datenbank wird nie beschrieben. Ein Spiel, das eine Datei schreibt, bekommt genau wie zuvor eine echte in seinem Datenordner, und ebenso jeder Name, der nicht gepackt ist. testScripts/packedIo ist der Test, der all das am eigenen Verhalten von Lua misst; sein Kopfkommentar sagt, wie man ihn ausführt.

Der Packer lehnt einen Ordner ab, der keine games.dat hat, der controls.dat, Framework.singe, eine Datei mit der Endung exe, sh, bat oder cmd oder eine Datei ohne Endung enthält, deren Name mit singe beginnt, der auf oberster Ebene einen Eintrag hat, der wie der Ordner selbst heißt (das würde die Regel vom eigenen Ordner mehrdeutig machen), oder dessen Skripte und Datendateien mit .. aus dem Spiel hinausgreifen; er meldet jede solche Datei, mit der Zeile. Zwei Dateien, deren Namen sich nur in der Groß- und Kleinschreibung unterscheiden, können nicht beide gepackt werden. Veraltete .index-Dateien werden übersprungen. --unpack lehnt eine Datenbank ab, deren gespeicherte Namen außerhalb des Zielordners landen würden (ein absoluter Pfad, ein Laufwerksbuchstabe oder eine ..-Komponente). Ein Spiel, das auf den Ordner eines anderen Spiels verweist (ein gemeinsames Framework daneben), muss diesen Ordner zuerst hineinkopieren. Bevor die Datenbank festgeschrieben wird, wird ihre games.dat geprüft: Jeder Eintrag braucht ein SCRIPT, und jedes SCRIPT, VIDEO, CABINET, MARQUEE und ATTRACT, das er nennt, muss eine Datei in der Datenbank sein (oder unter Singe/); ein falscher Pfad wird mit dem Titel des Eintrags gemeldet, und das Packen wird verweigert. --patch führt dieselbe Prüfung am gepatchten Spiel durch, sodass auch ein Patch keinen ins Leere zeigenden Pfad hinterlassen kann.

--patch nimmt entweder einen Ordner, der wie das Spiel aufgebaut ist und dessen Dateien die gepackten ersetzen, oder eine .patch-Datei, die --pack aus einem solchen Ordner erzeugt (Singe --pack fixes MyGame-1.1.patch; ein Patch braucht keine games.dat). Dateien, die der Patch nicht nennt, bleiben unberührt. So oder so ist die Änderung eine einzige Transaktion: Das Spiel bleibt intakt, wenn sie unterbrochen wird. Ein Patch kann auch eine Tabelle removed(path) mitbringen, die zu löschende Dateien nennt. Eine .patch lässt sich wie ein Spiel entpacken, aber sie kann nicht gestartet werden, und das Menü ignoriert sie.

Ein Patch, der eine große Datei durch eine kleine ersetzt, lässt den Platz, den der alte Inhalt belegt hat, in der Datenbank zurück, wo SQLite ihn für das Nächste behält, was geschrieben wird, statt ihn zurückzugeben. Für einen Patch, der ein Skript ändert, ist das in Ordnung, und für einen Entwickler, der ein Video ein Dutzend Mal neu packt, verschwenderisch: Die .game kann am Ende ein Mehrfaches der Größe ihres Inhalts haben. Deshalb sieht sich --patch den freien Platz an, sobald die Transaktion festgeschrieben ist, und wenn es mindestens ein Megabyte davon gibt, verdichtet es die Datenbank und sagt, wie viel es zurückgewonnen hat:

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

Das Ergebnis hat aufs Byte genau die Größe eines frischen Packens derselben Dateien. Das Verdichten schreibt die ganze Datei neu, deshalb wird es übersprungen, wenn es wenig zu gewinnen gibt. Nichts sonst in Singe braucht das; ein Spiel wird immer nur vom Packer geschrieben.

Der Datenordner eines gepackten Spiels ist nach der Datenbank benannt und dann nach dem Ordner des Skripts darin: MyGame/ für eine MyGame.game, deren Skript an ihrer Wurzel liegt, unter dem Datenordner (standardmäßig data/MyGame/), also dort, wo ihn auch das ungepackte MyGame/MyGame.singe hat, sodass Spielstände und Einstellungen zwischen einer ungepackten und einer gepackten Installation geteilt werden; ein in einem Unterordner gepacktes Skript (Game/Main.singe) bekommt MyGame/Game/. Auch der Videoindex kommt dorthin.

Dieser Ordner gehört dem Spiel, nicht dem Namen seiner Datei. Ein Spiel mit einer GAME_ID in seiner games.dat kennzeichnet den Ordner als seinen eigenen, sobald es zum ersten Mal dorthin schreibt, mit einer kleinen Datei package.id, die die Kennung enthält, und findet ihn von da an über diese Kennung: Benenne MyGame.game um oder verschiebe sie in einen anderen Ordner, und sie benutzt weiterhin MyGame/. Ein anderes Spiel, dessen Datei ebenfalls MyGame.game heißt, bekommt einen eigenen Ordner, MyGame- gefolgt von den ersten acht Zeichen seiner Kennung. Ein Ordner aus der Zeit davor trägt keine Kennzeichnung und geht an das erste Spiel dieses Namens, das läuft. Ein Spiel ohne GAME_ID hat nur seinen Dateinamen, an dem es zu erkennen ist; zwei solche Spiele mit demselben Dateinamen teilen sich also einen Ordner, wie schon immer.

Frühere 3.00-Builds gaben einem gepackten Spiel, dessen Skript in einem Unterordner lag, den Datenordner Game/ unter der Basis, den sich jedes Archiv mit diesem Aufbau teilte. Die Spielstände eines solchen Spiels gehören jetzt unter MyGame/Game/; verschiebe sie von Hand. Frühere 3.00-Builds behielten außerdem den eigenen Ordner des Spiels bei, den, unter dem seine games.dat das Skript nennt, sodass eine aus MyGame/ gepackte MyGame.game nach MyGame/MyGame/ schrieb; verschiebe, was dort liegt, eine Ebene nach oben.

Wenn Singe ein Spiel aus einer Datenbank startet, übergibt das Menü CONTAINER im games.dat-Eintrag, den es startet; das Feld wird vom Menü gesetzt, nie von Hand.

Für deine eigenen Daten gibt require("sqlite3") Skripten die Anbindung lsqlite3 an dasselbe SQLite, das die Engine verwendet. Lege Datenbanken, die das Spiel schreibt, in singeGetDataPath() ab:

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 findet einen Namen so wie io.open, eine Datenbank kann also im Spiel mitgeliefert werden — Level-Tabellen, Dialoge, Gegenstandslisten — und lässt sich trotzdem öffnen, wenn das Spiel gepackt ist. Nur zum Lesen geöffnet, wird eine gepackte Datenbank dort gelesen, wo sie liegt, ohne dass etwas kopiert wird:

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

Zum Schreiben geöffnet, was die Voreinstellung von sqlite3.open ist, wird eine gepackte Datenbank einmal in den Datenordner des Spiels kopiert, unter files/ wie alles andere, was ein gepacktes Spiel schreibt, und die Kopie wird geöffnet. Von da an bezeichnet der Name die Kopie, ob nur zum Lesen oder nicht, und das gepackte Original wird nie verändert. Die Datenbank eines ungepackten Spiels öffnet sich genau wie zuvor an Ort und Stelle. testScripts/packedSql ist der Test; sein Kopfkommentar sagt, wie man ihn ausführt.

Das Dateiformat, für alle, die Werkzeuge schreiben: drei Tabellen. meta(key, value) enthält version (1), gamedir (den Namen des gepackten Ordners), chunk (die Chunk-Größe in Bytes, 4194304) und packer. assets(path, name, size, data) hat eine Zeile pro Datei, wobei path der kleingeschriebene Schlüssel mit Schrägstrichen ist und name die Schreibweise des Autors; Dateien, die nicht größer als die Chunk-Größe sind, stehen in data, größere haben data NULL und liegen in chunks(path, chunk, data) als fortlaufend nummerierte Stücke. Singe öffnet die Datenbank nur lesend und unveränderlich, sodass es von schreibgeschützten Medien läuft und nie ein Journal daneben anlegt.

1.9. Ereignisgesteuert …​ oder nicht?

Traditionell verwendete Singe ein ereignisgesteuertes Programmiermodell — Singe kümmert sich um alles und ruft deinen Code nur auf, wenn es dir etwas mitteilen oder den Bildschirm aktualisieren muss. Das ist effizient und entspricht der Arbeitsweise der meisten Lua-basierten Spiel-Engines, kann aber umständlich sein. Seit Singe 2.10 gibt es ein neues Thread-Modell („threaded“), mit dem du prozeduralen Code schreiben kannst.

1.9.1. Ereignisgesteuert

Beim ereignisgesteuerten Programmiermodell steuert Singe die Hauptschleife des Programms und bestimmt die Reihenfolge der Ausführung. Singe kümmert sich automatisch um alle Einzelheiten des Decodierens und Darstellens von Video und Audio. Es verwaltet Controller, Mäuse und Tastatureingaben. Wenn Singe etwas Spielspezifisches braucht, ruft es einen Teil deines Skripts auf. Das einfachste Singe-Skript, das alle vorhandenen Callbacks zeigt, sieht so aus:

-- Singe-Spielgerüst.

-- Das Singe-Framework laden.
dofile("Singe/Framework.singe")

-- Deklariere hier alle globalen Variablen, die du brauchst.

function onControllerMoved(axis, value, which)
    --[[
        Meldet, welche Controller-Achse bewegt wurde, und ihren aktuellen Wert.
        (Bereich: -32768 bis 32767.) Das wird für analoge Geräte verwendet.
        Digitale Eingaben werden von onInput und onKey behandelt.
    --]]
end

function onInputPressed(what, device)
    --[[
        Im Tastaturmodus MODE_NORMAL werden Eingabeereignisse hier gemeldet, sobald
        die Taste oder der Knopf zuerst gedrückt wird. Eine vollständige Liste der
        Tasten, Knöpfe und Controller steht in Singe/Framework.singe. Bei MODE_FULL
        wird dieses Ereignis mit dem Keysym der gedrückten Taste aufgerufen. Kam der
        Schalter von einer Maus oder einer Lightgun, ist device der Index dieses Geräts
        (0 für das erste), so wie Hypseus ihn übergibt, damit ein Spiel mit zwei Lightguns
        seine Spieler unterscheiden kann; bei einer Taste oder einem Pad ist es nil.
    --]]
end

function onInputReleased(what, device)
    --[[
        Im Tastaturmodus MODE_NORMAL werden Eingabeereignisse hier gemeldet, wenn
        die Taste oder der Knopf losgelassen wird. Eine vollständige Liste der Tasten,
        Knöpfe und Controller steht in Singe/Framework.singe. Bei MODE_FULL wird
        dieses Ereignis mit dem Keysym der losgelassenen Taste aufgerufen. device ist
        wie bei onInputPressed.
    --]]
end

function onKeyPressed(key, scancode)
    --[[
        Im Tastaturmodus MODE_FULL werden Eingabeereignisse hier gemeldet, wenn die
        Taste gedrückt wird. Sowohl der Keysym als auch der Scancode werden geliefert.
        Eine Liste der verfügbaren Scancodes steht in Singe/Framework.singe.
    --]]
end

function onKeyReleased(key, scancode)
    --[[
        Im Tastaturmodus MODE_FULL werden Eingabeereignisse hier gemeldet, wenn die
        Taste losgelassen wird. Sowohl der Keysym als auch der Scancode werden
        geliefert. Eine Liste der verfügbaren Scancodes steht in Singe/Framework.singe.
    --]]
end

function onMouseMoved(x, y, xr, yr, which)
    --[[
        Wird aufgerufen, wenn die Maus bewegt wird. Im Modus SINGLE_MOUSE werden
        absolute X- und Y-Werte sowie die relative Positionsänderung geliefert.
        Im Modus MANY_MOUSE ist nur die relative Änderung verfügbar, dazu die
        Angabe, welche Maus bewegt wurde.
    --]]
end

function onOverlayUpdate()
    --[[
        Dies ist die einzige Stelle, an der du gefahrlos Zeichenoperationen ausführen
        kannst. Wenn du einen Zielcursor anzeigen willst, musst du die Mausposition
        aus onMouseMoved in globalen Variablen speichern und diese dann hier
        verwenden, um den Cursor zu zeichnen.
    --]]

    -- Singe mitteilen, ob wir die Anzeige verändert haben oder nicht.
    return(OVERLAY_UPDATED)  -- Oder OVERLAY_NOT_UPDATED, wenn nichts gezeichnet wurde.
end

function onShutdown()
    -- Wird aufgerufen, wenn der Benutzer dein Spiel beendet. Gib hier geladene Ressourcen frei.
end

function onSoundCompleted(channel)
    -- Der Sound auf „channel“ ist gerade zu Ende gespielt.
end

-- Hinweis:  Es gibt kein Ereignis „onStartup“.
--           Code, den du beim Start brauchst, kann hier stehen.

1.9.2. Thread-Modell

Seit Singe 2.10 kannst du das klassische prozedurale Programmiermodell verwenden. Um dieses Modell zu nutzen, deklariere eine Funktion singeMain() und binde das Singe-Framework am Ende deines Programms statt am Anfang ein. Lua beherrscht kein echtes Multithreading, deshalb verlässt sich dieses Modell darauf, dass der Spieleentwickler kooperatives Multitasking betreibt, indem er überall dort singeYield() aufruft, wo Code nennenswert Zeit verbraucht. Wie beim ereignisgesteuerten Modell verwaltet Singe weiterhin alle Eingaben, die Videodecodierung und die Audiodecodierung. Ein Beispielprogramm im Thread-Modell sieht so aus:

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. Hybrid

Die beiden Modelle lassen sich frei kombinieren. Wenn singeMain existiert, installiert Framework.singe sein eigenes onOverlayUpdate, aber jeder andere Callback wird weiterhin ausgelöst: Definiere onInputPressed, onSoundCompleted oder onShutdown neben singeMain, und sie werden zwischen den Yields der Koroutine aufgerufen. Eine typische Aufteilung hält den Ablauf des Spiels prozedural und reagiert dabei auf Eingabe- und Audioereignisse:

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")

Definiere onOverlayUpdate in diesem Modell nicht selbst; zeichne stattdessen aus singeMain heraus. Ein Fehler, der in singeMain ausgelöst wird, beendet das Spiel mit einem Traceback, und eine Rückkehr aus singeMain beendet es sauber.

1.10. Pausieren

Jedes Spiel bekommt umsonst eine funktionierende Pause. Solange die Pausentaste aktiviert ist (die Voreinstellung), lässt ein Druck auf die Taste, die INPUT_PAUSE zugeordnet ist, die Engine die Disc, jedes geladene Video und jeden Sound anhalten, eine Anzeige PAUSED über den letzten Frame zeichnen und das Skript nicht mehr ausführen: kein onOverlayUpdate, kein Fortsetzen von singeMain, keine Eingabe-, Maus-, Controller- oder Sound-Callbacks. Timer, die auf Lua-Bibliotheken aufbauen, halten mit an, weil nichts sie ausführt. Ein erneuter Druck auf die Taste setzt alles fort, was lief, und das Skript macht dort weiter, wo es aufgehört hat. Nur die eigenen Schalter der Engine (Pause, Beenden, Screenshot, Mausfang) funktionieren im eingefrorenen Zustand noch.

Eingaben bleiben über das Einfrieren hinweg wahrheitsgetreu. Alles, was das Skript für gedrückt hält, wird beim Beginn der Pause mit onInputReleased (oder onKeyReleased in MODE_FULL) losgelassen, und was beim Ende der Pause noch tatsächlich gehalten wird, wird erneut gedrückt. Ein Joystick, der während einer Pause gehalten wird, bleibt nie hängen.

Ein Spiel, das sein eigenes Pausenverhalten will (ein Pausenmenü, einen Halt in der Handlung, den der Spieler nicht überspringen darf), ruft singeSetPauseKeyEnabled(false) auf. Die Taste wird dann als SWITCH_PAUSE an das Skript geliefert, und das Spiel steuert singeSetPauseFlag selbst, was die Medien anhält, ohne das Skript einzufrieren.

In MODE_FULL gehört die Tastatur ganz dem Spiel, Tasten, die den Schaltern der Engine zugeordnet sind, bewirken dort also nichts (ein p, das in eine Highscore-Eingabe getippt wird, muss ein p bleiben). Gamepad- und Mausknöpfe, die diesen Schaltern zugeordnet sind, funktionieren in beiden Modi weiter, da sie sich nicht tippen lassen.

1.11. games.dat

Die Datei games.dat ermöglicht es Singe, neue Spiele automatisch zu finden, wenn der Endbenutzer sie installiert. Diese Datei ist äußerst wichtig und muss jedem Singe-Spiel beiliegen. Lege games.dat in den obersten Ordner deines Spiels. Ein Beispiel mit mehreren Spielen:

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"
    },
    -- ... weitere Einträge ...
}

Die Schlüssel 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 und TIER liest die Engine, wenn das Menü (oder dein eigenes Skript, über scriptExecute / scriptPush) den Eintrag startet; sie haben Vorrang vor der Befehlszeile. Die Zeile VIDEO ist die Disc: Ein Eintrag, der eine nennt, ist ein Laserdisc-Spiel, und ein Eintrag, der sie weglässt oder leer lässt, läuft ohne Disc und kann CANVAS_X / CANVAS_Y setzen (Standard 720x480); siehe Spiele ohne Disc. AUDIO_SUFFIX = "-es" spielt <base>-es.ogg neben dem Video der Disc ab statt des Tons darin, für eine Veröffentlichung, deren andere Sprachen als eigene Dateien geliefert werden; das ist dasselbe, was --altaudio tut. LEGACY_SPRITE_ARGS = true führt ein für Singe 2.10 geschriebenes Spiel mit der alten Reihenfolge der Sprite-Argumente aus (siehe Umstieg von Singe 2.10). Die übrigen Schlüssel liest das Menü für die Anzeige.

REQUIRES sagt, was das Spiel von einem Rechner braucht, als Liste von Namen: "SCENE" (die 3D-Szene), "GUI" (GUI-Dokumente), "SHADOWS", "POST" (Bloom und die anderen Effekte, die Float-Renderziele brauchen), "SKIN" (geskinnte Modelle) und "MORPH" (Morph-Ziele). Kein REQUIRES bedeutet 2D. Das Menü kennzeichnet ein Spiel, das dieser Rechner nicht ausführen kann, und sagt warum, statt es zu starten, und du schreibst die Liste selten selbst: Die Engine bemerkt beim Laufen, was ein Spiel verwendet, meldet im Trace, wenn das Spiel etwas verwendet, das REQUIRES nicht aufführt, und --pack schreibt die Liste in einen Eintrag, der keine hat. TIER (0 bis 3) gibt an, wie viel Rechner das Spiel will; das Menü misst die Stufe dieses Rechners an seinem eigenen Hintergrund und kennzeichnet ein Spiel, das mehr will, als eines, das langsam laufen könnte. Siehe singeCapabilities.

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

Ein direkt gestartetes Skript, ob über seinen Namen oder seinen Ordner, wird genauso behandelt: Singe sucht eine games.dat im Ordner des Skripts und bis zu drei Ordner darüber, und wenn das SCRIPT eines Eintrags das gestartete Skript nennt (Pfade in Einträgen zählen ab dem Ordner über der games.dat, sodass Collection/games.dat das Skript als Collection/AsteroidPatrol.singe nennt), gelten die Schlüssel dieses Eintrags. Der eine Unterschied zum Start aus dem Menü ist der Vorrang: Eine auf der Befehlszeile eingegebene Option (--framefile, --disc, --stretch, --nomouse, --xresolution, --yresolution, --sindengun, --audio, --audiodelay, --altaudio, --canvas) behält ihren Wert, denn wer sie eintippt, meint sie so. Ein Wert aus einer Einstellungsdatei nicht: Er ist eine Voreinstellung, und der Eintrag beschreibt das Spiel besser (siehe Die Einstellungsdatei). Eine games.dat, die sich nicht ausführen lässt, wird bei einem direkten Start gemeldet und ignoriert.

1.12. Spiele ohne Disc

Singe setzt keine Laserdisc mehr voraus. Ein Spiel ist nur dann ein Laserdisc-Spiel, wenn es eine nennt: ein VIDEO in seinem games.dat-Eintrag oder --disc (oder ein --framefile) auf der Befehlszeile. Alles andere läuft ohne Disc, und die Welt ist eine Zeichenfläche statt eines Videoframes: CANVAS_X / CANVAS_Y in games.dat oder --canvas=WxH auf der Befehlszeile, standardmäßig 720x480, damit ein Spiel ohne Disc wie ein Laserdisc-Spiel in Standardauflösung aussieht, sofern es nichts anderes verlangt.

Ohne Disc zeichnet die Engine auf Schwarz, das Overlay ist wie üblich standardmäßig halb so groß wie die Zeichenfläche, und die Funktionen disc* und vldp* werden harmlos: discGetState meldet DISC_EJECTED, discGetFrame gibt 0 zurück, discGetWidth / discGetHeight geben die Zeichenfläche zurück, vldpGetPixel gibt Schwarz zurück, und die Transportaufrufe schreiben in den Trace und tun nichts. Alles andere — das Overlay, Sprites, Schriftarten, Sounds, zusätzliche Videos über videoLoad, die Eingabe und beide Programmiermodelle — ist identisch. Die globale Variable SINGE_DISC sagt einem Skript, als welche Art von Spiel es läuft.

1.13. GUI

Menüs, Optionsseiten, HUDs und die Highscore-Eingabe wurden früher aus fontPrint, overlayBox und einem selbst gebauten Cursor zusammengesetzt. Singe 3 bringt eine GUI mit: ein Dokument, geschrieben in RML (einem HTML-ähnlichen Markup) und gestaltet mit RCSS (einem CSS-ähnlichen Stylesheet), gesetzt und gezeichnet von RmlUi, mit Textumbruch, Flexbox, Nine-Slice-Panels aus deinen eigenen Grafiken, Übergängen, Animationen, Formularelementen und einem Fokusmodell, das ein Gamepad steuern kann. Eine GUI ist ein RmlUi-Kontext fester Größe, der in seine eigene Textur gerendert und neu gezeichnet wird, wann immer sich sein Bild ändert (siehe guiRefresh), und diese Textur kommt überallhin, wo eine Textur hinkann: mit guiDraw über das Overlay gelegt oder mit materialSetGui auf einem Material in der 3D-Szene gezeigt, sodass dieselbe Optionsseite flach auf dem Bildschirm und auf dem Monitor eines modellierten Arcade-Automaten funktioniert. Eine GUI braucht das GPU-Gerät, das die 3D-Szene verwendet, und ist deshalb auf einem Rechner ohne ein solches nicht verfügbar (siehe Leistung und Anforderungen); guiNew beendet das Skript, statt mit false zu antworten, frage also zuerst singeHasGpu, wenn dein Spiel ohne auskommt. Das mitgelieferte Menü tut genau das und zeichnet sich stattdessen ins Overlay, wenn die Antwort nein ist (siehe Die zwei Renderer). Jeder hier genannte Aufruf hat einen Eintrag im Abschnitt Gui der Referenz.

Die Sprachreferenz für RML und RCSS ist die eigene Dokumentation von RmlUi unter https://mikke89.github.io/RmlUiDoc/, und sie lohnt die Lektüre vor dem ersten Dokument; dieses Kapitel behandelt, was Singe obendrauf setzt.

1.13.1. Dokumente und Stylesheets

guiNew(width, height) erzeugt eine GUI und gibt ein Ganzzahl-Handle zurück; bis zu sechzehn können gleichzeitig existieren. guiLoad(gui, name) lädt ein RML-Dokument hinein, zeigt es an und gibt ein Dokument-Handle zurück (bis zu zweiunddreißig pro GUI); guiHide, guiShow und guiClose tun, was ihre Namen sagen, und guiDelete verwirft die GUI, ihre Dokumente und ihre Textur. Ein Dokument ist meist so groß wie seine GUI, und eine GUI ist meist so groß wie das Overlay, für eine Vollbildseite, oder so groß wie das Panel, für ein HUD-Element:

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

Der Dokumentname geht wie der eines Sprites durch das virtuelle Dateisystem, er kann also ungepackt auf der Festplatte oder in einem gepackten Spiel liegen, und er wird relativ zu dem Ordner aufgelöst, in dem Singe gestartet wurde; stelle also für Dateien, die mit deinem Spiel ausgeliefert werden, DIR voran, genau wie bei spriteLoad. Namen innerhalb eines Dokuments (das href eines Stylesheets, ein Bild in einem Decorator, das src eines Sprite-Sheets) werden relativ zu der Datei aufgelöst, die sie nennt, wie bei RmlUi, und dann über dieselbe Suche, sodass ein Dokument, sein Stylesheet und seine Bilder nebeneinander im Spielordner liegen und ein gepacktes Spiel sie alle findet. Zwei Arten von Namen werden genommen, wie sie sind: die eigenen Dateien der Engine unter Singe/ und absolute Pfade.

Dieselbe Regel, andersherum gelesen, lässt ein Dokument, das unter Singe/ liegt, die Dateien eines Spiels erreichen: Ein relativer Name wird vom eigenen Ordner des Dokuments aus aufgelöst, also ist von Singe/Menu.rml aus der Name ../Collection/cabinet.png die Datei Collection/cabinet.png im Spieleverzeichnis, und ein Name unter ../MyGame.game/ ist eine Datei in diesem gepackten Spiel. Das mitgelieferte Menü tut genau das für die Automaten- und Marquee-Grafik des gewählten Spiels und setzt aus Lua einen Bild-Decorator auf das Grafikfeld, sodass das Bild unabhängig von seiner Größe hineinpasst:

-- Menu.singe: das Bild eines Spiels in eines der Grafikfelder einpassen.
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

Ein RML-Dokument besteht aus einem <head> mit einem Titel, Links auf Stylesheets oder einem eingebetteten <style> und einem <body> aus Elementen. Ein minimales, mit dem mitgelieferten Theme:

<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 zeichnet nichts, dessen Größe ihm nicht mitgeteilt wurde, und jedes Element ist display: inline, bis ein Stil etwas anderes sagt; ein Stylesheet ist also nicht optional. Singe/gui.rcss ist das Theme, das die Engine mitliefert: Es gibt Body, Überschriften und Absätzen eine Größe und eine Farbe, macht div zu einem Block und gestaltet jedes Formularelement. Binde es zuerst ein und überschreibe, was du willst, in einem eigenen Stylesheet oder einem eingebetteten <style>; die spätere Regel gewinnt wie in CSS. Längen im Theme sind in dp angegeben, dem dichteunabhängigen Pixel von RmlUi, das bei der eigenen Größe der GUI ein Pixel ist.

Text braucht eine Schrift. Die Engine lädt Singe/FreeSansBold.ttf für jede GUI als Ersatzschrift (die Schrift, die jedes Zeichen liefert, das keine andere Schrift hat); ihr Familienname ist FreeSans und ihre Stärke fett, was die body-Regel des Themes verlangt. guiLoadFont(name) fügt eine der eigenen Schriften des Spiels für jede GUI hinzu, und guiLoadFont(name, true) macht sie stattdessen zur Ersatzschrift. Ein Dokument nennt eine Schrift über den Familiennamen in der Datei, nicht über den Dateinamen; lade Schriftarten also vor den Dokumenten, die sie verwenden:

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

Die RCSS-Effekte von RmlUi werden vollständig gezeichnet. Kinder eines abgerundeten oder transformierten Elements werden auf dessen Form beschnitten (eine scrollende Liste mit border-radius trifft ihren Rahmen an der Rundung), filter: opacity() blendet eine Gruppe als Ganzes aus (die Eigenschaft opacity blendet jedes Teil für sich aus, so wie RmlUi sie definiert), mask-image schneidet ein Element nach dem Alpha eines Bildes aus, box-shadow wirft harte oder weiche Schatten, und filter und backdrop-filter nehmen blur, drop-shadow, brightness, contrast, invert, grayscale, sepia, hue-rotate und saturate. Die Decorators linear-gradient, radial-gradient und conic-gradient (wiederholend oder nicht) werden als solche gezeichnet; die Panels, Buttons und Fortschrittsbalken des mitgelieferten Themes verwenden sie. Drei Grenzen: Der benutzerdefinierte Decorator shader wird nicht unterstützt (er wird mit einer Warnung abgelehnt), ein Verlauf trägt höchstens sechzehn Farbstopps (weitere werden verworfen), und Effekte verschachteln sich höchstens acht Ebenen tief (ein tieferes Element wird ohne eigene Ebene gezeichnet). Jeder Effekt wird über eine Ebene in der Größe der GUI gerendert und ein Weichzeichner über mehrere Durchgänge; beschränke sie auf einem Pi also auf wenige Elemente und behalte guiGetStats im Blick, das die Ebenen, Durchgänge und Bytes zählt, die ein Frame gekostet hat.

1.13.2. Themes

Ein Theme ist ein Ordner mit RCSS und Bildern, und ein Spiel liefert sein eigenes Aussehen so aus, wie es Sprites ausliefert. Die übliche Form ist ein Stylesheet, das nach Singe/gui.rcss eingebunden wird, die Klassen des Themes umgestaltet und eigene hinzufügt, mit den Grafiken daneben. Das mitgelieferte Theme definiert:

  • .panel — ein umrandeter, abgerundeter, durchscheinender Kasten mit Innenabstand, der Rahmen einer Seite oder eines Dialogs.

  • .list — ein scrollender Kasten, dessen div-Kindelemente Zeilen sind: Sie nehmen den Fokus an, werden bei Hover und Fokus hervorgehoben, und eine Zeile mit der Klasse selected bleibt hervorgehoben. Eine senkrechte Bildlaufleiste erscheint, wenn die Zeilen überlaufen.

  • .muted — gedämpfterer Text, für Hinweise und Statuszeilen.

  • Die Formularelemente: button und input.submit, input.text, input.password und textarea, input.checkbox und input.radio, input.range mit Schiene und Schieberegler, select mit Pfeil und Aufklappliste und progress mit seiner Füllung; jedes mit den Zuständen Hover, Fokus und aktiv, und jedes mit tab-index: auto fokussierbar, damit ein Gamepad es erreichen kann.

Ein Panel aus deinen eigenen Grafiken ist ein Nine-Slice-Decorator über einem Sprite-Sheet, und Animationen sind RCSS-Keyframes; ein Ladebalken, der sich von selbst füllt, braucht also überhaupt kein Skript:

@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. Ein Dokument skripten

Es gibt zwei APIs, und es hilft, genau zu wissen, welche welche ist. Die flachen gui*-Aufrufe im eigenen Stil von Singe erzeugen eine GUI, laden und zeichnen Dokumente, leiten Eingaben weiter und erreichen Elemente über ihre ID: guiGetValue(gui, doc, id) liest den Wert eines Formularelements oder das innere RML jedes anderen Elements als String; guiSetValue(gui, doc, id, value) schreibt einen; und guiSetHandler(gui, doc, id, event, function) ruft eine Lua-Funktion auf, wenn das Element ein Ereignis auslöst ("click", "change", "submit" oder jeder andere Ereignisname von RmlUi). Die Funktion erhält (gui, document, id, event, value), mit value als dem Wert des Elements als String im Moment des Ereignisses: der Text eines Textfelds, der Wert einer select-Option, ein Range-Element in der eigenen Formatierung von RmlUi ("48.000000"), das innere RML eines Buttons. Alles, was eine Seite im Alltag braucht, decken diese drei Aufrufe ab:

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)

Alles andere in einem Dokument ist die Lua-API von RmlUi, die im eigenen Lua-Zustand des Spiels läuft: Ein <script>-Block in einem Dokument sowie onclick und die anderen on*-Attribute laufen mit den globalen Variablen des Spiels und können deshalb deine Funktionen ebenso aufrufen wie die gui*-Aufrufe. Von der Skriptseite aus sind dieselben Objekte über die globale Variable rmlui erreichbar: Kontexte heißen nach ihren Handles gui0, gui1, …​, und Dokumente sind nach der id ihres <body> geschlüsselt; der Button oben ist also rmlui.contexts["gui0"].documents["options"]:GetElementById("go"), und :DispatchEvent("click", {}) darauf drückt ihn aus dem Skript heraus (nützlich für Tests, die ohne Maus laufen). Elemente, ihre Attribute, Klassen, Stile und Kinder, data-model-Bindungen, die eine Lua-Tabelle in ein Dokument spiegeln, und der Rest des Objektmodells sind beim Lua-Plugin von RmlUi unter https://mikke89.github.io/RmlUiDoc/ dokumentiert; guiSetHandler ist die Abkürzung über die ID, kein Ersatz. Ein Dokument, das über diese API geschlossen wird (document:Close()), vergisst die Engine, und sein Handle löst danach einen Fehler aus.

1.13.4. Eingabe

Eine neue GUI zeigt nur an, was für ein HUD oder ein Schild richtig ist; guiSetInput(gui, true) lässt sie Eingaben annehmen, und guiSetInput(gui, false) schaltet das wieder ab. Für eine GUI, die Eingaben annimmt:

  • Die Maus und eine Lightgun (die eine Maus ist) kommen in Overlay-Koordinaten an, umgerechnet über den Sinden-Rand und den Overscan-Maßstab, genau wie für onMouseMoved, im Modus MOUSE_SINGLE. Die Engine findet die GUI unter dem Zeiger — die letzte, die in diesem Frame dort flach gezeichnet wurde, liegt oben, und ansonsten eine Fläche in der Szene, deren Material eine zeigt (siehe unten) — und skaliert die Position in die eigenen Pixel dieser GUI. Ein Druck auf ein Element gehört der GUI; die linke, rechte und mittlere Taste klicken, und das Rad scrollt.

  • Tasten gehen an jede GUI, die Eingaben annimmt, und eine Taste, die ein fokussiertes Element verwendet hat (ein Zeichen in einem Textfeld, ein Pfeil, der den Fokus bewegt hat, die Eingabetaste auf einem Button), wird verbraucht. Solange ein Text- oder Passwortfeld oder eine textarea den Fokus hat, betreibt die Engine die Texteingabe von SDL, sodass getippter Text als Text ankommt, unter Beachtung des Tastaturlayouts und jeder Bildschirmtastatur oder IME.

  • Pad- und Mausschalter (die SWITCH_*-Belegungen des Frameworks von einem Gamepad- oder Mausknopf) werden in die Tasten übersetzt, die ein Dokument versteht: Die vier Richtungen werden zu den Pfeiltasten, INPUT_ACTION_1 ist die Eingabetaste und INPUT_ACTION_2 ist Esc. Ein Schalter, der einer Tastaturtaste zugeordnet ist, hat die GUI bereits als diese Taste erreicht.

Die Regel, die ein HUD sicher macht, ist, dass ein Ereignis, das ein Element verwendet hat, nie das Spiel erreicht: Eine verbrauchte Taste kommt nicht als onInputPressed oder onKeyPressed an, ein Klick auf einen Button kommt nicht als Mausschalter an, eine übersetzte Richtung, die den Fokus bewegt hat, kommt nicht als SWITCH_UP an. Alles, was ein Dokument nicht verwendet hat, fällt zu den üblichen Callbacks durch, sodass ein HUD, das Eingaben annimmt, den Feuerknopf trotzdem durchlässt und eine Seite, auf der nichts fokussiert ist, jede Taste durchlässt.

Fokus und Navigation sind Sache des Dokuments. Das mitgelieferte Theme gibt jedem Bedienelement und jeder .list-Zeile tab-index: auto, sodass Tab zwischen ihnen wechselt, die Eingabetaste das fokussierte Bedienelement auslöst und die Pfeiltasten mit den nav-Eigenschaften von RmlUi (nav-up, nav-down, nav-left, nav-right oder nav: auto für alle vier) zwischen Bedienelementen wechseln. Eine Seite für einen Automaten mit einem Stick und zwei Knöpfen will diese auf allem, was der Spieler erreichen soll:

button, .list div { nav: auto; }

1.13.5. Eine GUI in der Szene

materialSetGui(material, gui) zeigt die Textur einer GUI als Grundfarbtextur eines Materials, in jedem Frame aktualisiert, neben materialSetVideo und materialSetView: ein Monitor, eine Cockpitkonsole, ein Schild. Kombiniere es mit materialSetUnlit, wenn das Bild nicht schattiert werden soll, und lass es beleuchtet, wenn es schattiert werden soll. Sonst ändert sich nichts; das Material wird beleuchtet, überblendet und gespiegelt wie jedes andere, und dieselbe GUI kann im selben Frame flach über das Overlay gezeichnet werden.

sceneProbeGui(x, y) beantwortet, welche GUI auf der Fläche unter einem Overlay-Punkt liegt und wo darauf: ein Strahl von der Kamera durch den Punkt gegen jedes sichtbare Mesh, dessen Material eine GUI zeigt, der das Handle und das Pixel in den eigenen Koordinaten dieser GUI zurückgibt, oder nil, wenn der Punkt neben jeder solchen Fläche liegt. Die Engine stellt dieselbe Frage, wenn die Maus oder eine Lightgun auf die Szene zeigt und nichts flach Gezeichnetes unter dem Zeiger liegt, sodass ein Klick auf den Monitor in einem 3D-Automaten den Button darunter drückt, ohne dass ein Skript beteiligt ist; der Aufruf ist für ein Spiel da, das es selbst wissen will, für ein Laservisier, einen Hover-Effekt oder einen 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. Neuladen, Leistung und Grenzen

Eine GUI gehört dem Skript, das sie erzeugt hat. Beenden, scriptPush, scriptExecute und ein Neuladen (siehe Neu laden während der Arbeit) bauen jede GUI und jedes Dokument zusammen mit dem übrigen Zustand des Skripts ab, und das Skript erzeugt sie neu, wenn es läuft; nichts aus dem Objektmodell rmlui überlebt, halte diese Objekte also nicht in globalen Variablen, die ein Neuladen wiederverwenden würde.

Jede GUI wird in jedem Frame aktualisiert, ob sie irgendwo gezeichnet wird oder nicht, sodass ein Dokument seine Animationen und Skripte auch außerhalb des Bildschirms weiterlaufen lässt, und eine GUI, die nicht mehr gebraucht wird, sollte gelöscht statt nur versteckt werden. In ihre Textur neu gezeichnet wird sie nur, wenn sich ihr Bild ändert; eine Seite oder ein HUD, das stillsteht, kostet die GPU also fast nichts (siehe guiRefresh). Die Kosten eines Frames, der sich ändert, bestimmen die Größe der Textur und die Komplexität des Dokuments: Auf einem Desktop ist eine Vollbildseite billig, auf einem Raspberry Pi halte eine GUI auf der Größe des Overlays oder kleiner und ziehe eine GUI mit mehreren Dokumenten mehreren GUIs vor. Jede Schrift kostet einen Atlas pro Größe, in der sie verwendet wird; eine Seite, die eine Schrift in drei Größen verwendet, zahlt also für drei Atlanten, und ein Dutzend Größen sind ein Dutzend. Sechzehn GUIs können gleichzeitig existieren, jede mit zweiunddreißig Dokumenten, und sechzehn guiDraw-Aufrufe werden pro Frame berücksichtigt.

Was ein Dokument zeigen kann und was nicht:

  • Bilder kommen aus Dateien. Bilder, Sprite-Sheets und Bild-Decorators laden PNG und die anderen Formate, die Singe liest, von der Festplatte oder aus einem gepackten Spiel. Ein Dokument kann kein Singe-Sprite, kein Video, nicht die 3D-Szene und nichts zeigen, was während des Spiels gezeichnet wird, und ein Skript kann ihm keine Pixel übergeben. Andersherum geht es: Die Textur einer GUI kommt mit materialSetGui auf ein 3D-Material.

  • Decorators: image, text, tiled-horizontal, tiled-vertical, tiled-box, ninepatch, der zweifarbige gradient (und seine Namen horizontal-gradient und vertical-gradient) sowie linear-gradient, radial-gradient und conic-gradient mit ihren repeating--Formen, mit höchstens sechzehn Farbstopps. Der benutzerdefinierte Decorator shader wird abgelehnt.

  • Filter: opacity, blur, drop-shadow, brightness, contrast, invert, grayscale, sepia, hue-rotate und saturate. Jeder andere Name wird mit einer Warnung im Trace ignoriert.

  • Ebenen: Filter, opacity unter 1, Maskenbilder und Box-Schatten werden jeweils über eine Ebene in der Größe der GUI gezeichnet, und höchstens acht stapeln sich gleichzeitig; eine weitere darüber hinaus wird ohne ihre Ebene gezeichnet und damit ohne ihren Effekt.

  • Bilder über 64 MB werden abgelehnt.

  • RML und RCSS sind die von RmlUi, nah an HTML und CSS, aber nicht dasselbe: Es gibt Flexbox und kein CSS Grid, und ein Dokument wird in Lua geskriptet, über guiSetHandler und das Objekt rmlui, statt in JavaScript. Die eigene Dokumentation von RmlUi ist maßgeblich dafür, was die Sprachen enthalten.

1.13.7. Ein durchgearbeitetes Beispiel

Eine Optionsseite über der Disc: ein Panel aus dem mitgelieferten Theme mit einem Namensfeld, einem Lautstärkeregler, einer Schwierigkeitsliste und zwei Buttons, über das Overlay gezeichnet und mit der Maus oder dem Stick bedient. Das Dokument, options.rml, neben dem Skript:

<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>

Das Skript lädt es in eine GUI von der Größe des Overlays, verdrahtet die drei Elemente, die es interessieren, und zeichnet es in jedem Frame, bis der Spieler Start drückt; die Disc läuft die ganze Zeit darunter:

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)
    -- Hier kommt nur an, was die Seite nicht verwendet hat: nichts, solange sie
    -- den Fokus hat, alles, sobald sie versteckt ist.
    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

Dieselbe Seite auf dem Bildschirm eines modellierten Automaten sind die fünf Zeilen aus Eine GUI in der Szene anstelle von guiDraw, und ein Klick auf den Monitor drückt den Button darunter.

1.14. Untertitel

Ein Spiel kann eine SubRip-Untertiteldatei mitliefern und Singe sie beim Abspielen über der Disc anzeigen lassen. Drei Aufrufe erledigen die ganze Arbeit: srtLoad liest die Datei, srtEnable schaltet sie ein und srtPosition legt fest, wo die Zeilen stehen. srtClear nimmt wieder weg, was gerade angezeigt wird. Die Funktion stammt aus Hypseus Singe, und die vier Aufrufe sind die von dort.

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

1.14.1. Das Dateiformat

SubRip (.srt) ist eine reine Textdatei aus nummerierten Cues:

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.

Jeder Cue besteht aus einer Nummer auf einer eigenen Zeile, dann einer Zeile mit zwei durch -→ getrennten Zeitstempeln, dann einer oder mehreren Textzeilen, dann einer Leerzeile. Ein Zeitstempel hat die Form HH:MM:SS,mmm: Stunden, Minuten und Sekunden durch Doppelpunkte getrennt, die Millisekunden nach einem Komma. Die Cue-Nummer wird gelesen und verworfen, die Nummern müssen also weder in der richtigen Reihenfolge noch überhaupt korrekt sein.

Der Parser ist absichtlich nachsichtig an den Stellen, an denen eine von Hand bearbeitete Datei schiefgeht. Wagenrückläufe sowie führende und nachgestellte Leerzeichen werden von jeder Zeile entfernt, sodass eine unter Windows geschriebene Datei unverändert lädt. Ein Cue, dessen Zeitzeile kein -→ enthält oder dessen Zeitstempel sich nicht parsen lassen, wird übersprungen, und die Datei wird weiter geladen. Ein Cue ohne Text wird übersprungen. Die Zeilen eines Cues werden mit Zeilenumbrüchen verbunden und so angezeigt, wie sie geschrieben sind, und <, > und & erscheinen als sie selbst auf dem Bildschirm, statt als Markup verstanden zu werden.

Was nicht unterstützt wird: Die Positionskoordinaten, die manche Werkzeuge an die Zeitzeile anhängen, werden ignoriert (srtPosition bestimmt die Höhe), und die gelegentlichen <i>- und <b>-Tags von SubRip werden als Text angezeigt statt befolgt. Cues dürfen sich zeitlich überschneiden; der zuletzt begonnene gewinnt.

srtLoad antwortet mit false und lädt nichts, wenn die Datei nicht gelesen werden kann, wenn sich nichts darin parsen lässt oder wenn keine Disc da ist — eine kaputte Datei ist also ein false, auf das ein Spiel reagieren kann, und kein Absturz. In jedem dieser Fälle gibt es eine Warnung aus, die die Datei nennt.

1.14.2. Die Zeitsteuerung

Zeitstempel werden beim Laden der Datei in Frame-Nummern der Disc umgerechnet, mit der Bildrate der Disc, die zu diesem Zeitpunkt geladen ist, und mit diesen Frame-Nummern gleicht die Engine jeden gezeichneten Frame ab. Daraus folgen zwei Dinge.

Erstens: Ein Untertitel übersteht einen Sprung. Die Disc irgendwohin zu schicken — discSearch, discSkipForward, ein Einzelschritt, eine Frame-Datei, die in ein anderes Segment übergeht — bringt beim nächsten gezeichneten Frame den Cue auf den Bildschirm, der die Stelle abdeckt, an der sie gelandet ist, vorwärts wie rückwärts. Nichts muss neu geladen und keine Uhr zurückgesetzt werden.

Zweitens: Die Datei muss nach der Disc getaktet sein, nicht nach der Uhr. Eine .srt, die für ein Video mit einer anderen Bildrate erstellt wurde, landet an der falschen Stelle, und eine, die geladen wird, bevor die Disc geöffnet ist, lädt überhaupt nicht. Lade Untertitel nach der Disc, was bei einem gewöhnlichen Spiel heißt: aus dem Hauptteil des Skripts.

Ein Cue wird angezeigt, solange der Frame der Disc zwischen seinen beiden Frames liegt, beide eingeschlossen. Der Untertitel wird nur dann neu gezeichnet, wenn sich der Cue ändert, Untertitel kosten also nichts, solange eine Zeile steht.

1.14.3. Gestaltung

Die Zeilen sind ein RmlUi-Dokument, keine geblittete Textzeile, und werden deshalb so gestaltet wie eine GUI. Zwei Dateien werden im Singe-Ordner mitgeliefert und beim ersten Start neben den anderen entpackt:

  • Singe/subtitle.rml — das Dokument. Es hat ein einziges Element, #slot, in das die Engine den aktuellen Cue oder das aktuelle Banner schreibt.

  • Singe/subtitle.rcss — das Aussehen. .cue ist der Block, der die von srtPosition angeforderte Höhe als inline gesetztes top trägt; .cue .text ist der Textbalken darin, standardmäßig weiß auf einem dunklen, abgerundeten Feld, das sich an den Text schmiegt, statt sich über das ganze Bild zu spannen.

Beide werden bei jedem Start neu geschrieben, wie alles im Ordner Singe, Änderungen daran halten also nicht lange. Um das Aussehen zu ändern, liefert ein Spiel eigene Kopien aus: subtitle.rml neben seinem Skript, dessen Link auf ein eigenes Stylesheet zeigt (etwa subtitle.rcss daneben), und Singe zeichnet dann dieses Dokument statt seines eigenen; der Programm-Trace meldet das. Die Engine setzt immer nur den Inhalt von #slot und das top von .cue, alles andere — die Schriftart, die Größe, die Farben, das Feld, ein Rahmen, ein Schatten — gehört also in das Stylesheet des Spiels und übersteht ein Engine-Update. Das Dokument wird über das Bild gezeichnet, über dem Overlay und unter den GUIs im Bildschirmraum, folgt dem Videorechteck, wohin auch immer --scalefactor, --shiftx, ein Bezel-Ausschnitt oder --rotate es setzen, und nimmt keine Mauseingaben an, ein Klick geht also direkt hindurch.

overlayBanner verwendet dasselbe Dokument, sodass ein Banner und ein Untertitel gleich aussehen und ein Spiel, das eines von beiden umgestaltet, beide umgestaltet.

Auf einem Rechner ohne GPU gibt es überhaupt keine GUIs; srtLoad parst die Datei trotzdem und antwortet wahrheitsgemäß, und es wird nichts gezeichnet. Eine Warnung weist einmal darauf hin.

1.15. 3D-Szenen

Singe 3 zeichnet eine 3D-Szene zwischen dem Laserdisc-Video und dem 2D-Overlay. Alles, was du schon weißt, gilt weiterhin: Sprites, Text und das Overlay liegen über der Szene, und das Video scheint überall dort durch, wo der Hintergrund der Szene transparent ist. Ein Spiel, das nie eine 3D-Funktion aufruft, ist nicht betroffen, und ein Spiel ohne Disc (siehe Spiele ohne Disc) kann ganz und gar ein 3D-Spiel sein.

Die folgenden Abschnitte bauen eine Szene in der Reihenfolge auf, in der du eine schreiben wirst: Knoten, dann Meshes und Materialien, Lichter, die Kamera, das Aussehen des Frames als Ganzes, Modelle und schließlich das, was auf all dem aufsetzt. Jeder hier genannte Aufruf hat einen Eintrag in der Lua-API-Referenz.

1.15.1. Woraus eine Szene besteht

Alles in einer Szene ist ein Knoten in einem einzigen Baum, und Knoten 0 ist die Wurzel. Ein Knoten hat eine Position, eine Rotation und eine Skalierung relativ zu seinem Elternknoten, und er kann eine Sache tragen: ein Mesh mit einem Material, ein Licht, ein Sprite oder eine Textzeile. Ein geladenes Modell wird zu einem Teilbaum von Knoten unter einer Wurzel, sodass dieselben Aufrufe eine modellierte Figur und einen geskripteten Würfel gleichermaßen bewegen.

Die Szene ist rechtshändig, mit +Y nach oben und -Z nach vorn, wie glTF und der Export von Blender. Die Einheiten sind die, die deine Modelle verwenden, und die Grundkörper nehmen dieselben Einheiten; die Physik (siehe Physik) geht von Metern aus. Rotationen sind in Grad angegeben, als drei Euler-Winkel, die als Gieren, Nicken und Rollen angewendet werden, oder als Quaternion, wenn der Wert aus einem Modell stammt. Das eigene Vorne eines Knotens ist sein -Z: Die Kamera blickt daran entlang, Richtungs- und Spotlichter strahlen daran entlang, und nodeLookAt dreht es zu einem Punkt in der Welt.

Es gibt zwei Wege, eine Szene zu füllen, frei kombinierbar:

  • Aus dem Skript bauen, mit den Grundkörper-Meshes (meshBox, meshSphere, meshPlane, meshCylinder, meshCone, meshTorus, meshHeightmap) oder deinen eigenen Vertexdaten (meshNew), dazu Materialien, Lichter und eine Kamera.

  • Modelle laden, im binären glTF-2.0-Format (.glb) mit modelLoad, und sie dann mit modelInstance so oft platzieren, wie du willst. Blender, Maya, 3ds Max und jede größere Engine exportieren .glb.

Eine minimale Szene besteht aus einem Mesh, einem Licht und einer Kamera:

sceneEnable(true)
sceneSetBackground(0, 0, 0, 0)     -- Transparent: Die Disc ist hinter der Szene zu sehen.

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)      -- Ein Grad pro Frame um die eigene Y-Achse.
    return OVERLAY_UPDATED
end

sceneEnable(true) ist der eine Aufruf, den jedes 3D-Spiel macht, und auf einem Rechner, der kein 3D zeichnen kann, ist es der Aufruf, der scheitert (siehe Leistung und Anforderungen). Ohne Kamera wird die Szene von (0, 0, 5) aus mit Blick auf den Ursprung betrachtet, und ohne einen Aufruf für den Hintergrund ist der Hintergrund der Szene undurchsichtig schwarz.

1.15.2. Knoten

Die Transformation eines Knotens wird direkt gesetzt (nodeSetPosition, nodeSetRotation, nodeSetQuaternion, nodeSetScale) oder schrittweise verändert (nodeMove, nodeRotate), immer im Raum seines Elternknotens. nodeSetParent hängt einen Knoten um und behält dabei seine lokale Transformation; nodeGetWorldPosition liest, wo er gelandet ist, nachdem jeder Elternknoten mitgeredet hat. nodeSetVisible versteckt einen Knoten und alles unter ihm, und nodeDelete gibt ihn und seine Kinder frei, zusammen mit jedem Körper, Emitter oder Sound, der an ihnen hängt.

Namen kommen aus Modellen: nodeFind(name, root) findet ein Gelenk oder ein Teil über den Namen, den es in der Datei hatte, unter der als root angegebenen Instanz. Auch ein geskripteter Knoten kann einen Namen bekommen (nodeSetName), und diese Namen durchsucht nodeFind ohne Wurzel.

-- Ein Turm auf einem Panzer: Das Rohr ist ein Kind des Turms, der Turm eines der Wanne,
-- sodass das Drehen des Turms das Rohr mitnimmt und das Bewegen der Wanne beides.
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)          -- Den Zylinder entlang -Z legen.

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

Zwei Aufrufe verbinden die Szene und das Overlay. sceneProject(x, y, z) wandelt einen Weltpunkt in Overlay-Koordinaten um, sodass ein Namensschild oder ein Lebensbalken, der mit fontPrint gezeichnet wird, einem 3D-Objekt folgen kann. sceneUnproject(sx, sy, distance) geht den anderen Weg: der Weltpunkt so weit entlang des Strahls durch ein Overlay-Pixel, was zusammen mit physicsRaycast Mausauswahl ergibt.

function onMouseMoved(x, y, dx, dy, which)
    -- Die Maus zeigt entlang eines Strahls von der Kamera; was er trifft, ist das Ziel.
    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. Meshes und Materialien

Ein Mesh ist Geometrie; ein Material ist, wie es aussieht; ein Knoten verbindet je eines davon (nodeSetMesh(node, mesh, material)). Teile beide nach Belieben: Ein meshBox und ein Material können auf tausend Knoten sitzen, und genau dieses Teilen macht den Renderer schnell (siehe Leistung und Anforderungen). meshNew baut ein Mesh aus Tabellen von Positionen, Normalen, Texturkoordinaten und Indizes, wenn die Grundkörper nicht genügen.

Ein Material beginnt als Grundfarbe mit Alpha (materialSetColor) und dem Metallic-Roughness-Look von glTF: materialSetMetallic und materialSetRoughness von 0 bis 1. Eine Rauheit nahe 0 ergibt ein spiegelscharfes Glanzlicht und 1 eine matte Oberfläche; ein Metall färbt seine Glanzlichter und Spiegelungen mit seiner eigenen Farbe und hat keine eigene diffuse Farbe. Darüber hinaus:

  • materialSetEmissive lässt eine Oberfläche Licht in ihrer eigenen Farbe abgeben (ein Bildschirm, eine Lampe, heißes Metall); es beleuchtet keine anderen Dinge, erzeugt aber Bloom (siehe Das Aussehen des Frames).

  • materialSetUnlit zeigt die Farbe, wie sie ist, und ignoriert jedes Licht: HUD-Elemente in der Szene, das eingebaute Leuchten des Glases einer Glühbirne.

  • materialSetDoubleSided zeichnet die Rückseite offener Formen, etwa einer von unten gesehenen Ebene oder einer Fahne.

  • materialSetBlend lässt das Alpha zählen, für Glas, Geister und Wasser. Überblendete Meshes werden nach allem Undurchsichtigen gezeichnet, nach Entfernung sortiert, und werfen keine Schatten.

  • materialSetCutoff behält nur die Texel, deren Alpha den Schwellwert erreicht, und verwirft den Rest; so werden Blätter, Zäune, Gitter und Maschendraht gezeichnet: ein Quad, das meiste davon weg. Anders als das Überblenden braucht es keine Sortierung und wirft trotzdem einen Schatten, und der Schatten wird ebenfalls ausgeschnitten, sodass ein Baum Blätterschatten wirft statt des Schattens seines Quads. Was den Schwellwert übersteht, ist undurchsichtig: Ein halbtransparentes Texel wird entweder ganz behalten oder verworfen, nie überblendet, sodass nichts hinter der Szene (am sichtbarsten das Bild der Disc) ein Blatt einfärbt. Ein Schwellwert von 0 (die Voreinstellung) schaltet die Maskierung ab. Ein aus glTF geladenes Modell bringt seinen eigenen mit: MASK setzt den Schwellwert aus der Datei, BLEND schaltet das Überblenden ein, und OPAQUE tut keines von beiden.

Die Textur eines Materials kann das Bild eines beliebigen geladenen Sprites sein (materialSetTexture), die Laserdisc selbst oder ein geladenes Video (materialSetVideo), das Bild einer zweiten Kamera (materialSetView, siehe Die Kamera und Ansichten) oder ein GUI-Dokument (materialSetGui, siehe GUI). Ein modellierter Arcade-Automat kann die Disc auf seinem eigenen Bildschirm abspielen oder dort seine Optionsseite zeigen. Texturkoordinaten kommen aus dem Mesh; die Grundkörper bilden ein Bild einmal über jede Fläche ab, und materialSetTiling wiederholt es, was Boden und Wände wollen. Texturen haben Mipmaps und werden anisotrop gefiltert, sodass ein Boden bis in die Ferne scharf bleibt; materialSetFilter(material, FILTER_NEAREST) hält Pixel-Art stattdessen blockig.

local stone = materialNew()
materialSetTexture(stone, spriteLoad(DIR .. "flagstones.png"))
materialSetTiling(stone, 12, 12)             -- Zwölf Wiederholungen über die Ebene.
materialSetRoughness(stone, 0.9)

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

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

Vier weitere Maps geben einer Oberfläche Details, die ihrer Geometrie fehlen, und ein geladenes Modell bringt sie mit, wenn seine Datei sie hat:

  • materialSetNormalMap beugt die Beleuchtung mit einer Normal-Map im Tangentenraum, sodass Ziegel aus einer flachen Wand hervortreten. Eine Stärke über 1 übertreibt den Effekt.

  • materialSetOcclusionMap verdunkelt Ritzen, die das Umgebungslicht und der Himmel nicht erreichen.

  • materialSetMetallicRoughnessMap variiert Metallic und Roughness über die Oberfläche, gepackt auf die glTF-Art (Roughness in Grün, Metallic in Blau) und mit den eigenen Faktoren des Materials multipliziert; setze diese also auf 1, wenn die Map bestimmen soll.

  • materialSetEmissiveMap sagt, welche Teile leuchten, eingefärbt und skaliert durch 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)     -- Der Mörtel leuchtet orange.
Komprimierte Texturen

Ein PNG wird auf der GPU zu vier Bytes pro Texel decodiert, plus ein weiteres Drittel für seine Mipmaps; ein Level von der Größe von Sponza belegt auf diese Weise 390 MB an Texturen, mehr, als ein Raspberry Pi 4 mit seiner Anzeige teilt. Texturen, die als KTX2-Dateien ausgeliefert werden (Basis Universal, erzeugt von util/compressTextures.py aus PNGs oder aus einem ganzen .gltf), bleiben auf der GPU komprimiert, bei einem Viertel der Größe oder weniger, in dem Blockformat, das der Rechner hat: BC7 auf Desktops, ASTC auf Apple-GPUs und dem Pi 4, ETC2 auf jedem Chip mit OpenGL ES 3 (dem Mali jedes Handhelds, dem Pi unter GLES), BC3 auf älteren Karten und einfaches RGBA, wo es nichts anderes gibt, alles aus der einen Datei. Gib materialSetTexture und den Map-Aufrufen einen .ktx2-Namen anstelle eines Sprites, und ein Modell, dessen Datei KHR_texture_basisu verwendet, lädt sie von selbst. sceneGetStats meldet den belegten Texturspeicher, sodass du den Unterschied sehen kannst.

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

1.15.4. Lichter und Schatten

Bis zu acht Lichter leuchten gleichzeitig, und jedes ist ein Knoten, sodass Lichter sich wie alles andere an Eltern hängen und animieren lassen:

  • LIGHT_DIRECTIONAL ist eine Sonne: Nur ihre Richtung zählt, und alles wird gleich beleuchtet. Eine Intensität von 1 beleuchtet eine ihr zugewandte weiße Fläche weiß.

  • LIGHT_POINT ist eine Glühbirne, die mit der Entfernung schwächer wird, und lightSetRange stoppt sie jenseits einer Entfernung ganz. Ihre Intensität ist ihre Helligkeit an der Glühbirne selbst, die Hälfte davon in einer Einheit Abstand; eine Glühbirne, die einen Raum beleuchten soll, braucht also eine Zahl im zweistelligen Bereich.

  • LIGHT_SPOT ist ein Kegel mit einem inneren Winkel, der voll beleuchtet ist, und einem äußeren Winkel, an dem das Licht zu nichts verblasst ist (lightSetCone).

sceneSetAmbient fügt ein wenig Licht aus allen Richtungen hinzu, damit Schatten nicht schwarz sind; ein Himmel macht das besser (siehe Das Aussehen des Frames). Farben, die als 0 bis 255 angegeben werden, sind sRGB, wie alles andere in Singe, und werden beim Hereinkommen in lineares Licht umgerechnet, sodass ein Licht von 128, 128, 128 ein Viertel so hell ist wie Weiß, nicht halb so hell.

Jedes Licht kann weichkantige Schatten von allem Undurchsichtigen werfen (lightSetShadow). Richtungs- und Spotlichter werfen sie über eine Shadow-Map, Punktlichter über eine Cube-Map, die in jede Richtung reicht, sodass eine Glühbirne in dem sitzen kann, was sie beleuchtet (ein Raum, ein Lampenschirm, der Automat): Geschlossene Meshes werfen auch von ihren Rückseiten Schatten, und der Tiefenbereich des Schattens wird an die Schattenwerfer um das Licht herum angepasst. nodeSetShadow(node, false) befreit ein Mesh vom Schattenwerfen: das eigene Glas der Glühbirne, ein leuchtendes Schild, ein Namensschild. sceneSetShadowSize setzt die Auflösung der Map (256 bis 4096, Standard 1024) und tauscht Schärfe gegen Geschwindigkeit.

Der Schatten eines Richtungslichts wird entlang der Blickrichtung in Kaskaden aufgeteilt (sceneSetShadowCascades, standardmäßig drei), jede eine Map, die an einen Ausschnitt dessen angepasst ist, was die Kamera sieht, sodass Schatten in einem großen Level aus der Nähe scharf bleiben und trotzdem bis sceneSetShadowDistance reichen. Eine einzige Kaskade passt eine einzige Map an die ganze Szene an, was zu kleinen Szenen und orthografischen Kameras passt. Eine Ansicht (viewNew) zeichnet mit denselben Maps und nimmt für jeden Punkt die feinste Kaskade, die ihn abdeckt, sodass ein Monitor die Schatten zeigt, die das Fenster zeigt.

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)              -- Drei Kaskaden bis 80 Einheiten.

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)              -- Eine Cube-Map: sechs Durchgänge pro Frame.
nodeSetShadow(bulbGlass, false)         -- Das Glas um sie herum wirft nichts.

1.15.5. Die Kamera und Ansichten

Jeder Knoten kann die Kamera sein (cameraSet); sie blickt entlang ihres eigenen -Z, also richtet nodeLookAt sie aus, und unter einen bewegten Knoten gehängt wird sie zur Verfolgerkamera. cameraSetPerspective(fovDegrees, near, far) ist das Standardobjektiv; cameraSetOrthographic(height, near, far) zeichnet ohne Perspektive, für Diagramme, HUD-artige Szenen und Spiele in Seitenansicht. Halte near so groß, wie die Szene es zulässt, denn die Genauigkeit des Tiefenpuffers verteilt sich zwischen near und far.

local camera = nodeNew()
nodeSetParent(camera, car)
nodeSetPosition(camera, 0, 2.5, 7)      -- Hinter und über dem Auto, in seinem Raum.
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 300)

Eine Ansicht ist eine zweite Kamera, die in jedem Frame in eine Textur gerendert und auf einem Material gezeigt wird: ein Überwachungsmonitor, ein Rückspiegel, ein Portal, ein Bild im Bild. viewNew(width, height) erzeugt eine in dieser Auflösung, viewSetCamera gibt ihr einen Kameraknoten, und materialSetView legt ihr Bild auf ein beliebiges Mesh. Ansichten teilen die Schatten des Frames und lassen Bloom aus, und jede rendert die Szene noch einmal; halte sie also wenige und klein. Jede Ansicht dreht Billboards (siehe Sprites und Text in der Szene) zu ihrer eigenen Kamera und zeichnet transparente Materialien von ihr aus von hinten nach vorn, sodass ein Monitor Namensschilder von vorn und Glas in der richtigen Reihenfolge sieht.

local rearCamera = nodeNew()
nodeSetParent(rearCamera, car)
nodeSetPosition(rearCamera, 0, 1.2, -2)
nodeSetRotation(rearCamera, 0, 180, 0)      -- Blick nach hinten.
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)            -- Die Ebene zeigt nach oben; stell sie auf, dem Fahrer zugewandt.

1.15.6. Das Aussehen des Frames

Die Szene wird in linearem Licht beleuchtet. Farben, die du als 0 bis 255 angibst, sind sRGB und werden beim Hereinkommen decodiert, Texturen werden von der GPU beim Abtasten decodiert, Lichter addieren sich ohne Abschneiden, und am Ende des Frames bringt eine Tonkurve das Ergebnis zurück auf den Bildschirm. Was das in der Praxis bedeutet:

  • sceneSetExposure(stops) hellt den ganzen Frame auf oder dunkelt ihn ab wie die Belichtung einer Kamera: +1 verdoppelt das Licht, -1 halbiert es, sodass eine Höhle und ein Strand dieselben Lichter und Materialien teilen können.

  • sceneSetTonemap wählt die Kurve: TONEMAP_NEUTRAL (die Voreinstellung, die Farben dort lässt, wo glTF-Viewer sie lassen, und nur das hellste Licht komprimiert), TONEMAP_ACES (ein filmischer Look mit mehr Kontrast) oder TONEMAP_NONE (bei Weiß abschneiden).

  • sceneSetBloom(threshold, strength) lässt alles leuchten, was heller als der Schwellwert ist: die Sonne durch ein Fenster, eine Glühbirne, ein selbstleuchtendes Schild, eine Flamme. Das Leuchten wird aus dem Licht der Szene vor der Tonkurve genommen, sodass nur, was wirklich hell ist, Bloom erzeugt; ein Schwellwert von 1 ist Weiß.

Der Himmel und sein Licht

sceneSetSky(file) hüllt die Szene in ein äquirektanguläres Panorama. Ein Radiance-Bild .hdr behält seinen vollen Umfang; ein PNG oder JPEG funktioniert auch. Der Himmel wird hinter allem gezeichnet, und sofern nicht sceneSetEnvironment(false) gilt, beleuchtet er auch die Szene: Seine Gesamtfarbe aus allen Richtungen ersetzt das flache Umgebungslicht, und seine Spiegelung zeigt sich auf Metallen und glänzenden Oberflächen, scharf auf einem Spiegel und umso unschärfer, je höher die Rauheit. Ohne Himmel haben Metalle nichts zu spiegeln, und nur das Umgebungslicht und die Lichter formen sie. sceneSetSkyIntensity skaliert den Himmel und sein Licht zusammen, sodass ein Panorama für Mittag und Abenddämmerung dient.

Nebel

sceneSetFog(r, g, b, near, far) blendet alles, Partikel eingeschlossen, zwischen zwei Entfernungen zu einer Farbe hin aus. Der Himmel wird nie vernebelt; passe also die Farbe des Nebels an den Horizont des Himmels an, und der ferne Rand der Szene verschwindet darin.

sceneSetSky(DIR .. "harbor.hdr")
sceneSetSkyIntensity(0.8)
sceneSetFog(190, 200, 215, 40, 160)        -- Die Farbe des Himmels am Horizont.
sceneSetExposure(-0.5)                     -- Etwas dunkler, als die Sonne es machen würde.
sceneSetBloom(1.0, 0.35)                   -- Nur, was heller als Weiß ist, leuchtet.

1.15.7. Modelle und Animation

modelLoad nimmt eine .glb über denselben spielrelativen Namen, den spriteLoad nimmt, und eine gepackte .game trägt sie mit. Die Datei muss in sich abgeschlossen sein: Meshes, Skins, Animationen und Texturen alle in der einen Datei, was der Standardexport von Blender ist. Ein Modell, das auf eine .bin oder ein Bild daneben verweist, wird mit einer Meldung abgelehnt, die die Datei nennt, aus demselben Grund, aus dem ein gepacktes Spiel in sich abgeschlossen sein muss. Materialien verwenden das Metallic-Roughness-Modell mit KHR_materials_emissive_strength und KHR_texture_basisu; eine Textur, die über einen zweiten Satz Texturkoordinaten adressiert wird, liest den ersten Satz, und KHR_texture_transform wird ignoriert, jeweils mit einer Zeile im Trace des Programms. Ein Skin kann bis zu 128 Gelenke haben. Das Laden ist der teure Teil; modelInstance platziert dann eine Kopie des Knotenbaums des Modells, so oft du willst, und jede Instanz teilt die Meshes und Materialien der Datei. modelDelete gibt das Modell frei; Instanzen behalten ihre Knoten, nackt.

local foxModel = modelLoad(DIR .. "Fox.glb")
local pack = {}
for i = 1, 6 do
    local fox = modelInstance(foxModel)
    nodeSetScale(fox, 0.02)                -- Die Datei ist in Zentimetern.
    nodeSetPosition(fox, i * 1.5 - 5, 0, 0)
    pack[i] = fox
end

Die Animationen eines Modells listet modelGetAnimations auf, und gesteuert werden sie pro Instanz mit animationPlay(node, nameOrIndex, loop, speed, fade) auf dem Wurzelknoten der Instanz, dazu Aufrufe zum Pausieren, Fortsetzen, Stoppen und Springen. Knotenanimation (Dinge, die sich bewegen), Skinning (Figuren, die sich verformen) und Morph-Ziele (Blend Shapes: Gesichter, Lippensynchronität, Muskelwölbungen) funktionieren alle. Animationen schreiten mit der echten Zeit fort und halten an, während das Spiel pausiert ist. Ein Morph-Gewicht lässt sich auch aus dem Skript mit nodeSetMorph setzen, nach Name oder Nummer, auf dem Knoten, der das Mesh trägt.

Ein fade in Sekunden blendet von dem über, was gerade lief, sodass ein Gehen ohne Ruck zu einem Laufen wird. Wenn nichts lief (nach animationStop oder wenn eine Ragdoll abgeschaltet wurde), beginnt die Überblendung bei der Pose, in der die Knoten sind, sodass sich eine Figur von dort aufrichtet, wo sie gefallen ist. Bis zu vier weitere Clips können gleichzeitig auf Ebenen über der Basis laufen (animationPlayLayer), jeder mit animationSetLayerWeight eingeblendet und mit animationSetLayerMask auf einen Teil des Skeletts beschränkt: ein Umsehen am Hals, während die Beine gehen, ein Winken mit einem Arm über einem Laufen.

animationPlay(fox, "Walk", true)
animationPlayLayer(fox, 1, "Survey", true, 1, 0.5)           -- Kopf dreht sich, über eine halbe Sekunde eingeblendet
animationSetLayerMask(fox, 1, nodeFind("b_Neck_04", fox))    -- ... nur am Hals und darüber.

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)   -- Schneller, in 0,4 s überblendet.
    end
end

1.15.8. Sound in der Szene

Ein Soundeffekt kann in der Szene platziert werden, sodass er von dort zu hören ist, wo er ist. soundSetPosition(channel, x, y, z) setzt einen spielenden Kanal an einen Weltpunkt, soundSetNode(channel, node) lässt ihn stattdessen einem Knoten folgen, und soundSetRange(channel, near, far) sagt, wo er in voller Lautstärke ist und wo er zu Stille verklungen ist. Sounds werden von der Kamera aus gehört, sofern soundSetListener nicht einen anderen Knoten nennt (den Kopf des Spielers, bei einem Third-Person-Spiel), und sie wandern nach links und rechts, wenn sich der Zuhörer dreht. Ein Kanal, der nicht in der Szene platziert ist, spielt wie immer, mit soundSetPan für Stereo.

local crackle = soundPlay(fireSound, -1)          -- Endlosschleife.
soundSetNode(crackle, brazier)
soundSetRange(crackle, 2, 18)                     -- Voll innerhalb von 2 Einheiten, weg bei 18.
soundSetListener(hero)

1.15.9. Sprites und Text in der Szene

Jeder Knoten kann statt eines Meshes ein Bild zeigen. nodeSetSprite(node, sprite, height) legt ein geladenes Sprite (jeden Frame eines animierten, wobei nodeSetSpriteFrame auswählt) auf ein Quad, das so viele Welteinheiten hoch ist, beleuchtet wie alles andere und Schatten werfend, sofern nodeSetShadow nichts anderes sagt. nodeSetText(node, text, height) tut dasselbe mit einer Textzeile in der gewählten Schriftart und Farbe, unbeleuchtet. Beide sind für den Rest der Engine Meshes: Sie hängen an Eltern, skalieren und nehmen das Überblenden eines Materials an.

nodeSetBillboard dreht einen Knoten in jedem Frame zur Kamera: BILLBOARD_ALL frontal (Namensschilder, Leuchteffekte, Impostors), BILLBOARD_Y nur um seine eigene Hochachse (Bäume, Lebensbalken, alles, was aufrecht bleiben muss), und BILLBOARD_NONE, um aufzuhören. Es funktioniert auch bei Meshes.

local tag = nodeNew()
nodeSetParent(tag, fox)
nodeSetPosition(tag, 0, 110, 0)         -- In den Zentimetern des Fox-Modells, über seinem Kopf.
nodeSetScale(tag, 50)                   -- Die Skalierung 0,02 der Instanz aufheben.
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. Vor dem Overlay

Die Szene wird normalerweise unter dem Overlay gezeichnet, sodass alles, was auf das Overlay gezeichnet wird, sie verdeckt. nodeSetLayer(node, LAYER_FRONT) verschiebt einen Knoten und alles, was an ihm hängt, stattdessen in die vordere Ebene: Dieselbe Kamera zeichnet ihn nach dem Overlay, von denselben Lichtern beleuchtet und mit derselben Belichtung, derselben Tonkurve und demselben Bloom fertiggestellt, sodass ein drehendes Logo, ein 3D-Titel oder ein Modell auf einer Highscore-Tabelle über 2D-Grafik stehen kann. Die vordere Ebene ist ein eigenes Bild, transparent gelöscht, sodass das Overlay überall dort sichtbar ist, wo sie nichts zeichnet, und nichts in der Szene hinter dem Overlay sie verdecken kann. GUIs und die über das Overlay gezeichneten Partikel liegen weiterhin darüber.

Vordere Knoten werfen weiterhin Schatten auf die Szene. Der Himmel, 3D-Partikel und Debug-Linien bleiben in der Szene, und Ansichten (viewNew) zeichnen nur die Knoten der Szene. Die Ebene kostet einen zweiten Renderdurchgang, und das nur in Frames, in denen etwas darin ist.

-- Eine goldene Münze, die sich über dem 2D-Titelbildschirm dreht.
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. Gelände

meshHeightmap(image, sizeX, sizeY, sizeZ) macht aus einem Graustufenbild hügeligen Boden: ein Vertex pro Pixel, Schwarz unten und Weiß sizeY hoch, mit Normalen aus den Steigungen und Texturkoordinaten über das Ganze. Gib seinem Material eine Textur und materialSetTiling, um sie alle paar Einheiten zu wiederholen. Bilder dürfen in jeder Richtung bis zu 1025 Pixel groß sein; eine Map von 257 Pixeln über 120 Einheiten ergibt einen Vertex pro halbe Einheit, was für Hügel reichlich ist.

Ein BODY_STATIC-Körper mit SHAPE_MESH auf diesem Knoten wird zu einem Höhenfeld, weit billiger, als die Dreiecke es wären, sodass Autos darauf fahren und Spieler darauf gehen, so wie sie sind. terrainGetHeight(node, x, z) sagt, wie hoch der Boden an einem Punkt ist, um Dinge darauf zu platzieren, ohne einen Strahl zu werfen.

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)             -- Ein Höhenfeld.

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. Navigation

Ein Navigationsmesh sagt Figuren, wo sie gehen können. navNew(radius, height, maxSlope, maxStep) beginnt eines für eine gegebene Agentengröße, navAddNode füttert es mit der Geometrie des Levels (die Wurzel einer Modellinstanz liefert das ganze Modell), und navBuild backt die begehbare Fläche: Böden, Rampen und Treppen, die der Agent erklimmen kann, abzüglich eines Rands um jede Wand und Säule. Sponza zu backen dauert auf einem Desktop eine Zehntelsekunde; navSave und navLoad bewahren ein gebackenes Mesh im Datenordner des Spiels auf, für Rechner, auf denen es länger dauert, und ein mit dem Spiel ausgeliefertes Mesh lädt genauso. navDraw zeigt das Mesh über der Szene, während du die Parameter richtig einstellst.

Abfragen beantworten dann die Fragen, die ein Spiel stellt: navPath gibt die Ecken des kürzesten Wegs zwischen zwei Punkten zurück, navNearest setzt einen Punkt auf das Mesh, navRaycast sagt, ob ein gerader Weg blockiert ist, und navRandomPoint sucht irgendeinen Ort aus, zu dem man schlendern kann.

Agenten (navAgentNew) laufen das Mesh für dich ab. navAgentMoveTo schickt einen irgendwohin, und er steuert unterwegs um die anderen Agenten herum, bewegt seinen Knoten (oder steuert einen Spieler-Controller darauf, mit navAgentSetPlayer) und ruft onNavArrived auf, wenn er ankommt. navAgentGetVelocity sagt dir, ob du das Gehen oder das Laufen abspielen sollst.

local nav = navNew(0.4, 1.6, 45, 0.3)   -- Ein Agent 0,8 breit, 1,6 hoch, steigt 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))   -- Weiter zum nächsten Ort.
end

1.15.13. Leistung und Anforderungen

Die Szene braucht eine GPU, die Vulkan (Linux), Direct3D 12 (Windows 10 und neuer), Metal (macOS) oder OpenGL ES 3.1 spricht. Das ES-Backend ist es, das die billigen Linux-Handhelds und den Raspberry Pi hereinholt, deren Mali- und VideoCore-Chips einen ausgereiften GLES-Treiber haben und entweder gar kein Vulkan oder ein unausgereiftes; es wird automatisch gewählt, wenn keines der anderen drei verfügbar ist, und es zeichnet dasselbe Bild aus denselben Shadern. Der Raspberry Pi 4 bleibt der Mindest-Pi für 3D: Der Pi 3 hat nur OpenGL ES 2.0, das das Skinning und die Morph-Ziele der Szene nicht ausdrücken kann. Auf einem Rechner ohne eines davon laufen 2D-Spiele genau wie zuvor (2D-Physik eingeschlossen), und der erste 3D-Aufruf beendet das Spiel mit einem Fehler, der das Problem nennt.

Meshes außerhalb des Blickfelds der Kamera werden übersprungen, und Kopien desselben Meshes mit demselben Material werden als ein instanzierter Aufruf gezeichnet, sodass ein Wald aus ein und demselben Baum etwa so viel kostet wie ein Baum. sceneGetStats meldet die gesammelten Zeichenvorgänge, wie viele davon im Blickfeld waren, wie viele Draw Calls das brauchte und den belegten Texturspeicher. So hilfst du nach:

  • Teile Meshes und Materialien zwischen Knoten (ein meshBox, viele Knoten; ein Modell, viele modelInstance-Aufrufe), statt für jedes Objekt eines zu erzeugen.

  • Geskinnte und morphende Meshes und überblendete werden einzeln gezeichnet; beschränke sie auf das, was die Szene braucht.

  • Kantenglättung (4x-Multisampling) ist überall eingeschaltet, wo die GPU sie anbietet; sceneSetAntialias(false) gewinnt auf einem Pi Geschwindigkeit zurück, ebenso ein kleineres sceneSetShadowSize und weniger schattenwerfende Punktlichter, von denen jedes sechs Durchgänge kostet.

  • Behalte auf kleinen Boards die Dreieckszahlen und Texturgrößen im Auge, liefere KTX2-Texturen aus und lade ein Modell einmal statt zweimal.

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. Physik

Körper, Gelenke, Trigger und Raycasts leben in der 3D-Szene und laufen auf Jolt Physics. Ein Körper hängt an einem Knoten, wie es ein Mesh tut, und von da an sind Knoten und Körper eins: Die Form des Körpers wird in Welteinheiten bemessen und vom Knoten skaliert, und welcher der beiden sich auch bewegt, der andere folgt. Die Einheiten sind Meter, Kilogramm und Sekunden, und die Schwerkraft ist standardmäßig 0, -9.81, 0. Physik braucht keine GPU; siehe 2D-Spiele.

1.16.1. Körper

bodyNew(node, type, shape, a, b, c) gibt einem Knoten einen Körper von einem von drei Typen:

  • Ein statischer Körper (BODY_STATIC) bleibt, wo der Knoten war, als der Körper erzeugt wurde: Böden, Wände, der Automat. Seinen Knoten danach zu bewegen, bewegt den Körper nicht.

  • Ein kinematischer Körper (BODY_KINEMATIC) folgt seinem Knoten, wohin das Skript oder eine Animation ihn auch bewegt, und schiebt dynamische Körper aus dem Weg, ohne selbst geschoben zu werden: ein Schläger, eine bewegliche Plattform, die Hand einer Figur.

  • Ein dynamischer Körper (BODY_DYNAMIC) wird von der Simulation bewegt und treibt seinen Knoten: Er fällt, prallt ab, rutscht und wird geschoben. Bewege seinen Knoten nicht selbst; gib ihm stattdessen Geschwindigkeiten, Kräfte oder Impulse (bodySetVelocity, bodyApplyForce, bodyApplyImpulse).

Die Form ist ein Quader, eine Kugel, eine Kapsel oder ein Zylinder, bemessen durch a, b und c (SHAPE_BOX nimmt Breite, Höhe und Tiefe; SHAPE_SPHERE einen Radius; SHAPE_CAPSULE und SHAPE_CYLINDER einen Radius und eine Höhe entlang Y), eine konvexe Hülle um das Mesh des Knotens (SHAPE_HULL, alles unter dem Knoten, also funktioniert die Wurzel einer Modellinstanz) oder die exakten Dreiecke des Meshes (SHAPE_MESH, nur für statische und kinematische Körper; auf einem Heightmap-Mesh ist es ein Höhenfeld, siehe Gelände).

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)   -- Der kinematische Schläger fegt durch den Stapel.
    return OVERLAY_UPDATED
end
Masse und Materialien

Die Masse eines dynamischen Körpers ergibt sich aus dem Volumen seiner Form bei der Dichte von Wasser, sodass ein Quader von der Größe einer Tür 140 Kilogramm wiegt und ein Stups ihn nicht bewegt. Setze bodySetMass bei allem, was sich leicht anfühlen soll, und bemiss Impulse nach der Masse: Ein Impuls von mass * speed setzt genau diese Geschwindigkeit. bodySetFriction und bodySetBounce machen Eis und Gummi; bodySetEnabled nimmt einen Körper aus der Welt und setzt ihn wieder ein, ohne ihn zu verlieren.

Zeitsteuerung

Die Welt macht nach der Uhr feste sechzig Schritte pro Sekunde, nachdem Animationen ihre Knoten in Pose gebracht haben und bevor die Szene gerendert wird, sodass ein von einer Animation getriebener kinematischer Körper mit der richtigen Geschwindigkeit schiebt. Das Spiel zu pausieren pausiert die Physik; physicsSetEnabled(false) pausiert sie allein. bodyIsResting sagt, wann ein Körper zur Ruhe gekommen ist, also wann ein geworfenes Ding liegen geblieben ist und Punkte gezählt werden können. Ein Körper, eine Spielfigur, eine Ragdoll, ein Soft Body oder ein Fahrzeug, dessen Knoten gelöscht wurde, wird zu Beginn des nächsten Frames freigegeben, ob aktiviert oder nicht und ob pausiert oder nicht, sodass sein Platz wieder frei ist; ein Knoten-Handle, das nodeNew später neu vergibt, trägt nichts von der Physik des alten Knotens, und playerExists und seinesgleichen antworten dafür mit false, bis es eine eigene bekommt.

1.16.2. Ereignisse und Abfragen

Definiere onCollision(nodeA, nodeB, x, y, z, speed), und Singe ruft es für jeden neuen Kontakt einmal auf, mit dem Punkt und der Geschwindigkeit, mit der die beiden Körper aufeinandertrafen, sodass ein Rempler und ein Crash verschieden klingen können. Ein Körper, der mit bodySetTrigger zum Trigger gemacht wurde, schiebt nichts, meldet aber über onTrigger(trigger, other, entered), was in ihn eintritt und ihn verlässt: eine Ziellinie, eine Tür, eine Gefahrenzone. physicsRaycast findet den ersten Körper entlang eines Strahls; mit sceneUnproject für den Strahl ist das die Objektauswahl mit der Maus (siehe Knoten). Eine Liste von Knoten als letztes Argument bleibt bei der Suche außen vor, sodass ein Schuss aus dem Inneren des eigenen Körpers der Spielfigur nicht dort endet.

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. Gelenke

jointHinge, jointBall und jointSlider verbinden zwei Körper oder einen Körper und die Welt, wenn der zweite Knoten -1 ist: Türen, Pendel, Schubladen, die Räder eines von der Seite gesehenen Autos. Anker und Achse werden in Weltkoordinaten angegeben, dort, wo die Körper stehen, wenn das Gelenk erzeugt wird. Scharniere und Schieber nehmen Grenzen (jointSetLimits): Ein positiver Scharnierwinkel ist eine Drehung des ersten Knotens um die Achse nach der Rechte-Hand-Regel, und eine positive Schieberstrecke verläuft entlang der Achse.

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)   -- Am Rahmen, um Y.
jointSetLimits(hinge, 0, 110)                            -- Öffnet in eine Richtung, 110 Grad.

Körper auf Modellinstanzen funktionieren wie alle anderen: bodyNew(instanceRoot, BODY_DYNAMIC, SHAPE_HULL) hüllt das ganze Modell in eine konvexe Hülle. Eine geskinnte Figur ist am besten eine Spielfigur (siehe unten) oder eine kinematische Kapsel, die Dinge schiebt, statt geschoben zu werden.

1.16.4. 2D-Spiele

Physik ist nicht an die 3D-Szene gebunden. Knoten gibt es auf jedem Rechner, mit GPU oder ohne, also kann ein 2D-Spiel Knoten Körper geben, physicsSet2D(true) aufrufen, damit sie sich nur in X und Y bewegen und nur um Z drehen, in Overlay-Koordinaten arbeiten, wobei die Schwerkraft den Bildschirm hinunter zeigt, und Sprites dort zeichnen, wo die Knoten sind. Das ist die Form, die auf einem Raspberry Pi 3 läuft, der kein 3D hat.

physicsSet2D(true)
physicsSetGravity(0, 900, 0)          -- Pixel pro Sekunde zum Quadrat; Overlay-Y läuft nach unten.

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

Gib jedem 2D-Körper etwas Tiefe (die dritte Größe), damit sich Formen in Z überlappen; 50 genügt. Kreise sind SHAPE_SPHERE. Spielfiguren und 2D-Emitter (siehe Partikel) funktionieren auch in dieser Welt, und ein Plattformspiel ist eine Spielfigur mit playerMove(node, vx).

1.16.5. Spielfiguren

Ein Körper geht, wohin Kräfte ihn schicken; eine Spielfigur geht, wohin das Skript sagt. playerNew setzt einen Character-Controller auf einen Knoten: standardmäßig eine Kapsel (playerNew(node, radius, height)) oder jede konvexe bodyNew-Form (playerNew(node, SHAPE_BOX, w, h, d) für einen Roboter, playerNew(node, SHAPE_SPHERE, r, 0) für etwas, das rollt und trotzdem Stufen steigt, SHAPE_HULL für den eigenen Umriss des Modells; drei Argumente bedeuten immer eine Kapsel, also schreibt eine Kugel ihre Größen aus). Die Form steht auf dem Ursprung des Knotens, und der sind die Füße. Jeden Frame gibt das Skript playerMove die horizontale Geschwindigkeit, die es will, und der Controller läuft Böden entlang, steigt Stufen bis playerSetStep hinauf, gleitet an Wänden entlang, verweigert Hänge, die steiler als playerSetSlope sind, fällt unter der Schwerkraft, fährt auf beweglichen Plattformen mit und schiebt leichte dynamische Körper aus dem Weg (playerSetPush). playerJump funktioniert nur mit Boden unter den Füßen und sagt, ob gesprungen wurde. Die Drehung des Knotens gehört dem Skript: Dreh ihn so, dass er in seine Laufrichtung schaut, und häng das Modell als Kind darunter.

hero = nodeNew()
nodeSetPosition(hero, 0, 0, 0)
playerNew(hero, 0.3, 1.0)               -- Eine Kapsel mit Radius 0.3, 1 hoch, Füße am Knoten.
fox = modelInstance(modelLoad(DIR .. "Fox.glb"))
nodeSetParent(fox, hero)

function onInputPressed(switch)
    if switch == SWITCH_BUTTON1 then
        playerJump(hero, 4.5)               -- Braucht Boden unter den Füßen.
    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

Spielfiguren melden onCollision, wenn sie einen Körper zu berühren beginnen, und onTrigger, wenn sie einen Sensor betreten oder verlassen, mit ihrem Knoten an der Stelle, die der Knoten eines Körpers einnähme, sodass eine Tür, ein Pickup und eine Lavagrube für eine Spielfigur genauso funktionieren wie für einen Ball. playerIsOnGround und playerGetGround sagen, worauf die Spielfigur steht, für Schrittgeräusche und um absichtlich von einer Plattform zu fallen. In einer 2D-Welt ist eine Spielfigur die Figur eines Plattformspiels: playerMove(node, vx) läuft entlang X, die Schwerkraft zeigt den Bildschirm hinunter, und alles andere ist gleich. Die Toleranzen des Controllers skalieren mit der Form, sodass sich eine 30 Pixel große Kapsel in einem Sprite-Spiel wie eine von 0,3 Metern in einem 3D-Spiel verhält.

1.16.6. Fahrzeuge

Ein Fahrzeug ist ein dynamischer Körper (das Chassis, mit bodyNew erzeugt wie jeder Körper, mit Blick nach -Z und Y oben), den Jolt über Räder antreibt: vehicleNew(node, VEHICLE_CAR) für alles mit Achsen, VEHICLE_MOTORCYCLE für zwei Räder hintereinander, die sich in Kurven legen und balancieren, oder VEHICLE_TANK für Räder auf zwei Ketten, die auf der Stelle wenden. Räder sind Knoten: vehicleAddWheel(node, wheelNode, radius, width, suspension) nimmt die Position des Rads daher, wo sein Knoten relativ zum Chassis steht, und von da an stellt die Engine diesen Knoten jeden Frame (seine X-Achse ist die Radachse, also will ein meshCylinder-Rad ein um 90 Grad gedrehtes Kind). Räder, die in einem Modell mit nodeFind("wheelFL", car) gefunden werden, funktionieren genauso. Standardmäßig lenken die Vorderräder, und alle treiben an; vehicleSetWheel legt es anders fest.

Jeden Frame übergibt das Skript die Eingaben des Fahrers: vehicleDrive(node, forward, right, brake, handBrake). Motor, Automatikgetriebe und Differenziale sind die von Jolt mit den Standardwerten eines 1500-kg-Autos; vehicleSetEngine, vehicleSetGears, vehicleSetSuspension, vehicleSetSteering, vehicleSetBrakes und vehicleSetAntiRoll stimmen sie ab, und jede Änderung baut das Fahrzeug beim nächsten Schritt an Ort und Stelle neu auf. vehicleGetSpeed, vehicleGetRpm und vehicleGetGear speisen ein Armaturenbrett. Ein Fahrzeug ist immer noch ein Körper: Es springt über Rampen, prallt gegen Wände, schiebt Kisten und meldet 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 },   -- Vorne links und rechts ...
    { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 },     -- ... hinten links und rechts.
}
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

Panzer nehmen forward als Gas und right als Drehung (ohne Gas drehen sie auf der Stelle) und ignorieren die Abstimmung von Lenkung, Bremsen und Stabilisator, da ihre Ketten selbst bremsen und lenken. Die Neigefeder des Motorrads ist auf das Chassis skaliert, sodass ein leichtes Motorrad genauso gut balanciert wie ein schweres. Fahrzeuge mit Rädern brauchen eine 3D-Welt; ein von der Seite gesehenes 2D-Auto ist ein Körper mit zwei per Scharnier befestigten Rädern, und das bauen die Gelenkaufrufe bereits.

1.16.7. Wasser

bodySetWater(node, density, linearDrag, angularDrag) füllt einen statischen Körper mit Wasser: Die Oberseite seines Quaders ist die Oberfläche, und jeder dynamische Körper darin schwimmt, sinkt oder rollt durch den Auftrieb von Jolt gegen diese Oberfläche (der eingetauchte Teil der Form zählt, sodass eine schräge Kiste sich aufrichtet), gebremst durch die Widerstände. bodySetCurrent gibt dem Wasser eine Strömung. density ist ein Faktor, 1 für Wasser, und das eigene bodySetBuoyancy jedes schwimmenden Körpers (Standard 1.2, das sanft schwimmt; unter 1 sinkt er) skaliert ihn. Das Volumen ist ein Trigger, also feuert onTrigger beim Hinein- und Hinausgehen, für Spritzer. Wasser wird nicht gezeichnet: Gib dem Knoten des Volumens ein Material mit Blending oder keines.

Eine Spielfigur im Wasser schwimmt: playerIsSwimming sagt es, playerMove(node, vx, vy, vz) steuert dann in drei Achsen, ohne vertikale Eingabe sinkt sie langsam (playerSetSwim setzt diese Rate und den Widerstand des Wassers), und die Strömung trägt sie mit. Ein Boot ist ein schwimmender Rumpf, dem vehicleNew(node, VEHICLE_BOAT) einen Propeller und ein Ruder gibt: vehicleSetThrust sagt, wie stark er schiebt und wo im Rumpf, vehicleSetRudder, wie stark es dreht, und vehicleDrive funktioniert wie bei einem Auto, alles nur, solange der Propeller unter einer Oberfläche ist.

pool = nodeNew()
nodeSetMesh(pool, meshBox(8, 3, 12), blue)   -- Blaues Material mit Blending, als Wasser gezeichnet.
nodeSetPosition(pool, 0, -1.5, 0)            -- Seine Oberseite bei Y = 0 ist die Oberfläche.
bodyNew(pool, BODY_STATIC, SHAPE_BOX, 8, 3, 12)
bodySetWater(pool, 1.0, 0.6, 0.2)
bodySetCurrent(pool, 0.5, 0, 0)              -- Treibt in Richtung +X.
bodySetBuoyancy(crate, 1.6)                  -- Liegt hoch im Wasser.
bodySetBuoyancy(anchor, 0.3)                 -- Geht unter.

1.16.8. Ragdolls

ragdollNew(node) sucht unter einer Modellinstanz nach ihrem Skin und macht aus dem Skelett ein Ragdoll-Rezept: Jedes Gelenk mit einem Kindgelenk wird zu einer Kapsel entlang dieses Knochens, durch ein Swing-Twist-Gelenk mit vernünftigen Grenzen mit dem nächsten Knochen darüber verbunden, und Endgelenke (Finger, Ohren, die Schwanzspitze) bewegen sich mit ihren Eltern mit. Nichts bewegt sich bis ragdollActivate: Dann stoppt die Animation, Körper werden dort erzeugt, wo die Knochen sind, und von diesem Moment an treibt die Physik die Gelenkknoten, sodass das geskinnte Mesh zusammensackt, auf den Boden schlägt und mit dem Rest der Welt zur Ruhe kommt.

ragdollApplyImpulse stößt einen Knochen über den Namen seines Gelenks an. ragdollSetStrength treibt jedes Gelenk zu der Pose hin, in der die Ragdoll aktiviert wurde, was einen schlaffen Sturz in ein Taumeln verwandelt oder eine am Boden liegende Figur ihre Gliedmaßen wieder einziehen lässt; einen Körper stellt es nicht auf, da sich nichts vom Boden abstößt. ragdollDeactivate gibt das Skelett an die Animation zurück, wo immer es liegt, und ein animationPlay mit Überblendung hebt es dann von dort sanft an. Stimme einen Knochen, der falsch aussieht, vor dem Aktivieren mit ragdollSetJoint ab.

fox = modelInstance(foxModel)
ragdollNew(fox)                            -- Rezept aus dem Skin; noch animiert.
function onCollision(a, b, x, y, z, speed)
    if (a == hero or b == hero) and speed > 3 then
        playerSetEnabled(hero, false)
        ragdollActivate(fox)                 -- Jetzt treibt die Physik das Skelett.
        ragdollApplyImpulse(fox, "b_Spine02_03", 40, 30, 0)
    end
end

1.16.9. Soft Bodies

Stoff, Seil und Wackelpudding sind Meshes, deren Vertices simuliert werden. softNew(node, SOFT_CLOTH) macht das Mesh des Knotens zu Stoff und seine Vertices (nach Position verschweißt) zu Partikeln, verbunden durch Dehnungs-, Scher- und Biege-Constraints, dort, wo der Knoten es in die Welt gesetzt hat; ein unterteiltes meshPlane(width, depth, columns, rows) ist der übliche Anfang. softNew(node, SOFT_BODY) macht dasselbe mit einem geschlossenen Mesh, und softSetPressure bläst es auf: ein Ballon, ein Wackelpudding. softNew(node, SOFT_ROPE, x, y, z, segments, radius) legt eine Kette von Partikeln von der Position des Knotens bis zu diesem Punkt und gibt dem Knoten ein Röhren-Mesh um sie herum (sein Aussehen setzt du mit nodeSetMaterial).

Soft Bodies kollidieren mit allem Starren, fallen unter der Schwerkraft und werden durch das Mesh gezeichnet, aus dem sie stammen und das die Engine jeden Frame neu schreibt. softPin hält das nächstgelegene Partikel fest, wo es ist oder an einem Knoten (die Kante der Flagge an der Stange, das obere Ende des Seils am Kran); softSetStiffness, softSetMass und softSetDamping stimmen das Material ab. Ein Knoten, dessen Mesh mit anderen Knoten geteilt wird, verändert diese mit, also gib einem Soft Body ein eigenes Mesh.

flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), red)
nodeSetPosition(flag, -4.2, 2.4, 0)
nodeSetRotation(flag, 90, 0, 0)                 -- Hängt aufrecht.
softNew(flag, SOFT_CLOTH)
for _, y in ipairs({ 1.9, 2.15, 2.4, 2.65, 2.9 }) do
    softPin(flag, -5, y, 0)                     -- Entlang der Stange.
end

Die Kosten wachsen mit der Partikelzahl: Ein Tuch von 20 mal 20 hat 441 Partikel und läuft gut auf einem Raspberry Pi 4; beschränke Stoff auf ein paar hundert Partikel und ein Seil auf ein Dutzend Segmente. Mit starren Körpern kollidieren die Partikel, nicht die Flächen, also hält erst ein ausreichend feines Mesh (Partikel näher beieinander als das kleinste Ding, das darauf landen wird) eine Kiste vom Durchfallen ab. Es gibt keine Selbstkollision: Stoff kann durch sich selbst hindurchgehen, wenn er zerknüllt wird. Geskinnte Meshes können keine Soft Bodies sein.

1.16.10. Die Physik sichtbar machen

Wenn eine Kiste durch den Boden fällt oder ein Gelenk sich in die falsche Richtung biegt, zeichnet physicsSetDebug jeden Frame als Linien über die Szene, was die Simulation tatsächlich enthält:

  • DEBUG_SHAPES: die Körper als Drahtgitter, nach Zustand gefärbt (schlafend, bewegt, statisch), die Spielfiguren in Gelb.

  • DEBUG_CONSTRAINTS: die Gelenke, Ragdoll-Gelenke und Fahrzeug-Constraints mit ihren Grenzen.

  • DEBUG_CONTACTS: ein rotes Kreuz, wo sich Körper in diesem Schritt getroffen haben.

  • DEBUG_VELOCITIES: eine Linie entlang der Geschwindigkeit jedes bewegten Körpers.

  • DEBUG_STATIC: zusätzlich die Formen der statischen Körper, die sonst aus bleiben, weil ein Level-Mesh sehr viele Linien ergibt.

Addiere sie, oder nimm DEBUG_ALL für die ersten vier. DEBUG_NONE schaltet es ab, und solange es aus ist, kostet es nichts. Ein Skript zeichnet seine eigenen Linien genauso mit lineDraw (einen Raycast, einen Pfad, eine Bounding Box), einen Frame nach dem anderen wie das Overlay, und navDraw zeigt ein Navigationsmesh.

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. Wo sie läuft

Die Physik läuft auf der CPU und braucht keine GPU, aber die Bibliothek ist für SSE4.1 auf x86 (2008 und später) und NEON auf dem Pi gebaut; ein Rechner darunter bekommt beim ersten bodyNew einen Fehler. Die Simulation nutzt alle Kerne bis auf einen, also rechnet ein Pi mit vier Kernen auf drei Threads; der Trace des Programms sagt, auf wie vielen.

1.17. Partikel

Funken, Rauch, Feuer, Regen, Staub, Magie: Alles, was aus vielen kleinen, kurzlebigen Dingen besteht, ist eine Aufgabe für einen Emitter. Ein Emitter hält ein Rezept (wie viele pro Sekunde, wie lange sie leben, wie schnell und in welche Richtung sie starten, was an ihnen zieht, wie sie wachsen, verblassen und sich drehen) und einen Pool von Partikeln, die er nach diesem Rezept laufen lässt. Das Skript setzt das Rezept einmal und startet dann den Emitter für einen gleichmäßigen Strom (emitterStart), lässt ihn für einen einmaligen Puff ausstoßen (emitterBurst) oder beides. Die Engine bewegt jedes lebende Partikel jeden Frame und hört damit auf, solange das Spiel pausiert ist.

Eine einzige Emitter-API dient dem Overlay und der 3D-Szene; nur die Einheiten und das Zeichnen unterscheiden sich. Alles, was als Minimum und Maximum angegeben wird (emitterSetLife, emitterSetSpeed, emitterSetSize), wird für jedes Partikel zufällig zwischen den beiden gewählt.

1.17.1. 2D-Emitter

emitterNew() ohne Argument erzeugt einen 2D-Emitter. Er lebt in Overlay-Koordinaten, Y nach unten, also ist die Schwerkraft eines Springbrunnens positives Y. Bewege ihn mit emitterSetPosition und zeichne ihn aus onOverlayUpdate mit emitterDraw. Das Overlay selbst ist ein Bild, das die CPU malt, also werden Partikel nicht hineingemalt: Die GPU zeichnet sie, entweder über dem ganzen Overlay (PARTICLE_OVER, der Standard) oder darunter und über dem Video und der 3D-Szene (PARTICLE_UNDER, für Rauch hinter der Punktzahl). 2D-Emitter laufen auf jedem Rechner, auf dem Singe läuft, den Raspberry Pi 3 eingeschlossen, und passen gut zu 2D-Physik: Lies die Knotenposition eines Körpers und gib sie an emitterSetPosition.

sparks = emitterNew()
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetLife(sparks, 0.3, 0.7)
emitterSetSpeed(sparks, 80, 200)
emitterSetDirection(sparks, 0, -1)       -- Den Bildschirm hinauf.
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. 3D-Emitter

emitterNew(node) erzeugt einen an einen Knoten gehängten 3D-Emitter. Partikel entstehen an der Weltposition des Knotens (über emitterSetRadius verteilt), in Welteinheiten, und zeichnen sich in der Szene nach jedem Mesh als der Kamera zugewandte Billboards: gegen die Geometrie tiefengetestet, ohne je Tiefe zu schreiben, unbeleuchtet, sofern nicht verlangt, ohne Schatten zu werfen oder zu empfangen. Standardmäßig bleibt ein Partikel, sobald es den Emitter verlässt, dort, wo es entstanden ist (Rauch treibt weiter dort, wo er entstand, während die Fackel weiterzieht); emitterSetLocal lässt stattdessen die ganze Wolke dem Knoten folgen. Wird der Knoten gelöscht, werden seine Emitter mitgelöscht.

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. Das Bild

Ein Partikel ist ein texturiertes Quad. Ohne Textur ist es eine weiche Scheibe, die die Engine bereitstellt; emitterSetTexture gibt ihm stattdessen ein geladenes Sprite (einen Rauchpuff, einen Funkenstreifen, eine Schneeflocke), und bei einem animierten Sprite wählt emitterSetFrames für jedes Partikel einen zufälligen Frame, sodass ein Atlas von Puffs eine abwechslungsreiche Wolke ergibt. Das Blending ist normal (PARTICLE_ALPHA) oder additiv (PARTICLE_ADD, für alles, was leuchtet). emitterSetColor gibt Farbe und Alpha bei der Geburt und beim Tod an, und das Partikel geht im Lauf seines Lebens von einem zum anderen über; emitterSetSize tut dasselbe für seine Größe, mit einem dritten Wert dafür, wie schnell es sich dreht.

1.17.4. Spuren, Kollisionen, beleuchtete und weiche Partikel

emitterSetTrail(emitter, length, width) merkt sich die letzten paar Positionen jedes Partikels und zeichnet ein Band durch sie, das zum Ende hin verblasst: Funken, Leuchtspurgeschosse, Kometen, in 2D wie in 3D. emitterSetCollide lässt Partikel abprallen: von einem waagerechten Boden in einer Höhe, die du angibst (COLLIDE_FLOOR, kostenlos), oder von der Physikwelt per Raycasts (COLLIDE_SCENE, nur 3D, pro Frame gedeckelt, sodass ein großer Emitter die Kosten über einige Frames verteilt).

Zwei weitere gibt es nur für 3D. emitterSetLit schattiert jedes Partikel als kleine, der Kamera zugewandte Kugel nach den Lichtern und dem Himmel der Szene, sodass Rauch die Farbe eines Kohlebeckens annimmt und Staub in der Sonne glitzert (Schatten werden nicht gelesen). emitterSetSoftness blendet ein Partikel über eine Strecke aus, wo es auf Geometrie trifft, sodass Rauch nicht in einen Boden schneidet und ein Springbrunnen nicht in sein Becken; das kostet einen zusätzlichen Tiefendurchgang der Szene pro Frame, solange irgendein Emitter es nutzt.

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)                  -- Nimmt die Farbe des Feuers von unten an.
emitterSetSoftness(smoke, 0.4)              -- Keine harte Kante, wo er auf die Schale trifft.
emitterStart(smoke)

embers = emitterNew(brazier)
emitterSetBlend(embers, PARTICLE_ADD)
emitterSetTrail(embers, 6, 0.02)            -- Ein kurzer Streifen hinter jedem Glutfunken.
emitterSetCollide(embers, COLLIDE_FLOOR, 0.3, 0.8, 0)   -- Prallen vom Boden bei Y = 0 ab.
emitterStart(embers)

1.17.5. Kosten

Partikel sind billig zu simulieren und kosten, was sie auf dem Bildschirm bedecken. Ein paar tausend kleine sind nichts; eine Handvoll großer additiver über dem ganzen Bildschirm ist das, was einen Raspberry Pi 4 ausbremst. Der Pool wird durch emitterSetMax gedeckelt (Standard 1000); wenn er voll ist, entstehen keine neuen, bis einige sterben.

1.18. Ein Spiel beschreiben statt es zu schreiben

Ein Spiel kann als Beschreibung geschrieben werden — eine Tabelle aus Ebenen, Entitäten und Regeln — und von Forge, dem Autorenwerkzeug, in ein gewöhnliches Singe-Spiel kompiliert werden. Forge ist ein eigenes Projekt mit eigenem Download und eigenem Buch.

1.19. Umstieg von Singe 2.10

Singe 3.00 hat das Sprite-Handle zum ersten Argument von spriteDraw, spriteLoop, spriteQuality, spriteRotate, spriteRotateAndScale, spriteScale und spriteSetFrame gemacht, sodass jeder Sprite-Aufruf jetzt zur video*-Familie passt. Um ein Spiel anzupassen, verschiebe das letzte Argument jedes dieser Aufrufe nach vorn:

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

Ein Spiel, das du nicht bearbeiten kannst, kann sich stattdessen für die alte Reihenfolge entscheiden. Setze entweder die globale Variable, bevor das Framework geladen wird:

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

oder füge LEGACY_SPRITE_ARGS = true zu seinem Eintrag in games.dat hinzu. An keiner anderen Aufrufform hat sich etwas geändert, wohl aber an einigen Verhaltensweisen:

  • Handles und Anzahlen werden als Lua-Ganzzahlen zurückgegeben; videoIsPlaying gibt einen Boolean zurück; mouseSetMode gibt nichts zurück.

  • Fehler in Callbacks beenden das Spiel jetzt mit einem Traceback, statt ausgegeben und ignoriert zu werden, so wie sich Argumentfehler schon immer verhalten haben.

  • Gehaltene Tasten wiederholen sich in MODE_NORMAL nicht mehr.

  • Neben das Spiel wird nichts geschrieben. Ohne --datadir ist der Datenordner data/<game>/ unter dem Spieleverzeichnis, wo 2.x den eigenen Ordner des Spiels benutzte; Spielstände, Einstellungen und Highscores gehören unter singeGetDataPath().

  • math.randomseed akzeptiert einen gebrochenen Startwert, wie unter dem Lua von 2.10; er wird abgerundet, bevor der Generator von Lua 5.4 ihn sieht. os.clock ist die Zeit nach der Uhr seit dem Start der Engine, nicht die Prozessorzeit.

  • Die Disc wird von der Engine auf Frame 1 geparkt, bevor dein Skript läuft; Framework.singe springt beim Laden nicht mehr.

  • onMouseMoved übergibt im Modus MANY_MOUSE im dritten und vierten Argument die echte Bewegung, und onControllerMoved übergibt den Controller-Index (0 bis 3) statt der Instanz-ID von SDL.

  • mouseEnable / mouseDisable und singeEnablePauseKey / singeDisablePauseKey funktionieren weiterhin, als Aliase von mouseSetEnabled und singeSetPauseKeyEnabled.

  • Eine Laserdisc wird nicht mehr vorausgesetzt. Ein Eintrag in games.dat mit einem VIDEO ist wie bisher ein Laserdisc-Spiel; einer ohne läuft stattdessen auf einer Zeichenfläche. Auf der Befehlszeile übergib --disc (oder --framefile), da ein neben dem Skript gefundenes Video keine Disc mehr bedeutet. Siehe Spiele ohne Disc.

  • Die Pausentaste pausiert jetzt das ganze Spiel, nicht nur die Medien: Das Skript ist eingefroren, bis die Taste erneut gedrückt wird, und SWITCH_PAUSE wird nur dann an das Skript geliefert, wenn die Taste deaktiviert wurde. Sie wirkt beim Drücken der Taste statt beim Loslassen. Siehe Pausieren.

  • fontPrint behält die Strings, die es rendert, und overlayClear füllt nur neu, was seit dem letzten Löschen gezeichnet wurde, sodass ein jeden Frame neu ausgegebenes HUD billig ist. Text aus Performancegründen mit fontToSprite zu rendern ist veraltet; es funktioniert weiterhin und ist immer noch der Weg zu Text, den du messen, skalieren oder drehen kannst. Siehe fontToSprite.

1.20. Engine-Konstanten

Die Engine definiert diese globalen Variablen, bevor irgendein Skript läuft, sodass sie controls.cfg und Framework.singe gleichermaßen zur Verfügung stehen:

Konstante Bedeutung

SWITCH_UP …​ SWITCH_RECORD

Werte, die in MODE_NORMAL an onInputPressed / onInputReleased übergeben werden. SWITCH_MOUSE_DISCONNECT löst die Engine selbst aus, wenn eine Maus oder Lightgun abgezogen wird, einmal als Drücken und einmal als Loslassen; keine Taste und kein Knopf erzeugt ihn. SWITCH_RECORD ist der Aufnahmeschalter, auf den die Engine selbst reagiert, wie auf den Screenshot-Schalter.

FONT_QUALITY_SOLID, FONT_QUALITY_SHADED, FONT_QUALITY_BLENDED

Argumente für fontQuality.

MODE_NORMAL, MODE_FULL

Argumente für keyboardSetMode.

MOUSE_SINGLE, MOUSE_MANY (auch SINGLE_MOUSE, MANY_MOUSE)

Argumente für mouseSetMode.

OVERLAY_NOT_UPDATED, OVERLAY_UPDATED

Rückgabewerte für onOverlayUpdate.

RENDER_PIXELATED, RENDER_SMOOTH

Argumente für spriteQuality / videoQuality.

SPRITE_ALPHA, SPRITE_ADD, SPRITE_MULTIPLY

Blending für spriteSetBlend.

DISC_STOPPED, DISC_PLAYING, DISC_PAUSED, DISC_EJECTED

Rückgabewerte von discGetState.

LIGHT_DIRECTIONAL, LIGHT_POINT, LIGHT_SPOT

Argumente für lightNew.

BODY_STATIC, BODY_DYNAMIC, BODY_KINEMATIC

Körpertypen für bodyNew.

SHAPE_BOX, SHAPE_SPHERE, SHAPE_CAPSULE, SHAPE_CYLINDER, SHAPE_HULL, SHAPE_MESH

Kollisionsformen für bodyNew.

JOINT_HINGE, JOINT_BALL, JOINT_SLIDER

Gelenktypen (die joint*-Aufrufe nennen sie direkt).

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

Was physicsSetDebug zeichnet; addiere sie.

PARTICLE_ALPHA, PARTICLE_ADD

Blending für emitterSetBlend.

PARTICLE_OVER, PARTICLE_UNDER

Wo 2D-Partikel gezeichnet werden, für emitterSetLayer.

COLLIDE_NONE, COLLIDE_FLOOR, COLLIDE_SCENE

Wovon Partikel abprallen, für emitterSetCollide.

BILLBOARD_NONE, BILLBOARD_ALL, BILLBOARD_Y

Wie ein Knoten sich der Kamera zuwendet, für nodeSetBillboard.

LAYER_SCENE, LAYER_FRONT

Ob ein Knoten unter dem Overlay oder davor gezeichnet wird, für nodeSetLayer.

VEHICLE_CAR, VEHICLE_MOTORCYCLE, VEHICLE_TANK, VEHICLE_BOAT

Fahrzeugarten für vehicleNew.

SOFT_CLOTH, SOFT_BODY, SOFT_ROPE

Arten von Soft Bodies für softNew.

FILTER_LINEAR, FILTER_NEAREST

Texturabtastung für materialSetFilter.

TONEMAP_NEUTRAL, TONEMAP_ACES, TONEMAP_NONE

Tonkurven für sceneSetTonemap.

SOUND_ERROR_INVALID, SOUND_REMOVE_HANDLE

-1, was soundPlay zurückgibt, wenn kein Kanal frei ist.

SINGE_VERSION_MAJOR, SINGE_VERSION_MINOR, SINGE_VERSION_STRING, SINGE_FRAMEWORK_VERSION

Die Engine-Version, als Ganzzahlen, als String ("v3.00") und als die Zahl, die singeVersion() zurückgibt.

SINGE_DEAD_ZONE

Die DEAD_ZONE aus controls.cfg, in rohen Achseneinheiten.

SINGE_TRIGGER_THRESHOLD

Die Schwelle der analogen Trigger in denselben rohen Einheiten; 0, wenn die Trigger auf SINGE_DEAD_ZONE liegen, was der Standard ist.

SINGE_LEGACY_SPRITE_ARGS

Wahr, wenn das Spiel die Sprite-Argumentreihenfolge von 2.10 verlangt hat.

SINGE_DISC

Wahr, wenn das Spiel eine Laserdisc hat; falsch, wenn die Zeichenfläche die Welt ist.

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

Aufbau der Eingabecodes für Controller und Maus und wie viele Achsen und Knöpfe ein Pad hat; Framework.singe baut daraus die Tabellen GAMEPAD_N und MOUSE_N, und ein Servicebildschirm geht damit ein Pad durch.

SINGE_SCALE_MIN, SINGE_SCALE_MAX, SINGE_SHIFT_MIN, SINGE_SHIFT_MAX, SINGE_ROTATE_STEP

Was vldpSetScale, vldpSetShift und vldpSetRotate annehmen. Begrenze auf diese Werte statt auf eigene Kopien: Eine Verschiebung außerhalb des Bereichs beendet das Skript.

Framework.singe fügt die Tabellen SCANCODE und MODIFIER hinzu (die Tasten- und Modifikatorwerte von SDL), GAMEPAD_0 bis GAMEPAD_3, MOUSE_0 bis MOUSE_3, die Indizes GAMEPAD_AXIS_* für controllerGetAxis und DIR.

1.21. Mitgelieferte Bibliotheken

Zusätzlich zu den Standardbibliotheken von Lua und der Singe-API stehen die folgenden Bibliotheken in Singe-Programmen zur Verfügung, ohne dass zusätzliche Software installiert werden muss:

Bibliothek Zweck

Copas

Asynchrone Netzwerkkommunikation

LuaFileSystem

Erweiterte Dateisystemunterstützung

json.lua

Kodieren und Dekodieren von JavaScript Object Notation

binaryheap

Datenstruktur Binärheap

timerwheel

Effiziente Timer-Planung

LuaSec

TLS-/SSL-Kommunikation

LuaSocket

TCP und UDP

LuaRS232

Zugriff auf serielle RS232-Schnittstellen

lsqlite3

SQLite-Datenbanken, require("sqlite3")

md5

require("md5") für sum, hexsum, exor, crypt und decrypt; die PUC-Rio-Bibliothek, die Hypseus mitliefert, deren sumhexa sie hexsum nennt

LuaBitOp

require("bit") für die bitweisen Operationen von Lua 5.1, die 5.4 als Operatoren hat

lrandom

require("random") für einen Mersenne-Twister-Generator, getrennt von math.random

Lua CJSON

require("cjson") zum Kodieren und Dekodieren von JSON, neben dem Modul json oben

LPeg

require("lpeg") für Parsing Expression Grammars

middleclass

require("middleclass") für Klassen, falls du Entitäten lieber daraus baust als aus Tabellen

lume

require("lume") für die kleinen Dinge, die jedes Spiel braucht: lerp, clamp, round, shuffle, split, serialize, weightedchoice

inspect

require("inspect"), um eine Tabelle in einer Form auszugeben, die ein Mensch lesen kann, für den Fall, dass debugPrint der Debugger ist

bump

require("bump") für Dinge in Bewegung, die nicht durcheinander hindurchgehen dürfen — es beantwortet, wo ein bewegtes Ding landet, was die collide-Aufrufe absichtlich nicht tun

MobDebug

require("mobdebug"), der Debugger, mit dem ZeroBrane Studio spricht; --debug startet ihn, sodass ein Spiel keine eigene Zeile dafür braucht

RmlUi

Das eigene Objektmodell der GUI, die globale Variable rmlui (siehe GUI)

Ihre Verwendung geht über den Rahmen dieses Dokuments hinaus. Die Bibliotheken md5, LuaBitOp, lrandom, Lua CJSON und LPeg sind dabei, weil Hypseus sie anbietet, sodass ein gegen Hypseus geschriebenes Spiel dieselben Module unter denselben Namen findet; nichts in Singe braucht sie.

1.22. Audio-Synchronisation

Singe zeigt Video nach der Audio-Uhr an: Ein Frame wird gezeigt, wenn der Ton zu hören ist, der zu ihm gehört. Die Engine misst beim Start ihren eigenen Audioweg. SDL kann nicht melden, wie viel Audio zwischen Mixer und Lautsprecher in der Warteschlange steht, also leert Singe das Gerät einmal, bevor irgendetwas Hörbares spielt, und zählt den Schub von Puffern, mit dem SDL es wieder auffüllt; dieser Schub ist die Tiefe der Warteschlange, und die Uhr zieht sie ab. Starte mit --program, um die Messung im Trace zu sehen (Audio device queue: …​).

Was die Engine nicht sehen kann, ist alles hinter dem Audioserver des Betriebssystems: ein DAC, ein HDMI-Receiver, eine Bluetooth-Verbindung. Diese fügen eine feste Verzögerung hinzu, die von Rechner zu Rechner verschieden ist. Wenn Aktionen auf dem Bildschirm sichtbar vor ihrem Ton kommen, übergib die fehlenden Millisekunden mit --audiodelay=MS, trag AUDIO_DELAY = MS in games.dat ein, oder lass das Spiel den Wert aus einem Service-Menü mit singeSetAudioDelay setzen. Positive Werte bedeuten, dass der Ton zu spät kommt; das Video wird passend zurückgehalten. Ein negativer Wert deckt den seltenen Fall ab, dass der Ton zu früh ankommt.

Das mitgelieferte Menü hat einen Kalibrierbildschirm für diese nachgelagerte Verzögerung. Drück in der Spieleliste die Taste, die auf INPUT_SERVICE gelegt ist (standardmäßig die Taste 9), und wähle Audio Delay aus den Service-Tools (siehe Die Service-Tools). Der Bildschirm ist eine Seite im Dokument des Menüs: Er deckt das Menü schwarz ab, zeigt die gerade erprobte Verzögerung und die von der Engine gemessene Warteschlange des Geräts, spielt einmal pro Sekunde ein Klicken und wird bei jedem Blitz für einen Frame weiß. Stell mit links und rechts (10 ms) und hoch und runter (1 ms) nach, bis Blitz und Klicken zusammenfallen, und drück dann Knopf 1, um zu speichern. Start setzt auf null zurück, und Knopf 2 (oder noch einmal die Servicetaste) bricht ab. Der Wert wird in machine.cfg im obersten Datenordner gespeichert und von der Engine auf jedes Spiel auf diesem Rechner angewendet, ob es aus dem Menü oder von der Befehlszeile gestartet wird; er wird zu einem AUDIO_DELAY pro Spiel hinzuaddiert. Kalibriere neu, wenn du Lautsprecher, Kopfhörer oder Bildschirme wechselst.

Der Bildschirm funktioniert, weil das Klicken und der Ton der Disc ein Mixer-Gerät und eine Warteschlange teilen: Der Blitz wird um die gemessene Warteschlange plus den erprobten Wert nach dem Klicken angesetzt, sodass der erprobte Wert genau dann, wenn beide zusammenfallen, die Verzögerung ist, die die Engine nicht sehen kann. Die Verzögerung des Bildschirms ist gratis mit eingerechnet. Ein Spiel kann die Werte mit singeGetAudioCalibration und singeGetAudioLatency lesen oder mit singeSetAudioCalibration einen eigenen Bildschirm anbieten.

Zwei Eigenschaften der Videodatei selbst spielen ebenfalls eine Rolle. AAC-Audio enthält Priming-Samples des Encoders, die Decoder laut Container überspringen sollen; Dateien, die ohne diese Angabe gemuxt wurden (ein MP4 ohne Edit-Liste, eine Matroska-Datei ohne Codec-Verzögerung), spielen ihren Ton etwa 20 Millisekunden zu spät, was AUDIO_DELAY auffangen kann. Und wenn der erste Videoframe einen späteren Zeitstempel hat als das erste Audio-Sample, beachtet Singe die Zeitangaben des Containers, sodass vorauslaufender Ton nicht verloren geht.

1.23. Video-, Audio- und Containerformate

Singe dekodiert Video direkt mit den Bibliotheken von FFmpeg und nutzt dabei den Hardware-Decoder der Plattform, wenn sie einen für den Codec bietet (VA-API oder VDPAU unter Linux, D3D11VA unter Windows, VideoToolbox unter macOS und auf einem ARM-Board die V4L2-Decoder — den Memory-to-Memory-Decoder, der auf einem Pi 4 H.264 abdeckt, den zustandslosen Request-API-Decoder, den ein Pi 5 für HEVC nutzt, und den eigenen von Rockchip auf einem RK3588), andernfalls seinen eigenen Software-Decoder; der Programm-Trace meldet, welcher es ist, und --softwarevideo erzwingt Software. Jeder Container und Codec, den das mitgelieferte FFmpeg demuxen und dekodieren kann, wird abgespielt: MP4, MKV, MPEG-Programmstreams, AVI, AV1 und die klassischen Daphne-Elementarstreams .m2v mit einer passenden .ogg-Audiodatei daneben. Jede Audiospur in der Datei steht discSetAudioTrack / videoSetAudioTrack zur Verfügung; alle Spuren müssen dasselbe Sample-Format, dieselbe Kanalzahl und dieselbe Rate haben.

Eine Laserdisc enthielt Halbbilder im Zeilensprungverfahren, und ein Rip, der sie beibehalten hat, zeigt auf jedem progressiven Display Kammartefakte. --deinterlace entscheidet, was geschieht: auto, der Standard, lässt bwdif über die Frames laufen, die die Datei als interlaced markiert, und lässt alles andere in Ruhe, sodass eine progressive Disc nichts kostet; on ist für eine Datei, deren Markierungen falsch sind; off rührt das Bild nie an. Für jedes Bild, das hineingeht, kommt eines heraus — eine Disc wird über Frame-Nummern angesprochen, also würde ein Deinterlacer, der aus jedem Frame zwei Halbbilder macht, jeden Frame im Index verschieben.

Wenn ein Video zum ersten Mal geöffnet wird, indiziert Singe es und speichert den Index neben den anderen Daten des Spiels (<name>-<hash>.index, wobei der Hash aus dem vollen Namen des Videos gebildet wird, sodass zwei Videos mit demselben Basisnamen getrennte Indizes behalten). Das Indizieren ist ein Durchgang über die Datei ohne Dekodieren, ein paar Sekunden selbst für eine Disc in Spielfilmlänge, und geschieht erneut, wenn sich das Video ändert. Wenn ein Video geladen wird, meldet Singe im Programm-Trace (--program) den Abstand seiner Keyframes, mit einer Warnung dort, wenn Keyframes mehr als zwei Sekunden auseinanderliegen, weil ein Sprung vom vorigen Keyframe aus vorwärts dekodieren muss. Das Dekodieren geschieht in einem eigenen Thread, sodass ein langsamer Sprung den vorigen Frame etwas länger zeigt, statt das Spiel anzuhalten.

Die Segmente einer Frame-Datei werden geöffnet, wenn die Disc sie erreicht, nicht alle auf einmal: das, das gerade spielt, das danach und Platz für einen Sprung zwischen zweien. Eine lange Frame-Datei kann Hunderte von Segmenten haben — ein veröffentlichtes Spiel hat 213 — und für jedes davon einen Decoder offen zu halten, kostet Hunderte offener Dateien ohne jeden Gewinn. Eine Frame-Datei, die eine Datei nennt, die nicht da ist, meldet das weiterhin beim Start.

Bei Laserdisc-Material zählen Frame-Genauigkeit und Sprunggeschwindigkeit, nicht Kompression. H.264 in MP4 oder MKV mit kurzem Keyframe-Intervall (eine oder zwei Sekunden) springt schnell und spielt auf jeder unterstützten Plattform; lange Keyframe-Intervalle machen discSearch sichtbar langsam, weil der Decoder vom vorigen Keyframe aus vorwärtsgehen muss. Standardauflösung (720x480 oder 720x576) ist das Optimum. Quellen in hoher Auflösung funktionieren, kosten aber auf Hardware der Raspberry-Pi-Klasse entsprechend mehr CPU, und das Overlay hat standardmäßig die halbe Videoauflösung, sodass übergroßes Video wenig bringt.

Soundeffekte und Musik liest zuerst SDL_mixer und FFmpeg alles, was SDL_mixer ablehnt, sodass beide zusammen Folgendes abdecken:

  • WAV, AIFF, AU und VOC für unkomprimiertes Audio. Kurze unkomprimierte WAV-Dateien haben die geringste Latenz und sind das, was ein Schuss sein sollte.

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

  • AAC (.m4a, .aac), ALAC, AC-3, WMA, APE, TTA, Speex und AMR — alles andere, was das mitgelieferte FFmpeg dekodiert.

  • Tracker-Module über libxmp: MOD, S3M, XM und IT sowie rund fünfzig weitere, darunter 669, AMF, MED, OKT, PTM, STM und ULT.

  • Chiptunes über game-music-emu: NSF und NSFE, SPC, VGM, GBS, AY, GYM, HES, KSS und SAP. Die gzip-komprimierte Form VGZ wird nicht gelesen; entpacke sie vorher zu VGM. Ein Chiptune, der seine Länge nicht angibt, spielt, bis er verstummt, und das muss nie geschehen; deshalb wird er beim Abspielen dekodiert statt vorab.

  • MIDI, aus einem SoundFont synthetisiert. Siehe MIDI.

Die Zeile Audio: im Kopf des Trace (--program oder --trace) listet die Decoder auf, die der Build tatsächlich enthält.

Bilder funktionieren genauso: zuerst SDL_image, FFmpeg für den Rest. Das deckt PNG, JPEG, WebP, GIF, BMP, TGA, PCX, PNM, LBM, QOI, XCF, XPM und SVG über SDL_image ab und TIFF, OpenEXR, JPEG 2000, DDS, PSD, DPX, AVIF und HEIC über FFmpeg. Ein animiertes GIF oder WEBP wird als Sprite-Animation geladen; siehe spriteLoad, das auch eine Größe zum Rastern eines SVG annimmt. Radiance-.hdr und OpenEXR funktionieren beide als Himmel (sceneSetSky) und behalten ihren vollen Umfang.

Schriftarten liest FreeType: TrueType, OpenType, WOFF, WOFF2, Type 1, BDF und PCF, mit Farbglyphen (als Bitmap wie als Vektor) und HarfBuzz-Shaping für Arabisch, Hebräisch und die indischen Schriften.

Kapitel 2. Lua-API-Referenz

Dieses Kapitel dokumentiert die Lua-API, die die Singe-Engine bereitstellt — jede Funktion, die dein Spielskript aufrufen kann, und jeden Callback, den Singe bei dir aufruft. Es richtet sich an Entwickler, die neue Spiele schreiben oder videolastige Spiele von anderen Engines portieren.

2.1. Konventionen

Jeder API-Eintrag unten folgt demselben Aufbau:

  • Signatur(en) in einem Codeblock, mit jeder akzeptierten Form.

  • Beschreibung dessen, was die Funktion tut, und aller Nebenwirkungen.

  • Parameter, im Fließtext aufgeführt oder als Tabelle, wenn es mehr als zwei sind.

  • Rückgabe-Zeile, die den an Lua zurückgegebenen Wert beschreibt (entfällt, wenn die Funktion nichts zurückgibt).

  • Hinweise, wenn es Fallstricke gibt, die einen Hinweis wert sind.

  • Seit — die Singe-Version, in der die Funktion zuerst erschienen ist.

  • Siehe auch — verwandte Funktionen, die du wahrscheinlich an derselben Stelle benutzt.

  • Beispiel — ein kurzer, realistischer Ausschnitt in der Form echten Spielcodes.

Ein Eintrag, der mit Hypseus-Erweiterung beginnt, ist da, damit ein für Hypseus Singe geschriebenes Spiel hier unverändert läuft. Dasselbe gilt für eine als die von Hypseus gekennzeichnete Argumentform bei einer Funktion, die sonst die von Singe nimmt.

Schreib keine neuen Spiele gegen die Hypseus-API. Diese Einträge gibt es aus Gründen der Kompatibilität, nicht als Empfehlung. Mehrere von ihnen antworten mit einem festen Wert, weil es das, was sie beschreiben, in Singe nicht gibt, manche werden angenommen und ignoriert, und andere tragen Skalen und Argumentreihenfolgen, die von einer anderen Engine geerbt sind — videoGetVolume() zählt bis 64, wo der Rest von Singe bis 100 zählt, und die spriteAnim-Namen nehmen das Sprite zuletzt, wo jeder Sprite-Aufruf von Singe es zuerst nimmt. Jeder Eintrag nennt das Singe-Gegenstück, das du stattdessen benutzen sollst. Neuer Code, der bei der Singe-API bleibt, ist kürzer, in sich einheitlich und wird nicht überrascht, wenn eine Kompatibilitätsantwort konstant bleibt.

Ein paar Regeln gelten für die ganze API:

  • Farben haben 8 Bit pro Kanal: Rot, Grün, Blau und Deckkraft sind jeweils Ganzzahlen von 0 bis 255.

  • Overlay-Koordinaten sind in der aktuellen Overlay-Auflösung angegeben (gesetzt mit overlaySetResolution), nicht in Bildschirmpixeln. Die Standardauflösung des Overlays ist in jeder Dimension die halbe Videoauflösung; rufe overlaySetResolution auf, um sie zu ändern.

  • Handles, die *Load-Funktionen zurückgeben (Sprites, Sounds, Schriftarten, Videos), sind opake Ganzzahlen. Gib sie unverändert an die anderen Funktionen dieses Namensraums zurück. Rechne nicht mit ihnen.

  • Ungültige Argumente brechen das Skript ab. Wird eine Funktion mit der falschen Anzahl von Argumenten, mit falschen Typen oder mit einem Handle aufgerufen, das bereits entladen wurde, beendet Singe das laufende Skript mit einem Fehler — es gibt nicht nil oder einen Fehlercode zurück. Prüfe Benutzereingaben in deinem Skript, bevor du sie an die API übergibst.

  • Gezeichnet werden muss aus onOverlayUpdate. Aufrufe einer Funktion overlay*, spriteDraw, videoDraw oder fontPrint aus anderen Callbacks erscheinen nicht auf dem Bildschirm und können das Overlay beschädigen. Das ist die eine Regel, über die jeder neue Singe-Entwickler stolpert.

2.2. Animation

Diese Aufrufe steuern die Animationen, die ein Modell mitbringt, pro Instanz. Jeder von ihnen nimmt den Wurzelknoten, den modelInstance zurückgibt; andere Knoten lösen einen Fehler aus, außer bei animationIsPlaying, das false antwortet. Animationen sind ab 1 in der Reihenfolge nummeriert, in der modelGetAnimations sie auflistet, oder so benannt, wie die Datei sie benennt. Ein Clip spielt auf der Basisebene, und bis zu vier weitere können auf den Ebenen 1 bis 4 darüber spielen; die Aufrufe für Zeit, Pause, Fortsetzen und Sprung betreffen nur die Basisebene. Die Zeit wird in Sekunden gemessen, läuft mit der Uhr um höchstens eine Zehntelsekunde pro Frame weiter und steht still, solange das Spiel pausiert ist. Knotenanimation, Skinning und Morph-Target-Gewichte werden alle gesteuert. Siehe den Teil Animation in 3D-Szenen.

2.2.1. animationGetTime

seconds = animationGetTime(node)

Die aktuelle Zeit im Clip der Basisebene, ob er spielt oder pausiert, in den eigenen Sekunden des Clips (ein speed von 2 bewegt sie doppelt so schnell). Ein Clip in Schleife springt an seinem Ende auf 0 zurück; einer ohne Schleife bleibt bei seiner Länge stehen. Wurde noch nichts gespielt, ergibt das 0. Clips auf den oberen Ebenen werden nicht gemeldet. Ein Knoten, der keine Instanzwurzel ist, beendet das Skript.

Rückgabe: Sekunden als Zahl.

Seit: 3.00. Siehe auch: animationSetTime, animationIsPlaying

Beispiel
-- Spiel den Schritt jedes Mal einmal, wenn der Laufzyklus seine zwei Aufsetzpunkte passiert.
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)

Ob der Clip der Basisebene auf dieser Instanz weiterläuft. Ein Clip ohne Schleife hört auf zu spielen, wenn er sein Ende erreicht, und animationPause und animationStop machen dies beide false; ein Clip in Schleife bleibt true, bis er gestoppt wird. Anders als bei den übrigen Aufrufen hier beendet ein Knoten, der keine Instanzwurzel ist, nicht das Skript, sondern bekommt false als Antwort.

Rückgabe: Boolean.

Seit: 3.00. Siehe auch: animationPlay, animationPause

Beispiel
-- Zurück zum Leerlauf, sobald der einmalige Angriff abgelaufen ist.
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)

Friert den Clip der Basisebene bei seiner aktuellen Zeit ein; die Knoten halten diese Pose, bis animationResume ihn fortsetzt oder ein anderer Clip gespielt wird. Clips auf den oberen Ebenen laufen weiter. Eine Instanz zu pausieren, auf der nichts spielt, ist harmlos. Ein Knoten, der keine Instanzwurzel ist, beendet das Skript.

Seit: 3.00. Siehe auch: animationResume, animationSetTime

Beispiel
-- Eine Zwischensequenz friert die Menge ein, während sich die Kamera bewegt.
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)

Startet einen der Clips des Modells von seinem Anfang an auf der Basisebene dieser Instanz und ersetzt, was dort gespielt hat; die Pose wird sofort aktualisiert. Mit einem fade läuft der alte Clip weiter, während er über so viele Sekunden ausgeblendet wird, und wenn nichts gespielt hat, beginnt die Überblendung bei der Pose, in der die Knoten gerade sind (eine eben abgeschaltete Ragdoll, eine per Skript gesetzte Pose), wobei Knoten, die der neue Clip nicht animiert, sanft in die Ruhepose des Modells zurückgleiten. Ein Knoten, der keine Instanzwurzel ist, ein Name, den das Modell nicht hat, oder eine Zahl außerhalb von 1 bis zur Anzahl der Clips beendet das Skript.

Parameter:

  • node — der Wurzelknoten der Instanz aus modelInstance.

  • nameOrIndex — ein Clipname, wie ihn die Datei speichert, oder seine Nummer ab 1 in der Reihenfolge von modelGetAnimations.

  • loop — Boolean, Standard true. Bei false bleibt der Clip bei seinem letzten Keyframe stehen, und animationIsPlaying wird false.

  • speed — Abspielrate, Standard 1. 2 ist doppelt so schnell; 0.5 ist halb so schnell.

  • fade — Sekunden für die Überblendung von dem, was gespielt hat, Standard 0 (ein harter Wechsel).

Beispiel
-- Eine Wache, die untätig herumsteht, bis der Spieler entdeckt wird, und dann rennt.
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)

Spielt einen Clip auf einer der vier Ebenen über der Basis, über alles darunter geblendet nach dem Gewicht der Ebene (animationSetLayerWeight, Standard 1) und auf einen Teil des Skeletts beschränkt, wenn eine Maske gesetzt ist (animationSetLayerMask). Höhere Ebenen werden über niedrigere geblendet; jede Ebene führt ihren eigenen Clip, ihre eigene Zeit und Schleife unabhängig von der Basis. nameOrIndex, loop, speed und fade bedeuten dasselbe wie bei animationPlay, mit einem Unterschied: Ein fade auf einer Ebene, die leer war, fährt das Gewicht der Ebene von 0 hoch, statt von einer Pose überzublenden. Eine Ebene außerhalb von 1 bis 4, ein Knoten, der keine Instanzwurzel ist, oder ein Clip, den das Modell nicht hat, beendet das Skript.

Parameter:

  • node — der Wurzelknoten der Instanz.

  • layer — 1 bis 4.

  • nameOrIndex — ein Clipname oder eine Clipnummer, wie bei animationPlay.

  • loop — Standard true.

  • speed — Standard 1.

  • fade — Sekunden, Standard 0.

Beispiel
-- Mit dem ganzen Körper gehen, sich nur mit dem Kopf umsehen.
animationPlay(fox, "Walk", true)
animationPlayLayer(fox, 1, "Survey", true, 1, 0.5)
animationSetLayerMask(fox, 1, nodeFind("b_Neck_04", fox))

-- Später mit einem Arm winken, egal, was die Beine gerade tun.
function onGreet()
    animationPlayLayer(fox, 2, "Wave", false, 1, 0.2)
end

2.2.6. animationResume

animationResume(node)

Setzt den Clip der Basisebene dort fort, wo animationPause ihn eingefroren hat, oder dort, wohin animationSetTime ihn inzwischen bewegt hat. Einen Clip fortzusetzen, der bereits spielt, ändert nichts. Eine Instanz ohne Clip auf ihrer Basisebene (nie gespielt oder gestoppt) beendet das Skript, ebenso ein Knoten, der keine Instanzwurzel ist.

Seit: 3.00. Siehe auch: animationPause, animationSetTime

Beispiel
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)

Beschränkt eine Ebene auf maskNode und alles darunter, sodass der Clip auf dieser Ebene nur diesen Teil des Modells bewegt und der Rest weiter den Ebenen darunter folgt. maskNode muss einer der eigenen Knoten der Instanz sein, gefunden mit nodeFind(name, node); die Instanzwurzel selbst zählt nicht. maskNode wegzulassen oder nil zu übergeben hebt die Beschränkung auf. Die Maske bleibt über spätere Aufrufe von animationPlayLayer hinweg auf der Ebene. Eine Ebene außerhalb von 1 bis 4 beendet das Skript, ebenso ein Knoten, der keine Instanzwurzel ist, oder ein maskNode, der nicht zu dieser Instanz gehört.

Parameter:

  • node — der Wurzelknoten der Instanz.

  • layer — 1 bis 4.

  • maskNode — ein Gelenk oder Knoten der Instanz; weggelassen oder nil für das ganze Modell.

Beispiel
-- Den Oberkörper auf das Ziel richten, während die Beine weitergehen.
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)

Wie stark der Clip einer Ebene über dem durchscheint, was darunter liegt, 0 (gar nicht) bis 1 (voll, der Standard); Werte außerhalb dieses Bereichs werden begrenzt. Das Gewicht gehört zur Ebene, nicht zum Clip, also übersteht es animationPlayLayer und animationStop auf dieser Ebene. Ändere es jeden Frame ein wenig, um eine Ebene von Hand ein- oder auszublenden, oder lass einen fade bei animationPlayLayer das einmal erledigen. Eine Ebene außerhalb von 1 bis 4 oder ein Knoten, der keine Instanzwurzel ist, beendet das Skript.

Seit: 3.00. Siehe auch: animationPlayLayer, animationSetLayerMask

Beispiel
-- Das Hinken wird schlimmer, je weniger Gesundheit bleibt.
function onHealthChanged(health)
    local limp = 1 - health / maxHealth
    animationSetLayerWeight(hero, 1, limp)
end

2.2.9. animationSetTime

animationSetTime(node, seconds)

Lässt den Clip der Basisebene zu einer Zeit in seinen eigenen Sekunden springen; negative Werte werden zu 0. Die Pose wird sofort aktualisiert, ob der Clip spielt oder nicht, sodass eine pausierte Instanz auf einen genauen Frame gespult werden kann und eine spielende von der neuen Zeit aus weiterläuft. Eine laufende Überblendung auf der Basisebene wird abgebrochen. Eine Instanz ohne Clip auf ihrer Basisebene beendet das Skript, ebenso ein Knoten, der keine Instanzwurzel ist.

Seit: 3.00. Siehe auch: animationGetTime, animationPause, animationResume

Beispiel
-- Eine Tür, deren Öffnungsclip einem Hebel folgt, den der Spieler zieht.
animationPlay(door, "Open", false)
animationPause(door)

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

2.2.10. animationStop

animationStop(node)
animationStop(node, layer)

Stoppt und vergisst jeden Clip auf der Instanz oder nur den Clip auf einer Ebene über der Basis (1 bis 4); die Basisebene allein lässt sich nicht ohne die Ebenen darüber stoppen. Die Knoten behalten ihre letzte Pose, aus der ein folgendes animationPlay mit einem fade sanft herausführt. Nachdem alles gestoppt wurde, beenden animationResume und animationSetTime das Skript, bis wieder etwas gespielt wird. Gewichte und Masken der Ebenen bleiben erhalten. Eine Ebene außerhalb von 1 bis 4 oder ein Knoten, der keine Instanzwurzel ist, beendet das Skript.

Seit: 3.00. Siehe auch: animationPlay, animationPlayLayer, animationPause

Beispiel
-- Den Körper an die Physik-Ragdoll übergeben: die Pose einfrieren, dann fallen lassen.
function onKilled()
    animationStop(hero)
    ragdollActivate(hero)
end

-- Das Winken auf Ebene 2 ist fertig; das Gehen darunter läuft weiter.
function onWaveFinished()
    animationStop(hero, 2)
end

2.3. Bezel

Das Artwork des Automaten und die Arcade-Punktetafel, die dazugehört. mainBezelLoaded fragt nach dem Artwork, das --bezel geladen hat; die scoreBezel-Familie steuert die Punkteanzeige, ein RmlUi-Dokument, das die Engine mitliefert und das ein Spiel durch eine eigene Kopie ersetzen kann, scoreBezel.rml neben seinem Skript. Jeder Aufruf hier ist eine Erweiterung von Hypseus Singe, beibehalten, damit dessen Spiele unverändert laufen, und jeder davon wird aus Sicht des Spielers in Bezels beschrieben.

Die Anzeige startet ausgeschaltet, wie in Hypseus, und nur ein Spiel schaltet sie ein. Werte, die ihr übergeben werden, bleiben gespeichert, ob sie angezeigt wird oder nicht, sodass ein Spiel sie setzen darf, bevor es die Anzeige einschaltet. Jedes Anzeigefeld hat so viele Stellen wie die Punktetafel von Hypseus — sechs für eine Punktzahl, zwei für die Credits, eine für die Zahl der Leben — und ein Wert wird darin rechtsbündig mit führenden Nullen angezeigt; eine Punktzahl mit mehr als sechs Stellen zeigt ihre letzten sechs. Auch die negativen Werte von Hypseus werden verstanden: -2 lässt in jeder Stelle einen Strich leuchten, -4 ein H und -5 ein A, und -1, -3 und jede andere negative Zahl lassen nichts leuchten.

2.3.1. mainBezelLoaded

loaded, id = mainBezelLoaded()

Hypseus-Erweiterung. Ob --bezel Artwork für den Automaten geladen hat, und die Kennung der geladenen Datei. Die Kennung ist der 64-Bit-FNV-1a-Hash der Bytes der Datei, als Dezimalstring ausgeschrieben, und genau das meldet auch Hypseus, sodass ein Spiel, das ein bestimmtes Bezel an seiner Nummer erkennt, hier dieselbe Datei erkennt. Ist kein Artwork geladen, lauten die Antworten false und "0".

Rückgabe: Boolean und die Kennung als String.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: setOverlayOnTop, Bezels

Beispiel
-- Den Sprite-Rahmen nur zeichnen, wenn der Spieler kein eigenes Artwork hat.
local loaded, id = mainBezelLoaded()
if not loaded then
    spriteDraw(frameSprite, 0, 0)
end

2.3.2. scoreBezelClear

scoreBezelClear()

Hypseus-Erweiterung. Leert jedes Anzeigefeld der Punkteanzeige: Die Credits, beide Punktzahlen und beide Lebensanzeigen zeigen gar nichts mehr, nur die abgedunkelten Ziffern dahinter bleiben. Die Werte werden nicht vergessen, aber das nächste scoreBezelCredits, scoreBezelScore oder scoreBezelLives lässt die Anzeige wieder mit dem leuchten, was sie dann enthält. Kann bei ausgeschalteter Anzeige gefahrlos aufgerufen werden.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelEnable

2.3.3. scoreBezelCredits

scoreBezelCredits(credits)

Hypseus-Erweiterung. Setzt das Anzeigefeld für die Credits, das zwei Stellen hat. Lässt außerdem eine Anzeige wieder leuchten, die scoreBezelClear geleert hat.

Parameter:

  • credits — Ganzzahl; die letzten zwei Stellen werden angezeigt.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelScore

2.3.4. scoreBezelEnable

scoreBezelEnable(enabled)
scoreBezelEnable(enabled, type)

Hypseus-Erweiterung. Blendet die Punkteanzeige ein oder aus. Das erste true baut sie aus der eigenen scoreBezel.rml des Spiels neben seinem Skript, wenn es eine gibt, und sonst aus Singe/scoreBezel.rml; sie danach aus- und wieder einzublenden kostet nichts und behält ihre Werte. Sie startet ausgeblendet, so wie auch Hypseus ausgeliefert wird, sodass sich ein Spiel, das dies nie aufruft, genau wie zuvor verhält — und es sollte scoreBezelGetState fragen, bevor es annimmt, dass es eine hat.

Das type von Hypseus wählt zwischen dessen fünf Backends für die Punktetafel. Singe hat eines, ein RmlUi-Dokument, also wird das Argument geprüft und ignoriert. Ein Rechner ohne GPU hat überhaupt keine GUIs; dort kann die Anzeige nicht gebaut werden, scoreBezelGetState antwortet weiter false, und eine Warnung wird einmal ausgegeben. Ein erstes Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

  • type — Ganzzahl, angenommen und ignoriert.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelGetState, Bezels

Beispiel
-- Die Anzeige der Engine, wenn es eine gibt, Sprites, wenn nicht.
scoreBezelEnable(true, 0)
if scoreBezelGetState() then
    scoreBezelTwinScoreOn(twoPlayer)
    scoreBezelCredits(credits)
else
    drawSpriteScoreboard()
end

2.3.5. scoreBezelGetState

state = scoreBezelGetState()

Hypseus-Erweiterung. Ob die Punkteanzeige zu sehen ist. Jedes Hypseus-Spiel fragt dies, bevor es die Anzeige benutzt, und zeichnet seine eigene Punktetafel mit Sprites, wenn die Antwort false ist, was der richtige Ausweg und kein Fehler ist.

Rückgabe: Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelEnable

2.3.6. scoreBezelLives

scoreBezelLives(player, lives)

Hypseus-Erweiterung. Setzt das Anzeigefeld für die Leben eines Spielers, das eine Stelle hat. player ist 1 oder 2; jede andere Zahl wird ignoriert, ebenso 2, bis scoreBezelTwinScoreOn(true) die Anzeigefelder des zweiten Spielers auf die Anzeige gebracht hat. Lässt außerdem eine Anzeige wieder leuchten, die scoreBezelClear geleert hat.

Parameter:

  • player — 1 oder 2.

  • lives — Ganzzahl; die letzte Stelle wird angezeigt.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelScore

2.3.7. scoreBezelScore

scoreBezelScore(player, score)

Hypseus-Erweiterung. Setzt das Anzeigefeld für die Punktzahl eines Spielers, das sechs Stellen hat. player ist 1 oder 2, mit derselben Regel für 2 wie bei scoreBezelLives. Lässt außerdem eine Anzeige wieder leuchten, die scoreBezelClear geleert hat.

Parameter:

  • player — 1 oder 2.

  • score — Ganzzahl; die letzten sechs Stellen werden angezeigt.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelLives

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

2.3.8. scoreBezelTwinScoreOn

scoreBezelTwinScoreOn(enabled)

Hypseus-Erweiterung. Bringt die Anzeigefelder für Punktzahl und Leben des zweiten Spielers auf die Anzeige oder nimmt sie wieder herunter und überlässt den Platz den anderen beiden. Sie abzuschalten leert auch die Anzeige, genau wie in Hypseus, also lass einen Wert folgen, wenn die Anzeigefelder des ersten Spielers leuchten sollen. Solange sie aus sind, tun scoreBezelScore(2, …​) und scoreBezelLives(2, …​) nichts. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: scoreBezelScore

2.4. Körper

Ein Körper gibt einem Szenenknoten einen Platz in der Physikwelt. Es gibt einen Körper pro Knoten, angesprochen über das Knoten-Handle: Ein statischer Körper bleibt, wo der Knoten war, als der Körper erzeugt wurde, ein kinematischer Körper folgt bei jedem Schritt seinem Knoten und schiebt, ohne geschoben zu werden, und ein dynamischer Körper wird von der Simulation bewegt und treibt seinen Knoten. Größen, Positionen und Geschwindigkeiten sind in Welteinheiten angegeben (Meter in einer 3D-Szene, Overlay-Pixel in einer 2D-Welt), Massen in Kilogramm und Zeit in Sekunden. Jeder Aufruf hier beendet das Skript, wenn der Knoten keinen Körper hat; ein Aufruf, der nur für eine Art von Körper sinnvoll ist (etwa eine Kraft auf einen statischen Körper), wird bei den anderen ignoriert, außer bodySetMass, das einen Fehler auslöst. Wie Körper, Knoten und der Frame zusammenpassen, steht unter Physik in Spieleentwicklung.

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)

Gibt dem Knoten einen Körper des angegebenen Typs, dort platziert, wo der Knoten gerade in der Welt ist (seine Eltern eingeschlossen), mit einer Kollisionsform, die durch a, b und c in Welteinheiten bemessen und mit der Weltskalierung des Knotens skaliert wird. Ein zweiter Aufruf auf demselben Knoten ersetzt den ersten, und ein Knoten, der eine Spielfigur hatte, verliert sie. Die Masse eines dynamischen Körpers ergibt sich aus dem Volumen seiner Form bei der Dichte von Wasser, also setze bodySetMass bei allem, was sich leicht anfühlen soll. Die Skalierung des Knotens später zu ändern, ändert die Größe des Körpers nicht. Beendet das Skript bei einem unbekannten Typ oder einer unbekannten Form, wenn auf diesem Rechner keine Physik verfügbar ist, wenn die Welt bereits 4096 Körper enthält oder wenn die Form nicht gebaut werden kann (ein dynamisches SHAPE_MESH oder eine Hülle ohne Mesh unter dem Knoten).

Parameter:

  • type — BODY_STATIC, BODY_DYNAMIC oder BODY_KINEMATIC.

  • shape — SHAPE_BOX (a, b, c sind Breite, Höhe und Tiefe), SHAPE_SPHERE (a ist der Radius), SHAPE_CAPSULE oder SHAPE_CYLINDER (a ist der Radius, b die Gesamthöhe entlang Y, Kappen eingeschlossen), SHAPE_HULL (eine konvexe Hülle um das Mesh des Knotens und alles darunter, keine Größen) oder SHAPE_MESH (die exakten Dreiecke, nur für statische und kinematische Körper; ein Heightmap-Mesh wird zu einem Höhenfeld).

  • a, b, c — die Größen, die die Form braucht; fehlende sind 0, und jede Größe wird auf mindestens 0.001 angehoben.

Hinweise: Eine Kugel wird mit der größten Skalierungsachse des Knotens skaliert, der Radius einer Kapsel oder eines Zylinders mit der größeren von X und Z. Eine Kapsel, die kürzer als ihr doppelter Radius ist, ist eine Kugel mit einem schmalen Stück in der Mitte.

Seit: 3.00. Siehe auch: bodySetMass, bodyDelete, physicsSetGravity, playerNew

Beispiel
-- Eine leichte Kiste und ein Entenmodell als Hülle, auf den Boden fallen gelassen.
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)

Übt auf einen dynamischen Körper eine Kraft in Newton aus, nur für die Schritte dieses Frames; ruf es jeden Frame auf, um weiter zu schieben. Ohne Punkt wirkt die Kraft durch den Schwerpunkt und bewegt den Körper nur; mit einem Weltpunkt (px, py, pz) dreht sie den Körper außerdem um seinen Mittelpunkt. Eine Kraft beschleunigt um Kraft geteilt durch Masse, also bemiss sie nach bodySetMass. Statische und kinematische Körper ignorieren sie.

Parameter:

  • fx, fy, fz — die Kraft in Newton entlang jeder Weltachse.

  • px, py, pz — optionaler Weltpunkt, an dem die Kraft angreift; weglassen für den Schwerpunkt.

Seit: 3.00. Siehe auch: bodyApplyImpulse, bodySetMass

Beispiel
-- Ein Ventilator bläst den Ballon durch den Raum, solange der Schalter an ist.
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)

Ändert den Impuls eines dynamischen Körpers auf einen Schlag: Ein Impuls von Masse mal Geschwindigkeit fügt diese Geschwindigkeit hinzu. Ohne Punkt wirkt er durch den Schwerpunkt; mit einem Weltpunkt (px, py, pz) dreht er den Körper außerdem, sodass ein Treffer nahe der Oberkante einer Kiste sie umkippt. Das ist der Aufruf für einen Treffer, einen Tritt, eine Explosion oder einen Abschuss, während bodyApplyForce für ein Schieben ist, das anhält. Statische und kinematische Körper ignorieren ihn.

Parameter:

  • ix, iy, iz — der Impuls in Kilogramm mal Meter pro Sekunde entlang jeder Weltachse.

  • px, py, pz — optionaler Weltpunkt, an dem der Impuls angreift; weglassen für den Schwerpunkt.

Seit: 3.00. Siehe auch: bodyApplyForce, bodySetVelocity, physicsRaycast

Beispiel
-- Schnipp, was unter der Maus ist, senkrecht nach oben, an der Stelle, an der es getroffen wurde.
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)

Entfernt den Körper aus der Welt; der Knoten und sein Mesh bleiben, wo sie sind. Jedes Gelenk, das am Körper hängt, und jedes darauf gebaute Fahrzeug verschwindet mit ihm. Den Knoten zu löschen entfernt auch seinen Körper, also wird dies nur gebraucht, um einen Knoten ohne seinen Körper zu behalten. Beendet das Skript, wenn der Knoten keinen Körper hat.

Seit: 3.00. Siehe auch: bodyNew, bodySetEnabled, jointDelete

Beispiel
-- Eine eingesammelte Münze ist nicht mehr fest und schwebt als einfacher Knoten nach oben.
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)

Wie schnell sich der Körper um jede Weltachse dreht, in Radiant pro Sekunde, beim letzten Schritt. Ein statischer Körper meldet null. Nützlich für die Tonhöhe eines Rads oder einen Drehzähler.

Rückgabe: Drei Zahlen, Radiant pro Sekunde um X, Y und Z.

Seit: 3.00. Siehe auch: bodySetAngularVelocity, bodyGetVelocity

Beispiel
-- Der Roulettekessel steht, wenn er sich kaum noch dreht.
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)

Wie schnell sich der Körper entlang jeder Weltachse bewegt, in Welteinheiten pro Sekunde, beim letzten Schritt. Ein statischer Körper meldet null; ein kinematischer Körper meldet die Geschwindigkeit, die sich aus der Bewegung seines Knotens ergab.

Rückgabe: Drei Zahlen, Einheiten pro Sekunde entlang X, Y und Z.

Seit: 3.00. Siehe auch: bodySetVelocity, bodyGetAngularVelocity

Beispiel
-- Ein Zischen abspielen, wenn der Ball richtig in Fahrt ist.
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)

Ob die Simulation den Körper schlafen gelegt hat, weil er sich nicht mehr bewegt. Statische Körper und mit bodySetEnabled aus der Welt genommene Körper gelten als ruhend. Ein ruhender Körper wacht von selbst auf, wenn ihn etwas berührt oder wenn eine Geschwindigkeit, eine Kraft oder ein Impuls angewendet wird.

Rückgabe: Boolean.

Seit: 3.00. Siehe auch: bodySetEnabled, bodySetVelocity

Beispiel
-- Die Runde endet, sobald jeder Kegel zur Ruhe gekommen ist.
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)

Setzt die Drehung um jede Weltachse, in Radiant pro Sekunde, und weckt den Körper. Statische Körper ignorieren es. Die Drehung eines kinematischen Körpers wird beim nächsten Schritt von seinem Knoten überschrieben, also wirkt der Aufruf nur bei dynamischen Körpern fort.

Seit: 3.00. Siehe auch: bodyGetAngularVelocity, bodySetVelocity

Beispiel
-- Die Münze werfen: nach oben und sich dabei überschlagend.
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)

Setzt die Restitution des Körpers, von 0 (bleibt sofort liegen) bis 1 (prallt mit allem zurück, womit er ankam); Werte außerhalb dieses Bereichs werden begrenzt. Der Standard ist 0.1. Die Werte der beiden sich berührenden Körper werden kombiniert, sodass ein lebhafter Ball auf einem dämpfenden Boden trotzdem springt.

Seit: 3.00. Siehe auch: bodySetFriction, bodyNew

Beispiel
-- Ein Gummiball, in die Szene fallen gelassen.
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)

Wie der Körper schwimmt, wenn er in einem Wasservolumen ist: 1 ist neutral, mehr schwimmt höher, weniger sinkt, und 0 ist ein Stein. Der Standard ist 1.2, das sanft schwimmt. Der Faktor multipliziert die eigene Dichte des Wassers aus bodySetWater, und negative Werte werden auf 0 begrenzt. Nur dynamische Körper werden von Wasser bewegt, aber der Wert kann auf jedem Körper gesetzt werden.

Seit: 3.00. Siehe auch: bodySetWater, bodySetCurrent

Beispiel
-- Eine Kiste, die hoch im Wasser liegt, ein Anker, der untergeht, ein Ball, der auf und ab tanzt.
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)

Setzt die Strömung in einem Wasservolumen, in Welteinheiten pro Sekunde entlang jeder Weltachse; dynamische Körper, die darin schwimmen, treiben mit der Strömung, und eine schwimmende Spielfigur wird von ihr mitgetragen. Der Standard ist keine Strömung. Setze sie auf dem Knoten, auf dem bodySetWater aufgerufen wurde; auf jedem anderen Körper wird sie gespeichert und bewirkt nichts.

Seit: 3.00. Siehe auch: bodySetWater, bodySetBuoyancy

Beispiel
-- Ein Fluss, der alles, was hineinfällt, flussabwärts trägt.
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)

Nimmt den Körper mit false aus der Welt: Er kollidiert nicht mehr, bewegt sich nicht mehr, treibt seinen Knoten weder an noch folgt er ihm, und er gilt als ruhend. true setzt ihn dort wieder ein, wo er ist, und weckt ihn. Der Körper behält Form, Masse und Einstellungen, also ist das billiger, als ihn für etwas, das kommt und geht, zu löschen und neu zu erzeugen.

Seit: 3.00. Siehe auch: bodyIsResting, bodyDelete

Beispiel
-- Die Zugbrücke ist nur fest, solange sie unten ist.
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)

Setzt die Oberflächenreibung: 0 ist Eis, 0.5 (der Standard) ist gewöhnlich, höhere Werte greifen stärker. Negative Werte werden auf 0 begrenzt. Die Werte der beiden sich berührenden Körper werden kombiniert, sodass ein rutschiger Boden einen niedrigen Wert auf dem Boden braucht, nicht auf allem, was darauf läuft.

Seit: 3.00. Siehe auch: bodySetBounce, bodyNew

Beispiel
-- Ein zugefrorener Teich mitten im Level.
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)

Skaliert die Masse eines dynamischen Körpers und mit ihr seine Trägheit neu. Tu das bei allem, was sich leicht oder schwer anfühlen soll: Der Standard ist das Volumen der Form bei der Dichte von Wasser, sodass ein türgroßer Quader etwa 140 Kilogramm wiegt und ein Stups ihn nicht bewegt. Kräfte und Impulse skalieren mit der Masse, also setze die Masse, bevor du sie abstimmst. Beendet das Skript, wenn der Körper nicht dynamisch oder die Masse nicht positiv ist.

Seit: 3.00. Siehe auch: bodyNew, bodyApplyImpulse, playerSetPush

Beispiel
-- Eine Kiste, die der Held schieben kann, und ein Amboss, den niemand schieben kann.
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)

Macht den Körper mit true zum Trigger: Er schiebt nichts und hält nichts auf, aber onTrigger meldet jeden Körper und jede Spielfigur, die ihn betreten und verlassen. false macht ihn wieder fest: Was in ihm war, wird ohne Meldung des Verlassens vergessen, während ein Trigger, in dem der Körper selbst steht, ihn weiter meldet. Ein Trigger ist meist ein statischer Quader oder eine statische Kugel über einer Tür, einer Ziellinie oder einer Gefahrenzone. Strahlen aus physicsRaycast treffen Trigger wie jeden anderen Körper.

Hinweise: Eine Spielfigur gilt als in einem Trigger, wenn sich ihre Bounding Boxes überlappen, also ist ein runder Trigger für Spielfiguren ein eckiger.

Seit: 3.00. Siehe auch: onTrigger, bodyNew, bodySetWater

Beispiel
-- Eine Ziellinie quer über die Strecke.
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)

Setzt die Geschwindigkeit des Körpers entlang jeder Weltachse, in Welteinheiten pro Sekunde, und weckt ihn. Das ersetzt jede Geschwindigkeit, die der Körper hatte, während bodyApplyImpulse etwas hinzufügt. Statische Körper ignorieren es, und die Geschwindigkeit eines kinematischen Körpers wird beim nächsten Schritt aus der Bewegung seines Knotens überschrieben.

Beispiel
-- Den Ball zu der Seite hin aufschlagen, die den letzten Punkt verloren hat.
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)

Füllt einen statischen Körper mit Wasser und macht ihn zum Trigger: Die Oberseite seiner Form ist die Oberfläche, und jeder dynamische Körper darin schwimmt, sinkt oder rollt durch den Auftrieb gegen diese Oberfläche (der eingetauchte Teil der Form zählt, sodass eine schräge Kiste sich aufrichtet), gebremst durch die Widerstände. Eine Spielfigur, deren Mitte unter der Oberfläche liegt, schwimmt. Weil das Volumen ein Trigger ist, feuert onTrigger beim Hinein- und Hinausgehen. Das Wasser wird nicht gezeichnet: Gib dem Knoten ein Material mit Blending oder keines. Beendet das Skript, wenn der Körper nicht statisch ist.

Parameter:

  • density — ein Faktor, 1 für Wasser; das eigene bodySetBuoyancy jedes Körpers skaliert ihn. Negative Werte werden auf 0 begrenzt.

  • linearDrag — wie schnell das Wasser Bewegung durch sich hindurch bremst; Standard 0.5.

  • angularDrag — wie schnell es Drehung bremst; Standard 0.1.

Hinweise: Spielfiguren und Boote sehen höchstens acht Wasservolumen; weitere lassen Körper trotzdem schwimmen, aber in ihnen wird nicht geschwommen.

Beispiel
-- Ein ins Deck eingelassenes Becken; seine Oberseite bei Y = 0 ist die Oberfläche.
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. Kamera

Die Kamera ist ein Knoten wie jeder andere: Platziere sie mit nodeSetPosition, richte sie mit nodeLookAt aus, häng sie für eine Verfolgeransicht an ein bewegtes Objekt und benenne sie mit cameraSet. Sie blickt entlang ihrer eigenen -Z-Richtung. Ohne Kameraknoten wird die Szene von (0, 0, 5) aus mit Blick auf den Ursprung betrachtet. Die Projektion wird getrennt gesetzt und gilt für den Knoten, der gerade die Kamera ist: standardmäßig perspektivisch mit einem vertikalen Sichtfeld von 60 Grad von 0.1 bis 1000 Einheiten oder orthografisch mit cameraSetOrthographic. Gerenderte Ansichten (viewNew) teilen die Projektion, blicken aber von ihren eigenen Knoten aus. Siehe 3D-Szenen.

2.5.1. cameraSet

cameraSet(node)
cameraSet(-1)

Macht einen Knoten zur Kamera: Die Szene wird von seiner Weltposition aus mit Blick entlang seiner eigenen -Z-Richtung gezeichnet, sodass Bewegung und Drehung seiner Eltern zählen. Jeder Knoten geht, auch einer, der zugleich ein Mesh oder ein Licht trägt, und die Kamera zu wechseln ist ein einziger Aufruf. -1 stellt die Standardansicht von (0, 0, 5) mit Blick auf den Ursprung wieder her. Wird der Kameraknoten gelöscht, fällt die Ansicht ebenfalls auf die Standardansicht zurück. Beendet das Skript bei einem ungültigen Knoten-Handle.

Beispiel
-- Eine Verfolgerkamera hinter dem Auto des Spielers und eine feste für die Wiederholung.
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)

Schaltet auf eine Parallelprojektion um, die height Welteinheiten von oben bis unten zeigt, wobei die Breite dem Seitenverhältnis der Ebene folgt, von near bis far vor der Kamera. Entfernung lässt Dinge nicht schrumpfen, was zu Diagrammen, isometrischen und seitlichen Ansichten und HUD-artigen Szenen passt. Die Einstellung gilt für den aktuellen und jeden späteren Kameraknoten, bis cameraSetPerspective aufgerufen wird. Der Schatten eines gerichteten Lichts benutzt unter einer orthografischen Kamera eine einzige Shadow Map, egal, was sceneSetShadowCascades sagt.

Parameter:

  • height — die sichtbare Höhe, in Welteinheiten.

  • near — die kleinste gezeichnete Entfernung, in Welteinheiten vor der Kamera.

  • far — die größte gezeichnete Entfernung.

Beispiel
-- Eine isometrische Ansicht des Spielbretts:  12 Einheiten hoch, von weit oben und seitlich.
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)

Schaltet auf die übliche perspektivische Projektion um, den Standard. fov ist das vertikale Sichtfeld in Grad (Standard 60); near und far (Standards 0.1 und 1000) begrenzen, was gezeichnet wird, in Welteinheiten vor der Kamera. Die Tiefengenauigkeit verteilt sich zwischen beiden, also halte near so groß, wie die Szene es erlaubt, und far nicht größer als nötig: 0.05 bis 100 für einen Raum, 0.1 bis 400 für eine Landschaft. Die Einstellung gilt für den aktuellen und jeden späteren Kameraknoten und für gerenderte Ansichten.

Parameter:

  • fov — vertikales Sichtfeld in Grad; ein weites 70 wirkt schnell, ein enges 40 wie ein Teleobjektiv.

  • near — die kleinste gezeichnete Entfernung.

  • far — die größte gezeichnete Entfernung.

Seit: 3.00. Siehe auch: cameraSetOrthographic, cameraSet, sceneProject

Beispiel
-- Ein engeres Objektiv für die Cockpitansicht, der Standard für draußen.
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. Kollision

Ob sich zwei flache Dinge berühren. Für Körper beantwortet Jolt das in drei Dimensionen (siehe Körper); diese Aufrufe beantworten es für das Overlay, wo die Hitboxen einer Lightgun und bei einem 2D-Spiel schlicht alles zu Hause sind.

Es sind schlichte Funktionen: keine Handles, kein Zustand, nichts zu erzeugen oder freizugeben und nichts, was in jedem Frame aktualisiert werden müsste. Die Koordinaten sind die, in denen du ohnehin zeichnest — meist Overlay-Pixel. Ein Rechteck ist eine Ecke und eine Größe, so wie jeder Zeichenaufruf der Engine eines entgegennimmt. Eine Berührung genau an einer Kante zählt als Berührung, und ein Rechteck ohne Breite oder Höhe berührt überhaupt nichts.

Keine davon bewegt etwas. Nimm require("bump") und lass es die Arbeit tun, wenn du nicht nur wissen willst, ob sich zwei Dinge getroffen haben, sondern wo das bewegte Objekt am Ende steht — an einer Wand entlanggleitend, statt tot in ihr stecken zu bleiben; genau dafür wird es mitgeliefert.

2.6.1. collideCircles

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

Ob sich zwei Kreise überschneiden. Billiger, als es aussieht: Für eine Ja-oder-Nein-Frage wird keine Quadratwurzel gezogen.

Parameter:

  • x1, y1, radius1 — Zahlen; der erste Kreis.

  • x2, y2, radius2 — Zahlen; der zweite.

Rückgabe: true oder false.

Seit: 3.00. Siehe auch: collideRectCircle

2.6.2. collidePointCircle

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

Ob ein Punkt innerhalb eines Kreises liegt. Der Rand zählt als innen.

Parameter:

  • pointX, pointY — Zahlen; der Punkt.

  • x, y, radius — Zahlen; der Kreis.

Rückgabe: true oder false.

Seit: 3.00.

2.6.3. collidePointPolygon

inside = collidePointPolygon(pointX, pointY, points)

Ob ein Punkt innerhalb eines Polygons beliebiger Form liegt, konkave eingeschlossen. Die Tabelle ist eine flache Liste aus x, y, x, y — die Form, die eine Hitbox in den meisten Spielen ohnehin hat — und der Umlaufsinn spielt keine Rolle. Weniger als drei Ecken enthalten nichts. Höchstens 256 Ecken.

Parameter:

  • pointX, pointY — Zahlen; der Punkt.

  • points — Tabelle; eine gerade Anzahl von Zahlen, abwechselnd x und y.

Rückgabe: true oder false.

Seit: 3.00.

Beispiel
-- Hat der Schuss den Drachen getroffen, dessen Umriss kein Rechteck ist?
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)

Ob ein Punkt innerhalb eines Rechtecks liegt. Der Rand zählt als innen.

Parameter:

  • pointX, pointY — Zahlen; der Punkt.

  • x, y, width, height — Zahlen; das Rechteck.

Rückgabe: true oder false.

Seit: 3.00.

Beispiel
-- Eine Hitbox in der Größe des Sprites, zu dem sie gehört.
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)

Ob sich ein Rechteck und ein Kreis überschneiden; dazu wird der Punkt des Rechtecks gesucht, der dem Mittelpunkt des Kreises am nächsten liegt.

Parameter:

  • x, y, width, height — Zahlen; das Rechteck.

  • circleX, circleY, radius — Zahlen; der Kreis.

Rückgabe: true oder false.

Seit: 3.00.

2.6.6. collideRects

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

Ob sich zwei Rechtecke überschneiden. Die Funktion, zu der du am häufigsten greifen wirst.

Parameter:

  • x1, y1, width1, height1 — Zahlen; das erste Rechteck.

  • x2, y2, width2, height2 — Zahlen; das zweite.

Rückgabe: true oder false.

Seit: 3.00. Siehe auch: collidePointRect

2.6.7. collideSegments

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

Ob sich zwei Strecken kreuzen: ein Schuss entlang einer Bahn gegen eine Wand oder der Schritt, den ein bewegtes Objekt machen will, gegen die Kante, die es nicht überschreiten darf. Strecken, die aufeinander liegen, ergeben false, weil „wo kreuzen sie sich“ dann keine eindeutige Antwort hat.

Parameter:

  • ax1, ay1, ax2, ay2 — Zahlen; die Enden der ersten Strecke.

  • bx1, by1, bx2, by2 — Zahlen; die der zweiten.

Rückgabe: true oder false.

Seit: 3.00.

2.7. Farbe

Die Vordergrund- und die Hintergrundfarbe sind globale Werte der Engine statt Argumente jedes Aufrufs: du setzt sie mit colorForeground und colorBackground, und jeder spätere Zeichenaufruf liest sie, bis sie sich ändern. Die Vordergrundfarbe verwenden die Formprimitive overlay* und TrueType-Text aus fontPrint und fontToSprite; die Hintergrundfarbe verwenden overlayClear und Text in FONT_QUALITY_SHADED. overlayPrint verwendet keine von beiden. Kanäle sind Ganzzahlen von 0 bis 255, auf diesen Bereich begrenzt, und beide Farben nehmen ein optionales Alpha an. Die Aufrufe, die sie verwenden, stehen in den Abschnitten Overlay und Schriftart.

2.7.1. colorBackground

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

Setzt die Hintergrundfarbe: womit overlayClear das Overlay füllt und was Text in FONT_QUALITY_SHADED aus fontPrint und fontToSprite hinter seine Glyphen malt. Beim Start ist sie transparentes Schwarz, und Alpha ist ohne Angabe 0, sodass colorBackground(0, 0, 0) gefolgt von overlayClear() das Overlay wieder unsichtbar macht. Ein teilweises Alpha über Schwarz dunkelt das Video ab; 255 verdeckt es. Kanalwerte außerhalb des Bereichs werden begrenzt statt abgewiesen.

Parameter:

  • r, g, b — Rot, Grün und Blau, 0 bis 255.

  • a — Deckkraft, 0 (transparent) bis 255 (deckend); Standard 0.

Seit: 1.x Siehe auch: colorForeground, overlayClear, fontQuality

Beispiel
-- Deckendes Schwarz hinter dem Kalibrierungsbildschirm, transparent während des Spiels.
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)

Setzt die Vordergrundfarbe, die overlayBox, overlayCircle, overlayEllipse, overlayLine und overlayPlot verwenden, und die Textfarbe für fontPrint und fontToSprite. Beim Start ist sie deckendes Weiß, und Alpha ist ohne Angabe 255, das Gegenteil von colorBackground. Sprites und overlayPrint werden mit ihren eigenen Pixeln gezeichnet und nicht eingefärbt. Kanalwerte außerhalb des Bereichs werden begrenzt statt abgewiesen.

Parameter:

  • r, g, b — Rot, Grün und Blau, 0 bis 255.

  • a — Deckkraft, 0 (transparent) bis 255 (deckend); Standard 255.

Beispiel
-- Punktestand in Weiß, Warnung beim letzten Leben in Rot, beides aus derselben Schriftart.
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. Befehlszeile

Drei Aufrufe melden Zahlen, die der Benutzer beim Start von Singe gewählt hat. Es gibt sie, damit sich ein Spiel vom Launcher aus abstimmen lässt, statt das Spiel bearbeiten zu müssen. Alle drei sind Erweiterungen von Hypseus Singe, und Singe selbst macht nichts mit den Werten: was sie bedeuten, entscheidet das Spiel. Die Optionen sind in Befehlszeilenoptionen beschrieben, und sie lassen sich auch in einer Einstellungsdatei setzen (siehe Die Einstellungsdatei).

Keiner der drei Werte ändert sich während eines Laufs, lies also jeden einmal und behalte ihn.

2.8.1. getFValue

value = getFValue()

Hypseus-Erweiterung. Gibt die als --fvalue angegebene Zahl zurück oder 0, wenn die Option nicht verwendet wurde. Sie ist ein Kanal für eine einzige Zahl von demjenigen, der Singe gestartet hat, zum Spiel, gedacht für einen Wert, den ein Frontend von Start zu Start ändern will — einen Schwierigkeitsgrad, eine Anzahl Start-Credits, einen Menüindex. Die Engine reicht ihn nur durch.

Der Wert reicht von 0 bis 100000 und behält drei Nachkommastellen, so viele, wie Hypseus behält, sodass ein Spiel, das die Zahl vergleicht, dieselbe sieht wie dort.

Rückgabe: Zahl.

Seit: 3.00 (Hypseus) Siehe auch: ratioGetX, ratioGetY

Beispiel
-- Der Launcher übergibt --fvalue 2 für den Automaten auf schwer.
local difficulty = getFValue()
if difficulty == 0 then
    difficulty = 1
end

2.8.2. ratioGetX

factor = ratioGetX()

Hypseus-Erweiterung. Gibt die als --xratio angegebene Zahl zurück oder 0, wenn die Option nicht verwendet wurde. Für Hypseus geschriebene Lightgun-Spiele lesen sie und strecken damit ihre eigenen Lightgun-Koordinaten, für einen Automaten, dessen Bildschirm nicht die Form hat, in der das Video gemastert wurde — 1.33 bildet ein 16:9-Panel auf 4:3-Material ab. Singe wendet sie auf nichts an; die Rechnung macht das Spiel, genau wie in Hypseus, und deshalb behandelt jedes Spiel, das sie liest, 0 und alles unter 1 als 1.

Der Wert reicht von 0 bis 100 und behält zwei Nachkommastellen, so wie Hypseus ihn behält.

Rückgabe: Zahl.

Seit: 3.00 (Hypseus) Siehe auch: ratioGetY, getFValue, mouseGetPosition

Beispiel
-- Die Form der Lightgun-Koordinaten, die dieser Automat will.
local ratioX = ratioGetX()
if ratioX <= 1 then
    ratioX = 1
end
local offsetX = (ratioX - 1) * (overlayGetWidth() / 2)

2.8.3. ratioGetY

factor = ratioGetY()

Hypseus-Erweiterung. Die senkrechte Hälfte des Paares: die als --yratio angegebene Zahl oder 0, wenn die Option nicht verwendet wurde. Siehe ratioGetX.

Rückgabe: Zahl.

Seit: 3.00 (Hypseus) Siehe auch: ratioGetX, getFValue

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

2.9. Controller

Singe unterstützt bis zu vier Gamecontroller mit den Indizes 0 bis 3, die beim Start und immer dann automatisch geöffnet werden, wenn einer eingesteckt oder entfernt wird; ein controllerLoad gibt es nicht. Analoge Achsen werden über onControllerMoved gemeldet (siehe Engine-Callbacks) und mit controllerGetAxis abgefragt, im Rohbereich von SDL von -32768 bis 32767. Digitale Tasten und jede Richtung jeder Achse sind Schalter wie die Tasten der Tastatur: sie erreichen onInputPressed und onInputReleased, wenn eine Belegung in controls.cfg einen Code aus den Tabellen GAMEPAD_0 bis GAMEPAD_3 verwendet (zum Beispiel INPUT_ACTION_1 = { GAMEPAD_0.BUTTON_A }), und controllerGetButton fragt den aktuellen Zustand einer Taste ab. SINGE_DEAD_ZONE aus dem Eintrag DEAD_ZONE in controls.cfg ist die Schwelle, die die Engine selbst verwendet, bevor eine Achsenrichtung als gedrückter Schalter zählt; behandle Achsenbewegungen darunter als Rauschen. Einzelnen Achsen kann mit DEAD_ZONES jeweils eine andere Schwelle gegeben werden und den analogen Triggern mit TRIGGER_THRESHOLD eine eigene (zurückgelesen als SINGE_TRIGGER_THRESHOLD); siehe Totzonen und Trigger. Ein Gerät, das SDL nicht als Gamepad erkennt, wird trotzdem als eines geöffnet, über ein Mapping, das Singe dafür schreibt, sodass ein Arcade-Encoder oder ein Flightstick in diesen Slots wie jedes Pad erscheint — siehe Jedes Gerät ist ein Gamepad.

2.9.1. controllerDoRumble

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

Hypseus-Erweiterung. Lässt einen Controller mit beiden Motoren in einer von vier Stärken für eine von vier Dauern vibrieren. Die Form mit zwei Argumenten spricht Controller 0 an. Ein Slot ohne Controller tut nichts (Hypseus bricht dort ab, deshalb sichern sich seine Spiele mit controllerIsValid ab); eine Stärke oder Dauer außerhalb von 1 bis 4 oder ein Index außerhalb von 0 bis 3 bricht das Skript ab. Ein Controller ohne Vibrationsunterstützung ignoriert den Aufruf.

Parameter:

  • controller — Controller-Index, 0 bis 3.

  • strength — 1 bis 4, von einem Viertel bis zur vollen Stärke.

  • duration — 1 bis 4, ergibt 150, 300, 600 oder 1200 ms.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: controllerIsValid, controllerGetButton

Beispiel
-- Ein kurzer Stoß bei jedem Treffer, ein langer mit voller Stärke, wenn der Spieler stirbt.
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)

Gibt die Stellung einer analogen Achse zurück, wie die Engine sie zuletzt gesehen hat. Der Wert wird bei jedem Achsenereignis aktualisiert, auch bei Bewegung innerhalb der Totzone, und ist 0 für einen Controller, der nicht verbunden ist, oder eine Achse, die sich nie bewegt hat. Sticks reichen von -32768 bis 32767; Trigger ruhen bei 0 und erreichen voll gedrückt 32767. Ein Index außerhalb von 0 bis 3 oder eine Achse außerhalb von 0 bis 5 bricht das Skript ab.

Parameter:

  • controller — Controller-Index, 0 bis 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) oder GAMEPAD_AXIS_RIGHT_TRIGGER (5).

Rückgabe: Ganzzahl, -32768 bis 32767.

Seit: 2.00 Siehe auch: controllerGetButton, onControllerMoved

Beispiel
-- Lenken mit dem linken Stick, Gas geben mit dem rechten Trigger.
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)

Gibt zurück, ob eine Taste gerade gehalten wird, direkt vom Controller gelesen statt aus der Ereigniswarteschlange. Verwende es zum Aufladen durch Gedrückthalten und für ähnliche Fälle, in denen onInputPressed und onInputReleased umständlich sind. Ein Slot ohne Controller ergibt false. Der Tastencode muss aus der Tabelle GAMEPAD_N desselben Controller-Index stammen; ein Code aus der Tabelle eines anderen Controllers oder ein Achsencode fällt aus dem Tastenbereich und bricht das Skript ab, ebenso ein Index außerhalb von 0 bis 3.

Parameter:

  • controller — Controller-Index, 0 bis 3.

  • button — ein Wert BUTTON_* oder DPAD_* aus der passenden Tabelle, etwa GAMEPAD_0.BUTTON_A.value.

Rückgabe: Boolean.

Beispiel
-- Aufladen, solange A gehalten wird, feuern beim Loslassen.
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)

Der Name des Geräts in einem Controller-Slot, wie SDL ihn meldet, oder nil, wenn der Slot leer ist. Ein Gerät, das SDL nicht erkannt hat, meldet seinen eigenen Namen über das Mapping, das Singe dafür geschrieben hat, sodass ein Service-Bildschirm einen Arcade-Encoder ebenso leicht mit Namen auflisten kann wie ein Markenpad. Ein Index außerhalb von 0 bis 3 bricht das Skript ab.

Parameter:

  • controller — Controller-Index, 0 bis 3.

Rückgabe: String oder nil.

Seit: 3.00 Siehe auch: controllerIsValid, mouseGetName

Beispiel
-- Ein Service-Bildschirm, der auflistet, was eingesteckt ist.
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()

Hypseus-Erweiterung, in Singe immer 0. Hypseus addiert diesen Offset zu einem Schaltercode, der von einem Gamepad kam, damit ein Spiel erkennen kann, welches Gerät was gedrückt hat, und den Schalter trotzdem durch Abziehen zurückgewinnt. Singe liefert Gamepad-Eingaben als gewöhnliche belegte Schalter ohne eine solche Markierung, deshalb antwortet es mit 0: ein Spiel, das auf den verschobenen Bereich prüft, nimmt seinen anderen Zweig und liest den Schalter so, wie er ist.

Rückgabe: eine Ganzzahl, immer 0.

Seit: 3.00 Siehe auch: controllerSetPadding

2.9.6. controllerHowMany

count = controllerHowMany()

Hypseus-Erweiterung. Wie viele Gamepads geöffnet sind, von den vier Slots, die Singe hat. Da jeder Joystick, den Singe öffnen kann, zum Gamepad wird (siehe Jedes Gerät ist ein Gamepad), werden hier auch ein Arcade-Encoder oder ein Spinner mitgezählt.

Die Anzahl ändert sich, wenn Geräte ein- und ausgesteckt werden, lies sie also, wenn du sie brauchst, statt einmal beim Start. Sie sagt nichts darüber, welche Slots besetzt sind: ein Gerät kann Slot 0 leer lassen, während Slot 1 in Gebrauch ist, deshalb ist controllerIsValid weiterhin der Weg, nach einem bestimmten Slot zu fragen.

Parameter: keine.

Rückgabe: Zahl, 0 bis 4.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: controllerIsValid, controllerGetName, mouseHowMany

Beispiel
-- Zwei Spieler nur anbieten, wenn Spieler zwei etwas zum Festhalten hat.
local twoPlayer = controllerHowMany() >= 2

2.9.7. controllerIsValid

valid = controllerIsValid(controller)

Hypseus-Erweiterung. Gibt zurück, ob gerade ein Controller im Slot geöffnet ist; Controller kommen und gehen beim Ein- und Ausstecken im laufenden Betrieb, frag also vor jedem controllerDoRumble. Ein Index außerhalb von 0 bis 3 bricht das Skript ab.

Parameter:

  • controller — Controller-Index, 0 bis 3.

Rückgabe: Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: controllerDoRumble, controllerGetAxis

Beispiel
-- Die Pad-Hinweise nur zeigen, wenn es ein Pad gibt, auf das sie hinweisen können.
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)

Hypseus-Erweiterung, angenommen und ignoriert. Warum es den Offset, den sie verlangt, in Singe nicht gibt, steht bei controllerGetPadding. Ihn einzuschalten, ohne die Ereignisse zu markieren, wäre schlimmer, als ihn ausgeschaltet zu lassen, weil das Spiel dann einen Offset von Schaltercodes abziehen würde, die nie einen trugen.

Rückgabe: nichts.

Seit: 3.00 Siehe auch: controllerGetPadding

2.10. Debugging

Zwei Aufrufe, um zu sehen, was ein Skript tut: debugPrint schreibt Text, und lineDraw zeichnet für einen Frame eine Linie über die 3D-Szene (physicsSetDebug und navDraw zeichnen über dieselben Linien). Ausgegebenes geht an die Konsole, von der aus Singe gestartet wurde, ist also während der Entwicklung sichtbar und in einem Automaten harmlos, wo --noconsole es stummschaltet. Läuft Singe mit --trace, wird außerdem jeder API-Aufruf, auch dieser, mit seinen Argumenten in trace.txt im Datenordner geschrieben; so bekommst du eine dauerhafte Aufzeichnung. Die Befehlszeilenoptionen stehen im Kapitel über das Starten von Singe. Reicht Ausgeben nicht, hält ZeroBrane Studio das Spiel an einem Haltepunkt an, zeigt, was in seinen Variablen steht, und geht es Zeile für Zeile durch.

2.10.1. Der Trace-Kopf

Ganz gleich, ob --program oder --trace sie geöffnet hat: trace.txt beginnt mit einem Block, der den Rechner und den Lauf beschreibt, zwischen zwei Linien, sodass er sich als Ganzes in einen Fehlerbericht einfügen lässt:

----------------------------------------------------------------
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 ist der Renderer, der tatsächlich erzeugt wurde, und das GPU-Backend, das er gewählt hat, oder ein Hinweis, dass es kein GPU-Gerät gibt und 3D nicht verfügbar ist. Decoder ist das, was auf diesem Rechner für Video versucht wird; welchen Decoder ein bestimmtes Video tatsächlich bekommen hat, hält der Trace beim Öffnen dieses Videos ein paar Zeilen weiter unten fest, da ein Codec womöglich keinen Hardwareweg anbietet. Settings listet auf, was die Einstellungsdatei geliefert hat, none, wenn es keine gab. Jedes Spiel in einer Warteschlange bekommt seine eigene Datei und seinen eigenen Kopf.

2.10.2. debugPrint

debugPrint(message)

Gibt eine Zeile auf der Konsole (Standardausgabe) aus. Wurde Singe mit --noconsole gestartet, wird nichts ausgegeben; mit --trace landen der Aufruf und seine Nachricht außerdem in trace.txt. Das Argument muss ein String oder eine Zahl sein; alles andere bricht das Skript ab, verpacke Werte also in tostring oder verwende string.format. Der Aufruf ist billig genug, um im ausgelieferten Code zu bleiben, wird aber nicht gedrosselt, eine Ausgabe in onOverlayUpdate läuft also in jedem Frame.

Parameter:

  • message — der auszugebende Text; eine Zahl wird umgewandelt.

Seit: 1.x Siehe auch: singeGetTicks

Beispiel
-- Protokollieren, warum der Schuss danebenging, mit dem Frame, in dem es passiert ist.
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)

Zeichnet eine gerade Linie zwischen zwei Punkten in Weltkoordinaten über die Szene, nur für den aktuellen Frame, weiß, sofern keine Farbe angegeben ist. Ruf es in jedem Frame auf, um eine Linie auf dem Bildschirm zu halten, wie beim Overlay. Die Linie wird gegen die Tiefe der Szene getestet, schreibt aber keine Tiefe, versteckt sich also wie alles andere hinter Wänden und verdeckt selbst nie etwas. Solange die Szene deaktiviert ist, wird nichts gezeichnet. Sie ist dafür gedacht, zu sehen, was ein Skript tut (einen Raycast, einen Pfad, eine Bounding Box); physicsSetDebug und navDraw zeichnen über dieselben Linien.

Parameter:

  • x0, y0, z0 — der Startpunkt, in Welteinheiten.

  • x1, y1, z1 — der Endpunkt, in Welteinheiten.

  • r, g, b — die Linienfarbe, 0 bis 255 je Kanal, begrenzt; weiß, wenn weggelassen.

Seit: 3.00. Siehe auch: physicsSetDebug, navDraw, physicsRaycast

Beispiel
-- Zeigen, wohin der Geschützturm zielt und ob der Schuss treffen würde.
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. Disc

Die Disc ist das Haupt-Laserdisc-Video, das, für dessen Emulation Singe ursprünglich gebaut wurde. Ein Spiel hat höchstens eine Disc, die beim Start aus dem in games.dat genannten VIDEO oder aus --disc / --framefile auf der Befehlszeile geöffnet wird; ein Spiel, das keine nennt, läuft ohne Disc (siehe Spiele ohne Disc). Alle disc*-Funktionen arbeiten mit dieser einen impliziten Disc und nehmen kein Handle. Frame-Nummern sind nullbasierte Positionen in der Videodatei (oder in der zusammengesetzten Frame-Datei) und der Zeitbezug für jede Verzweigungsentscheidung in einem Laserdisc-Spiel. Ohne Disc geben die Abfragefunktionen 0 zurück, discGetState meldet DISC_EJECTED, und die Transportfunktionen schreiben eine Trace-Zeile und tun nichts. Zusätzliche Clips über der Disc sind Aufgabe der Familie Video.

2.11.1. discAudio

discAudio(channel, enabled)

Schaltet einen Kanal der Tonspur der Disc ein oder aus. Der Kanal wird auf die eingestellte Laserdisc-Lautstärke (--volume_vldp, Standard 100) gesetzt, wenn enabled true ist, und auf 0, wenn es false ist; der andere Kanal bleibt, wie er ist. Viele Originaltitel hatten Erzählung oder eine Datenspur nur auf einem Kanal, und mit diesem Aufruf bringst du sie zum Schweigen. Ein anderer Kanal als 1 oder 2 beendet das Skript. Ohne Disc tut der Aufruf nichts.

Parameter:

  • channel — 1 für den linken Kanal, 2 für den rechten.

  • enabled — Boolean. true setzt den Kanal wieder auf die eingestellte Laserdisc-Lautstärke, false schaltet ihn stumm.

Beispiel
-- Der rechte Kanal dieser Disc trägt die Datenspur des Arcade-Automaten.
function startGame()
    discAudio(1, true)
    discAudio(2, false)
    discSkipToFrame(SCENE_FIRST_FRAME)
end

2.11.2. discAudioSuffix

opened = discAudioSuffix(suffix)

Hypseus-Erweiterung. Schaltet die Disc auf eine eigene Audiodatei neben ihrem Video um: <base><suffix>.ogg, wobei die Basis der Name der Videodatei ohne Endung ist, sodass movie.m2v mit "-es" die Datei movie-es.ogg abspielt. Die Datei wird beim aktuellen Frame geöffnet, und die Wiedergabe richtet sich neu aus, wie bei discSetAudioTrack; Lautstärke, Wiedergabezustand und Spurindex bleiben erhalten, sofern die neue Datei so viele Spuren hat. Mit einer Frame-Datei schaltet jedes Segment um. Ein leeres Suffix stellt das Standardaudio wieder her: die .ogg neben einer .m2v oder den Ton in jedem anderen Container. Gibt true zurück, wenn die Datei geöffnet wurde; fehlt sie, läuft das bisherige Audio weiter, nichts wird gemerkt, und false kommt zurück (Hypseus hinterlässt in diesem Fall Stille). Das Suffix wird vergessen, wenn das Skript neu geladen wird. Ohne Disc gibt der Aufruf false zurück. Verwende ihn für ein Sprachmenü, dessen Spuren als eigene Dateien mitgeliefert werden; Spuren innerhalb einer Datei sind Aufgabe von discSetAudioTrack.

Parameter:

  • suffix — String, der an den Basisnamen des Videos angehängt wird, etwa "-es"; "" für das Standardaudio.

Rückgabe: Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: discSetAudioTrack, discGetAudioTracks, discAudio

Beispiel
-- Sprachdateien werden als movie.ogg, movie-es.ogg und movie-fr.ogg mitgeliefert.
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(...)

Tut nichts. Echte Laserdisc-Player konnten mit einer anderen Geschwindigkeit als 1x laufen; der Software-Player von Singe kann das nicht, deshalb nimmt der Aufruf beliebige Argumente an, schreibt eine Trace-Zeile und kehrt zurück. Er bleibt erhalten, damit Skripte von vor 2.00 ohne Änderungen laden.

Hinweise:

Nicht implementiert. Nur aus Gründen der Abwärtskompatibilität erhalten. Es gibt keinen Ersatz; die Wiedergabegeschwindigkeit ist auf die Bildrate der Videodatei festgelegt.

Seit: 1.x Siehe auch: discPlay, discSkipToFrame

Beispiel
-- Alte Skripte umrahmten eine Zeitlupen-Wiederholung manchmal mit Geschwindigkeitswechseln.
-- Die Aufrufe sind heute harmlos, aber die Wiederholung läuft mit normaler Geschwindigkeit.
discChangeSpeed(0.5)
discSkipToFrame(REPLAY_FIRST_FRAME)
discChangeSpeed(1)

2.11.4. discGetAudioTrack

track = discGetAudioTrack()

Gibt den nullbasierten Index der Tonspur zurück, die die Disc gerade abspielt. Beim Start wählt die Engine die durch --audio oder den Eintrag AUDIO_TRACK in games.dat genannte Spur (Standard 0), sofern die Disc so viele Spuren hat. Gibt ohne Disc 0 zurück.

Rückgabe: ganzzahliger Spurindex.

Beispiel
-- Bei jedem Druck auf die Sprachtaste zur nächsten Synchronfassung wechseln.
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()

Gibt zurück, wie viele Audiostreams die Videodatei der Disc enthält. Mehrere Streams sind typischerweise alternative Synchronfassungen. Ein stummes Video meldet 0, ebenso ein Spiel ohne Disc, sichere Schleifen und Modulo-Rechnungen also gegen null ab.

Rückgabe: ganzzahlige Anzahl, 0 oder mehr.

Beispiel
-- Aus den Tonspuren der Disc ein Sprachauswahlmenü bauen.
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)

Die Sprache, mit der eine Untertitelspur im eigenen Container der Disc gekennzeichnet ist, als der ISO-639-Code, den die Datei trägt (eng, fra, spa). Eine Spur, die die Datei mit nichts kennzeichnet, ergibt einen leeren String, und das ist kein Fehler — viele Dateien kennzeichnen gar nichts.

Parameter:

  • track — Zahl; 0 bis discGetSubtitleTracks() - 1.

Rückgabe: ein String.

Seit: 3.00. Siehe auch: discGetSubtitleTracks, srtLoadTrack

2.11.7. discGetSubtitleTracks

count = discGetSubtitleTracks()

Wie viele Untertitelspuren der eigene Container der Disc enthält. 0 ohne Disc und 0 für eine Disc, deren Untertitel als eigene .srt mitgeliefert werden — was die übliche Anordnung ist und wofür srtLoad da ist.

Spuren, die Bilder statt Wörter enthalten (die Arten von DVD und Blu-ray, VobSub und PGS), werden hier mitgezählt, damit die Nummerierung mit dem übereinstimmt, was jeder andere Player zeigt, aber srtLoadTrack kann sie nicht lesen: da gibt es nichts zu lesen, nur Bitmaps der Wörter.

Parameter:

  • Keine.

Rückgabe: eine Zahl.

Seit: 3.00. Siehe auch: srtLoadTrack, discGetSubtitleLanguage

Beispiel
-- Die Sprachen anbieten, die die Disc selbst mitbringt.
for track = 0, discGetSubtitleTracks() - 1 do
    languages[#languages + 1] = { track = track, code = discGetSubtitleLanguage(track) }
end

2.11.8. discGetFrame

frame = discGetFrame()

Gibt den Frame zurück, den die Disc gerade zeigt. Mit einer Frame-Datei ist die Nummer die Position in der zusammengesetzten Folge, Segmentgrenzen sind für das Skript also unsichtbar. Gibt 0 zurück, solange die Disc gestoppt ist, und ohne Disc. Frag ihn in onOverlayUpdate ab, um darauf zu reagieren, dass das Video einen Entscheidungspunkt erreicht.

Rückgabe: ganzzahlige Frame-Nummer.

Seit: 1.x Siehe auch: discSearch, discSkipToFrame, discGetState

Beispiel
-- Die Attract-Sequenz in einer Schleife abspielen und im Zeitfenster zum Ducken eine Aufforderung zeigen.
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()

Die Anzahl der Frames auf der Disc, also eins mehr als der höchste Frame, den discSearch findet. Eine Frame-Datei antwortet für die ganze Disc statt für das laufende Segment, die Anzahl ändert sich also nicht, wenn Segmente kommen und gehen. Ohne Disc antwortet sie mit 0.

Rückgabe: ganzzahlige Anzahl der Frames, 0 ohne Disc.

Seit: 3.00. Siehe auch: discGetFrame, discSearch

Beispiel
-- Zur Mitte der Disc springen, wo auch immer die liegt.
discSearch(math.floor(discGetFrameCount() / 2))

2.11.10. discGetHeight

height = discGetHeight()

Gibt die Höhe des Disc-Videos in Pixeln zurück. Ohne Disc gibt es die Höhe der Zeichenfläche zurück (CANVAS_Y in games.dat oder --canvas, Standard 480), es ist also immer die Größe des Hintergrunds, über den das Overlay gestreckt wird. Kombiniere es mit discGetWidth, um dem Overlay dieselbe Auflösung wie dem Video zu geben.

Rückgabe: ganzzahlige Höhe in Pixeln.

Beispiel
-- In der nativen Auflösung der Disc zeichnen, damit Pixelprüfungen und Zeichnen ein Raster teilen.
overlaySetResolution(discGetWidth(), discGetHeight())
crosshairLimitX = discGetWidth() - 1
crosshairLimitY = discGetHeight() - 1

2.11.11. discGetLanguage

code = discGetLanguage(track)

Gibt das in der Videodatei gespeicherte Sprach-Tag für eine der Tonspuren der Disc zurück. Das Tag ist ein dreibuchstabiger ISO-639-Code wie "eng" oder "jpn". Spuren ohne dreibuchstabiges Tag ergeben "unk", ebenso jede Spur, wenn es keine Disc gibt. Mit Disc beendet eine Spur außerhalb von 0 bis discGetAudioTracks() - 1 das Skript.

Rückgabe: String mit dem Sprachcode.

Beispiel
-- Die japanische Synchronfassung bevorzugen, wenn die Disc eine hat.
for track = 0, discGetAudioTracks() - 1 do
    if discGetLanguage(track) == "jpn" then
        discSetAudioTrack(track)
        break
    end
end

2.11.12. discGetState

state = discGetState()

Gibt den Transportzustand der Disc als eine der Konstanten DISC_* zurück. Ein Spiel ohne Disc meldet DISC_EJECTED; nach discStop meldet die Disc DISC_STOPPED bis zum nächsten discPlay, discSearch oder discSkipToFrame; ansonsten ist der Zustand DISC_PLAYING, solange das Video vorrückt, und DISC_PAUSED, wenn nicht. Einen eigenen Suchzustand gibt es nicht; eine Disc, die gerade springt, meldet DISC_PAUSED oder DISC_PLAYING, je nachdem, was angefordert wurde.

Rückgabe: eine der folgenden Konstanten, die die Engine definiert und die jedem Skript zur Verfügung stehen.

Konstante Wert Bedeutung

DISC_STOPPED

2

Gestoppt (discStop wurde aufgerufen)

DISC_PLAYING

3

Läuft

DISC_PAUSED

4

Pausiert

DISC_EJECTED

5

Das Spiel hat keine Disc (siehe Spiele ohne Disc)

Seit: 1.x (RDG) Siehe auch: discPlay, discPause, discStop

Beispiel
-- Die Pausentaste darf kein Anhalten fortsetzen, das das Story-Skript verlangt hat.
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()

Gibt die Breite des Disc-Videos in Pixeln zurück. Ohne Disc gibt es die Breite der Zeichenfläche zurück (CANVAS_X in games.dat oder --canvas, Standard 720). Zusammen mit discGetHeight ist das die Größe, auf die das Overlay skaliert wird, weshalb das mitgelieferte Menü beide an overlaySetResolution übergibt.

Rückgabe: ganzzahlige Breite in Pixeln.

Beispiel
-- Ein Titel-Sprite zentrieren, egal wie breit die Disc gerade ist.
overlaySetResolution(discGetWidth(), discGetHeight())
titleSprite = spriteLoad("graphics/title.png")
titleX = (discGetWidth() - spriteGetWidth(titleSprite)) / 2

2.11.14. discPause

discPause()

Hält die Wiedergabe beim aktuellen Frame an, der auf dem Bildschirm bleibt. Der Ton der Disc pausiert mit. Der Aufruf wird ignoriert, solange die Disc gestoppt ist, und tut ohne Disc nichts. Fortsetzen mit discPlay.

Seit: 1.x Siehe auch: discPlay, discStop, singeSetPauseFlag

Beispiel
-- Den letzten Frame der Szene halten, während der Spieler eine Tür wählt.
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)

Springt zu frame, zeigt ihn und pausiert. Das ist dieselbe Bindung wie discSearch unter einem zweiten Namen; die beiden sind in jeder Hinsicht austauschbar, einschließlich der dort beschriebenen Regeln für die Begrenzung. Bevorzuge discSearch in neuem Code und behalte discPauseAtFrame nur beim Portieren alter Skripte.

Hinweise:

Veralteter Alias. Verwende discSearch in neuem Code.

Seit: 1.18 Siehe auch: discSearch, discPlay

Beispiel
-- Portierter 1.x-Code:  auf dem ersten Frame der Szene parken, bis der Spieler bereit ist.
function onInputPressed(what)
    if what == SWITCH_START1 then
        discPauseAtFrame(SCENE_FIRST_FRAME)
        waitingForPlayer = true
    end
end

2.11.16. discPlay

discPlay()

Startet die Wiedergabe beim aktuellen Frame oder setzt sie fort und hebt den von discStop gesetzten Stoppzustand auf. Der Ton läuft mit dem Video weiter, und die Wiedergabeuhr startet beim aktuellen Frame neu, damit eine lange Pause keinen Sprung verursacht. Tut ohne Disc nichts, außer das Stopp-Flag zu löschen.

Seit: 1.x Siehe auch: discPause, discStop, discSkipToFrame

Beispiel
-- Üblicher Start des Attract-Modus:  den ersten Frame anfahren, dann losrollen.
function attractBegin()
    discSearch(ATTRACT_FIRST_FRAME)
    overlayClear()
    discPlay()
    attractRunning = true
end

2.11.17. discSearch

discSearch(frame)

Springt mit der Disc zu frame, zeigt diesen Frame und pausiert darauf; war die Disc gestoppt, wird der Stoppzustand aufgehoben. Die Disc hält den Frame bis zu discPlay, discSkipToFrame oder einem anderen Transportaufruf. Ein negativer Frame wird auf den ersten Frame begrenzt und einer hinter dem Ende auf den letzten; mit einer Frame-Datei wird das Segment gewählt, das den Frame enthält, und die Position innerhalb davon begrenzt. Tut ohne Disc nichts.

Parameter:

  • frame — Ziel-Frame-Nummer, nullbasiert.

Seit: 1.x Siehe auch: discSkipToFrame, discPlay, discGetFrame

Beispiel
-- Der Spieler hat den linken Gang gewählt:  die Szene anfahren und auf das Startsignal warten.
function goLeft()
    discSearch(CORRIDOR_LEFT_FIRST_FRAME)
    soundPlay(SOUND_DOOR)
    waitingForPlayer = true
end

2.11.18. discSearchBlanking

discSearchBlanking(...)

Tut nichts. Auf Laserdisc-Hardware wählte das, ob der Bildschirm dunkel wurde, während der Player einen Frame suchte; der Software-Player von Singe springt, ohne dunkel zu werden, deshalb nimmt der Aufruf beliebige Argumente an, schreibt eine Trace-Zeile und kehrt zurück.

Hinweise:

Nicht implementiert. Nur aus Gründen der Abwärtskompatibilität erhalten. Es gibt keinen Ersatz.

Seit: 1.x Siehe auch: discSearch, discSkipBlanking

Beispiel
-- Skripte von vor 2.00 setzten die Austastmodi oft einmal beim Start.  Harmlos.
discSearchBlanking(false)
discSkipBlanking(false)
discSearch(TITLE_FRAME)

2.11.19. discSetAudioTrack

discSetAudioTrack(track)

Schaltet die Disc auf eine andere Tonspur um. Bereits eingereihtes Audio der alten Spur wird verworfen, und die Wiedergabe richtet sich neu aus, die Änderung ist also fast sofort zu hören. Mit Disc beendet eine Spur außerhalb von 0 bis discGetAudioTracks() - 1 das Skript; ohne Disc tut der Aufruf nichts. Verwende ihn, um ein Sprachmenü umzusetzen oder eine zwischen Sitzungen gespeicherte Vorliebe zu beachten.

Parameter:

  • track — nullbasierter Index der Tonspur.

Beispiel
-- Die Sprache anwenden, die der Spieler im Optionsbildschirm gewählt hat.
function applyLanguage(choice)
    if choice >= 0 and choice < discGetAudioTracks() then
        discSetAudioTrack(choice)
        settings.language = choice
        saveSettings()
    end
end

2.11.20. discSetFPS

discSetFPS(...)

Tut nichts. Die Bildrate stammt aus der Videodatei, deshalb nimmt der Aufruf beliebige Argumente an, schreibt eine Trace-Zeile und kehrt zurück. Nichts im mitgelieferten Framework.singe ruft ihn auf; das tun nur Skripte von vor 2.00.

Hinweise:

Nicht implementiert. Nur aus Gründen der Abwärtskompatibilität erhalten. Die Bildrate wird aus der Videodatei gelesen und kann nicht aus einem Skript gesetzt werden.

Seit: 1.x Siehe auch: discGetFrame, discSkipToFrame

Beispiel
-- Ein portiertes 1.x-Skript.  Der Aufruf wird ignoriert; Bilder pro Sekunde sind eine Eigenschaft der Datei.
discSetFPS(29.97)
discSearch(TITLE_FRAME)
discPlay()

2.11.21. discSkipBackward

discSkipBackward(frames)

Springt um frames vom aktuellen Frame zurück, ohne den Wiedergabe- oder Pausenzustand zu ändern: eine laufende Disc spielt von der neuen Position aus weiter, eine pausierte bleibt dort pausiert. Der Aufruf wird ignoriert, solange die Disc gestoppt ist, und ohne Disc. Die Differenz wird nicht geprüft; ein negativer Wert springt vorwärts, und eine Differenz, die größer als der aktuelle Frame ist, wird bei Frame 0 begrenzt. Mit einer Frame-Datei gilt die Differenz für die Frame-Nummer, die discGetFrame meldet, ein Sprung kann also in ein früheres Segment hinüberreichen.

Parameter:

  • frames — Anzahl der Frames, die vom aktuellen Frame abgezogen werden.

Beispiel
-- Die letzte Sekunde (30 Frames) wiederholen, wenn der Spieler eine Aufforderung verpasst.
function missedPrompt()
    lives = lives - 1
    discSkipBackward(30)
    promptShown = false
end

2.11.22. discSkipBlanking

discSkipBlanking(...)

Tut nichts. Früher wählte es auf Laserdisc-Hardware, ob der Bildschirm bei einem Sprung dunkel wurde; der Software-Player von Singe wird nie dunkel, deshalb nimmt der Aufruf beliebige Argumente an, schreibt eine Trace-Zeile und kehrt zurück.

Hinweise:

Nicht implementiert. Nur aus Gründen der Abwärtskompatibilität erhalten. Es gibt keinen Ersatz.

Seit: 1.x Siehe auch: discSearchBlanking, discSkipToFrame

Beispiel
-- Skripte von vor 2.00 setzten die Austastmodi oft einmal beim Start.  Harmlos.
discSearchBlanking(false)
discSkipBlanking(false)
discSearch(TITLE_FRAME)

2.11.23. discSkipForward

discSkipForward(frames)

Springt um frames vom aktuellen Frame vorwärts, ohne den Wiedergabe- oder Pausenzustand zu ändern. Das Spiegelbild von discSkipBackward: ignoriert, solange gestoppt, und ohne Disc, die Differenz wird nicht geprüft, und ein Ziel hinter dem letzten Frame wird beim letzten Frame begrenzt. Mit einer Frame-Datei gilt die Differenz für die Frame-Nummer, die discGetFrame meldet, ein Sprung kann also in ein späteres Segment hinüberreichen.

Parameter:

  • frames — Anzahl der Frames, die zum aktuellen Frame addiert werden.

Beispiel
-- Einen wiederkehrenden Spieler das zweisekündige Intro der Szene überspringen lassen.
function onInputPressed(what)
    if what == SWITCH_BUTTON1 and inSceneIntro then
        discSkipForward(60)
        inSceneIntro = false
    end
end

2.11.24. discSkipToFrame

discSkipToFrame(frame)

Springt zu frame und spielt von dort ab, egal in welchem Zustand die Disc ist; wenn nötig, wird der Stoppzustand aufgehoben. Im Gegensatz dazu springt discSearch und pausiert. Ein Frame vor dem Anfang oder hinter dem Ende wird auf den ersten oder letzten Frame begrenzt; mit einer Frame-Datei wird das Segment gewählt, das den Frame enthält, und die Position innerhalb davon begrenzt. Tut ohne Disc nichts, außer das Stopp-Flag zu löschen.

Parameter:

  • frame — Ziel-Frame-Nummer, nullbasiert.

Seit: 1.x Siehe auch: discSearch, discPlay, discGetFrame

Beispiel
-- Beim erneuten Spielen das Intro überspringen.
function startGame()
    if hasPlayedBefore then
        discSkipToFrame(GAMEPLAY_FIRST_FRAME)
    else
        discSkipToFrame(INTRO_FIRST_FRAME)
    end
end

2.11.25. discStepBackward

discStepBackward()

Bewegt die Disc genau einen Frame zurück und pausiert darauf, egal in welchem Wiedergabezustand sie vorher war. Ein Schritt bei Frame 0 bleibt auf Frame 0. Wird wie discSkipBackward ignoriert, solange die Disc gestoppt ist. Gedacht für framegenaues Debugging und Service-Bildschirme. Tut ohne Disc nichts.

Beispiel
-- Service-Bildschirm:  links und rechts schieben die Disc jeweils um einen Frame.
function onInputPressed(what)
    if what == SWITCH_LEFT then
        discStepBackward()
    elseif what == SWITCH_RIGHT then
        discStepForward()
    end
end

2.11.26. discStepForward

discStepForward()

Bewegt die Disc genau einen Frame vorwärts und pausiert darauf, egal in welchem Wiedergabezustand sie vorher war. Ein Schritt auf dem letzten Frame bleibt auf dem letzten Frame. Wie discStepBackward wird der Aufruf ignoriert, solange die Disc gestoppt ist. Tut ohne Disc nichts.

Beispiel
-- Frame-Finder:  Schritt für Schritt durch eine Szene gehen und die Frame-Nummer ausgeben.
function onOverlayUpdate()
    overlayClear()
    overlayPrint(8, 8, "Frame " .. discGetFrame())
    if stepping then
        discStepForward()
    end
    return OVERLAY_UPDATED
end

2.11.27. discStop

discStop()

Stoppt die Disc. Die Wiedergabe hält an, das Video wird durch den klassischen blauen Bildschirm ersetzt, discGetState meldet DISC_STOPPED, und discGetFrame gibt 0 zurück, bis die Disc wieder gestartet wird. Während sie gestoppt ist, werden discPause, discSkipForward, discSkipBackward, discStepForward und discStepBackward ignoriert. Jeder der Aufrufe discPlay, discSearch oder discSkipToFrame hebt den Stoppzustand auf. Ein zweites discStop wird ignoriert.

Seit: 1.x Siehe auch: discPlay, discPause, discGetState

Beispiel
-- Game Over:  auf den blauen Bildschirm hinter der Punktetabelle zurückfallen.
function gameOver()
    discStop()
    soundPlay(SOUND_GAME_OVER)
    showScores = true
end

2.12. Emitter

Emitter erzeugen, bewegen und zeichnen Partikel; siehe Partikel. Handles sind Ganzzahlen. Ein 2D-Emitter lebt in Overlay-Koordinaten, Y nach unten, und zeichnet, wenn emitterDraw es aus onOverlayUpdate verlangt; ein 3D-Emitter sitzt an einem Knoten, lebt in Welteinheiten und zeichnet sich selbst in der Szene. Die Rezeptaufrufe lassen sich in beliebiger Reihenfolge machen, vor oder nach dem Start des Emitters, und wirken auf die nächsten geborenen Partikel (einige wenige, unten vermerkt, auch auf die lebenden). Alles, was als Minimum und Maximum angegeben wird, wird für jedes Partikel zufällig dazwischen gezogen. Partikel laufen mit der Uhr weiter, höchstens eine Zehntelsekunde pro Frame, und halten an, solange das Spiel pausiert ist.

2.12.1. emitterNew

emitter = emitterNew()
emitter = emitterNew(node)

Erzeugt einen Emitter. Ohne Argument ist es ein 2D-Emitter an der Overlay-Position (0, 0), der mit emitterSetPosition bewegt wird; mit einem Knoten ist es ein 3D-Emitter, dessen Partikel an der Weltposition dieses Knotens geboren werden, und er braucht die 3D-Szene, sodass der Aufruf auf einem Rechner ohne sie das Skript beendet (2D-Emitter funktionieren überall). Ein neuer Emitter strömt noch nicht; ruf emitterStart oder emitterBurst auf. Wird der Knoten gelöscht, werden seine Emitter mitgelöscht. Standardwerte: 50 Partikel pro Sekunde, die ein bis zwei Sekunden leben, 30 Grad Streuung, Weiß, das zu transparent verblasst, normales Blending, keine Schwerkraft, keine Dämpfung, keine Drehung, kein Radius, keine Textur, kein Schweif und keine Kollision, ein Pool von 1000; ein 2D-Emitter schickt sie mit 50 bis 100 Overlay-Einheiten pro Sekunde den Bildschirm hinauf und lässt sie von 16 auf 4 schrumpfen, ein 3D-Emitter mit 1 bis 2 Welteinheiten pro Sekunde die Y-Achse hinauf, schrumpfend von 0,2 auf 0,05.

Rückgabe: Das Handle des Emitters.

Seit: 3.00. Siehe auch: emitterDelete, emitterStart, emitterBurst, emitterDraw

Beispiel
-- Abgas vom Triebwerksknoten des Schiffs; das Rezept wird gesetzt, bevor der Strom beginnt.
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)

Entfernt den Emitter, seine lebenden Partikel und seine Kopie der Textur sofort; nichts blendet aus. Verwende stattdessen emitterStop, um die letzten Partikel zu Ende leben zu lassen. Ein 3D-Emitter wird auch von selbst entfernt, wenn sein Knoten gelöscht wird. Ein Handle, das kein lebender Emitter ist, beendet das Skript, leere die Variable also danach.

Seit: 3.00. Siehe auch: emitterNew, emitterStop, emitterIsActive

Beispiel
-- Die Explosion ist vorbei: ihren Emitter freigeben, sobald der letzte Funke erloschen ist.
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)

Das Bild, das jedes Partikel trägt: ein geladenes Sprite oder keines (ein Argument oder nil) für die eingebaute weiche Scheibe. Der Emitter behält seine eigene Kopie der Pixel des Sprites, jeden Frame eines animierten Sprites eingeschlossen, das Sprite kann danach also entladen werden. Das Setzen der Textur setzt den Frame-Bereich auf Frame 0 zurück und setzt jedes lebende Partikel auf Frame 0, ruf emitterSetFrames also danach auf, nicht davor. Blending und Tönung wirken auf das Bild wie auf die Scheibe.

Seit: 3.00. Siehe auch: emitterSetFrames, spriteLoad, emitterSetBlend

Beispiel
-- Schnee: ein Spritesheet mit sechs Flockenformen, eine pro Partikel zufällig gewählt.
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)

Mit einem animierten Sprite als Textur nimmt jedes neue Partikel einen zufälligen Frame von first bis last und behält ihn sein Leben lang; Frames zählen ab 0. Die Werte werden auf die Frames begrenzt, die die Textur hat, und last wird auf first angehoben, wenn es kleiner ist. Standard: nur Frame 0, auf den auch emitterSetTexture zurücksetzt. Mit der eingebauten Scheibe oder einem Sprite aus einem einzigen Frame hat der Bereich keine Wirkung.

Seit: 3.00. Siehe auch: emitterSetTexture, spriteLoad

Beispiel
-- Das Wölkchen-Sheet hat vier weiche Wölkchen, dann vier härtere Trümmerbrocken.
emitterSetTexture(smoke, puffSheet)
emitterSetFrames(smoke, 0, 3)
emitterSetTexture(debris, puffSheet)
emitterSetFrames(debris, 4, 7)

2.12.5. emitterSetBlend

emitterSetBlend(emitter, mode)

Wie sich Partikel mit dem verbinden, was hinter ihnen liegt. PARTICLE_ALPHA (Standard) blendet normal, für Rauch, Staub, Regen und Trümmer; PARTICLE_ADD addiert Licht, für Feuer, Funken, Leuchten und Magie, und dunkelt nie ab. Wirkt sofort auf die lebenden Partikel. Alles andere als diese beiden Konstanten beendet das Skript.

Seit: 3.00. Siehe auch: emitterSetColor, emitterSetTexture

Beispiel
-- Funken leuchten; der Rauch über ihnen nicht.
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)

Nur 2D: wohin emitterDraw die Partikel setzt. PARTICLE_OVER (Standard) zeichnet über allem auf dem Overlay; PARTICLE_UNDER zeichnet unter dem Overlay und über dem Video und der 3D-Szene, für Rauch hinter dem Punktestand. Bei einem 3D-Emitter wird die Einstellung angenommen und ignoriert. Alles andere als diese beiden Konstanten beendet das Skript.

Seit: 3.00. Siehe auch: emitterDraw, emitterSetPosition

Beispiel
-- Regen fällt hinter dem HUD, die Trefferfunken davor.
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)

Wie viele Partikel pro Sekunde ein gestarteter Emitter erzeugt; Standard 50, negative Werte werden zu 0. Bruchteile summieren sich, sodass 0.5 alle zwei Sekunden eines erzeugt. Ändere den Wert während des Stroms, um eine Flamme oder eine Schubdüse zu drosseln. Ein voller Pool (emitterSetMax) erzeugt keine weiteren, bis einige sterben, egal bei welcher Rate.

Seit: 3.00. Siehe auch: emitterStart, emitterBurst, emitterSetMax

Beispiel
-- Der Abgasstrahl der Schubdüse folgt dem Gashebel.
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)

Wie lange jedes neue Partikel lebt, zufällig zwischen den beiden gezogen; Standard 1 bis 2. Seine Größe und Farbe laufen über diese Zeit von ihrem Anfang zu ihrem Ende, die Lebensdauer bestimmt also das Tempo jedes Ausblendens. Das Minimum wird bei 0.001 oder darüber gehalten, und das Maximum wird auf das Minimum angehoben, wenn es kleiner ist. Lebende Partikel behalten die Lebensdauer, mit der sie geboren wurden.

Seit: 3.00. Siehe auch: emitterSetSize, emitterSetColor, emitterSetRate

Beispiel
-- Mündungsfeuer: ein Stoß, der in einer Zehntelsekunde vorbei ist.
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)

Nur 3D: blendet ein Partikel über distance Welteinheiten aus, wo es auf Geometrie dahinter trifft, sodass ein Rauchwölkchen keine harte Linie zeichnet, wo es eine Wand kreuzt, und ein Springbrunnen in sein Becken eintaucht, statt es zu zerschneiden. 0 (der Standard) schaltet es aus; negative Werte werden zu 0. Solange irgendein Emitter es verwendet, wird die Tiefe der Szene pro Frame einmal mehr gerendert, ein Raspberry Pi sollte es also sparsam einsetzen. Ein 2D-Emitter speichert den Wert und ignoriert ihn.

Seit: 3.00. Siehe auch: emitterSetLit, emitterSetBlend

Beispiel
-- Rauch aus der Feuerschale wird weich am Pfosten, an dem er vorbeisteigt.
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)

Anfangsgeschwindigkeit jedes neuen Partikels, zufällig zwischen den beiden gezogen, in Overlay-Einheiten pro Sekunde (2D) oder Welteinheiten pro Sekunde (3D); Standard 50 bis 100 in 2D und 1 bis 2 in 3D. Das Maximum wird auf das Minimum angehoben, wenn es kleiner ist. Die Geschwindigkeit bestimmt, wie weit ein Partikel kommt, bevor Dämpfung, Schwerkraft und seine Lebensdauer übernehmen.

Beispiel
-- Ein Springbrunnen wirft Tropfen kräftig und gerade; Staub bewegt sich kaum.
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)

Die mittlere Richtung, in die neue Partikel aufbrechen; nur die Richtung zählt, nicht die Länge. 2D-Standard (0, -1), den Bildschirm hinauf, da Y im Overlay nach unten wächst; 3D-Standard (0, 1, 0), die Y-Achse der Welt hinauf. Ein 2D-Emitter ignoriert z; ein 3D-Emitter, der zwei Werte bekommt, erhält z = 0. Ein Nullvektor wird als (0, -1, 0) behandelt. Bei einem 3D-Emitter ist die Richtung in Weltachsen angegeben, nicht in denen des Knotens, dreh sie also selbst, wenn sich der Knoten dreht.

Seit: 3.00. Siehe auch: emitterSetSpread, emitterSetSpeed

Beispiel
-- Das Abgas strömt hinter dem Schiff hinaus, egal wohin es zeigt.
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)

Der halbe Winkel des Kegels (3D) oder Fächers (2D) um die Richtung, in den neue Partikel geworfen werden, 0 bis 180; 0 ist eine gerade Linie, 180 jede Richtung. Standard 30; Werte außerhalb des Bereichs werden begrenzt. In 3D werden die Richtungen gleichmäßig über die Kappe des Kegels verteilt, sodass sich ein weiter Kegel nicht zu seiner Achse hin ballt.

Seit: 3.00. Siehe auch: emitterSetDirection, emitterSetRadius

Beispiel
-- Feuerwerk fliegt überallhin; die Fackelflamme bleibt eine schmale Säule.
emitterSetSpread(fireworks, 180)
emitterSetSpread(flame, 15)

2.12.13. emitterSetGravity

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

Eine konstante Beschleunigung auf jedes Partikel, in Overlay-Einheiten (2D) oder Welteinheiten (3D) pro Sekunde zum Quadrat: (0, 500) zieht 2D-Funken den Bildschirm hinunter, (0, -20) lässt 2D-Rauch aufsteigen, (0, -9.8, 0) ist die Erde in der Szene. Standard keine. Sie wirkt ab dem nächsten Frame auf die lebenden Partikel. Partikel sind keine Physikkörper; gib ihnen emitterSetCollide, damit sie von einem Boden oder der Szene abprallen.

Beispiel
-- Funken fallen, Rauch steigt, beides vom selben Schleifer.
emitterSetGravity(sparks, 0, 500)
emitterSetGravity(smoke, 0, -20)

-- Unter Wasser streben die Blasen zur Oberfläche.
emitterSetGravity(bubbles, 0, 3, 0)

2.12.14. emitterSetDrag

emitterSetDrag(emitter, perSecond)

Wie schnell Partikel ihre Geschwindigkeit verlieren: in jedem Frame wird die Geschwindigkeit mit 1 - perSecond * dt multipliziert, nie unter 0, sodass 1 den größten Teil der Geschwindigkeit innerhalb einer Sekunde nimmt und 0 (der Standard) sie für immer behält. Negative Werte werden zu 0. Rauch, Glut und Feuerwerk werden langsamer; Funken und Regen nicht. Wirkt ab dem nächsten Frame auf die lebenden Partikel.

Seit: 3.00. Siehe auch: emitterSetGravity, emitterSetSpeed

Beispiel
-- Eine Feuerwerksbombe: schnell hinaus, dann schweben und fallen.
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)

Größe bei der Geburt und beim Tod, in Overlay-Einheiten (2D) oder Welteinheiten (3D), gleichmäßig über die Lebensdauer des Partikels wechselnd; Standard 16 bis 4 in 2D und 0.2 bis 0.05 in 3D. variation (0 bis 1, Standard 0) skaliert beide Größen jedes neuen Partikels mit einem einzigen Zufallsfaktor zwischen 1 - variation und 1 + variation, sodass ein Wölkchen sein ganzes Leben lang etwas größer oder kleiner ist. Negative Größen werden zu 0, und variation wird begrenzt. Ein texturiertes Partikel wird als Quadrat dieser Größe gezeichnet; ein breiteres Bild wird gestaucht.

Seit: 3.00. Siehe auch: emitterSetLife, emitterSetColor, emitterSetSpin

Beispiel
-- Rauch wächst, während er dünner wird; Funken schrumpfen zu nichts.
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)

Wovon Partikel abprallen. COLLIDE_NONE (Standard) ist nichts; COLLIDE_FLOOR ist eine waagerechte Ebene in der Höhe floor, unterhalb derer (größeres Y in 2D, kleineres Y in 3D) ein Partikel auf die Ebene zurückgesetzt und reflektiert wird; COLLIDE_SCENE ist die Physikwelt, nur für 3D-Emitter, mit einem Raycast pro Partikel entlang seiner Bewegung in jedem Frame, begrenzt auf 200 Raycasts pro Emitter und Frame und dort fortgesetzt, wo sie aufgehört haben, sodass ein großer Emitter die Kosten über ein paar Frames verteilt. Bei einem 2D-Emitter wird COLLIDE_SCENE angenommen und tut nichts. Ein anderer Modus als diese drei beendet das Skript.

Parameter:

  • mode — COLLIDE_NONE, COLLIDE_FLOOR oder COLLIDE_SCENE.

  • bounce — wie viel Geschwindigkeit einen Aufprall übersteht, 0 bis 1, Standard 0.5; begrenzt.

  • friction — wie viel Gleitgeschwindigkeit pro Aufprall verloren geht, 0 bis 1, Standard 0.2; begrenzt.

  • floor — Höhe der Bodenebene, in Welteinheiten bei einem 3D-Emitter oder in Overlay-Einheiten bei einem 2D-Emitter, Standard 0. Wird nur von COLLIDE_FLOOR verwendet.

Beispiel
-- Funken prallen auf dem Werkstattboden ab (Overlay-Zeile 440) und hinterlassen Streifen.
sparks = emitterNew()
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetGravity(sparks, 0, 500)
emitterSetCollide(sparks, COLLIDE_FLOOR, 0.4, 0.2, 440)
emitterSetTrail(sparks, 6, 3)

-- Glut in der Szene prallt von allem ab, was die Physikwelt enthält.
emitterSetCollide(embers, COLLIDE_SCENE, 0.3, 0.5)

2.12.17. emitterSetColor

emitterSetColor(emitter, r, g, b, a, r2, g2, b2, a2)

Farbe und Deckkraft bei der Geburt (r, g, b, a) und beim Tod (r2, g2, b2, a2), jeweils 0 bis 255, gleichmäßig über die Lebensdauer des Partikels wechselnd; Werte außerhalb des Bereichs werden begrenzt. Standard: von Weiß und deckend zu Weiß und transparent. Die Tönung multipliziert die Textur oder die eingebaute Scheibe, ein weißes Bild nimmt die Farbe also genau an. Ein Ein- und Ausblenden braucht zwei Emitter oder eine Textur, in der die Form steckt; ein Rezept fährt eine einzige gerade Rampe.

Seit: 3.00. Siehe auch: emitterSetBlend, emitterSetLife, emitterSetSize

Beispiel
-- Flamme: hellgelb am Fuß, verglimmt zu mattem Rot und ist weg.
emitterSetColor(flame, 255, 200, 90, 255, 255, 40, 0, 0)
-- Staubkörnchen blenden aus dem Nichts ein und schweben; ihre Lebensdauer beendet sie.
emitterSetColor(dust, 255, 240, 200, 0, 255, 240, 200, 160)

2.12.18. emitterSetSpin

emitterSetSpin(emitter, min, max)

Drehgeschwindigkeit jedes neuen Partikels in Grad pro Sekunde, zufällig zwischen den beiden gezogen; negative Werte drehen andersherum, und ein Bereich, der 0 überspannt, ergibt beides. Jedes Partikel beginnt mit einem zufälligen Winkel, ob es sich dreht oder nicht. Standard keine. Das Maximum wird auf das Minimum angehoben, wenn es kleiner ist. Die Drehung sieht man an einem texturierten Partikel oder einem Schweif; die eingebaute Scheibe ist rund und sieht in jedem Winkel gleich aus.

Seit: 3.00. Siehe auch: emitterSetTexture, emitterSetSize

Beispiel
-- Blätter taumeln; Glut dreht sich kaum.
emitterSetTexture(leaves, leafSprite)
emitterSetSpin(leaves, -180, 180)
emitterSetSpin(embers, -20, 20)

2.12.19. emitterSetRadius

emitterSetRadius(emitter, radius)

Neue Partikel werden irgendwo innerhalb dieses Abstands vom Ursprung des Emitters geboren, gleichmäßig über eine Scheibe (2D) oder eine Kugel (3D), in Overlay- oder Welteinheiten. Standard 0, ein Punkt; negative Werte werden zu 0. Ein Radius füllt ein Volumen, einen Fackelkopf oder ein Stück Staub in der Luft, wo ein Punkt eine Nadel ergäbe.

Seit: 3.00. Siehe auch: emitterSetSpread, emitterSetPosition

Beispiel
-- Staub in einer raumgroßen Luftkugel, das meiste schon da, wenn das Level beginnt.
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)

Nur 3D: schattiert jedes Partikel nach den Lichtern und dem Himmel der Szene, als wäre es eine kleine Kugel, die zur Kamera zeigt, sodass Rauch die Farbe einer Feuerschale annimmt und Staub in der Sonne glitzert. Standardmäßig aus; Schatten werden nicht berücksichtigt. Mit PARTICLE_ADD wird die Beleuchtung trotzdem auf die Tönung angewendet, bevor sie addiert wird. Ein 2D-Emitter speichert den Wert und ignoriert ihn.

Seit: 3.00. Siehe auch: emitterSetSoftness, emitterSetBlend

Beispiel
-- Der Rauch über jeder Feuerschale nimmt ihren Feuerschein an.
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)

Ob lebende Partikel dem Emitter folgen. false (Standard) lässt jedes dort, wo es geboren wurde, sodass eine durch einen Raum getragene Fackel Rauch hinter sich lässt; true hält die ganze Wolke relativ zum Ursprung des Emitters, sodass sich der Abgasstrahl einer Schubdüse mit dem Schiff bewegt. Das Umschalten überführt die lebenden Partikel ohne Sprung von einem Bezugssystem ins andere. Bei einem 3D-Emitter ist der Ursprung die Weltposition des Knotens; bei einem 2D-Emitter ist es der Punkt von emitterSetPosition, eine lokale 2D-Wolke gleitet also ebenfalls mit. Schweife folgen derselben Regel.

Seit: 3.00. Siehe auch: emitterSetPosition, emitterSetRadius

Beispiel
-- Eine magische Aura, die die Zauberin beim Gehen umhüllt.
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)

Der Pool: wie viele Partikel gleichzeitig leben dürfen, Standard 1000. Ein voller Pool erzeugt keine weiteren, weder aus dem Strom noch aus einem Stoß, bis einige sterben. Eine Änderung der Anzahl baut den Pool neu und tötet jedes lebende Partikel, setz sie also vor dem Start. Bemiss den Pool als Rate mal längste Lebensdauer plus den größten Stoß. Eine Anzahl unter 1 beendet das Skript.

Seit: 3.00. Siehe auch: emitterSetRate, emitterBurst, emitterGetCount

Beispiel
-- 300 Tropfen pro Sekunde mit bis zu 1,6 Sekunden Leben brauchen etwa 480; lass Luft.
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)

Nur 2D: wo neue Partikel geboren werden, in Overlay-Koordinaten; Standard (0, 0). Setze die Position in jedem Frame, um einem Sprite oder einem 2D-Physikkörper zu folgen. Lebende Partikel bleiben, wo sie sind, außer emitterSetLocal ist eingeschaltet. Ein 3D-Emitter folgt seinem Knoten und beendet hier das Skript; bewege stattdessen den Knoten.

Seit: 3.00. Siehe auch: emitterDraw, emitterSetLocal, emitterSetRadius

Beispiel
-- Funken fliegen dort, wo das Schleifer-Sprite in diesem Frame ist.
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)

Ein Band hinter jedem Partikel durch seine letzten length Positionen, eine pro Frame aufgezeichnet (2 bis 16; 0 oder 1 für keines, der Standard), width breit in Welt- oder Overlay-Einheiten, in 2D wie in 3D. Das Band trägt die aktuelle Tönung des Partikels, verblasst zu seinem Ende hin zu transparent und wird mit der mittleren Spalte des Partikelbilds texturiert, sodass der weiche Rand der Scheibe zum Rand des Bands wird. Die Werte werden auf den Bereich begrenzt. Eine Änderung der Länge baut den Speicher der Schweife neu, lebende Partikel beginnen ihre Bänder also von vorn. Funken, Glut, Leuchtspurgeschosse, Kometen.

Beispiel
-- Leuchtspurgeschosse: winzig, schnell und ganz Streifen.
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)

Beginnt den stetigen Strom mit der eingestellten Rate; von da an erzeugt der Emitter in jedem Frame Partikel bis emitterStop. Einen Emitter zu starten, der bereits strömt, ändert nichts. Der Strom braucht keinen Zeichenaufruf, um zu laufen; ein 2D-Emitter, der strömt, aber nicht gezeichnet wird, verbraucht trotzdem seinen Pool.

Seit: 3.00. Siehe auch: emitterStop, emitterSetRate, emitterBurst

Beispiel
-- Das Triebwerk zündet, wenn der Spieler Gas gibt, und erlischt, wenn er es wegnimmt.
function onThrottle(open)
    if open then
        emitterStart(exhaust)
    else
        emitterStop(exhaust)
    end
end

2.12.26. emitterStop

emitterStop(emitter)

Beendet den Strom; die lebenden Partikel leben ihr Leben zu Ende, und jeder noch geschuldete Bruchteil eines Partikels wird verworfen. emitterBurst funktioniert auch bei einem gestoppten Emitter, und emitterIsActive bleibt true, bis das letzte Partikel stirbt. Verwende emitterClear, um die Partikel außerdem sofort zu entfernen.

Seit: 3.00. Siehe auch: emitterClear, emitterStart, emitterIsActive

Beispiel
-- Die Fackel erlischt: die Flamme stoppen, den letzten Rauch davontreiben lassen.
function onTorchDoused()
    emitterStop(flame)
    emitterStop(smoke)
    soundPlay(hiss)
end

2.12.27. emitterBurst

emitterBurst(emitter, count)

Erzeugt count Partikel auf einmal nach dem aktuellen Rezept, mit oder ohne Strom: eine Explosion, ein Spritzer, ein Wölkchen. Es werden nur so viele erzeugt, wie im Pool Platz haben; emitterSetMax legt den Platz fest. Ein 2D-Emitter stößt sie an seinem Punkt von emitterSetPosition aus, ein 3D-Emitter an seinem Knoten, verteilt über emitterSetRadius.

Seit: 3.00. Siehe auch: emitterStart, emitterSetMax, emitterSetRadius

Beispiel
-- Feuerwerk: ungefähr jede Sekunde platzt irgendwo über der Disc eine Bombe.
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)

Tötet jetzt jedes lebende Partikel und vergisst jeden noch geschuldeten Bruchteil eines Partikels. Der Strom wird nicht gestoppt: ein gestarteter Emitter erzeugt im nächsten Frame weiter neue Partikel, ruf also auch emitterStop auf, um ihn endgültig zu leeren. Verwende es, wenn eine Szene wechselt und die alten Funken nicht nachglimmen dürfen.

Seit: 3.00. Siehe auch: emitterStop, emitterDelete

Beispiel
-- Das Level neu starten: die Emitter bleiben, die alten Partikel gehen.
function resetLevel()
    for _, emitter in ipairs(levelEmitters) do
        emitterStop(emitter)
        emitterClear(emitter)
    end
    placePlayer()
end

2.12.29. emitterDraw

emitterDraw(emitter)

Nur 2D, aus onOverlayUpdate: stellt die Partikel des Emitters in die Warteschlange, damit sie in diesem Frame gezeichnet werden, über oder unter dem Overlay je nach emitterSetLayer, in Overlay-Koordinaten, die auf das Fenster abgebildet werden. Emitter auf derselben Ebene zeichnen in der Reihenfolge, in der sie eingereiht wurden. Die Warteschlange leert sich in jedem Frame, der Aufruf gehört also in jeden Frame, in dem die Partikel zu sehen sein sollen; einen Emitter nicht zu zeichnen, hält ihn nicht an. Bis zu 64 Emitter pro Ebene werden in einem Frame gezeichnet. Ein 3D-Emitter zeichnet sich selbst in der Szene und beendet hier das Skript.

Beispiel
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)

Wie viele Partikel des Emitters in diesem Frame leben, 0 bis zur Größe des Pools. Nützlich, um einen Pool abzustimmen, für ein Budget auf dem Bildschirm oder um zu wissen, wann ein Stoß verklungen ist.

Rückgabe: Die Anzahl der lebenden Partikel, eine Ganzzahl.

Seit: 3.00. Siehe auch: emitterSetMax, emitterIsActive

Beispiel
-- Entwicklungs-Overlay: wie viel von jedem Pool in Gebrauch ist.
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)

Ob der Emitter strömt oder noch lebende Partikel hat: true ab emitterStart oder emitterBurst, bis der Strom gestoppt und das letzte Partikel gestorben ist, false, sobald die Explosion vorbei ist. Ein strömender Emitter, dessen Pool gerade leer ist, ist trotzdem aktiv.

Rückgabe: Boolean.

Seit: 3.00. Siehe auch: emitterStop, emitterGetCount, emitterDelete

Beispiel
-- Einmalige Explosionen leben in einer Liste und werden freigegeben, wenn sie ausgebrannt sind.
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. Schriftart

Singe hat zwei Text-Renderer. Die eingebaute Konsolenschrift wird von overlayPrint gezeichnet und braucht keine Assets; die Familie font* lädt TrueType-Dateien in einer festen Punktgröße und rendert sie entweder mit fontPrint direkt auf das Overlay oder mit fontToSprite in ein wiederverwendbares Sprite. Schriftart-Handles sind Ganzzahlen aus fontLoad, und die Engine hält eine global ausgewählte Schriftart, die fontLoad auf die gerade geladene Schriftart setzt und fontSelect ändert. Text wird in der aktuellen Vordergrundfarbe in der von fontQuality gewählten Qualität gerendert, und Textpositionen sind Overlay-Koordinaten. Gib Schriftarten mit fontUnload frei; Singe/FreeSansBold.ttf wird mit der Engine mitgeliefert und ist immer verfügbar.

2.13.1. fontLoad

result = fontLoad(filename, pointSize)

Öffnet eine TrueType-Schriftart in einer Punktgröße und macht sie zur ausgewählten Schriftart. Die Größe ist für die Lebensdauer des Handles fest, lade dieselbe Datei also einmal pro benötigter Größe. Der Name geht wie jedes andere Asset durch das virtuelle Dateisystem; stelle DIR voran für Dateien, die mit deinem Spiel mitgeliefert werden, oder verwende Singe/FreeSansBold.ttf für den mitgelieferten Schriftschnitt. Eine Datei, die sich nicht öffnen lässt, beendet das Skript mit Unable to open und dem Namen.

Parameter:

  • filename — Pfad zu einer .ttf-Datei.

  • pointSize — ganzzahlige Punktgröße.

Rückgabe: ganzzahliges Schriftart-Handle.

Seit: 1.x Siehe auch: fontSelect, fontUnload, fontQuality

Beispiel
-- Zwei Größen des mitgelieferten Schriftschnitts: groß für den Titel, klein für das 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)

Rendert einen String mit der ausgewählten Schriftart, der aktuellen Qualität und der aktuellen Vordergrundfarbe (bei FONT_QUALITY_SHADED zusätzlich der Hintergrundfarbe) und blittet ihn dann mit seiner oberen linken Ecke bei (x, y) auf das Overlay. Ruf es aus onOverlayUpdate auf, wenn nötig in jedem Frame: die Engine behält jeden String, den sie rendert, mit Schriftart, Qualität, Farben und Text als Schlüssel, und ein späterer Aufruf, der denselben verlangt, blittet ihn nur noch. Strings, die etwa eine Sekunde lang nicht ausgegeben wurden, werden vergessen, und die Strings einer Schriftart verschwinden, wenn sie entladen wird, sodass Text, der sich ändert, nicht mehr kostet als schon immer, und Text, der sich nicht ändert, fast nichts. Eine ganze Seite Highscores in jedem Frame neu auszugeben ist in Ordnung. Ohne ausgewählte Schriftart endet das Skript mit einem Fehler.

Parameter:

  • x, y — obere linke Ecke in Overlay-Koordinaten; Nachkommastellen werden abgeschnitten.

  • text — der zu rendernde String.

Beispiel
-- Live-Anzeige der Audiokalibrierung; der Text ändert sich in jedem Frame, also direkt rendern.
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)

Wählt, wie fontPrint und fontToSprite Text von nun an rastern. Die Einstellung ist global, nicht pro Schriftart, und beginnt bei FONT_QUALITY_SOLID. Sprites, die fontToSprite schon erzeugt hat, behalten die Qualität, mit der sie gerendert wurden. Ein Wert außerhalb der drei Konstanten beendet das Skript mit einem Fehler.

Parameter:

  • mode — FONT_QUALITY_SOLID (1): am schnellsten, Ein-Bit-Kanten, keine Kantenglättung. FONT_QUALITY_SHADED (2): kantengeglättete Glyphen auf einem gefüllten Rechteck in der Hintergrundfarbe. FONT_QUALITY_BLENDED (3): kantengeglättete Glyphen mit Alpha pro Pixel, die sich über alles blenden; die übliche Wahl.

Seit: 1.x Siehe auch: fontPrint, fontToSprite, colorBackground

Beispiel
-- Text in BLENDED über dem Video, aber ein Beschriftungsfeld in SHADED für die Debug-Anzeige.
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)

Macht eine geladene Schriftart zu der, die fontPrint und fontToSprite verwenden. Die Auswahl bleibt bis zum nächsten fontSelect oder fontLoad bestehen, da auch das Laden auswählt. Sie kann so oft wie nötig geändert werden, auch mehrmals innerhalb eines onOverlayUpdate. Ein unbekanntes oder entladenes Handle (oder gar keine Zahl) lässt die aktuelle Schriftart ausgewählt und gibt eine Warnung aus, so wie Hypseus Singe es durchgehen lässt.

Seit: 1.x Siehe auch: fontLoad, fontPrint, fontToSprite

Beispiel
-- Titel im großen Schriftschnitt, Punktestand im kleinen, in jedem Frame.
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)

Rendert einen String mit der ausgewählten Schriftart, Qualität und den Farben in ein neues Sprite und gibt dessen Handle zurück. Das Sprite ist von da an unabhängig von der Schriftart, übersteht also fontUnload, und es funktioniert mit jedem sprite*-Aufruf: zeichne es, miss es, skaliere oder drehe es und gib es mit spriteUnload frei. Für einen String, der sich ändert, rendere ein neues Sprite und entlade das alte. Ohne ausgewählte Schriftart endet das Skript mit einem Fehler.

Text aus Leistungsgründen in ein Sprite zu rendern ist veraltet. fontPrint behält jetzt, was es rendert, sodass es etwa so viel kostet, denselben String in jedem Frame auszugeben, wie ein daraus gemachtes Sprite zu zeichnen, ohne dass ein Sprite zu verwalten ist. Verwende fontToSprite, wenn der Text ein Sprite sein muss: um ihn zu skalieren, zu drehen, zu spiegeln oder mit spriteGetWidth und spriteGetHeight zu messen.

Rückgabe: ganzzahliges Sprite-Handle.

Seit: 1.x Siehe auch: fontPrint, spriteDraw, spriteGetWidth, spriteUnload

Beispiel
-- Ein Titel, der sich drehend hereinwächst:  Text, der ein Sprite sein muss, um gedreht und skaliert zu werden.
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)

Schließt eine Schriftart und macht ihr Handle ungültig. Sprites, die mit fontToSprite daraus gemacht wurden, sind nicht betroffen. War die entladene Schriftart die ausgewählte, ist danach keine Schriftart ausgewählt, und das nächste fontPrint oder fontToSprite beendet das Skript mit einem Fehler, bis fontSelect oder fontLoad eine andere wählt.

Seit: 2.00 Siehe auch: fontLoad, fontSelect, onShutdown

Beispiel
-- Die Schriftarten und die Text-Sprites, die sie erzeugt haben, freigeben.
function onShutdown()
    spriteUnload(titleSprite)
    for _, line in ipairs(descriptionLines) do
        spriteUnload(line)
    end
    fontUnload(titleFont)
    fontUnload(hudFont)
end

2.14. Gui

Eine GUI ist ein RmlUi-Dokumentbaum fester Größe, der in jedem Frame in seine eigene Textur gerendert wird: guiNew erzeugt eine und gibt ein ganzzahliges Handle zurück, guiLoad legt ein RML-Dokument hinein und gibt ein Dokument-Handle zurück, guiDraw legt sie über das Overlay, und materialSetGui zeigt sie auf einem Material in der Szene. Dokumente sind HTML-artiges RML, gestaltet mit CSS-artigem RCSS, und werden wie Sprites über das virtuelle Dateisystem geladen; Singe/gui.rcss ist das mitgelieferte Theme und Singe/FreeSansBold.ttf der Ersatzschriftschnitt. Die Helfer nach id, guiGetValue, guiSetValue und guiSetHandler, erreichen Elemente ohne das Objektmodell; alles andere ist die Lua-API von RmlUi auf dem globalen rmlui, wo eine GUI der Kontext namens gui gefolgt von ihrem Handle ist. Bis zu sechzehn GUIs gibt es gleichzeitig, jede mit zweiunddreißig Dokumenten. Eine GUI braucht das GPU-Gerät, deshalb beendet guiNew das Skript auf einem Rechner ohne eines; ein falsches GUI-Handle löst No GUI N aus, ein falsches Dokument-Handle No document N in GUI G. Siehe GUI unter Spieleentwicklung.

2.14.1. guiClose

guiClose(gui, document)

Entlädt das Dokument aus der GUI und verwirft seine Elemente, seine Handler und seine Skripte. Das Dokument-Handle ist danach ungültig. Ein Dokument, das sein eigenes Skript über die API von RmlUi schließt (document:Close()), wird auf dieselbe Weise entladen. Löst bei einem ungültigen Handle No document N in GUI G aus.

Seit: 3.00. Siehe auch: guiLoad, guiHide, guiDelete

Beispiel
-- Die Seite für den Highscore-Eintrag wird nur einmal gebraucht; nach der Eingabe des Namens weg damit.
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)

Gibt die GUI, jedes Dokument darin und ihre Textur frei und beendet das Aktualisieren und Rendern in jedem Frame, das sie kostete. Materialien, die sie über materialSetGui zeigen, kehren zu ihrer eigenen Textur zurück. Das Handle ist danach ungültig und beendet das Skript, wenn es noch einmal verwendet wird; da eine GUI weiter rendert, ob sie gezeichnet wird oder nicht, lösche die, mit denen ein Spiel fertig ist, statt sie zu verstecken.

Seit: 3.00. Siehe auch: guiNew, guiClose, materialSetGui

Beispiel
-- Die Optionsseite lebt nur, solange der Spieler darin ist.
function closeOptions()
    guiDelete(optionsGui)
    optionsGui = nil
    discPlay()
end

2.14.3. guiDraw

guiDraw(gui)
guiDraw(gui, x, y)
guiDraw(gui, x, y, width, height)

Legt die Textur der GUI für diesen Frame über das Overlay, in Overlay-Koordinaten, sodass sie wie alles andere auf dem Overlay dem Sinden-Rahmen und der Overscan-Skalierung folgt: mit einem Argument über das ganze Overlay, in ihrer eigenen Größe mit einer Ecke bei x, y oder skaliert in das Rechteck width mal height. Die Stelle des Aufrufs im Zeichnen des Skripts entscheidet, was unter der GUI liegt und was darüber: alles, was vorher auf das Overlay gezeichnet wurde, bleibt darunter, und alles, was danach gezeichnet wird — bis zum nächsten guiDraw oder bis das Skript das nächste Mal an der Reihe ist — kommt auf eine eigene Ebene, die über diese GUI gelegt wird. Ein Zeiger, der nach dem HUD gezeichnet wird, liegt über dem HUD; ein danach gezeichnetes zweites Dokument liegt über dem Zeiger, mit seiner eigenen Ebene darüber. Bis zu sechzehn solcher Ebenen pro Frame; ein Aufruf darüber hinaus zeichnet seine GUI ohne etwas darüber. overlayClear leert die Ebene, auf die gerade gezeichnet wird, und overlaySetMonochrome macht nur das Basis-Overlay grau. Der Aufruf gilt einen Frame; mach ihn aus onOverlayUpdate (oder singeMain) in jedem Frame, in dem die GUI sichtbar sein soll. GUIs zeichnen über dem Overlay in der Reihenfolge der Aufrufe (die letzte oben), unter Partikeln in PARTICLE_OVER und der Pausenanzeige, und die GUI, die zuletzt unter dem Zeiger gezeichnet wurde, ist die, die die Maus bekommt. Bis zu sechzehn Aufrufe pro Frame werden beachtet; weitere werden ignoriert. Jede andere Anzahl von Argumenten löst Expected 1, 3 or 5 arguments aus.

Parameter:

  • x, y — die obere linke Ecke, in Overlay-Koordinaten.

  • width, height — die Größe, in der gezeichnet wird, in Overlay-Pixeln; ohne Angabe die eigene Größe der GUI.

Seit: 3.00. Siehe auch: guiNew, materialSetGui, overlaySetResolution

Beispiel
-- Das HUD sitzt in der unteren rechten Ecke mit einem Drittel der Breite des Overlays, und das Visier
-- der Lightgun wird danach gezeichnet, sodass das Panel das Visier nie verdeckt.
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)

Dasselbe wie guiDraw, nur dass das Rechteck über das ganze Fenster gemessen wird statt über das Bild. Die Koordinaten sind weiterhin Overlay-Koordinaten — 0, 0 ist oben links im Fenster und overlayGetWidth(), overlayGetHeight() unten rechts — sodass eine GUI auf der Bezel-Grafik neben dem Bild, darüber oder darunter sitzen kann. Ohne Bezel und ohne --scalefactor, --shiftx oder --shifty ist das Bild das ganze Fenster, und dies ist genau guiDraw.

GUIs im Bildschirmraum zeichnen nach allem anderen, die Bezel-Grafik eingeschlossen, und teilen sich die sechzehn Zeichenaufrufe pro Frame mit guiDraw. Ein Klick findet sie auf dieselbe Weise: der Zeiger wird in den Bildschirmraum übertragen, bevor er geprüft wird, sodass eine GUI im Bildschirmraum, die Eingaben annimmt, die Maus bekommt, wo auch immer sie gezeichnet wurde.

Parameter:

  • x, y — die obere linke Ecke, in Overlay-Koordinaten, über das Fenster gemessen.

  • width, height — die Größe, in der gezeichnet wird; ohne Angabe die eigene Größe der GUI.

Seit: 3.00. Siehe auch: guiDraw, Bezels, scoreBezelEnable

Beispiel
-- Eine Karte auf der linken Säule der Automatengrafik, außerhalb des Bilds.
function onOverlayUpdate()
    overlayClear()
    guiDrawScreen(mapGui, 8, 44, 38, 114)
    return OVERLAY_UPDATED
end

2.14.5. guiGetHeight

height = guiGetHeight(gui)

Die Höhe der GUI in ihren eigenen Pixeln, wie an guiNew übergeben. Beendet das Skript bei einem ungültigen Handle.

Rückgabe: Eine Ganzzahl.

Seit: 3.00. Siehe auch: guiGetWidth, guiNew

Beispiel
-- Einen kleinen Dialog auf dem Overlay zentrieren.
local x = (overlayGetWidth() - guiGetWidth(dialog)) / 2
local y = (overlayGetHeight() - guiGetHeight(dialog)) / 2
guiDraw(dialog, x, y)

2.14.6. guiGetStats

stats = guiGetStats()

Was das Rendern aller GUIs im letzten abgeschlossenen Frame gekostet hat, zum Abstimmen von Dokumenten, die Filter, Masken und Schatten verwenden (die alle über eine Ebene in der Größe der GUI zeichnen). Die Zähler gelten für alle GUIs zusammen. In einem Frame, in dem sich das Bild keiner GUI geändert hat, sind sie alle null, da nichts neu gezeichnet wurde (siehe guiRefresh).

Rückgabe: Eine Tabelle mit den Feldern drawCalls (indizierte Zeichenaufrufe, einschließlich Maskenschreibvorgängen, Kompositionen und Filterdurchgängen), layerPushes (betretene Ebenen für Filter, Maskenbilder und Box-Schatten), filterPasses (Durchgänge in voller Größe und Blits innerhalb von Filterketten; eine Unschärfe kostet mehrere), maskWrites (Zeichenaufrufe in die Stencil-Clipmaske), layerBytes (Bytes der derzeit belegten Ebenentexturen; jede hat die Größe ihrer GUI bei vier Bytes pro Pixel) und passes (begonnene Render-Durchgänge; jeder Ebenenwechsel beginnt einen).

Seit: 3.00. Siehe auch: guiNew, GUI

Beispiel
-- Beobachten, was ein Bildschirm voller Effekte kostet.
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)

Der Wert des Elements mit dieser id im Dokument, als String: der Wert eines Formularelements (der Text eines Textfelds, der value einer Option eines select, ein Schieberegler in der eigenen Formatierung von RmlUi wie "85.000000", das Attribut value eines Kontrollkästchens oder Optionsfelds, "on", wenn es keines hat, ob es angekreuzt ist oder nicht; sein Zustand ist sein Attribut checked, das über die API von RmlUi gelesen wird) oder bei jedem anderen Element sein inneres RML. Gibt nil zurück, wenn kein Element diese id hat, sodass eine Seite abgefragt werden kann, ohne das Skript zu beenden; ein falsches GUI- oder Dokument-Handle beendet es. Werte, die länger als 4095 Zeichen sind, werden abgeschnitten.

Rückgabe: Ein String oder nil.

Seit: 3.00. Siehe auch: guiSetValue, guiSetHandler

Beispiel
-- Das ganze Formular lesen, wenn Start gedrückt wird.
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)

Die Breite der GUI in ihren eigenen Pixeln, wie an guiNew übergeben. Beendet das Skript bei einem ungültigen Handle.

Rückgabe: Eine Ganzzahl.

Seit: 3.00. Siehe auch: guiGetHeight, guiNew

Beispiel
-- Liegt der abgefragte Punkt in der rechten Hälfte der Seite des Monitors?
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)

Versteckt das Dokument: es wird nicht gezeichnet und nimmt keine Eingaben an, behält aber seine Elemente und Werte, und guiShow bringt es so zurück, wie es war. Löst bei einem ungültigen Handle No document N in GUI G aus.

Seit: 3.00. Siehe auch: guiShow, guiClose

Beispiel
-- Zwei Seiten in einer GUI: die Optionsseite verschwindet, während die Steuerungsseite erscheint.
guiSetHandler(gui, options, "controls", "click", function()
    guiHide(gui, options)
    guiShow(gui, controls)
end)

2.14.10. guiLoad

document = guiLoad(gui, filename)

Lädt ein RML-Dokument in die GUI, zeigt es an und gibt ein ganzzahliges Dokument-Handle für die anderen Aufrufe zurück. Der Name geht wie der eines Sprites durch das virtuelle Dateisystem und wird relativ zu dem Ordner aufgelöst, in dem Singe gestartet wurde, stelle also DIR voran für Dateien, die mit deinem Spiel mitgeliefert werden; Stylesheets, Bilder und Schriftarten, die im Dokument genannt werden, werden relativ zu der Datei aufgelöst, die sie nennt, und dann über dieselbe Suche, sodass ein gepacktes Spiel sie findet. Die <script>-Blöcke und on*-Attribute des Dokuments laufen im Lua-Zustand des Spiels, und es ist als rmlui.contexts["guiN"].documents["<body id>"] erreichbar. Ein Dokument, das sich nicht laden lässt, beendet das Skript mit dem Namen und dem Grund von RmlUi (eine fehlende Datei, ein Parse-Fehler); die eigenen Warnungen von RmlUi zu Markup und Stil gehen an die Konsole. Jede GUI fasst bis zu zweiunddreißig Dokumente.

Rückgabe: Das Dokument-Handle, eine Ganzzahl.

Seit: 3.00. Siehe auch: guiNew, guiShow, guiHide, guiClose, guiLoadFont

Beispiel
-- Die Titelseite und das HUD teilen sich eine GUI in der Größe des Overlays.
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)

Lädt einen TrueType- oder OpenType-Schriftschnitt für jede GUI, sodass Dokumente ihn in font-family über den Familiennamen in der Datei nennen können (wobei font-weight und font-style unter den Schnitten einer Familie wählen). Mit fallback true bedient der Schnitt auch jede Glyphe, die kein anderer Schnitt hat, was bis dahin der engine-eigene Singe/FreeSansBold.ttf tut (Familie FreeSans, Gewicht fett, der Schnitt, den das mitgelieferte Theme verwendet). Lade Schriftarten vor den Dokumenten, die sie verwenden. Jeder Schnitt kostet einen Glyphenatlas pro Größe, in der er verwendet wird. Eine Datei, die sich nicht öffnen lässt, beendet das Skript mit Unable to load und dem Namen.

Parameter:

  • filename — die Schriftdatei, über das virtuelle Dateisystem wie bei fontLoad.

  • fallback — true, um dies zum Ersatzschnitt zu machen; false (der Standard) für einen gewöhnlichen Schnitt.

Seit: 3.00. Siehe auch: guiLoad, fontLoad

Beispiel
-- Der Anzeigeschnitt des Spiels für Überschriften; das mitgelieferte FreeSans bleibt für den Fließtext.
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)

Erzeugt eine GUI von width mal height Pixeln, die in jedem Frame in ihre eigene Textur gerendert wird, ob sie gezeichnet wird oder nicht, und gibt ihr Handle zurück. Die Größe ist der Koordinatenraum des Dokuments: 100% des Body ist die ganze Textur, und ein dp ist eines ihrer Pixel. Eine GUI in der Größe des Overlays passt zu einer Seite im Vollbild; ein HUD-Element oder ein Monitor in der Szene will eine kleinere, und ein Raspberry Pi will alles bescheiden. Eine neue GUI zeigt nur an, bis guiSetInput Eingaben einschaltet. Löst bei einer Größe von null oder kleiner The size must be positive aus und No GUI available, wenn schon sechzehn in Gebrauch sind oder der Rechner kein GPU-Gerät hat (eine GUI braucht dasselbe Gerät wie die 3D-Szene).

Parameter:

  • width — die Breite der Textur in Pixeln.

  • height — die Höhe der Textur in Pixeln.

Rückgabe: Das GUI-Handle, eine Ganzzahl.

Seit: 3.00. Siehe auch: guiLoad, guiDraw, guiDelete, materialSetGui

Beispiel
-- Eine Seite in der Größe des Overlays, über die Disc gezeichnet.
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)

Zeichnet die GUI im nächsten Frame erneut, auch wenn sich scheinbar nichts an ihr geändert hat. Eine GUI wird nur neu gezeichnet, wenn sich ihr Bild ändert: wenn das Dokument eines Frames genau das zeichnet, was der letzte Frame gezeichnet hat, und dazwischen nichts Neues erzeugt wurde, enthält die Textur dieses Bild schon und wird behalten, was der GPU den größten Teil der Kosten einer GUI in den Frames erspart, in denen ein HUD oder ein Menü stillsteht. Änderungen über RML, RCSS, die Lua-Schnittstelle von RmlUi oder die gui*-Aufrufe werden alle bemerkt. Dieser Aufruf ist der Ausweg, falls doch einmal eine übersehen wird — eine GUI, die aufhört, sich zu aktualisieren, wenn sie es sollte — und ein Spiel sollte ihn nicht brauchen; wenn doch, ist das eine Meldung wert. Eine GUI, die es nicht gibt, beendet das Skript.

Seit: 3.00. Siehe auch: guiDraw, guiGetStats

Beispiel
-- Ein Notbehelf, solange eine übersehene Änderung gemeldet ist:  das HUD in jedem Frame neu zeichnen.
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)

Ruft function(gui, document, id, event, value) auf, wann immer das Element mit dieser id das genannte Ereignis auslöst: "click" für Schaltflächen und Zeilen, "change" für Formularelemente, "submit" für ein Formular oder jeden anderen Ereignisnamen von RmlUi ("focus", "mouseover", "keydown", …​). value ist der Wert des Elements in diesem Moment als String, so wie guiGetValue ihn zurückgeben würde (ein Schieberegler kommt so, wie RmlUi ihn formatiert, "85.000000", gib ihn also durch tonumber). Pro Element und Ereignis wird eine Funktion behalten; eine andere zu setzen ersetzt sie, und nil entfernt sie. Der Handler gehört zur id, nicht zu einem Element: setze ihn nach dem Neuaufbau erneut, wenn das Element ersetzt wird — eine über inner_rml neu aufgebaute Liste erzeugt neue Elemente — und er hängt sich an das Element, das die id jetzt trägt. Handler laufen, während die Ereignisse geschehen, zwischen den eigenen Callbacks des Spiels, und ein Fehler in einem beendet das Spiel wie ein Fehler in jedem Callback. Ids sind höchstens 63 Zeichen lang. Löst No element "id" in document N of GUI G aus, wenn das Element nicht existiert, und Argument 5 must be a function or nil bei allem anderen an dieser Stelle.

Parameter:

  • id — das Attribut id des Elements.

  • event — der Ereignisname von RmlUi.

  • function — die aufzurufende Lua-Funktion oder nil, um keine mehr aufzurufen.

Seit: 3.00. Siehe auch: guiGetValue, guiSetValue, guiSetInput

Beispiel
-- Ein Lautstärkeregler wirkt, während er bewegt wird; Start liest den Rest des Formulars.
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)

Ob Maus und Lightgun, Tasten, getippter Text und die Schalter des Frameworks von einem Pad oder einer Maus die GUI erreichen. Eine neue GUI zeigt nur an, was zu einem HUD oder einem Schild passt; schalte Eingaben für ein Menü oder ein Formular ein. Solange sie eingeschaltet sind, erreicht der Zeiger die GUI, wo auch immer sie flach gezeichnet (die zuletzt gezeichnete oben) oder auf einer Fläche in der Szene gezeigt wird, jede Taste geht an sie außer Tab, das die GUI nur bekommt, während in ein Textfeld getippt wird (RmlUi verwendet es, um den Fokus zu bewegen, und gibt es nie zurück, und ein Spiel, dessen Tasten Tab einschließen, würde es sonst verlieren), ein Textfeld mit Fokus schaltet die Texteingabe von SDL ein, und die Richtungen des Pads kommen als Pfeiltasten an, mit ACTION_1 als Eingabetaste und ACTION_2 als Esc. Was ein Element verwendet, erreicht nie onInputPressed, onKeyPressed oder die Maus-Callbacks; was nichts verwendet hat, fällt wie üblich zu ihnen durch. Beendet das Skript bei einem ungültigen Handle.

Seit: 3.00. Siehe auch: guiSetHandler, guiDraw, sceneProbeGui

Beispiel
-- Das HUD nimmt nie Eingaben an; die Pausenseite schon, solange sie angezeigt wird.
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)

Setzt den Wert des Elements mit dieser id: den Wert eines Formularelements (den Text eines Textfelds, die Zahl eines Schiebereglers, den value einer Option eines select; der Zustand checked eines Kontrollkästchens ist ein Attribut und wird über die API von RmlUi gesetzt) oder bei jedem anderen Element sein inneres RML, sodass ein Absatz oder ein div mit schlichtem Text oder mit Markup neu geschrieben werden kann. Das Dokument berechnet sein Layout im nächsten Frame neu. Löst No element "id" in document N of GUI G aus, wenn das Element nicht existiert.

Parameter:

  • id — das Attribut id des Elements.

  • value — der neue Wert, ein String; Zahlen werden umgewandelt.

Seit: 3.00. Siehe auch: guiGetValue, guiSetHandler

Beispiel
-- Die Punktezeile und die Lebenszeile werden in jedem Frame neu geschrieben; die Lebenszeile ist Markup.
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)

Zeigt ein von guiHide verstecktes Dokument an (ein Dokument wird angezeigt, wenn guiLoad zurückkehrt, der Aufruf ist dann also nicht nötig). Ein angezeigtes Dokument wird überall gezeichnet, wo seine GUI gezeichnet wird, und nimmt Eingaben an, wenn seine GUI es tut. Löst bei einem ungültigen Handle No document N in GUI G aus.

Seit: 3.00. Siehe auch: guiHide, guiLoad

Beispiel
-- Die Game-Over-Seite erscheint, wenn das letzte Leben verloren geht.
function onLastLifeLost()
    guiSetValue(gui, gameOver, "final", string.format("%08d", score))
    guiShow(gui, gameOver)
end

2.15. Gelenk

Gelenke verbinden zwei Körper, oder einen Körper mit der Welt, wenn der zweite Knoten -1 ist, und geben ein ganzzahliges Gelenk-Handle zurück, das die anderen Aufrufe entgegennehmen. Anker und Achsen werden in Weltkoordinaten zu dem Zeitpunkt angegeben, an dem das Gelenk entsteht, mit den Körpern dort, wo sie sich dann befinden; platziere die Knoten also und gib ihnen Körper, bevor du sie durch ein Gelenk verbindest. Abstände sind in Welteinheiten, Scharnierwinkel in Grad. Wird einer der beiden Körper oder sein Knoten gelöscht, wird das Gelenk mitgelöscht; ein Handle, das gelöscht wurde, beendet das Skript, wenn es wieder übergeben wird. Siehe Physik unter Spieleentwicklung, Gelenke.

2.15.1. jointHinge

joint = jointHinge(nodeA, nodeB, ax, ay, az, dx, dy, dz)

Erzeugt ein Scharnier zwischen den beiden Körpern durch den Weltpunkt (ax, ay, az) entlang der Achse (dx, dy, dz): eine Tür, ein Rad, ein Hebel, eine Wippe. Die Körper teilen sich diesen Punkt und diese Achse und können sich nur um sie drehen. Die Achse wird normalisiert, ihre Länge spielt also keine Rolle; eine Nullachse wird zu (0, 1, 0). Beide Knoten müssen einen Körper tragen, oder nodeB darf -1 sein, um nodeA per Scharnier an der Welt zu befestigen. Beendet das Skript, wenn ein Knoten keinen Körper hat oder das Gelenk nicht erzeugt werden kann.

Parameter:

  • nodeA — der Körper, dessen Drehung gemessen wird; ein positiver jointSetLimits-Winkel ist seine Drehung um die Achse nach der Rechte-Hand-Regel.

  • nodeB — der andere Körper oder -1 für die Welt.

  • ax, ay, az — der Anker, ein Weltpunkt, durch den die Scharnierachse geht.

  • dx, dy, dz — die Scharnierachse in Weltkoordinaten.

Rückgabe: Das Gelenk-Handle.

Seit: 3.00. Siehe auch: jointSetLimits, jointDelete, jointBall

Beispiel
-- Eine Tür, entlang ihrer linken Kante an der Welt angeschlagen, die sich 100 Grad in eine Richtung öffnet.
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)
-- Später schwingt sie durch einen Stoß nahe der Klinke auf.
bodyApplyImpulse(door, 0, 0, -60, 0.5, -0.62, 1.45)

2.15.2. jointBall

joint = jointBall(nodeA, nodeB, ax, ay, az)

Erzeugt ein Kugelgelenk am Weltpunkt (ax, ay, az): Die Körper können sich beliebig darum drehen, sich aber nicht voneinander lösen. Ein Pendel, ein Kettenglied, ein hängendes Schild, eine Ragdoll-Schulter. Beide Knoten müssen einen Körper tragen, oder nodeB darf -1 sein, um nodeA an einem festen Punkt in der Welt aufzuhängen. Ein Kugelgelenk hat keine Grenzen, deshalb lehnt jointSetLimits es ab. Beendet das Skript, wenn ein Knoten keinen Körper hat oder das Gelenk nicht erzeugt werden kann.

Parameter:

  • nodeA — der erste Körper.

  • nodeB — der andere Körper oder -1 für die Welt.

  • ax, ay, az — der Anker, der Weltpunkt, um den die Körper schwenken.

Rückgabe: Das Gelenk-Handle.

Seit: 3.00. Siehe auch: jointHinge, jointDelete, bodyApplyImpulse

Beispiel
-- Eine Kette aus vier Gliedern an einem Haken, jedes per Kugelgelenk mit dem darüber verbunden.
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)

Lässt die Körper relativ zueinander nur entlang der Achse (dx, dy, dz) durch den Anker (ax, ay, az) gleiten, wobei ihre Ausrichtung erhalten bleibt: eine Schublade, ein Kolben, ein Aufzug, eine Schiebetür. Die Achse wird normalisiert, ihre Länge spielt also keine Rolle; eine Nullachse wird zu (0, 1, 0). Beide Knoten müssen einen Körper tragen, oder nodeB darf -1 sein, damit nodeA auf einer fest in der Welt verankerten Schiene läuft. Beendet das Skript, wenn ein Knoten keinen Körper hat oder das Gelenk nicht erzeugt werden kann.

Parameter:

  • nodeA — der Körper, dessen Weg gemessen wird; ein positiver jointSetLimits-Abstand liegt in Achsrichtung.

  • nodeB — der andere Körper oder -1 für die Welt.

  • ax, ay, az — ein Weltpunkt auf der Schiene.

  • dx, dy, dz — die Bewegungsrichtung in Weltkoordinaten.

Rückgabe: Das Gelenk-Handle.

Seit: 3.00. Siehe auch: jointSetLimits, jointHinge, bodySetVelocity

Beispiel
-- Eine Kiste auf einer Schiene entlang X, zu Beginn seitwärts angestoßen und 2.4 Einheiten weiter gestoppt.
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)

Begrenzt den Winkel eines Scharniers in Grad oder den Weg eines Schiebegelenks in Welteinheiten, nach beiden Seiten von der Stellung aus, in der das Gelenk begann. Ein positiver Scharnierwinkel ist eine Drehung von nodeA um die Achse nach der Rechte-Hand-Regel; ein positiver Schiebeweg liegt in Achsrichtung. low wird auf höchstens 0 begrenzt und high auf mindestens 0, sodass die Ausgangsstellung immer im Bereich liegt. Ruf es erneut auf, um den Bereich jederzeit zu ändern. Beendet das Skript bei einem Kugelgelenk oder einem Handle, das nicht mehr existiert.

Parameter:

  • joint — das Handle aus jointHinge oder jointSlider.

  • low — der äußerste negative Winkel oder Abstand, 0 oder darunter.

  • high — der äußerste positive Winkel oder Abstand, 0 oder darüber.

Hinweise: Die beiden Körper tauschen die Rollen, wenn sie in umgekehrter Reihenfolge angegeben werden, was das Vorzeichen des Bereichs spiegelt.

Seit: 3.00. Siehe auch: jointHinge, jointSlider

Beispiel
-- Ein Hebel, der 30 Grad in jede Richtung kippt und einrastet, sobald das Rätsel gelöst ist.
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)

Entfernt das Gelenk; die Körper sind wieder frei voneinander und behalten die Geschwindigkeit, die sie gerade hatten. Gelenke verschwinden auch mit einem ihrer Körper, deshalb wird dies nur gebraucht, um zwei Körper voneinander zu lösen, die beide bleiben. Beendet das Skript bei einem Handle, das nicht existiert oder bereits gelöscht wurde.

Seit: 3.00. Siehe auch: jointHinge, jointBall, bodyDelete

Beispiel
-- Das Seil reißt, wenn die daran hängende Kiste hart genug getroffen wird.
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

Jeder Controller, den Singe öffnet, ist ein Gamepad und wird über die controller*-Aufrufe gelesen; ein Gerät, das SDL nicht erkennt, erreicht sie über eine Belegung, die Singe dafür schreibt, es gibt also nichts anderes aufzurufen. Siehe Jedes Gerät ist ein Gamepad. Die beiden Aufrufe hier sorgen dafür, dass ein Stick eine Maus vertreten kann.

2.16.1. joyMouseEnable

joyMouseEnable(enabled)

Hypseus-Erweiterung. Schaltet Joystick-als-Maus ein oder aus, während das Spiel läuft. Ist es eingeschaltet, steuert der linke Stick des Gamepad-Slots 0 den Zeiger, den das Spiel sieht, über dasselbe onMouseMoved, das auch eine echte Maus erreicht, und bleibt dabei innerhalb des Bildes; --js_range ist die Geschwindigkeit, und die Achse folgt ihrer eigenen Totzone. Das macht ein Lightgun-Spiel an einem Automaten mit Stick und ohne Maus spielbar.

Es startet mit --joymouse, das standardmäßig aus ist, und ein singeReload setzt es dorthin zurück. In diesem Standard weicht Singe von Hypseus ab: Die mitgelieferte controls.cfg legt diesen Stick bereits auf die vier Richtungsschalter, und wenn er ungefragt auch noch den Cursor steuerte, würde das jedes vorhandene Spiel überraschen.

Parameter:

  • enabled — Boolean.

Rückgabe: nichts.

Seit: 3.00 (Hypseus) Siehe auch: joyMouseIsEnabled, onMouseMoved, mouseGetPosition

Beispiel
-- Ein Schießspiel, das den Spieler mit dem Stick zielen lässt, wenn keine Maus angeschlossen ist.
if mouseHowMany() == 0 then
    joyMouseEnable(true)
end

2.16.2. joyMouseIsEnabled

enabled = joyMouseIsEnabled()

Ob der Stick gerade den Mauscursor steuert, gleich ob das durch --joymouse oder durch joyMouseEnable entschieden wurde.

Rückgabe: Boolean.

Seit: 3.00 Siehe auch: joyMouseEnable

2.17. Tastatur

Singe liest die Tastatur in einem von zwei Modi, die mit keyboardSetMode gewählt werden. Im MODE_NORMAL (der Standard) werden Tasten über die Belegungen in controls.cfg in die SWITCH_*-Werte übersetzt, die onInputPressed und onInputReleased erreichen, und nicht belegte Tasten werden ignoriert; im MODE_FULL erreicht jede Taste das Skript roh, über onKeyPressed und onKeyReleased sowie über onInputPressed und onInputReleased. Unabhängig vom Modus fragen keyboardIsDown, keyboardGetLastDown und keyboardGetLastUp den aktuellen Tastaturzustand ab, und genau das will das Thread-Modell (siehe Thread-Modell). Ein Scancode bezeichnet eine physische Tastenposition (die Taste A ist auf jedem Layout Scancode 4), ein Keysym dagegen das Zeichen, das die Taste erzeugt; die Tabelle SCANCODE in Framework.singe benennt jeden Scancode, keyboardIsDown nimmt Scancodes entgegen, und onKeyPressed liefert beides. Die Callbacks selbst sind unter Engine-Callbacks beschrieben.

2.17.1. keyboardCatchQuit

keyboardCatchQuit(catch)

Hypseus-Erweiterung. Übergibt den Beenden-Schalter an das Skript, genau wie singeSetQuitKeyEnabled(not catch): keyboardCatchQuit(true) verhindert, dass die Engine bei INPUT_QUIT beendet wird, und false stellt das wieder her. Es ist eine in Framework.singe definierte Funktion, die erhalten bleibt, damit für Hypseus Singe geschriebene Spiele unverändert laufen.

Hinweise: Veralteter Alias.

Neuer Code sollte singeSetQuitKeyEnabled aufrufen.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: singeSetQuitKeyEnabled, singeQuit

Beispiel
-- Hypseus-Spielcode; die moderne Schreibweise ist 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()

Gibt den Scancode der Taste zurück, die im aktuellen Frame zuletzt gedrückt wurde, oder 0, wenn seit dem letzten Frame nichts gedrückt wurde. Der Wert wird nach jedem Aufruf von onOverlayUpdate gelöscht, was ihn zu einer einmaligen Abfrage „wurde gerade eine Taste gedrückt“ für das Thread-Modell macht. Controller- und Maustasten werden hier ebenfalls festgehalten, als ihre Codes GAMEPAD_N und MOUSE_N, da die Engine sie über denselben Weg leitet wie Tasten. Der Wert wird unabhängig vom Tastaturmodus und von den Belegungen in controls.cfg festgehalten.

Rückgabe: ganzzahliger Scancode oder 0.

Seit: 2.10 Siehe auch: keyboardGetLastUp, keyboardIsDown

Beispiel
-- Thread-Modell: auf einen Tastendruck pro Frame reagieren.
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()

Gibt den Scancode der Taste zurück, die im aktuellen Frame zuletzt losgelassen wurde, oder 0, wenn seit dem letzten Frame nichts losgelassen wurde. Er wird wie bei keyboardGetLastDown nach jedem Aufruf von onOverlayUpdate gelöscht und hält Controller- und Maustastencodes auf dieselbe Weise fest.

Rückgabe: ganzzahliger Scancode oder 0.

Seit: 2.10 Siehe auch: keyboardGetLastDown, keyboardIsDown

Beispiel
-- Ein aufgeladener Schuss feuert, wenn die Feuertaste losgelassen wird.
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()

Gibt den geltenden Tastaturmodus zurück: MODE_NORMAL (0) oder MODE_FULL (1). Jedes Skript beginnt im MODE_NORMAL, auch nach einem Neuladen.

Rückgabe: ganzzahliger Modus.

Seit: 1.x (RDG) Siehe auch: keyboardSetMode

Beispiel
-- Gemeinsame Hilfsfunktion für Texteingabe, die den Modus wiederherstellt, den der Aufrufer gerade hatte.
function promptForName()
    local previous = keyboardGetMode()
    keyboardSetMode(MODE_FULL)
    entering = true
    restoreMode = previous
end

2.17.5. keyboardGetModifiers

modifiers = keyboardGetModifiers()

Gibt die gerade gehaltenen Modifikatortasten als Bitmaske aus SDL-KMOD_*-Bits zurück. Prüfe sie mit einem bitweisen Und gegen die Werte in der Tabelle MODIFIER: die Einträge für einzelne Tasten wie MODIFIER.LSHIFT und die zusammengefassten MODIFIER.SHIFT, MODIFIER.CTRL, MODIFIER.ALT und MODIFIER.GUI, die beide Seiten abdecken. Es liest den aktuellen Zustand, funktioniert also in jedem Tastaturmodus und aus jedem Callback.

Rückgabe: ganzzahlige Bitmaske.

Seit: 2.10 Siehe auch: keyboardGetLastDown, onKeyPressed

Beispiel
-- Umschalt+Tab blendet das Statistik-Overlay ein und aus.
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)

Prüft, ob eine Taste gerade physisch gehalten wird, anhand des Zustands, den die Engine für jedes Tastenereignis führt, das sie sieht. Es hängt weder vom Tastaturmodus noch von controls.cfg ab und funktioniert aus jedem Callback, eignet sich also für Bewegung, die weitergehen soll, solange eine Taste gehalten wird. Scancodes außerhalb des Bereichs, den SDL definiert, ergeben false, statt abzubrechen.

Parameter:

  • scancode — ein Wert aus der Tabelle SCANCODE, etwa SCANCODE.LEFT.value.

Rückgabe: Boolean.

Seit: 2.10 Siehe auch: keyboardGetLastDown, controllerGetButton

Beispiel
-- Bewegung in acht Richtungen aus gehaltenen Tasten.
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)

Wechselt zwischen den beiden Tastaturmodellen. Im MODE_NORMAL erreichen nur in controls.cfg belegte Tasten das Skript, als SWITCH_*-Werte, die Tastenwiederholung wird verworfen, sodass jeder Druck einmal ankommt, und die Engine reagiert auf ihre eigenen Schalter (Pause, Beenden, Screenshot, Maus einfangen). Im MODE_FULL erreicht jede Taste onInputPressed und onInputReleased als ihr Keysym und onKeyPressed und onKeyReleased als Keysym und Scancode, der Text, den ein Tastendruck erzeugt, erreicht onTextInput, die Tastenwiederholung wird für die Texteingabe geliefert, und Tastaturbelegungen der engineeigenen Schalter werden ignoriert, damit das Spiel jede Taste behält; Belegungen von Controller- und Maustasten wirken weiterhin, und diese Tasten erreichen das Skript weiterhin als ihre SWITCH_*-Werte, da sie nicht getippt werden können. Die meisten Spiele setzen den Modus einmal beim Start; ein Spiel mit Texteingabe wechselt für deren Dauer zu MODE_FULL und wieder zurück. Jeder andere Wert bricht das Skript ab. Im MODE_FULL sind die Keysyms von vier Tasten zugleich Schalternummern — Rücktaste ist 8 (SWITCH_BUTTON3), Tab 9 (SWITCH_COIN1), Eingabetaste 13 und Esc 27 — und ein Skript, das onInputPressed für einen Pad- oder Mausschalter liest und zugleich diese Tasten erwartet, sollte deshalb mit keyboardIsDown nach der Taste sehen, bevor es den Wert als den Schalter behandelt.

Parameter:

  • mode — MODE_NORMAL (0) oder MODE_FULL (1).

Seit: 1.x (RDG) Siehe auch: keyboardGetMode, onInputPressed, onKeyPressed

Beispiel
-- Die Highscore-Eingabe nimmt rohe Tasten, danach kehrt der Spielmodus zurück.
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. Licht

Lichter sind Knoten, die ein Licht tragen, von lightNew erzeugt und mit den Knotenaufrufen bewegt, verknüpft und animiert. Bis zu acht sichtbare Lichter leuchten in einem Frame, in Knotenreihenfolge; sceneSetAmbient und ein Himmel aus sceneSetSky fügen Licht aus allen Richtungen hinzu. Richtungs- und Spotlichter leuchten entlang der -Z-Achse des Knotens, richte sie also mit nodeLookAt oder nodeSetRotation aus; Punktlichter brauchen nur eine Position. Farben sind Ganzzahlen von 0 bis 255, Intensitäten sind Faktoren im linearen Licht der Szene, Winkel sind in Grad und Abstände in Welteinheiten. Jeder lightSet*-Aufruf beendet das Skript bei einem Knoten, der kein Licht trägt. Siehe 3D-Szenen zu Beleuchtung, Belichtung und Schatten.

2.18.1. lightNew

node = lightNew(type)
node = lightNew(type, parent)

Erzeugt einen neuen Knoten, der ein Licht trägt, und gibt das Knoten-Handle zurück. Das Licht beginnt weiß mit Intensität 1, ohne Reichweitenbegrenzung und, bei einem Spot, mit einem Kegel von 20 bis 30 Grad. Platziere und richte es mit den Knotenaufrufen aus: nodeSetPosition für ein Punkt- oder Spotlicht, nodeLookAt für ein Richtungs- oder Spotlicht. Ein Licht, das einem sich bewegenden Knoten untergeordnet ist, bewegt sich mit ihm, sodass ein Scheinwerfer an einem Auto oder eine Fackel in einer Hand nur ein Aufruf ist. Beendet das Skript bei einem unbekannten Typ oder wenn kein Knoten erzeugt werden kann.

Parameter:

  • type — LIGHT_DIRECTIONAL (eine Sonne; nur ihre Richtung zählt), LIGHT_POINT (eine Glühbirne, die mit der Entfernung in alle Richtungen schwächer wird) oder LIGHT_SPOT (ein Kegel entlang der -Z-Achse des Knotens).

  • parent — der Elternknoten; die Wurzel, wenn er weggelassen wird.

Rückgabe: Das Knoten-Handle des Lichts, eine Ganzzahl.

Beispiel
-- Warmes Führungslicht von links oben, ein kühles Aufhelllicht von rechts
-- und ein Scheinwerfer, der mit dem Auto mitfährt.
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)

Die Farbe des Lichts, 0 bis 255 pro Kanal (Werte außerhalb des Bereichs werden begrenzt), als sRGB behandelt; standardmäßig weiß. Die Helligkeit gehört in lightSetIntensity, nutze die Farbe also für den Farbton (eine warme Glühbirne 255, 230, 190, ein kühler Mond 150, 190, 255) und lass mindestens einen Kanal nahe 255. Beendet das Skript, wenn der Knoten kein Licht trägt.

Seit: 3.00. Siehe auch: lightSetIntensity, lightNew

Beispiel
-- Die Leuchtreklame wechselt durch ihre Farben.
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)

Die Form des Kegels eines Spotlichts, beide Winkel von der Achse aus gemessen (der -Z-Achse des Knotens): volle Helligkeit innerhalb von innerDegrees, die bis outerDegrees sanft auf nichts abfällt. Die Standardwerte sind 20 und 30. Ein schmaler Abstand zwischen beiden ergibt einen hart umrandeten Bühnenspot, ein breiter einen weichen Lichtfleck. Die Werte werden für jedes Licht gespeichert, aber nur ein LIGHT_SPOT verwendet sie. Beendet das Skript, wenn der Knoten kein Licht trägt.

Parameter:

  • node — der Knoten des Lichts.

  • innerDegrees — halber Winkel der vollen Helligkeit, in Grad von der Achse.

  • outerDegrees — halber Winkel, bei dem das Licht nichts mehr erreicht, in Grad von der Achse; wird auf innerDegrees angehoben, wenn er kleiner ist.

Seit: 3.00. Siehe auch: lightNew, lightSetRange, nodeLookAt

Beispiel
-- Ein hart umrandeter Bühnenspot aus dem Lichtrigg auf den Sänger.
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)

Der Helligkeitsfaktor des Lichts im linearen Licht der Szene, standardmäßig 1. Ein Richtungslicht der Intensität 1 beleuchtet eine ihm zugewandte weiße Fläche bis zu Weiß. Ein Punkt- oder Spotlicht fällt mit der Entfernung als 1 / (1 + d^2) ab, seine Intensität ist also die Helligkeit am Licht selbst, die Hälfte davon eine Einheit entfernt und ein Hundertstel zehn Einheiten entfernt; Glühbirnen brauchen meist Werte deutlich über 1, 10 bis 50 für einen Raum, und sceneSetExposure holt die ganze Szene wieder in den Bereich. Beendet das Skript, wenn der Knoten kein Licht trägt.

Seit: 3.00. Siehe auch: lightSetRange, sceneSetExposure, lightSetColor

Beispiel
-- Eine Laterne, die im Wind flackert.
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)

Wie weit ein Punkt- oder Spotlicht reicht, in Welteinheiten; 0 (der Standard) bedeutet keine Begrenzung. Das Licht fällt an der Reichweite zusätzlich zu seinem Abfall mit der Entfernung auf genau nichts ab, sodass Lichter nicht aufploppen, wenn Objekte sie überqueren. Eine Reichweite begrenzt auch, wie weit die Shadow Map eines schattenwerfenden Lichts reichen muss, was seine Schatten scharf hält. Richtungslichter ignorieren sie. Beendet das Skript, wenn der Knoten kein Licht trägt.

Seit: 3.00. Siehe auch: lightSetIntensity, lightSetShadow

Beispiel
-- Straßenlaternen die Straße entlang, jede beleuchtet ihr eigenes Stück.
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)

Lässt das Licht Schatten von allem Opaken in der Szene werfen oder beendet das; standardmäßig aus. Jedes der acht Lichter darf Schatten werfen, in beliebiger Kombination. Ein Spotlicht erhält eine Shadow Map; ein Richtungslicht erhält eine Map pro Kaskade (sceneSetShadowCascades); ein Punktlicht erhält eine Cube Map aus sechs Ansichten, die jede Richtung abdeckt (eine Glühbirne in einem Raum), zum sechsfachen Preis. nodeSetShadow befreit ein Mesh vom Schattenwerfen. Beendet das Skript, wenn der Knoten kein Licht trägt.

Hinweise: Jede Shadow Map kostet pro Frame einen zusätzlichen Durchgang über die Szene, eine Cube Map sechs und eine kaskadierte Sonne so viele, wie sie Kaskaden hat; die Größe der Maps wird mit sceneSetShadowSize gesetzt. Eine moderne integrierte GPU schafft acht Schattenwerfer bequem; ein Raspberry Pi will einen oder zwei bei 512.

Beispiel
-- Die Sonne wirft Schatten; die Lampen leuchten nur.  Das Glas der Glühbirne
-- darf seine eigene Lampe nicht verschatten.
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. Material

Ein Material bestimmt, wie ein Mesh aussieht: eine Grundfarbe mit Alpha, eine optionale Grundtextur aus einem Sprite, einer KTX2-Datei, einem Video oder einer gerenderten Ansicht, und die Metallic-Roughness-Parameter von glTF mit vier optionalen Maps. materialNew gibt ein ganzzahliges Handle zurück; übergib es an nodeSetMesh oder nodeSetMaterial und an jeden materialSet*-Aufruf. Materialien werden gemeinsam genutzt, eine Änderung an einem ändert also jedes Mesh, das damit gezeichnet wird, und ein Knoten ohne Material wird weiß und halb rau gezeichnet. Farben sind Ganzzahlen von 0 bis 255 pro Kanal und werden als sRGB behandelt; Faktoren wie die Rauheit reichen von 0 bis 1. Ein ungültiges Handle beendet das Skript. Siehe 3D-Szenen dazu, wie Materialien beleuchtet werden.

2.19.1. materialNew

material = materialNew()

Legt ein neues Material an und gibt sein Handle zurück. Es beginnt weiß und deckend (Farbe 255, 255, 255, 255), mit Rauheit 0.5, Metallic 0, ohne Emissionsfarbe, mit Kachelung 1, 1, linearer Filterung, einseitig, beleuchtet und ohne Textur oder Maps. Setz, was davon abweicht, und übergib das Handle an nodeSetMesh. Geladene Modelle bringen ihre eigenen Materialien mit, dies ist also für Meshes, die im Skript gebaut werden. Beendet das Skript auf einem Rechner ohne nutzbare GPU.

Rückgabe: Das Material-Handle, eine Ganzzahl.

Beispiel
-- Gebürstetes Gold für einen Pokal, durchscheinendes blaues Glas für seine 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)

Gibt das Material und jede Textur frei, die es hochgeladen hat. Jeder Knoten, der damit gezeichnet wurde, fällt auf das Standardaussehen zurück (weiß, halb rau); weise diesen Knoten also zuerst mit nodeSetMaterial ein anderes zu, wenn sie ein Aussehen behalten sollen. Das Handle ist danach ungültig und beendet das Skript, wenn es erneut verwendet wird. Das private Material, das ein Knoten unter nodeSetSprite oder nodeSetText für sich selbst anlegt, gehört dem Knoten und kann nicht gelöscht werden; der Aufruf beendet das Skript, und es wird freigegeben, wenn das Sprite oder der Text entfernt wird. Materialien sind billig; sie zu löschen ist vor allem bei solchen wichtig, die große Texturen trugen.

Seit: 3.00. Siehe auch: materialNew, nodeSetMaterial

Beispiel
-- Das Aussehen des Bodens im Level austauschen, wenn die Jahreszeit wechselt.
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)

Bei true wird das Material durchscheinend gezeichnet, gemischt nach dem Alpha der Grundfarbe multipliziert mit dem Alpha der Textur, nach jedem deckenden Mesh und vom entferntesten an sortiert. Gemischte Meshes schreiben keine Tiefe, lass es also für feste Oberflächen auf false (der Standard): Bei einem deckenden Mesh mit eingeschaltetem Mischen können Dinge dahinter durchscheinen. Verwende es mit einem Alpha unter 255 aus materialSetColor oder einer Textur mit Transparenz.

Seit: 3.00. Siehe auch: materialSetColor, materialSetTexture

Beispiel
-- Ein Kraftfeld, das sichtbar wird, wenn es getroffen wird.
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)

Setzt die Grundfarbe, 0 bis 255 pro Kanal (Werte außerhalb des Bereichs werden begrenzt), wobei a standardmäßig 255 ist. Die Farbe wird als sRGB behandelt und in linearem Licht beleuchtet. Hat das Material eine Textur, ein Video oder eine Ansicht, wird diese mit der Farbe multipliziert, Weiß lässt das Bild also, wie es ist, und eine dunklere Farbe tönt es. Das Alpha wirkt nur mit materialSetBlend.

Parameter:

  • material — das Material-Handle.

  • r, g, b — Rot, Grün und Blau, 0 bis 255.

  • a — Deckkraft, 0 bis 255; 255, wenn weggelassen.

Beispiel
-- Teamfarben auf dem einen Auto-Mesh.
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)

Verwirft jedes Texel, dessen Alpha unter cutoff liegt, und zeichnet den Rest vollständig deckend, im beleuchteten Durchgang wie im Schattendurchgang, sodass eine Blätterkarte den Schatten ihrer Blätter wirft statt den ihres Quads. Das ist das Alpha-Masking von glTF: Anders als materialSetBlend braucht es keine Sortierung, aber ein Texel wird ganz behalten oder verworfen, nie überblendet. Der Schwellwert wird auf 0 bis 1 begrenzt, und 0, der Standard, schaltet das Masking ab. Ein aus glTF geladenes Modell kommt mit dem Schwellwert, den seine Datei einem MASK-Material gibt.

Parameter:

  • material — ganzzahliges Material-Handle.

  • cutoff — Zahl; das Alpha, 0 bis 1, das ein Texel braucht, um gezeichnet zu werden.

Beispiel
-- Ein Maschendrahtzaun:  ein einziges texturiertes Quad, die Löcher ausgeschnitten, beide Seiten gezeichnet.
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)

Zeichnet beide Seiten jedes Dreiecks, statt die Rückseite zu verwerfen. Nötig für offene Formen, die von hinten gesehen werden, etwa eine einzelne meshPlane, die von unten betrachtet wird, eine Flagge oder eine Blattkarte. Geschlossene Formen sehen so oder so gleich aus, lass es bei ihnen also auf false (der Standard): Ein doppelseitiges Material kostet Füllrate, und Schatten werden ebenfalls von beiden Seiten geworfen.

Seit: 3.00. Siehe auch: meshPlane, materialSetBlend

Beispiel
-- Ein Banner, das über der Straße hängt, von beiden Seiten lesbar.
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)

Das Licht, das die Oberfläche von sich aus abgibt, 0 bis 255 pro Kanal (Werte außerhalb des Bereichs werden begrenzt), zusätzlich zur Beleuchtung: Bildschirme, Glühbirnen, Neon, Instrumententafeln. Der Standard ist Schwarz, kein Leuchten. Es beleuchtet nichts anderes und wirft kein Licht; setz dafür einen Lichtknoten an dieselbe Stelle. Mit materialSetEmissiveMap gibt die Map an, wo auf der Oberfläche diese Farbe gilt. Emittierende Oberflächen, die hell genug sind, um die Schwelle von sceneSetBloom zu überschreiten, leuchten.

Hinweise: Ein unbeleuchtetes Material (materialSetUnlit) zeigt nur seine Grundfarbe; die Emissionsfarbe wird darauf ignoriert.

Beispiel
-- Eine Warnlampe, die rot pulsiert, wenn der Reaktor überhitzt.
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)

Eine Textur, die angibt, welche Teile der Oberfläche leuchten. Ihre Farbe wird mit der Farbe aus materialSetEmissive multipliziert, setz diese also ebenfalls: Weiß, um die eigenen Farben der Map zu verwenden, oder eine Tönung. Das Bild stammt aus einem geladenen Sprite (eine Kopie wird hochgeladen, das Sprite darf danach also entladen werden) oder aus einer .ktx2-Datei nach Namen, komprimiert auf der GPU gehalten. Mit nil oder ohne zweites Argument wird die Map entfernt. Beendet das Skript, wenn die Textur nicht hochgeladen werden kann oder die Datei keine KTX2-Textur ist.

Beispiel
-- Ein Bedienfeld, dessen Knöpfe und Anzeigen aufleuchten.
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)

Wie die Texturen des Materials abgetastet werden. FILTER_LINEAR (der Standard) mischt zwischen Texeln und zwischen Mipmap-Stufen, mit anisotroper Filterung auf Oberflächen, die unter flachem Winkel gesehen werden. FILTER_NEAREST nimmt das nächstgelegene Texel und die nächstgelegene Mipmap-Stufe, sodass Pixel-Art auf einem Quad scharf bleibt. Jede Textur trägt eine vollständige Mipmap-Kette, eine klein gesehene Textur flimmert also in keinem Fall. Jeder andere Wert beendet das Skript.

Seit: 3.00. Siehe auch: materialSetTexture, materialSetUnlit

Beispiel
-- Eine Kachel aus 16 mal 16 Pixeln, ohne Verschmieren auf einen Block gezeichnet.
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)

Zeigt eine GUI aus guiNew als Grundfarbtextur des Materials, in jedem Frame aktualisiert: ein Monitor, ein Cockpit-Bedienfeld, ein Schild, mit demselben Dokument, das ein guiDraw flach zeigen würde. Meist kombiniert mit materialSetUnlit, damit die Seite nicht von den Lichtern schattiert wird, und wie jede Textur von der Grundfarbe getönt. Mit nil oder ohne zweites Argument kehrt das Material zu seiner eigenen Textur zurück, die darunter erhalten bleibt; das Löschen der GUI bewirkt dasselbe. Das Setzen einer GUI verwirft jedes Video und jede Ansicht, die das Material zeigte. Solange die GUI Eingaben annimmt, erreichen die Maus oder eine Lightgun, die auf eine mit dem Material gezeichnete Oberfläche zeigt, sie über dieselbe Abtastung wie sceneProbeGui. Beendet das Skript bei einem ungültigen GUI-Handle.

Beispiel
-- Die Optionsseite auf dem Bildschirm des modellierten Automaten.
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)

Wie metallisch die Oberfläche ist, 0 für Nichtmetalle (Lack, Kunststoff, Holz, Haut) bis 1 für Metalle, die ihre Glanzlichter und Spiegelungen mit der Grundfarbe tönen. Der Standard ist 0. Werte dazwischen sind für Mischungen und abgenutzte Oberflächen; die meisten Materialien wollen das eine oder das andere Ende. Mit materialSetMetallicRoughnessMap multipliziert der Blaukanal der Map diesen Wert. Ein Metall hat ohne einen Himmel aus sceneSetSky wenig zu spiegeln, kombiniere also beides.

Beispiel
-- Verchromte Stoßstange, lackierte Karosserie.
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)

Eine Textur, die die Oberflächenbeschaffenheit über die Fläche variiert: Ihr Grünkanal multipliziert die Rauheit aus materialSetRoughness und ihr Blaukanal den Metallic-Wert aus materialSetMetallic, so wie glTF sie packt, eine Map aus einem glTF-Werkzeug funktioniert also unverändert. Setz beide Faktoren auf 1, um allein die Werte der Map zu verwenden. Das Bild stammt aus einem Sprite oder einer .ktx2-Datei nach Namen; nil oder kein zweites Argument entfernt die Map. Beendet das Skript, wenn die Textur nicht hochgeladen werden kann.

Beispiel
-- Zerkratzte Metallbeplankung:  glänzend, wo der Lack abgeschabt ist.
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)

Eine Normal Map im Tangentenraum (die übliche bläuliche Art, flach bei 128, 128, 255), die die Beleuchtung pro Texel neigt, sodass Ziegel, Rillen und Nieten ohne zusätzliche Geometrie das Licht einfangen. Jedes Mesh hat Tangenten dafür: die eigenen eines Modells, wenn die Datei sie enthält, sonst aus den UVs berechnet. Das Bild stammt aus einem Sprite oder einer .ktx2-Datei nach Namen; nil oder kein zweites Argument entfernt die Map. Beendet das Skript, wenn die Textur nicht hochgeladen werden kann.

Parameter:

  • material — das Material-Handle.

  • sprite oder "file.ktx2" — die Map, aus einem geladenen Sprite oder einer KTX2-Datei; nil oder weggelassen entfernt sie.

  • strength — wie stark die Unebenheiten die Beleuchtung neigen, 1 (der Standard) wie erstellt, 0 flach, über 1 übertrieben.

Beispiel
-- Eine Ziegelmauer aus einer flachen Ebene, deren Mörtelfugen die tiefe Sonne einfangen.
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)

Lässt das Material Tiefe und keine Farbe schreiben. Was das Mesh verdeckt, ist verborgen, als wäre das Mesh massiv, aber das Mesh selbst ist nicht zu sehen: Alles dahinter Gezeichnete — ein gemalter Hintergrund, die Disc — scheint durch. Es ist der Stellvertreter für etwas, das im Bild, aber nicht in der Szene ist: eine Säule in einem gemalten Raum, hinter der eine 3D-Figur hergehen muss, ein Türrahmen, ein Tisch. Ein Occluder wirft keinen Schatten, da das Gemälde schon einen hat, und nimmt kein Licht an. false (der Standard) macht das Material wieder gewöhnlich.

Seit: 3.00. Siehe auch: materialSetBlend, materialSetUnlit

Beispiel
-- Eine Säule, die im Gemälde ist:  eine unsichtbare Box, wo sie steht, damit
-- der Held dahinter verschwindet und auf der anderen Seite wieder auftaucht.
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)

Eine Ambient-Occlusion-Map, die Verdeckung im Rotkanal (Weiß für offen, dunkel für Spalten), die das Umgebungs- und Himmelslicht in Ecken und Falten abdunkelt. Direktes Licht von Lichtknoten ist davon nicht betroffen, wie in glTF. Das Bild stammt aus einem Sprite oder einer .ktx2-Datei nach Namen; nil oder kein zweites Argument entfernt die Map. Beendet das Skript, wenn die Textur nicht hochgeladen werden kann.

Parameter:

  • material — das Material-Handle.

  • sprite oder "file.ktx2" — die Map, aus einem geladenen Sprite oder einer KTX2-Datei; nil oder weggelassen entfernt sie.

  • strength — wie viel von der Map angewendet wird, von 0, gar nicht, bis 1 (der Standard), voll.

Beispiel
-- Vorberechnete Schattierung für die Höhlenwände, halbe Stärke, damit die Lampen die Ecken noch erreichen.
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)

Wie rau die Oberfläche ist, 0 für ein spiegelscharfes Glanzlicht bis 1 für matt. Der Standard ist 0.5. Glanzlichter folgen dem GGX-Modell, niedrige Werte ergeben also einen kleinen hellen Fleck und scharfe Himmelsspiegelungen, hohe Werte einen breiten weichen Schimmer und verschwommene Spiegelungen. Mit materialSetMetallicRoughnessMap multipliziert der Grünkanal der Map diesen Wert.

Beispiel
-- Die Straße wird nass, wenn es regnet:  derselbe Asphalt, schärfere Glanzlichter.
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)

Verwendet das Bild eines Sprites als Grundfarbtextur (eine Kopie wird hochgeladen, das Sprite darf danach also entladen werden) oder eine KTX2-Datei nach Namen, die auf der GPU im Blockformat komprimiert gehalten wird, das der Rechner hat (siehe Komprimierte Texturen unter 3D-Szenen). Mit nil oder ohne zweites Argument wird die Textur entfernt, und das Material zeigt nur seine Grundfarbe. Das Setzen einer Textur verwirft außerdem jedes Video und jede Ansicht, die das Material zeigte. Texturkoordinaten stammen aus dem Mesh; die Grundformen legen ein Bild einmal über jede Fläche, und materialSetTiling wiederholt es. Ein Name, der keine KTX2-Datei ist, beendet das Skript (lade andere Bilder mit spriteLoad), ebenso ein fehlgeschlagenes Hochladen.

Beispiel
-- Eine Kiste, texturiert mit einem Sprite, das das Spiel ohnehin für das Menü lädt,
-- und ein Boden aus einer komprimierten Textur, die mit dem Spiel ausgeliefert wird.
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)

Wie oft sich die Texturen des Materials (Grundtextur und Maps gleichermaßen) über den UV-Bereich 0 bis 1 einer Oberfläche wiederholen, standardmäßig 1 und 1. 24, 24 auf einer 120 Einheiten breiten Heightmap kachelt eine Textur alle fünf Einheiten. Texturen wiederholen sich über ihre Ränder hinaus, das Bild muss also nahtlos kacheln. Werte unter 1 zeigen einen Teil des Bildes; negative Werte spiegeln es.

Parameter:

  • material — das Material-Handle.

  • u — Wiederholungen in U-Richtung der Oberfläche.

  • v — Wiederholungen in V-Richtung der Oberfläche.

Seit: 3.00. Siehe auch: materialSetTexture, meshHeightmap

Beispiel
-- Gras alle fünf Einheiten über die Hügel.
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)

Zeigt die Grundfarbe und die Textur genau so, wie sie sind, und ignoriert jedes Licht, das Umgebungslicht und den Himmel: für Videobildschirme, Monitore, die eine Ansicht zeigen, Skyboxen und flach schattierte Looks. Nebel wirkt weiterhin. Die Emissionsfarbe und die Maps werden bei einem unbeleuchteten Material nicht verwendet. Der Standard ist false.

Beispiel
-- Das Marquee des Arcade-Automaten:  ein Bild, das von innen beleuchtet ist,
-- die Lichter des Raums sollen es also nicht schattieren.
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)

Zeigt eine gerenderte Ansicht aus viewNew als Grundfarbtextur des Materials, in jedem Frame aktualisiert: ein Überwachungsmonitor, ein Rückspiegel, ein Portal. Meist kombiniert mit materialSetUnlit, damit das Bild nicht von den Lichtern schattiert wird, und wie jede Textur von der Grundfarbe getönt. Mit nil oder ohne zweites Argument kehrt das Material zu seiner eigenen Textur zurück, die darunter erhalten bleibt. Das Setzen einer Ansicht verwirft jedes Video, das das Material zeigte. Beendet das Skript bei einem ungültigen Ansichts-Handle.

Beispiel
-- Ein Rückspiegel am Auto des Spielers.
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)

Verwendet die Laserdisc (ohne video) oder ein mit videoLoad geladenes Video als Grundfarbtextur, in jedem Frame aktualisiert, solange es läuft. Meist kombiniert mit materialSetUnlit, damit das Bild nicht von den Lichtern getönt wird. Das Video läuft weiter, ob es zusätzlich auf dem Overlay gezeichnet wird oder nicht, und mehrere Materialien dürfen dasselbe zeigen. Das Setzen eines Videos verwirft jede Textur und jede Ansicht, die das Material hatte; materialSetTexture entfernt es wieder.

Hinweise: Die Disc-Form beendet das Skript in einem Spiel ohne Disc, ebenso ein ungültiges Video-Handle.

Seit: 3.00. Siehe auch: videoLoad, materialSetUnlit, materialSetTexture

Beispiel
-- Ein modellierter Automat, dessen Bildschirm die Laserdisc zeigt, und eine Wand aus
-- Monitoren, die einen Attract-Clip in Schleife abspielen.
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. Mesh

Ein Mesh ist Geometrie auf der GPU: eine Grundform, die die Engine baut, ein Gelände aus einem Bild oder Vertexdaten aus deinem Skript. Handles sind Ganzzahlen, die von den mesh*-Konstruktoren zurückgegeben werden; beliebig viele Knoten können sich ein Mesh teilen, und Knoten, die dasselbe Mesh mit demselben Material zeichnen, werden als ein instanzierter Aufruf gezeichnet, erzeuge also ein Mesh und viele Knoten. Größen sind in Szeneneinheiten, und jede Grundform ist auf den Ursprung ihres Knotens zentriert, sofern nicht anders angegeben, sodass die Transformation des Knotens sie platziert, dreht und skaliert. Texturkoordinaten laufen einmal über jede Fläche oder Oberfläche von 0 bis 1. Jeder Konstruktor braucht den unter 3D-Szenen beschriebenen 3D-Renderer und bricht das Skript ab, wenn dieser nicht verfügbar ist.

2.20.1. meshBox

mesh = meshBox(width, height, depth)

Ein Quader, width entlang X, height entlang Y und depth entlang Z, auf den Ursprung zentriert. Jede der sechs Flächen hat ihre eigenen vier Vertices mit einer flachen Normale, sodass Kanten scharf schattiert werden, und die Textur wird einmal über jede Fläche gelegt. Kisten, Wände, Böden und Autokarosserien sind allesamt Quader.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: nodeSetMesh, meshPlane, bodyNew

Beispiel
-- Eine steinerne Bodenplatte und ein Stapel Kisten, die sich ein Mesh teilen.
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)

Ein auf Y stehender Kegel mit geschlossener Grundfläche: der Grundkreis mit radius bei -height / 2 und die Spitze bei +height / 2. segments (Standard 24, mindestens 3) gibt an, wie viele Facetten ihn umlaufen; die Seiten werden über sie hinweg weich schattiert. Die Textur legt sich einmal um die Seiten und einmal über die Grundfläche. Über 1024 wird segments als 1024 genommen.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: meshCylinder, nodeSetMesh

Beispiel
-- Ein Lampenschirm über der Glühbirne und eine Reihe Kiefern aus je einem Kegel.
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)

Ein Zylinder entlang Y, an beiden Enden geschlossen, von -height / 2 bis +height / 2. segments (Standard 24, mindestens 3) gibt an, wie viele Facetten ihn umlaufen, weich schattiert. Für ein Rad oder eine Münze dreh den Knoten um 90 Grad um X oder Z, sodass die Achse dort liegt, wo du sie brauchst. Über 1024 wird segments als 1024 genommen.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: meshCone, meshTorus, nodeSetRotation

Beispiel
-- Ein Laternenpfahl und ein auf die Seite gelegter Reifen als Rad.
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)

Gibt die GPU-Puffer des Meshs und seine CPU-Kopie frei. Knoten, die es verwendet haben, bleiben ohne Mesh (und ohne Morph-Gewichte) zurück und zeichnen nichts, bis sie ein anderes erhalten; das Handle wird ungültig und kann von einem späteren Konstruktor wiederverwendet werden. Meshes werden nicht freigegeben, wenn ein Knoten gelöscht wird, lösch ein Mesh also selbst, wenn nichts es mehr verwenden wird.

Seit: 3.00. Siehe auch: meshNew, nodeSetMesh, nodeDelete

Beispiel
-- Die Strecke zwischen den Runden aus einer neuen Heightmap neu bauen.
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)

Ein Geländemesh aus einem Graustufenbild, 2 bis 1025 Pixel in jede Richtung: ein Vertex pro Pixel über sizeX mal sizeZ Einheiten, auf den Knoten zentriert, jeder angehoben um den Rotkanal des Pixels (0 Schwarz bis 255 Weiß) mal sizeY, wobei die oberste Zeile des Bildes am fernen (-Z-)Rand liegt. Normalen werden aus den Steigungen berechnet, und die Texturkoordinaten laufen über das Ganze von 0 bis 1, sodass materialSetTiling die Wiederholung der Textur festlegt. Die Höhenwerte werden behalten: terrainGetHeight liest sie, und ein SHAPE_MESH-Körper auf dem Knoten wird zu einem Höhenfeld. Eine Datei, die sich nicht öffnen oder dekodieren lässt, die falsche Größe oder kein 3D-Renderer bricht das Skript ab.

Parameter:

  • image — der spielrelative Name des Bildes, in jedem Format, das spriteLoad liest.

  • sizeX — die Breite des Geländes entlang X in Welteinheiten.

  • sizeY — die Höhe eines weißen Pixels über einem schwarzen.

  • sizeZ — die Tiefe des Geländes entlang Z in Welteinheiten.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: terrainGetHeight, materialSetTiling, bodyNew

Beispiel
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)
-- Die Füße des Drachen auf dem Hang, wo immer der Boden dort ist.
nodeSetPosition(dragon, -8, terrainGetHeight(hills, -8, 3) or 0, 3)

2.20.6. meshNew

mesh = meshNew(positions, normals, uvs, indices)

Baut Geometrie aus Zahlentabellen. Tangenten für Normal Mapping werden für dich berechnet, und ebenso weiche Normalen, wenn normals nil ist, indem die Dreiecke gemittelt werden, die sich jeden Vertex teilen. Dreiecke zeigen nach vorn, wenn ihre Vertices von außen gesehen gegen den Uhrzeigersinn laufen; gib dem Material materialSetDoubleSided, wenn die Rückseite zu sehen sein muss. Eine Tabelle der falschen Form oder ein Index außerhalb der Vertexliste bricht das Skript mit einer Meldung ab, die sagt, was davon.

Parameter:

  • positions — x, y, z für jeden Vertex, einer nach dem anderen; mindestens ein Vertex.

  • normals — x, y, z pro Vertex, gleich viele wie in positions, oder nil, um sie berechnen zu lassen.

  • uvs — u, v pro Vertex (0 bis 1, v im Bild nach unten) oder nil für keine (jeder Vertex bei 0, 0).

  • indices — drei Vertexnummern pro Dreieck, ab 1 gezählt in der Reihenfolge, in der die Vertices in positions stehen; mindestens ein Dreieck.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: nodeSetMesh, materialSetDoubleSided, meshDelete

Beispiel
-- Ein flacher Pfeil entlang +X, von oben gesehen (doppelseitig, damit er auch von unten funktioniert).
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)

Ein flaches Rechteck in der XZ-Ebene, nach +Y gewandt, width entlang X und depth entlang Z, auf den Ursprung zentriert, mit der Textur einmal darüber gelegt. Zwei Argumente ergeben ein einzelnes Quad. columns (und rows, das standardmäßig columns ist) unterteilen es in so viele Quads in jede Richtung, was ein Soft Body (softNew) braucht, um sich wie Stoff zu biegen; beide müssen mindestens 1 sein. Dreh den Knoten um 90 Grad um X, um es nach +Z gewandt aufzurichten. Es ist einseitig, sofern sein Material nicht doppelseitig ist.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: materialSetDoubleSided, materialSetVideo, softNew

Beispiel
-- Der Boden, ein Bildschirm, der die Disc zeigt, und eine Flagge, die zu Stoff werden soll.
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)

Eine Kugel mit radius, auf den Ursprung zentriert, aus Breiten- und Längenbändern gebaut: segments (Standard 32, mindestens 3) um den Äquator und halb so viele von Pol zu Pol. Die Textur legt sich einmal um sie herum, v vom oberen Pol zum unteren. Weniger Segmente ergeben ein leichteres Mesh für Bälle, die aus der Ferne gesehen werden; mehr ergeben aus der Nähe eine glattere Silhouette. Über 1024 wird segments als 1024 genommen.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: meshTorus, nodeSetMesh, bodyNew

Beispiel
-- Eine Glaskugel auf dem Boden und eine kleine Markierungskugel, die ein Aussehen teilt.
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)

Ein Ring, der in der XZ-Ebene um Y liegt, auf den Ursprung zentriert: radius vom Mittelpunkt bis zur Mitte des Rohrs und tubeRadius der eigene Radius des Rohrs. segments (Standard 32, mindestens 3) laufen um den Ring und halb so viele (mindestens 3) um das Rohr. Die Textur legt sich in u einmal um den Ring und in v einmal um das Rohr. Über 1024 wird segments als 1024 genommen.

Rückgabe: Das Mesh-Handle.

Seit: 3.00. Siehe auch: meshSphere, meshCylinder

Beispiel
-- Ein goldener Ring, auf die Kante gestellt, damit der Ball hindurchrollen kann.
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. Mikrofon

Ein Mikrofon, für ein Gesangsspiel oder alles, was zuhört. Es ist immer nur ein Aufnahmegerät geöffnet, gehört als ein Kanal mit 48000 Samples pro Sekunde, gleich was die Hardware liefert; SDL wandelt um. Singe behält die neuesten acht Sekunden dessen, was es hört, und jeder Aufruf unten antwortet daraus, das Fragen kostet also nichts, was das Spiel nicht ohnehin schon bezahlt hat.

Was ein Spiel meist will, ist micPitch — der gesungene Ton — und micLevel. Ein Spiel, das den Klang selbst analysiert oder ihn irgendwohin schickt, liest die Samples mit micRead; die Stimme-Aufrufe kodieren sie für ein Netzwerk.

Das Mikrofon wird geschlossen, wenn das Spiel endet. Nichts wird geöffnet, bevor ein Skript danach fragt.

Ein gesungener Ton erreicht das Spiel ein wenig, nachdem er gesungen wurde: Die Soundkarte, der Treiber und die Puffer halten ihn jeweils einen Moment fest. Ein Gesangsspiel, das das Timing bewertet, zieht das ab. micCalibrate misst es, indem es Klicks über die Lautsprecher abspielt und misst, wann sie zurückkommen, und das Ergebnis wird für den Rechner behalten, wie die Audiokalibrierung. Mithören und Kalibrierung wurden bisher nur ohne echte Hardware getestet; Tonhöhe, Pegel, Lesen und Aufnehmen wurden mit einem bekannten Signal getestet.

2.21.1. micCalibrate

started = micCalibrate()

Misst die Latenz des Mikrofons: Spielt fünf Klicks über die Lautsprecher ab, im Abstand von Sekundenbruchteilen, und misst für jeden, wann er über das Mikrofon zurückkommt. Das dauert ein paar Sekunden; micCalibration sagt, wann es fertig ist. Das Ergebnis ist das des mittleren der gehörten Klicks und wird für diesen Rechner behalten. Mach es in einem ruhigen Raum, mit Lautsprechern, die laut genug sind, dass das Mikrofon sie hört.

Rückgabe: true, wenn die Messung gestartet wurde; false, wenn kein Mikrofon geöffnet ist oder kein Lautsprecher die Klicks abspielen kann.

Seit: 3.00. Siehe auch: micCalibration, micLatency

2.21.2. micCalibration

state, latency = micCalibration()

Wie eine Kalibrierung vorankommt.

Rückgabe: state, eines von "idle", "running", "done" oder "failed" (weniger als drei der Klicks wurden zurück gehört), und die Latenz in Millisekunden, sobald eine bekannt ist, sonst nil.

Seit: 3.00. Siehe auch: micCalibrate

Beispiel
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()

Hört auf zuzuhören und beendet damit auch jedes Aufnehmen und Mithören. Das Mikrofon wird auch geschlossen, wenn das Spiel endet.

Seit: 3.00.

2.21.4. micIsOpen

open = micIsOpen()

Rückgabe: true, solange ein Mikrofon geöffnet ist.

Seit: 3.00.

2.21.5. micLatency

milliseconds = micLatency()

Rückgabe: die Zeit zwischen dem Entstehen eines Klangs und dem Moment, in dem das Spiel ihn hört, wie auf diesem Rechner von micCalibrate gemessen (zu einem beliebigen Zeitpunkt, in einem beliebigen Spiel) oder von micSetLatency gesetzt; bis dahin nil.

Seit: 3.00.

2.21.6. micLevel

rms, peak = micLevel()

Wie laut der zuletzt gehörte Moment war.

Rückgabe: der RMS- und der Spitzenwert des letzten Sample-Blocks, jeweils 0 bis 1. Ein gleichmäßiger Ton bei Vollaussteuerung ergibt etwa 0.71 RMS. Beide sind 0, wenn kein Mikrofon geöffnet ist.

Seit: 3.00.

2.21.7. micList

names = micList()

Rückgabe: eine Liste der Namen der Mikrofone, die dieser Rechner hat, für micOpen. Sie wird jedes Mal neu erstellt, sodass ein seit dem letzten Aufruf angeschlossenes Mikrofon erscheint.

Seit: 3.00.

2.21.8. micMonitor

ok = micMonitor(on [, volume])

Spielt das, was das Mikrofon hört, über die Lautsprecher zurück, sodass sich ein Sänger über der Musik selbst hört. Aus, bis es verlangt wird: Auf den meisten Geräten kommt die Stimme so spät zurück, dass es irritiert, und bei einem Laptop speisen die Lautsprecher das Mikrofon. Alles, was länger als eine Zehntelsekunde auf die Wiedergabe wartet, wird verworfen, statt verspätet gehört zu werden.

Parameter:

  • on — Boolean.

  • volume — Zahl, 0 bis 1; 1, sofern nicht angegeben.

Rückgabe: true oder false, wenn kein Mikrofon geöffnet ist oder kein Lautsprecher zum Abspielen da ist.

Seit: 3.00.

2.21.9. micOpen

opened = micOpen([name])

Beginnt zuzuhören, und zwar dem genannten Mikrofon (aus micList) oder dem Standardmikrofon des Rechners. Ein bereits geöffnetes Mikrofon wird zuerst geschlossen.

Rückgabe: true, wenn es geöffnet wurde.

Seit: 3.00.

Beispiel
if not micOpen() then
	message = "No microphone.  This game needs one."
end

2.21.10. micPitch

hz, clarity = micPitch()

Der gesungene Ton, ermittelt aus den neuesten 43 Millisekunden, die gehört wurden. Es findet einen Grundton zwischen 50 und 2000 Hz, was jede Singstimme abdeckt, und trifft bei einem sauberen Ton auf ein, zwei Hertz genau.

Rückgabe: der Grundton in Hz und wie eindeutig der Klang ein einzelner Ton ist, 0 bis 1. Bei nichts Stimmhaftem — Stille, einem Atemzug, einem Husten, einer Menschenmenge — ist hz gleich 0. Wandle Hz mit 69 + 12 * math.log(hz / 440, 2) in eine Notennummer um: 69 ist das A über dem mittleren C, und jede 1 ist ein Halbton.

Seit: 3.00.

Beispiel
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          -- Halbtöne zu hoch (positiv) oder zu tief
	if math.abs(off) < 0.5 then
		score = score + 1
	end
end

2.21.11. micRead

samples = micRead([max])

Was seit dem letzten Aufruf gehört wurde, das Älteste zuerst.

Parameter:

  • max — Zahl, die größte Anzahl zurückzugebender Samples; alles Wartende, sofern nicht angegeben.

Rückgabe: ein String aus 16-Bit-Samples, je zwei Bytes, Little Endian, ein Kanal mit 48000 pro Sekunde: #samples / 2 davon. Lies eines mit string.unpack("<i2", samples, n * 2 - 1). Ein Spiel, das länger als acht Sekunden nicht liest, verliert die ältesten.

Seit: 3.00.

2.21.12. micRecordStart

started = micRecordStart(name)

Schreibt alles, was von jetzt an gehört wird, in eine WAV-Datei (ein Kanal, 16 Bit, 48000 pro Sekunde) bis micRecordStop. Der Name ist eine beliebige Datei, die das Spiel schreiben darf, und landet dort, wo die anderen geschriebenen Dateien des Spiels landen.

Rückgabe: true, wenn die Datei geöffnet wurde.

Seit: 3.00.

2.21.13. micRecordStop

micRecordStop()

Beendet die Aufnahme.

Seit: 3.00.

2.21.14. micSetLatency

micSetLatency(milliseconds | nil)

Setzt die Mikrofonlatenz dieses Rechners, wie es ein Service-Menü anhand einer auf anderem Weg gemachten Messung tut; nil vergisst sie. Sie wird mit den anderen Einstellungen des Rechners gespeichert.

Parameter:

  • milliseconds — Zahl, 0 bis 1000, oder nil.

Seit: 3.00.

2.22. MIDI

Zwei Dinge, die nichts miteinander zu tun haben, teilen sich diesen Namen, und es lohnt sich, sie auseinanderzuhalten.

Eine MIDI-Datei ist Musik und wird wie jede andere Musik abgespielt: Gib .mid an musicLoad. Singe synthetisiert sie aus einem SoundFont, denn eine MIDI-Datei enthält Noten statt Klang. Singe liefert keinen SoundFont mit — ein guter ist Dutzende Megabyte groß, für ein Format, das fast kein Spiel nutzt — deshalb nenne einen mit --soundfont, leg einen unter Singe/soundfont.sf2 ab, damit ein gepacktes Spiel seinen eigenen mitbringt, oder lass Singe den finden, den deine Distribution installiert hat. Die Zeile SoundFont: im Kopf des Trace sagt, welcher verwendet wurde. Gibt es nirgends einen SoundFont, schlägt das Laden einer .mid fehl und sagt das.

MIDI-Ports sind die Aufrufe unten. Sie senden und empfangen Live-Nachrichten auf einem echten Port: ein Automat, der ein externes Klangmodul ansteuert, oder ein Keyboard, eine Faderbox oder eine Bedienoberfläche, die als weiteres Eingabegerät gelesen werden. Nichts hier synthetisiert etwas, und nichts hier rührt eine MIDI-Datei an.

Ports werden ab 0 nummeriert. Nichts wird geöffnet, bevor ein Skript zum ersten Mal fragt — ein MIDI-Port kostet einen Dateideskriptor und eine Runde Treiberkonfiguration, und ein Spiel, das MIDI nie erwähnt, bezahlt nie dafür — und so nimmt der erste dieser Aufrufe den Bestand des Rechners auf, und midiRescan sucht erneut nach einem seither angeschlossenen Gerät. Es dürfen gleichzeitig ein Eingabe- und ein Ausgabeport geöffnet sein. Kanäle sind 1 bis 16, so wie ein Mensch sie zählt, nicht 0 bis 15 wie auf der Leitung, und jeder andere Wert ist 0 bis 127. Auf einem Rechner ganz ohne MIDI — ohne Ports oder ohne installierte MIDI-Bibliothek — sind die Anzahlen 0, die Öffnen-Aufrufe antworten false, und die Sende-Aufrufe antworten false; nichts schlägt fehl.

Linux erreicht jeden Port über den ALSA-Sequencer, der sowohl die Hardware-Schnittstellen umfasst als auch jeden Synthesizer oder jedes andere Programm, das einen anmeldet. macOS verwendet CoreMIDI und Windows die Multimedia-MIDI-Aufrufe, wobei Ausgabegerät 0 meist der Synthesizer ist, den das System selbst mitbringt.

2.22.1. midiCloseInput

midiCloseInput()

Hört auf, dem Eingabeport zuzuhören. onMidiMessage wird nicht mehr ausgelöst. Einen Port zu schließen, der nicht geöffnet ist, bewirkt nichts.

Parameter:

  • Keine.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: midiOpenInput

2.22.2. midiCloseOutput

midiCloseOutput()

Gibt den Ausgabeport frei. Die Sende-Aufrufe antworten von nun an false. Einen Port zu schließen, der nicht geöffnet ist, bewirkt nichts.

Parameter:

  • Keine.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: midiOpenOutput

2.22.3. midiControlChange

sent = midiControlChange(channel, control, value)

Bewegt einen Controller auf dem geöffneten Ausgabeport: Lautstärke ist Controller 7, Panorama 10, das Haltepedal 64.

Parameter:

  • channel — Zahl; 1 bis 16.

  • control — Zahl; 0 bis 127.

  • value — Zahl; 0 bis 127.

Rückgabe: true, wenn die Nachricht hinausging.

Seit: 3.00. Siehe auch: midiSend

Beispiel
-- Die Lautstärke des Moduls absenken, während eine Figur spricht.
midiControlChange(1, 7, 40)

2.22.4. midiInputCount

count = midiInputCount()

Wie viele MIDI-Eingabeports dieser Rechner hat. 0, wenn es keine gibt oder die Plattform gar kein MIDI hat.

Parameter:

  • Keine.

Rückgabe: eine Zahl.

Seit: 3.00. Siehe auch: midiInputName

2.22.5. midiInputName

name = midiInputName(index)

Der Name eines Eingabeports, für einen Einstellungsbildschirm, auf dem ein Spieler einen auswählen kann.

Parameter:

  • index — Zahl; 0 bis midiInputCount() - 1.

Rückgabe: ein String oder nil, wenn der Index keinen Port bezeichnet.

Seit: 3.00. Siehe auch: midiInputCount

Beispiel
-- Ein Einstellungsbildschirm, der die Eingangsports auflistet, einen pro Zeile.
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()

Ob ein Eingabeport geöffnet ist.

Parameter:

  • Keine.

Rückgabe: true oder false.

Seit: 3.00. Siehe auch: midiOpenInput

2.22.7. midiIsOutputOpen

open = midiIsOutputOpen()

Ob ein Ausgabeport geöffnet ist. Es lohnt sich, vor einer Reihe von Nachrichten zu fragen, da sonst jede einzeln false antworten würde.

Parameter:

  • Keine.

Rückgabe: true oder false.

Seit: 3.00. Siehe auch: midiOpenOutput

2.22.8. midiNoteOff

sent = midiNoteOff(channel, key)

Lässt einen Ton auf dem geöffneten Ausgabeport los. Ein nicht beendeter Ton klingt, bis etwas ihn stoppt, deshalb braucht jedes midiNoteOn einen dieser Aufrufe.

Parameter:

  • channel — Zahl; 1 bis 16.

  • key — Zahl; 0 bis 127, wobei 60 das mittlere C ist.

Rückgabe: true, wenn die Nachricht hinausging.

Seit: 3.00. Siehe auch: midiNoteOn

2.22.9. midiNoteOn

sent = midiNoteOn(channel, key, velocity)

Lässt einen Ton auf dem geöffneten Ausgabeport erklingen.

Parameter:

  • channel — Zahl; 1 bis 16. Kanal 10 ist auf einem General-MIDI-Gerät Schlagzeug.

  • key — Zahl; 0 bis 127, wobei 60 das mittlere C ist.

  • velocity — Zahl; 0 bis 127, wie hart die Taste angeschlagen wurde.

Rückgabe: true, wenn die Nachricht hinausging.

Seit: 3.00. Siehe auch: midiNoteOff

Beispiel
-- Ein Stinger auf einem externen Modul, wenn der Spieler getroffen wird.
midiNoteOn(10, 49, 110)
midiNoteOff(10, 49)

2.22.10. midiOpenInput

opened = midiOpenInput(index)

Hört einem Eingabeport zu. onMidiMessage wird dann für jede ankommende Nachricht ausgelöst. Welcher Eingabeport auch immer geöffnet war, wird zuerst geschlossen.

Parameter:

  • index — Zahl; 0 bis midiInputCount() - 1.

Rückgabe: true, wenn der Port geöffnet wurde.

Seit: 3.00. Siehe auch: midiCloseInput, onMidiMessage

Beispiel
if midiInputCount() > 0 then
	midiOpenInput(0)
end

2.22.11. midiOpenOutput

opened = midiOpenOutput(index)

Nimmt einen Ausgabeport für die Sende-Aufrufe. Welcher Ausgabeport auch immer geöffnet war, wird zuerst geschlossen.

Parameter:

  • index — Zahl; 0 bis midiOutputCount() - 1.

Rückgabe: true, wenn der Port geöffnet wurde.

Seit: 3.00. Siehe auch: midiCloseOutput

2.22.12. midiOutputCount

count = midiOutputCount()

Wie viele MIDI-Ausgabeports dieser Rechner hat.

Parameter:

  • Keine.

Rückgabe: eine Zahl.

Seit: 3.00. Siehe auch: midiOutputName

2.22.13. midiOutputName

name = midiOutputName(index)

Der Name eines Ausgabeports.

Parameter:

  • index — Zahl; 0 bis midiOutputCount() - 1.

Rückgabe: ein String oder nil, wenn der Index keinen Port bezeichnet.

Seit: 3.00. Siehe auch: midiOutputCount

2.22.14. midiPitchBend

sent = midiPitchBend(channel, value)

Verbiegt die Tonhöhe eines Kanals. 8192 ist die Mitte und bedeutet keine Verbiegung; wie weit 0 und 16383 reichen, ist eine Einstellung des empfangenden Geräts, meist zwei Halbtöne.

Parameter:

  • channel — Zahl; 1 bis 16.

  • value — Zahl; 0 bis 16383.

Rückgabe: true, wenn die Nachricht hinausging.

Seit: 3.00.

2.22.15. midiProgramChange

sent = midiProgramChange(channel, program)

Wählt den Klang, den ein Kanal spielt. Die Nummern sind die des empfangenden Geräts; auf einem General-MIDI-Gerät ist 0 ein Konzertflügel.

Parameter:

  • channel — Zahl; 1 bis 16.

  • program — Zahl; 0 bis 127.

Rückgabe: true, wenn die Nachricht hinausging.

Seit: 3.00.

2.22.16. midiRescan

midiRescan()

Sucht erneut nach Ports, für ein Gerät, das angeschlossen wurde, während das Spiel läuft. Ein geöffneter Port bleibt geöffnet. Indizes sind nur so stabil wie die Liste, lies die Namen danach also neu, statt anzunehmen, dass Port 2 immer noch derselbe ist.

Parameter:

  • Keine.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: midiInputCount, midiOutputCount

2.22.17. midiSend

sent = midiSend(byte [, byte [, byte]])
sent = midiSend(string)

Jede beliebige Nachricht, für die, die die benannten Aufrufe nicht abdecken. Mit Zahlen sendet es diese so, wie sie sind, also ein Statusbyte und bis zu zwei Datenbytes — und beachte, dass das Statusbyte den Kanal in seinen unteren vier Bits trägt, ab 0 gezählt, anders als jeder andere Aufruf hier. Mit einem String sendet es den ganzen String; so geht eine System-Exclusive-Nachricht hinaus.

Parameter:

  • byte — Zahl; 0 bis 255, eine bis drei davon.

  • string — ein String aus Bytes, unverändert gesendet.

Rückgabe: true, wenn die Nachricht hinausging.

Seit: 3.00. Siehe auch: midiNoteOn, midiControlChange

Beispiel
-- Alle Noten aus auf Kanal 1, wofür es keinen benannten Aufruf gibt.
midiSend(0xB0, 123, 0)

-- Eine System-Exclusive-Nachricht, mit allen Bytes.
midiSend(string.char(0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7))

2.23. Modell

Modelle sind binäre glTF-2.0-Dateien (.glb), die einmal geladen und beliebig oft platziert werden. Ein Modell muss in sich geschlossen sein (Puffer und Bilder in der Datei); eines, das auf eine Datei daneben verweist, wird abgelehnt. Das Laden liefert ein ganzzahliges Handle; modelInstance baut die Knoten des Modells in die Szene ein und gibt ihre Wurzel zurück, die dann jeder node*- und animation*-Aufruf entgegennimmt. Positionen und Größen innerhalb eines Modells sind in Welteinheiten, so wie die Datei sie speichert; der Wurzelknoten skaliert die ganze Instanz. Siehe 3D-Szenen.

2.23.1. modelLoad

model = modelLoad(name)

Liest eine .glb über dieselbe Suche wie jedes andere Asset (Spieleverzeichnis, Datenordner, gepackte Datenbank), lädt ihre Meshes und Materialien einmal auf die GPU hoch und behält ihren Knotenbaum, ihre Skins und Animationen zum Instanzieren. Ruf es einmal beim Start auf und instanziere das Handle so oft wie nötig; dieselbe Datei zweimal zu laden erzeugt zwei Kopien auf der GPU. Es braucht die 3D-Szene und schlägt deshalb auf einem Rechner ohne geeignete GPU fehl wie jeder andere 3D-Aufruf. Eine fehlerhafte Datei beendet das Skript mit einer Meldung, die das Problem nennt: Die Datei konnte nicht gelesen werden, ist kein glTF, verweist auf einen externen Puffer oder ein externes Bild, besteht die Validierung nicht, enthält eine Grundform, die nicht hochgeladen werden konnte, hat einen Skin mit mehr als 128 Gelenken oder hat ein geskinntes Mesh, das ein Gelenk mit der Nummer 128 oder höher nennt. Ein geskinntes Mesh, das ein Gelenk jenseits der Skins nennt, die es verwenden, wird geladen, ebenso eine Animation, deren Keyframes nicht gelesen werden können (dieser Sampler wird übersprungen); beides wird im Programm-Trace vermerkt. Eine Textur, die nicht dekodiert werden kann, oder ein fehlendes KTX2-Bild lässt das Laden nicht fehlschlagen; das Material kommt ohne diese Map aus, und der Programm-Trace (--program) sagt, welche es ist.

Rückgabe: Das Modell-Handle, eine Ganzzahl.

Seit: 3.00. Siehe auch: modelInstance, modelGetAnimations, modelDelete

Beispiel
-- Einmal laden, dreimal platzieren.
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)

Gibt die Meshes, Materialien und eingelesenen Daten des Modells frei. Jede daraus erzeugte Instanz wird zugleich vergessen: Ihre Knoten bleiben in der Szene (Position, Elternknoten und Kinder unverändert), zeichnen aber nichts, ihre Animationen bleiben stehen, wo sie sind, und ein späterer animation*-Aufruf auf ihrer Wurzel beendet das Skript, weil der Knoten keine Modellinstanz mehr ist. Lösch die Wurzeln der Instanzen mit nodeDelete, wenn die Knoten auch nicht mehr gebraucht werden. Ein Handle, das kein geladenes Modell ist, beendet das Skript.

Seit: 3.00. Siehe auch: modelLoad, modelInstance, nodeDelete

Beispiel
-- Das Hangar-Level verlassen: seine Requisiten und das Modell dahinter verwerfen.
function unloadHangar()
    for _, crate in ipairs(hangarCrates) do
        nodeDelete(crate)
    end
    hangarCrates = {}
    modelDelete(crateModel)
    crateModel = nil
end

2.23.3. modelGetAnimations

names = modelGetAnimations(model)

Listet die Animationsclips des Modells in Dateireihenfolge als Tabelle von Strings auf, sodass names[3] der Clip ist, den animationPlay(node, 3) abspielt. Ein Clip, den der Exporter unbenannt gelassen hat, ergibt einen leeren String; er kann trotzdem über seine Nummer abgespielt werden. Ein Modell ohne Animationen ergibt eine leere Tabelle. Ein Handle, das kein geladenes Modell ist, beendet das Skript.

Rückgabe: Eine Tabelle von Strings, ab 1 indiziert.

Seit: 3.00. Siehe auch: animationPlay, modelLoad

Beispiel
-- Die Clips einmal nach Namen suchen, damit der Rest des Spiels Nummern verwendet.
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)

Baut den Knotenbaum des Modells unter einem neuen Wurzelknoten auf, der selbst unter parent oder der Wurzel der Szene hängt. Die Wurzel ist ein gewöhnlicher Knoten: Positioniere, drehe, skaliere oder verknüpfe sie wie jeden anderen und lösch sie mit nodeDelete, um die ganze Instanz zu entfernen. Die eigenen Knoten des Modells übernehmen ihre glTF-Namen (oder den Namen ihres Meshs, wenn der Knoten unbenannt ist), sodass nodeFind(name, node) sie erreicht; ein Mesh mit mehreren Materialien wird zu einem Kindknoten pro Teil; Lichter in der Datei werden zu Szenenlichtern mit der Farbe, Intensität, Reichweite und dem Kegel aus der Datei; Skins werden angehängt und Morph-Gewichte gesetzt. Die Knoten stehen in der Pose der Datei, bis eine Animation läuft. Ein Handle, das kein geladenes Modell ist, oder ein parent, das kein Knoten ist, beendet das Skript, ebenso, wenn die Knoten ausgehen.

Rückgabe: Das Handle des Wurzelknotens der Instanz.

Seit: 3.00. Siehe auch: modelLoad, nodeFind, animationPlay, nodeDelete

Beispiel
-- Ein Geschützturm auf der Wanne des Panzers, der sich also mit der Wanne dreht und für sich schwenkt.
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. Maus

Singe liest bis zu vier Mäuse und behandelt Lightguns als Mäuse. Im standardmäßigen Einzelmausmodus steuert jedes Zeigegerät einen Cursor, der als Maus 0 gemeldet wird; mouseSetMode(MOUSE_MANY) unterscheidet die Geräte, was ein Lightgun-Automat für zwei Spieler braucht. Positionen kommen in Overlay-Koordinaten an, nicht in Bildschirmpixeln, über onMouseMoved (siehe Engine-Callbacks) und auf Abruf von mouseGetPosition. Maustasten und das Mausrad sind Schalter wie Tasten: Sie erreichen onInputPressed und onInputReleased, wenn controls.cfg einen Code aus den Tabellen MOUSE_0 bis MOUSE_3 belegt, und die mitgelieferten Standardwerte belegen die linke Taste mit SWITCH_BUTTON3, die rechte mit SWITCH_BUTTON1 und die mittlere mit SWITCH_BUTTON2. Die Engine startet mit eingefangener Maus, die eingeschaltet ist, sofern nicht --nomouse angegeben oder keine Maus gefunden wurde.

2.24.1. mouseDisable

mouseDisable()

Schaltet die Mauseingabe aus, genau wie mouseSetEnabled(false). Es ist eine in Framework.singe definierte Funktion, die erhalten bleibt, damit ältere Spiele unverändert laufen.

Hinweise: Veralteter Alias.

Neuer Code sollte mouseSetEnabled mit false aufrufen.

Seit: 1.18 (RDG) Siehe auch: mouseSetEnabled, mouseEnable

Beispiel
-- Älterer Spielcode; die moderne Schreibweise ist mouseSetEnabled(false).
function cutsceneBegin()
    mouseDisable()
    discSearch(CUTSCENE_START)
end

2.24.2. mouseEnable

mouseEnable()

Schaltet die Mauseingabe ein, genau wie mouseSetEnabled(true), und bleibt wie dieses aus, wenn Singe mit --nomouse gestartet wurde. Es ist eine in Framework.singe definierte Funktion, die erhalten bleibt, damit ältere Spiele unverändert laufen.

Hinweise: Veralteter Alias.

Neuer Code sollte mouseSetEnabled mit true aufrufen.

Seit: 1.18 (RDG) Siehe auch: mouseSetEnabled, mouseDisable

Beispiel
-- Älterer Spielcode; die moderne Schreibweise ist mouseSetEnabled(true).
function cutsceneEnd()
    mouseEnable()
    discSearch(LEVEL_START)
end

2.24.3. mouseGetName

name = mouseGetName(mouse)

Der Name, den der Maustreiber einem Gerät gibt, oder nil, wenn es kein Gerät mit diesem Index gibt. Damit lassen sich zwei Pistolen an einem Automaten auf einem Service-Bildschirm unterscheiden, was sonst Raterei ist, wenn sich beide als Maus 0 und 1 melden. Ein Index außerhalb von 0 bis 3 bricht das Skript ab.

Parameter:

  • mouse — Geräteindex, 0 bis 3.

Rückgabe: String oder nil.

Seit: 3.00 Siehe auch: mouseHowMany, mouseSetMode, controllerGetName

Beispiel
-- Die Pistolen auf dem Kalibrierungsbildschirm benennen.
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()

Hypseus-Erweiterung, immer 0, aus dem Grund, den controllerGetPadding nennt. Hypseus addiert diesen Offset zu den Eingabecodes, die seine Mäuse im relativen Modus melden; die Codes von Singe tragen keinen solchen Offset, es gibt also nichts abzuziehen.

Rückgabe: eine Ganzzahl, immer 0.

Seit: 3.00 Siehe auch: controllerGetPadding

2.24.5. mouseGetPosition

x, y = mouseGetPosition(index)

Gibt die zuletzt gemeldete Position einer Maus in Overlay-Koordinaten zurück, dieselben Werte, die das jüngste onMouseMoved für dieses Gerät trug. Im Einzelmausmodus bewegt sich nur Maus 0; im Mehrmausmodus hat jedes Gerät seine eigene Position, die in der Mitte des Videos beginnt. Die Position wird nicht mehr aktualisiert, solange die Mauseingabe ausgeschaltet ist. Frag sie in onOverlayUpdate oder singeMain ab, wenn das einfacher ist, als den Callback zu verfolgen. Ein Index außerhalb von 0 bis 3 bricht das Skript ab.

Parameter:

  • index — Mausindex, 0 bis 3.

Rückgabe: zwei Ganzzahlen, x und y, in Overlay-Koordinaten.

Beispiel
-- Das Fadenkreuz dort zeichnen, wohin die Pistole zeigt.
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()

Gibt die Anzahl der Mäuse zurück, die die Engine beim Start gefunden hat, 0 bis 4. Später angeschlossene Geräte werden nicht gezählt. Wurde keine gefunden, bleibt die Maus ausgeschaltet. Entscheide damit, ob du einen zweiten Lightgun-Spieler anbietest.

Rückgabe: Ganzzahl, 0 bis 4.

Seit: 1.18 (RDG) Siehe auch: mouseSetMode, mouseGetPosition

Beispiel
-- Zwei Pistolen vorhanden: jedem Spieler einen Cursor geben.
if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
    players = 2
else
    players = 1
end

2.24.7. mouseSetCaptured

mouseSetCaptured(captured)

Fängt die Maus ein, beschränkt sie auf das Singe-Fenster und versteckt den Cursor, oder gibt sie frei und zeigt den Cursor wieder. Die Engine fängt die Maus beim Start ein, die meisten Spiele rufen dies also nie auf; ein Level-Editor im Fenster oder ein Spiel, das den Desktop-Cursor sichtbar haben will, gibt sie frei. Der Schalter, der in controls.cfg mit INPUT_GRAB belegt ist, schaltet denselben Zustand über die Tastatur um.

Parameter:

  • captured — Boolean; true fängt ein und versteckt, false gibt frei und zeigt.

Seit: 2.00 Siehe auch: mouseSetEnabled, mouseGetPosition

Beispiel
-- Der Level-Editor will den Desktop-Cursor; das Spiel versteckt ihn wieder.
function editorToggle()
    editing = not editing
    mouseSetCaptured(not editing)
end

2.24.8. mouseSetEnabled

mouseSetEnabled(enabled)

Schaltet die Mauseingabe ein oder aus. Solange sie aus ist, werden Bewegungs-, Tasten- und Radereignisse verworfen, bevor sie das Skript erreichen: onMouseMoved wird nicht mehr ausgelöst, Maustasten erzeugen keine Schalter mehr, und mouseGetPosition gibt weiter die letzte Position zurück, die es hatte. Der Cursor selbst bewegt sich weiterhin. Das Einschalten beachtet --nomouse; wurde Singe mit dieser Option gestartet, bleibt die Maus aus. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Seit: 3.00 Siehe auch: mouseSetCaptured, mouseSetMode, mouseEnable

Beispiel
-- Die Pistole ignorieren, solange die Attract-Schleife läuft.
function attractBegin()
    mouseSetEnabled(false)
    discSearch(ATTRACT_START)
end

function attractEnd()
    mouseSetEnabled(true)
end

2.24.9. mouseSetMode

mouseSetMode(mode)

Wählt, wie Mäuse gelesen werden. Im MOUSE_SINGLE (der Standard) steuern die Zeigerereignisse des Fensters einen Cursor, der als Gerät 0 gemeldet wird, wobei absolute Positionen und relative Bewegung beide in Overlay-Koordinaten umgerechnet werden. Im MOUSE_MANY wird jedes physische Gerät getrennt gelesen: Relative Bewegung wird zu einer Position pro Gerät aufsummiert, die auf den Videobereich begrenzt ist, absolute Geräte wie Grafiktabletts und manche Lightguns werden auf das Video abgebildet, und onMouseMoved meldet den Geräteindex. Beide Modi liefern dieselben fünf Tasten und das senkrechte Mausrad als Schalter. SINGLE_MOUSE und MANY_MOUSE werden als ältere Schreibweisen akzeptiert; jeder andere Wert bricht das Skript ab. --manymouse ist die eigene Entscheidung des Benutzers und hat Vorrang vor diesem Aufruf: Ist es angegeben, ist der Modus von Anfang an MOUSE_MANY, und mouseSetMode(MOUSE_SINGLE) schaltet ihn nicht ab, sodass ein Automat mit zwei Pistolen von außen auch mit einem Spiel funktioniert, das nie danach fragt.

Parameter:

  • mode — MOUSE_SINGLE (100) oder MOUSE_MANY (200).

Seit: 1.18 (RDG) Siehe auch: mouseHowMany, onMouseMoved, mouseGetPosition

Beispiel
-- Kooperatives Lightgun-Spiel: Jede Pistole steuert ihren eigenen Cursor.
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. Musik

Hintergrundmusik, getrennt von den Soundeffekten geladen und abgespielt und mit eigener Lautstärke. Hypseus lässt Musik genau aus diesem Grund auf einem zweiten Mixer laufen, und Singe gibt ihr stattdessen eine eigene Verstärkung: musicSetVolume verändert nie einen Soundeffekt, und soundSetVolume verändert nie die Musik.

Ein Musik-Handle ist eine eigene Art von Handle, weder ein Sound-Handle noch ein Kanal: Ein Handle ist ein Stück, und es spielt, pausiert, setzt fort und stoppt für sich allein. Anders als bei den sechzehn Soundeffekt-Kanälen gibt es keine Kanalbegrenzung.

Die Lautstärkeskala ist die von Hypseus, 0 bis 128, fast doppelt so groß wie die 0 bis 63 der sound-Familie, sodass ein für Hypseus geschriebenes Spiel seine eigenen Zahlen behält. Musik beginnt so laut wie die Soundeffekte, mit dem, was --volume_nonvldp gesetzt hat; Hypseus startet seinen Musik-Mixer dagegen bei einem Drittel, was jedes Hypseus-Spiel sofort mit musicSetVolume(soundGetVolume() * 2) überschreibt.

Jedes Format, das die Sound-Familie liest, wird auch hier gelesen: WAV, Ogg Vorbis, Opus, FLAC, MP3, WavPack und der Rest. Der Kopf des Trace, den --program und --trace schreiben, listet in seiner Zeile Audio: genau auf, welche Decoder der Build enthält.

Das Pausieren der Engine (die Pausentaste oder singeSetPauseFlag) pausiert die Musik mit, und das Fortsetzen bringt sie zurück; ein Neuladen stoppt jedes Stück und gibt es frei.

2.25.1. musicGetPosition

seconds = musicGetPosition(id)

Wo sich der Zuhörer in einem laufenden Stück befindet, in Sekunden: die eigene Position des Mixers abzüglich dessen, was noch auf dem Weg zu den Lautsprechern ist — die Gerätewarteschlange, die Audiokalibrierung des Rechners und die Audioverzögerung des Spiels — und so kommt ein darauf abgestimmtes Bild zusammen mit dem Klang an. Es ist die Uhr, nach der animiert wird, wenn die Musik führt, wie in einer Demo oder einem Rhythmusspiel, und sie bleibt beim Lied, wie lange es auch läuft, während das Zählen von Frames oder Ticks abdriftet. Der Mixer bewegt seine Position jeweils um einen Puffer, zwischen den Sprüngen läuft die Antwort also mit der Uhr weiter, nie mehr als 50 ms, und sie bewegt sich in jedem Frame gleichmäßig. Ein pausiertes Stück steht still. Ein Stück, das nicht läuft, antwortet -1.

Parameter:

  • id — Zahl; ein Musik-Handle.

Rückgabe: Zahl; Sekunden seit Beginn des Stücks oder -1.

Beispiel
-- Bei jedem Schlag eines Lieds mit 120 Schlägen pro Minute aufblitzen, genau auf dem Schlag, wie er zu hören ist.
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])

Hypseus-Erweiterung. Ob dieses Stück läuft oder — ohne Handle — ob irgendeine Musik läuft. Ein pausiertes Stück läuft nicht.

Parameter:

  • id — optionale Zahl; ein Musik-Handle.

Rückgabe: Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicPlay, musicPause

Beispiel
if not musicIsPlaying(theme) then
    musicPlay(theme, -1)
end

2.25.3. musicLoad

id = musicLoad(filename)

Hypseus-Erweiterung. Lädt ein Musikstück über das virtuelle Dateisystem und gibt sein Handle zurück. Die ganze Datei wird vorab dekodiert, wie bei einem Sound, ein langes Stück kostet also Speicher — außer einem Chiptune, der seine Länge nicht angibt, oder etwas, das dekodiert mehr als 512 MB hätte, die beide beim Abspielen dekodiert werden; das Handle gilt bis musicUnload oder zu einem Neuladen.

Eine Datei, die fehlt oder die kein einkompilierter Decoder lesen kann, beendet das Skript, wie bei soundLoad.

Parameter:

  • filename — String; ein Pfad, den das virtuelle Dateisystem erreichen kann.

Rückgabe: Zahl, das Musik-Handle.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicPlay, musicUnload, soundLoad

Beispiel
local theme = musicLoad("music/attract.mp3")
musicSetVolume(96)
musicPlay(theme, -1)

2.25.4. musicPause

musicPause([id])

Hypseus-Erweiterung. Pausiert dieses Stück an seiner Stelle oder jede Musik, wenn kein Handle angegeben ist. musicResume setzt es wieder fort.

Parameter:

  • id — optionale Zahl; ein Musik-Handle.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicResume, musicStop

Beispiel
-- Der Spieler hat die Karte geöffnet; die Musik anhalten statt neu starten.
musicPause()

2.25.5. musicPlay

id = musicPlay(id [, loops])

Hypseus-Erweiterung. Spielt ein Stück von seinem Anfang an und antwortet mit seinem Handle, so wie die Spiele von Hypseus es aufbewahren (sndHandle = musicPlay(music)), um das Stück später zu stoppen. loops bedeutet dasselbe wie bei soundPlay: 0, der Standard, spielt einmal, -1 spielt endlos, und N wiederholt N-mal zusätzlich. Die Anzahl wird auf -1 bis 64 begrenzt, so wie Hypseus sie begrenzt, damit ein Spiel, das mehr verlangt, bekommt, was es dort bekommen hätte.

Ein Stück abzuspielen, das bereits läuft, startet es erneut von vorn.

Parameter:

  • id — Zahl; ein Musik-Handle.

  • loops — optionale Zahl; -1 bis 64. Standard 0.

Rückgabe: Zahl; das Handle, das es bekommen hat.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicStop, musicSetVolume

Beispiel
musicPlay(theme, -1)     -- Immer im Kreis, bis etwas es stoppt.

2.25.6. musicResume

musicResume([id])

Hypseus-Erweiterung. Setzt ein pausiertes Stück fort oder jede pausierte Musik, wenn kein Handle angegeben ist.

Die eigene Form von Hypseus ohne Argument tut gar nichts; die von Singe setzt alles fort, und das ist das Gegenstück zu musicPause.

Parameter:

  • id — optionale Zahl; ein Musik-Handle.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicPause

Beispiel
musicResume()

2.25.7. musicSetVolume

volume = musicSetVolume(volume)

Hypseus-Erweiterung. Setzt die Verstärkung für alle Musik auf einmal, auf der Skala 0 bis 128 von Hypseus, und antwortet mit dem übernommenen Pegel. Es verändert nichts außer Musik: Die Soundeffekte behalten, was soundSetVolume ihnen gegeben hat, und soundSetVolume lässt die Musik in Ruhe.

Ein Pegel außerhalb von 0 bis 128 beendet das Skript. Der Pegel gilt für bereits laufende Stücke und für alle danach geladenen und kehrt bei einem Neuladen zum Anfangspegel zurück.

Parameter:

  • volume — Zahl; 0 bis 128.

Rückgabe: Zahl, der gesetzte Pegel.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: soundSetVolume, musicPlay

Beispiel
-- Was ein Hypseus-Spiel schreibt:  der Sound-Pegel, verdoppelt auf die Musikskala.
musicSetVolume(soundGetVolume() * 2)

2.25.8. musicStop

musicStop([id [, fadeMs]])

Hypseus-Erweiterung. Stoppt dieses Stück oder jede Musik, wenn kein Handle angegeben ist (ein nil-Handle zählt als keines). fadeMs blendet es über so viele Millisekunden aus, statt es abzuschneiden; 0, der Standard, stoppt sofort. Eine negative Ausblendzeit beendet das Skript.

Parameter:

  • id — optionale Zahl; ein Musik-Handle.

  • fadeMs — optionale Zahl; Millisekunden zum Ausblenden. Standard 0.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicPlay, musicPause

Beispiel
musicStop(theme, 1500)   -- Über anderthalb Sekunden ausgeblendet.

2.25.9. musicUnload

musicUnload(id)

Hypseus-Erweiterung. Stoppt das Stück und gibt es frei. Das Handle ist danach ungültig, und es zu verwenden beendet das Skript.

Parameter:

  • id — Zahl; ein Musik-Handle.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: musicLoad

Beispiel
musicUnload(theme)

Navigationsmeshes, aus Szenengeometrie gebacken, und die Crowd-Agenten, die sie ablaufen (siehe 3D-Szenen, Navigation). navNew und navLoad geben ein Mesh-Handle zurück und navAgentNew ein Agenten-Handle; beide sind Ganzzahlen, werden bei jedem Aufruf geprüft, und ein ungültiges beendet das Skript. Positionen sind in Welteinheiten, Geschwindigkeiten in Einheiten pro Sekunde und Steigungen in Grad. Bis zu acht Meshes gleichzeitig, 128 Agenten auf jedem und 256 insgesamt. Die Abfragen und die Agenten brauchen ein Mesh, das navBuild gebacken oder navLoad gelesen hat; vorher geben die Abfragen nil zurück, navDraw zeichnet nichts, und navAgentNew beendet das Skript.

navAddNode(nav, node)

Fügt das Mesh des Knotens und das Mesh jedes Knotens darunter der Geometrie hinzu, aus der das Navigationsmesh gebacken wird, so wie sie gerade in der Welt stehen; platziere sie also zuerst. Der Wurzelknoten einer Modellinstanz fügt das ganze Modell hinzu, und ein aus Grundformen gebautes Level lässt sich Knoten für Knoten hinzufügen. Nur Mesh-Geometrie zählt: Körper, Sprites und Text fügen nichts hinzu. Beendet das Skript, sobald das Mesh gebaut ist.

Seit: 3.00. Siehe auch: navNew, navBuild, modelInstance

Beispiel
-- Boden und Wände sind begehbare Geometrie; die Kisten nicht, sie bewegen sich.
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)

Nimmt den Agenten vom Mesh und gibt sein Handle frei; der Knoten bleibt, wo er ist, und wird nicht mehr bewegt. Das Löschen des Meshs mit navDelete tut das für jeden Agenten darauf. Ein ungültiges Handle beendet das Skript.

Seit: 3.00. Siehe auch: navAgentNew, navDelete

Beispiel
-- Ein Wächter, der stirbt, hört auf zu navigieren; ab hier übernimmt die Ragdoll das Modell.
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)

Wie die Crowd den Agenten in diesem Frame bewegt, in Welteinheiten pro Sekunde entlang jeder Achse; die Länge reicht bis zur Geschwindigkeit des Agenten und fällt auf null, wenn er anhält. Damit wählst du zwischen einer Steh-, einer Geh- und einer Laufanimation oder passt den Gehzyklus an die zurückgelegte Strecke an.

Rückgabe: Drei Zahlen.

Seit: 3.00. Siehe auch: navAgentMoveTo, animationPlay

Beispiel
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)

Ob der Agent das letzte Ziel erreicht hat, das navAgentMoveTo ihm gegeben hat: höchstens anderthalb seiner Radien vom Ziel entfernt und fast zum Stehen gekommen. Es wird true in dem Moment, in dem onNavArrived ausgelöst wird, und bleibt true bis zum nächsten navAgentMoveTo; für einen Agenten, der nie irgendwohin geschickt oder unterwegs angehalten wurde, ist es false.

Rückgabe: Wahr oder falsch.

Seit: 3.00. Siehe auch: onNavArrived, navAgentMoveTo, navAgentStop

Beispiel
-- Die Patrouille wartet an jedem Posten eine Weile, bevor sie weitergeht.
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)

Schickt den Agenten zu Fuß zu dem Punkt des Meshs, der x, y, z am nächsten liegt, und sucht diesen bis zu 2 Einheiten seitlich und 4 nach oben oder unten. Die Crowd plant die Route über die folgenden Frames und steuert den Agenten unterwegs um die anderen Agenten herum; onNavArrived wird ausgelöst, sobald er dort ankommt. Gibt false zurück und lässt den Agenten, wie er war, wenn kein Punkt des Meshs nah genug ist oder die Crowd die Anfrage ablehnt. Ein neues Ziel ersetzt das alte jederzeit.

Parameter:

  • agent — das Handle von navAgentNew.

  • x, y, z — das Ziel in Welteinheiten; es wird auf das Mesh eingerastet.

Rückgabe: Wahr, wenn der Agent losgegangen ist.

Seit: 3.00. Siehe auch: navAgentStop, navNearest, navPath

Beispiel
-- Der Begleiter folgt dem Helden, zweimal pro Sekunde neu ausgerichtet.
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)       -- Der Held ist nicht auf dem Mesh:  er springt, schwimmt
        end
    end
    return OVERLAY_NOT_UPDATED
end
agent = navAgentNew(nav, node, radius, height, speed)

Setzt einen Agenten dieser Größe auf das Mesh, an den Punkt, der der Weltposition des Knotens am nächsten liegt (die unveränderte Position, wenn innerhalb von 2 Einheiten seitlich und 4 nach oben oder unten nichts liegt), mit einer Gehgeschwindigkeit von speed Einheiten pro Sekunde und einer Beschleunigung von 8 Einheiten pro Sekunde zum Quadrat. Radius und Höhe werden auf mindestens 0.01 gehalten, so wie navNew seine eigenen hält. Von da an bewegt die Engine den Knoten in jedem Frame entlang des Meshs, im Koordinatensystem seines Elternknotens, und dreht ihn um Y in seine Laufrichtung, wann immer er sich schneller als 0.05 Einheiten pro Sekunde bewegt; Knoten blicken entlang -Z, wie Modelle. Die Crowd steuert Agenten umeinander herum, nimmt Kurven vorweg und hält sie auseinander. Um eine Spielfigur auf dem Knoten zu steuern, statt den Knoten zu platzieren, siehe navAgentSetPlayer. Beendet das Skript, wenn das Mesh nicht gebaut ist oder schon 128 Agenten darauf sind.

Parameter:

  • nav — ein gebautes Mesh von navNew oder navLoad.

  • node — der zu bewegende Knoten; meist die Wurzel einer Modellinstanz.

  • radius — der Radius des Agenten, mit dem er Abstand zu anderen hält, in Welteinheiten; höchstens der eigene Radius des Meshs.

  • height — die Höhe des Agenten, in Welteinheiten.

  • speed — die höchste Gehgeschwindigkeit, in Welteinheiten pro Sekunde.

Rückgabe: Das Handle des Agenten, eine Ganzzahl.

Beispiel
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)

Mit true hört der Agent auf, seinen Knoten zu platzieren, und gibt stattdessen in jedem Frame seine Geschwindigkeit als playerMove (nur waagerecht) an die Spielfigur auf dem Knoten weiter, sodass Treppen, Steigungen, Schieben und Kollisionen weiter funktionieren; vor jeder Aktualisierung der Crowd wird die Weltposition des Controllers als die eigene des Agenten zurückgelesen, sodass ein Abdrängen vom Kurs in der Planung berücksichtigt wird. Der Knoten dreht sich weiterhin in seine Laufrichtung. Der Knoten braucht einen Controller von playerNew, sonst bewegt sich nichts. Mit false platziert der Agent den Knoten wieder selbst.

Seit: 3.00. Siehe auch: playerNew, playerMove, navAgentNew

Beispiel
-- Ein Begleiter, der dem Helden durch das Level folgt und herumgestoßen werden kann.
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)

Vergisst das Ziel des Agenten: Die Crowd steuert ihn auf nichts mehr zu, er bremst an Ort und Stelle bis zum Stillstand ab, und onNavArrived wird nicht ausgelöst. Andere Agenten gehen weiterhin um ihn herum. Schick ihn mit navAgentMoveTo irgendwohin, damit er wieder losgeht.

Seit: 3.00. Siehe auch: navAgentMoveTo, navAgentIsArrived

Beispiel
-- Wächter erstarren, wenn der Alarm ertönt, und drehen sich zum Geräusch.
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)

Backt das begehbare Mesh aus allem, was navAddNode hinzugefügt hat: Böden und Steigungen bis zum Winkel des Meshs, Stufen bis zu seiner Höhe, wobei um jede Wand und jede Abbruchkante der Radius des Agenten abgeschnitten und alles weggelassen wird, über dem weniger als die Höhe des Agenten frei ist. Das Backen arbeitet mit Zellen, die ein Drittel des Agentenradius breit sind, und umfasst höchstens 4096 mal 4096 davon, ein kleiner Radius über einem großen Level ist also langsam und kann fehlschlagen; eine Zehntelsekunde für Sponza auf einem Desktop, ein paar Sekunden auf einem Raspberry Pi. Die hinzugefügte Geometrie wird danach freigegeben, und es kann nichts mehr hinzugefügt werden; back stattdessen ein weiteres Mesh. navSave bewahrt das Ergebnis auf. Beendet das Skript, wenn nichts hinzugefügt wurde, das Mesh schon gebaut ist oder das Backen fehlschlägt.

Seit: 3.00. Siehe auch: navNew, navAddNode, navSave, navDraw

Beispiel
-- Gebacken wird einmal, während der Titelbildschirm zu sehen ist, und fürs nächste Mal aufbewahrt.
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)                              -- Ein Frame, um das gebackene Mesh kurz anzusehen
end
navDelete(nav)

Gibt das Mesh und jeden Agenten darauf frei; ihre Knoten bleiben, wo sie sind. Das Mesh-Handle und die Agenten-Handles sind danach ungültig und beenden das Skript, wenn sie verwendet werden. Der Platz ist frei für ein neues navNew oder navLoad.

Seit: 3.00. Siehe auch: navNew, navAgentDelete

Beispiel
function loadLevel(index)
    if levelNav then
        navDelete(levelNav)                   -- Nimmt die Agenten des alten Levels mit
    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)

Zeichnet die Polygone des gebackenen Meshs für diesen Frame als Linien über die Szene, cyan, sofern keine Farbe angegeben ist, jedes Polygon als Fächer aus Dreiecken, sodass ein Polygon mit mehr als drei Seiten seine Diagonalen zeigt. Ruf es in jedem Frame auf, solange du hinsiehst; es kostet drei Linien pro Dreieck, und ein noch nicht gebautes Mesh zeichnet nichts. Damit prüfst du, neben physicsSetDebug, ob ein gebackenes Mesh den Boden abdeckt und die Möbel auslässt.

Parameter:

  • nav — das Mesh.

  • r, g, b — die Linienfarbe, je 0 bis 255; Standard 0, 255, 255.

Seit: 3.00. Siehe auch: lineDraw, navBuild, physicsSetDebug

Beispiel
function onOverlayUpdate()
    if showNavMesh then
        navDraw(nav)                          -- Cyan über dem Boden
        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)

Lädt ein Mesh, das navSave geschrieben hat, und sucht es zuerst unter den Dateien des Spiels (so kann ein gebackenes Mesh mit dem Spiel ausgeliefert werden, gepackt oder nicht) und dann im Datenordner des Spiels. Das Mesh kommt gebaut zurück, bereit für Agenten und Abfragen, und nimmt kein navAddNode mehr an. Steigung und Stufe, mit denen es gebacken wurde, stehen in der Datei; Radius und Höhe der Agenten sind das, womit die Crowd steuert, gib also die Werte an, für die es gebacken wurde. Beendet das Skript, wenn die Datei nicht gelesen werden kann, kein Navigationsmesh ist, kürzer ist als das Mesh, das ihr Kopf beschreibt (abgeschnitten oder von Hand bearbeitet), oder kein Mesh-Platz frei ist.

Parameter:

  • name — der Name der Datei, relativ zum Spieleverzeichnis oder zum Datenordner.

  • agentRadius — der Agentenradius, für den das Mesh gebacken wurde, in Welteinheiten.

  • agentHeight — die Agentenhöhe, für die es gebacken wurde, in Welteinheiten.

Rückgabe: Das Mesh-Handle, eine Ganzzahl.

Seit: 3.00. Siehe auch: navSave, navNew

Beispiel
-- Das mitgelieferte gebackene Mesh für das Museum; Agenten 0,8 breit und 1,7 hoch.
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)

Der Punkt des Meshs, der einem Punkt am nächsten liegt, gesucht bis zu 2 Einheiten seitlich und 4 nach oben oder unten, oder nil, wenn nichts so nah ist. Damit rastest du einen Spawnpunkt, einen Abwurfpunkt oder einen Klick auf dem Boden ein, bevor du ihn einem Agenten übergibst, und findest die Höhe des Bodens unter einem Punkt.

Parameter:

  • nav — das Mesh.

  • x, y, z — der einzurastende Punkt, in Welteinheiten.

Rückgabe: Drei Zahlen oder nil.

Seit: 3.00. Siehe auch: navPath, navAgentMoveTo, sceneUnproject

Beispiel
-- Den Gegner auf dem Boden erscheinen lassen, der dem Spawner am nächsten ist, oder gar nicht.
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)

Beginnt ein Navigationsmesh für Agenten mit diesem Radius und dieser Höhe, die Stufen bis maxStep Einheiten und Steigungen bis maxSlope Grad erklimmen können. Radius und Höhe werden auf mindestens 0.01 gehalten, die Steigung zwischen 0 und 89 und die Stufe auf mindestens 0. Der Radius legt auch die Auflösung des Backens fest, da eine Zelle ein Drittel davon ist; er entscheidet also, wie lange navBuild braucht und wie groß ein Level sein kann, das es abdeckt. Füge Geometrie mit navAddNode hinzu, dann navBuild. Beendet das Skript, wenn schon acht Meshes existieren.

Parameter:

  • agentRadius — der Radius der Agenten, in Welteinheiten; Wände werden um so viel aufgepolstert.

  • agentHeight — wie hoch sie sind; unter niedrigeren Decken ist nichts begehbar.

  • maxSlope — die steilste begehbare Steigung, in Grad.

  • maxStep — die höchste Stufe, die sie erklimmen, in Welteinheiten.

Rückgabe: Das Mesh-Handle, eine Ganzzahl.

Seit: 3.00. Siehe auch: navAddNode, navBuild, navLoad

Beispiel
-- Sponza für einen Agenten, 0,8 breit und 1,6 hoch, der 0,3 hoch steigt und Steigungen bis 45 Grad geht.
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)

Die Eckpunkte des kürzesten Wegs von einem Punkt zu einem anderen, beide zuerst auf das Mesh eingerastet, als Tabelle von { x, y, z }-Tabellen, die erste am Start und die letzte am Ende; bis zu 256 Eckpunkte. Kann das Ende nicht erreicht werden, endet der Weg am nächsten erreichbaren Punkt unterwegs, sodass der letzte Eckpunkt immer dort liegt, wo ein Agent stehen kann. nil, wenn eines der Enden nicht in der Nähe des Meshs liegt oder kein Weg gefunden wird. Damit zeichnest du eine Route, misst, wie weit etwas zu Fuß entfernt ist, oder bewegst selbst etwas daran entlang; Agenten tun das von sich aus.

Parameter:

  • nav — das Mesh.

  • x0, y0, z0 — wo der Weg beginnt.

  • x1, y1, z1 — wo er endet.

Rückgabe: Eine Tabelle von { x, y, z }-Tabellen oder nil.

Seit: 3.00. Siehe auch: navAgentMoveTo, navRaycast, navNearest

Beispiel
-- Wie weit der Ausgang zu Fuß ist, für das Entfernungs-Anzeigefeld der Karte.
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)

Ein zufälliger Punkt auf dem begehbaren Mesh, irgendwo innerhalb seiner Reichweite, zum Umherwandern, zum Verstreuen von Gegenständen zum Aufsammeln oder zum Platzieren eines Spawnpunkts. nil nur, wenn das Mesh nicht gebaut ist.

Rückgabe: Drei Zahlen oder nil.

Seit: 3.00. Siehe auch: navAgentMoveTo, navNearest

Beispiel
-- Zwanzig Münzen über den Boden streuen, jede ein wenig darüber.
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)

Ob ein gerader Weg von einem Punkt zu einem anderen das Mesh verlässt, an einer Wand oder einer Abbruchkante, und wo er es täte. Der Start wird auf das Mesh eingerastet; false allein heißt, dass der Weg frei ist oder dass der Start nicht in der Nähe des Meshs liegt. Ist er blockiert, ist der Punkt dort, wo die Linie den Rand des Meshs kreuzt, mit einer zwischen den beiden Enden interpolierten Höhe. Eine billige Prüfung, ob eine Abkürzung existiert, bevor du navPath fragst.

Parameter:

  • nav — das Mesh.

  • x0, y0, z0 — wo der Weg beginnt.

  • x1, y1, z1 — wo er enden würde.

Rückgabe: false oder true und der Punkt, an dem der Weg das Mesh verlässt.

Seit: 3.00. Siehe auch: navPath, physicsRaycast

Beispiel
-- Eine geworfene Granate rollt nur so weit, wie der Boden es zulässt.
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)

Schreibt das gebackene Mesh unter name in den Datenordner des Spiels, für navLoad beim nächsten Mal oder zum Kopieren in den Spielordner, um es auszuliefern. Das Mesh muss gebaut sein. Beendet das Skript, wenn es das nicht ist oder die Datei nicht geschrieben werden kann.

Seit: 3.00. Siehe auch: navLoad, navBuild

Beispiel
-- Einmal auf diesem Rechner gebacken, in späteren Läufen dann aus dem Datenordner geladen.
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. Netzwerk

Was die Engine unter Singe/Net.singe hinzufügt, dem HTTP-Client des Menüs. Die meisten Spiele berühren es nie: Einen Punktestand senden oder einen Katalog abrufen läuft über Net.singe, das dies für dich aufruft.

2.27.1. netTrustHost

ok = netTrustHost(connection, host)

Lässt eine LuaSec-Client-Verbindung ein Zertifikat ablehnen, das nicht für host ausgestellt ist. Nach ssl.wrap und vor dem Handshake aufrufen. Ein mit verify = "peer" angelegter Kontext prüft, dass das Zertifikat des Servers auf eine vertrauenswürdige Wurzel zurückgeht, was sagt, dass das Zertifikat echt ist, aber nicht, wem es gehört: Ohne diesen Aufruf wird ein echtes Zertifikat für jeden anderen Namen angenommen, und connection:sni(host) ändert daran nichts, denn es sagt dem Server nur, welches Zertifikat er vorzeigen soll. Mit ihm schlägt der Handshake fehl, wenn das Zertifikat host nicht unter seinen Namen führt, oder unter seinen Adressen, wenn host eine IP-Adresse ist. Ein Platzhalter in einem Zertifikat steht für genau ein ganzes Label.

Parameter:

  • connection — eine Verbindung aus ssl.wrap. Alles andere bricht das Skript ab.

  • host — String, der Name oder die Adresse, zu der verbunden wird.

Rückgabe: true, oder false, wenn der Name nicht gesetzt werden konnte.

Seit: 3.00. Siehe auch: netTrustSystem

Beispiel
-- Das Zertifikat muss zu dem Server gehören, der gefragt wurde.
local wrapped = ssl.wrap(sock, context)
wrapped:sni("scores.example.com")
netTrustHost(wrapped, "scores.example.com")

2.27.2. netTrustSystem

lists, report = netTrustSystem(context)

Fügt die eigenen vertrauenswürdigen Stammzertifikate des Rechners zu einem LuaSec-Client-Kontext hinzu, zusätzlich zu dem, was der Kontext schon enthält (normalerweise das mitgelieferte Singe/cacerts.pem). Eine mit dem Kontext aufgebaute Verbindung wird dann bestätigt, wenn eine der beiden Listen die Wurzel des Servers kennt. Die Liste des Rechners ist, der Reihe nach: die Datei oder das Verzeichnis, das SSL_CERT_FILE oder SSL_CERT_DIR nennt, wenn gesetzt; sonst unter Linux das Bündel der Distribution (der erste der üblichen sechs Orte, der existiert), unter Windows der Stammzertifikatspeicher des Systems oder unter macOS die Vertrauensanker des Systems. cacerts.local.pem im Datenordner wird ebenfalls hinzugefügt, wenn es existiert; die Engine schreibt es nie.

lists ist die Anzahl der Listen, die etwas hinzugefügt haben. report nennt, was befragt wurde, ein what path pro Zeile (what ist system oder local), für eine Fehlermeldung, mit der ein Mensch etwas anfangen kann.

Seit: 3.00. Siehe auch: utilSha256

Beispiel
-- Ein Kontext für jede Anfrage:  das mitgelieferte Bündel, darüber die Wurzeln dieses Rechners.
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. Knoten

Jedes Objekt in einer Szene ist ein Knoten in einem einzigen Baum: Knoten 0 ist die Wurzel, und jeder andere Knoten hängt unter einem Elternknoten. Ein Knoten trägt eine Position, eine Rotation und eine Skalierung relativ zu diesem Elternknoten und kann ein Mesh mit einem Material zeichnen, ein Sprite oder eine Textzeile zeigen oder als Licht leuchten; Kinder erben die Transformation von allem über ihnen. Handles sind Ganzzahlen, die nodeNew, modelInstance und lightNew zurückgeben; ein Handle, dessen Knoten gelöscht wurde, bricht das Skript ab, wenn es wieder übergeben wird, und ein freigegebenes Handle kann von einem späteren nodeNew wiederverwendet werden. Positionen und Größen sind in Szeneneinheiten und Rotationen in Grad, mit +Y nach oben und -Z nach vorn, wie unter 3D-Szenen beschrieben.

2.28.1. nodeNew

node = nodeNew()
node = nodeNew(parent)

Erzeugt einen leeren Knoten im Ursprung seines Elternknotens, ungedreht, mit Skalierung 1, sichtbar, Schatten werfend, ohne Mesh oder Material. Ohne parent kommt der Knoten unter die Wurzel; mit einem wird er das letzte Kind dieses Knotens und bewegt sich von da an mit ihm. Leere Knoten dienen als Drehpunkte und Gruppen: Platziere einen, häng dann Meshes, Lichter oder eine Kamera darunter und beweg die Gruppe als Ganzes.

Rückgabe: Das Knoten-Handle.

Seit: 3.00. Siehe auch: nodeSetMesh, nodeSetParent, nodeDelete, lightNew

Beispiel
-- Ein Geschützturm, dessen Rohr sich am Turm dreht, der sich wiederum auf dem Sockel dreht.
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)

Entfernt den Knoten und alles darunter und gibt jedes Handle in diesem Teilbaum frei; ein Sprite oder Text auf einem davon wird ebenfalls freigegeben. Meshes und Materialien, die die Knoten gezeichnet haben, bleiben unberührt, da andere Knoten sie teilen können. War der gelöschte Knoten die Kamera, fällt die Szene auf die Standardansicht zurück. Der Wurzelknoten kann nicht gelöscht werden; der Versuch bricht das Skript ab.

Seit: 3.00. Siehe auch: nodeNew, nodeSetVisible, meshDelete

Beispiel
-- Schüsse leben zwei Sekunden, dann verschwinden ihre Knoten.
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)

Sucht per Tiefensuche nach dem ersten Knoten namens name, beginnend bei root (der Wurzel der Szene, wenn weggelassen), und prüft root selbst vor seinen Kindern, den Teilbaum jedes Kindes der Reihe nach. Gibt nil zurück, wenn nichts passt. Modellknoten tragen die Namen aus ihrer glTF-Datei, sodass ein Knochen, ein Mesh oder ein in Blender als Markierung platziertes Empty unter der Wurzel der Instanz über diesen Namen gefunden werden kann. Mit nodeSetName gesetzte Namen werden genauso gefunden.

Rückgabe: Ein Knoten-Handle oder nil.

Beispiel
-- Eine Fackel an die rechte Hand des Helden hängen, gefunden über den Namen ihres Knochens.
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)

Die direkten Kinder des Knotens als Tabelle von Handles, in der Reihenfolge, in der sie angehängt wurden; ein Knoten, der einen neuen Elternknoten bekommt, kommt ans Ende von dessen Liste. Enkel sind nicht enthalten; geh rekursiv vor, um einen ganzen Teilbaum abzulaufen. Eine leere Tabelle heißt, dass der Knoten keine Kinder hat.

Rückgabe: Eine Tabelle von Knoten-Handles.

Seit: 3.00. Siehe auch: nodeGetParent, nodeFind, nodeSetParent

Beispiel
-- Jedem Teil einer geladenen Requisite dasselbe abgenutzte Material geben.
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)

Das aktuelle Gewicht eines Morph-Ziels des Meshs des Knotens, angegeben über den Namen oder über die Nummer ab 1 in der Reihenfolge, in der nodeGetMorphs sie auflistet. Der Knoten ist der, der das Mesh trägt, nicht die Wurzel einer Modellinstanz. Ein Name oder eine Nummer, die das Mesh nicht hat, bricht das Skript ab.

Rückgabe: Eine Zahl, 0, bis etwas das Ziel setzt.

Seit: 3.00. Siehe auch: nodeSetMorph, nodeGetMorphs

Beispiel
-- Das Lächeln über mehrere Frames einblenden, statt es schlagartig einzuschalten.
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)

Die Morph-Ziele des Meshs des Knotens als Tabelle von Namen, in der Reihenfolge, in der die Datei sie speichert; diese Reihenfolge ist die Nummerierung, die nodeSetMorph und nodeGetMorph annehmen. Exporter, die keine Namen schreiben, ergeben leere Strings, und diese Ziele lassen sich trotzdem über die Nummer setzen. Ein Knoten ohne Mesh oder ein Mesh ohne Ziele ergibt eine leere Tabelle.

Rückgabe: Eine Tabelle von Strings.

Seit: 3.00. Siehe auch: nodeSetMorph, nodeGetMorph, modelLoad

Beispiel
-- Die Zielnamen des Gesichts einmal Nummern zuordnen, damit die Lippensynchronisation sie indizieren kann.
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)

Der Name des Knotens: was auch immer nodeSetName ihm gegeben hat, bei einem Modellknoten sein glTF-Name, ein leerer String, wenn er keines von beiden hat. Der Wurzelknoten heißt root.

Rückgabe: Ein String.

Seit: 3.00. Siehe auch: nodeSetName, nodeFind

Beispiel
-- Den Knotenbaum eines Modells auf der Konsole ausgeben, während man die Knochennamen herausfindet.
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)

Das Handle des Elternknotens oder nil für die Wurzel. Jeder andere Knoten hat einen Elternknoten, und sei es nur die Wurzel.

Rückgabe: Ein Knoten-Handle oder nil.

Seit: 3.00. Siehe auch: nodeSetParent, nodeGetChildren

Beispiel
-- Von einem angeklickten Mesh-Knoten bis zur Spitze seiner Modellinstanz hinaufsteigen.
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)

Die Position des Knotens relativ zu seinem Elternknoten, wie zuletzt von nodeSetPosition, nodeMove oder der Engine gesetzt (ein Körper, ein Fahrzeug oder eine Animation, die ihn bewegt). Wo der Knoten in der Welt ist, sagt nodeGetWorldPosition.

Rückgabe: Drei Zahlen.

Seit: 3.00. Siehe auch: nodeSetPosition, nodeGetWorldPosition, nodeMove

Beispiel
-- Die Kamera folgt dem Auto, drei Einheiten darüber, drei rechts daneben und neun dahinter.
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)

Die Rotation des Knotens relativ zu seinem Elternknoten als Einheitsquaternion, die Form, in der Modelle und Animationen sie speichern. Damit kopierst du eine Rotation zwischen Knoten oder bewahrst eine Pose ohne die Mehrdeutigkeit von Euler-Winkeln auf.

Rückgabe: Vier Zahlen.

Seit: 3.00. Siehe auch: nodeSetQuaternion, nodeGetRotation

Beispiel
-- Die Pose der Tür vor dem Ragdoll-Test merken und sie danach zurücksetzen.
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)

Die Rotation des Knotens relativ zu seinem Elternknoten als Euler-Winkel in Grad, auf dieselbe Weise zerlegt, wie nodeSetRotation sie zusammensetzt: um Y gedreht, dann um X geneigt, dann um Z gerollt. Die Winkel beschreiben dieselbe Rotation, die gesetzt wurde, müssen aber nicht dieselben Zahlen sein: X kommt zwischen -90 und 90 zurück, und wenn es 90 oder -90 erreicht, wird die Verdrehung Y zugeschlagen und Z als 0 gemeldet.

Rückgabe: Drei Zahlen.

Seit: 3.00. Siehe auch: nodeSetRotation, nodeGetQuaternion

Beispiel
-- Ein Kompass im Overlay nach dem Kurs des Schiffs.
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)

Die eigene Skalierung des Knotens pro Achse, wie von nodeSetScale gesetzt (1, 1, 1 bei einem neuen Knoten). Die Skalierungen der Elternknoten sind nicht eingerechnet.

Rückgabe: Drei Zahlen.

Seit: 3.00. Siehe auch: nodeSetScale

Beispiel
-- Das Power-up in jedem Frame ein wenig zur vollen Größe wachsen lassen.
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)

Wo der Ursprung des Knotens in Weltkoordinaten liegt, mit der Transformation jedes Elternknotens angewandt, Stand des zuletzt gerenderten Frames. In diesem Frame gemachte Änderungen (deine oder die eines Körpers) zeigen sich nach dem nächsten Rendern, und ein in diesem Frame erzeugter Knoten meldet bis dahin 0, 0, 0. Das ist die Position, die du sceneProject oder einer Abstandsprüfung übergibst.

Rückgabe: Drei Zahlen.

Seit: 3.00. Siehe auch: sceneProject, nodeLookAt, nodeGetPosition

Beispiel
-- Ein Namensschild im Overlay über der Ente, wohin die Physik sie auch gebracht hat.
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)

Dreht den Knoten so, dass sein eigenes -Z auf eine Position in der Welt zeigt, und hält sein +Y so nah an der Aufwärtsrichtung der Welt, wie die Richtung es zulässt. Das wollen Kameras und Lichter, und es dient ebenso einem Geschützturm oder einem Kopf, der ein Ziel verfolgt. Nur die Rotation des Knotens ändert sich; seine Position bleibt. Fällt das Ziel mit der Position des Knotens zusammen, ändert sich nichts.

Hinweise: Der Weltpunkt wird mit der Transformation des Elternknotens aus dem zuletzt gerenderten Frame in die Koordinaten des Elternknotens umgerechnet; ein Knoten, dessen Elternknoten sich in eben diesem Frame bewegt hat, zielt von dort, wo der Elternknoten war.

Seit: 3.00. Siehe auch: cameraSet, lightNew, nodeSetRotation

Beispiel
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)

Bewegt den Knoten entlang seiner eigenen Achsen: Der Versatz wird mit der aktuellen Rotation des Knotens gedreht und zu seiner Position addiert, sodass nodeMove(ship, 0, 0, -0.1) das Schiff vorwärts fährt, wohin es auch zeigt, und nodeMove(ship, 0.1, 0, 0) es seitlich nach rechts versetzt. Für einen absoluten Ort in den Koordinaten des Elternknotens nimm nodeSetPosition.

Seit: 3.00. Siehe auch: nodeSetPosition, nodeRotate

Beispiel
-- Panzersteuerung:  mit links und rechts drehen, mit hoch und runter fahren.
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)

Dreht den Knoten um die angegebenen Grad um seine eigenen Achsen, zusätzlich zu seiner aktuellen Rotation: nodeRotate(wheel, 5, 0, 0) in jedem Frame lässt das Rad um sein eigenes X kreisen, wie auch immer die Achse geneigt ist. Die drei Winkel werden so kombiniert, wie nodeSetRotation sie kombiniert (Y, dann X, dann Z), bevor sie angewandt werden. Positive Winkel drehen gegen den Uhrzeigersinn, wenn man entlang der Achse zum Ursprung blickt.

Seit: 3.00. Siehe auch: nodeSetRotation, nodeMove, nodeSetQuaternion

Beispiel
-- Das Logo dreht sich pro Frame um ein halbes Grad um seine eigene Hochachse.
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)

Dreht den Knoten in jedem Frame zur Kamera hin. BILLBOARD_ALL richtet ihn frontal zu ihr aus und übernimmt alle drei Achsen von der Kamera; BILLBOARD_Y dreht nur um die Hochachse der Welt, sodass der Knoten aufrecht bleibt (Bäume, Lebensbalken); BILLBOARD_NONE, der Standard, dreht gar nicht. Weltposition und Skalierung des Knotens bleiben erhalten, und seine eigene Rotation wird ignoriert, solange ein Modus gesetzt ist. Jeder andere Wert bricht das Skript ab. Es funktioniert bei Meshes ebenso wie bei Sprites und Text und dreht sich zu der Kamera, die gerade zeichnet: Auch eine Ansicht sieht das Billboard von vorn, während sein Schatten der Kamera des Fensters folgt.

Seit: 3.00. Siehe auch: nodeSetSprite, nodeSetText, cameraSet

Beispiel
-- Ein Name über dem Fuchs, frontal zur Kamera, und ein Kisten-Symbol, das
-- sich nur um seine eigene Hochachse dreht.
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)

Wählt, wo im Fenster der Knoten gezeichnet wird. LAYER_SCENE, der Standard, zeichnet ihn in der Szene unter dem Overlay; LAYER_FRONT zeichnet ihn nach dem Overlay, mit derselben Kamera und denselben Lichtern, in eine eigene transparente Ebene. Ein Knoten in der vorderen Ebene nimmt seine Kinder mit, gleich wie sie selbst eingestellt sind. Jeder andere Wert bricht das Skript ab. Siehe Vor dem Overlay.

Seit: 3.00. Siehe auch: sceneEnable, nodeSetVisible, emitterSetLayer

Beispiel
-- Das Schiff des Spielers steht auf dem 2D-Kartenbildschirm, solange er offen ist, und kehrt
-- in die Welt zurück, wenn er sich schließt.
function showMap(open)
    nodeSetLayer(ship, open and LAYER_FRONT or LAYER_SCENE)
end

2.28.19. nodeSetMaterial

nodeSetMaterial(node, material)
nodeSetMaterial(node, nil)

Legt ein Material auf das Mesh, das der Knoten hat, und behält das Mesh. nil entfernt es und lässt das Standardaussehen: weiß, halb rau, ohne Textur. Damit gestaltest du ein Teil eines Modells um, wechselst ein Hervorhebungsmaterial ein und aus oder kleidest ein Mesh ein, das die Engine für dich gemacht hat, etwa die Röhre eines Seils aus softNew. Ein Material-Handle, das nicht existiert, bricht das Skript ab.

Seit: 3.00. Siehe auch: nodeSetMesh, materialNew, softNew

Beispiel
-- Das Seil hängt am Kran; die Engine macht seine Röhre, wir kleiden sie ein.
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)

Gibt dem Knoten ein Mesh zum Zeichnen, mit einem Material oder, wenn weggelassen, dem Standardaussehen (weiß, halb rau). Beide Argumente müssen gültige Handles sein; ein fehlendes Mesh oder Material bricht das Skript ab. Jeder Knoten kann zeichnen, auch einer innerhalb einer Modellinstanz, und beliebig viele Knoten können sich ein Mesh teilen. Die Morph-Gewichte des Knotens werden auf die Ziele des neuen Meshs bemessen und beginnen bei 0.

Seit: 3.00. Siehe auch: meshBox, materialNew, nodeSetMaterial, nodeSetVisible

Beispiel
-- Eine Autokarosserie mit vier Rädern, jedes ein Zylinder, so gedreht, dass sein X die Achse ist.
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)

Legt fest, wie viel eines Morph-Ziels (Blend Shape) das Mesh des Knotens zeigt, über den Namen oder über die Nummer ab 1; Gewichte liegen meist zwischen 0 und 1, und mehrere Ziele addieren sich. Der Knoten ist der, der das Mesh trägt, bei einem Modell also ein Kind der Instanzwurzel (nodeFind mit dem Namen des Meshs oder nodeGetChildren). Ein Ziel, das das Mesh nicht hat, bricht das Skript ab. Eine Animation mit einem Gewichtskanal schreibt die Gewichte in jedem Frame, solange sie läuft, und überschreibt, was du gesetzt hast.

Hinweise: Bis zu acht Ziele mit einem Gewicht ungleich null wirken pro Mesh in einem Frame; bei mehr werden die acht mit dem größten Betrag des Gewichts verwendet.

Seit: 3.00. Siehe auch: nodeGetMorph, nodeGetMorphs, animationPlay

Beispiel
-- Lippensynchronisation aus einer Tabelle von Mundöffnungen pro Disc-Frame.
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)

Benennt den Knoten, damit nodeFind ihn später finden kann, und ersetzt jeden Namen, den er hatte (den glTF-Namen eines Modellknotens eingeschlossen). Namen müssen nicht eindeutig sein; nodeFind gibt den ersten Treffer in der Reihenfolge der Tiefensuche zurück.

Seit: 3.00. Siehe auch: nodeFind, nodeGetName

Beispiel
-- Erzeugte Kisten bekommen Namen, damit das Level-Skript sie über ihren Platz findet.
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)

Verschiebt den Knoten mit seinem ganzen Teilbaum unter einen anderen Elternknoten, als dessen letztes Kind. Lokale Position, Rotation und Skalierung des Knotens bleiben, wie sie sind, er sitzt nun also mit diesem Versatz zum neuen Elternknoten und bewegt sich mit ihm; übergib 0, um ihn zur Wurzel zurückzubringen. Die Wurzel kann nicht verschoben werden, und ein Knoten kann nicht unter sich selbst oder einen seiner eigenen Nachkommen; beides bricht das Skript ab.

Seit: 3.00. Siehe auch: nodeGetParent, nodeNew, nodeSetPosition

Beispiel
-- Eine Kiste aufheben:  Sie fährt von nun an in der Hand mit und wird später abgesetzt.
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)

Setzt den Knoten auf x, y, z in den Koordinaten seines Elternknotens; für einen Knoten unter der Wurzel sind das Weltkoordinaten. Kinder kommen mit. Ein Knoten mit einem dynamischen Körper wird danach von der Physik bewegt; setz seine Position vor bodyNew oder teleportiere ihn über die Körper-Aufrufe.

Seit: 3.00. Siehe auch: nodeMove, nodeGetPosition, nodeSetRotation

Beispiel
-- Kisten, entlang eines Grats fallen gelassen, jede sechs Einheiten über dem Boden an ihrer Stelle.
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)

Setzt die Rotation des Knotens relativ zu seinem Elternknoten als Quaternion, für Werte, die aus nodeGetQuaternion, einem Modell oder deiner eigenen Rechnung stammen. Die Quaternion wird beim Übernehmen normalisiert, muss also nicht die Länge eins haben.

Seit: 3.00. Siehe auch: nodeSetRotation, nodeGetQuaternion

Beispiel
-- Der Geist kopiert die Pose des Helden genau, einen Takt später.
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)

Setzt die Rotation des Knotens relativ zu seinem Elternknoten als Euler-Winkel in Grad und ersetzt, was er hatte: Der Knoten wird zuerst um sein Y gedreht (Gieren), dann um sein X geneigt (Nicken), dann um sein Z gerollt. Positive Winkel drehen gegen den Uhrzeigersinn, wenn man entlang der Achse zum Ursprung blickt, sodass nodeSetRotation(plane, 90, 0, 0) eine Bodenebene aufrichtet, bis sie nach +Z zeigt.

Seit: 3.00. Siehe auch: nodeRotate, nodeSetQuaternion, nodeLookAt

Beispiel
-- Ein Monitorbildschirm auf einem Ständer, der zur Kamera bei +Z zeigt.
local monitor = nodeNew()
nodeSetMesh(monitor, meshPlane(2.0, 1.5), screen)
nodeSetPosition(monitor, -3, 2.1, 1.06)
nodeSetRotation(monitor, 90, 0, 0)
-- Eine Rampe, um 25 Grad um Z geneigt.
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)

Skaliert den Knoten und alles darunter, gleichmäßig mit einem Faktor oder pro Achse mit dreien. Geladene Modelle sind oft in Zentimetern oder Metern; skaliere die Instanzwurzel einmal passend zu deiner Szene und platziere Dinge darunter in den eigenen Einheiten des Modells. Sprites und Text auf dem Knoten werden ebenfalls skaliert, zusätzlich zu ihrer height.

Seit: 3.00. Siehe auch: nodeGetScale, modelInstance

Beispiel
-- Der Fuchs ist in Zentimetern modelliert:  ein Hundertstel bringt ihn auf Meter.
local fox = modelInstance(foxModel)
nodeSetParent(fox, player)
nodeSetScale(fox, 0.01)
nodeSetRotation(fox, 0, 90, 0)
-- Eine abgeflachte Kugel als Pfütze.
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)

Ob das Mesh des Knotens in Shadow Maps gezeichnet wird; true bei jedem neuen Knoten. Schalte es für das Mesh um ein Licht herum aus (eine Glühbirne, eine Flamme), damit es sein eigenes Licht nicht abschattet, und für alles, was leuchtet. Der Knoten zeichnet weiterhin und empfängt weiterhin Schatten von anderen. Es gilt nur für den Knoten, nicht für seine Kinder.

Seit: 3.00. Siehe auch: lightSetShadow, nodeSetVisible, materialSetUnlit

Beispiel
-- Eine Glühbirne in ihrem Schirm:  Das Glas wirft keinen Schatten, der Schirm schon.
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)

Zeigt ein geladenes Sprite auf dem Knoten: ein Quad, height Welteinheiten hoch (Standard 1) und so breit, wie das Seitenverhältnis des Bilds es ergibt, nach dem Alpha des Bilds geblendet, von beiden Seiten gezeichnet und von der Szene beleuchtet, sofern lit nicht false ist. Jeder Frame eines animierten Sprites wird hochgeladen, und der erste wird gezeigt; nodeSetSpriteFrame wählt einen anderen. Das Quad wird zum Mesh des Knotens mit einem eigenen Material und ersetzt jedes Mesh, Sprite oder jeden Text, den er hatte; nil oder kein zweites Argument nimmt das Bild ab und lässt den Knoten leer. Es bricht das Skript ab, wenn der 3D-Renderer nicht verfügbar ist.

Parameter:

  • sprite — ein Handle von spriteLoad oder nil zum Entfernen.

  • height — die Höhe des Quads in Welteinheiten, Standard 1; die Skalierung des Knotens multipliziert sie.

  • lit — true (Standard) schattiert das Bild mit den Lichtern und Schatten der Szene; false zeigt es, wie es ist.

Beispiel
-- Ein Kisten-Symbol, das über dem Fuchs schwebt und sich zum Spieler dreht.
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)
-- Ein unbeleuchtetes Leuchten, das im Schatten genauso wirkt.
local flare = nodeNew(torchTip)
nodeSetSprite(flare, spriteLoad("flare.png"), 0.3, false)
nodeSetBillboard(flare, BILLBOARD_ALL)

2.28.30. nodeSetSpriteFrame

nodeSetSpriteFrame(node, frame)

Welcher Frame des animierten Sprites des Knotens gezeigt wird, gezählt ab 0. Das Sprite des Knotens läuft nicht von selbst weiter; treib es aus onOverlayUpdate an. Ein Knoten ohne Sprite oder ein Frame, den es nicht hat, bricht das Skript ab; Text und ein unbewegtes Sprite haben nur Frame 0.

Seit: 3.00. Siehe auch: nodeSetSprite, spriteLoad

Beispiel
-- Ein Lagerfeuer-Sprite, das seine Frames mit zehn pro Sekunde durchläuft.
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)

Zeigt eine Textzeile auf dem Knoten, gerendert in der gewählten Schriftart (fontSelect) in der aktuellen Qualität (fontQuality) in der Vordergrundfarbe (colorForeground), auf einem Quad, height Welteinheiten hoch (Standard 1) und so breit, wie der gerenderte Text es ergibt. Er ist unbeleuchtet, geblendet und von beiden Seiten gezeichnet: Namensschilder, Schilder, ein Punktestand über einem Tisch. Wie ein Sprite wird er zum Mesh des Knotens und ersetzt jedes Mesh, Sprite oder jeden Text dort; ruf es erneut auf, um den Text zu ändern, und mit nil oder ohne zweites Argument, um ihn abzunehmen. Ohne gewählte Schriftart oder ohne den 3D-Renderer bricht es das Skript ab.

Beispiel
-- Ein festes Schild an der Lampe und ein Punktestand, der sich aktualisiert, wenn er sich ändert.
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)

Versteckt oder zeigt den Knoten und alles darunter; das eigene Flag eines Kindes gilt weiterhin, wenn sein Elternknoten wieder gezeigt wird. Versteckte Meshes werden nicht gezeichnet, und versteckte Lichter hören auf zu leuchten. Damit hältst du eine Markierung oder eine Ersatz-Requisite bereit, ohne sie zu löschen und neu zu bauen.

Seit: 3.00. Siehe auch: nodeSetMesh, nodeDelete

Beispiel
-- Eine Markierung, die dort erscheint, wo der Ball zuletzt den Schläger getroffen hat.
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

Das Overlay ist eine 32-Bit-RGBA-Fläche, die in jedem Frame über das Video gelegt wird; alles 2D-Zeichnen landet darauf. Seine Koordinaten sind die mit overlaySetResolution gesetzte Overlay-Auflösung, standardmäßig die halbe Breite und Höhe des Videos, und werden bei der Anzeige auf das Fenster skaliert. Zeichne aus onOverlayUpdate (oder im Thread-Modell aus singeMain) und gib OVERLAY_UPDATED zurück, wenn sich etwas geändert hat. Die overlay*-Grundformen zeichnen ein Pixel breite Umrisse in der aktuellen Vordergrundfarbe und schneiden stillschweigend ab, was außerhalb der Fläche liegt. overlayPrint ist die Ausnahme: Es nimmt Koordinaten in Zeichenzellen und kopiert die eingebaute Konsolenschrift unverändert, ohne die Farbeinstellungen zu beachten.

2.29.1. overlayBanner

overlayBanner(text [, height])

Hypseus-Erweiterung. Zeigt eine kurze Meldung über dem Bild für etwa dreißig gezeichnete Frames und nimmt sie dann wieder weg. height ist, wo sie sitzt, in Prozent von oben über das Bild, von 1 bis 95; der Standard ist 47, der von Hypseus selbst, und eine Zahl außerhalb dieses Bereichs wird durch den Standard ersetzt statt abgelehnt.

Eine Meldung mit mehr als 60 Zeichen wird ignoriert, genau wie Hypseus sie ignoriert. Das Banner wird von demselben mitgelieferten Dokument gezeichnet, das die Untertitel verwenden (Singe/subtitle.rml, gestaltet durch Singe/subtitle.rcss), es sieht also aus wie ein Untertitel und wird mit ihnen gestaltet; solange es zu sehen ist, nimmt es den Platz jedes Untertitels ein, und der Untertitel kehrt zurück, wenn seine Zeit abgelaufen ist. Der Text wird als Text gezeichnet, sodass <, > und & als sie selbst auf dem Bildschirm ankommen.

Parameter:

  • text — String; bis zu 60 Zeichen.

  • height — optionale Zahl; 1 bis 95, ein Prozentwert von oben über das Bild. Standard 47.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: srtLoad, Untertitel, overlayPrint

Beispiel
-- Dem Spieler sagen, was gerade passiert ist, ohne dafür ein HUD zu bauen.
overlayBanner("Extra life!", 20)

2.29.2. overlayBox

overlayBox(x1, y1, x2, y2)

Zeichnet den Umriss des achsenparallelen Rechtecks mit den gegenüberliegenden Ecken (x1, y1) und (x2, y2) als vier ein Pixel breite Linien in der Vordergrundfarbe. Beide Ecken gehören dazu und können in beliebiger Reihenfolge angegeben werden. Eine gefüllte Variante gibt es nicht; füll das ganze Overlay mit overlayClear auf einer Hintergrundfarbe oder eine Fläche mit einem gestreckten Sprite.

Seit: 2.00 Siehe auch: overlayLine, colorForeground, overlayClear

Beispiel
-- Das Overlay rot umrahmen und jeden Plattformblock umreißen.
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)

Zeichnet einen ein Pixel breiten Kreisumriss in der Vordergrundfarbe, zentriert auf (x, y), mit dem Mittelpunktalgorithmus. Ein Radius von 0 oder weniger zeichnet nichts. Koordinaten und Radius sind Ganzzahlen in Overlay-Einheiten; Nachkommastellen werden abgeschnitten.

Parameter:

  • x, y — Mittelpunkt in Overlay-Koordinaten.

  • radius — Radius in Overlay-Einheiten.

Seit: 2.00 Siehe auch: overlayEllipse, overlayPlot, colorForeground

Beispiel
-- Ein Fadenkreuz, das rot wird, solange der Spieler getroffen ist.
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()

Füllt das ganze Overlay mit der aktuellen Hintergrundfarbe. Ist die Farbe dieselbe wie beim letzten Löschen, wird nur das neu gefüllt, was seitdem gezeichnet wurde, sodass das Löschen eines Overlays mit ein paar Textzeilen fast nichts kostet, wie groß es auch ist. Der Hintergrund beginnt als transparentes Schwarz, ohne einen Aufruf von colorBackground löscht dies das Overlay also zurück zu unsichtbar, und das Video scheint durch. Ein teilweise deckender Hintergrund dämpft das Video; ein vollständig deckender verdeckt es. Die meisten Spiele rufen es als Erstes in onOverlayUpdate auf. Argumente werden ignoriert.

Seit: 1.x Siehe auch: colorBackground, onOverlayUpdate

Beispiel
-- Das pausierte Video hinter dem Service-Menü auf halbe Helligkeit dämpfen.
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)

Zeichnet einen ein Pixel breiten Ellipsenumriss in der Vordergrundfarbe, einbeschrieben in das achsenparallele Rechteck mit den gegenüberliegenden Ecken (x1, y1) und (x2, y2). Die Ecken können in beliebiger Reihenfolge angegeben werden. Ein Rechteck mit gleicher Breite und Höhe ergibt einen Kreis, das ist also auch der Weg, einen Kreis aus seinem umschließenden Rechteck statt aus seinem Mittelpunkt zu zeichnen.

Seit: 2.00 Siehe auch: overlayCircle, overlayBox

Beispiel
-- Den gewählten Automaten mit einem Oval hervorheben, das zu seinem Feld passt.
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()

Gibt die Höhe einer Zeichenzelle der eingebauten Konsolenschrift in Pixeln zurück, die Einheit, in der overlayPrint zählt. Die Konsolenschrift ist ein einziges eingebettetes Bild mit 256 Glyphen, das einmal geladen wird, bevor irgendein Skript läuft, der Wert ändert sich also nie, solange das Programm läuft. Argumente werden ignoriert.

Rückgabe: ganzzahlige Höhe einer Zelle in Pixeln.

Beispiel
-- Wie viele Zeilen Konsolentext passen, wie groß das Overlay auch ist.
ROWS = overlayGetHeight() // overlayGetFontHeight()
overlayPrint(0, ROWS - 1, "along the bottom")

2.29.7. overlayGetFontWidth

result = overlayGetFontWidth()

Gibt die Breite einer Zeichenzelle der eingebauten Konsolenschrift in Pixeln zurück, die Einheit, in der overlayPrint zählt. Nimm sie mit overlayGetWidth, um auszurechnen, wie viele Spalten passen, oder um Konsolentext an etwas auszurichten, das in Pixeln gezeichnet ist. Teile mit // statt /: Die gewöhnliche Division von Lua ergibt eine Zahl mit Nachkommastellen, und eine Zellenposition muss ganzzahlig sein. Argumente werden ignoriert.

Rückgabe: ganzzahlige Breite einer Zelle in Pixeln.

Beispiel
-- Eine Zeile Konsolentext zentrieren, ohne die Spaltenzahl fest einzutragen.
local columns = overlayGetWidth() // overlayGetFontWidth()
local text    = "GAME OVER"

overlayPrint((columns - #text) // 2, 10, text)

2.29.8. overlayGetHeight

result = overlayGetHeight()

Gibt die Höhe der Overlay-Fläche in Overlay-Einheiten zurück: den zuletzt an overlaySetResolution übergebenen Wert oder, vor jedem Aufruf, die halbe Videohöhe. Lies sie beim Start, nach dem Setzen der Auflösung, um Positionen nach der tatsächlichen Zeichenfläche anzuordnen. Argumente werden ignoriert.

Rückgabe: ganzzahlige Höhe.

Seit: 1.x Siehe auch: overlayGetWidth, overlaySetResolution

Beispiel
-- Das Textfeld am unteren Rand verankern, wie groß das Overlay auch ist.
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()

Gibt die Breite der Overlay-Fläche in Overlay-Einheiten zurück: den zuletzt an overlaySetResolution übergebenen Wert oder, vor jedem Aufruf, die halbe Videobreite. Nimm sie, um Elemente rechtsbündig auszurichten oder zu zentrieren, statt eine Breite fest einzutragen. Argumente werden ignoriert.

Rückgabe: ganzzahlige Breite.

Seit: 1.x Siehe auch: overlayGetHeight, overlaySetResolution

Beispiel
-- Das Marquee rechtsbündig ausrichten und den Titel zentrieren, unabhängig von der Auflösung.
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)

Zeichnet eine ein Pixel breite Bresenham-Linie in der Vordergrundfarbe von (x1, y1) nach (x2, y2), beide Endpunkte eingeschlossen. Pixel außerhalb des Overlays werden verworfen, Endpunkte dürfen also außerhalb der Fläche liegen. Koordinaten werden auf Ganzzahlen abgeschnitten.

Seit: 2.00 Siehe auch: overlayPlot, overlayBox, colorForeground

Beispiel
-- Den Laser von der Waffe zum Zielpunkt zeichnen und ein einfaches Zielkreuz.
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)

Setzt ein Overlay-Pixel auf die Vordergrundfarbe. Ein Punkt außerhalb der Fläche wird ignoriert. Jeder Aufruf sperrt und entsperrt das Overlay, Tausende Punkte pro Frame aus Lua zu setzen ist also langsam; nimm ein Sprite für alles mit Struktur und heb dies für Sterne, Funken und Debugging-Markierungen auf.

Seit: 2.00 Siehe auch: overlayLine, colorForeground

Beispiel
-- Ein langsam funkelndes Sternenfeld hinter dem Titel.
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)

Gibt einen String in der eingebauten Konsolenschrift fester Breite der Engine aus. Anders als bei jedem anderen Zeichenaufruf ist die Position eine Zeichenzelle: Die Engine multipliziert column und row mit Breite und Höhe der Glyphen, sodass (0, 0) die Zelle oben links ist und (1, 0) eine Glyphe weiter rechts. Glyphen werden unverändert aus dem Schriftbild kopiert; die aktuellen Vorder- und Hintergrundfarben werden nicht angewandt, und nur der eigene Hintergrund der Schrift ist transparent. Jedes Byte des Strings wählt eine der 256 Glyphen der Schrift, der Text wird also als Bytes behandelt, nicht als UTF-8. Zeichen, die über den rechten Rand des Overlays hinausliefen, werden verworfen, und Text, der jenseits des Rands beginnt, zeichnet nichts.

Parameter:

  • column, row — Zeichenzelle, 0 oben links.

  • text — der auszugebende String.

Hinweise: Die Konsolenschrift ist für Diagnose- und Service-Bildschirme gedacht. Nimm fontPrint oder fontToSprite für farbigen oder proportionalen Text. Die Größe einer Zelle in Pixeln ist overlayGetFontWidth mal overlayGetFontHeight, also ist overlayGetWidth() // overlayGetFontWidth() die Anzahl der Spalten, die passen.

Seit: 1.x Siehe auch: fontPrint, overlayClear, colorBackground

Beispiel
-- Diagnose in der Ecke, während ein Download fertig wird.
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)

Hypseus-Erweiterung. Zeigt das Overlay in Grau: Vor jedem Hochladen wandelt die Engine eine Kopie davon mit den Gewichten nach BT.601 in Luma um und lässt den Alphakanal, wie er ist (Hypseus wendet darauf einen Schwellenwert an). Die eigenen Pixel des Overlays bleiben farbig, nichts, was das Skript zurückliest, ändert sich also, und das Zeichnen geht wie gewohnt weiter. Kombiniere es mit vldpSetMonochrome für einen Schwarzweißmodus. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpSetMonochrome, overlayClear

Beispiel
-- Eine Einstellung steuert sowohl die Disc als auch das Overlay.
function applyChroma(color)
    vldpSetMonochrome(not color)
    overlaySetMonochrome(not color)
end

2.29.14. overlaySetResolution

overlaySetResolution(width, height)

Ersetzt das Overlay durch eine neue Fläche der angegebenen Größe und verwirft alles bisher Gezeichnete. Von da an ist jede Overlay-Koordinate, jede Sprite-Position und jedes Ergebnis von overlayGetWidth oder overlayGetHeight im neuen Koordinatenraum, den die Engine bei der Anzeige auf das Fenster skaliert. Ruf es einmal beim Start auf, vor dem Zeichnen; der Standard ist in jeder Dimension die halbe Videoauflösung. Eine Breite oder Höhe von 0 oder weniger beendet das Skript mit einem Fehler. Höhere Auflösungen bringen feinere Platzierung und schärferen Text für mehr Kompositionsarbeit pro Frame; die native Größe der Disc aus discGetWidth und discGetHeight ist die übliche Wahl.

Parameter:

  • width — neue Overlay-Breite in Pixeln, größer als 0.

  • height — neue Overlay-Höhe in Pixeln, größer als 0.

Seit: 2.00 Siehe auch: overlayGetWidth, overlayGetHeight, discGetWidth

Beispiel
-- An die Disc anpassen und das Menü dann in diesem Koordinatenraum anordnen.
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()

Hypseus-Erweiterung, angenommen und ignoriert. Hypseus blittet sein Overlay mit einem Schwellenwert von 128 auf dem Alphakanal, sodass ein halb transparentes Pixel entweder voll deckend oder verschwunden ist, und dies bittet es, die Fläche stattdessen so hochzuladen, wie sie ist, und richtig zu blenden. Das Overlay von Singe war schon immer volles RGBA mit echtem Alpha pro Pixel, was dies verlangt, gilt also bereits.

Rückgabe: nichts.

Seit: 3.00

2.29.16. setOverlayLinearScale

setOverlayLinearScale(enabled)

Hypseus-Erweiterung. Wählt, wie das Overlay auf dem Weg ins Fenster gefiltert wird. Mit true, dem Standard und dem, was ein Neuladen wiederherstellt, wird es linear abgetastet, sodass ein Overlay mit niedriger Auflösung weich wird statt klotzig; mit false wird das nächste Pixel genommen, was Pixel-Art, ein Pixel breite Umrisse und kleinen Text scharf hält. Linear ist der Standard, weil jede Version von Singe das Overlay so gezeichnet hat; Hypseus nimmt standardmäßig stattdessen das nächste Pixel, ein von Hypseus übernommenes Spiel, das dies nie aufruft, sieht also etwas weicher aus, bis es das tut. Am Zeichnen ändert sich nichts, nur die abschließende Skalierung von der Overlay-Auflösung auf das Fenster, sodass alles auf dem Overlay — die Grundformen, Schriften, Sprites und die 3D-Ebene — gemeinsam durch den einen Filter geht und das Disc-Bild dahinter unberührt bleibt. Die Einstellung übersteht overlaySetResolution, das das Overlay ersetzt. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: overlaySetResolution, spriteQuality

Beispiel
-- Ein 320x240-Overlay auf einem 4K-Bildschirm; der gemalte Titel weich, die Pixelgrafik des Spiels scharf.
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)

Hypseus-Erweiterung. Wählt, ob das Overlay und die über das Bild gezeichneten GUIs über dem Bezel-Artwork liegen oder darunter. Nur Artwork, das vor dem Bild gezeichnet wird (--bezelflip), liegt überhaupt je über ihnen, bei Artwork dahinter — dem Standard — ändert dies also nichts. false ist die Einstellung, mit der ein Spiel beginnt, und der eigene Standard von Hypseus. Sie bleibt gespeichert, bis das Skript neu lädt.

Die Einstellung wird nur festgehalten, solange Artwork geladen ist; ohne tut der Aufruf nichts und antwortet false und "0", genau wie Hypseus. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean; true legt das Overlay und die GUIs über das Artwork.

Rückgabe: Boolean, ob Artwork geladen ist, und seine Kennung als String ("0", wenn keines geladen ist).

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: mainBezelLoaded, guiDrawScreen, Bezels

Beispiel
-- Der Rahmen des Automaten überlappt das Bild, aber die Punktezeile muss lesbar bleiben.
if mainBezelLoaded() then
    setOverlayOnTop(true)
end

2.29.18. setOverlayOpacity

setOverlayOpacity(alpha)

Hypseus-Erweiterung. Wie deckend das ganze Overlay ist, von 0 (unsichtbar) bis 255 (so, wie das Spiel es gezeichnet hat). Es multipliziert das Alpha, das die eigenen Pixel des Overlays schon tragen, sodass ein halb transparentes Sprite halb so deckend bleibt wie der Rest; es ändert den Inhalt des Overlays nicht, und nichts muss neu gezeichnet werden.

Der Wert wird auf 0 bis 255 begrenzt statt abgelehnt, und ein Skript beginnt bei 255. Er bleibt gespeichert, bis das Skript neu lädt, und übersteht eine Änderung der Overlay-Auflösung.

Die GUIs, die 3D-Szene und das Bezel-Artwork werden getrennt gezeichnet und sind nicht betroffen.

Parameter:

  • alpha — Zahl; 0 bis 255.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: setOverlayLinearScale, overlaySetResolution

Beispiel
-- Das ganze Head-up-Display über eine halbe Sekunde ausblenden.
local fade = 255
function onOverlayUpdate()
    fade = math.max(0, fade - 8)
    setOverlayOpacity(fade)
    return OVERLAY_UPDATED
end

2.30. Physik

Aufrufe auf Ebene der Welt: die Strahlabfrage, die Schwerkraft, der 2D-Modus, das Pausieren und das Debug-Zeichnen. Die Physik wird mit der Engine initialisiert, vor dem ersten bodyNew gibt es also nichts einzuschalten; die Welt rechnet sechzig Schritte pro Sekunde nach der Uhr, nach den Animationen und bevor die Szene rendert. Positionen und Abstände sind in Welteinheiten und die Schwerkraft in Einheiten pro Sekunde zum Quadrat. Wie Körper, Knoten und der Frame zusammenpassen, steht unter Physik in Spieleentwicklung.

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)

Findet den ersten Körper entlang eines Strahls von (x, y, z) in Richtung (dx, dy, dz), innerhalb von maxDistance Welteinheiten. Die Richtung wird normalisiert, jede Länge funktioniert also, aber eine Nullrichtung trifft nichts. Trigger und Spielfiguren werden wie jeder andere Körper getroffen; eine Spielfigur wird über ihren Knoten gemeldet. Liefert sceneUnproject zwei Punkte entlang der Maus, ist das die Objektauswahl per Maus; senkrecht nach unten von einem Punkt aus ist es eine Höhenmessung.

Parameter:

  • x, y, z — der Start des Strahls in Weltkoordinaten.

  • dx, dy, dz — seine Richtung; nur die Richtung zählt.

  • maxDistance — wie weit gesucht wird; Standard 1000, und 0 oder weniger, oder nil, bedeutet den Standard.

  • ignoredNodes — optionale Liste von bis zu 4096 nicht negativen Knoten-Handles, die von dieser Abfrage ausgeschlossen sind. Ausgeschlossen wird genau der Knoten, den ein Strahl zurückgibt, nimm also bei Bedarf die Knoten der Kindkörper mit auf. Körper behalten ihren aktivierten Zustand und ihre Kontakte. Ein Strahl, der in einem ignorierten Körper beginnt, kann den nächsten Körper ganz normal treffen. Eine leere Liste, oder nil, lässt die Abfrage ungefiltert; veraltete Handles haben keine Wirkung.

Rückgabe: Der Knoten des Körpers, der Trefferpunkt und die Oberflächennormale dort oder ein einzelnes nil, wenn nichts getroffen wird.

Seit: 3.00. Siehe auch: sceneUnproject, bodyApplyImpulse, lineDraw

Beispiel
-- Die Markierung auf den ebenen Boden setzen, der gerade unter dem Cursor liegt.
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
Beispiel
-- Ein Schuss aus der Brust der Spielfigur.  Der Strahl beginnt im eigenen Körper der Spielfigur und
-- geht durch den Schild, den sie trägt; beide bleiben also außen vor, und an keinem der Körper ändert sich etwas.
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)

Mit true bewegen sich von nun an erzeugte Körper nur in X und Y und drehen sich nur um Z: die Welt eines 2D-Spiels, meist in Overlay-Koordinaten mit einer Schwerkraft in Richtung +Y, sodass Dinge den Bildschirm hinunterfallen. Bereits erzeugte Körper behalten ihre Freiheit, ruf es also vor jedem bodyNew auf; false kehrt für danach erzeugte Körper zu vollem 3D zurück. Spielfiguren sind anders: Solange der Modus an ist, läuft jede Spielfigur, wann immer sie erzeugt wurde, entlang X mit auf 0 gehaltenem Z, und playerMove nimmt einen einzigen Wert. Die 2D-Welt funktioniert ohne GPU, auch auf dem Raspberry Pi 3.

Seit: 3.00. Siehe auch: physicsSetGravity, bodyNew, playerMove

Beispiel
-- Die Welt eines Plattformspiels in Overlay-Pixeln: Schwerkraft den Bildschirm hinunter, ein Boden und Wände.
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)

Zeichnet in jedem Frame, solange die Maske gesetzt ist, als Linien über die Szene, was die Simulation enthält: DEBUG_SHAPES die Form jedes bewegten Körpers als Drahtgitter (Soft Bodies eingeschlossen und eingeschaltete Spielfiguren in Gelb), DEBUG_CONSTRAINTS Gelenke, Ragdoll-Gelenke und Fahrzeug-Constraints mit ihren Grenzen, DEBUG_CONTACTS ein rotes Kreuz, wo sich Körper in diesem Schritt getroffen haben, und DEBUG_VELOCITIES eine Linie entlang der Geschwindigkeit jedes bewegten Körpers. Addiere die Flags; DEBUG_ALL sind alle vier. Die Formen statischer Körper bleiben aus, sofern nicht DEBUG_STATIC hinzukommt, weil ein Level-Mesh sehr viele Linien ergibt. DEBUG_NONE schaltet es ab, und solange es aus ist, wird nichts gezeichnet und nichts kostet etwas.

Hinweise: Ein Build von Singe ohne den Debug-Renderer von Jolt gibt eine Meldung auf der Konsole aus und zeichnet nichts.

Seit: 3.00. Siehe auch: lineDraw, navDraw, physicsSetEnabled

Beispiel
-- Die Physik-Einblendung mit einer Debug-Taste umschalten; auch die statischen Formen, da das Level klein ist.
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)

Pausiert die Simulation mit false und setzt sie mit true fort. Solange sie pausiert ist, läuft kein Schritt: Dynamische Körper halten still und behalten ihre Geschwindigkeiten, kinematische Körper folgen ihren Knoten nicht mehr, Spielfiguren bewegen sich nicht mehr, und kein onCollision oder onTrigger wird ausgelöst. Während der Pause sammelt sich keine Zeit an, das Fortsetzen holt die verpassten Schritte also nicht nach. Die eigene Pause des Spiels tut dasselbe ohne diesen Aufruf; nimm ihn für ein Menü, eine Zwischensequenz oder ein Standbild, bei dem der Rest des Spiels weiterläuft.

Seit: 3.00. Siehe auch: physicsSetGravity, bodyIsResting

Beispiel
-- Die Welt einfrieren, solange das Inventar offen ist.
function openInventory()
    inventoryOpen = true
    physicsSetEnabled(false)
end

function closeInventory()
    inventoryOpen = false
    physicsSetEnabled(true)
end

2.30.5. physicsSetGravity

physicsSetGravity(x, y, z)

Setzt die Beschleunigung, die jeder dynamische Körper und jede Spielfigur spürt, in Welteinheiten pro Sekunde zum Quadrat entlang jeder Weltachse. Der Standard ist 0, -9.81, 0, die Erdschwerkraft in Metern; 0, 0, 0 ist der Weltraum, und ein 2D-Spiel in Overlay-Pixeln will etwa 0, 900, 0, da Y im Overlay den Bildschirm hinunterläuft. Die der Schwerkraft entgegengesetzte Richtung ist für Spielfiguren „oben“: die Richtung, in der sie stehen, springen und Stufen erklimmen.

Eine Änderung der Schwerkraft weckt jeden Körper, Soft Bodies eingeschlossen, sodass eine zur Ruhe gekommene Kiste fällt, wenn sich die Schwerkraft zur Seite dreht, und Stoff weht, wenn sich ein aus Schwerkraft gemachter Wind ändert. Dieselbe Schwerkraft erneut zu setzen weckt nichts.

Seit: 3.00. Siehe auch: bodyNew, physicsSet2D, playerSetGravityScale

Beispiel
-- Das Mond-Level: ein Sechstel der Erdanziehung und ein passend längerer Sprung.
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. Spielfigur

Eine Spielfigur ist ein Character-Controller auf einem Knoten: Während ein Körper dorthin geht, wohin Kräfte ihn schicken, geht eine Spielfigur dorthin, wohin das Skript sagt, läuft Böden entlang, steigt Stufen hinauf, gleitet an Wänden entlang, fährt auf Plattformen mit und schiebt leichte Körper beiseite. Spielfiguren werden über ihren Knoten angesprochen, und ein Knoten trägt einen Körper oder eine Spielfigur, nicht beides. Größen und Geschwindigkeiten sind in Welteinheiten (Meter in einer 3D-Szene, Overlay-Pixel in einer 2D-Welt), und die Toleranzen des Controllers skalieren mit der Form, sodass sich eine 30 Pixel große Kapsel wie eine von 0,3 Metern verhält. Die Spielfigur treibt bei jedem Schritt die Position ihres Knotens und überlässt die Rotation dem Skript. Jeder Aufruf hier beendet das Skript, wenn der Knoten keine Spielfigur hat. Siehe Physik in Spieleentwicklung, Spielfiguren.

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)

Setzt eine Spielfigur auf den Knoten, dort, wo der Knoten gerade in der Welt ist: eine Kapsel mit diesem Radius und dieser Gesamthöhe oder jede konvexe bodyNew-Form mit ihren Größen, skaliert mit der Weltskalierung des Knotens. Die Form steht auf dem Ursprung des Knotens, der Knoten sind also die Füße. Sie beginnt mit einer Masse von 70 Kilogramm, einer Schubkraft von 300 Newton, einer Hanggrenze von 45 Grad, einer Stufenhöhe von 0.3, skaliert mit der Form, dem Schwerkraftfaktor 1 und den Standardwerten fürs Schwimmen. Ersetzt jeden Körper und jede Spielfigur, die der Knoten hatte. Beendet das Skript bei SHAPE_MESH (eine Spielfigur braucht eine konvexe Form; nimm SHAPE_HULL), wenn auf diesem Rechner keine Physik verfügbar ist oder wenn die Spielfigur nicht erzeugt werden kann (eine Hülle mit zu wenig Mesh oder schon sechzehn Spielfiguren).

Parameter:

  • radius, height — eine Kapsel, Radius und Gesamthöhe entlang der Aufwärtsrichtung, Kappen eingeschlossen.

  • SHAPE_* — eine Formkonstante, gefolgt von ihren bodyNew-Größen; SHAPE_HULL nimmt keine und umhüllt das Mesh des Knotens und alles darunter.

Hinweise: Ein Aufruf mit genau drei Argumenten ist immer eine Kapsel, eine Kugel braucht also nach ihrem Radius ein viertes Argument (eine beliebige Zahl), um als SHAPE_SPHERE gelesen zu werden.

Seit: 3.00. Siehe auch: playerMove, playerDelete, bodyNew, nodeSetParent

Beispiel
-- Der Held: eine Kapsel, am Knoten hängt das Fox-Modell, die Füße auf dem Boden.
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)
-- Ein Roboter ist ein Quader; er biegt rechtwinklig ab und kann nicht rollen.
robot = nodeNew()
playerNew(robot, SHAPE_BOX, 0.8, 1.6, 0.6)

2.31.2. playerDelete

playerDelete(node)

Entfernt die Spielfigur; der Knoten und was darunter hängt bleiben, wo sie sind. Das Löschen des Knotens entfernt auch seine Spielfigur, ebenso, wenn der Knoten mit bodyNew einen Körper bekommt. Beendet das Skript, wenn der Knoten keine Spielfigur hat.

Seit: 3.00. Siehe auch: playerNew, playerSetEnabled

Beispiel
-- Der Held steigt ins Auto: Der Controller verschwindet, das Modell fährt mit.
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)

Teilt der Spielfigur die Geschwindigkeit mit, die sie in diesem Frame will, in Welteinheiten pro Sekunde. Am Boden oder in der Luft werden die beiden waagerechten Werte so verwendet, wie sie angegeben sind, zusätzlich zu der Plattform, auf der sie steht; der senkrechte Anteil kommt von der Schwerkraft, dem Boden und playerJump, und vy wird ignoriert. Schwimmt die Spielfigur, steuern sie alle drei Werte, und das Wasser führt ihre Geschwindigkeit mit dem Widerstand aus playerSetSwim sanft an sie heran, wobei sie mit der Sinkgeschwindigkeit sinkt, wenn vy gleich 0 ist. In einer 2D-Welt läuft ein einzelnes vx entlang X, und jedes vz wird ignoriert. Ruf es in jedem Frame aus onOverlayUpdate auf: Die Anforderung wird von den Schritten dieses Frames verbraucht, und in einem Frame ohne Anforderung steht sie still.

Parameter:

  • vx, vz — die gewünschte waagerechte Geschwindigkeit, Welteinheiten pro Sekunde (2D: Overlay-Pixel entlang X).

  • vy — die gewünschte senkrechte Geschwindigkeit beim Schwimmen; positiv ist nach oben.

Beispiel
-- Mit dem linken Stick gehen, aufwärts schwimmen, solange der Knopf gehalten wird, in Laufrichtung schauen.
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)

Ob die Spielfigur beim letzten Schritt im Wasser war: die Mitte ihrer Form unter der Oberfläche eines bodySetWater-Volumens. Beim Schwimmen steuert playerMove in drei Achsen, die Schwerkraft weicht der Sinkgeschwindigkeit, und die Strömung des Wassers trägt die Spielfigur mit.

Rückgabe: Boolean.

Seit: 3.00. Siehe auch: playerSetSwim, bodySetWater, playerMove

Beispiel
-- Die Animation wechseln, wenn der Held ins Wasser geht.
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)

Bittet die Spielfigur, beim nächsten Schritt mit dieser Aufwärtsgeschwindigkeit, in Welteinheiten pro Sekunde, vom Boden abzuheben. Das wird nur gewährt, wenn gerade begehbarer Boden unter den Füßen ist, sodass ein gehaltener Knopf die Spielfigur nicht hüpfen lässt und ein Sprung in der Luft nichts tut. Eine negative Geschwindigkeit wird als 0 behandelt. Die Spielfigur behält ihre waagerechte Geschwindigkeit während des Sprungs, und playerMove steuert sie auch in der Luft.

Rückgabe: true, wenn der Sprung gewährt wurde.

Beispiel
-- Auf den Aktionsknopf springen, mit einem Geräusch nur, wenn es wirklich geschehen ist.
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)

Legt fest, wie sich die Spielfigur im Wasser verhält: wie schnell sie sinkt, in Welteinheiten pro Sekunde, wenn playerMove keine senkrechte Bewegung verlangt (Standard 0.3), und wie schnell das Wasser ihre Geschwindigkeit zu dem hinzieht, was playerMove verlangt, als Rate pro Sekunde (Standard 2, sodass der größte Teil des Unterschieds innerhalb einer Sekunde verschwunden ist; 0 ändert die Geschwindigkeit nie). Beide werden auf mindestens 0 begrenzt. Ein schwerer Taucher sinkt schnell, mit hohem Widerstand; ein Korken sinkt gar nicht.

Parameter:

  • sinkSpeed — das Absinken ohne senkrechte Eingabe, Einheiten pro Sekunde.

  • drag — die Rate, mit der das Wasser die Geschwindigkeit zur Anforderung hinzieht, pro Sekunde.

Seit: 3.00. Siehe auch: playerIsSwimming, playerMove, bodySetWater

Beispiel
-- Die Rüstung zieht den Helden hinunter; leg sie ab, um zu treiben.
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)

Setzt die ganze Geschwindigkeit der Spielfigur, in Welteinheiten pro Sekunde entlang jeder Weltachse, und verwirft jede in diesem Frame gemachte playerMove-Anforderung. Der senkrechte Anteil ist das, was bleibt: Eine Aufwärtsgeschwindigkeit hebt die Spielfigur vom Boden, und sie fällt unter der Schwerkraft zurück, das ist ein Sprungfeld oder ein Abprallen. Der waagerechte Anteil hält nur bis zum nächsten Schritt, wenn er durch das ersetzt wird, was playerMove verlangt (nichts, wenn es nicht aufgerufen wird), weil eine Spielfigur keinen eigenen waagerechten Schwung hat. Ein Rückstoß oder ein Dash ist hier also ein Stoß nach oben plus eine playerMove-Geschwindigkeit, die über die folgenden Frames eingespeist wird.

Seit: 3.00. Siehe auch: playerGetVelocity, playerMove, playerJump

Beispiel
-- Ein Treffer des Ogers wirft den Helden hoch und über die nächsten Frames von ihm weg.
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)

Die Geschwindigkeit der Spielfigur nach dem letzten Schritt, in Welteinheiten pro Sekunde entlang jeder Weltachse, einschließlich dessen, was der Boden, auf dem sie mitfährt, ihr gegeben hat. Lies den senkrechten Anteil, um Steigen von Fallen zu unterscheiden, oder das Ganze für ein dumpfes Landegeräusch.

Rückgabe: Drei Zahlen.

Seit: 3.00. Siehe auch: playerSetVelocity, playerIsOnGround

Beispiel
-- Fallschaden aus der Geschwindigkeit, mit der der Held auf dem Boden aufgeschlagen ist.
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)

Ob die Spielfigur beim letzten Schritt auf begehbarem Boden steht: einer Fläche, die nicht steiler als playerSetSlope ist. In der Luft oder auf einem zu steilen Hang ist es false. Das ist dieselbe Prüfung, die playerJump macht.

Rückgabe: Boolean.

Seit: 3.00. Siehe auch: playerGetGround, playerJump, playerSetSlope

Beispiel
-- Coyote Time: Ein Sprung ist noch ein paar Frames lang erlaubt, nachdem man über eine Kante gelaufen ist.
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)

Worauf die Spielfigur steht, und die Oberflächennormale des Bodens dort. Der Knoten ist der Körper unter den Füßen, ob begehbar oder nicht; in der Luft ist er nil, und die Normale ist dann 0, 1, 0. Unterscheide über den Knoten eine bewegliche Plattform, Eis oder eine Druckplatte vom Boden und neige über die Normale ein Modell in einen Hang.

Rückgabe: Der Knoten, auf dem sie steht, oder nil, dann die Normale.

Seit: 3.00. Siehe auch: playerIsOnGround, bodySetFriction

Beispiel
-- Schritte klingen auf der Holzbrücke anders, und die Platte öffnet das Tor.
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)

Die höchste Stufe, die die Spielfigur ohne Sprung erklimmt, in Welteinheiten; alles Höhere ist eine Wand, an der sie entlanggleitet. Der Standard ist 0.3 bei einer Form, deren kleinste halbe Ausdehnung 0.3 ist (eine Kapsel mit Radius 0.3), und skaliert mit der Form, sodass eine 30 Pixel große Spielfigur in einer 2D-Welt mit 30 Pixeln beginnt. Dieselbe Strecke ist, wie weit die Spielfigur über die Kante einer Stufe hinweg nach unten am Boden haftet, eine größere Stufe hält sie also auch auf Gefällen am Boden. Negative Werte werden auf 0 begrenzt.

Seit: 3.00. Siehe auch: playerSetSlope, playerNew

Beispiel
-- Treppen in diesem Level steigen 0,35 pro Stufe; sicherstellen, dass der Held sie schafft.
playerNew(hero, 0.3, 1.0)
playerSetStep(hero, 0.4)
-- Die Absätze des 2D-Plattformspiels sind 26 Pixel hoch.
playerNew(runner, 16, 48)
playerSetStep(runner, 26)

2.31.12. playerSetSlope

playerSetSlope(node, degrees)

Der steilste Hang, den die Spielfigur hinaufgeht, in Grad gegen die Waagerechte; steilerer Boden gilt nicht als Stehen, die Spielfigur rutscht ihn also hinunter und kann nicht von ihm abspringen. Der Standard ist 45, und der Wert wird zwischen 0 und 89 begrenzt. Ein niedriger Wert macht Hügel zu Hindernissen, ein hoher lässt die Spielfigur fast alles erklimmen, was keine Wand ist.

Seit: 3.00. Siehe auch: playerSetStep, playerIsOnGround

Beispiel
-- Die Bergziege klettert, wo der Held rutscht.
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)

Die Masse der Spielfigur, verwendet, wenn sie dynamische Körper schiebt, und als ihr Gewicht auf jedem, auf dem sie steht. Der Standard ist 70 Kilogramm; Werte unter 0.001 werden darauf angehoben. Die Masse wirkt sich nicht darauf aus, wie die Spielfigur fällt oder geht, nur auf das Schieben, kombiniere sie also mit playerSetPush.

Seit: 3.00. Siehe auch: playerSetPush, bodySetMass

Beispiel
-- Der Troll walzt durch, was der Held umgehen muss.
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)

Wie stark die Spielfigur dynamische Körper schiebt, in die sie hineinläuft, in Newton. Der Standard 300 bewegt Kisten und Bälle, aber keine Automaten; 0 geht um alles herum, als wäre es statisch. Negative Werte werden auf 0 begrenzt. Das eigene bodySetMass eines Körpers entscheidet, was eine gegebene Stärke bewegen kann.

Seit: 3.00. Siehe auch: playerSetMass, bodySetMass

Beispiel
-- Der Stärketrank lässt den Helden zehn Sekunden lang den Felsbrocken bewegen.
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)

Multipliziert die Schwerkraft der Welt für diese Spielfigur allein: 1 (der Standard) fällt wie alles andere, 0 schwebt, wo sie ist (eine Leiter, ein Raum ohne Schwerkraft, ein fliegendes Reittier), mehr fällt schneller und fühlt sich schwer an, und weniger ergibt einen schwebenden Sprung. Es ändert nicht, was playerJump beim Absprung tut, nur wie schnell die Spielfigur wieder herunterkommt. Beim Schwimmen tritt die Sinkgeschwindigkeit des Wassers an die Stelle der Schwerkraft.

Seit: 3.00. Siehe auch: physicsSetGravity, playerJump, playerSetSwim

Beispiel
-- Auf der Leiter klettert der Held mit dem Stick, statt zu fallen.
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)

Teleportiert die Spielfigur an eine Position in der Welt, ohne unterwegs etwas zu berühren, und hält sie schlagartig an. Der Knoten bewegt sich mit und behält seine Rotation. Nimm es zum Erscheinen, Wiedererscheinen und für Levelwechsel; den Knoten stattdessen mit nodeSetPosition zu bewegen lässt die Spielfigur, wo sie war, und der Knoten wird beim nächsten Schritt zurückgezogen.

Seit: 3.00. Siehe auch: playerSetVelocity, nodeSetPosition

Beispiel
-- Nach einem Sturz in die Grube zurück zum letzten Checkpoint.
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)

Mit false verlässt die Spielfigur die Simulation: Ihr Körper wird aus der Welt entfernt, sie bewegt sich also nicht, fällt nicht, treibt ihren Knoten nicht und blockiert nichts, onTrigger meldet, dass sie jeden Trigger verlässt, in dem sie stand, und beim Debug-Zeichnen wird sie ausgelassen. true setzt den Körper zurück und nimmt ihn dort wieder auf, wo der Knoten gerade ist. Schalte eine Spielfigur aus, solange eine Ragdoll, eine Zwischensequenz oder ein Fahrzeug über die Figur verfügt.

Seit: 3.00. Siehe auch: playerDelete, ragdollNew, bodySetEnabled

Beispiel
-- Ein harter Treffer übergibt das Skelett des Helden an die 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

Das Skelett eines geskinnten Modells, an die Physik übergeben (siehe Physik, Ragdolls). Eine Ragdoll wird über den Knoten angesprochen, der ragdollNew übergeben wurde, meist die Wurzel einer Modellinstanz, und ein Knoten ohne Ragdoll beendet in jedem Aufruf nach ragdollNew das Skript. Knochen werden über ihre Gelenkknoten benannt, die Namen, die nodeFind sieht, ohne Rücksicht auf Groß- und Kleinschreibung verglichen; Abstände sind in Welteinheiten, Winkel in Grad, Impulse in Newtonsekunden und die Motorstärke in Newtonmetern. Bis zu acht Ragdolls gleichzeitig mit je bis zu 48 Knochen.

2.32.1. ragdollNew

ragdollNew(node)

Sucht am Knoten und darunter nach dem ersten geskinnten Mesh und baut aus seinem Skelett ein Ragdoll-Rezept: Jedes Gelenk, das ein Kindgelenk hat, wird zu einem Knochen, einer Kapsel, die vom Gelenk zu seinen Kindern verläuft und mit dem nächsten Knochen darüber durch ein Swing-Twist-Gelenk verbunden ist, begrenzt auf 45 Grad Schwenk und 30 Grad Verdrehung. Gelenke ohne Kindgelenk, etwa Fingerspitzen und die Spitze eines Schwanzes, bewegen sich mit ihrem Elternknochen mit und können in den anderen Aufrufen nicht genannt werden. Noch wird nichts simuliert: Das Modell animiert weiter bis ragdollActivate. Ein erneuter Aufruf auf demselben Knoten verwirft zuerst die alte Ragdoll. Beendet das Skript, wenn keine Physik verfügbar ist, wenn unter dem Knoten kein geskinntes Mesh mit Knochen liegt oder wenn schon acht Ragdolls existieren.

Seit: 3.00. Siehe auch: ragdollActivate, ragdollSetJoint, modelInstance

Beispiel
-- Ein Wächter, der auf den Spieler zuläuft; die Ragdoll ist vor dem Zusammenprall bereit.
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)                          -- Nur das Rezept; läuft weiter

2.32.2. ragdollDelete

ragdollDelete(node)

Entfernt die Ragdoll: ihre Körper und Gelenke, wenn sie aktiv ist, dann das Rezept. Die Gelenkknoten bleiben, wo die Physik sie gelassen hat, das Modell liegt also, wie es gefallen ist, bis eine Animation es bewegt, und der Knoten ist frei für ein neues ragdollNew. Ein Knoten ohne Ragdoll beendet das Skript.

Seit: 3.00. Siehe auch: ragdollNew, ragdollDeactivate, nodeDelete

Beispiel
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)              -- Fünf Sekunden reglos:  aufräumen
            nodeDelete(body.node)
            table.remove(fallen, i)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.32.3. ragdollSetJoint

ragdollSetJoint(node, jointName, radius, swingDegrees, twistDegrees)

Stimmt das Rezept eines Knochens ab. Die Werte werden gelesen, wenn die Körper erzeugt werden, ruf es also vor ragdollActivate auf; eine bereits aktive Ragdoll behält ihre Körper, bis sie deaktiviert und erneut aktiviert wird. Der Radius 0 verlangt die automatische Kapsel, 0,22 der Knochenlänge und nie dünner als 0.02 Einheiten. Der Schwenk ist der halbe Öffnungswinkel des Kegels, durch den sich der Knochen relativ zu seinem Elternknochen bewegen darf, die Verdrehung, wie weit er sich um seine eigene Achse drehen darf; beide werden auf 0 bis 179 begrenzt. Nur Knochen können genannt werden, nicht die Endgelenke; der Name wird ohne Rücksicht auf Groß- und Kleinschreibung verglichen, und ein Name ohne Knochen beendet das Skript.

Parameter:

  • node — der Knoten der Ragdoll.

  • jointName — der Name des Gelenkknotens, wie im Modell.

  • radius — der Radius der Kapsel in Welteinheiten oder 0 für automatisch.

  • swingDegrees — wie weit der Knochen von seinem Elternknochen wegschwenken darf; Standard 45.

  • twistDegrees — wie weit er sich um seine eigene Achse verdrehen darf; Standard 30.

Seit: 3.00. Siehe auch: ragdollNew, ragdollActivate, nodeFind

Beispiel
ragdollNew(fox)
ragdollSetJoint(fox, "b_Neck_04", 0, 30, 20)          -- Ein steiferer Hals
ragdollSetJoint(fox, "b_Tail01_012", 0.03, 80, 60)    -- Ein peitschender Schwanz
for _, leg in ipairs({ "b_LeftLeg01_015", "b_RightLeg01_019" }) do
    ragdollSetJoint(fox, leg, 0, 60, 15)              -- Hüften schwenken weit, verdrehen kaum
end
ragdollActivate(fox)

2.32.4. ragdollActivate

ragdollActivate(node)

Übergibt das Skelett aus seiner aktuellen Pose an die Physik: Jede Animationsebene auf dem Knoten stoppt, für jeden Knochen wird dort, wo sein Gelenk gerade steht, eine dynamische Kapsel erzeugt, zwischen ihnen werden die Swing-Twist-Gelenke erzeugt, und von da an treibt jeder Physikschritt die Gelenkknoten aus den Körpern, sodass das geskinnte Mesh folgt. Die Knochen kollidieren mit der Welt und miteinander, außer jeder Knochen mit seinem Elternknochen. Die Pose in diesem Moment ist das, wohin ragdollSetStrength zieht. Eine bereits aktive Ragdoll bleibt, wie sie ist. Beendet das Skript, wenn der Körper eines Knochens nicht erzeugt werden kann.

Beispiel
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)        -- Der Controller lässt los
        ragdollActivate(guardFox)             -- Ab hier übernimmt die Physik das Skelett
        ragdollApplyImpulse(guardFox, "b_Spine02_03", 40, 30, 0)
    end
end

2.32.5. ragdollDeactivate

ragdollDeactivate(node)

Entfernt die Körper und Gelenke und gibt das Skelett zurück. Die Gelenkknoten behalten die Pose, in der die Ragdoll sie gelassen hat, und nichts bewegt sie, bis eine Animation läuft; ein animationPlay mit Überblendung blendet aus dieser Pose heraus, sodass eine am Boden liegende Figur aufstehen kann. Das Rezept bleibt, sodass ragdollActivate später wieder übernehmen kann, wo auch immer die Animation das Skelett hinbewegt hat. Tut nichts bei einer Ragdoll, die nicht aktiv ist.

Seit: 3.00. Siehe auch: ragdollActivate, animationPlay

Beispiel
-- Sobald der Körper zur Ruhe gekommen ist, steht der Held über eine halbe Sekunde auf.
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)

Treibt jedes Gelenk mit einem Motor an, der zu der Pose zieht, in der die Ragdoll aktiviert wurde, begrenzt auf so viele Newtonmeter; 0 (Standard) schaltet die Motoren aus, und der Körper wird schlaff. Die Motoren sind Federn mit 4 Hz, kritisch gedämpft. Es kann vor dem Aktivieren oder während sich die Ragdoll bewegt gesetzt werden und wirkt ab dem nächsten Schritt. Einen Körper stellt es nicht auf, da sich nichts vom Boden abstößt: Ein paar Dutzend Newtonmeter verwandeln einen Sturz in ein Taumeln und lassen eine am Boden liegende Figur ihre Gliedmaßen einziehen.

Seit: 3.00. Siehe auch: ragdollActivate, ragdollIsResting

Beispiel
-- Schlaff zu Boden geschlagen; einen Moment später spannt sich der Kämpfer an und rollt sich zusammen.
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)

Gibt dem Körper des Knochens, der am genannten Gelenk beginnt, einen Impuls in Newtonsekunden entlang der Weltachsen: der Schlag, der Schuss, die Explosion. Die Ragdoll muss aktiv sein, ruf also zuerst ragdollActivate auf und stoß dann. Gibt false zurück und tut nichts, wenn die Ragdoll nicht aktiv ist oder kein Knochen diesen Namen hat (Endgelenke sind keine Knochen); der Name wird ohne Rücksicht auf Groß- und Kleinschreibung verglichen.

Parameter:

  • node — der Knoten der Ragdoll.

  • jointName — der Name des Gelenkknotens, wie im Modell.

  • x, y, z — der Impuls in Newtonsekunden, entlang der Weltachsen.

Rückgabe: Wahr, wenn der Knochen gefunden wurde und die Ragdoll aktiv war.

Seit: 3.00. Siehe auch: ragdollActivate, bodyApplyImpulse, nodeFind

Beispiel
-- Ein Treffer von der Position des Schützen aus:  Der Impuls zeigt von der Waffe weg.
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)

Ob die Physik das Skelett gerade treibt: true von ragdollActivate bis ragdollDeactivate oder ragdollDelete. Ein Knoten ohne Ragdoll beendet das Skript.

Rückgabe: Wahr oder falsch.

Seit: 3.00. Siehe auch: ragdollActivate, ragdollIsResting

Beispiel
-- Der Lebensbalken hängt nur über dem Modell, solange es auf den Beinen ist.
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)

Ob der Körper jedes Knochens eingeschlafen ist, was die Physik tut, sobald ein Körper einen Moment lang still war. false, solange die Ragdoll nicht aktiv ist, es kann also nicht dazu dienen, ein untätiges Modell von einem zur Ruhe gekommenen zu unterscheiden; prüf auch ragdollIsActive.

Rückgabe: Wahr oder falsch.

Seit: 3.00. Siehe auch: ragdollIsActive, ragdollDeactivate

Beispiel
-- Die Runde endet, sobald sich der Verlierer nicht mehr bewegt.
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. Spielstand

Alles, was das Spiel beim nächsten Start noch wissen soll: Highscores, die Optionen des Spielers, wie weit er gekommen ist. Eine Tabelle pro Spiel, als JSON im eigenen Datenordner des Spiels abgelegt (siehe singeGetDataPath), sodass ein gepacktes .game schreibgeschützt bleibt und zwei Spiele sich nie in die Quere kommen.

Die Schlüssel bestimmst du. Werte dürfen Zahlen, Strings, Booleans oder Tabellen daraus sein, beliebig tief verschachtelt — eine ganze Highscore-Tabelle geht als ein einziger Wert hinein. Eine Funktion oder ein Handle auf etwas, das der Engine gehört, nicht: Beides bedeutet beim nächsten Lauf nichts, und so etwas zu speichern ist ein Fehler statt einer späteren Überraschung.

Was du setzt, wird gespeichert, und was du zurückbekommst, gehört dir. Tabellen werden beim Hineingeben und beim Herausholen kopiert; eine Tabelle zu ändern, die du zurückgelesen hast, ändert also nichts, bis du sie wieder speicherst, und eine Tabelle zu ändern, die du gespeichert hast, greift danach nicht in den Spielstand hinein. Für eine Vorschau, die der Spieler dann verwirft, genügt es deshalb, sie nicht zu speichern.

Geschrieben wird einmal am Ende jedes Frames, der etwas geändert hat, egal wie viele Schlüssel du darin setzt, und noch einmal, wenn das Spiel beendet wird — einschließlich allem, was in onShutdown gesetzt wird. Für einen Automaten, der jederzeit den Strom verlieren kann, schreibt saveFlush sofort. Die Datei wird neben die alte geschrieben und über sie umbenannt, sodass ein Stromausfall während des Schreibens den vorigen Spielstand hinterlässt statt der Hälfte eines neuen.

Ganzzahlen kommen als Ganzzahlen zurück. JSON hat nur eine Art von Zahl und Lua zwei, sodass eine als 100 gespeicherte Punktzahl sonst als 100.0 zurückkäme und mit Dezimalpunkt ausgegeben würde.

2.33.1. saveClear

saveClear()

Vergisst alles und schreibt den leeren Spielstand hinaus. Für das „Highscores zurücksetzen“ eines Service-Menüs.

Parameter:

  • Keine.

Rückgabe: nichts.

Seit: 3.00.

2.33.2. saveDelete

saveDelete(key)

Entfernt einen Schlüssel. Einen Schlüssel zu löschen, den es nie gab, ist kein Fehler.

Parameter:

  • key — der zu entfernende Schlüssel.

Rückgabe: nichts.

Seit: 3.00.

2.33.3. saveFlush

saveFlush()

Schreibt den Spielstand jetzt statt am Ende des Frames. Nutze es nach etwas, das du auf keinen Fall verlieren willst — einem neuen Highscore auf einem Automaten, der an der Steckdose ausgeschaltet wird.

Parameter:

  • Keine.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: saveSet

2.33.4. saveGet

value = saveGet(key [, default])

Was unter diesem Schlüssel gespeichert wurde. Wurde nichts gespeichert, kommt der Standardwert zurück, oder nil, wenn es keinen gibt — so unterscheidet man den ersten Lauf von einem späteren.

Parameter:

  • key — der zu lesende Schlüssel.

  • default — optional; was geantwortet wird, wenn der Schlüssel nicht da ist.

Rückgabe: der gespeicherte Wert, der Standardwert oder nil.

Seit: 3.00. Siehe auch: saveSet

Beispiel
-- Die Läufe zählen und die zehn besten Punktzahlen merken.
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()

Eine Kopie des ganzen Spielstands, zum Lesen: um ihn beim Debuggen auszugeben oder um Schlüssel durchzugehen, deren Namen das Spiel nicht im Voraus kennt. Zu ändern, was zurückkommt, ändert nichts — eine ganze Tabelle schreibt saveSetAll.

Parameter:

  • Keine.

Rückgabe: eine Tabelle; leer, wenn nichts gespeichert wurde.

Seit: 3.00. Siehe auch: saveSetAll, saveGet

Beispiel
-- Was ist da drin?  inspect wird genau dafür mitgeliefert.
debugPrint(require("inspect")(saveGetAll()))

2.33.6. saveSet

saveSet(key, value)

Bewahrt einen Wert auf, bis das Spiel deinstalliert wird. Geschrieben wird am Ende des Frames, sodass zwanzig Schlüssel, in einer Schleife gesetzt, eine einzige Datei schreiben.

Parameter:

  • key — der zu schreibende Schlüssel.

  • value — eine Zahl, ein String, ein Boolean oder eine Tabelle daraus.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: saveGet, saveFlush

2.33.7. saveSetAll

saveSetAll(everything)

Ersetzt den ganzen Spielstand in einem Schritt durch diese Tabelle. Schlüssel, die da waren und in der übergebenen Tabelle fehlen, sind weg.

Dieser Aufruf existiert, um einen alten Spielstand auf einen neuen Aufbau umzustellen. Mit saveClear und einer Schleife von saveSet gibt es einen Moment, in dem der Spielstand leer ist, und ein Rechner, der in diesem Moment ausgeschaltet wird, verliert alles; dieser Aufruf hat keinen solchen Moment, denn die Datei wird einmal am Ende des Frames aus der fertigen Tabelle geschrieben.

Parameter:

  • everything — Tabelle; was der Spielstand nun enthalten soll. Dieselben Werte, die saveSet nimmt.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: saveGetAll, saveClear

Beispiel
-- Version 1 hielt eine Punktzahl in zwei Schlüsseln; Version 2 hält eine Tabelle davon.
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. Szene

Die Szene ist die 3D-Ebene, die zwischen dem Video der Disc und dem Overlay gezeichnet wird; Knoten, die mit nodeSetLayer in die vordere Ebene gelegt werden, werden stattdessen nach dem Overlay gezeichnet. Sie ist aus, bis sceneEnable(true) aufgerufen wird, hat die Größe des Overlays und wird jeden Frame mit der Farbe von sceneSetBackground gelöscht. Die sceneSet*-Aufrufe bestimmen das Aussehen der ganzen Ebene: Umgebungslicht, Himmel, Nebel, Belichtung und Tonkurve, Bloom, Kantenglättung und Schattenqualität; Farben sind Ganzzahlen von 0 bis 255, und Entfernungen sind in Welteinheiten. sceneProject und sceneUnproject verbinden Weltkoordinaten und Overlay-Koordinaten, und sceneGetStats meldet die Arbeit des letzten Frames. Siehe 3D-Szenen.

2.34.1. sceneEnable

sceneEnable(enabled)

Schaltet die 3D-Ebene ein oder aus. Knoten, Meshes und Materialien können gebaut werden, bevor sie an ist, und überstehen ihr Ausschalten; nur das Zeichnen hört auf. Beendet das Skript, wenn sie ohne nutzbare GPU eingeschaltet wird (siehe 3D-Szenen); ein Spiel mit einem 2D-Ersatz fragt deshalb zuerst singeCapabilities().SCENE ab. Die Anzeige wird in jedem Fall im nächsten Frame aufgefrischt.

Seit: 3.00. Siehe auch: sceneSetBackground, sceneSetAntialias

Beispiel
-- Auf das einfache Overlay zurückfallen, wenn 3D nicht verfügbar ist.
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()

Die Größe der Ebene, also die Auflösung des Overlays: der Raum, in dem sceneProject und sceneUnproject arbeiten, und die Größe, in der die Szene gerendert wird. Ändern lässt sie sich mit overlaySetResolution. Bevor die Ebene eine Größe hat, sind beide Werte 0.

Rückgabe: Zwei Ganzzahlen, die Breite und die Höhe in Overlay-Koordinaten.

Seit: 3.00. Siehe auch: overlaySetResolution, sceneUnproject

Beispiel
-- Ein Fadenkreuz in der Mitte der Ansicht und das Ding darunter.
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()

Die Zahlen des letzten Frames von der Kamera des Fensters: die zum Zeichnen gesammelten Meshes, wie viele davon im Sichtfeld der Kamera lagen, die Zeichenaufrufe, die nach dem Instanzieren daraus wurden, und der Texturspeicher, den die Szene belegt, in Kilobyte. Zum Abstimmen: Eine Szene mit Hunderten drawn, aber einer Handvoll calls teilt ihre Meshes gut, und ein textureKB, das nicht in den Speicher eines Raspberry Pi passt, verlangt nach KTX2-Texturen. Gerenderte Ansichten zählen nicht.

Rückgabe: Vier Ganzzahlen.

Seit: 3.00. Siehe auch: sceneEnable, modelInstance, materialSetTexture

Beispiel
-- Ein Debug-Anzeigefeld in der Ecke, während das Level abgestimmt wird.
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)

Misst die Zeit der 3D-Szene. sceneMeasure(true) startet: Jeder Frame danach wartet, bis die GPU die Szene fertig hat, und zählt diese Zeit zusammen, sodass die Arbeit gemessen wird statt des Takts der Anzeige. sceneMeasure(false) hält an und gibt die Millisekunden zurück, die ein Frame im Schnitt brauchte, oder nil, wenn kein Frame gezeichnet wurde. Das Warten kostet Bildrate, also miss ein paar Sekunden, nicht ein ganzes Spiel.

Rückgabe: nichts beim Starten; eine Zahl oder nil beim Anhalten.

Seit: 3.00. Siehe auch: singeSaveTier, sceneGetStats

Beispiel
-- Zwei Sekunden Titelbildschirm sagen, ob die vollen Effekte passen.
sceneMeasure(true)
-- ... zwei Sekunden später:
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)

Welche GUI auf der Oberfläche unter einem Overlay-Punkt liegt und wo darauf: ein Strahl von der Kamera durch den Punkt, mit der Kamera des zuletzt gerenderten Frames, gegen die Dreiecke jedes sichtbaren Knotens, dessen Material eine GUI zeigt (materialSetGui), wobei die Texturkoordinaten des nächsten Treffers die Stelle auf der GUI angeben. Gibt das GUI-Handle und das Pixel in den eigenen Koordinaten dieser GUI zurück (0, 0 oben links, guiGetWidth, guiGetHeight unten rechts), oder nur nil, wenn der Punkt auf keiner solchen Oberfläche liegt, die Szene aus ist oder noch nichts gerendert wurde. Die Engine stellt dieselbe Frage, wenn die Maus oder eine Lightgun auf die Szene zeigt, während eine GUI, die Eingaben annimmt, auf einer Oberfläche liegt und nichts flach Gezeichnetes unter dem Zeiger ist, sodass Klicks auf einen Monitor in der Szene kein Skript brauchen; der Aufruf ist für ein Spiel, das die Antwort selbst haben will, für ein Laservisier, einen Hover-Effekt oder einen Test.

Parameter:

  • sx, sy — der Punkt, in Overlay-Koordinaten (eine Maus- oder Lightgun-Position).

Rückgabe: Eine Ganzzahl und zwei Ganzzahlen, oder nil.

Beispiel
-- Der Punkt einer Lightgun leuchtet dort, wo er auf dem Bildschirm des Cockpits landet.
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)

Wo ein Weltpunkt in Overlay-Koordinaten landet, mit der Kamera des zuletzt gerenderten Frames. depth ist 0 an der nahen Clipping-Ebene und 1 an der fernen, zum Sortieren von Beschriftungen oder um sie mit der Entfernung auszublenden. inFront ist false, wenn der Punkt hinter der Kamera liegt, und x und y sind dann bedeutungslos; vor dem ersten gerenderten Frame gibt es nichts, wogegen projiziert werden kann, und jeder Wert kommt als 0 zurück, mit inFront false. Punkte vor der Kamera, aber außerhalb der Ansicht kommen mit Koordinaten jenseits der Ränder des Overlays zurück; prüf sie also vor dem Zeichnen gegen sceneGetSize. Der übliche Einsatz ist ein Namensschild oder Lebensbalken, mit fontPrint oder spriteDraw über einem 3D-Objekt gezeichnet.

Parameter:

  • wx, wy, wz — der Weltpunkt, in Welteinheiten.

Rückgabe: Zwei Zahlen, eine Zahl und ein Boolean.

Beispiel
-- Ein Name und ein Lebensbalken, die über jeder Figur schweben.
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)

Der Weltpunkt distance Einheiten entlang des Strahls durch ein Overlay-Pixel, mit der Kamera des zuletzt gerenderten Frames. Zwei Entfernungen ergeben einen Strahl zum Auswählen mit physicsRaycast; eine setzt ein Objekt dorthin, „wo der Spieler geklickt hat“. Bevor der erste Frame gezeichnet wurde, gibt es den Ursprung zurück.

Parameter:

  • sx, sy — das Overlay-Pixel, in Overlay-Koordinaten.

  • distance — wie weit entlang des Strahls, in Welteinheiten; 0 ist die nahe Clipping-Ebene.

Rückgabe: Drei Zahlen, der Weltpunkt.

Seit: 3.00. Siehe auch: sceneProject, mouseGetPosition, physicsRaycast

Beispiel
-- Eine Markierung auf das setzen, was der Spieler angeklickt hat, oder 8 Einheiten entfernt, wenn nichts.
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)

Licht von überall, 0 bis 255 pro Kanal, als sRGB behandelt; der Standard ist ein mattes Grau von 26, 26, 26. Es hellt die Seiten auf, die kein Licht erreicht, damit sie nicht schwarz sind, und materialSetOcclusionMap dunkelt es in Ritzen ab. Ist ein Himmel gesetzt und sceneSetEnvironment an, ersetzt das Licht des Himmels diesen Wert.

Seit: 3.00. Siehe auch: lightNew, sceneSetEnvironment, sceneSetSky

Beispiel
-- Ein mondbeschienener Hof:  überall ein schwaches Blau, ein kalter Mond als Richtungslicht.
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)

Schaltet 4x-Multisampling ein oder aus; es ist standardmäßig an, wo immer die GPU es für die Formate der Ebene anbietet, und fehlt stillschweigend, wo nicht. Es auszuschalten bringt auf einem Raspberry Pi Geschwindigkeit. Die Renderziele werden sofort neu gebaut, ruf es also bei der Einrichtung auf statt in jedem Frame.

Seit: 3.00. Siehe auch: sceneEnable, sceneSetShadowSize

Beispiel
-- Eine Qualitätseinstellung aus dem Optionsbildschirm des Spiels.
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)

Die Farbe, mit der die Ebene jeden Frame gelöscht wird, 0 bis 255 pro Kanal. a ist 255, wenn es weggelassen wird, ein deckender Hintergrund; unter 255 scheint das Video durch, und 0 (die übliche Wahl für ein Spiel mit Disc) macht den Hintergrund völlig transparent. Bis zum ersten Aufruf wird die Ebene schwarz und transparent gelöscht. Ein Himmel aus sceneSetSky wird über den Hintergrund gezeichnet, sodass das Video nicht mehr durchscheint, solange einer gesetzt ist.

Parameter:

  • r, g, b — die Löschfarbe.

  • a — das Lösch-Alpha; 255, wenn weggelassen.

Seit: 3.00. Siehe auch: sceneEnable, sceneSetSky, sceneSetFog

Beispiel
-- Die Disc ist hinter dem 3D-Cockpit zu sehen; ein deckender Nachthimmel für das Menü.
function showCockpit()
    sceneSetBackground(0, 0, 0, 0)
    discPlay()
end

function showMenu()
    discPause()
    sceneSetBackground(10, 12, 30)
end

2.34.11. sceneSetBloom

sceneSetBloom(threshold, strength)

Ein Leuchten um alles, was heller als threshold ist, genommen aus dem linearen Licht der Szene vor Belichtung und Tonkurve (wo 1 Weiß ist) und mit strength wieder hinzugefügt. Die Standards sind ein Schwellwert von 1 und eine Stärke von 0, also kein Bloom; 0.2 bis 0.4 ist dezent, 1 ist ein Dunst. Das Leuchten wird über eine Kette von Durchgängen in halber Größe weichgezeichnet, kostet also wenig, und nur die Kamera des Fensters bekommt es: Gerenderte Ansichten lassen es aus. Negative Werte werden auf 0 begrenzt.

Parameter:

  • threshold — die lineare Helligkeit, über der ein Pixel leuchtet; 1 ist Weiß vor der Tonkurve.

  • strength — wie viel des Leuchtens wieder hinzugefügt wird; 0 für nichts.

Beispiel
-- Neon und Scheinwerfer leuchten; der Asphalt nicht.
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)

Ob der mit sceneSetSky gesetzte Himmel die Szene beleuchtet: sein diffuses Licht aus allen Richtungen anstelle von sceneSetAmbient und seine Spiegelungen auf Metallen und glänzenden Oberflächen, scharf auf einem Spiegel und umso unschärfer, je höher die Rauheit. Standardmäßig an, sodass ein Himmel die Szene beleuchtet, sobald er gesetzt ist; false behält den Himmel nur als Hintergrund, und das flache Umgebungslicht kehrt zurück. Ohne Himmel hat es keine Wirkung.

Beispiel
-- Ein gemalter Hintergrund, der das Chrom nicht tönen darf.
sceneSetSky(DIR .. "Skies/matteBackdrop.png")
sceneSetEnvironment(false)
sceneSetAmbient(40, 40, 45)

2.34.13. sceneSetExposure

sceneSetExposure(stops)

Hellt die ganze Szene in fotografischen Blendenstufen auf oder dunkelt sie ab, -10 bis 10 (Werte außerhalb werden begrenzt): +1 verdoppelt das Licht, -1 halbiert es. Der Standard ist 0. Es wird nach dem Bloom und vor der Tonkurve angewandt, sodass eine helle Szene bei +2 zu Weiß hin gestaucht statt abgeschnitten wird und eine Höhle und ein Strand dieselben Lichter teilen können. Animiere es für eine langsame Anpassung beim Gang von drinnen ins Tageslicht.

Beispiel
-- Augen gewöhnen sich:  die Belichtung jeden Frame sanft zum Zielwert des Bereichs führen.
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()

Entfernungsnebel: klar bis near Einheiten von der Kamera, ganz in der Nebelfarbe ab far, auf Meshes (auch unbeleuchteten) und Partikeln gleichermaßen; additive Partikel blenden aus, statt grau zu werden. Ohne Argumente oder mit einem far, das nicht größer als near ist, gibt es keinen Nebel. Der Himmel wird nicht vernebelt, wähl also eine Farbe nahe seinem Horizont oder, wenn es keinen Himmel gibt, nahe dem Hintergrund. Jede andere Anzahl von Argumenten beendet das Skript.

Parameter:

  • r, g, b — die Nebelfarbe, 0 bis 255.

  • near — die Entfernung, bei der der Nebel beginnt, in Welteinheiten von der Kamera.

  • far — die Entfernung, ab der nur noch Nebel bleibt.

Beispiel
-- Morgendunst über den Hügeln, der sich im Laufe des Levels auflöst.
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)

In wie viele Maps der Schatten eines Richtungslichts entlang der Blickrichtung aufgeteilt wird, 1 bis 4 (Werte außerhalb werden begrenzt; der Standard ist 3). Jede Kaskade deckt einen Ausschnitt des Blickfelds der Kamera bis sceneSetShadowDistance ab, der nächste Ausschnitt der kleinste, sodass Schatten nahe der Kamera scharf sind, egal wie groß das Level ist. 1 passt eine Map an die ganze Szene an, was für kleine Szenen richtig ist, und wird bei einer orthografischen Kamera immer verwendet. Jede Kaskade ist ein weiterer Schattendurchgang für jedes schattenwerfende Richtungslicht; 2 ist eine vernünftige Wahl auf einem Raspberry Pi.

Beispiel
-- Ein großes Außenlevel:  scharfe Schatten nahe dem Spieler, die weit reichen.
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)

Wie weit kaskadierte Schatten von der Kamera aus reichen, in Welteinheiten; der Standard ist 60, und Werte unter 1 werden auf 1 begrenzt. Dahinter wirft ein Richtungslicht keinen Schatten. Kürzere Entfernungen machen jede Kaskade schärfer, da dieselben Maps weniger Fläche abdecken; setz sie also etwa so weit, wie der Spieler einen Schatten erkennen kann. Es zählt nur bei mehr als einer Kaskade unter einer perspektivischen Kamera.

Seit: 3.00. Siehe auch: sceneSetShadowCascades, sceneSetShadowSize

Beispiel
-- Die Schatten müssen nur bis zur hinteren Wand der Arena reichen.
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)

Texel pro Seite jeder Shadow Map, jeder Kaskade und jeder Würfelfläche, 256 bis 4096 (Werte außerhalb werden begrenzt; der Standard ist 1024). Größer ist schärfer und langsamer, im Speicher ebenso wie in der Zeit, denn jedes schattenwerfende Licht hat seine eigenen Maps in dieser Größe. 2048 passt zu einem Desktop, 512 zu einem Raspberry Pi. Die Maps werden im nächsten Frame neu gebaut.

Beispiel
-- Die Shadow Maps an den Rechner anpassen.
if singeGetPlatform() == "raspberrypi" then
    sceneSetShadowSize(512)
else
    sceneSetShadowSize(2048)
end

2.34.18. sceneSetSky

sceneSetSky(file)
sceneSetSky(nil)
sceneSetSky()

Hüllt die Szene in ein äquirektanguläres Panorama: ein Radiance-.hdr (wie HDRI-Seiten sie ausliefern, mit vollem Umfang) oder ein PNG, JPEG oder anderes Bild, das SDL_image liest, aus sRGB decodiert. Der Name ist spielrelativ wie bei spriteLoad. Der Himmel wird hinter allem anstelle der Hintergrundfarbe gezeichnet (sodass das Video nicht mehr durchscheint) und beleuchtet die Szene, sofern nicht sceneSetEnvironment(false) gilt. Seine Mitte zeigt nach -Z und seine Oberseite nach oben. Er wird in einen Würfel mit bis zu 1024 Texeln pro Fläche umgerechnet, sodass ein Bild von 2048 mal 1024 reichlich ist und größere auf einem Raspberry Pi einen Moment zur Vorbereitung brauchen. Ohne Argument oder mit nil wird der Himmel entfernt. Beendet das Skript, wenn die Datei nicht gelesen werden kann oder 3D nicht verfügbar ist.

Beispiel
-- Ein bedeckter Himmel für das Hafenlevel, mit einem auf seinen Horizont abgestimmten Nebel.
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)

Die Helligkeit des Himmels und des Lichts, das er wirft, 1 wie geladen; negative Werte werden auf 0 begrenzt. Nützlich, um einen zu hellen PNG-Himmel abzudunkeln, einen .hdr-Himmel zum Hauptlicht der Szene zu machen oder den Himmel ein- und auszublenden. Es multipliziert den Himmel selbst, anders als sceneSetExposure, das alles skaliert.

Beispiel
-- Abenddämmerung:  Der Himmel und sein Licht werden über zehn Sekunden dunkler.
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)

Die Kurve, die das lineare Licht der Szene auf den Bildschirm abbildet, angewandt nach der Belichtung. TONEMAP_NEUTRAL (der Standard) hält die Farben getreu und staucht nur das hellste Licht; TONEMAP_ACES ist die filmische Kurve mit mehr Kontrast und einem wärmeren Auslauf; TONEMAP_NONE schneidet bei Weiß ab. Videomaterialien, unbeleuchtete Oberflächen und der Himmel durchlaufen dieselbe Kurve, sodass ein Spiel, dessen Disc genau wie gefilmt aussehen muss, TONEMAP_NONE mit einer Belichtung von 0 will. Jeder andere Wert beendet das Skript.

Seit: 3.00. Siehe auch: sceneSetExposure, sceneSetBloom

Beispiel
-- Ein filmischer Look für die Zwischensequenz, getreue Farben fürs Spielen.
function onCutsceneStart()
    sceneSetTonemap(TONEMAP_ACES)
    sceneSetExposure(0.5)
end

function onCutsceneEnd()
    sceneSetTonemap(TONEMAP_NEUTRAL)
    sceneSetExposure(0)
end

2.35. Skript

Mit diesen Funktionen übergibt ein Singe-Skript die Kontrolle an ein anderes Singe-Skript: der Mechanismus hinter dem eingebauten Launcher Menu.singe. Spieleentwickler sollten nicht zu ihnen greifen; bau dein Spiel als ein einziges Skript und überlass die Verkettung dem Menüsystem. Sie sind hier der Vollständigkeit halber dokumentiert und für alle, die das Menü selbst pflegen.

Beide Aufrufe nehmen eine Tabelle in der Form eines GAMES[]-Eintrags in games.dat und stellen sie für die Skriptausführung der Engine in die Warteschlange. Die neue Konfiguration geht von der laufenden aus, sodass Befehlszeilenoptionen wie der Datenordner und der Trace übernommen werden, die Disc, das Video und der Container aber nie: Jeder Eintrag bringt seine eigenen mit. Das aktuelle Skript endet am Ende des Frames, onShutdown wird ausgelöst, und das wartende Skript startet mit einem frischen Lua-Zustand (siehe Engine-Callbacks). Der Datenordner des neuen Skripts folgt derselben Regel wie ein Start über die Befehlszeile (siehe singeGetDataPath); kann er nicht angelegt werden, wird das aufrufende Skript abgebrochen.

2.35.1. scriptExecute

scriptExecute(config)

Ersetzt das laufende Skript durch das, welches die Tabelle beschreibt. Das aktuelle Skript hält am Ende dieses Frames an, und onShutdown läuft; die Kontrolle kehrt nie zu ihm zurück, und wenn das neue Skript endet, geht die Engine zu dem über, was sonst noch in der Warteschlange steht, oder beendet sich. Die String-Schlüssel, die die Engine kennt, sind SCRIPT, CONTAINER, VIDEO, STRETCH, NO_MOUSE, RESOLUTION_X, RESOLUTION_Y, SINDEN_GUN, AUDIO_TRACK, AUDIO_DELAY, LEGACY_SPRITE_ARGS, CANVAS_X und CANVAS_Y; andere Schlüssel werden ignoriert, und Schlüssel, die keine Strings sind, werden übersprungen. Ein SCRIPT, CONTAINER oder VIDEO, das kein String ist, bricht das Skript ab, und ebenso ein Argument, das keine Tabelle ist.

Parameter:

  • config — eine Tabelle mit games.dat-Feldern, mindestens SCRIPT oder CONTAINER.

Seit: 2.00 Siehe auch: scriptPush, singeQuit

Beispiel
-- Ein Launcher, der nie zu sich selbst zurückkehrt.
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)

Startet das Skript, das die Tabelle beschreibt, und stellt die aktuelle Konfiguration dahinter in die Warteschlange, sodass das aktuelle Skript, wenn das neue endet, wieder von vorn läuft. Nichts bleibt erhalten: onShutdown des aktuellen Skripts läuft jetzt, sein Lua-Zustand wird verworfen, und der spätere Lauf ist ein Neustart, weshalb Menu.singe seine Auswahl vor dem Push in eine Datei speichert. Die Tabelle nimmt dieselben Schlüssel wie scriptExecute.

Parameter:

  • config — eine Tabelle mit games.dat-Feldern, wie bei scriptExecute.

Seit: 2.00 Siehe auch: scriptExecute, singeQuit, onShutdown

Beispiel
-- Menu.singe: das gewählte Spiel starten und danach zurückkommen.
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

Die Funktionen im Namensraum singe* steuern die Engine selbst: das Fenster, Screenshots, das Pausensystem, Beenden und Neuladen, die Audioverzögerung für Lippensynchronität und ein paar Pfade und Flags, die von der Befehlszeile und aus games.dat kommen. Nichts hier nimmt ein Handle. Das Pausenverhalten ist unter Pausieren beschrieben, die Werte der Audioverzögerung unter Audio-Synchronisation.

2.36.1. allowSocketCall

allowed = allowSocketCall()

Hypseus-Erweiterung, in Singe immer false. Hypseus antwortet damit, ob der Benutzer ihm erlaubt hat, Daten an einen Statistikserver zu senden, was dort -noserversend abschaltet; das Senden selbst ist dort auskommentiert. Singe sendet nirgendwohin etwas, also ist nichts erlaubt, und die Antwort ändert sich nie. Die Funktion gibt es, damit ein Spiel, das fragt, nicht an einer fehlenden Funktion stehen bleibt.

Rückgabe: ein Boolean, immer false.

Seit: 3.00

2.36.2. getUserString

id = getUserString()

Hypseus-Erweiterung, immer ein leerer String. Trotz des Namens ist es kein String, den der Benutzer gesetzt hat: Hypseus antwortet mit der Installations-ID des Rechners, die es mit Netzwerkstatistiken sendet, genommen aus der MachineGuid von Windows oder der Machine-ID von Linux. Singe sendet nirgendwohin etwas und gibt einem Spiel keinen Fingerabdruck des Rechners, auf dem es läuft.

Rückgabe: ein String, immer leer.

Seit: 3.00 Siehe auch: allowSocketCall

2.36.3. singeDisablePauseKey

singeDisablePauseKey()

Übergibt die Pausentaste an das Skript, genau wie singeSetPauseKeyEnabled(false). Es ist eine in Framework.singe definierte Funktion, die erhalten bleibt, damit ältere Spiele unverändert laufen.

Hinweise: Veralteter Alias.

Neuer Code sollte singeSetPauseKeyEnabled mit false aufrufen.

Seit: 1.18 (RDG) Siehe auch: singeSetPauseKeyEnabled, singeEnablePauseKey

Beispiel
-- Älterer Spielcode; die moderne Schreibweise ist singeSetPauseKeyEnabled(false).
singeDisablePauseKey()

function onInputPressed(what)
    if what == SWITCH_PAUSE then
        togglePauseMenu()
    end
end

2.36.4. singeEnablePauseKey

singeEnablePauseKey()

Gibt die Pausentaste an die Engine zurück, genau wie singeSetPauseKeyEnabled(true). Es ist eine in Framework.singe definierte Funktion, die erhalten bleibt, damit ältere Spiele unverändert laufen.

Hinweise: Veralteter Alias.

Neuer Code sollte singeSetPauseKeyEnabled mit true aufrufen.

Seit: 1.18 (RDG) Siehe auch: singeSetPauseKeyEnabled, singeDisablePauseKey

Beispiel
-- Älterer Spielcode; die moderne Schreibweise ist singeSetPauseKeyEnabled(true).
function pauseMenuClose()
    singeSetPauseFlag(false)
    singeEnablePauseKey()
end

2.36.5. utilFileMove

ok = utilFileMove(from, to)

Verschiebt die Datei from nach to und ersetzt in einem Schritt, was dort liegt: to ist in jedem Augenblick entweder die Datei, die es war, oder die neue als Ganzes, nie verschwunden und nie halb geschrieben, was os.rename unter Windows nicht verspricht und das Überschreiben einer Datei an Ort und Stelle nirgends. from wird zuerst auf die Platte gebracht. Liegen beide auf verschiedenen Platten, wird die Datei unter einem vorläufigen Namen neben to kopiert, jeder Schreibvorgang geprüft, und bekommt den Namen erst, wenn die Kopie vollständig ist. Gedacht, um einen Download oder eine frisch geschriebene Datei an die Stelle einer zu setzen, die funktioniert. Beide sind Pfade auf der Platte, wie io.open sie nimmt.

Parameter:

  • from — String, die Datei, die verschoben wird.

  • to — String, wohin sie kommt.

Rückgabe: true, oder false, wenn es nicht ging: to ist dann, wie es war, und from ist noch da.

Seit: 3.00. Siehe auch: utilFilePart, utilSha256File

Beispiel
-- Die neuen Einstellungen neben die alten schreiben, dann tauschen.
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)

Der Name, unter dem eine Datei geschrieben wird, bevor utilFileMove sie an path setzt: path, gefolgt von einer Zahl, die zu diesem laufenden Singe gehört, und .part. Zwei Singe, die dieselbe Datei gleichzeitig schreiben, etwa dasselbe Spiel zweimal gestartet, schreiben dann jeweils ihre eigene Datei statt gemeinsam in eine, und behalten wird die des Singe, das zuletzt fertig wird. Die Anfrage entfernt außerdem, was ein mittendrin beendetes Singe für denselben path zurückgelassen hat, sodass sich nichts ansammelt.

Parameter:

  • path — String, wohin die fertige Datei kommt.

Rückgabe: Der Name, unter dem geschrieben wird, ein String. Er ist jedes Mal derselbe, wenn dieses Singe für denselben path fragt.

Seit: 3.00. Siehe auch: utilFileMove

Beispiel
-- Den Geist der besten Runde behalten, ohne dass je eine halb geschriebene Datei seinen Platz einnimmt.
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)

SHA-256 eines Strings, als 64 Hexadezimalzeichen in Kleinbuchstaben. Binärsicher, funktioniert also mit den Bytes einer Datei ebenso gut wie mit Text.

Um zu entscheiden, ob die Bytes, die du hast, die Bytes sind, die dir versprochen wurden: ein heruntergeladenes Spiel gegen den Hashwert, den sein Katalogeintrag trägt, oder der öffentliche Schlüssel eines Servers gegen einen Pin. Das mitgelieferte Modul md5 gibt es weiterhin für eine Prüfsumme, aber ein Hashwert, mit dem entschieden wird, ob man etwas vertraut, muss einer sein, dem man noch vertrauen kann.

Parameter:

  • data — ein String aus Bytes. Ein leerer bricht das Skript ab.

Rückgabe: String, 64 Hexadezimalzeichen in Kleinbuchstaben.

Seit: 3.00.

Beispiel
-- Einen Download ablehnen, der nicht unversehrt angekommen ist.
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)

SHA-256 des Inhalts einer Datei, wie utilSha256 es für einen String liefert, blockweise gelesen, sodass die Datei nie als Ganzes im Speicher liegt: Ein Spiel kann mehrere Gigabyte groß sein. path ist ein Pfad auf der Platte, wie io.open ihn nimmt.

Parameter:

  • path — String, die Datei, die gelesen wird.

Rückgabe: String, 64 Hexadezimalzeichen in Kleinbuchstaben, oder nil, wenn die Datei nicht gelesen werden kann.

Seit: 3.00. Siehe auch: utilSha256, utilFileMove

Beispiel
-- Einen Download ablehnen, der nicht unversehrt angekommen ist, egal wie groß er ist.
if utilSha256File("game.part") ~= expected then
    os.remove("game.part")
end

2.36.9. singeCapabilities

capabilities = singeCapabilities()

Was dieser Rechner ausführen kann. Die Tabelle hat einen Eintrag pro Fähigkeitsname, den eine REQUIRES-Liste in games.dat verwenden kann (SCENE, GUI, SHADOWS, POST, SKIN, MORPH), jeder true oder false, sowie tier: die gemessene Leistungsklasse des Rechners von 0 (kein 3D) bis 3 (eine Desktop-GPU), oder nil, bevor das Menü sie gemessen hat. Ein Spiel fragt, damit es auf etwas verzichten kann, statt deswegen abgewiesen zu werden.

Rückgabe: eine Tabelle.

Seit: 3.00. Siehe auch: singeHasGpu, singeSaveTier, sceneMeasure

Beispiel
-- Schatten, wo der Rechner sie hat, eine einfache Sonne, wo nicht.
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()

Gibt die geltende Audioverzögerung des Rechners in Millisekunden zurück: den Wert, den der Kalibrierbildschirm des Menüs in machine.cfg im obersten Datenordner gespeichert hat, oder einen seitdem mit singeSetAudioCalibration gesetzten. Null, wenn der Rechner nie kalibriert wurde. Sie gilt für jedes Spiel auf dem Rechner, zusätzlich zur Verzögerung pro Spiel aus singeGetAudioDelay.

Rückgabe: ganzzahlige Millisekunden.

Beispiel
-- Menu.singe: den Kalibrierbildschirm mit dem gespeicherten Wert beginnen.
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()

Gibt die geltende Audioverzögerung des Spiels in Millisekunden zurück, ob sie aus --audiodelay, aus dem Schlüssel AUDIO_DELAY im games.dat-Eintrag des Spiels oder von singeSetAudioDelay kommt. Null, wenn keine gesetzt wurde. Sie wird zur Kalibrierung des Rechners und zur gemessenen Gerätelatenz addiert, wenn die Engine entscheidet, wann jeder Videoframe gezeigt wird.

Rückgabe: ganzzahlige Millisekunden.

Beispiel
-- Service-Menü: den aktuellen Sync-Versatz neben seinem Schieberegler zeigen.
function drawSyncSetting(y)
    local delay = singeGetAudioDelay()
    fontPrint(40, y, string.format("A/V offset: %+d ms", delay))
end

2.36.12. singeGetAudioLatency

milliseconds = singeGetAudioLatency()

Gibt die Warteschlange des Audiogeräts zurück, die die Engine beim Öffnen des Mixers gemessen hat, in Millisekunden: die Zeit zwischen der Übergabe von Samples an den Mixer und ihrem Eintreffen am Gerät, vor jeder Kalibrierung oder Verzögerung pro Spiel. Die Engine gleicht sie bereits aus; ein Kalibrierbildschirm braucht sie, um sein Klicken und seinen Blitz zu planen, und in einer Diagnoseansicht lohnt es sich, sie auszugeben.

Rückgabe: ganzzahlige Millisekunden.

Beispiel
-- Menu.singe: Der Blitz folgt dem Klicken um die Gerätewarteschlange plus den Kandidaten.
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()

Gibt den Ordner zurück, in den Singe für dieses Spiel schreibt, mit einem abschließenden Pfadtrenner, sodass ein Dateiname direkt angehängt werden kann. Es ist ein nach dem Spiel benannter Unterordner der Basis von --datadir (bei einem gepackten Spiel der Name der Datenbank und dann der Ordner des Skripts darin); ohne --datadir ist die Basis data im Spieleverzeichnis. Screenshots, Videoindizes und trace.txt landen dort, und dorthin gehören auch Spielstände, Highscores und Einstellungen; Singe 2.x schrieb sie neben das Spiel, das schreibgeschützt sein kann.

Rückgabe: String-Pfad, der auf einen Trenner endet.

Seit: 2.00 Siehe auch: singeGetScriptPath, singeScreenshot

Beispiel
-- Menu.singe behält seine letzte Auswahl zwischen den Läufen.
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()

Die GAME_ID aus dem games.dat-Eintrag dieses Spiels, oder nil, wenn er keine hat. Es ist die ID, unter der der Online-Dienst das Spiel kennt, und der Schlüssel, unter dem eine Bestenliste geführt wird.

Das Format ist eine UUID, in der kanonischen Form mit 36 Zeichen — acht Hexziffern, drei Gruppen zu vier, dann zwölf, durch Bindestriche getrennt:

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

Nichts anderes wird angenommen. Die ID ist ein Pfadsegment in den URLs des Dienstes, sodass eine mit einem Schrägstrich oder Fragezeichen veröffentlicht würde und dann nie erreichbar wäre, und zwei IDs, die sich nur in der Groß- und Kleinschreibung unterscheiden, wären für die Datenbank zwei Spiele und für jeden, der sie liest, eines. Verglichen wird ohne Rücksicht auf Groß- und Kleinschreibung, gespeichert in Kleinbuchstaben, sodass eine in Großbuchstaben getippte ID dasselbe Spiel ist.

Jede UUID tut es — erzeug eine, wie du willst, oder lass publish.lua eine ausgeben. Ein Spiel ohne ID kann gespielt, aber nicht gewertet werden: Es gäbe nichts Beständiges, unter dem eine Bestenliste geführt werden könnte, und eine zur Laufzeit erfundene ID ergäbe jedes Mal eine andere Bestenliste, wenn die Dateien verschoben werden.

Ein .game, eine ID. Ein .game mit mehreren Einträgen in seiner games.dat — eine Sammlung oder ein Spiel in zwei Sprachen — ist ein einziger Download, und jeder Eintrag darin trägt dieselbe GAME_ID. Der Online-Dienst führt jeden Eintrag als eigenes Spiel und nimmt kein .game an, dessen Einträge sich über ihre ID uneinig sind oder bei dem sie in einem Eintrag fehlt. Ihre Punkte bleiben trotzdem getrennt: siehe Online-Highscores.

Rückgabe: String oder nil.

Seit: 3.00. Siehe auch: Online-Highscores, games.dat

Beispiel
-- Die Bestenliste nur anbieten, wenn dieses Spiel eine Identität hat, unter der es gewertet wird.
if singeGetGameId() then
    showLeaderboardButton()
end

2.36.15. singeGetHeight

height = singeGetHeight()

Gibt die Höhe des Singe-Fensters in Bildschirmpixeln zurück, nicht in Overlay-Einheiten, so wie das Fenster im Moment des Aufrufs ist. Zum Zeichnen nimm overlayGetHeight; dies ist für einen Einstellungsbildschirm, der die Anzeige meldet, oder um zu entscheiden, wie viel Detail sich eine Szene leisten kann.

Rückgabe: ganzzahlige Pixel.

Seit: 1.x Siehe auch: singeGetWidth, overlayGetHeight

Beispiel
-- Die Anzeige im Service-Menü melden.
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()

Gibt das Pausenflag der Engine zurück: true, solange das Spiel durch die Pausentaste oder durch singeSetPauseFlag pausiert ist. Das ist unabhängig davon, ob die Disc auf einem angehaltenen Frame steht (discGetState); lies es, um zu wissen, ob eine Pause absichtlich angefordert wurde. Solange die Pausentaste das Spiel eingefroren hält, läuft kein Callback, sodass das Flag aus einem Callback heraus nur nach dem eigenen singeSetPauseFlag(true) des Skripts als true zu sehen ist.

Rückgabe: Boolean.

Seit: 1.x (RDG) Siehe auch: singeSetPauseFlag, singeSetPauseKeyEnabled

Beispiel
-- Timer stehen still, solange die eigene Pause des Spiels aktiv ist.
function onOverlayUpdate()
    if not singeGetPauseFlag() then
        elapsed = elapsed + 1
        updateEnemies()
    end
    drawFrame()
    return OVERLAY_UPDATED
end

2.36.17. singeGetScriptPath

path = singeGetScriptPath()

Gibt den Pfad der laufenden Skriptdatei zurück, so wie die Engine ihn aufgelöst hat. Framework.singe leitet aus diesem Wert die globale Variable DIR ab, den Ordner des Skripts mit abschließendem Trenner, und mit DIR bauen die meisten Spiele die Pfade zu ihren Assets.

Rückgabe: String-Pfad.

Seit: 1.15 (RDG) Siehe auch: singeGetDataPath

Beispiel
-- So leitet Framework.singe DIR ab; Spiele laden dann relativ dazu.
DIR = singeGetScriptPath():match("(.*[/\\])") or "./"
titleSprite = spriteLoad(DIR .. "images/title.png")

2.36.18. singeGetSystemInfo

info = singeGetSystemInfo()

Alles, was der Kopf des Trace über diesen Rechner und diesen Lauf weiß, in einer Tabelle. Sie ist für einen Service-Bildschirm und für Fehlerberichte gedacht: die Antwort auf „worauf lief es“, ohne den Spieler zu bitten, ein Log zu suchen.

Rückgabe: eine Tabelle mit diesen Feldern, alle Strings außer den vier Größen:

  • version — die Version der Engine, wie SINGE_VERSION_STRING.

  • os — Name und Release des Betriebssystems sowie die Architektur.

  • cpu — der Prozessor, seine Kernzahl und der Speicher in Megabyte.

  • renderer — der Name des verwendeten 2D-Renderers von SDL.

  • gpu — der SDL_GPU-Treiber hinter der 3D-Szene oder ein Hinweis, dass 3D nicht verfügbar ist.

  • decoder — welche Hardware-Videodecoder der Build versuchen wird, in Worten.

  • audio — die einkompilierten Audioformate, durch Kommas getrennt.

  • soundFont — der SoundFont, den die MIDI-Wiedergabe verwendet, oder warum es keinen gibt.

  • midi — die offenen MIDI-Ports oder ein Hinweis, dass keine angefordert wurden.

  • dataPath — der Datenordner dieses Spiels.

  • dataRoot — der Datenordner, der der Engine übergeben wurde, direkt über dataPath, unter dem jedes Spiel auf dem Rechner schreibt.

  • platform — der Plattformteil des Release-Namens, etwa Linux-x86_64: welches Release diese ausführbare Datei ist und nach welchem man den Dienst fragt.

  • executable — der absolute Pfad der laufenden ausführbaren Datei.

  • windowWidth, windowHeight — Ganzzahlen, das Fenster in Pixeln.

  • canvasWidth, canvasHeight — Ganzzahlen, die Zeichenfläche in Pixeln.

Seit: 3.00. Siehe auch: singeGetDataPath, Die Service-Tools

Beispiel
-- Ein Diagnosebildschirm auf eine Taste.
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()

Gibt die Zeit der Uhr in Millisekunden seit dem Start der Engine zurück. Es ist die Uhr für Timer, Entprellung und Animation, und sie läuft weiter, während das Spiel durch die Pausentaste eingefroren ist; ein Timer, der pausierte Zeit nicht mitzählen darf, sollte also singeGetPauseFlag lesen oder ab dem Moment des Auftauens messen. Luas os.clock() misst normalerweise Prozessorzeit, die stillsteht, während die Engine untätig ist; Singe ersetzt sie durch echte Sekunden seit dem Start der Engine, sodass bestehende Spiele, die sie als Uhr benutzt haben, weiter funktionieren.

Rückgabe: ganzzahlige Millisekunden.

Seit: 3.00 Siehe auch: singeGetPauseFlag, debugPrint

Beispiel
-- Die Aufforderung „insert coin“ zweimal pro Sekunde blinken lassen.
function drawAttractPrompt()
    local phase = (singeGetTicks() // 250) % 2
    if phase == 0 then
        fontPrint(120, 200, "INSERT COIN")
    end
end

2.36.20. singeGetWidth

width = singeGetWidth()

Gibt die Breite des Singe-Fensters in Bildschirmpixeln zurück, das Gegenstück zu singeGetHeight. Zum Zeichnen auf das Overlay dient stattdessen overlayGetWidth.

Rückgabe: ganzzahlige Pixel.

Seit: 1.x Siehe auch: singeGetHeight, overlayGetWidth

Beispiel
-- Ein Texturbudget nach der Fenstergröße wählen.
local pixels = singeGetWidth() * singeGetHeight()
if pixels > 1920 * 1080 then
    textureSet = "high"
else
    textureSet = "low"
end

2.36.21. singeHasGpu

present = singeHasGpu()

Ob das GPU-Gerät gestartet ist. Alles, was darüber gezeichnet wird, ist ohne eines nicht verfügbar: die 3D-Szene, 3D-Partikel und jedes GUI-Dokument. 2D-Partikel werden mit dem Overlay gezeichnet und brauchen kein Gerät. Frag dies ab, bevor du etwas davon anforderst, denn guiNew und die Szenenaufrufe beenden das Skript, statt false zu antworten — es gibt keine Möglichkeit, es zu versuchen und sich davon zu erholen.

Einem Rechner kann eines fehlen, weil er gar keinen Vulkan-, Direct3D-12- oder Metal-Treiber hat oder weil --nogpu angegeben wurde. Das mitgelieferte Menü ruft dies beim Start auf und wählt anhand der Antwort einen Renderer (siehe Die zwei Renderer).

Rückgabe: Boolean; wahr, wenn ein GPU-Gerät vorhanden ist.

Beispiel
-- Ein Spiel mit einem 3D-Titelbildschirm und einem flachen als Rückfall.
if singeHasGpu() then
    buildSceneTitle()
else
    buildSpriteTitle()
end

2.36.22. singeIsRecording

recording = singeIsRecording()

Ob eine Aufnahme läuft oder angefordert wurde und mit dem nächsten gezeichneten Frame beginnt. Siehe singeRecordStart.

Rückgabe: Boolean.

Seit: 3.00 Siehe auch: singeRecordStart, singeRecordStop

Beispiel
-- Ein roter Punkt in der Ecke des eigenen Pausenbildschirms des Spiels, solange es aufgenommen wird.
if singeIsRecording() then
    overlayCircle(overlayGetWidth() - 12, 12, 5)
end

2.36.23. singePack

result = singePack(directory, database)

Packt das Spiel in directory in die Einzeldatei-Datenbank database, genau wie singe --pack es von der Befehlszeile tut, und gibt true zurück, wenn es gelungen ist. Der Ordner muss der eigene Ordner eines Spiels sein: einer, der keinen Support-Ordner Singe/, keinen Launcher und nichts anderes enthält, was der Packer ablehnt, und die Gründe für eine Ablehnung werden wie bei der Befehlszeile auf der Konsole ausgegeben. So kann ein Autorenwerkzeug ein Spiel veröffentlichen, ohne die Engine zu verlassen.

Parameter:

  • directory — der Ordner des Spiels, so wie der Packer ihn nimmt.

  • database — die zu schreibende .game-Datei; sie wird ersetzt, falls sie existiert.

Rückgabe: true bei Erfolg, sonst false.

Seit: 3.00 Siehe auch: Spiele in einer Datei

Beispiel
-- Das Spiel neben seinem Ordner veröffentlichen und Bescheid geben.
if singePack(singeGetDataPath() .. "CoinRun", singeGetDataPath() .. "CoinRun.game") then
    debugPrint("packed")
end

2.36.24. singeQuit

singeQuit()

Beendet das laufende Skript am Ende dieses Frames: Die Spielschleife hält an, onShutdown läuft, und die Engine geht zum nächsten wartenden Skript über oder beendet sich, wenn es keines gibt. Ein aus dem Menü mit scriptPush gestartetes Spiel kehrt deshalb zum Menü zurück, das von vorn beginnt. Im Thread-Modell erledigt das die Rückkehr aus singeMain für dich. Der Schalter, der in controls.cfg auf INPUT_QUIT gelegt ist, und das Schließen des Fensters beenden das Skript auf dieselbe Weise. Ruf es nicht aus onShutdown auf, das schon der Weg nach draußen ist.

Seit: 1.x (RDG) Siehe auch: onShutdown, singeReload, scriptPush

Beispiel
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)

Beendet die Engine wie singeQuit und startet, sobald alles abgebaut ist, die ausführbare Datei unter path an ihrer Stelle mit denselben Argumenten. So bringt das Tool Engine Update des Menüs einen Automaten auf ein neueres Singe, das es neben das laufende gelegt hat: Die neue Datei wird ausführbar gemacht und gestartet, und unter Windows, das ein laufendes Image nicht ersetzt, wird sie neben diesem unter ihrem eigenen Namen gestartet. Die Datei muss bereits existieren; andernfalls antwortet der Aufruf false, ohne etwas zu tun. Hier wird nichts entpackt oder kopiert: Das neue Singe entpackt seine eigenen Support-Dateien beim ersten Lauf.

Ist path nicht die laufende ausführbare Datei, wird die laufende unmittelbar vor dem Start der neuen neben sich selbst als old-<name> beiseitegelegt, ein Name, nach dem kein Launcher sucht. Lässt sich die neue nicht starten, bekommt die alte ihren Namen zurück, und die Datei, die nicht starten wollte, wird in failed-<name> umbenannt, sodass der Launcher weiterhin ein Singe findet, das funktioniert.

Parameter:

  • path — die zu startende ausführbare Datei.

Rückgabe: true, wenn der Neustart eingerichtet ist, false, wenn die Datei nicht da ist.

Seit: 3.00 Siehe auch: singeQuit, singeGetSystemInfo

Beispiel
-- Ein neueres Singe wurde heruntergeladen und geprüft;  an es übergeben.
local folder = singeGetSystemInfo().executable:match("^(.*[/\\])")
singeRelaunch(folder .. "Singe-v3.01-Linux-x86_64")

2.36.26. singeRecordStart

singeRecordStart([name])

Beginnt ab dem nächsten gezeichneten Frame, das Spiel aufzunehmen, Bild und Ton zusammen, als MP4 im Datenordner des Spiels (siehe singeGetDataPath). Ohne Namen heißen die Dateien singe000.mp4 aufwärts, wie bei Screenshots; mit einem Namen geht die Aufnahme in diese Datei, wobei .mp4 angehängt wird, wenn der Name keine Endung hat, und eine Datei dieses Namens ersetzt wird, und ein Name, der einen Ordner enthält, bricht das Skript ab. Ein Aufruf während einer laufenden Aufnahme wird ignoriert. Der Schalter, der in controls.cfg auf INPUT_RECORD gelegt ist, standardmäßig F10, startet und stoppt dieselben Aufnahmen.

Das Bild ist das ganze Fenster, wie es gezeigt wird, Letterbox eingeschlossen, in Fenstergröße, genau das, was ein Screenshot erfasst; der Ton ist die fertige Mischung, Musik, Effekte und Video-Tonspuren zusammen. Beides wird in einem eigenen Thread codiert, sodass das Spiel für das Zurückkopieren jedes Frames von der GPU bezahlt und für wenig sonst. Das Bild ist H.264, wo der Rechner einen Hardware-Encoder hat, den Singe benutzen kann — VA-API unter Linux, VideoToolbox unter macOS, Media Foundation unter Windows, V4L2 auf den ARM-Boards, die einen haben — und überall sonst MPEG-4 aus dem eigenen Encoder von FFmpeg; der Ton ist AAC. Der Trace nennt den Encoder, wenn die Aufnahme beginnt, und zählt beim Stoppen alle verworfenen Frames.

Im Spiel läuft die Aufnahme mit 60 Frames pro Sekunde nach der echten Uhr. Ein Frame, der kommt, während der Encoder noch beschäftigt ist, wird aus der Aufnahme verworfen, statt das Spiel warten zu lassen, und der Ton wird um die Warteschlange des Audiogeräts nach hinten verschoben, sodass beides so zusammenpasst wie auf dem Bildschirm. Unter --deterministic läuft die Aufnahme stattdessen mit einem Frame pro Taktschritt, und die Engine wartet auf den Encoder, statt etwas zu verwerfen; mit --record gestartet, mischt ein deterministischer Lauf seinen Ton außerdem Schritt für Schritt in den Speicher, sodass die Aufnahme Frame für Frame und Sample für Sample exakt ist.

Parameter:

  • name — optionaler String; ein Dateiname, kein Pfad.

Rückgabe: nichts.

Beispiel
-- Der Attract-Modus nimmt seinen eigenen Trailer auf:  ein Durchlauf, dann Schluss.
function attractBegin()
    singeRecordStart("trailer")
end

function attractEnd()
    singeRecordStop()
end

2.36.27. singeRecordStop

singeRecordStop()

Schließt die Aufnahme beim nächsten gezeichneten Frame ab: Was noch wartet, wird codiert und die Datei geschlossen, sodass sie von Anfang bis Ende abspielbar ist. Wird ignoriert, wenn nichts aufgenommen wird. Eine Aufnahme, die beim Ende des Spiels noch läuft, wird auf dieselbe Weise abgeschlossen.

Rückgabe: nichts.

Seit: 3.00 Siehe auch: singeRecordStart, singeIsRecording

Beispiel
-- Eine Runde des Spiels aufnehmen:  von der ersten Münze bis Game Over.
function onGameOver()
    singeRecordStop()
end

2.36.28. singeReload

singeReload()

Führt das Spiel am Ende dieses Frames erneut von seinem Skript aus, wie es F5 und eine geänderte Datei unter --reload tun; dieser Aufruf funktioniert auch ohne die Option. Jeder Sound hört auf, der Lua-Zustand wird verworfen, ohne onShutdown aufzurufen, alles, was das Skript geladen hat, wird freigegeben, Szene, Physik (einschließlich ihrer Debug-Zeichnung), Partikel und Navigation werden zurückgesetzt, das Overlay kehrt zu seiner Standardauflösung zurück, und Lautstärke der Soundeffekte, Mausmodus, Mausfang, Tastaturmodus, Pausentaste, Zuhörer und Pausenflag kehren zu ihren Standards zurück. Tasten und Knöpfe, die über das Neuladen hinweg gehalten werden, werden bis zum Loslassen ignoriert, wie bei einem frischen Start, und die Disc wird angehalten auf ihrem ersten Frame geparkt, mit der Standard-Tonspur ausgewählt, wie beim Start. Die Engine selbst (das Fenster, die Controller, die Mäuse) bleibt, wie sie ist. Es passt zum Neustart-Eintrag eines Debug-Menüs oder zu einem Level-Editor, der neu lädt, was er gerade gespeichert hat.

Seit: 3.00. Siehe auch: singeQuit

Beispiel
-- Editor: das Level speichern, dann das Spiel damit neu starten.
function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.F9.value then
        saveLevel(singeGetDataPath() .. "level.lua")
        singeReload()
    end
end

2.36.29. singeSaveGeometry

singeSaveGeometry()

Bewahrt die aktuelle Skalierung, Verschiebung und Drehung des Bildes für diesen Rechner auf. Sie kommen in machine.cfg im obersten Datenordner, neben die Audioverzögerung, und die Engine wendet sie auf jedes Spiel an, das sie danach startet, aus dem Menü oder von der Befehlszeile, und über singeReload hinweg. Eine tatsächlich auf der Befehlszeile eingetippte Option gewinnt: --scalefactor übersteuert die gespeicherte Skalierung, --shiftx oder --shifty die gespeicherte Verschiebung, --rotate die gespeicherte Drehung. Die Datei wird ganz geschrieben, sodass die Audioverzögerung erhalten bleibt, wie sie ist.

Das ist eine Einstellung des Automaten, keine des Spiels: So wird ein Monitor einmal ausgerichtet statt einmal pro Spiel. Das Tool Display im mitgelieferten Menü ist genau dieser Aufruf hinter Knopf 1.

Rückgabe: nichts.

Beispiel
-- Der Betreiber ist mit dem Bild zufrieden:  für den Automaten behalten.
function onInputPressed(input)
    if input == SWITCH_BUTTON1 then
        singeSaveGeometry()
    end
end

2.36.30. singeSaveTier

singeSaveTier(tier)

Bewahrt die Leistungsklasse dieses Rechners, 0 bis 3, in machine.cfg neben der Audioverzögerung und der Geometrie auf, wo singeCapabilities sie meldet und das Menü sie mit dem TIER jedes Spiels vergleicht. Das mitgelieferte Menü misst die Leistungsklasse selbst, daran, wie lange sein 3D-Hintergrund zum Zeichnen braucht (sceneMeasure), und speichert sie nur, wenn sie sich ändert; niemand fragt den Spieler.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: singeCapabilities, singeSaveGeometry

Beispiel
-- Ein Rechner ganz ohne 3D hat Leistungsklasse 0.
if not singeHasGpu() then
	singeSaveTier(0)
end

2.36.31. singeScreenshot

singeScreenshot()
singeScreenshot(name)

Fordert einen Screenshot des ganzen Fensters an, Letterbox eingeschlossen, aufgenommen nach dem Zeichnen des nächsten Frames und als PNG im Datenordner des Spiels gespeichert (siehe singeGetDataPath). Ohne Namen heißen die Dateien singe000.png aufwärts; jeder Skriptlauf sucht ab null nach dem ersten freien Namen, und spätere Aufnahmen machen nach der zuletzt gespeicherten weiter. Mit einem Namen geht die Aufnahme in diese Datei, wobei .png angehängt wird, wenn der Name keine Endung hat, und eine Datei dieses Namens ersetzt wird; ein Name, der einen Ordner enthält, bricht das Skript ab. Den Screenshot zu benennen ist für Skripte gedacht, die absichtlich Bilder erzeugen, etwa die, die die Anleitungen eines Buches bebildern, damit ein erneuter Lauf das Bild ersetzt, statt eines hinzuzufügen. Der Aufruf erzwingt ein Neuzeichnen, sodass die Aufnahme auch gemacht wird, während die Anzeige ruht. Der Schalter, der in controls.cfg auf INPUT_SCREENSHOT gelegt ist, tut dasselbe.

Seit: 1.x Siehe auch: singeGetDataPath

Beispiel
-- Ein Testskript hält ein paar Frames fest, während es durch die Szene fliegt.
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)

Setzt die Audioverzögerung des Rechners, wendet sie sofort an und schreibt sie in machine.cfg im obersten Datenordner, sodass jedes Spiel auf dem Rechner sie übernimmt. Der Kalibrierbildschirm des Menüs ruft es auf; ein Spiel mit eigenem Service-Menü darf das auch. Der Wert ist positiv, wenn der Ton später zu hören ist, als das Gerät meldet; die Engine verzögert die Videoanzeige um so viel. Werte außerhalb von -1000 bis 1000 brechen das Skript ab. Kann machine.cfg nicht geschrieben werden, gilt der Wert für diesen Lauf trotzdem, und eine Meldung geht an die Konsole.

Parameter:

  • milliseconds — Ganzzahl, -1000 bis 1000, positiv, wenn der Ton zu spät kommt.

Beispiel
-- Menu.singe: die vom Spieler eingestellte Kalibrierung behalten oder verwerfen.
function calibrationEnd(save)
    if save then
        singeSetAudioCalibration(CAL_VALUE)
    end
    CALIBRATING = false
end

2.36.33. singeSetAudioDelay

singeSetAudioDelay(milliseconds)

Setzt die Audioverzögerung des Spiels für diesen Lauf: wie viel später (positiv) oder früher (negativ) der Ton zu hören ist, als die Engine messen kann, sodass sich die Videoanzeige passend verschiebt. Sie gilt für die Disc und für jedes Video, das das Skript abspielt, zusätzlich zur Kalibrierung des Rechners. Nichts wird gespeichert; ein Spiel, das die Einstellung in einem Service-Menü anbietet, speichert den Wert mit seinen anderen Einstellungen und ruft dies beim Start erneut auf. Werte außerhalb von -1000 bis 1000 brechen das Skript ab.

Parameter:

  • milliseconds — Ganzzahl, -1000 bis 1000, positiv, wenn der Ton zu spät kommt.

Beispiel
-- Service-Menü: den Versatz ein wenig verschieben und merken.
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)

Setzt den Titel des Singe-Fensters. Ruf es einmal beim Start mit dem Anzeigenamen des Spiels auf; nichts anderes verwendet den Wert. Das Argument muss ein String oder eine Zahl sein.

Parameter:

  • title — der Fenstertitel.

Seit: 1.15 (RDG) Siehe auch: singeVersion

Beispiel
singeSetGameName("Asteroid Patrol")
keyboardSetMode(MODE_NORMAL)
hudFont = fontLoad(DIR .. "fonts/FreeSansBold.ttf", 18)

2.36.35. singeSetPauseFlag

singeSetPauseFlag(paused)

Setzt das Pausenflag der Engine aus dem Skript. true hält die Disc an, falls sie läuft, sowie jedes geladene Video und jeden Soundeffekt-Kanal und merkt sich, welche liefen; false setzt genau diese fort. Anders als die Pausentaste friert dies das Skript nicht ein: Callbacks werden weiter ausgelöst, sodass das Skript sein Pausenmenü zeichnen und entscheiden kann, wann es das Flag löscht. Spiele, die ihre eigene Pause verwalten, sollten außerdem mit singeSetPauseKeyEnabled(false) die Pausentaste übernehmen, denn die Taste der Engine schaltet dasselbe Flag um und würde sonst gegen das Skript arbeiten. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • paused — Boolean.

Seit: 1.x (RDG) Siehe auch: singeGetPauseFlag, singeSetPauseKeyEnabled

Beispiel
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)

Legt fest, wem die Pausentaste gehört, die in controls.cfg auf INPUT_PAUSE gelegt ist. Solange sie aktiviert ist (der Standard, bei jedem Neuladen wiederhergestellt), gehört sie der Engine: Ein Druck auf die Taste friert das Spiel vollständig ein (siehe Pausieren), und in MODE_NORMAL erhält das Skript nie SWITCH_PAUSE. Solange sie deaktiviert ist, ignoriert die Engine die Taste, und SWITCH_PAUSE erreicht onInputPressed und onInputReleased wie jeder andere Schalter, sodass das Spiel mit singeSetPauseFlag seine eigene Pause betreiben kann. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Beispiel
-- Die Engine darf während des Spiels pausieren, aber nicht, während der Spieler seine Initialen eingibt.
function beginInitials()
    singeSetPauseKeyEnabled(false)
    keyboardSetMode(MODE_FULL)
end

function endInitials()
    keyboardSetMode(MODE_NORMAL)
    singeSetPauseKeyEnabled(true)
end

2.36.37. singeSetQuitKeyEnabled

singeSetQuitKeyEnabled(enabled)

Hypseus-Erweiterung. Legt fest, ob sich die Engine beim Schalter beendet, der in controls.cfg auf INPUT_QUIT gelegt ist, ob von der Tastatur oder einem Controller. Ist es aktiviert (der Standard, bei jedem Neuladen wiederhergestellt), beendet ein Druck darauf das Spiel. Ist es deaktiviert, ignoriert die Engine den Schalter, sodass ein Spiel erst nachfragen oder speichern kann; das Skript erhält SWITCH_QUIT in jedem Fall über onInputPressed und onInputReleased, und singeQuit beendet das Spiel weiterhin. Der Schließen-Knopf des Fensters beendet immer. Framework.singe definiert keyboardCatchQuit(catch), den Namen von Hypseus Singe für dieselbe Einstellung mit umgekehrtem Sinn. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: keyboardCatchQuit, singeSetPauseKeyEnabled, singeQuit

Beispiel
-- Nachfragen, bevor ein laufendes Spiel verlassen wird.
singeSetQuitKeyEnabled(false)

function onInputPressed(what)
    if what == SWITCH_QUIT then
        if confirmQuit() then
            singeQuit()
        end
    end
end

2.36.38. singeVersion

version = singeVersion()

Gibt die Version der Engine als Zahl zurück, Hauptversion plus Nebenversion als Bruchteil, sodass 3.00 als 3 zurückkommt. Vergleich sie mit < und >=, um eine zu alte Engine abzulehnen oder um Funktionen herum zu verzweigen; SINGE_VERSION_MAJOR, SINGE_VERSION_MINOR und SINGE_VERSION_STRING werden außerdem als globale Variablen gesetzt, für Skripte, die die Teile oder den Text wollen.

Rückgabe: Zahl.

Seit: 1.x (RDG) Siehe auch: singeSetGameName

Beispiel
if singeVersion() < 3 then
    error("This game needs Singe 3.00 or newer, found " .. SINGE_VERSION_STRING)
end

2.36.39. singeWantsCrosshairs

wanted = singeWantsCrosshairs()

Gibt true zurück, sofern Singe nicht mit --nocrosshair gestartet wurde. Zeichne das Software-Fadenkreuz nur, wenn es true zurückgibt; Spieler mit Lightguns, die ihr eigenes Fadenkreuz auf den Bildschirm bringen, schalten das der Software mit dieser Option ab. Der Wert ändert sich während eines Laufs nicht, lies ihn also einmal.

Rückgabe: Boolean.

Seit: 2.00 Siehe auch: mouseGetPosition, onMouseMoved

Beispiel
drawCrosshair = singeWantsCrosshairs()

function onOverlayUpdate()
    overlayClear()
    drawTargets()
    if drawCrosshair then
        spriteDraw(reticle, cursorX, cursorY, true)
    end
    return OVERLAY_UPDATED
end

2.37. Soft Bodies

Stoff, Druckkörper und Seile: Meshes, deren Vertices als Partikel simuliert werden (siehe Physik, Soft Bodies). Ein Soft Body wird über seinen Knoten angesprochen, und ein Knoten ohne einen beendet in jedem Aufruf nach softNew das Skript. Positionen sind in Welteinheiten, Masse in Kilogramm, und die Steifigkeitswerte reichen von 0 bis 1. Die Engine schreibt das Mesh des Knotens nach jedem Schritt aus den Partikeln neu, und die Simulation endet von selbst, wenn der Knoten gelöscht wird oder ein anderes Mesh bekommt. Bis zu 16 Soft Bodies gleichzeitig, mit je bis zu 32 Pins.

2.37.1. softNew

softNew(node, SOFT_CLOTH)
softNew(node, SOFT_BODY)
softNew(node, SOFT_ROPE, x, y, z, segments, radius)

Bei SOFT_CLOTH und SOFT_BODY wird das Mesh des Knotens, mit drei oder mehr Vertices, zu den Partikeln: Vertices an derselben Position (innerhalb von 0.0001 Einheiten) werden zu einem verschweißt, dort platziert, wo die Transformation des Knotens sie in der Welt hinsetzt, und die Dreiecke ergeben die Dehnungs-, Scher- und Biege-Constraints. Stoff kollidiert auf beiden Seiten und ist das, was ein offenes Tuch braucht; ein Körper ist ein geschlossenes Mesh, das softSetPressure aufblasen kann. Bei SOFT_ROPE braucht der Knoten kein Mesh: segments + 1 Partikel laufen in einer Linie von der Weltposition des Knotens bis zum Weltpunkt, der Knoten bekommt ein neues sechsseitiges Röhren-Mesh mit diesem Radius um sie herum (und behält das Material, das er hatte), und die Partikel kollidieren als Kugeln mit diesem Radius, während Partikel von Stoff und Körpern Kugeln mit Radius 0.03 sind. Jede Art beginnt mit Dehnung 0.9, Biegung 0.2, Masse 1 Kilogramm, Dämpfung 0.1 und Druck 0. Ein Soft Body, der schon auf dem Knoten ist, wird entfernt, bevor der neue erzeugt wird, sodass ein fehlschlagender Aufruf den Knoten ohne einen zurücklässt; das Röhren-Mesh eines Seils geht mit, weshalb der Knoten eines Seils nicht zu Stoff oder einem Körper werden kann (der Aufruf scheitert mangels Mesh). Beendet das Skript, wenn Physik nicht verfügbar ist, die Art unbekannt ist, die Zahl der Argumente nicht zur Art passt, das Mesh fehlt, ein Seil keine Segmente oder keinen Radius hat oder schon 16 Soft Bodies existieren.

Parameter:

  • node — der Knoten, der das Mesh trägt (Stoff, Körper), oder der Anfangspunkt des Seils.

  • x, y, z — das ferne Ende des Seils, in Welteinheiten.

  • segments — wie viele Glieder das Seil hat, 1 oder mehr; ein Dutzend ist reichlich.

  • radius — der Radius des Seils, in Welteinheiten; auch die Größe, mit der seine Partikel kollidieren.

Hinweise: Ein Mesh, das sich mehrere Knoten teilen, wird für alle neu geschrieben, also gib einem Soft Body ein eigenes Mesh. Geskinnte Meshes können keine Soft Bodies sein.

Seit: 3.00. Siehe auch: softPin, softSetStiffness, softSetPressure, meshPlane

Beispiel
-- Eine Flagge an der Stange:  ein aufrechtes Gitter, entlang seiner linken Kante angeheftet.
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)                -- Entlang der Stange
end

2.37.2. softDelete

softDelete(node)

Beendet die Simulation und gibt ihren Körper frei. Der Knoten behält sein Mesh in der Form, in der es zuletzt geschrieben wurde, sodass ein fallengelassenes Tuch über der Kiste drapiert bleibt und ein Seil seine Röhre behält; die ursprüngliche Form des Meshs wird nicht wiederhergestellt. Ein Knoten ohne Soft Body beendet das Skript.

Seit: 3.00. Siehe auch: softNew, nodeDelete

Beispiel
-- Sobald sich das Tuch über die Statue gelegt hat, es einfrieren und nicht mehr dafür bezahlen.
function onOverlayUpdate()
    if covering then
        settleFrames = settleFrames + 1
        if settleFrames > 240 then
            softDelete(sheet)                 -- Der Faltenwurf bleibt, wie er ist
            covering = false
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.37.3. softPin

softPin(node, x, y, z)
softPin(node, x, y, z, otherNode)

Sucht das Partikel, das dem Weltpunkt am nächsten liegt, wo immer die Partikel gerade sind, und heftet es fest. Allein wird das Partikel festgehalten, wo es ist; mit otherNode wird es vor jedem Schritt an die Weltposition dieses Knotens versetzt, sodass ein Seil an einem schwingenden Kran hängt und ein Umhang den Schultern folgt. Der Punkt muss nicht auf dem Mesh liegen, da das nächste Partikel gewinnt, und dasselbe Partikel erneut anzuheften ändert nur, wem es folgt. Nach 32 Pins tut der Aufruf nichts.

Parameter:

  • node — der Knoten des Soft Body.

  • x, y, z — ein Weltpunkt; das ihm nächste Partikel wird angeheftet.

  • otherNode — ein Knoten, dem das Partikel von nun an folgen soll.

Seit: 3.00. Siehe auch: softUnpin, softNew, nodeGetWorldPosition

Beispiel
-- Ein Seil vom Haken des Krans hinaus und hinunter, das mit dem Kran schwingt.
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)               -- Das obere Ende fährt am Haken mit

2.37.4. softUnpin

softUnpin(node, x, y, z)

Löst das angeheftete Partikel, das dem Weltpunkt am nächsten liegt. Ist dieses Partikel nicht angeheftet, passiert nichts. Der Körper wird um die aktuelle Form herum neu gebaut, was auch jedes Partikel schlagartig anhält, sodass eine losgelassene Flagge aus der Ruhe zu fallen beginnt.

Seit: 3.00. Siehe auch: softPin

Beispiel
-- Die Ecke des Banners reißt los, wenn die Windböe trifft.
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)

Wie stark sich das Material dagegen wehrt, gedehnt (und, bei Stoff, geschert) und gefaltet zu werden, 0 bis 1; Werte außerhalb werden begrenzt. 1 ist starr, 0 das Lockerste, was der Solver zulässt. Standards 0.9 und 0.2. Der Körper wird um die aktuelle Form herum neu gebaut: Die Ruhelängen werden zu den Längen dieses Moments, und jedes Partikel hält an; richte das Material also ein, bevor sich der Stoff zu bewegen beginnt. Ein Seil hat nur Dehnung.

Parameter:

  • node — der Knoten des Soft Body.

  • stretch — Widerstand gegen Dehnung, 0 bis 1; Standard 0.9.

  • bend — Widerstand gegen Falten, 0 bis 1; Standard 0.2.

Seit: 3.00. Siehe auch: softSetMass, softSetDamping

Beispiel
-- Seide, Segeltuch und eine Gummiplane aus demselben Gitter.
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)

Bläst einen SOFT_BODY auf: 0 (Standard) ist ein schlaffer Beutel und ein paar Einheiten ein praller Ballon; ein negativer Wert wird zu 0. Es ändert den laufenden Körper, ohne ihn neu zu bauen, und weckt ihn, sodass ein Ballon aufgepumpt oder abgelassen werden kann, während er hüpft. Stoff und Seil haben kein Volumen zum Aufblasen.

Seit: 3.00. Siehe auch: softNew, softSetStiffness, meshSphere

Beispiel
softNew(balloon, SOFT_BODY)                  -- Ein meshSphere von 0.5
softSetMass(balloon, 0.6)
softSetPressure(balloon, 8)                  -- Ein praller Ballon

function onOverlayUpdate()
    if punctured then
        pressure = math.max(pressure - 0.1, 0)
        softSetPressure(balloon, pressure)   -- Zischt über ein paar Sekunden hinweg leer
    end
    return OVERLAY_NOT_UPDATED
end

2.37.7. softSetMass

softSetMass(node, kilograms)

Die Masse des ganzen Körpers, gleichmäßig auf seine Partikel verteilt; Standard 1, mindestens 0.001. Angeheftete Partikel wiegen trotzdem nichts. Der Körper wird um die aktuelle Form herum neu gebaut, und jedes Partikel hält an, also setz sie vorab.

Seit: 3.00. Siehe auch: softSetStiffness, softSetDamping

Beispiel
-- Ein an vier Ecken angeheftetes Tuch fängt eine darauf fallende Kiste auf.
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)                        -- Schwer genug, um nicht zu flattern
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)

Wie schnell die Bewegung der Partikel abklingt, 0 aufwärts; Standard 0.1, und ein negativer Wert wird zu 0. Höhere Werte beruhigen eine Flagge, die nicht aufhört, Wellen zu schlagen, oder ein Seil, das ewig schwingt. Der Körper wird um die aktuelle Form herum neu gebaut, und jedes Partikel hält an.

Seit: 3.00. Siehe auch: softSetMass, softSetStiffness

Beispiel
-- Ein Vorhang in stiller Luft kommt schnell zur Ruhe; derselbe Vorhang am offenen Fenster bewegt sich weiter.
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. Sound

Soundeffekte sind Audioclips (WAV ist die sichere Wahl), die in den Speicher geladen und über SDL_mixer gemischt werden, getrennt vom eigenen Ton der Disc und vom Ton der video*-Assets. soundLoad gibt ein Sound-Handle zurück, das die Daten des Clips bezeichnet; soundPlay startet diesen Clip auf einem von sechzehn Mixerkanälen und gibt die Kanalnummer zurück, 0 bis 15, die soundPause, soundResume, soundStop, soundIsPlaying und jeder soundSet*-Aufruf nehmen. Ein Clip kann auf mehreren Kanälen gleichzeitig spielen, und eine Kanalnummer wird wiederverwendet, sobald der Kanal frei ist; halte die beiden Arten von Nummern also auseinander. Eine Gesamtlautstärke der Effekte (soundSetVolume, 0 bis 63) skaliert jeden Kanal. Ein spielender Kanal kann auch in der 3D-Szene sitzen, einem Knoten folgend oder fest an einem Punkt in Welteinheiten, wo er nach seiner Entfernung vom Zuhörer im Stereobild verteilt und abgeschwächt wird (siehe 3D-Szenen); für 2D-Spiele verteilt soundSetPan einen Kanal ohne Szene im Stereobild.

2.38.1. soundFullStop

soundFullStop()

Stoppt jeden Effektkanal auf einmal, pausierte eingeschlossen, und gibt sie zur Wiederverwendung frei. Kein Clip wird entladen; die Handles aus soundLoad bleiben gültig. Jeder Kanal, der spielte oder pausiert war, meldet sich über onSoundCompleted, genau wie nach soundStop. Ruf es bei einem Szenenwechsel oder vor einer Zwischensequenz auf, statt jeden gestarteten Kanal zu verfolgen.

Seit: 1.16 Siehe auch: soundStop, onSoundCompleted

Beispiel
function enterAttractMode()
    soundFullStop()
    ambientChannel = -1
    engineChannel  = -1
    discPlay()
end

2.38.2. soundGetPosition

x, y, z, gain = soundGetPosition(channel)

Meldet, wo ein platzierter Kanal relativ zum Zuhörer sitzt, als Richtung der Länge eins im Bezugssystem des Zuhörers (x positiv nach rechts, y positiv nach oben, z positiv hinter den Zuhörer), und den Lautstärkefaktor, den ihm seine Entfernung gerade gibt, 0 bis 1. Die Werte werden einmal pro Frame aus dem Zuhörer und dem Knoten oder Punkt des Kanals aufgefrischt. Ein Kanal, der seit seinem Start nicht in der Szene platziert wurde, gibt 0, 0, 0, 1 zurück. Gedacht für Anzeigen im Radarstil und zum Prüfen einer Mischung aus einem Testskript; ein Kanal außerhalb von 0 bis 15 bricht das Skript ab.

Rückgabe: drei Zahlen für die Richtung und eine für die Abschwächung durch die Entfernung.

Seit: 3.00. Siehe auch: soundSetNode, soundSetPosition, soundSetRange

Beispiel
-- Einen Pfeil im HUD auf den nächsten hörbaren Gegner richten.
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()

Gibt die Gesamtlautstärke der Effekte zurück, 0 bis 63. Beim Start spiegelt sie die Effektlautstärke von der Befehlszeile wider; ein Spiel, das eine Lautstärkeeinstellung zeigt, sollte sie also lesen, statt das Maximum anzunehmen.

Rückgabe: Ganzzahl, 0 bis 63.

Seit: 1.16 Siehe auch: soundSetVolume

Beispiel
-- Die Effekte absenken, während der Erzähler spricht, und danach zurückholen.
function narratorBegin()
    savedVolume = soundGetVolume()
    soundSetVolume(math.floor(savedVolume / 3))
    narratorChannel = soundPlay(narratorClip)
end

2.38.4. soundIsPlaying

playing = soundIsPlaying(channel)

Prüft, ob ein Kanal gerade spielt. Ein pausierter Kanal meldet false, ebenso ein Kanal, dessen Clip zu Ende ist. Ein Kanal außerhalb von 0 bis 15 bricht das Skript ab; ein Kanal, der bloß verstummt ist, nicht.

Rückgabe: Boolean.

Seit: 1.16 (RDG) Siehe auch: soundPlay, soundPause

Beispiel
-- Den Alarm nicht neu starten, solange er noch tönt.
function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

2.38.5. soundLoad

id = soundLoad(filename)

Lädt einen Audioclip in den Speicher und gibt sein Handle zurück. Der Pfad geht durch das virtuelle Dateisystem des Spiels, er funktioniert also aus einem losen Ordner genauso wie aus einem gepackten Spiel. Lade Clips einmal beim Start, nicht in einem Callback, der jeden Frame ausgelöst wird. Eine Datei, die sich nicht öffnen oder decodieren lässt, bricht das Skript ab.

Rückgabe: ganzzahliges Sound-Handle. Das ist ein Daten-Handle, keine Kanalnummer.

Seit: 1.x Siehe auch: soundPlay, soundUnload

Beispiel
-- Clip-Handles, einmal geladen und in onShutdown entladen.
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)

Hypseus-Erweiterung. Baut einen Sound aus Bytes in einem Lua-String statt aus einer Datei. Jedes Format, das soundLoad liest, wird hier gelesen, und das zurückgegebene Handle wird mit dem Rest der sound-Familie genau gleich verwendet.

Der String darf Nullbytes enthalten; seine Länge, nicht seine erste Null, entscheidet, wie viel gelesen wird. Die Bytes werden während des Aufrufs decodiert, und der String wird nicht behalten, er darf danach also verworfen werden. Bytes, die kein Audio sind, oder ein leerer String beenden das Skript, wie es eine unlesbare Datei bei soundLoad tut.

Nutze es für Audio, das ein Spiel selbst erzeugt, entpackt oder entschlüsselt. Audio, das das virtuelle Dateisystem über seinen Namen erreicht, lädt man besser mit soundLoad, das nicht die ganze Datei in einem Lua-String hält — das gilt auch für Audio in einem gepackten .game.

Parameter:

  • data — String aus Bytes.

Rückgabe: Zahl, das Sound-Handle.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: soundLoad, spriteLoadData, soundPlay

Beispiel
-- Ein Soundeffekt, den das Spiel aus seinem eigenen Archiv entpackt.
local bytes = myArchive:extract("beep.wav")
local beep  = soundLoadData(bytes)
soundPlay(beep)

2.38.7. soundPause

wasPlaying = soundPause(channel)

Pausiert einen Kanal an Ort und Stelle; soundResume setzt ihn an derselben Stelle fort. Ein pausierter Kanal gilt weiter als belegt, soundPlay gibt ihn also nicht an einen anderen Clip aus, und soundIsPlaying meldet für ihn false. Einen Kanal zu pausieren, der nicht spielt, bewirkt nichts. Ein Kanal außerhalb von 0 bis 15 bricht das Skript ab.

Rückgabe: Boolean, true, wenn der Kanal im Moment des Aufrufs spielte.

Seit: 1.16 (RDG) Siehe auch: soundResume, soundIsPlaying

Beispiel
-- Das Motorgeräusch anhalten, während der Funkspruch läuft.
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)

Startet einen geladenen Clip auf dem ersten freien Kanal und gibt die Nummer dieses Kanals zurück. Ein Kanal gilt als frei, wenn er weder spielt noch pausiert ist. Der neue Kanal beginnt mit der Gesamtlautstärke (oder mit volume darunter), mittig, ohne Position in der Szene und mit dem Standardbereich, egal was die vorige Nutzung des Kanals gesetzt hat. Sind alle sechzehn Kanäle belegt, spielt nichts, und -1 (SOUND_ERROR_INVALID) kommt zurück; ein Spiel, das viele sich überlagernde Sounds abfeuert, sollte darauf prüfen. Ein Handle, das nicht geladen ist, bricht das Skript ab.

Parameter:

  • id — Sound-Handle aus soundLoad.

  • loops — 0 (der Standard) spielt den Clip einmal, eine positive Zahl wiederholt ihn so oft zusätzlich, -1 wiederholt ihn, bis er gestoppt wird. Alles unter -1 bricht das Skript ab.

  • volume — die eigene Lautstärke des Kanals, 0 bis 63, unter der Gesamtlautstärke; der Standard ist 63, der Clip so laut, wie die Gesamtlautstärke erlaubt. Ein Wert außerhalb dieses Bereichs bricht das Skript ab. soundSetChannelVolume ändert sie, während der Clip spielt.

Rückgabe: ganzzahlige Kanalnummer, 0 bis 15, oder -1, wenn kein Kanal frei ist.

Seit: 1.x; volume seit 3.00. Siehe auch: soundLoad, soundStop, soundSetChannelVolume, soundSetNode

Beispiel
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)

Setzt einen Kanal, den soundPause angehalten hat, dort fort, wo er aufgehört hat. Einen Kanal fortzusetzen, der nicht pausiert ist, bewirkt nichts. Ein Kanal außerhalb von 0 bis 15 bricht das Skript ab.

Rückgabe: Boolean, true, wenn der Kanal im Moment des Aufrufs pausiert war.

Seit: 1.16 (RDG) Siehe auch: soundPause

Beispiel
function onSoundCompleted(channel)
    if channel == radioChannel then
        radioChannel = -1
        if engineWasRunning then
            soundResume(engineChannel)
        end
    end
end

2.38.10. soundSetChannelVolume

soundSetChannelVolume(channel, volume)

Setzt die eigene Lautstärke eines Kanals, zusätzlich zur Gesamtlautstärke aus soundSetVolume: Der Kanal spielt mit der Gesamtlautstärke mal diesem Wert, mal seiner Abschwächung durch die Entfernung, wenn er in der Szene ist. Jeder Kanal beginnt mit voller Lautstärke, wenn soundPlay ihn nimmt, sofern soundPlay keine Lautstärke bekommen hat, sodass ein leiser Schritt und ein lauter Schuss sich eine Gesamtlautstärke teilen können. Werte außerhalb von 0 bis 63 brechen das Skript ab, ebenso ein Kanal außerhalb von 0 bis 15.

Parameter:

  • channel — Kanalnummer aus soundPlay.

  • volume — Ganzzahl, 0 (stumm) bis 63 (so laut wie die Gesamtlautstärke).

Seit: 3.00 Siehe auch: soundPlay, soundSetVolume

Beispiel
-- Ein Motor, der mit dem Gas lauter wird:  ein wiederholter Clip, dessen Kanallautstärke
-- jeden Frame dem Pedal folgt.
engine = soundPlay(engineClip, -1, 20)

function onOverlayUpdate()
    soundSetChannelVolume(engine, math.floor(20 + throttle * 43))
end

2.38.11. soundSetListener

soundSetListener(node)
soundSetListener()

Wählt den Knoten, von dem aus platzierte Kanäle gehört werden, in die Richtung blickend, in die er blickt. Ohne Argument oder mit nil ist der Zuhörer die Kamera der Szene, was für ein Spiel in der Ich-Perspektive oder mit fester Kamera richtig ist; ein Third-Person-Spiel nimmt meist lieber den Knoten der Spielfigur, damit Sounds um die Figur herum wandern statt um die Kamera. Wird der Knoten später gelöscht, fällt der Zuhörer auf die Kamera zurück. Ein Knoten-Handle, das nicht existiert, bricht das Skript ab.

Seit: 3.00. Siehe auch: soundSetNode, soundSetPosition, cameraSet

Beispiel
-- Verfolgerkamera, aber die Welt vom Auto aus hören.
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)

Hängt einen spielenden Kanal an einen Knoten der Szene, sodass er jeden Frame von dort zu hören ist, wo der Knoten gerade ist: Der Kanal wird im Stereobild in die Richtung des Knotens vom Zuhörer aus verteilt und gemäß soundSetRange nach seiner Entfernung abgeschwächt. Ein Aufruf ohne Knoten oder mit nil nimmt den Kanal mit voller Gesamtlautstärke wieder aus der Szene. Ein Kanal, dessen Knoten gelöscht wird, fällt von selbst auf einfache Wiedergabe zurück. Die Verbindung hält, bis der Kanal gestoppt oder von soundPlay wiederverwendet wird. Ein Kanal außerhalb von 0 bis 15 oder ein Knoten, der nicht existiert, bricht das Skript ab.

Seit: 3.00. Siehe auch: soundSetPosition, soundSetRange, soundSetListener

Beispiel
-- Jede Feuerschale knistert von dort, wo sie steht.
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)

Verteilt einen Kanal für Spiele ohne Szene im Stereobild: -1 ist ganz links, 1 ganz rechts, 0 mittig, und Werte außerhalb dieses Bereichs werden begrenzt. Weg von der Mitte wird nur der gegenüberliegende Lautsprecher leiser; bei pan = 0.5 spielt der linke Lautsprecher mit halber Verstärkung und der rechte mit voller. Der Aufruf nimmt den Kanal aus der Szene, falls soundSetNode oder soundSetPosition ihn dort platziert hatte. Ein Kanal außerhalb von 0 bis 15 bricht das Skript ab.

Seit: 3.00. Siehe auch: soundPlay, soundSetNode

Beispiel
-- Ein vorbeifahrendes Auto danach im Stereobild verteilen, wo es auf dem Overlay ist.
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)

Setzt einen spielenden Kanal an einen festen Punkt in der Szene, in Welteinheiten, und ersetzt jeden Knoten, dem er gefolgt ist. Er wird dann wie ein an einen Knoten gehängter Kanal vom Zuhörer aus im Stereobild verteilt und abgeschwächt. Passt zu einem Sound, der an seinem Platz bleibt, etwa einem Wasserfall oder einem klingelnden Telefon; eine bewegte Quelle geht leichter mit soundSetNode. Ein Kanal außerhalb von 0 bis 15 bricht das Skript ab.

Seit: 3.00. Siehe auch: soundSetNode, soundSetRange, soundGetPosition

Beispiel
-- Der Wasserfall bewegt sich nie, also wird kein Knoten gebraucht.
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)

Legt fest, wie ein platzierter Kanal mit der Entfernung vom Zuhörer leiser wird. Innerhalb von near spielt er mit voller Lautstärke; darüber hinaus ist seine Verstärkung near geteilt durch die Entfernung; über das letzte Fünftel von far blendet er außerdem linear aus und erreicht bei far Stille. Die Standards sind 1 und 30 Welteinheiten und werden wiederhergestellt, wann immer soundPlay den Kanal wiederverwendet. Ein Flüstern will ein kleines far, ein Wasserfall ein großes.

Parameter:

  • channel — Kanalnummer aus soundPlay.

  • near — Entfernung, innerhalb derer der Kanal volle Lautstärke hat, größer als 0.

  • far — Entfernung, bei der er stumm ist, größer als near. Jedes andere Paar bricht das Skript ab.

Seit: 3.00. Siehe auch: soundSetNode, soundSetPosition, soundGetPosition

Beispiel
-- Die Schritte einer Wache sind nur aus der Nähe hörbar; die Sirene trägt weit.
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)

Setzt die Gesamtlautstärke der Effekte und wendet sie sofort auf jeden Kanal an, ob spielend oder pausiert. Die eigene Lautstärke jedes Kanals aus soundSetChannelVolume und, bei platzierten Kanälen, die Abschwächung durch die Entfernung wirken zusätzlich. Werte außerhalb von 0 bis 63 brechen das Skript ab.

Parameter:

  • volume — Ganzzahl, 0 (stumm) bis 63 (am lautesten).

Seit: 1.16 Siehe auch: soundGetVolume, soundSetChannelVolume

Beispiel
-- Lautstärkeregler im Service-Menü, gesteuert über die Schalter links und rechts.
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)

Hält einen Kanal sofort an, ob spielend oder pausiert, und gibt ihn zur Wiederverwendung frei. Der Kanal meldet sich über onSoundCompleted, genau wie wenn der Clip von selbst endet; ein Skript, das in diesem Callback Sounds aneinanderreiht, sollte also prüfen, ob es den Kanal selbst gestoppt hat. Das nächste soundPlay kann dieselbe Nummer wieder ausgeben, verwirf die Nummer also auf der Lua-Seite. Ein Kanal außerhalb von 0 bis 15 bricht das Skript ab.

Rückgabe: Boolean, true, wenn der Kanal im Moment des Aufrufs spielte. Ein pausierter Kanal gibt false zurück, wird aber trotzdem gestoppt.

Seit: 1.x (RDG) Siehe auch: soundFullStop, onSoundCompleted

Beispiel
function playerDied()
    if engineChannel >= 0 then
        soundStop(engineChannel)
        engineChannel = -1
    end
    soundPlay(explosionClip)
    lives = lives - 1
end

2.38.18. soundUnload

soundUnload(id)

Gibt einen geladenen Clip frei und macht sein Handle ungültig. Der Mixer hält die Daten des Clips am Leben, bis jeder Kanal, der ihn noch spielt, gestoppt hat, sodass das Entladen keinen spielenden Kanal abschneidet. Jede spätere Verwendung des Handles, auch ein weiteres soundUnload, bricht das Skript ab. Der übliche Ort dafür ist onShutdown.

Parameter:

  • id — Sound-Handle aus soundLoad, keine Kanalnummer.

Seit: 2.00 Siehe auch: soundLoad, onShutdown

Beispiel
function onShutdown()
    soundUnload(shotClip)
    soundUnload(missClip)
    soundUnload(coinClip)
    soundUnload(ambientClip)
    fontUnload(hudFont)
end

2.39. Sprite

Sprites sind 2D-Bitmaps, die mit spriteLoad von der Festplatte geladen oder mit fontToSprite aus Text gerendert und in Overlay-Koordinaten auf das Overlay gezeichnet werden. Jeder sprite*-Aufruf nimmt das ganzzahlige Handle als erstes Argument (Singe 2.10 stellte es ans Ende; siehe Umstieg von Singe 2.10), und ein Handle, das entladen wurde, beendet das Skript mit einem Fehler. Jedes Format, das SDL_image liest, wird angenommen; ein animiertes GIF oder WEBP mit zwei oder mehr Frames lädt als Animation, die auf Frame 0 steht, angehalten und ohne Wiederholung, bis spritePlay und spriteLoop etwas anderes sagen. Farbe 0 wird transparent gezeichnet, wie bei Hypseus: Palettenindex 0 oder reines Schwarz, und das schließt deckendes Schwarz in einem Bild mit Alphakanal ein, dessen Alpha ebenfalls beachtet wird. Um das deckende Schwarz eines Bildes zu behalten, lade es nach drawTransparent(true). Gib jedes Sprite mit spriteUnload frei, meist aus onShutdown.

Sprite-Sheets. Hypseus Singe erweitert die Familie um Sprite-Sheets: spriteLoadFrames zerlegt einen einzeiligen Streifen gleich großer Frames in eine Animation, die nicht läuft, und spriteDrawFrame zeichnet einen gewählten Frame (ab 1 gezählt), ohne die Wiedergabe anzutasten. Ansonsten ist ein Sheet eine gewöhnliche Animation, also nehmen spriteSetFrame (ab 0 gezählt), spritePlay, spriteDraw, nodeSetSprite und emitterSetTexture es alle an, und spriteFrameWidth und spriteFrameHeight melden die unskalierte Größe eines Frames. Die mit „Hypseus-Erweiterung“ markierten Einträge gibt es, damit für Hypseus Singe geschriebene Spiele unverändert laufen.

2.39.1. drawTransparent

drawTransparent(boolean)

Hypseus-Erweiterung. Entscheidet, ob Farbe 0 auf den danach geladenen Sprites und dem danach gerenderten Text transparent gezeichnet wird. false, der Standard, stanzt Farbe 0 aus, wie Hypseus es tut: Palettenindex 0 oder reines Schwarz, und das schließt deckendes Schwarz in einem Bild mit Alphakanal ein, sodass schwarze Schrift oder ein schwarzer Umriss verschwindet. true zeichnet sie allein nach ihrem Alphakanal, sodass deckendes Schwarz schwarz bleibt. Bereits geladene Sprites behalten die Einstellung, mit der sie geladen wurden, und jedes Skript beginnt bei false.

Rückgabe: nichts.

Seit: 3.00

Beispiel
-- Die Schrift des Logos ist deckendes Schwarz:  lade es allein nach seinem Alpha, dann zurück
-- zum üblichen Farbschlüssel für die eigenen Grafiken des Spiels.
drawTransparent(true)
logo = spriteLoad("art/logo.png")
drawTransparent(false)

2.39.2. spriteBlend

spriteBlend(boolean, sprite)

Hypseus-Erweiterung, angenommen und ignoriert. Sie ist ein Notbehelf für jene Engine: Hypseus lädt Sprites mit ausgeschaltetem Blend-Modus von SDL, und dies schaltet ihn für ein Sprite wieder ein. Singe zeichnet jedes Sprite ohnehin mit seinem Alphakanal, das Blending ist also von vornherein nie aus. Das Sprite-Handle wird trotzdem geprüft, ein falsches ist also weiterhin ein Fehler. Um stattdessen das Licht eines Sprites zu addieren oder mit ihm zu multiplizieren, siehe spriteSetBlend.

Rückgabe: nichts.

Seit: 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)

Blittet das Sprite so auf das Overlay, wie es gerade gedreht und skaliert ist. Ruf es aus onOverlayUpdate auf. Die ersten beiden Formen zeichnen in der Größe, die spriteGetWidth und spriteGetHeight melden, mit (x, y) als oberer linker Ecke; die letzten beiden strecken dieses Bild in das Rechteck von (x, y) bis einschließlich (x2, y2), immer mit Nächster-Nachbar-Abtastung, was auch immer spriteQuality sagt. Ist das Sprite eine laufende Animation, rückt das Zeichnen sie zuerst um die echte Zeit weiter, die seit dem vorigen Zeichnen (oder seit spritePlay) vergangen ist, durchläuft so viele Frames, wie diese Zeit abdeckt, und zeigt jeden Frame mindestens 10 ms lang, auch wenn die Datei weniger verlangt. Ist der letzte Frame vorüber, springt die Wiedergabe auf Frame 0 zurück, falls spriteLoop gesetzt ist; ansonsten bleibt sie auf dem letzten Frame stehen und hält an. Teile außerhalb des Overlays werden abgeschnitten.

Parameter:

  • id — Sprite-Handle aus spriteLoad oder fontToSprite.

  • x, y — Ankerpunkt in Overlay-Koordinaten; Nachkommastellen werden abgeschnitten.

  • x2, y2 — gegenüberliegende Ecke des Zielrechtecks, einschließlich, für die gestreckten Formen.

  • centered — Boolean. Bei true wird das Bild (oder das gestreckte Rechteck) so verschoben, dass (x, y) sein Mittelpunkt ist statt seiner oberen linken Ecke.

Hinweise: Eine laufende Animation, die eine Weile nicht gezeichnet wird, holt beim nächsten Zeichnen auf; ruf spritePause auf, wenn sie stattdessen ihren Frame halten soll. Verwende für gedrehte Sprites die zentrierte Form, da die Drehung den Begrenzungsrahmen verändert und ein Anker oben links zu wandern scheint.

Seit: 1.x. Zentrierte und gestreckt-zentrierte Formen in 2.10 hinzugefügt. Siehe auch: spriteLoad, spriteRotate, spriteGetWidth, videoDraw

Beispiel
-- Automaten-Artwork in natürlicher Größe, das Attract-Standbild in seinen Kasten gequetscht
-- und ein Cursor, der an seinem Mittelpunkt verankert ist.
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)

Hypseus-Erweiterung. Blittet einen Frame eines Sprite-Sheets (oder einer beliebigen Animation) mit (x, y) als oberer linker Ecke auf das Overlay, ohne zu ändern, auf welchem Frame das Sprite steht oder ob es läuft. Frames werden ab 1 gezählt, wie Hypseus sie zählt; ein Frame außerhalb von 1 bis zur Frame-Anzahl zeichnet Frame 1. Ein Standbild zeichnet sich selbst und ignoriert frame. Eine mit spriteFlip gesetzte Spiegelung gilt. Die eigene Drehung und Skalierung des Sprites aus spriteRotate und spriteScale werden ignoriert: Die erste Form zeichnet den Frame in seiner natürlichen Größe, die anderen multiplizieren die Breite des Frames mit scaleX (oder scale) und seine Höhe mit scaleY (oder scale), mit Nächster-Nachbar-Abtastung. Ruf es aus onOverlayUpdate auf.

Parameter:

  • id — Sprite-Handle aus spriteLoadFrames oder spriteLoad.

  • x, y — obere linke Ecke in Overlay-Koordinaten; Nachkommastellen werden abgeschnitten.

  • frame — Frame-Nummer, 1 bis zur Frame-Anzahl; Nachkommastellen werden abgeschnitten.

  • scale, scaleX, scaleY — Größenfaktoren, 1 für natürliche Größe.

Hinweise: spriteSetFrame zählt Frames ab 0; spriteDrawFrame zählt ab 1.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteLoadFrames, spriteDraw, spriteSetFrame, spriteFrameWidth

Beispiel
-- Ein Ziffernstreifen mit zehn Frames zeichnet den Punktestand, eine Ziffer pro Frame.
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)

Hypseus-Erweiterung. Zeichnet ein Rechteck aus einem Sprite mit seiner oberen linken Ecke bei x, y: in seiner eigenen Größe oder, wenn x2 und y2 angegeben sind, so gestreckt, dass es den Kasten bis zu dieser Ecke füllt, so wie spriteDraw ein ganzes Sprite streckt. Es ist der einzige Aufruf, der ein Quellrechteck nimmt: spriteDraw nimmt das ganze Sprite und spriteDrawFrame einen ganzen Frame eines Sheets, während dieser ein beliebiges Rechteck nimmt. So schneidet ein Spiel eine Kachel, eine Ziffer oder einen Buchstaben aus einem Bild aus, ohne es viele Male zu laden.

Die gestreckte Form ist Singes eigene, und auf ihr baut ein Straßenrennspiel auf. Jede Bildschirmzeile unterhalb des Horizonts ist ein Stück Straße in einer gewissen Entfernung, also schneidet das Spiel eine Zeile aus einem Bild des Straßenquerschnitts aus und streckt sie auf die Breite der Straße in dieser Entfernung, zentriert dort, wohin die Kurven sie getragen haben. Gut hundert Aufrufe pro Frame zeichnen die ganze Straße samt Kurven und Hügeln, und nichts wird neu aufgebaut. Dieselbe Form zeichnet ein Sprite, das teilweise hinter einer Hügelkuppe verborgen ist: Schneide seinen oberen Teil aus und strecke ihn auf das, was noch zu sehen ist. spriteScale kann keins von beidem, da es jedes Mal, wenn sich die Größe ändert, das ganze Bild neu aufbaut.

Das Rechteck ist in den eigenen Pixeln des Sprites angegeben und muss darin liegen; ein Rechteck, das das nicht tut, oder eines ohne Breite oder Höhe beendet das Skript und nennt die Größe des Sprites, und ebenso ein x2 ohne y2. Eine Streckung, deren Kasten keine Breite oder Höhe hat, weil x2 links von x oder y2 über y liegt, zeichnet nichts. Die Streckung nimmt den nächstgelegenen Pixel, statt zu mischen, und hält so die Farben einer ein Pixel hohen Zeile genau so, wie sie gezeichnet wurden. Das Sprite, aus dem gezeichnet wird, ist das Sprite, wie es gerade gezeichnet wird, also ändert ein spriteRotate oder ein spriteScale, was die Koordinaten bedeuten.

Unter LEGACY_SPRITE_ARGS steht das Handle an dritter Stelle, spriteDrawGrid(x, y, spr, sourceX, sourceY, width, height), wo Hypseus es hinsetzt, und x2, y2 folgen am Ende wie hier.

Parameter:

  • id — Zahl; ein Sprite-Handle.

  • x, y — Zahlen; wo die obere linke Ecke des Rechtecks landet, in Overlay-Koordinaten.

  • sourceX, sourceY — Zahlen; die obere linke Ecke des Rechtecks im Sprite.

  • width, height — Zahlen; seine Größe, mindestens 1.

  • x2, y2 — Zahlen, optional und nur zusammen; die untere rechte Ecke des Kastens, in den es gestreckt wird, einschließlich.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe; die gestreckte Form ist neu in 3.00 und Singes eigene. Siehe auch: spriteDraw, spriteDrawFrame

Beispiel
-- Eine Zahl, gezeichnet aus einem Streifen von zehn Ziffern, jede 16 mal 24.
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
Beispiel
-- Eine gerade Straße bis zum Horizont, eine Bildschirmzeile nach der anderen.  road.png ist 256 Pixel breit und zwei
-- Zeilen hoch:  ein heller Querschnitt der Straße und ein dunkler, die sich die Straße hinunter abwechseln, damit man
-- ihre Bewegung sieht.  Zeile y des Bildschirms ist der Boden in der Entfernung EYE * FOCAL / (y - HORIZON).
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)

Hypseus-Erweiterung. Zeichnet den Frame, den spriteRotateFrame zuletzt gedreht hat, zentriert auf x, y. Dies ist das Gegenstück zu jenem Aufruf und der Grund, weshalb es beide gibt: spriteDrawFrame ignoriert absichtlich die Drehung und Skalierung eines Sprites, also verwendet ein Spiel, das einen Frame eines Sheets gedreht haben will, stattdessen diese beiden.

Mit einem Maßstab wird der gedrehte Frame beim Zeichnen um ihn gestreckt — zusätzlich zu dem Maßstab, mit dem er gedreht wurde — und das Ergebnis ist weiterhin auf x, y zentriert. scaleX allein skaliert beide Achsen.

Zeichnen vor jedem spriteRotateFrame beendet das Skript, da es keinen gedrehten Frame zum Zeichnen gibt.

Unter LEGACY_SPRITE_ARGS steht das Handle am Ende, wie Hypseus es schreibt.

Parameter:

  • id — Zahl; ein Sprite-Handle.

  • x, y — Zahlen; der Mittelpunkt des gezeichneten Frames, in Overlay-Koordinaten.

  • scale oder scaleX, scaleY — optionale Zahlen; ein weiterer Maßstab beim Zeichnen.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteRotateFrame, spriteDrawFrame

Beispiel
-- Eine Kompassnadel:  ein Frame des Sheets, der dorthin zeigt, wohin die Spielfigur geht.
spriteRotateFrame(needle, heading, 1)
spriteDrawRotatedFrame(needle, 320, 240)

2.39.7. spriteFlip

spriteFlip(id, horizontal, vertical)

Spiegelt das Sprite von links nach rechts, von oben nach unten oder beides, bis es wieder mit false, false aufgerufen wird. Die Spiegelung gilt für jedes Zeichnen des Sprites: spriteDraw, jeden Frame aus spriteDrawFrame und den gedrehten Frame aus spriteDrawRotatedFrame. Sie wird nach der Drehung und Skalierung aus spriteRotate und spriteScale angewendet, ein gedrehtes Sprite wird also so gespiegelt, wie es auf dem Bildschirm erscheint, und ein gedrehter Frame wird einfach in die andere Richtung gespiegelt, statt erneut gedreht zu werden. Das gespiegelte Bild wird nur neu aufgebaut, wenn sich die Flags ändern; ein von spriteDrawFrame gezeichneter Frame wird einmal gespiegelt und behalten, bis ein anderer Frame verlangt wird. spriteDrawGrid ignoriert die Spiegelung, da sein Rechteck aus dem ungespiegelten Bild geschnitten wird.

Eine Figur, die in beide Richtungen läuft, braucht nur Grafiken, die in eine Richtung schauen: Spiegle das Sprite, wenn sie sich umdreht.

Parameter:

  • id — Sprite-Handle.

  • horizontal — true spiegelt von links nach rechts.

  • vertical — true spiegelt von oben nach unten.

Rückgabe: nichts.

Beispiel
-- Das Sheet des Helden schaut nach rechts; nach links schauen dieselben Frames, gespiegelt.
function onOverlayUpdate()
    overlayClear()
    spriteFlip(hero, heroVx < 0, false)
    spriteDrawFrame(hero, heroX, heroY, walkFrame)
    return OVERLAY_UPDATED
end

2.39.8. spriteFrameHeight

height = spriteFrameHeight(id)

Hypseus-Erweiterung. Gibt die Höhe eines Frames des Sprites vor jeder Skalierung oder Drehung zurück: die Höhe des Streifens bei einem Sheet aus spriteLoadFrames, die Höhe eines Frames bei einer Animation und die Höhe des Bildes bei einem Standbild (Hypseus meldet hier die gezeichnete Fläche). spriteGetHeight meldet stattdessen die Größe, wie sie gezeichnet wird.

Rückgabe: Ganzzahl.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteFrameWidth, spriteGetHeight, spriteLoadFrames

Beispiel
-- Einen Frame auf einem Punkt zentrieren.
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)

Hypseus-Erweiterung. Gibt die Breite eines Frames des Sprites vor jeder Skalierung oder Drehung zurück: die Breite des Streifens geteilt durch die Frame-Anzahl bei einem Sheet aus spriteLoadFrames, die Breite eines Frames bei einer Animation und die Breite des Bildes bei einem Standbild (Hypseus meldet dort 0). spriteGetWidth meldet stattdessen die Größe, wie sie gezeichnet wird.

Rückgabe: Ganzzahl.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteFrameHeight, spriteGetWidth, spriteLoadFrames

Beispiel
-- Die Frames eines Streifens nebeneinander auslegen.
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)

Gibt den nullbasierten Index des Frames zurück, den das Sprite gerade zeigt. Standbilder und Animationen, die nicht weitergerückt sind, melden 0. Frames rücken nur innerhalb von spriteDraw weiter, der Wert ändert sich also zwischen Zeichenaufrufen, nicht zwischen beliebigen Aufrufen. Verwende es, um Sound oder Spiellogik auf einen bestimmten Frame einer Animation abzustimmen.

Rückgabe: ganzzahliger Frame-Index, 0 bei einem Standbild.

Seit: 2.10 Siehe auch: spriteSetFrame, spriteIsPlaying, spriteDraw

Beispiel
-- Den Schuss auf dem Frame auslösen, auf dem das Mündungsfeuer erscheint.
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)

Hypseus-Erweiterung. Wie viele Frames ein Sprite hat: die Frame-Anzahl eines von spriteLoadFrames geladenen Sheets oder eines animierten GIF oder WEBP und 0 bei einem Standbild. Es ist die Anzahl, bis zu der die nullbasierte Frame-Nummer von spriteSetFrame läuft, und eins mehr als die größte, die es annimmt.

Parameter:

  • id — Zahl; ein Sprite-Handle.

Rückgabe: Zahl; 0 bei einem Standbild.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteLoadFrames, spriteGetFrame, spriteSetFrame

Beispiel
-- Zum nächsten Frame weiterschalten, wie auch immer das Sheet ausgefallen ist.
local frames = spriteGetFrames(walk)
if frames > 0 then
    spriteSetFrame(walk, (spriteGetFrame(walk) + 1) % frames)
end

2.39.12. spriteGetHeight

result = spriteGetHeight(id)

Gibt die Höhe des Sprites zurück, wie es jetzt gezeichnet würde, in Overlay-Koordinaten. Skalierung und Drehung, die mit spriteScale, spriteRotate oder spriteRotateAndScale angewendet wurden, sind eingeschlossen, ein gedrehtes Sprite meldet also die Höhe seines gedrehten Begrenzungsrahmens, nicht die des Quellbildes. Bei einer Animation wird der aktuelle Frame gemessen. Die gestreckten Formen von spriteDraw beeinflussen den Wert nicht.

Rückgabe: ganzzahlige Höhe.

Seit: 2.00 Siehe auch: spriteGetWidth, spriteScale, spriteRotate

Beispiel
-- Vorgerenderte Beschreibungszeilen stapeln, im Abstand der Höhe der Text-Sprites.
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)

Gibt die Breite des Sprites zurück, wie es jetzt gezeichnet würde, in Overlay-Koordinaten, einschließlich jeder gerade angewendeten Skalierung und Drehung. Bei einer Animation wird der aktuelle Frame gemessen. Zusammen mit spriteGetHeight ist das der übliche Weg, ein Sprite in einem Kasten zu zentrieren oder mit fontToSprite gerenderten Text zu messen.

Rückgabe: ganzzahlige Breite.

Seit: 2.00 Siehe auch: spriteGetHeight, spriteScale, fontToSprite

Beispiel
-- Das Automatenbild in seinem Feld zentrieren und den Titel über die Breite des Overlays.
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)

Meldet, ob die Animation des Sprites gerade weiterrückt. Ein frisch geladenes Sprite meldet false; spritePlay schaltet sie ein, und spritePause oder das Ende einer Animation ohne Wiederholung schaltet sie aus. Frag es regelmäßig ab, um herauszufinden, wann eine einmalige Animation fertig ist.

Rückgabe: Boolean, true, solange die Animation läuft.

Hinweise: spritePlay und spritePause prüfen nicht auf Animationsdaten, ein Standbild meldet also, was diese Aufrufe zuletzt gesetzt haben.

Seit: 2.10 Siehe auch: spritePlay, spritePause, spriteLoop

Beispiel
-- Das Menü zurückhalten, bis die einmalige Logo-Animation fertig ist.
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)

Lädt ein Bild und gibt ein ganzzahliges Handle für die anderen sprite*-Aufrufe zurück. Der Name geht durch das virtuelle Dateisystem der Engine, die Datei kann also ungepackt auf der Festplatte oder in einem gepackten Spiel liegen; er wird relativ zu dem Ordner aufgelöst, in dem Singe gestartet wurde, stelle also für Dateien, die mit deinem Spiel ausgeliefert werden, DIR voran. Jedes Format in Video-, Audio- und Containerformate wird gelesen. Ein animiertes GIF oder WEBP mit zwei oder mehr Frames lädt als Animation, auf Frame 0 abgestellt, nicht laufend und ohne Wiederholung; jede andere Datei, auch ein GIF mit nur einem Frame, lädt als Standbild. Ein Bild mit mehr als 8 Bit pro Kanal oder mit Gleitkommapixeln wird beim Laden in 8-Bit-RGBA umgewandelt und von da an als solches behandelt. Pixel mit dem Rohwert 0 im eigenen Pixelformat der Datei werden transparent. Das Laden ist synchron, und eine Datei, die sich nicht öffnen oder dekodieren lässt, beendet das Skript mit der Fehlermeldung des Laders, statt nil zurückzugeben.

Die optionale Größe ist für ein Vektorbild — ein SVG — gedacht, das keine eigene Größe hat, die etwas taugt: Das Bild wird so gerastert, dass es unter Wahrung seiner eigenen Proportionen in diesen Kasten passt, statt in der Größe der Datei gerastert und hochskaliert zu werden. Frag spriteGetWidth und spriteGetHeight, was dabei herausgekommen ist, denn wenn eine quadratische Zeichnung in einen breiten Kasten eingepasst wird, bleibt Breite ungenutzt. Jedes andere Format ignoriert die Größe.

Parameter:

  • filename — String; das zu ladende Bild.

  • width — optionale Zahl; die Breite, in die ein SVG eingepasst wird, 1 oder mehr.

  • height — optionale Zahl; die Höhe, in die ein SVG eingepasst wird, 1 oder mehr. Beide müssen zusammen angegeben werden.

Rückgabe: ganzzahliges Sprite-Handle.

Hinweise: Animationen starten nicht von selbst. Ruf nach dem Laden spriteLoop(id, true) und spritePlay(id) auf, wenn die Animation laufen und sich wiederholen soll.

Seit: 1.x. Unterstützung für animierte GIF/WEBP in 2.10 hinzugefügt; die Vektorgröße in 3.00. Siehe auch: spriteUnload, spritePlay, spriteLoop, fontToSprite

Beispiel
-- Die Menügrafiken einmal beim Start laden; die Attract-Schleife ist ein animiertes WEBP.
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)

Hypseus-Erweiterung. Baut ein Sprite aus einem Bild, das in einem Lua-String steht, statt aus einer Datei. Jedes Format, das spriteLoad liest, wird hier gelesen, animierte GIF und WEBP eingeschlossen, und eine so geladene Animation verhält sich genau wie eine aus einer Datei geladene.

Der String darf Nullbytes enthalten; seine Länge, nicht seine erste Null, entscheidet, wie viel gelesen wird. Das Bild wird während des Aufrufs dekodiert, und der String wird nicht behalten. Bytes, die kein Bild sind, oder ein leerer String beenden das Skript, so wie eine unlesbare Datei bei spriteLoad.

Verwende es für Grafiken, die ein Spiel selbst erzeugt, entpackt oder entschlüsselt. Grafiken, die das virtuelle Dateisystem über ihren Namen erreicht — auch Grafiken in einer gepackten .game — lädt man besser mit spriteLoad, das nicht die ganze Datei in einem Lua-String hält.

Parameter:

  • data — String aus Bytes.

Rückgabe: Zahl, das Sprite-Handle.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteLoad, soundLoadData

Beispiel
-- Ein Bild, das das Spiel in seiner eigenen Datendatei aufbewahrt.
local bytes = myArchive:extract("logo.png")
local logo  = spriteLoadData(bytes)
spriteDraw(logo, 10, 10)

2.39.17. spriteLoadFrames

result = spriteLoadFrames(count, filename)

Hypseus-Erweiterung. Lädt ein Bild, das count gleich große Frames in einer einzigen Zeile enthält, und gibt ein Sprite-Handle zurück. Die Frame-Breite ist die Bildbreite geteilt durch count (ganzzahlige Division; übrige Spalten rechts fallen weg), und die Frame-Höhe ist die Bildhöhe. Das Sheet wird zu einer gewöhnlichen Animation, auf Frame 0 abgestellt, nicht laufend und ohne Wiederholung, sodass spriteDraw den aktuellen Frame zeigt statt des ganzen Streifens (wie Hypseus ihn zeichnet), und spriteDrawFrame wählt jeden Frame direkt. Der Name geht wie bei spriteLoad durch das virtuelle Dateisystem, und Pixel mit dem Rohwert 0 werden in jedem Frame transparent. Eine Anzahl außerhalb von 2 bis 512, ein Bild, das schmaler als count Pixel ist, oder eine Datei, die sich nicht lesen lässt, beendet das Skript mit einem Fehler.

Parameter:

  • count — Anzahl der Frames über die Breite des Bildes, 2 bis 512.

  • filename — das Streifenbild.

Rückgabe: ganzzahliges Sprite-Handle.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteDrawFrame, spriteFrameWidth, spriteLoad, spriteUnload

Beispiel
-- Ein Autostreifen mit fünf Frames; Frame 3 ist das Auto, das geradeaus zeigt.
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)

Legt fest, ob die Animation nach ihrem letzten Frame wieder bei Frame 0 beginnt oder dort anhält. Neue Sprites wiederholen nicht. Die Einstellung wird jedes Mal abgefragt, wenn spriteDraw über den letzten Frame hinausgeht, sie kann also geändert werden, während die Animation läuft. Sie an einem Sprite zu setzen, das schon angehalten hat, startet die Wiedergabe nicht neu; dafür ruf spritePlay auf. Das Argument muss ein Lua-Boolean sein.

Parameter:

  • id — Sprite-Handle.

  • loop — Boolean. true springt zurück auf Frame 0; false (der Standard) hält auf dem letzten Frame an, und spriteIsPlaying gibt von da an false zurück.

Seit: 2.10 Siehe auch: spritePlay, spriteIsPlaying, spriteSetFrame

Beispiel
-- Die Fackel flackert endlos; die Explosion spielt einmal pro Treffer.
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)

Erzeugt ein leeres Sprite, jedes Pixel transparent, das spriteSetPixels füllen soll: ein Bild, das das Skript selbst macht, statt es zu laden. Jede Seite ist 1 bis 4096 Pixel lang; alles andere beendet das Skript. Das Sprite ist ein Standbild und kann alles, was jedes andere Standbild kann: Es lässt sich zeichnen, drehen, skalieren, strecken und einfärben, und es kann die Textur eines Materials sein.

Parameter:

  • width, height — Zahlen; seine Größe in Pixeln.

Rückgabe: Zahl, das Sprite-Handle.

Seit: 3.00 Siehe auch: spriteSetPixels, spriteLoadData

Beispiel
local minimap = spriteNew(64, 64)

2.39.20. spritePause

spritePause(id)

Hält die Animation auf ihrem aktuellen Frame an. Der Frame wird von spriteDraw weiter gezeichnet, und die pausierte Zeit wird nicht mitgezählt, wenn spritePlay fortsetzt, der Frame springt also nicht vor. Ein Sprite zu pausieren, das nicht läuft, ändert nichts.

Seit: 2.10 Siehe auch: spritePlay, spriteIsPlaying

Beispiel
-- Den Gegner mitten im Schritt einfrieren, während das Treffer-Aufblitzen läuft.
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)

Startet die Animation oder setzt sie von ihrem aktuellen Frame aus fort, wobei der erste Schritt ab dem Moment des Aufrufs gemessen wird. Ein Sprite, das bereits läuft, bleibt unberührt, der Frame-Timer wird also nicht zurückgesetzt. Ein neues Sprite muss mit diesem Aufruf gestartet werden; Laden allein animiert es nicht.

Hinweise: Eine Animation ohne Wiederholung, die ihren letzten Frame erreicht hat, bleibt auf diesem Frame, wenn sie erneut abgespielt wird. Um sie noch einmal abzuspielen, ruf zuerst spriteSetFrame(id, 0) auf.

Seit: 2.10 Siehe auch: spritePause, spriteSetFrame, spriteLoop

Beispiel
-- Die einmalige Explosion am Aufprallpunkt neu starten.
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)

Wählt die Abtastung, die verwendet wird, wenn das Sprite für Drehung oder Skalierung neu aufgebaut wird. RENDER_PIXELATED behält harte Pixelkanten, RENDER_SMOOTH interpoliert. Neue Sprites sind pixelig. Die Einstellung zählt nur, solange eine Drehung oder ein Maßstab ungleich 1.0 wirkt; ein untransformiertes Sprite wird direkt aus seinem Quellbild gezeichnet, und die gestreckten Formen von spriteDraw verwenden immer Nächster-Nachbar-Abtastung. Den Modus zu ändern baut das transformierte Bild sofort neu auf, setze ihn also einmal nach dem Laden statt in jedem Frame.

Parameter:

  • id — Sprite-Handle.

  • mode — RENDER_PIXELATED (0) oder RENDER_SMOOTH (1). Jede Zahl ungleich null wählt glatt.

Seit: 2.10 Siehe auch: spriteScale, spriteRotate, spriteRotateAndScale

Beispiel
-- Fotografische Marquee-Grafik soll interpolieren; Pixelgrafik muss scharf bleiben.
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)

Hypseus-Erweiterung. Wird aus Kompatibilitätsgründen angenommen und tut nichts. In Hypseus wendet das Flag die transparente Farbe erneut auf die Kopien an, die spriteRotate und spriteScale erzeugen und die ihren Hintergrund sonst deckend zeichnen würden; die transformierten Kopien von Singe tragen die Transparenz in ihrem Alphakanal, es gibt also nichts neu auszustanzen. Ein falsches Handle oder ein Argument, das kein Boolean ist, bricht das Skript ab, wie bei jedem anderen Sprite-Aufruf.

Parameter:

  • id — Sprite-Handle.

  • enabled — Boolean, ignoriert.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteRotate, spriteScale, spriteLoad

Beispiel
-- Hypseus-Spielcode; in Singe harmlos.
badge = spriteLoad(DIR .. "badge.png")
spriteResetColorKey(badge, true)

2.39.24. spriteRotate

spriteRotate(id, degrees)

Dreht das Sprite im Uhrzeigersinn um seinen Mittelpunkt. Der Winkel wird modulo 360 reduziert und darf gebrochen oder negativ sein. Der aktuelle Maßstab bleibt erhalten. Das gedrehte Bild wird nur neu aufgebaut, wenn sich der Winkel tatsächlich ändert; denselben Winkel in jedem Frame zu wiederholen kostet also nichts, während ein neuer Winkel in jedem Frame auch in jedem Frame neu aufbaut. Die Drehung vergrößert den Begrenzungsrahmen, also ändern sich spriteGetWidth und spriteGetHeight, und die zentrierte Form von spriteDraw ist die richtige.

Seit: 2.10 Siehe auch: spriteRotateAndScale, spriteDraw, spriteQuality

Beispiel
-- Kisten aus einer 2D-Physikszene, im Winkel ihrer Körper gezeichnet.
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)

Setzt Drehung und Maßstab zusammen. Das Ergebnis ist dasselbe wie spriteRotate gefolgt von spriteScale, aber das transformierte Bild wird einmal statt zweimal neu aufgebaut, und gar nicht, wenn sich nichts geändert hat. Skalierungsfaktoren sollten größer als 0 sein; ein negativer wird ohne sein Vorzeichen genommen, und einer, der keine Pixel übrig ließe, null eingeschlossen, lässt stattdessen eines übrig.

Parameter:

  • id — Sprite-Handle.

  • degrees — Drehung im Uhrzeigersinn, modulo 360 reduziert.

  • scale — einheitlicher Faktor, 1.0 für natürliche Größe.

  • scaleX, scaleY — getrennte waagerechte und senkrechte Faktoren.

Seit: 2.10 Siehe auch: spriteRotate, spriteScale, spriteQuality

Beispiel
-- Eine Münze, die sich dreht und schrumpft, während sie zum Punktezähler fliegt.
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)

Hypseus-Erweiterung. Nimmt einen Frame aus einem Sprite-Sheet, dreht ihn um degrees im Uhrzeigersinn, skaliert ihn mit dem eigenen spriteScale des Sprites und behält das Ergebnis für spriteDrawRotatedFrame. Die eigene gezeichnete Fläche des Sprites bleibt unberührt, also zeigen spriteDraw und spriteDrawFrame weiter, was sie gezeigt haben.

Frames werden ab 1 gezählt, wie spriteDrawFrame sie zählt (und anders als spriteGetFrame und spriteSetFrame, die ab 0 zählen); ein Frame außerhalb des Sheets ist Frame 1 statt eines Fehlers. Ein Standbild dreht sein ganzes Bild.

Drehen ist nicht umsonst: Der Frame wird jedes Mal Pixel für Pixel neu gezeichnet, dreh ihn also, wenn sich der Winkel ändert, statt in jedem Frame. Der Winkel wird modulo 360 genommen, und spriteQuality entscheidet, ob die gedrehten Kanten geglättet werden.

Unter LEGACY_SPRITE_ARGS steht das Handle am Ende, spriteRotateFrame(degrees, frame, spr), wie Hypseus es schreibt.

Parameter:

  • id — Zahl; ein Sprite-Handle.

  • degrees — Zahl; im Uhrzeigersinn.

  • frame — Zahl; 1 bis zur Frame-Anzahl.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: spriteDrawRotatedFrame, spriteRotate, spriteScale

Beispiel
-- Ein Schiffs-Sprite, dessen Rumpf Frame 1 und dessen Schub Frame 2 ist.
spriteRotateFrame(ship, angle, thrusting and 2 or 1)
spriteDrawRotatedFrame(ship, shipX, shipY)

2.39.27. spriteScale

spriteScale(id, scale)
spriteScale(id, scaleX, scaleY)

Skaliert das Sprite um seinen Mittelpunkt, einheitlich oder pro Achse, und behält die aktuelle Drehung. Faktoren müssen größer als 0 sein; 1.0 ist natürliche Größe, und ein Faktor von genau 1.0 auf beiden Achsen ohne Drehung zeichnet das Quellbild direkt. Das skalierte Bild wird nur neu aufgebaut, wenn sich ein Faktor ändert, mit der von spriteQuality gewählten Abtastung. Nimm lieber die gestreckte Form von spriteDraw, wenn sich die Zielgröße in jedem Frame ändert, da sie nichts neu aufbaut.

Parameter:

  • id — Sprite-Handle.

  • scale — einheitlicher Faktor.

  • scaleX, scaleY — getrennte waagerechte und senkrechte Faktoren.

Seit: 2.10 Siehe auch: spriteRotateAndScale, spriteQuality, spriteDraw

Beispiel
-- Den hervorgehobenen Menüeintrag vergrößern; neu aufgebaut wird nur, wenn sich die Auswahl bewegt.
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)

Multipliziert bei jedem Zeichnen des Sprites, in jeder Form, das Alpha jedes Pixels mit alpha / 255: spriteDraw, spriteDrawFrame, spriteDrawGrid und spriteDrawRotatedFrame, gedreht oder nicht. 255, der Standard, zeichnet es, wie es ist, und 0 gar nicht, ein Logo blendet also ohne zweites Bild ein und aus. Werte außerhalb des Bereichs werden begrenzt.

Parameter:

  • id — Zahl; ein Sprite-Handle.

  • alpha — Zahl; 0 bis 255.

Rückgabe: nichts.

Seit: 3.00 Siehe auch: spriteSetBlend, spriteSetTint

Beispiel
-- Der Titel blendet über zwei Sekunden ein.
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)

Wie jedes Zeichnen des Sprites es über das legt, was schon auf dem Overlay ist. SPRITE_ALPHA, der Standard, zeichnet es nach seinem Alpha darüber. SPRITE_ADD addiert seine Farbe, skaliert mit seinem Alpha, zu dem, was da ist, und kann also nur aufhellen: Leuchten, Licht, Funken und die Shadebobs der alten Demos, bei denen ein Ball, der immer wieder über sich selbst gezeichnet wird, zu Weiß ausbrennt. SPRITE_MULTIPLY dunkelt das, was da ist, mit seiner Farbe ab, für Schatten und getöntes Glas.

Addierte und multiplizierte Pixel behalten das eigene Alpha des Overlays, sie zeigen sich also nur dort, wo schon etwas auf dem Overlay gezeichnet ist: Über einem transparenten Overlay, über einem Video oder der 3D-Szene, ändern sie nichts. Zeichne zuerst etwas Deckendes, oder verwende emitterSetBlend mit PARTICLE_ADD, das über alles addiert. Alles außer den drei Konstanten beendet das Skript.

Parameter:

  • id — Zahl; ein Sprite-Handle.

  • blend — SPRITE_ALPHA, SPRITE_ADD oder SPRITE_MULTIPLY.

Rückgabe: nichts.

Seit: 3.00 Siehe auch: spriteSetAlpha, spriteSetTint, emitterSetBlend

Beispiel
-- Shadebobs:  ein weicher weißer Ball, entlang einer Bahn addiert und nie gelöscht, sodass die Spur zu Weiß aufläuft.
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)

Springt mit einer Animation auf den angegebenen Frame und startet den Verzögerungstimer dieses Frames neu, sodass der Frame seine volle Dauer gezeigt wird, bevor der nächste kommt. Der Wiedergabezustand ändert sich nicht: Ein pausiertes Sprite bleibt auf dem neuen Frame pausiert, und ein laufendes macht von dort aus weiter. Der Aufruf wird ignoriert bei Standbildern, bei Frames außerhalb von 0 bis zum letzten Frame und wenn das Sprite diesen Frame schon zeigt.

Hinweise: Frames werden hier ab 0 gezählt; spriteDrawFrame, die Hypseus-Erweiterung, zählt sie ab 1.

Seit: 2.10 Siehe auch: spriteGetFrame, spritePlay, spriteDrawFrame

Beispiel
-- Die Tür in dem Zustand zeigen, in dem sie laut Spiellogik ist.
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)

Ersetzt jedes Pixel eines Standbild-Sprites aus einem String, Zeile für Zeile von oben. Ohne Palette hat der String vier Bytes pro Pixel: Rot, Grün, Blau und Alpha. Mit einer ist es ein Byte pro Pixel, jeweils die Nummer einer Farbe in der Palette, die aus 256 Farben zu je drei Bytes (Rot, Grün und Blau, alle deckend) oder vier (mit Alpha) besteht. Ein String der falschen Länge, eine Palette der falschen Länge oder ein animiertes Sprite beendet das Skript.

So zeichnet ein Skript ein Bild Pixel für Pixel, schnell genug für jeden Frame: die Plasmas, Tunnel, das Feuer und das Wasser der alten Demos, eine Minikarte oder eine Höhenkarte, die gerade bearbeitet wird. Den String zu bauen ist Arbeit des Skripts, halte das Bild also klein und strecke es beim Zeichnen: Eine Lua-Schleife füllt ein Bild von 320 mal 240 auf einem Desktop-Rechner in wenigen Millisekunden. Der Palettenmodus ist die alte Art, billig zu animieren: Setze dieselben Pixel noch einmal mit der um eine Farbe weitergedrehten Palette, und alles wechselt die Farbe, ohne dass etwas neu berechnet wird. Ein Sprite, das gedreht oder skaliert ist, wird mit seinen neuen Pixeln erneut gedreht und skaliert; ein Material, das das Sprite zeigt, sieht die Änderung erst, wenn materialSetTexture wieder mit dem Sprite aufgerufen wird, was es neu hochlädt.

Auch ein geladenes Bild kann neue Pixel bekommen; es hat die Größe, mit der es geladen wurde.

Parameter:

  • id — Zahl; ein Standbild-Sprite.

  • pixels — String; width * height * 4 Bytes oder width * height mit einer Palette.

  • palette — optionaler String; 768 oder 1024 Bytes.

Rückgabe: nichts.

Seit: 3.00 Siehe auch: spriteNew, materialSetTexture

Beispiel
-- Feuer:  jedes Pixel der Durchschnitt der Pixel darunter, beim Aufsteigen abkühlend, durch eine Palette von
-- Schwarz über Rot und Gelb bis Weiß.  In jedem Frame über den unteren Teil des Bildschirms gestreckt.
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)

Multipliziert bei jedem Zeichnen des Sprites, in jeder Form, die Farbe jedes Pixels mit r, g, b / 255. Ein weißes Sprite zeichnet in jeder Farbe, und jedes Sprite lässt sich ohne zweites Bild abdunkeln oder zu einer Farbe hin verschieben: Aus einem weißen Ball wird ein ganzer Regenbogen davon, und ein weißes Sprite von einem Pixel, mit spriteDraw gestreckt, wird zu einem gefüllten Rechteck in jeder Farbe. 255, 255, 255, der Standard, zeichnet es, wie es ist. Werte außerhalb des Bereichs werden begrenzt.

Parameter:

  • id — Zahl; ein Sprite-Handle.

  • r, g, b — Zahlen; 0 bis 255.

Rückgabe: nichts.

Seit: 3.00 Siehe auch: spriteSetAlpha, spriteSetBlend

Beispiel
-- Ein Ring aus Bällen, jeder in seiner eigenen Farbe, aus einem weißen Bild.
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)

Gibt das Sprite frei: das Quellbild, die transformierte Kopie, falls es eine gibt, und alle Animations-Frames. Das Handle ist danach ungültig, und jede weitere Verwendung beendet das Skript mit einem Fehler. Von fontToSprite erzeugte Sprites werden genauso freigegeben. Sprites, die beim Ende des Spiels noch geladen sind, gibt die Engine frei, aber Spiele, die während des Spielens Sprites erzeugen (zum Beispiel Text, der neu gerendert wird, wenn sich der Punktestand ändert), müssen die alten entladen, sonst wächst der Speicher ohne Grenze.

Seit: 2.00 Siehe auch: spriteLoad, fontToSprite, onShutdown

Beispiel
-- Den Punktestand nur neu rendern, wenn er sich ändert, und das vorige Sprite freigeben.
function updateScoreSprite()
    if scoreSprite ~= nil then
        spriteUnload(scoreSprite)
    end
    scoreSprite = fontToSprite("SCORE " .. score)
end

function onShutdown()
    spriteUnload(scoreSprite)
    spriteUnload(cabinetSprite)
end

2.40. Untertitel

SubRip-Untertitel über dem Disc-Bild. Ein Spiel lädt eine .srt mit srtLoad, schaltet sie mit srtEnable ein, und die Engine blendet jeden Cue ein und wieder aus, sobald die Disc ihn erreicht. Siehe Untertitel für das Dateiformat, die Zeitsteuerung und wie man sie umgestaltet.

Die Untertitel und overlayBanner teilen sich ein mitgeliefertes Dokument, Singe/subtitle.rml, gestaltet von Singe/subtitle.rcss; ein Spiel, das ein anderes Aussehen will, liefert seine eigene subtitle.rml neben seinem Skript aus, und Singe verwendet dann diese (siehe Untertitel). Beide werden über das Bild gezeichnet, über dem Overlay und unter den GUIs im Bildschirmraum, und sie nehmen keine Mauseingaben an.

2.40.1. srtClear

srtClear()

Hypseus-Erweiterung. Nimmt sofort vom Bildschirm, was dort steht — einen Cue oder ein Banner — und lässt die geladenen Cues und den Eingeschaltet-Zustand in Ruhe. Der Cue, der zu sehen war, bleibt weg, bis die Disc den nächsten erreicht; nichts muss neu geladen und nichts wieder eingeschaltet werden.

Parameter: keine.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: srtEnable, overlayBanner

Beispiel
-- Eine Zwischensequenz endet früh; die Zeile entfernen, die noch zu sehen war.
srtClear()

2.40.2. srtEnable

srtEnable(enabled)

Hypseus-Erweiterung. Ob die geladenen Cues angezeigt werden, während die Disc läuft. Ausschalten nimmt einen gerade sichtbaren Cue mit weg; erneutes Einschalten zeigt den Cue an, der den Frame abdeckt, auf dem die Disc steht. Ein Skript beginnt mit ausgeschalteten Untertiteln, ein Spiel, das welche lädt, muss sie also einschalten.

Ein Argument, das kein Boolean ist, beendet das Skript.

Parameter:

  • enabled — Boolean.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: srtLoad, srtClear

Beispiel
srtEnable(SETTINGS.subtitles)

2.40.3. srtLoad

loaded = srtLoad(filename)

Hypseus-Erweiterung. Liest eine SubRip-Datei über das virtuelle Dateisystem und wandelt ihre Zeitstempel in Disc-Frames bei der eigenen Bildrate der Disc um. Laden ersetzt, was vorher geladen war; srtEnable zeigt es dann an.

Der Aufruf antwortet mit false und hat nichts geladen, wenn sich die Datei nicht lesen lässt, wenn sie keinen Cue enthält, der sich parsen lässt, oder wenn es keine Disc gibt, an der sie sich ausrichten ließe — eine fehlerhafte Datei ist also ein false, kein Absturz. In jedem dieser Fälle wird eine Warnung mit dem Namen der Datei ausgegeben. Cues, die sich in einer sonst guten Datei nicht parsen lassen, werden übersprungen, wie Hypseus sie überspringt.

Da die Zeitstempel beim Laden der Datei zu Frame-Nummern werden und die Engine die Frame-Nummer abgleicht, wird ein Cue wiedergefunden, wohin die Disc auch geschickt wird: Eine Suche, ein Skip oder ein Einzelschritt landet sofort auf der richtigen Zeile.

Parameter:

  • filename — String; ein Pfad, den das virtuelle Dateisystem erreichen kann.

Rückgabe: Boolean, ob ein Cue geladen wurde.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: srtEnable, srtPosition, Untertitel

Beispiel
if srtLoad("subs/" .. language .. ".srt") then
    srtEnable(true)
end

2.40.4. srtLoadTrack

loaded = srtLoadTrack(track)

Dasselbe wie srtLoad, nur dass die Untertitel aus dem eigenen Container der Disc kommen statt aus einer .srt-Datei daneben. Alles nach dem Laden ist gleich: Die Cues werden zu Disc-Frame-Nummern bei der Bildrate der Disc, sie werden also nach jedem Sprung wiedergefunden, und srtEnable, srtPosition und srtClear funktionieren genauso.

Die ganze Datei wird einmal durchlaufen, um die Spur einzusammeln, ohne Bilder zu dekodieren, bei einer langen Disc dauert das also einen Moment — tu es, während etwas anderes auf dem Bildschirm ist, statt zwischen zwei Frames des Spielgeschehens.

Eine Spur, die Bilder statt Wörter enthält (VobSub oder PGS), lässt sich nicht lesen: Der Aufruf antwortet mit false, wie bei einer unlesbaren .srt, und lässt die Untertitel gelöscht zurück. Ebenso bei einer Spurnummer, die nichts benennt, und ebenso bei einem Spiel ohne Disc.

Parameter:

  • track — Zahl; 0 bis discGetSubtitleTracks() - 1.

Rückgabe: true, wenn mindestens ein Cue gelesen wurde.

Seit: 3.00. Siehe auch: srtLoad, discGetSubtitleTracks, srtEnable

Beispiel
-- Untertitel, die der Rip mitgebracht hat, mit einer .srt neben dem Spiel als Rückfallebene.
if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

2.40.5. srtPosition

srtPosition(percent)

Hypseus-Erweiterung. Wo ein Untertitel sitzt, in Prozent der Bildhöhe von oben, von 1 bis 95. Der Standard ist 80. Eine Zahl außerhalb dieses Bereichs wird ignoriert, wie Hypseus sie ignoriert, statt begrenzt oder abgelehnt zu werden.

Die Höhe gilt sofort für den Cue auf dem Bildschirm und für jeden Cue danach. overlayBanner trägt seine eigene Höhe und ist nicht betroffen.

Parameter:

  • percent — Zahl; 1 bis 95.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: srtLoad, Untertitel

Beispiel
-- Die Zeilen von der Punktetafel am unteren Rand fernhalten.
srtPosition(70)

2.41. Online-Highscores

Ein Spiel meldet eine Punktzahl mit einer Zeile:

scoreSubmit(playerScore)

Alles andere wurde einmal im Menü eingerichtet: welcher Dienst, welches Konto und unter welchem Namen der Spieler erscheint (siehe Online: Konten, Spiele und Punkte). Ein Spiel braucht nur eine GAME_ID in seinem Eintrag in games.dat — eine UUID, unter der die Bestenliste geführt wird. Siehe singeGetGameId für das Format.

Aufruf Was er tut

scoreBegin()

Meldet, dass ein Durchgang beginnt. Optional, aber den Aufruf wert: siehe unten.

scoreSubmit(value [, board [, meta]])

Reiht eine Punktzahl in die Warteschlange ein. Gibt false zurück, wenn der Automat nicht angemeldet ist oder das Spiel keine GAME_ID hat.

scoreLowestWins([board])

Legt fest, dass eine Bestenliste die niedrigste Punktzahl zuerst einordnet. Ruf es vor der ersten Punktzahl der Bestenliste auf.

scoreBoard(onDone [, board])

Holt die Bestenliste. onDone(ok, result) mit result.top (eine Liste von {name, value}), result.standing (value und rank dieses Spielers und die Anzahl der players) und result.order, "highest" oder "lowest", je nachdem, wie die Bestenliste ordnet. Ein Automat, der nicht angemeldet ist, kann sie auch holen: siehe unten.

scorePlayerName()

Der Name, unter dem dieser Automat meldet, oder nil, wenn noch keiner gewählt wurde.

scoreSignedIn()

Ob dieser Automat bei einem Online-Konto angemeldet ist.

scoreWaiting()

Wie viele Punktzahlen in der Warteschlange stehen und noch nicht gesendet sind.

scoreUpdate()

Einmal pro Frame, aus onOverlayUpdate. Ohne es geht nichts voran.

scoreGameId()

Die GAME_ID des Spiels aus seinem Eintrag in games.dat, oder nil, wenn es keine hat. Ein Spiel ohne sie lässt sich spielen, aber nicht in eine Rangliste eintragen.

Eine Punktzahl wird eingereiht, nicht gesendet. Sie wird auf die Festplatte geschrieben und dem Dienst übergeben, wenn eine Verbindung besteht, denn ein Automat ist oft offline, und ein Spiel darf nie an der Leitung hängen bleiben, um seine eigene Bestenliste zu zeigen. Eine eingereihte Punktzahl übersteht es, wenn der Rechner ausgeschaltet wird.

Jeder kann eine Bestenliste lesen. Ein Automat, der nicht angemeldet ist, holt trotzdem die Bestenliste eines Spiels, das der Dienst allen anbietet, ohne standing, weil es keinen Spieler gibt, der irgendwo platziert sein könnte; so kann ein Spiel zeigen, wohin es melden würde, und den Spieler bitten, sich anzumelden. scoreSignedIn() unterscheidet die beiden Fälle: Ein Automat, der angemeldet ist, aber noch keinen Namen gewählt hat, hat ebenfalls keinen scorePlayerName(), und ihn zum Anmelden aufzufordern wäre falsch. Ein Spiel, das der Dienst bestimmten Konten vorbehält, hat keine Bestenliste für einen Automaten, der bei keinem davon angemeldet ist; das Holen schlägt fehl, wie es bei einem Spiel fehlschlüge, das der Dienst nicht kennt. Melden braucht immer ein Konto.

Ein Spiel kann mehr als eine Bestenliste haben. Gib einen Namen für die Bestenliste an, um jeden Spielmodus getrennt zu halten — ein Zeitrennen getrennt von einer Punktesumme, leicht getrennt von schwer — und lies sie mit demselben Namen zurück. Bestenlisten werden auch nach dem Skript getrennt, das gerade läuft: Ohne Namen kommt eine Punktzahl auf die Bestenliste, die nach dem Skript benannt ist, seinem Dateinamen ohne Endung, also meldet Collection/Raid.singe an raid; mit einem Namen kommt der Name des Skripts zuerst, also meldet scoreSubmit(points, "hard") aus diesem Skript an raid.hard. Jeder Titel in einer .game trägt dieselbe GAME_ID, und dies ist es, was die Spiele einer Sammlung auf eigenen Bestenlisten hält, selbst wenn zwei von ihnen ihre Modi gleich benennen, während ein Spiel, das zweimal aufgeführt ist (etwa in zwei Sprachen: zwei Einträge in games.dat, ein Skript), einen einzigen Satz behält. Namen von Bestenlisten sind kleingeschrieben und enthalten Buchstaben, Ziffern, -, _ und .; alles andere wird zu -. Der ganze Name hat höchstens 32 Zeichen, und der Teil des Skripts wird zuerst gekürzt, damit der Name des Modus erhalten bleibt.

Eine Bestenliste kann die niedrigste Punktzahl zuerst einordnen. Schläge, Tode, Sekunden: Manche Spiele zählen etwas, von dem ein Spieler weniger haben will. Ruf scoreLowestWins mit dem Namen der Bestenliste auf, so wie scoreSubmit ihn nimmt, und zwar vor ihrer ersten Punktzahl; dann laufen jede an diese Bestenliste gesendete Punktzahl und jedes Holen von ihr in diese Richtung. Die erste Punktzahl einer Bestenliste legt ihre Richtung für immer fest, sodass keine Bestenliste je in beide Richtungen geordnet wird: Eine Punktzahl, die danach in die andere Richtung gesendet wird, wird abgelehnt, und die Warteschlange verwirft sie, statt es erneut zu versuchen. Auf einer solchen Bestenliste ist null eine Punktzahl, und ebenso eine Zahl unter null, eine Runde unter Par.

Beispiel
-- Ein Golfspiel:  Die wenigsten Schläge gewinnen, und Par ist eine eigene Bestenliste.
scoreLowestWins("strokes")
scoreLowestWins("par")

function roundOver(strokes, coursePar)
    scoreSubmit(strokes, "strokes")
    scoreSubmit(strokes - coursePar, "par")    -- -2 ist zwei unter Par
end

Der Name auf einer Bestenliste ist ein Handle, nie eine Adresse. Er wird im Tool Online Account gewählt, getrennt vom Konto geführt und ist das Einzige an einem Spieler, das andere Spieler sehen. Drei bis zwanzig Zeichen aus Buchstaben, Ziffern, Bindestrichen und Unterstrichen, beginnend und endend mit einem Buchstaben oder einer Ziffer — keine Leerzeichen, keine Punkte und kein @, sodass ein Handle nicht einmal wie eine E-Mail-Adresse aussehen kann. Groß- und Kleinschreibung zählt für die Eindeutigkeit nicht, also sind Ann und ANN ein Name.

Ein Handle wird einmal gewählt. Freies Umbenennen hieße, dass die Geschichte einer Bestenliste eigentlich niemandem gehört, also kann ein Spieler sein Handle danach nicht ändern, und eine E-Mail-Adresse lässt sich überhaupt nicht ändern.

Ein Handle, das niemand beanspruchen sollte (admin, staff), oder eines mit Wörtern, die auf einem Bildschirm in einem öffentlichen Raum nichts zu suchen haben, wird abgelehnt, wenn es gewählt wird. Eine Punktzahl wird abgelehnt, bis ein Name gewählt wurde, denn eine Punktzahl, auf der niemandes Name steht, steht in keinem brauchbaren Sinn auf einer Bestenliste.

Was eine Punktzahl bedeutet. Der Automat ist der Rechner des Spielers, eine gemeldete Punktzahl ist also eine Behauptung — nichts, was der Client tun kann, macht mehr daraus, und sie mit einem im Client mitgelieferten Geheimnis zu signieren, sähe nur nach Sicherheit aus. Deshalb gibt hier nichts vor, eine zu prüfen, und ein Spiel sollte nicht so geschrieben werden, als täte etwas anderes es.

scoreBegin() aufzurufen lohnt sich für das Eine, das keine Behauptung ist. Ruf es auf, wenn ein Durchgang beginnt; die Punktzahl, die folgt, trägt mit, wie lange der Durchgang gedauert hat, gemessen am anderen Ende statt auf diesem Rechner. Diese Zahl ist nicht durch den Rechner des Spielers gegangen, und genau das macht sie wertvoll.

Nichts wird deswegen abgelehnt, also kostet der Aufruf ein Spiel eine Zeile und kann nie eine legitime Punktzahl abweisen. Ein Automat, der offline ist, wenn ein Durchgang beginnt, zeichnet einfach keine Zeit auf, was ehrlich ist und nicht kaputt.

Beispiel
function startLevel()
    scoreBegin()          -- die Zeitmessung beginnt jetzt, am anderen Ende
    ...
end
Beispiel
-- Am Ende eines Spiels die Punktzahl melden und dann zeigen, wo sie gelandet ist.
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. Statistik

Das Overlay für Entwickler, in der oberen linken Ecke: wie lange der Frame gedauert hat und sein schlechtester Wert der letzten zwei Sekunden, die Bildrate, der Speicher von Lua, wie viele Sprites, Sounds und Timer am Leben sind, wie viele Knoten der Szene gezeichnet wurden und in wie vielen Batches, wie viel Texturspeicher sie belegt und was die Disc gerade tut.

Es wird mit der eigenen Debug-Schrift von SDL gezeichnet, braucht also keine Schriftdatei, kein Asset und kein GUI-Dokument, und es erscheint sogar auf einem Rechner, auf dem das 3D-Gerät nie hochgekommen ist. Es wird gezeichnet, nachdem singeScreenshot sein Bild aufgenommen hat, landet also nie in einem Screenshot.

Lass es in einem ausgelieferten Spiel aus. Nichts hindert dich daran, es in deinem eigenen Service-Menü hinter eine Taste zu legen.

2.42.1. statsEnable

statsEnable(enabled)

Zeigt das Overlay an oder blendet es aus. Solange es angezeigt wird, wird das Bild in jedem Frame neu gezeichnet, die Zahlen bewegen sich also weiter, auch wenn sich sonst nichts auf dem Bildschirm bewegt.

Parameter:

  • enabled — Boolean.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: statsIsEnabled

Beispiel
-- Eine Entwicklertaste hinter einem Flag, damit das ausgelieferte Spiel keine solche Taste hat.
function onInputPressed(key)
    if DEVELOPER and key == SWITCH_SERVICE then
        statsEnable(not statsIsEnabled())
    end
end

2.42.2. statsIsEnabled

shown = statsIsEnabled()

Ob das Overlay eingeschaltet ist.

Parameter:

  • Keine.

Rückgabe: true oder false.

Seit: 3.00.

2.43. Gelände

Höhenkarten-Boden, gemacht mit meshHeightmap, das ein Graustufenbild in ein Mesh mit einem Vertex pro Pixel verwandelt; terrainGetHeight liest dieses Mesh über den Knoten, der es trägt, wieder aus. Positionen und Höhen sind in Welteinheiten, und Position und Maßstab des Knotens werden berücksichtigt. Siehe Gelände in 3D-Szenen.

2.43.1. terrainGetHeight

height = terrainGetHeight(node, x, z)

Die Welthöhe des Höhenkarten-Meshes auf node an der Weltposition x, z, interpoliert zwischen den nächsten vier Abtastwerten, oder nil jenseits seiner Ränder oder wenn das Mesh des Knotens keine Höhenkarte ist. Weltposition und Maßstab des Knotens zählen; seine Drehung wird ignoriert, da Gelände flach liegt. Verwende es, um Bäume zu platzieren, Dinge auf dem Boden erscheinen zu lassen oder für eine Kamera, die der Oberfläche folgt, ohne die Kosten eines Raycasts. Beendet das Skript bei einem Knoten-Handle, das nicht gültig ist.

Parameter:

  • node — der Knoten, dessen Mesh aus meshHeightmap kam.

  • x, z — die abzutastende Weltposition.

Rückgabe: Eine Zahl oder nil außerhalb des Geländes.

Seit: 3.00. Siehe auch: meshHeightmap, physicsRaycast, nodeSetPosition

Beispiel
-- Bäume auf den Hügeln und eine Kamera, die nie unter den Boden taucht.
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. Timer

Etwas, das später geschehen soll, ohne dass du selbst Frames zählst. Timer laufen auf der Uhr der Engine, die unter --deterministic die virtuelle ist, sodass sich ein zeitgesteuertes Spiel zwischen zwei Läufen genau wiederholt. Sie feuern mit den übrigen Callbacks des Frames, auf demselben Thread wie alles andere — es gibt nichts zu sperren und nichts, das feuern kann, während dein Skript mitten in etwas steckt.

Ein Timer, der in Rückstand geraten ist — ein langes Laden, ein Haltepunkt — feuert einmal, wenn das Spiel aufholt, statt die zwanzig Male zu feuern, die er verpasst hat.

Alles wird vergessen, wenn das Skript neu lädt, ein Timer aus dem letzten Lauf feuert also nie in den nächsten hinein.

2.44.1. timerAfter

id = timerAfter(milliseconds, function)

Ruft die Funktion einmal auf, später. Die Funktion bekommt die eigene id des Timers, sodass eine Funktion mehreren Timern dienen kann.

Parameter:

  • milliseconds — Zahl; null oder weniger feuert im nächsten Frame.

  • function — aufgerufen als function(id).

Rückgabe: eine Zahl; die id des Timers.

Seit: 3.00. Siehe auch: timerCancel, timerEvery

Beispiel
-- Die Explosion ausklingen lassen, bevor der Game-Over-Bildschirm kommt.
soundPlay(bang)
timerAfter(1500, function()
    showGameOver()
end)

2.44.2. timerCancel

timerCancel(id)

Stoppt einen Timer. Einen abzubrechen, der schon gefeuert hat, ist kein Fehler, also muss nichts vorher prüfen.

Parameter:

  • id — Zahl; aus timerAfter oder timerEvery.

Rückgabe: nichts.

Seit: 3.00.

2.44.3. timerEvery

id = timerEvery(milliseconds, function)

Ruft die Funktion immer wieder auf, bis der Timer abgebrochen wird.

Parameter:

  • milliseconds — Zahl; wie lange zwischen den Aufrufen.

  • function — aufgerufen als function(id).

Rückgabe: eine Zahl; die id des Timers.

Seit: 3.00. Siehe auch: timerCancel

Beispiel
-- Den Countdown einmal pro Sekunde weiterzählen und stoppen, wenn er abgelaufen ist.
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)

Ob der Timer noch einmal feuern wird: true für einen wiederholenden, bis er abgebrochen wird, false für einen einmaligen, der schon ausgelöst hat.

Parameter:

  • id — Zahl.

Rückgabe: true oder false.

Seit: 3.00.

2.45. Tween

Eine Zahl über die Zeit von einem Wert zu einem anderen bewegen, entlang einer Kurve. Ein- und Ausblendungen, Gleitbewegungen, Kamerafahrten, ein Lebensbalken, der sich leert, ein Menü, das hereingleitet — alles dasselbe.

tweenValue gibt dir die Zahl und lässt dich entscheiden, was sie bedeutet. Das ist Absicht: Die Engine hat Knoten, Sprites, GUI-Elemente, Materialien und Lichter, und ein Tween, der jedes davon kennte, brächte fünf Sätze von Aufrufen mit, die im Gleichschritt zu halten wären. Einer, der eine Zahl übergibt, bringt keinen mit, und er funktioniert mit Dingen, von denen die Engine nie gehört hat.

Die Easing-Kurven sind die üblichen. EASE_LINEAR ist gar keine Kurve; EASE_QUAD_*, EASE_CUBIC_*, EASE_SINE_* und EASE_EXPO_* reichen von sanft bis scharf; EASE_BACK_* schießt über das Ziel hinaus und kommt zurück; EASE_ELASTIC_* federt; EASE_BOUNCE_* fällt und springt auf. Jede gibt es als _IN (langsam am Anfang), _OUT (langsam am Ende) und _IN_OUT (beides).

2.45.1. tweenCancel

tweenCancel(id)

Stoppt einen Tween, wo er gerade ist. Keine der beiden Funktionen wird wieder aufgerufen, und der Wert bleibt, wo immer er angekommen war.

Parameter:

  • id — Zahl; aus tweenValue.

Rückgabe: nichts.

Seit: 3.00.

2.45.2. tweenIsActive

running = tweenIsActive(id)

Ob der Tween noch läuft.

Parameter:

  • id — Zahl.

Rückgabe: true oder false.

Seit: 3.00.

2.45.3. tweenValue

id = tweenValue(from, to, milliseconds, easing, onUpdate [, onDone])

Bewegt eine Zahl über milliseconds von from nach to und ruft dabei in jedem Frame onUpdate(value, progress) auf — progress läuft von 0 bis 1 und ignoriert die Kurve — und am Ende einmal onDone(). Das letzte onUpdate landet immer genau auf to, sodass nichts ein Pixel zu kurz endet.

Parameter:

  • from, to — Zahlen.

  • milliseconds — Zahl; null oder weniger kommt im nächsten Frame an.

  • easing — einer der EASE_-Werte.

  • onUpdate — aufgerufen als function(value, progress).

  • onDone — optional; ohne Argumente aufgerufen, wenn er fertig ist.

Rückgabe: eine Zahl; die id des Tweens.

Seit: 3.00. Siehe auch: tweenCancel

Beispiel
-- Den Titel hereingleiten lassen und gleichzeitig das Overlay einblenden.
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. Fahrzeug

Autos, Motorräder, Panzer und Boote, gebaut auf einem Chassis-Körper (siehe Physik, Fahrzeuge und Wasser). Ein Fahrzeug hat kein eigenes Handle: Es wird über seinen Chassis-Knoten angesprochen, der bereits einen BODY_DYNAMIC-Körper aus bodyNew tragen muss, und ein Knoten ohne Fahrzeug beendet in jedem Aufruf nach vehicleNew das Skript. Das Chassis blickt nach -Z mit Y oben; Entfernungen sind Welteinheiten, Kräfte Newton, Drehmomente Newtonmeter und Motordrehzahlen Umdrehungen pro Minute. Jeder Abstimmungsaufruf markiert das Fahrzeug für einen Neuaufbau beim nächsten Physikschritt, um die Radpositionen herum, die beim Hinzufügen der Räder festgehalten wurden. Bis zu 16 Fahrzeuge gleichzeitig, jedes mit bis zu 16 Rädern.

2.46.1. vehicleNew

vehicleNew(node, kind)

Macht aus dem dynamischen Körper auf node das Chassis eines Fahrzeugs. Ein Auto, Motorrad oder Panzer braucht mindestens zwei Räder aus vehicleAddWheel, bevor der nächste Physikschritt es baut; ein Boot hat keine Räder und wird von einem Propeller geschoben, der nur unter einer mit bodySetWater gemachten Oberfläche wirkt. Das neue Fahrzeug beginnt mit den Standardwerten: ein Motor mit 500 Nm, der bei 6000 U/min sein Maximum erreicht und im Leerlauf mit 1000 dreht, das Fünfgang-Automatikgetriebe von Jolt, 35 Grad Lenkeinschlag, Bremsen mit 1500 Nm und eine Handbremse mit 4000 Nm, eine Federung mit 1,5 Hz bei 0,5 Dämpfung und keine Stabilisatoren. Ein erneuter Aufruf auf demselben Knoten verwirft zuerst das alte Fahrzeug und seine Räder. Beendet das Skript bei einer unbekannten Art, einem Knoten, dessen Körper nicht dynamisch ist, einer Art mit Rädern in einer 2D-Welt oder wenn schon 16 Fahrzeuge existieren.

Parameter:

  • node — der Chassis-Knoten, der einen BODY_DYNAMIC-Körper trägt.

  • kind — VEHICLE_CAR (beliebig viele Achsen), VEHICLE_MOTORCYCLE (zwei Räder hintereinander, die sich in Kurven legen), VEHICLE_TANK (Räder auf zwei Ketten, wendet auf der Stelle) oder VEHICLE_BOAT (ein schwimmender Rumpf mit Propeller und Ruder).

Beispiel
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)

Entfernt das Fahrzeug von seinem Chassis: den Rad-Constraint, die Fahrereingabe und die ganze Abstimmung. Der Körper bleibt ein gewöhnlicher dynamischer Körper, ein Wrack rutscht und überschlägt sich also weiter, und die Radknoten bleiben, wo der letzte Schritt sie hingestellt hat; nichts bewegt sie wieder, außer das Skript tut es. Ein Knoten ohne Fahrzeug beendet das Skript.

Seit: 3.00. Siehe auch: vehicleNew, bodyDelete

Beispiel
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)                    -- Das Chassis überschlägt sich als Körper weiter
        soundPlay(crashSound)
        emitterStart(smoke)
    end
end

2.46.3. vehicleAddWheel

index = vehicleAddWheel(node, wheelNode, radius, width, suspension)

Fügt dem Fahrzeug ein Rad hinzu, dort, wo wheelNode relativ zum Chassis steht, wenn das Fahrzeug das nächste Mal gebaut wird. Die Federung hängt das Rad unbelastet suspension Einheiten unter diesen Punkt und federt bis auf die Hälfte davon ein. Von da an schreibt die Engine nach jedem Schritt die Welttransformation des Radknotens, mit X als Achse und Y oben, also gehört der sichtbare Reifen auf einen Kindknoten: ein um 90 Grad um Z gedrehter meshCylinder. Räder, die entlang der Front vor der durchschnittlichen Radposition liegen, zählen als Vorderräder: Sie lenken standardmäßig und haben keine Handbremse. Ein Panzer ordnet seine Räder der linken oder rechten Kette zu, je nachdem, auf welcher Seite des Chassis sie sitzen, und braucht mindestens eines auf jeder Seite. Werte unter 0.001 werden darauf angehoben. Beendet das Skript beim 17. Rad.

Parameter:

  • node — der Chassis-Knoten.

  • wheelNode — der Knoten, an dem das Rad hängt; seine Position relativ zum Chassis ist der Befestigungspunkt, und die Engine stellt ihn von nun an.

  • radius — der Radius des Rads, in Welteinheiten.

  • width — die Breite des Rads, in Welteinheiten.

  • suspension — die Länge der Federung bei voller Ausdehnung, in Welteinheiten; sie federt bis auf die Hälfte ein.

Rückgabe: Der Index des Rads, ab 0, für vehicleSetWheel, vehicleIsWheelOnGround und vehicleGetWheelSlip.

Hinweise: Ein Fahrzeug wird erst gebaut, wenn es zwei Räder hat, und ein Auto oder Motorrad braucht außerdem ein angetriebenes Rad; bis dahin steht es als einfacher Körper da, und die Fahraufrufe tun nichts.

Seit: 3.00. Siehe auch: vehicleSetWheel, vehicleSetSuspension, nodeFind

Beispiel
-- Das Lkw-Modell trägt leere Knoten, die nach seinen Rädern benannt sind.
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)

Stellt den Propeller eines Boots ein: die Kraft, mit der er bei Vollgas schiebt, Standard 2000 Newton, und den Punkt im Bezugssystem des Rumpfs, an dem er schiebt, Standard 0, -0.2, 1, knapp unter Deck am Heck. Der Schub wirkt entlang der Front des Rumpfs und nur, solange dieser Punkt unter einer Wasseroberfläche ist; derselbe Punkt entscheidet, ob Ruder und Bremse wirken. Eine negative Kraft wird zu 0. Arten mit Rädern speichern die Werte und ignorieren sie.

Parameter:

  • node — der Knoten des Rumpfs.

  • maxForce — der Schub bei Vollgas, in Newton.

  • x, y, z — wo der Propeller sitzt, im Bezugssystem des Rumpfs; das Heck ist +Z.

Seit: 3.00. Siehe auch: vehicleSetRudder, bodySetWater, bodySetBuoyancy

Beispiel
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)                    -- Liegt hoch im Becken
vehicleNew(raft, VEHICLE_BOAT)
vehicleSetThrust(raft, 600, 0, -0.1, 1.2)     -- Ein Außenborder, ans Heck gehängt
vehicleSetRudder(raft, 300)

2.46.5. vehicleSetWheel

vehicleSetWheel(node, index, steered, driven)

Legt fest, ob ein Rad mit der Lenkeingabe einschlägt und ob der Motor es antreibt, und ersetzt die Standardwerte für dieses Rad: Vorderräder lenken, und jedes Rad wird angetrieben außer dem vorderen eines Motorrads. Angetriebene Räder werden quer über das Chassis paarweise zu Differenzialen zusammengefasst, eines pro Achse, und das Drehmoment des Motors wird gleichmäßig auf die Achsen verteilt; ein angetriebenes Rad ohne Partner ist eine eigene Achse. Ein Panzer ignoriert beide Flags, da seine Ketten jedes Rad antreiben und den Rumpf drehen. Wirkt beim Neuaufbau im nächsten Schritt. Beendet das Skript bei einem Index, für den das Fahrzeug kein Rad hat.

Parameter:

  • node — der Chassis-Knoten.

  • index — der Index des Rads aus vehicleAddWheel.

  • steered — true, damit das Rad bei vollem Einschlag bis zu vehicleSetSteering einschlägt.

  • driven — true, damit der Motor es dreht.

Beispiel
-- Ein Sportwagen mit Hinterradantrieb:  Die Vorderräder lenken nur.
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)

Stellt den Motor ein: Spitzendrehmoment in Newtonmetern, die Drehzahlgrenze und die Leerlaufdrehzahl in Umdrehungen pro Minute. Die Standardwerte sind 500, 6000 und 1000, und die Leerlaufdrehzahl ist wieder 1000, wenn sie weggelassen wird. Das Drehmoment wird auf 1 oder mehr gehalten, die Drehzahlgrenze auf 100 oder mehr und die Leerlaufdrehzahl zwischen 1 und der Drehzahlgrenze. Ein Boot hat keinen Motor und ignoriert den Aufruf. Wirkt beim Neuaufbau im nächsten Schritt.

Parameter:

  • node — der Chassis-Knoten.

  • maxTorque — Spitzendrehmoment, in Newtonmetern.

  • maxRpm — die Drehzahlgrenze, in Umdrehungen pro Minute.

  • minRpm — die Leerlaufdrehzahl, in Umdrehungen pro Minute; Standard 1000.

Seit: 3.00. Siehe auch: vehicleSetGears, vehicleGetRpm

Beispiel
vehicleSetEngine(tank, 1500, 4000, 800)       -- Ein Diesel:  Drehmoment untenherum
vehicleSetEngine(bike, 150, 9000, 1200)       -- Ein Schreihals

function onOverlayUpdate()
    local rpm = vehicleGetRpm(bike)
    overlayClear()
    fontPrint(20, 20, string.format("%5.0f rpm", rpm))
    if rpm > 8500 then
        spriteDraw(shiftLight, 200, 20)       -- Zeit zum Hochschalten
    end
    return OVERLAY_UPDATED
end

2.46.7. vehicleSetGears

vehicleSetGears(node, { ratio, ... })
vehicleSetGears(node, { ratio, ... }, reverseRatio)
vehicleSetGears(node, { ratio, ... }, reverseRatio, automatic)

Stellt das Getriebe ein: ein bis acht Vorwärtsübersetzungen, den ersten Gang zuerst, die Übersetzung des Rückwärtsgangs (Standard 2.9, als positive Zahl angegeben) und ob das Getriebe selbst schaltet (Standard true). Ein Fahrzeug, das diesen Aufruf nie bekommt, fährt mit dem Fünfganggetriebe von Jolt, 2.66, 1.78, 1.3, 1.0 und 0.74, mit demselben Rückwärtsgang. Ist automatic false, schaltet das Getriebe nicht mehr von selbst, und es gibt keinen Aufruf, um es aus dem Skript zu schalten. Ein Boot hat kein Getriebe und ignoriert den Aufruf. Wirkt beim Neuaufbau im nächsten Schritt. Beendet das Skript, wenn die Tabelle leer ist oder mehr als acht Übersetzungen enthält.

Parameter:

  • node — der Chassis-Knoten.

  • { ratio, …​ } — Übersetzungen der Vorwärtsgänge, Motorumdrehungen pro Getriebeumdrehung, der erste Gang zuerst; eine bis acht davon.

  • reverseRatio — die Übersetzung des Rückwärtsgangs; Standard 2.9.

  • automatic — true (Standard), damit das Getriebe selbst schaltet.

Seit: 3.00. Siehe auch: vehicleGetGear, vehicleSetEngine

Beispiel
-- Ein eng gestuftes Sechsganggetriebe für den Rennwagen, ein lang übersetztes Dreiganggetriebe für den 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)

Stellt das Ruder eines Boots ein: das Drehmoment um die Hochachse des Rumpfs bei voller Lenkeingabe, Standard 800 Newtonmeter. Das Ruder greift mit der Geschwindigkeit, ein Fünftel des Drehmoments im Stand und das volle ab 3 Welteinheiten pro Sekunde, und es dreht andersherum, während das Boot rückwärts fährt. Es wirkt nur, solange der Propellerpunkt unter Wasser ist. Ein negatives Drehmoment wird zu 0; Arten mit Rädern ignorieren den Aufruf.

Seit: 3.00. Siehe auch: vehicleSetThrust, vehicleDrive

Beispiel
vehicleNew(patrolBoat, VEHICLE_BOAT)
vehicleSetThrust(patrolBoat, 4000, 0, -0.4, 3.5)
vehicleSetRudder(patrolBoat, 2500)            -- Schwerer Rumpf, großes Ruder

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)

Stellt die Feder jedes Rads ein: ihre Eigenfrequenz in Hertz (Standard 1.5, auf 0.1 oder mehr gehalten; höher ist härter) und ihren Dämpfungsgrad (Standard 0.5; 0 schwingt nach, 1 kommt ohne Überschwingen zur Ruhe). Wirkt beim Neuaufbau im nächsten Schritt, auf alle Räder gleichzeitig; eine Feder pro Rad gibt es nicht. Ein Boot hat keine Federung und ignoriert den Aufruf.

Parameter:

  • node — der Chassis-Knoten.

  • frequency — die Eigenfrequenz der Feder, in Hertz.

  • damping — der Dämpfungsgrad, ab 0 aufwärts.

Seit: 3.00. Siehe auch: vehicleAddWheel, vehicleSetAntiRoll

Beispiel
-- Der Buggy schwebt über die Dünen; der Rennwagen bewegt sich kaum auf seinen Federn.
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)

Legt fest, wie weit die gelenkten Räder bei vollem Einschlag einschlagen, in Grad; Standard 35, begrenzt auf 0 bis 89. Eine Lenkeingabe von -1 oder 1 aus vehicleDrive erreicht diesen Winkel, kleinere Eingaben einen entsprechenden Anteil davon. Wirkt beim Neuaufbau im nächsten Schritt. Ein Panzer lenkt mit seinen Ketten und ein Boot mit seinem Ruder, also ignorieren beide den Aufruf.

Seit: 3.00. Siehe auch: vehicleSetWheel, vehicleDrive

Beispiel
-- Das Gokart wendet auf der Stelle; der Lkw braucht einen weiten Bogen.
vehicleSetSteering(kart, 45)
vehicleSetSteering(truck, 25)
vehicleSetSteering(bus, 20)
if difficulty == "arcade" then
    vehicleSetSteering(truck, 35)             -- Nachsichtiges Fahrverhalten
end

2.46.11. vehicleSetBrakes

vehicleSetBrakes(node, brakeTorque, handBrakeTorque)

Stellt das Bremsmoment ein, das jedes Rad bei voll getretenem Pedal aufbringen kann, Standard 1500 Newtonmeter, und das Moment der Handbremse an den Hinterrädern, Standard 4000; die Vorderräder, also die vor der durchschnittlichen Radposition, haben keine Handbremse. Negative Werte werden zu 0. Ein Panzer bremst seine Ketten mit den Kettenstandardwerten von Jolt und ignoriert den Aufruf, und ein Boot bremst durch einen Widerstand gegen seine eigene Geschwindigkeit, also ignoriert es den Aufruf ebenfalls. Wirkt beim Neuaufbau im nächsten Schritt.

Parameter:

  • node — der Chassis-Knoten.

  • brakeTorque — Bremsmoment der Fußbremse an jedem Rad, in Newtonmetern.

  • handBrakeTorque — Bremsmoment der Handbremse an den Hinterrädern, in Newtonmetern.

Seit: 3.00. Siehe auch: vehicleDrive, vehicleGetWheelSlip

Beispiel
vehicleSetBrakes(car, 2200, 6000)             -- Rennbeläge und eine Handbremse, bereit zum Driften

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)

Fügt an jeder Achse einen Stabilisator hinzu, in Newton pro Meter; 0 (Standard) baut keinen ein, und ein negativer Wert wird zu 0. Ein Stabilisator verbindet die beiden angetriebenen Räder einer Achse, eine Achse, deren Räder nicht angetrieben sind, bekommt also keinen, und ein Motorrad hat keinen. Ein paar Hundert halten ein Auto in Kurven flach; zu viel hebt die kurveninneren Räder an. Ein Panzer ignoriert den Aufruf. Wirkt beim Neuaufbau im nächsten Schritt.

Seit: 3.00. Siehe auch: vehicleSetSuspension, vehicleSetWheel

Beispiel
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)                  -- Bleibt flach durch die Schikane

2.46.13. vehicleDrive

vehicleDrive(node, forward, right)
vehicleDrive(node, forward, right, brake)
vehicleDrive(node, forward, right, brake, handBrake)

Setzt die Eingabe des Fahrers, die bis zum nächsten Aufruf gilt, ruf es also in jedem Frame aus onOverlayUpdate auf. Gas und Lenkung reichen von -1 bis 1, Bremse und Handbremse von 0 bis 1; Werte außerhalb werden begrenzt, und weggelassene Eingaben sind 0. Ein Auto oder Motorrad bekommt alle vier als Fahrereingabe von Jolt, wobei negatives Gas über den Rückwärtsgang zurücksetzt. Ein Panzer nimmt forward als sein Gas, und right bremst die innere Kette ab; ohne Gas laufen die Ketten gegeneinander, sodass sich der Rumpf auf der Stelle dreht, und die Handbremse wird ignoriert. Ein Boot nimmt forward als Gas des Propellers, right als Ruder und brake als Widerstand gegen die Geschwindigkeit des Rumpfs, ignoriert die Handbremse und tut gar nichts, solange der Propeller außerhalb des Wassers ist. Jede Eingabe ungleich null weckt ein Chassis, das eingeschlafen ist.

Parameter:

  • node — der Chassis-Knoten.

  • forward — Gas, -1 bis 1; negativ fährt rückwärts.

  • right — Lenkung, -1 (links) bis 1 (rechts).

  • brake — Fußbremse, 0 bis 1; Standard 0.

  • handBrake — Handbremse, 0 bis 1; Standard 0.

Beispiel
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                             -- Rückwärts, solange A gedrückt ist
    end
    vehicleDrive(car, gas, steer, brake, handBrake)
    return OVERLAY_NOT_UPDATED
end

2.46.14. vehicleGetSpeed

speed = vehicleGetSpeed(node)

Die Geschwindigkeit des Chassis-Körpers entlang seiner Front, in Welteinheiten pro Sekunde, negativ, während er rückwärts fährt; seitliche Bewegung in einem Drift zählt nicht. Funktioniert für jede Art, Boote eingeschlossen, ab dem Moment, in dem vehicleNew aufgerufen wird.

Rückgabe: Eine Zahl.

Seit: 3.00. Siehe auch: vehicleGetRpm, vehicleGetGear, bodyGetVelocity

Beispiel
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)

Die Drehzahl des Motors in Umdrehungen pro Minute, zwischen der Leerlaufdrehzahl und der Drehzahlgrenze aus vehicleSetEngine, für einen Drehzahlmesser oder die Tonhöhe einer Motorgeräuschschleife. 0 für ein Boot, das keinen Motor hat, und für ein Fahrzeug, das noch nicht gebaut wurde, weil ihm Räder fehlen.

Rückgabe: Eine Zahl.

Seit: 3.00. Siehe auch: vehicleSetEngine, vehicleGetGear

Beispiel
-- Ein Drehzahlbalken, der über 6000 rot wird.
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)

Der Gang, den das Getriebe eingelegt hat: 0 im Leerlauf, -1 im Rückwärtsgang, ab 1 aufwärts für die Vorwärtsgänge in der Reihenfolge, in der vehicleSetGears sie angegeben hat. 0 für ein Boot und für ein Fahrzeug, das noch nicht gebaut wurde.

Rückgabe: Eine Ganzzahl.

Seit: 3.00. Siehe auch: vehicleSetGears, vehicleGetRpm

Beispiel
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)

Ob der Cast der Federung dieses Rads in diesem Schritt etwas gefunden hat, gegen das sie drücken kann. false für einen Index, für den das Fahrzeug kein Rad hat, und für ein Fahrzeug, das noch nicht gebaut wurde; in keinem der beiden Fälle wird ein Fehler ausgelöst.

Rückgabe: Wahr oder falsch.

Seit: 3.00. Siehe auch: vehicleAddWheel, vehicleGetWheelSlip

Beispiel
-- In der Luft, wenn kein Rad den Boden berührt; eine Landung nach einem Sprung lässt die Kamera wackeln.
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)

Wie stark das Rad entlang seiner Rollrichtung durchdreht oder rutscht, von 0 haftend bis 1 durchdrehend oder blockiert, für Reifenquietschen, Rauch und Bremsspuren. Immer 0 für die Räder eines Panzers, für einen Index, für den das Fahrzeug kein Rad hat, und für ein Fahrzeug, das noch nicht gebaut wurde.

Rückgabe: Eine Zahl.

Seit: 3.00. Siehe auch: vehicleIsWheelOnGround, vehicleGetSpeed

Beispiel
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. Ansicht

Eine Ansicht ist eine zweite Kamera, die in jedem Frame in eine Textur gerendert wird, für einen Monitor, einen Spiegel oder ein Portal in der Szene: viewNew erzeugt eine und gibt ein ganzzahliges Handle zurück, viewSetCamera hängt sie an einen Knoten, und materialSetView zeigt sie auf einem Material. Bis zu vier gibt es gleichzeitig; jede rendert die ganze Szene noch einmal in ihrer eigenen Größe, in Pixeln unabhängig vom Overlay, mit der Projektion der Hauptkamera, den Schatten des Frames (die Kaskaden eines Richtungslichts eingeschlossen: Jeder Punkt nimmt die feinste Kaskade, die ihn abdeckt) und ohne Bloom, setze also wenige und kleine ein. Jede Ansicht dreht Billboards (nodeSetBillboard) zu ihrer eigenen Kamera und sortiert Zeichenaufrufe mit Blending von ihr aus von hinten nach vorn, sodass eine Ansicht, deren Kamera von woanders schaut, Billboards trotzdem von vorn und transparente Objekte in der richtigen Reihenfolge sieht. Ein falsches Handle beendet das Skript. Siehe 3D-Szenen.

2.47.1. viewDelete

viewDelete(view)

Gibt die Ansicht und ihre Texturen frei und beendet den zusätzlichen Render-Durchgang, den sie gekostet hat. Materialien, die sie zeigen, kehren zu ihrer eigenen Textur zurück. Das Handle ist danach ungültig und beendet das Skript, wenn es wieder verwendet wird; da es nur vier Ansichten gleichzeitig gibt, lösche die, die ein Level nicht mehr braucht.

Seit: 3.00. Siehe auch: viewNew, materialSetView

Beispiel
-- Die Monitore im Sicherheitsraum rendern nur, solange die Spielfigur darin ist.
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)

Erzeugt eine Kamera, die in jedem Frame in eine Textur von width mal height gerendert wird (jeweils auf 1 bis 4096 begrenzt), aus der Standardansicht, bis viewSetCamera einen Knoten nennt, und gibt das Ansicht-Handle für materialSetView zurück. Die Ansicht verwendet die Projektion aus cameraSetPerspective oder cameraSetOrthographic in ihrem eigenen Seitenverhältnis. Die Szene rendert pro Ansicht einmal mehr, also reichen 512 mal 384 für einen Monitor völlig, und ein Raspberry Pi will es kleiner. Beendet das Skript, wenn 3D nicht verfügbar ist oder schon vier Ansichten in Gebrauch sind.

Parameter:

  • width — die Breite der Textur in Pixeln.

  • height — die Höhe der Textur in Pixeln.

Rückgabe: Das Ansicht-Handle, eine Ganzzahl.

Seit: 3.00. Siehe auch: viewSetCamera, materialSetView, viewDelete

Beispiel
-- Ein Überwachungsmonitor, der eine Kamera hinter der Spielfigur zeigt.
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)

Der Knoten, von dem aus die Ansicht schaut, entlang seiner eigenen -Z-Achse wie die Hauptkamera, also zählt die Bewegung seiner Elternknoten. Mit nil oder ohne zweites Argument kehrt die Ansicht zur Standardansicht von (0, 0, 5) mit Blick auf den Ursprung zurück. Hänge den Knoten für einen Rückspiegel an ein Auto, oder spiegle die Position der Hauptkamera an einer Wand für einen Spiegel darin. Beendet das Skript bei einem Knoten-Handle, das nicht gültig ist.

Seit: 3.00. Siehe auch: viewNew, cameraSet, nodeLookAt

Beispiel
-- Der Monitor in der Lobby wechselt zwischen drei Überwachungskameras.
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. Video

Die Familie video* verwaltet zusätzliche Videoclips über der Disc: eine Figur, die in einer Ecke spricht, eine vorgerenderte Animation an einem Wendepunkt der Geschichte, mehrere gleichzeitige Einspieler. Mit videoLoad können beliebig viele Videos geladen werden, und jedes gibt ein opakes ganzzahliges Handle zurück, das jede andere video*-Funktion als erstes Argument nimmt; ein Handle, das entladen wurde, beendet das Skript. Videos werden mit videoDraw in Overlay-Koordinaten auf das Overlay gezeichnet und wie Sprites darübergelegt, und ein Video läuft nur weiter, während es gezeichnet wird (oder über materialSetVideo als Material dient). Jedes Video hat seine eigene Tonspurauswahl und Stereolautstärke, unabhängig von der Disc. Wie Sprites müssen Videos aus onOverlayUpdate gezeichnet und schließlich mit videoUnload freigegeben werden; die Zeichenregeln stehen unter Overlay.

2.48.1. videoDraw

videoDraw(id, x, y, x2, y2)
videoDraw(id, x, y, centered)

Bringt ein Video zu dem Frame, den seine Uhr verlangt, und zeichnet diesen Frame auf das Overlay. Die Uhr folgt dem Audio des Videos, wenn es welches hat, und sonst der realen Zeit, ein Aufruf kann also null, einen oder mehrere Frames weiterrücken; ein Video, das sein Ende erreicht, springt zu Frame 0 zurück. Die Form mit fünf Argumenten streckt den Frame in das Rechteck von (x, y) bis einschließlich (x2, y2), immer mit Nearest-Neighbor-Abtastung und ohne Rücksicht auf videoScale, videoRotate und videoQuality. Die Form mit vier Argumenten zeichnet den Frame in seiner nativen Größe, transformiert durch videoScale und videoRotate, verankert an seiner linken oberen Ecke oder, wenn centered true ist, an seiner Mitte; der transformierte Frame wird nur neu erzeugt, wenn sich der Frame oder die Transformation ändert, und gedrehte Ecken sind transparent. Hat der Decoder noch keinen Frame erzeugt, wird nichts gezeichnet.

Ein Frame, den videoScale oder videoRotate weder skaliert noch dreht, wird stattdessen von der GPU unter dem Overlay gezeichnet und kostet so gut wie nichts, wenn er dort auf das Overlay kommt, wo seit einem overlayClear auf eine transparente Farbe nichts gezeichnet wurde — etwa als Hintergrundvideo, das zuerst gezeichnet wird. Alles, was danach gezeichnet wird, liegt weiterhin darüber. Er wird dann so auf den Bildschirm skaliert wie das Overlay, statt zuerst per Nearest-Neighbor ins Overlay. Überall sonst kopiert die CPU den Frame ins Overlay, was auf einem kleinen Rechner mehrere Millisekunden pro Frame kostet; zeichne ein Video also vor allem, was darüber liegt, nicht danach.

Parameter:

  • id — Video-Handle aus videoLoad.

  • x, y — Ankerpunkt in Overlay-Koordinaten.

  • x2, y2 — gegenüberliegende Ecke des Zielrechtecks, einschließlich.

  • centered — Boolean. true setzt die Mitte des gezeichneten Frames auf (x, y), false seine linke obere Ecke. Verwende true für gedrehte Videos.

Hinweise: Ein Video, das nicht gezeichnet wird, läuft nicht weiter, ein verborgener Clip ist also von selbst pausiert. Zeichne nur aus onOverlayUpdate.

Seit: 2.00. Die skalierte/gedrehte Form mit dem Flag centered kam in 2.10 hinzu. Siehe auch: videoLoad, videoScale, videoRotate, spriteDraw

Beispiel
-- Attract-Clip in einem festen Kasten, als Schleife über seine eigenen Start- und End-Frames.
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)

Gibt den nullbasierten Index der Tonspur zurück, die ein geladenes Video abspielt. videoLoad wählt die durch --audio oder den Eintrag AUDIO_TRACK in games.dat genannte Spur (Standard 0), sofern die Datei so viele Spuren hat; ein Video ganz ohne Audio meldet -1.

Rückgabe: ganzzahliger Spurindex.

Beispiel
-- Im Options-Overlay zeigen, welche Synchronfassung die Zwischensequenz verwendet.
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)

Gibt zurück, wie viele Audiostreams ein geladenes Video enthält. Ein stummer Clip meldet 0; sichere Schleifen und Modulo-Rechnungen dagegen ab.

Rückgabe: ganzzahlige Anzahl, 0 oder mehr.

Beispiel
-- Das Sprachmenü nur anbieten, wenn die Zwischensequenz wirklich eine Auswahl hat.
cutscene = videoLoad("videos/briefing.mkv")
if videoGetAudioTracks(cutscene) > 1 then
    buildLanguageMenu(cutscene)
else
    languageMenuEnabled = false
end

2.48.4. videoGetFrame

frame = videoGetFrame(id)

Gibt den Frame zurück, auf dem ein geladenes Video steht, nullbasiert. Die Position ändert sich nur, während das Video läuft und gezeichnet wird, und springt auf 0 zurück, wenn der Clip von vorn beginnt. Vergleiche sie mit deinen eigenen Start- und Endmarken, um einen Abschnitt als Schleife zu spielen, oder mit videoGetFrameCount, um das Ende eines einmal abgespielten Clips zu erkennen.

Rückgabe: ganzzahlige Frame-Nummer.

Seit: 2.00 Siehe auch: videoSeek, videoGetFrameCount, videoDraw

Beispiel
-- Die Steuerung an den Spieler zurückgeben, wenn das Briefing einmal durchgelaufen ist.
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)

Gibt die Gesamtzahl der Frames eines geladenen Videos zurück, gezählt aus der Frame-Tabelle der Datei, als sie indiziert wurde. Die Frames reichen von 0 bis count - 1. Verwende es für Fortschrittsbalken, um eine Schleife umlaufen zu lassen oder um zu erkennen, wann ein einmal abgespielter Clip fast fertig ist.

Rückgabe: ganzzahlige Anzahl der Frames.

Seit: 2.00 Siehe auch: videoGetFrame, videoSeek, videoIsPlaying

Beispiel
-- Fortschrittslinie unter einem Ladeclip:  ein Umriss und eine Füllung, die wächst.
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)

Gibt die Höhe der Frames eines geladenen Videos in Pixeln zurück, die native Größe der Datei und nicht die Größe, in der es gezeichnet wird. Kombiniere es mit videoScale, um einen Clip unter Beibehaltung seines Seitenverhältnisses in einen Kasten einzupassen.

Rückgabe: ganzzahlige Höhe in Pixeln.

Seit: 2.00 Siehe auch: videoGetWidth, videoScale

Beispiel
-- Den Clip ohne Verzerrung in ein 320x240-Fenster einpassen.
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)

Gibt das in der Datei gespeicherte Sprach-Tag für eine Tonspur eines geladenen Videos zurück. Das Tag ist ein dreibuchstabiger ISO-639-Code wie "eng" oder "jpn"; eine Spur ohne dreibuchstabiges Tag ergibt "unk". Eine Spur außerhalb von 0 bis videoGetAudioTracks(id) - 1 beendet das Skript.

Parameter:

  • id — Video-Handle.

  • track — nullbasierter Index der Tonspur.

Rückgabe: String mit dem Sprachcode.

Beispiel
-- Die Synchronfassung der Zwischensequenz an die für die Disc gewählte Sprache anpassen.
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)

Schlägt den englischen Namen eines Sprachcodes nach. Anders als die übrigen video*-Funktionen nimmt sie kein Handle; sie ist ein reines Nachschlagen in einer Tabelle, das zweibuchstabige Codes nach ISO 639-1 und dreibuchstabige Codes nach ISO 639-2 (sowohl die T- als auch die B-Form) annimmt, verglichen ohne Rücksicht auf Groß- und Kleinschreibung. Unbekannte Codes, auch das "unk", das für Spuren ohne Tag zurückkommt, ergeben "Unknown". Framework.singe stellt sie zur Symmetrie mit der Disc-API auch als discGetLanguageDescription bereit.

Parameter:

  • code — Sprachcode wie "en", "eng" oder "jpn".

Rückgabe: String mit dem Namen der Sprache oder "Unknown".

Seit: 2.10 Siehe auch: videoGetLanguage, discGetLanguage

Beispiel
-- Aus den Spuren eines Videos ein Menü zur Sprachauswahl bauen.
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()

Gibt die Stereolautstärke eines geladenen Videos als zwei Prozentwerte zurück. Ein frisch geladenes Video steht auf beiden Kanälen auf dem Pegel von --volume_nonvldp (Standard 100). Beachte, dass zwei Werte zurückkommen, der linke zuerst.

Ohne Argument aufgerufen ist es eine Hypseus-Erweiterung, die stattdessen die eigene Lautstärke der Laserdisc liefert, als einzelne Zahl auf der Skala 0 bis 64 von Hypseus statt als Prozentwert. Dessen Spiele verdoppeln sie für musicSetVolume, dessen Bereich 0 bis 128 ist. Der Pegel folgt --volume_vldp.

Rückgabe: zwei Ganzzahlen, links und rechts, jeweils 0 bis 100; oder ohne Argument eine Ganzzahl, 0 bis 64.

Seit: 2.00, die Disc-Form ohne Argument 3.00 Siehe auch: videoSetVolume, videoLoad

Beispiel
-- Die Zwischensequenz leiser stellen, während eine Sprachzeile läuft, und danach wiederherstellen.
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)

Gibt die Breite der Frames eines geladenen Videos in Pixeln zurück, die native Größe der Datei und nicht die Größe, in der es gezeichnet wird.

Rückgabe: ganzzahlige Breite in Pixeln.

Seit: 2.00 Siehe auch: videoGetHeight, videoScale

Beispiel
-- Einen in nativer Größe gezeichneten Clip oben im Overlay zentrieren.
local x = (overlayGetWidth() - videoGetWidth(clip)) / 2
function onOverlayUpdate()
    videoDraw(clip, x, 16, false)
    return OVERLAY_UPDATED
end

2.48.11. videoIsPlaying

playing = videoIsPlaying(id)

Meldet, ob ein geladenes Video im Wiedergabezustand ist, also ob seit dem letzten videoPause videoPlay aufgerufen wurde. Auch ein laufendes Video rückt nur weiter, während es gezeichnet wird. Nach videoLoad beginnen Videos pausiert.

Rückgabe: Boolean.

Seit: 2.00 Siehe auch: videoPlay, videoPause, videoGetFrame

Beispiel
-- Eine Taste schaltet den Bild-im-Bild-Clip um.
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)

Öffnet eine Videodatei und gibt ihr Handle zurück. Jeder Container und jeder Codec, den das mitgelieferte FFmpeg dekodieren kann, wird angenommen. Die Engine erzeugt oder liest einen Frame-Index in einem Datenordner, der nach dem Ort des Videos unter Singes oberstem Datenordner benannt ist, das erste Laden einer großen Datei kann also einen Moment dauern; lässt sich dieser Ordner nicht anlegen, wird das Skript beendet. Das Video beginnt pausiert auf Frame 0, mit der Tonspur aus --audio oder dem Eintrag AUDIO_TRACK in games.dat (Standard 0), sofern die Datei so viele Spuren hat, und mit beiden Kanälen auf dem Pegel von --volume_nonvldp. Die Frames werden nach RGB dekodiert, damit sie auf das Overlay gezeichnet werden können.

Parameter:

  • filename — Pfad zur Videodatei, relativ zum Spieleverzeichnis oder innerhalb eines gepackten Spiels.

Rückgabe: ganzzahliges Video-Handle.

Seit: 2.00 Siehe auch: videoPlay, videoDraw, videoUnload

Beispiel
-- Den Attract-Clip des gewählten Spiels laden und auf den Anfang seiner Schleife setzen.
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)

Pausiert ein geladenes Video. Seine Uhr bleibt stehen, seine Tonspur pausiert, und videoDraw zeichnet weiter den Frame, auf dem es angehalten hat. Ein bereits pausiertes Video noch einmal zu pausieren schadet nicht.

Seit: 2.00 Siehe auch: videoPlay, videoIsPlaying

Beispiel
-- Den Attract-Clip anhalten, solange der Kalibrierungsbildschirm offen ist.
function calibrationBegin()
    calibrating = true
    if attractVideo then
        videoPause(attractVideo)
    end
end

2.48.14. videoPlay

videoPlay(id)

Startet ein geladenes Video ab seinem aktuellen Frame oder setzt es dort fort. Die Uhr wird bei diesem Frame neu gestartet, ein nach langer Pause fortgesetztes Video macht also dort weiter, wo es angehalten hat, statt nach vorn zu springen, und die Tonspur läuft mit ihm weiter. Das Video rückt nur weiter, während es mit videoDraw gezeichnet oder als Material verwendet wird.

Seit: 2.00 Siehe auch: videoPause, videoSeek, videoDraw

Beispiel
-- Das Briefing über der pausierten Disc starten.
function startBriefing()
    discPause()
    videoSeek(briefing, 0)
    videoPlay(briefing)
    briefingRunning = true
end

2.48.15. videoQuality

videoQuality(id, smooth)

Wählt die Filterung, die verwendet wird, wenn die Form von videoDraw mit vier Argumenten das Video skaliert oder dreht. Jeder Wert ungleich null wählt RENDER_SMOOTH (bilinear), null wählt RENDER_PIXELATED (Nearest-Neighbor), den Standard. Eine Änderung markiert den transformierten Frame für die Neuerzeugung beim nächsten Zeichnen. Sie wirkt weder auf die gestreckte Form mit fünf Argumenten, die immer Nearest-Neighbor verwendet, noch auf ein nicht transformiertes Video.

Parameter:

  • id — Video-Handle.

  • smooth — RENDER_PIXELATED (0) oder RENDER_SMOOTH (1).

Seit: 2.10 Siehe auch: videoScale, videoRotate, videoDraw

Beispiel
-- Ein fotografischer Clip, verkleinert in eine Ecke, sieht gefiltert besser aus.
pipVideo = videoLoad("videos/copilot.mkv")
videoScale(pipVideo, 0.4)
videoQuality(pipVideo, RENDER_SMOOTH)
videoPlay(pipVideo)

2.48.16. videoRotate

videoRotate(id, degrees)

Setzt die Drehung, die die Form von videoDraw mit vier Argumenten anwendet, in Grad im Uhrzeigersinn, nach derselben Konvention wie spriteRotate. Der Winkel wird modulo 360 reduziert und behält sein Vorzeichen, 450 und 90 sind also gleich, und -90 dreht eine Vierteldrehung gegen den Uhrzeigersinn. Der mit videoScale gesetzte Maßstab bleibt erhalten. Gedreht wird um die Mitte des Frames, zeichne gedrehte Videos also mit centered auf true. Ein geänderter Winkel markiert den transformierten Frame für die Neuerzeugung beim nächsten Zeichnen.

Parameter:

  • id — Video-Handle.

  • degrees — Drehung in Grad, im Uhrzeigersinn.

Seit: 2.10 Siehe auch: videoRotateAndScale, videoScale, videoDraw

Beispiel
-- Das Radarbild langsam drehen, während es läuft.
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)

Setzt Drehung und Maßstab in einem Aufruf, nach denselben Regeln wie videoRotate und videoScale: Grad im Uhrzeigersinn, modulo 360 reduziert, und Maßstabsfaktoren, die größer als 0 sein müssen. Verwende es, wenn sich beides in jedem Frame ändert, damit der transformierte Frame einmal statt zweimal neu erzeugt wird.

Parameter:

  • id — Video-Handle.

  • degrees — Drehung in Grad, im Uhrzeigersinn.

  • scale — einheitlicher Maßstabsfaktor, 1.0 für die native Größe.

  • scaleX, scaleY — getrennte waagerechte und senkrechte Faktoren.

Seit: 2.10 Siehe auch: videoRotate, videoScale, videoDraw

Beispiel
-- Ein Clip taumelt und schrumpft davon, während er weggeschickt wird.
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)

Setzt den Maßstab, den die Form von videoDraw mit vier Argumenten anwendet, als Faktor der nativen Größe; 1.0 ist unskaliert. Die mit videoRotate gesetzte Drehung bleibt erhalten. Ein geänderter Maßstab markiert den transformierten Frame für die Neuerzeugung beim nächsten Zeichnen. Faktoren von 0 oder weniger lassen sich nicht rendern und lassen die Engine beim nächsten videoDraw abbrechen, halte animierte Maßstäbe also über null. Die gestreckte Form von videoDraw mit fünf Argumenten ignoriert diese Einstellung.

Parameter:

  • id — Video-Handle.

  • scale — einheitlicher Maßstabsfaktor, größer als 0.

  • scaleX, scaleY — getrennte waagerechte und senkrechte Faktoren, jeder größer als 0.

Beispiel
-- Die Zwischensequenz in einem Viertel ihrer Größe in der Ecke zeigen, während das Spiel weiterläuft.
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)

Setzt ein geladenes Video auf frame und startet dort seine Uhr neu. Der Wiedergabe- oder Pausenzustand bleibt unverändert: ein laufendes Video macht beim nächsten Zeichnen ab dem neuen Frame weiter, ein pausiertes zeigt ihn. Die Frame-Nummer wird modulo der Anzahl der Frames umgebrochen, -1 ist also der letzte Frame, und ein Wert hinter dem Ende landet wieder innerhalb des Clips.

Parameter:

  • id — Video-Handle.

  • frame — Ziel-Frame, nullbasiert.

Seit: 2.00 Siehe auch: videoGetFrame, videoGetFrameCount, videoPlay

Beispiel
-- Den Attract-Clip zwischen den beiden Marken aus games.dat als Schleife spielen.
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)

Schaltet ein geladenes Video auf eine andere seiner Tonspuren um. Bereits eingereihtes Audio der alten Spur wird verworfen, und die Wiedergabe richtet sich neu aus, die Änderung ist also fast sofort zu hören. Die bereits verwendete Spur zu wählen tut nichts. Eine Spur außerhalb von 0 bis videoGetAudioTracks(id) - 1 beendet das Skript, was bei einem stummen Clip jeden beliebigen Wert bedeutet.

Parameter:

  • id — Video-Handle.

  • track — nullbasierter Index der Tonspur.

Beispiel
-- Das Menü speichert für den Attract-Clip jedes Spiels eine eigene Tonspur.
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)

Setzt die Stereolautstärke eines geladenen Videos als Prozentwerte. Die Werte werden kommentarlos auf 0 bis 100 begrenzt. Die Einstellung wird auch bei einem stummen Clip gemerkt und von videoGetVolume zurückgemeldet.

Mit einem Argument aufgerufen ist es eine Hypseus-Erweiterung, die stattdessen die eigene Lautstärke der Laserdisc setzt, auf der Skala 0 bis 64 von Hypseus statt als Prozentwert: das Gegenstück zum bloßen videoGetVolume(). Ein Pegel außerhalb von 0 bis 64 wird ignoriert, statt fatal zu sein, und genau das macht Hypseus mit einem solchen.

Parameter:

  • id — Video-Handle.

  • left, right — Kanallautstärken, 0 (stumm) bis 100 (voll).

  • volume — die Lautstärke der Laserdisc, 0 (stumm) bis 64 (voll).

Seit: 2.00 Siehe auch: videoGetVolume, discAudio

Beispiel
-- Den Ton der Zwischensequenz in weniger als einer halben Sekunde ausblenden, während die Steuerung zurückkehrt.
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)

Hält den Decoder an und gibt alles frei, was ein geladenes Video belegt: Decoder, Tonspur, zwischengespeicherte Frames und die transformierte Fläche. Das Handle ist danach ungültig, und es an irgendeine video*-Funktion zu übergeben beendet das Skript, leere also die Variable, die es enthielt. Videos, die beim Ende des Skripts noch geladen sind, gibt die Engine frei.

Parameter:

  • id — Video-Handle.

Seit: 2.00 Siehe auch: videoLoad, videoPause

Beispiel
-- Die Assets des gewählten Spiels verwerfen, bevor das nächste geladen wird.
function unloadGameAssets()
    if attractVideo then
        videoUnload(attractVideo)
        attractVideo = nil
    end
end

2.49. VLDP

Der Namensraum vldp* ist älter als Singe 2.00 und existiert, damit ältere Skripte weiterlaufen. vldpGetHeight und vldpGetWidth sind dieselben Bindungen wie discGetHeight und discGetWidth, vldpSetVerbose tut nichts, und vldpGetPixel ist das einzige Mitglied ohne modernes Gegenstück: Es liest ein Pixel des aktuellen Disc-Frames an Overlay-Koordinaten und ist immer noch der übliche Weg zur Treffererkennung auf vorab aufgenommenem Video. Ohne Disc gibt es Schwarz zurück (siehe Spiele ohne Disc).

Veraltet. Bevorzuge in neuem Code discGetHeight und discGetWidth. vldpGetPixel bleibt aktuell.

Hypseus Singe hat elf weitere Mitglieder hinzugefügt, die unter diesem Präfix bleiben, damit seine Spiele unverändert laufen: vldpFocusArea und vldpResetFocus beschneiden das Disc-Bild, vldpGetScale und vldpSetScale melden und ändern den Skalierungsfaktor der Anzeige, vldpGetRotate und vldpSetRotate tun dasselbe für die Drehung der Darstellung, vldpGetYUVPixel liest rohe Abtastwerte, und vldpFlash, vldpSetBlend, vldpSetLuma und vldpSetMonochrome ändern, wie das Bild selbst aussieht. Jedes ist unten mit „Hypseus-Erweiterung“ gekennzeichnet. Maßstab und Drehung sind zwei der Eingaben für Das Videorechteck.

Die vier Bildregler arbeiten auf dem dekodierten Frame, auf seinen Luma- und Chroma-Ebenen, bevor er den Bildschirm erreicht: vldpSetBlend und vldpSetLuma werden nacheinander angewendet, während jeder Frame hochgeladen wird, vldpSetMonochrome ersetzt das Chroma, und vldpFlash ersetzt das Bild für einen Frame vollständig. Sie kosten pro Frame einen Durchgang über die Luma-Ebene, solange sie eingeschaltet sind, und gar nichts, solange sie aus sind, sie lassen vldpGetPixel und vldpGetYUVPixel das Bild so lesen, wie es dekodiert wurde, und mit einer Frame-Datei folgen sie der Wiedergabe von Segment zu Segment. Alle vier gehen wieder aus, wenn das Skript neu geladen wird (außer Monochrom, das zu dem zurückkehrt, was --monochrome verlangt hat), und keiner von ihnen berührt ein mit videoDraw gezeichnetes Video.

2.49.1. vldpFlash

vldpFlash()

Hypseus-Erweiterung. Legt ein weißes Bild auf die Disc, so wie ein echter Laserdisc-Player aufblitzt, wenn er sucht. Es erscheint sofort, und die nächste Aktualisierung der Disc nimmt es wieder weg, es hält also einen gezeichneten Frame lang, ob die Disc läuft, pausiert oder gestoppt ist.

Das Weiß ist der Wert, mit dem Hypseus blitzt, 90 Prozent Luma mit neutralem Chroma, nicht reines Weiß, und genau das ist das Weiß eines Videosignals tatsächlich. Overlay, GUIs und das Bezel-Artwork werden wie üblich darübergezeichnet, ein Heads-up-Display bleibt also während des Blitzes lesbar.

Ohne Disc oder bei einer Disc, deren erster Frame noch nicht dekodiert wurde, tut der Aufruf nichts.

Parameter: keine.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: discSearch, vldpSetLuma

Beispiel
-- Einen Treffer unterstreichen.
vldpFlash()

2.49.2. vldpFocusArea

vldpFocusArea(x, y, width, height)
vldpFocusArea()

Hypseus-Erweiterung. Zeigt nur ein Rechteck des Disc-Frames, angegeben in Disc-Pixeln, gestreckt auf den Raum, den sonst der ganze Frame füllt, mit der üblichen weichen Skalierung des Renderers; das Seitenverhältnis folgt dem, was width und height ergeben. Das Rechteck wird innerhalb des Frames gehalten, und eines, das ganz außerhalb liegt, bricht das Skript ab. Ohne Argumente wird wieder der ganze Frame gezeigt (Hypseus ignoriert diesen Aufruf und verwendet vldpResetFocus; Singe nimmt beides an). Der Fokus ist nur ein Anzeigeeffekt: vldpGetPixel, vldpGetYUVPixel, die Mauszuordnung und die Disc auf einem 3D-Material behalten alle die ungezoomten Koordinaten, Treffererkennung auf einem gezoomten Bild muss der Aufrufer also selbst skalieren. Ohne Disc tut der Aufruf nichts. Wird zurückgesetzt, wenn das Skript neu geladen wird.

Parameter:

  • x, y — linke obere Ecke in Disc-Pixeln.

  • width, height — Größe des Rechtecks in Disc-Pixeln.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpResetFocus, vldpGetWidth, vldpGetPixel

Beispiel
-- Während der Verfolgungsjagd auf die mittleren 80 % des Bildes zoomen.
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()

Gibt die Höhe des Disc-Videos in Pixeln zurück oder ohne Disc die Höhe der Zeichenfläche. Das ist dieselbe Bindung wie discGetHeight, registriert unter ihrem Namen aus der Zeit vor 2.00.

Rückgabe: ganzzahlige Höhe in Pixeln.

Hinweise:

Veralteter Alias. Verwende discGetHeight in neuem Code.

Seit: 1.x Siehe auch: discGetHeight, vldpGetWidth

Beispiel
-- Ein 1.x-Skript, das sein Overlay nach der Disc bemisst.
overlaySetResolution(vldpGetWidth(), vldpGetHeight())
centerX = vldpGetWidth() / 2
centerY = vldpGetHeight() / 2

2.49.4. vldpGetPixel

r, g, b = vldpGetPixel(x, y)

Liest die Farbe eines Pixels des Disc-Frames, der gerade auf dem Bildschirm ist. Die Koordinaten sind Overlay-Koordinaten: Die Engine teilt sie durch den Maßstab von Overlay zu Video und schneidet die Nachkommastellen ab, du übergibst also dieselben Zahlen, mit denen du zeichnest. Gibt 0, 0, 0 zurück, wenn es keine Disc gibt, wenn noch kein Frame dekodiert wurde oder wenn die skalierten Koordinaten außerhalb des Videos liegen. Spiele, die es verwenden, markieren Ziele im Quellmaterial typischerweise mit einer markanten Farbe und prüfen beim Betätigen des Abzugs das Pixel unter dem Fadenkreuz, statt für jeden Frame Trefferzonen anzulegen.

Parameter:

  • x, y — Overlay-Koordinaten; Bruchwerte werden angenommen.

Rückgabe: drei Ganzzahlen, Rot, Grün und Blau, jeweils 0 bis 255.

Beispiel
-- Treffertest für die Lightgun:  Ziele sind auf Gegner-Frames in reinem Magenta gemalt.
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()

Hypseus-Erweiterung. Gibt die Drehung der Darstellung in Grad im Uhrzeigersinn zurück: die Option --rotate oder das, was vldpSetRotate zuletzt gesetzt hat, und 0, wenn keins von beiden. Zurückgegeben werden immer nur 0, 90, 180 und 270, denn das sind die einzigen Winkel, in die Singe dreht.

Rückgabe: Ganzzahl, 0, 90, 180 oder 270.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpSetRotate, vldpGetScale

Beispiel
-- Ein Automat im Hochformat will seine Punkteanzeige an der langen Seite.
if vldpGetRotate() == 90 or vldpGetRotate() == 270 then
    layoutPanel(PANEL_TALL)
else
    layoutPanel(PANEL_WIDE)
end

2.49.6. vldpGetScale

scale = vldpGetScale()

Hypseus-Erweiterung. Gibt den Skalierungsfaktor der Anzeige als Prozentwert zurück: die Option --scalefactor oder das, was vldpSetScale zuletzt angewendet hat, und 100, wenn keins von beiden angegeben wurde. Hypseus-Spiele teilen 100 durch ihn, um die Geometrie ihres Overlays an das verkleinerte Bild anzupassen. Er hat nichts mit vldpFocusArea oder der Overlay-Auflösung zu tun.

Rückgabe: Ganzzahl, 25 bis 100.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpSetScale, vldpFocusArea, overlayGetWidth

Beispiel
-- Hypseus-Spielcode:  die Visiere skalieren mit dem Bild.
if vldpGetScale ~= nil then
    gunScale = 100 / vldpGetScale()
else
    gunScale = 1
end

2.49.7. vldpGetShift

x, y = vldpGetShift()

Der Versatz des Bildes innerhalb des Fensters als Prozentwerte, die Optionen --shiftx und --shifty oder das, was vldpSetShift zuletzt angewendet hat, und 0, 0, wenn keins von beiden angegeben wurde. Im Extremfall füllt eine Verschiebung genau den Platz, den --scalefactor übrig gelassen hat, 100 bei einem Maßstab von 100 bewegt also nichts.

Rückgabe: zwei Ganzzahlen, jeweils -100 bis 100.

Seit: 3.00. Siehe auch: vldpSetShift, vldpGetScale

Beispiel
-- Melden, wohin der Betreiber das Bild gesetzt hat.
local x, y = vldpGetShift()
fontPrint(10, 10, string.format("shift %d, %d", x, y))

2.49.8. vldpGetWidth

width = vldpGetWidth()

Gibt die Breite des Disc-Videos in Pixeln zurück oder ohne Disc die Breite der Zeichenfläche. Das ist dieselbe Bindung wie discGetWidth, registriert unter ihrem Namen aus der Zeit vor 2.00.

Rückgabe: ganzzahlige Breite in Pixeln.

Hinweise:

Veralteter Alias. Verwende discGetWidth in neuem Code.

Seit: 1.x Siehe auch: discGetWidth, vldpGetHeight

Beispiel
-- Ein 1.x-Skript, das sein Overlay nach der Disc bemisst.
overlaySetResolution(vldpGetWidth(), vldpGetHeight())
centerX = vldpGetWidth() / 2
centerY = vldpGetHeight() / 2

2.49.9. vldpGetYUVPixel

y, u, v = vldpGetYUVPixel(x, y)

Hypseus-Erweiterung. Liest die rohen Abtastwerte eines Pixels des gerade gezeigten Disc-Frames, vor jeder Farbumrechnung: den Luma-Wert und die zwei Chroma-Werte, jeweils 0 bis 255, mit Chroma in der 4:2:0-Auflösung des dekodierten Bildes (neutral ist 128). Die Koordinaten sind Overlay-Koordinaten, skaliert und abgeschnitten genau wie bei vldpGetPixel. Gibt -1, -1, -1 zurück, wenn es keine Disc gibt, wenn noch kein Frame dekodiert wurde oder wenn die skalierten Koordinaten außerhalb des Videos liegen. Unbeeinflusst von vldpFocusArea und vldpSetMonochrome. Günstiger als vldpGetPixel, wenn nur die Helligkeit zählt.

Parameter:

  • x, y — Overlay-Koordinaten; Bruchwerte werden angenommen.

Rückgabe: drei Ganzzahlen, Y, U und V, jeweils 0 bis 255, oder -1, -1, -1.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpGetPixel, discGetFrame

Beispiel
-- Die Straße ist dunkel; alles Helle unter dem Auto ist ein Hindernis.
function carHitsSomething()
    local y = vldpGetYUVPixel(carX + carWidth / 2, carY + carHeight)
    return y >= 120
end

2.49.10. vldpResetFocus

vldpResetFocus()

Hypseus-Erweiterung. Zeigt nach vldpFocusArea wieder den ganzen Disc-Frame, genau wie vldpFocusArea() ohne Argumente. Der eigene Name von Hypseus für das Zurücksetzen, erhalten, damit seine Spiele unverändert laufen.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpFocusArea

Beispiel
function onChaseEnded()
    vldpResetFocus()
end

2.49.11. vldpSetBlend

vldpSetBlend(enabled)

Hypseus-Erweiterung. Glättet das Disc-Bild von Zeile zu Zeile: Jeder Luma-Wert wird zum Mittelwert aus sich selbst und den Werten direkt darüber und darunter. Das ist der eigene Drei-Tap-Blendfilter von Hypseus, und es gibt ihn, um einer Überspielung im Zeilensprungverfahren die harten Kanten zu nehmen, ohne das Bild seitlich weicher zu machen.

Die Chroma-Ebenen bleiben unberührt, die Glättung ändert also das Helligkeitsdetail und nicht die Farbe. Ausschalten bringt das Bild genau so zurück, wie es dekodiert wurde.

Ohne Disc tut der Aufruf nichts, wird aber trotzdem gemerkt, sodass er wirkt, wenn später eine Disc geladen wird. Ein Argument, das kein Boolean ist, beendet das Skript.

Parameter:

  • enabled — Boolean.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpSetLuma, vldpSetMonochrome

Beispiel
-- Ein Schalter im Service-Bildschirm für eine verrauschte Überspielung.
vldpSetBlend(SETTINGS.softenVideo)

2.49.12. vldpSetLuma

vldpSetLuma(enabled [, level])

Hypseus-Erweiterung. Macht das Disc-Bild heller oder dunkler. level reicht von 0 bis 8, und 4, der Standard, ändert nichts: Der Abstand zu 4 wird in Achteln zu jedem Luma-Wert addiert, 0 halbiert also die Helligkeit, 8 hebt sie um die Hälfte an, und die Stufen dazwischen sind gleichmäßig. Eine Stufe außerhalb von 0 bis 8 beendet das Skript.

Da nur das Luma geändert wird, bleibt die Farbe, wo sie ist: Eine höhere Stufe hellt das Bild auf, ohne die Farbe auszuwaschen, was der Bildregler eines echten Players tut und was ein Farbmultiplikator nicht täte. Ausschalten oder Stufe 4 bringt das Bild genau so zurück, wie es dekodiert wurde.

vldpSetLuma(true) ohne Stufe tut deshalb sichtbar nichts, und so verhält sich auch Hypseus.

Ohne Disc tut der Aufruf nichts, wird aber trotzdem gemerkt, sodass er wirkt, wenn später eine Disc geladen wird.

Parameter:

  • enabled — Boolean.

  • level — optionale Zahl; 0 bis 8, wobei 4 neutral ist. Standard 4.

Rückgabe: nichts.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpSetBlend, vldpSetMonochrome, vldpFlash

Beispiel
-- Eine Nachtszene, die der Spieler nicht erkennen kann; lass ihn sie aufhellen.
vldpSetLuma(true, 6)

2.49.13. vldpSetMonochrome

vldpSetMonochrome(enabled)

Hypseus-Erweiterung. Zeigt die Disc nur in Luma: Die Chroma-Ebenen werden beim Hochladen jedes Frames durch neutrale Werte ersetzt, eine pausierte Disc ändert sich also sofort. Mit einer Frame-Datei folgt die Einstellung der Wiedergabe von Segment zu Segment. vldpGetPixel und vldpGetYUVPixel geben weiterhin die Farbwerte zurück, und zusätzliche, mit videoDraw gezeichnete Videos sind nicht betroffen. Kombiniere es mit overlaySetMonochrome für einen Schwarzweißmodus. Ohne Disc tut der Aufruf nichts; wird zurückgesetzt, wenn das Skript neu geladen wird. Ein Argument, das kein Boolean ist, bricht das Skript ab.

Parameter:

  • enabled — Boolean.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: overlaySetMonochrome, vldpGetPixel

Beispiel
-- Ein DIP-Schalter wählt Farbe oder Schwarzweiß.
vldpSetMonochrome(not dipChroma)
overlaySetMonochrome(not dipChroma)

2.49.14. vldpSetRotate

applied = vldpSetRotate(degrees)

Hypseus-Erweiterung. Dreht die ganze Darstellung im Uhrzeigersinn: Disc, Overlay, GUIs, 3D-Szene und Partikel drehen sich alle zusammen, und Maus- und Lightgun-Positionen werden zurückgedreht, sodass ein Klick weiterhin dort landet, wo gezeichnet wird. Eine Vierteldrehung vertauscht die Form der dargestellten Fläche, sodass ein Hochformatfenster ausgefüllt wird, statt das Bild mit Letterbox in einen Streifen zu setzen.

Hypseus nimmt jeden Winkel von 0 bis 359 an; Singe nimmt nur 0, 90, 180 und 270 und antwortet auf alles andere mit false, statt das Skript zu beenden. Ein beliebiger Winkel ließe der Mauszuordnung und dem Sinden-Rahmen keine sinnvolle Bedeutung, und kein Spiel in der Hypseus-Bibliothek verlangt einen.

Die Drehung kostet ein bildschirmgroßes Renderziel und einen zusätzlichen Blit pro Frame, solange sie nicht null ist, und gar nichts, solange sie es ist. Wird beim Neuladen des Skripts auf den Wert von --rotate zurückgesetzt.

Parameter:

  • degrees — Ganzzahl, 0, 90, 180 oder 270.

Rückgabe: Boolean, true, wenn die Drehung angewendet wurde.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpGetRotate, vldpSetScale

Beispiel
-- Ein senkrechter Shooter-Abschnitt auf einem drehbaren Monitor.
if not vldpSetRotate(90) then
    debugPrint("This build will not turn the screen.")
end

2.49.15. vldpSetScale

applied = vldpSetScale(percent)

Hypseus-Erweiterung. Verkleinert das Bild um seine Mitte auf percent des Fensters, das Gegenstück zu --scalefactor zur Laufzeit, und baut das Videorechteck neu auf, sodass Disc, Overlay, GUIs, 3D-Szene, Partikel, ein etwaiger Sinden-Rahmen und die Mauszuordnung ihm alle folgen. Werte außerhalb von 25 bis 100 ergeben false und ändern nichts, statt das Skript zu beenden.

Änderungen sind auf eine alle 15 Millisekunden begrenzt, so wie Hypseus seinen eigenen Zoom bei gehaltener Taste begrenzt; ein Aufruf innerhalb dieses Zeitfensters ergibt false, ein Skript, das den Maßstab über eine gehaltene Taste steuert, sollte also weiter aufrufen, bis es greift. Wird beim Neuladen des Skripts auf den Wert von --scalefactor zurückgesetzt.

Parameter:

  • percent — Ganzzahl, 25 bis 100.

Rückgabe: Boolean, true, wenn der Maßstab angewendet wurde.

Seit: 3.00, als Erweiterung von Hypseus Singe. Siehe auch: vldpGetScale, vldpSetRotate

Beispiel
-- Bei jedem Druck des Spielers auf die Einstelltaste einen Schritt herauszoomen.
function onInputPressed(input)
    if input == SWITCH_BUTTON3 then
        vldpSetScale(vldpGetScale() - 5)
    end
end

2.49.16. vldpSetShift

vldpSetShift(x, y)

Verschiebt das Bild innerhalb des Fensters, das Gegenstück zu --shiftx und --shifty zur Laufzeit, und baut das Videorechteck neu auf, sodass Disc, Overlay, GUIs, 3D-Szene, Partikel, ein etwaiger Sinden-Rahmen und die Mauszuordnung ihm alle folgen. Die Werte sind Prozentwerte des Platzes, den --scalefactor übrig gelassen hat, bei einem Maßstab von 100 gibt es also nichts, wohin es sich bewegen könnte. Ein Wert außerhalb von -100 bis 100 beendet das Skript, anders als bei vldpSetScale, das false ergibt.

Parameter:

  • x — Ganzzahl, -100 bis 100.

  • y — Ganzzahl, -100 bis 100.

Rückgabe: nichts.

Seit: 3.00. Siehe auch: vldpGetShift, vldpSetScale, singeSaveGeometry

Beispiel
-- Das Bild bei jedem Druck des Betreibers auf die Taste ein Stück nach links schieben.
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(...)

Tut nichts. Früher schaltete es die Protokollierung im ursprünglichen Videoplayer um; der Aufruf nimmt beliebige Argumente an, schreibt eine Trace-Zeile und kehrt zurück. Das Tracing von Engine und Skript läuft jetzt über Befehlszeilenoptionen (--program und --trace).

Hinweise:

Nicht implementiert. Nur aus Gründen der Abwärtskompatibilität erhalten. Verwende --trace auf der Befehlszeile, um API-Aufrufe zu protokollieren.

Seit: 1.x Siehe auch: debugPrint, discGetState

Beispiel
-- Portierter 1.x-Startcode.  Der Aufruf wird ignoriert; starte Singe stattdessen mit --trace.
vldpSetVerbose(true)
overlaySetResolution(discGetWidth(), discGetHeight())
discSearch(TITLE_FRAME)

2.50. Stimme

Die Bausteine, aus denen ein Sprachchat gebaut wird, ohne das Netzwerk: Opus, um eine Stimme klein genug zum Senden zu machen und wieder zurück, ein Prozessor, der ein Mikrofon säubert, bevor gesendet wird, und ein Jitter-Buffer, der das, was spät und durcheinander ankommt, in der richtigen Reihenfolge abspielt. Die Pakete zu senden und die anderen Spieler zu finden ist Sache des Spiels selbst oder einer späteren Version von Singe.

Samples sind Strings aus 16-Bit-Werten, je zwei Bytes, Little Endian, so wie micRead sie liefert; bei zwei Kanälen wechseln sich links und rechts ab. Ein Frame ist ein festes Stück Zeit: 20 Millisekunden, 960 Samples bei 48000, ist das übliche für eine Stimme.

Jedes Objekt hier ist ein Handle. voiceFree gibt eines frei; alle werden freigegeben, wenn das Spiel endet.

Ein Mikrofon, gereinigt, kodiert und wieder dekodiert
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)    -- das ist es, was du sendest
			local heard  = opusDecode(decoder, packet)     -- und das spielt die andere Seite ab
		end
	end
	return OVERLAY_UPDATED
end

2.50.1. jitterGet

packet, status = jitterGet(jitter [, span])

Das Paket, das jetzt abgespielt werden soll, und der Buffer rückt um einen Schritt weiter. Ruf es einmal je Frame-Dauer auf, egal, was angekommen ist.

Parameter:

  • span — Zahl, die zu nehmenden Samples; ohne Angabe der Schritt.

Rückgabe: das Paket oder nil und ein Status: "ok", "missing" (nichts ist fällig: gib nil an opusDecode, um die Lücke zu füllen) oder "insertion" (der Buffer wächst, um verspätete Pakete aufzufangen: spiel ein wenig Stille ab).

Seit: 3.00.

2.50.2. jitterNew

jitter = jitterNew([step])

Ein Jitter-Buffer: Pakete gehen nach ihrem Zeitstempel hinein, wenn sie ankommen, und kommen der Reihe nach heraus, einen Schritt nach dem anderen, ein wenig verzögert, damit ein verspätetes es noch schafft.

Parameter:

  • step — Zahl, die Samples, um die jedes jitterGet weiterrückt; 960, sofern nicht angegeben.

Rückgabe: das Handle des Jitter-Buffers.

Seit: 3.00.

2.50.3. jitterPut

jitterPut(jitter, packet, timestamp [, span])

Ein Paket, das angekommen ist. Der Buffer behält seine eigene Kopie.

Parameter:

  • packet — String, 1 bis 4000 Bytes.

  • timestamp — Zahl, wo das Paket beginnt, in Samples: Der Sender zählt sie, 0, 960, 1920 und so weiter.

  • span — Zahl, die Samples, die das Paket abdeckt; der Schritt, sofern nicht angegeben.

Seit: 3.00.

2.50.4. opusDecode

samples = opusDecode(decoder, packet | nil)

Ein Paket zurück zu Samples. nil für ein Paket, das nie angekommen ist, bittet Opus, die Lücke mit etwas Plausiblem zu füllen, so lang wie das letzte Paket.

Rückgabe: die Samples.

Seit: 3.00.

2.50.5. opusDecoderNew

decoder = opusDecoderNew([rate [, channels]])

Parameter:

  • rate — Zahl: 8000, 12000, 16000, 24000 oder 48000; 48000, sofern nicht angegeben.

  • channels — Zahl, 1 oder 2; 1, sofern nicht angegeben.

Rückgabe: das Handle des Decoders.

Seit: 3.00.

2.50.6. opusEncode

packet = opusEncode(encoder, samples)

Ein Frame aus Samples als ein Paket. Ein Frame umfasst 2,5, 5, 10, 20, 40 oder 60 Millisekunden an Samples; alles andere wird abgelehnt.

Rückgabe: das Paket, ein String.

Seit: 3.00.

2.50.7. opusEncoderNew

encoder = opusEncoderNew([rate [, channels [, application]]])

Parameter:

  • rate — Zahl: 8000, 12000, 16000, 24000 oder 48000; 48000, sofern nicht angegeben.

  • channels — Zahl, 1 oder 2; 1, sofern nicht angegeben.

  • application — String: "voip" für Sprache, darauf abgestimmt, verstanden zu werden; "audio" für Musik; "lowdelay" für die geringste Verzögerung auf Kosten von etwas Qualität. "voip", sofern nicht angegeben.

Rückgabe: das Handle des Encoders.

Seit: 3.00.

2.50.8. opusEncoderSet

opusEncoderSet(encoder, bitrate [, complexity])

Parameter:

  • bitrate — Zahl, Bits pro Sekunde; 0 lässt sie, wie sie ist. Eine Stimme ist bei 16000 bis 24000 klar.

  • complexity — Zahl, 0 bis 10: wie viel Arbeit für Qualität aufgewendet wird.

Seit: 3.00.

2.50.9. voiceFree

voiceFree(handle)

Gibt einen Opus-Encoder oder -Decoder, einen Sprachprozessor oder einen Jitter-Buffer frei.

Seit: 3.00.

2.50.10. voiceProcess

cleaned, voiced = voiceProcess(processor, mic [, speaker])

Ein Frame vom Mikrofon, gereinigt: das Echo dessen, was die Lautsprecher spielten, herausgenommen, Hintergrundgeräusche unterdrückt und der Pegel ausgeglichen.

Parameter:

  • mic — String, ein Frame aus Samples vom Mikrofon.

  • speaker — String, derselbe Frame dessen, was die Lautsprecher gespielt haben, falls etwas: etwa die Stimmen der anderen Spieler. Dessen Echo wird herausgenommen.

Rückgabe: der gereinigte Frame und true, wenn er wie eine Stimme klingt — so sendet man nichts, solange niemand spricht.

Seit: 3.00.

2.50.11. voiceProcessorNew

processor = voiceProcessorNew([frame [, rate [, tailMs]]])

Parameter:

  • frame — Zahl, Samples pro Aufruf; 960, sofern nicht angegeben.

  • rate — Zahl; 48000, sofern nicht angegeben.

  • tailMs — Zahl, das längste Echo, das ausgelöscht wird, in Millisekunden: wie lange ein Klang im Raum nachhallt. 200, sofern nicht angegeben. Von 1 bis 2000.

Rückgabe: das Handle des Prozessors.

Seit: 3.00.

2.51. Hilfsfunktionen des Frameworks

Framework.singe definiert fünf kleine Hilfsfunktionen eigener Art, global wie der Rest der API, die Spiele für frühere Versionen benutzen. Neuer Code kann lume und inspect aus den mitgelieferten Bibliotheken vorziehen.

Funktion Was sie tut

utilDeepCopy(value)

Eine Kopie von value bis ganz nach unten: Eine Tabelle wird Schlüssel für Schlüssel kopiert, ihre Schlüssel, Werte und ihre Metatabelle ihrerseits kopiert; alles andere kommt unverändert zurück.

utilDump(value)

value als Text zum Ausgeben. Eine Tabelle wird zu { ["key"] = value,}, verschachtelte Tabellen in eigenen Klammern; alles andere geht durch tostring. Für eine Tabelle, die sich zu lesen lohnt, macht es require("inspect") besser.

utilGetTableSize(t)

Wie viele Schlüssel t enthält, alle, nicht nur die Folge, die #t misst.

utilOffsetTable(source, offset)

Eine tiefe Kopie einer Tabelle in der Form von SCANCODE, { NAME = { name = NAME, value = N } }, mit offset zu jedem value addiert.

utilTrim(s)

s ohne die Leerzeichen an beiden Enden.

2.52. Engine-Callbacks

Das sind Funktionen, die das Skript definiert und die Singe aufruft, wenn das passende Ereignis eintritt; alle sind optional, und eine nicht definierte wird übersprungen. Eingabe-Callbacks werden ausgelöst, während Ereignisse gelesen werden, onOverlayUpdate läuft höchstens einmal alle 15 Millisekunden, und keiner von ihnen läuft, solange die Pausentaste das Spiel eingefroren hält (siehe Pausieren). Ein Fehler in einem Callback beendet das Spiel mit einem Traceback. Im Thread-Modell übernimmt singeMain den Großteil der Logik pro Frame (siehe Thread-Modell): Die anderen Callbacks werden weiterhin ausgelöst, aber Framework.singe installiert sein eigenes onOverlayUpdate, um die Koroutine singeMain anzutreiben, ein Spiel im Thread-Modell definiert also singeMain, onShutdown und die Eingabe-Callbacks, die es haben will.

2.52.1. onControllerMoved

function onControllerMoved(axis, value, which)
end

Wird für jedes Achsenbewegungsereignis eines verbundenen Controllers aufgerufen, auch für Bewegung innerhalb der Totzone, ein Stick unter einem Daumen löst ihn also viele Male pro Sekunde aus. Richtungen jenseits von SINGE_DEAD_ZONE wirken außerdem als Schalter, wenn controls.cfg sie belegt, ein Spiel, das nur digitale Lenkung braucht, kann also GAMEPAD_0.AXIS_LEFT_X_L und GAMEPAD_0.AXIS_LEFT_X_R belegen und diesen Callback ignorieren. Der Wert wird für controllerGetAxis gespeichert, bevor der Callback läuft.

Parameter:

  • axis — 0 bis 5, entsprechend den Konstanten GAMEPAD_AXIS_*.

  • value — rohe Stellung, -32768 bis 32767; Trigger ruhen bei 0.

  • which — Controller-Index, 0 bis 3, der Index, den controllerGetAxis und die Tabellen GAMEPAD_N verwenden.

Beispiel
-- Analoge Lenkung nur über den linken Stick des ersten Controllers.
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

Wird aufgerufen, wenn eine logische Eingabe gedrückt oder losgelassen wird. Was ankommt, hängt vom Tastaturmodus ab. In MODE_NORMAL ist what ein SWITCH_*-Wert: Tasten, Controller-Knöpfe, Achsenrichtungen jenseits der Totzone, Mausknöpfe und das Mausrad kommen alle auf diesem Weg an, übersetzt durch controls.cfg, jeder Druck einmal und ohne Tastenwiederholung, und Eingaben, die keinem Schalter zugeordnet sind, werden ignoriert. SWITCH_PAUSE kommt nur nach singeSetPauseKeyEnabled(false) an; sonst friert die Engine das Spiel bei dieser Taste ein, und das Skript sieht sie nie. In MODE_FULL ist what das Keysym der Taste (der Zeichenwert, nicht der Scancode), Wiederholungen werden geliefert, und Controller- und Mausknöpfe übergeben 0; jedes Ereignis erreicht außerdem onKeyPressed und onKeyReleased, die den Scancode oder Knopfcode tragen. Wenn die Pausentaste das Spiel einfriert, wird zuerst jeder Schalter, den das Skript gedrückt hält, über onInputReleased losgelassen, und beim Auftauen wird alles, was noch tatsächlich gedrückt ist, erneut gedrückt, sodass ein Spiel nie einen veralteten Knopf sieht. Was in der ersten Sekunde nach dem Start des Skripts oder nachdem das Fenster den Fokus zurückerhalten hat, gedrückt wird, gilt als von vorher gehalten und wird samt seinem Loslassen verschluckt. Ein Schalter kommt von gar keinem Bedienelement: SWITCH_MOUSE_DISCONNECT wird von der Engine ausgelöst, wenn eine Maus oder Lightgun abgezogen wird, einmal als Druck und sofort danach einmal als Loslassen, sodass ein Lightgun-Spiel merkt, dass seine Lightgun weg ist (siehe Mäuse, Lightguns und wer entscheidet).

Beispiel
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

Wird nur in MODE_FULL aufgerufen, für jede Taste, die gedrückt oder losgelassen wird, mit dem logischen Keysym (dem Zeichen, das die Taste im aktuellen Layout erzeugt) und dem physischen Scancode (der Position der Taste, verglichen mit der Tabelle SCANCODE). Gehaltene Tasten wiederholen sich in diesem Modus, und genau das will eine Texteingabe. Controller- und Mausknöpfe kommen ebenfalls durch, mit keysym 0 und ihrem GAMEPAD_N- oder MOUSE_N-Code als scancode. Für Text verwende keysym; für Steuerungen, bei denen Tasten als Knöpfe dienen, verwende scancode, damit die Belegung auf jedem Layout gleich ist. Tastaturbelegungen der eigenen Schalter der Engine wirken in diesem Modus nicht, ein Spiel in MODE_FULL muss also seinen eigenen Ausweg bieten.

2.52.4. onTextInput

function onTextInput(text)
end

Wird nur in MODE_FULL aufgerufen, nachdem Umschaltzustand und Layout der Tastatur angewendet wurden, mit dem Text, den ein Tastendruck erzeugt hat — ein Zeichen oder ein paar, in UTF-8. So kommt ein Großbuchstabe, ein Anführungszeichen oder ein Buchstabe aus einem nicht englischen Layout so an, wie die Person ihn getippt hat. onKeyPressed liefert denselben Druck als sein Keysym ohne Umschaltung und seinen Scancode und ist der richtige für Tasten, die Befehle sind; dieser hier ist der richtige für Tasten, die Text sind. Eine GUI mit einem fokussierten Textfeld bekommt den Text zuerst, und das Skript hört nichts davon.

Seit: 3.00. Siehe auch: onKeyPressed, keyboardSetMode

Beispiel
-- Highscore-Initialen: Buchstaben als Text; Eingabetaste und Rücktaste nach 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

Wird für jede Nachricht aufgerufen, die auf dem MIDI-Eingangsport ankommt, den midiOpenInput geöffnet hat, einmal pro Nachricht, zusammen mit den übrigen Eingaben des Frames. Die drei Zahlen sind die Nachricht, wie ein Gerät sie sendet: status trägt die Art in seinen oberen vier Bits und den Kanal in seinen unteren vier, gezählt ab 0, eine Note auf dem ersten Kanal kommt also als 0x90 an. bytes ist die ganze Nachricht als String, was eine System-Exclusive-Nachricht braucht und woraus eine Nachricht, die länger als drei Bytes ist, gelesen werden muss.

Nachrichten, die ankommen, während kein Port offen ist, werden nicht eingereiht; nichts von vor dem Öffnen des Ports wird geliefert.

Parameter:

  • status — Zahl; das Statusbyte, 0x80 bis 0xFF.

  • data1 — Zahl; das erste Datenbyte oder 0, wenn die Nachricht keins hat.

  • data2 — Zahl; das zweite Datenbyte oder 0, wenn die Nachricht keins hat.

  • bytes — String; die ganze Nachricht, wie lang sie auch ist.

Seit: 3.00. Siehe auch: midiOpenInput, midiSend

Beispiel
-- Ein MIDI-Keyboard spielt das Spiel:  das mittlere C und darüber sind die vier Feuerknöpfe.
local MIDI_NOTE_ON = 0x90

function onMidiMessage(status, data1, data2, bytes)
    -- Die Art steht in den oberen vier Bits; der Kanal in den unteren vier wird hier ignoriert.
    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

Wird für jedes Mausbewegungsereignis aufgerufen, mit der Position und der Bewegung seit dem vorigen Ereignis in Overlay-Koordinaten. Im Modus MOUSE_SINGLE wird die Zeigerposition des Fensters in Overlay-Koordinaten umgerechnet, und which ist immer 0. Im Modus MOUSE_MANY wird die relative Bewegung jedes Geräts zu seiner eigenen Position aufsummiert, begrenzt auf den Videobereich, und which ist der Geräteindex; ein absolutes Gerät wie ein Grafiktablett meldet seine abgebildete Position mit xRelative und yRelative gleich 0. Die Position wird für mouseGetPosition gespeichert, bevor der Callback läuft, ein Spiel kann diesen Callback also ignorieren und stattdessen abfragen. Gezeichnet werden muss trotzdem erst in onOverlayUpdate: Behalte hier die letzte Position in globalen Variablen und zeichne den Cursor dort.

Parameter:

  • x, y — Position in Overlay-Koordinaten.

  • xRelative, yRelative — Bewegung seit dem vorigen Ereignis, in Overlay-Koordinaten.

  • which — Mausindex, 0 bis 3.

Beispiel
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

Wird nach einem Physikschritt einmal für jeden neuen Kontakt zwischen zwei Körpern aufgerufen, nie wieder für ein Paar, das in Berührung bleibt. Eine Kiste, die landet, ein Ball, der den Automaten trifft, das Auto des Spielers, das eine Wand streift. Kontakte mit Triggern melden sich stattdessen über onTrigger. Die Ereignisse eines Schritts werden danach gemeinsam geliefert, bevor der Frame gezeichnet wird.

Parameter:

  • nodeA, nodeB — die Knoten der beiden Körper.

  • x, y, z — wo sie sich berührt haben, in Welteinheiten.

  • speed — wie schnell sie aufeinandertrafen, in Welteinheiten pro Sekunde.

Seit: 3.00. Siehe auch: onTrigger, bodyNew

Beispiel
-- Harte Landungen machen dort Lärm, wo sie passieren.
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

Wird aufgerufen, wenn ein Körper einen mit bodySetTrigger gemachten Trigger betritt oder verlässt, einmal auf dem Weg hinein und einmal auf dem Weg hinaus, unabhängig von den beteiligten Formen (ein Mesh oder eine zusammengesetzte Form, die an mehreren Stellen berührt, zählt trotzdem als ein Körper). Trigger schieben nie etwas, das hier ist also der Weg, zu bemerken, dass ein Körper eine Tür durchquert, einen Checkpoint erreicht oder in eine Todeszone fällt.

Parameter:

  • trigger — der Knoten des Trigger-Körpers.

  • other — der Knoten, der ihn betreten oder verlassen hat.

  • entered — true auf dem Weg hinein, false auf dem Weg hinaus.

Seit: 3.00. Siehe auch: bodySetTrigger, onCollision

Beispiel
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

Wird aufgerufen, wenn ein Navigationsagent das Ziel erreicht, das navAgentMoveTo ihm gegeben hat, einmal pro Ankunft, nach der Navigationsaktualisierung des Frames. Schick den Agenten woandershin oder spiel seine Leerlaufanimation ab. Ein Skript, das lieber abfragt, kann stattdessen navAgentIsArrived aufrufen.

Parameter:

  • agent — das Handle aus navAgentNew.

Seit: 3.00. Siehe auch: navAgentMoveTo, navAgentIsArrived

Beispiel
-- Endlos zwischen Wegpunkten patrouillieren.
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

Der eine Callback, in dem Zeichnen erlaubt ist. Singe ruft ihn höchstens einmal alle 15 Millisekunden auf, solange das Spiel nicht eingefroren ist, gezählt ab dem Beginn des vorigen Aufrufs, die Zeit, die das Skript selbst braucht, fällt also in diese 15 Millisekunden, statt zu ihnen hinzuzukommen; jeder anderswo gemachte Aufruf von overlay*, spriteDraw, videoDraw, fontPrint oder Ähnlichem erscheint nicht auf dem Bildschirm und kann das Overlay beschädigen. Gib OVERLAY_UPDATED (1) zurück, wenn sich das Overlay geändert hat, damit Singe es erneut über das Video legt, oder OVERLAY_NOT_UPDATED (0), wenn sich nichts geändert hat, damit das vorige Gesamtbild wiederverwendet wird; gar nichts zurückzugeben zählt als OVERLAY_NOT_UPDATED. Die Anzeige wird ohnehin neu gezeichnet, sobald ein neuer Video-Frame ankommt oder eine 3D-Szene eingeschaltet ist, der Rückgabewert ist also eine Optimierung für statische Bildschirme. Nachdem er zurückgekehrt ist, löscht die Engine die Werte hinter keyboardGetLastDown und keyboardGetLastUp. Im Thread-Modell definiert Framework.singe diese Funktion selbst, um singeMain fortzusetzen, und gibt immer OVERLAY_UPDATED zurück; definiere sie nicht zusätzlich.

Rückgabe: OVERLAY_UPDATED oder OVERLAY_NOT_UPDATED.

Beispiel
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

Wird einmal aufgerufen, wenn das Skript endet, ob durch singeQuit, den Beenden-Schalter, das Schließen des Fensters, scriptExecute oder scriptPush, nach dem letzten Frame und bevor der Lua-Zustand verworfen wird. singeReload ruft ihn nicht auf. Speichere hier Einstellungen und gib die Sprites, Sounds, Schriftarten und Videos frei, die das Skript geladen hat; die Engine stoppt danach jeden Sound und gibt frei, was übrig ist, ein vergessenes Handle ist also kein Leck, aber ausdrückliches Entladen behält die Reihenfolge beim Herunterfahren unter der Kontrolle des Skripts. Ruf von hier aus nicht singeQuit auf.

Beispiel
function onShutdown()
    saveHighScores()
    spriteUnload(reticle)
    fontUnload(hudFont)
    soundUnload(shotClip)
    soundUnload(coinClip)
end

2.52.12. onSoundCompleted

function onSoundCompleted(channel)
end

Wird jedes Mal mit der Kanalnummer aufgerufen, wenn ein Kanal stoppt: wenn sein Clip endet, wenn die letzte Schleife fertig ist und wenn soundStop oder soundFullStop ihn anhält, ein Skript, das von hier aus Sounds verkettet, sollte also wissen, welche Kanäle es selbst gestoppt hat. Der Mixer bemerkt den Stopp auf seinem eigenen Thread, und die Engine liefert den Callback zwischen den Frames auf dem Spiel-Thread; solange die Pausentaste das Spiel eingefroren hält, warten die Meldungen, und sie werden verworfen, wenn ein Skript endet oder neu geladen wird. Bis zu 64 Abschlüsse werden zwischen den Frames eingereiht; was in einem Frame darüber hinausgeht, geht verloren.

Parameter:

  • channel — die Kanalnummer, die der Aufruf soundPlay zurückgegeben hat.

Beispiel
-- Die Musik-Playlist der Reihe nach abspielen, für immer.
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

Der Einstiegspunkt des Thread-Modells. Definiert ein Skript sie, verpackt Framework.singe sie in eine Koroutine und installiert ein onOverlayUpdate, das die Koroutine einmal pro Frame fortsetzt, sodass die Funktion als gerade Linie aus Spiellogik läuft, die singeYield() (ein Alias von coroutine.yield) aufruft, wo immer sie einen Frame vergehen lassen will. Alles, was vor einem Yield gezeichnet wird, landet im Overlay dieses Frames. Die Rückkehr aus singeMain ruft singeQuit auf; ein Fehler darin beendet das Spiel mit einem Traceback. Die Callbacks für Eingabe, Sound, Physik und Navigation werden zwischen den Fortsetzungen weiterhin ausgelöst, ein Spiel im Thread-Modell kann sie also mit Abfragen mischen.

Beispiel
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. Hypseus-Kompatibilität

Alles in diesem Abschnitt existiert, damit ein für Hypseus Singe geschriebenes Spiel unverändert läuft. Nichts davon wird für ein neues Spiel empfohlen. Bevorzuge den Singe-Aufruf, den jeder Eintrag nennt: Er ist der, der weiter Funktionen dazugewinnt, und er schleppt nicht die Maßstäbe, Argumentreihenfolgen oder festen Antworten einer anderen Engine mit.

Hypseus Singe registriert in seiner Engine einige Namen, die Singe stattdessen aus Singe/Framework.singe beantwortet, damit ein für Hypseus geschriebenes Spiel unverändert läuft. Jeder wird nur definiert, wenn die Engine ihn nicht schon bereitstellt, eine künftige Umsetzung in der Engine gewinnt also. keyboardCatchQuit ist unter Tastatur dokumentiert; setOverlayLinearScale und setOverlayOnTop sind echte Engine-Aufrufe unter Overlay; mainBezelLoaded und die sieben scoreBezel-Aufrufe sind echte Engine-Aufrufe unter Bezel; getFValue, ratioGetX und ratioGetY sind echte Engine-Aufrufe unter Befehlszeile; joyMouseEnable ist ein echter Engine-Aufruf unter Joystick; allowSocketCall und getUserString sind echte Engine-Aufrufe unter Singe, und drawTransparent unter Sprite; und die ganze Familie music ist jetzt ein Satz echter Engine-Aufrufe unter Musik. Die sechs spriteAnim-Namen unten sind einfache Aliase, gesetzt nach dem Umhüllen der veralteten Sprite-Aufrufe, sie nehmen also die Argumentreihenfolge, die auch der Rest der Sprite-Familie nimmt: die von Hypseus (Handle zuletzt) unter LEGACY_SPRITE_ARGS und die von Singe 3.00 (Handle zuerst) ohne es.

Funktion Von Framework.singe bereitgestellt als

setOverlaySize(preset [, width, height])

overlaySetResolution mit einer gewählten Größe: 1 ist die Videogröße der Disc, 3 ist 360x240, 4 ist die angegebene Größe (ignoriert, wenn sie fehlt, wie in Hypseus), und alles andere, 2 eingeschlossen, ist die halbe Disc auf beiden Achsen. Ohne Disc melden discGetWidth und discGetHeight die Zeichenfläche, und in diese zeichnet ein Spiel ohne Disc.

setOverlayResolution(width, height)

Ein Alias von overlaySetResolution. Hypseus registriert eine Funktion unter beiden Namen.

rewriteStatus()

Stub, der false zurückgibt. In Hypseus meldet er, ob Asset-Pfade für eine Installation mit -espath umgeschrieben werden; das virtuelle Dateisystem von Singe findet die Dateien eines Spiels dort, wo sie installiert wurden, es wird also nichts umgeschrieben, und das Spiel behält seinen eigenen Asset-Ordner.

hypseusGetHeight()

Ein Alias von singeGetHeight.

hypseusGetWidth()

Ein Alias von singeGetWidth.

takeScreenshot()

Ein Alias von singeScreenshot. Hypseus verweigert einen zweiten Screenshot innerhalb von fünf Sekunden; Singe hat keine solche Drosselung.

mouseHowManyReal()

Ein Alias von mouseHowMany. Hypseus zählt echte Mäuse getrennt von denen, die es aus einem Gamepad ableitet; Singe hat keine abgeleiteten Mäuse, seine Zahl ist also schon die echte.

spriteAnimGetFrame(spr)

Ein Alias von spriteGetFrame.

spriteAnimIsPlaying(spr)

Ein Alias von spriteIsPlaying.

spriteAnimLoop(loop, spr)

Ein Alias von spriteLoop.

spriteAnimPause(spr)

Ein Alias von spritePause.

spriteAnimPlay(spr)

Ein Alias von spritePlay.

spriteAnimSetFrame(frame, spr)

Ein Alias von spriteSetFrame.

2.54. Nicht implementiert und veraltet

Eine Handvoll API-Funktionen wird zur Kompatibilität auf Skriptebene beibehalten, und die mit „Tut nichts“ markierten tun nichts. Sie lassen sich gefahrlos aufrufen; sie schreiben einfach eine Trace-Meldung und kehren zurück. Bevorzuge für neuen Code die aufgeführten Ersatzfunktionen.

Funktion Status Ersatz

discChangeSpeed

Tut nichts

 — (war für Wiedergabe mit variabler Geschwindigkeit auf echter LD-Hardware)

discSearchBlanking

Tut nichts

 — (war das Austasten des Bildschirms während eines Sprungs auf echter LD-Hardware)

discSkipBlanking

Tut nichts

 — (derselbe Grund)

discSetFPS

Tut nichts

Die Bildrate wird aus der Videodatei gelesen.

vldpGetHeight

Funktioniert

discGetHeight

vldpGetWidth

Funktioniert

discGetWidth

vldpSetVerbose

Tut nichts

 — 

colorBackground(r,g,b)

Funktioniert

Bevorzuge die Form mit 4 Argumenten, colorBackground(r, g, b, a).

colorForeground(r,g,b)

Funktioniert

Bevorzuge die Form mit 4 Argumenten, colorForeground(r, g, b, a).

daphneGetWidth / daphneGetHeight / daphneScreenshot

Aliase in Framework.singe

Bevorzuge die singe*-Entsprechungen.

discPauseAtFrame

Funktioniert (Alias)

discSearch.

Außerdem bindet Framework.singe random = { new = math.random } neu, damit Skripte aus der Zeit vor 2.00, die random.new() verwenden, weiterhin funktionieren. Neuer Code sollte direkt math.random verwenden.