Bevor du anfängst

Dieses Buch bringt dir das Programmieren bei. Es geht davon aus, dass du in deinem Leben noch keine Zeile Code geschrieben hast, und es geht nicht davon aus, dass du Programmierer werden willst — nur, dass du ein Spiel machen willst.

Jede Lektion endet mit etwas, das du starten und mit dem du spielen kannst. Nichts wird für später aufgehoben: Es gibt keine Theoriekapitel, bevor das erste Bild auf dem Bildschirm erscheint. Dein erstes funktionierendes Programm schreibst du in etwa zehn Minuten, und es wird fünf Zeilen lang sein.

Singe ist eine Spiel-Engine. Du kannst damit alles machen, was du mit jeder anderen Engine machen kannst, in zwei Dimensionen oder in drei, und der größte Teil dieses Buchs handelt genau davon. Was es abhebt, ist, dass es außerdem FMV-Video („Full Motion Video“) als die Welt abspielen kann, in der das Spiel stattfindet; so funktionierten die Laserdisc-Spiele der Spielhallen, und das kann fast nichts anderes gut. Das ist eine Fähigkeit, keine Pflicht: Ein Spiel spielt nur dann Video ab, wenn es darum bittet, und nichts, was du in den ersten dreizehn Lektionen schreibst, kommt auch nur in die Nähe davon.

Die Sprache ist Lua, die Singe für alles benutzt. Lua wurde von Leuten gewählt, die sie Künstlern und Designern beibringen mussten, und das merkt man. Es gibt keine Semikolons, die man vergessen kann, keine Typen, die man deklarieren muss, und keinen Compiler, mit dem man kämpfen muss. Wenn du einen Fehler machst, sagt dir Singe die Datei, die Zeile und was es nicht verstanden hat.

Was du brauchst

  • Singe. Eine Datei. Leg sie in einen Ordner, den du wiederfindest.

  • Einen Texteditor. Editor, TextEdit im Modus für reinen Text, Notepad++, VS Code oder irgendetwas anderes, das reinen Text speichert. Eine Textverarbeitung geht nicht: Sie speichert Formatierungen, die du nicht siehst, und Singe kann das nicht lesen.

  • Sonst nichts. Du brauchst keine Laserdisc, keine Videodatei, kein Zeichenprogramm und keine Grafiken. Der ganze erste Teil zeichnet alles selbst, und ab dem zweiten Teil kommen die Bilder, die Sounds, das Video und die Modelle, die du brauchst, alle mit dem Buch oder mit der Engine. Was du brauchst, steht weiter unten.

Wie du dieses Buch liest

Tipp den Code ab. Kopier ihn nicht und füg ihn nicht ein. Abtippen ist langsamer, und genau darum geht es: Du wirst kleine Fehler machen, und indem du sie behebst, lernst du zu lesen, was der Computer dir sagt. Jede Lektion hat einen Abschnitt Probier es aus mit Änderungen, die du machen sollst, und die sind so wichtig wie die Lektion.

Wenn eine Lektion schiefgeht und du nicht siehst, warum, liegt das fertige Skript jeder Lektion im Ordner learn, der mit diesem Buch kommt, benannt nach seiner Lektion: 01-hello.singe und so weiter. Lies es erst, nachdem du es selbst versucht hast.

Wie deine Ordner aufgebaut sind

Lektion eins richtet das ein, und jede spätere Lektion setzt es voraus, also lohnt es sich, es jetzt einmal zu sehen.

Du hast einen Arbeitsordner, in dem deine Kopie von Singe liegt. Jede Lektion legt darin einen neuen Ordner an, benannt nach dem Skript, das darin liegt.

singe/                 <- dein Arbeitsordner, mit Singe darin
    Singe/             <- hier legt die Engine ihre eigenen Dateien ab
    data/              <- und alles, was deine Spiele speichern
    hello/
        hello.singe
    rocks/
        rocks.singe
        art/

Du startest eine Lektion aus dem Arbeitsordner, indem du ihren Ordner nennst, also startet Singe rocks die Datei rocks/rocks.singe. Diese Kurzform funktioniert, weil Ordner und Skript denselben Namen haben. Das ist dieselbe Form, die ein echtes installiertes Spiel hat, und darum benutzt das Buch sie ab der ersten Lektion, statt später aufzuräumen.

Was zu diesem Buch gehört

Ab dem zweiten Teil benutzen die Lektionen Bilder und Sounds. Sie liegen im Ordner art, der mit dem Buch kommt, und du kopierst diesen Ordner in den Lektionsordner, in dem du gerade arbeitest, und behältst den Namen bei. Es gibt ein Raumschiff, einen Felsen, einen Schuss, einen Stern, vier Frames von jemandem, der läuft, und zwei Geräusche. art/README.txt listet sie mit ihren Größen auf.

Den Rest liefert Singe selbst. Wenn du zum ersten Mal irgendetwas startest, entpackt die Engine einen Ordner namens Singe in deinen Arbeitsordner, und darin sind ein Video, eine Schriftart, zwei 3D-Modelle und ein Klick. Die Lektionen, die diese brauchen, benutzen die, die schon auf deiner Festplatte liegen, also musst du nichts suchen und nichts kaufen. Nichts davon ist hübsch. Alles davon ist echt, und etwas Besseres einzusetzen ist meist nur ein geänderter Dateiname.

Dies ist nicht das Forge-Buch

Forge, ein eigenes Werkzeug mit einem eigenen Buch, macht ein Spiel, indem man es beschreibt, statt es zu programmieren. Das ist ein anderer Weg an einen anderen Ort, für jemanden, der überhaupt keinen Code schreiben will. Wenn du hierhergekommen bist, um programmieren zu lernen, bist du hier richtig. Du brauchst weder Forge noch sein Buch, und dieses Buch baut nicht darauf auf.

Die Singe-Referenz ist das Nachschlagewerk: jede Funktion, jedes Argument, jeder Rückgabewert und das Programmiermodell dahinter. Sie ist kein Tutorial und versucht nicht, eines zu sein. Ungefähr ab Lektion sechs wirst du anfangen, zu ihr zu greifen, und am Ende dieses Buchs wirst du sie mehr benutzen als dieses Buch. Sie kommt im selben Download wie dieses hier.

Die Reihe

Einunddreißig Lektionen in vier Teilen. Jede braucht die vorige und sonst nichts.

Teil eins: Die Ideen. Keine Grafiken, kein Video, nichts zu installieren. Du zeichnest mit den Formen und dem Text, die die Engine schon hat, und lernst, woraus ein Programm besteht.

  1. Hallo — ein Skript, eine Funktion, ein String und etwas auf dem Bildschirm.

  2. Zahlen, die sich ändern — Variablen, Rechnen und Bewegung hineinbringen.

  3. Entscheidungen treffen — if, Vergleiche und die Steuerung abfragen.

  4. Noch einmal — for und while, und hundert Stück von etwas zeichnen.

  5. Deine eigenen Funktionen — Argumente, Rückgabewerte und warum du dir die Mühe machen solltest.

  6. Listen von Dingen — Tabellen, ipairs, Hinzufügen und Entfernen.

  7. Ein Spiel — alles bisher, spielbar, in etwa hundertzwanzig Zeilen.

  8. Wenn etwas schiefgeht — Fehlermeldungen lesen, debugPrint und Neuladen mit F5.

Teil zwei: Ein echtes Spiel. Grafiken, Sound und die Form, die ein fertiges Spiel annimmt.

  1. Bilder — Sprites, Laden, Zeichnen und Frames.

  2. Sound — Effekte, Musik und wann man was lädt.

  3. Dinge treffen — Kollision, das Spiele-Kit und Hitboxen.

  4. Punkte, Leben und Game Over — Zustand, Speichern und Neustarten.

  5. Ein Spielordner — games.dat, Grafiken für das Menü und Starten daraus.

Teil drei: Video. Film als die Welt des Spiels abspielen, und die Arcade-Konventionen, die darum herum entstanden sind. Überspring diesen Teil, wenn dein Spiel kein Video will; nichts danach hängt von diesem Teil ab.

  1. Video abspielen — die Disc, Frames, Springen und Warten.

  2. Die andere Schreibweise — das Thread-Modell und warum es zu Video passt.

  3. Verzweigungen — Entscheidungen, Pfade und die Form eines verzweigten Videospiels.

  4. Lightguns — Zielen, Schießen und die Kalibrierung, die ein Automat braucht.

  5. Quick-Time-Events — Aufforderungen, Zeitfenster und die Reaktionszeit des Spielers bewerten.

Teil vier: Alles andere. Jede Lektion steht für sich; nimm sie in beliebiger Reihenfolge.

  1. Text, der gut aussieht — Schriftarten, Qualität und Ausmessen.

  2. Menüs und Bildschirme — die GUI, Dokumente und Gestaltung.

  3. Untertitel — und warum sie ein eigenes System sind.

  4. Hinein in 3D — Szenen, Kameras und Koordinaten.

  5. Modelle und Licht — glTF, Materialien und Animation.

  6. Physik — Körper, Kräfte, Gelenke und wann man sie nicht benutzt.

  7. Partikel — Emitter und eine Explosion bauen.

  8. Figuren, die sich selbst bewegen — Navigation und Wegfindung.

  9. Musik und MIDI — Spuren, SoundFonts und Instrumente.

  10. Online — Konten, Highscore-Tabellen und der Katalog.

  11. Daten aufbewahren — Datenbanken, Tabellen und die Fragen, die du ihnen stellst.

  12. Ausliefern — Packen, Patchen, Lizenzen und die Veröffentlichung.

  13. Im Automaten — Steuerung, Service-Menüs, Bezels und die Dinge, die nur auf echter Hardware zählen.

Lektion 1: Hallo

Die fertige Lektion

Das hast du am Ende dieser Lektion. Viel her macht es nicht. Es ist aber auch ein Programm, das du geschrieben hast, und es läuft auf einer echten Spiel-Engine, und alles andere in diesem Buch baut auf den fünf Zeilen auf, die es gemacht haben.

Richte deinen Arbeitsordner ein

Leg einen Ordner an, in dem du alles aufbewahrst, mit dem Namen singe oder wie du willst, und leg deine Kopie von Singe hinein. Das ist dein Arbeitsordner, und jede Lektion in diesem Buch legt darin einen neuen Ordner an. Du legst ihn einmal an und denkst nie wieder darüber nach.

Leg im Arbeitsordner einen Ordner namens hello an und darin eine Datei namens hello.singe.

singe/                 <- dein Arbeitsordner, mit Singe darin
    hello/
        hello.singe

Diese Verschachtelung ist keine Pedanterie. Singe behandelt den Ordner, aus dem du es startest, als den Ort, an dem die Spiele wohnen, ein Ordner pro Spiel, und es legt dort auch seine eigenen Dateien ab. Dein Spiel kommt in einen eigenen Ordner, eine Ebene tiefer. Ab Lektion zwei ist jede Lektion ein weiterer Ordner neben hello.

Zwei Dinge zu den Namen. Am Teil nach dem Punkt, .singe, erkennt Singe, dass das ein Skript ist. Und auf den meisten Computern, die nicht Windows sind, zählen Großbuchstaben: Hello.singe und hello.singe sind zwei verschiedene Dateien. Gewöhn dir gleich jetzt an, Namen genau so zu tippen, wie sie sind.

Dass Ordner und Skript denselben Namen haben, ist ebenfalls wichtig, und gleich siehst du, warum.

Öffne hello.singe in deinem Texteditor. Die Datei ist leer. Das ist richtig.

Tipp das ein

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

Speichere die Datei.

Mach dir noch keine Gedanken darüber, was das alles bedeutet. Zwei Dinge solltest du bemerken, bevor du es startest, denn sie gelten für jedes Programm, das du je schreiben wirst.

Das erste: Die Leerzeichen am Anfang der mittleren drei Zeilen sind mit Absicht da. Am Programm ändern sie überhaupt nichts — Singe würde es ohne sie genauso ausführen. Aber sie zeigen dir auf einen Blick, dass diese drei Zeilen in das Ding gehören, das mit function anfängt und mit end aufhört. Das macht jeder Programmierer. Mach es vom ersten Tag an, dann musst du es später nie lernen.

Das zweite ist die Reihenfolge der Zeilen. Sie passieren von oben nach unten, eine nach der anderen, wie die Schritte eines Rezepts. Das ist das Allerwichtigste an einem Programm, und fast alles, was Anfänger verwirrt, kommt daher, dass sie es vergessen.

Starte es

Öffne ein Terminal, geh in deinen Arbeitsordner — nicht in den Ordner hello darin — und nenne den Ordner, den du starten willst:

Singe hello

Unter Windows ist das Singe.exe hello. Wenn deine Kopie von Singe woanders liegt, tipp den Pfad dorthin, etwa ../Singe hello.

Darum haben Ordner und Skript denselben Namen. Bekommt Singe einen Ordner, sucht es darin nach einem Skript, das genauso heißt. Nennst du sie verschieden, bekommst du Error: Unable to locate the game., und damit sagt die Engine, dass sie nachgesehen und nichts gefunden hat, was sie kennt. Du kannst stattdessen auch immer alles ausschreiben, Singe hello/hello.singe, und das tut dasselbe.

Ein schwarzes Fenster geht auf, mit dem Wort Hello! nahe der linken oberen Ecke. Drück Esc oder Q, um es zu beenden.

Zwei Dinge sind passiert, um die du nicht gebeten hast, und beide sind normal. In deinem Arbeitsordner sind neben hello Ordner namens Singe und data aufgetaucht: Im ersten entpackt die Engine die Dateien, die sie braucht, im zweiten landet alles, was deine Spiele speichern. Lass beide in Ruhe. Und das Fenster ist größtenteils schwarz, weil du außer sechs Zeichen nichts gezeichnet hast.

Was gerade passiert ist

Jetzt die fünf Zeilen, eine nach der anderen.

function onOverlayUpdate()

function beginnt eine Gruppe von Anweisungen und gibt ihr einen Namen. Alles von hier bis zum passenden end gehört dazu. Diese hier heißt onOverlayUpdate, und die leeren Klammern nach dem Namen ergeben in Lektion fünf einen Sinn.

Diesen Namen suchst du dir nicht aus. Singe sucht eine Funktion mit genau diesem Namen und ruft sie etwa sechzigmal pro Sekunde auf, für immer, damit du Gelegenheit zum Zeichnen hast. Schreibst du sie onoverlayupdate oder onOverlayUpdated, findet Singe sie nicht, dein Fenster bleibt schwarz, und nichts sagt dir, dass du einen Fehler gemacht hast. Das ist die erste echte Lektion: Der Computer tut, was du geschrieben hast, nicht, was du gemeint hast.

Eine Funktion, die du schreibst und die die Engine aufruft, ist ein Callback. Du rufst ihn nicht selbst auf, und du kannst nicht bestimmen, wann er läuft; du schreibst ihn, und Singe ruft dich zurück, wenn es etwas zu tun gibt. Jeder Name in diesem Buch, der mit on anfängt, ist ein Callback, und es gibt einen für fast alles, was passieren kann: ein gedrückter Knopf, eine getippte Taste, ein Sound, der zu Ende ist, die Disc, die einen Frame erreicht. onOverlayUpdate ist der fürs Zeichnen, und er ist der einzige Ort, an dem gezeichnet werden darf.

    overlayClear()

Das ist auch eine Funktion, aber keine, die du schreiben musst: Singe stellt sie bereit, zusammen mit mehreren hundert anderen, und du rufst sie auf. Eine Funktion aufrufen heißt, ihren Namen hinzuschreiben, gefolgt von Klammern. Diese hier wischt den Bildschirm sauber.

Sie kommt zuerst, weil Zeichnen nicht ersetzt, was vorher da war, sondern darüber zeichnet. Erst löschen, dann zeichnen, jedes Mal.

    overlayPrint(2, 2, "Hello!")

Noch ein Aufruf, und diesem muss man drei Dinge sagen, die durch Kommas getrennt in die Klammern kommen. Dinge, die du einer Funktion so übergibst, heißen Argumente.

Die ersten beiden sind Zahlen: wie weit nach rechts und wie weit nach unten. Das dritte ist der Text, der ausgegeben werden soll, und er steht in doppelten Anführungszeichen, weil du dem Computer so sagst, dass Hello! ein Stück Text ist und nicht der Name von irgendetwas. Text in Anführungszeichen heißt String, und du wirst ständig Strings benutzen.

Früher oder später willst du ein doppeltes Anführungszeichen in einem String haben, und der naheliegende Weg funktioniert nicht: Das zweite Anführungszeichen beendet den String zu früh, und du bekommst denselben Fehler unfinished string, den du am Ende dieser Lektion kennenlernst. Es gibt zwei Wege drumherum, und es lohnt sich, beide zu kennen.

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

Der erste setzt einen Backslash vor jedes Anführungszeichen, das zum Text gehört. Der Backslash sagt „das nächste Zeichen gehört zum String, es ist nicht sein Ende“, und das Paar zusammen heißt Escape-Sequenz. Der zweite benutzt einfache Anführungszeichen, um die Enden des Strings zu markieren, und damit bleiben doppelte Anführungszeichen frei für gewöhnlichen Text. Lua nimmt beide Arten von Anführungszeichen, solange der String mit derselben Art endet, mit der er angefangen hat.

Beide Zeilen geben genau dasselbe aus. Nimm, was leichter zu lesen ist, und das sind meistens die einfachen Anführungszeichen, wenn der Text voller doppelter ist.

Die beiden Zahlen sind keine Pixel. overlayPrint ist der eigene schlichte Text der Engine, und er zählt in Zeichenzellen: (0, 0) ist ganz oben links in der Ecke, (1, 0) ist einen Buchstaben weiter rechts und (0, 1) eine Zeile tiefer. (2, 2) ist also zwei Buchstaben nach rechts und zwei Zeilen nach unten. Andere Arten, Text zu zeichnen, zählen sehr wohl in Pixeln, und die lernst du in Lektion neunzehn kennen.

    return OVERLAY_UPDATED

return gibt eine Antwort an den zurück, der die Funktion aufgerufen hat. Singe stellt deinem onOverlayUpdate bei jedem Aufruf eine Frage: Hast du etwas geändert? OVERLAY_UPDATED heißt ja, also bring es auf den Bildschirm.

OVERLAY_UPDATED steht nicht in Anführungszeichen, weil es kein Text ist. Es ist ein Name, den Singe schon einem Wert gegeben hat, damit du etwas schreiben kannst, das man lesen kann, statt einer Zahl, die du dir merken müsstest.

end

Das passende Ende der function. Jede function hat genau eins, und es zu vergessen ist der häufigste Fehler überhaupt.

Probier es aus

Ändere immer nur eine Sache, speichere und starte es noch einmal. Dieser Kreislauf — ändern, starten, hinsehen — ist die ganze Arbeit.

  1. Verschieb den Text. Ändere overlayPrint(2, 2, "Hello!") in overlayPrint(10, 5, "Hello!"). Dann probier (0, 0). Dann probier (200, 2) und finde heraus, warum er verschwunden ist.

  2. Sag etwas anderes. Schreib deinen eigenen Namen zwischen die Anführungszeichen.

  3. Sag zwei Dinge. Füg unter der ersten eine zweite Zeile mit overlayPrint ein, mit einer anderen Zeilennummer und anderem Text. Nichts hindert dich daran, so viele zu haben, wie du willst.

  4. Nimm das Löschen raus. Lösch die Zeile overlayClear() und starte es. Nichts ändert sich, weil sich auf deinem Bildschirm noch nichts bewegt. Setz sie trotzdem wieder ein. In Lektion zwei wird sie enorm wichtig, und jetzt ist ein guter Moment, um zu sehen, dass manche Fehler warten, bevor sie zubeißen.

Mach es absichtlich kaputt

Anfänger verbringen mehr Zeit damit, Fehlermeldungen zu lesen, als Bücher übers Programmieren, also bringen wir die erste gleich hinter uns.

Lösch das schließende Anführungszeichen nach Hello!, sodass die Zeile overlayPrint(2, 2, "Hello!) lautet, und starte es. Singe weigert sich zu starten und sagt:

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

Lies die Meldung von links. hello/hello.singe ist die Datei: der Ordner, dann das Skript darin. 3 ist die Zeile. Der Rest ist, was schiefgegangen ist, in diesem Fall ein Stück Text, das geöffnet und nie geschlossen wurde. Geh in Zeile drei, setz das Anführungszeichen wieder ein, und es läuft.

Fast jeder Fehler, den du je sehen wirst, hat diese Form: eine Datei, eine Zeile und eine Beschwerde. Die Beschwerde ist manchmal für jemanden geschrieben, der Lua schon kann, aber Datei und Zeile stimmen immer, und in neun von zehn Fällen reicht die Zeile.

Hör auf, es neu zu starten

Du hast Singe jetzt fünf- oder sechsmal von Hand gestartet. Lass das. Starte es stattdessen so:

Singe -R hello

-R sagt Singe, dass es dein Skript beobachten soll. Speichere eine Änderung in deinem Editor, und das Spiel startet sich einen Moment später selbst neu, mit deiner Änderung darin, ohne das Fenster zu schließen. Speicherst du einen Fehler, wird der Fehler ausgegeben, und das Fenster bleibt leer, bis du eine Korrektur speicherst.

Benutze -R für den Rest dieses Buchs.

Was du gelernt hast

  • Ein Programm ist eine Datei mit Anweisungen, die der Reihe nach passieren, von oben nach unten.

  • Eine function fasst Anweisungen unter einem Namen zusammen und hört bei ihrem end auf.

  • onOverlayUpdate ist ein Name, nach dem Singe sucht und den es viele Male pro Sekunde aufruft, und dort kommt alles hin, was du zeichnest.

  • Eine Funktion aufrufen heißt, ihren Namen und Klammern zu schreiben. Alles in den Klammern ist ein Argument.

  • Eine Funktion, die die Engine für dich aufruft, statt dass du sie selbst aufrufst, ist ein Callback. onOverlayUpdate ist einer.

  • Text in doppelten Anführungszeichen ist ein String.

  • Lösch den Bildschirm, bevor du darauf zeichnest.

  • Ein Fehler nennt dir die Datei und die Zeile. Fang dort an.

Beim nächsten Mal

Dein Hello! sitzt, wo du es hingesetzt hast, und bewegt sich nie. Damit es sich bewegt, brauchst du einen Ort, an dem eine Zahl liegt, die sich ändert — eine Variable. Darum geht es in der ganzen Lektion zwei.

Lektion 2: Zahlen, die sich ändern

Die fertige Lektion

In Lektion eins hast du ein Wort auf den Bildschirm gebracht, und da saß es dann. Am Ende dieser Lektion gleitet dasselbe Wort durchs Fenster, kehrt um, wenn es an einen Rand kommt, und das tut es wegen vier Zahlen, die das Programm sechzigmal pro Sekunde ändert.

Unterwegs triffst du auf die eine Idee, über die mehr Anfänger stolpern als über jede andere: Wo du etwas hinschreibst, entscheidet, wie lange es lebt.

Leg einen neuen Ordner an

Leg neben deinem Ordner hello einen Ordner namens numbers an und darin eine Datei namens numbers.singe. Tipp das Programm aus Lektion eins hinein, oder kopier hello.singe herüber und benenne sie um — beides ist in Ordnung, und das Abtippen ist keine verschwendete Zeit.

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

Starte es mit Singe -R numbers und lass es laufen. Dank dem -R vom Ende der Lektion eins musst du es für den Rest dieser Lektion nicht wieder starten; speichere die Datei, und das Fenster zieht von selbst nach.

Zähl die Frames

In Lektion eins hieß es, dass Singe onOverlayUpdate etwa sechzigmal pro Sekunde aufruft. Das ist leicht gesagt und schwer zu glauben, also zähl nach.

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

Speichere. Oben links in der Ecke steht frame 1, und es bleibt für immer bei frame 1.

Das ist enttäuschend, und es ist zugleich das Nützlichste in dieser Lektion, also reparier es noch nicht. Sieh dir an, was du geschrieben hast, und denk über die Reihenfolge der Zeilen nach, die laut Lektion eins das Wichtigste an einem Programm ist.

Singe ruft onOverlayUpdate auf. Die erste Zeile setzt frames auf null. Die zweite zählt eins dazu, macht eins. Du gibst es aus, du kehrst zurück, und die Funktion ist vorbei. Dann ruft Singe sie wieder auf, und als Erstes wird frames wieder auf null gesetzt.

Du zählst keine Frames. Du zählst bis eins, sechzigmal pro Sekunde.

Hol die Zeile heraus

Nimm die Zeile frames = 0 aus der Funktion heraus und setz sie darüber, für sich allein, vor das Wort function.

frames = 0


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

Speichere. Die Zahl steigt, schnell, und hört nicht auf.

Sonst hat sich nichts geändert. Der einzige Unterschied ist, wo die Zeile steht, und das ist schon die ganze Idee. Zeilen in einer Funktion passieren jedes einzelne Mal, wenn die Funktion aufgerufen wird. Zeilen außerhalb jeder Funktion passieren einmal, wenn Singe deine Datei liest, bevor das Spiel anfängt.

frames = 0 musste einmal passieren. Es passierte sechzigmal pro Sekunde und machte die Arbeit der Zeile darunter zunichte.

Alles, was sich bewegt und was du je schreibst, hat diese Form. Die Zahl draußen anlegen, drinnen ändern.

Was gerade passiert ist

Da drin stecken drei neue Stücke Code. Hier sind sie einzeln.

frames = 0

Das denkt sich einen Namen aus, frames, und legt die Zahl null dahinter. Ein Name mit einem Wert dahinter ist eine Variable, und sie heißt so, weil der Wert variieren darf — sich ändern, während das Programm läuft.

Das = ist nicht das Gleichheitszeichen aus der Schule. Es sagt nicht, dass frames gleich null ist; es sagt leg null in frames, und es arbeitet immer in diese Richtung, von rechts nach links. Programmierer nennen das Zuweisung, und es lohnt sich, die Zeile beim Schreiben so laut auszusprechen: „frames bekommt null“.

Den Namen wählst du. Er kann fast alles sein, was mit einem Buchstaben anfängt und keine Leerzeichen enthält, und er sollte sagen, was das Ding ist. frames ist ein guter Name. f ist ein schlechter, und in einer Woche wirst du dir dafür nicht dankbar sein.

    frames = frames + 1

Das ist die Zeile, bei der die Leute innehalten und starren, denn als Aussage übers Rechnen ist sie Unsinn: Nichts ist gleich sich selbst plus eins.

Sie ist keine Aussage übers Rechnen. Denk daran, dass = die rechte Seite in den Namen links legt, und lies sie in dieser Reihenfolge, rechts zuerst. Rechne frames + 1 aus, mit dem, was gerade in frames steht. Dann leg das Ergebnis zurück in frames. Stand in frames eine Sechs, ergibt die rechte Seite sieben, und sieben kommt in frames.

Eins zu einer Variablen dazuzuzählen wie hier wirst du tausende Male schreiben.

Das + tut, was du erwartest, und die anderen drei auch: - subtrahiert, * multipliziert und / dividiert. Es gibt keine Taste x zum Malnehmen, darum übernimmt das der Stern.

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

overlayPrint will Text, und frames ist eine Zahl, kein Text. Die zwei Punkte fügen die beiden zusammen und übergeben das Ergebnis als einen String: die fünf Zeichen frame, ein Leerzeichen und dann so viele Ziffern, wie die Zahl braucht.

Diese zwei Punkte sind der Verbindungsoperator, und es lohnt sich, seinen richtigen Namen zu kennen, weil die Fehlermeldungen ihn benutzen: Strings aneinanderzuhängen heißt Konkatenation.

Beachte das Leerzeichen in den Anführungszeichen, vor dem schließenden. Ohne es bekommst du frame6. Lua hängt genau das aneinander, was du ihm gibst, und tut nichts Eigenes dazu.

Lua macht für dich aus einer Zahl Text, wenn du sie so an einen String hängst, und darum musstest du nichts Besonderes tun. Das macht es nicht mit allem. Wenn du je versuchst, etwas anzuhängen, das weder Text noch Zahl ist, hält Lua mit einem Fehler an, und der Weg drumherum ist tostring, das aus allem überhaupt Text macht:

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

Diese Zeile tut genau dasselbe wie die davor. Für Zahlen brauchst du tostring nicht. In Lektion drei wirst du es brauchen.

Bring es in Bewegung

Jetzt hast du alles, was du brauchst, um das Wort zu bewegen. Das Wort wird gezeichnet, wo du willst, du hast eine Möglichkeit, eine Zahl von einem Frame zum nächsten aufzubewahren, und du hast eine Möglichkeit, sie zu ändern.

Gib der Spalte eine eigene Variable außerhalb der Funktion und zähl drinnen etwas dazu.

frames = 0
wordX  = 0


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

Speichere. Das Wort schießt rechts hinaus und kommt nie zurück.

Es ist in jedem Frame eine Spalte weitergerückt, sechzigmal pro Sekunde, also hat es das ganze Fenster in etwa einer Sekunde durchquert. Bremse es, indem du weniger als eine ganze Spalte dazuzählst:

    wordX = wordX + 0.25

Jetzt braucht es vier Frames für eine Spalte, und das Wort kriecht. wordX ist meistens eine Zahl wie 12.75, und das ist überhaupt keine Spalte; Singe löst das, indem es beim Zeichnen alles nach dem Punkt wegwirft: 12.75 wird in Spalte zwölf gezeichnet. Genau weil der Bruchteil in der Variablen bleibt, kannst du dich langsamer als eine Spalte pro Frame bewegen. Die Zahl ist feiner als der Bildschirm.

Wo ist der Rand?

Das Wort haut immer noch ab. Um es umkehren zu lassen, musst du wissen, wo der rechte Rand ist, und das könntest du durch Zählen herausfinden: Ein Spiel ohne Video bekommt standardmäßig eine Welt von 720 mal 480, das Overlay, auf das du zeichnest, ist halb so groß, 360 mal 240, und die Buchstaben der eingebauten Konsolenschrift sind sechs Pixel breit, also gibt es sechzig Spalten.

Mach das nicht. Frag die Engine.

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

overlayGetWidth und overlayGetHeight sind zwei weitere Funktionen, die Singe bereitstellt, wie overlayPrint. Sie bekommen nichts und geben eine Zahl zurück: wie breit und wie hoch die Zeichenfläche ist. In Lektion eins hast du gesehen, wie return einen Wert zurückgibt, und das hier ist das andere Ende davon — eine Funktion, die du aufrufst, kann dir etwas geben, und hier rechnest du mit dem, was sie dir gegeben hat.

Die Zahlen, die sie dir geben, sind in Pixeln, und overlayPrint zählt in Zeichenzellen, also musst du teilen. overlayGetFontWidth sagt dir, wie viele Pixel breit eine Zelle ist, und overlayGetFontHeight, wie hoch, sodass du die Antwort nie selbst kennen musst. Die zwei Schrägstriche heißen teilen und den Bruchteil wegwerfen, denn ein Drittel einer Zeichenzelle ist kein Ort, an dem du etwas ausgeben kannst. Der gewöhnliche einfache Schrägstrich würde dir einen Bruch geben, und ein Bruchteil einer Zelle ist auch kein Ort.

string.len zählt die Zeichen in einem String, und es steht da, damit das Wort umkehrt, wenn sein letzter Buchstabe den Rand erreicht, und nicht sein erster. Probier es ohne, und du siehst sechs Zeichen ins Nichts gleiten.

Die Großbuchstaben in CELL_WIDTH, das festhält, was dir overlayGetFontWidth gibt, sind eine Gewohnheit, keine Regel. Lua ist das egal, aber mit einem Namen in Großbuchstaben sagen Programmierer „das ist eine Zahl, die ich einmal oben festlege und nie wieder anfasse“, und das ist besser als eine nackte 6 mitten in einer Datei, die einen Monat später keiner erklären kann.

Lass es umkehren

In die andere Richtung zu laufen ist überhaupt keine Arbeit: Statt in jedem Frame 0.25 dazuzuzählen, zähl -0.25 dazu. Bewahr den Betrag also in einer eigenen Variablen auf und dreh sein Vorzeichen um, wenn das Wort an einem Rand ankommt.

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

Das ist eine Entscheidung, und um Entscheidungen geht es in der ganzen Lektion drei, also nimm es für eine Lektion einfach hin. Lies es laut: wenn wordX über lastColumn hinaus ist, dann mach die zwei eingerückten Zeilen; sonst überspring sie. Das end schließt es ab, so wie end eine Funktion abschließt.

Die erste Zeile heftet das Wort genau an den Rand, damit ein schnelles Wort nicht darüber hinaussegeln kann. Die zweite ist das Umdrehen. -speedX ist minus das, was in speedX steht; stand dort 0.25, steht jetzt -0.25 darin, und wenn du in jedem Frame -0.25 dazuzählst, läuft das Wort den Weg zurück, den es gekommen ist. Erreicht es den linken Rand, dreht das passende if es wieder um, und es wird wieder zu 0.25.

Noch zwei davon für den oberen und den unteren Rand, und das Wort springt im ganzen Fenster herum.

Das Ganze

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

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

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


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

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

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

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

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

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

TOP_ROW hält das Wort aus den obersten zwei Zeilen heraus, damit es nie über den Frame-Zähler kritzelt. In lastRow steht ein - 1 statt eines string.len, weil ein Wort viele Zeichen breit, aber immer nur eine Zeile hoch ist.

Beachte, dass die ganze obere Hälfte der Datei einmal läuft und die ganze untere Hälfte sechzigmal pro Sekunde, und dass du an der Einrückung erkennst, welche welche ist. Dafür waren die Leerzeichen da.

Probier es aus

  1. Ändere die Geschwindigkeiten. Probier speedX = 1 und speedY = 1. Dann probier 0.05 für beide. Dann mach eine viel größer als die andere.

  2. Ändere das Wort. Schreib ein viel längeres Wort zwischen die Anführungszeichen — lang genug, um ein Drittel des Fensters zu füllen — und sieh zu, wie das Abprallen rechts immer noch an der richtigen Stelle passiert. Das ist string.len, das seine Arbeit tut.

  3. Nimm das Löschen raus. Lösch die Zeile overlayClear(). Lektion eins hat versprochen, dass das eines Tages wichtig wird, und heute ist der Tag: Das Wort schmiert eine Spur quer durchs Fenster und radiert nichts davon weg, weil Zeichnen schon immer über das gezeichnet hat, was da war. Setz sie wieder ein.

  4. Halt die Seitwärtsbewegung an. Setz speedX = 0 und starte es. Finde heraus, warum das Wort jetzt nie Spalte null verlässt und warum das if für den linken Rand nie anspringt.

  5. Mach den Frame-Zähler absichtlich kaputt. Schieb die Zeile frames = 0 zurück in die Funktion, über frames = frames + 1. Sieh zu, wie der Zähler bei eins hängen bleibt, während sich das Wort tadellos weiterbewegt. Dann finde heraus, warum das Wort nichts davon merkt.

Mach es absichtlich kaputt

Ersetze die zwei Punkte in der Zeile mit dem Frame-Zähler durch ein Pluszeichen, sodass sie so lautet:

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

Speichere. Das Fenster geht zu, Singe hält an, und im Terminal steht:

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

gefolgt von mehreren Zeilen, die mit stack traceback: anfangen und die du vorerst ignorieren kannst.

Lies es so, wie Lektion eins es dir beigebracht hat: die Datei, die Zeile, dann die Beschwerde. Zeile 42 ist die Zeile, die du geändert hast. Die Beschwerde sagt, Lua sollte einen String zu einer Zahl addieren, und Addieren ist etwas für Zahlen. + und .. sehen auf dem Papier ähnlich aus und erledigen völlig verschiedene Aufgaben: Plus ist Rechnen, .. ist Kleber.

Diesen Fehler lohnt es sich kennenzulernen, wegen der Stelle, an der er auftaucht. Der Fehler aus Lektion eins hat Singe angehalten, bevor dein Spiel überhaupt anfing, weil Lua die Datei gar nicht lesen konnte. Dieser hier steckt in einer völlig lesbaren Zeile, die erst schiefgeht, wenn sie läuft; also ging das Fenster auf, das Spiel lief, und es starb im ersten Frame. Beide Arten nennen dir die Datei und die Zeile. Fang so oder so dort an.

Was du gelernt hast

  • Eine Variable ist ein Name mit einem Wert dahinter, und der Wert kann sich ändern.

  • = heißt „leg die rechte Seite in den Namen links“, nicht „ist gleich“.

  • frames = frames + 1 rechnet zuerst die rechte Seite aus und speichert sie dann.

  • +, -, * und / rechnen, wie du es erwartest; // teilt und wirft den Bruchteil weg.

  • .. hängt Text aneinander und macht dabei aus einer Zahl Text.

  • Eine Zeile in onOverlayUpdate läuft in jedem Frame. Eine Zeile außerhalb jeder Funktion läuft einmal, bevor das Spiel anfängt.

  • Alles, was sich von einem Frame zum nächsten etwas merken muss, muss draußen wohnen.

  • overlayGetWidth und overlayGetHeight sagen dir die Größe der Zeichenfläche, damit du sie nie raten musst.

  • overlayClear wird wichtig, sobald sich irgendetwas bewegt.

Beim nächsten Mal

Das Wort bewegt sich, aber es bewegt sich von selbst, und nichts, was du tust, ändert etwas daran. In Lektion drei nimmst du dir die vier if-Blöcke vor, die du auf Treu und Glauben benutzt hast, lernst, was sie wirklich sagen, und richtest sie auf die Pfeiltasten statt auf die Ränder des Bildschirms. Das Kästchen, das du am Ende durchs Fenster steuerst, ist die Spielfigur des Spiels, das du in Lektion sieben baust.

Lektion 3: Entscheidungen treffen

Die fertige Lektion

Alles, was du bisher geschrieben hast, tut in jedem Frame dasselbe. Das Wort aus Lektion zwei hat sich bewegt, ob du wolltest oder nicht, und umgekehrt ist es nur wegen vier Blöcken Code, die du auf Treu und Glauben hinnehmen solltest.

In dieser Lektion geht es um diese vier Blöcke, und zwar richtig. Am Ende stellt dein Programm Fragen, handelt nach den Antworten, und — weil die interessanteste Frage, die ein Spiel stellen kann, „Was macht der Spieler?“ lautet — du steuerst ein Kästchen mit den Pfeiltasten durchs Fenster. Heb dieses Kästchen gut auf. Es ist die Spielfigur des Spiels, das du in Lektion sieben baust.

Leg einen neuen Ordner an

Ein Ordner namens decisions, darin eine Datei namens decisions.singe, und in einem Terminal läuft Singe -R decisions. Wie beim letzten Mal.

Was ein if wirklich sagt

Hier ist der Block aus Lektion zwei für sich allein.

if wordX > lastColumn then
    wordX = lastColumn
end

Vier Teile. Das Wort if. Eine Frage. Das Wort then. Und ein Rumpf aus Zeilen, die nur laufen, wenn die Antwort auf die Frage Ja ist, abgeschlossen mit end.

Die Frage ist wordX > lastColumn, und die eigentliche Arbeit macht das >. Es vergleicht die beiden Zahlen links und rechts davon und liefert eine Antwort, die entweder wahr oder falsch ist. Diese beiden Wörter sind kein Text und keine Zahlen; sie sind eigene Werte, Booleans genannt, und ein Boolean ist das Einzige, wofür sich ein if interessiert.

Die Einrückung ist dieselbe Idee wie in Lektion eins: Die Zeilen darin sind eingerückt, damit du auf einen Blick siehst, was zum if gehört, und das end steht genau unter dem if, das den Block geöffnet hat. Lua würde es auch ohne die Leerzeichen ausführen. Du könntest es dann nicht lesen.

Es gibt sechs solche Vergleiche, und du wirst alle benutzen.

a < b

a ist kleiner als b

a > b

a ist größer als b

a ⇐ b

a ist kleiner oder gleich b

a >= b

a ist größer oder gleich b

a == b

a ist dasselbe wie b

a ~= b

a ist nicht dasselbe wie b

Bei den letzten beiden musst du aufpassen, aus verschiedenen Gründen.

~= heißt „ist nicht gleich“. Die meisten Sprachen schreiben das !=, und wenn du schon einmal ein Programm gesehen hast, tippen deine Finger !=, und Lua lehnt es ab. Die Schlangenlinie liegt auf deiner Tastatur neben der 1 oder unter dem #, je nachdem, wo du wohnst.

== sind zwei Gleichheitszeichen, und das ist kein Tippfehler für eins. Das ist einer der häufigsten Fehler beim Programmieren, und es lohnt sich, kurz dabei stehen zu bleiben.

In Lektion zwei hast du gelernt, dass ein Gleichheitszeichen leg die rechte Seite in den Namen links bedeutet. Das ist etwas, das du tust. Es ändert etwas.

Zwei Gleichheitszeichen bedeuten sind die beiden gleich? Das ist eine Frage, die du stellst. Sie ändert nichts, und sie gibt wahr oder falsch zurück.

lives = 3
if lives == 3 then

Die erste Zeile setzt lives auf drei. Die zweite fragt, ob es drei ist. Verschiedene Aufgaben, verschiedene Symbole, ein Zeichen Unterschied. Lua erwischt dich, wenn du sie verwechselst, und den Fehler, den es dann meldet, lernst du am Ende dieser Lektion kennen.

Wenn die Antwort Nein ist

Ein if allein tut überhaupt nichts, wenn die Antwort falsch ist. Sehr oft willst du, dass stattdessen das andere passiert, und dafür gibt es else.

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

Genau einer der beiden Rümpfe läuft, nie beide, nie keiner, also steht in message am Ende immer einer der beiden Strings und nie gar nichts.

Wenn es mehr als zwei Möglichkeiten gibt, hängt elseif sie aneinander.

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

Lua probiert die Fragen von oben und hört bei der ersten auf, die wahr ist. Eine Punktzahl von 6000 ist nicht größer als 10000, also probiert es die nächste, und die ist wahr, also wird rank zu pilot, und die anderen beiden Fragen werden nie gestellt. Dieser letzte Punkt ist wichtig: Das elseif für 1000 ist bei einer Punktzahl von 6000 auch wahr, aber es wird nie erreicht, und darum geht die Reihenfolge vom Größten zum Kleinsten.

Die ganze Kette braucht genau ein end, ganz egal, wie viele elseif-Teile darin stecken. Es ist eine Entscheidung, nicht vier.

Wahr, falsch und gar nichts

Du musst nicht zwei Dinge vergleichen, um einen Boolean zu bekommen. Du kannst einen aufbewahren.

paused = false

Das ist eine Variable wie jede andere, und der Wert darin ist der Boolean false selbst, ohne Anführungszeichen geschrieben, weil es nicht das Wort „false“ ist, sondern die Idee. Dasselbe gilt für true. Eine Variable, die einen von beiden enthält, kann direkt in ein if, ganz ohne Vergleich:

if paused then

Lies es als „if paused“. Das ist besseres Englisch als if paused == true, das dasselbe auf dem Umweg tut, und erfahrene Programmierer schauen dich seltsam an, wenn du das schreibst.

Drei Wörter verbinden diese Antworten und drehen sie um.

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

and ist wahr, wenn beide Seiten wahr sind. or ist wahr, wenn eine der beiden Seiten wahr ist, oder beide. not macht aus wahr falsch und aus falsch wahr. Sie lesen sich wie Englisch, und, ungewöhnlich fürs Programmieren, sie bedeuten auch, was sie im Englischen bedeuten.

Es gibt noch einen Wert, den du kennen solltest, und er ist der, der die verwirrendsten Fehler deines ersten Jahres erzeugt.

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

Wenn du nie etwas in lives gelegt hast, gibt das lives nil aus. Lua beschwert sich nicht über einen Namen, den es nie gesehen hat; es gibt dir nil, und das ist sein Wort für hier ist nichts. Es ist nicht die Null, und es ist kein leerer String. Die Null ist eine Zahl, die du speichern wolltest. nil ist das Fehlen eines Werts.

Du bist nil schon zweimal begegnet, ohne dass es dir jemand gesagt hat. frames = frames + 1 ohne die Zeile frames = 0 darüber schlägt fehl, weil du Lua gebeten hast, eins zu nichts zu addieren. Und ein Callback, den du falsch schreibst, ist ebenfalls nil, und darum bringt dir ein falsch geschriebenes onOverlayUpdate ein schwarzes Fenster und überhaupt keinen Fehler: Singe sucht nach dem Namen, findet dort nichts und macht still mit seinem Tag weiter.

tostring steht in dieser Zeile, weil .. einen Boolean oder ein nil an nichts anhängt. Zahlen wandelt es für dich um; diese nicht. Das war das Versprechen am Ende von Lektion zwei, und jetzt hast du eine Verwendung dafür.

Zum Schluss die Regel, die den ganzen Abschnitt zusammenhält, denn if nimmt alles, was du ihm gibst, nicht nur wahr und falsch:

In Lua ist alles wahr außer false und nil.

Null ist wahr. Ein leerer String ist wahr. Nur diese beiden sind es nicht, und wenn du das einmal weißt, liest sich if movingLeft then tadellos, ob in movingLeft nun true oder false steht oder ob es nie gesetzt wurde.

Die Steuerung abfragen

Zeit, den Spieler etwas zu fragen. Dafür braucht es einen neuen Callback.

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

onInputPressed ist der zweite Callback, den du geschrieben hast, und er funktioniert genau so, wie Lektion eins es beschrieben hat: Du schreibst ihn, Singe ruft ihn auf. onOverlayUpdate wird in einem festen Takt aufgerufen. Dieser hier wird aufgerufen, wenn etwas passiert — wenn der Spieler irgendetwas drückt, das die Engine erkennt.

Der Unterschied zu onOverlayUpdate ist das Wort in den Klammern. Singe muss dir sagen, welches Steuerelement gedrückt wurde, also übergibt es der Funktion einen Wert, und what ist der Name, unter dem du ihn entgegennehmen willst. In Lektion eins hießen die Dinge, die du einer Funktion übergibst, Argumente; von innen gesehen ist der Name, der eines auffängt, ein Parameter. Der Name gehört dir: Nenn ihn what, nenn ihn button, nenn ihn k. Singe füllt ihn so oder so.

SWITCH_RIGHT ist ein Name, den die Engine schon einem Wert gegeben hat, wie OVERLAY_UPDATED in Lektion eins. Du musst nichts laden, um ihn zu benutzen; Singe legt sie alle fest, bevor dein Skript läuft. Es gibt einen für alles, was ein Automat hat: SWITCH_LEFT, SWITCH_RIGHT, SWITCH_UP, SWITCH_DOWN, SWITCH_BUTTON1 bis SWITCH_BUTTON4, SWITCH_START1, SWITCH_COIN1 und mehr. Die Tabelle Engine-Konstanten in der Referenz deckt die ganze Familie ab, die von SWITCH_UP bis SWITCH_RECORD reicht. Sie heißen absichtlich nicht „die rechte Pfeiltaste“, denn dasselbe SWITCH_RIGHT kommt an, ob der Spieler eine Pfeiltaste gedrückt hat, einen Joystick oder den Stick eines Gamepads. Du schreibst das Spiel einmal, und es funktioniert mit allen dreien.

Füg diesen Callback hinzu, gib boxX außerhalb der Funktionen einen Startwert und zeichne etwas bei boxX. Drück die Pfeiltaste nach rechts. Das Kästchen springt bei jedem Drücken zehn Pixel weiter.

Es ist passiert, und es passiert gerade

Halt die Pfeiltaste gedrückt. Mehr passiert nicht.

onInputPressed wird einmal aufgerufen, beim Hinunterdrücken, und erst wieder, wenn du loslässt und noch einmal drückst. Es gibt keine Tastenwiederholung. Für manche Dinge ist das genau richtig — einen Schuss abfeuern, eine Münze einwerfen, einen Menüpunkt wählen — und fürs Laufen genau falsch, denn das muss so lange weitergehen, wie die Taste gehalten wird.

Das sind wirklich zwei verschiedene Fragen. Es ist passiert ist ein Ereignis, und davon hörst du einmal. Es passiert gerade ist ein Zustand, und der dauert an. Singe erzählt dir von Ereignissen, und aus Ereignissen machst du einen Zustand, indem du sie dir selbst merkst.

Zwei Callbacks, eine Variable dazwischen.

movingRight = false


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


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

onInputReleased ist der dritte Callback, und er ist das Spiegelbild des zweiten: Singe ruft ihn auf dem Weg zurück nach oben auf, mit demselben SWITCH_-Wert. Zusammen sorgen die beiden dafür, dass movingRight die Wahrheit darüber sagt, was der Finger des Spielers gerade tut.

Bewegt hat sich noch nichts, und genau darum geht es. Das Drücken und das Bewegen sind jetzt zwei getrennte Aufgaben. Das Bewegen kommt dorthin, wo alle Arbeit hinkommt, die in jedem Frame passiert.

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

Das Kästchen gleitet jetzt gleichmäßig, solange die Taste unten ist, mit einer Geschwindigkeit, die du bestimmst, und das Rechnen ist wieder in der einen Funktion, die sechzigmal pro Sekunde läuft, wo es hingehört. Diese Form — Ereignisse setzen Flags, der Frame handelt nach den Flags — ist die Art, wie fast jedes Spiel seine Steuerung behandelt, und du wirst sie in jeder Lektion wieder benutzen, in der es eine Spielfigur gibt.

Ein Kästchen zeichnen

overlayBox bekommt zwei Ecken: links und oben am Rechteck, dann rechts und unten.

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

Es zeichnet einen Umriss, vier Linien, ein Pixel dick, und kein gefülltes Rechteck. Unter den Zeichenaufrufen fürs Overlay gibt es überhaupt kein gefülltes Rechteck. Wenn du später einen massiven Block willst, gibt es Wege dahin, und Lektion neun zeigt den üblichen.

Seine Zahlen sind Pixel, keine Zeichenzellen. Darauf fallen Leute herein, denn overlayPrint hat in Lektion zwei in Zellen von sechs mal dreizehn Pixeln gezählt, und alles andere in Singe zählt in Pixeln. overlayPrint ist der Sonderling; die übrigen Zeichenaufrufe — overlayBox, overlayLine, overlayCircle, overlayEllipse und overlayPlot — arbeiten alle in denselben Pixeln, die overlayGetWidth meldet.

colorForeground legt die Farbe fest, als drei Zahlen von 0 bis 255: wie viel Rot, wie viel Grün, wie viel Blau. Alle drei auf 255 ist Weiß, alle auf 0 ist Schwarz, und (255, 220, 0) ist ein warmes Gelb. Beachte, dass es kein Argument von overlayBox ist. Es ist eine Einstellung: Du änderst sie, und alles, was du danach zeichnest, kommt in der neuen Farbe heraus, bis du sie wieder änderst. overlayPrint ist wieder einmal die Ausnahme — die Konsolenschrift bringt ihre eigenen Farben fest eingebacken mit und ignoriert dich.

Das Ganze

BOX_SIZE  = 20
BOX_SPEED = 2

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

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

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


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


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


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

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

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

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

    overlayClear()

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

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

Vier Dinge darin sind einen zweiten Blick wert.

movingLeft and not movingRight steht da, weil ein Spieler beide Pfeiltasten gleichzeitig halten kann. Ohne das not würden die beiden gegeneinander kämpfen, und das Kästchen würde zittern oder wegdriften; mit ihm gewinnt keine, wenn beide gehalten werden, und das Kästchen steht still, und genau das erwartet ein Spieler.

maxX wird einmal oben ausgerechnet, mit overlayGetWidth, so wie in Lektion zwei, und das - 1 ist da, weil das letzte Pixel der Fläche um eins kleiner ist als ihre Breite. Nimm das - 1 heraus, und die rechte Kante des Kästchens fällt von der Fläche und verschwindet, weil Singe alles, was du außerhalb des Overlays zeichnest, wortlos wegwirft.

Die Begrenzungsblöcke benutzen elseif statt zweier getrennter if-Blöcke. Das Kästchen kann nicht gleichzeitig links und rechts über den Rand hinaus sein, also ist es verschwendete Arbeit, die zweite Frage zu stellen, wenn die erste wahr war.

Und die Farbentscheidung ist ein if, dessen einzige Aufgabe es ist, einen Wert auszuwählen. Gelb, solange der Spieler etwas tut, blau, solange nicht, und so siehst du gratis, dass deine Eingabeverarbeitung wirklich funktioniert.

Probier es aus

  1. Ändere die Geschwindigkeit. BOX_SPEED = 1 und BOX_SPEED = 8. Sieh dir bei acht an, was die Begrenzung macht, wenn du das Kästchen in eine Ecke schiebst.

  2. Zeig deine Flags. Füg onOverlayUpdate eine Zeile hinzu: overlayPrint(0, 1, "left " .. tostring(movingLeft)). Halte die linke Pfeiltaste, lass sie los und sieh zu, wie der Wert umspringt. Dann nimm das tostring weg und lies den Fehler, den Lua dir gibt.

  3. Mach es schneller, wenn ein Knopf gedrückt ist. Füg ein Flag running hinzu, das in den beiden Eingabe-Callbacks von SWITCH_BUTTON1 gesteuert wird, und benutze ein if in onOverlayUpdate, um dich um das Doppelte von BOX_SPEED zu bewegen, solange es wahr ist.

  4. Markier die Mitte. Zeichne ein zweites, kleines Kästchen in die Mitte des Fensters, das die Farbe wechselt, wenn das Kästchen des Spielers es überlappt. Du brauchst and, um vier Vergleiche zu verbinden, und es ist schwieriger, als es klingt. Es ein bisschen falsch hinzubekommen ist normal; Lektion elf macht es richtig.

  5. Nimm das Loslassen raus. Lösch die ganze Funktion onInputReleased und starte es. Das Kästchen macht einen Schritt und hält dann nie wieder an. Finde heraus, welche Zeile jetzt nie erreicht wird.

Mach es absichtlich kaputt

Such den Begrenzungsblock und mach aus dem < in seinem ersten Vergleich ein einzelnes Gleichheitszeichen, sodass er so lautet:

    if boxX = 0 then

Speichere. Das Fenster bleibt leer, und im Terminal steht:

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

Das ist der Fehler, vor dem der ganze Abschnitt über == gewarnt hat, und die Meldung ist ein gutes Beispiel für einen Fehler, der völlig zutreffend und völlig nutzlos ist, wenn du ihn wörtlich nimmst. Lua will nicht, dass du das Wort then hinzufügst. Lua ist bis if boxX gekommen, hat als Nächstes einen Vergleich oder ein then erwartet und = gefunden, und das kann keins von beiden sein.

Immer wenn du 'then' expected nach einem if siehst, such ein einfaches =, das ein doppeltes sein sollte. Fast immer ist es das.

Achte darauf, wo dieser hier aufgetaucht ist: Das Spiel ist nie gestartet, genau wie beim unvollständigen String in Lektion eins, weil Lua die Datei nicht lesen konnte. Der Fehler mit dem Frame-Zähler in Lektion zwei passierte während des Laufens. Fehler in der Form deines Codes halten dich auf, bevor das Spiel anfängt. Fehler in dem, was dein Code tut, warten, bis er läuft.

Was du gelernt hast

  • if question then …​ end führt einen Rumpf nur aus, wenn die Antwort wahr ist.

  • else liefert den anderen Fall, und elseif hängt weitere an; die erste wahre Frage gewinnt, und die übrigen werden nie gestellt.

  • Die Vergleiche sind <, >, ⇐, >=, == und ~=.

  • = legt einen Wert in einen Namen. == fragt, ob zwei Dinge gleich sind.

  • true und false sind Werte, und du kannst sie in Variablen aufbewahren.

  • and, or und not verbinden diese Antworten und drehen sie um.

  • nil bekommst du von einem Namen, den du nie gesetzt hast, und es ist nicht die Null.

  • Alles ist wahr außer false und nil.

  • onInputPressed und onInputReleased sind Callbacks, die Singe mit einem SWITCH_-Wert aufruft, wenn der Spieler ein Steuerelement drückt oder loslässt.

  • Ein Drücken ist ein Ereignis und passiert einmal; halte den Zustand in einer Variablen fest und handle in jedem Frame danach.

  • overlayBox zeichnet einen Umriss in Pixeln, und colorForeground ist eine Einstellung, kein Argument.

Beim nächsten Mal

Ein Kästchen ist leicht. Hundert Sterne sind es nicht, zumindest nicht so, wie du bisher geschrieben hast, denn hundert Zeilen overlayPlot abzutippen ist niemandes Vorstellung von einem schönen Abend. In Lektion vier geht es um die Schleife: dem Computer zu sagen, dass er dasselbe viele Male tun soll, jedes Mal mit etwas anderem, und erst das macht einen Bildschirm voll mit irgendwas möglich.

Lektion 4: Noch einmal

Die fertige Lektion

Du hast ein Wort und ein Kästchen gezeichnet. Ein Spiel braucht hundert Dinge: Sterne, Steine, Geschosse, die Zeilen eines Menüs. Hundert Zeilen abzutippen ist nicht die Antwort, und wenn es das wäre, müsstest du noch einmal hundert tippen, sobald du hunderteins willst.

Diese Lektion ist die Antwort. Am Ende treibt ein Sternenfeld dein Fenster hinunter, und jeder einzelne Stern wird von denselben fünf Zeilen Code gezeichnet.

Leg einen neuen Ordner an

Ein Ordner namens repeating, darin eine Datei namens repeating.singe, und in einem Terminal läuft Singe -R repeating.

Vierzig Punkte

Tipp das ein und starte es.

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

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

    return OVERLAY_UPDATED
end

Eine Reihe aus vierzig weißen Punkten quer durch die Mitte des Fensters.

overlayPlot ist der einfachste Zeichenaufruf, den es gibt: Er setzt ein Pixel auf die aktuelle Vordergrundfarbe, und genau das will ein Stern. Alles Interessante hier steckt in den drei Zeilen drumherum.

    for star = 1, 40 do

Das sagt: Tu das Folgende vierzigmal, und bei jedem Durchlauf steht in star eine andere Zahl — eins beim ersten Mal, zwei beim zweiten, vierzig beim letzten. Beide Enden zählen mit, also sind 1, 40 wirklich vierzig Durchläufe und nicht neununddreißig. Diese Form ist eine Schleife, und diese hier ist eine numerische for-Schleife.

star ist ein Name, den du dir ausdenkst, so wie du dir in Lektion zwei frames ausgedacht hast, und die Schleife füllt ihn für dich. Du setzt ihn nicht, und du solltest ihn in der Schleife nicht ändern. Es gibt ihn nur zwischen dem for und seinem end; fragst du danach nach ihm, bekommst du nil.

Das do ist Pflicht und leicht zu vergessen. Lässt du es weg, sagt Lua 'do' expected near, gefolgt von dem, was es stattdessen gefunden hat, und das ist das Erste in der nächsten Zeile.

        overlayPlot(star * 8, 100)

Der Rumpf. Das ist es, was vierzigmal läuft, und es ist jedes Mal dieselbe Zeile — was sich ändert, ist star, also landet der erste Punkt bei x gleich 8, der zweite bei 16 und der letzte bei 320. Eine Schleife ist nur nützlich, wenn der Rumpf etwas mit der Nummer der Schleife macht, und das Erste, wozu du jedes Mal greifen wirst, ist, damit zu rechnen.

Der Rumpf ist eine Stufe weiter eingerückt als das for, aus demselben Grund, aus dem bisher alles andere eingerückt war.

    end

Schließt die Schleife. Jetzt kennst du drei Dinge, die ein end brauchen: function, if und for. Sie funktionieren alle gleich, sie lassen sich ineinander verschachteln, und an der Einrückung behältst du den Überblick, welches end wozu gehört.

In größeren Schritten zählen

Die Schleife zählt in Einerschritten hoch, wenn du ihr nichts anderes sagst. Füg eine dritte Zahl hinzu, und sie zählt stattdessen in diesen Schritten.

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

Lies es als von, bis, Schrittweite. Diese hier geht 0, 10, 20 und so weiter und hört beim letzten Pixel der Fläche oder davor auf, und so zeichnet sie eine gepunktete Linie ganz quer hinüber, egal wie groß das Fenster gerade ist. Es ist dieselbe Punktreihe wie vorher, beschrieben danach, wo die Punkte hinkommen, statt wie viele es sind.

Die Schrittweite kann negativ sein, dann zählt die Schleife rückwärts.

    for countdown = 10, 1, -1 do

Zehn, neun, acht, bis hinunter zu eins. Mit einer negativen Schrittweite ist die zweite Zahl der Boden statt der Decke, was du wohl auch erwartest, und ein falsches Vorzeichen ergibt eine Schleife, die nie läuft: for i = 10, 1 do ohne Schrittweite zählt von zehn aufwärts in Richtung eins, ist schon hinter dem Ende, bevor es losgeht, und tut nichts. Kein Fehler, keine Ausgabe. Wenn eine deiner Schleifen nie zu laufen scheint, prüf zuerst die Richtung.

Die Schrittweite kann auch ein Bruch sein, aber das brauchst du seltener, als du denkst.

Eine Schleife in einer anderen

Der Rumpf einer Schleife ist gewöhnlicher Code, und gewöhnlicher Code kann eine Schleife enthalten.

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

Das zeichnet ein Punktraster über das ganze Fenster. Setz es in deinem onOverlayUpdate anstelle der Reihe ein und sieh es dir an, denn wie es abläuft, solltest du dir jetzt klarmachen und nicht erst in Lektion elf, wenn etwas davon abhängt.

Die äußere Schleife läuft einmal mit row gleich 0. Darin läuft die ganze innere Schleife von Anfang bis Ende — achtzehn Spalten, achtzehn Punkte, eine Zeile des Rasters. Erst wenn die innere Schleife fertig ist, geht die äußere weiter zu row gleich 20 und lässt die ganze innere Schleife noch einmal laufen.

Der Rumpf der inneren Schleife läuft also achtzehn mal zwölf, das sind zweihundertsechzehn Mal, bei zwölf Durchläufen der äußeren. Wegen dieser Multiplikation füllst du mit verschachtelten Schleifen ein Rechteck mit was auch immer, und darum solltest du auch einen Blick auf die Zahlen werfen, bevor du drei davon verschachtelst.

Beachte, dass die Position jedes Punkts beide Schleifenvariablen braucht: column für waagerecht und row für senkrecht. Das ist das Muster. Wenn der innere Rumpf nur die innere Variable benutzt, zeichnet die innere Schleife immer wieder dasselbe an dieselbe Stelle, und du hast eine langsame Art geschrieben, es einmal zu tun.

Wenn du nicht weißt, wie viele

Eine for-Schleife muss wissen, wie oft, bevor sie anfängt. Manchmal weißt du das nicht, und dann willst du die andere Sorte.

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

Eine while-Schleife prüft vor jedem Durchlauf eine Frage, genau so eine Frage, wie ein if sie stellen würde, und macht weiter, solange die Antwort wahr ist. Ist die Antwort falsch, hört sie auf und macht mit der Zeile nach dem end weiter. Ist die Antwort gleich beim ersten Mal falsch, läuft der Rumpf überhaupt nie.

Dieses Beispiel zeichnet dieselbe gepunktete Linie wie das for mit Schrittweite zehn, und es braucht drei Zeilen für das, was for in einer erledigt hat, also nimm dafür for. Hier ist der Unterschied, der es entscheidet:

  • Nimm for, wenn die Zahl der Durchläufe feststeht, bevor du anfängst. Vierzig Sterne. Jedes zehnte Pixel quer hinüber. Jede Zeile eines Rasters.

  • Nimm while, wenn du darauf wartest, dass etwas wahr wird, und nicht vorher sagen kannst, wie lange das dauert. Karten austeilen, bis der Stapel leer ist. Immer wieder fragen, bis der Spieler etwas Gültiges eintippt. Eine Liste durchgehen, bis du findest, was du gesucht hast.

Ein while hat drei Teile, und alle drei musst du selbst schreiben: die Variable vor der Schleife anlegen, sie im while prüfen und sie im Rumpf ändern. Die for-Schleife erledigt alle drei für dich, und darum greifst du zu ihr, wenn sie passt. Vergiss im while den dritten Teil, und die Frage hört nie auf, wahr zu sein; genau das machst du am Ende dieser Lektion absichtlich.

Ein Stern aus seiner eigenen Nummer

Jetzt das Sternenfeld und ein Problem, das den Rest von Teil eins prägt.

Jeder Stern braucht ein eigenes x und ein eigenes y, und du hast keine Möglichkeit, hundert getrennte Variablen aufzubewahren — star1X, star2X und so weiter bis hundert zu schreiben ist schlimmer, als die hundert Zeilen abzutippen, um die du herumkommen wolltest. Also speichere sie nicht. Rechne jede Position aus dem Einzigen aus, was einen Stern von seinen Nachbarn unterscheidet: seiner Nummer.

        starX = (star * 37) % width

Das % ist der letzte der Rechenoperatoren, und es ist der Rest: das, was beim Teilen übrig bleibt. Fünfzehn geteilt durch vier ist drei, Rest drei, also ist 15 % 4 gleich 3. Seine nützliche Eigenschaft ist, dass das Ergebnis nie so groß werden kann wie die Zahl rechts, also ist der Rest beim Teilen durch width immer eine Position irgendwo auf dem Bildschirm, ganz egal, wie groß die linke Seite wird.

Stern 1 landet bei 37, Stern 5 bei 185, Stern 10 bei 10 — 370 ist über 360 hinausgelaufen und links wieder hereingekommen. Siebenunddreißig ist gewählt, weil es keinen gemeinsamen Teiler mit 360 hat, und das verhindert, dass die Sterne in ordentlichen Streifen landen; probier stattdessen 36, und du siehst das Problem sofort.

Das Hinabtreiben ist derselbe Trick mit einer Zahl, die mit der Zeit wächst.

drift = 0


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

drift wohnt außerhalb der Funktion und steigt in jedem Frame, genau wie frames in Lektion zwei. Wenn du es zum y jedes Sterns addierst, bewegt sich das ganze Feld gemeinsam nach unten, und das % holt einen Stern, der unten herausfällt, oben wieder herein, für immer, gratis.

math.floor wirft den Bruchteil einer Zahl weg und gibt den ganzen Teil darunter zurück: math.floor(7.9) ist 7. In Lektion zwei hieß es, dass Singe das beim Zeichnen für dich tut, und das stimmt auch, aber wenn du es selbst tust, ist die Zahl, mit der du arbeitest, die Zahl, die auf dem Bildschirm erscheint. Das wird in Lektion sieben wichtig, wenn sich zwei Dinge einig sein müssen, ob sie sich berühren.

Beachte, dass layer darin eine zweite Schleifenvariable ist. Die Sterne werden von einer Schleife in einer Schleife gezeichnet, und die äußere ist keine Zeile eines Rasters, sondern eine Entfernung: drei Ebenen von Sternen, jede mit eigener Geschwindigkeit und eigener Helligkeit, und das lässt ein flaches Punktfeld aussehen, als hätte es Tiefe.

Zufall

Sterne funkeln. Funkeln heißt eine Helligkeit, die in jedem Frame ein bisschen anders ist, und „ein bisschen anders“ ist math.random.

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

math.random(60, 90) gibt eine ganze Zahl von 60 bis 90 zurück, beide eingeschlossen, bei jedem Aufruf neu gewählt. Rufst du es ganz ohne Argumente auf, bekommst du stattdessen einen Bruch zwischen 0 und 1, und diese Form nimmst du, wenn etwas in einem von fünf Fällen passieren soll. Den Zufallsgenerator musst du nicht einrichten; das macht Lua, wenn Singe startet.

Das Addieren von layer * 55 hebt die nahen Ebenen aus dem trüben Bereich heraus, also bleiben die fernen Sterne schwach und die nahen sind fast weiß. Gleich viel Rot, Grün und Blau ist, wie Lektion drei erklärt hat, ein Grauton.

Weil shade in jedem Frame für jeden Stern neu gewählt wird, flackert jeder Stern für sich, und bei sechzig Frames pro Sekunde wirkt das wie Funkeln und nicht wie ein Fehler.

Das Ganze

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

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


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

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

    return OVERLAY_UPDATED
end

Hundertzwanzig Sterne, gezeichnet von fünf Zeilen, und die Datei ist kürzer als die aus Lektion drei.

Weiter kommst du mit diesem Ansatz aber auch nicht, und es lohnt sich, ehrlich zu sagen, warum, solange du es vor dir hast. Jeder Stern darin ist eine Formel. Nichts an einem Stern wird gemerkt: Du kannst keinen heller machen als seinen Nachbarn und ihn so bleiben lassen, du kannst keinen vom Himmel schießen, und du kannst keinen vom Spieler einsammeln lassen, weil es keinen Ort gibt, an dem du aufschreiben könntest, dass ihm etwas passiert ist. Stern siebzehn ist kein Ding. Er ist eine Zahl, die kurz durch eine Variable namens star wandert.

Sobald du hundert Dinge willst, die sich jedes etwas Eigenes merken, brauchst du einen Ort für hundert Sätze von Fakten. Das ist Lektion sechs, und das Sternenfeld ist der Grund, warum es sie gibt.

Probier es aus

  1. Mehr und weniger. Probier STARS_PER_LAYER = 200, dann 4. Dann LAYERS = 8, und sieh dir an, was layer * LAYER_BRIGHT mit shade macht, wenn die Nummer der Ebene groß wird. Die Zahlen, die colorForeground annimmt, hören bei 255 auf.

  2. Ändere die Abstände. Setz ACROSS_STEP auf 36 und starte es. Die Sterne ordnen sich in Streifen, weil 36 genau zehnmal in 360 passt. Stell es wieder auf 37 und probier 71 und 90.

  3. Stopp das Funkeln. Ersetze die Zeile mit math.random durch ein schlichtes shade = layer * 70 und vergleiche. Entscheide, was dir besser gefällt; es gibt keine richtige Antwort, und zu bemerken, dass du einen Geschmack hast, gehört zur Arbeit.

  4. Lass sie nach oben fallen. Ein Zeichen.

  5. Zeichne auch das Raster. Setz die verschachtelte Rasterschleife von vorhin wieder ein, nach den Sternen, in einer gedämpften Farbe. Zwei verschachtelte Schleifen in einer Funktion, die zwei verschiedene Dinge zeichnen, und die zweite stört die erste nicht.

Mach es absichtlich kaputt

Jeder Fehler bisher war eine Meldung. Dieser hier nicht, und genau darum solltest du ihn kennenlernen, während du mit ihm rechnest.

Setz das in dein onOverlayUpdate, direkt unter overlayClear(), starte es und lies den nächsten Absatz, bevor du irgendetwas anderes tust.

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

Die Zeile, die x weiterschiebt, fehlt, also bleibt x auf null, also hört x < width nie auf, wahr zu sein. Die Schleife dreht sich für immer und setzt immer dasselbe Pixel, und sie steckt in onOverlayUpdate, also kehrt onOverlayUpdate nie zurück. Singe wartet auf deine Funktion. Es kann nicht zeichnen, es kann die Tastatur nicht lesen, und es kann sich nicht beenden.

Was du siehst, ist ein Fenster, in dem sich nichts mehr bewegt. Esc bewirkt nichts. Q bewirkt nichts. Ausgegeben wird auch nichts.

Geh in das Terminal, in dem du Singe gestartet hast, und drück Strg und C zusammen. Singe hält deine Schleife an und sagt dir, wo sie gerade war:

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

Vielleicht sagt es das zweimal, ein paar Sekunden auseinander, bevor es sich beendet. Einmal reicht völlig. Zeile 20 ist das end deines while, und dort drehte sich die Schleife, als du sie angehalten hast. Nimm die Schleife heraus, speichere und starte Singe neu.

Das ist ein Bericht, kein Fehler. Nichts hat sich beschwert, bis du gefragt hast, weil aus Sicht des Computers nichts schiefgegangen ist. Du hast eine Schleife verlangt, die läuft, solange x kleiner als die Breite ist, und genau die hast du bekommen. Das ist die eine Art von Fehler, bei der dir die Fehlermeldungen nicht helfen können, und das Gegenmittel ist eine Gewohnheit: Jedes Mal, wenn du ein while schreibst, schreib die Zeile, die die Variable ändert, bevor du irgendetwas anderes in den Rumpf schreibst.

Was du gelernt hast

  • for name = first, last do …​ end führt seinen Rumpf einmal für jede Zahl vom ersten bis zum letzten Wert aus, beide eingeschlossen.

  • Eine dritte Zahl ist die Schrittweite, und sie darf negativ sein, um rückwärts zu zählen.

  • Die Schleifenvariable gibt es nur in der Schleife, und der Rumpf sollte sie benutzen.

  • for braucht ein do, und jede Schleife braucht ein end.

  • Eine Schleife in einer Schleife lässt bei jedem Durchlauf der äußeren die ganze innere laufen, und so füllst du ein Rechteck.

  • while question do …​ end wiederholt, solange die Frage wahr ist, und du musst selbst im Rumpf etwas ändern.

  • Nimm for, wenn du weißt, wie oft, und while, wenn du darauf wartest, dass etwas wahr wird.

  • % ist der Rest, und er hält eine wachsende Zahl in einem Bereich.

  • math.random(a, b) liefert eine ganze Zahl von a bis b; math.floor wirft den Bruchteil weg.

  • Eine Schleife, die nie endet, friert das ganze Spiel ohne Fehlermeldung ein, und mit Strg und C im Terminal kommst du wieder heraus.

Beim nächsten Mal

Sieh dir dieses onOverlayUpdate noch einmal an. Es zeichnet Sterne, es rechnet Positionen aus, es wählt Farben, und es wird langsam zu einer Funktion, die vier Aufgaben erledigt statt einer. In Lektion fünf schreibst du eigene Funktionen, gibst ihnen Argumente, so wie Singes Funktionen sie bekommen, und holst Antworten aus ihnen heraus — und das Sternenfeld wird zu einer Zeile, in der drawStars() steht.

Lektion 5: Deine eigenen Funktionen

Die fertige Lektion

Lektion vier hat mit einer Warnung über dein eigenes Programm geendet: onOverlayUpdate rechnet aus, wohin hundertzwanzig Sterne kommen, entscheidet, wie hell jeder ist, zeichnet sie und zählt die Drift, und das ist eine Funktion, die vier Aufgaben erledigt. Gleich soll sie eine fünfte übernehmen, denn ein Sternenfeld, vor dem nichts ist, ist kein Spiel.

In dieser Lektion nimmst du sie auseinander. Du schreibst eigene Funktionen — Funktionen, von denen Singe nie gehört hat und die es nie aufrufen wird — und gibst die Arbeit an sie ab. Am Ende ist das ganze Sternenfeld eine Zeile, in der drawStars() steht, unten auf dem Bildschirm ist wieder ein Schiff, und das Programm ist leichter zu lesen als damals, als es weniger getan hat.

Leg einen neuen Ordner an

Ein Ordner namens functions, darin eine Datei namens functions.singe, und in einem Terminal läuft Singe -R functions.

Kopier das fertige Programm aus Lektion vier hinein. Hier ist es, unverändert, und es lohnt sich, es einmal laufen zu lassen, bevor du irgendetwas anfasst:

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

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


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

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

    return OVERLAY_UPDATED
end

Drei Ebenen von Sternen, die mit drei Geschwindigkeiten das Fenster hinuntertreiben. Nichts in der ersten Hälfte dieser Lektion ändert, was du siehst. Alles darin ändert, wie sich das Programm liest.

Eine Aufgabe, ein Name

Fang mit den zwei Zeilen an, die einen Stern auf den Bildschirm bringen. Füg über onOverlayUpdate das hier ein:

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

Dann lösch in der inneren Schleife diese zwei Zeilen und ruf stattdessen die Funktion auf:

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

Speichere. Das Bild ist dasselbe.

Du hast schon früher Funktionen geschrieben — onOverlayUpdate ist eine, onInputPressed und onInputReleased aus Lektion drei ebenso. Aber das sind Callbacks. Du schreibst sie, und Singe ruft sie auf. drawStar ist anders. Singe hat nie von ihr gehört. Sie läuft, weil du ihren Namen und Klammern geschrieben hast, genauso wie du overlayPlot aufrufst, und nichts auf der Welt führt sie aus, wenn du es nicht tust.

Das ist der ganze Trick. Wenn du ab jetzt denkst „und jetzt zeichne einen Stern“, kannst du „zeichne einen Stern“ hinschreiben und es so meinen.

Ein Parameter ist ein Name, kein Ding

Sieh dir die erste Zeile von drawStar noch einmal an.

function drawStar(x, y, shade)

Die drei Namen in den Klammern sind Parameter. Ein Parameter ist ein Name, den die Funktion für das benutzt, was der Aufrufer ihr übergeben hat. Wenn du drawStar(starX, starY, shade) schreibst, setzt Lua x auf das, was in starX steht, y auf das, was in starY steht, shade auf das, was in shade steht, und führt dann die Funktion aus.

Die Namen haben nichts miteinander zu tun. Die Zahl des Aufrufers heißt da draußen starX und hier drinnen x, und es würde genauso funktionieren, wenn du sie across oder banana nennen würdest. In der Funktion gibt es nur die Namen in den Klammern, und sie enthalten Kopien von dem, was hereingekommen ist.

Hier ergeben die leeren Klammern aus Lektion eins endlich einen Sinn.

function onOverlayUpdate()

Nichts in den Klammern heißt keine Parameter: Die Engine hat dieser Funktion nichts zu sagen, also gibt es nichts zu benennen. Vergleich das mit dem Callback, den du in Lektion drei geschrieben hast.

function onInputPressed(what)

Ein Parameter namens what. Diesem hier hat die Engine etwas zu sagen — welches Steuerelement gedrückt wurde — also gibt es einen Namen, der es auffängt. Du benutzt seit Lektion drei einen Parameter.

Ein Parameter ist wirklich die eigene Kopie der Funktion, und es lohnt sich, dir das einmal selbst zu beweisen. Tipp das ein, ruf es aus onOverlayUpdate auf und nimm es danach wieder heraus:

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

Ruf sie als half(drift) auf. Die Funktion halbiert ihr number und gibt die Antwort zurück, und drift da draußen in onOverlayUpdate zählt weiter, als wäre nichts passiert. Eine Funktion kann nicht über einen Parameter hinausgreifen und die Variablen des Aufrufers ändern. Sie bekommt eine Kopie, und was sie mit der Kopie macht, ist ihre Sache.

Eine Antwort zurückgeben

half hat etwas getan, was die Funktionen, die du bisher geschrieben hast, nicht getan haben: Sie hat eine Antwort gegeben. Das ist die letzte Zeile.

    return number

return gibt einen Wert an den zurück, der die Funktion aufgerufen hat, und der Aufruf wird zu diesem Wert. Schreib smaller = half(drift), und Lua führt half aus, nimmt, was half zurückgegeben hat, und legt es in smaller. Du hast return in Lektion eins kennengelernt, wo onOverlayUpdate den Wert OVERLAY_UPDATED zurückgibt, um Singes Frage zu beantworten, ob sich etwas geändert hat. Das ist dasselbe Wort mit derselben Aufgabe, nur dass jetzt du derjenige bist, der die Frage stellt.

Die Zeile mit der Helligkeit bettelt geradezu darum, eine Funktion mit einer Antwort zu werden. Füg diese hier hinzu:

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

Der ganze Rumpf ist ein return, und das ist bei einer kleinen Funktion normal. Jetzt kann die innere Schleife die Antwort direkt an drawStar weitergeben, ohne einen Namen dazwischen:

            drawStar(starX, starY, shadeFor(layer))

Ein Aufruf in einem Aufruf. Lua rechnet zuerst den inneren aus, bekommt von shadeFor eine Zahl zurück und übergibt diese Zahl an drawStar als drittes Argument. So etwas hast du schon geschrieben, ohne es zu merken: Das math.floor(drift * layer * LAYER_SPEED) in Lektion vier ist ein Aufruf, dessen Antwort sofort an Ort und Stelle benutzt wird, mitten in einer größeren Rechnung.

Zwei Antworten auf einmal

Die beiden Zeilen für die Position sind schwieriger, weil es zwei Zahlen sind, die zusammen ausgerechnet werden, und du müsstest dir eine aussuchen, die du zurückgibst. In den meisten Sprachen kann eine Funktion einen Wert zurückgeben, und zwei herauszubekommen ist lästig. Lua lässt dich so viele zurückgeben, wie du willst.

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

Du fängst die Antworten auf, indem du links zwei Namen hinschreibst, durch ein Komma getrennt:

            local x, y = starAt(star, layer)

Der erste Wert kommt in den ersten Namen, der zweite in den zweiten. Gibst du weniger Namen an, als die Funktion zurückgibt, werden die übrigen Werte weggeworfen: local x = starAt(star, layer) gibt dir die waagerechte Zahl und verliert die senkrechte, ohne Beschwerde. Gibst du mehr Namen an, als es Werte gibt, sind die überzähligen nil.

Ignorier das Wort local in diesen beiden Blöcken noch eine Minute. Es bekommt gleich einen eigenen Abschnitt, und das ist der wichtige.

Das Sternenfeld in einer Zeile

Die innere Schleife besteht jetzt aus drei kurzen Zeilen, und alle drehen sich um eine Ebene von Sternen. Das ist eine Aufgabe mit einem Namen.

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

Und die äußere Schleife ist auch eine Aufgabe mit einem Namen:

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

Funktionen, die Funktionen aufrufen, die Funktionen aufrufen, drei Stufen tief, und jede ist drei oder vier Zeilen lang, die du auf einmal im Kopf behalten kannst. onOverlayUpdate kann jetzt sagen, was ein Frame ist:

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

Das ist das Versprechen vom Ende der Lektion vier, eingelöst.

Hol das Schiff zurück

Jetzt die fünfte Aufgabe, die, die aus dem alten onOverlayUpdate ein Durcheinander gemacht hätte. Hol das Kästchen zurück, das du in Lektion drei gesteuert hast, diesmal als Schiff, das nahe am unteren Bildschirmrand sitzt und sich nur nach links und rechts bewegt.

Es braucht ein paar eigene Werte, oben bei den anderen, und die beiden Eingabe-Callbacks aus Lektion drei, ohne die Zweige für oben und unten:

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

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


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

Es zu zeichnen sind zwei Zeilen, also ist es eine Funktion:

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

Beim Bewegen zahlt sich die Lektion aus. In Lektion drei hat es für jede Richtung vier Zeilen mit if und elseif gebraucht, um das Kästchen auf dem Bildschirm zu halten. Diese Idee — eine Zahl zwischen einer Untergrenze und einer Obergrenze halten — hat einen Namen, und der Name ist clamp:

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

Drei Rückgaben, und höchstens eine davon passiert je, denn return gibt nicht nur eine Antwort zurück: Es hält die Funktion auf der Stelle an. Nichts danach läuft. Liegt der Wert unter der Untergrenze, gib die Untergrenze zurück und hör auf. Liegt er über der Obergrenze, gib die Obergrenze zurück und hör auf. Sonst gib zurück, was hereingekommen ist.

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

Eine Funktion, die ohne return endet, gibt nichts zurück, und das ist nil. Das ist richtig für drawPlayer und movePlayer, die aufgerufen werden, um etwas zu tun, nicht um etwas zu beantworten. In einer Funktion wie clamp ist es ein Fehler: Lass das letzte return value weg, und jede Position mitten im Bereich kommt als nil zurück.

Wo Namen wohnen

Jeder Name, den du seit Lektion zwei angelegt hast, war eine globale Variable. Eine globale Variable gehört dem ganzen Programm: drift, playerX und LAYERS können von jeder Funktion in der Datei jederzeit gelesen und geschrieben werden, und sie bleiben da, solange das Spiel läuft.

Das klingt bequem, und bei sechs Namen ist es das auch. Der Ärger fängt bei sechzig an. Jede globale Variable ist ein Name, den sich das ganze Programm reserviert hat; wenn also irgendeine andere Funktion einen Platz für eine waagerechte Position braucht und ihn auch starX nennt, sind die beiden dieselbe Schublade, und jede überschreibt die Zahl der anderen. Wenn in einer globalen Variable etwas Falsches steht, kann es alles in der Datei dort hineingelegt haben, und um herauszufinden, was, musst du die ganze Datei lesen.

Eine lokale Variable ist das Gegenmittel. Schreib das Wort local vor einen Namen, wenn du ihn zum ersten Mal benutzt, und der Name existiert nur innerhalb der function, der Schleife oder des if, in dem er geschrieben wurde.

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

x und y gehen hier niemanden sonst etwas an. Eine andere Funktion kann ihr eigenes x haben, und die beiden begegnen sich nie. Wenn das x von starAt falsch ist, sind die drei Zeilen oben die einzigen drei Zeilen, die das gewesen sein können. Ohne das Wort local würden diese beiden Zeilen still zwei weitere globale Variablen anlegen, und genau das waren starX und starY die ganze Zeit.

Jetzt der Teil, der alle überrascht. Tipp diese Funktion ein und setz eine Zeile in onOverlayUpdate, die dir zeigt, was sie zurückgibt:

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

Count: 1, und es bleibt bei Count: 1, solange das Spiel läuft, obwohl die Funktion sechzigmal pro Sekunde aufgerufen wird und jedes Mal eins dazuzählt. Eine lokale Variable wird frisch angelegt, wenn die Funktion anfängt, und ist weg, wenn die Funktion endet; also wird counted als 0 geboren, wird zu 1 und stirbt, sechzigmal pro Sekunde, für immer. Eine lokale Variable merkt sich nichts. Nimm die beiden wieder heraus, wenn du es dir angesehen hast.

Das ist kein Mangel, sondern genau der Sinn: Eine lokale Variable kann nicht vom letzten Aufruf vergiftet werden, weil vom letzten Aufruf nichts übrig ist. Wenn du dir doch etwas von einem Aufruf zum nächsten merken musst (und drift und playerX müssen das), muss der Name außerhalb jeder Funktion wohnen. Setz ihn mit local davor an den Anfang der Datei:

local drift   = 0
local playerX = width // 2

Ein local ganz oben in der Datei, außerhalb aller Funktionen, lebt so lange wie das Skript und ist für jede Funktion darunter sichtbar. Auf das letzte Wort kommt es an: darunter. Eine lokale Variable existiert von ihrer eigenen Zeile an abwärts, also kann eine Funktion, die über der Zeile steht, die sie anlegt, sie nicht sehen. Dasselbe gilt für die Funktionen selbst, sobald du sie mit local markierst, und darum hat das fertige Skript die Reihenfolge, die es hat: zuerst die Werte, dann deine eigenen Funktionen, dann ganz zum Schluss die Callbacks.

Geh jetzt die ganze Datei durch und setz local vor jeden Namen, den du angelegt hast — die Konstanten in Großbuchstaben, width und height, drift, die vier Werte der Spielfigur und jede deiner eigenen Funktionen. Drei Namen bekommen es nicht: onInputPressed, onInputReleased und onOverlayUpdate müssen global bleiben, weil Singe sie über ihren Namen findet und ein lokaler Name von außerhalb der Datei unsichtbar ist.

Sei ehrlich zu dir, was lokale Variablen nicht reparieren. Lua beschwert sich nicht, wenn du dich bei einem Namen vertippst, dem du etwas zuweist — movinLeft = true statt movingLeft = true. Es legt eine brandneue globale Variable mit deinem Tippfehler als Namen an, setzt sie und lässt die echte in Ruhe. Nichts bewegt sich, nichts meldet einen Fehler, und du starrst zehn Minuten lang darauf. Davor retten dich lokale Variablen nicht. Den Namen zweimal zu lesen schon.

Das Ganze

Hier ist das fertige Programm, mit jedem Stück der Lektion darin.

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

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

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

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


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


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


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


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


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


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


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


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


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


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


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

Auf zwei Dinge lohnt es sich hinzuweisen, bevor du weitermachst.

local function drawStar(x, y, shade) markiert die Funktion selbst als lokal. Deine eigenen Funktionen sind Namen wie alle anderen, und sie gehören nur dieser Datei. Die drei Callbacks bleiben global, damit Singe sie finden kann.

Und onOverlayUpdate besteht jetzt aus sechs Zeilen, die sagen, was ein Frame ist: die Drift zählen, den Bildschirm löschen, die Spielfigur bewegen, den Himmel zeichnen, die Spielfigur zeichnen, fertig. Es erledigt fünf Aufgaben, indem es fünf Dinge beim Namen nennt, die jeweils eine Aufgabe erledigen, und das ist die Form jeder Spielschleife, die du je schreiben wirst.

Eine Funktion ist ein Name für eine Idee

clamp wird einmal aufgerufen. Sie herauszuziehen hat überhaupt keine Tipparbeit gespart — vier Zeilen kamen heraus, eine ging hinein, und anderswo ist eine Funktion mit neun Zeilen aufgetaucht. Es hat sich trotzdem gelohnt.

Eine Funktion ist nicht nur ein Weg, dich nicht zu wiederholen. Sie ist ein Weg, einer Idee einen Namen zu geben, damit der Code, der die Idee benutzt, den Namen sagen und weitermachen kann. „Halte die Spielfigur zwischen dem linken und dem rechten Rand“ ist ein Gedanke, den du einmal hattest. clamp(playerX, 0, width - PLAYER_WIDTH - 1) ist dieser Gedanke, aufgeschrieben. Vier if-Anweisungen sind derselbe Gedanke, zerlegt in Stücke, die du jedes Mal, wenn du sie liest, im Kopf wieder zusammensetzen musst.

Wenn du entscheidest, ob etwas es verdient, eine Funktion zu sein, frag nicht, wie oft du sie aufrufen wirst. Frag, ob es einen Namen hat.

Probier es aus

  1. Benenne einen Parameter um. Ändere in der Funktion drawStar überall x und y in across und down. Fass nichts außerhalb davon an. Starte es. Finde heraus, warum nichts kaputtgegangen ist.

  2. Zeichne sie andersherum. Vertausch drawStars() und drawPlayer() in onOverlayUpdate und sieh dir das Schiff an. Dann stell sie zurück. Jede dieser fünf Zeilen ist eine Aufgabe, und ihre Reihenfolge auf dem Bildschirm ist ihre Reihenfolge in der Funktion.

  3. Benutz clamp für eine Helligkeit. Ändere shadeFor zu return clamp(math.random(60, 90) + layer * 90, 0, 200) und sieh dir die drei Ebenen an. Dann nimm das clamp heraus und sieh noch einmal hin: colorForeground hat die Zahlen die ganze Zeit still für dich gedeckelt, und jetzt siehst du, wo.

  4. Ruf drawStar mit zwei Argumenten auf. Schreib drawStar(100, 100) irgendwo in drawLayer und starte es. Der Fehler nennt genau das, was gefehlt hat. Lies ihn, bevor du das dritte Argument wieder einsetzt.

  5. Verschieb eine lokale Variable. Nimm die Zeile local drift = 0 und schieb sie ans Ende der Datei, unter alles andere. Starte es, lies den Fehler und denk über das Wort „darunter“ im Abschnitt oben nach.

Mach es absichtlich kaputt

In einer Datei mit lokalen Variablen kommt es auf die Reihenfolge an, und der Fehler, den du bekommst, wenn du diese Reihenfolge durcheinanderbringst, ist nicht der, den du erwartest.

Nimm die ganze Funktion drawStar und schieb sie ans Ende des Skripts, unter onOverlayUpdate. Alles ist noch da, gleich geschrieben. Starte es:

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

Das sieht anders aus als der Fehler in Lektion eins, weil es eine andere Art von Fehler ist. Der Fehler aus Lektion eins wurde erwischt, bevor das Skript lief. Dieser hier wurde erwischt, während es lief, und darum nennt Singe die Funktion, in der es gerade steckte, und darum steht darunter ein Traceback: die Liste, wer wen aufgerufen hat, das Neueste zuerst. Zeile 50 liegt in drawLayer, das von Zeile 57 in drawStars aufgerufen wurde, das von Zeile 101 in onOverlayUpdate aufgerufen wurde. Deine Zeilennummern weichen ab, wenn deine Datei nicht genau mit der oben übereinstimmt, und die Engine hängt darunter vielleicht noch eine oder zwei eigene Zeilen an. Das Wort upvalue ist Luas Name für eine lokale Variable, die sich eine Funktion aus der Datei um sie herum geliehen hat; lies vorerst darüber hinweg.

Die Beschwerde selbst lohnt es sich auswendig zu lernen. „Attempt to call a nil value“ heißt, dass du Klammern hinter einen Namen gesetzt hast, in dem nichts stand. Das Wort global vor drawStar ist der Teil, der alles verrät: Du hast drawStar als lokal markiert, und als Lua drawLayer gelesen und nirgendwo darüber eine lokale Variable dieses Namens gefunden hat, blieb nur noch, es mit einer globalen zu versuchen — und eine globale namens drawStar gibt es auch nicht. Setz die Funktion wieder über den Code, der sie aufruft, und der Fehler verschwindet.

Was du gelernt hast

  • Du kannst eigene Funktionen schreiben, und nichts führt sie aus außer deinen eigenen Aufrufen.

  • Die Namen in den Klammern einer Funktion sind Parameter, und sie sind die eigenen Kopien der Funktion von dem, was der Aufrufer übergeben hat.

  • return gibt einen Wert zurück und hält die Funktion an der Stelle an, und eine Funktion, die ohne ein solches endet, gibt nil zurück.

  • Ein Aufruf kann ein Argument eines anderen Aufrufs sein, und der innere passiert zuerst.

  • Lua kann mehr als einen Wert zurückgeben, und du fängst sie mit mehreren Namen auf, durch Kommas getrennt.

  • local legt einen Namen an, der nur dort existiert, wo er geschrieben wurde.

  • Eine lokale Variable in einer Funktion wird bei jedem Aufruf frisch angelegt und merkt sich nichts vom letzten.

  • Eine lokale Variable ist nur unterhalb der Zeile sichtbar, die sie anlegt, also kommen Werte und deine eigenen Funktionen über die Callbacks, die sie benutzen.

  • Callbacks bleiben global, weil Singe sie über ihren Namen findet.

  • Eine Funktion lohnt sich, wenn das, was sie tut, einen Namen hat, auch wenn du sie nur einmal aufrufst.

Beim nächsten Mal

Deine hundertzwanzig Sterne sind immer noch hundertzwanzig Kopien von drei Ideen. Nichts im Programm ist ein Stern: Es gibt eine Zahl und etwas Rechnerei, die aus der Zahl eine Position macht. Du kannst nicht sagen „dieser hier ist näher, also fällt er schneller und leuchtet heller“, weil es kein „dieser hier“ gibt, über das du es sagen könntest, und du kannst keinen Stern unten herausfallen und durch einen neuen ersetzen lassen, weil da nichts ist, was man entfernen könnte.

Lektion sechs gibt dir das Ding, das einen Stern festhält, und dann einen Weg, hundertzwanzig davon festzuhalten und einen hunderteinundzwanzigsten hinzuzufügen, während das Spiel läuft. Es ist die nützlichste Lektion in diesem Teil des Buchs.

Lektion 6: Listen von Dingen

Die fertige Lektion

Du hast hundertzwanzig Sterne, und keiner davon existiert. Nirgends in deinem Programm gibt es einen Stern: Es gibt eine Schleife, die hundertzwanzigmal läuft, und bei jedem Durchlauf rechnet sie aus der Nummer des Sterns und seiner Ebene zwei Zahlen aus, setzt ein Pixel und vergisst alles. Die drei Ebenen sind da, um das eine vorzutäuschen, was diese Anordnung nicht kann: einen Stern anders sein zu lassen als seinen Nachbarn.

Diese Lektion gibt dir, was fehlt. Du lernst, wie du eine Liste von Dingen aufbewahrst, wie du ein Ding machst, das mehrere benannte Werte auf einmal hält, und dann, wie du beides zu einer Liste von Dingen zusammensetzt, von denen sich jedes seine eigene Position, Geschwindigkeit und Helligkeit merkt. Es ist die längste Lektion in diesem Teil des Buchs und die, auf die sich alles Spätere stützt. Lass dir Zeit damit.

Leg einen neuen Ordner an

Ein Ordner namens tables, darin eine Datei namens tables.singe, und in einem Terminal läuft Singe -R tables. Kopier das fertige Programm aus Lektion fünf hinein: das Sternenfeld, das Raumschiff und alles andere.

Eine Liste

Füg diese Zeile oben in tables.singe ein, unter den anderen Werten, und die drei Aufrufe von overlayPrint in onOverlayUpdate, über dem return.

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

Starte es. Ada in einer Zeile, Alan in der nächsten und There are 3 names. darunter.

Die geschweiften Klammern in der ersten Zeile machen eine Tabelle. Eine Tabelle ist der eine Behälter, den Lua hat, und alles, wovon du je mehr als eins aufbewahrst, kommt in eine. Hier hält sie drei Strings hintereinander, und diese Form nennt man eine Liste.

Die eckigen Klammern in den nächsten Zeilen holen einen Eintrag heraus. names[1] ist der erste Eintrag, names[3] der dritte, und die Zahl in den Klammern heißt Index.

Bei dieser Zahl trennen sich die Wege von Lua und fast jeder anderen Sprache, der du begegnen wirst. Lua zählt ab eins. C, Java, Python, JavaScript und die meisten anderen zählen ab null, also ist ihr erster Eintrag Eintrag null und ihr dritter Eintrag Index zwei. Der erste Eintrag von Lua ist Eintrag eins, und das ist genau das eine, worüber Programmierer stolpern, die von woanders herkommen. Du kommst von nirgendwo, also hast du es leichter: Der erste ist Nummer eins.

names[0] ist übrigens kein Fehler. Dort ist nichts gespeichert, also ist es nil — der Nichts-Wert aus Lektion drei. Ein Index, der nie gefüllt wurde, liefert beim Lesen immer nil, und das ist eine Freundlichkeit, bis zu dem Moment, in dem du versuchst, es zu benutzen.

Das # vor dem Namen einer Tabelle ist für eine Weile das letzte neue Satzzeichen. Es gibt dir, wie viele Einträge in der Liste sind, also ist #names gleich 3. Weil die Anzahl und der letzte Index dieselbe Zahl sind, ist names[#names] immer der letzte Eintrag, egal wie lang die Liste wird.

Hinzufügen und Wegnehmen

Eine Liste, die du komplett ausschreiben musst, nützt einem Spiel nicht viel. Mit diesen beiden Aufrufen ändert sich eine Liste, während das Programm läuft.

    table.insert(names, "Katherine")

Das hängt Katherine hinten an, und #names ist jetzt 4. table.insert ist eine Funktion wie jede andere, und der Punkt in der Mitte ihres Namens bedeutet, dass sie in einer Tabelle namens table wohnt, die Lua mitbringt — einer Tabelle voller Funktionen, die mit Tabellen arbeiten. Du musst sie weder anlegen noch laden. Sie ist da.

Gib table.insert drei Argumente, und das mittlere sagt, wohin der neue Eintrag kommt.

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

Edsger kommt vorne hinein, und alles, was schon da war, rückt auf, um Platz zu machen: Ada war Eintrag eins und ist jetzt Eintrag zwei. Nichts wird überschrieben, und nichts geht verloren.

Einen Eintrag herauszunehmen ist das Spiegelbild.

    table.remove(names, 2)

Eintrag zwei verschwindet, und alles dahinter rückt nach, um die Lücke zu schließen, sodass die Liste nie ein Loch in der Mitte hat. table.remove gibt außerdem den Eintrag zurück, den es herausgenommen hat, also wirft local gone = table.remove(names, 2) ihn weg und sagt dir in einer Zeile, was er war. Lass die Zahl ganz weg — table.remove(names) — und es nimmt den letzten Eintrag, und so benutzt du eine Liste am schnellsten als Stapel.

Setz diese drei Aufrufe nacheinander in dein Skript, starte es nach jedem und sieh zu, wie sich die Anzahl in der dritten Zeile ändert.

Eine Liste durchlaufen

Eine Möglichkeit, jeden Eintrag zu besuchen, kennst du schon, denn du benutzt sie seit Lektion vier:

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

Das funktioniert. Bei eins anfangen, bei der Anzahl aufhören, den Zähler als Index benutzen. Es gibt einen besseren Weg, und so wirst du es ab jetzt schreiben:

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

ipairs läuft eine Liste ab Eintrag eins durch, bis sie zu Ende ist, und gibt deiner Schleife bei jedem Durchlauf zwei Dinge: den Index und den Eintrag selbst. Auf das zweite kommt es an. Mit dem zählenden for bekommst du eine Zahl und musst mit names[i] zurück zur Tabelle, um herauszufinden, was dort steht; mit ipairs hast du den Eintrag schon in der Hand, unter dem Namen, den du als zweiten hinschreibst.

Außerdem kann man es schwerer falsch machen. for i = 1, #names ist eine Stelle, an der man sich leicht um eins verzählt — fang bei null an, und du gibst ein nil aus, hör bei #names - 1 auf, und dir fehlt der letzte — und in ipairs steht überhaupt keine Zahl, die man falsch machen könnte.

Meistens willst du gar nicht den Index, nur den Eintrag. Schreib den Index als einzelnen Unterstrich, und fertig:

    for _, name in ipairs(names) do

_ ist ein ganz gewöhnlicher Name, und nichts in Lua behandelt ihn besonders. Es ist eine Gewohnheit, mit der Programmierer sagen: „Hier kommt etwas an, und ich werde es nicht benutzen.“ Wer deine Schleife liest, weiß auf einen Blick, dass der Index darin keine Rolle spielt.

Lösch jetzt die Versuche mit names und mit ihnen die Zeilen mit overlayPrint. Du weißt, was eine Liste ist. Zeit, etwas Besseres als einen String hineinzulegen.

Eine Tabelle kann auch ein Datensatz sein

Ein Stern muss sich vier Dinge merken: wo er waagerecht ist, wo er senkrecht ist, wie schnell er fällt und wie hell er ist. Vier getrennte Listen, die du alle von Hand im Gleichschritt halten musst, wären furchtbar. Mach stattdessen eine Tabelle und leg Namen hinein.

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

Die leeren geschweiften Klammern machen eine leere Tabelle. Die vier Zeilen danach legen Werte hinein, unter Namen statt unter Nummern, und mit dem Punkt sagst du, welchen Namen du meinst. star.x liest man als das x von star, und es verhält sich genau wie jede andere Variable: Lies es, weise ihm etwas zu, zähl etwas dazu.

    star.y = star.y + star.speed

Eine so benutzte Tabelle — eine feste Menge benannter Werte, die ein Ding beschreiben — ist ein Datensatz, und die Namen darin sind seine Felder. Es ist dieselbe Art Tabelle wie die Liste oben. Der einzige Unterschied ist, dass man die Einträge einer Liste über eine Nummer findet und die Felder eines Datensatzes über einen Namen, und eine Tabelle kann beides gleichzeitig, falls du das je willst.

Der Punkt ist eine Kurzschreibweise. star.x und star["x"] bedeuten genau dasselbe, und das solltest du einmal gesehen haben: Die eckigen Klammern nehmen einen Namen genauso gern wie eine Zahl, also sind eine Liste und ein Datensatz wirklich eine Idee mit zwei Hüten. Benutz den Punkt. Er liest sich besser.

Ein Feld, das du nie gesetzt hast, ist nil, genau wie ein Index, den du nie gefüllt hast. Es gibt nirgends eine Liste erlaubter Feldnamen, und nichts prüft deine Rechtschreibung, also ist star.sped kein Fehler — es ist nil, und was dann passiert, lernst du am Ende dieser Lektion kennen.

Vier Zeilen zu schreiben, um vier Felder zu füllen, wird schnell langweilig. Du kannst die Felder gleich beim Anlegen der Tabelle in die geschweiften Klammern schreiben:

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

Dieselbe Tabelle, eine Anweisung. Die Kommas trennen die Felder, hinter dem letzten braucht es kein Komma, und die Zeilen sind nur so verteilt, damit man sie leicht lesen kann.

Eine Liste von Datensätzen

Hier ist die ganze Idee dieser Lektion in zwei Zeilen:

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

Eine Liste kann alles halten, auch eine Tabelle. Eine Liste von Datensätzen ist also eine Liste von Dingen, von denen sich jedes alles über sich selbst merkt. stars[1] ist ein ganzer Stern, und stars[1].y ist, wie weit unten auf dem Bildschirm dieser Stern steht. Fast jedes Spiel, das du je schreibst, ist eine Handvoll solcher Listen: die Gegner, die Schüsse, die Extras und die fallenden Blöcke.

Eine Sache über Tabellen musst du wissen, bevor du den Code schreibst, und sie erwischt jeden einmal. Wenn du einer Funktion eine Tabelle übergibst, wird sie nicht kopiert. Eine Zahl wird kopiert — darum konnte half in Lektion fünf ihre number zerhacken, ohne drift zu stören — aber eine Tabelle wird geteilt. Beide Namen verweisen auf dieselbe Tabelle, und eine Änderung über den einen ist über den anderen zu sehen.

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

Das bewegt den dritten Stern in der Liste. Keine Kopie davon: ihn selbst. Genau das willst du hier, und genau das lässt den nächsten Abschnitt funktionieren, aber denk daran, wenn eine Funktion, die du geschrieben hast, etwas ändert, bei dem du das nicht erwartet hast.

Bau das Sternenfeld neu

Die Rechnerei fliegt raus. Ein Stern wird gleich zu einem Ding.

Lösch starAt, shadeFor, drawLayer und das alte drawStar und mit ihnen die Konstanten, die sie benutzt haben: LAYERS, STARS_PER_LAYER, ACROSS_STEP, DOWN_STEP, LAYER_SHIFT und LAYER_SPEED. Die Variable drift fliegt auch raus, und ebenso die Zeile mit drift oben in onOverlayUpdate. LAYER_BRIGHT bleibt, unter einem Namen, der keine Ebenen mehr erwähnt, und zwei Werte kommen dazu:

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

Hundertzwanzig hattest du vorher auch: drei Ebenen zu je vierzig. Die Liste fängt leer an, und das hier füllt sie:

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

newStar macht einen Stern und gibt ihn zurück. Sieh dir das letzte Feld an und vergleich es mit shadeFor aus Lektion fünf: dieselbe Rechnung, mit der eigenen Geschwindigkeit des Sterns dort, wo früher die Nummer der Ebene stand. Die Ebenen sind nicht so sehr verschwunden als vielmehr aufgelöst. Jeder Stern sucht sich jetzt seine eigene Geschwindigkeit aus, ein, zwei oder drei Pixel pro Frame, und ein Stern, der schneller fällt, ist heller; das ist die ganze Illusion von Tiefe, und sie kostet eine Zeile.

Das anfängliche y ist ein Parameter, weil die beiden Aufrufer Verschiedenes wollen. Die Sterne, die beim Start des Spiels entstehen, sollen über den ganzen Bildschirm verstreut sein; die, die später entstehen, kommen oben herein.

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

Noch ruft nichts makeStars auf. Füg ganz unten in der Datei eine Zeile hinzu, nach allem anderen und in überhaupt keiner Funktion:

makeStars()

Über diese Zeile gibt es noch mehr zu sagen, und das wartet bis zum Ende der Lektion. Jetzt das Zeichnen, das jedes Mal kürzer wird, wenn du es anfasst:

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


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

drawStar hat in Lektion fünf drei Zahlen bekommen und bekommt jetzt einen Stern. Alles, was es wissen muss, steckt im Stern, und genau darum gibt es überhaupt Datensätze: ein Ding zum Herumreichen statt vier, und keine Gefahr, sie in der falschen Reihenfolge zu übergeben. Und drawStars hat seine Schleife über die Ebenen verloren, zusammen mit jedem Interesse daran, wie viele Sterne es gibt oder woher sie kommen.

Sterne, die kommen und gehen

Jetzt der Teil, den das alte Sternenfeld überhaupt nicht konnte. Sterne fallen mit ihrer eigenen Geschwindigkeit, verschwinden unten und werden oben ersetzt.

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

Ruf sie in onOverlayUpdate auf, in der Zeile, in der früher drift = drift + 1 stand.

Jeder Stern bewegt sich um seine eigene speed nach unten, und das ist die Zeile, die Lektion fünf nicht schreiben konnte. Das while unten ist das Auffüllen: Solange es weniger als hundertzwanzig Sterne gibt, mach oben auf dem Bildschirm einen neuen. Es läuft so oft, wie es muss, und hört dann auf, und das ist das richtige Werkzeug, wenn du nicht weißt, wie viele fehlen.

Die for-Zeile oben zählt rückwärts, mit der Schrittweite, die du in Lektion vier kennengelernt hast. for i = #stars, 1, -1 besucht zuerst den letzten Eintrag und arbeitet sich zurück bis Eintrag eins. Das ist keine Verzierung. Es ist der einzige sichere Weg, das zu tun, was diese Schleife tut, und der nächste Abschnitt erklärt, warum.

Nie vorwärts entfernen

Schreib dieselbe Schleife vorwärts, und sie ist kaputt:

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

Geh sie von Hand mit vier Sternen durch, und nimm an, dass die Sterne zwei und drei beide unten angekommen sind.

  • i ist 1. Stern eins ist in Ordnung.

  • i ist 2. Stern zwei ist unten hinaus, also fliegt er raus. Alles rückt nach: Der Stern, der drei war, ist jetzt zwei, und der Stern, der vier war, ist jetzt drei.

  • i ist 3. Das ist der Stern, der früher vier war. Stern drei wurde nie angesehen. Das Entfernen von Eintrag zwei hat ihn auf Platz zwei rücken lassen, und die Schleife war schon bei Platz zwei gewesen und weitergezogen.

  • i ist 4. Es gibt keinen Eintrag vier mehr. stars[4] ist nil.

Zwei getrennte Fehler aus einem kleinen Versehen. Einträge werden übersprungen, also wird ein Stern, der unten angekommen war, diesmal nicht einmal angesehen. Ein Stern, der einen Frame länger überlebt, schadet niemandem, aber dieselbe Schleife über eine Liste von Gegnern, die erst das Ansehen tötet, ist ein Fehler, dem du eine Stunde lang hinterherjagst. Der zweite Fehler ist lauter. Die Liste ist jetzt kürzer als die Anzahl, mit der die Schleife angefangen hat, weil #stars einmal ausgerechnet wurde, vor jedem Entfernen, und so greifen die letzten Durchläufe der Schleife über das Ende der Liste hinaus:

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

„Attempt to index a nil value“ heißt, dass du einen Punkt hinter etwas gesetzt hast, in dem nichts war. Das (local 'star') am Ende nennt es beim Namen: star war nil, also hatte star.y keinen Ort, an dem es nachsehen konnte.

Rückwärts zu laufen behebt beide Fehler auf einmal, und es lohnt sich zu sehen, warum, statt es einfach zu glauben. Wenn du Eintrag i entfernst, rückt alles hinter i einen Platz nach unten — und wenn du rückwärts läufst, ist alles hinter i genau das, was du schon besucht hast. Was noch kommt, die Einträge i - 1 bis hinunter zu 1, hat sich überhaupt nicht bewegt. Dass die Liste hinter dir schrumpft, kann dir auch nicht schaden, denn du läufst auf Eintrag eins zu, und Eintrag eins ist immer da.

Die Regel, die du für den Rest deines Lebens benutzen wirst: Wenn eine Schleife Einträge aus der Liste entfernen könnte, die sie durchläuft, lauf sie rückwärts durch.

ipairs ist keine Ausnahme davon. Einträge mitten in einer ipairs-Schleife zu entfernen geht auf dieselbe Weise schief. ipairs ist zum Ansehen da, und das rückwärts laufende for zum Ändern.

Füg selbst welche hinzu

Noch ein Zweig in onInputPressed, und du kannst zusehen, wie die Liste wächst, während das Spiel läuft. Das kommt zu den anderen beiden:

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

addBurst kommt über die Callbacks, zu deinen anderen Funktionen. Und damit du siehst, wie sich die Länge der Liste ändert, bring die Anzahl in onOverlayUpdate auf den Bildschirm:

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

Drück den Knopf — die Leertaste, außer du hast geändert, woher SWITCH_BUTTON1 kommt — ein Dutzend Mal. Die Anzahl steigt mit jedem Drücken um zehn, und der Himmel wird dichter, und solange du ihn gedrückt hältst, wiederholt sich nichts: onInputPressed erfährt es einmal, wenn der Knopf nach unten geht. Dann sieh zu, wie die Anzahl von selbst auf hundertzwanzig zurückgeht, während die zusätzlichen Sterne unten ankommen und entfernt werden, denn das Auffüllen füllt die Liste immer nur bis STAR_COUNT auf und kürzt sie nie.

Weder dem Zeichnen noch dem Bewegen noch dem Entfernen musste jemand sagen, dass sich die Zahl der Sterne geändert hat. Sie arbeiten alle mit der Liste.

Das Ganze

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

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

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

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


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


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


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


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


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


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


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


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


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


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


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


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


makeStars()

Was gerade passiert ist

Das Programm ist kürzer als das aus Lektion fünf, und es tut etwas, woran Lektion fünf nicht einmal denken konnte. Drei Stücke sind einen zweiten Blick wert.

makeStars()

Diese einzelne Zeile ganz unten in der Datei steht in keiner Funktion, und man übersieht sie leicht. Lua liest deine Datei von oben nach unten, wenn Singe sie lädt, und eine Zeile ganz außen in der Datei läuft sofort an Ort und Stelle, einmal, bevor die Engine irgendetwas aufgerufen hat. Alles darüber sind Definitionen — hier ist ein Wert, hier ist eine Funktion — und das hier ist die eine Anweisung, die beim Laden passiert. Sie muss ganz unten stehen, weil es makeStars erst gibt, wenn die Zeile gelesen wurde, die es erzeugt.

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

star ist eine lokale Variable, die bei jedem Durchlauf der Schleife neu entsteht, und sie hält dieselbe Tabelle, die in der Liste liegt — keine Kopie davon. star.y zu ändern bewegt den Stern, der in der Liste steht. Würden Tabellen kopiert, würde diese Schleife pro Frame hundertzwanzig Kopien bewegen, und auf dem Bildschirm würde sich nie etwas ändern.

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

Vergleich das mit Lektion vier: zwei verschachtelte Schleifen, zwei Rechnungen pro Stern, ein Rest, damit jeder auf dem Bildschirm bleibt, und drei Ebenen, um die Vielfalt vorzutäuschen, die du jetzt umsonst bekommst. Das Zeichnen weiß nicht mehr und kümmert sich nicht mehr darum, wie die Sterne dorthin gekommen sind, wo sie sind, wie viele es gibt oder was als Nächstes mit ihnen passiert. Jeder Teil des Programms erledigt eine Aufgabe, und die Liste ist das, worauf sich alle einigen.

Probier es aus

  1. Mehr Tiefe. Ändere math.random(1, 3) in math.random(1, 6) und STAR_SHADE in 25. Mehr Geschwindigkeiten, mehr Helligkeitsstufen, ein tieferer Himmel.

  2. Weniger Sterne, größerer Schwung. Setz STAR_COUNT auf 10 und BURST_COUNT auf 100, dann drück den Knopf drei- oder viermal. Sieh zu, wie die Anzahl auf dem Bildschirm steigt, und miss, wie lange es dauert, bis sie wieder abgeflossen ist.

  3. Gib einem Stern ein weiteres Feld. Füg age = 0 in newStar hinzu, zähl in moveStars eins zu star.age dazu und bring stars[1].age neben der Anzahl auf den Bildschirm. Sonst muss sich nichts im Programm ändern, damit es eine neue Tatsache über jeden Stern mitträgt.

  4. Hör auf, sie zu entfernen. Lösch die drei Zeilen des Blocks if star.y >= height aus moveStars und starte es. Warte zehn Sekunden, dann lies die Anzahl auf dem Bildschirm und sieh dir den Himmel an. Finde heraus, wie beides gleichzeitig wahr sein kann.

  5. Mach es vorwärts. Ändere for i = #stars, 1, -1 in for i = 1, #stars und lass es laufen, bis es umfällt. Dann lies den Abschnitt oben noch einmal, mit dem echten Fehler vor Augen.

Mach es absichtlich kaputt

Schreib einen Feldnamen falsch. Ändere in moveStars das star.speed in star.sped:

        star.y = star.y + star.sped

Starte es:

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

Deine Zeilennummern werden nicht genau diese sein, außer deine Datei stimmt Zeile für Zeile mit der oben überein. Was du liest, sind der Name der Datei, die Zahl dahinter und die Beschwerde.

Lies zuerst das Ende der ersten Zeile. Mit field 'sped' sagt dir Lua, welcher Name leer ausging, und es sagt dir, dass es ein Feld war — etwas hinter einem Punkt — und keine eigene Variable von dir. „Attempt to perform arithmetic on a nil value“ ist das, was es gerade tat, als es das merkte: nil zu einer Zahl addieren, und das geht nicht.

Es gab keine Beschwerde, als die Tabelle ohne ein Feld sped gemacht wurde, und keine in dem Moment, in dem du danach gefragt hast. Eine Tabelle gibt für jeden Namen, den sie nicht hat, kommentarlos nil heraus. Der Fehler kommt später, in der ersten Zeile, die versucht, das Nichts, das du bekommen hast, zu benutzen, und die kann weit von dem Tippfehler entfernt sein. Wenn du nil value (field 'something') siehst, such die Stelle, an der dieser Name anders geschrieben wurde.

Was du gelernt hast

  • Geschweifte Klammern machen eine Tabelle, den einen Behälter, den Lua hat. Eine Tabelle, die als Liste benutzt wird, hält Einträge hintereinander, und eckige Klammern mit einem Index holen einen heraus.

  • Lua zählt ab eins. Die meisten anderen Sprachen zählen ab null.

  • #list ist die Anzahl der Einträge darin, und list[#list] ist der letzte.

  • table.insert fügt einen Eintrag hinzu, am Ende oder an einer Stelle, die du nennst; table.remove nimmt einen heraus und schließt die Lücke.

  • Ein Index oder ein Feld, das nie gefüllt wurde, ist nil, und nichts warnt dich, bis du es benutzt.

  • ipairs läuft eine Liste durch und gibt dir den Index und den Eintrag; _ ist die übliche Schreibweise für einen Index, den du nicht willst.

  • Eine Tabelle, die als Datensatz benutzt wird, hält benannte Felder, die du mit einem Punkt erreichst.

  • In einer Liste von Datensätzen bewahrt ein Spiel seine Gegner auf, seine Schüsse und alles andere, wovon es mehr als eins gibt.

  • Tabellen werden geteilt, nicht kopiert, wenn du sie herumreichst.

  • Wenn eine Schleife Einträge aus der Liste entfernen kann, die sie durchläuft, lauf sie rückwärts durch.

Beim nächsten Mal

Du hast jetzt alle Teile eines Spiels: Dinge, die sich bewegen, ein Raumschiff, das auf die Steuerung hört, Entscheidungen, Schleifen, Funktionen und eine Liste, in die Dinge hinein- und aus der sie wieder hinausgehen können, während das Spiel läuft.

Lektion sieben setzt sie zu einem Spiel zusammen, das du verlieren kannst. Du steuerst am unteren Rand des Bildschirms entlang, von oben fallen Blöcke, und du gehst ihnen aus dem Weg — und die fallenden Blöcke sind eine Liste von Datensätzen, gemacht, bewegt und entfernt genau wie deine Sterne.

Lektion 7: Ein Spiel

Die fertige Lektion

Vor sechs Lektionen hast du ein Wort auf einen schwarzen Bildschirm gebracht. Seitdem hast du jede Idee gelernt, aus der ein kleines Spiel besteht: Variablen, Entscheidungen, Schleifen, eigene Funktionen und Listen von Dingen. Diese Lektion bringt dir keine neue Idee bei. Sie gibt die aus, die du schon hast.

Du baust ein Spiel namens Dodge. Blöcke fallen vom Himmel, du schiebst einen Balken am unteren Rand entlang, um ihnen aus dem Weg zu gehen, und jeder Block, der dich verfehlt, ist ein Punkt. Erwischen dich drei davon, ist es vorbei. Du baust es in sechs Schritten, und jeder davon läuft: Du musst nie hundert Zeilen abtippen und hoffen.

Leg den Ordner an

Leg einen Ordner namens dodge an und darin eine Datei namens dodge.singe. Starte es so, wie du seit Lektion eins alles startest:

Singe -R dodge

Lass das die ganze Lektion über in einem Terminal laufen. Jedes Mal, wenn du speicherst, startet das Spiel mit deiner Änderung neu.

Schritt eins: Etwas, das du steuern kannst

Tipp das ein, speichere und steuere es mit den Pfeiltasten nach links und rechts.

dofile("Singe/Framework.singe")

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

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

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


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


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


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

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

Fünfzig Zeilen, und fast nichts davon ist neu. Zwei Dinge darin schon, also nimm dir zuerst die erste Zeile vor.

dofile("Singe/Framework.singe")

dofile gehört zu Lua, nicht zu Singe, und es bedeutet „geh und führ diese Datei aus, dann mach hier weiter“. Die Datei, die es ausführt, ist Singe/Framework.singe, eine der Dateien, die die Engine in deinen Arbeitsordner entpackt hat, als du in Lektion eins zum ersten Mal irgendetwas gestartet hast. Öffne sie in deinem Texteditor und sieh hinein: Es ist gewöhnliches Lua, nicht anders als das, was du seit Lektion zwei schreibst, und es steckt nichts Magisches darin.

Sie auszuführen gibt deinem Skript eine Reihe von Namen, die es danach benutzen kann. Zu diesen greift dieses Buch:

  • DIR, in dem der Ordner steht, in dem dein eigenes Skript liegt. Lektion neun braucht es, sobald ein Spiel ein Bild lädt, und es ist der eigentliche Grund, warum diese Zeile hier steht.

  • SCANCODE und MODIFIER, Namen für jede Taste einer Tastatur, für ein Spiel, das Getipptes liest statt eines Joysticks.

  • GAMEPAD_0 bis GAMEPAD_3 und MOUSE_0 bis MOUSE_3, für einen Automaten, an dem von etwas mehr als eins angeschlossen ist.

  • Ein paar Helfer, deren Namen mit util anfangen, und die sechs Aufrufe, die eine Punktzahl an eine Bestenliste schicken; das ist Lektion achtundzwanzig.

  • Die zweite, ganz andere Art, ein Spiel zu schreiben; das ist Lektion fünfzehn.

Eine Sache gibt es dir nicht, auch wenn man das ganz natürlich annimmt. SWITCH_LEFT und jeder andere Name, der mit SWITCH_ anfängt, kommt von der Engine selbst, bevor überhaupt ein Skript läuft. Darum konnten die Lektionen drei bis sechs die Pfeiltasten abfragen, ohne etwas zu laden. Das Framework ergänzt, was schon da ist; es liefert es nicht.

Dieses Spiel hier benutzt nichts aus dem Framework. Die Zeile steht da, weil jedes Spiel von Lektion neun bis zum Ende des Buchs sie sehr wohl braucht, und weil fast jedes echte Singe-Spiel so anfängt. Sie wird einmal gelesen, beim Start, und dann vergessen.

Das zweite Neue ist, wie die Pfeiltasten behandelt werden, denn das ist das Erste, was Anfänger falsch machen.

onInputPressed bewegt die Spielfigur nicht. Es setzt goingLeft auf true, und onInputReleased setzt es wieder auf false. Das Bewegen passiert in onOverlayUpdate, das sechzigmal pro Sekunde fragt: „Hält der Spieler links gedrückt?“ Würdest du die Spielfigur stattdessen in onInputPressed bewegen, bekämst du einen Schritt pro Druck: Singe meldet ein Drücken genau einmal, wenn die Taste nach unten geht, und wiederholt es nie, und der Eintrag zu onInputPressed in der Referenz sagt das klar und deutlich. Die Taste zu halten würde überhaupt nichts tun.

Der Callback fürs Drücken hält also fest, was über die Welt wahr ist, und das Update entscheidet, was damit geschieht. Bleib bei dieser Trennung, und dein Eingabecode bleibt für immer fünf Zeilen lang.

Die vier Namen in Großbuchstaben sind gewöhnliche Variablen. PLAYER_SPEED in Großbuchstaben zu schreiben ist eine Nachricht an dich selbst und an jeden, der mitliest: Dieser Wert wird einmal oben gesetzt und ändert sich nie. Nichts in Lua erzwingt das. Es ist wichtig, weil es gleich zehn davon geben wird, und wenn das Spiel zu schwer ist, willst du eine offensichtliche Stelle haben, an der du eine Zahl herunterdrehst.

screenWidth und screenHeight kommen von der Engine, statt eingetippt zu werden, also richtet sich das Spiel nach der Größe, die das Overlay gerade hat. playerY wird einmal aus der Höhe ausgerechnet: Der Balken sitzt PLAYER_MARGIN Pixel über dem unteren Rand und bewegt sich nie nach oben oder unten, also gibt es keinen Grund, es in jedem Frame neu auszurechnen.

Das - 1 in der Zeile mit overlayBox ist kein Tippfehler. overlayBox zeichnet durch beide Ecken, die du ihm gibst, also ist ein Kasten von playerX bis playerX + 40 einundvierzig Pixel breit. Eins abzuziehen macht den Balken, den du siehst, genau vierzig breit, und das wird in Schritt vier wichtig, wenn etwas entscheiden muss, ob es dich berührt hat.

Schritt zwei: Etwas zum Ausweichen

Ein Block, der fällt. Füg der Liste oben zwei Konstanten hinzu:

local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5

Zwei weitere Variablen unter goingRight:

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

Lass ihn in onOverlayUpdate fallen, direkt über der Zeile overlayClear():

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

Und zeichne ihn unter der Zeile, die die Spielfigur zeichnet:

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

Speichere. Ein rotes Quadrat fällt, kommt unten an und taucht oben an einer neuen Stelle wieder auf.

Er fängt bei -BLOCK_SIZE an, und das ist über dem oberen Rand des Bildschirms. An einer negativen Position ist nichts falsch: Die Engine zeichnet den Teil des Kastens, der auf dem Overlay liegt, und wirft den Rest stillschweigend weg. Der Block gleitet ins Bild, statt plötzlich aufzutauchen.

BLOCK_SPEED ist 1.5, keine ganze Zahl, also ist blockY die meiste Zeit so etwas wie 83.5. Auch das ist in Ordnung. Beim Zeichnen wird der Bruchteil abgeschnitten, und weil er in der Variablen bleibt, kann sich der Block langsamer als ein Pixel pro Frame bewegen.

Schritt drei: Ein Himmel voll davon

Ein Block ist kein Spiel. In Lektion sechs hast du gelernt, viele von etwas in einer Liste aufzubewahren, und genau dafür war das gut.

Lösch blockX und blockY und setz an ihre Stelle das hier:

local blocks     = {}
local spawnTimer = 0

Füg oben noch eine Konstante hinzu:

local SPAWN_FRAMES  = 40

Jetzt eine Funktion, die einen Block macht und ihn in die Liste legt. Setz sie über onInputPressed:

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

Ersetze den Fall-Code aus Schritt zwei durch das hier:

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

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

Und ersetze die eine Zeile, die den Block gezeichnet hat, durch eine Schleife über alle:

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

Speichere. Es regnet Blöcke.

Ein Block ist ein Datensatz: eine kleine Tabelle mit einem x und einem y darin, und so verhinderst du, dass zwei Zahlen, die zusammengehören, auseinanderdriften. blocks ist eine Liste solcher Datensätze, und diese Form hat die Welt fast jedes Spiels.

spawnTimer zählt pro Frame um eins herunter, und wenn er null erreicht, wird ein Block geboren und der Timer wieder aufgezogen. Vierzig Frames sind etwa zwei Drittel einer Sekunde. In diesem Spiel gibt es keine Uhr, und es braucht auch keine: onOverlayUpdate ist der Herzschlag, und Herzschläge zu zählen ist eine völlig brauchbare Art, Zeit zu messen.

Die Fall-Schleife läuft rückwärts — von #blocks hinunter bis 1, Schritt für Schritt — weil sie unterwegs Dinge entfernt. Das ist die Regel aus Lektion sechs, und jetzt hast du zum ersten Mal einen echten Grund, sie zu befolgen. Entfernst du beim Vorwärtslaufen Eintrag drei, rückt alles um eins nach, also ist der Block, der Eintrag vier war, jetzt Eintrag drei, und die Schleife sieht ihn nie an. Beim Rückwärtslaufen ist alles, was sich verschiebt, schon erledigt.

Die Zeichenschleife benutzt dagegen ipairs, weil sie nichts entfernt und nur einen Block nach dem anderen haben will.

Schritt vier: Getroffen werden

Die Blöcke fallen glatt durch dich hindurch. Zeit, das zu bemerken.

Die Engine hat eine Funktion für genau diese Frage. Ändere die Prüfung in der Fall-Schleife von diesem:

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

zu diesem:

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

Speichere und fahr mit dem Balken in einen fallenden Block. Er verschwindet.

collideRects bekommt zwei Rechtecke und antwortet true, wenn sie sich überlappen. Jedes Rechteck sind vier Zahlen: eine Ecke, dann eine Breite und eine Höhe — nicht zwei Ecken, was die andere vernünftige Art ist, ein Rechteck zu beschreiben, und die Art, wie overlayBox es macht. Der Eintrag zu collideRects in der Referenz nennt die Reihenfolge, und es lohnt sich, ihn jetzt anzusehen, denn die acht Argumente in der falschen Reihenfolge zu übergeben ist die Art Fehler, die überhaupt keine Fehlermeldung erzeugt, nur ein Spiel, in dem nie etwas irgendetwas trifft.

Das könntest du selbst schreiben. Es sind vier Vergleiche, und es ist wirklich nicht schwer. Nimm trotzdem die der Engine, aus drei Gründen. Sie ist richtig, auch in den kniffligen Fällen: ein Rechteck ohne Breite, zwei Rechtecke, die sich nur an einer Kante berühren. Sie sagt, was sie meint, also liest sich die Zeile als „haben sich die beiden überlappt“ statt als vier mit and verbundene Vergleiche, die du jedes Mal entschlüsseln musst, wenn du zu ihr zurückkommst. Und wenn du bei Lektion elf ankommst, wo die Dinge ständig aneinanderstoßen, kennst du die Familie schon: collidePointRect für einen Mausklick, collideCircles für zwei runde Dinge und collideSegments für einen Schuss gegen eine Wand. Die Referenz führt sie zusammen auf.

Das Einzige, was die Engine dir nicht abnehmen kann, ist zu entscheiden, was ein Rechteck bedeutet. Das Rechteck des Blocks ist hier der ganze Block. In einem echten Spiel willst du oft, dass das Trefferrechteck etwas kleiner ist als das Bild, damit sich ein knappes Verfehlen auch wie ein knappes Verfehlen anfühlt. Das ist eine Designentscheidung, und in Lektion elf triffst du sie.

Schritt fünf: Punkte und Leben

Getroffen zu werden sollte etwas kosten, und Überleben sollte etwas wert sein.

Zwei weitere Konstanten oben:

local BLOCK_FASTER  = 0.05
local START_LIVES   = 3

Drei weitere Variablen, neben spawnTimer:

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

BLOCK_SPEED ist jetzt die Geschwindigkeit, mit der das Spiel anfängt, und blockSpeed die, mit der es gerade läuft. Ändere die Fall-Zeile so, dass sie die Variable benutzt:

        block.y = block.y + blockSpeed

Dann trenn die beiden Fälle, denn sie tun jetzt Verschiedenes:

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

Und zeig die Zahlen an. Setz das direkt vor das return:

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

Speichere und spiel eine Minute lang. Es wird schwerer, und das ist der ganze Trick: Jeder Block, dem du ausweichst, lässt die nächsten um ein Zwanzigstel Pixel pro Frame schneller fallen. Nach zwanzig Punkten sind sie spürbar flotter. Du musstest kein einziges Wort über Schwierigkeitsstufen schreiben.

Du wirst auch zusehen, wie LIVES auf -4 fällt, weil das Spiel noch nichts anhält. Das ist der nächste Schritt, und er ist der wichtigste.

Schritt sechs: Game Over und noch eine Runde

Hier ist die Falle. Der naheliegende Weg zu einem Game-Over-Bildschirm ist eine Variable namens gameOver, die auf true gesetzt wird, wenn die Leben aufgebraucht sind. Dann willst du vor dem ersten Spiel einen Titelbildschirm, also fügst du started hinzu. Dann willst du eine Pausentaste, also fügst du paused hinzu. Jetzt hast du drei Wahr-oder-falsch-Variablen, acht Kombinationen davon, und fünf dieser Kombinationen sind Unsinn, den dein Code sorgfältig nie erzeugen darf. Jeder Anfänger schreibt dieses Spiel mindestens einmal, und hier gehen kleine Spiele sterben.

Mach stattdessen das hier. Eine Variable hält fest, was das Spiel gerade tut, als Wort:

local state      = "waiting"

Sie ist "waiting" vor dem ersten Spiel, "playing" während eines Spiels und "over", wenn die Leben weg sind. Drei Zustände, eine Variable, und so etwas wie eine unmögliche Kombination gibt es nicht. An den Strings ist nichts Magisches; es sind Wörter, die du gewählt hast, und du musst sie jedes Mal gleich schreiben.

Jetzt die Funktion, die ein Spiel beginnt. Jede Variable, die zu einem Spiel gehört, bekommt hier ihren Anfangswert zurück, an einer einzigen Stelle:

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

Das letzte Leben zu verlieren beendet es. Im Zweig für die Kollision, unter lives = lives - 1:

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

Die Leertaste startet ein Spiel, aber nur, wenn nicht schon eins läuft. Füg onInputPressed einen Zweig hinzu:

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

~= heißt „ist nicht gleich“. state ~= "playing" ist wahr beim Warten und wahr nach dem Ende, und das sind genau die beiden Momente, in denen die Leertaste ein Spiel starten soll. SWITCH_BUTTON1 ist standardmäßig die Leertaste und außerdem der A-Knopf an einem Controller.

Zwei kleine Funktionen bringen die Wörter auf den Bildschirm. printCentered erledigt die Rechnung einmal, damit der Titelbildschirm und der Game-Over-Bildschirm sie nicht jeder für sich schlecht machen:

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


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


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

mit einer weiteren Konstanten oben:

local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

Zum Schluss der wichtige Teil. Schieb alles, was zeichnet, aus onOverlayUpdate in eine Funktion namens drawGame, schieb alles, was bewegt, in eine Funktion namens updatePlaying — beide stehen im vollständigen Skript unten — und lass onOverlayUpdate so aussehen:

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

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

    return OVERLAY_UPDATED
end

Speichere. Du hast ein Spiel: einen Titelbildschirm, ein Spiel, ein Game Over und einen Weg zurück an den Anfang.

Lies diese dreizehn Zeilen noch einmal, denn sie sind die Form jedes Spiels, das du je schreiben wirst. Die Welt bewegt sich nur, solange der Zustand "playing" ist, also friert der Game-Over-Bildschirm ein, und die letzten Blöcke hängen genau dort, wo sie waren. Die Welt wird in jedem Frame gezeichnet, egal in welchem Zustand, denn das Bild ist in allen dreien dasselbe; der Zustand entscheidet nur, welche Wörter darüber kommen. Und es gibt genau eine Stelle, die diese Entscheidung trifft.

Das hast du dir mit der Variablen state erkauft. Wenn du eine Pause einbaust, fügst du diesem if einen Zweig hinzu und onInputPressed eine Zeile, und sonst muss nichts im Spiel irgendetwas davon wissen.

Das Ganze

Hier ist es, fertig. Wenn deins nicht übereinstimmt, lohnt es sich, den Unterschied zu finden.

dofile("Singe/Framework.singe")

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

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

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


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


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


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


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


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


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


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

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

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


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


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


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

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

    return OVERLAY_UPDATED
end

Ungefähr hundertzwanzig Zeilen Code, und du hast sie alle eine Handvoll nach der anderen geschrieben.

Was gerade passiert ist

Ein paar Stücke verdienen einen zweiten Blick.

local blocks     = {}
local score      = 0


function startGame()
    score = 0
end

Die Daten sind local, die Funktionen nicht. Das sind zwei bewusste und gegensätzliche Entscheidungen.

Die Daten sind local, damit sie zu dieser Datei gehören und nichts von außen hineingreifen und sie ändern kann. Die Funktionen sind global, damit sie sich in beliebiger Reihenfolge gegenseitig aufrufen können: drawOverText ist vor printCentered definiert und ruft es trotzdem auf, weil ein globaler Name erst im Moment des Aufrufs nachgeschlagen wird, und bis dahin ist die ganze Datei gelesen. Mach diese Funktionen local, und die Datei muss so sortiert sein, dass nichts benutzt wird, bevor es auftaucht, und über diese Regel würdest du für den Rest des Buchs stolpern. Drei der Namen hier haben überhaupt keine Wahl: onOverlayUpdate und die beiden Eingabe-Callbacks müssen global sein, denn so findet Singe sie.

Innerhalb der Datei ist die Reihenfolge alphabetisch, mit den drei Callbacks am Ende. Das ist keine Regel von Lua. Es ist dafür da, dass du spawnBlock in sechs Monaten findest, ohne irgendetwas zu lesen.

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

#text ist die Länge eines Strings, in Zeichen. # hast du in Lektion sechs kennengelernt, als es die Einträge einer Liste gezählt hat, und hier erledigt es dieselbe Aufgabe. "GAME OVER" hat neun Zeichen, also fängt es auf einem Bildschirm mit sechzig Spalten in Spalte fünfundzwanzig an, und links davon bleiben fünfundzwanzig Zellen Platz und rechts sechsundzwanzig. math.floor wirft den Bruchteil weg, denn eine Spalte fünfundzwanzigeinhalb gibt es nicht.

TEXT_COLUMNS rechnet aus, wie viele Zeichenzellen nebeneinander auf den Bildschirm passen. overlayPrint zählt in Zellen, während alles andere in Pixeln zählt, also wird die Breite des Overlays durch die Breite einer Zelle geteilt, und die sagt dir overlayGetFontWidth. Zwei Schrägstriche statt einem, denn ein Bruchteil einer Spalte ist kein Ort, an dem man etwas ausgeben kann. Rechne es so aus, und die Zentrierung bleibt bei jeder Overlay-Größe richtig; darum geht es im vierten Punkt von Probier es aus.

    colorForeground(255, 90, 90)

colorForeground setzt eine Farbe, die gesetzt bleibt. Es ist kein Argument von overlayBox; es ist ein Schalter, den du umlegst, und alles, was danach gezeichnet wird, kommt in dieser Farbe heraus, bis du ihn wieder umlegst. Darum setzt drawGame Grün, zeichnet die Spielfigur, setzt Rot und zeichnet dann alle Blöcke, ohne die Farbe noch einmal zu erwähnen.

Auf overlayPrint wirkt es sich nicht aus. Die Konsolenschrift wird genau so, wie sie ist, in ihren eigenen Farben aufs Overlay kopiert, und der Eintrag zu overlayPrint in der Referenz sagt das ausdrücklich. Farbiger Text braucht eine geladene Schriftart, und das ist Lektion neunzehn.

Probier es aus

  1. Mach es leichter, dann unfair. Ändere PLAYER_WIDTH in 80 und spiel eine Runde. Dann ändere es in 12, so groß wie ein Block. Beachte, dass du für keins von beiden das Zeichnen oder die Kollision anfassen musstest.

  2. Schneller beschleunigen. Ändere BLOCK_FASTER von 0.05 in 0.5 und sieh, wie viele Punkte du schaffst. Dann probier 0 und frag dich, ob das Spiel dann noch spielenswert ist.

  3. Ein Extraleben. Gib dem Spieler alle zehn Punkte ein Leben zurück. Alles, was du brauchst, steht schon in updatePlaying, in dem Zweig, der die Punktzahl erhöht.

  4. Spiel es größer. Starte es mit Singe -R --canvas=1280x720 dodge. Das Spiel richtet sich richtig ein, samt zentriertem Text, weil es die Engine gefragt hat, wie groß der Bildschirm ist. TEXT_COLUMNS hat auch gefragt.

  5. Halt es an. Füg einen vierten Zustand hinzu, "paused". SWITCH_BUTTON2 soll zwischen "playing" und "paused" wechseln, und während der Pause soll sich nichts bewegen. Richtig gemacht sind das drei Zeilen, und updatePlaying musst du überhaupt nicht anfassen.

Mach es absichtlich kaputt

Geh in spawnBlock und lösch die Zeile, die block.y setzt, sodass es so lautet:

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

Speichere, drück die Leertaste, und Singe hält hiermit an:

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

Zeile 97 ist block.y = block.y + blockSpeed. Die Beschwerde lautet, dass etwas in dieser Rechnung keine Zahl ist, und der Teil in Klammern sagt dir, was: field 'y', also das y in einer Tabelle. Es hat keinen Wert, weil du ihm nie einen gegeben hast, und etwas ohne Wert ist in Lua nil.

Achte darauf, wo die Fehlermeldung ist und wo der Fehler. Die Meldung kommt aus updatePlaying, vierzig Zeilen von spawnBlock entfernt, und dort ist überhaupt nichts falsch. updatePlaying ist nur das erste Stück Code, das das Pech hat, den Schaden zu berühren. Das ist der Normalfall, nicht die Ausnahme, und dieser Spur rückwärts zu folgen ist eine Fertigkeit.

Setz die Zeile wieder ein. Dann blätter um, denn in der nächsten Lektion geht es um nichts anderes.

Was du gelernt hast

  • Ein Spiel ist eine Welt, die sich ändert, eine Welt, die gezeichnet wird, und eine Entscheidung darüber, was davon zu tun ist — und das sind drei getrennte Stücke Code.

  • Die Eingabe-Callbacks sollten festhalten, was gedrückt gehalten wird; das Update sollte entscheiden, was das bedeutet.

  • Eine Liste von Datensätzen ist die Form fast jeder Spielwelt.

  • Entferne Dinge aus einer Liste, indem du sie rückwärts durchläufst.

  • collideRects beantwortet, ob sich zwei Rechtecke überlappen, und die Version der Engine ist besser als deine, weil sie richtig ist, sich gut liest und eine Familie hat, der du wieder begegnen wirst.

  • Eine Variable state, die ein Wort hält, schlägt drei Wahr-oder-falsch-Flags und schlägt sie weiter, während das Spiel wächst.

  • Starte ein Spiel aus einer Funktion, die alles zurücksetzt, damit das zweite Spiel genau wie das erste ist.

  • Zahlen, an denen du vielleicht drehen willst, gehören in benannte Konstanten oben in der Datei.

  • Bau ein Spiel in Schritten, die jeder für sich laufen. Ein Programm, das nie funktioniert hat, ist viel schwerer zu reparieren als eins, das vor fünf Minuten noch funktioniert hat.

Beim nächsten Mal

Du hast jetzt genug Code geschrieben, um interessante Fehler zu machen. Die nächste Lektion ist die, um die sich kein Anfängerbuch kümmert: was die Fehlermeldungen von Singe wirklich sagen, wie du herausfindest, was wirklich in einer Variablen steckt, statt zu raten, und wie du ein Problem so lange halbierst, bis es sich nirgends mehr verstecken kann.

Lektion 8: Wenn etwas schiefgeht

Die fertige Lektion

Du hast ein Spiel geschrieben. Ab jetzt wirst du mehr Zeit damit verbringen, Programme zu reparieren, als sie zu schreiben, und das ist kein Zeichen, dass mit dir etwas nicht stimmt. Das ist die Arbeit. Der Unterschied zwischen jemandem, dem Programmieren Spaß macht, und jemandem, der es aufgibt, ist fast nie Talent; es ist die Frage, ob er gelernt hat zu lesen, was der Computer ihm sagt.

In dieser Lektion gibt es also nichts Neues zu bauen. Es geht um die fünf Meldungen, die du für den Rest deines Lebens am häufigsten sehen wirst, was jede davon wirklich bedeutet, und um vier Wege, den Fehler dahinter aufzuspüren. Lass dodge.singe aus Lektion sieben offen, denn du wirst es mehrmals absichtlich kaputt machen.

Zwei Arten anzuhalten

Singe hält aus zwei verschiedenen Gründen an, und es sagt das auf zwei verschiedene Arten.

Wenn das Skript gar nicht erst startet, bekommst du diese Form:

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

Lua liest deine ganze Datei, bevor es auch nur ein Wort davon ausführt, und das hier heißt, dass es aus dem Gelesenen nicht schlau wurde. Überhaupt nichts ist gelaufen.

Wenn das Skript gut gestartet ist, aber später etwas schiefging, bekommst du stattdessen diese Form:

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

Das Spiel lief. Singe hat dein onOverlayUpdate aufgerufen, wie es das sechzigmal pro Sekunde tut, und diesmal kam der Aufruf nicht zurück.

Beide Formen enthalten dieselben drei Dinge, und das sind genau die drei, die du willst: eine Datei, eine Zeile und eine Beschwerde. Lies sie in dieser Reihenfolge, jedes Mal.

Die Zeilennummern in dieser Lektion stammen aus dem fertigen Listing von Lektion sieben. Liegen deine um eine oder zwei Zeilen daneben, dann tut es deine Datei auch, und nichts am Lesen eines Fehlers hängt davon ab, dass die Nummer stimmt.

Die, die es aufhalten, bevor es anfängt

Das sind die leichten, und es sind auch die, die sich am schlimmsten anfühlen, weil der Bildschirm schwarz bleibt und es nichts zu sehen gibt.

Geh in updatePlaying und lösch das Wort then aus der Zeile if spawnTimer ⇐ 0 then. Speichere:

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

Lua ist ans Ende der if-Zeile gekommen, wollte das Wort then und hat stattdessen den Anfang der nächsten Zeile gefunden — das ist spawnBlock(), und daher kommt der Teil near 'spawnBlock'. „Near“ heißt „hier habe ich es gemerkt“, und das ist meistens das Erste nach dem, was du weggelassen hast.

Jetzt ein fieserer. Setz then wieder ein und lösch stattdessen das end in der letzten Zeile von spawnBlock. Speichere:

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

Zeile 148 ist das Ende der Datei, gleich hinter ihrer letzten Zeile. An Zeile 148 ist nichts falsch. Lua hat bis ganz zum Ende gelesen — <eof> nennt es das Ende einer Datei — und dabei immer noch auf ein end gewartet, das nie kam, und bis dahin hatte es jede Funktion nach spawnBlock verschluckt, als gehöre sie dazu.

Die nützliche Hälfte dieser Meldung ist (to close 'function' at line 58), und dort fängt spawnBlock an. Wenn eine Meldung aufs Ende der Datei zeigt, glaub dem, was in den Klammern steht, nicht der Zeilennummer. Das ist auch der Grund, warum die Einrückung so wichtig ist: Ein fehlendes end ist in einer Reihe von Zeilen fast unsichtbar und sofort offensichtlich, sobald alles darunter eine Stufe zu weit eingerückt ist.

Zwei weitere, die du wiedererkennen solltest, denn beiden begegnest du noch diese Woche:

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

Ein Anführungszeichen, das du geöffnet und nie geschlossen hast; das kennst du aus Lektion eins.

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

Das ist if state = "playing" then. Ein = setzt eine Variable, zwei == stellen eine Frage, und Lua lässt dich in einem if keine setzen. Es sieht nach einer seltsamen Beschwerde aus, und sie bedeutet immer dasselbe.

Attempt to Index a Nil Value

Diese Meldung wirst du mit großem Abstand am häufigsten sehen.

Geh in spawnBlock und schreib block in der ersten Zeile, die es benutzt, falsch, sodass dort blocl.x = math.random(0, screenWidth - BLOCK_SIZE) steht. Speichere, drück die Leertaste:

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

Indizieren ist das, was der Punkt tut. blocl.x heißt „geh in das Ding namens blocl und such darin das x“. Das geht nur bei einer Tabelle.

Nil nennt Lua einen Namen, hinter dem nichts steht. Du hast es bisher selten gesehen, weil du sorgfältig allem einen Wert gegeben hast, aber jeder Name, den du nie benutzt hast, ist schon nil, und wer einen Namen falsch tippt, erfindet einen nagelneuen.

Die ganze Meldung sagt also: Du hast einen Punkt auf etwas angewendet, das es nicht gibt.

Der Teil in Klammern ist das Geschenk. global 'blocl' ist genau der Name des Dings, das leer war. Such in deiner Datei danach. Kommt er genau einmal vor, ist es ein Tippfehler, und du hast ihn in zehn Sekunden gefunden.

Das Wort vor dem Namen sagt dir, wo Lua danach gesucht hat:

  • global — ein Name, vor dem nirgends ein local steht.

  • local — ein Name, den du in der Funktion, in der du gerade bist, mit local deklariert hast.

  • field — ein Name nach einem Punkt, wie das y in block.y.

  • upvalue — ein local von weiter außen, das diese Funktion sehen kann, und das sind alle Variablen von dodge.singe, denn sie werden oben in der Datei deklariert und in Funktionen benutzt.

field ist die andere häufige Ursache, und die ist überhaupt kein Tippfehler. Wenn du block.hit.when geschrieben und block.hit nie gesetzt hast, bekommst du attempt to index a nil value (field 'hit'). Der Punkt, der scheitert, ist der zweite. Lua sagt dir, welcher, indem es ihn beim Namen nennt.

Attempt to Call a Nil Value

Mach blocl wieder rückgängig. Jetzt schreib eine Engine-Funktion falsch: Ändere in drawGame das overlayPrint in overlayPirnt. Speichere:

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

Dasselbe nil, anderes Vergehen. Aufrufen ist das, was die Klammern tun, und das geht nur bei einer Funktion. Es gibt keine Funktion namens overlayPirnt, also ist overlayPirnt gleich nil, also haben die Klammern nichts, was sie aufrufen könnten.

Das passiert aus vier Gründen, nach Häufigkeit geordnet:

  1. Du hast eine deiner eigenen Funktionen falsch geschrieben.

  2. Du hast eine von Singe falsch geschrieben. Nichts in der Engine prüft deine Rechtschreibung, wenn die Datei geladen wird, also ist ein falsch geschriebener Engine-Name einfach ein weiterer Name, der zufällig leer ist, und er kostet dich nichts, bis die Zeile läuft.

  3. Die Funktion gibt es in Singe überhaupt nicht — es war eine vernünftige Vermutung, und vernünftige Vermutungen liegen etwa die Hälfte der Zeit daneben. Die Funktionsliste in der Referenz ist der einzige Weg, sicher zu sein.

  4. Du hast sie local gemacht und von irgendwo oberhalb der Stelle aufgerufen, an der sie deklariert ist. Genau darum sind die Funktionen in dodge.singe global.

Es gibt eine viel schlimmere Version dieses Fehlers, und du bist ihr in Lektion eins begegnet, ohne es zu wissen: Schreib einen Callback falsch, und du bekommst überhaupt keine Meldung. onOverlayUpdated ist kein Fehler. Es ist eine völlig ordentliche Funktion, von der Singe nie gehört hat und die es nie aufrufen wird, also bleibt der Bildschirm schwarz, und nichts beschwert sich. Wenn ein ganzer Teil des Spiels überhaupt nichts tut, verdächtige den Namen.

Attempt to Perform Arithmetic on a Nil Value

Setz overlayPrint wieder ein. Schreib in updatePlaying in der Fall-Zeile blockSpeed falsch, sodass sie block.y = block.y + blockSped lautet:

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

Rechnen heißt +, -, * und /. Du kannst nicht nichts zu einer Zahl addieren. Wieder nennen die Klammern das leere Ding, und wieder ist die häufigste Ursache ein Tippfehler — aber dieser hier hat noch eine zweite Ursache, die du kennen solltest, weil sie schwerer zu sehen ist.

Eine Variable, der du nie eine Zahl gegeben hast, ist nil, nicht null. Wenn du dem Spiel einen Highscore hinzufügst und oben local hiScore ohne = 0 schreibst, steht darin nil, bis etwas sie setzt, und das erste hiScore + score hält das Spiel an. Lua lässt Zahlen nicht für dich bei null anfangen. Das machst du.

Zwei nahe Verwandte, mit derselben Ursache und demselben Heilmittel:

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

.., das einen String an etwas hängt, das nicht da ist. Den siehst du jedes Mal, wenn du eine Punktzahl ausgibst, die du zu setzen vergessen hast — hier hiScore, angehängt an die Punktezeile in drawGame, die jetzt Zeile 37 ist, weil local hiScore darüber steht.

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

Das ist if score > hiScore then, unter state = "over" gesetzt, um beim Ende eines Spiels die beste Punktzahl festzuhalten, ohne dass etwas in hiScore steht. Beachte, dass diese Meldung nichts in Klammern nennt. Wenn Lua dir nicht sagen kann, welche Seite leer war, zeigt dir der übernächste Abschnitt, wie du es herausfindest.

Ein Argument der falschen Art

Jede Meldung bisher kam von Lua. Diese kommt von Singe, und sie sieht völlig anders aus, also lohnt es sich, sie absichtlich kennenzulernen.

Angenommen, du willst sehen, was in blocks steckt, und versuchst, es auszugeben. Füg drawGame diese Zeile hinzu, unter der Punktzahl:

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

Kein Dateiname, kein Traceback, kein attempt to irgendwas. Eine Beschwerde der Engine fängt mit der Zeilennummer an, dann kommt der Name der Funktion, die sich geweigert hat, dann, was sie wollte. Hier hat overlayPrint eine Tabelle bekommen, wo es Text braucht, und es hat angehalten, statt etwas Sinnloses zu zeichnen.

Die Schwestermeldung zählt, statt zu prüfen:

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

Das ist ein overlayBox, dem eine Ecke fehlt. Das seltsam aussehende argument(s) stammt von der Engine, nicht aus einem Tippfehler von dir.

Wenn du so eine bekommst, ist der Eintrag zu dieser Funktion in der Referenz die Antwort, und das kostet dich eine Minute. Jeder Eintrag listet die Argumente der Reihe nach auf, mit dem, was jedes sein muss. Singe prüft sie, weil die Alternative ein Spiel ist, das zehn Minuten läuft und dann Müll zeichnet.

Herausfinden, was wirklich drinsteckt

Die Hälfte der Fehlersuche ist überhaupt nicht das Lesen von Fehlermeldungen. Es ist der Fall, in dem nichts abstürzt und nichts funktioniert: Blöcke, die nie erscheinen, eine Spielfigur, die sich nicht bewegen will, eine Punktzahl, die bei null hängt. Dafür musst du in das laufende Spiel hineinsehen, und dafür gibt es zwei Wege.

Der erste ist debugPrint, das eine Zeile in das Terminal schreibt, aus dem du Singe gestartet hast. Nimm die Zeile, aus der du nicht schlau wirst, und setz eins darüber:

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

Jetzt siehst du dir an, was wirklich da ist, statt dessen, wovon du sicher bist, dass es da ist, und in dieser Lücke wohnen die Fehler. Gib playerX auf dieselbe Weise aus, und du siehst auch die Wahrheit darüber: Es wird als 160.0 ausgegeben, nicht als 160, weil Teilen mit / in Lua immer eine Zahl mit Nachkommateil ergibt, auch wenn der Nachkommateil null ist.

Zwei Dinge werden dich beißen. Das erste ist, dass debugPrint auf Text oder einer Zahl besteht; gib ihm etwas anderes, und es hält das Spiel an, so wie overlayPrint es getan hat. debugPrint(blocks) zeigt dir keine Liste, und debugPrint("left " .. goingLeft) ganz oben in updatePlaying zeigt dir auch kein true oder false:

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

tostring ist die Lösung. Es nimmt überhaupt alles und gibt dir Text dafür, also ist tostring(goingLeft) entweder "true" oder "false", und die Zeile funktioniert.

Das zweite ist, dass onOverlayUpdate sechzigmal pro Sekunde läuft, also gibt ein debugPrint darin sechzig Zeilen pro Sekunde aus, und du kannst keine davon lesen. Die Referenz sagt das auch in ihrem Eintrag: Der Aufruf ist billig, aber nichts bremst ihn.

Bevor du irgendetwas anderes machst, setz einen Schalter vor jede Debug-Zeile, die du hinzufügst, damit du den Lärm abstellen kannst, ohne sie alle wieder aufspüren zu müssen:

local DEBUG = true


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

Jedes debugLog im Spiel gehorcht diesem einen true. Ändere es in false, und das Spiel wird still; ändere es zurück, und alles ist wieder da.

Dann gib etwas aus, wenn etwas passiert, statt in jedem Frame:

            debugLog("hit at y " .. math.floor(block.y) .. ", lives now " .. lives)

Oder gib es nach einem Timer aus, der genau so heruntergezählt wird, wie Blöcke erzeugt werden:

    reportTimer = reportTimer - 1
    if reportTimer <= 0 then
        debugReport()
        reportTimer = REPORT_FRAMES
    end

Im Ordner learn liegt das Ganze als 08-when-it-goes-wrong.singe: Es ist das Spiel aus Lektion sieben mit einem Bericht etwa alle zwei Sekunden, einer Zeile, wenn du getroffen wirst, und einer Zeile, wenn das Spiel endet.

Der zweite Weg hineinzusehen ist, es auf den Bildschirm zu bringen, und das ist besser für alles, was sich in jedem Frame ändert, denn sechzig Zeilen pro Sekunde in einem Terminal sind nutzlos, aber eine Zahl, die in der Ecke tickt, lässt sich leicht beobachten:

    if DEBUG then
        overlayPrint(1, 3, "BLOCKS " .. #blocks .. "   PLAYER " .. playerX)
    end

Das Problem halbieren

Wenn du nicht siehst, welche von zwanzig Zeilen falsch ist, hör auf zu suchen und fang an wegzunehmen.

Setz zwei Bindestriche an den Anfang einer Zeile, und Lua ignoriert den Rest davon. Das ist ein Kommentar, und meistens hinterlässt man sich damit Notizen, aber die bessere Verwendung ist diese:

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

Kommentier die Hälfte von drawGame aus und starte es. Ist das Problem noch da, steckt es in der Hälfte, die du behalten hast. Ist es weg, steckt es in der Hälfte, die du entfernt hast. Setz diese Hälfte wieder ein und halbiere sie. Zwanzig Zeilen brauchen fünf solche Runden, und jede Runde ist einmal speichern und einmal hinsehen.

Das funktioniert nicht nur mit Zeilen. Kommentier den Rumpf von updatePlaying aus, und die Blöcke hören auf, sich zu bewegen, und das sagt dir, ob das, was du jagst, im Bewegen steckt oder im Zeichnen. Kommentier den Zweig mit collideRects aus und sieh nach, ob das Spiel aufhört abzustürzen. Du versuchst dabei nicht, irgendetwas zu reparieren. Du versuchst herauszufinden, wo es nicht ist.

Schnellere Runden

All das hängt davon ab, dass du etwas in ein paar Sekunden ausprobieren kannst, und dafür ist -R da. Du benutzt es seit Lektion eins; hier steht, was es wirklich tut, und das solltest du jetzt wissen, wo du dich darauf stützen wirst.

Singe beobachtet jede Skriptdatei, die dein Spiel geladen hat. Wenn du eine speicherst, fängt das Spiel wieder von vorne an: Alles, was das Skript gemacht hat, wird weggeworfen, und deine Datei läuft neu, in der Zeit, die das Lesen der Datei braucht, und nicht in der Zeit, die das Starten der Engine braucht. F5 macht dasselbe auf Wunsch, ohne dass du etwas speicherst.

Eine Taste, die du während des Neuladens gedrückt hältst, wird ignoriert, bis du sie loslässt, also läuft die Spielfigur nach einem Neuladen nicht von allein davon.

Die beiden Arten anzuhalten verhalten sich hier verschieden, und es ist nützlich zu wissen, welche du vor dir hast, ohne die Meldung zu lesen. Ein Skript, das sich nicht kompilieren lässt, wird gemeldet und überstanden: Das Fenster bleibt offen und leer, die Datei wird weiter beobachtet, und wenn du die Korrektur speicherst, kommt das Spiel zurück. Ein Absturz in einem Callback — alle attempt to-Meldungen und die Beschwerden der Engine über Argumente — reißt Singe mit, und du startest es von Hand neu.

Einen Traceback lesen

Die Zeilen unter stack traceback: sind die Liste der Funktionen, die gerade liefen, als alles anhielt, die innerste zuerst. Hier ist noch einmal der von blocl:

	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Lies ihn von unten nach oben, und er ist ein Satz. Singe hat onOverlayUpdate aufgerufen. In Zeile 136 hat onOverlayUpdate updatePlaying aufgerufen. In Zeile 92 hat updatePlaying spawnBlock aufgerufen. In Zeile 60 hat spawnBlock aufgegeben.

Die oberste Zeile ist die Stelle, an der es kaputtging. Die Zeilen darunter zeigen, wie es dorthin kam, und die brauchst du, wenn die oberste Zeile unschuldig aussieht. Eine Funktion, die eine Zahl zu block.y addiert, ist nicht falsch; eine Funktion, die einen Block ohne y in die Liste gelegt hat, schon. Nur die Spur verbindet die beiden, und die Spur wird dir jedes einzelne Mal ausgegeben.

Die Gewohnheit

Alles oben ist Technik. Das hier ist die Gewohnheit, und sie ist wichtiger:

Ändere eine Sache. Starte es. Sieh dir an, was passiert ist.

Wenn etwas nicht funktionieren will, ist die Versuchung groß, vier Dinge auf einmal zu ändern, weil eines davon es ja sein muss. Mach das, und es funktioniert auf eine neue Art nicht, und jetzt weißt du nicht, welches der vier es war oder ob sich zwei davon gegenseitig aufheben. Du hast das Problem größer gemacht und besser versteckt.

Eine Änderung. Starten. Hinsehen. Es fühlt sich langsamer an. Es ist das Schnellste, was es gibt, und jeder erfahrene Programmierer, dem du je begegnest, macht es so, aus genau dem Grund, den du gleich herausfinden wirst.

Probier es aus

  1. Lern sie alle kennen. Mach jeden der fünf Fehler aus dieser Lektion absichtlich in dodge.singe, einen nach dem anderen, und lies die Meldung, bevor du ihn behebst. Du wirst nie wieder Angst vor ihnen haben.

  2. Beobachte den Erzeuger. Setz ein debugPrint in spawnBlock, das das x des neuen Blocks ausgibt. Spiel dreißig Sekunden lang, dann sieh dir die Zahlen an. Sind sie über den Bildschirm verteilt, oder bevorzugen sie eine Seite?

  3. Schalt es ab. Ändere im Skript der Lektion DEBUG in false und überzeug dich davon, dass nichts ausgegeben wird und das Spiel unverändert ist.

  4. Ein Fehler ohne Fehlermeldung. Ändere in updatePlaying if spawnTimer ⇐ 0 then in if spawnTimer == 0 then, was so aussieht, als bedeute es dasselbe. Starte es und fang ein Spiel an. Es gibt keine Fehlermeldung, nichts stürzt ab, und kein einziger Block fällt je, du kannst also nicht einmal verlieren. Setz ein debugLog in spawnBlock, füg spawnTimer der ersten Zeile hinzu, die debugReport ausgibt, und spiel noch einmal. Finde aus dem, was sie sagen, und aus dem, was eines von beiden nie sagt, heraus, warum == die falsche Frage war.

  5. Mach den Namen eines Callbacks kaputt. Benenne onInputPressed in onInputPress um und starte es. Keine Fehlermeldung wird ausgegeben, nichts stürzt ab, die Spielfigur bewegt sich nicht, und die Leertaste startet kein Spiel. Dann erklär dir selbst, warum das der gefährlichste Fehler in dieser Lektion ist.

Was du gelernt hast

  • Fehlermeldungen haben eine Datei, eine Zeile und eine Beschwerde. Lies sie in dieser Reihenfolge.

  • Error running script heißt, dass nichts gelaufen ist; die Form mit einem Traceback heißt, dass es lief und angehalten hat.

  • nil ist ein Name, hinter dem nichts steht, und es steckt hinter den meisten Fehlermeldungen, die du je sehen wirst.

  • Das Wort in Klammern nennt das leere Ding und sagt, ob es global, lokal, ein Feld oder ein Upvalue war.

  • Ein fehlendes end wird am Ende der Datei gemeldet, und die Klammern sagen dir, wo der Fehler wirklich steckt.

  • Beschwerden der Engine sehen anders aus: eine Zeilennummer, ein Funktionsname und was sie stattdessen wollte.

  • debugPrint zeigt dir, was wirklich in einer Variablen steckt. tostring macht alles ausgebbar, und ein Schalter wie DEBUG stellt den Lärm ab.

  • Kommentier mit -- eine Hälfte aus, um herauszufinden, in welcher Hälfte das Problem steckt.

  • Ein falsch geschriebener Callback erzeugt überhaupt keine Fehlermeldung, und das macht ihn schlimmer als einen Fehler, der eine erzeugt.

  • Ändere eine Sache, starte es, sieh hin.

Beim nächsten Mal

Damit endet Teil eins. Du kannst ein Spiel schreiben, und jetzt kannst du auch eins reparieren, und das heißt, dass alles ab hier Anbau ist und kein Fundament mehr. Teil zwei fängt damit an, diese farbigen Kästen durch echte Bilder zu ersetzen, und von da an sieht das Spiel, das du baust, allmählich wie ein Spiel aus, das auch jemand anders spielen wollen würde.

Lektion 9: Bilder

Die fertige Lektion

Alles, was du bisher gezeichnet hast, hast du mit Kästen, Linien und dem schlichten Text der Engine gezeichnet. Das war Absicht: Acht Lektionen ohne Grafiken hießen acht Lektionen, in denen nichts schiefgehen konnte außer deinem Programm. Jetzt werden aus den Kästen ein Raumschiff und ein paar Felsen.

Ein Bild, das die Engine aufs Overlay zeichnet, heißt Sprite. Diese Lektion lädt sie, zeichnet sie, misst sie aus, bringt sie in die richtige Reihenfolge und geht durch ein Bild, das mehrere Frames einer Animation enthält. Am Ende sieht das Spiel aus Lektion sieben wie ein Spiel aus.

Das Grafik-Kit

Du musst nichts zeichnen. Zu diesem Buch gehört ein kleiner Ordner mit Grafiken, und alles in dieser und der nächsten Lektion benutzt ihn.

Such den Ordner art, der mit dem Buch gekommen ist, und kopier den ganzen Ordner in den Ordner dieser Lektion, neben dein Skript. Am Ende sollte das so aussehen:

singe/                 <- dein Arbeitsordner
    Singe/
    data/
    rocks/
        rocks.singe
        art/
            spaceship.png
            asteroid.png
            bullet.png
            star.png
            walk.png
            shoot.wav
            boom.wav

Deine Grafiken kommen in den eigenen Ordner deines Spiels, und der Ordner Singe der Engine bleibt, wo er ist, draußen im Arbeitsordner. Das ist gleich wichtig, denn es entscheidet, wie du eine Datei benennst, wenn du sie lädst.

Der Ordner Singe ist der, den die Engine bei deinem allerersten Start in Lektion eins für dich entpackt hat. Es lohnt sich zu wissen, was darin ist, denn diese Dateien darfst du ebenfalls benutzen, und jeder Leser dieses Buchs hat sie:

  • Singe/click.wav — ein kurzer Klick, den das Menü der Engine für seinen Soundtest benutzt.

  • Singe/FreeSansBold.ttf — eine TrueType-Schriftart, für Lektion neunzehn.

  • Singe/menuIntro.flac — die Musik, die das Menü der Engine spielt. Du benutzt sie in Lektion zehn.

  • Singe/menuBackground.mkv — ein Video, für Lektion vierzehn.

  • Singe/DragonModel.glb und Singe/SingeText.glb — zwei 3D-Modelle, für Lektion dreiundzwanzig.

  • Singe/missing.png — das Bild, das die Engine zeichnet, wenn ein Spiel nach einem fragt, das sie nicht finden kann.

Die Bilder im Kit sind absichtlich klein. Das Raumschiff ist 32 Pixel breit und 24 hoch, ein Felsen ist 24 mal 24, ein Schuss 4 mal 10 und ein Stern 8 mal 8. Das klingt winzig, bis du dich daran erinnerst, wie groß der Bildschirm wirklich ist, und das klären wir als Nächstes.

Wie groß der Bildschirm ist

Ohne Video zum Abspielen gibt Singe deinem Spiel eine Zeichenfläche von 720 Pixeln Breite und 480 Höhe, und die Fläche, auf die du zeichnest — das Overlay — ist in jeder Richtung halb so groß: 360 mal 240. Singe streckt sie für dich, bis sie das Fenster füllt, also ist ein Raumschiff von 32 Pixeln etwa ein Zehntel so breit wie der Bildschirm, und ungefähr so sieht ein Raumschiff in einem Arcade-Spiel aus.

Tipp nie 360 und 240 in dein Programm. Frag:

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()

Diese beiden melden die Größe des Overlays, und ein Spiel, das fragt, ist ein Spiel, das immer noch funktioniert, wenn jemand es in einer anderen Größe startet.

Eine Sache zählt nicht in diesen Pixeln: overlayPrint aus Lektion eins zählt in Zeichenzellen. Jede Zelle ist 6 Pixel breit und 13 hoch, also passen auf ein Overlay von 360 mal 240 60 Spalten mal 18 Zeilen Text. Sprites sind in Pixeln, overlayPrint ist in Zellen, und wer die beiden verwechselt, verbringt damit einen verwirrten Nachmittag, wenn er es zulässt.

Ein Bild auf dem Bildschirm

Leg neben deinem Ordner art eine neue Datei an und tipp das ein.

dofile("Singe/Framework.singe")

local ship = spriteLoad(DIR .. "art/spaceship.png")


function onOverlayUpdate()
    overlayClear()
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(ship)
end

Starte es. Ein kleines blaues Raumschiff sitzt nahe der Mitte eines schwarzen Bildschirms und zeigt nach oben.

Was gerade passiert ist

Vier neue Dinge, eins nach dem anderen.

local ship = spriteLoad(DIR .. "art/spaceship.png")

spriteLoad liest eine Bilddatei von der Festplatte, dekodiert sie und hält das Bild im Speicher. Was es zurückgibt, ist nicht das Bild. Es ist ein Handle: eine schlichte Zahl, eine Eintrittskarte, die Art der Engine zu sagen: „das da“. Du gibst diese Zahl jedes Mal an die Engine zurück, wenn du etwas mit dem Bild tun willst, und du musst nie wissen oder dich darum kümmern, welche Zahl es ist.

Gib sie aus, wenn du willst — debugPrint(ship) aus Lektion acht zeigt dir eine kleine Zahl — aber über die Zahl selbst musst du dir keine Gedanken machen, und nichts in deinem Programm sollte je davon abhängen, welche es ist. Die einzige Regel ist, dass du sie irgendwo aufbewahrst, wo du wieder an sie herankommst, und genau dafür ist eine Variable da.

DIR ist auch neu, und es löst ein Problem, das der Aufbau erzeugt, den du seit Lektion eins benutzt. Singe sucht Dateien relativ zu dem Ordner, in dem du standest, als du es gestartet hast, nicht relativ zu deinem Skript. Du startest es aus deinem Arbeitsordner, also schickt ein schlichtes art/spaceship.png die Engine auf die Suche nach singe/art/spaceship.png, draußen neben dem Ordner Singe. Dort sind deine Grafiken nicht. Sie liegen eine Ebene tiefer, in rocks/art/spaceship.png, bei deinem Skript.

DIR schließt diese Lücke. Es ist ein Stück Text mit dem Ordner, in dem dein Skript liegt, mit dem Schrägstrich schon am Ende, also nennt DIR .. "art/spaceship.png" — zwei Stücke Text mit .. verbunden, wie du es seit Teil eins machst — das Bild richtig, egal wie das Spiel gestartet wurde, und nennt es auch dann noch richtig, wenn du den ganzen Ordner woandershin verschiebst.

DIR ist einer der Namen, die Singe/Framework.singe festlegt, und dafür ist die Zeile mit dofile oben in deinem Skript da. Diese Zeile und was darin steckt hast du in Lektion sieben kennengelernt, und jetzt verdient sie sich ihren Platz: Ohne sie gibt es kein DIR, und ohne DIR findet die Engine dein Raumschiff nicht.

Benutz DIR für jede Datei, die dein Spiel lädt, von hier bis zum Ende des Buchs.

    spriteDraw(ship, 160, 100)

Zeichne das Sprite mit diesem Handle an dieser Position. Wie jeder Zeichenaufruf funktioniert es nur in onOverlayUpdate.

Die Position ist die linke obere Ecke des Bildes, nicht seine Mitte. Verlang (160, 100), und das oberste, linkeste Pixel des Raumschiffs landet dort, und der Rest hängt nach rechts unten. Darüber stolpert jeder einmal, meistens, wenn er etwas zentrieren will und es um seine halbe Größe zu weit rechts unten herauskommt.

Wenn du lieber die Mitte angeben willst, sag es:

    spriteDraw(ship, 160, 100, true)

Ein viertes Argument true bedeutet „nimm diesen Punkt als Mitte“. Beide Formen stehen im Eintrag zu spriteDraw in der Referenz, zusammen mit zwei weiteren, die das Bild in ein Rechteck strecken.

function onShutdown()
    spriteUnload(ship)
end

onShutdown ist ein Callback wie onOverlayUpdate und die beiden Eingabe-Callbacks aus Lektion drei. Die Engine ruft ihn einmal auf, wenn dein Spiel endet. Hier gibst du zurück, was du genommen hast: spriteUnload gibt das Bild frei und wirft das Handle weg.

Genau genommen könntest du ihn weglassen. Die Engine gibt alles frei, was dein Skript geladen hat, wenn das Spiel endet, also ist ein vergessenes spriteUnload kein Speicherleck. Schreib es trotzdem. Es kostet eine Zeile, es sagt, was deinem Programm gehört, und gleich siehst du den Fall, in dem das vergessene Freigeben wirklich zählt.

Eine Warnung zu diesem Handle: Sobald du ein Sprite freigegeben hast, ist die Zahl tot. Damit zu zeichnen zeichnet nicht einfach nichts, es beendet dein Spiel mit einem Fehler.

Transparenz und warum es ein PNG ist

Das Raumschiff ist ein Dreieck mit zwei Flossen. Die Datei, in der es wohnt, ist ein Rechteck, 32 mal 24, denn jede Bilddatei ist ein Rechteck. Was ist also mit den Ecken passiert?

Sie sind transparent. Ein PNG kann für jedes einzelne Pixel sagen, wie deckend es ist, und die Bilder im Kit sagen für jedes Pixel außerhalb der Form „überhaupt nicht da“. Singe hält sich daran, also scheint der schwarze Hintergrund durch die Ecken, und das Raumschiff hat einen Umriss statt eines Kastens drumherum.

Das ist der Grund, warum das Kit aus PNG besteht und nicht aus JPEG. Ein JPEG kann überhaupt keine Transparenz speichern — es würde dir das Raumschiff in einem grauen Kasten geben — und es verschmiert außerdem harte Kanten, und das ist das Letzte, was kleine Grafiken brauchen. Für Spielgrafiken PNG. Für ein Foto, das den ganzen Bildschirm füllt und keine transparenten Stellen hat, ist JPEG in Ordnung und viel kleiner. Der Eintrag zu spriteLoad in der Referenz listet jedes Format auf, das Singe lesen kann, und das sind viele.

Probier es selbst: Mach aus dem Schwarz etwas anderes, indem du einen Kasten hinter das Raumschiff zeichnest, bevor du das Raumschiff zeichnest. Die Ecken zeigen, was auch immer dahinter ist, und genau darum geht es.

Lade nicht, während du zeichnest

Hier ist der Fehler, den dieser Abschnitt verhindern soll. Er sieht völlig vernünftig aus:

function onOverlayUpdate()
    overlayClear()
    local ship = spriteLoad(DIR .. "art/spaceship.png")
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end

Starte das, und es funktioniert. Es zeichnet das Raumschiff. Nichts beschwert sich. Du hättest keinen Grund zu glauben, dass etwas falsch ist.

onOverlayUpdate läuft etwa sechzigmal pro Sekunde. Das sind sechzig frische Kopien des Raumschiffs, die jede Sekunde in den Speicher geladen werden, dreitausendsechshundert pro Minute, und keine einzige davon wird je freigegeben. Das Spiel läuft zwei Minuten lang wunderbar, wird langsamer, und dann geht dem Rechner der Speicher aus, und es stirbt. Schlimmer noch: Es stirbt bei der Vorführung und nicht, während du getestet hast.

Die Regel: einmal laden, oft zeichnen. Laden ist langsam und braucht Speicher. Zeichnen ist schnell und braucht keinen. Also kommt spriteLoad oben in deine Datei, außerhalb jeder Funktion, wo es einmal läuft, wenn das Skript startet.

Das gilt nicht nur für Sprites. Jedes somethingLoad in der Engine funktioniert so — Sounds in Lektion zehn, Schriftarten in Lektion neunzehn, Modelle in Lektion dreiundzwanzig. Wenn du merkst, dass du Load in eine Funktion tippst, die in jedem Frame läuft, halt an und schieb es hinaus.

Wie groß ist es?

Du weißt, dass das Raumschiff 32 mal 24 groß ist, weil dieses Buch es dir gesagt hat. Dein Programm weiß es nicht, und es sollte es auch nicht wissen müssen. Frag:

local shipWidth  = spriteGetWidth(ship)
local shipHeight = spriteGetHeight(ship)

Jetzt kannst du das Raumschiff auf dem Bildschirm halten, weil die Position ganz rechts, an der es sitzen darf, screenWidth - shipWidth ist, und es in die Mitte setzen, weil die Mitte (screenWidth - shipWidth) / 2 ist. In keiner der beiden Zeilen steht eine Zahl, die sich ändern müsste, wenn jemand das Raumschiff ein bisschen größer neu zeichnet.

Beide melden die Größe so, wie das Sprite gerade gezeichnet würde. Wenn du ein Sprite je mit spriteScale oder spriteRotate skalierst oder drehst, ändert sich die Antwort entsprechend. Meistens ist das genau, was du willst, und es wird dich genau einmal überraschen.

Zeichenreihenfolge

Sprites verschmelzen nicht. Späteres verdeckt Früheres, Pixel für Pixel, genau wie Papierausschnitte, die du an eine Wand klebst. Die Reihenfolge deiner spriteDraw-Aufrufe ist also die Reihenfolge von hinten nach vorne:

    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()

Die Sterne sind am weitesten hinten, also kommen sie zuerst. Das Raumschiff ist vor allem anderen auf dem Spielfeld. Die Punktzahl liegt über allem. Dreh das um, und dein sorgfältig gezeichnetes Raumschiff versteckt sich das ganze Spiel über hinter dem Sternenfeld, und keine Fehlermeldung sagt dir das — nur ein Raumschiff, das du nicht siehst.

overlayClear kommt immer noch zuerst, vor allem anderen. Zeichnen ersetzt nie, es verdeckt nur, also fängt der Frame jedes Mal leer an.

Frames

Öffne art/walk.png in irgendeinem Bildbetrachter. Es ist kein Bild von einer Person. Es ist ein Bild von vier Personen, nebeneinander: dieselbe Figur an vier Punkten eines Schritts, jede 24 Pixel breit, in einem Streifen von 96 Pixeln Breite.

Ein Bild, das mehrere Frames einer Animation enthält, ist ein Sprite-Sheet, und so wird fast jede 2D-Animation gespeichert. Eine Datei, ein Laden, ein Handle, und das Spiel sucht sich aus, welchen Ausschnitt es zeichnet.

Leg neben der ersten eine zweite Datei an, walk.singe:

dofile("Singe/Framework.singe")

local walk      = spriteLoadFrames(4, DIR .. "art/walk.png")
local walkFrame = 1
local walkTick  = 0
local walkX     = 0


function onOverlayUpdate()
    overlayClear()
    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end
    walkX = walkX + 1
    if walkX > overlayGetWidth() then
        walkX = -spriteFrameWidth(walk)
    end
    spriteDrawFrame(walk, walkX, 100, walkFrame)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(walk)
end

Starte es mit Singe rocks/walk.singe. Eine kleine Figur läuft gleichmäßig über den Bildschirm, verschwindet am rechten Rand und kommt von links wieder herein.

spriteLoadFrames ist spriteLoad mit einer zusätzlichen Angabe: wie viele Frames im Streifen sind. Die Anzahl kommt zuerst, vor dem Dateinamen, und das ist das Gegenteil von dem, was die meisten raten. Es teilt die Breite des Bildes durch die Anzahl und merkt sich die Ausschnitte. Vier Frames in einem Streifen von 96 Pixeln heißt vier Frames von 24 Pixeln Breite. Gib die falsche Anzahl an — sagen wir 3 — und du bekommst drei Ausschnitte von 32 Pixeln, die jeweils Teile von zwei Figuren zeigen, und so findest du auf denkwürdig alberne Weise heraus, dass du die falsche Zahl getippt hast.

spriteDrawFrame zeichnet einen Ausschnitt. Es bekommt das Handle, wohin er soll, und welchen Frame, in dieser Reihenfolge, und die Frames sind ab 1 nummeriert: Frame 1 ist die Figur ganz links und Frame 4 die ganz rechts.

Pass bei dieser 1 auf. Anderswo in der Sprite-Familie — spriteSetFrame und spriteGetFrame — sind die Frames ab 0 nummeriert. Das ist ein Zufall der Geschichte, beide stehen in der Referenz, und dieses Buch benutzt spriteDrawFrame und zählt ab 1.

spriteFrameWidth meldet die Breite eines Frames, hier 24, und nicht die 96 des ganzen Streifens. spriteFrameHeight ist sein Partner. Wenn du wissen willst, wie breit ein Ausschnitt eines Sheets ist, sind das die beiden, die du fragst, und nicht spriteGetWidth.

Die Frame-Nummer ist eine Zahl in einer Variablen wie jede andere, also ist das Laufen Rechnerei:

    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end

Zähl die Frames, die vorbeiziehen. Bei jedem achten geh zum nächsten Bild weiter, und nach dem vierten Bild geh zurück zum ersten. Sechzig Frames pro Sekunde geteilt durch acht sind zwischen sieben und acht Schritte pro Sekunde, und für einen Zyklus aus vier Frames ist das ein flotter, aber glaubhafter Gang. Ändere die 8, und du änderst die Geschwindigkeit: größer ist langsamer.

Du fragst dich vielleicht, warum du überhaupt zählst, wenn die Engine spritePlay hat, um eine Animation für dich abzuspielen. Das hat sie, und für ein animiertes GIF ist das die richtige Antwort, denn ein GIF trägt die Zeitsteuerung für jeden seiner Frames in der Datei. Ein schlichter Streifen wie walk.png hat keine Zeitsteuerung, also spielt die Engine ihn so schnell ab, wie sie darf — hundert Frames pro Sekunde, fünfundzwanzig vollständige Schrittzyklen pro Sekunde, ein verwischter Fleck. Wenn die Frames aus einem Streifen kommen, zähl selbst.

Das Spiel bekommt seine Grafiken

Jetzt setz es zusammen. Im Spiel aus Lektion sieben hast du einen Kasten am unteren Rand des Bildschirms gesteuert, und andere Kästen sind darauf gefallen. Jeder Kasten wird zu einem Bild, und wenn du schon dabei bist, bekommt das Raumschiff etwas zum Schießen.

Die Änderungen hängen alle zusammen, also kommt hier das ganze Skript. Es ist länger als alles, was du bisher geschrieben hast, und es steckt nichts darin, was du nicht schon kennst.

dofile("Singe/Framework.singe")

local SHIP_SPEED  = 3
local SHOT_SPEED  = 6
local ROCK_COUNT  = 6
local STAR_COUNT  = 40
local START_LIVES = 3
local HIT_SCORE   = 10

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")
local rockSprite = spriteLoad(DIR .. "art/asteroid.png")
local shotSprite = spriteLoad(DIR .. "art/bullet.png")
local starSprite = spriteLoad(DIR .. "art/star.png")

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local shipWidth    = spriteGetWidth(shipSprite)
local shipHeight   = spriteGetHeight(shipSprite)
local rockWidth    = spriteGetWidth(rockSprite)
local rockHeight   = spriteGetHeight(rockSprite)
local shotWidth    = spriteGetWidth(shotSprite)
local shotHeight   = spriteGetHeight(shotSprite)

local shipX   = (screenWidth - shipWidth) / 2
local shipY   = screenHeight - shipHeight - 4
local goLeft  = false
local goRight = false
local rocks   = {}
local shots   = {}
local stars   = {}
local score   = 0
local lives   = START_LIVES
local over    = false


function drawHud()
    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(50, 1, "LIVES " .. lives)
    if over then
        overlayPrint(25, 8, "GAME OVER")
        overlayPrint(17, 10, "PRESS 1 TO PLAY AGAIN")
    end
end


function drawRocks()
    for _, rock in ipairs(rocks) do
        spriteDraw(rockSprite, rock.x, rock.y)
    end
end


function drawShots()
    for _, shot in ipairs(shots) do
        spriteDraw(shotSprite, shot.x, shot.y)
    end
end


function drawStars()
    for _, star in ipairs(stars) do
        spriteDraw(starSprite, star.x, star.y)
    end
end


function newRock(rock)
    rock.x     = math.random(0, screenWidth - rockWidth)
    rock.y     = -rockHeight - math.random(0, 160)
    rock.speed = math.random(8, 20) / 10
end


function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goLeft = false
    elseif what == SWITCH_RIGHT then
        goRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    updateStars()
    if not over then
        updateShip()
        updateShots()
        updateRocks()
    end
    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
end


function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end


function startGame()
    shipX = (screenWidth - shipWidth) / 2
    score = 0
    lives = START_LIVES
    over  = false
    shots = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
end


function updateRocks()
    for _, rock in ipairs(rocks) do
        rock.y = rock.y + rock.speed
        if rock.y > screenHeight then
            newRock(rock)
        end
        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                over = true
            end
        end
    end
end


function updateShip()
    if goLeft then
        shipX = shipX - SHIP_SPEED
    end
    if goRight then
        shipX = shipX + SHIP_SPEED
    end
    if shipX < 0 then
        shipX = 0
    end
    if shipX > screenWidth - shipWidth then
        shipX = screenWidth - shipWidth
    end
end


function updateShots()
    for i = #shots, 1, -1 do
        local shot = shots[i]
        local gone = false

        shot.y = shot.y - SHOT_SPEED
        if shot.y + shotHeight < 0 then
            gone = true
        end
        for _, rock in ipairs(rocks) do
            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
            end
        end
        if gone then
            table.remove(shots, i)
        end
    end
end


function updateStars()
    for _, star in ipairs(stars) do
        star.y = star.y + star.speed
        if star.y > screenHeight then
            star.y = 0
            star.x = math.random(0, screenWidth - 1)
        end
    end
end


for i = 1, STAR_COUNT do
    stars[i] = { x = math.random(0, screenWidth - 1), y = math.random(0, screenHeight - 1), speed = math.random(1, 3) / 4 }
end

startGame()

Die Pfeiltasten nach links und rechts steuern. Die Leertaste feuert. Wenn die Felsen dir das letzte Leben genommen haben, startet 1 ein neues Spiel.

Auf ein paar Dinge darin lohnt es sich zu zeigen.

Die vier Aufrufe von spriteLoad und die acht Messungen stehen oben, außerhalb jeder Funktion, also passieren sie einmal. Alles danach ist mit screenWidth, shipWidth und ihren Freunden geschrieben, und im ganzen Spielcode steht keine einzige nackte Pixelzahl.

Die Funktionen stehen in alphabetischer Reihenfolge, und diese Gewohnheit lohnt es sich jetzt anzunehmen. Lua ist das völlig egal — sie ist für dich, in sechs Monaten, wenn du in einer Datei mit vierzig Funktionen nach updateShots suchst.

Die letzten beiden Dinge in der Datei sind überhaupt keine Funktionen. Es sind schlichte Anweisungen am Ende des Skripts: das Sternenfeld bauen und dann startGame aufrufen, um die Felsen aufzustellen und die Punktzahl auf null zu setzen. Sie laufen einmal, der Reihe nach, wenn das Skript geladen wird, und sie müssen nach den Funktionen kommen, die sie benutzen.

overlapping sind die vier Vergleiche, von denen Lektion sieben gesagt hat, dass du sie selbst schreiben könntest, statt collideRects aufzurufen, ausgeschrieben als Funktion mit denselben acht Argumenten. Zwei Rechtecke verfehlen sich, wenn eines ganz links, rechts, über oder unter dem anderen liegt; ist keins dieser vier wahr, überlappen sie sich. Lektion elf ersetzt das durch etwas, das die Engine bereitstellt, und erklärt, warum das Rechteck die falsche Form für ein Raumschiff ist.

Ein letzter Hinweis für den Fall, dass du Singe-Code von anderen Leuten liest. Jeder Sprite-Aufruf in diesem Buch nimmt das Handle zuerst. Singe 2.10 hat es ans Ende gesetzt, und ein Spiel kann die Engine bitten, das weiter so zu machen, also steht in Code, den du im Netz findest, vielleicht spriteDraw(x, y, ship). Kopier das nicht. Das Handle zuerst ist die aktuelle Reihenfolge und die, die die Referenz beschreibt.

Probier es aus

  1. Zentrier das Raumschiff auf seiner Position. Gib dem spriteDraw des Raumschiffs true als viertes Argument. Sieh dir an, wohin das Raumschiff springt, und finde aus der Strecke, um die es sich bewegt hat, heraus, was das vierte Argument wirklich getan hat.

  2. Mehr Felsen. Ändere ROCK_COUNT in 20. Dann in 200. Irgendwo zwischen diesen beiden hört das Spiel auf, spielbar zu sein, und irgendwo weit darüber hinaus fängt das Spiel an, langsamer zu werden. Finde beide Stellen.

  3. Lass das Raumschiff wachsen. Füg spriteScale(shipSprite, 2) ganz unten in der Datei ein, in der Zeile über startGame(). Starte es und steuere gegen den rechten Rand: Das Raumschiff ist doppelt so groß, hält aber immer noch dort an, wo das kleine angehalten hat, und es hängt über den rechten Rand und über den unteren hinaus. Finde heraus, warum, dann schieb diese eine Zeile nach oben über die Aufrufe von spriteGetWidth und sieh zu, wie es richtig wird. Der Eintrag zu spriteScale in der Referenz erklärt, was das Skalieren mit den Maßen macht.

  4. Bau den Läufer ein. Lade walk.png im Spiel und lass die laufende Figur als Kulisse über den oberen Rand des Bildschirms laufen. Du brauchst das Zählen der Frames aus dem Lauf-Skript, und du musst entscheiden, wohin in onOverlayUpdate das Zeichnen kommt — vor die Sterne, hinter die Felsen.

  5. Gib etwas frei, das du noch benutzt. Füg spriteUnload(starSprite) ganz unten in der Datei ein, nach startGame(), und starte es. Lies, was du bekommst.

Mach es absichtlich kaputt

Großbuchstaben zählen, und bei Grafiken beißt das am heftigsten. Ändere das Laden des Raumschiffs so, dass es ein großes S benutzt:

local shipSprite = spriteLoad(DIR .. "art/Spaceship.png")

Das Spiel weigert sich zu starten:

10:spriteLoad:  Couldn't open rocks/art/Spaceship.png: No such file or directory

Lies es genauso wie den Fehler in Lektion eins, aber beachte, dass die Form ein bisschen anders ist. 10 ist die Zeile. spriteLoad ist die Engine-Funktion, die aufgegeben hat, und kein Dateiname — wenn die Beschwerde von Singe kommt statt von Lua, bekommst du das. Dann der Grund, und der ist hier in den eigenen Worten deines Betriebssystems formuliert und wird von Rechner zu Rechner leicht anders aussehen.

No such file or directory heißt, dass der Computer genau ist, nicht unfreundlich. Es gibt wirklich keine Datei namens Spaceship.png; es gibt eine namens spaceship.png, und für einen Rechner mit Linux sind das zwei verschiedene Namen. Unter Windows und auf den meisten Macs hätte es funktioniert, und das ist schlimmer, denn es heißt, dass der Fehler auf den Rechner von jemand anderem wandert und dort zum ersten Mal auftaucht.

Die andere Hälfte dieses Fehlers, der du begegnen wirst, ist der Ordner. Wenn du das Grafik-Kit an die falsche Stelle gelegt oder Singe aus dem falschen Verzeichnis gestartet hast, ist die Meldung genau dieselbe und die Lösung nicht. Der Pfad in der Meldung hilft: Er ist der ganze Name, den Singe versucht hat, gezählt ab dem Ordner, in dem du es gestartet hast, und das rocks/ vorne ist der Teil, den DIR hinzugefügt hat. Prüf drei Dinge, in dieser Reihenfolge: Heißt die Datei genau so, wie du getippt hast, liegt sie im Ordner art, und liegt dieser Ordner art neben deinem Skript?

Was du gelernt hast

  • Ein Bild, das aufs Overlay gezeichnet wird, ist ein Sprite und wird mit spriteLoad geladen.

  • spriteLoad gibt ein Handle zurück: eine Zahl, die für die Engine „dieses Bild“ bedeutet und die du in einer Variablen aufbewahrst.

  • DIR ist der Ordner, in dem dein Skript liegt, und jede Datei, die dein Spiel lädt, sollte damit benannt werden.

  • spriteDraw(handle, x, y) zeichnet es, ab seiner linken oberen Ecke, und nur in onOverlayUpdate. Ein viertes Argument true meint stattdessen die Mitte.

  • Lade einmal, oben in der Datei. Laden in onOverlayUpdate frisst Speicher, bis das Spiel stirbt.

  • spriteUnload gibt ein Bild zurück, meistens aus onShutdown, und danach ist das Handle tot.

  • PNG kann Transparenz, und darum sind die Ecken des Raumschiffs keine schwarzen Kästen.

  • spriteGetWidth und spriteGetHeight messen ein Sprite so, wie es jetzt gezeichnet würde, also musst du seine Größe nie in dein Programm tippen.

  • Sprites verdecken einander. Die Reihenfolge, in der du zeichnest, geht von hinten nach vorne.

  • spriteLoadFrames(count, file) zerteilt einen Streifen in Frames, und spriteDrawFrame(handle, x, y, frame) zeichnet einen davon, gezählt ab 1.

Beim nächsten Mal

Das Spiel sieht richtig aus und klingt nach überhaupt nichts. In Lektion zehn bekommen die Schüsse ein Geräusch, die Felsen eine Explosion, und unter dem Ganzen spielt etwas — und du lernst deinen fünften Callback kennen, den, mit dem die Engine dir sagt, dass ein Sound zu Ende ist.

Lektion 10: Sound

Die fertige Lektion

Ein Spiel ohne Sound fühlt sich kaputt an, und zwar auf eine Art, die man schwer benennen kann. Die Schüsse fliegen los, und nichts passiert. Die Felsen zerbrechen, und nichts passiert. Leg auf jedes davon ein Geräusch von einer halben Sekunde, und dasselbe Spiel fühlt sich plötzlich an, als wäre es aus etwas gemacht.

Diese Lektion gibt deinem Spiel einen Schuss, eine Explosion und Musik darunter. Unterwegs stellt sie dir deinen fünften Callback vor: den, mit dem die Engine dir sagt, dass ein Sound fertig abgespielt ist.

Ein Geräusch

Im Grafik-Kit, das du in Lektion neun kopiert hast, stecken zwei Sounds, shoot.wav und boom.wav, und die Explosion ist von den beiden leichter zu hören. Leg neben deinem Ordner art eine neue Datei an und tipp das ein.

dofile("Singe/Framework.singe")

local boom = soundLoad(DIR .. "art/boom.wav")


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(boom)
    end
end


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Press space.")
    return OVERLAY_UPDATED
end


function onShutdown()
    soundUnload(boom)
end

Starte es und tipp drei- oder viermal schnell auf die Leertaste. Die Knalle türmen sich übereinander, statt einander abzuschneiden.

Hältst du die Leertaste gedrückt, bekommst du genau einen Knall, keinen ganzen Strom davon. Das ist dasselbe Verhalten, das du in Lektion drei kennengelernt hast: Eine gehaltene Taste ist ein Drücken, einmal gemeldet, und die Engine wirft die Wiederholungen weg, die deine Tastatur schickt. Darum braucht das Lenken onInputReleased und eine Variable, statt Tastendrücke zu zählen.

Was gerade passiert ist

Die Form ist dieselbe wie in Lektion neun: einmal oben laden, das Handle benutzen, am Ende zurückgeben.

local boom = soundLoad(DIR .. "art/boom.wav")

soundLoad liest eine Audiodatei, behält sie im Speicher und gibt ein Handle zurück — dieselbe Idee wie ein Sprite-Handle, eine Zahl, die für die Engine „diesen Clip da“ bedeutet. DIR steht aus demselben Grund da wie in Lektion neun: Der Sound wohnt im Ordner deines Spiels, und das Spiel muss ihn finden können, egal von wo aus Singe gestartet wurde.

Alles, was Lektion neun übers Laden gesagt hat, gilt hier Wort für Wort. Lade oben in der Datei, einmal. Ein soundLoad in onOverlayUpdate lädt den Clip sechzigmal pro Sekunde und gibt nie einen zurück, und ein paar Minuten später stirbt das Spiel daran.

        soundPlay(boom)

Spiel ihn ab. Mehr gehört zum Abspielen eines Soundeffekts nicht, und um den Rest kümmert sich die Engine: Der Clip fängt an, er hört auf, und er kommt deinem Programm nie in die Quere.

Aber soundPlay gibt auch etwas zurück, und das ist nicht dieselbe Zahl, die du hineingegeben hast. Ändere die Zeile und sieh hin:

        local channel = soundPlay(boom)
        debugPrint("clip " .. boom .. " on channel " .. channel)

Tipp ein halbes Dutzend Mal schnell auf die Leertaste und beobachte die beiden Zahlen. Die Clip-Nummer ändert sich nie. Die Kanalnummer steigt — 0, dann 1, dann 2 — und sobald die früheren Knalle vorbei sind, fällt sie zurück und fängt an, die kleinen Nummern wiederzuverwenden.

Das ist die eine Sache beim Sound, über die jeder stolpert, also lohnt es sich, sie langsam zu sagen. Hier sind zwei verschiedene Arten von Zahlen im Spiel.

Das Clip-Handle von soundLoad ist die Aufnahme. Davon gibt es eins. Es ändert sich nicht, es spielt weder, noch spielt es nicht, es ist der Sound, der im Speicher sitzt und darauf wartet, benutzt zu werden.

Der Kanal von soundPlay ist eine Aufführung dieser Aufnahme. Singe hat sechzehn davon, nummeriert von 0 bis 15, und jeder Sound, den man gerade hört, belegt einen. Darum überlappen sich die Knalle: Das zweite Drücken hat das erste nicht unterbrochen, es hat eine zweite Aufführung auf dem nächsten freien Kanal gestartet.

Alles, was mit einem Sound, den du hörst, etwas tut, nimmt einen Kanal: soundStop, soundIsPlaying, soundPause, soundResume. Alles, was mit der Aufnahme etwas tut, nimmt das Handle: soundPlay und soundUnload. Gib das eine dort hinein, wo das andere hingehört, und du bekommst nicht immer einen Fehler, denn 3 ist eine gültige Kanalnummer und auch ein völlig brauchbares Clip-Handle — du bekommst Stille, oder der falsche Sound hört auf, und das ist viel schwerer zu finden.

Sechzehn ist viel, aber nicht endlos. Wenn alle Kanäle belegt sind, spielt nichts, und soundPlay gibt statt einer Kanalnummer -1 zurück. Ein Spiel, das sehr viele Sounds auf einmal abfeuert, sollte damit rechnen, und gleich schreibst du eins.

Lautstärke

Es gibt drei Lautstärken, und sie werden miteinander multipliziert.

Die Gesamtlautstärke der Effekte gilt für alles. soundGetVolume liest sie, und soundSetVolume setzt sie, auf einer Skala von 0 bis 63.

    soundSetVolume(40)

Lass es. Diese Zahl gehört dem Spieler, nicht dir: Sie startet bei dem, was er beim Starten des Spiels verlangt hat, und ein Spiel, das sie überschreibt, ist ein Spiel, das in irgendjemandes stillem Zimmer zu laut ist. Ändere die Gesamtlautstärke nur, wenn der Spieler dich darum bittet, über einen Optionsbildschirm. soundGetVolume gibt es, damit ein Optionsbildschirm zeigen kann, wie hoch sie gerade ist, statt zu raten.

Wonach du greifen solltest, ist die Kanallautstärke, die unter der Gesamtlautstärke sitzt. Gib soundPlay ein drittes Argument, und diese eine Aufführung ist leiser:

    soundPlay(shootClip, 0, 35)

Die 0 in der Mitte gibt an, wie oft wiederholt wird, und die musst du angeben, weil die Lautstärke danach kommt. 0 heißt: einmal abspielen. -1 heißt: in Schleife, bis etwas es anhält, und so würdest du ein Motorbrummen oder Wind machen. Der Eintrag zu soundPlay in der Referenz listet alle drei Argumente auf.

Die dritte Lautstärke ist die Entfernung, für Sounds, die in einer 3D-Welt platziert sind. Die kommt in Teil vier dran, wenn das Spiel in drei Dimensionen umzieht.

Musik hat eine eigene Lautstärke, und die hat eine andere Skala. Gleich mehr dazu.

Anhalten und Nicht-Anhalten

soundStop nimmt einen Kanal und schneidet ihn dort ab, wo er gerade ist:

    soundStop(engineChannel)
    engineChannel = -1

Beachte die zweite Zeile. Sobald ein Kanal aufhört, darf die Engine genau diese Nummer an das nächste soundPlay vergeben, also gehört eine Kanalnummer, die du noch festhältst, jetzt vielleicht zu einem völlig anderen Sound. Wirf sie weg, sobald du ihn anhältst. -1 ist das Nützliche, was du dort hineinschreibst, denn das ist derselbe Wert, den dir soundPlay gibt, wenn es gar nichts abspielen konnte, und so deckt ein einziger Test beides ab: if channel >= 0 then.

soundStop ist für einen Sound, der jetzt falsch ist — das Motorgeräusch, wenn der Motor ausgeht, der Alarm, wenn jemand auf den Alarm reagiert hat. Für einen kurzen Effekt ist es das falsche Werkzeug. Eine halbsekündige Explosion, die nach einer Zehntelsekunde abgehackt wird, klingt wie ein Fehler, weil sie einer ist.

Also tu meistens einfach gar nichts. Lass ihn zu Ende spielen. Ein Soundeffekt, den du startest und an den du nie wieder denkst, hört von selbst auf und gibt seinen Kanal von selbst frei, und genau das willst du.

Das gilt sogar am Ende. soundUnload schneidet einen Clip, der noch spielt, nicht ab: Die Engine hält den Ton am Leben, bis der letzte Kanal, der ihn benutzt, aufgehört hat. Du kannst in onShutdown entladen, ohne dir Sorgen zu machen, dass du etwas zum Schweigen gebracht hast.

soundIsPlaying(channel) beantwortet, ob ein Kanal gerade Geräusche macht. Wofür man es hauptsächlich braucht, ist nicht Neugier, sondern Zurückhaltung: ein Alarm, der einmal ertönen soll und nicht jedes Mal neu anfängt, wenn das Spiel merkt, dass die Gefahr immer noch da ist.

function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

Lies die Bedingung laut vor: Spiel den Alarm ab, wenn es keinen Alarmkanal gibt oder wenn der, den du hast, aufgehört hat. Sonst lass ihn in Ruhe.

Der Sound, der stottert

Jetzt kommt der Fehler. Jeder schreibt ihn, meistens innerhalb einer Woche, nachdem er Sound entdeckt hat.

Angenommen, du willst, dass das Schiff weiterfeuert, solange der Knopf gedrückt ist, statt einmal pro Drücken. Du würdest es so machen, wie du lenkst: eine Variable firing, die in onInputPressed auf true gesetzt wird und in onInputReleased zurück auf false, und der Schuss wird in onOverlayUpdate erzeugt, solange sie wahr ist. Das ist ein völlig vernünftiger Wunsch, und das Geräusch sieht aus, als gehörte es genau dorthin, zum Schuss:

function onOverlayUpdate()
    if firing then
        shots[#shots + 1] = { x = shipX, y = shipY }
        soundPlay(shootClip)
    end
    ...

Was herauskommt, ist kein Schuss. Es ist ein surrendes Rasseln oder ein harter, flacher Ton oder ein Geräusch, als ginge eine kleine Maschine kaputt.

onOverlayUpdate läuft etwa sechzigmal pro Sekunde. Halt den Knopf eine Sekunde lang gedrückt, und du hast sechzig Aufführungen eines Clips verlangt, der ungefähr eine Fünftelsekunde dauert, und jede fängt über der letzten an. In jedem Moment spielen etwa elf davon, jede einen Frame hinter der vorigen, und was du hörst, sind sechzig Kopien desselben Anfangs, übereinandergestapelt.

Die Lösung ist kein schlauerer Sound. Sie besteht darin, den Sound dort abzuspielen, wo das Ereignis passiert, und nicht dort, wo der Zustand wahr ist:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(shootClip, 0, 35)
    end
end

onInputPressed passiert einmal, wenn der Knopf runtergeht. Ein Drücken, ein Schuss, ein Geräusch.

Wenn du wirklich Dauerfeuer willst, ist die Antwort dieselbe, nur in anderer Form: Mach das Feuern selbst zu einem Ereignis. Zähl Frames, genau wie der Laufzyklus sie in Lektion neun gezählt hat, und erzeuge nur jeden achten Frame einen Schuss. Das Geräusch gehört zum Schuss, also spielt es sieben- oder achtmal pro Sekunde statt sechzigmal, und das ist ein Maschinengewehr statt eines Rasselns.

Das ist die Regel, und es lohnt sich, sie aus dieser Lektion mitzunehmen: Sounds gehören zu Ereignissen, nicht zu Bedingungen. Ein Drücken, ein Treffer, ein Tod, ein aufgesammeltes Ding — jedes davon passiert einmal und verdient einen Sound. „Der Knopf ist unten“ und „das Schiff bewegt sich“ sind keine Ereignisse; sie sind Hunderte Frames hintereinander wahr, und alles, was du von dort aus abspielst, spielt hundertfach.

Gehört ein Sound wirklich zu einem Zustand, der andauert — ein Motor, Wind, eine Sirene — dann starte ihn einmal mit -1 als Schleifenzahl, behalt den Kanal und halt ihn an, wenn der Zustand endet.

Der fünfte Callback

Manchmal musst du tatsächlich wissen, wann ein Sound fertig ist. Schreib diese Funktion, und die Engine ruft sie auf:

function onSoundCompleted(channel)
end

Das ist dein fünfter Callback, nach onOverlayUpdate in Lektion eins, den beiden Eingabe-Callbacks in Lektion drei und onShutdown in Lektion neun, und er funktioniert genauso wie sie alle: Du schreibst ihn, du rufst ihn nie auf, die Engine ruft dich. Der channel, den er dir übergibt, ist der Kanal, der gerade still geworden ist — die Nummer, die dir soundPlay gegeben hat, als du ihn gestartet hast.

Er wird ausgelöst, wenn ein Clip zu Ende ist, wenn die letzte Wiederholung einer Schleife fertig ist, und wenn du einen Kanal selbst mit soundStop anhältst. Das Letzte überrascht Leute, die mit dem Callback einen Sound an den nächsten hängen: Auch ein absichtlich angehaltener Kanal wird als fertig gemeldet, und wenn du nicht aufpasst, startet der nächste Sound in der Kette trotzdem.

Das Spiel benutzt ihn gleich für etwas, das sich lohnt. Wenn das letzte Leben weg ist, spielt die Explosion des Schiffs, und das Spiel hält still — kein GAME OVER, kein Ausblenden der Musik — bis diese Explosion wirklich vorbei ist. Dann hört alles auf einmal auf. Das sind eine Handvoll Zeilen, und sie machen den Unterschied zwischen einem Ende und einem Schnitt.

Musik ist kein Soundeffekt

Du könntest ein dreiminütiges Stück mit soundLoad laden und mit soundPlay abspielen. Tu es nicht. Musik bekommt eine eigene Familie von Aufrufen, und zwar aus Gründen, die zählen:

  • Musik hat ihre eigene Lautstärke, getrennt von den Effekten, also kann ein Spieler die Musik leiser drehen und die Schüsse trotzdem hören.

  • Es gibt keine Grenze von sechzehn Kanälen und keine Kanalnummer. Ein Handle ist ein Musikstück, und du hältst es über dieses Handle an, pausierst es und setzt es fort.

  • musicStop kann ein Stück über ein, zwei Sekunden ausblenden, statt es abzuschneiden.

Die Aufrufe spiegeln die, die du schon kennst:

local theme = musicLoad("Singe/menuIntro.flac")

musicSetVolume(50)
musicPlay(theme, -1)

musicLoad gibt ein Handle. musicPlay startet es, mit derselben Schleifenzahl wie soundPlay: -1 für immer. musicStop(theme) beendet es, und musicStop(theme, 1500) nimmt sich anderthalb Sekunden, um es auszublenden. musicUnload gibt es zurück.

Jetzt die Falle. Die Musiklautstärke reicht von 0 bis 128, nicht von 0 bis 63. Soundeffekte benutzen eine Skala und Musik eine andere, doppelt so lange, aus historischen Gründen, die überhaupt kein Trost sind, wenn deine Musik mit der halben Lautstärke herauskommt, die du gemeint hast. Wenn du mit Musik arbeitest, verdopple die Zahl, die du für einen Effekt im Kopf hattest.

Das Stück, das dort geladen wird, ist die eigene Menümusik der Engine, aus dem Ordner Singe, den die Engine bei deinem ersten Start in deinen Arbeitsordner entpackt hat. Es ist zehn Sekunden lang und wurde so geschrieben, dass es am Ende ausblendet, also klingt es in Schleife genau wie eine zehnsekündige Schleife, die immer wieder ausblendet. Zum Lernen der Aufrufe ist das in Ordnung, und für ein fertiges Spiel taugt es überhaupt nicht, denn das liefert ein längeres eigenes Stück mit. Jedes der üblichen Formate geht: Der Abschnitt Musik in der Referenz listet sie auf, und Ogg Vorbis oder MP3 sind die vernünftige Wahl, weil ein paar Minuten Musik als WAV eine riesige Datei sind.

Das Spiel bekommt einen Soundtrack

Öffne das Spiel aus Lektion neun. Alles hier kommt dazu; nichts fliegt raus.

Vier Dinge zum Laden, oben, bei den Sprites:

local shootClip = soundLoad(DIR .. "art/shoot.wav")
local boomClip  = soundLoad(DIR .. "art/boom.wav")
local clickClip = soundLoad("Singe/click.wav")
local theme     = musicLoad("Singe/menuIntro.flac")

Die ersten beiden haben ein DIR davor und die letzten beiden nicht, und das ist Absicht. DIR bedeutet den Ordner deines Spiels. Ein Name, der mit Singe/ anfängt, bedeutet stattdessen den eigenen Ordner der Engine, wo auch immer der ist — und darum funktioniert dofile("Singe/Framework.singe") seit Lektion sieben ebenfalls ohne DIR. Deine eigenen Dateien brauchen DIR; die der Engine nie.

Zwei neue Variablen, neben den anderen:

local dying        = false
local deathChannel = -1

dying ist der Moment zwischen dem Verlust des letzten Lebens und dem Ende des Spiels: Die Explosion klingt noch, und auf dem Bildschirm bewegt sich nichts.

Der Schuss bekommt sein Geräusch in onInputPressed, genau dort, wo der Schuss selbst erzeugt wird, und der Neustart bekommt einen Klick, damit sich das Drücken von 1 anfühlt, als hätte es etwas getan:

function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            soundPlay(clickClip)
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    end
end

Ein Felsen, der getroffen wird, knallt, und ein Felsen, der dich trifft, auch. In updateShots, neben den Punkten:

                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)

Und in updateRocks, wo das Leben verloren geht, der interessante Teil:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

Wenn das letzte Leben weg ist, spielt die Explosion, und ihr Kanal wird gemerkt. Das Spiel ist jetzt dying, und das hält alle Bewegung an, sagt aber noch nicht GAME OVER.

Das if channel < 0 ist die Grenze von sechzehn Kanälen, erledigt. Falls genau in diesem Moment zufällig alle Kanäle belegt waren, gibt es keine Explosion und keinen Kanal, auf den man warten könnte, und ohne diese beiden Zeilen säße das Spiel für immer in dying fest und wartete auf einen Sound, der nie gespielt wurde. Auf etwas zu warten, das nicht kommen kann, ist einer der einfachsten Wege, ein Programm aufzuhängen, und die Absicherung ist immer billiger als der Fehler.

Jetzt der neue Callback und die kleine Funktion, die er sich mit dieser Absicherung teilt:

function endGame()
    dying        = false
    deathChannel = -1
    over         = true
    musicStop(theme, 1500)
end


function onSoundCompleted(channel)
    if channel == deathChannel then
        endGame()
    end
end

Die Engine ruft onSoundCompleted für jeden Kanal auf, der aufhört, also prüft er als Erstes, ob das der Kanal ist, der ihn interessiert. Alles andere — jeder Schuss, jeder Felsen — läuft durch und wird ignoriert.

onOverlayUpdate muss stillhalten, solange die Explosion läuft, und das ist ein Wort:

    if not over and not dying then
        updateShip()
        updateShots()
        updateRocks()
    end

startGame setzt die beiden neuen Variablen zurück und startet die Musik von vorn:

    dying        = false
    deathChannel = -1
    musicSetVolume(50)
    musicPlay(theme, -1)

Und onShutdown gibt zurück, was geladen wurde:

function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
    soundUnload(shootClip)
    soundUnload(boomClip)
    soundUnload(clickClip)
    musicUnload(theme)
end

Starte es. Schieß auf die Felsen, lass dich dreimal von einem treffen und hör dir das Ende an: Der letzte Knall spielt vollständig aus, und erst wenn er weg ist, fängt die Musik an auszublenden, und die Worte erscheinen.

Das fertige Skript liegt im Ordner learn als 10-sound.singe, falls du vergleichen willst.

Probier es aus

  1. Mach den Schuss noch leiser. Ändere die 35 im soundPlay des Schusses in 10, dann in 63. Finde die Zahl, bei der er unter den Explosionen liegt statt obendrauf.

  2. Dreh die Musik leiser, ohne die Effekte anzufassen. Ändere musicSetVolume(50) in musicSetVolume(15). Überzeug dich, dass die Knalle genauso laut sind wie vorher, und genau deshalb ist Musik ein eigenes System.

  3. Schneid das Ende ab. Ändere in endGame das musicStop(theme, 1500) in musicStop(theme). Hör dir beide Enden zweimal an. Der Unterschied ist eine Zahl in einem Argument, und er ist kein kleiner Unterschied.

  4. Gib dem Schiff einen Motor. Starte soundPlay(clickClip, -1, 12) in startGame, heb den Kanal, den es dir gibt, in einer eigenen Variablen auf und halt ihn in endGame an. Der Klick dauert eine Fünfzigstelsekunde, also ist er in Schleife ein Brummen, und näher kommt dieses Kit an einen Motor nicht heran. Dann nimm das soundStop wieder heraus, spiel drei Spiele hintereinander und hör dir an, was du gebaut hast.

  5. Zähl die Kanäle. Gib jedes Mal, wenn ein Felsen explodiert, die Kanalnummer aus. Dann erhöh ROCK_COUNT, bis mehrere auf einmal explodieren, und erhöh weiter, bis du eine -1 vorbeikommen siehst.

Mach es absichtlich kaputt

Du hast jetzt zwei Lautstärkeskalen im Kopf, und früher oder später kommt die falsche aus deinen Fingern. Füg diese Zeile für sich allein ein, direkt unter den vier Zeilen mit soundLoad und musicLoad:

soundSetVolume(100)

Das Spiel weigert sich zu starten:

20:soundSetVolume:  Invalid sound volume value:  100

Die Zeilennummer, die du bekommst, ist die Zeile, in die du es tatsächlich getippt hast, deine ist also vielleicht nicht 20. Dann kommt die Funktion, die sich beschwert hat, und der Wert, über den sie sich beschwert hat. Die Meldung sagt dir nicht, wie groß der Bereich ist — dafür ist der Eintrag zu soundSetVolume in der Referenz da — aber sie sagt dir die Zahl, die sie nicht angenommen hat, und sobald du weißt, dass Effekte bei 63 aufhören, ist die Korrektur eine einzige Zahl.

100 ist eine verdächtige Zahl für eine Lautstärke, und es lohnt sich zu wissen, warum du sie getippt hast. Fast sicher hast du dir Lautstärke als Prozentwert gedacht, weil jeder Lautstärkeregler, den du je benutzt hast, bis 100 geht. Der von Singe nicht. Effekte gehen von 0 bis 63 und Musik von 0 bis 128, und keins von beiden ist ein Prozentsatz von irgendetwas.

Das ist die allgemeine Form eines Engine-Fehlers, im Gegensatz zu den Lua-Fehlern in Lektion eins: eine Zeilennummer, der Name der Engine-Funktion, die du aufgerufen hast, und eine Beschwerde über die Werte, die du ihr übergeben hast. Wenn du so einen siehst, ist der Eintrag zu dieser Funktion in der Referenz das Nächste, was du liest.

Was du gelernt hast

  • soundLoad liest einen Clip und gibt ein Handle zurück. Lade einmal, oben in der Datei.

  • soundPlay startet einen Clip und gibt einen Kanal zurück, und das ist eine andere Art von Zahl als das Handle.

  • Singe mischt sechzehn Kanäle. Wenn alle belegt sind, gibt soundPlay -1 zurück, und nichts spielt.

  • Kanalnummern werden wiederverwendet. Vergiss eine, sobald du ihren Kanal angehalten hast.

  • Kurze Effekte lässt du in Ruhe zu Ende spielen; soundStop ist für Sounds, die falsch geworden sind.

  • soundUnload schneidet einen Clip, der noch spielt, nicht ab.

  • Spiel einen Sound dort ab, wo das Ereignis passiert, nicht dort, wo eine Bedingung wahr ist, sonst spielt er sechzigmal pro Sekunde.

  • onSoundCompleted(channel) ist ein Callback, den die Engine jedes Mal aufruft, wenn ein Kanal still wird, egal aus welchem Grund.

  • Musik ist ein eigenes System mit eigenen Handles, eigener Lautstärke und ohne Kanalgrenze.

  • Die Effektlautstärke geht von 0 bis 63. Die Musiklautstärke geht von 0 bis 128. Das sind keine Prozentwerte.

Beim nächsten Mal

Deine Felsen werden getroffen, wenn sich ihre Rechtecke überlappen, und darum zählt ein Schuss auch dann, wenn er durch eine Ecke des Himmels fliegt. In Lektion elf bekommst du die eigenen Kollisionstests der Engine, lernst, was eine Hitbox ist, und findest heraus, warum das Rechteck um einen runden Felsen die falsche Form hat.

Lektion 11: Dinge treffen

Die fertige Lektion

Dein Spiel aus Lektion zehn funktioniert. Schüsse zerbrechen Felsen, Felsen kosten Leben, und die Explosionen knallen an den richtigen Stellen. Sieh aber genau hin, und du merkst, dass es schummelt, und zwar in beide Richtungen. Ein Felsen, der an der Flügelspitze vorbeigleitet, kostet ein Leben. Ein Schuss, der neben einem Felsen durch den leeren Himmel fliegt, zerbricht ihn trotzdem.

Zwei Dinge in einem Spiel berühren sich, wenn die Zahlen das sagen. Niemand sieht sich die Bilder an. Diese Lektion bringt die Zahlen mit dem in Einklang, was der Spieler sieht: Sie tauscht deinen selbst geschriebenen Test gegen den der Engine, verkleinert die geprüften Boxen, bis sie zu den Dingen darin passen, und gibt dir einen Schalter, der dir diese Boxen zeigt. Das Bild oben ist das Spiel mit eingeschaltetem Schalter.

Wo du stehst

Das Spiel fragt an genau zwei Stellen „berühren sich diese beiden?“, und beide benutzen overlapping, die Funktion, die du in Lektion neun eingetippt hast. Die eine steht in updateRocks, wo ein Felsen auf das Schiff trifft:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then

Die andere steht in updateShots, wo ein Schuss auf einen Felsen trifft:

            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Alles in dieser Lektion ändert diese beiden Zeilen und fügt ein paar kleine Funktionen hinzu, die sie füttern. Sonst ändert sich am Spiel nichts. Das ganze fertige Skript liegt in learn/11-hitting-things.singe, falls du dich verläufst.

Lies es noch einmal

Diesen Teil hat Lektion neun schon erledigt: overlapping ist Rechteckkollision, von Hand ausgeschrieben. Lies es noch einmal, bevor du es wegwirfst, denn es ist die ganze Idee:

function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end

Direkt ist die Frage „berühren sich diese beiden?“ schwer zu beantworten, rückwärts ist sie leicht. Zwei Rechtecke berühren sich nicht, wenn eins von ihnen ganz links vom anderen liegt, oder ganz rechts, oder ganz darüber, oder ganz darunter. Eine fünfte Art, sich zu verfehlen, gibt es nicht. Wenn keine dieser vier stimmt, berühren sie sich.

Jedes if ist eine der vier Arten, sich zu verfehlen. ax + aw ist der rechte Rand des ersten Rechtecks, also liest sich ax + aw ⇐ bx als „das erste hört auf, bevor das zweite anfängt“, und genau das bedeutet „ganz links“ in Zahlen. Dieselbe Form noch dreimal, für rechts, darüber und darunter, mit y und den Höhen statt x und den Breiten, und dann bleibt nur noch true übrig.

Das sind die acht Zahlen, die jeder Kollisionstest braucht: eine Ecke und eine Größe für jedes der beiden Dinge. Behalt die Form im Kopf, denn gleich löschst du sie.

Die Engine hat es schon

collideRects kennst du aus Lektion sieben, wo es in Dodge die fallenden Blöcke erwischt hat. Lektion neun hat denselben Test von Hand ausgeschrieben, damit du hineinsehen kannst. Du hast hineingesehen. Lösch overlapping und ändere die beiden Zeilen aus Wo du stehst so, dass sie stattdessen die Engine aufrufen:

        if collideRects(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            if not gone and collideRects(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Dieselben acht Zahlen, in derselben Reihenfolge: Ecke und Größe des ersten Rechtecks, dann die des zweiten. Starte es, und das Spiel spielt sich genau wie vorher, und genau darum geht es. Der einzige Unterschied liegt ganz am Rand. Dein ⇐ hat gesagt, dass sich zwei Rechtecke, die sich an einer Kante treffen, nicht berühren. collideRects sagt, dass sie es tun, und ein Rechteck ohne Breite oder Höhe berührt überhaupt nichts. In solchen kniffligen Fällen gehen selbst geschriebene Versionen still und leise schief, und sie sind ein Grund, die der Engine zu benutzen.

collideRects gehört zu einer Familie von Kollisionstests, und die Familie ist ein Teil dessen, was dieses Buch das Spiele-Kit nennt: eine Handvoll schlichter Funktionen für die Dinge, die früher fast jedes Spiel für sich selbst geschrieben hat. Zu prüfen, ob sich zwei Dinge berühren, ist eins davon. Eine Zahl fürs nächste Mal aufzuheben ist ein anderes, und das ist Lektion zwölf. Eine Weile warten, eine Zahl sanft von einem Wert zum anderen gleiten lassen und zeigen, wie lange jeder Frame gedauert hat, sind der Rest. Die Referenz gibt jedem Teil einen eigenen Abschnitt: Kollision, Spielstand, Timer, Tween und Statistik.

Die Kollisionstests sind die schlichtesten von allen: schlichte Fragen, ohne Handles, die man aufheben muss, und ohne etwas, das man einrichten oder freigeben muss. Und keiner davon bewegt irgendetwas. collideRects sagt dir, dass Schiff und Felsen am selben Ort sind; was du dagegen tust, entscheidest du, und alles Interessante an einem Spiel passiert in dieser Entscheidung.

Das Bild ist nicht die Hitbox

Lektion zehn hat versprochen zu erklären, warum das Rechteck um einen runden Felsen die falsche Form hat. Das Rechteck um das Schiff ist auch falsch, und zwar aus demselben Grund.

Zeichne das Rechteck des Schiffs, 32 mal 24, auf Papier und mal das Schiff darin aus. Es ist ein Dreieck mit zwei Flossen, also ist in beiden oberen Ecken und zwischen den Flossen leerer Himmel. Der Felsen ist rund, also ist in allen vier Ecken seines Quadrats leerer Himmel. Ein Felsen, der die obere Ecke des Schiffsrechtecks streift, hat das Schiff nicht getroffen. Er ist am Flügel vorbeigeflogen, und ein Spieler, der dafür ein Leben verliert, wird sagen, dass das Spiel geschummelt hat — und er hat recht.

Die Box, die du prüfst, ist also nicht das Bild, das du zeichnest. Sie ist kleiner, und sie sitzt im Bild. Füg den Konstanten oben in deiner Datei drei Zahlen hinzu:

local SHIP_PAD_X  = 6
local SHIP_PAD_Y  = 5
local ROCK_PAD    = 4

Der Abstand sagt, wie weit vom jeweiligen Rand nach innen das echte Ding anfängt. Sechs Pixel weg an jeder Seite des Schiffs und fünf oben und unten lassen eine Box von 20 mal 14 in der Mitte eines Bilds von 32 mal 24 übrig, und da ist ungefähr der Rumpf. Vier weg an jeder Seite des Felsens lassen 16 mal 16 übrig, und das ist fast nur Felsen.

Beide Boxen sind ein bisschen kleiner als die Dinge, für die sie stehen, und das ist Absicht. Eine Box, die etwas zu klein ist, beschert dem Spieler Beinahe-Treffer, die sich wie Können anfühlen. Eine Box, die etwas zu groß ist, beschert ihm Treffer, die sich wie Schummelei anfühlen. Spieler verzeihen das Erste und nie das Zweite.

Statt diese Rechnung bei jedem Test auszuschreiben, schreib sie einmal pro Art von Ding:

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end


function shipBox()
    return shipX + SHIP_PAD_X, shipY + SHIP_PAD_Y, shipWidth - SHIP_PAD_X * 2, shipHeight - SHIP_PAD_Y * 2
end

Die Größen kommen aus rockWidth, shipWidth und ihren Freunden, den Messungen, die Lektion neun an den Bildern vorgenommen hat, also steht im Spielcode immer noch keine einzige nackte Pixelgröße. Zeichne das Schiff größer, und die Box wächst mit.

Jede dieser Funktionen gibt vier Zahlen auf einmal zurück, durch Kommas getrennt. Eine Funktion darf so viele Werte zurückgeben, wie sie will, und auffangen kannst du sie mit einer Liste von Namen links vom =:

function shipHitsRock(rock)
    local sx, sy, sw, sh = shipBox()
    local rx, ry, rw, rh = rockBox(rock)

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)
end

Jetzt liest sich der Test in updateRocks wie die Frage, die er stellt:

        if shipHitsRock(rock) then

Die Rechnung mit dem Abstand steht an genau zwei Stellen, und die Zahlen, die sie benutzt, stehen oben in der Datei, also kannst du einstellen, wie fair sich das Spiel anfühlt, indem du eine Zahl änderst, statt deine Tests zu durchsuchen.

Setz die neuen Funktionen an ihre Plätze im Alphabet, wie Lektion neun es verlangt hat: rockBox nach onSoundCompleted, dann shipBox und shipHitsRock.

Zurückschießen

Damit ist die Seite des Schiffs erledigt. Die andere Kollision im Spiel ist die, mit der du zurückschießt: jeder Schuss gegen jeden Felsen, in updateShots. Sie hat dasselbe Problem wie das Schiff, nur in klein. Ein Schuss ist ein Rechteck von 4 mal 10, das gegen das ganze Quadrat des Felsens von 24 mal 24 geprüft wird, also zerbricht ein Schuss, der nur durch die leere Ecke neben einem Felsen fliegt, ihn trotzdem.

Du könntest dem Schuss eine eigene Box mit Abstand geben. Sieh dir aber zuerst die Zahlen an. Zieh von einem Schuss, der vier Pixel breit ist, einen Abstand ab, und es bleibt fast nichts übrig, und ein ganzes Rechteck zu prüfen, nur um herauszufinden, ob ein Lichtsplitter etwas berührt hat, ist mehr Maschinerie, als die Frage verdient.

Ein Schuss ist fast ein Punkt

Prüf stattdessen die Spitze. collidePointRect fragt, ob ein Punkt in einem Rechteck liegt — zwei Zahlen für den Punkt, dann Ecke und Größe des Rechtecks:

function shotHitsRock(shot, rock)
    local rx, ry, rw, rh = rockBox(rock)

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)
end

shot.y ist die Oberkante des Schusses, und shot.x + shotWidth / 2 liegt auf seiner halben Breite, also ist der geprüfte Punkt die Mitte der Nase des Schusses. Dort glaubt ein Spieler, dass ein Schuss ist. Auf der Seite des Felsens steht dasselbe rockBox, das auch der Test des Schiffs benutzt, also ist ein Felsen gleich groß, egal was ihn trifft.

Die Funktion kommt nach shipHitsRock, und der Test in updateShots wird zu:

            if not gone and shotHitsRock(shot, rock) then

Entscheiden, was passiert ist

Keiner der Kollisionstests tut etwas. Sie antworten, und dein Code entscheidet. Hier sind die beiden Stellen, die entscheiden, mit ihren neuen Fragen darin. Zuerst updateRocks:

        if shipHitsRock(rock) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

Und die Schleife in updateShots:

        for _, rock in ipairs(rocks) do
            if not gone and shotHitsRock(shot, rock) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)
            end
        end

Alles unter den Fragen ist genau das, was Lektion zehn dort hinterlassen hat. Ein Felsen, der das Schiff trifft, knallt, geht zurück nach oben und kostet ein Leben. Ein Felsen, der abgeschossen wird, knallt, geht zurück nach oben und bringt Punkte. Der Schuss verschwindet auch, und das not gone verhindert, dass ein Schuss zwei Felsen zerbricht. Ändere irgendetwas davon, und du änderst das Spiel, ohne einen einzigen Kollisionstest anzufassen, und genau darum werden die Fragen und die Antworten getrennt gehalten.

Starte es. Flieg dicht an einem Felsen vorbei und lass ihn eine Flosse streifen: Du behältst das Leben. Schieß knapp neben einen Felsen, und der Schuss segelt vorbei. Schieß mitten in einen hinein, und er zerbricht, wie immer.

Die Boxen sehen

Die Hitboxen sind unsichtbar, und damit ist auch ein Fehler darin unsichtbar. Zeichne sie, während du arbeitest. Noch eine Konstante oben:

local SHOW_BOXES  = false

Zwei weitere Funktionen, und die kommen ganz an den Anfang des Alphabets:

function drawBox(x, y, width, height)
    overlayBox(x, y, x + width - 1, y + height - 1)
end


function drawBoxes()
    colorForeground(0, 255, 0)
    drawBox(shipBox())
    for _, rock in ipairs(rocks) do
        drawBox(rockBox(rock))
    end
end

Und in onOverlayUpdate, nachdem das Schiff gezeichnet ist und bevor die Punkte obendrauf kommen:

    spriteDraw(shipSprite, shipX, shipY)
    if SHOW_BOXES then
        drawBoxes()
    end
    drawHud()

Ändere SHOW_BOXES in true, und grüne Umrisse erscheinen über den Grafiken, wie im Bild oben in dieser Lektion. Ändere es zurück, wenn du fertig bist. Ein Schalter wie dieser, ein Wort oben in einer Datei, das ein Bild davon einschaltet, was das Programm glaubt, ist mehr wert als noch so viel Anstarren.

Was gerade passiert ist

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end

Vier Werte aus einem return, durch Kommas getrennt. Lua gibt gern so viele zurück, wie du willst, und der Aufrufer entscheidet, wie viele er behält. Wenn so ein Aufruf das Letzte in den Klammern eines anderen Aufrufs ist, werden alle vier weitergereicht, und darum funktioniert drawBox(rockBox(rock)) und gibt drawBox seine vier Argumente. Überall sonst in einer Argumentliste überlebt nur der erste Wert. Diese Regel beißt genau einmal zu, und zwar am Ende dieser Lektion.

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)

collideRects will acht Zahlen: Ecke und Größe, Ecke und Größe. Es gibt true oder false zurück und ändert nichts. Weil die Antwort mit return direkt wieder aus der Funktion herauskommt, liest sich shipHitsRock(rock) überall, wo es benutzt wird, wie eine Frage.

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)

collidePointRect will sechs: einen Punkt, dann ein Rechteck. Der Rand zählt als innen, also trifft ein Schuss genau auf der Grenze. Benutz es immer dann, wenn eine Seite der Frage so klein ist, dass ihre Größe keine Rolle spielt.

    colorForeground(0, 255, 0)
    overlayBox(x, y, x + width - 1, y + height - 1)

Beide kennst du aus Lektion sieben. overlayBox nimmt zwei Ecken, nicht eine Ecke und eine Größe — die einzige Stelle in dieser Lektion, an der die Zahlen ihre Form ändern — und das - 1 ist da, weil beide Ecken dazugehören. colorForeground ist ein Schalter, der umgelegt bleibt, also kommt alles, was drawBoxes zeichnet, grün heraus. Sprites und overlayPrint kümmern sich nicht darum, also sieht der Rest des Spiels aus wie vorher.

Der Rest der Familie

collideRects und collidePointRect tragen die meisten 2D-Spiele. Die anderen sind für die Formen da, die Rechtecke schlecht beschreiben, und jede ist dieselbe Art von schlichter Frage:

  • collideCircles und collidePointCircle, für alles Runde. Ein Kreis ist ein Mittelpunkt und ein Radius.

  • collideRectCircle, für ein rundes Ding gegen ein eckiges.

  • collidePointPolygon, für eine Form mit eigenen Ecken — ein Drache, ein Kontinent, ein seltsam geformter Knopf. Du gibst ihm eine flache Liste von Zahlen: x, y, x, y.

  • collideSegments, für zwei Strecken, die sich kreuzen.

Ehrlich gesagt ist dein Felsen rund, und die Kreistests passen besser zu ihm als jede Box. Der Abstand ist die billige Antwort, und für die meisten Spiele reicht er, darum kommt er zuerst. Die genaue Antwort ist eins der Dinge, die du unten ausprobieren kannst.

collideSegments ist wichtiger, als es klingt. Dein Schuss bewegt sich sechs Pixel pro Frame, und die Felsen haben sechzehn Pixel Hitbox, also kann ein Schuss nicht an einem vorbei, ohne in ihm geprüft zu werden. Mach den Schuss schnell genug — vierzig Pixel pro Frame — und er springt von unterhalb eines Felsens nach oberhalb davon, ist kein einziges Mal am selben Ort wie der Felsen und trifft nie irgendetwas. Die Linie von dort, wo der Schuss war, bis dorthin, wo er jetzt ist, zu ziehen und collideSegments zu fragen, ob diese Linie einen Rand kreuzt, ist das Heilmittel. Langsame Dinge brauchen es nicht.

Es gibt einen Kollisions-Callback in Singe, onCollision, und der ist nicht dafür da. Er gehört zur 3D-Physik-Engine: Körper mit Masse, die in drei Dimensionen fallen und voneinander abprallen und dir sagen, wo sie sich berührt haben und wie heftig. Du lernst ihn in Lektion vierundzwanzig kennen. Nichts auf dem Overlay meldet sich von selbst, und nichts muss das. Deine Felsen sind in einer Liste, du weißt, wie viele es sind, und Fragen ist billig.

Und wenn du nicht nur wissen willst, ob sich zwei Dinge getroffen haben, sondern auch, wo das bewegte landen soll — an einer Wand entlanggleiten, statt mitten in ihr stehen zu bleiben — dann beantworten die Kollisionsaufrufe das mit Absicht nicht. Für genau diese Aufgabe liegt Singe eine Bibliothek namens bump bei, und der Abschnitt Mitgelieferte Bibliotheken in der Referenz sagt, wie du an sie herankommst.

Probier es aus

  1. Nimm den Abstand raus. Setz ROCK_PAD auf 0 und spiel eine Minute. Dann setz es auf 8 und spiel noch einmal. Bei einem davon fühlt es sich an, als würde das Spiel dich anlügen.

  2. Sieh dir an, was du prüfst. Setz SHOW_BOXES auf true und beobachte die grünen Umrisse, während ein Felsen am Schiff vorbeizieht. Jetzt setz SHIP_PAD_X auf 16, spiel und achte darauf, dass dich nichts mehr treffen kann. Finde anhand der Rechnung in shipBox heraus, warum.

  3. Mach den Schuss zu schnell. Setz SHOT_SPEED auf 40. Zähl, wie viele von zehn Felsen du triffst. Rechne an den Zahlen aus, warum das passiert, bevor du es zurückänderst.

  4. Nimm den ganzen Schuss. Schreib shotHitsRock so um, dass es collideRects mit dem vollen Rechteck des Schusses benutzt statt collidePointRect mit seiner Nase. Spiel beide und entscheide, welche dir lieber ist; es gibt keine richtige Antwort, und das zu wissen lohnt sich.

  5. Mach den Felsen rund. Gib dem Felsen einen Kreis statt einer Box: Sein Mittelpunkt liegt rock.x + rockWidth / 2 nach rechts und rock.y + rockHeight / 2 nach unten, und ein Radius von 10 passt ungefähr. Nimm collideRectCircle für das Schiff und collidePointCircle für den Schuss, und zeichne den Kreis in drawBoxes mit overlayCircle, das einen Mittelpunkt und einen Radius nimmt.

Mach es absichtlich kaputt

Die beiden Boxen sind schon je vier Werte, also ist es verlockend, sie direkt hineinzustecken und die acht lokalen Namen wegzulassen:

function shipHitsRock(rock)
    return collideRects(shipBox(), rockBox(rock))
end

Das sieht richtig aus und ist falsch. Starte es, und das Spiel hält an, bevor es überhaupt etwas zeichnet:

186:collideRects:  Expected 8 argument(s), got 5.

Die Zeile ist die, die du gerade getippt hast, deine ist also vielleicht nicht 186. Die Fünf ist aber dieselbe. rockBox(rock) ist das Letzte in den Klammern, also sind alle vier seiner Werte hineingegangen. shipBox() ist es nicht, also wurde es auf einen gekürzt. Eins plus vier ist fünf, und collideRects rät die anderen drei nicht.

Dieser Fehler kommt von der Engine und nicht von Lua, darum hat er dieselbe Form wie die in Lektion neun und zehn: Die Zahl vorne ist die Zeile, dann kommt der Name der Funktion, die sich geweigert hat, dann die Beschwerde. Setz die acht lokalen Namen wieder ein.

Was du gelernt hast

  • Kollision ist Rechnen mit Rechtecken, und du kannst sie selbst schreiben.

  • Zwei Rechtecke verfehlen sich auf genau vier Arten; wenn keine davon stimmt, treffen sie sich.

  • collideRects nimmt eine Ecke und eine Größe für jedes von zwei Rechtecken und antwortet true oder false. Ränder, die sich nur berühren, zählen für ihn als Berührung.

  • Die Kollisionstests gehören zum Spiele-Kit, schlichte Funktionen, bei denen man nichts einrichten muss. Spielstand, Timer, Tween und Statistik sind der Rest davon.

  • collidePointRect fragt, ob ein Punkt in einem Rechteck liegt, und das ist die richtige Frage für alles, was klein ist.

  • Die Box, die du prüfst, ist kleiner als das Bild, das du zeichnest, sonst fühlt sich das Spiel unfair an.

  • Eine Funktion kann mehrere Werte zurückgeben, und nur der letzte Aufruf in einer Argumentliste reicht sie alle weiter.

  • Die Kollisionstests antworten nur. Was danach passiert, ist dein Code, und wenn du die beiden getrennt hältst, kannst du jedes davon allein ändern.

  • Wenn du deine Hitboxen auf den Bildschirm zeichnest, wird aus einem unsichtbaren Fehler ein sichtbarer.

  • onCollision ist für Körper in der 3D-Physik, nicht für Sprites auf dem Overlay.

Beim nächsten Mal

Das Spiel zählt deine Punkte und nimmt dir Leben, und sobald du es beendest, ist die beste Punktzahl, die je jemand erreicht hat, weg. Es steckt mitten in der Action, sobald es geladen ist. Und es merkt sich, was es gerade tut, mit zwei Wahr-oder-falsch-Variablen, over und dying, und das ist genau die Falle, vor der dich Lektion sieben gewarnt hat. Lektion zwölf gibt ihm einen Titelbildschirm, eine Variable statt dieser beiden und einen Highscore, der morgen noch da ist.

Lektion 12: Punkte, Leben und Game Over

Die fertige Lektion

Dein Spiel zählt Punkte, nimmt Leben und sagt GAME OVER. Es ist fast ein Spiel. Drei Dinge fehlen noch. Es hat keine Eingangstür: Sobald es geladen ist, steckt es mitten in der Action. Es vergisst: Beende es, und die beste Punktzahl, die je jemand erreicht hat, geht mit. Und es merkt sich, was es gerade tut, mit zwei Wahr-oder-falsch-Variablen, over und dying, und das ist die Falle, vor der dich Lektion sieben gewarnt hat.

Diese Lektion behebt alle drei. Eine Variable dafür, was das Spiel gerade tut, ein Titelbildschirm, von dem aus es losgeht, ein Highscore, der morgen noch da ist, und ein zweites Spiel, das genau wie das erste anfängt.

Ein Spiel ist immer in genau einem Zustand

Sieh irgendeinem Arcade-Automaten zwei Minuten lang zu. Er zeigt einen Titel und wartet auf jemanden. Jemand drückt Start, und er spielt. Dem Spieler gehen die Leben aus, und der Automat sagt das, dann wartet er wieder. Der Automat tut immer genau eins dieser Dinge.

Dodge in Lektion sieben hat das in einer Variablen festgehalten, die ein Wort hielt: "waiting", "playing" oder "over". Das Spiel aus Lektion neun ist zu einem over zurückgekehrt, das nur wahr oder falsch sein kann, und Lektion zehn hat dying danebengestellt. Zähl, was zwei davon sagen können. Jede ist true oder false, also ergeben sie zusammen vier Kombinationen. Drei bedeuten etwas: Spielen, Sterben und Vorbei. Die vierte, beide auf einmal, ist Unsinn, und dein Code muss sorgfältig darauf achten, sie nie zu erzeugen. Er achtet darauf: Sieh dir endGame an, das dying zurück auf false setzt, bevor es over auf true setzt. Jetzt füg einen Titelbildschirm hinzu. Das ist ein drittes Flag, acht Kombinationen, und vier davon Unsinn. Das ist genau die Falle aus Lektion sieben, und hier gehen kleine Spiele sterben.

Mach es also wie Dodge. Vier Zustände, eine Variable. Schreib die Namen der Zustände unter deine anderen Konstanten:

local TITLE   = "title"
local PLAYING = "playing"
local DYING   = "dying"
local OVER    = "over"

Dann nimm over und dying aus deinen Variablen heraus und setz eine Zeile an ihre Stelle:

local state        = TITLE

Dodge hat die Wörter selbst benutzt. Namen in Großbuchstaben sind nicht schlauer, und sie fangen keinen Tippfehler ab: Lua behandelt einen falsch geschriebenen Namen als nil und ein falsch geschriebenes Wort als ein Wort, zu dem nichts passt, und beides gibt dir ein Spiel, das stillschweigend nicht mehr reagiert. Was dir die Namen einbringen, ist eine Liste. Jeder Zustand, in dem das Spiel sein kann, steht einmal aufgeschrieben oben in der Datei, wo du alle vier auf einen Blick siehst.

Überall, wo das Spiel früher ein Flag gesetzt hat, setzt es jetzt den Zustand. In updateRocks, wo das letzte Leben verloren geht:

            if lives <= 0 then
                state        = DYING
                deathChannel = channel

In endGame werden aus zwei Zeilen eine, und die unsinnige Kombination ist weg, weil es nichts mehr zu kombinieren gibt:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
end

Und in startGame werden die beiden Zeilen, die beide Flags zurückgesetzt haben, zu state = PLAYING.

Eine Stelle, die entscheidet

In jedem Frame trifft onOverlayUpdate die beiden Entscheidungen, auf die es ankommt: was sich bewegt und welche Wörter obendrauf kommen. Was sich bewegt, ist ein einziger Test:

    if state == PLAYING then
        updateShip()
        updateShots()
        updateRocks()
    end

Das ersetzt if not over and not dying then, und es sagt, was es meint. Auf dem Titelbildschirm, während die letzte Explosion spielt, und wenn das Spiel vorbei ist, bewegt sich nichts. Das bekommst du, indem du die Funktionen nicht aufrufst, die Dinge bewegen. Ein Spiel anzuhalten ist kein besonderes Feature; es ist Weglassen.

Die Welt wird trotzdem in jedem Frame gezeichnet, egal in welchem Zustand, genau wie Dodge sie gezeichnet hat. Nur die Wörter ändern sich. Ersetz die Zeile drawHud() hierdurch:

    if state == TITLE then
        drawTitle()
    else
        drawHud()
    end

drawTitle ist neu, und es kommt nach drawStars:

function drawTitle()
    overlayPrint(25, 6, "R O C K S")
    overlayPrint(25, 9, "BEST " .. best)
    overlayPrint(22, 12, "PRESS 1 TO PLAY")
end

best ist die bisher beste Punktzahl, und sie kommt im nächsten Abschnitt dazu; bis dahin läuft das Spiel nicht. Vor dem ersten Spiel ist die Liste der Felsen leer, also zeigt der Titelbildschirm die vorbeiziehenden Sterne und das Schiff, das unten wartet, und mehr braucht ein Titelbildschirm nicht.

Eine Zeile muss weg, sonst siehst du den Titel nie. Lösch das startGame() ganz unten in der Datei. Das Spiel beginnt jetzt auf seinem Titelbildschirm, und Neu anfangen sagt, warum diese Zeile wichtig ist.

drawHud stellt eine eigene Frage. Ändere sein if over then in:

    if state == OVER then

Der Eingabe-Callback braucht dieselbe Art von Nachdenken. Hier ist er vollständig:

function onInputPressed(what)
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 and state == PLAYING then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then
        soundPlay(clickClip)
        startGame()
    end
end

Lies ihn von oben. Die Pfeiltasten werden in jedem Zustand festgehalten, denn sie sagen nur, welche Tasten unten sind, und nichts bewegt das Schiff, außer der Zustand ist PLAYING. Feuern bedeutet nur beim Spielen etwas. Und 1 startet ein Spiel vom Titelbildschirm oder vom Game-Over-Bildschirm aus, aber nicht, solange die letzte Explosion noch klingt: Das Spiel ist erst vorbei, wenn es das sagt. Die Klammern funktionieren wie beim Rechnen. Das or darin wird zuerst ausgerechnet, und dann verbindet das and es mit der Taste.

Punkte und Leben

Beides hast du seit Lektion neun, und daran ändert sich kaum etwas. Neu ist die beste Punktzahl, und die fängt als gewöhnliche Variable an. Stell sie zu den anderen, unter lives:

local best         = 0

Zeig sie in der Zeile oben quer über den Bildschirm, zwischen den anderen beiden. In drawHud:

    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(25, 1, "BEST " .. best)
    overlayPrint(50, 1, "LIVES " .. lives)

Und gib endGame die Aufgabe, einen Rekord zu bemerken:

    if score > best then
        best = score
    end

Starte es. Der Titel sagt BEST 0. Drück 1, schieß etwas ab, verlier, und der Game-Over-Bildschirm zeigt deine Punktzahl als die beste. Drück wieder 1, und die beste bleibt, während die Punkte von vorn anfangen. Jetzt beende es, starte es noch einmal und sieh dir den Titel an: BEST 0. Der Rekord hat genau so lange gelebt wie das Programm. Das ist die zweite Hälfte dieser Lektion.

Wo du gerade bei den Leben bist: Lektion neun hat den Test als lives ⇐ 0 geschrieben, nicht als lives == 0, und dabei sollte es bleiben. Heute kann nichts zwei Leben auf einmal nehmen, also können die beiden nur übereinstimmen. An dem Tag, an dem du einen Felsen einbaust, der zwei kostet, steigt == 0 glatt über die Null hinweg, und der Spieler spielt mit minus einem Leben weiter, während ⇐ 0 weiter funktioniert. Frag nach dem, was du meinst.

Neu anfangen

Das startGame() unten in der Datei hast du schon gelöscht. In Lektion zehn hat diese Zeile das erste Spiel gestartet und das Drücken von 1 jedes spätere, und das sind zwei Wege hinein. Jetzt gibt es einen. Jedes Spiel, das erste eingeschlossen, beginnt, wenn jemand 1 drückt und startGame läuft, also fangen das erste und das fünfte Spiel genau gleich an.

startGame muss alles zurücksetzen, was ein Spiel verändert:

function startGame()
    shipX        = (screenWidth - shipWidth) / 2
    score        = 0
    lives        = START_LIVES
    state        = PLAYING
    deathChannel = -1
    shots        = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
    musicSetVolume(50)
    musicPlay(theme, -1)
end

Genauso wichtig ist zu wissen, was es in Ruhe lässt, und warum. best überlebt jedes Spiel; das ist seine ganze Aufgabe. Die Sterne sind Kulisse. Und goLeft und goRight gehören überhaupt nicht dem Spiel. Sie gehören der Tastatur, und nur die Tastatur sollte sie ändern.

Das Letzte ist ein Fehler, den du gerade behoben hast, ohne es zu merken. Der Eingabe-Callback aus Lektion zehn fing mit if over then an, und solange das Spiel vorbei war, hat er jede Taste außer 1 weggeworfen. Drück die Pfeiltaste nach rechts, während GAME OVER zu sehen ist, halt sie gedrückt und drück 1. Das neue Schiff rührt sich nicht: Das Drücken der Pfeiltaste wurde weggeworfen, das Loslassen ist noch nicht passiert, und so ist goRight gleich false, während die Taste eindeutig unten ist. Das Schiff bleibt stehen, bis du loslässt und noch einmal drückst. Der neue Callback hält die Pfeiltasten in jedem Zustand fest, also ist die gehaltene Taste immer noch gehalten, wenn das Spiel beginnt.

Fehler beim Neuanfangen sind die häufigsten Fehler in jedem Spiel, und sie fühlen sich beim Spielen alle gleich an: Das zweite Spiel ist auf subtile Weise falsch, und das erste war in Ordnung. Wenn das passiert, lies startGame und stell zwei Fragen. Was hat das letzte Spiel geändert, das dieses nicht zurücksetzt? Und was setzt dieses zurück, das das Spiel nie hätte anfassen dürfen?

Eine Zahl, die das Programm überlebt

Alles, was dein Spiel bisher festgehalten hat — score, lives, die Liste der Felsen — lebt im Speicher, und der Speicher ist in dem Moment weg, in dem das Programm aufhört.

Singe gibt jedem Spiel einen eigenen Spielstand: eine Menge von Namen mit Werten darunter, für dich auf die Festplatte geschrieben. Er ist ein weiterer Teil des Spiele-Kits aus Lektion elf, also dieselbe Art von Ding wie collideRects: schlichte Aufrufe, nichts zu laden oder freizugeben.

saveSet("highScore", 4200)

saveSet nimmt einen Namen — den Schlüssel — und einen Wert. Den Schlüssel suchst du dir aus, und er ändert sich nie; der Wert ist das, was du dir merken willst. Zahlen, Strings, true und false und ganze Tabellen davon passen alle hinein. Dinge, die nur Sinn ergeben, solange das Programm läuft, passen nicht. Ein Sprite-Handle ist nur eine Zahl, also lässt es sich speichern, und morgen ist es eine Zahl, die nichts bedeutet. Eine Funktion lässt sich überhaupt nicht aufschreiben, und der Versuch, eine zu speichern, hält das Spiel mit einem Fehler an, statt dich das erst nächste Woche herausfinden zu lassen.

Das Zurücklesen ist die andere Hälfte. Ändere die Zeile, die du für best eingefügt hast:

local best         = saveGet("highScore", 0)

Sie läuft einmal, wenn das Spiel startet. Das zweite Argument ist der Standardwert: was geantwortet wird, wenn unter diesem Schlüssel noch nie etwas gespeichert wurde. Gleich mehr dazu, denn darum dreht sich der ganze Fehler dieser Lektion.

Und lass endGame den Rekord aufschreiben, wenn er fällt:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
    if score > best then
        best = score
        saveSet("highScore", best)
        saveFlush()
    end
end

Du musst Singe nicht bitten, die Datei zu schreiben. Es schreibt sie einmal am Ende jedes Frames, in dem sich etwas geändert hat, egal wie viele Schlüssel du setzt, und noch einmal, wenn das Spiel herunterfährt. saveFlush schreibt sie stattdessen sofort: Ein neuer Highscore ist einen eigenen Schreibvorgang wert, denn ein Arcade-Automat wird an der Steckdose ausgeschaltet, und ein Frame ist eine lange Zeit.

Starte es, stell eine Punktzahl auf, beende es und starte es noch einmal. Der Titel erinnert sich.

Der Abschnitt Spielstand in der Referenz listet den Rest der Familie auf. saveDelete vergisst einen Schlüssel, saveClear vergisst alles — das ist das „Highscores zurücksetzen“ in einem Service-Menü — und saveGetAll gibt dir eine Kopie von allem, und das ist nützlich, wenn du den ganzen Spielstand ausgeben willst, während du nach etwas suchst.

Wo die Datei wirklich landet

Sie landet nicht neben deinem Skript, und das ist kein Zufall.

Ein fertiges Spiel liegt vielleicht auf einer Disc, auf einer Netzwerkfreigabe oder in einer einzigen gepackten Datei (Lektion dreißig), und auf nichts davon kann man schreiben. Ein Spiel, das neben seinem eigenen Skript speichert, funktioniert perfekt auf dem Rechner, auf dem du es geschrieben hast, und scheitert auf der Hälfte der Rechner, auf denen es installiert wird. Singe 2 hat es so gemacht, und das war falsch.

Darum kommt alles, was Singe für ein Spiel schreibt — der Spielstand, Screenshots, sein Log — an einen Ort, und singeGetDataPath sagt dir, wohin:

debugPrint(singeGetDataPath())

Schreib das kurz direkt unter die Zeile mit dofile und starte es. Es sagt data/rocks/: der Ordner data, der in deinem Arbeitsordner aufgetaucht ist, als du in Lektion eins zum allerersten Mal etwas gestartet hast, und darin ein Ordner mit demselben Namen wie der Ordner deines Spiels. Dort findest du save.json. Öffne die Datei in deinem Texteditor: Es ist reiner Text, und dein Highscore steht darin unter dem Namen, den du ihm gegeben hast.

Das ist auch die Antwort, wann immer du eine eigene Datei brauchst. Bau den Namen aus singeGetDataPath() zusammen, und sie landet irgendwo, wo man schreiben kann; schreib in einen Namen, den du dir selbst ausgedacht hast, und früher oder später tut sie das nicht.

Beim ersten Mal ist nichts da

Wenn irgendjemand dein Spiel zum allerersten Mal startet, wurde noch nie ein Highscore gespeichert. saveGet hat nichts zurückzugeben, also gibt es den Standardwert zurück, den du ihm gegeben hast:

local best         = saveGet("highScore", 0)

Nichts gespeichert, also ist best gleich 0, der Titelbildschirm sagt BEST 0, und das erste Spiel, das irgendjemand spielt, stellt einen Rekord auf. Genau das willst du, und es kostet ein zusätzliches Argument.

Lass die 0 weg, und saveGet hat keinen Standardwert, auf den es zurückgreifen kann, also antwortet es nil — der Wert, mit dem Lua „hier ist nichts“ sagt und den du in Lektion drei kennengelernt hast. nil ist nicht null. Du kannst nichts dazuzählen, du kannst es nicht mit einer Zahl vergleichen, und du kannst es nicht an einen String kleben. Es geht im ersten Frame schief, jedes Mal, auf jedem Rechner, auf dem das Spiel noch nicht gespielt wurde — und dazu gehört jeder Rechner, auf dem deine Spieler es gleich installieren, aber nicht der, auf dem du testest.

Gib jedem saveGet einen Standardwert. Das ist die billigste Angewohnheit in diesem Buch.

Was gerade passiert ist

local TITLE   = "title"

Eine Konstante: ein Name, den du einmal setzt und nie änderst, in Großbuchstaben, damit du auf einen Blick siehst, dass es eine ist, wie in Lektion sieben. Lua erzwingt das nicht — nichts hindert dich daran, TITLE etwas zuzuweisen — also sind die Großbuchstaben eine Nachricht an den Nächsten, der es liest, und das bist du in zwei Wochen.

    if state == PLAYING then

Die Frage, die entscheidet, ob sich die Welt bewegt. Wenn du später einen fünften Zustand hinzufügst — eine Pause oder eine Bonusrunde — fragst du als Erstes, ob sich die Welt darin bewegt, und hierhin kommt die Antwort.

    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then

Ohne die Klammern würde Lua zuerst das and verbinden und das als „die Taste ist 1 und der Zustand ist der Titel, oder der Zustand ist vorbei“ lesen. Dann würde jede Taste, die die Zweige darüber nicht abgefangen haben, vom Game-Over-Bildschirm aus ein Spiel starten, die Feuertaste eingeschlossen, und ein Spieler, der noch auf den Feuerknopf hämmert, wenn der letzte Felsen trifft, säße in dem Moment, in dem GAME OVER erscheint, in einem neuen Spiel. Die Klammern sorgen dafür, dass das or zuerst passiert. Wenn du and und or mischst, setz die Klammern, auch wenn du glaubst, die Reihenfolge zu kennen. Wer es als Nächstes liest, muss sie dann nicht kennen.

        saveSet("highScore", best)
        saveFlush()

saveSet legt die Zahl in den Spielstand; saveFlush bringt den Spielstand jetzt auf die Festplatte statt erst am Ende des Frames. Beide stehen im if, also wird die Datei nur geschrieben, wenn der Rekord wirklich gebrochen wird, und das ist ein paarmal pro Sitzung statt sechzigmal pro Sekunde.

local best         = saveGet("highScore", 0)

Einmal gelesen, beim Start, in eine gewöhnliche Variable. Der Rest des Spiels liest best, statt noch einmal saveGet aufzurufen, denn der Spielstand ist eine Datei, und eine Variable ist eine Variable. Schreib in beide, wenn der Rekord fällt.

Probier es aus

  1. Geh zurück zum Titel. Ein Arcade-Automat bleibt nicht ewig auf GAME OVER stehen. Schlag timerAfter im Abschnitt Timer der Referenz nach, einem weiteren Teil des Spiele-Kits, und benutz es in endGame, um den Zustand fünf Sekunden nach Spielende zurück auf TITLE zu setzen. Dann drück nach einem Spielende schnell 1 und sorg dafür, dass der Timer dein neues Spiel nicht nach drei Sekunden zurück auf den Titel wirft.

  2. Zeig die Leben als Schiffe. Zeichne shipSprite mit spriteDraw einmal pro Leben in die rechte obere Ecke, statt die Zahl auszugeben. Eine for-Schleife aus Lektion vier, und shipWidth sagt dir, wie weit du sie auseinandersetzen musst.

  3. Speichere mehr als eine Zahl. Füg saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1) in startGame ein und gib es auf dem Titelbildschirm aus. Beende es, starte es noch einmal und sieh zu, wie es sich erinnert.

  4. Finde die Datei und mach sie kaputt. Öffne data/rocks/save.json in deinem Editor, ändere den Highscore in etwas Absurdes und starte das Spiel. Dann lösch die Datei ganz und starte es noch einmal. Beides wird deinen Spielern passieren.

  5. Setz ihn aus dem Spiel heraus zurück. Lass eine Taste, die du nie aus Versehen drücken würdest, saveClear() aufrufen, und sieh dir danach den Titelbildschirm an. Vorsicht: best ist noch im Speicher, und saveClear rührt es nicht an. Finde heraus, was sonst noch passieren muss.

Mach es absichtlich kaputt

Nimm den Standardwert heraus, sodass die Zeile so lautet:

local best         = saveGet("highScore")

Wenn du schon einen Highscore aufgestellt hast, passiert überhaupt nichts, und genau das ist die Falle: Der Spielstand hat den Schlüssel, also gibt saveGet ihn zurück. Lösch zuerst data/rocks/save.json und starte es dann. Der Titelbildschirm erscheint nie, und du bekommst das hier:

Error executing function 'onOverlayUpdate':  rocks/rocks.singe:101: attempt to concatenate a nil value (upvalue 'best')
stack traceback:
	rocks/rocks.singe:101: in function 'drawTitle'
	rocks/rocks.singe:165: in function 'onOverlayUpdate'

Lies es so, wie Lektion acht es dir beigebracht hat. Datei und Zeile führen dich zu overlayPrint(25, 9, "BEST " .. best) in drawTitle, und die Beschwerde sagt, dass etwas, das nil war, an einen String geklebt wurde. .. verbindet zwei Strings, und nil ist keiner. Wenn deine Zeilen anders angeordnet sind, sind es deine Zahlen auch.

Die Zeile, die sie nennt, ist nicht die, in der der Fehler steckt. In Zeile 101 ist das Spiel schließlich darüber gestolpert; gemacht wurde der Fehler oben in der Datei, wo nach best gefragt wurde und nichts da war. Diese Lücke zwischen der Stelle, an der ein schlechter Wert entsteht, und der, an der er bemerkt wird, ist das Schwierigste an nil, und der Grund, warum ein Standardwert ein Argument kostet und einen Abend rettet.

Setz die 0 wieder ein.

Was du gelernt hast

  • Ein Spiel ist immer in genau einem Zustand, und Wahr-oder-falsch-Flags, die zu sagen versuchen, in welchem, erzeugen Kombinationen, die nichts bedeuten.

  • Halte den Zustand in einer Variablen fest, mit seinen möglichen Werten einmal oben in der Datei benannt.

  • onOverlayUpdate entscheidet, was sich bewegt und was gesagt wird, indem es den Zustand fragt.

  • Ein Spiel anzuhalten heißt, die Dinge nicht aufzurufen, die es bewegen.

  • Starte jedes Spiel, das erste eingeschlossen, über eine einzige Funktion, und lass diese Funktion alles zurücksetzen, was ein Spiel verändert — und sonst nichts.

  • Tasten gehören der Tastatur. Halte sie in jedem Zustand fest.

  • saveSet speichert einen Wert unter einem Schlüssel, und saveGet liest ihn bei einem späteren Lauf zurück.

  • saveFlush schreibt die Datei sofort, für die Dinge, die du auf keinen Fall verlieren willst.

  • Der Spielstand kommt in den eigenen Datenordner des Spiels, den singeGetDataPath nennt. Schreib nie neben dein Skript.

  • saveGet ohne Standardwert antwortet nil, wenn nichts gespeichert wurde, und nil macht den ersten Frame auf einem Rechner kaputt, auf dem dein Spiel noch nie lief.

  • Wenn du and und or mischst, setz Klammern.

Beim nächsten Mal

Dein Spiel ist jetzt ein Spiel, und es ist ein Ordner, von dem nur du weißt, wie man ihn startet. Lektion dreizehn gibt ihm eine games.dat, damit das eigene Menü der Engine es mit einem Titel und einem Bild auflistet und ein Spieler, der noch nie von dir gehört hat, es starten kann, ohne irgendetwas zu tippen.

Lektion 13: Ein Spielordner

Die fertige Lektion

Dein Spiel ist ein Skript in einem Ordner, dessen Namen du dir merkst, und du startest es, indem du seinen Namen in ein Terminal tippst. Für dich ist das in Ordnung, für alle anderen nutzlos. Ein Spieler sollte einen Ordner neben Singe kopieren, das Menü starten, dein Spiel mit seinem Titel und seinen Grafiken in der Liste sehen und einen Knopf drücken können. Das Bild oben ist dieses Menü, mit deinem Spiel darin.

Dafür braucht es eine neue Datei, etwa sechs Zeilen lang, und zwei Bilder, die du mit einer Taste aufnehmen kannst. An deinem Skript ändert sich überhaupt nichts.

Gib dem Spiel einen Namen

Ein Spiel hat zwei Namen, einen für den Computer und einen für Menschen.

Der für den Computer ist der Ordner, und den hast du in Lektion neun ausgesucht: rocks, mit rocks.singe darin. Ordner und Skript haben denselben Namen, so wie in jeder Lektion seit Lektion eins, und darum findet Singe rocks das Skript allein über den Ordner. Halte diesen Namen schlicht. Keine Leerzeichen, denn die liest ein Terminal als Lücke zwischen zwei Namen. Und überall, wo du ihn tippst, genau dieselbe Groß- und Kleinschreibung: Auf den meisten Computern, die nicht Windows sind, sind rocks und Rocks zwei verschiedene Ordner, und ein Spiel, das nur auf deinem Rechner läuft, ist kein Spiel, das irgendjemand anderes haben kann.

Der Name für Menschen kann alles sein, was du willst, mit Großbuchstaben, Leerzeichen und allem, und er wohnt nicht im Ordnernamen. Er wohnt in der Datei, um die es in dieser Lektion geht, damit du nie einen Ordner umbenennen musst, wenn du das Spiel im Menü umbenennst.

Was in den Ordner kommt

Alles, was dein Spiel braucht, und sonst nichts. Am Ende dieser Lektion sieht er so aus:

rocks/
    games.dat       Was das Menü liest
    rocks.singe     Das Spiel
    art/            Das Grafik-Kit aus Lektion neun
        spaceship.png
        asteroid.png
        bullet.png
        star.png
        shoot.wav
        boom.wav
        ...
    cabinet.png     Ein Bild, das das Menü neben der Liste zeigt
    marquee.png     Ein Bild, das das Menü darüber zeigt

Alles andere, was beim Lernen darin gelandet ist — walk.singe aus Lektion neun, der kleine Soundtest aus Lektion zehn — gehört nicht zum Spiel. Verschieb es in einen eigenen Ordner neben rocks. Im Grafik-Kit sind auch ein paar Dateien, die dieses Spiel nie lädt, und die schaden vorerst nicht. In Lektion dreißig gehst du einen Spielordner durch und nimmst alles heraus, was nicht zum Spiel gehört.

Die Regel hinter diesem Aufbau lautet: Ein Spiel greift nie über seinen eigenen Ordner hinaus. Nicht für Grafiken, nicht für einen Sound und nicht für eine Bibliothek, die du auch in einem anderen Spiel benutzt — wenn du Code zwischen zwei Spielen teilst, behält jedes seine eigene Kopie. Es gibt genau einen Ort außerhalb des Ordners, aus dem ein Spiel laden darf, und aus dem lädst du schon: der Ordner Singe der Engine selbst, in dem Singe/Framework.singe liegt und seit Lektion zehn auch der Klick und die Musik.

Der Spielordner liegt in deinem Arbeitsordner, neben der Engine:

singe/                 Dein Arbeitsordner
    Singe-v3.00-...    Die Engine selbst, wie auch immer deine heißt
    Menu.sh            Startet das Menü.  Unter Windows Menu.bat
    Singe/             Hilfsdateien.  Nicht deine; lass sie in Ruhe
    data/              Alles, was irgendetwas schreibt, auch dein Spielstand
    rocks/             Dein Spiel

Genau so sieht es auch auf dem Rechner eines Spielers aus. Die Engine hat Singe, data und Menu.sh (Menu.bat unter Windows) geschrieben, als du in Lektion eins zum allerersten Mal etwas gestartet hast. Lektion eins hat die ersten beiden erwähnt. Das dritte ist neu für dich, und diese Lektion setzt es ein.

Pfade zählen ab dort, wo Singe gestartet wurde

Das machst du seit Lektion neun, also ist das hier eine Erinnerung und keine Änderung.

Jeder Name, den dein Spiel lädt — art/spaceship.png, art/boom.wav — wird ab dem Ordner gesucht, in dem Singe gestartet wurde, nicht ab dem Ordner, in dem dein Skript liegt. Du startest Singe in deinem Arbeitsordner, also würde ein nacktes art/spaceship.png in singe/art gesucht, und das gibt es nicht. DIR ist der eigene Ordner deines Skripts, mit dem Schrägstrich schon am Ende, also zeigt ein Name, der daran geklebt wird, auf deine Datei, egal von wo aus Singe gestartet wurde:

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

Das Menü startet Singe in dem Ordner, in dem Menu.sh liegt, und das ist wieder dein Arbeitsordner, also tut DIR dort genau dasselbe wie bei dir. Das tut es auch weiterhin, wenn das Spiel in Lektion dreißig in eine einzige Datei gepackt wird, wenn der Arbeitsordner von jemand anderem ganz anders heißt und auf einem Rechner, den du nie sehen wirst. Ein Name, der mit Singe/ anfängt, ist der Ordner der Engine und braucht nie DIR; jeder Name, der dir gehört, braucht es.

games.dat

Mit games.dat stellt sich ein Spiel vor. Das Menü liest die games.dat jedes Spielordners neben sich und listet auf, was es findet. Keine games.dat, kein Eintrag: Dein Ordner ist unsichtbar, egal wie gut das Spiel darin ist.

Leg in deinem Ordner rocks eine neue Datei namens games.dat an. Das ist die kleinste, die funktioniert:

GAMES = {
    {
        TITLE  = "Rocks",
        SCRIPT = "rocks/rocks.singe"
    }
}

Das ist Lua, und es ist eine Tabelle von der Art, die du in Lektion sechs kennengelernt hast: GAMES ist eine Liste, und jedes Ding in der Liste ist ein Datensatz, der ein Spiel beschreibt. Ein Ordner kann mehrere Spiele enthalten — darum ist es eine Liste — aber deiner enthält eins.

SCRIPT ist das Feld, das die Engine braucht, um das Spiel zu starten, und TITLE das, das das Menü braucht, um es aufzulisten. Der Pfad des Skripts zählt ab dem Ordner über der games.dat, nicht ab dem Ordner, in dem die games.dat liegt. Eine games.dat in rocks nennt ihr eigenes Skript also rocks/rocks.singe. Das sieht aus, als stünde rocks zweimal da, und es ist richtig so. Jeder andere Pfad in der Datei funktioniert genauso. Machst du es falsch, beschwert sich nichts, wenn du den Namen tippst: Der Eintrag passt einfach nie zu dem Skript, das du gestartet hast.

TITLE ist der Name für Menschen vom Anfang dieser Lektion. Ihn zeigt das Menü an, und Spiele werden nach Titel sortiert aufgelistet, also bestimmt ein Titel auch, wo dein Spiel in der Liste steht.

Dem Menü mehr erzählen

Das Menü hat neben der Liste eine ganze Fläche zu füllen, und es füllt sie aus dem Rest des Eintrags:

GAMES = {
    {
        TITLE       = "Rocks",
        SCRIPT      = "rocks/rocks.singe",
        CANVAS_X    = 720,
        CANVAS_Y    = 480,
        YEAR        = 2026,
        GENRE       = "Shooter",
        DEVELOPER   = "Your Name Here",
        PUBLISHER   = "Your Name Here",
        DESCRIPTION = "Shoot the rocks before they reach your ship.",
        CABINET     = "rocks/cabinet.png",
        MARQUEE     = "rocks/marquee.png"
    }
}

CABINET und MARQUEE sind gewöhnliche Bilddateien in deinem Spielordner, in jedem Format, das Singe lesen kann. Das Automaten-Artwork ist das große Bild neben der Liste, und das Marquee ist der Streifen darüber. Mach sie so groß, wie du willst; das Menü passt sie in ihre Flächen ein.

Du brauchst kein Zeichenprogramm, um sie zu machen, denn dein Spiel kann sein eigenes Bild aufnehmen. Starte es, und wenn der Bildschirm so aussieht, wie die Welt ihn sehen soll, drück F12 (oder F11, weil manche Desktops F12 für sich behalten). Singe speichert ein Bild des Fensters im Datenordner deines Spiels, data/rocks, mit dem Namen singe000.png, dann singe001.png und so weiter. Nimm eins vom Titelbildschirm auf und eins mitten im Gefecht. Kopier sie in deinen Ordner rocks und benenn sie um: Das Gefecht ist cabinet.png, der Titel ist marquee.png.

Ein echtes Marquee ist ein breiter Streifen mit dem Namen des Spiels in großen Buchstaben, und ein ganzer Bildschirm, der hineingequetscht wird, sieht aus wie eine Briefmarke. Bis du etwas Besseres hast, reicht es. Lass MARQUEE weg, und das Menü setzt stattdessen das eigene Ersatzbild der Engine dorthin, ein rosa Schachbrett mit der Aufschrift MISSING, und das ist schlimmer.

YEAR, GENRE, DEVELOPER, PUBLISHER und DESCRIPTION sind der Text darunter, und die Engine sieht sie sich nie an. Sie sind für den Menschen, der das Menü liest, und darum geht es ja.

CANVAS_X und CANVAS_Y sind die Größe der Welt deines Spiels, und 720 mal 480 ist der Standard — dieselbe Welt, in der du seit Lektion eins zeichnest. Setz sie nur, wenn dein Spiel eine andere Form will. Ein Spiel ohne Feld VIDEO ist ein Spiel ohne Video, und das ist deins; ab Lektion vierzehn fängt dieses Feld an, wichtig zu werden.

Der Abschnitt games.dat in der Referenz listet jedes Feld auf, das es gibt, darunter mehrere für Hardware, die du noch nicht hast. Bei ein paar weiteren lohnt es sich, die Namen jetzt schon zu kennen.

REQUIRES sagt, was ein Spiel über schlichtes 2D hinaus vom Rechner braucht: "GUI" für die Menüs und Seiten aus Lektion zwanzig, "SCENE" für das 3D, das in Lektion zweiundzwanzig anfängt, und noch ein paar mehr. Das Menü liest es, damit es einem Spieler sagen kann „dieser Rechner kann das nicht starten“, statt das Spiel auf halbem Weg scheitern zu lassen. Rocks ist schlichtes 2D, und genau das bedeutet es, wenn REQUIRES fehlt, also lass es weg. Die Liste musst du selten selbst ausarbeiten, denn Singe merkt, was ein Spiel beim Laufen benutzt, und sagt es, wenn der Eintrag es nicht aufführt. Ab Lektion zwanzig wirst du Zeilen wie diese sehen, egal ob das Spiel überhaupt eine games.dat hat:

Warning:  this game uses GUI, which its games.dat does not list in REQUIRES.

Das ist ein Rat, kein Fehler; das Spiel läuft so oder so. Die Abhilfe ist eine Zeile im Eintrag, REQUIRES = { "GUI" },, und wenn du in Lektion dreißig ein Spiel packst, wird die Liste für dich geschrieben, falls der Eintrag keine hat. Sein Partner TIER, eine Zahl von 0 bis 3, sagt, wie viel Rechner ein Spiel braucht, und kann warten, bis du ein Spiel schreibst, das schwer genug ist, dass es darauf ankommt.

GAME_ID ist eine eindeutige Kennung für dein Spiel, die die Online-Bestenlisten in Lektion achtundzwanzig brauchen und sonst nichts. Und RESOLUTION_X und RESOLUTION_Y verlangen eine bestimmte Fenstergröße. Ignorier den Rest, bis dich etwas danach suchen lässt.

Aus dem Menü starten

Starte Menu.sh — unter Windows Menu.bat — aus deinem Arbeitsordner. Es findet das neueste Singe daneben und startet das Menü.

Dein Spiel steht in der Liste, mit seinen Grafiken daneben und seiner Beschreibung darunter. Es ist das Einzige in der Liste, weil rocks der einzige Ordner ist, dem du eine games.dat gegeben hast; hello, dodge und der Rest sind für das Menü keine Spiele. Hoch und runter bewegen dich um ein Spiel, links und rechts um eine Seite, und Start oder ein Feuerknopf spielt das ausgewählte. Beende das Spiel mit Esc, und du bist zurück im Menü, beim selben Spiel, bereit für die nächste Runde. Das Menü merkt sich auch zwischen zwei Starts, bei welchem Spiel du warst.

Mehr gehört, was die Engine angeht, zum Ausliefern eines Spiels nicht. Ein Spieler kopiert deinen Ordner neben Singe, und es erscheint.

Den Namen zu tippen funktioniert immer noch, und zwar genauso:

Singe rocks

Wenn du ein Skript so von Hand startest, sucht Singe eine games.dat daneben — und in bis zu drei Ordnern darüber — und wenn ein Eintrag das Skript nennt, das du gestartet hast, gelten die Einstellungen dieses Eintrags dafür. Ein Spiel spielt sich also aus dem Terminal genauso wie aus dem Menü, und das heißt, du kannst weiterarbeiten wie bisher, mit -R und einem Texteditor, und dich trotzdem darauf verlassen, was ein Spieler bekommt. Es schreibt auch an dieselbe Stelle: Egal auf welchem Weg gestartet, der Spielstand deines Spiels ist der in data/rocks.

Später: eine Datei

In einem Ordner lässt es sich leicht arbeiten, aber er ist etwas umständlich weiterzugeben: ein Dutzend Dateien, ein Ordner in einem Ordner und ein Spieler, der alles an die falsche Stelle entpackt. Ein fertiges Singe-Spiel lässt sich in eine einzige .game-Datei packen, die die Engine direkt startet, mit Grafiken, Sounds und allem, und die ein Spieler neben Singe kopiert, und fertig.

Dafür muss sich an deinem Spiel nichts ändern. Das ist Lektion dreißig, und es lohnt sich, darauf zu warten: Pack ein Spiel, das nicht fertig ist, und du packst es morgen noch einmal.

Was gerade passiert ist

GAMES = {
    {

Zwei geschweifte Klammern, weil es eine Liste von Datensätzen ist. Die äußere ist die Liste. Die innere ist das erste Ding in der Liste, also der Datensatz für ein Spiel. Eine davon falsch zu setzen ist der übliche Fehler, und Lua sagt dir die Zeile.

        SCRIPT      = "rocks/rocks.singe",

Gezählt ab dem Ordner über der games.dat, und das ist dein Arbeitsordner. Es ist derselbe Name, den du nach Singe tippen würdest, um das Skript von Hand zu starten, und so merkst du ihn dir am leichtesten.

Das Komma am Ende der Zeile trennt ein Feld vom nächsten, genau wie in Lektion sechs. Nach dem letzten Feld eines Datensatzes steht kein Komma — Lua stört es nicht, wenn eins dasteht, aber lass es weg, dann sieht deine Datei aus wie die von allen anderen. Ein Komma, das mittendrin fehlt, ist eine andere Sache, und das ist der Fehler dieser Lektion.

        CABINET     = "rocks/cabinet.png",

Ein Bild, das das Menü lädt und nicht dein Spiel, also wird es so benannt wie SCRIPT, ab dem Ordner darüber, und nicht mit DIR. DIR gehört deinem Skript, während es läuft, und das Menü und die Engine lesen games.dat, bevor dein Skript gestartet ist.

Probier es aus

  1. Mach bessere Bilder. Wenn du ein Zeichenprogramm hast, mach eine richtige marquee.png: einen breiten Streifen, auf dem ROCKS in großen Buchstaben steht. Setz sie an die Stelle des Screenshots und sieh dir das Menü noch einmal an.

  2. Gib Dodge eine games.dat. Schreib eine games.dat in deinen Ordner dodge aus Lektion sieben und starte das Menü. Jetzt sind es zwei Spiele, nach Titel sortiert. Dann ändere den TITLE von Rocks in Asteroid Field und sieh zu, wie es über Dodge rutscht: Die Liste ist nach Titel sortiert, nicht nach Ordner.

  3. Mach games.dat fürs Menü kaputt. Lösch eine der schließenden geschweiften Klammern in der games.dat in rocks und starte das Menü. Dein Spiel ist aus der Liste verschwunden, und das Terminal sagt, warum. Setz sie wieder ein.

  4. Mach SCRIPT falsch. Setz CANVAS_X auf 1280 und CANVAS_Y auf 720 und starte Singe rocks. Das Spielfeld ist breiter. Jetzt ändere SCRIPT in rocks.singe und starte es noch einmal. Das Spiel hat wieder seine alte Größe, und nichts hat es dir gesagt: Der Eintrag nennt nicht mehr das Skript, das du gestartet hast, also gilt er nicht. Setz beides zurück.

  5. Finde deinen Spielstand. Starte das Spiel aus dem Menü, stell einen Highscore auf, kehr ins Menü zurück und beende das Menü. Starte Singe rocks und sieh dir den Titel an. Dann such in data/rocks die Datei, die ihn sich gemerkt hat.

Mach es absichtlich kaputt

Nimm das Komma am Ende der Zeile mit TITLE weg, sodass der Anfang der Datei so lautet:

GAMES = {
    {
        TITLE       = "Rocks"
        SCRIPT      = "rocks/rocks.singe",

Starte Singe rocks. Das Spiel startet, und das Terminal sagt das hier:

Note:  rocks/games.dat ignored:  [string "rocks/games.dat"]:4: '}' expected (to close '{' at line 2) near 'SCRIPT'

Dein Spiel läuft trotzdem, weil ein Spiel, das über seinen Namen gestartet wird, seinen Eintrag nicht braucht. Es läuft einfach ohne ihn. Starte aber das Menü, und dein Spiel ist weg. War es das einzige, sagt die Liste No games yet, und das Terminal sagt dasselbe auf andere Art:

rocks/games.dat:  rocks/games.dat:4: '}' expected (to close '{' at line 2) near 'SCRIPT'  Skipped.

Lies ihn wie jeden anderen Lua-Fehler. Die Datei ist rocks/games.dat, und die Zeile ist 4. Aber Zeile 4 ist die Zeile mit SCRIPT, und an der ist nichts falsch. Der Fehler steckt am Ende von Zeile 3. Nach TITLE = "Rocks" hat Lua entweder ein Komma und ein weiteres Feld erwartet oder die }, die den Datensatz schließt, der in Zeile 2 angefangen hat. Stattdessen hat es SCRIPT gefunden, also ist Zeile 4 die Stelle, an der es den Fehler bemerkt hat. Sein Vorschlag zur Korrektur — eine } — ist falsch; seine Zeile liegt um eins daneben. Wenn ein Fehler auf den Anfang einer Zeile zeigt, sieh dir das Ende der Zeile davor an.

Setz das Komma wieder ein und starte das Menü noch einmal.

Was du gelernt hast

  • Ein Spiel ist ein Ordner: das Skript, seine Grafiken und eine games.dat, und nichts von außerhalb außer dem eigenen Ordner Singe der Engine.

  • Der Name des Ordners ist für den Computer, also halte ihn schlicht. Der Name für Menschen ist TITLE.

  • Namen, die dein Skript lädt, zählen ab dort, wo Singe gestartet wurde, und darum wird jeder davon aus DIR zusammengebaut.

  • games.dat ist eine Lua-Datei mit einer Liste GAMES, und jeder Eintrag ist ein Spiel.

  • Ein Eintrag braucht TITLE und SCRIPT und sonst nichts; Pfade darin zählen ab dem Ordner über der games.dat.

  • CABINET, MARQUEE, YEAR, GENRE, DEVELOPER, PUBLISHER und DESCRIPTION sind das, was das Menü dem Spieler zeigt, und F12 nimmt ein Bild auf, das du für die ersten beiden benutzen kannst.

  • REQUIRES sagt dem Menü, was ein Spiel über 2D hinaus braucht, und Singe warnt dich, wenn ein Spiel etwas benutzt, das sein Eintrag nicht aufführt.

  • Menu.sh oder Menu.bat startet das mitgelieferte Menü, das jeden Spielordner daneben auflistet, nach Titel sortiert.

  • Ein Spiel, das über seinen Namen gestartet wird, bekommt ebenfalls seinen Eintrag aus games.dat, also verhält es sich auf beiden Wegen gleich, und eine games.dat, die sich nicht laden lässt, wird gemeldet und ignoriert.

  • Ein fertiges Spiel kann später in eine einzige Datei gepackt werden, in Lektion dreißig.

Beim nächsten Mal

Damit ist Teil zwei fertig: Du hast ein Spiel, mit Grafiken, Sound, Kollision, Punkten und einem Weg, wie jemand anderes es starten kann. In Teil drei geht es um das, was fast keine andere Engine kann — Film als die Welt abspielen, in der das Spiel stattfindet — und Lektion vierzehn fängt mit der Disc, dem Frame und dem Warten an.

Lektion 14: Video abspielen

Die fertige Lektion

Singe kann einen Film abspielen und dein Spiel darin laufen lassen. Das Bild wird zur Welt, und das Overlay, auf dem du seit Lektion eins zeichnest, liegt obendrauf. In dieser Lektion startest du ein Video, findest heraus, welcher Frame gerade zu sehen ist, hältst es an und springst zu jedem beliebigen Moment.

Vor alldem muss eine Sache klar gesagt werden, denn sie entscheidet, ob du diesen Teil des Buchs überhaupt lesen solltest.

Ein Spiel spielt nur dann Video ab, wenn es darum bittet

Singe ist eine Spiel-Engine. Alles, was du in Teil eins und zwei gebaut hast — die Sprites, der Sound, die Kollisionen, die Punkte, der Spielordner — ist das ganze Singe, und nichts davon hat mit Video zu tun. Was Teil drei hinzufügt, ist eine Zugabe: Ein Spiel kann darum bitten, dass hinter ihm ein Film läuft, und dann ist der Film die Welt statt einer schwarzen Zeichenfläche.

Sonst ändert sich nichts. onOverlayUpdate wird immer noch sechzigmal pro Sekunde aufgerufen. overlayPrint zählt immer noch in Zeichenzellen. Deine Sprites werden dort gezeichnet, wo sie vorher gezeichnet wurden. Ein Spiel mit Video und ein Spiel ohne werden auf dieselbe Art geschrieben, mit denselben Funktionen, und teilen sich dasselbe Buch.

Wenn das Spiel, das du machen willst, also kein Video hat, kannst du diesen Teil jetzt zuklappen und zu Teil vier gehen. Nichts in Teil vier hängt von irgendetwas in Teil drei ab, und die einzigen Lektionen, die diese hier brauchen, sind die vier, die nach ihr kommen.

Noch da? Gut.

Du hast schon ein Video

Du musst keins suchen, keins kaufen und keins machen. Als du Singe in Lektion eins zum ersten Mal gestartet hast, ist in deinem Arbeitsordner ein Ordner namens Singe aufgetaucht. Öffne ihn und sieh nach: Unter den Dateien, die die Engine entpackt hat, ist menuBackground.mkv. Das ist der Hintergrund, den das eigene Menü der Engine benutzt, es ist 720 mal 480 Pixel groß und 420 Frames lang — etwa vierzehn Sekunden.

Das ist das Video für diese Lektion und die beiden danach.

Leg in deinem Arbeitsordner, neben den Ordnern aus den anderen Lektionen, einen Ordner namens movie an und darin eine Datei namens movie.singe. Mehr musst du nicht vorbereiten. Du startest Singe aus dem Arbeitsordner, wie seit Lektion eins, also liegt der Ordner Singe samt Video direkt neben deinem Spiel, und Singe/menuBackground.mkv ist der Name, den du der Engine gleich gibst. Kopieren musst du nichts.

Tipp das ein

dofile("Singe/Framework.singe")


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    return OVERLAY_UPDATED
end


discPlay()

Speichere die Datei.

Starte es

Das Video gehört nicht zu deinem Skript, also lädst du es auch nicht in deinem Skript. Du gibst es der Engine auf der Befehlszeile mit, mit -v:

Singe -R -v Singe/menuBackground.mkv movie

-v ist die Kurzform von --framefile und nennt das Video, das das Spiel abspielen soll. Der Name deines Skripts kommt zuletzt, wie immer. -R ist dasselbe -R, das du seit Lektion eins benutzt, und es startet das Spiel immer noch neu, wenn du speicherst.

Um das Bitten geht es bei -v. Wenn du eine Videodatei neben dein Skript legst und nichts sagst, bemerkt die Engine sie, sagt das auf der Konsole und startet dein Spiel ohne sie. Ein Spiel ist nur dann ein Videospiel, wenn jemand sagt, dass es eins ist.

Ein Fenster geht auf. Ein Ball aus orangefarbenem Feuer füllt es, aus dem Feuer formt sich ein Drache, darunter erscheint das Wort SINGE, und dann rollt ein magentafarbenes Gitter unter einer orangefarbenen Sonne davon. In der linken oberen Ecke, über allem, zählt eine Zahl hoch.

Sieh es dir bis zum Ende an. Dann sieh dir an, was am Ende passiert.

Was gerade passiert ist

discPlay()

Singe nennt das Video die Disc, und jede Funktion, die es steuert, fängt mit disc an. Der Name ist historisch: Die Engine hat ihr Leben damit begonnen, Spiele abzuspielen, die ihren Film auf einer Laserdisc hatten, und der Name ist an der Idee hängen geblieben. Es ist eine Videodatei auf deiner Festplatte und sonst nichts.

Ein Spiel hat höchstens eine Disc, also nimmt keine der disc-Funktionen ein Argument, das sagt, welche. Es gibt nur die eine.

Diese Zeile steht in keiner Funktion. Sie steht für sich allein unten in der Datei, und sie läuft einmal, wenn Singe dein Skript lädt — vor dem ersten onOverlayUpdate, vor allem anderen. Singe hat keinen Callback onStartup, weil es keinen braucht: Ein Lua-Skript ist eine Liste von Anweisungen, und alles, was du außerhalb einer Funktion schreibst, passiert, während die Datei gelesen wird. Startcode kommt nach Konvention ganz unten hin, unter die Funktionen.

Du brauchst discPlay(), weil die Disc nicht von selbst startet. Wenn das Spiel beginnt, parkt die Engine die Disc auf Frame eins und pausiert sie dort. Nichts bewegt sich, bis du darum bittest.

    overlayPrint(2, 2, "Frame " .. discGetFrame())

discGetFrame beantwortet eine Frage: Welcher Frame ist gerade zu sehen? Es nimmt keine Argumente und gibt eine Zahl zurück.

Achte darauf, wo diese Zahl gezeichnet wird. Spalte 2, Zeile 2 — genau dort, wo in Lektion eins Hello! hinkam, und sie landet an derselben Stelle auf dem Bildschirm. Das Overlay, auf dem du zeichnest, ist auf jeder Seite halb so groß wie das Video, und das ist bei einem Video von 720 mal 480 genau 360 mal 240, also genau die Größe, auf der du seit dreizehn Lektionen zeichnest. Deine Koordinaten haben sich nicht verschoben. Wenn du je ein Video in einer anderen Größe abspielst, ändert das Overlay seine Größe mit, und overlaySetResolution stellt es auf jede Größe, die du willst; der Eintrag in der Referenz hat die Einzelheiten.

Das ist die ganze Idee des Overlays. Das Video liegt darunter. Deine Zeichnung liegt obendrauf, und überall, wo du nicht gezeichnet hast, scheint der Film durch. Darum ist overlayClear jetzt noch wichtiger als bisher: Lösch das Overlay, und du siehst den Film.

Ein Frame ist eine Adresse

Die Zahl, die discGetFrame zurückgibt, ist eine Framenummer. Ein Frame ist ein einzelnes stehendes Bild. Dieses Video enthält 420 davon und zeigt etwa dreißig pro Sekunde, also dauert es etwa vierzehn Sekunden.

Frames werden ab null gezählt, also hat dieses Video die Frames 0 bis 419. Die Anzahl und die letzte Nummer sind nicht dasselbe, und darüber stolpert jeder einmal. discGetFrameCount sagt dir die Anzahl — 420 — und der höchste Frame, nach dem du fragen kannst, ist eins weniger.

Das Wichtige an einer Framenummer ist, dass sie sich nie ändert und nie verschiebt. Frame 110 ist der Moment, in dem der Drache Feuer speit, in dieser Kopie der Datei, auf diesem Rechner, heute und nächstes Jahr. Sekunden verschieben sich, weil ein Video nicht immer genau mit der Rate läuft, die du glaubst. Eine Framenummer ist die Adresse eines Moments, und aus Adressen ist ein Videospiel gebaut: Du schreibst dir den Frame auf, in dem der Drache erscheint, und von da an kannst du den Film dorthin schicken, wann immer du willst.

Diese Zahlen zu finden ist eine Arbeit, die du einmal pro Video machst, und das Skript, das du geschrieben hast, ist das Werkzeug dafür: Lass den Film laufen, beobachte den Zähler, schreib dir die Frames auf, in denen etwas passiert. Alles in Lektion sechzehn baut auf einer Liste von Zahlen auf, die genau so gefunden wurden.

Was am Ende passiert ist

Der Zähler hat 419 erreicht, und dann stand er wieder auf 0, und das Feuer war zurück.

Wenn die Disc über das Ende hinausläuft, startet die Engine sie wieder ab Frame null. Sie hält nicht an, und sie sagt dir nichts. Ein echtes Spiel lässt es nie so weit kommen: Es beobachtet die Framenummer und schickt die Disc woandershin, bevor das Ende kommt. Weil das jemand vergessen hat, spielt ein halbfertiges Videospiel mitten in einem Kampf plötzlich seine eigene Titelsequenz ab.

Anhalten, Springen und Fragen

Füg diese Funktion über onOverlayUpdate ein:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
    end
end

Speichere und probier jede aus. Die Leertaste spielt und pausiert. Links geht zurück zum Anfang. Rechts springt etwa eine Sekunde weiter. Die Taste 1 hält die Disc ganz an, und was du bekommst, ist ein blauer Bildschirm — die Farbe, die ein Laserdisc-Player zeigte, wenn er angehalten hatte, und sie ist geblieben, weil sehr viele Spiele ihre Punktetabelle darauf gezeichnet haben.

Das sind fünf neue Aufrufe, und sie teilen sich in zwei Arten auf.

Fragen. discGetState gibt einen von vier Namen zurück, die die Engine schon für dich festgelegt hat: DISC_PLAYING, DISC_PAUSED, DISC_STOPPED und DISC_EJECTED. Sie sind wie OVERLAY_UPDATED — keine Anführungszeichen, weil sie Namen für Werte sind und kein Text. Vergleiche mit ==, so wie du in Lektion drei Zahlen verglichen hast.

Sagen. discPlay startet oder setzt fort. discPause friert auf dem Frame ein, der gerade zu sehen ist, und lässt ihn auf dem Bildschirm. discStop ist der schwerere: Das Bild wird durch den blauen Bildschirm ersetzt, discGetFrame antwortet 0, bis die Disc wieder läuft, und discPause und die Sprungaufrufe werden ignoriert, solange sie angehalten ist. Jeder von discPlay, discSearch oder discSkipToFrame hebt das Anhalten wieder auf.

Zwei Aufrufe schicken die Disc zu einem Frame, und der Unterschied zwischen ihnen ist das Einzige in dieser Lektion, das du dir einprägen solltest:

  • discSearch(frame) geht dorthin und pausiert dort.

  • discSkipToFrame(frame) geht dorthin und spielt von dort ab.

Nimm Search, wenn du auf einem Bild parken und warten willst. Nimm Skip, wenn eine Szene anfangen soll. discSkipForward(30) und discSkipBackward(30) sind dieselbe Idee, gemessen ab dort, wo du bist, statt ab dem Anfang, und sie lassen die Disc spielen, wenn sie gespielt hat, und pausiert, wenn sie pausiert war.

Es gibt auch discPauseAtFrame, das unter einem älteren Namen genau das tut, was discSearch tut. Die Referenz kennzeichnet es als alten Alias. Du wirst es in den Skripten anderer Leute sehen; schreib in deine eigenen discSearch.

Warten ist schwerer, als es klingt

Das ist der Satz, aus dem jedes Videospiel besteht:

Spiel von Frame 0 bis Frame 120, dann stell dem Spieler eine Frage.

Versuch, ihn zu schreiben. Du kannst nicht „spiel, dann warte, dann frag“ schreiben, weil du keinen Ort hast, an dem du das schreiben könntest. Du hast onOverlayUpdate, das Singe sechzigmal pro Sekunde aufruft und das jedes einzelne Mal sofort zurückkehren muss. Eine Funktion, die dasäße und wartete, würde die Engine abwürgen: kein Zeichnen, keine Eingabe, kein Video.

Du kannst also nicht „dann“ sagen. Du musst aus dem „dann“ eine Variable machen, die sich merkt, wie weit du gekommen bist, und sie bei jedem dieser sechzig Aufrufe prüfen:

local asking = false


function onOverlayUpdate()
    overlayClear()
    if not asking and discGetFrame() >= 120 then
        discPause()
        asking = true
    end
    if asking then
        overlayPrint(2, 4, "Left or right?")
    end
    return OVERLAY_UPDATED
end

Das funktioniert. Lies es, und du siehst, dass es funktioniert. Aber achte darauf, was es gekostet hat: eine Variable, deren einzige Aufgabe es ist, sich zu merken, in welchem Teil des Satzes du bist, und zwei if-Anweisungen, die sie ehrlich halten.

Jetzt füg den Rest der Szene hinzu. Der Spieler antwortet, also spielt als Nächstes eins von zwei Dingen. Jedes davon endet irgendwo und stellt eine weitere Frage. Ein bescheidenes verzweigtes Spiel hat vierzig solcher Momente, und jeder davon will seine eigene Variable und sein eigenes if. Am Ende hast du ein Skript, in dem die Geschichte nirgends aufgeschrieben steht — sie ist über ein Dutzend Flags verteilt, und um herauszufinden, was nach dem Drachen passiert, musst du sie alle lesen.

Merk dir diesen Gedanken. Lektion fünfzehn ist nichts anderes als die Lösung dafür.

Wenn es kein Video gibt

Starte dein Skript wieder auf die schlichte Art, ohne -v:

Singe -R movie

Nichts stürzt ab. Du bekommst ein schwarzes Fenster mit Frame 0 in der Ecke.

Das lohnt sich zu verstehen, denn es ist die beruhigende Hälfte des Versprechens vom Anfang dieser Lektion. Ein Spiel ohne Disc führt trotzdem jeden disc-Aufruf aus, den du machst; sie tun nur nichts Nützliches. Die Engine dokumentiert genau, was sie antworten, und das ändert sich nie: discGetFrame und discGetFrameCount geben 0 zurück, discGetState gibt DISC_EJECTED zurück, discGetWidth und discGetHeight geben die Größe der Zeichenfläche zurück, und discPlay, discPause, discSearch und der Rest werden im Log vermerkt und ansonsten ignoriert.

Du kannst kein Skript kaputt machen, indem du eine Disc-Funktion aufrufst, wenn es keine Disc gibt.

Wenn ein Skript es wissen muss, fragt es SINGE_DISC. Das ist ein weiterer Name, den die Engine festlegt, bevor dein Skript läuft, und er ist true, wenn das Spiel ein Video hat, und false, wenn die Welt eine schlichte Zeichenfläche ist. So schreibt man richtig ein Spiel, das auf beide Arten laufen kann:

    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

not dreht einen Wahr-oder-falsch-Wert um, wie in Lektion drei.

Das Ganze

Zusammengesetzt, mit einer kleinen Funktion, die den Zustand in Worte fasst, und einem Frame, an dem angehalten wird, ist das hier das fertige Skript. Es ist ein Frame-Finder: das Werkzeug, das du jedes Mal benutzen wirst, wenn du einem neuen Video begegnest.

dofile("Singe/Framework.singe")

local stopAt = 400
local held   = false


local function stateName()
    local state = discGetState()

    if state == DISC_PLAYING then
        return "playing"
    elseif state == DISC_PAUSED then
        return "paused"
    elseif state == DISC_STOPPED then
        return "stopped"
    end
    return "not there"
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
        held = false
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
        held = false
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

    if not held and frame >= stopAt then
        discPause()
        held = true
    end

    overlayPrint(2, 2, "Frame " .. frame .. " of " .. discGetFrameCount())
    overlayPrint(2, 4, "The disc is " .. stateName() .. ".")
    overlayPrint(2, 6, "Space plays and pauses.  Left rewinds.")
    overlayPrint(2, 7, "Right jumps on a second.  1 stops the disc.")
    if held then
        overlayPrint(2, 9, "Holding at frame " .. stopAt .. ".")
    end

    return OVERLAY_UPDATED
end


discPlay()

held ist dieselbe Art von Variable wie asking oben, und sie ist aus einem Grund da, den du testen kannst: Nimm sie heraus, lass if frame >= stopAt then discPause() end stehen und versuch dann, mit der Leertaste über Frame 400 hinaus weiterzumachen. Es geht nicht. Die Disc läuft eine Sechzigstelsekunde lang weiter, und das nächste onOverlayUpdate pausiert sie wieder, für immer. Mit held sagst du „das habe ich schon einmal gemacht“.

Probier es aus

  1. Finde den Drachen. Starte es, beobachte den Zähler und schreib dir den Frame auf, in dem der Drache zum ersten Mal erscheint, den Frame, in dem er Feuer speit, und den Frame, in dem das Gitter den Bildschirm übernimmt. Diese drei Zahlen wirst du in Lektion sechzehn brauchen.

  2. Geh es Schritt für Schritt durch. Ändere discSkipForward(30) in discSkipForward(1) und halt die Pfeiltaste nach rechts gedrückt. Jetzt ändere stopAt in einen Frame mitten im Drachen und benutz discSearch und die Pfeiltaste, um genau darauf zu landen.

  3. Lass es in Schleife laufen. Ändere das Anhalten so, dass es statt bei Frame 400 zu pausieren discSkipToFrame(0) aufruft. Du hast einen Attract-Modus gebaut: eine Szene, die für immer läuft, bis jemand einen Knopf drückt.

  4. Frag nach einem Frame, den es nicht gibt. Ändere die Zeile mit SWITCH_RIGHT in discSkipToFrame(100000). Es stürzt nicht ab. Lies den Eintrag zu discSkipToFrame in der Referenz und finde den Satz, der sagt, warum.

  5. Spiel es ohne das Video. Starte Singe -R movie und drück dann jede Taste. Nichts, was du drückst, kann es kaputt machen.

Mach es absichtlich kaputt

Der Fehler, der hier am meisten Zeit kostet, ist kein Lua-Fehler. Starte das hier:

Singe -R -v menuBackground.mkv movie

Der Pfad ist falsch — er zählt ab dem Arbeitsordner, und das Video liegt dort im Ordner Singe, nicht lose herum — und Singe startet nicht. Stattdessen gibt es seine ganze Liste von Befehlszeilenoptionen aus, was beim ersten Mal erschreckend ist, und dann das hier als allerletzte Zeile:

Error:  Unable to locate video.

So eine Wand aus Optionen bedeutet immer dasselbe: Die Engine ist nie bis zu deinem Spiel gekommen. Ignorier die Wand und lies die letzte Zeile.

Der ist leicht. Die wenig hilfreiche Version davon ist, ganz ohne -v zu starten und zu vergessen, dass du das getan hast. Es gibt keinen Fehler, weil ein Spiel ohne Video ein völlig gutes Spiel ist. Du bekommst einen schwarzen Bildschirm und einen Zähler, der auf 0 festhängt, und suchst zwanzig Minuten lang in deinem Skript nach dem Fehler.

Genau dafür ist der Block mit SINGE_DISC im fertigen Skript da. Drei Zeilen davon, und das Spiel sagt dir, was nicht stimmt, statt zu schmollen. Bau so eine Prüfung in jedes Skript ein, das ein Video braucht.

Was du gelernt hast

  • Ein Spiel spielt nur dann Video ab, wenn es darum bittet, und alles andere in Singe funktioniert so oder so gleich.

  • Singe nennt das Video die Disc. Ein Spiel hat eine, und die disc-Funktionen nehmen kein Handle, weil es nichts gibt, zwischen dem man wählen müsste.

  • Das Video kommt mit -v auf die Befehlszeile, nicht ins Skript.

  • Das Overlay wird über das Bild gezeichnet, und der Film scheint überall durch, wo du nicht gezeichnet hast.

  • Ein Frame ist ein einzelnes stehendes Bild, ab null gezählt, und eine Framenummer ist die Adresse eines Moments.

  • discGetFrame fragt, wo die Disc ist; discGetFrameCount sagt, wie viele Frames es gibt; discGetState sagt, was die Disc gerade tut.

  • discPlay, discPause und discStop steuern sie. discSearch geht zu einem Frame und pausiert; discSkipToFrame geht zu einem Frame und spielt.

  • Eine Disc, die über das Ende hinausläuft, fängt wieder bei Frame null an, ohne es dir zu sagen.

  • Ohne Disc ist jeder disc-Aufruf harmlos, und an SINGE_DISC erkennt ein Skript, in welcher Art von Spiel es steckt.

  • Du kannst in onOverlayUpdate nicht warten, also muss „dann“ als Variable ausgeschrieben werden.

Beim nächsten Mal

Der letzte Punkt ist der wunde. Ein Videospiel ist eine Liste von Schritten — spiel dies, frag das, spiel jenes — und du hast gerade gesehen, dass das Callback-Modell nicht „dann“ sagen kann ohne ein Flag und ein if für jeden Schritt. Lektion fünfzehn zeigt dir die andere Art, wie Singe dich ein Skript schreiben lässt, und darin ist „dann“ eine neue Zeile.

Lektion 15: Die andere Schreibweise

Die fertige Lektion

Jede Lektion bisher war auf dieselbe Art geschrieben. Du schreibst Funktionen, deren Namen mit on anfangen, Singe ruft sie auf, wann es ihm passt, und du sagst nie, in welcher Reihenfolge irgendetwas passiert. Das ist das ereignisgesteuerte Modell, und so funktionieren die meisten Spiel-Engines.

Singe hat ein zweites Modell. Darin schreibst du dein Spiel als Liste von Schritten, von der ersten Zeile bis zur letzten, und du darfst warten. In dieser Lektion schreibst du dieselbe kurze Videosequenz auf beide Arten und siehst den Unterschied mit eigenen Augen.

Der Ablauf

Das macht das Spiel, auf Deutsch:

  1. Starte den Film am Anfang und spiel ihn bis Frame 120.

  2. Halte dort an und bitte den Spieler, die Leertaste zu drücken.

  3. Wenn er sie drückt, spiel weiter bis Frame 300.

  4. Halte dort an, sag „The end.“, warte vier Sekunden und beende das Spiel.

Vier Schritte. Lies sie noch einmal und achte darauf, dass in jedem von ihnen das Wort „dann“ steckt, ausgesprochen oder nicht.

Die Art, die du kennst

Leg im Ordner movie aus Lektion vierzehn eine Datei namens events.singe an und tipp das hier ein:

dofile("Singe/Framework.singe")

local step    = 1
local endedAt = 0


function onInputPressed(what)
    if what == SWITCH_BUTTON1 and step == 2 then
        step = 3
        discPlay()
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    overlayPrint(2, 2, "Frame " .. frame)

    if step == 1 then
        if frame >= 120 then
            discPause()
            step = 2
        end
    elseif step == 2 then
        overlayPrint(2, 4, "Press the space bar to go on.")
    elseif step == 3 then
        if frame >= 300 then
            discPause()
            endedAt = singeGetTicks()
            step = 4
        end
    elseif step == 4 then
        overlayPrint(2, 4, "The end.")
        if singeGetTicks() - endedAt > 4000 then
            singeQuit()
        end
    end

    return OVERLAY_UPDATED
end


discSearch(0)
discPlay()

Starte es. Den Ordner zu nennen würde movie.singe starten, also nenn stattdessen das Skript, so wie Lektion eins es dir gezeigt hat:

Singe -R -v Singe/menuBackground.mkv movie/events.singe

Es funktioniert. Es macht genau die vier Schritte. singeGetTicks ist neu — es gibt die Zahl der Millisekunden seit dem Start der Engine zurück, und so misst man gewöhnlich eine Zeitspanne — und singeQuit beendet das Spiel, genau das, was die Engine für dich tut, wenn du Esc drückst.

Lies jetzt das Skript und versuch, die vier Schritte darin zu finden. Sie sind da, aber von innen nach außen gekehrt. Die Reihenfolge der Geschichte steht in den Werten von step, nicht in der Reihenfolge der Zeilen, und step wird in einer Funktion gesetzt und in einer anderen gelesen. Um die Frage „Was passiert, nachdem der Spieler die Leertaste gedrückt hat?“ zu beantworten, musst du das Ganze auf einmal im Kopf behalten.

Und das ist die einfache Version. Es gibt darin zwei Entscheidungen.

Die andere Art

Fang eine neue Datei an, steps.singe, und tipp das hier ein:

local message = ""
local pressed = false


local function drawFrame()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    overlayPrint(2, 4, message)
end


local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end


local function waitForButton()
    pressed = false
    while not pressed do
        drawFrame()
        singeYield()
    end
end


local function waitSeconds(seconds)
    local stopTime = singeGetTicks() + seconds * 1000

    while singeGetTicks() < stopTime do
        drawFrame()
        singeYield()
    end
end


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


function singeMain()
    discSearch(0)
    discPlay()
    playTo(120)
    discPause()

    message = "Press the space bar to go on."
    waitForButton()

    message = ""
    discPlay()
    playTo(300)
    discPause()

    message = "The end."
    waitSeconds(4)
end


dofile("Singe/Framework.singe")

Starte es genauso, diesmal mit movie/steps.singe am Ende. Es macht dieselben vier Dinge.

Lies jetzt singeMain. Die vier Schritte sind die vier Absätze, der Reihe nach, von oben nach unten, und nirgends gibt es eine Variable step, denn die Stelle in der Geschichte ist die Stelle in der Funktion. Darum geht es in dieser ganzen Lektion.

Was gerade passiert ist

function singeMain()

singeMain ist ein Name, nach dem Singe sucht, wie onOverlayUpdate. Wenn dein Skript sie definiert, lässt das Framework dein Spiel von ihr aus laufen: Sie wird einmal aufgerufen, am Anfang, und dein Spiel dauert so lange, wie sie dauert. Wenn sie zurückkehrt, wird das Spiel beendet.

        singeYield()

Das ist der Aufruf, der das möglich macht, und er bedeutet „lass einen Frame passieren“.

Singe macht nicht zwei Dinge gleichzeitig — hier läuft nichts parallel, egal, was der Name Thread-Modell (englisch threaded) nahelegt. Was passiert, ist Folgendes: singeYield hält deine Funktion genau dort an, wo sie gerade steht, gibt die Kontrolle an die Engine zurück und merkt sich die Stelle. Die Engine zeichnet den Frame, liest die Eingaben, lässt das Video weiterlaufen und startet deine Funktion dann wieder ab der Zeile nach dem singeYield, mit jeder Variablen genau so, wie du sie verlassen hast.

Eine while-Schleife mit einem singeYield darin ist also eine Art zu warten. Es ist die einzige Art zu warten, und du musst eines in jede Schleife setzen, die auf etwas wartet. Das ist ein Handel, den du mit der Engine abschließt: Du darfst dasitzen und warten, solange du ihr sechzigmal pro Sekunde den Frame zurückgibst.

local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end

Singe hat keine Funktion „warte, bis das Video Frame 120 erreicht“. Es braucht keine, denn du kannst sie in vier Zeilen schreiben, und das hast du gerade getan. Mach weiter, solange die Disc den Frame, den du willst, noch nicht erreicht hat; gib in jeder Runde einen Frame zurück.

waitForButton hat dieselbe Form mit einer anderen Frage, und waitSeconds hat noch einmal dieselbe Form, mit einer Uhr. Drei kleine Funktionen, einmal geschrieben, und ihretwegen liest sich singeMain wie die deutschen Sätze oben in der Lektion. Genau dafür sind deine eigenen Funktionen da, hat Lektion fünf gesagt.

        drawFrame()
        singeYield()

Jede Warteschleife zeichnet, bevor sie den Frame abgibt, und das ist der Teil, der die Leute überrascht. Im Thread-Modell gibt es kein eigenes onOverlayUpdate, also wird nichts gezeichnet, was du nicht selbst zeichnest. Was du vor einem singeYield zeichnest, erscheint in diesem Frame. Hör auf zu zeichnen, und das Overlay hört auf, sich zu ändern.

Darum gibt es message. singeMain setzt es, und drawFrame gibt es aus, und die drei Warteschleifen rufen alle drawFrame auf. Das ist ein kleiner Preis dafür, dass die Geschichte wieder in der richtigen Reihenfolge steht.

dofile("Singe/Framework.singe")

Ganz unten. Das ist wichtiger als alles andere in dieser Lektion, also lohnt es sich zu wissen, warum.

dofile führt ein anderes Skript innerhalb deines Skripts aus, und eines der Dinge, die das Framework dabei tut, ist, nach einer Funktion namens singeMain zu suchen. Wenn es eine findet, baut es dein Spiel um sie herum und schreibt ein eigenes onOverlayUpdate, dessen ganze Aufgabe es ist, dein singeMain einmal pro Frame wieder anzustoßen. Findet es keine, tut es nichts dergleichen, und dein Spiel ist ein gewöhnliches ereignisgesteuertes Spiel.

Also muss das Framework geladen werden, nachdem es singeMain gibt. Lädst du es oben, so wie in jeder Lektion seit der siebten, dann gibt es in dem Moment, in dem es nachsieht, noch kein singeMain, und du bekommst ein Spiel, in dem kein Spiel steckt.

Die Regeln

Es sind vier, und zusammen decken sie jeden Fehler ab, den du hier machen kannst.

Das Framework kommt zuletzt. Aus dem Grund oben.

Schreib kein eigenes onOverlayUpdate. Das Framework hat schon eines geschrieben, und es kann nur eines geben: Welches der beiden zuletzt geschrieben wird, gewinnt, und das andere wird kommentarlos weggeworfen. Steht deins über dem dofile, fliegt deins raus, und was du zeichnest, erscheint nie. Steht es darunter, fliegt das des Frameworks raus, und dein singeMain läuft nie wieder. Zeichne stattdessen aus singeMain heraus.

Jede wartende Schleife braucht ein singeYield. Eine Schleife ohne gibt den Frame nie zurück. Das Fenster zeichnet sich nicht mehr neu, reagiert nicht mehr, und das Spiel ist weg; um herauszukommen, schließt du das Terminal. Es gibt keine Fehlermeldung, denn aus Sicht der Engine ist deine Funktion noch nicht fertig.

Wenn singeMain zurückkehrt, endet das Spiel. Das ist ordentlich, wenn du es so meinst, und eine Überraschung, wenn nicht. Ein Spiel, das ewig weiterlaufen soll, endet mit einer Schleife, die nie verlassen wird:

    while true do
        drawFrame()
        singeYield()
    end

Eingaben kommen trotzdem an

Sieh dir noch einmal an, wo pressed gesetzt wird:

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

Das ist ein Callback, in einem Skript, das als Liste von Schritten geschrieben ist. Beide Modelle laufen gleichzeitig, und das ist so gewollt.

Wenn es singeMain gibt, wird dir nur onOverlayUpdate weggenommen. Alles andere — onInputPressed, onInputReleased, onKeyPressed, onSoundCompleted, onShutdown, alle — wird genau so ausgelöst wie immer, in den Lücken zwischen deinen Yields. Die übliche Art, ein Spiel in diesem Modell zu schreiben, ist also die, die du gerade benutzt hast: die Geschichte in singeMain und ein kleiner Callback, der ein Ereignis auffängt und der Geschichte eine Notiz hinterlässt, die sie finden kann.

waitForButton setzt pressed auf false, bevor es zu warten anfängt, und wirft damit alles weg, worauf der Spieler vorher herumgehämmert hat. Lass diese Zeile weg, und ein Knopf, der während des Videos gedrückt wurde, zählt als Antwort auf eine Frage, die noch gar nicht gestellt wurde.

Welches du nimmst

Keines der beiden Modelle ist das bessere. Sie passen zu verschiedenen Aufgaben, und ein echtes Spiel nimmt das, was passt.

Das Thread-Modell passt zu allem, was ein Ablauf ist. Spiel das ab, dann frag, dann spiel jenes ab. Ein Vorspann. Eine Zwischensequenz. Ein Tutorial. Ein Bosskampf mit drei Phasen. Alles, was du ganz natürlich als nummerierte Liste beschreiben würdest, ist ein singeMain, das darauf wartet, geschrieben zu werden, und nichts ist so sehr ein Ablauf wie Video, und darum kommt Teil drei genau hier darauf.

Das ereignisgesteuerte Modell passt zu allem, was eine Situation ist. Zehn Gegner und ein Spieler, alle in Bewegung, alle stoßen zusammen, keiner in irgendeiner Reihenfolge. Das Spiel, das du in Lektion sieben geschrieben hast, hat überhaupt keinen Ablauf: Jeder Frame ist dieselbe Frage, noch einmal gestellt, und das ist genau die Form von onOverlayUpdate. Schreib das als Liste von Schritten, und du gewinnst nichts und verlierst die Klarheit.

Wenn ein Spiel beides ist (und das sind die meisten), wird es auch als beides geschrieben. singeMain geht der Reihe nach durch die Level, und in jedem Level erledigt eine Schleife sechzigmal pro Sekunde die Arbeit aus Lektion sieben, bis das Level endet.

Probier es aus

  1. Füg einen Schritt hinzu. Lass den Film nach waitForButton stattdessen zurückspringen: discSkipToFrame(0), dann playTo(60), dann weiter wie vorher. Zwei neue Zeilen an einer Stelle, und sonst muss nichts im Skript davon wissen.

  2. Füg denselben Schritt in das andere ein. Mach das jetzt in events.singe. Zähl, an wie vielen Stellen du etwas ändern musstest.

  3. Schreib waitFrames. Eine vierte Hilfsfunktion neben den anderen drei, die eine bestimmte Zahl von Video-Frames wartet statt einer bestimmten Zahl von Sekunden. Benutz discGetFrame und merk dir, wo du angefangen hast.

  4. Lass ein Yield weg. Lösch das singeYield() in playTo und starte es. Mach dich bereit, das Terminal zu schließen, denn nichts anderes hält es an. Setz es jetzt wieder ein, lösch stattdessen drawFrame() und finde an dem, was du siehst, heraus, warum der Frame-Zähler stehen bleibt, der Film aber nicht.

  5. Mach eine Schleife daraus. Pack den ganzen Inhalt von singeMain in while true do …​ end, damit der Ablauf von vorn anfängt, statt zu enden. Mit Esc kommst du trotzdem heraus, denn das war nie deine Aufgabe.

Mach es absichtlich kaputt

Verschieb die Zeile dofile("Singe/Framework.singe") vom Ende von steps.singe an den Anfang und starte es.

Es gibt keinen Fehler. Nichts wird ausgegeben. Das Fenster geht auf, der erste Frame des Films steht da, und mehr passiert nie.

Das ist die schlimmste Art von Bug, und genau darum lohnt es sich, ihm absichtlich zu begegnen. Aus Sicht der Engine ist nichts schiefgegangen: Dein Skript wurde geladen, das Framework wurde geladen, und keines von beiden hat ein onOverlayUpdate definiert, also hat die Engine nichts aufzurufen. Die Disc steht auf Frame eins, pausiert, genau so, wie die Engine sie hinterlassen hat, denn das discPlay, das sie gestartet hätte, steckt in einem singeMain, das nie jemand ausführt.

Wenn ein Spiel im Thread-Modell überhaupt nichts tut, sieh dir zuerst die letzte Zeile der Datei an. Fast immer liegt es daran.

Was du gelernt hast

  • Singe kennt zwei Arten, ein Skript zu schreiben, und du wählst, indem du singeMain definierst oder nicht.

  • Im Thread-Modell ist dein Spiel eine Liste von Schritten und läuft von oben nach unten.

  • singeYield() gibt der Engine einen Frame zurück und macht mit der nächsten Zeile weiter.

  • Warten ist eine while-Schleife mit einem singeYield darin. Die Wartefunktion, die du brauchst, schreibst du selbst; die Engine liefert keine.

  • Nichts wird gezeichnet, wenn du es nicht zeichnest, vor einem Yield, in jedem Frame.

  • dofile("Singe/Framework.singe") kommt ans Ende eines Skripts im Thread-Modell.

  • Schreib kein eigenes onOverlayUpdate, wenn es singeMain gibt.

  • Jeder andere Callback wird weiterhin ausgelöst, also lassen sich Ereignisse und Schritte frei mischen.

  • Wenn singeMain zurückkehrt, endet das Spiel.

  • Abläufe wollen das Thread-Modell, Situationen das ereignisgesteuerte.

Beim nächsten Mal

Du kannst jetzt „spiel das ab, dann frag, dann spiel jenes ab“ als drei Zeilen schreiben. Ein verzweigtes Videospiel ist nichts anderes als dieser Satz, ein paar hundert Mal, wobei die Antworten entscheiden, welche Zeile als Nächstes kommt. Lektion sechzehn baut eines, und der interessante Teil ist am Ende gar nicht das Video. Es ist, die Karte davon, was wohin führt, in einer Form zu halten, die du noch lesen kannst, wenn das Spiel vierzig Szenen hat.

Lektion 16: Verzweigungen

Die fertige Lektion

Ein verzweigtes Videospiel ist ein Film mit Gabelungen darin. Eine Szene läuft, der Spieler entscheidet, und als Nächstes läuft eine andere Szene. Mach das zwanzig- oder dreißigmal, und du hast ein Spiel, das die Leute jahrelang immer wieder spielen, weil sie das Ende suchen, das sie noch nicht gesehen haben.

In dieser Lektion baust du eines. Es hat vier Szenen, zwei Entscheidungen, einen Timer bei jeder Entscheidung, einen Tod und drei Leben. Der Code, der es abspielt, ist etwa dreißig Zeilen lang, und er wäre immer noch etwa dreißig Zeilen lang, wenn das Spiel zweihundert Szenen hätte — denn das Spiel selbst wird überhaupt nicht in Code geschrieben.

Stell dir vor, es ist ein Drache

Das Video, das jeder hat, ist Singe/menuBackground.mkv, dieselben 420 Frames, die du seit Lektion vierzehn steuerst. Es ist ein Feuerball, ein Drache aus Papier, das Wort SINGE und dann ein magentafarbenes Gitter, das unter einer orangefarbenen Sonne endlos davonrollt.

Ein Drama ist es nicht. Niemand darin könnte in Gefahr geraten, und dem Sonnenuntergang ist egal, wie du dich entscheidest.

Spiel trotzdem mit. Für zwei Minuten ist der Drache echt genug, und alles, was du gleich schreibst, funktioniert genau gleich, wenn das Material ein Stuntman ist, der von einer Klippe stürzt. Hier ist die Karte, und die Frame-Nummern sind die, die du in Lektion vierzehn selbst herausgefunden hast:

Szene Frames Was passiert

arrive

0 bis 119

Feuer, und der Drache landet. Left or Right?

sunset

120 bis 259

Er speit Feuer. Duck Left or run Right?

pit

260 bis 339

Du wirst gefressen. Du verlierst ein Leben.

escape

340 bis 410

Das Gitter rollt davon, und du bist entkommen.

Links ist sozusagen immer richtig: Links von arrive führt zu sunset, links von sunset bringt dich zu escape. Rechts führt beide Male in die pit, und zu langes Zögern ebenso.

Die Karte ist Daten, kein Code

Hier ist das ganze Spiel, und es ist eine Tabelle.

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

Eine Tabelle mit Namen statt Zahlen auf der linken Seite, genau wie in Lektion sechs, und jeder Wert darin ist wieder eine Tabelle. Jede dieser inneren Tabellen ist ein Datensatz: eine Szene, Feld für Feld beschrieben.

scenes.arrive ist die erste Szene. scenes.arrive.first ist 0. scenes.arrive.left ist der String "sunset", und das ist der Name einer anderen Szene in derselben Tabelle — so werden die Gabelungen aufgeschrieben. Eine Szene enthält nicht die Szene nach ihr. Sie enthält den Namen der Szene nach ihr, und der Name wird nachgeschlagen, wenn es so weit ist.

Die Felder bedeuten Folgendes:

first und last

Die Frames, zwischen denen die Szene läuft.

ask

Der Frame, in dem die Frage erscheint. Der Spieler hat von ask bis last Zeit zu antworten, und das ist der Timer.

prompt

Was die Frage sagt.

left und right

Die Szene, zu der die jeweilige Antwort führt.

goesTo

Wohin die Szene geht, wenn niemand gewählt hat — weil dem Spieler die Zeit ausgegangen ist oder weil es gar keine Frage gab. Bei pit, einem Tod, ist es der Ort, an den der neue Versuch zurückkehrt.

death

Nur vorhanden, und dann true, bei einer Szene, die ein Leben kostet.

An dieser Tabelle sind drei Dinge bemerkenswert.

Das erste: Sie ist das Designdokument. Du kannst sie jemandem geben, der noch nie eine Zeile Lua geschrieben hat, und er kann das Spiel aus ihr herauslesen. Wenn sich der Drache dreifach gabeln soll, fügst du ein Feld hinzu. Wenn du eine weitere Szene willst, fügst du einen weiteren Datensatz hinzu. Du suchst nicht nach dem Code, der Szenen abspielt, denn den änderst du nicht.

Das zweite: Die Datensätze haben nicht alle dieselbe Form. pit hat kein ask, kein prompt und kein left — darin gibt es nichts zu wählen. escape hat kein goesTo, denn es ist das Ende und führt nirgendwohin. Ein Feld, das nicht in einer Tabelle steht, liest sich als nil, das Wort, das du in Lektion drei für „da ist nichts“ kennengelernt hast, und nach scenes.escape.goesTo zu fragen ist kein Fehler. Es ist nil, und nil ist eine Antwort. Code, der diese Datensätze liest, muss darauf vorbereitet sein, und gleich siehst du die eine Zeile, die es ist.

Das dritte ist, was die Tabelle nicht enthält: Nichts darin zeichnet, spielt ab oder wartet. Sie ist eine Beschreibung. Diese Trennung ist der ganze Trick dieser Lektion.

Eine Funktion, die jede Szene abspielt

Das ist die Code-Hälfte, und es gibt nur eine Funktion von nennenswerter Größe. Geschrieben im Thread-Modell aus Lektion fünfzehn, denn nichts ist so sehr ein Ablauf wie ein verzweigtes Spiel.

local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end

Sie nimmt den Namen einer Szene, spielt sie ab und gibt den Namen der Szene zurück, die als Nächstes kommt. Das ist ihre ganze Abmachung, und das Spiel besteht dann aus drei Zeilen:

function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end

Fang bei arrive an. Spiel die Szene ab, die du gerade in der Hand hast, und nimm in die Hand, was sie dir zurückgibt. Wenn sie nil zurückgibt, gibt es keine nächste Szene, die Schleife endet, und das Spiel ist vorbei.

Das Ganze

Leg dragon.singe in deinem Ordner movie an und tipp das hier ein. Es ist das bisher längste Skript im Buch, und jedes Stück davon ist erklärt, bis auf die zwei kleinen Hilfsfunktionen, die danach kommen.

local FPS = 30

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

local answer = nil
local ending = "You got out alive."
local lives  = 3


local function drawScene(scene, frame, asking)
    overlayClear()
    overlayPrint(2, 2, "Lives: " .. lives)
    if scene.death then
        overlayPrint(2, 4, "That did not go well.")
    elseif asking then
        overlayPrint(2, 4, scene.prompt)
        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")
    end
end


local function waitForGo(text)
    answer = nil
    while answer ~= "go" do
        overlayClear()
        overlayPrint(2, 2, "Lives: " .. lives)
        overlayPrint(2, 4, text)
        singeYield()
    end
end


local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        answer = "left"
    elseif what == SWITCH_RIGHT then
        answer = "right"
    elseif what == SWITCH_BUTTON1 then
        answer = "go"
    end
end


function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end


dofile("Singe/Framework.singe")

Starte es:

Singe -R -v Singe/menuBackground.mkv movie/dragon.singe

Spiel es vier- oder fünfmal. Geh zweimal nach links und entkomme. Geh nach rechts und werde gefressen. Setz dich auf deine Hände und werde trotzdem gefressen. Verlier alle drei Leben.

Was gerade passiert ist

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do

Eine Szene ist ein Sprung, gefolgt von Warten, und das ist das Muster aus Lektion fünfzehn, nur dass die Zahlen aus dem Datensatz kommen, statt eingetippt zu sein. discSkipToFrame geht zu einem Frame und spielt ab dort ab, und genau das ist ein Szenenwechsel.

Die Frame-Nummer stimmt in dem Augenblick, in dem der Aufruf zurückkehrt, also glaubt das while nie, es sei noch in der Szene, die du gerade verlassen hast.

        local asking = scene.ask ~= nil and frame >= scene.ask

Die eine Zeile, die auf ein fehlendes Feld vorbereitet ist, und der Grund, warum die Todesszene ask weglassen kann.

and heißt, dass beide Hälften wahr sein müssen, wie schon in Lektion drei, und Lua prüft zuerst die linke Hälfte. Wenn scene.ask nil ist, ist die linke Hälfte falsch, Lua hört dort auf, und der Vergleich auf der rechten Seite findet nie statt. Und das ist auch gut so, denn nil mit einer Zahl zu vergleichen ist ein Fehler, und dem begegnest du am Ende dieser Lektion.

asking ist die Antwort auf „Steht die Frage gerade auf dem Bildschirm?“, einmal pro Frame ausgerechnet und dreimal benutzt.

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end

Solange die Frage nicht zu sehen ist, wird alles weggeworfen, was der Spieler drückt. Das muss so sein, sonst beantwortet ein Spieler, der während des Films auf der linken Pfeiltaste lehnt, eine Frage, die er noch gar nicht gelesen hat.

Sobald die Frage zu sehen ist, beendet eine Antwort die Szene sofort. return scene[answer] ist einen zweiten Blick wert: answer enthält den String "left" oder "right", und scene["left"] ist dasselbe wie scene.left. Wenn du den Namen in eckige Klammern setzt statt hinter einen Punkt, kannst du ein Feld nachschlagen, dessen Namen du in einer Variablen hast. Zwei Zeilen Code für beide Antworten, und bei fünf Antworten wären es immer noch zwei Zeilen.

Das elseif erklärt auch, warum nur "left" und "right" durchgelassen werden. Die Leertaste setzt answer auf "go", und scene["go"] ist nil, also würde ein verirrter Druck auf die Leertaste während einer Frage das Spiel stillschweigend beenden. Sag, was du annimmst.

    discPause()

Direkt nach der Schleife, und leicht zu vergessen. Die Szene hat ihren letzten Frame erreicht, aber die Disc hat keine Ahnung, dass die Szene vorbei ist — sie spielt einfach weiter in das Material, das zufällig als Nächstes in der Datei liegt, und in einem echten Spiel ist das die Mitte einer Szene von ganz woanders. Halte sie in dem Moment an, in dem du sie nicht mehr willst.

    if scene.death then
        lives = lives - 1

scene.death ist bei jeder Szene außer pit nil, und nil zählt in einem if als falsch, also liest sich das als „wenn diese Szene ein Tod war“. Du musst death = false nicht in die anderen drei Datensätze schreiben, und du solltest es auch nicht: Dass das Feld fehlt, sagt es genauso gut, und dann gibt es nur eine Stelle, die entscheidet, welche Szenen tödlich sind.

Der neue Versuch steckt in den zwei Zeilen darunter. Nimm ein Leben weg, und wenn noch welche übrig sind, bleib auf dem Frame stehen und warte auf die Leertaste. Dann schickt return scene.goesTo den Spieler zurück zu arrive, und das weiß der Datensatz. Ändere goesTo in "sunset", und aus dem Neustart wird ein Checkpoint — ein Wort, und die Schwierigkeit des Spiels ändert sich.

        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")

Der Timer. scene.last - frame ist die Zahl der Frames, die noch übrig sind, und wenn du durch die Frames in einer Sekunde teilst, werden daraus Sekunden. math.ceil rundet eine Zahl auf die nächste ganze Zahl auf, also zeigt der Countdown 3, 2, 1 und nie 0.4 oder 2.966666.

FPS ist 30, weil dieses Video mit etwas über dreißig Frames pro Sekunde läuft. Es ist die einzige Zahl im Skript, die geschätzt ist, und sie ist eine benannte Schätzung oben in der Datei statt einer 30, die mitten in einer Zeile vergraben ist, damit es genau eine Sache zu ändern gibt, wenn du das Video wechselst.

Achte darauf, woran der Timer gemessen wird: am Film. Der Spieler läuft gegen das Video um die Wette, nicht gegen eine Uhr, also kann die Frage nie länger bleiben als die Einstellung, zu der sie gehört. Das ist der Grund, warum verzweigte Spiele in Frames zählen.

Warum nicht alles von Hand ausschreiben

Du könntest dieses Spiel als eine lange Funktion schreiben. Spiel die Frames 0 bis 119 ab; wenn links, spiel 120 bis 259 ab; wenn wieder links, spiel 340 bis 410 ab; sonst spiel 260 bis 339 ab, nimm ein Leben weg, geh zurück an den Anfang. Bei vier Szenen wäre das kürzer als das, was du jetzt hast.

Bei vierzig Szenen wäre es eine Katastrophe, und es lohnt sich, genau zu sagen, warum.

Die Frame-Nummern wären über den ganzen Code verstreut, jede einmal hingeschrieben und nie benannt, also hieße es, jede Stelle zu suchen, an der sie vorkommt, wenn du änderst, wo eine Szene anfängt. Die Form der Geschichte wäre in der Form der if-Anweisungen vergraben, also könnte niemand das Spiel sehen, ohne alles zu lesen. Und eine Szene hinzuzufügen hieße, den Code zu ändern, der abspielt, also den Code, der schon funktioniert — jede neue Szene eine weitere Gelegenheit, eine alte kaputt zu machen.

Die Version, die du geschrieben hast, hat ein Stück Code, das Szenen abspielt, und ein Stück Daten, das sagt, welche Szenen es gibt. Eine Szene hinzuzufügen berührt nur die Daten. Das ist die zusätzliche halbe Stunde wert, und dieselbe Idee steckt auch hinter der Datei games.dat aus Lektion dreizehn: Beschreib die Sache und schreib dann ein Stück Code, das die Beschreibung liest.

Probier es aus

  1. Füg ein Ende hinzu. Gib escape eine Frage und eine zweite Endszene, die Frames von irgendwo im Film wiederverwendet. Nur die Tabelle ändert sich.

  2. Mach es fair. Setz ask in beiden Szenen herunter, sodass der Spieler fünf Sekunden statt drei hat, und dann herauf, sodass er eine hat. Finde die Zahl, die du wirklich ausliefern würdest.

  3. Verschieb den Checkpoint. Ändere das goesTo von pit in "sunset" und spiel es. Dann überleg, was passiert, wenn ein Spieler in arrive stirbt — und ob die Todesszene wissen sollte, woher sie kam, statt es gesagt zu bekommen.

  4. Zähl, was der Spieler gesehen hat. Leg neben scenes eine Tabelle an, die festhält, welche Szenennamen schon gespielt wurden, und zeig die Anzahl in der Ecke. Jetzt hast du ein Spiel, das sagen kann: „Du hast drei von fünf Enden gefunden.“

  5. Mach die Karte kaputt. Ändere das left von arrive in "cave", eine Szene, die es nicht gibt. Starte es, geh nach links und lies, was Lua sagt. Dieser Fehler ist der häufigste, den ein datengesteuertes Spiel hat, und wenn du seine Form kennst, sparst du dir eine Stunde.

Mach es absichtlich kaputt

Nimm die Absicherung aus der Zeile mit asking heraus, sodass sie so lautet:

        local asking = frame >= scene.ask

Starte es und geh nach rechts. Die Szene arrive läuft problemlos, denn arrive hat ein ask. Dann beginnt die Szene pit, die keins hat, und das Spiel bleibt mit dieser Meldung stehen:

Error executing function 'onOverlayUpdate':  movie/dragon.singe:68: attempt to compare nil with number
stack traceback:
	[C]: in function 'error'
	Singe/Framework.singe:603: in function 'onOverlayUpdate'

Lies es so, wie Lektion eins es dir beigebracht hat. Die Datei und die Zeile kommen zuerst, und sie stimmen genau: Zeile 68 ist die Zeile, die du gerade geändert hast. Die Beschwerde ist der Rest: Du hast Lua gefragt, ob eine Zahl größer als nil ist, und Lua hat keine Ahnung. scene.ask ist nil, weil der Datensatz pit kein Feld ask hat, und ein Feld, das nicht da ist, ist nil.

Ein Teil dieser Meldung verdient eine Erklärung, denn er ist eine Lüge durch Weglassen. Die genannte Funktion ist onOverlayUpdate, und die hast du nicht geschrieben. Das ist die eigene des Frameworks, die, von der Lektion fünfzehn gesagt hat, dass sie installiert wird, um dein singeMain anzutreiben. Der Fehler kam durch sie heraus, also ist das der Name, den die Engine gerade zur Hand hatte, und der Traceback darunter — die Liste der Funktionen, die liefen, die innerste zuerst — kann nur zeigen, wie das Framework deinen Fehler weiterreicht. Ignorier beides. Die Datei und die Zeile ganz oben sind deine, und sie sind die, die stimmen.

Was du gelernt hast

  • Ein verzweigtes Spiel ist eine Menge von Szenen, und jede davon nennt die Szenen, die nach ihr kommen.

  • Halte die Szenen als Daten — eine Tabelle von Datensätzen — und der Code, der sie abspielt, bleibt eine einzige Funktion, egal wie groß das Spiel wird.

  • Ein Datensatz enthält den Namen der nächsten Szene, nicht die Szene selbst, und der Name wird nachgeschlagen, wenn er gebraucht wird.

  • Ein Feld, das nicht in einem Datensatz steht, ist nil, und das ist kein Fehler, aber Code, der Datensätze liest, muss damit rechnen.

  • scene[answer] schlägt das Feld nach, dessen Name in einer Variablen steht; scene.left und scene["left"] sind dasselbe Feld.

  • Häng den Timer an das Video: Eine Entscheidung dauert von einem Frame bis zu einem anderen, also kann sie nie länger dauern als ihre eigene Einstellung.

  • Wirf alles weg, was der Spieler gedrückt hat, bevor die Frage erschien.

  • Halte die Disc an, sobald eine Szene endet, sonst spielt sie weiter in das Material der nächsten Szene.

  • Ein fehlendes Feld, das für falsch steht — death bei drei von vier Datensätzen — hält die Beschreibung kurz und ehrlich.

  • nil mit einer Zahl zu vergleichen ist ein Fehler, und mit and vermeidest du ihn.

Beim nächsten Mal

Dein Spiel fragt nach links oder rechts. Die Arcade-Automaten, in denen diese Art von Spiel groß geworden ist, fragten etwas Schwierigeres: Ziel auf das Ding auf dem Bildschirm und schieß darauf. In Lektion siebzehn geht es um Lightguns — wohin der Spieler zielt, was das Spiel damit macht und die Kalibrierung, ohne die ein echter Automat nicht auskommt.

Lektion 17: Lightguns

Die fertige Lektion

Du baust eine Schießbude. Ziele erscheinen über dem Video bei Frames, die du aussuchst, du zielst auf den Bildschirm und drückst einen Abzug, und die, die du triffst, bringen Punkte.

Um das zu schreiben, brauchst du keine Lightgun. Du brauchst eine Maus, denn für Singe ist eine Lightgun eine Maus: Sie meldet eine Position in denselben Koordinaten, über dieselben Aufrufe, und ihr Abzug kommt als derselbe Schalter an wie eine Maustaste. Schreib das Spiel für die Maus auf deinem Schreibtisch, und es funktioniert auf einem Automaten mit einer festgeschraubten Lightgun, und nur andersherum ist es vernünftig. Eine Lightgun ist keine andere Art von Eingabe. Sie ist eine Maus, mit der jemand zielt.

Worauf du zielst

Fang genauso an wie in Lektion vierzehn, mit dem Video, das die Engine für dich entpackt hat:

Singe -R -v Singe/menuBackground.mkv gallery

Dieses Material ist ein lila Gitter und ein Sonnenuntergang. Es ist kein Banküberfall. Jede Frame-Nummer in dieser Lektion bezieht sich darauf, damit der Code an dem Tag läuft, an dem du ihn eintippst, und der ganze Clip ist 720 mal 480 groß und etwa 420 Frames lang, und bei ungefähr dreißig Frames pro Sekunde sind das vierzehn Sekunden. Stell dir besseres Material vor. Dem Code ist egal, was auf dem Bild ist.

Pass das Overlay an das Video an

Schreib das oben in gallery.singe, unter die Zeile mit dofile:

overlaySetResolution(discGetWidth(), discGetHeight())

Ohne diesen Aufruf ist das Overlay in jeder Richtung halb so groß wie das Video — hier 360 mal 240 — und jede Koordinate, mit der du zeichnest, und jede Mausposition, die du bekommst, liegt in diesem kleineren Raum. Am kleinen Overlay ist nichts falsch, aber es ist eine Umrechnung mehr, die du im Kopf behalten musst, während du herausfindest, wo ein Schuss gelandet ist. Wenn das Overlay zum Video passt, ist ein Ziel bei x = 80 achtzig Pixel weit im Bild, und ein Schuss bei x = 80 ebenso. Der Eintrag zu overlaySetResolution in der Referenz erklärt, was das kostet.

Wohin die Lightgun zielt

Das beantwortet ein einziger Aufruf:

local x, y = mouseGetPosition(0)

mouseGetPosition gibt zwei Zahlen zurück, und das hast du noch keine Funktion tun sehen, aber Lua hat damit überhaupt kein Problem: Eine Funktion darf so viele Werte zurückgeben, wie sie will, und du fängst sie auf, indem du genauso viele Namen links vom = aufschreibst. Die 0 sagt, nach welchem Zeigegerät du fragst, von null an gezählt. Mit einer Maus oder einer Lightgun ist die Antwort immer Gerät 0.

Die Zahlen sind in Overlay-Koordinaten, nicht in Desktop-Pixeln, und darum hat sich der Aufruf oben gelohnt. Die Position ist die letzte, die das Gerät gemeldet hat, also kannst du sie abfragen, wann du willst und so oft du willst. Frag sie in onOverlayUpdate ab und zeichne mit der Antwort.

Es gibt noch einen anderen Weg zu denselben Zahlen. onMouseMoved ist ein Callback, wie onOverlayUpdate, und die Engine ruft ihn jedes Mal auf, wenn sich ein Zeiger bewegt, und gibt ihm die neue Position. Das ist die richtige Wahl, wenn du auf Bewegung reagieren willst. Für ein Fadenkreuz willst du das nicht: Du willst wissen, wo das Ding gerade jetzt ist, und mouseGetPosition sagt dir das, ohne dass du eine Kopie aufheben musst.

Ein Fadenkreuz zeichnen

Die Engine zeichnet dir keins. Ein Fadenkreuz besteht aus vier Linien und einem Kreis:

local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end

Die Lücken sind wichtiger als die Linien. Wenn die vier Speichen vor dem Kreis aufhören, bleibt in der Mitte ein Loch, durch das du das Ziel siehst, und darum geht es bei einem Fadenkreuz überhaupt, und genau das zeichnen Anfänger als Erstes zu.

Eine Sache solltest du fragen, bevor du es zeichnest:

local drawAim = singeWantsCrosshairs()

Das gibt false zurück, wenn der Spieler Singe mit --nocrosshair gestartet hat. Manche Lightguns setzen einen eigenen Punkt auf den Bildschirm, und zwei Fadenkreuze ein paar Pixel auseinander sind schlimmer als keins. Die Antwort kann sich nicht ändern, während das Spiel läuft, also lies sie einmal oben aus und heb sie in einer Variablen auf.

Den Mauszeiger des Systems musst du nicht verstecken, denn das hat Singe schon getan. Es fängt die Maus beim Start ein, und dadurch bleibt sie im Fenster, und der Pfeil des Desktops ist versteckt. Willst du ihn je zurückhaben, etwa für einen Level-Editor, dann gibt mouseSetCaptured(false) die Maus frei, und die Taste, die mit INPUT_GRAB belegt ist, in der mitgelieferten Steuerung G, schaltet dasselbe während des Spielens um.

Der Abzug

Ein Abzug ist ein Knopf, und Knöpfe kommen bei onInputPressed an, das du zum ersten Mal in Lektion drei gesehen hast:

function onInputPressed(what, device)
    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    -- ...
end

SWITCH_BUTTON3 ist die linke Maustaste, und bei einer Lightgun ist es der Abzug. Die mitgelieferte controls.cfg belegt die linke Taste mit SWITCH_BUTTON3, die rechte mit SWITCH_BUTTON1 und die mittlere mit SWITCH_BUTTON2. Diese Nummern sehen durcheinandergewürfelt aus, und das sind sie auch: Die Schalter sind die Knöpfe des Arcade-Bedienfelds, und welches echte Bedienelement mit welchem verdrahtet ist, ist Sache des Automaten, nicht des Spiels. Die linke Umschalttaste ist ebenfalls mit SWITCH_BUTTON3 belegt, also kannst du beim Testen auch ohne Maus schießen.

Das zweite Argument ist das Neue. Wenn der Schalter von einer Maus oder einer Lightgun kam, ist device die Nummer dieses Geräts — 0 für das erste, 1 für das zweite und so weiter. Wenn er von einer Taste oder einem Gamepad kam, ist es nil, denn dann war kein Zeigegerät beteiligt. Darum steht im Aufruf oben device or 0: Wenn device nil ist, nimm stattdessen 0. Du wirst or ständig so benutzen, und es liest sich genau so, wie es klingt — „device oder nichts, und dann null“.

Dieses eine zusätzliche Argument macht einen Automaten mit zwei Lightguns möglich. Die Lightgun von Spieler eins ist Gerät 0, die von Spieler zwei ist Gerät 1, und dasselbe onInputPressed unterscheidet sie, ohne dass du raten musst.

Hat er etwas getroffen?

Wie man das beantwortet, weißt du schon. Das ist Lektion elf:

if collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then

Ein Schuss ist ein Punkt. Ein Ziel ist ein Rechteck. collidePointRect fragt, ob der Punkt im Rechteck liegt, und der Rand zählt als innen. Am Schießen ist nichts Besonderes. Der Treffertest eines Lightgun-Spiels ist derselbe Treffertest, mit dem ein Plattformspiel herausfindet, ob du auf einem Block gelandet bist, und die collide-Familie in der Referenz hat die übrigen Formen.

Ziele, die kommen und gehen

Das Einzige, was Video ändert, ist, wann es ein Ziel gibt. In Lektion elf war ein Felsen da, bis du ihn abgeschossen hast. Hier ist ein Ziel auf dem Bildschirm, solange der Film den Teil der Szene zeigt, zu dem es gehört, und dann ist es weg, ob du es getroffen hast oder nicht.

Das sind zwei Felder mehr im Datensatz, und das Werkzeug dafür hat dir Lektion sechs gebaut:

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

Vier Datensätze, jeder mit dem Frame, in dem das Ziel erscheint, dem Frame, in dem es verschwindet, und der Stelle, an der es sitzt. Ein fünftes Ziel hinzuzufügen heißt, eine Zeile hinzuzufügen. Zu dieser Form solltest du jedes Mal greifen, wenn du gerade dabei bist, dieselben vier Zeilen Code mit anderen Zahlen darin zu schreiben.

Ob ein Ziel zählt, ist dann eine kleine eigene Funktion:

local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end

Das Zeichnen fragt sie, und das Schießen auch, und genau dafür steht sie an einer Stelle: Ein Ziel, das du sehen kannst, und ein Ziel, das du treffen kannst, können sich nie widersprechen.

Das Ganze

-- Programmieren lernen mit Singe -- Lektion 17: Lightguns

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local LAST_FRAME  = 400
local TARGET_SIZE = 96
local HIT_SCORE   = 100
local FLASH_TIME  = 12

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

local aimX    = overlayGetWidth() / 2
local aimY    = overlayGetHeight() / 2
local score   = 0
local shots   = 0
local hits    = 0
local flash   = 0
local flashX  = 0
local flashY  = 0
local drawAim = singeWantsCrosshairs()


local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end


local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end


local function startRound()
    score = 0
    shots = 0
    hits  = 0
    flash = 0
    for _, target in ipairs(targets) do
        target.hit = false
    end
    discSkipToFrame(FIRST_FRAME)
end


function onInputPressed(what, device)
    if what == SWITCH_START1 then
        startRound()
        return
    end

    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    local frame = discGetFrame()

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then
            target.hit = true
            hits       = hits + 1
            score      = score + HIT_SCORE
            flash      = FLASH_TIME
            flashX     = x
            flashY     = y
            return
        end
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if frame >= LAST_FRAME then
        startRound()
        frame = FIRST_FRAME
    end

    aimX, aimY = mouseGetPosition(0)

    overlayClear()

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) then
            colorForeground(255, 200, 0, 255)
            overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)
            overlayCircle(target.x + TARGET_SIZE / 2, target.y + TARGET_SIZE / 2, TARGET_SIZE / 3)
        end
    end

    if flash > 0 then
        colorForeground(255, 255, 255, 255)
        overlayCircle(flashX, flashY, 30 - flash * 2)
        flash = flash - 1
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   HITS " .. hits .. "/" .. shots .. "   FRAME " .. frame)

    if drawAim then
        drawCrosshair(aimX, aimY)
    end

    return OVERLAY_UPDATED
end


startRound()

Ziel auf ein gelbes Kästchen und klick. Der Zähler in der Ecke geht hoch, ein weißer Ring öffnet sich da, wo du getroffen hast, und das Kästchen verschwindet. Daneben geschossen, und nur die Zahl der Schüsse geht hoch, und das ist die billigste Punktetafel, die es gibt, und sie sagt einem Spieler mehr darüber, wie er sich schlägt, als die Punktzahl. Die Runde fängt von selbst neu an, wenn der Film zu Ende ist, und mit 1 fängt sie neu an, wann immer du willst.

Was gerade passiert ist

local frame = discGetFrame()

if frame >= LAST_FRAME then
    startRound()
    frame = FIRST_FRAME
end

Das Video ist die Uhr, wie schon in Lektion vierzehn, und mit discGetFrame liest du sie ab. Alles andere im Frame wird von dieser einen Zahl aus entschieden. Wenn der Film über das Ende des letzten Ziels hinausläuft, fängt die Runde von vorn an: startRound löscht die Punkte, markiert jedes Ziel als nicht getroffen und schickt die Disc mit discSkipToFrame zurück an den Anfang. Die Zeile darunter setzt auch die lokale Kopie von frame, denn die wurde vor dem Sprung gelesen und enthält noch die alte Zahl. Ohne sie würde das Zeichnen darunter einen Frame lang mit einer Zahl arbeiten, die nicht mehr stimmt.

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(...) then

Zähl den Schuss, bevor du nach einem Treffer suchst, damit auch ein Fehlschuss zählt. Dann geh die Liste durch. Das return in der Schleife hört beim ersten getroffenen Ziel auf, und das heißt, dass eine Kugel nicht zwei sich überlappende Ziele erwischen kann — eine Regel, die du so oder so festlegen musst, und das hier ist die Zeile, die sie festlegt.

overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)

overlayBox will zwei gegenüberliegende Ecken, nicht eine Ecke und eine Größe, also ist die ferne Ecke die nahe plus die Größe. Das - 1 kommt daher, dass beide Ecken dazugehören: Ein Kästchen von 80 bis 175 ist sechsundneunzig Pixel breit. collidePointRect will dagegen eine Ecke und eine Größe, und darum steht TARGET_SIZE dort für sich allein und wird hier zur Ecke addiert. Die beiden zu verwechseln ist ein wirklich häufiger Bug, und er zeigt sich als Ziele, die du ein Stück außerhalb der Stelle treffen kannst, an der sie gezeichnet sind.

if flash > 0 then
    colorForeground(255, 255, 255, 255)
    overlayCircle(flashX, flashY, 30 - flash * 2)
    flash = flash - 1
end

flash ist ein Countdown in Frames, der auf zwölf gesetzt wird, wenn ein Schuss trifft, und jedes Mal um eins kleiner wird, wenn der Bildschirm gezeichnet wird. Weil der Radius aus dem Countdown ausgerechnet wird, wächst der Ring, während die Zahl schrumpft. Zwölf Frames sind weniger als eine halbe Sekunde. Eine Rückmeldung, die länger dauert, fühlt sich nicht mehr wie eine Folge des Abzugs an, sondern wie Wetter.

Zwei Lightguns

Du bist zwei Änderungen von einem Automaten für zwei Spieler entfernt, und keine davon steckt in der Spielschleife.

Die erste ist mouseSetMode(MOUSE_MANY), das Singe sagt, jedes Gerät einzeln zu lesen, statt alle zu einem Mauszeiger zusammenzulegen. mouseHowMany() sagt, wie viele es beim Start gefunden hat, also fragt ein Spiel normalerweise nach, bevor es sich festlegt:

if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
end

Danach ist mouseGetPosition(1) die zweite Lightgun, und das Argument device von onInputPressed sagt, welche Lightgun geschossen hat. Behalte zwei Fadenkreuze, zwei Punktestände und eine Liste von Zielen, und du hast ein kooperatives Spiel.

Die zweite Änderung steht gar nicht in deinem Skript. Die mitgelieferte controls.cfg belegt nur die Tasten der ersten Maus, also kommt der Abzug der zweiten Lightgun nirgends an. Ein Automat mit zwei Lightguns braucht in dieser Datei eine eigene Zeile, die beide nennt:

INPUT_ACTION_3 = { SCANCODE.LSHIFT, GAMEPAD_0.BUTTON_X, MOUSE_0.BUTTON_LEFT, MOUSE_1.BUTTON_LEFT }

Schreib das in deine Anleitung. Ein Spieler, dessen zweite Lightgun nichts tut, gibt deinem Spiel die Schuld, und damit hat er halb recht.

Die andere Art, einen Treffer zu prüfen

Es gibt eine zweite Art, die Frage „Hat dieser Schuss etwas getroffen?“ zu beantworten, und es lohnt sich, von ihr zu wissen, auch wenn du sie heute nicht benutzt. vldpGetPixel(x, y) liest die Farbe eines Pixels des Video-Frames, der gerade auf dem Bildschirm ist. Spiele benutzen das seit der allerersten Version von Singe: Mal jedes Ziel im Material in einer Farbe an, die sonst nirgends vorkommt, und frag beim Abdrücken, welche Farbe unter dem Fadenkreuz ist.

Das bringt dir Trefferformen, die der Handlung genau folgen, umsonst und ohne Rechtecke, die du anlegen musst. Es kostet dich Material, das du dafür vorbereiten musst, und einen Treffertest, den du weder sehen noch debuggen kannst. Der Eintrag zu vldpGetPixel in der Referenz hat die Einzelheiten. Rechtecke sind die richtige Voreinstellung; das hier behältst du in der Hinterhand.

Was nur einen Automaten kümmert

Alles oben funktioniert auf deinem Schreibtisch. Einige Dinge gibt es auf deinem Schreibtisch überhaupt nicht, und jetzt ist ein guter Moment, sie zu nennen, damit sie dich später nicht überraschen.

Kalibrierung. Einer echten Lightgun muss man sagen, wo der Bildschirm ist, denn sie ist eine Kamera, die von da, wo der Spieler gerade steht, auf einen Monitor schaut. Die Service-Tools von Singe haben einen Bildschirm Light Gun, der Ziele in die Mitte und in jede Ecke setzt und markiert, wohin die Lightgun tatsächlich gezielt hat, also siehst du, in welche Richtung sie danebenliegt. Dein Spiel kalibriert nicht und sollte es auch nicht versuchen.

Der Sinden-Rahmen. Eine beliebte Familie von Lightguns findet den Bildschirm, indem sie nach einem hellen Rahmen sucht, der um das Bild gezeichnet ist. --sindengun zeichnet diesen Rahmen, und die Engine rechnet die Positionen zurück in das kleinere Bild darin, also bekommt dein Spiel weiterhin Koordinaten, die das bedeuten, was sie vorher bedeutet haben.

Bildschirme, die nicht die Form des Films haben. ratioGetX() und ratioGetY() geben dir die Zahlen, die ein Spieler auf der Befehlszeile angegeben hat, für einen Bildschirm, dessen Proportionen nicht zum Material passen. Singe wendet sie nicht an; ein Spiel, das sie haben will, rechnet selbst.

Lightguns, die verschwinden. SWITCH_MOUSE_DISCONNECT kommt bei onInputPressed an, wenn eine Lightgun ausgesteckt wird. Kein Knopf erzeugt es; die Engine löst es aus. Ein Spiel, das darauf achtet, kann „PLAYER 2 GUN DISCONNECTED“ auf den Bildschirm schreiben, statt so auszusehen, als sei es abgestürzt.

Gar keine Maus. Ein Automat mit einem Joystick und ohne Zeigegerät kann den Mauszeiger mit dem Stick steuern, und das schaltet joyMouseEnable ein.

Nichts davon ändert das Spiel, das du geschrieben hast. Das alles ist Lektion einunddreißig.

Probier es aus

  1. Verschieb ein Ziel. Ändere das x des dritten Ziels in 680 und starte es. Der größte Teil davon hängt jetzt über den rechten Rand hinaus, denn das Overlay ist 720 breit und das Ziel 96. Den schmalen Streifen, der übrig ist, kannst du immer noch treffen. Entscheide, was an den Rändern passieren soll.

  2. Mach die Ziele leichter. Ändere TARGET_SIZE in 140. Achte darauf, dass sich das Zeichnen und der Treffertest beide ändern und dass du nur eine Zahl geändert hast. Dafür ist eine benannte Konstante da.

  3. Zähl die Treffsicherheit. Füg eine Zeile hinzu, die hits als Prozentsatz von shots ausgibt. Sichere dich gegen das Teilen durch null vor dem ersten Schuss ab und finde heraus, was Lua ausgibt, wenn du es nicht tust.

  4. Lass ein Ziel dich bestrafen. Füg einem Datensatz ein Feld penalty = true hinzu und zieh Punkte ab, wenn es getroffen wird. Achte darauf, dass du einem Datensatz ein Feld hinzufügst, nicht allen vieren, und dass die ohne das Feld dort nil haben.

  5. Nimm das return heraus aus der Schleife in onInputPressed und lass dann zwei Ziele sich überlappen, indem du ihnen dieselben Frames und fast dieselbe Position gibst. Ein Schuss erwischt jetzt beide. Entscheide, welches Verhalten dein Spiel will.

Mach es absichtlich kaputt

Ändere den Schusstest so, dass er SWITCH_BUTTON1 statt SWITCH_BUTTON3 benutzt, und starte es. Nichts geht kaputt. Kein Fehler erscheint. Die linke Taste tut nichts mehr, und jetzt schießt die rechte.

Das ist die schlimmste Art von Bug und die häufigste in Eingabecode: Das Programm ist nicht falsch, es ist nur mit dem falschen Ding verdrahtet. Es gibt keine Fehlermeldung zu lesen, denn du hast eine vernünftige Frage zu einem Schalter gestellt, den es gibt, und er hat ehrlich geantwortet.

Zwei Dinge finden ihn. Das erste ist debugPrint aus Lektion acht:

function onInputPressed(what, device)
    debugPrint("switch " .. what .. " from device " .. tostring(device))

Jetzt gibt jeder Druck eine Zeile aus, und du siehst, was der Abzug wirklich schickt. Beachte tostring(device): device ist bei einem Tastendruck nil, und nil mit .. an einen String zu hängen ist ein Fehler. tostring macht daraus das Wort nil, und die Zeile wird ausgegeben.

Das zweite ist der eigene Input Test der Engine in den Service-Tools, der jedes Gerät zeigt, das sie sieht, und den letzten Schalter, den das Spiel bekommen hätte. Wenn ein Knopf nichts tut, sagt dir dieser Bildschirm, welche Hälfte des Problems du hast: Entweder kommt der Schalter an und dein Spiel ignoriert ihn, oder er kommt gar nicht an.

Was du gelernt hast

  • Eine Lightgun meldet sich als Maus, also funktioniert ein Spiel, das für die Maus geschrieben ist, mit einer Lightgun.

  • mouseGetPosition(device) gibt zwei Werte zurück, die Position des Zeigers in Overlay-Koordinaten.

  • Eine Funktion in Lua kann mehr als einen Wert zurückgeben, und du fängst sie auf, indem du genauso viele Namen aufschreibst.

  • singeWantsCrosshairs() sagt, ob du dein eigenes Fadenkreuz zeichnen sollst. Lies es einmal aus.

  • Singe fängt den Mauszeiger des Systems beim Start ein und versteckt ihn; das musst du nicht tun.

  • onInputPressed bekommt ein zweites Argument, das nennt, welche Maus oder Lightgun geschossen hat, und nil, wenn es eine Taste oder ein Gamepad war.

  • Ein Treffertest gegen ein Rechteck ist collidePointRect, dieselbe Kollision, die du in Lektion elf gelernt hast.

  • Das Frame-Fenster eines Ziels ist nur zwei Felder mehr in seinem Datensatz.

  • a or b gibt dir b, wenn a nil ist.

  • Kalibrierung, der Sinden-Rahmen und die Verdrahtung für zwei Lightguns liegen außerhalb deines Skripts.

Beim nächsten Mal

Deine Schießbude verlangt eine Sache: triff das, dort. Die andere Arcade-Konvention, auf der Videospiele aufbauen, verlangt etwas Schwierigeres — drück das, jetzt, und du hast eine halbe Sekunde. Lektion achtzehn baut ein Quick-Time-Event, mit einer Aufforderung, einem Zeitfenster, das in Frames gemessen wird, und drei verschiedenen Enden, je nachdem, ob du richtig, falsch oder zu langsam warst.

Lektion 18: Quick-Time-Events

Die fertige Lektion

Eine Aufforderung erscheint. Du hast eine halbe Sekunde. Drück das Richtige, und die Geschichte geht weiter; drück das Falsche oder gar nichts, und sie geht woandershin.

Das ist schon die ganze Idee, und erstaunlich viele Videospiele bestehen aus fast nichts anderem. Jedes Teil hast du schon: Lektion vierzehn hat dir Frames gegeben, Lektion sechs eine Liste von Datensätzen, Lektion drei Eingaben und Lektion sechzehn Verzweigungen. Diese Lektion setzt sie zusammen und fügt eine Sache hinzu, die wirklich neu ist — ein Zeitfenster und das, was passiert, wenn es sich schließt.

Die Uhr ist der Film

Alles hier wird in Frames gemessen, nicht in Sekunden, und dabei lohnt es sich anzuhalten, denn das ist die eine Entscheidung, die das Ganze funktionieren lässt.

Lektion vierzehn hat gesagt, dass ein Frame die Adresse eines Augenblicks im Film ist. Die Aufforderung muss erscheinen, wenn der Schauspieler zum Schlag ausholt, und das Zeitfenster muss sich schließen, wenn die Faust ankommt. Das sind keine Zeiten, das sind Stellen im Material, und du hast sie gefunden, indem du Schritt für Schritt hindurchgegangen bist. Wenn du das Zeitfenster in Sekunden schreibst, musst du eine Stoppuhr starten, wenn die Aufforderung erscheint, und dann können die beiden Uhren — deine und die des Films — auseinanderlaufen. Wenn das Video auf einem langsamen Rechner ruckelt, läuft deine Stoppuhr weiter, und der Spieler wird für seine Hardware bestraft.

Frames können nicht auseinanderlaufen, denn es gibt nur eine Uhr. discGetFrame() ist die Zeit, immer. Ein Zeitfenster sind zwei Frame-Nummern, und „wie viel ist noch übrig“ ist eine Subtraktion.

Starte mit demselben Video wie vorher:

Singe -R -v Singe/menuBackground.mkv moves

Immer noch das lila Gitter und der Sonnenuntergang. Stell dir einen Kampf vor.

Eine Aktion ist ein Datensatz

Hier ist die Tabelle, an der die ganze Lektion hängt:

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

Vier Aktionen. Jede sagt, wann das Zeitfenster aufgeht, wann es sich schließt, welcher Schalter die Antwort ist und was auf den Bildschirm kommt. Fünfundvierzig Frames sind bei der Bildrate dieses Videos etwa anderthalb Sekunden, und das ist großzügig; echte Spiele geben dir oft weniger als die Hälfte davon.

Alles, was eine Aktion zu einer Aktion macht, steht in dieser Tabelle. Nirgends weiter unten gibt es Code, der weiß, dass es vier Aktionen gibt oder dass die zweite nach oben geht oder dass das erste Zeitfenster bei Frame sechzig aufgeht. Eine fünfte Aktion hinzuzufügen heißt, eine Zeile hinzuzufügen. Alle Aktionen neu zu timen heißt, Zahlen zu ändern. Niemand muss eine Funktion lesen, um den Kampf zu ändern.

Das ist kein Trick nur für diese Lektion. Das ist der Unterschied zwischen einem Spiel, das du feinabstimmen kannst, und einem, bei dem du es nicht kannst, und es kostet nichts, es von Anfang an so zu machen. Wenn du merkst, dass du gerade zum vierten Mal if frame == 60 then schreiben willst, hör auf und mach stattdessen eine Tabelle.

Was wann passiert

Mit einer Aktion können drei Dinge passieren, und das sind drei verschiedene Ausgänge, nicht zwei:

  • Der Spieler drückt innerhalb des Zeitfensters den richtigen Schalter. Gib Punkte und spiel weiter.

  • Der Spieler drückt innerhalb des Zeitfensters einen falschen Schalter. Er hat es versucht und ist gescheitert.

  • Das Zeitfenster schließt sich ganz ohne Antwort. Er ist erstarrt.

Fauler Code behandelt die letzten beiden gleich. Spiele tun das fast nie, denn sie fühlen sich beim Spielen völlig verschieden an: Falsch zu raten ist ein Fehler, und zu erstarren ist ein anderer Fehler, und der Film geht meistens für jeden woandershin. Hier schickt die falsche Antwort die Disc zu Frame 362 und keine Antwort zu Frame 388, und bei diesem Material heißt das zwei etwas verschiedene Mengen Sonnenuntergang. Bei echtem Material wären es zwei verschiedene Einstellungen davon, wie du verlierst.

Also bekommt jeder Datensatz während des Durchgangs ein fünftes Feld — answer — mit dem Wert nil, bis mit der Aktion etwas passiert, und dann einem von drei Strings:

move.answer = "right"
move.answer = "wrong"
move.answer = "late"

nil ist der Wert, den Lua dir für ein Feld gibt, das niemand gesetzt hat. Du hast ihn in Lektion drei kennengelernt. Hier verdient er sich seinen Platz: „noch keine Antwort“ ist wirklich ein anderer Zustand als jede der drei Antworten, und nil sagt das, ohne dass du dir ein Wort dafür ausdenken musst.

Die Aktion finden, nach der gerade gefragt wird

Alles andere muss eine Sache wissen: Welche Aktion ist gerade offen, wenn überhaupt eine?

local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end

Geh die Liste durch und antworte mit der ersten Aktion, deren Zeitfenster diesen Frame abdeckt und die noch nicht beantwortet ist. Passt nichts, antworte mit nil.

Dass hier absichtlich nil zurückgegeben wird, ist bemerkenswert. Eine Funktion, die manchmal keine Antwort hat, sollte das sagen, und „keine Aktion ist offen“ ist eine völlig gute Antwort. Der Aufrufer schreibt dann if move ~= nil then, und der Code, der die Aufforderung zeichnet, läuft nie, wenn es nichts zum Auffordern gibt.

Der Test move.answer == nil verhindert, dass nach einer Aktion zweimal gefragt wird. In dem Moment, in dem der Spieler sie richtig hat, verschwindet die Aufforderung, auch wenn das Zeitfenster noch offen ist — und genau das soll sie tun, denn er hat ja geantwortet.

Die Antwort lesen

function onInputPressed(what)
    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end

Lies es von oben nach unten. Wenn der Schalter keine der vier Richtungen ist, geht er uns nichts an — raus. Wenn keine Aktion offen ist, bedeutet ein Druck auf eine Richtung nichts — raus. Sonst gibt es genau eine Aktion, mit der verglichen wird, und einen Vergleich, den es zu machen gilt.

Diese beiden frühen return-Zeilen sind Wächter: Sie werfen die Fälle hinaus, die dich nicht interessieren, damit der Code darunter immer nur in der einen Situation läuft, für die er geschrieben wurde. Andersherum geschrieben, mit der eigentlichen Arbeit drei Ebenen tief in drei if-Blöcken verschachtelt, sagt es dasselbe und ist viel schwerer zu lesen.

isDirection ist eine winzige Funktion, die nichts anderes tut, als die erste Zeile kurz zu halten:

local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end

Achte darauf, dass sie den Vergleich selbst zurückgibt, statt if …​ then return true else return false end zu sagen. Ein Vergleich ist schon true oder false. Zu prüfen, ob etwas wahr ist, nur um dann zu sagen, dass es wahr ist, ist eine Gewohnheit, die man früh ablegen sollte.

Das Zeitfenster schließt sich

Niemand drückt etwas, und die Frames ziehen weiter vorbei. Irgendetwas muss das bemerken. Dieses Etwas ist onOverlayUpdate, denn es läuft in jedem Frame, ob der Spieler etwas tut oder nicht:

if not runOver then
    for _, move in ipairs(moves) do
        if move.answer == nil and frame > move.last then
            move.answer = "late"
            endRun("TOO SLOW", LATE_FRAME)
            break
        end
    end
end

Eine Aktion, die nicht beantwortet ist und deren letzter Frame schon vorbei ist, wurde verpasst. break verlässt die Schleife sofort, denn sobald der Durchgang vorbei ist, hat es keinen Sinn, sich den Rest anzusehen.

endRun ist die Verzweigung, und es ist dieselbe Verzweigung, die du in Lektion sechzehn geschrieben hast:

local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end

Drei Zeilen. Merk dir, was gesagt werden soll, merk dir, dass der Durchgang vorbei ist, und schick den Film woandershin. Ein verpasstes Quick-Time-Event ist kein besonderer Mechanismus. Es ist eine Entscheidung, die der Spieler getroffen hat, indem er keine getroffen hat, und der Film verzweigt darauf genau so, wie er bei einer Tür verzweigt, die der Spieler gewählt hat.

Eine Anzeige, die sich leert

Der Spieler kann keine Frame-Nummern sehen. Er muss sehen, wie die Zeit abläuft, und er muss es sehen, ohne von der Action wegzuschauen, und das heißt: eine Form, die sich ändert, statt einer Zahl, die zählt.

Zwei Zahlen geben dir alles:

local left = move.last - frame
local span = move.last - move.first

span ist, wie lang das Zeitfenster ist. left ist, wie viel davon noch übrig ist. Der Balken ist left von span der vollen Breite:

fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)

// ist eine Division, die den Nachkommateil wegwirft, und das willst du hier, denn einen Balken, der hundertdreiunddreißig und ein Drittel Pixel breit ist, gibt es nicht. Multiplizier, bevor du teilst: GAUGE_W * left // span und nicht GAUGE_W * (left // span). Sonst wird der Nachkommateil weggeworfen, solange er noch die einzige Information ist, die du hast, und der Balken springt zwischen voll und leer hin und her, ohne irgendetwas dazwischen.

Ein gefülltes Rechteck gibt es im Overlay nicht. overlayBox zeichnet einen Umriss, und den willst du für den Rahmen um die Anzeige, und die Füllung machst du selbst:

local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end

Achtzehn waagerechte Linien, übereinandergestapelt. Der Wächter oben ist wichtig: Im allerletzten Frame des Zeitfensters ist left null, die Breite ist null, und ohne ihn ist x + width - 1 ein Pixel links von x, und du zeichnest eine kurze Linie rückwärts statt gar nichts.

Der letzte Schliff ist ein Farbwechsel, wenn es eng wird:

if left * 3 < span then
    colorForeground(255, 60, 60, 255)
else
    colorForeground(255, 200, 0, 255)
end

Im letzten Drittel wird der Balken rot. So geschrieben — die übrige Zeit multiplizieren, statt die Spanne zu teilen — bleibt alles bei ganzen Zahlen und funktioniert für ein Zeitfenster jeder Länge.

Das Ganze

-- Programmieren lernen mit Singe -- Lektion 18: Quick-Time-Events

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local WRONG_FRAME = 362
local LATE_FRAME  = 388
local LAST_FRAME  = 415

local PROMPT_COL  = 54
local PROMPT_ROW  = 22
local GAUGE_X     = 210
local GAUGE_Y     = 330
local GAUGE_W     = 300
local GAUGE_H     = 18

local RIGHT_SCORE = 100

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

local score   = 0
local runOver = false
local verdict = ""


local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end


local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end


local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end


local function startRun()
    score   = 0
    runOver = false
    verdict = ""
    for _, move in ipairs(moves) do
        move.answer = nil
    end
    discSkipToFrame(FIRST_FRAME)
end


local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end


function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if not runOver then
        for _, move in ipairs(moves) do
            if move.answer == nil and frame > move.last then
                move.answer = "late"
                endRun("TOO SLOW", LATE_FRAME)
                break
            end
        end
    end

    if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then
        if not runOver then
            verdict = "CLEAR"
            runOver = true
        end
        discSearch(LAST_FRAME)
    end

    overlayClear()

    local move = nil
    if not runOver then
        move = moveAt(frame)
    end

    if move ~= nil then
        local left = move.last - frame
        local span = move.last - move.first

        overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

        colorForeground(255, 255, 255, 255)
        overlayBox(GAUGE_X - 2, GAUGE_Y - 2, GAUGE_X + GAUGE_W + 1, GAUGE_Y + GAUGE_H + 1)

        if left * 3 < span then
            colorForeground(255, 60, 60, 255)
        else
            colorForeground(255, 200, 0, 255)
        end
        fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   FRAME " .. frame)

    if runOver then
        overlayPrint(2, 3, verdict)
        overlayPrint(2, 4, "PRESS 1 TO RUN IT AGAIN")
    end

    return OVERLAY_UPDATED
end


startRun()

Die Pfeiltasten beantworten die Aufforderungen. Schaff alle vier, und der Film läuft bis zum Ende und bleibt dort bei CLEAR stehen. Mach eine falsch oder setz dich auf deine Hände, und er springt zu einem anderen Frame, mit einem anderen Wort auf dem Bildschirm. Mit 1 geht es noch einmal los.

Was gerade passiert ist

Das meiste hast du schon gelesen. Vier Stücke sind einen zweiten Blick wert.

if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then

Das Ende des Films muss abgefangen werden, sonst läuft er über das Ende hinaus, und es gibt nichts mehr zu sehen. discSearch geht zu einem Frame und pausiert dort, und genau das will eine letzte Einstellung. Die Hälfte mit discGetState() verhindert, dass das in jedem der folgenden Frames wieder passiert: Sobald die Disc pausiert ist, ist sie nicht mehr DISC_PLAYING, also ist die Bedingung falsch, und der Sprung wird nicht sechzigmal pro Sekunde wiederholt. discGetState und die Konstanten DISC_* stehen in der Referenz unter discGetState.

local move = nil
if not runOver then
    move = moveAt(frame)
end

onOverlayUpdate fragt selbst noch einmal nach der offenen Aktion, statt es sich von onInputPressed sagen zu lassen. Das ist Absicht. Es gibt genau eine Funktion, die weiß, welche Aktion offen ist, und alle fragen sie. Käme die Aufforderung aus einer Variablen, die der Eingabecode auf dem neuesten Stand hält, dann würden sich zwei Stücke Code dieselbe Tatsache merken, und früher oder später läge eines davon falsch. Wenn du die Wahl zwischen Fragen und Merken hast, frag.

overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

overlayPrint zählt in Zeichenzellen, wie schon seit Lektion eins, also ist die Aufforderung nach Augenmaß platziert: Spalte vierundfünfzig liegt für Wörter dieser Länge nah genug an der Mitte. Nah genug, nicht richtig, und „PRESS RIGHT“ endet drei Zeichen weiter rechts als „PRESS UP“. Lektion neunzehn lädt eine echte Schriftart und mit ihr die Möglichkeit, einen String in Pixeln auszumessen und richtig zu zentrieren.

function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

Ein Callback, zwei völlig verschiedene Aufgaben, ausgewählt durch runOver. Während der Durchgang läuft, bedeuten die Richtungen Aktionen; sobald er vorbei ist, bedeutet nur noch die Starttaste etwas. Eine Variable, die entscheidet, welche Regeln gelten, ist ein Zustand, und so hat Lektion zwölf das auch genannt, und ein Spiel besteht zum größten Teil aus einer kleinen Zahl davon.

Probier es aus

  1. Mach es schwerer. Ändere das last der ersten Aktion von 105 in 75. Fünfzehn Frames sind eine halbe Sekunde. Spiel es und finde heraus, ob du das schaffst.

  2. Füg eine Aktion hinzu. Schreib eine fünfte Zeile in die Tabelle, mit einem Zeitfenster zwischen den Frames 370 und 400, und setz LAST_FRAME auf 418 hoch. Keine andere Zeile solltest du anfassen müssen. Wenn doch, weiß irgendetwas im Code zu viel über die Tabelle.

  3. Bewerte die Geschwindigkeit. Gib mehr Punkte für frühes Antworten. Rechne in onInputPressed, dort, wo die richtige Antwort Punkte bekommt, left und span aus move und discGetFrame() so aus wie die Anzeige, und addiere RIGHT_SCORE * left // span statt RIGHT_SCORE. Entscheide, ob das Spiel dadurch besser wird oder nur hektischer.

  4. Gib einer falschen Antwort ihre eigene Folge. Statt den Durchgang zu beenden, lass einen falschen Druck fünfzig Punkte kosten und das Zeitfenster für einen neuen Versuch offen. Du musst aufhören, move.answer zu setzen, und dabei begegnest du dem Grund, warum es überhaupt gesetzt wurde.

  5. Zwei Aufforderungen auf einmal. Lass die Zeitfenster zweier Aktionen sich überlappen und sieh, was passiert. moveAt gibt den ersten Treffer zurück, also wird immer nur nach einer gefragt. Entscheide, was du willst und was es dafür bräuchte.

Mach es absichtlich kaputt

Lösch das break aus der Schleife, die verpasste Aktionen findet, und verpass die erste mit Absicht. Der Durchgang endet, die Disc springt, und alles sieht richtig aus.

Setz jetzt debugPrint(move.name .. " missed") neben move.answer = "late" und mach es noch einmal. Die Konsole zeigt eine Zeile, wie zu erwarten.

Dann nimm auch noch das if not runOver then um die Schleife heraus und verpass wieder die erste Aktion:

LEFT missed
UP missed
RIGHT missed
DOWN missed

Die erste Zeile kommt, wenn sich das Zeitfenster schließt, wie vorher. Die anderen drei kommen zusammen im allernächsten Frame, in dem Augenblick, in dem die Disc bei 388 landet: Jedes übrige Zeitfenster liegt jetzt in der Vergangenheit, also wird jede unbeantwortete Aktion auf einmal verpasst, und jede ruft endRun auf und springt noch einmal. Das Spiel funktioniert immer noch mehr oder weniger, und genau das macht es gefährlich. Drei zusätzliche Sprünge in einem einzigen Frame, dreimal wird das Urteil überschrieben, und nichts auf dem Bildschirm sagt es dir.

Auch hier gibt es keine Fehlermeldung. Die Lehre ist, dass dieses break und dieser Wächter keine Ordnungsliebe sind. Sie sind die zwei Zeilen, die sagen „das ist schon entschieden“, und Code, der etwas immer wieder entscheidet, das schon entschieden ist, ist eine der zuverlässigsten Quellen von Bugs, die du je schreiben wirst.

Was du gelernt hast

  • Ein Quick-Time-Event ist eine Aufforderung, ein Zeitfenster und eine Folge.

  • Miss das Zeitfenster in Frames, denn der Film ist die Uhr, und es darf immer nur eine Uhr geben.

  • Halte die Aktionen in einer Tabelle von Datensätzen, damit eine Aktion hinzuzufügen heißt, eine Zeile hinzuzufügen.

  • Richtig, falsch und keine Antwort sind drei Ausgänge, und sie führen meistens an drei verschiedene Orte.

  • nil in einem Feld eines Datensatzes ist ein echter Zustand: Noch hat niemand geantwortet.

  • Eine Funktion beantwortet „Welche Aktion ist offen?“, und alle fragen sie, statt eine Kopie aufzuheben.

  • Wächter — ein frühes return für die Fälle, die dich nicht interessieren — halten die eigentliche Arbeit unverschachtelt.

  • // teilt und wirft den Nachkommateil weg; multiplizier, bevor du teilst.

  • overlayBox zeichnet einen Umriss, also ist ein gefüllter Balken ein Stapel von overlayLine-Aufrufen.

  • Eine verpasste Aktion ist eine Verzweigung, und discSkipToFrame nimmt sie, genau wie in Lektion sechzehn.

Beim nächsten Mal

Teil drei ist fertig. Du kannst Film abspielen, auf ihn warten, an ihm verzweigen, auf ihn zielen und den Spieler gegen ihn antreten lassen. Was du über all das geschrieben hast, ist die Konsolenschrift der Engine, die sechs Pixel breit ist und für Diagnosen gedacht. In Lektion neunzehn lädst du eine echte Schrift, misst sie aus und sorgst dafür, dass die Wörter auf dem Bildschirm so aussehen, als gehörten sie zum Spiel.

Lektion 19: Text, der gut aussieht

Die fertige Lektion

Jedes Wort, das du seit Lektion eins auf den Bildschirm gebracht hast, kam aus overlayPrint, und overlayPrint hat genau eine Schriftart: einen Pixelblock fester Breite, der in die Engine eingebaut ist, für immer gleich groß, in welcher Farbe er gerade eben ist. Für einen Frame-Zähler ist sie perfekt. Für einen Titel, eine Punktzahl, ein Menü oder alles, was ein Spieler ansehen und nicht einfach überlesen soll, ist sie falsch.

Diese Lektion lädt eine echte Schriftart von der Festplatte, gibt Text mit ihr aus, färbt ihn ein, misst ihn aus, damit du Dinge zentrieren kannst, und zeigt dir, was das Ausgeben von Text wirklich kostet. Am Ende hast du einen Titelbildschirm, der gewollt aussieht statt zufällig.

Gib dem Overlay eine Größe, in der du denken kannst

Fang eine neue Datei namens text.singe mit zwei Zeilen an:

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

Die erste Zeile hast du schon oft geschrieben; sie lädt das Framework, das DIR, die Namen SWITCH_* und die Namen FONT_QUALITY_* definiert, die du gleich benutzt.

Die zweite ist wichtiger, als sie aussieht. Das Overlay — die Fläche, auf der alles landet, was du zeichnest — ist am Anfang halb so groß wie die Welt. Ein Spiel ohne Video hat eine Zeichenfläche von 720 mal 480, also ist das Overlay am Anfang 360 mal 240 groß, und eine Schrift in 36 Punkt ist auf einem Overlay, das 360 Pixel breit ist, riesig. overlaySetResolution ersetzt das Overlay durch eines in der Größe, um die du bittest, und von da an liegt jede Koordinate, die du angibst, und alles, was overlayGetWidth und overlayGetHeight dir sagen, in diesem Raum.

discGetWidth() und discGetHeight() antworten mit der Größe des Videos, wenn es eines gibt, und mit der Größe der Zeichenfläche, wenn nicht, also bekommst du mit dieser einen Zeile ein Overlay, das zur Welt passt, egal welche Art von Spiel das hier ist. Ruf es einmal auf, am Anfang, bevor du irgendetwas zeichnest.

Lade eine Schriftart

Schreib darunter:

fontQuality(FONT_QUALITY_BLENDED)

local titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)

fontLoad öffnet eine TrueType-Schriftdatei und gibt dir eine Zahl zurück — ein Handle — und die benutzt du immer, wenn du diese Schriftart willst. Das zweite Argument ist die Punktgröße, und die steht fest, solange es das Handle gibt. Es gibt keine Möglichkeit, die Größe einer geladenen Schriftart nachträglich zu ändern. Wenn du dieselbe Schrift in drei Größen willst, rufst du fontLoad dreimal auf und behältst drei Handles.

Singe/FreeSansBold.ttf ist die Schriftart, die die Engine in den Ordner Singe in deinem Arbeitsordner entpackt hat, als du zum ersten Mal irgendetwas gestartet hast. Jede Kopie von Singe hat sie, also kannst du dich auf sie verlassen. Jede andere .ttf-Datei funktioniert genauso; leg sie neben dein Skript und lade sie als DIR .. "myfont.ttf".

Gib jetzt Text mit ihr aus:

function onOverlayUpdate()
    overlayClear()
    fontPrint(24, 60, "ASTEROID PATROL")
    return OVERLAY_UPDATED
end

Starte es. Große weiße Buchstaben oben links.

Achte darauf, was du nicht getan hast: Du hast fontPrint nie gesagt, welche Schriftart es benutzen soll. fontLoad macht die Schriftart, die es gerade geladen hat, zur ausgewählten, und fontPrint zeichnet immer mit der, die gerade ausgewählt ist. Wenn mehr als eine Schriftart geladen ist, wählst du mit fontSelect zwischen ihnen, und das machst du gleich.

Achte auch darauf, dass 24 und 60 Pixel sind, keine Zeichenzellen. Das ist der Unterschied zwischen fontPrint und overlayPrint, über den die Leute stolpern: overlayPrint(2, 2, …​) heißt zwei Buchstaben nach rechts und zwei Zeilen nach unten, fontPrint(2, 2, …​) dagegen zwei Pixel nach rechts und zwei Pixel nach unten, also eingequetscht in die Ecke. Das y, das du angibst, ist die Oberkante des Texts, nicht die Grundlinie, auf der er steht.

Farbe

fontPrint nimmt drei Argumente, und keines davon ist eine Farbe. Die Farbe kommt von woanders:

    colorForeground(255, 211, 90)
    fontPrint(24, 60, "ASTEROID PATROL")

colorForeground setzt Rot, Grün und Blau von 0 bis 255 und, wenn du willst, eine vierte Zahl für die Deckkraft. Es ist kein Argument für irgendetwas; es ist eine Einstellung, die sich die Engine merkt. Alles, was danach gezeichnet wird, kommt in dieser Farbe heraus, bis du sie wieder änderst, genau so, wie overlayBox und overlayLine schon funktionieren. Das Muster ist also immer dasselbe: Setz die Farbe, dann zeichne.

Das ist das Erste, was die Leute bei Schriftarten falsch machen, und das Zweite kommt in ein paar Seiten.

Qualität

fontQuality entscheidet, wie die Buchstaben gerastert werden, also wie die Kurven eines Buchstabens zu Pixeln werden. Es gibt drei Möglichkeiten. Probier jede aus, indem du sie über die Zeile mit fontLoad setzt und dir das Ergebnis genau ansiehst.

FONT_QUALITY_SOLID ist die schnellste. Jedes Pixel gehört entweder zum Buchstaben oder nicht, also kommen die Diagonalen und Kurven mit sichtbaren Treppenstufen heraus. Bei 48 Punkt sieht das billig aus. Bei 12 Punkt auf einem kleinen Overlay kann es schärfer aussehen als die anderen, und manchmal willst du genau das.

FONT_QUALITY_SHADED glättet die Kanten, aber dazu mischt es sie mit der aktuellen Hintergrundfarbe, und diesen Hintergrund zeichnet es als volles Rechteck hinter den ganzen String. Du bekommst ein Etikett mit einem Kasten drumherum, ob du einen wolltest oder nicht. Für ein Debug-Anzeigefeld über einem unruhigen Bild ist das die richtige Antwort und für fast alles andere die falsche.

FONT_QUALITY_BLENDED glättet die Kanten und lässt sie durchsichtig, also sitzen die Buchstaben auf dem, was gerade hinter ihnen ist. Sie kostet am meisten, und sie ist das, was du fast immer willst. Nimm sie, außer du hast einen Grund dagegen.

Die Einstellung ist global, nicht pro Schriftart, und sie gilt ab dem Moment, in dem du sie aufrufst. Sprites, die du schon gemacht hast, behalten die Qualität, mit der sie gemacht wurden. Der Eintrag zu fontQuality in der Referenz nennt die drei Namen und ihre Werte.

Ausmessen, damit du Dinge zentrieren kannst

Früher oder später — meistens nach etwa zehn Minuten — willst du den Titel in der Mitte des Bildschirms haben. Du weißt, dass der Bildschirm overlayGetWidth() breit ist. Du weißt nicht, wie breit der Text ist, und es gibt keinen Aufruf fontMeasure, den du fragen könntest.

Was es stattdessen gibt, ist fontToSprite. Es rendert einen String mit der ausgewählten Schriftart, der aktuellen Qualität und der aktuellen Farbe, und statt ihn auf den Bildschirm zu bringen, gibt es dir ein Sprite zurück: dieselbe Art von Handle, die dir spriteLoad gibt, und das heißt, jeder sprite*-Aufruf, den du in Lektion neun gelernt hast, funktioniert damit. Auch die beiden, die es ausmessen.

fontSelect(titleFont)
colorForeground(255, 211, 90)
local titleImage = fontToSprite("ASTEROID PATROL")

Und dann, in onOverlayUpdate:

    local x = (overlayGetWidth() - spriteGetWidth(titleImage)) / 2
    spriteDraw(titleImage, x, 60)

Das ist Zentrieren, und das ist schon der ganze Trick. Nimm die Breite des Platzes, zieh die Breite des Dings ab, und die Hälfte von dem, was übrig bleibt, ist der Abstand auf jeder Seite.

Rechtsbündig ist dieselbe Idee mit weniger Rechnerei. So setzt du Text an den rechten Rand:

    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), y)

spriteGetHeight misst die andere Richtung, um Zeilen zu stapeln oder senkrecht zu zentrieren.

In diesem ersten Codeblock steckt ein Haken, und das ist das Zweite, was alle falsch machen. Die Farbe wird eingebacken, wenn das Sprite gemacht wird, nicht wenn es gezeichnet wird. colorForeground über fontToSprite ändert den Text. Setzt du es stattdessen über spriteDraw, tut es überhaupt nichts, denn colorForeground ist eine Einstellung für das Zeichnen von Text und Linien, und ein Sprite wird mit seinen eigenen Pixeln gezeichnet. Wenn dein sorgfältig eingefärbter Titel weiß herauskommt, liegt es daran.

Ein Sprite lässt sich umfärben, nachdem es gemacht wurde, aber mit einem Sprite-Aufruf, nicht mit colorForeground. spriteSetTint(image, red, green, blue) multipliziert jedes Pixel des Sprites bei jedem Zeichnen mit dieser Farbe, also kann Text, der in Weiß gerendert wurde, heute gelb und morgen rot gezeichnet werden, ohne neu gemacht zu werden. Weiß ist die Farbe, in der du renderst, wenn du einfärben willst: Alles, was mit Weiß multipliziert wird, bleibt, was es war, also ist die Tönung genau die Farbe, um die du bittest.

Was Ausgeben kostet

Wenn fontPrint einen String zum ersten Mal sieht, leistet es echte Arbeit: Es rastert jeden Buchstaben aus den Umrissen der Schriftart und baut ein Bild des ganzen Strings. Dann behält es dieses Bild. Wenn du denselben String das nächste Mal ausgibst, mit derselben Schriftart, Qualität und denselben Farben, überspringt es all das und kopiert das Bild, das es schon hat, und das kostet ungefähr so viel wie das Zeichnen eines Sprites. Ein String, den du nicht mehr ausgibst, wird eine Sekunde später losgelassen, also häuft sich nichts an.

Das heißt, die naheliegende Art, einen Titelbildschirm zu schreiben, ist auch die schnelle. "ASTEROID PATROL" sechzigmal pro Sekunde auszugeben rendert ihn einmal. Eine Punktzahl, die sich zweimal pro Sekunde ändert, wird zweimal pro Sekunde gerendert, von selbst, ohne dass du Buch führen musst.

Der eine Fall, der etwas kostet, ist Text, der in jedem Frame anders ist (ein Timer in Millisekunden, ein Frame-Zähler), denn jeder Frame ist ein String, den fontPrint noch nie gesehen hat. Auf einem Desktop-Rechner spielt das keine Rolle. Auf einem Raspberry Pi oder einem Handheld spielt ein Bildschirm voll davon sehr wohl eine. Die Abhilfe ist, den Text seltener zu ändern: Ein Timer in ganzen Sekunden ist einmal pro Sekunde ein neuer String, nicht sechzigmal.

Warum hat diese Lektion dann überhaupt fontToSprite benutzt? Weil ein Sprite Dinge kann, die ausgegebener Text nicht kann:

  • Es kann ausgemessen werden, und das ist die einzige Möglichkeit, Text zu zentrieren oder an der rechten Seite auszurichten.

  • Es kann skaliert und gedreht werden, mit den sprite*-Aufrufen aus Lektion neun.

  • Es kann seine Schriftart überleben, und das ist gleich wichtig.

Nimm fontPrint für Text und fontToSprite, wenn du eines davon brauchst.

Die Punktzahl in dieser Lektion braucht eines davon: Sie sitzt am rechten Rand, also muss sie ausgemessen werden, also muss sie ein Sprite sein. Und ein Sprite einer Punktzahl stimmt nur, bis sich die Punktzahl ändert. Wenn sie das tut, render ein neues Sprite und entlade das alte — vergisst du das, bleibt bei jeder Änderung ein Sprite als Leck zurück:

local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end

scoreShown merkt sich, welche Punktzahl dieses Sprite zeigt, damit der Zeichencode erkennen kann, ob es noch stimmt:

    if score ~= scoreShown then
        renderScore()
    end

string.format("%06d", score) ist reines Lua, nicht Singe. Es macht aus einer Zahl einen String, und %06d heißt „als ganze Zahl, mindestens sechs Stellen, mit Nullen aufgefüllt“, und darum haben Arcade-Punktzahlen führende Nullen. Ändere es in %d, und die Nullen verschwinden.

Schriftarten wegräumen

fontUnload schließt eine Schriftart und macht ihr Handle ungültig. Sprites, die du mit fontToSprite gemacht hast, sind davon nicht betroffen (ist ein Sprite einmal gerendert, hat es mit der Schriftart nichts mehr zu tun), also kannst du eine Schriftart entladen und weiter Text zeichnen, der aus ihr gemacht wurde.

Eine scharfe Kante: Wenn du die ausgewählte Schriftart entlädst, ist danach keine Schriftart ausgewählt, und das nächste fontPrint beendet dein Spiel mit einem Fehler. Wähl zuerst eine andere aus, wenn du weiter Text ausgeben willst.

Der ordentliche Platz für all das ist onShutdown, ein Callback, den die Engine einmal aufruft, wenn das Spiel beendet wird:

function onShutdown()
    spriteUnload(titleImage)
    fontUnload(titleFont)
end

Singe räumt hinter dir auf, wenn das Spiel endet, also fängt nichts Feuer, wenn du das weglässt. Schreib es trotzdem. Ein Spiel, das freigibt, was es geladen hat, ist ein Spiel, das du zweimal laden kannst.

Das ganze Skript

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local MARGIN  = 24
local TITLE_Y = 60
local SCORE_Y = 170
local LABEL_Y = 186
local HINT_Y  = 300
local CLOCK_Y = 430

local score      = 0
local titleFont  = nil
local scoreFont  = nil
local smallFont  = nil
local titleImage = nil
local hintImage  = nil
local scoreImage = nil
local scoreShown = nil


local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end


local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end


fontQuality(FONT_QUALITY_BLENDED)

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

fontSelect(titleFont)
colorForeground(255, 211, 90)
titleImage = fontToSprite("ASTEROID PATROL")

fontSelect(smallFont)
colorForeground(140, 200, 255)
hintImage = fontToSprite("Press the fire button to score")

renderScore()


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        score = score + 125
    end
end


function onOverlayUpdate()
    overlayClear()

    spriteDraw(titleImage, centered(titleImage), TITLE_Y)

    if score ~= scoreShown then
        renderScore()
    end
    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), SCORE_Y)

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")
    fontPrint(MARGIN, CLOCK_Y, "Running for " .. (singeGetTicks() // 1000) .. " seconds")

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(titleImage)
    spriteUnload(hintImage)
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontUnload(titleFont)
    fontUnload(scoreFont)
    fontUnload(smallFont)
end

Starte es und halt den Feuerknopf gedrückt. Der Titel und der Hinweis sitzen zentriert, die Punktzahl klettert am rechten Rand hoch und wird nur neu gerendert, wenn sie sich ändert, der Hinweis blinkt, und das Etikett und die Uhr werden in jedem Frame mit fontPrint ausgegeben — die Uhr in ganzen Sekunden, also ist sie nur einmal pro Sekunde ein neuer String.

Was gerade passiert ist

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

Eine Datei, drei Größen, drei Handles. Jedes kostet Speicher für seinen eigenen Satz gerenderter Glyphen, also lade die Größen, die du benutzt, und keine weiteren. Drei sind normal. Ein Dutzend riecht verdächtig.

Nach diesen drei Zeilen ist smallFont die ausgewählte Schriftart, denn Laden wählt aus. Darum ruft der Code fontSelect(titleFont) auf, bevor er den Titel rendert: Das zuletzt Geladene ist nicht das, was du zuerst willst.

local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end

Einmal als Funktion geschrieben, weil es zweimal benutzt wird und weil du es beim nächsten Mal, wenn du etwas zentriert haben willst, wieder brauchst. Gib der Rechnung einen Namen, und du musst sie nie wieder lesen.

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

singeGetTicks() ist die Zahl der Millisekunden seit dem Start der Engine. // ist eine Division, die den Rest wegwirft, also zählt singeGetTicks() // 500 halbe Sekunden, und % 2 ist der Rest nach dem Teilen durch zwei, also 0, 1, 0, 1 …​ Der Hinweis wird also eine halbe Sekunde lang gezeichnet und eine halbe Sekunde lang ausgelassen. Nichts zu zeichnen ist die Art, wie man etwas blinken lässt.

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")

Hier werden beide Einstellungen gebraucht, und es lohnt sich, klar zu sehen, warum. Ein Sprite zu zeichnen ändert weder die ausgewählte Schriftart noch die Farbe, also lassen die beiden spriteDraw-Aufrufe darüber beides genau so, wie sie es vorgefunden haben. Aber der Code am Anfang hat nacheinander drei verschiedene Schriftarten ausgewählt, und renderScore wählt jedes Mal eine weitere aus, wenn sich die Punktzahl bewegt, also ist die Auswahl, wenn diese Zeile läuft, die, die zufällig zuletzt gewählt wurde. Versuch nicht, darüber Buch zu führen. Wähl die Schriftart aus und setz die Farbe unmittelbar bevor du etwas ausgibst, jedes Mal. Das sind zwei Zeilen, und sie ersparen dir eine ganze Kategorie ratloser Abende.

Probier es aus

  1. Ändere die Qualität. Schreib FONT_QUALITY_SOLID in die Zeile mit fontQuality und sieh dir die Kurve des S in ASTEROID an. Dann probier FONT_QUALITY_SHADED und achte darauf, was hinter jedem String passiert.

  2. Mach den Hinweis gelb. Verschieb die Zeile colorForeground(140, 200, 255) von über fontToSprite direkt über das spriteDraw, das hintImage zeichnet, und ändere die Zahlen. Finde heraus, warum nichts passiert. Dann setz sie zurück, mach den Hinweis stattdessen weiß und färb ihn mit spriteSetTint gelb, direkt bevor er gezeichnet wird.

  3. Richte die Uhr rechtsbündig aus. Die Uhr wird mit fontPrint gezeichnet, und das lässt sich nicht ausmessen. Bring sie trotzdem an den rechten Rand. Es gibt nur einen Weg, und ihn zu finden ist der Sinn der Sache.

  4. Nimm die Prüfung von scoreShown heraus, sodass renderScore() stattdessen in jedem Frame läuft. Es sieht genauso aus, aber jetzt wird die Punktzahl sechzigmal pro Sekunde gerendert statt dann, wenn sie sich ändert — genau die Arbeit, die fontPrint dir erspart, wenn du es lässt. Dann nimm auch das spriteUnload in renderScore heraus, lass es eine Minute laufen und beobachte, wie viel Speicher dein Spiel benutzt.

  5. Gib eine Uhr in Millisekunden aus. Ändere die Zeile der Uhr so, dass sie singeGetTicks() ohne das // 1000 ausgibt. Es funktioniert immer noch; es ist jetzt in jedem Frame ein String, den fontPrint noch nie gesehen hat. Auf einem langsamen Rechner ist das die Art von Text, die etwas kostet.

  6. Nimm deine eigene Schriftart. Such dir eine .ttf auf deinem Rechner, kopier sie neben dein Skript und lade sie mit DIR .. "thatfont.ttf". Manche Schriftarten sehen bei 18 Punkt furchtbar aus und bei 48 gut. Das ist die Schuld der Schriftart, nicht deine.

Mach es absichtlich kaputt

Füg eine Zeile fontPrint(24, 60, "SCORE") direkt unter overlaySetResolution(discGetWidth(), discGetHeight()) ein, sodass sie läuft, bevor irgendein fontLoad gelaufen ist. Singe startet und stirbt sofort:

4:fontPrint:  No font selected.

Lies das wie jeden anderen Fehler. 4 ist die Zeile. fontPrint ist der Engine-Aufruf, der sich beschwert hat — Meldungen in dieser Form kommen aus dem Inneren der Engine und nicht von Lua, darum nennen sie die Funktion statt der Datei. Der Rest ist die Beschwerde, und hier ist sie genau: Du hast verlangt, etwas auszugeben, und es gab keine Schriftart, mit der das ging.

Diesem Fehler wirst du in echt auf eine weniger offensichtliche Art begegnen. Entlade die ausgewählte Schriftart, während das Spiel läuft, und das nächste fontPrint sagt genau dasselbe, mehrere hundert Zeilen entfernt von dem fontUnload, das es verursacht hat.

Was du gelernt hast

  • fontLoad öffnet eine TrueType-Datei in einer festen Punktgröße und gibt ein Handle zurück. Eine Größe, ein Handle.

  • Eine Schriftart zu laden wählt sie aus; fontSelect wählt zwischen geladenen Schriftarten.

  • fontPrint zählt in Pixeln und overlayPrint in Zeichenzellen.

  • Farbe ist kein Argument. colorForeground ist eine Einstellung; setz sie, dann zeichne.

  • fontQuality bestimmt, wie Buchstaben gerastert werden, und FONT_QUALITY_BLENDED ist die übliche Antwort.

  • fontPrint behält, was es rendert, also ist es billig, in jedem Frame denselben Text auszugeben; Text, der in jedem Frame anders ist, ist das, was kostet.

  • fontToSprite rendert in ein Sprite, das spriteGetWidth ausmisst und die sprite*-Aufrufe skalieren und drehen können. Nimm es dafür, nicht für Geschwindigkeit.

  • Ausmessen ist die Art, wie du Text zentrierst oder rechtsbündig ausrichtest, denn sonst kann dir nichts sagen, wie breit ein String wird.

  • colorForeground erreicht Text, wenn er gemacht wird, nie ein Sprite, wenn es gezeichnet wird; mit spriteSetTint färbst du ein Sprite nachträglich um.

  • fontUnload gibt eine Schriftart frei; die Sprites, die sie gemacht hat, überleben sie.

Beim nächsten Mal

Text, der gut aussieht, ist noch weit entfernt von einem Menü, das funktioniert. Eine Seite mit einem Titel, einer Liste, durch die du einen Cursor bewegst, einem Schieberegler und einem Knopf sind hundert Zeilen Zeichnen und Cursor-Rechnerei, wenn du sie aus den Aufrufen dieser Lektion baust. Lektion zwanzig baut sie überhaupt nicht aus diesen Aufrufen.

Lektion 20: Menüs und Bildschirme

Die fertige Lektion

Ein Menü kannst du aus dem bauen, was du schon kennst. Ein Kasten, etwas Text, ein Cursor, der sich bewegt, wenn sich der Stick bewegt, ein if für jede Auswahl und Rechnerei, damit alles in einer Reihe bleibt, wenn du eine vierte Option hinzufügst. Das funktioniert. Es sind aber auch rund hundert Zeilen für eine Seite mit drei Buttons darauf, und jede dieser Zeilen musst du pflegen.

Singe hat eine ganze Dokument-Engine eingebaut — RmlUi — und ein Menü, das dafür geschrieben ist, ist eine Seite, wie eine Webseite, mit einem Stylesheet. Sie bricht ihren Text selbst um. Sie ordnet sich selbst neu an, wenn du eine Option hinzufügst. Sie weiß, was ein Button ist, was ein Schieberegler ist und auf welches Bedienelement der Spieler gerade zeigt. Diese Lektion baut damit ein Pausenmenü, über einem Spiel, das dahinter weiterläuft.

Zwei Dateien

Eine GUI-Seite besteht aus zwei Dingen: einem Dokument, das sagt, was auf der Seite ist, und Lua, das sagt, was die Seite tut. Sie liegen in getrennten Dateien, und genau darum geht es bei der ganzen Übung — das Layout ist kein Code mehr.

Fang mit einem Skript namens menu.singe an und mit einem Spiel, das so klein ist, dass es in einen Absatz passt: ein Raumschiff, das über den Bildschirm fliegt, und eine Punktzahl, die jedes Mal steigt, wenn es auf der anderen Seite ankommt. So etwas schreibst du seit Lektion sieben.

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local ship  = spriteLoad(DIR .. "art/spaceship.png")
local shipX = 0
local speed = 2
local score = 0


function onOverlayUpdate()
    overlayClear()
    shipX = shipX + speed
    if shipX > overlayGetWidth() then
        shipX = -spriteGetWidth(ship)
        score = score + 10
    end
    spriteDraw(ship, shipX, 300)
    return OVERLAY_UPDATED
end

Das läuft. Jetzt das Dokument. Leg neben deinem Skript eine Datei namens pause.rml an:

<rml>
<head>
	<title>Pause</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		#frame { width: 380dp; margin: 80dp auto; }
		.row { display: block; margin: 8dp 0; }
		label { display: inline-block; width: 100dp; }
		button { nav: auto; }
		input.range { nav: auto; width: 200dp; }
		#status { min-height: 28dp; }
	</style>
</head>
<body id="pause">
	<div id="frame" class="panel">
		<h1>Paused</h1>
		<p class="row">Score <span id="score">000000</span></p>
		<div class="row"><label>Speed</label><input type="range" id="speed" min="1" max="8" step="1" value="2"/></div>
		<div class="row">
			<button id="resume" autofocus>Resume</button>
			<button id="restart">Restart</button>
			<button id="quit">Quit</button>
		</div>
		<p id="status" class="muted">Arrow keys move, Return chooses.</p>
	</div>
</body>
</rml>

Wenn du schon einmal den Quelltext einer Webseite gesehen hast, kommt dir das bekannt vor. Wenn nicht, hier ist alles, was du brauchst, um es zu lesen.

Ein Dokument besteht aus Elementen. Ein Element beginnt mit einem Namen in spitzen Klammern, <h1>, endet mit demselben Namen und einem Schrägstrich, </h1>, und was dazwischen steht, ist darin. Manche Elemente haben nichts darin und schließen sich selbst mit einem Schrägstrich am Ende, wie das <input …​/> oben. Elemente lassen sich ineinander verschachteln, und die Einrückung zeigt die Verschachtelung genauso, wie sie es in Lua tut.

Die Wörter im öffnenden Tag sind Attribute, geschrieben als name="value". Zwei davon sind für dich wichtiger als der Rest. id gibt einem Element einen Namen, über den dein Skript es finden kann, und so reden Lua und das Dokument miteinander. class steckt das Element in eine Gruppe, auf die das Stylesheet zielen kann; panel, muted und list sind Gruppen, die das eigene Stylesheet der Engine schon kennt.

Die Auszeichnungssprache heißt RML und die Stilsprache RCSS. Sie gehören zu RmlUi, nicht zu Singe. Das GUI-Kapitel der Referenz verweist für die vollständige Liste dessen, was du schreiben kannst, auf die eigene Dokumentation von RmlUi, und die wirst du irgendwann haben wollen. Alles in dieser Lektion funktioniert ohne sie.

Zeig sie an

Zurück ins Skript. Füg über onOverlayUpdate Folgendes ein:

local gui  = guiNew(overlayGetWidth(), overlayGetHeight())
local page = guiLoad(gui, DIR .. "pause.rml")

guiNew erzeugt eine GUI: ein Rechteck fester Größe, in das Dokumente gesetzt und gezeichnet werden. Es gibt ein Handle zurück, so wie fontLoad und spriteLoad. Wenn du sie so groß wie das Overlay machst, ist ein Pixel des Dokuments ein Pixel deines Overlays, und das hält die Rechnerei in deinem Kopf einfach.

guiLoad liest ein Dokument in diese GUI und gibt ein zweites Handle zurück, für das Dokument selbst. Fast jeder andere Aufruf nimmt beide: die GUI und das Dokument darin. Eine GUI kann bis zu zweiunddreißig Dokumente aufnehmen — eine Titelseite, eine Optionsseite und eine Game-Over-Seite können sich eine teilen — und es können bis zu sechzehn GUIs gleichzeitig existieren.

Noch ist nichts auf dem Bildschirm, denn ein Dokument zu laden zeichnet es nicht. Füg in onOverlayUpdate direkt vor dem return eine Zeile ein:

    guiDraw(gui)

Starte es. Das Panel ist da, über dem Raumschiff, mit seiner Überschrift, seinen drei Buttons und seinem Schieberegler, und du hast überhaupt keinen Zeichencode geschrieben.

guiDraw legt die GUI nur für diesen Frame über das Overlay, wie jeder andere Zeichenaufruf, also gehört es in onOverlayUpdate und muss im nächsten Frame wieder aufgerufen werden. Wo du es hinsetzt, entscheidet, was oben liegt: Alles, was du davor gezeichnet hast, liegt darunter, und alles, was du danach zeichnest, kommt darüber. Ein Fadenkreuz, das nach guiDraw gezeichnet wird, wird nie vom Menü verdeckt.

Lass den Spieler sie benutzen

Klick auf einen Button. Nichts passiert, und der Button leuchtet nicht einmal auf.

Eine neue GUI ist ein Bild, kein Bedienfeld. Das ist Absicht: Ein HUD oder ein Schild soll nicht den Feuerknopf verschlucken. So nimmt eine Seite Eingaben an:

guiSetInput(gui, true)

Jetzt funktioniert die Maus, die Buttons leuchten unter dem Zeiger auf, und die Pfeiltasten wechseln zwischen den Bedienelementen, weil das Dokument das mit nav: auto verlangt hat. Auf einem Gamepad oder einem Stick kommen die vier Richtungen als Pfeiltasten an, der erste Aktionsknopf als Eingabetaste und der zweite als Esc. Ein Automat mit einem Joystick und zwei Knöpfen bedient diese Seite, ohne zu wissen, dass sie ein Dokument ist.

Das Bedienelement, auf das die Tasten gerade wirken, hat den Fokus, und ein fokussierter Button trägt einen goldenen Rahmen. Der Fokus beginnt auf Resume, weil dieser Button autofocus sagt: Jedes Mal, wenn die Seite gezeigt wird, geht der Fokus an das so markierte Bedienelement. Lass es weg, und die Pfeiltasten haben nichts, von dem aus sie sich bewegen können, bis der Spieler etwas anklickt, und das passiert auf einem Automaten ohne Maus nie.

Klicken bewirkt aber immer noch nichts, weil niemand zuhört.

Sprich mit ihr

Drei Aufrufe verbinden das Dokument mit deinem Skript, und zusammen erledigen sie fast alles.

guiSetHandler(gui, page, "resume", "click", function()
    closeMenu()
end)

guiSetHandler sagt: Wenn das Element mit dieser id dieses Ding tut, ruf diese Funktion auf. Die id ist die aus dem Dokument. Der Name des Ereignisses ist einer von RmlUi: "click" für Buttons, "change" für alles, was der Spieler verstellt, und eine lange Liste weiterer, die du nachschlagen kannst, wenn du sie brauchst. Pro Element und pro Ereignis wird eine Funktion behalten, also ersetzt eine neue die alte, und nil statt einer Funktion entfernt sie.

Deine Funktion wird mit fünf Argumenten aufgerufen — der GUI, dem Dokument, der id, dem Ereignis und dem aktuellen Wert des Elements als String. Nimm so viele, wie du willst, und ignorier den Rest, so wie du in Lua sowieso schon Argumente ignorierst.

guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
    speed = math.floor(tonumber(value))
end)

Der Schieberegler übergibt seinen Wert als String, und RmlUi formatiert Zahlen auf seine eigene Art, also kommt 4 als "4.000000" an. tonumber macht aus dem String eine Zahl, und math.floor wirft die Nachkommastellen weg. Diesen Schritt auszulassen und den String als Zahl zu benutzen ist ein Fehler, den du genau einmal machst.

guiSetValue(gui, page, "score", string.format("%06d", score))

guiSetValue schreibt in ein Element. Bei einem Formularelement setzt es dessen Wert; bei allem anderen — einem Absatz, einem div, dem <span id="score"> in deinem Dokument — ersetzt es, was im Element steht, und die Seite ordnet sich im nächsten Frame neu an. guiGetValue ist derselbe Aufruf rückwärts, und es antwortet nil für eine id, die nichts hat, also kannst du nach einem Element fragen, das vielleicht nicht da ist, ohne abzustürzen.

Das ist die ganze Alltags-API: guiSetHandler, guiSetValue, guiGetValue. Über die eigenen Lua-Objekte von RmlUi, erreichbar über die globale Variable rmlui, gibt es noch viel mehr, und das GUI-Kapitel der Referenz zeigt, wie. Du kommst weit, bevor du das brauchst.

Versteck sie wieder

Ein Pausenmenü ist nicht die ganze Zeit zu sehen. guiHide nimmt ein Dokument vom Bildschirm, und guiShow holt es zurück, mit allem, was der Spieler getippt oder gewählt hat.

Die Pause selbst ist singeSetPauseFlag(true). Das hält die Disc, die Videos und die Sounds an, ruft aber deine Callbacks weiter auf, also kannst du weiter zeichnen. Die Engine hat ihre eigene Pausetaste, die das Skript komplett einfriert, und die beiden würden sich in die Quere kommen; singeSetPauseKeyEnabled(false) nimmt der Engine diese Taste weg, sodass SWITCH_PAUSE wie jeder andere Schalter bei onInputPressed ankommt. Auf einer Tastatur ist diese Taste P.

local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    guiHide(gui, page)
    guiSetInput(gui, false)
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    guiSetValue(gui, page, "score", string.format("%06d", score))
    guiShow(gui, page)
    guiSetInput(gui, true)
end

Die Eingabe zusammen mit der Seite abzuschalten ist keine Verzierung. Eine versteckte Seite, die noch Eingaben annimmt, frisst dem Spieler für den Rest des Spiels die Pfeiltasten.

Was die Seite nicht benutzt, bekommst du trotzdem

Das ist die Regel, durch die man eine GUI gefahrlos während des Spiels stehen lassen kann, und es lohnt sich, sie klar auszusprechen: Ein Ereignis, das ein Element benutzt hat, erreicht nie deine Callbacks. Eine Eingabetaste, die den fokussierten Button gedrückt hat, kommt nicht als onInputPressed an. Ein Pfeil, der den Fokus bewegt hat, kommt nicht als SWITCH_LEFT an. Ein Klick auf einen Button ist kein Mausschalter.

Alles, was die Seite nicht benutzt hat, fällt wie gewohnt direkt durch. Darum schließt P dieses Menü: Kein Element im Dokument benutzt P, also kommt die Taste genauso bei onInputPressed an wie dann, wenn das Menü weg ist. Und darum lässt ein HUD, das Eingaben annimmt, den Feuerknopf trotzdem durch.

Eine Taste hält sich nicht an die Regel. RmlUi benutzt Tab, um den Fokus zu bewegen, und gibt die Taste nie zurück, also gibt Singe Tab nur dann an eine GUI, wenn gerade wirklich in ein Textfeld getippt wird. Ein Spiel, das Tab mit etwas belegt, behält die Taste.

Gestalte sie

Sieh dir noch einmal den <head> des Dokuments an. Eine Zeile erledigt den größten Teil der Arbeit:

	<link type="text/rcss" href="Singe/gui.rcss"/>

Das ist das Theme, das die Engine mitliefert, und darum hat dein Panel einen Rahmen, einen Farbverlauf und eine goldene Überschrift, ohne dass du irgendetwas davon ausgesucht hast. Ohne Stylesheet zeichnet RmlUi fast nichts, weil jedes Element zuerst inline ist und so groß wie sein Inhalt. Dieses Theme zuerst einzubinden und zu überschreiben, was dir nicht gefällt, ist also der schnellste Weg zu einer Seite, die nach etwas aussieht.

Das Theme gibt dir .panel (einen gerahmten Kasten mit runden Ecken), .list (einen scrollenden Kasten, dessen div-Zeilen aufleuchten und den Fokus annehmen), .muted (blasseren Text für Hinweise), Überschriften und jedes Formularelement mit seinen Zuständen für Hover, Fokus und gedrückt. Das GUI-Kapitel der Referenz listet sie auf.

Alles nach dem Link gehört dir. Der <style>-Block in pause.rml überschreibt das Theme für diese Seite, wobei spätere Regeln über frühere gewinnen und eine Regel für eine id eine Regel für eine class schlägt. Für ein echtes Spiel schreib deine eigenen Regeln in eine .rcss-Datei neben dem Dokument und binde sie als zweite ein, dann ist dein Aussehen eine einzige Datei für jede Seite.

Die Einheit dp ist ein Pixel in der eigenen Größe der GUI — deine GUI ist so groß wie das Overlay, also sind 380dp 380 Overlay-Pixel. margin: 80dp auto ist der Trick, mit dem man einen Block bekannter Breite zentriert: auto verteilt, was übrig bleibt, gleichmäßig auf beide Seiten. Es gibt kein Ausmessen und keine Rechnerei, was du nach Lektion neunzehn vielleicht ein bisschen ärgerlich findest.

Um deine eigene Schriftart in einem Dokument zu benutzen, lade sie mit guiLoadFont vor den Dokumenten, die sie benutzen, und nenn sie in RCSS beim Familiennamen, der in der Schriftdatei steht, nicht bei ihrem Dateinamen.

Wann du nichts davon benutzen solltest

Eine GUI ist eine Seite. Sie ist die richtige Antwort für ein Menü, einen Optionsbildschirm, eine Highscore-Tabelle, einen Game-Over-Bildschirm oder ein HUD mit einem echten Layout.

Für eine Punktzahl in der Ecke ist sie die falsche Antwort. Das sind zwei Zeilen fontPrint aus Lektion neunzehn, und sie in ein Dokument zu packen bringt dir nichts und kostet dich eine Textur. Dasselbe gilt für ein Fadenkreuz, eine Lebensleiste, die du mit overlayBox gezeichnet hast, und eine Zeile Debug-Text.

Drei Tatsachen entscheiden das für dich.

Eine GUI braucht eine GPU. Auf einem Rechner ohne — einer alten Kiste, einem kleinen Pi, einem Rechner ganz ohne Treiber für Vulkan, Direct3D 12 oder Metal — gibt es keine GUIs, und guiNew antwortet nicht höflich mit false, sondern beendet dein Spiel. Der 3D-Szene aus Lektion zweiundzwanzig geht es genauso, also fragst du das nicht zum letzten Mal. Frag zuerst singeHasGpu(), wenn dein Spiel an beiden Orten laufen muss, und halte eine schlichte Overlay-Version bereit, auf die du zurückfallen kannst. Das eigene Menü der Engine macht genau das.

Eine GUI kostet eine Textur und einen Layout-Durchgang in jedem Frame, ob du sie zeichnest oder nicht. Eine GUI, mit der du fertig bist, solltest du mit guiDelete löschen, nicht nur verstecken. Verstecken ist für eine Seite, die du in einer Minute wieder zeigst.

Und ein Neuladen reißt eine GUI ab. F5, -R und alles, was das Skript neu startet, nehmen jede GUI mit, und das Skript erzeugt sie neu, wenn es läuft. Das ist in Ordnung, solange du sie im Hauptteil deines Skripts baust und nicht in irgendeiner Ecke, die nur einmal läuft.

Das ganze Skript

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())
singeSetPauseKeyEnabled(false)

local SHIP_Y = 300

local ship    = spriteLoad(DIR .. "art/spaceship.png")
local hudFont = fontLoad("Singe/FreeSansBold.ttf", 20)
local shipX   = 0
local speed   = 2
local score   = 0
local paused  = false
local gui     = nil
local page    = nil


local function say(text)
    if gui ~= nil then
        guiSetValue(gui, page, "status", text)
    end
end


local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    if gui ~= nil then
        guiHide(gui, page)
        guiSetInput(gui, false)
    end
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    if gui ~= nil then
        guiSetValue(gui, page, "score", string.format("%06d", score))
        guiShow(gui, page)
        guiSetInput(gui, true)
    end
end


if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")
    guiHide(gui, page)
    guiSetInput(gui, false)

    guiSetHandler(gui, page, "resume", "click", function()
        closeMenu()
    end)

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

    guiSetHandler(gui, page, "quit", "click", function()
        singeQuit()
    end)

    guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
        speed = math.floor(tonumber(value))
        say("Speed " .. speed)
    end)
end


function onInputPressed(what)
    if what == SWITCH_PAUSE then
        if paused then
            closeMenu()
        else
            openMenu()
        end
    end
end


function onOverlayUpdate()
    overlayClear()

    if not paused then
        shipX = shipX + speed
        if shipX > overlayGetWidth() then
            shipX = -spriteGetWidth(ship)
            score = score + 10
        end
    end
    spriteDraw(ship, shipX, SHIP_Y)

    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    fontPrint(16, 16, string.format("SCORE %06d", score))
    fontPrint(16, 40, "P pauses")

    if paused then
        if gui ~= nil then
            guiDraw(gui)
        else
            colorForeground(255, 211, 90)
            fontPrint(16, 70, "PAUSED -- no GPU, so no menu")
        end
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    if gui ~= nil then
        guiDelete(gui)
    end
    spriteUnload(ship)
    fontUnload(hudFont)
end

Was gerade passiert ist

if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")

Die ganze GUI wird in diesem if gebaut, und auf einem Rechner ohne GPU bleibt gui nil. Jeder Aufruf, der die GUI anfasst, ist mit if gui ~= nil abgesichert, und die Pause funktioniert auch ohne Menü. Das sind vier zusätzliche Zeilen, und sie machen den Unterschied zwischen „hat auf diesem Rechner kein Menü“ und „startet auf diesem Rechner nicht“.

    guiHide(gui, page)
    guiSetInput(gui, false)

guiLoad zeigt das Dokument, das es geladen hat, also muss eine Seite, die versteckt anfangen soll, sofort versteckt werden. Bei einer neuen GUI ist die Eingabe schon aus, aber wenn du sie hier abschaltest, sind openMenu und closeMenu genaue Spiegelbilder voneinander, und bei gespiegelten Paaren macht man viel schwerer etwas falsch.

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

Der Handler ist eine Funktion ohne Namen, geschrieben an der Stelle, an der sie benutzt wird. Lua lässt dich function(…​) …​ end überall schreiben, wo ein Wert erwartet wird, und weil guiSetHandler eine Funktion will, kannst du ihm gleich an Ort und Stelle eine geben, statt sie erst zu benennen und dann den Namen zu übergeben. Sie erreicht score, shipX und closeMenu, weil diese weiter oben in derselben Datei deklariert sind, und genau darum werden die Handler unterhalb der Dinge eingerichtet, die sie anfassen.

    if not paused then
        shipX = shipX + speed

Das Pause-Flag hält die Disc und die Sounds an, nicht deine Rechnerei. onOverlayUpdate wird weiter aufgerufen — genau darum geht es, denn sonst könnte das Menü nicht gezeichnet werden — also musst du alles von dir, was während der Pause anhalten soll, selbst anhalten.

Probier es aus

  1. Füg einen vierten Button hinzu. Kopier die Zeile <button id="quit">, gib ihr eine neue id und neuen Text, und füg einen Handler dafür hinzu. Achte darauf, dass nichts neu ausgemessen oder verschoben werden musste.

  2. Gestalte sie um. Ändere im <style>-Block #frame in width: 260dp; margin: 20dp; und sieh zu, wie das Panel wandert und der Text sich von selbst neu umbricht.

  3. Nimm das guiSetInput(gui, true) in openMenu heraus. Die Seite erscheint trotzdem. Finde allein am Bildschirm heraus, was du verloren hast.

  4. Lass die Seite die ganze Zeit sichtbar. Lösch die Aufrufe von guiHide, ändere beide Aufrufe guiSetInput(gui, false) in true und zeichne die GUI in jedem Frame statt nur während der Pause. Dann drück die Pfeiltasten und die Eingabetaste, während das Raumschiff fliegt. Die Seite nimmt sie für sich: Der Fokus wandert, der Schieberegler ändert die Geschwindigkeit, und die Eingabetaste drückt den Button, der gerade den Fokus hat. Ein Spiel, das mit diesen Tasten steuert, würde sie nie zu hören bekommen. Darum ist ein HUD guiSetInput(gui, false).

  5. Setz die Punktzahl auf die Seite statt ins HUD. Ruf guiSetValue für score in jedem Frame auf statt nur in openMenu, und lösch die fontPrint-Zeile. Dann entscheide, welche der beiden Varianten dir wirklich lieber ist, und warum.

Mach es absichtlich kaputt

Ändere eine id in pause.rml, von id="resume" in id="continue", und lass das Skript in Ruhe. Singe startet und stirbt:

52:guiSetHandler:  No element "resume" in document 0 of GUI 0.

Lies sie, wie du jeden Fehler der Engine liest. Die Zeile, der Aufruf, der sich beschwert hat, dann die Beschwerde — und diese Beschwerde ist genau. Sie sagt nicht, dass das Dokument kaputt ist; das Dokument wurde einwandfrei geladen. Sie sagt, dass du nach einem Element mit einem Namen gefragt hast, den nichts darin hat.

guiSetHandler und guiSetValue sterben beide an einer fehlenden id, weil ein Handler, den du anhängen wolltest und nicht angehängt hast, ein Fehler ist, von dem du sofort hören willst. guiGetValue ist die Ausnahme: Es antwortet stattdessen mit nil, also kannst du fragen, ob etwas da ist.

Der andere Fehler, den du kennenlernen solltest, ist der, den du bekommst, wenn das Dokument selbst nicht lädt. Benenn pause.rml um und starte es. Diesmal nennt Singe die Datei und zitiert den eigenen Grund von RmlUi, und das Gemecker von RmlUi über dein Markup und deine Stile landet in der Konsole, ob das Laden klappt oder nicht. Lies diese Konsole, wenn eine Seite zum ersten Mal leer bleibt; meistens hat sie schon gesagt, warum.

Was du gelernt hast

  • Eine GUI ist ein Rechteck fester Größe, in das Dokumente gesetzt und gezeichnet werden; guiNew erzeugt eine, und guiDelete gibt sie frei.

  • guiLoad legt ein RML-Dokument in eine GUI und zeigt es an; guiHide, guiShow und guiClose verwalten es danach.

  • guiDraw legt die GUI für einen Frame über das Overlay, also kommt es wie jeder andere Zeichenaufruf in onOverlayUpdate.

  • Eine neue GUI zeigt nur an; erst guiSetInput macht sie bedienbar.

  • guiSetHandler führt deine Funktion aus, wenn ein Element angeklickt oder verändert wird, guiSetValue schreibt in ein Element, und guiGetValue liest eines.

  • Ein Ereignis, das ein Element benutzt hat, erreicht nie deine eigenen Callbacks; alles andere fällt wie gewohnt durch.

  • Singe/gui.rcss ist das mitgelieferte Theme; binde es zuerst ein und überschreib es in einem <style>-Block oder einem eigenen Stylesheet.

  • Eine GUI braucht eine GPU, also frag singeHasGpu(), wenn dein Spiel auch ohne laufen muss.

  • Jede GUI rendert in jedem Frame, ob du sie zeichnest oder nicht, also lösch die, mit denen du fertig bist.

  • Eine Punktzahl in der Ecke sind zwei Zeilen fontPrint, kein Dokument.

Beim nächsten Mal

Es gibt noch eine weitere Art von Text auf dem Bildschirm, und sie hat ein eigenes System, aus einem Grund, der nichts damit zu tun hat, wie sie aussieht. In Lektion einundzwanzig geht es um Untertitel und um die Spieler, die dein Spiel ohne sie nicht spielen können.

Lektion 21: Untertitel

Die fertige Lektion

Irgendwann spielt jemand dein Spiel, der nicht hören kann.

Wenn in deinem Spiel gesprochen wird und es keine Untertitel hat, kann diese Person es nicht spielen. Nicht „es ist schwerer für sie“ — sie kommt zur ersten Szene, in der eine Figur das sagt, was dem Spieler erklärt, was er tun soll, und hört auf. Das ist schon alles, und es ist der Grund, warum es diese Lektion gibt, statt nur einen Absatz in Lektion neunzehn.

Der andere Grund ist praktisch. Untertitel nachträglich in ein fertiges Spiel einzubauen ist eine Qual. Du musst jede gesprochene Zeile finden, herausfinden, auf welchem Frame sie liegt, und dabei entdecken, dass die Hälfte deiner Zeiten falsch ist, weil dein Video mitten im Projekt neu kodiert wurde. Machst du es, während du das Spiel schreibst, ist es ein Nachmittag. Singe gibt dir ein System, das den schweren Teil erledigt, und diese Lektion zeigt, wie man es benutzt.

Es ist nicht einfach gezeichneter Text

Du könntest Untertitel selbst machen. Eine Liste von Zeilen mit Start- und Endzeiten führen, in onOverlayUpdate auf die Uhr sehen und die aktuelle Zeile mit fontToSprite zeichnen. Das haben schon Leute gemacht. Hier ist, warum du es nicht tun solltest.

Untertitel richten sich nach der Disc, nicht nach einer Uhr. Wenn srtLoad deine Datei liest, rechnet es jeden Zeitstempel sofort in eine Frame-Nummer der Disc um, mit der Bildrate der Disc, die geladen ist. Ab diesem Moment sieht die Engine überhaupt nicht mehr auf eine Uhr; bei jedem gezeichneten Frame fragt sie, welcher Cue den Frame abdeckt, auf dem die Disc gerade steht.

Diese eine Entscheidung bringt dir das, was ein selbst gebautes System nie richtig hinbekommt: Ein Untertitel übersteht einen Sprung. Schick die Disc irgendwohin — discSearch, discSkipForward, ein Einzelschritt, eine Verzweigung in ein anderes Segment — und im nächsten gezeichneten Frame steht die richtige Zeile da, vorwärts wie rückwärts, ohne dass etwas neu geladen oder eine Uhr zurückgesetzt wird. In einem verzweigten Spiel wie in Lektion sechzehn, in dem die Entscheidungen des Spielers die Disc ständig herumspringen lassen, ist das der Unterschied zwischen funktioniert und funktioniert fast.

Es zeichnet auch an der richtigen Stelle. Das Untertitel-Dokument liegt über dem Bild, über deinem Overlay, unter jeder GUI im Bildschirmraum, und es folgt dem Bild, wohin die Einstellungen des Spielers es auch setzen — ein verkleinertes Bild, ein verschobenes, ein gedrehter Automat, ein Loch in einem Bezel. Es nimmt keine Mauseingaben an, also geht ein Lightgun-Schuss direkt hindurch. Das alles selbst richtig hinzubekommen ist eine Woche, die du nicht eingeplant hattest.

Schreib die Datei

Untertitel kommen in eine SubRip-Datei, die auf .srt endet und reiner Text ist, den du in jedem Editor tippen kannst. Es ist eines der einfachsten Formate, die es gibt. Leg neben deinem Skript eine Datei namens subtitles.srt an:

1
00:00:01,000 --> 00:00:04,000
They told us the cave was empty.

2
00:00:04,200 --> 00:00:08,000
They were wrong about
a great many things.

3
00:00:08,500 --> 00:00:13,000
Keep your light on the floor.

Ein Cue besteht aus vier Dingen. Einer Nummer auf einer eigenen Zeile. Einer Zeile mit zwei Zeitstempeln und dazwischen einem Pfeil aus zwei Bindestrichen und einem Größer-als-Zeichen. Einer oder mehreren Zeilen Text. Einer Leerzeile zum Abschluss.

Ein Zeitstempel ist HH:MM:SS,mmm — Stunden, Minuten und Sekunden, durch Doppelpunkte getrennt, dann ein Komma, dann Millisekunden. Das Komma ist kein Tippfehler, und ein Punkt geht nicht. 00:00:04,200 ist vier Sekunden und eine Fünftelsekunde nach dem Start.

Die Cue-Nummern werden gelesen und weggeworfen, also müssen sie weder in der richtigen Reihenfolge noch überhaupt richtig sein. Nummerier sie trotzdem; irgendwann wirst du Cue einundvierzig suchen.

Cue zwei zeigt, wie ein Cue mit zwei Zeilen aussieht. Die Zeilen werden so gezeigt, wie du sie geschrieben hast, also entscheidest du, wo eine lange Zeile umbricht, und das ist wichtiger, als du denkst, und kommt weiter unten dran.

Der Parser ist mit Absicht nachsichtig bei den Dingen, die in einer von Hand bearbeiteten Datei schiefgehen. Windows-Zeilenenden werden ohne Änderung geladen, und Leerzeichen am Anfang und Ende jeder Zeile werden entfernt. Ein Cue, dessen Zeitstempel sich nicht lesen lassen, wird übersprungen, und der Rest der Datei wird weiter geladen, was freundlich ist, bis du dich fragst, wo Zeile zwölf geblieben ist. Ein paar Dinge werden nicht unterstützt: Die Tags <i> und <b>, die manche Werkzeuge schreiben, werden als Text gezeigt, statt befolgt zu werden, und die Positionskoordinaten, die manche Werkzeuge an die Zeitzeile anhängen, werden ignoriert. Der Abschnitt über Untertitel in der Referenz hat die vollständige Liste.

Lade sie und schalte sie ein

Drei Aufrufe, und die Reihenfolge zählt.

if srtLoad(DIR .. "subtitles.srt") then
    srtPosition(80)
    srtEnable(true)
end

srtLoad liest die Datei und antwortet true oder false. Es antwortet false und hat dann nichts geladen, in drei Fällen: Die Datei lässt sich nicht lesen, nichts darin lässt sich verstehen, oder es gibt keine Disc. In allen drei Fällen gibt es eine Warnung mit dem Dateinamen auf der Konsole aus. Das ist gutes Design, und du solltest es nutzen: Eine fehlende Untertiteldatei ist es nicht wert, deswegen ein Spiel abzuschießen, aber ein Spiel stillschweigend ohne Untertitel auszuliefern ist es wert, bemerkt zu werden.

Der Fall „keine Disc“ ist der, der dich erwischen wird. Die Zeitstempel müssen zu Frame-Nummern mit der Bildrate der Disc werden, und bevor eine Disc offen ist, gibt es keine Bildrate, die man benutzen könnte. Lade Untertitel also nach der Disc, und in einem gewöhnlichen Skript heißt das: aus dem Hauptteil des Skripts, wo auch alles andere läuft, was du auf der obersten Ebene geschrieben hast. Daraus folgt, dass eine .srt, die für ein Video mit einer Bildrate geschnitten wurde, bei einem Video mit einer anderen an der falschen Stelle landet. Stimm die Zeiten deiner Datei auf das Video ab, das du wirklich ausliefern wirst.

srtEnable(true) schaltet die geladenen Cues ein. Ein Skript fängt immer mit ausgeschalteten Untertiteln an, also muss ein Spiel, das welche lädt, sie einschalten. Schaltest du sie wieder aus, verschwindet, was gerade zu sehen ist, und schaltest du sie wieder ein, erscheint, was den Frame abdeckt, auf dem die Disc gerade steht — kein Suchen, kein Zustand, den du dir merken musst.

Ob Untertitel an sind, ist eine Einstellung, keine Entscheidung, die du für den Spieler triffst. Setz sie auf deine Optionsseite aus Lektion zwanzig, speichere sie mit saveSet aus Lektion zwölf und gib srtEnable, was der Spieler zuletzt gewählt hat.

Wo sie sitzen

srtPosition(70)

srtPosition ist ein Prozentwert von oben nach unten im Bild, von 1 bis 95, und der Standard ist 80. Er gilt für den Cue, der gerade zu sehen ist, und für jeden Cue danach. Eine Zahl außerhalb des Bereichs wird ignoriert, statt auf den Bereich begrenzt zu werden, also lässt ein Tippfehler die Position genau, wo sie war, und sagt nichts. Prüf deine also nach.

Achtzig Prozent liegt tief, und das mit Absicht: Der untere Teil des Bildes ist meistens der langweiligste Teil der Einstellung. Schieb sie nach oben, wenn der untere Teil nicht langweilig ist — wenn dein Spiel eine Punkteanzeige am unteren Rand zeichnet oder wenn das Lightgun-Fadenkreuz des Spielers dort unten wohnt.

Einen wegnehmen

srtClear()

srtClear nimmt sofort vom Bildschirm, was gerade dort steht, und lässt die geladenen Cues und den eingeschalteten Zustand in Ruhe. Die Zeile, die zu sehen war, bleibt weg, bis die Disc den nächsten Cue erreicht. Benutz es, wenn eine Szene früher endet und du nicht willst, dass die letzte Dialogzeile über der nächsten Einstellung hängt.

Es gibt noch einen Aufruf, der die Untertitel-Mechanik mitbenutzt, und vielleicht hast du ihn schon benutzt:

overlayBanner("Extra life!", 20)

overlayBanner zeigt etwa dreißig gezeichnete Frames lang eine kurze Nachricht über dem Bild und nimmt sie dann wieder weg. Es wird vom selben Dokument gezeichnet wie die Untertitel, also sieht ein Banner aus wie ein Untertitel, und solange eines zu sehen ist, nimmt es den Platz jedes Untertitels ein, der zurückkommt, wenn die Zeit des Banners abgelaufen ist. Sein eigenes Höhenargument ist von srtPosition unabhängig und steht standardmäßig auf 47, der Mitte des Bildes. Nachrichten mit mehr als sechzig Zeichen werden komplett ignoriert, also scheint eine lange überhaupt nicht zu funktionieren.

Untertitel, die schon im Video stecken

Manche Videodateien bringen ihre eigenen Untertitelspuren mit. Wenn deine das tut, brauchst du überhaupt keine .srt:

if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

srtLoadTrack nimmt eine Spurnummer von 0 bis discGetSubtitleTracks() - 1, und alles nach dem Laden ist gleich. discGetSubtitleLanguage(track) sagt dir, mit welcher Sprache eine Spur beschriftet ist, als Code aus drei Buchstaben wie eng oder fra, damit ein Spiel dem Spieler anbieten kann, was sein Video zufällig mitbringt.

Zwei Warnungen. Eine Spur zu lesen geht einmal durch die ganze Videodatei, ohne Bilder zu dekodieren, also dauert eine Disc in Spielfilmlänge einen Moment: Mach das, während etwas anderes auf dem Bildschirm ist, nicht zwischen zwei Frames des Spiels. Und Untertitelspuren mit Bildern der Wörter statt der Wörter selbst — die Art, die DVDs und Blu-rays benutzen — können nicht gelesen werden. Sie werden mitgezählt, damit die Nummerierung zu dem passt, was andere Videoplayer anzeigen, aber srtLoadTrack antwortet für sie false.

Das ganze Skript

Dieses hier braucht ein Video. Du hast eins: Singe/menuBackground.mkv, das die Engine in deinen Arbeitsordner entpackt hat, als du zum ersten Mal irgendetwas gestartet hast. Sag Singe mit --framefile, dass es das als Disc benutzen soll; das schaltet auch die Disc ein:

Singe --framefile=Singe/menuBackground.mkv subtitles
dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local HUD_X     = 16
local STEP      = 5
local TOP_LIMIT = 10
local LOW_LIMIT = 95

local hudFont = fontLoad("Singe/FreeSansBold.ttf", 18)
local loaded  = false
local showing = false
local height  = 80


if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

if loaded then
    srtPosition(height)
    showing = true
    srtEnable(true)
end

discPlay()


function onInputPressed(what)
    if not loaded then
        return
    end
    if what == SWITCH_BUTTON1 then
        showing = not showing
        srtEnable(showing)
        if showing then
            overlayBanner("Subtitles on", 20)
        else
            overlayBanner("Subtitles off", 20)
        end
    elseif what == SWITCH_UP then
        height = math.max(TOP_LIMIT, height - STEP)
        srtPosition(height)
    elseif what == SWITCH_DOWN then
        height = math.min(LOW_LIMIT, height + STEP)
        srtPosition(height)
    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()
    end
end


function onOverlayUpdate()
    overlayClear()
    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    if loaded then
        if showing then
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles ON at " .. height .. "%")
        else
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles OFF")
        end
        fontPrint(HUD_X, 40, "Fire toggles them, up and down move them, left rewinds")
    else
        fontPrint(HUD_X, 16, "No subtitles loaded.")
        fontPrint(HUD_X, 40, "Run with --framefile and check subtitles.srt is beside the script.")
    end
    return OVERLAY_UPDATED
end


function onShutdown()
    fontUnload(hudFont)
end

Drück Feuer zum Umschalten, hoch und runter, um die Zeilen zu verschieben, und links, um an den Anfang zurückzuspulen. Auf das Zurückspulen solltest du achten: Die Disc springt zurück auf Frame null, und gleich im nächsten Frame ist der richtige Cue da, ohne dass du irgendetwas dafür tust.

Was gerade passiert ist

if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

Nimm die eigenen Untertitel des Videos, wenn es welche hat, fall auf die Datei neben dem Skript zurück, wenn nicht, und wisse am Ende, was davon — wenn überhaupt etwas — funktioniert hat. Beide Aufrufe antworten mit einem Boolean, also besteht der Rückfall aus zwei if-Anweisungen und keinen Sonderfällen. menuBackground.mkv hat keine Untertitelspur, also bekommst du in Wirklichkeit die Datei, die du getippt hast.

function onInputPressed(what)
    if not loaded then
        return
    end

return ohne etwas dahinter verlässt die Funktion sofort. Ohne geladene Untertitel gibt es für keine dieser Tasten etwas zu tun, und früh auszusteigen ist klarer, als den ganzen Rumpf in ein if zu packen. srtEnable aufzurufen, wenn nichts geladen ist, schadet nicht, aber Code zu schreiben, der nur Sinn ergibt, wenn er nichts tut, ist eine Angewohnheit, die man sich besser nicht zulegt.

    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()

Das srtClear ist nicht nötig. Die Engine zeigt im nächsten gezeichneten Frame sowieso den richtigen Cue für Frame null. Es steht da, damit du es löschen und zusehen kannst, was passiert: Die alte Zeile bleibt für einen Sekundenbruchteil stehen, während die Disc dorthin kommt, wo sie hinwill. Bei einem langsamen Sprung sieht man dieses Aufblitzen der falschen Zeile, und vorher zu löschen ist der Weg, es zu vermeiden.

Text über einem bewegten Bild lesbar machen

Das System bringt die Wörter auf den Bildschirm. Ob jemand sie lesen kann, ist dein Problem, und das gilt für jede Zeile Text, die du über Video zeichnest — eine Aufforderung aus Lektion achtzehn, eine Punktzahl, eine Auswahl an einer Verzweigung — nicht nur für Untertitel.

Bleib weg von den Rändern. Fernseher schneiden seit siebzig Jahren die Ränder von Bildern ab, und Arcade-Monitore sind schlimmer, nicht besser. Geh davon aus, dass die äußeren fünf Prozent des Bildes auf jeder Seite auf dem Bildschirm von irgendjemandem gar nicht zu sehen sind. Halte alles, was ein Spieler lesen muss, innerhalb davon. Darum hört srtPosition bei 95 auf und nicht bei 100.

Kontrast ist keine Farbwahl, er ist eine Garantie. Weißer Text über einem Bild ist weißer Text über dem, was das Bild gerade zufällig zeigt, und in zwei Sekunden ist das vielleicht ein Schneefeld. Der mitgelieferte Untertitelstil löst das so, wie Filmuntertitel es tun: ein dunkles Panel, das sich eng um den Text legt, plus ein Schatten von einem Pixel. Wenn du deinen eigenen Text über Video zeichnest, mach das eine oder das andere — ein overlayBox dahinter oder eine dunkle Kopie des Textes, um ein Pixel versetzt. Verlass dich nicht auf das Bild.

Brich deine Zeilen selbst um. Zwei kurze Zeilen liest man schneller als eine lange, und eine Zeile, die umbricht, wo du es nicht ausgesucht hast, bricht meistens an der falschen Stelle. Peil ungefähr vierzig Zeichen pro Zeile an und nicht mehr als zwei Zeilen auf einmal. Brich an einer natürlichen Pause um: They were wrong about / a great many things liest sich; They were wrong / about a great many things stolpert.

Lass sie lange genug stehen. Eine angenehme Lesegeschwindigkeit liegt irgendwo bei fünfzehn Zeichen pro Sekunde, also will eine Zeile mit vierzig Zeichen ungefähr drei Sekunden. Sieh dir Cue eins in der Datei oben an: zweiunddreißig Zeichen, drei Sekunden. Wenn eine Dialogzeile kurz und schnell ist, ist es freundlicher, den Cue noch einen Moment über das Ende des Gesprochenen hinaus stehen zu lassen, als ihn wegzureißen.

Setz sie dorthin, wo die Action nicht ist. Wenn das Wichtige in der Einstellung am unteren Bildrand ist, schieb die Untertitel für diese Szene mit srtPosition nach oben. Du kannst es so oft aufrufen, wie du willst, und der Spieler merkt nie, dass du es getan hast.

Sie gestalten

Die Zeilen werden von einem Dokument gezeichnet, derselben Art, die du in Lektion zwanzig kennengelernt hast, und zwei Dateien in deinem Ordner Singe entscheiden, wie sie aussehen:

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

  • Singe/subtitle.rcss — der Stil. .cue ist der Block, der die Höhe trägt, die srtPosition verlangt hat, und .cue .text ist der Textbalken darin: weiß, fett, auf einem dunklen Panel mit runden Ecken, das sich eng um den Text legt, mit einem Schatten.

Öffne subtitle.rcss und lies sie — es sind ungefähr vierzig Zeilen. Dann lass sie in Ruhe, denn eine Änderung dort hält nicht. Bei jedem Start legt Singe seine eigene Kopie von allem im Ordner Singe zurück, was verändert wurde, und sagt das:

>>> Updated File:  Singe/subtitle.rcss

Dieser Ordner gehört der Engine. Dein Spiel bringt stattdessen seine eigene Kopie mit. Kopier beide Dateien aus Singe in deinen Ordner subtitles, neben das Skript. Dann öffne deine Kopie von subtitle.rml und ändere die eine Zeile in ihrem <head>, die den Stil einbindet, sodass sie so lautet:

	<link type="text/rcss" href="subtitle.rcss"/>

Ein Name in einem Dokument zählt ab dem eigenen Ordner des Dokuments, außer ein Name, der mit Singe/ anfängt, denn der meint immer den Ordner der Engine. Der Link, so wie du ihn kopiert hast, Singe/subtitle.rcss, holt immer noch den Stil der Engine. Der neue holt deinen.

Wenn Singe eine subtitle.rml neben deinem Skript findet, zeichnet es die Untertitel damit statt mit seiner eigenen. Häng -p an den Befehl an, und Singe beschreibt unterwegs Zeile für Zeile, was es gerade tut:

Singe -p --framefile=Singe/menuBackground.mkv subtitles

Wenn der erste Cue erscheint, ist eine dieser Zeilen diese:

Using the game's own subtitles/subtitle.rml

Jetzt ändere font-size, color, background-color, border-radius oder font-effect in deiner subtitle.rcss, speichere und starte es noch einmal. Die Engine setzt immer nur den Inhalt von #slot und die Höhe von .cue, also gehört alles andere in deinen beiden Dateien dir, und nichts, was Singe beim Start tut, rührt sie an. Wenn -p sagt, dass es deine verwendet, und sich das Aussehen nicht geändert hat, lies den Link noch einmal: Eine Kopie, in der noch Singe/ steht, verwendet still und leise den Stil der Engine.

Weil overlayBanner dasselbe Dokument benutzt, gestaltest du mit den Untertiteln auch deine Banner um, und das ist meistens, was du willst, und gut zu wissen, bevor du dich fragst, warum.

Eine Grenze: Das Untertitel-Dokument ist ein Dokument, und Dokumente brauchen eine GPU. Auf einem Rechner ohne liest srtLoad deine Datei trotzdem und antwortet trotzdem ehrlich, und es wird nichts gezeichnet. Eine Warnung sagt das einmal.

Probier es aus

  1. Füg einen vierten Cue zu subtitles.srt hinzu, zwischen elf und dreizehn Sekunden. Speichere und starte es. Dann stell ihn außer der Reihe, als Cue 99, an den Anfang der Datei, und überzeug dich, dass es trotzdem funktioniert.

  2. Gib einem Cue einen falschen Zeitstempel — schreib 00:00:05.500 mit einem Punkt statt eines Kommas — und starte es. Sieh zu, welche Zeile verschwindet, und bemerke, dass überhaupt nichts dazu gesagt wird. Eine Datei, die lädt, ist noch keine Datei, die stimmt.

  3. Gestalte sie um. Ändere in deiner eigenen subtitle.rcss — der Kopie neben deinem Skript, nicht der in Singe — .cue .text auf gelben Text auf einem völlig durchsichtigen Hintergrund und füg dann einen kräftigeren Schatten hinzu. Dann spiel es über dem Video ab und entscheide ehrlich, ob es noch lesbar ist.

  4. Mach die Zeitsteuerung absichtlich kaputt. Ändere jeden Zeitstempel in der Datei so, dass er zwei Sekunden zu spät ist, und sieh zu, wie ein korrekt funktionierendes System nutzlose Untertitel liefert. Genau das macht ein neu kodiertes Video mit dir.

  5. Setz den Umschalter in ein Menü. Nimm die Pausenseite aus Lektion zwanzig, füg eine Checkbox hinzu und verbinde sie mit srtEnable. Dann speichere die Wahl mit saveSet, damit sie beim nächsten Mal noch an ist. Das ist die Version, die deine Spieler wirklich wollen.

Mach es absichtlich kaputt

Starte das Skript ohne die Option --framefile:

Singe subtitles

Das Fenster geht auf, schwarz, mit deiner Ersatznachricht darauf, und die Konsole sagt:

Warning:  No subtitles were loaded from subtitles/subtitles.srt.

Kein Absturz und kein Fehlerdialog, weil srtLoad mit false geantwortet und dein Skript damit umgegangen ist.

Das ist der wertvollste Fehlschlag in dieser Lektion, denn er ist der, der passiert, ohne dass es jemand merkt. Es gibt keine Disc, also gibt es keine Bildrate, also gibt es nichts, in das man die Zeitstempel umrechnen könnte, also wird nichts geladen. Hättest du srtLoad(…​) einfach so hingeschrieben und die Antwort weggeworfen, wäre dein Spiel einwandfrei gelaufen und hätte keine Untertitel gezeigt, und du hättest es erst erfahren, als es dir jemand gesagt hat.

Benutz die Antwort. Jedes Mal.

Was du gelernt hast

  • Ein Spiel mit Sprache und ohne Untertitel ist ein Spiel, das manche Leute überhaupt nicht spielen können.

  • Untertitel gleich beim Schreiben einzubauen ist ein Nachmittag; sie nachzurüsten nicht.

  • Untertitel sind eine .srt-Datei: eine Nummer, zwei Zeitstempel mit -→ dazwischen, der Text und eine Leerzeile.

  • srtLoad rechnet die Zeitstempel beim Laden in Frame-Nummern der Disc um, und darum übersteht ein Cue jeden Sprung.

  • Die Datei muss nach der Disc geladen werden, und das Laden antwortet false, wenn es nicht klappt, auch dann, wenn es keine Disc gibt. Prüf die Antwort.

  • srtEnable schaltet sie ein, und ein Skript fängt immer mit ausgeschalteten an.

  • srtPosition setzt sie als Prozentwert von oben im Bild, 1 bis 95.

  • srtClear nimmt weg, was gerade zu sehen ist, und overlayBanner benutzt dasselbe Dokument.

  • srtLoadTrack liest Untertitel aus der Videodatei selbst, wenn sie welche hat.

  • Singe schreibt seinen Ordner Singe bei jedem Start neu, also kopierst du, um Untertitel umzugestalten, subtitle.rml und subtitle.rcss neben dein Skript, lässt den Link der Kopie auf dein eigenes Stylesheet zeigen und änderst dieses.

  • Text über einem bewegten Bild braucht einen sicheren Rand, seinen eigenen Kontrast, Zeilen, die du selbst umgebrochen hast, und Zeit, um gelesen zu werden.

Beim nächsten Mal

Das war das Letzte zum Thema Text. Teil vier geht weiter, ohne dass du ihn der Reihe nach lesen musst, und die nächste Lektion öffnet eine Tür, die zwanzig Lektionen lang zu war: overlayGetWidth und overlayGetHeight sind zwei Zahlen, und eine Szene hat drei. Lektion zweiundzwanzig ist die dritte.

Lektion 22: Hinein in 3D

Die fertige Lektion

Alles, was du bisher gezeichnet hast, war flach. Sprites, Text, Kästen und Linien leben alle auf dem Overlay, einer Glasscheibe vorn im Fenster mit denselben Koordinaten wie in Lektion eins. Diese Lektion stellt eine Welt hinter diese Scheibe: einen Ort mit Tiefe, an dem ein Ding näher oder weiter weg sein kann und an dem eine Kamera entscheidet, was du davon siehst.

Am Ende hast du eine Kiste, die im Raum schwebt und die du mit den Pfeiltasten drehen kannst, und die Zahlen für ihre Winkel stehen in der Ecke, ausgegeben mit demselben overlayPrint, das du an deinem allerersten Tag benutzt hast. Dieser letzte Teil ist wichtiger, als er klingt, und es gibt einen Abschnitt dazu.

Eine Szene, eine Kiste und ein Licht

Leg einen Ordner an, leg eine Datei namens spin.singe hinein und tipp das ein.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)


function onOverlayUpdate()
    nodeRotate(box, 0, 0.5, 0)
    return OVERLAY_UPDATED
end

Starte es mit Singe -R spin. Eine orangefarbene Kiste dreht sich langsam vor einem dunkelblauen Hintergrund, beleuchtet von oben rechts, mit einer hellen Seite, während die anderen in den Schatten abfallen.

In diesem Skript gibt es keine Kamera. Singe hat dich auf (0, 0, 5) gesetzt, mit Blick auf die Mitte der Welt, weil eine Szene ohne Kamera ja von irgendwoher gesehen werden muss. Gleich ersetzt du das durch deine eigene Kamera.

Wenn das Fenster schwarz bleibt, lies die Konsole. Auf einem Rechner, dessen Grafik keine 3D-Szene zeichnen kann, hält sceneEnable das Spiel mit einer Meldung an, die das sagt, und dagegen kannst du nichts tun, außer die Lektion woanders zu starten. 2D-Spiele funktionieren auf so einem Rechner weiter; 3D nicht.

Was gerade passiert ist

Die drei Aufrufe ganz oben richten die Welt als Ganzes ein.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

sceneEnable(true) schaltet die 3D-Ebene ein. Das ist der eine Aufruf, den jedes 3D-Spiel macht, und bis du ihn machst, wird nichts gezeichnet, was du in der Szene baust.

sceneSetBackground ist die Farbe, mit der die Szene in jedem Frame gelöscht wird, Rot, Grün und Blau von 0 bis 255, so wie Farben seit Lektion neun funktionieren. Du kannst ihm eine vierte Zahl für die Transparenz geben, und so stellt ein Spiel, das Video abspielt, ein 3D-Objekt vor den Film. Lässt du sie weg, ist der Hintergrund undurchsichtig.

sceneSetAmbient ist ein bisschen Licht, das aus allen Richtungen gleichzeitig kommt. Seine Aufgabe ist, die Seiten, die keine Lampe erreicht, davor zu bewahren, rein schwarz zu sein. Dreh es später auf 0, 0, 0 herunter und sieh, wie hart das Bild wird.

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

Ein Material ist, wie eine Oberfläche aussieht: ihre Farbe, wie glänzend sie ist, ob ein Bild darauf ist. materialNew erzeugt eins und gibt eine Zahl zurück, die dafür steht, dieselbe Art von Handle, die dir spriteLoad in Lektion neun gegeben hat. Bewahr es in einer Variablen auf, denn jeder spätere Aufruf braucht es.

materialSetRoughness reicht von 0, einem Spiegel mit einem winzigen, harten Glanzpunkt, bis 1, einer kreidigen, matten Oberfläche ganz ohne Glanzpunkt. 0.6 ist Farbe auf Holz. Es gibt noch ein Dutzend weitere materialSet-Aufrufe, und die nächste Lektion benutzt ein paar davon; der Abschnitt Material in der Referenz listet sie alle auf.

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

Das ist der wichtige Teil. Ein Knoten ist ein Ort in der Welt. Er hat eine Position, eine Drehung und eine Skalierung, und für sich allein zeichnet er überhaupt nichts: Er ist eine Stelle, an die man Dinge hängen kann. Alles in einer 3D-Szene ist ein Knoten, auch die Lichter und die Kamera.

nodeNew erzeugt einen leeren Knoten in der Mitte der Welt. nodeSetMesh hängt zwei Dinge daran: ein Mesh, das ist die Form, und das Material, das ist, wie diese Form aussieht. meshBox(2, 2, 2) baut eine Kiste, zwei Einheiten breit, zwei hoch und zwei tief, und gibt ein Handle darauf zurück, so wie materialNew es getan hat.

Meshes und Materialien lohnt es sich zu teilen. Ein meshBox-Handle kann von hundert Knoten benutzt werden, und so zeichnest du hundert Kisten billig. Hundert einzelne Kisten zu bauen, die zufällig gleich groß sind, ist der Anfängerweg, eine Szene langsam zu machen.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)

lightNew erzeugt ebenfalls einen Knoten — einen, der ein Licht trägt — und gibt sein Knoten-Handle zurück, also stellst du es mit denselben Aufrufen auf und richtest es aus, die du für alles andere benutzt. LIGHT_DIRECTIONAL ist eine Sonne: Sie ist so weit weg, dass nur die Richtung zählt, in die sie scheint, und darum ist die Position hier nur insofern wichtig, als nodeLookAt aus ihr die Richtung ausrechnet.

Nimm diese drei Zeilen heraus und starte es noch einmal. Die Kiste wird fast schwarz, weil nur noch das schwache Umgebungslicht übrig ist. Um Licht geht es in der ganzen Lektion dreiundzwanzig, und das hier ist ein erster Vorgeschmack auf die häufigste Enttäuschung in 3D: Das Modell wurde einwandfrei geladen, und die Szene ist schwarz, weil nichts darauf scheint.

    nodeRotate(box, 0, 0.5, 0)

nodeRotate dreht einen Knoten um so und so viele Grad um jede seiner eigenen drei Achsen, zusätzlich zu der Drehung, die er schon hatte. Ein halbes Grad pro Frame, bei etwa sechzig Frames pro Sekunde, ist eine Umdrehung alle zwölf Sekunden. Das ist derselbe Trick wie in Lektion zwei: Eine kleine Änderung, in jedem Frame angewandt, wirkt wie Bewegung.

Welche Richtung ist welche

Drei Zahlen beschreiben einen Ort in der Szene, und du musst wissen, was jede davon bedeutet, bevor du irgendetwas irgendwohin stellen kannst.

  • X geht nach rechts. Größeres X ist weiter rechts.

  • Y geht nach oben. Größeres Y ist höher. Der Boden einer Szene ist meistens y = 0.

  • Z geht auf dich zu, aus dem Bildschirm heraus. Größeres Z ist näher an der Standardkamera, und negatives Z ist die Richtung, in die die Kamera schaut.

Das Letzte erwischt jeden. Dinge, die vor der Kamera sein sollen, kommen auf negatives Z. Das ist keine Marotte von Singe: glTF und Blender benutzen dieselbe Anordnung, also kommt ein Modell, das aus Blender exportiert wurde, so ausgerichtet an, wie Singe es erwartet.

Glaub mir nichts davon einfach so. Füg diese Zeile nach der Zeile mit nodeSetMesh ein, speichere und sieh hin:

nodeSetPosition(box, 3, 1, 0)

Die Kiste springt nach rechts und nach oben. nodeSetPosition setzt einen Knoten an eine genaue Stelle und ersetzt die Position, die er vorher hatte. Passend dazu gibt es nodeMove(node, dx, dy, dz), das einen Knoten stattdessen um einen Betrag verschiebt, entlang seiner eigenen Achsen, also fährt nodeMove(ship, 0, 0, -0.1) ein Schiff vorwärts, egal in welche Richtung es gerade zeigt.

Probier als Nächstes nodeSetPosition(box, 0, 0, -20). Die Kiste schrumpft in die Ferne, und das ist negatives Z, das seine Arbeit macht. Dann probier (0, 0, 20): Die Kiste verschwindet, weil du sie hinter die Kamera gestellt hast.

Zwei weitere Aufrufe machen den Satz komplett.

nodeSetRotation(box, 0, 45, 0)
nodeSetScale(box, 0.5)

nodeSetRotation setzt die Drehung direkt in Grad, während nodeRotate etwas dazuzählt. Die drei Zahlen sind um X, um Y und um Z: Eine Drehung um Y macht ein Mensch, der auf dem Boden steht und sich in eine andere Richtung dreht, und die wirst du am häufigsten benutzen. nodeSetScale macht den Knoten größer oder kleiner, entweder mit einer Zahl für alle drei Achsen oder mit dreien, einer für jede.

Nimm beide Experimente wieder heraus, bevor du weitermachst. Der Rest der Lektion geht von dem Skript aus, wie du es zuerst getippt hast.

Deine eigene Kamera

Die Standardansicht ist eine Höflichkeit, keine Funktion. Stell eine Kamera hinein.

local camera = nodeNew()
nodeSetPosition(camera, 0, 2, 7)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(60, 0.1, 100)

Setz das unter das Licht, vor dein onOverlayUpdate, und starte es. Jetzt schaust du leicht von oben auf die Kiste, aus zwei Einheiten Höhe und sieben Einheiten Abstand.

Eine Kamera ist ein Knoten wie jeder andere. cameraSet sagt der Engine, aus welchem Knoten sie herausschauen soll, und die Szene wird von der Position dieses Knotens aus gezeichnet, mit Blick entlang seines eigenen negativen Z. Eine Kamera von Hand mit nodeSetRotation auszurichten wäre eine Qual, also erledigt nodeLookAt das für dich: Gib ihm einen Punkt in der Welt, und es dreht den Knoten so, dass er dorthin schaut.

cameraSetPerspective ist das Objektiv. Die erste Zahl ist das Sichtfeld in Grad, von oben nach unten: wie viel von der Welt in die Höhe des Fensters gequetscht wird. Eine kleine Zahl wie 35 ist ein Teleobjektiv, das alles flach drückt; eine große wie 90 ist ein Weitwinkel, der den Raum riesig aussehen lässt und die Ecken ausbeult. 60 ist ein angenehmer Standardwert. Die anderen beiden Zahlen sind die kleinste und die größte Entfernung, die gezeichnet wird, und Dinge außerhalb dieses Bereichs werden überhaupt nicht gezeichnet.

Weil die Kamera ein gewöhnlicher Knoten ist, funktioniert alles, was du über Knoten gelernt hast, auch bei ihr. Später hängst du eine Kamera unter ein fahrendes Auto und bekommst eine Verfolgerkamera geschenkt.

Mit den Pfeiltasten drehen

Das Koordinatensystem von einer Buchseite abzulesen ist ein schlechter Weg, es zu lernen. Etwas darin herumzubewegen ist ein guter. Ersetz dein onOverlayUpdate hiermit und füg die beiden neuen Callbacks und die vier Variablen darüber ein.

local turnLeft  = false
local turnRight = false
local tiltUp    = false
local tiltDown  = false

Die kommen ganz oben in die Datei, über alles andere.

function onInputPressed(what)
    if what == SWITCH_LEFT then
        turnLeft = true
    elseif what == SWITCH_RIGHT then
        turnRight = true
    elseif what == SWITCH_UP then
        tiltUp = true
    elseif what == SWITCH_DOWN then
        tiltDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        turnLeft = false
    elseif what == SWITCH_RIGHT then
        turnRight = false
    elseif what == SWITCH_UP then
        tiltUp = false
    elseif what == SWITCH_DOWN then
        tiltDown = false
    end
end


function onOverlayUpdate()
    if turnLeft then
        nodeRotate(box, 0, -1.5, 0)
    end
    if turnRight then
        nodeRotate(box, 0, 1.5, 0)
    end
    if tiltUp then
        nodeRotate(box, -1.5, 0, 0)
    end
    if tiltDown then
        nodeRotate(box, 1.5, 0, 0)
    end

    return OVERLAY_UPDATED
end

onInputPressed und onInputReleased sind Callbacks wie onOverlayUpdate: Du schreibst sie, und Singe ruft sie auf, wenn ein Steuerelement gedrückt oder wieder losgelassen wird. Ein Druck kommt einmal an, nicht immer wieder, solange die Taste gehalten wird, und darum setzt jeder eine Variable, und der Zeichen-Callback erledigt die Arbeit. Dieses Muster — der Druck setzt ein Flag, der Frame liest das Flag — ist der Weg, aus einer Engine, die dir nur Änderungen meldet, ein „solange die Taste gehalten wird“ herauszuholen.

Die Namen mit SWITCH_ kommen von der Engine selbst, also muss nichts geladen werden, um sie zu benutzen. Sie sind auch keine Tasten. Sie sind das, was ein Steuerelement bedeutet, und controls.cfg entscheidet, welche Taste, welcher Knopf oder welche Stick-Richtung jeden davon erzeugt. Deine Pfeiltasten schicken heute SWITCH_LEFT und seine Freunde; der Stick eines Gamepads schickt dasselbe, und dein Skript merkt den Unterschied nie.

Die Vorzeichen sind so gewählt, dass jeder Pfeil die Seite, auf die du schaust, in die Richtung bewegt, die du gedrückt hast. Eine Drehung um Y um einen positiven Winkel schwenkt diese vordere Seite nach rechts, also verlangt der linke Pfeil einen negativen. Wenn dir das verkehrt herum vorkommt, tausch die Vorzeichen; es ist deine Steuerung, nicht die der Engine.

Das Overlay liegt immer noch oben

Füg diese Zeilen in onOverlayUpdate über dem return ein.

    local pitch, yaw = nodeGetRotation(box)

    overlayClear()
    overlayPrint(2, 2, "Arrow keys turn the box.")
    overlayPrint(2, 4, "yaw " .. math.floor(yaw) .. "  pitch " .. math.floor(pitch))

Neu ist daran nichts außer dem, worüber es ausgegeben wird. overlayPrint ist der Aufruf aus Lektion eins, der in Zeichenzellen zählt und keine geladene Schriftart braucht, und er zeichnet über eine 3D-Szene, ohne dass man ihm irgendetwas davon gesagt hat.

So ist die Anordnung, und es lohnt sich, es klar auszusprechen: Singe zeichnet zuerst das Video, dann die 3D-Szene darüber, dann das Overlay darüber. Deine Punktzahl, deine Leben, dein Timer, dein Fadenkreuz und deine Untertitel sind alles Arbeit fürs Overlay, genau wie in Teil zwei. Ein 3D-Spiel zeigt seine Punktzahl in der Ecke mit denselben fünf Zeilen, die ein 2D-Spiel benutzt.

nodeGetRotation gibt drei Zahlen zurück, die Winkel um X, Y und Z, und diese Zeile behält die ersten beiden in pitch und yaw. Das sind die üblichen Namen dafür: Pitch ist die Nase, die hoch- und runtergeht, Yaw ist das Drehen nach links und rechts. math.floor wirft die Nachkommastellen weg, damit die Zahlen aufhören zu flackern.

Beobachte den Yaw, während du den linken Pfeil gedrückt hältst. Er zählt über -180 hinaus herunter und kommt von 180 wieder herum, weil die Winkel als die kleinste Drehung gemeldet werden, die dorthin führt, und nicht als laufende Summe. Wenn dein Spiel wissen muss, wie oft sich der Spieler gedreht hat, zähl das selbst mit.

Probier es aus

  1. Beweg die Kamera. Ändere nodeSetPosition(camera, 0, 2, 7) in (0, 8, 7), dann in (7, 2, 7), dann in (0, 0.2, 7). Jedes Mal hält nodeLookAt die Kiste in der Mitte, also bekommst du für eine einzige Zahl einen anderen Blick auf dieselbe Szene.

  2. Wechsle das Objektiv. Probier cameraSetPerspective(30, 0.1, 100), dann (90, 0.1, 100), ohne die Kamera zu bewegen. Ein Spiel fühlt sich mit einem weiten Sichtfeld schnell an und mit einem engen gemessen, und das ist der billigste Stimmungsregler, den es gibt.

  3. Stell eine zweite Kiste hinein. Kopier die zwei Zeilen, die die Kiste gemacht haben, benenn die Variable in mark um und gib ihr nodeSetPosition(mark, 3, 0, 0) und nodeSetScale(mark, 0.3). Jetzt hast du einen Orientierungspunkt, an dem du die erste Kiste messen kannst. Stell sie nacheinander auf (0, 3, 0) und (0, 0, -3) und sag laut, welche Achse welche ist.

  4. Teil das Mesh. Statt meshBox zweimal aufzurufen, bewahr das erste in einer Variablen auf und gib beiden Knoten dasselbe Handle. Nichts sieht anders aus. Genau darum geht es: eine Form, zwei Orte.

  5. Häng die Kamera an die Kiste. Behalte die zweite Kiste aus dem letzten Schritt, sonst bleibt nichts übrig, woran man die Bewegung sehen kann. Dann schlag nodeSetParent in der Referenz nach und häng die Kamera unter die erste Kiste. Halte eine Pfeiltaste gedrückt: Die Kamera fährt die Drehung der Kiste mit, also steht die Kiste still, und der Rest der Szene schwenkt vorbei. Das ist eine Zeile von einer Ego-Perspektive entfernt, und so findest du auch heraus, dass eine Verfolgerkamera einen Elternknoten will statt Rechnerei.

Mach es absichtlich kaputt

Vertipp dich beim Namen des Materials. Ändere die Zeile mit nodeSetMesh so, dass sie pain statt paint benutzt:

nodeSetMesh(box, meshBox(2, 2, 2), pain)

Singe hält an, bevor das Spiel startet, und gibt etwas aus wie:

15:nodeSetMesh:  Argument 3 must be a number.

Das ist eine andere Form von Fehler als die in Lektion eins, und er kommt von der Engine statt von Lua. Die Zahl vorn ist die Zeile. Der Name danach ist der Aufruf, der sich beschwert hat. Die Beschwerde selbst ist, dass das dritte Ding, das du ihm gegeben hast, keine Zahl war.

Es lohnt sich, dem Grund nachzugehen, denn er erklärt eine ganze Familie von Fehlern. pain ist eine Variable, die nie einen Wert bekommen hat, und in Lua ist eine leere Variable nil — der Wert, der „hier ist nichts“ bedeutet. Wenn du nil an einen Aufruf übergibst, der ein Material-Handle will, bekommst du genau das. Wenn du von einem Engine-Aufruf „must be a number“ siehst, such in dieser Zeile nach einem falsch geschriebenen Variablennamen oder nach einem Handle, das du vergessen hast aufzubewahren.

Was du gelernt hast

  • sceneEnable(true) schaltet die 3D-Ebene ein, und in 3D wird nichts gezeichnet, bis du es aufrufst.

  • Ein Knoten ist ein Ort in der Welt mit einer Position, einer Drehung und einer Skalierung. Meshes, Lichter und Kameras hängen alle an Knoten.

  • Ein Mesh ist die Form und ein Material das Aussehen, und jedes davon kann von beliebig vielen Knoten geteilt werden.

  • X ist rechts, Y ist oben, und negatives Z ist die Richtung, in die die Kamera schaut.

  • nodeSetPosition und nodeSetRotation setzen einen Wert direkt; nodeMove und nodeRotate ändern ihn um einen Betrag.

  • Jeder Knoten kann die Kamera sein. nodeLookAt richtet sie aus, und cameraSet wählt sie.

  • Das Sichtfeld in cameraSetPerspective ändert, wie sich die Szene anfühlt, ohne etwas zu bewegen.

  • Eine Szene ohne Licht ist schwarz, und das ist das Erste, was du prüfst, wenn nichts erscheint.

  • Das Overlay ist immer noch da, immer noch oben und immer noch der Ort für deine Punktzahl.

Beim nächsten Mal

Eine Kiste ist ein armseliger Drache. Die nächste Lektion lädt ein echtes Modell — eines, das die Engine schon in deinen Arbeitsordner entpackt hat, also gibt es nichts herunterzuladen und nichts zu zeichnen — stellt es auf den Boden und beleuchtet es richtig. Das ist Lektion dreiundzwanzig.

Lektion 23: Modelle und Licht

Die fertige Lektion

Mit Kisten und Kugeln kommst du weit, aber früher oder später will das Spiel einen Drachen. Ein Modell ist eine Form, die jemand anders in einem Modellierprogramm gebaut hat: Hunderte von Dreiecken, eigene Farben und Oberflächen, manchmal ein Skelett und Bewegungen dazu, alles in einer Datei. Eins zu laden sind zwei Zeilen. Dass es nach etwas aussieht, ist eine Frage des Lichts, und Licht ist der größte Teil dieser Lektion.

Du brauchst keine Grafiken und keine Downloads. Als du Singe zum allerersten Mal gestartet hast, hat es einen Ordner namens Singe in deinen Arbeitsordner entpackt, und darin liegen zwei Modelle: DragonModel.glb, der Drache aus dem eigenen Titelbildschirm der Engine, und SingeText.glb, der Schriftzug darunter. Diese Lektion benutzt den Drachen.

Die Szene drumherum

Ein Modell braucht einen Platz zum Stehen. Leg einen Ordner an, leg darin dragon.singe an und fang mit einem Boden und einer Kamera an. Wenn du Lektion zweiundzwanzig gemacht hast, ist nichts davon neu; wenn nicht, ist es eine eingeschaltete Szene, eine flache Platte zum Draufstehen und ein Punkt, von dem aus man schaut.

sceneEnable(true)
sceneSetBackground(10, 12, 20)
sceneSetAmbient(28, 30, 38)

local stone = materialNew()
materialSetColor(stone, 105, 105, 115)
materialSetRoughness(stone, 0.9)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(24, 0.4, 24), stone)
nodeSetPosition(floor, 0, -0.2, 0)

local camera = nodeNew()
nodeSetPosition(camera, 0, 2.6, 9)
nodeLookAt(camera, 0, 1.7, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 200)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Starte es mit Singe -R dragon. Eine graue Platte, leicht von oben gesehen, vor einem dunkelblauen Hintergrund. Die Platte ist vierundzwanzig Einheiten breit und etwas weniger als eine halbe Einheit dick, und wenn du sie auf y = -0.2 setzt, liegt ihre Oberseite genau bei y = 0, und damit ist alles, was du später platzierst, leicht zu durchschauen: Der Boden ist null.

Den Drachen laden

Zwei Zeilen.

local dragonModel = modelLoad("Singe/DragonModel.glb")
local dragon      = modelInstance(dragonModel)

Setz sie hinter den Boden und speichere. Ein Drache erscheint, und er ist viel zu groß für das Bild — du schaust auf seine Mitte.

Was gerade passiert ist

Die beiden Zeilen haben verschiedene Aufgaben, und der Unterschied ist wichtig.

modelLoad liest die Datei, gibt die Formen und ihre Oberflächen an die Grafikkarte und hält das Ganze bereit. Das ist der langsame Aufruf. Mach ihn einmal, wenn das Spiel startet, und nie mitten im Spiel.

modelInstance stellt eine Kopie in die Szene und gibt dir einen Knoten zurück — einen gewöhnlichen Knoten, dieselbe Art, die dir nodeNew gibt, den du mit den Aufrufen, die du schon kennst, platzierst, drehst, skalierst und löschst. Instanziieren ist der billige Aufruf. Lade einen Baum, instanziiere ihn vierzigmal, und du hast einen Wald, mit einer Kopie der Formen auf der Grafikkarte und vierzig Stellen, an denen sie gezeichnet werden.

Mit dem Modell kommt alles, was in der Datei war: die Formen, die Oberflächen und ihre Farben, die Anordnung der Teile, ein Skelett, falls es eins gibt, und Bewegungen, falls es welche gibt. Für ein geladenes Modell baust du keine Materialien; es hat seine eigenen mitgebracht.

Größe, und das Erste, was schiefgeht

Der Drache ist ungefähr siebeneinhalb Einheiten hoch. Deine Kamera steht neun Einheiten entfernt. Darum füllt er das Fenster.

nodeSetScale(dragon, 0.5)

Füg das unter der Zeile mit modelInstance ein. Jetzt ist er keine vier Einheiten hoch, steht auf dem Boden und passt ins Bild.

Das ist kein Detail; es ist das häufigste erste Problem mit einem Modell, und es hat zwei Gesichter. Ein Modell, das in Zentimetern gebaut wurde, kommt hundertmal zu groß an, und du siehst eine riesige Fläche, die den Bildschirm füllt, was meistens nach „meine Szene ist kaputt“ aussieht statt nach „ich stecke im Hals des Drachen“. Ein Modell, das in irgendeiner anderen Einheit gebaut wurde, kommt so klein an, dass es ein Punkt ist oder vor dem Hintergrund unsichtbar, und du nimmst an, dass die Datei nicht geladen wurde.

Die Lösung ist immer dieselbe: eine Skalierung auf dem Knoten der Instanz. Nicht auf den Teilen, nicht im Modellierprogramm, wenn es sich vermeiden lässt, sondern ein nodeSetScale auf dem Knoten, den dir modelInstance gegeben hat, gewählt, indem du eine Zahl ausprobierst und hinsiehst. 0.01 und 100 sind beides völlig gewöhnliche Antworten.

Wenn du nicht sagen kannst, wie groß etwas ist, verschaff dir ein Lineal. Stell eine Kiste von einer Einheit daneben:

local ruler = nodeNew()
nodeSetMesh(ruler, meshBox(1, 1, 1), stone)
nodeSetPosition(ruler, 3, 0.5, 0)

Ein Ding in Kistengröße neben dem Modell sagt dir auf einen Blick, ob das Modell ein Drache oder ein Berg ist. Nimm das Lineal wieder heraus, wenn du fertig bist.

Wenn du ihn schon platzierst, dreh ihn so, dass er dich ansieht:

nodeSetRotation(dragon, 0, -60, 0)

Der Drache wurde mit Blick entlang des positiven X modelliert, also nach rechts, darum steht er am Anfang im Profil. Eine Drehung um Y bringt ihn herum zur Kamera. Die „Vorderseite“ eines Modells ist die Richtung, die die Person gewählt hat, die es gebaut hat, und um sie herauszufinden, musst du es drehen und hinsehen.

Licht

Starte, was du jetzt hast. Der Drache ist da, und er ist trostlos: eine flache, trübe Form ohne Glanzlichter und ohne Schatten. Das liegt daran, dass das einzige Licht in deiner Szene das Umgebungslicht ist, das schwache Leuchten von überall, das sceneSetAmbient einstellt.

Das ist die allerhäufigste Enttäuschung in 3D, und sie passiert jedem: Das Modell wurde einwandfrei geladen, und die Szene ist schwarz oder fast schwarz, weil nichts darauf scheint. Bevor du die Datei verdächtigst, stell ein Licht hinein.

Es gibt drei Arten, und jede ist ein Knoten, also platzierst du sie und richtest sie aus mit nodeSetPosition und nodeLookAt, wie alles andere.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -6, 9, 7)
nodeLookAt(sun, 0, 1.5, 0)
lightSetColor(sun, 255, 244, 224)
lightSetIntensity(sun, 1.8)
lightSetShadow(sun, true)

LIGHT_DIRECTIONAL ist eine Sonne. Sie wird behandelt, als wäre sie unendlich weit weg, also zählt nur die Richtung, in die sie scheint, und alles in der Szene bekommt gleich viel davon. Ihre Position ist dazu da, dass nodeLookAt sie damit ausrichten kann. Das ist das Licht, das einer Szene ihre Hauptform gibt, und die meisten Szenen wollen genau eins.

lightSetIntensity ist die Helligkeit. Bei einem Richtungslicht macht 1 eine weiße Fläche, die ihm direkt zugewandt ist, ganz weiß, also ist 1.8 ein heller Tag. lightSetColor färbt es: ein leicht warmes Weiß für die Sonne, ein kaltes Blau für Mondlicht und der Abschnitt Licht in der Referenz für den Rest.

lightSetShadow(sun, true) sorgt dafür, dass der Drache auf dem Boden sitzt, statt darüber zu schweben. Schatten sind standardmäßig aus, weil jedes Licht, das Schatten wirft, in jedem Frame einen weiteren Durchgang über die ganze Szene kostet. Schalte sie für das eine Licht ein, auf das es ankommt, und lass sie bei den anderen aus; ein kleiner Rechner wird es dir danken.

local torch = lightNew(LIGHT_POINT)
nodeSetPosition(torch, 3.5, 1.2, 3.0)
lightSetColor(torch, 255, 150, 70)
lightSetIntensity(torch, 14)
lightSetRange(torch, 12)

LIGHT_POINT ist eine Glühbirne. Sie sitzt an einer Stelle, scheint in alle Richtungen und wird mit der Entfernung schwächer. Dieses Schwächerwerden ist der Grund, warum die Zahl 14 ist und nicht 1: Die Intensität eines Punktlichts ist seine Helligkeit direkt am Licht, und wenn es ein paar Einheiten weit gekommen ist, ist nicht mehr viel übrig. Eine Glühbirne, die einen Raum beleuchtet, will meistens etwas im zweistelligen Bereich. Wenn ein Punktlicht scheinbar nichts tut, ist das fast immer der Grund.

lightSetRange sagt, wie weit es reicht, bevor es ganz aufhört, und das verhindert, dass eine Lampe in einem Raum den nächsten schwach mitbeleuchtet, und kostet nichts.

Die dritte Art ist LIGHT_SPOT, ein Kegel, der entlang des eigenen negativen Z des Knotens zeigt, mit lightSetCone für den Winkel der hellen Mitte und des weichen Rands: eine Taschenlampe, ein Scheinwerfer, ein Suchscheinwerfer. Bis zu acht Lichter leuchten gleichzeitig, und das ist mehr, als die meisten Szenen brauchen. Wenn du mehr willst, willst du eigentlich weniger.

Starte es jetzt. Eine fast weiße Sonne von links, ein warmes orangefarbenes Leuchten von rechts, ein Schatten auf der Platte und ein Drache mit einer Vorder- und einer Rückseite.

Materialien, so weit du sie heute brauchst

Der Drache hat seine eigenen Materialien mitgebracht, und es sind drei: ein dunkles Metall, ein helleres champagnerfarbenes Metall und ein blasses Glas, in das man ein Stückchen hineinsehen kann. Die meisten seiner Teile sind aus mehr als einem davon geschnitten. Du musst nichts davon anfassen, und meistens solltest du es auch nicht.

Wenn du doch ändern willst, wie ein Teil eines Modells aussieht, machst du ein Material wie in Lektion zweiundzwanzig und legst es auf das Teil:

local red = materialNew()
materialSetColor(red, 220, 50, 40)
materialSetRoughness(red, 0.4)
nodeSetMaterial(nodeFind("crest", dragon), red)

nodeFind(name, root) durchsucht eine Modellinstanz nach einem Teil mit dem Namen, den es in der Datei hatte, und gibt seinen Knoten zurück, oder nil, wenn es keinen solchen Namen gibt. So greifst du in ein Modell hinein: ein Geschützturm, ein Rad, eine Hand, an die man eine Fackel hängt, oder der Kamm des Drachen.

Der Kamm ist ein Stück aus einem Material, also trägt sein Knoten die Form selbst, und die Zeile oben malt ihn neu an. Ein Teil, das aus mehreren Materialien gebaut ist, wird als Knoten mit einem Kind pro Stück gespeichert, und ein Material auf dem Elternknoten ändert nichts, was man sieht. Wenn ein nodeSetMaterial scheinbar nichts tut, ist das der Grund, und nodeGetChildren zeigt dir, was darunter liegt.

Vier Zahlen beschreiben die meisten Oberflächen. Die Farbe, aus materialSetColor. materialSetRoughness, von 0 für einen Spiegel bis 1 für Kreide. materialSetMetallic, das für fast alles 0 ist — Farbe, Holz, Plastik, Haut — und 1 für echtes Metall, und die Werte dazwischen braucht man kaum. Und materialSetEmissive, das eine Oberfläche in ihrer eigenen Farbe leuchten lässt, für Bildschirme, Lampen und glühendes Eisen, ohne etwas drumherum zu beleuchten.

Eins solltest du über Metall wissen: Eine Metalloberfläche zeigt dir ihre Spiegelungen statt einer eigenen Farbe, also sieht sie in einer Szene, in der es nichts zu spiegeln gibt, dunkel und stumpf aus. Darum braucht das dunkle Metall des Drachen die Sonne, um lebendig zu werden. Die richtige Lösung ist ein Himmel (sceneSetSky), der die Szene in ein Panorama hüllt, das hinter allem zu sehen ist und sie zugleich beleuchtet; „Das Aussehen des Frames“ in der Referenz behandelt das.

Bewegung, die das Modell mitbringt

Viele Modelle bringen Animationen mit: ein Gehen, ein Rennen, ein Herumstehen, eine Tür, die aufgeht. Sie sind in der Datei gespeichert, und eine abzuspielen ist ein einziger Aufruf auf dem Wurzelknoten der Instanz.

animationPlay(dragon, "Walk", true)

Das zweite Argument ist der Name des Clips, wie die Datei ihn speichert, oder seine Nummer. true heißt: endlos in einer Schleife. Zwei weitere, optionale Zahlen setzen die Geschwindigkeit und die Überblendung: animationPlay(hero, "Run", true, 1.2, 0.4) spielt das Rennen ein Fünftel schneller ab und blendet über vier Zehntelsekunden hinein, sodass aus einem Gehen ohne Ruck ein Rennen wird. animationStop, animationPause und animationIsPlaying tun, was ihre Namen sagen.

Diese Zeile kannst du noch nicht ausführen, und hier ist der ehrliche Grund: Der Drache in deinem Ordner Singe hat keine Animationen. Er ist ein Modell, keine Vorstellung. Nach einem Clip zu fragen, der nicht da ist, hält das Spiel mit einem Fehler an, also nimm nie etwas an — frag:

local clips = modelGetAnimations(dragonModel)

if #clips > 0 then
    animationPlay(dragon, 1, true)
else
    debugPrint("DragonModel.glb carries no animation clips.  The wings are turned by hand.")
end

modelGetAnimations gibt eine Tabelle mit den Namen der Clips in der Datei zurück, der Reihe nach, also ist clips[1] der erste und #clips die Anzahl — die Tabellen-Aufrufe aus Lektion sechs, auf einer Tabelle, die die Engine gefüllt hat. Starte es und beobachte die Konsole: Die Meldung erscheint, weil diese Anzahl null ist.

Gewöhn dir diese Prüfung bei jedem Modell an, das du nicht selbst gemacht hast. Sie kostet drei Zeilen und macht aus „das Spiel ist beim Start gestorben“ einen Satz im Log.

Die Teile selbst bewegen

Ein Modell ohne Animationen ist keine Statue. Seine Teile sind Knoten, und Knoten drehen sich.

local wingLeft  = nodeFind("wingL", dragon)
local wingRight = nodeFind("wingR", dragon)
function onOverlayUpdate()
    local flap = math.sin(singeGetTicks() / 260) * 22

    nodeSetRotation(wingLeft, flap, 0, 0)
    nodeSetRotation(wingRight, -flap, 0, 0)
    nodeRotate(dragon, 0, 0.25, 0)

    overlayClear()
    overlayPrint(2, 2, "Singe/DragonModel.glb")
    overlayPrint(2, 4, "animation clips in the file: " .. #clips)
    return OVERLAY_UPDATED
end

Speichere. Die Flügel schlagen, der Drache dreht sich langsam auf der Stelle, und der Schatten auf dem Boden schlägt mit.

singeGetTicks ist die Anzahl der Millisekunden, seit die Engine gestartet ist, also steigt sie für immer gleichmäßig an. math.sin nimmt diese steigende Zahl und gibt einen Wert zurück, der gleichmäßig von -1 bis 1 und wieder zurück gleitet, ein voller Flügelschlag ungefähr alle anderthalb Sekunden bei diesem Teiler. Die Multiplikation mit 22 macht daraus einen Winkel von zweiundzwanzig Grad in jede Richtung. Teilst du durch eine größere Zahl, wird der Schlag langsamer; multiplizierst du mit einer größeren Zahl, wird er weiter. Diese eine Zeile ist die billigste Animation, die es gibt, und es lohnt sich, sie in der Tasche zu behalten.

Die Flügel drehen sich um ihre eigene X-Achse, und zwar um die Schulter statt um die Mitte des Tiers, weil der, der die Datei gebaut hat, den Knoten jedes Teils dorthin gesetzt hat, wo das Gelenk hingehört. Ein Modell, das nicht so gebaut wurde, schwenkt seine Teile stattdessen um die Mitte des Modells, und die Lösung ist, den Knoten des Teils zu verschieben; der Abschnitt Knoten in der Referenz behandelt das.

Achte darauf, dass das Drehen des ganzen Drachen dem Drehen der Flügel nicht in die Quere kommt. Die Teile hängen unter der Wurzel der Instanz, also nimmt eine Drehung der Wurzel alles mit, und die eigene Drehung jedes Flügels kommt obendrauf. Diese Anordnung — ein Ding in einem Ding in einem Ding, und jedes bewegt sich in der Welt seines Elternknotens — ist das, wofür ein Szenenbaum da ist.

Deine eigenen Modelle

Wenn du eigene machst, exportiere aus Blender — oder Maya, 3ds Max oder irgendetwas anderem Modernen — als glTF 2.0 binary, also als .glb-Datei. Das ist die Standardwahl von Blender und das einzige Modellformat, das Singe liest.

Die eine Regel ist, dass die Datei in sich geschlossen sein muss: die Formen, die Bilder darauf und die Bewegungen, alles in der einen .glb. Eine Datei, die auf eine .bin oder eine .png daneben verweist, wird abgelehnt, mit einer Meldung, die nennt, was sie wollte. Der Exporter von Blender macht mit seinen Standardeinstellungen das Richtige.

Nicht alles, was du bauen kannst, übersteht die Reise. Der Abschnitt „Modelle und Animation“ in der Referenz, im Kapitel 3D-Szenen, ist die Liste: was gelesen wird, was stillschweigend ignoriert wird, und die Grenzen (ein Skelett darf zum Beispiel bis zu hundertachtundzwanzig Gelenke haben). Lies ihn einmal, bevor du ein Wochenende in ein Modell steckst, nicht danach.

Probier es aus

  1. Mach das Licht aus. Kommentier den ganzen sun-Block aus, indem du -- an den Anfang jeder Zeile setzt, und starte es. Dann mach dasselbe mit sceneSetAmbient. Merk dir, wie das aussieht, denn eines Tages passiert es, ohne dass du es wolltest.

  2. Beweg die Sonne. Ändere nodeLookAt(sun, 0, 1.5, 0) in nodeLookAt(sun, 0, 20, 0), sodass die Sonne über den Kopf des Drachen zielt. Sieh zu, wie der Schatten und die Glanzlichter verschwinden. Ein Licht auszurichten ist keine Verzierung.

  3. Heiz die Fackel an. Erhöh die Intensität des Punktlichts von 14 auf 60 und senk seine Reichweite auf 4. Dann setz es auf (0, 6, 0), über den Drachen. Ein Punktlicht ist eine Glühbirne, und du entscheidest, wo die Glühbirne hängt.

  4. Instanziiere ihn zweimal. Ruf modelInstance(dragonModel) ein zweites Mal auf, bewahr das Ergebnis in einer anderen Variablen auf, skalier es und setz es auf (-4, 0, -3). Einmal geladen, zwei Drachen. Dann versuch stattdessen, das Modell zweimal zu laden, und versteh, warum du das nicht tun solltest.

  5. Finde ein anderes Teil. Die Teile des Drachen heißen head, jaw, neck, tail, body, crest, hornL, hornR, wingL, wingR, foreLegL, foreLegR, hindLegL und hindLegR. Lass den Schwanz mit seinem eigenen math.sin in einer anderen Geschwindigkeit schwingen als die Flügel. Dann probier nodeFind("wings", dragon) und sieh, was ein falscher Name anrichtet, wenn du das nil direkt an nodeSetRotation weitergibst.

Mach es absichtlich kaputt

Ändere den Dateinamen in Singe/Dragonmodel.glb — ein einziger Großbuchstabe Unterschied — und starte es. Singe hält an, bevor das Spiel startet:

13:modelLoad:  Unable to read Singe/Dragonmodel.glb.

Die Zeile, der Aufruf und die Beschwerde, in dieser Reihenfolge. „Unable to read“ heißt, dass die Engine nachgesehen und nichts gefunden hat, und das ist fast immer eins von drei Dingen: Der Name ist falsch geschrieben, die Groß- und Kleinschreibung stimmt nicht, oder die Datei liegt nicht da, wo du gesagt hast. Unter Windows wäre die Groß- und Kleinschreibung verziehen worden, und dein Spiel würde dann bei allen unter Linux scheitern, und das ist ein schlimmerer Fehler als dieser. Tipp Namen genau.

Dieselbe Meldung mit einem richtigen Dateinamen heißt, dass die Datei nicht dort liegt, wo die Engine nachgesehen hat. Der Ordner Singe wird in dem Ordner angelegt, aus dem du die Engine startest, also zeigt Singe/DragonModel.glb ebenfalls woandershin, wenn du Singe von woanders gestartet hast.

Was du gelernt hast

  • modelLoad liest eine .glb einmal; modelInstance setzt so oft, wie du willst, Kopien davon in die Szene.

  • Die Wurzel einer Instanz ist ein gewöhnlicher Knoten: Platzier, dreh, skalier und lösch ihn wie jeden anderen.

  • Ein Modell bringt seine eigenen Formen und Materialien mit.

  • Ein Modell kommt in der Größe an, die sein Autor benutzt hat, und darum gehört ein nodeSetScale auf der Instanz zum Platzieren dazu.

  • Eine Szene ohne Licht ist schwarz oder fast schwarz, und das ist das Erste, was du prüfst, wenn ein Modell falsch aussieht.

  • Ein Richtungslicht ist eine Sonne, ein Punktlicht ist eine Glühbirne, die mit der Entfernung schwächer wird und eine viel größere Intensität braucht, und ein Spotlicht ist ein Kegel.

  • Schatten sind aus, bis lightSetShadow sie einschaltet, und jeder kostet etwas.

  • nodeFind erreicht ein Teil eines Modells über seinen Namen aus der Datei.

  • modelGetAnimations sagt, was ein Modell abspielen kann, und nach einem Clip zu fragen, der nicht da ist, ist ein Fehler.

  • Ein Modell ohne Animationen lässt sich trotzdem Teil für Teil bewegen.

Beim nächsten Mal

Alles in dieser Szene bewegt sich, weil du es ihm gesagt hast, Frame für Frame. Die nächste Lektion gibt diese Arbeit an eine Physik-Engine ab: Kisten, die fallen, rollen, sich stapeln und sich gegenseitig umwerfen, ohne dass du eine Zeile Rechnerei schreibst — und die schwierigere Frage, wann du sie das tun lassen solltest. Das ist Lektion vierundzwanzig.

Lektion 24: Physik

Die fertige Lektion

Bis jetzt hat sich alles, was sich in deinen Spielen bewegt hat, bewegt, weil du gerechnet hast. Eine Zahl ist in jedem Frame um zwei gestiegen; wenn sie über einen Rand hinaus war, hast du sie umgedreht. Das ist der ehrliche Weg, ein Spiel in Bewegung zu bringen, und die meisten Spiele bestehen daraus.

Diese Lektion gibt die Rechnerei an jemand anderen ab. Eine Physik-Engine simuliert die Welt — Schwerkraft, Fallen, Rutschen, Stapeln, Abprallen, Rollen und Dinge, die zusammenstoßen — und bewegt deine Knoten für dich. Am Ende hast du eine Wanne voller Kisten und eine Kanone, die sie umwirft. Im letzten Abschnitt geht es darum, wann du nichts davon tun solltest, und das ist der Teil, den du zweimal lesen solltest.

Was sie tut und was nicht

Gib einem Knoten einen Körper, und die Simulation übernimmt ihn. Von da an fällt er durch die Schwerkraft, landet auf dem, was unter ihm ist, kippt, wenn er außerhalb der Mitte getroffen wird, liegt ruhig in einem Stapel, rutscht aus, bis er steht, und der Knoten folgt, wohin die Simulation ihn auch setzt. Du setzt seine Position nicht mehr selbst. Das ist der Handel: Du gibst Position und Drehung dieses Knotens ab und bekommst dafür Verhalten, das du nicht schreiben musstest.

Was sie nicht tut, ist irgendetwas, das dein Spiel betrifft. Sie weiß nicht, was eine Punktzahl ist, oder dass die rote Kiste die ist, die Punkte bringt, oder dass das Herunterfallen von der Kante ein Leben kostet. Sie animiert keine gehende Figur, sie weiß nicht, wie sich ein Sprung anfühlen soll, und sie wird ein Objekt nicht so bewegen, dass du es genau vorhersagen kannst. Physik ist eine Maschine, die glaubwürdiges Chaos erzeugt.

Die Einheiten sind Meter, Kilogramm und Sekunden. Die Schwerkraft ist 0, -9.81, 0, wenn du nichts anderes sagst, und das ist die der Erde, nach unten, in Metern pro Sekunde zum Quadrat. Eine Kiste, die eine Einheit breit ist, ist einen Meter breit, und sie fällt auch so. Wenn deine Szene in einem anderen Maßstab gebaut ist, sieht alles aus, als fiele es durch Sirup oder durch einen Zeichentrickfilm, und die Lösung ist, in Metern zu bauen.

Ein Boden und eine Kiste

Leg einen Ordner an, leg crates.singe an und tipp das ein. Es ist eine Szene, eine Platte, eine Kiste über der Platte und drei Zeilen Physik.

sceneEnable(true)
sceneSetBackground(16, 18, 26)
sceneSetAmbient(40, 42, 50)

local stone = materialNew()
materialSetColor(stone, 110, 110, 120)
materialSetRoughness(stone, 0.9)

local wood = materialNew()
materialSetColor(wood, 190, 140, 80)
materialSetRoughness(wood, 0.8)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(16, 0.4, 16), stone)
nodeSetPosition(floor, 0, -0.2, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

local crate = nodeNew()
nodeSetMesh(crate, meshBox(0.8, 0.8, 0.8), wood)
nodeSetPosition(crate, 0.3, 4, 0)
nodeSetRotation(crate, 20, 0, 15)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
bodySetMass(crate, 4)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -5, 9, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 1.7)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 4, 11)
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Starte es mit Singe -R crates. Die Kiste fällt aus vier Metern Höhe, landet auf einer Ecke, weil du sie gekippt hast, schaukelt auf eine Seite und bleibt liegen. Drück F5, um es noch einmal zu starten und es dir noch einmal anzusehen.

Nichts in onOverlayUpdate bewegt irgendetwas. Die beiden Aufrufe von bodyNew haben alles erledigt.

Was gerade passiert ist

bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

bodyNew gibt einem Knoten einen Körper. Es nimmt den Knoten, welche Art von Körper es ist, welche Form die Simulation dafür benutzen soll, und die Größen dieser Form.

Es gibt drei Arten, und die richtige auszuwählen ist der größte Teil der Kunst.

  • BODY_STATIC bewegt sich nie. Er wird dort hingesetzt, wo der Knoten ist, wenn du den Körper erzeugst, und dort bleibt er für immer. Böden, Wände, der Erdboden, der Automat, das Level. Den Knoten danach zu bewegen bewegt den Körper nicht, und das ist eine Falle, die man sich merken sollte: statisch heißt statisch.

  • BODY_DYNAMIC wird von der Simulation bewegt. Er fällt, prallt ab, rutscht, wird geschubst und zieht seinen Knoten mit. Das ist eine Kiste, ein Fass, ein Ball, ein Trümmerstück.

  • BODY_KINEMATIC geht dorthin, wo du seinen Knoten hinsetzt, und schiebt dynamische Körper aus dem Weg, ohne je selbst geschubst zu werden. Eine bewegliche Plattform, ein Schläger, eine Tür auf einer Schiene, die schwingende Faust einer Figur. Er ist die Brücke zwischen deiner Rechnerei und der Simulation: Du steuerst ihn, er steuert sie.

Die Form ist nicht das Mesh. Sie ist ein grober Ersatz, den die Simulation benutzt, weil sie Fragen über einen Quader viel schneller beantworten kann als über neunhundert Dreiecke. SHAPE_BOX nimmt eine Breite, eine Höhe und eine Tiefe; SHAPE_SPHERE nimmt einen Radius; SHAPE_CAPSULE und SHAPE_CYLINDER nehmen einen Radius und eine Höhe. Es gibt SHAPE_HULL, das das Mesh unter dem Knoten wie mit Schrumpffolie umhüllt — die übliche Antwort für ein Modell — und SHAPE_MESH, die exakten Dreiecke, die statische Kulissen benutzen dürfen und ein fallendes Objekt nicht.

Die Größen richtig hinzubekommen ist deine Sache. Nichts prüft, ob der Körper, den du beschrieben hast, zu dem Mesh passt, das du gezeichnet hast, und eine Kiste, die mit 0.8 gezeichnet und mit einem Körper von 2 erzeugt wurde, schwebt über dem Boden und wirft Dinge aus der Entfernung um. Wenn sich etwas verhält, als hätte es eine andere Größe, dann hat es die auch.

bodySetMass(crate, 4)

Die Masse eines dynamischen Körpers ergibt sich aus seiner Form bei der Dichte von Wasser, und das macht Dinge viel schwerer, als du erwartest: Ein Quader von der Größe einer Tür wiegt ungefähr hundertvierzig Kilogramm, und nichts, was du darauf werfen kannst, bewegt ihn. Setz die Masse von allem, was sich leicht anfühlen soll. Vier Kilogramm sind eine Kiste, die du hochheben könntest.

Die Masse ist wichtig, weil Kräfte durch sie geteilt werden. Derselbe Stoß bewegt ein leichtes Ding weiter, und es braucht einen Impuls von Masse mal Geschwindigkeit, um etwas mit dieser Geschwindigkeit in Bewegung zu setzen. Stimm zuerst die Masse ab und danach die Kräfte, sonst drehst du dich im Kreis.

Dinge in Bewegung bringen

Drei Aufrufe schubsen einen dynamischen Körper herum, und sie sind nicht austauschbar.

bodySetVelocity(node, x, y, z) sagt „du bewegst dich jetzt mit dieser Geschwindigkeit“ und ersetzt, was er vorher getan hat. Das ist ein Aufschlag, ein Abschuss, ein Erscheinen mit schon etwas Tempo.

bodyApplyImpulse(node, ix, iy, iz) ist ein Treffer: ein Tritt, eine Explosion, ein Schläger, der einen Ball trifft. Er kommt zu dem dazu, was der Körper schon getan hat. Gib ihm als drei weitere Zahlen einen Punkt in der Welt, und er trifft dort statt in der Mitte, sodass eine Kiste, die oben getroffen wird, umkippt, statt zu rutschen.

bodyApplyForce(node, fx, fy, fz) ist ein Schub, der anhält: eine Rakete, ein Ventilator, ein Förderband. Eine Kraft, die einen Frame lang wirkt, tut fast nichts, und das überrascht Leute, die einen Impuls erwartet haben.

Die Schwerkraft selbst ist physicsSetGravity(x, y, z), und sie gilt für die ganze Welt. Der Mond ist physicsSetGravity(0, -1.62, 0), der Weltraum ist alles Nullen, und ein Spiel mit seitlicher Schwerkraft ist eine Zeile entfernt.

Zwei weitere Einstellungen runden das Gefühl eines Objekts ab. bodySetBounce(node, amount) reicht von 0, das sofort liegen bleibt, bis 1, das mit allem zurückkommt, womit es angekommen ist; der Standard ist ein kaum spürbares 0.1. bodySetFriction(node, amount) ist 0 für Eis und standardmäßig 0.5. Beide werden zwischen den zwei Dingen kombiniert, die sich berühren, also braucht ein vereister Boden die kleine Zahl auf dem Boden, nicht auf allem, was darüber läuft.

Wissen, wann sich Dinge berühren

function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 then
        knocks = knocks + 1
    end
end

knocks ist dort eine Variable von dir, die oben in der Datei mit local knocks = 0 wartet, und das Spielzeug weiter unten gibt sie aus.

onCollision ist ein Callback wie onOverlayUpdate: Du schreibst ihn, die Engine ruft ihn auf. Er kommt einmal für jeden neuen Kontakt — zwei Körper, die sich weiter berühren, melden sich nicht noch einmal — mit beiden Knoten, dem Punkt in der Welt, an dem sie sich getroffen haben, und wie schnell sie sich getroffen haben. Durch die Geschwindigkeit können ein Anstupsen und ein Krachen verschieden klingen, und sie ist der Grund, warum der Test oben das sanfte Setzen eines Stapels ignoriert.

Die andere Hälfte des Paars ist onTrigger. Mach einen Körper mit bodySetTrigger(node, true) zu einem Trigger, und er hört auf, Dinge zu schieben: Er wird zu einem Bereich, der über onTrigger(trigger, other, entered) meldet, was hineinkommt und was ihn verlässt. Eine Ziellinie, ein Türdurchgang, eine Grube, ein Gegenstand zum Aufsammeln. Er ist der 3D-Nachfahre der Kollisionsprüfungen aus Lektion elf, und für alles, was nach „hat der Spieler diese Stelle erreicht“ aussieht, ist er das, was du willst, statt eines festen Körpers.

Das Spielzeug

Jetzt das Ganze. Fang mit dem Skript von oben an und bau es hierzu um: eine Wanne mit vier Wänden, sechs Kisten in einer Pyramide und eine Stahlkugel, die du ausrichten und abschießen kannst. Die Teile kennst du alle schon.

Alles, was sich der neue Code merkt, kommt ganz oben in die Datei, über die Szene:

local crates     = {}
local balls      = {}
local aimX       = 0
local aimLeft    = false
local aimRight   = false
local knocks     = 0
local showShapes = false

Zu den Materialien kommen zwei weitere gemeinsam genutzte Handles: ein poliertes Metall für die Kugel und die Zielmarkierung und ein Kisten-Mesh für alle sechs Kisten.

local steel = materialNew()
materialSetColor(steel, 200, 205, 215)
materialSetMetallic(steel, 1)
materialSetRoughness(steel, 0.25)

local crateMesh = meshBox(0.8, 0.8, 0.8)

Die Wände der Wanne sind vier statische Quader, gemacht in einer Schleife aus einer Tabelle von Platzierungen, und das ist Lektion sechs, die ehrliche Arbeit leistet:

local wallMesh = meshBox(16, 1, 0.4)

for _, side in ipairs({ { 0, -8, 0 }, { 0, 8, 0 }, { -8, 0, 90 }, { 8, 0, 90 } }) do
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, stone)
    nodeSetPosition(wall, side[1], 0.5, side[2])
    nodeSetRotation(wall, 0, side[3], 0)
    bodyNew(wall, BODY_STATIC, SHAPE_BOX, 16, 1, 0.4)
end

Jeder Eintrag ist ein X, ein Z und eine Drehung um Y. Zwei Wände liegen quer hinten und vorn; zwei sind um neunzig Grad gedreht und bilden die Seiten. Ein Mesh reicht für alle vier, und der Körper wird erst erzeugt, nachdem der Knoten platziert und gedreht ist, weil ein statischer Körper die Position und Drehung des Knotens aus dem Moment übernimmt, in dem er erzeugt wird.

Die Kisten kommen aus einer Funktion, damit sechs davon sechs Zeilen sind:

local function crateAt(x, y)
    local crate = nodeNew()

    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, x, y, -2)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
    bodySetMass(crate, 4)
    crates[#crates + 1] = crate
end

Sie bewahrt jede Kiste, die sie macht, in der Tabelle crates auf, und so kann der Zeichen-Callback später allen eine Frage stellen. Sechs Aufrufe bauen die Pyramide, drei auf dem Boden, zwei darauf und eine obendrauf:

crateAt(-0.9, 0.4)
crateAt(0, 0.4)
crateAt(0.9, 0.4)
crateAt(-0.45, 1.25)
crateAt(0.45, 1.25)
crateAt(0, 2.1)

Die oberen Reihen sitzen eine Fingerbreite über denen darunter und fallen in dem Moment an ihren Platz, in dem das Spiel startet. Eine kleine Lücke zu lassen ist einfacher, als genau zu stapeln, und es ist freundlicher zur Simulation, als ihr einen Haufen zu geben, der schon zusammengepresst ist.

Jeder Schuss macht eine neue Kugel:

local function fire()
    local ball = nodeNew()

    nodeSetMesh(ball, meshSphere(0.35, 24), steel)
    nodeSetPosition(ball, aimX, 1.2, 6)
    bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.35)
    bodySetMass(ball, 3)
    bodySetBounce(ball, 0.3)
    bodySetVelocity(ball, 0, 2, -14)
    balls[#balls + 1] = ball
    if #balls > 5 then
        nodeDelete(balls[1])
        table.remove(balls, 1)
    end
end

Sieh dir die Reihenfolge an. Der Knoten wird erzeugt, bekommt eine Form zum Zeichnen, wird platziert und bekommt erst dann einen Körper. Ein dynamischer Körper fängt dort an, wo sein Knoten ist, und danach läuft der Verkehr andersherum: Der Körper bewegt den Knoten. Wenn du die Position eines dynamischen Knotens danach selbst setzt, kämpfst du gegen die Simulation, und die Simulation gewinnt. Wenn etwas bewegt werden muss, gib ihm eine Geschwindigkeit, triff es mit einem Impuls, oder mach es wie hier — erzeug ein neues und lass das alte gehen.

Das alte gehen zu lassen ist nodeDelete, das den Knoten freigibt, alles darunter und den Körper, der darauf mitfuhr. Ohne diese drei Zeilen bliebe jeder Schuss für immer in der Welt, und ein paar hundert Kugeln später würde die Simulation eine Menge Arbeit für Dinge erledigen, die niemand sehen kann. Aufräumen gehört dazu, wenn man Physik benutzt.

Die Steuerung und die Anzeige sind der Rest:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        fire()
    elseif what == SWITCH_BUTTON3 then
        showShapes = not showShapes
        if showShapes then
            physicsSetDebug(DEBUG_SHAPES + DEBUG_CONTACTS)
        else
            physicsSetDebug(DEBUG_NONE)
        end
    elseif what == SWITCH_LEFT then
        aimLeft = true
    elseif what == SWITCH_RIGHT then
        aimRight = true
    end
end

Die Leertaste feuert, Umschalt schaltet die Physikansicht ein und aus, und mit gedrückten Pfeiltasten verschiebst du den Abschusspunkt. Eine flache Metallplatte ohne Körper, die in jedem Frame auf aimX gesetzt wird, zeigt, woher die nächste Kugel kommt. Das vollständige Skript, mit dem Callback fürs Loslassen und dem Rest der Einrichtung, ist 24-physics.singe im Ordner learn.

physicsSetDebug ist der nützlichste Aufruf in dieser Lektion. Er zeichnet, was die Simulation tatsächlich enthält — die echten Formen als Drahtgitter und ein rotes Kreuz überall dort, wo sich in diesem Schritt zwei Körper berührt haben — über deine Szene. Wenn zum ersten Mal eine Kiste eine Handbreit über dem Boden schwebt, durch ihn hindurchfällt oder etwas aus zwei Metern Entfernung umwirft, schalte das ein, und die Antwort steht auf dem Bildschirm. Füg DEBUG_STATIC hinzu, um auch den Boden und die Wände zu sehen. Solange es aus ist, kostet es nichts.

Zum Schluss das Zählen:

function onOverlayUpdate()
    local over    = 0
    local settled = true

    if aimLeft then
        aimX = math.max(aimX - 0.08, -5)
    end
    if aimRight then
        aimX = math.min(aimX + 0.08, 5)
    end
    nodeSetPosition(marker, aimX, 0.05, 6)

    for _, crate in ipairs(crates) do
        local pitch, _, roll = nodeGetRotation(crate)

        if math.abs(pitch) > 30 or math.abs(roll) > 30 then
            over = over + 1
        end
        if not bodyIsResting(crate) then
            settled = false
        end
    end

    overlayClear()
    overlayPrint(2, 2, "Arrows aim.  Space fires.  Shift shows the shapes.")
    overlayPrint(2, 4, "knocked over " .. over .. " of " .. #crates .. "   hard hits " .. knocks)
    if settled then
        overlayPrint(2, 6, "everything has settled")
    end
    return OVERLAY_UPDATED
end

Eine Kiste zählt als umgeworfen, wenn sie mehr als dreißig Grad geneigt ist, und das ist eine Spielregel, geschrieben in einer Zeile Rechnerei, die auf dem aufsetzt, was die Simulation getan hat. nodeGetRotation liefert drei Winkel, und hier werden der erste und der dritte gebraucht, also wird der mittlere in einer Variablen namens _ aufgefangen. Dieser Unterstrich ist ein gewöhnlicher Name, an dem nichts Besonderes ist, und wird nach Konvention benutzt, um zu sagen: „Den hier ignoriere ich.“

bodyIsResting sagt, ob die Simulation einen Körper schlafen gelegt hat, weil er sich nicht mehr bewegt. Daran erkennst du, dass ein Schuss vorbei ist: kein Timer, kein Raten, sondern jede Kiste schläft. Ein Bowlingspiel wertet seinen Frame genau an dieser Stelle.

Wann du sie nicht benutzen solltest

Physik ist das verlockendste Werkzeug in jeder Engine und das, das die meisten Wochenenden verschwendet. Drei Dinge sind über sie wahr, und keins davon ist die Schuld der Engine.

Sie ist teuer. Jeder dynamische Körper ist Arbeit in jedem Schritt, sechzigmal pro Sekunde, ob ihn jemand ansieht oder nicht. Vierzig Kisten sind in Ordnung. Viertausend nicht, und auf einem kleinen Rechner auch vierhundert nicht.

Sie ist unberechenbar. Starte dein Spielzeug zweimal, und die Kisten landen anders. Das lässt es lebendig aussehen, und es ist auch der Grund, warum sich ein Spiel bei nichts darauf verlassen kann, was jedes Mal gleich ausgehen muss. Eine Tür, die aufgehen muss, eine Plattform, die ankommen muss, ein Sprung, den der Spieler schaffen können muss: Das ist Rechnerei, oder ein Tween, oder ein kinematischer Körper auf einem Pfad, den du geschrieben hast. Überlass nie etwas, das der Spieler tun muss, einer Simulation, die es hinter eine Kiste fallen lassen kann.

Sie ist schwer abzustimmen. Die Masse, die Reibung, das Abprallen, die Form und die Größe ziehen alle aneinander, und „es fühlt sich falsch an“ hat selten nur eine Ursache. Jede Stunde, die du damit verbringst, dass sich eine Physik-Kiste gut anfühlt, ist eine Stunde, die du nicht mit dem Spiel verbracht hast.

Greif also zu ihr, wenn das Chaos der eigentliche Zweck ist: Dinge, die umkippen, fliegende Trümmer, ein Haufen, der sich setzt, ein Ball, der durch einen Raum scheppert, ein Fahrzeug, das über unebenes Gelände rollt, eine Ragdoll, die eine Treppe hinunterpurzelt. Das kann niemand von Hand schreiben, und niemand kann dir genau sagen, wie es aussehen soll.

Greif nicht zu ihr, wenn du weißt, was passieren soll. Ein Geschoss, das geradeaus fliegt, sind zwei Zeilen aus Lektion zwei. Eine Plattform, die hoch- und runterfährt, ist math.sin. Eine Spielfigur, die so geht und springt, wie Spieler es erwarten, will einen Character-Controller (playerNew, in der Referenz), weil ein Mensch kein Quader ist und sich nie wie einer verhält. Ein Gegner, der patrouilliert, will einen Pfad. Ein Menü, das hereingleitet, will einen Tween.

Die Regel, die am besten taugt: Benutz Physik für die Dinge, denen der Spieler zusieht, und Rechnerei für die Dinge, die der Spieler tut.

Probier es aus

  1. Ändere die Welt. Füg physicsSetGravity(0, -1.62, 0) weit oben ein und feuere noch einmal. Dann probier 0, -30, 0. Dieselben Kisten, ein anderer Planet, eine Zeile.

  2. Ändere die Kugel. Mach die Kugel mit bodySetMass(ball, 30) zehnmal schwerer, dann mit 0.3 zehnmal leichter, und lass die Geschwindigkeit gleich. Dann setz die Masse zurück und ändere stattdessen die -14. Zwei Wege, härter zuzuschlagen, und sie fühlen sich nicht gleich an.

  3. Mach die Kisten zu Eis. Füg in crateAt bodySetFriction(crate, 0.02) ein und füg eine Zeile hinzu, die auch dem Boden eine niedrige Reibung gibt. Sieh zu, wie sich der Haufen von vornherein weigert, stehen zu bleiben.

  4. Mach die Form absichtlich falsch. Ändere in crateAt die Größen des Körpers auf 2, 2, 2, während das Mesh bei 0.8 bleibt. Starte es, sieh zu, wie die Kisten schweben und sich aus dem Nichts schubsen, dann drück Umschalt und sieh zu, wie die Debug-Ansicht es in einem Bild erklärt.

  5. Werte es richtig. Benutz bodyIsResting auf jeder Kiste, um zu bemerken, wann der Schuss vorbei ist, und zähl erst dann, wie viele umgefallen sind, und addier das zu einer Punktzahl. Das ist die Wertungshälfte eines Bowlingspiels.

Mach es absichtlich kaputt

Füg unter dem bodyNew des Bodens eine Zeile ein, die den Boden schwer macht, und das ist etwas, von dem man vernünftigerweise denken könnte, dass man es will:

bodySetMass(floor, 200)

Singe hält das Spiel mit etwas wie dem hier an:

32:bodySetMass:  Node 1 is not a dynamic body, or the mass is not positive.

Die erste Zahl ist die Zeile in deiner eigenen Datei, also wird deine anders sein.

Die Zahl nach Node ist das Handle des Knotens, die Zahl, die nodeNew zurückgegeben hat. Die Beschwerde ist genau: Masse gehört zu Dingen, die die Simulation bewegt, und ein statischer Körper wird von nichts bewegt, also hat er keine Masse, die man setzen könnte. Dass du danach fragst, ist ein Zeichen, dass der Körper die falsche Art für das ist, was du im Sinn hattest — und wenn du wirklich einen schweren Boden willst, der sich verschieben lässt, dann willst du einen dynamischen Körper mit großer Masse oder einen kinematischen, den du selbst bewegst.

Dieselbe Meldung erscheint bei einer Masse von 0, die Leute schreiben, wenn sie „schwerelos“ meinen. Schwerelos ist keine Masse. Es ist eine Welt ohne Schwerkraft oder playerSetGravityScale auf einem Character-Controller.

Was du gelernt hast

  • Ein Körper hängt an einem Knoten, und von da an sind Knoten und Körper ein Ding.

  • Statisch bewegt sich nie, dynamisch wird von der Simulation bewegt, und kinematisch wird von dir bewegt und schiebt alles andere beiseite.

  • Die Kollisionsform ist ein Ersatz für das Mesh, und du bist dafür verantwortlich, dass ihre Größen zu dem passen, was du gezeichnet hast.

  • Die Masse ist standardmäßig das Volumen der Form bei der Dichte von Wasser, also setz sie bei allem, was sich leicht anfühlen soll.

  • bodySetVelocity ersetzt die Bewegung eines Körpers, bodyApplyImpulse ist ein Treffer, und bodyApplyForce ist ein Schub, der anhält.

  • Setz nicht die Position eines dynamischen Knotens; lösch ihn und mach einen neuen, wenn du ihn neu anfangen lassen musst.

  • onCollision meldet jeden neuen Kontakt mit seinem Punkt und seiner Geschwindigkeit, und ein Trigger-Körper meldet Ankünfte und Abgänge über onTrigger.

  • bodyIsResting sagt dir, wann alles stillsteht, und dann ist meistens ein Zug vorbei.

  • physicsSetDebug zeichnet die eigene Sicht der Simulation, und es beantwortet die meisten Physikfragen schneller, als Code zu lesen.

  • Physik ist teuer, nicht wiederholbar und fummelig. Benutz sie für das Chaos, nicht für die Dinge, von denen das Spiel abhängt.

Beim nächsten Mal

Fallende Kisten sind eine Art von Spektakel. Die andere Art besteht aus tausend winzigen Dingen, die eine halbe Sekunde leben: Funken, Rauch, Feuer, Regen und Staub. In der nächsten Lektion geht es um Emitter, und sie endet mit einer Explosion. Das ist Lektion fünfundzwanzig.

Lektion 25: Partikel

Die fertige Lektion

Am Ende dieser Lektion fliegt ein Raumschiff über den unteren Rand des Bildschirms und zieht Feuer aus seinem Triebwerk hinter sich her, und ein Knopf sprengt es in hundertvierzig wirbelnde Funken, die vom Boden abprallen. Du schreibst keine einzige Zeile, die einen Funken zeichnet.

Das ist die ganze Idee dieser Lektion. Du beschreibst das Feuer; die Engine macht es.

Warum du die Funken nicht zeichnest

Du könntest es auch andersherum machen. Du weißt genug: eine Tabelle von Funken aus Lektion sechs, jeder mit einem x, einem y und einer Geschwindigkeit; eine Schleife in onOverlayUpdate, die jeden einzelnen davon bewegt, ihn verblassen lässt, ihn wegwirft, wenn er stirbt, und ihn zeichnet. Das funktioniert. Es sind aber auch zweihundert Zeilen Buchhaltung, die jedes Spiel neu schreibt, und sie laufen in Lua, ein Funke nach dem anderen, sechzigmal pro Sekunde.

Singe macht das stattdessen für dich. Du gibst ihm ein Rezept — wie viele Funken pro Sekunde, wie lange jeder lebt, wie schnell und in welche Richtung sie losfliegen, was an ihnen zieht, wie sie aussehen und zu welcher Farbe sie verblassen — und es verwaltet die Funken selbst. Das Ding, das das Rezept enthält und ausführt, heißt Emitter.

Ein Emitter ist kein Bild und auch kein Objekt in deinem Spiel. Er ist die Beschreibung einer Art von Feuer, aufbewahrt an einem Ort, auf den du zeigen kannst, und er kann dieses Feuer überall machen, wo du ihn darum bittest.

Fang mit etwas an, das sich bewegt

Partikel wirken überzeugender, wenn sie von etwas ausgehen, also fang mit einem Raumschiff an. Leg einen Ordner an, kopier den Ordner art des Buchs hinein und schreib das hier in particles.singe:

dofile("Singe/Framework.singe")

local SHIP_WIDTH  = 32
local SHIP_HEIGHT = 24
local SHIP_SPEED  = 120

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

local shipX = (overlayGetWidth() - SHIP_WIDTH) / 2
local shipY = overlayGetHeight() - 56

local movingLeft  = false
local movingRight = false
local lastTicks   = singeGetTicks()


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


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


function onOverlayUpdate()
    local now     = singeGetTicks()
    local seconds = (now - lastTicks) / 1000
    lastTicks     = now

    if movingLeft then
        shipX = shipX - SHIP_SPEED * seconds
    end
    if movingRight then
        shipX = shipX + SHIP_SPEED * seconds
    end

    overlayClear()
    spriteDraw(shipSprite, shipX, shipY)
    return OVERLAY_UPDATED
end

Starte es mit Singe -R particles und steuere mit den Pfeiltasten nach links und rechts. Hier ist nichts neu: ein Sprite aus Lektion neun, die Schalter aus Lektion drei und singeGetTicks, damit sich das Schiff mit derselben Geschwindigkeit bewegt, egal wie hoch die Bildrate ist.

Die eine Zeile, auf die es sich zu zeigen lohnt, ist dofile("Singe/Framework.singe"). Sie definiert DIR, den Ordner, in dem dein Skript liegt, also findet DIR .. "art/spaceship.png" das Bild, egal aus welchem Ordner du Singe gestartet hast.

Gib ihm einen Abgasstrahl

Jetzt das Feuer. Füg das hier über den Callbacks ein, nach den Variablen des Schiffs:

local exhaust = emitterNew()
emitterSetBlend(exhaust, PARTICLE_ADD)
emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)
emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)
emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)
emitterSetMax(exhaust, 120)
emitterStart(exhaust)

Und zwei Zeilen in onOverlayUpdate. Die erste kommt direkt vor overlayClear, die zweite direkt nach spriteDraw:

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)
    emitterDraw(exhaust)

Speichere. Das Schiff sitzt jetzt auf einer kurzen Zunge aus gelber Flamme, und die Flamme fliegt mit, wenn du steuerst.

Spreng es in die Luft

Ein Abgasstrahl läuft für immer. Eine Explosion passiert einmal, und das behandelt die Engine als eine andere Art von Auftrag an denselben Emitter.

Erst noch zwei Dateien und eine Zahl. Die beiden Dateien kommen oben neben das Sprite des Schiffs:

local sparkSprite = spriteLoad(DIR .. "art/star.png")
local boomSound   = soundLoad(DIR .. "art/boom.wav")

und das hier kommt neben shipX und shipY, zwanzig Einheiten über dem unteren Rand des Bildschirms:

local ground = overlayGetHeight() - 20

Jetzt das zweite Rezept, unter dem ersten:

local boom = emitterNew()
emitterSetTexture(boom, sparkSprite)
emitterSetBlend(boom, PARTICLE_ADD)
emitterSetLife(boom, 0.4, 1.1)
emitterSetSpeed(boom, 40, 220)
emitterSetSpread(boom, 180)
emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)
emitterSetSize(boom, 10, 2, 0.4)
emitterSetSpin(boom, -240, 240)
emitterSetColor(boom, 255, 255, 220, 255, 255, 70, 20, 0)
emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)
emitterSetMax(boom, 400)

Fällt dir auf, dass emitterStart fehlt? Dieser Emitter wird nie strömen.

Füg über onInputPressed eine Funktion ein, die ihn auslöst:

function explode()
    if not flying then
        return
    end
    flying = false
    emitterStop(exhaust)
    emitterSetPosition(boom, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT / 2)
    emitterBurst(boom, 140)
    soundPlay(boomSound)
    timerAfter(RESPAWN_MS, function()
        flying = true
        emitterStart(exhaust)
    end)
end

Dafür braucht es noch drei Dinge: local RESPAWN_MS = 1400 bei den anderen Konstanten, local flying = true bei den anderen Variablen und einen Zweig in onInputPressed:

    elseif what == SWITCH_BUTTON1 then
        explode()

Zum Schluss sollte das Schiff nicht da sein, solange es in Stücken ist. Pack das Steuern und das Zeichnen in onOverlayUpdate in if flying then …​ end und füg emitterDraw(boom) neben dem anderen Zeichenaufruf ein. Das fertige Skript ist learn/25-particles.singe.

Drück die Leertaste — standardmäßig Knopf eins — und das Schiff zerfällt in eine Wolke taumelnder Sterne, die im Bogen nach unten fliegen, auf den Boden schlagen und abprallen.

Was gerade passiert ist

In dieser Lektion gibt es sehr viele neue Aufrufe, und sie haben alle dieselbe Form: zuerst der Emitter, dann das, was du einstellst. Nimm sie dir in Gruppen vor.

local exhaust = emitterNew()

Macht einen Emitter und gibt ein Handle zurück: eine Zahl, mit der die Engine ihn wiederfindet, genau wie die Zahl, die dir spriteLoad gibt. Ohne Argument bekommst du einen zweidimensionalen Emitter, der in Overlay-Koordinaten lebt und aus onOverlayUpdate gezeichnet wird. Gib emitterNew stattdessen einen Knoten, und du bekommst einen dreidimensionalen, der in der Szene lebt und sich selbst zeichnet; alles andere in dieser Lektion ist für beide gleich.

Ein neuer Emitter hat schon ein vollständiges Rezept — fünfzig Partikel pro Sekunde, weiß, ein bis zwei Sekunden Lebensdauer, langsam den Bildschirm hinauftreibend — also widersprichst du mit jedem Aufruf danach einem Standardwert. Der Eintrag zu emitterNew in der Referenz listet sie alle auf.

emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)

Neunzig Partikel pro Sekunde, und jedes lebt zwischen fünfzehn Hundertstel und vier Zehntel Sekunden. Diese beiden Zahlen zusammen entscheiden, wie viel Feuer es gibt: Neunzig pro Sekunde, die eine Drittelsekunde leben, heißt, dass in jedem Moment etwa dreißig auf dem Bildschirm sind.

Überall, wo ein Emitter-Aufruf einen kleinsten und einen größten Wert nimmt, bekommt jedes Partikel seinen eigenen Wert, zufällig zwischen den beiden gewählt. Daher kommt das Zerfranste. Ein Feuer, in dem jede Flamme genau so lange lebte wie jede andere, sähe aus wie eine Maschine.

emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)

In welche Richtung sie losfliegen, wie breit der Fächer ist und wie schnell. Das Y des Overlays wächst nach unten, wie schon seit Lektion eins, also ist (0, 1) den Bildschirm hinunter — hinten aus einem Schiff heraus, das nach oben zeigt. emitterSetSpread ist der halbe Winkel des Fächers: Zwölf Grad sind ein enger Strahl, neunzig öffnen ihn zum halben Kreis, und hundertachtzig sind alle Richtungen auf einmal.

emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)

Diese beiden sind der Grund, warum die Flamme wie eine Flamme aussieht. Ein Partikel hat nicht eine Größe und eine Farbe; es hat eine Größe und eine Farbe bei der Geburt und eine andere beim Tod, und es gleitet gleichmäßig von der einen zur anderen, über die Lebensdauer, die es gezogen hat. Also fängt jeder Funke sieben Overlay-Einheiten breit und blassgelb an und endet eine Einheit breit und orangerot mit einem Alpha von null, und das ist unsichtbar. Er schrumpft und verblasst, weil du gesagt hast, wo er endet, nicht weil ihn irgendetwas verblassen ließ.

emitterSetColor nimmt acht Zahlen, und das ist viel zu lesen: Rot, Grün, Blau und Alpha am Anfang, dann Rot, Grün, Blau und Alpha am Ende.

emitterSetBlend(exhaust, PARTICLE_ADD)

Wie sich ein Partikel mit dem verbindet, was dahinter ist. PARTICLE_ALPHA ist normales Malen und der Standard: Nimm es für Rauch, Staub, Regen und Trümmer. PARTICLE_ADD addiert stattdessen sein Licht zum Bild, also sind zwei Funken übereinander heller als einer, und nichts wird je dunkler. Feuer, Funken, Laser und Magie sind additiv. Rauch nicht, und additiv gezeichneter Rauch sieht aus wie Dampf, der von innen beleuchtet wird.

emitterSetMax(exhaust, 120)
emitterStart(exhaust)

emitterSetMax ist die Größe des Pools: wie viele Partikel dieses Emitters gleichzeitig existieren dürfen. Ist der Pool voll, wird nichts Neues geboren, bis etwas stirbt. Neunzig pro Sekunde, die bis zu vier Zehntel Sekunden leben, brauchen etwa sechsunddreißig, also sind hundertzwanzig bequem. Stell es ein, bevor du startest, denn wenn du es später änderst, wird jedes lebende Partikel weggeworfen.

emitterStart dreht den Hahn auf. Von da an macht der Emitter in jedem Frame Partikel, ob du ihn zeichnest oder nicht, bis emitterStop ihn wieder zudreht. Beachte, was emitterStop nicht tut: Es stoppt neue Partikel, und die, die schon leben, leben ihr Leben zu Ende und verblassen ganz normal. Darum verweht der Abgasstrahl, statt zu verschwinden, wenn das Schiff explodiert. Wenn du sie sofort weghaben willst, tötet emitterClear sie.

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)

So folgt ein Emitter etwas. Ein zweidimensionaler Emitter lässt alles an einem Punkt entstehen, und dieser Punkt ist dort, wo du ihn zuletzt hingesetzt hast, also setzt du ihn in jedem Frame nach dem, was sich gerade bewegt: der Position eines Sprites, dem Knoten eines Physikkörpers, der Maus. Neue Partikel erscheinen am neuen Ort; die schon in der Luft sind, bleiben, wo sie geboren wurden, und genau das ist richtig für einen Abgasstrahl, denn Abgas bleibt zurück.

Ein dreidimensionaler Emitter wird an einem Knoten gemacht und folgt diesem Knoten von selbst, ganz ohne Aufruf in deinem Update. Und wenn du doch willst, dass die ganze Wolke mit dem Ding mitreist — ein Schild, eine Aura, ein Triebwerksstrahl von außen gesehen — schaltet emitterSetLocal das ein.

    emitterDraw(exhaust)

Zweidimensionale Emitter werden gezeichnet, wenn du darum bittest, einmal pro Frame, aus onOverlayUpdate. Die Reihenfolge deiner Aufrufe von emitterDraw ist die Reihenfolge, in der sie übereinanderliegen. Diesen Aufruf zu vergessen ist der Fehler, den jeder einmal macht: Der Emitter läuft weiter, verbraucht weiter seinen Pool und zeigt nichts.

Jetzt die eigenen Aufrufe der Explosion.

emitterSetTexture(boom, sparkSprite)

Ohne Textur ist jedes Partikel ein weicher runder Klecks, den die Engine selbst zeichnet; das benutzt der Abgasstrahl, und für eine Flamme ist es richtig. Mit einer Textur trägt jedes Partikel dieses Bild — hier star.png, acht mal acht Pixel. Der Emitter nimmt sich seine eigene Kopie der Pixel, also darfst du das Sprite danach entladen, und die Partikel funktionieren weiter.

emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)

Schwerkraft ist ein gleichmäßiger Zug, in Overlay-Einheiten pro Sekunde pro Sekunde, und sie ist nach unten positiv, aus demselben Grund, aus dem der Abgasstrahl mit positivem Y feuert. Der Luftwiderstand (Drag) ist das Gegenteil: Er nimmt Geschwindigkeit weg, in jedem Frame ein bisschen, also fliegen die Funken hart hinaus und bleiben dann in der Luft hängen. Funken mit Schwerkraft und ohne Luftwiderstand regnen gerade nach unten wie ein Feuerwerk; erst der Luftwiderstand lässt sie aussehen, als bewegten sie sich durch Luft.

emitterSetSpin(boom, -240, 240)
emitterSetSize(boom, 10, 2, 0.4)

Die Drehung ist in Grad pro Sekunde, und ein Bereich, der über null hinweggeht, lässt manche in die eine und manche in die andere Richtung drehen. Man sieht sie auf einer Textur, und am eingebauten Klecks bewirkt sie gar nichts, denn der ist rund.

Die dritte Zahl bei emitterSetSize ist die Variation. Sie skaliert beide Größen jedes Partikels mit einem einzigen zufälligen Faktor — hier irgendwo von null Komma sechs bis eins Komma vier — damit die Funken nicht alle derselbe Stern in derselben Größe sind.

emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)

COLLIDE_FLOOR legt in der Höhe, die du angibst, einen flachen, unsichtbaren Boden quer durch die Welt, und Partikel prallen davon ab. Die beiden Zahlen davor sagen, wie viel Geschwindigkeit einen Aufprall übersteht und wie viel seitliche Geschwindigkeit abgerieben wird. Das kostet nichts, weil es ein Vergleich pro Partikel ist, und es lässt Trümmer aussehen, als wären sie irgendwo gelandet, statt durch die Welt zu fallen. In einem dreidimensionalen Spiel lässt COLLIDE_SCENE Partikel stattdessen von der echten Geometrie abprallen, und das kostet sehr viel mehr.

Ein Schweif merkt sich die letzten paar Orte, an denen ein Partikel war, und zeichnet ein verblassendes Band durch sie hindurch. Vier Positionen und zwei Einheiten Breite machen aus jedem Stern einen kurzen Streifen.

    emitterBurst(boom, 140)

Und das ist die andere Art, Partikel zu machen. emitterStart ist ein Hahn; emitterBurst ist eine Handvoll, auf einmal geworfen. Der Emitter muss dafür nicht strömen, und dieser hier tut es nie. Alles andere — das Rezept, der Pool, die Position — funktioniert genauso.

Diese Unterscheidung solltest du dir merken. Alles, was andauert, ist ein Strom, den du startest und stoppst: Abgas, Rauch, Regen, eine Fackel, ein Wasserfall. Alles, was in einem Moment passiert, ist ein Stoß: eine Explosion, ein Platschen, ein Schritt im Staub, ein Kugeleinschlag, ein Mündungsfeuer. Viele Effekte sind beides, aus einem Emitter oder aus zweien: Eine Granate platzt und raucht dann.

Wie viele sind zu viele

Die ehrliche Antwort ist, dass Partikel billig zu bewegen und teuer anzusehen sind.

Zehntausend Partikel zu bewegen ist Rechnen, und ein Computer, der überhaupt ein Spiel laufen lassen kann, schafft das, ohne es zu merken. Was kostet, ist das Zeichnen, und was das Zeichnen kostet, ist ungefähr die Zahl der Bildschirmpixel, die die Partikel bedecken, Überlappungen mitgezählt. Zweihundert Funken, acht Pixel breit, bedecken weniger vom Bildschirm als eine Rauchwolke, die ihn ausfüllt. Das ist die Regel: klein und viele ist fast umsonst, groß und überlappend nicht.

Additives Mischen ist die teure Art, denn nichts, was es zeichnet, kann übersprungen werden — jede Schicht addiert sich zu dem, was darunter ist, also malt der Rechner alle. Ein Dutzend additive Blitze über den ganzen Bildschirm, übereinander, bremst einen Raspberry Pi 4 zum Schneckentempo aus, während ihn zehntausend winzige hüpfende Funken nicht stören.

Also: Ein paar tausend kleine Partikel sind kein Grund zur Sorge. Bevor du darüber hinausgehst, bring die Anzahl auf den Bildschirm und behalte sie im Auge.

    overlayPrint(2, 4, "Particles alive: " .. (emitterGetCount(exhaust) + emitterGetCount(boom)))

Mit emitterGetCount bemisst du einen Pool ehrlich, statt zu raten. Steht die Zahl genau bei deinem emitterSetMax, ist dein Pool voll, und die Engine weigert sich still, Partikel zu machen, um die du gebeten hast. Kommt sie nie in die Nähe, reservierst du Speicher für nichts.

Probier es aus

  1. Mach aus dem Abgasstrahl Rauch. Ändere emitterSetBlend(exhaust, PARTICLE_ADD) in PARTICLE_ALPHA, stell die Farbe auf Grau, das zu durchsichtigem Grau verblasst, und lass ihn mit emitterSetSize(exhaust, 3, 14) wachsen statt schrumpfen. Drei Zeilen haben eine andere Maschine gemacht.

  2. Nimm der Explosion den Luftwiderstand. Lösch die Zeile mit emitterSetDrag und vergleiche. Dann setz den Luftwiderstand wieder ein und nimm stattdessen die Schwerkraft weg. Das eine sieht aus wie ein Feuerwerk und das andere wie ein Unfall.

  3. Mach den Abgasstrahl breiter. Setz emitterSetSpread(exhaust, 180). Das Schiff sieht nicht mehr aus, als hätte es ein Triebwerk. Die Streuung leistet mehr, als du denkst.

  4. Wirf tausend auf einmal. Ändere emitterBurst(boom, 140) in emitterBurst(boom, 1000) und beobachte die Anzahl auf dem Bildschirm. Sie wird keine tausend erreichen. Finde anhand von emitterSetMax heraus, warum nicht, dann vergrößere den Pool, mach die Funken viermal so groß und sieh, was das mit der Bildrate macht.

  5. Zünde die Explosion dort, wo das Schiff nicht ist. Schreib emitterSetPosition(boom, 40, 60) in explode statt der Position des Schiffs. Ein Emitter ist die Beschreibung eines Feuers, kein Ding, das irgendwo lebt, und du kannst denselben im selben Frame an zehn Stellen zünden.

Mach es absichtlich kaputt

Die Konstanten — PARTICLE_ADD, COLLIDE_FLOOR, OVERLAY_UPDATED — sind Namen, die Singe Zahlen gegeben hat. Schreib eine davon leicht falsch, und Lua beschwert sich nicht, denn in Lua ist ein Name, der nie einen Wert bekommen hat, kein Fehler: Er ist nil, der Wert, der „hier ist nichts“ bedeutet.

Ändere die Mischzeile des Abgasstrahls in einen Namen, der genauso naheliegend klingt:

emitterSetBlend(exhaust, PARTICLE_ADDITIVE)

Singe hält an, bevor das Spiel startet, und nennt die Zeile in deiner Datei, in der dieser Aufruf steht:

22:emitterSetBlend:  Argument 2 must be a number.

Dieser Fehler hat eine andere Form als die Lua-Fehler aus Lektion acht, weil er von der Engine kommt und nicht von Lua. Erst kommt die Zeilennummer, dann der Aufruf, der sich gewehrt hat, dann die Beschwerde. Argument zwei von emitterSetBlend ist der Mischmodus, und angekommen ist nil, weil PARTICLE_ADDITIVE kein Name ist, den je irgendetwas definiert hat.

„Must be a number“ heißt fast immer genau das: eine falsch geschriebene Konstante oder eine Variable, von der du dachtest, du hättest sie gesetzt. Die Lösung ist, den Namen mit der Referenz zu vergleichen, und dort heißt er PARTICLE_ADD.

Was du gelernt hast

  • Ein Emitter enthält ein Rezept für eine Art von Partikel und verwaltet die Partikel selbst, also zeichnet dein Skript nie eins.

  • emitterNew ohne Argument macht einen zweidimensionalen Emitter in Overlay-Koordinaten; mit einem Knoten macht es einen dreidimensionalen in der Szene.

  • Jeder Emitter fängt mit einem vollständigen Rezept an, und jeder Aufruf von emitterSet…​ ändert einen Teil davon.

  • Überall, wo ein Aufruf einen kleinsten und einen größten Wert nimmt, zieht jedes Partikel seinen eigenen Wert zufällig dazwischen, und daher kommt das Zerfranste.

  • Größe und Farbe werden für die Geburt und für den Tod festgelegt, und das Partikel gleitet über sein Leben von der einen zur anderen.

  • emitterStart strömt bis emitterStop; emitterBurst wirft eine Handvoll auf einmal. Andauernde Effekte sind Ströme, kurze sind Stöße.

  • emitterStop lässt die lebenden Partikel zu Ende leben; emitterClear tötet sie sofort.

  • Ein zweidimensionaler Emitter wird in jedem Frame mit emitterSetPosition bewegt und in jedem Frame mit emitterDraw gezeichnet. Ein dreidimensionaler folgt seinem Knoten und zeichnet sich selbst.

  • Partikel kosten, was sie auf dem Bildschirm bedecken, nicht, was ihre Bewegung kostet, und additives Mischen ist die teure Art.

  • emitterSetMax begrenzt den Pool, und emitterGetCount sagt dir, ob du die Größe richtig geraten hast.

Beim nächsten Mal

Die Explosion hat hundertvierzig Dinge bewegt, ohne dass ihr jemand gesagt hat, wohin eins davon fliegen soll, aber es waren Funken, und Funken ist es egal, wogegen sie stoßen. In Lektion sechsundzwanzig geht es um etwas, dem es nicht egal ist: eine Figur, die von hier nach dort muss, und eine Wand im Weg.

Lektion 26: Figuren, die sich selbst bewegen

Die fertige Lektion

In dieser Lektion baust du einen Raum mit einer Wand quer durch die Mitte und stellst zwei Figuren hinein. Die eine schickst du per Knopfdruck in eine Ecke. Die andere sucht sich zufällig irgendeinen Ort aus, läuft dorthin und sucht sich, wenn sie ankommt, einen anderen aus, für immer.

Keine von beiden läuft in die Wand, und du schreibst nie eine Zeile, die sagt, wie man um sie herumkommt. Das ist neu. Jede Lektion bis zu dieser hat Dinge dorthin bewegt, wo du sie hinhaben wolltest. Das ist die erste Lektion, in der das Spiel selbst etwas herausfindet.

Das Problem mit dem Laufen auf etwas zu

Hier ist der naheliegende Weg, eine Figur zu einem Punkt laufen zu lassen, und so schreibt es jeder zuerst. Nimm das Ziel, zieh ab, wo du bist, und geh ein kleines Stück auf der Linie dazwischen, in jedem Frame, bis du ankommst.

In einem leeren Raum funktioniert das wunderbar.

Stell eine Wand in den Raum, und es funktioniert nicht mehr, und zwar auf eine Art, die eher dumm als kaputt aussieht: Die Figur marschiert in die Wand, bleibt dort stehen und schrammt daran, einen Meter neben einem Durchgang, den sie nicht sehen kann, weil nichts in „geh auf das Ziel zu“ eine Ahnung davon hat, dass es in der Welt Formen gibt.

Da kannst du dich nicht herausflicken. Wenn die Figur zur Seite abbiegt, sobald sie eine Wand berührt, bleibt sie in der ersten Ecke hängen, die sie findet. Es reicht auch nicht, zu wissen, wo die Wände sind, denn der Weg um eine Wand herum kann lang sein, kann sich erst vom Ziel entfernen, bevor er zurückkommt, und kann überhaupt nicht existieren.

Was du brauchst, ist eine Möglichkeit, eine echte Frage zu stellen: Wie laufe ich von hier nach dort? Um sie zu beantworten, braucht es etwas, das die Form des Bodens kennt.

Was ein Navigationsmesh ist

Stell dich in einen Raum und sieh auf den Boden. Auf manchem davon könntest du laufen. Auf manchem nicht: Er liegt unter einem Tisch, in einer Wand, jenseits der Kante eines Balkons oder hinter einer Stufe, die zu hoch zum Hinaufsteigen ist. Stell dir jetzt vor, du malst den Teil an, auf dem du laufen könntest, und wirfst alles andere weg — die Wände, die Möbel, die Decke, die Kulisse. Übrig bleibt eine flache Form, oder mehrere, mit Löchern, wo die Säulen sind, und Lücken, wo es hinuntergeht.

Diese angemalte Form ist ein Navigationsmesh, und mehr braucht eine Figur nicht, um einen Weg zu planen. Es ist nicht das Level. Es ist eine vereinfachte Karte der Teile des Levels, auf denen ein Mensch stehen kann, und weil es einfach ist, lassen sich Fragen dazu schnell beantworten.

Singe macht es für dich aus dem Level, das du schon hast. Du sagst, wie groß die Figuren sind, gibst ihm die Geometrie, und es findet heraus, was begehbar ist: Böden und Rampen innerhalb der Steigung, die du erlaubst, Stufen, die nicht höher sind, als du erlaubst, und um jede Wand und jede Kante wird ein Rand abgeschnitten, damit eine Figur, die eine Breite hat, keine Ecke schneidet. Das nennt man Backen, es passiert einmal, und das Ergebnis kann in einer Datei gespeichert und beim nächsten Mal geladen werden.

Ein Raum mit einer Wand darin

Leg einen Ordner namens navigation an und darin eine Datei namens navigation.singe. Dieser Teil ist eine dreidimensionale Szene, und darum ging es in Lektion zweiundzwanzig: Eine Szene ist eine Welt, die in drei Dimensionen gezeichnet wird, und alles darin hängt an einem Knoten, also an einer Position, einer Drehung und einer Skalierung, an die du eine Form hängen kannst.

Wenn du diese Lektion übersprungen hast, kannst du dieser hier trotzdem folgen. Nimm die nächsten beiden Blöcke einfach als „ein grauer Boden, zwanzig Einheiten im Quadrat, drei hellbraune Wände darauf und eine Kamera, die auf das Ganze hinunterschaut“.

local ROOM         = 20
local WALL_HEIGHT  = 2
local AGENT_RADIUS = 0.4
local AGENT_HEIGHT = 1.8
local WALK_SPEED   = 2.2

sceneEnable(true)
sceneSetBackground(28, 32, 42, 255)
sceneSetAmbient(80, 86, 100)

local floorLook = materialNew()
materialSetColor(floorLook, 96, 102, 110)
materialSetRoughness(floorLook, 0.9)

local wallLook = materialNew()
materialSetColor(wallLook, 150, 128, 104)
materialSetRoughness(wallLook, 0.8)

local ground = nodeNew()
nodeSetMesh(ground, meshPlane(ROOM, ROOM), floorLook)

local wallMesh = meshBox(1, WALL_HEIGHT, 1)
local walls    = {}


function addWall(x, z, width, depth)
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, wallLook)
    nodeSetScale(wall, width, 1, depth)
    nodeSetPosition(wall, x, WALL_HEIGHT / 2, z)
    walls[#walls + 1] = wall
end


addWall(-4, 0, 12, 0.6)
addWall(7.5, 0, 5, 0.6)
addWall(-3, -6, 0.6, 8)

Die Einheiten hier sind Meter, denn davon geht die dreidimensionale Welt von Singe aus. Die ersten beiden Wände laufen quer durch die Mitte des Raums, mit einer Lücke von drei Metern dazwischen: ein Durchgang. Die dritte ist ein Stummel, der in die hintere Hälfte ragt, damit die Figuren etwas haben, um das sie herumlaufen müssen, wenn sie durch sind.

Füg ein Licht und eine Kamera hinzu, damit es etwas zu sehen gibt:

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 8, 14, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 3.5)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 17, 19)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 120)


function onOverlayUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Starte es mit Singe -R navigation. Ein grauer Boden, eine Wand mit einer Lücke und ein Stummel, von oben und von hinten gesehen.

Back den Boden

Sechs Zeilen machen aus diesem Raum eine Karte:

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)
navAddNode(nav, ground)
for _, wall in ipairs(walls) do
    navAddNode(nav, wall)
end
navBuild(nav)

Setz sie hinter die Wände und vor das Licht. Dann füg in onOverlayUpdate unter overlayClear eine Zeile ein, damit du siehst, was du bekommen hast:

    navDraw(nav, 0, 170, 190)

Starte es noch einmal. Ein Netz aus blaugrünen Dreiecken liegt über dem Boden, und es hört vor den Wänden auf. Die Lücke, die es lässt, ist keine Dekoration: Es sind die 0,4 Meter Abstand, die eine Figur mit einem Radius von 0,4 Metern braucht, damit ihre Schultern nicht durch den Stein gehen. Der Durchgang ist im Mesh immer noch ein Durchgang, denn drei Meter sind breit genug, um hindurchzugehen; mach die Lücke einen halben Meter breit, und das Blau würde sich darüber schließen, und für jede Figur in deinem Spiel gäbe es dort überhaupt keine Tür.

Sieh es dir einen Moment lang an, denn navDraw ist das Werkzeug, zu dem du jedes Mal greifen wirst, wenn eine Figur etwas Unerklärliches tut. In neun von zehn Fällen liegt die Antwort vor dir auf dem Boden.

Jemand, der darauf läuft

Eine Figur ist ein Knoten. Wie sie aussieht, geht die Navigation nichts an, also bau das Billigste, was zeigt, in welche Richtung sie schaut: einen Kasten mit einer Nase dran.

function makeWalker(x, z, look)
    local walker = nodeNew()
    nodeSetPosition(walker, x, 0, z)
    local body = nodeNew()
    nodeSetParent(body, walker)
    nodeSetMesh(body, meshBox(0.7, AGENT_HEIGHT, 0.7), look)
    nodeSetPosition(body, 0, AGENT_HEIGHT / 2, 0)
    local nose = nodeNew()
    nodeSetParent(nose, body)
    nodeSetMesh(nose, meshSphere(0.22, 16), look)
    nodeSetPosition(nose, 0, 0.4, -0.45)
    return walker
end

Das kommt zu addWall. Es braucht eine Farbe, also füg neben den anderen Materialien eine hinzu:

local walkerLook = materialNew()
materialSetColor(walkerLook, 225, 85, 60)
materialSetEmissive(walkerLook, 70, 18, 10)

Und jetzt die Zeile, für die es diese Lektion gibt. Nach navBuild:

local walker      = makeWalker(-7, 7, walkerLook)
local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

navAgentNew setzt den Knoten auf das Mesh und gibt einen Agenten zurück: das Wort der Engine für etwas, das sie bereit ist, für dich herumlaufen zu lassen. Ab diesem Moment gehört die Position dieses Knotens der Engine. In jedem Frame bewegt sie ihn und dreht ihn in die Richtung, in die er geht, und das tut sie so lange, bis du ihm sagst, wohin er gehen soll, oder den Agenten wegnimmst.

Starte es. Ein roter Kasten mit einer Nase erscheint in der vorderen Ecke und tut absolut nichts, weil du noch um nichts gebeten hast.

Ihn irgendwohin schicken

Gib ihm eine Liste von Orten und einen Knopf.

local posts = {
    {  7, 0,  7 },
    {  7, 0, -7 },
    { -7, 0, -7 },
    { -7, 0,  7 },
    { 30, 0, 30 }
}
local post    = 0
local message = "Button 1 sends the red one somewhere."


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    post = post % #posts + 1
    local target = posts[post]
    if navAgentMoveTo(walkerAgent, target[1], target[2], target[3]) then
        message = string.format("Walking to post %d.", post)
    else
        message = string.format("No path to post %d.  Staying put.", post)
    end
end

Gib die Meldung aus, damit du siehst, was passiert. In onOverlayUpdate, nach navDraw:

    overlayPrint(2, 2, message)

Starte es und drück Knopf eins — standardmäßig die Leertaste. Der Kasten dreht sich, läuft in die hintere Ecke seiner eigenen Raumhälfte und bleibt stehen. Drück noch einmal. Er läuft an der Wand entlang, findet den Durchgang, geht hindurch, kommt auf der anderen Seite heraus und bleibt in der hinteren Ecke stehen. Drück ein drittes Mal, und er geht um den Stummel herum zur vierten Ecke. Du hast ihm nichts von dem Durchgang gesagt. Nichts in deinem Skript erwähnt den Durchgang. Er hat ihn gefunden, weil der Durchgang ein Loch in einer Form ist, und um Löcher herumzugehen ist genau das, wofür das Mesh da ist.

Jeder Eintrag in posts besteht aus drei Zahlen, einem x, einem y und einem z, weil ein Punkt in einer dreidimensionalen Welt drei braucht. Y zeigt nach oben, und deine sind alle null, weil hier alles auf dem Boden liegt. Die Tabelle posts ist eine Tabelle aus Tabellen, aus Lektion sechs, und posts[post] ist eine der inneren.

Wissen, wann er ankommt

Der Kasten bleibt stehen, wenn er ankommt, aber dein Skript weiß nicht, dass er angekommen ist. Lass es dir sagen:

function onNavArrived(agent)
    message = string.format("Arrived at post %d.", post)
end

Das ist ein Callback, dieselbe Idee wie onOverlayUpdate in Lektion eins: Du schreibst ihn, die Engine ruft ihn auf. Dieser läuft einmal, in dem Moment, in dem ein Agent das Ziel erreicht, das er bekommen hat. Nicht, wenn er in der Nähe ist, und nicht in jedem Frame danach — einmal, bei der Ankunft.

Er bekommt den Agenten übergeben, denn ein Spiel hat mehr als einen. Dieses Argument ist die Zahl, die navAgentNew zurückgegeben hat, und indem du es vergleichst, erkennst du, welche deiner Figuren gerade dort angekommen ist, wo sie hinwollte.

Wenn es keinen Weg gibt

Drück den Knopf ein fünftes Mal, und die Meldung lautet No path to post 5. Staying put., und der Kasten bewegt sich nicht.

Posten fünf liegt bei { 30, 0, 30 }, und das ist zwanzig Meter außerhalb eines Raums, der zwanzig Meter breit ist. Dort gibt es keinen begehbaren Boden, es gibt keine Route dorthin, und es gibt nichts Vernünftiges, was eine Figur dagegen tun könnte. navAgentMoveTo sagt das, indem es false zurückgibt, und es lässt den Agenten genau so, wie er war.

Das ist der Teil, den Anfänger überspringen, und es ist der Teil, der zubeißt. Echte Spiele bitten ständig um unmögliche Wege, denn das Ziel ist meistens der Spieler, und der Spieler kommt überallhin: Er steht auf einer Kiste, ist mitten im Sprung, im Wasser, hinter einer Tür, die zugefallen ist, oder durch eine Lücke geschlüpft, die das Navigationsmesh als zu schmal weggeschnitten hat. Jeder dieser Fälle lässt ein völlig vernünftiges navAgentMoveTo false zurückgeben.

Dein Skript entscheidet, was das bedeutet. Eine Wache, die dich nicht erreichen kann, sollte wieder Streife gehen, oder zum nächsten Punkt laufen, den sie erreichen kann, und dort warten, oder rufen. Was sie nicht tun darf, ist nichts, während dein Code still ein zurückgegebenes false übergeht und du dich eine Stunde lang fragst, warum einer von zwanzig Gegnern erstarrt ist.

Zwei andere Aufrufe helfen hier, und es lohnt sich, sie zu kennen, bevor du sie brauchst. navNearest nimmt irgendeinen Punkt und gibt die nächstgelegene Stelle auf dem Mesh zurück, oder nil, wenn nichts in der Nähe ist; so machst du aus „wo der Spieler ist“ „irgendwo, wo eine Figur wirklich stehen kann“. Und navPath stellt dieselbe Frage wie navAgentMoveTo, ohne jemanden zu bewegen: Es gibt die Ecken der Route als Tabelle von Punkten zurück, oder nil, wenn es keine Route gibt. Du kannst sie ausmessen, zeichnen oder entscheiden, dass der Weg zu lang ist, um sich damit abzugeben.

Das Zeichnen ist der nützliche Trick. Füg das hier in onOverlayUpdate ein:

    local target = posts[post]
    if target ~= nil then
        local x, y, z = nodeGetWorldPosition(walker)
        local route   = navPath(nav, x, y, z, target[1], target[2], target[3])
        if route ~= nil then
            for i = 2, #route do
                local a = route[i - 1]
                local b = route[i]
                lineDraw(a[1], a[2] + 0.1, a[3], b[1], b[2] + 0.1, b[3], 255, 215, 60)
            end
        end
    end

Jetzt läuft eine gelbe Linie vom Kasten bis dorthin, wo er hinwill, knickt durch den Durchgang ab und wird kürzer, während er läuft. Schick ihn zu Posten fünf, und die Linie wird gar nicht gezeichnet, weil navPath nil zurückgegeben und das if es abgefangen hat. Du siehst der Entscheidung zu, die der Agent trifft, auf den Boden gezeichnet.

Ein zweiter Läufer

Eine Figur, die Wänden ausweicht, ist Navigation. Zwei Figuren, die Wänden und einander ausweichen, sind das, was dir die Engine tatsächlich gibt, und es kostet vier Zeilen mehr.

Füg neben dem roten ein blaues Material hinzu, dann das hier unter dem ersten Agenten:

local wanderer      = makeWalker(6, -6, wandererLook)
local wandererAgent = navAgentNew(nav, wanderer, AGENT_RADIUS, AGENT_HEIGHT, 1.4)

Schick ihn nach der Kamera irgendwohin, damit er loslegt:

navAgentMoveTo(wandererAgent, navRandomPoint(nav))

Und bring onNavArrived bei, die beiden auseinanderzuhalten:

function onNavArrived(agent)
    if agent == wandererAgent then
        navAgentMoveTo(agent, navRandomPoint(nav))
    else
        message = string.format("Arrived at post %d.", post)
    end
end

navRandomPoint sucht sich eine Stelle auf dem begehbaren Mesh aus — irgendwo darauf, nie in einer Wand — und gibt drei Zahlen zurück, und das ist genau das, was navAgentMoveTo als Nächstes haben will. Weil der Callback bei der Ankunft feuert und seine Antwort eine weitere Reise ist, wandert der blaue Kasten jetzt durch den Raum, solange das Spiel läuft, aus vier Zeilen und ganz ohne Zustand.

Sieh zu, wie sich die beiden im Durchgang begegnen. Keiner bleibt abrupt stehen, und keiner läuft durch den anderen hindurch: Beide weichen rechtzeitig ein wenig zur Seite aus und gehen aneinander vorbei. Das sind die Agenten, die umeinander herumsteuern, und das ist der Unterschied zwischen Figuren und Möbeln.

Das fertige Skript ist learn/26-navigation.singe.

Was gerade passiert ist

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)

Beginnt ein Navigationsmesh, und die vier Zahlen sind eine Beschreibung des Menschen, für den es gedacht ist: 0,8 Meter breit, 1,8 Meter groß, fähig, eine Steigung von bis zu fünfundvierzig Grad zu gehen, und fähig, eine Stufe von bis zu 0,3 Metern hinaufzusteigen.

Jede dieser Zahlen ändert die Form, die herauskommt. Eine breitere Figur verliert mehr Boden an den Rand um die Wände und findet einen Durchgang vielleicht verschlossen. Eine größere kann nicht unter einem niedrigen Balken durchgehen. Erlaube eine steilere Steigung, und eine Rampe wird zur Straße; erlaube weniger, und sie wird zur Klippe.

Der Radius entscheidet auch, wie fein der Boden vermessen wird, also dauert das Backen bei einem sehr kleinen Radius über einem sehr großen Level lange. Den Eintrag zu navNew in der Referenz solltest du lesen, bevor du deine Zahlen wählst.

navAddNode(nav, ground)
navBuild(nav)

navAddNode übergibt Geometrie — einen Knoten und alles, was unter ihm hängt, so wie es in diesem Moment in der Welt steht, also stell die Dinge an ihren Platz, bevor du sie hinzufügst. Ein Aufruf nimmt ein ganzes geladenes Modell. Nur echte Formen zählen: Ein Licht, ein Sound oder ein Physikkörper für sich allein fügt nichts hinzu.

navBuild erledigt das Backen, und es ist der langsame Aufruf in dieser Lektion: nichts, was du bemerken würdest, für einen Raum wie diesen, eine Zehntelsekunde für eine Kathedrale auf einem Desktop-Rechner, mehrere Sekunden auf einem Raspberry Pi. Mach es, während ein Titelbildschirm zu sehen ist, nicht, während der Spieler wartet.

Danach wird die Geometrie weggeworfen, und das Mesh ist geschlossen. Du kannst nichts mehr hinzufügen. Wenn dein Level seine Form ändert — eine Tür geht auf, eine Brücke stürzt ein — backst du ein anderes Mesh, und navDelete gibt das alte frei.

Auf einem langsamen Rechner willst du lieber gar nicht backen, also schreibt navSave das fertige Mesh in eine Datei, und navLoad liest es wieder ein, gebaut und bereit. Back einmal auf deinem eigenen Rechner, liefere die Datei mit dem Spiel aus, und der Spieler wartet nie.

local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

Ein Agent ist ein Knoten, den die Engine für dich herumlaufen lässt, weil sie sich dazu bereit erklärt hat. Radius und Höhe benutzt sie hier, um Abstand zu anderen Agenten zu halten, und die letzte Zahl ist seine Höchstgeschwindigkeit in Metern pro Sekunde — 2,2 ist zügiges Gehen, 1,4 ist Schlendern, 6 ist ein Sprint.

Setz ab jetzt die Position dieses Knotens nicht mehr selbst. Zwei Dinge, die einen Knoten bewegen, kämpfen miteinander, und der Kampf sieht aus wie Ruckeln. Wenn deine Figur nicht nur laufen, sondern auch von der Physik herumgeschubst werden soll, gibt es dafür einen Aufruf — navAgentSetPlayer übergibt die Steuerung stattdessen einem Physik-Controller — und der Eintrag dazu in der Referenz erklärt, wann du das willst.

local ok = navAgentMoveTo(walkerAgent, x, y, z)

Setzt das Ziel. Der Aufruf läuft nicht selbst dorthin; er sagt, wo „dort“ ist, und die Engine kümmert sich in den folgenden Frames darum. Du darfst ihn jederzeit erneut aufrufen, und das neue Ziel ersetzt das alte; so folgt eine Wache einem Spieler, der rennt: Richte sie ein- oder zweimal pro Sekunde neu aus, nicht sechzigmal.

Und er gibt true oder false zurück, und du musst nachsehen.

navAgentStop(walkerAgent)

Wird oben nicht benutzt, ist aber die andere Hälfte des Paars: Es vergisst das Ziel, und der Agent wird langsamer, bis er dort steht, wo er gerade ist. onNavArrived feuert nicht, weil er nicht angekommen ist. Benutz es, wenn der Grund für die Reise weggefallen ist.

Auf Tempo kommt es nicht an

Noch ein Aufruf, denn er macht aus einer Vorführung etwas, das wie ein Spiel aussieht.

    local vx, vy, vz = navAgentGetVelocity(walkerAgent)
    local speed      = math.sqrt(vx * vx + vz * vz)
    overlayPrint(2, 4, string.format("Speed %.2f", speed))

navAgentGetVelocity sagt dir, wie sich der Agent gerade jetzt bewegt: nicht, wohin er geht, sondern wie schnell und in welche Richtung er in diesem Frame tatsächlich unterwegs ist. Beobachte die Zahl, wenn der Kasten losläuft und wenn er zum Stehen kommt. Er beschleunigt sanft und bremst sanft.

An diese Zahl hängst du eine Animation. Eine Figur, deren Beine sich mit der Geschwindigkeit bewegen, mit der sie wirklich unterwegs ist, wirkt lebendig; eine, deren Laufzyklus mit fester Geschwindigkeit läuft, während sie beschleunigt, sieht aus, als liefe sie Schlittschuh. Mit einem echten Modell statt des Kastens würdest du diese Geschwindigkeit mit ein paar Schwellenwerten vergleichen und eine Steh-, eine Geh- oder eine Renn-Animation abspielen — darum geht es in Lektion dreiundzwanzig, und das Beispiel in der Referenz unter navAgentGetVelocity ist genau dafür geschrieben.

Und das ist der eigentliche Punkt dieser Lektion. Eine Figur, die die schnelle gerade Linie nimmt und an einer Wand entlangschrammt, ist schlechter als eine, die eine Sekunde später losgeht, sich richtig dreht, außen herum durch die Tür geht und langsamer wird, wenn sie ankommt. Niemand, der ein Spiel spielt, misst, wie schnell ein Gegner bei ihm war. Aber jeder merkt sofort, ohne sagen zu können, warum, wenn sich etwas so bewegt, wie sich kein Lebewesen bewegen würde.

Probier es aus

  1. Mach die Tür zu. Ändere die ersten beiden Wände so, dass die Lücke zwischen ihnen einen halben Meter breit ist statt drei: addWall(-4, 0, 13, 0.6) und addWall(6.5, 0, 7, 0.6). Starte es und sieh dir an, was navDraw zeigt, bevor du irgendetwas drückst. Dann schick den Kasten hinüber und sieh, was er tut.

  2. Mach alle dick. Setz AGENT_RADIUS auf 2.0 und starte es. Der Durchgang ist immer noch drei Meter breit, und die blauen Dreiecke sind daraus verschwunden. Nichts ist kaputt; das Mesh beantwortet jetzt eine andere Frage.

  3. Schick ihn zur Maus. Nimm mit sceneUnproject den Punkt unter dem Mauszeiger, rück ihn mit navNearest auf das Mesh und schick den Kasten dorthin, wenn der Knopf gedrückt wird. Dass navNearest nil zurückgibt, ist der Fall, um den du dich kümmern musst, und er tritt immer dann ein, wenn der Zeiger nicht über dem Boden ist.

  4. Füg vier weitere Wanderer hinzu. Pack die vier Zeilen des blauen Läufers in eine Schleife mit for aus Lektion vier, bewahr die Agenten in einer Tabelle auf und lass sie alle herumwandern. Beobachte den Durchgang, wenn drei von ihnen gleichzeitig hindurchwollen.

  5. Back es einmal. Ruf navSave(nav, "room.nav") nach navBuild auf, dann ersetze navNew, die Aufrufe von navAddNode und navBuild durch ein einziges navLoad("room.nav", AGENT_RADIUS, AGENT_HEIGHT). Jetzt ändere die Position einer Wand und starte es noch einmal. Was du siehst, ist die Falle, die mit gebackenen Meshes kommt, und es lohnt sich, ihr einmal absichtlich zu begegnen.

Mach es absichtlich kaputt

Backen schließt das Mesh. Versuch, nachträglich noch etwas hinzuzufügen — eine Kiste, die du spät hingestellt hast, oder eine Wand, die du vergessen hast — indem du diese Zeile direkt hinter navBuild(nav) setzt:

navAddNode(nav, ground)

Singe hält an, bevor das Spiel startet, und nennt die Zeile in deiner Datei, in der dieser Aufruf steht:

68:navAddNode:  The mesh is already built.

Ein Fehler der Engine hat die Form: die Zeile, der Aufruf, der sich gewehrt hat, und die Beschwerde, und diese Beschwerde meint, was sie sagt: navBuild hat die Geometrie verbraucht, die es bekommen hat, und es gibt nichts mehr, wozu man etwas hinzufügen könnte.

Die Lösung ist nie, den Aufruf von navAddNode zu verschieben. Sie ist, zu bemerken, dass du Geometrie für zwei Level hast und zwei Meshes willst, oder dass du zu früh gebacken hast. Füg alles hinzu, dann bau, und bau zuletzt.

Was du gelernt hast

  • Auf ein Ziel zuzugehen funktioniert in einem leeren Raum und versagt, sobald es eine Wand gibt, und kein noch so eifriges Flicken behebt das.

  • Ein Navigationsmesh ist eine vereinfachte Karte des Bodens, auf dem eine Figur stehen kann, ohne die Wände, die Abgründe und den Abstand um sie herum.

  • navNew beschreibt die Figur, für die das Mesh ist, navAddNode übergibt die Geometrie des Levels, und navBuild backt es. Nach dem Backen kann nichts mehr hinzugefügt werden.

  • navSave und navLoad bewahren ein gebackenes Mesh in einer Datei auf, damit der Spieler nie darauf wartet.

  • navDraw zeigt dir das Mesh, und es ist das Erste, was du dir ansiehst, wenn sich eine Figur seltsam verhält.

  • navAgentNew gibt der Engine einen Knoten zum Herumlaufen; ab dann bewegst du diesen Knoten nicht mehr selbst.

  • navAgentMoveTo setzt ein Ziel und gibt false zurück, wenn es keinen Weg dorthin gibt. Darum musst du dich kümmern, und es passiert oft.

  • onNavArrived wird einmal aufgerufen, wenn ein Agent sein Ziel erreicht, und erfährt, welcher Agent es ist.

  • navPath beantwortet dieselbe Frage, ohne jemanden zu bewegen, und nil heißt: keine Route.

  • Agenten steuern umeinander herum, nicht nur um das Level herum.

  • Mit navAgentGetVelocity passt ein Laufzyklus zu der Strecke, die zurückgelegt wird.

Beim nächsten Mal

Deine beiden Kästen laufen jetzt schweigend durch einen Raum. In Lektion siebenundzwanzig geht es darum, was du darunterlegst: Musik, die sauber in einer Schleife läuft und mit dem Video im Takt bleibt, und MIDI, mit dem ein Spiel ein Instrument spielen kann — oder ein echtes Instrument das Spiel.

Lektion 27: Musik und MIDI

Die fertige Lektion

Diese Lektion besteht aus zwei Lektionen, die zufällig zusammenwohnen.

Die erste Hälfte ist Musik: wie ein Spiel ein Musikstück richtig abspielt, warum das nicht dasselbe ist, wie einen Soundeffekt abzuspielen, und was zu tun ist, wenn die Musik mit dem Video im Takt bleiben muss.

Die zweite Hälfte ist MIDI, dem die meisten Leute noch nie begegnet sind und das einem Spiel etwas gibt, was nichts anderes kann. Am Ende spielt ein Keyboard, das an deinen Computer angeschlossen ist, dein Spiel.

Ein Soundeffekt und ein Musikstück sind verschiedene Dinge

Wie man einen Sound abspielt, weißt du schon. Lektion zehn hat eine .wav mit soundLoad geladen und mit soundPlay abgefeuert, und wenn du diese beiden Aufrufe auf einen vier Minuten langen Song richtest, spielen sie ihn ab.

Lass es. Singe hält Soundeffekte und Musik auseinander, und diese Trennung lohnt sich aus vier Gründen.

  • Sie haben ihre eigenen Lautstärken. soundSetVolume rührt die Musik nie an, und musicSetVolume rührt die Schüsse nie an. Jedes Spiel, das je veröffentlicht wurde, hat das gebraucht, denn Spieler drehen die Musik leiser und die Effekte lauter.

  • Musik hat keine Kanalgrenze. Soundeffekte teilen sich sechzehn Kanäle, und wenn alle sechzehn belegt sind, spielt der siebzehnte nicht. Ein Musiktrack liegt auf keinem Kanal, also kann ihn nichts verdrängen.

  • Ein Handle ist ein Track, und er pausiert, läuft weiter, stoppt und blendet aus, ganz für sich, ohne etwas anderes zu stören.

  • Musik pausiert mit dem Spiel. Drück die Pausetaste, und sie hält an, wo sie ist. Komm zurück, und sie macht weiter. Du schreibst nichts, damit das passiert.

Eine Sache, die nicht anders ist, solltest du kennen, weil die Leute das Gegenteil annehmen: Singe dekodiert eine Musikdatei vorab in den Speicher, genau wie einen Soundeffekt. Ein langer Track kostet Speicher. Er wird nicht Stück für Stück von der Festplatte gestreamt. Fünf Minuten Musik sind ein paar Dutzend Megabyte Speicher, solange sie geladen sind, also lade den Track für das Level, in dem du gerade bist, und gib ihn mit musicUnload frei, wenn du es verlässt.

Einen Track abspielen

Jeder Leser dieses Buchs hat schon ein Musikstück, denn die Engine hat eins in deinen Arbeitsordner entpackt, als du zum ersten Mal irgendetwas gestartet hast. Fang eine Datei mit diesen drei Zeilen an:

local theme = musicLoad("Singe/menuIntro.flac")
musicSetVolume(64)
musicPlay(theme, -1)


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Music: " .. (musicIsPlaying(theme) and "playing" or "stopped"))
    return OVERLAY_UPDATED
end

Starte es mit Singe -R music. Zehn Sekunden Musik, dann fängt sie von vorn an, und sie fängt immer wieder von vorn an.

Das macht die -1. musicPlay nimmt eine Anzahl von Wiederholungen: Lass sie weg oder übergib 0, und der Track spielt einmal; übergib 3, und er spielt insgesamt viermal; übergib -1, und er wiederholt sich, bis ihn etwas stoppt. Ein Menü, ein Titelbildschirm oder der Hintergrund eines Levels ist fast immer -1.

Zwei Details in diesem kleinen Skript sind die Tinte wert. musicLoad nimmt einen Pfad und keinen Pfad mit DIR .., weil Singe/menuIntro.flac eine der eigenen Dateien der Engine ist und in dem Ordner liegt, den die Engine in deinen Arbeitsordner entpackt hat. musicIsPlaying antwortet true oder false, und das and …​ or …​ mitten in diesem overlayPrint ist die Lua-Kurzform aus Lektion drei, um einen von zwei Werten auszuwählen.

Die Lautstärkeskala ist nicht die, die du kennst

musicSetVolume(64) stellt sie auf etwa die Hälfte. Soundeffekte gehen von 0 bis 63; Musik geht von 0 bis 128, also doppelt so weit.

Das ist kein Fehler und auch kein Witz. Singe kann Spiele ausführen, die für Hypseus geschrieben wurden, eine Engine, deren Musiklautstärke schon immer auf einer Skala von 0 bis 128 lag, und die Zahlen zu ändern würde die Musik dieser Spiele still und heimlich doppelt so laut machen, wie ihre Autoren es wollten. Also behält Singe beide Skalen, jede an die Familie von Aufrufen gebunden, zu der sie gehört. Effekte: 0 bis 63. Musik: 0 bis 128. Gib musicSetVolume eine Zahl außerhalb dieses Bereichs, und das Skript hält an; das siehst du am Ende dieser Lektion selbst.

Was Singe abspielt

Fast alles. WAV, Ogg Vorbis, Opus, MP3, FLAC, WavPack, AAC und darüber hinaus eine lange Liste, alles über dasselbe musicLoad.

Zwei Familien sind interessanter als die gewöhnlichen, und beide gibt es, weil sie winzig sind.

Tracker-Module — .mod, .s3m, .xm, .it und gut fünfzig Verwandte — enthalten eine Handvoll kurzer aufgenommener Instrumente und eine Liste, auf welchen Noten sie gespielt werden sollen. Eine vier Minuten lange Melodie kann unter hundert Kilobyte bleiben.

Chiptunes — .nsf, .spc, .vgm, .gbs und ihre Verwandtschaft — gehen noch weiter: Sie enthalten die Registerschreibzugriffe für den echten Soundchip eines Nintendo, eines Mega Drive oder eines Spectrum, und Singe emuliert den Chip, um sie abzuspielen. Wenn ein Spiel nach 1989 klingen soll und nicht nach einer Aufnahme von 1989, geht es so.

Beide lassen sich wie alles andere mit musicLoad laden. Der Abschnitt Video-, Audio- und Containerformate in der Referenz hat die vollständige Liste, auch welcher Container zu welchem Codec gehört.

Stoppen, Pausieren und Ausblenden

musicPause(theme)
musicResume(theme)
musicStop(theme)
musicStop(theme, 2000)

musicPause hält den Track an, wo er ist, und musicResume macht an dieser Stelle weiter. musicStop beendet ihn, und beim nächsten Abspielen fängt der Track wieder von vorn an. Mit einer zweiten Zahl blendet musicStop den Track über so viele Millisekunden aus, statt ihn abrupt abzuschneiden — hier zwei Sekunden. Dieses Ausblenden ist das Einfachste überhaupt, was du tun kannst, damit sich ein Spiel fertig anfühlt. Musik, die mitten im Takt aufhört, wenn der Spieler durch eine Tür geht, klingt wie ein Bug, selbst für jemanden, der nicht sagen könnte, warum.

Ruf einen der vier ganz ohne Handle auf, und er wirkt auf alle Musik auf einmal; genau das will ein Pausenbildschirm.

Jetzt die ehrliche Grenze, denn du wirst nach dieser Funktion suchen, und sie ist nicht da: Singe kann keine zwei Tracks überblenden. musicSetVolume ist eine einzige Verstärkung über alle Musik, keine Lautstärke pro Track, also gibt es keine Möglichkeit, einen Track lauter zu machen, während ein anderer leiser wird. Was du tun kannst, ist, den alten auszublenden und den neuen zu starten, während er verklingt; für einen Levelwechsel ist das nah genug dran, und für ein Kampfthema, das unter ein Erkundungsthema gleitet, hörbar nicht dasselbe. Wenn du heute eine echte Überblendung brauchst, machst du aus den beiden Stücken eine einzige Datei und springst darin, oder du nimmst die Überlappung in Kauf.

Musik, Video und im Takt bleiben

Wenn dein Spiel Video abspielt — das Thema von Teil drei — gibt es eine Sache über Sound zu wissen, und sie ist überhaupt kein Musik-Aufruf.

Singe zeigt einen Frame des Videos dann, wenn der Sound zu hören ist, der dazugehört, nicht nach einem Timer. Der Ton ist die Uhr, und das Bild folgt ihm. So herum ist es richtig, denn ein Ohr bemerkt eine Fünftelsekunde Versatz in einer Stimme, und ein Auge bemerkt denselben Versatz an einem Mund nicht.

Die Engine misst beim Start ihren eigenen Audioweg. Was sie nicht messen kann, ist alles, nachdem das Betriebssystem den Ton weitergereicht hat: ein Verstärker, ein Fernseher, ein HDMI-Receiver, ein Bluetooth-Headset. Jedes davon fügt seine eigene Verzögerung hinzu, sie ist auf jedem Rechner anders, und sie zeigt sich darin, dass der Ton etwas später ankommt als das Ding, das ihn gemacht hat.

Die Lösung ist eine einzige Zahl:

singeSetAudioDelay(45)

Fünfundvierzig Millisekunden „der Ton ist spät; halte das Bild entsprechend zurück“. Du kannst sie auch als --audiodelay=45 auf der Befehlszeile übergeben oder in den Eintrag des Spiels in games.dat schreiben. singeGetAudioDelay liest zurück, was gerade gilt, und das zeigt ein Service-Menü neben seinem Schieberegler an.

Du musst die Zahl nicht raten. Singes eigenes Menü hat einen Kalibrierungsbildschirm: Er spielt einmal pro Sekunde einen Klick und lässt den Bildschirm weiß aufblitzen, du stellst nach, bis Blitz und Klick gleichzeitig passieren, und er speichert das Ergebnis für jedes Spiel auf diesem Rechner. Der Abschnitt Audio-Synchronisation in der Referenz beschreibt ihn und erklärt, warum er funktioniert. Wenn du einen Automaten baust, lass ihn einmal laufen, nachdem du die Lautsprecher angeschlossen hast, und denk nie wieder daran.

Das andere Ding namens MIDI

MIDI sind zwei Dinge, die nichts miteinander zu tun haben, unter einem Namen, und sie auseinanderzuhalten ist schon der größte Teil davon, es zu verstehen.

Hier ist das erste, in einem Absatz. Eine Aufnahme — eine .wav, eine .mp3 — ist eine Messung eines Klangs, vierundvierzigtausendmal pro Sekunde genommen. MIDI ist das nicht. Eine MIDI-Datei enthält, was gespielt wurde: in diesem Moment, auf diesem Kanal, drück Taste sechzig so fest; etwas später lass sie los. Sie ist näher an Noten oder an der Lochrolle eines selbstspielenden Klaviers als an einer Aufnahme. Darum hat eine MIDI-Datei ein paar Kilobyte, wenn dieselbe Musik als Audio ein paar Megabyte hat, und darum enthält eine MIDI-Datei auch überhaupt keinen Klang. Irgendetwas muss die Noten spielen.

Eine MIDI-Datei ist Musik, also spielt sie wie Musik:

local tune = musicLoad("music/overworld.mid")
musicPlay(tune, -1)

Aber das Ding, das die Noten spielt, muss irgendwoher kommen, und dieses Ding ist ein SoundFont: eine Datei voller aufgenommener Instrumente — ein Klavier, eine Trompete, eine Snare-Drum — mit markierten Noten und Schleifenpunkten, damit die Engine daraus jede Note jedes Instruments bauen kann.

Singe liefert keinen mit. Ein guter SoundFont hat Dutzende Megabyte, und das wären Dutzende Megabyte, die jede Kopie der Engine mit sich herumträgt, für ein Format, das die meisten Spiele nie anfassen. Also nennst du einen mit --soundfont, oder du legst einen nach Singe/soundfont.sf2, damit ein gepacktes Spiel seinen eigenen mitbringt, oder du lässt Singe den finden, den deine Linux-Distribution installiert hat. Gibt es nirgends einen SoundFont, schlägt das Laden einer .mid fehl und sagt das auch.

Darum klingt dieselbe MIDI-Datei auf zwei Rechnern verschieden, und darum klang sie auf den Computern der Neunzigerjahre so schlecht. Die Datei ist eine Liste von Noten. Was du hörst, ist der SoundFont, der sie gerade gespielt hat: Ein guter ist ein Raum voller Instrumente, ein billiger ist ein Raum voller Spielzeug, und die Noten sind in beiden gleich. Wenn eine MIDI-Datei in dein Spiel kommt, liefere den SoundFont mit. Sonst hast du nicht entschieden, wie deine Musik klingt; du hast es dem überlassen, was auf dem Rechner des Spielers installiert ist.

MIDI als Leitung

Jetzt das zweite Ding, und das ist das interessante.

MIDI ist auch ein Kabel, und Nachrichten, die darüber laufen. Schließ ein Musik-Keyboard an deinen Computer an, und jede Taste, die du drückst, schickt eine Nachricht: Note On, Kanal 1, Taste 60, Anschlagstärke 90. Dreh an einem Regler einer Controller-Oberfläche, und sie schickt Controller 7 auf Kanal 1 steht jetzt auf 40. Diese Nachrichten gibt es, ob gerade Musik läuft oder nicht. Sie sind ein weiteres Eingabegerät, wie ein Joystick mit achtundachtzig Knöpfen, die wissen, wie fest du sie anschlägst.

Und es geht auch in die andere Richtung. Dein Spiel kann solche Nachrichten hinausschicken, an einen Synthesizer, ein Soundmodul, eine Bühnenlichtsteuerung oder irgendetwas anderes an der Leitung.

Ports werden ab null gezählt, und Singe öffnet nichts, bis du darum bittest — ein Spiel, das MIDI nie erwähnt, zahlt auch nie für MIDI. Ein Eingangsport und ein Ausgangsport dürfen gleichzeitig offen sein. Mach so eine Bestandsaufnahme des Rechners:

local inPort  = "none"
local outPort = "none"

if midiInputCount() > 0 and midiOpenInput(0) then
    inPort = midiInputName(0)
end
if midiOutputCount() > 0 and midiOpenOutput(0) then
    outPort = midiOutputName(0)
end

Auf einem Rechner ganz ohne MIDI sind die Anzahlen null, die Aufrufe zum Öffnen antworten false, und nichts schlägt fehl. Das ist wichtig: Es heißt, dass du diesen Code in ein echtes Spiel schreiben und es ausliefern kannst, und die neunundneunzig von hundert Spielern ohne MIDI-Keyboard merken nie, dass er da ist. Die Namen sind für einen Einstellungsbildschirm, auf dem ein Spieler den Port auswählt, denn Port null ist selten der, den er will. midiRescan sucht noch einmal nach etwas, das angeschlossen wurde, während das Spiel läuft.

Zuhören

Jede ankommende Nachricht geht an einen Callback, genauso wie jeder Tastendruck an onInputPressed geht:

local MIDI_NOTE_ON = 0x90


function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
end

Die meisten MIDI-Nachrichten sind drei Bytes lang, und die drei Zahlen, die du bekommst, sind genau diese Bytes, so wie das Gerät sie geschickt hat. Eine Nachricht mit weniger Bytes gibt dir für jedes, das ihr fehlt, eine 0.

status sagt, welche Art Nachricht es ist und von welchem Kanal sie kam, beides vermischt: Die Art steht in den oberen vier Bits und der Kanal in den unteren vier. 0x90 ist Note On, und eine Note auf Kanal 1 kommt als 0x90 an, während dieselbe Note auf Kanal 5 als 0x94 ankommt. status & 0xF0 behält die obere Hälfte und wirft den Kanal weg, und das willst du, außer es ist dir wichtig, welcher Kanal es war. (& ist das bitweise Und von Lua, und 0x90 ist eine Zahl in hexadezimaler Schreibweise — zur Basis sechzehn — weil jedes MIDI-Dokument der Welt sie so schreibt.)

data1 und data2 sind die anderen beiden Bytes, und was sie bedeuten, hängt von der Art ab. Bei einem Note On sind sie die Taste und die Anschlagstärke: Taste 60 ist das mittlere C, und die Anschlagstärke ist, wie fest sie angeschlagen wurde, 1 bis 127.

Die Prüfung auf data2 == 0 ist keine Pedanterie. Ein Note On mit einer Anschlagstärke von null bedeutet Note Off: So sagt fast jedes Keyboard, das je gebaut wurde, „ich habe losgelassen“, und wenn du das nicht herausfilterst, löst dein Spiel bei jeder Taste zweimal aus.

bytes ist die ganze Nachricht als String; so liest du eine Nachricht, die länger als drei Bytes ist.

Spielen

Senden ist leichter als Empfangen.

midiNoteOn(1, 60, 100)
midiNoteOff(1, 60)

Das mittlere C auf Kanal 1, mit hundert angeschlagen und dann losgelassen. Kanäle gehen hier von 1 bis 16, wie ein Mensch sie zählt, nicht von 0 bis 15 wie auf der Leitung; damit ist Singe nett zu dir.

Jedes midiNoteOn braucht ein midiNoteOff. Eine Note, die nie losgelassen wird, klingt, bis etwas sie stoppt, und der klassische erste MIDI-Bug ist ein Spiel, das abstürzt oder sich beendet, während drei Noten gedrückt sind, und einen Akkord im Raum hängen lässt. Also bilde Paare, und zwar über einen Timer statt von Hand:

function playTarget()
    if not midiIsOutputOpen() then
        return
    end
    local key = target
    midiNoteOn(1, key, 100)
    timerAfter(HOLD_MS, function()
        midiNoteOff(1, key)
    end)
end

local key = target leistet echte Arbeit. timerAfter führt seine Funktion vier Zehntelsekunden später aus, und bis dahin kann sich target in eine andere Note geändert haben; wenn du es in eine lokale Variable kopierst, lässt der Timer die Note los, die wirklich gedrückt wurde. Kopier alles, was ein Timer später braucht.

Die anderen Sende-Aufrufe erledigen den Rest dessen, was MIDI ist: midiProgramChange wählt, welches Instrument ein Kanal spielt, midiControlChange bewegt einen Controller (Lautstärke ist 7, Panorama ist 10, das Haltepedal ist 64), midiPitchBend verbiegt die Tonhöhe eines Kanals, und midiSend schickt jede beliebige Nachricht als rohe Bytes, für die Dinge, die die benannten Aufrufe nicht abdecken.

Ein Grund, sich dafür zu interessieren

Das alles ist Maschinerie. Hier ist, wofür sie da ist.

Setz die beiden Hälften zusammen, und das Spiel verlangt eine Note, der Spieler spielt sie auf einem echten Instrument, und das Spiel weiß, ob sie richtig war:

function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
    if data1 == target then
        score = score + 1
        pickTarget()
        playTarget()
    end
end

Elf Zeilen, und du hast das Gerüst eines Lernspiels für Musik. Füg eine Uhr hinzu, und du hast ein Rhythmusspiel, das echtes Spielen bewertet statt vier Plastikknöpfe. Nimm data2 in die Prüfung auf, und es achtet darauf, wie fest du die Note anschlägst. Vergleich die Zeit, zu der die Note ankam, mit der Zeit, zu der sie fällig war, und du bewertest das Timing auf die Millisekunde genau.

Und weil MIDI nicht nur hereinkommt, sondern auch hinausgeht, kann ein Automat Dinge, die nichts anderes kann. Ein echtes Instrument, das an den Automaten angeschlossen ist. Ein externes Soundmodul, das die Partitur spielt, damit die Melodie eine Tiefe hat, die ihr keine Sample-Bank gibt. Bühnenlichter am Automaten, die im Takt blinken, weil das Spiel ihnen den Takt geschickt hat. Wenn du zu den Leuten gehörst, die Arcade-Automaten bauen, ist das der Aufruf, mit dem der Automat ein eigenes Ding wird statt eines Kastens um einen Computer.

Das fertige Skript ist learn/27-midi.singe: die Musiksteuerung, die Portliste und das Ratespiel, in etwa hundert Zeilen. Die Leertaste schickt die Note hinaus, die linke Alt-Taste pausiert die Musik, die linke Umschalttaste blendet sie aus, und die Pfeiltasten nach oben und unten ändern die Lautstärke. Starte es ohne MIDI-Hardware, und die Musikhälfte funktioniert, und die MIDI-Hälfte sagt zweimal none, und genau so soll es sich auf dem Rechner eines Spielers verhalten.

Aufräumen

function onShutdown()
    midiCloseInput()
    midiCloseOutput()
    musicUnload(theme)
end

onShutdown wird einmal aufgerufen, wenn das Spiel endet, und dort gibt ein Skript Dinge zurück. Einen Port zu schließen, der nicht offen ist, bewirkt nichts, also musst du vorher nichts prüfen.

Probier es aus

  1. Lass es viermal statt für immer laufen. Ändere musicPlay(theme, -1) in musicPlay(theme, 3) und zähl mit. Die Zahl gibt an, wie oft er sich wiederholt, nicht, wie oft er spielt.

  2. Blende länger aus. Ändere das Ausblenden am Knopf, der die Musik stoppt, in musicStop(theme, 4000) und hör dir an, was für einen Unterschied vier Sekunden machen. Dann probier musicStop(theme, 100).

  3. Zeig den Kanal. Rechne in onMidiMessage den Kanal mit (status & 0x0F) + 1 aus und gib ihn aus. Spiel auf deinem Keyboard und sieh nach, auf welchem Kanal es ist — und dann such seine Einstellungen und ändere diesen Kanal, um dir selbst zu beweisen, dass die Zahl echt ist.

  4. Bewerte die Anschlagstärke. Gib einen Punkt für die richtige Note und drei Punkte, wenn data2 über hundert liegt, damit das Spiel belohnt, wer die Note spielt, als meinte er es ernst.

  5. Spiel die Antwort. Wenn der Spieler eine Note richtig trifft, lass das Spiel ihm einen kleinen Akkord zurückspielen, mit drei Aufrufen von midiNoteOn, ein paar Noten auseinander, und drei Timern, die sie wieder loslassen. Dafür brauchst du einen echten Ausgangsport oder einen Software-Synthesizer, und unter Linux ist das jedes Programm, das sich bei ALSA anmeldet.

Mach es absichtlich kaputt

Die beiden Lautstärkeskalen kann man leicht verwechseln, und Singe hält lieber an, als deine Musik in einer Lautstärke abzuspielen, die du nicht wolltest. Füg unter musicPlay(theme, -1) eine Zeile ein, mit der Zahl, die volle Lautstärke für einen Soundeffekt wäre, wenn du sie im Kopf verdoppelt und dich dabei verrechnet hättest:

musicSetVolume(200)

Singe hält an, bevor das Spiel startet, und nennt die Zeile in deiner Datei, in der dieser Aufruf steht:

107:musicSetVolume:  Invalid music volume value:  200

Die Zeile, der Aufruf, der sich gewehrt hat, und die Beschwerde, die dir hier die Zahl wörtlich zurückgibt, damit es keinen Streit darüber gibt, was angekommen ist. Musik ist 0 bis 128. Soundeffekte sind 0 bis 63. Wenn ein Lautstärke-Aufruf dein Spiel anhält, lautet die Frage, mit welcher der beiden Familien du gerade sprichst.

Was du gelernt hast

  • Musik und Soundeffekte sind in Singe getrennt: eigene Lautstärken, keine Kanalgrenze für Musik und eine Pause, die der Pause des Spiels folgt.

  • Eine Musikdatei wird vorab in den Speicher dekodiert, also kostet ein langer Track Speicher und sollte freigegeben werden, wenn du das Level verlässt.

  • musicPlay(track, -1) wiederholt für immer; eine positive Zahl gibt an, wie oft sich der Track wiederholt.

  • Die Musiklautstärke geht von 0 bis 128 und die Effektlautstärke von 0 bis 63, und der Unterschied ist Kompatibilität mit Hypseus, kein Fehler.

  • musicStop(track, milliseconds) blendet aus, und ein Ausblenden ist der billigste Feinschliff, den es gibt. Es gibt keine Überblendung, weil eine einzige Verstärkung für alle Musik gilt.

  • Singe zeigt Video nach der Uhr des Tons, und singeSetAudioDelay gleicht die Verzögerung dessen aus, woraus der Ton kommt.

  • Eine MIDI-Datei enthält Noten, keinen Klang, und braucht einen SoundFont, um überhaupt hörbar zu sein. Singe liefert keinen mit, also liefere deinen eigenen mit, sonst ist deine Musik das, was der Rechner des Spielers zufällig hat.

  • MIDI-Ports sind etwas völlig anderes: Live-Nachrichten hinein und hinaus, auf einer Leitung, ohne irgendetwas mit MIDI-Dateien zu tun.

  • onMidiMessage gibt dir die rohen Bytes. Die oberen vier Bits von status sind die Art, die unteren vier der Kanal, und ein Note On mit Anschlagstärke null bedeutet Note Off.

  • Jedes midiNoteOn braucht ein midiNoteOff, und mit einem Timer bildest du die Paare.

  • Auf einem Rechner ohne MIDI antwortet jeder Aufruf false oder null, und nichts schlägt fehl, also kannst du MIDI-Unterstützung gefahrlos ausliefern.

Beim nächsten Mal

Dein Spiel hat Musik und einen Punktestand, den ein MIDI-Keyboard hochtreiben kann. Lektion achtundzwanzig bringt diesen Punktestand vom Rechner weg: Konten, Highscore-Tabellen, die andere Leute sehen können, und der Katalog, der dein Spiel der Welt zeigt.

Lektion 28: Online

Die fertige Lektion

In Lektion zwölf hast du einen Highscore gespeichert. Am nächsten Morgen ist er immer noch da, und dafür ist ein Highscore größtenteils da, aber es ist ein Highscore auf einem einzigen Rechner. Diese Lektion bringt einen Punktestand auf eine Bestenliste, die andere Leute sehen können.

Es ist auch die Lektion über das Scheitern. Alles andere, was du geschrieben hast, scheitert aus Gründen, die du finden kannst: Eine Datei fehlt, eine Zahl ist falsch, eine Funktion ist falsch geschrieben. Das Netzwerk scheitert aus Gründen, die niemand im Raum sehen kann. In einem Gebäude, in dem du nie warst, wurde ein Kabel herausgezogen, und dein Spiel muss weiterlaufen. Das meiste von dem, was folgt, handelt davon.

Was der Dienst ist

Singe kann mit einem Master-Dienst sprechen, einem Server, der drei Dinge verwaltet:

  • ein Konto, das zum Rechner gehört und nicht zu einem einzelnen Spiel;

  • einen Katalog von Spielen zum Herunterladen und Aktualisieren;

  • Highscore-Bestenlisten, eine oder mehrere pro Spiel.

Der Standarddienst ist master.singeengine.com, und ein Betreiber, der seinen eigenen betreibt, richtet den Rechner woandershin aus. Der Abschnitt über den Online-Dienst im Handbuch beschreibt beide Seiten.

Jetzt der Teil, den die Leute überspringen. Der Dienst ist kein Mehrspielerdienst: Es gibt keine Möglichkeit, dass zwei Spieler im selben Spiel sind. Er ist keine Cloud für Spielstände; der Spielstand aus Lektion zwölf bleibt auf dem Rechner. Er ist kein Kopierschutz, und nichts darin hindert irgendwen daran, dein Spiel zu spielen. Er ist keine Pflicht: Ein Spiel, das sich nie anmeldet, läuft genau so, wie es immer gelaufen ist, und das ist der einzige vernünftige Standard für etwas, das eine funktionierende Verbindung braucht.

Die Bestenliste ist also ein Extra. Behalte den lokalen Highscore aus Lektion zwölf, zeig ihn weiter an, und lass die Online-Bestenliste das sein, was manchmal da ist.

Anmelden passiert einmal, und nicht in deinem Spiel

Das Konto gehört zum Rechner. Es wird im mitgelieferten Menü angelegt und angemeldet, hinter der Taste, die mit INPUT_SERVICE belegt ist, im Tool namens Online Account. Das Token, das es dabei bekommt, wird in master.dat im obersten Datenordner geschrieben, eine Ebene über dem eigenen Datenordner jedes Spiels, also reicht jedes Spiel auf dem Rechner seine Punkte unter derselben Anmeldung ein.

Dein Spiel fragt nie nach einer E-Mail-Adresse und nie nach einem Passwort. Es gibt keine Funktion dafür, und das ist Absicht: Ein Spieler, der ein Passwort in ein Spiel tippt, das er heruntergeladen hat, kann nicht wissen, wohin es geht.

Als was ein Spieler auf einer Bestenliste erscheint, ist ein Handle: 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. Es wird getrennt vom Konto geführt, es ist das Einzige an einem Spieler, das andere Spieler sehen, und es wird einmal gewählt — ein Betreiber kann eins ändern, ein Spieler nicht, denn eine Bestenliste, deren Namen sich ständig ändern, ist eigentlich niemandes Geschichte. Solange kein Handle gewählt ist, werden Punktestände abgelehnt, denn ein Punktestand, auf dem kein Name steht, steht in keinem sinnvollen Sinn auf einer Bestenliste.

Das Tool Online Account zeigt den Namen, unter dem dieser Rechner einreicht, und dein Spiel liest ihn mit scorePlayerName(), das nil antwortet, wenn es keinen gibt. Gut zu wissen, bevor es dich verwirrt: Ein Punktestand, hinter dem kein Handle steht, wird vom Dienst abgelehnt, nicht von scoreSubmit, also erfährt dein Spiel nichts davon. Wenn scorePlayerName() nil ist, sag das auf dem Bildschirm, solange noch jemand da ist, der es lesen kann.

Dein Spiel braucht eine ID

Eine Bestenliste muss unter irgendetwas geführt werden. Dieses Etwas ist GAME_ID im Eintrag deines Spiels in games.dat, der Datei, die du in Lektion dreizehn angelegt hast:

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

Es ist eine UUID, in genau dieser Form: acht hexadezimale Ziffern, drei Gruppen zu vier, dann zwölf, getrennt durch Bindestriche. Erzeug dir eine, wie du willst, und füg sie ein; es ist egal, welche du bekommst, nur darf sie sich nie wieder ändern. Der Eintrag zu singeGetGameId in der Referenz erklärt, warum nichts anderes akzeptiert wird.

singeGetGameId() gibt sie zurück, oder nil, wenn der Eintrag keine hat. Ein Spiel ohne ID kann gespielt, aber in keine Rangliste aufgenommen werden, und vorher zu fragen ist der Weg, keine Bestenliste anzubieten, die nie funktionieren kann:

if singeGetGameId() then
    -- showLeaderboardButton ist deine eigene Funktion, keine von Singe.
    showLeaderboardButton()
end

Die sechs Aufrufe

Alles, was ein Spiel mit dem Dienst macht, sind sechs Funktionen, und sie kommen aus Singe/Framework.singe, also ist das dofile oben in deinem Skript hier keine Kür:

dofile("Singe/Framework.singe")

scoreBegin() sagt, dass eine Partie beginnt. scoreSubmit(value) stellt einen Punktestand in die Warteschlange. scoreBoard(onDone) holt die Bestenliste. scorePlayerName() ist das Handle. scoreWaiting() ist die Zahl der Punktestände, die noch nicht hinausgegangen sind. Und scoreUpdate() muss einmal pro Frame laufen, aus onOverlayUpdate, sonst wird keiner der anderen je fertig.

Der letzte ist der ganze Trick dieser Lektion, darum wird er zweimal gesagt. Nichts hier spricht mit dem Netzwerk, wenn du es aufrufst. scoreSubmit schreibt in eine Warteschlange und kehrt sofort zurück. scoreBoard merkt sich, was du willst, und kehrt sofort zurück. Die eigentliche Arbeit passiert Stück für Stück in scoreUpdate, zwischen deinen Frames, und darum ruckelt dein Spiel nie, während die Leitung langsam ist. Lass scoreUpdate weg, und nichts geht kaputt, nichts meldet einen Fehler, und nie passiert irgendetwas.

function onOverlayUpdate()
    scoreUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Einen Punktestand einreichen

Am Ende eines Spiels:

if scoreSubmit(score) then
    fetchBoard()
else
    saying = "Kept here only:  " .. whyNotPosted()
end

scoreSubmit antwortet false, wenn es kein Konto gibt oder das Spiel keine GAME_ID hat, und true, wenn der Punktestand in die Warteschlange gegangen ist. Beachte, was das else nicht tut: Es wirft den Punktestand nicht weg, es entschuldigt sich nicht lang und breit, und es hält den Spieler nicht davon ab, ein neues Spiel zu starten. Es sagt eine kurze Zeile, denn der Spieler hat nichts falsch gemacht und kann es von hier aus nicht beheben.

Die Warteschlange ist der Grund, warum das sicher ist. Ein Punktestand in der Warteschlange wird auf die Festplatte geschrieben, also übersteht er das Ausschalten des Rechners, und er wird dem Dienst übergeben, sobald es das nächste Mal eine Verbindung gibt — eine Stunde später oder nächsten Dienstag. Darum landet auch ein Automat in einem Raum mit schlechtem WLAN am Ende auf der Bestenliste.

Sei ehrlich zu dir, was die Grenze dieses Versprechens angeht: Die Warteschlange hält Punktestände für einen Rechner, der ein Konto hat. Hat sich nie jemand angemeldet, antwortet scoreSubmit false, und der Punktestand wird nicht für später aufgehoben, weil es niemanden gibt, für den man ihn aufheben könnte. scoreWaiting() sagt dir, wie viele noch in der Warteschlange sind, und diese Zahl irgendwo zu zeigen ist eine Freundlichkeit: Sie ist der Unterschied zwischen „der Dienst ist kaputt“ und „drei deiner Punktestände warten darauf, dass das Internet zurückkommt“.

scoreBegin() verdient einen eigenen Absatz. Ruf es auf, wenn eine Partie beginnt, und der Dienst notiert den Moment nach seiner eigenen Uhr. Der Punktestand, der folgt, trägt mit sich, wie lange die Partie gedauert hat, gemessen auf dem Server, und das ist die einzige Zahl in einer Einreichung, die nicht durch den Rechner des Spielers gegangen ist. Aufgrund dieser Zahl wird nichts abgelehnt: Sie wird dem, der den Dienst betreibt, neben dem Punktestand gezeigt, und ein Mensch entscheidet. Ein Rechner, der offline war, als die Partie begann, zeichnet keine Zeit auf, und das ist ehrlich, nicht kaputt.

Und wo wir schon ehrlich sind: Ein eingereichter Punktestand ist eine Behauptung. Das Spiel läuft auf dem Computer des Spielers, also kann nichts, was der Client tut, mehr daraus machen, und ein geheimer Schlüssel, der in deinem Spiel mitgeliefert wird, sähe nur nach Sicherheit aus. Der Dienst zeichnet auf, wer was behauptet hat, begrenzt, wie schnell Punktestände ankommen können, und markiert die wilden, damit ein Mensch sie sich ansieht. Entwirf deine Bestenliste mit diesem Wissen.

Die Bestenliste zurücklesen

scoreBoard ist die erste Funktion in diesem Buch, die eine Funktion als Argument nimmt.

scoreBoard(function(ok, result)
    ...
end)

Du hast in Lektion fünf Funktionen geschrieben und ihnen Namen gegeben. Diese hier hat keinen Namen: Sie wird dort geschrieben, wo sie gebraucht wird, direkt an scoreBoard übergeben und später aufgerufen — vielleicht Sekunden später — wenn die Antwort ankommt. Das ist wieder ein Callback, dieselbe Idee wie onOverlayUpdate, nur dass du diesmal bestimmst, wer ihn aufruft.

ok ist true oder false. Ist es false, ist result ein kurzer String, der sagt, warum. Ist es true, ist result eine Tabelle mit zwei Teilen:

  • result.top, eine Liste von Zeilen, jede mit einem name und einem value;

  • result.standing, mit dem eigenen value dieses Spielers, seinem rank und der Zahl der players auf der Bestenliste — dieser Teil kann fehlen, wenn der Spieler nichts darauf hat.

Zwischen dem Aufruf und dem Callback läuft dein Spiel weiter und zeichnet. Diese Lücke ist echt, und der Spieler kann sie sehen, also füll sie mit etwas. Das Skript unten setzt eine Textzeile auf "Asking the service…​", bevor es aufruft, und der Callback ersetzt diese Zeile entweder durch die Bestenliste oder durch den Grund, warum es keine gibt. Ein Bildschirm, der vier Sekunden lang nichts sagt, sieht kaputt aus; ein Bildschirm, der sagt, was er tut, ist nur langsam.

Der Katalog

Das Dritte, was der Dienst tut, ist, Spiele aufzulisten. Das Tool Get Games im Menü zeigt alles, was der Dienst anbietet, markiert, was auf diesem Rechner schon installiert ist, und lädt es herunter, aktualisiert oder entfernt es. Ein Download wird mit der Prüfsumme verglichen, die der Katalog veröffentlicht hat, bevor er irgendetwas ersetzt, also schlägt eine Übertragung, die beschädigt ankommt, fehl, statt ein Spiel zu installieren, das nicht läuft. Ein Spiel, das der Dienst zurückgezogen hat, funktioniert weiter und wird als installiert, aber nicht mehr angeboten angezeigt: Es bekommt nur keine Updates mehr, denn wer ein Spiel hat, der hat es.

Dein Spiel ruft nichts davon auf, und das sollte es auch nicht. Der Katalog ist für dich als Autor eines Spiels wichtig, nicht als Schreiber eines Skripts: Dorthin kommt deine .game-Datei, wenn du sie veröffentlichst, und das ist Lektion dreißig, und er ist ein weiterer Grund, warum deine games.dat eine GAME_ID braucht, die sich nie ändert. Falls du die Liste doch einmal aus einem Skript heraus willst: Singe/Master.singe ist das Modul, das unter alledem liegt, und es lohnt sich, es einmal zu lesen.

Was der Dienst über einen Spieler weiß

Wenn du ein Spiel auslieferst, das Punktestände einreicht, übergibst du die Daten von jemand anderem an einen Server, und das ist deine Verantwortung, auch wenn du den Server nicht geschrieben hast. Also sag es klar und deutlich, im Info-Bildschirm oder in der Liesmich-Datei deines Spiels:

  • Der Dienst speichert eine E-Mail-Adresse und ein Passwort für das Konto. Mit der Adresse wird ein verlorenes Passwort wiederhergestellt, und für nichts anderes. Sie wird anderen Spielern nie gezeigt und kann nachträglich nicht geändert werden.

  • Das Handle ist das, was auf Bestenlisten erscheint. Es wird absichtlich vom Konto getrennt geführt, damit andere Spieler nie eine Adresse zu sehen bekommen, und es wird mit einer Liste von Namen, die niemand beanspruchen sollte, und von Wörtern abgeglichen, die nicht auf einen Bildschirm in einem öffentlichen Raum gehören.

  • Ein Punktestand trägt seinen Wert, die Bestenliste, auf der er steht, die Zeit, die der Dienst aufgezeichnet hat, und das Handle. Das ist alles.

  • Der Katalog weiß, welche Spiele auf dem Rechner installiert sind und in welcher Version, denn so bietet er dir ein Update an.

Was nichts davon tut, ist, einem Spieler von Spiel zu Spiel zu folgen, irgendetwas zu verkaufen oder in den Rechner nach etwas zu greifen, das du nicht geschickt hast. Dein Spiel sollte der Liste nichts hinzufügen. Wenn du einem Punktestand zusätzliche Informationen anhängst — scoreSubmit nimmt dafür ein optionales drittes Argument — dann sollten sie nur vom Spiel handeln.

Das Skript

Ein Reaktionstest: Warte auf das Wort, drück den Knopf, und dein Punktestand ist, was von tausend übrig bleibt. Es ist ein kleines Spiel, und der Rest davon ist der Online-Teil.

Leg einen Ordner namens reaction an und schreib das hier in reaction.singe darin. Gib dem Ordner eine games.dat wie die aus Lektion dreizehn, die reaction/reaction.singe nennt, mit der Zeile GAME_ID von oben in ihrem Eintrag.

dofile("Singe/Framework.singe")

local WAIT_MIN = 1000
local WAIT_MAX = 3000
local PERFECT  = 1000

local state    = "attract"
local goAt     = 0
local score    = 0
local best     = saveGet("best", 0)
local saying   = "Button 1 to play."
local top      = nil
local standing = nil


local function whyNotPosted()
    if not singeGetGameId() then
        return "this game has no GAME_ID."
    end
    return "this machine is not signed in."
end


local function fetchBoard()
    top      = nil
    standing = nil
    saying   = "Asking the service..."
    scoreBoard(function(ok, result)
        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end
        top      = result.top
        standing = result.standing
        if #top == 0 then
            saying = "The board is empty.  You could be first."
        else
            saying = ""
        end
    end)
end


local function finish(reaction)
    score = PERFECT - reaction
    if score < 0 then
        score = 0
    end
    if score > best then
        best = score
        saveSet("best", best)
    end
    state = "result"
    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end
end


local function play()
    state    = "waiting"
    goAt     = singeGetTicks() + math.random(WAIT_MIN, WAIT_MAX)
    score    = 0
    top      = nil
    standing = nil
    saying   = ""
    scoreBegin()
end


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state  = "result"
        score  = 0
        saying = "Too soon.  Nothing posted."
    elseif state == "go" then
        finish(singeGetTicks() - goAt)
    else
        play()
    end
end


function onOverlayUpdate()
    scoreUpdate()

    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST")

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Best on this machine:  " .. best)
    overlayPrint(2, 5, "Posting as:  " .. (scorePlayerName() or "nobody yet"))
    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())
    overlayPrint(2, 8, saying)

    if top then
        for place, row in ipairs(top) do
            if place > 5 then
                break
            end
            overlayPrint(2, 9 + place, place .. ".  " .. row.name .. "  " .. row.value)
        end
    end
    if standing then
        overlayPrint(2, 16, "You are " .. standing.rank .. " of " .. standing.players .. ".")
    end

    return OVERLAY_UPDATED
end

Starte es mit Singe -R reaction. Auf einem Rechner, der nie angemeldet war, läuft das Spiel, es behält deinen besten Punktestand und sagt Kept here only: this machine is not signed in. Das ist der wichtige Durchlauf, und es ist der, den die meisten deiner Spieler haben werden.

Was gerade passiert ist

local top      = nil
local standing = nil

Zwei Variablen, die meistens nil sind. nil heißt „hier ist nichts“, und das steht in einer Variablen, bevor irgendetwas hineingelegt wird. Diese beiden enthalten die Bestenliste, wenn es eine gibt, und nil, wenn nicht: während die Anfrage unterwegs ist, nach einem Fehlschlag und vor dem ersten Spiel. Der Zeichencode fragt if top then und zeichnet nichts, wenn nichts da ist, und das ist die Form von fast jedem Stück Netzwerkcode, das du schreiben wirst.

    saying   = "Asking the service..."
    scoreBoard(function(ok, result)

Die Reihenfolge ist wichtig. Die Textzeile wird vor dem Aufruf gesetzt, denn der Aufruf kehrt sofort zurück, und der Callback läuft vielleicht erst nach Sekunden. Wenn du den Text nur im Callback setzt, zeigt der Bildschirm bis zur Antwort die Meldung des letzten Spiels, und das ist genau die falsche Meldung im genau falschen Moment.

        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end

Der Fehlschlag kommt zuerst, und er ist kurz. tostring macht aus allem, was zurückkam, Text, damit das Zusammenfügen mit .. nicht fehlschlagen kann; result ist ein String, wenn ok falsch ist, aber eine Zeile Zeichencode, die dem Typ von etwas vertraut, das sie von einem Server bekommen hat, ist eine Zeile, die auf ihren Absturz wartet. Der Spieler sieht einen Satz, und das Spiel läuft weiter.

    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end

Dass scoreSubmit false antwortet, ist kein Fehler. Es ist eine Tatsache über diesen Rechner, und die beiden Tatsachen, die es bedeuten kann, sollte man auseinanderhalten, und genau das tut whyNotPosted: Eine fehlende GAME_ID ist dein Fehler, und ein nicht angemeldeter Rechner ist niemandes Fehler. Der lokale beste Punktestand wurde schon gespeichert, zwei Zeilen darüber, bevor irgendetwas davon versucht wurde. Erst speichern, dann einreichen, immer.

    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())

Die Warteschlange, auf dem Bildschirm. Auf einem Rechner mit Verbindung steht hier für immer 0, und niemand bemerkt es. Auf einem Rechner ohne Verbindung steigt die Zahl, und der Spieler weiß, dass das Spiel seine Punktestände aufbewahrt, statt sie zu fressen.

function onOverlayUpdate()
    scoreUpdate()

Erste Zeile des Frames, vor allem anderen. Setz es dorthin, wo kein if es überspringen kann, denn ein scoreUpdate, das nur auf dem Game-Over-Bildschirm läuft, ist eine Warteschlange, die sich nur auf dem Game-Over-Bildschirm leert.

Probier es aus

  1. Zieh den Stecker. Trenn den Rechner vom Netzwerk, spiel ein paar Spiele und beobachte die Zahl bei Waiting to send. Steck ihn wieder ein und sieh zu, wie sie sinkt, ohne dass du etwas tust.

  2. Lösch die ID. Nimm GAME_ID aus deiner games.dat heraus und starte es noch einmal. Die Meldung ändert sich. Setz sie wieder ein.

  3. Zeig mehr von der Bestenliste. Die Schleife hört nach fünf Zeilen auf. Das Overlay ist standardmäßig achtzehn Zeichenzeilen hoch, also rechne aus, wie viele du wirklich unterbringst, und verschieb die Zeile mit standing, wenn nötig.

  4. Gib der Bestenliste einen Namen. scoreSubmit(score, "reaction") und scoreBoard(onDone, "reaction") benutzen eine Bestenliste mit diesem Namen statt der, die nach deinem Skript benannt ist. Reich aus demselben Spiel auf zwei Bestenlisten ein — sagen wir, eine für den Punktestand und eine für die schnellste einzelne Reaktion — und lass Knopf 2 umschalten, welche gezeigt wird.

  5. Mach das Warten sichtbar. Zeichne zwischen dem Aufruf von scoreBoard und dem Moment, in dem der Callback läuft, einen Punkt, der sich bewegt. Dann finde heraus, wie lange das bei deiner Verbindung wirklich dauert und ob es sich gelohnt hat, ihn zu zeichnen.

Mach es absichtlich kaputt

Nimm die erste Zeile aus onOverlayUpdate heraus, sodass der Aufruf scoreUpdate() fehlt, und spiel ein Spiel.

Nichts passiert. Kein Fehler, keine Meldung, keine Bestenliste, und die Zahl bei Waiting to send steigt und bleibt für immer oben. Das Spiel läuft einwandfrei.

Das ist die schlimmste Art von Bug, und es lohnt sich, ihr einmal absichtlich zu begegnen: ein fehlender Schritt, der Stille erzeugt statt einer Beschwerde. Es gibt keine Zeilennummer, die du dir ansehen kannst, denn nichts ist schiefgegangen — du hast um Arbeit gebeten und ihr dann nie eine Gelegenheit gegeben, zu passieren. Wenn etwas in Singe, das einen Callback nimmt, dich nie zurückruft, ist die erste Frage immer, ob das, was es antreibt, in jedem Frame läuft.

Der andere Fehler, dem du begegnen wirst, ist lauter. Setz scoreUpdate() wieder ein, lösch oben die Zeile mit dofile und starte es:

Error executing function 'onOverlayUpdate':  reaction/reaction.singe:89: attempt to call a nil value (global 'scoreUpdate')
stack traceback:
	reaction/reaction.singe:89: in function 'onOverlayUpdate'

Zeile 89 ist das scoreUpdate(), das du wieder eingesetzt hast, eine Zeile weiter oben, jetzt wo das dofile fehlt. Lies wie immer die erste Zeile: die Funktion, die die Engine aufgerufen hat, die Datei, die Zeile und die Beschwerde. Wieder nil — im Namen scoreUpdate steckt nichts, weil die Datei, die ihn definiert, nie geladen wurde. Alle sechs dieser Aufrufe wohnen in Singe/Framework.singe.

Was du gelernt hast

  • Der Dienst verwaltet ein Konto, einen Katalog und Highscore-Bestenlisten. Er ist kein Mehrspielerdienst, keine Cloud für Spielstände und nie Pflicht.

  • Das Konto gehört zum Rechner und wird in den Service-Tools des Menüs angemeldet. Ein Spiel fragt nie nach einem Passwort.

  • Eine Bestenliste wird unter GAME_ID in games.dat geführt, einer UUID, die sich nie ändern darf. singeGetGameId() liest sie.

  • scoreSubmit stellt einen Punktestand in eine Warteschlange auf der Festplatte und kehrt sofort zurück; die Warteschlange übersteht das Ausschalten des Rechners.

  • scoreUpdate() muss in jedem Frame laufen, sonst wird nichts von dem, was der Dienst tut, je fertig.

  • scoreBoard übergibt seine Antwort an eine Funktion, die du schreibst und die später läuft. Zeichne in der Zwischenzeit etwas.

  • Jeder Netzwerkaufruf kann fehlschlagen, und ein Fehlschlag ist kein Fehler. Sag eine kurze Zeile und spiel weiter.

  • Ein eingereichter Punktestand ist eine Behauptung, und der Dienst behandelt ihn auch so.

  • Behalte den lokalen Highscore. Er ist der, der immer funktioniert.

Beim nächsten Mal

Ein Highscore ist eine einzige Zahl, und der Spielstand aus Lektion zwölf ist der richtige Ort dafür. Lektion neunundzwanzig ist für alles andere, was ein Spiel aufbewahren will: jede Runde, die irgendwer spielt, die Level, die du mitlieferst, und die Fragen, die du beiden stellen willst. Sie nimmt diesen Reaktionstest und gibt ihm eine Datenbank.

Lektion 29: Daten aufbewahren

Die fertige Lektion

Lektion zwölf hat einen Highscore gespeichert: eine Zahl, unter einem Namen, am nächsten Morgen noch da. Für einen Highscore ist das genau richtig, und für fast alles andere, was ein Spiel aufbewahren will, ist es falsch. Eine Liste jeder Runde, die irgendwer gespielt hat. Die beste Zeit auf jeder von zwanzig Strecken. Vierzig Level, die jemand in einer Tabellenkalkulation entworfen hat. Die Frage „Was ist mein Bestwert auf der schweren Stufe?“, die ein Haufen gespeicherter Zahlen nicht beantworten kann, ohne dass du die Antwort von Hand schreibst.

Genau dafür ist eine Datenbank da, und Singe hat eine eingebaut. Diese Lektion nimmt den Reaktionstest aus Lektion achtundzwanzig, gibt ihm Stufen, die mit dem Spiel ausgeliefert werden, und lässt ihn jeden Durchgang aufbewahren, den irgendwer spielt, und Fragen dazu beantworten.

Was eine Datenbank ist

Eine Datenbank ist eine Datei voller Tabellen. Eine Tabelle besteht aus Zeilen und Spalten, wie eine Tabellenkalkulation, bei der die Spaltennamen vorher feststehen: Eine Tabelle mit Durchgängen könnte in jeder Zeile eine Stufe, eine Punktzahl und eine Zeit haben. Du legst Zeilen hinein und stellst Fragen, um Zeilen herauszubekommen, und die Fragen werden in SQL geschrieben, einer kleinen Sprache, die diese Arbeit schon gemacht hat, bevor es die meisten Programmiersprachen gab, von denen du je gehört hast.

Die Datenbank, die Singe mitbringt, ist SQLite. Sie ist kein Server, den du installierst, und kein Dienst, bei dem du dich registrierst. Sie ist eine Bibliothek, die Datenbank ist eine gewöhnliche Datei, und dasselbe SQLite steckt in deinem Handy, in deinem Browser und wahrscheinlich in deinem Auto. Du musst kein SQL können, um dieser Lektion zu folgen; jede Anweisung darin wird erklärt, wenn sie vorbeikommt, und die drei, die du am häufigsten brauchen wirst — CREATE TABLE, INSERT und SELECT — sind alle dabei.

Eine öffnen

local sqlite3 = require("sqlite3")

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

require("sqlite3") lädt eine Bibliothek, die mit Singe kommt, und gibt sie dir als Tabelle zurück, also ist alles, was SQLite kann, sqlite3. irgendwas. sqlite3.open öffnet eine Datenbankdatei und legt sie an, wenn es sie noch nicht gibt, also macht der erste Start deines Spiels eine leere, und jeder Start danach findet sie wieder.

Die Datei kommt nach singeGetDataPath(), aus demselben Grund wie der Spielstand aus Lektion zwölf: Der eigene Ordner eines Spiels kann auf einer Disc liegen, auf einer Netzwerkfreigabe oder in eine einzige Datei gepackt sein, und in nichts davon kann man schreiben. Alles, was ein Spiel schreibt, kommt in seinen Datenordner.

Eine Tabelle anlegen

Eine leere Datenbank hat keine Tabellen. Du legst eine an, indem du sie beschreibst:

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

exec führt SQL aus, das nichts zurückgibt. Die doppelten eckigen Klammern sind Luas langer String: Alles zwischen ihnen, Zeilenumbrüche eingeschlossen, ist ein einziger String, und so hältst du SQL lesbar.

CREATE TABLE nennt die Tabelle und ihre Spalten, jede mit einem Typ: TEXT für Wörter und INTEGER für ganze Zahlen. NOT NULL heißt, dass jede Zeile dort einen Wert haben muss. INTEGER PRIMARY KEY ist etwas Besonderes: SQLite füllt es selbst aus und zählt dabei hoch, also bekommt jede Zeile ihre eigene Nummer, ohne dass du darüber nachdenken musst.

IF NOT EXISTS sorgt dafür, dass das bei jedem Spielstart gefahrlos laufen kann. Beim ersten Mal legt es die Tabelle an. Bei jedem Mal danach ist die Tabelle schon da, und die Zeile tut nichts. Ohne diese drei Wörter würde der zweite Start deines Spiels mit einem Fehler anhalten, der sagt, dass es die Tabelle schon gibt.

Eine Zeile hineinlegen

Du könntest das SQL für eine neue Zeile bauen, indem du Strings zusammenklebst:

runs:exec("INSERT INTO runs (stage, score, at) VALUES ('" .. stage .. "', " .. score .. ", " .. os.time() .. ")")

Lass das. Es funktioniert, bis ein Name einen Apostroph enthält, und dann beendet dieses Anführungszeichen den String zu früh, und die Anweisung ist Unsinn. In einem Spiel, in dem Spieler etwas tippen dürfen, wird es schlimmer: Was immer sie tippen, wird Teil deines SQL.

Der richtige Weg ist, die Anweisung einmal zu schreiben, mit Fragezeichen dort, wo die Werte hinkommen, und die Werte getrennt zu übergeben:

local addRun = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")

local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
end

prepare macht aus dem SQL eine Anweisung, die du immer wieder benutzen kannst. bind_values setzt der Reihe nach einen Wert in jedes Fragezeichen. Was immer ein Wert enthält, Apostrophe eingeschlossen, er ist ein Wert und nie Teil des SQL. step führt die Anweisung aus, und reset macht sie bereit, wieder zu laufen. os.time() ist gewöhnliches Lua: die aktuelle Zeit als Anzahl von Sekunden, und das ist der einfachste Weg, „wann“ zu speichern.

Einmal vorbereiten und die Anweisung wiederverwenden ist außerdem schneller, weil SQLite nur einmal ausrechnet, wie es sie ausführt. Für ein Spiel, das eine Zeile pro Minute schreibt, spielt das keine Rolle. Für einen Level-Editor, der tausend schreibt, schon.

Fragen stellen

Zeilen kommen mit nrows wieder heraus, das ein SELECT ausführt und dir jede Zeile als Tabelle gibt, mit den Spaltennamen als Schlüsseln:

for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC LIMIT 5") do
    debugPrint(row.stage .. "  " .. row.score)
end

Lies das SQL von links nach rechts. SELECT stage, score sagt, welche Spalten du willst. FROM runs sagt, welche Tabelle. ORDER BY score DESC sortiert die Zeilen nach Punktzahl, die höchste zuerst, und LIMIT 5 hört nach fünf auf. Das ist eine Highscore-Tabelle, und sie hat nie Sortiercode von dir gebraucht.

Die Fragen können klüger sein als die, die du von Hand schreiben wollen würdest:

for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
    debugPrint(row.stage .. ":  best " .. row.top .. " of " .. row.tries)
end

GROUP BY stage fasst die Zeilen zu einer Gruppe pro Stufe zusammen, und MAX(score) und COUNT(*) werden für jede Gruppe ausgerechnet: die beste Punktzahl auf dieser Stufe und wie oft sie gespielt wurde. AS top gibt der Antwort einen Namen, und das ist der Schlüssel, mit dem du sie wieder ausliest.

Wenn eine Frage nur eine Antwort hat, gibt urows die Spalten selbst zurück statt einer Tabelle, und das ist für eine Anzahl ordentlicher:

for count in runs:urows("SELECT COUNT(*) FROM runs") do
    played = count
end

Frag, wenn es sich ändert

Keine dieser Fragen gehört in onOverlayUpdate. Eine Abfrage ist schnell, aber sechzig davon pro Sekunde, für Antworten, die sich einmal pro Minute ändern, heißt, dass das Spiel neunundfünfzig von sechzig Malen dieselbe Frage stellt und dieselbe Antwort bekommt.

Also fragt das Spiel dann, wenn sich die Antwort geändert haben kann — einmal beim Start und dann jedes Mal, wenn ein Durchgang aufgezeichnet wird — und behält, was zurückkam, in gewöhnlichen Tabellen:

local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    -- und dasselbe für die anderen beiden Fragen
end

onOverlayUpdate zeichnet aus best, und das kostet nichts. record ruft nach jeder neuen Zeile refresh auf, also ist die Tabelle auf dem Bildschirm nie veraltet.

Daten, die mit dem Spiel ausgeliefert werden

Die andere Hälfte der Daten eines Spiels ist der Teil, den du schreibst, bevor irgendwer spielt: die Stufen, die Level, die Gegenstände, die Dialogzeilen. Das kann auch eine Datenbank sein, gemacht mit irgendeinem SQLite-Werkzeug — dem Programm sqlite3 auf der Befehlszeile oder einem Programm mit Fenstern wie DB Browser for SQLite — und in den Ordner deines Spiels neben seine Grafiken gelegt. Das Grafik-Kit hat eine, stages.db, mit einem Namen und der kürzesten und längsten Wartezeit für jede Stufe.

Ein Spiel öffnet diese anders:

local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

DIR ist der Ordner deines Spiels, in dem die Grafiken liegen. sqlite3.OPEN_READONLY sagt, dass du nur lesen willst, und das zählt an dem Tag, an dem du auslieferst. Wenn du dein Spiel in der nächsten Lektion in eine einzige Datei packst, wird eine schreibgeschützt geöffnete Datenbank direkt aus dieser Datei gelesen, ohne dass irgendetwas entpackt wird. Eine, die zum Schreiben geöffnet wird, wird einmal in den Datenordner des Spiels kopiert, und von da an änderst du die Kopie; die Datei, die du ausgeliefert hast, wird nie beschrieben.

Halte die beiden Arten also auseinander. Was du gemacht hast, kommt in deinen Ordner und wird schreibgeschützt geöffnet. Was das Spiel macht, kommt in den Datenordner. Die Stufen werden hier einmal beim Start in eine gewöhnliche Tabelle gelesen, und die Datenbank wird geschlossen, denn für eine Liste mit vier Stufen lohnt es sich nicht, eine Datei offen zu halten.

Zum Schluss schließen

Anweisungen und Datenbanken belegen Speicher und halten eine Datei offen, bis du sagst, dass du fertig bist, und der ordentliche Ort, das zu sagen, ist onShutdown:

function onShutdown()
    addRun:finalize()
    runs:close()
end

finalize ist close für eine Anweisung. Eine Datenbank lässt sich nicht schließen, solange eine Anweisung, die aus ihr gemacht wurde, noch da ist, also kommen die Anweisungen zuerst dran.

Das ganze Skript

Leg einen Ordner namens runs an, kopier den Ordner art des Buchs hinein, wegen stages.db, und schreib das hier in runs.singe:

dofile("Singe/Framework.singe")

local sqlite3 = require("sqlite3")

local PERFECT = 1000

-- Was mit dem Spiel ausgeliefert wird:  die Stufen, einmal gelesen und geschlossen.
local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

-- Was das Spiel schreibt:  jeder Durchgang, den irgendwer spielt, aufbewahrt im Datenordner.
local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

local addRun   = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")
local stageAt  = 1
local state    = "attract"
local goAt     = 0
local score    = 0
local best     = {}
local perStage = {}
local played   = 0


-- Die Fragen, gestellt, wenn ein Durchgang dazukommt, statt in jedem Frame.
local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    perStage = {}
    for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
        perStage[#perStage + 1] = row
    end
    for count in runs:urows("SELECT COUNT(*) FROM runs") do
        played = count
    end
end


local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
    refresh()
end


local function play()
    local stage = stages[stageAt]

    state = "waiting"
    goAt  = singeGetTicks() + math.random(stage.waitMin, stage.waitMax)
    score = 0
end


function onInputPressed(what)
    if what == SWITCH_BUTTON2 and state ~= "waiting" and state ~= "go" then
        stageAt = stageAt % #stages + 1
        return
    end
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)
    elseif state == "go" then
        score = math.max(0, PERFECT - (singeGetTicks() - goAt))
        state = "result"
        record(stages[stageAt].name, score)
    else
        play()
    end
end


function onOverlayUpdate()
    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST:  " .. stages[stageAt].name)

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play, button 2 for another stage.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Runs kept:  " .. played)
    overlayPrint(2, 6, "BEST RUNS")
    for place, row in ipairs(best) do
        overlayPrint(2, 6 + place, string.format("%d.  %-8s %4d", place, row.stage, row.score))
    end
    overlayPrint(24, 6, "BY STAGE")
    for line, row in ipairs(perStage) do
        overlayPrint(24, 6 + line, string.format("%-8s best %4d of %d", row.stage, row.top, row.tries))
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    addRun:finalize()
    runs:close()
end


refresh()

Starte es mit Singe -R runs. Knopf 1 startet eine Runde und hält sie an, wie in Lektion achtundzwanzig, und Knopf 2 wechselt zwischen den Runden zur nächsten Stufe. Spiel auf jeder ein paar. Dann beende es und starte es noch einmal: Jeder Durchgang ist noch da, die besten fünf links und der Bestwert jeder Stufe rechts.

Was gerade passiert ist

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

Hier sind zwei Dateien im Spiel, und sie sind nicht gleich. art/stages.db gehört dir: Du hast sie geschrieben, sie wird mit dem Spiel ausgeliefert, und das Spiel liest sie nur. runs.db gehört dem Spiel: Es gab sie nicht, bis der erste Start sie angelegt hat, sie wohnt im Datenordner, und niemand liefert sie aus.

    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)

Ein zu früh gedrückter Knopf zeichnet trotzdem einen Durchgang auf, mit einer Punktzahl von nichts. Die Datenbank ist eine Aufzeichnung dessen, was passiert ist, und ein Frühstart ist passiert. Ob man diese Zeilen zeigt, ist eine Frage für das SELECT, nicht etwas, das man versteckt, indem man sie nie schreibt.

    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do

ORDER BY score DESC, id sortiert nach Punktzahl und, wo zwei Punktzahlen gleich sind, nach id — der Reihenfolge, in der sie gespielt wurden. Ohne den zweiten Schlüssel kommen zwei gleiche Punktzahlen in der Reihenfolge zurück, die SQLite gerade bequem ist, und die kann sich von einem Start zum nächsten ändern. Eine Tabelle, die sich ohne sichtbaren Grund neu mischt, sieht kaputt aus, auch wenn sie es nicht ist.

Probier es aus

  1. Zeig das Datum. os.date("%Y-%m-%d", row.at) macht aus einer gespeicherten Zeit wieder etwas, das ein Mensch lesen kann. Füg jedem der besten Durchgänge das Datum hinzu.

  2. Ignorier die Frühstarts. Füg WHERE score > 0 in die Frage nach den besten Durchgängen ein, zwischen FROM runs und ORDER BY. Dann zähl die Frühstarts auf jeder Stufe mit einer eigenen Frage.

  3. Füg eine Stufe hinzu. Öffne stages.db in einem SQLite-Werkzeug, füg eine Zeile hinzu und starte das Spiel. Am Skript ändert sich nichts. Genau darum hält man Daten aus dem Skript heraus.

  4. Lösch den Verlauf. runs:exec("DELETE FROM runs") leert die Tabelle. Leg es auf einen Knopf, ruf danach refresh auf und sieh zu, wie alles auf nichts geht. Das ist das „Highscores zurücksetzen“ in einem Service-Menü.

  5. Schreib tausend Zeilen. Ruf record in einer Schleife tausendmal auf und miss die Zeit mit singeGetTicks. Dann setz runs:exec("BEGIN") vor die Schleife und runs:exec("COMMIT") dahinter und miss noch einmal. Eine Transaktion macht aus vielen Schreibvorgängen einen, und der Unterschied ist groß genug, dass es sich lohnt, ihn zu behalten.

Mach es absichtlich kaputt

Nimm addRun:reset() aus record heraus und spiel drei Runden auf drei verschiedenen Stufen.

Kein Fehler. Das Spiel läuft einwandfrei. Aber die Tabelle rechts sagt, dass du die erste Stufe dreimal gespielt hast, und die besten Durchgänge sind drei Kopien deiner ersten Punktzahl. bind_values konnte keine neuen Werte in eine Anweisung setzen, die schon gelaufen und nicht zurückgesetzt worden war, also hat es aufgegeben — leise, mit einer Zahl als Rückgabe, die du nicht geprüft hast — und step hat die Anweisung noch einmal mit den Werten ausgeführt, die sie schon hatte.

Das ist der Fehler, auf den es in dieser Lektion ankommt, weil er nicht wie einer aussieht. Eine Abfrage, die scheitert, ist laut. Ein Schreibvorgang, der das Falsche schreibt, ist still, und du findest ihn eine Woche später in den Daten. Wenn die Zeilen in einer Datenbank nicht das sind, was du erwartest, sieh dir den Code an, der sie hineingelegt hat, bevor du dir den Code ansiehst, der sie liest.

Setz reset wieder ein und mach es auf die laute Art kaputt: Ändere score im ersten SELECT in refresh in scroe.

Error running script:  no such column: scroe
stack traceback:
	[C]: in method 'nrows'
	runs/runs.singe:42: in local 'refresh'
	runs/runs.singe:132: in main chunk

SQLite liest die Spaltennamen, wenn es die Frage vorbereitet, also hält ein falsch geschriebener das Spiel sofort an, und die Meldung nennt ihn genau. Den Traceback liest man von innen nach außen: nrows hat sich beschwert, refresh hat es in Zeile 42 aufgerufen, und das Skript selbst hat refresh in Zeile 132 aufgerufen, der letzten Zeile, als das Spiel startete. Darum steht da running script, statt dass eine Funktion genannt wird, die die Engine aufgerufen hat: Das Spiel ist nie bis zum ersten Frame gekommen.

Was du gelernt hast

  • Eine Datenbank ist eine Datei voller Tabellen; eine Tabelle besteht aus Zeilen mit benannten Spalten.

  • require("sqlite3") gibt dir SQLite. sqlite3.open öffnet eine Datei und legt sie an, wenn sie fehlt.

  • Was das Spiel schreibt, kommt nach singeGetDataPath(). Was du auslieferst, kommt in deinen Ordner und wird mit sqlite3.OPEN_READONLY geöffnet.

  • CREATE TABLE IF NOT EXISTS kann gefahrlos bei jedem Spielstart laufen.

  • Werte kommen über prepare, bind_values, step und reset hinein, nie, indem man Strings ins SQL klebt.

  • nrows gibt Zeilen als Tabellen zurück; urows gibt die Spalten selbst zurück.

  • ORDER BY, LIMIT, GROUP BY, MAX und COUNT beantworten die Fragen, für die du sonst Schleifen schreiben würdest.

  • Frag, wenn sich die Antwort ändern kann, nicht in jedem Frame.

  • In onShutdown werden erst die Anweisungen finalisiert, dann wird die Datenbank geschlossen.

Beim nächsten Mal

Dein Spiel hat jetzt einen Ordner voller Dinge: ein Skript, Grafiken, Sounds und eine oder zwei Datenbanken. Lektion dreißig macht aus diesem Ordner eine einzige Datei, die ein Fremder auf seinen eigenen Rechner kopieren und spielen kann — und deine schreibgeschützte Datenbank geht mit und öffnet sich noch genau so wie jetzt.

Lektion 30: Ausliefern

Die fertige Lektion

Du hast einen Ordner. Darin liegen ein Skript, ein paar Bilder, ein paar Sounds und die games.dat, die du in Lektion dreizehn geschrieben hast. Er läuft, weil alles, was er braucht, da ist, wo du es hingelegt hast, und du weißt, wo das ist.

Diese Lektion macht aus diesem Ordner eine einzige Datei, die jemand, der dich nie getroffen hat, auf seinen Rechner kopieren und spielen kann. Das meiste davon sind zwei Befehlszeilen. Der Rest ist der Teil, den dir niemand beibringt: was in die Datei gehört, wessen Arbeit außer deiner darin steckt und wie du herausfindest, ob sie irgendwo anders als hier funktioniert.

Eine Datei

Ein fertiges Singe-Spiel wird als eine einzige .game-Datei ausgeliefert. Eine packst du so:

Singe --pack MyGame MyGame.game

Der erste Name ist der Ordner deines Spiels, der zweite die Datei, die geschrieben werden soll. Singe liest jede Datei im Ordner in eine Datenbank und sagt, was es getan hat:

>>> Packed 42 files (3819204 bytes) from MyGame into MyGame.game

Starte es so, wie du alles startest:

Singe MyGame.game

Das startet den ersten Eintrag in der games.dat darin; --entry=2 startet den zweiten, für eine Datei, die mehr als ein Spiel enthält. Um es zu installieren, kopiert der Spieler MyGame.game neben das Programm Singe. Das mitgelieferte Menü findet es und listet es auf. Mehr gibt es nicht: keinen Installer, kein Archiv zum Entpacken, keinen Ordner, der an die richtige Stelle muss.

Was das Packen mit jedem Dateinamen macht

Nichts in deinem Spiel muss sich ändern, damit es gepackt werden kann, und es lohnt sich zu wissen, warum, denn genau das wird dich am ehesten überraschen.

Jeder Name, den dein Spiel benutzt — dofile, require, io.open, spriteLoad, soundLoad, fontLoad, videoLoad, eine Frame-Datei, eine controls.cfg — geht durch ein und dieselbe Suche. Bei einem losen Ordner ist diese Suche das gewöhnliche Dateisystem. Bei einem gepackten Spiel wird der Name an drei Orten probiert, und der erste Treffer gewinnt:

  1. ein loser Ordner, der so heißt wie die Datei ohne ihre Endung — MyGame/ neben MyGame.game;

  2. der Datenordner des Spiels, unter files/, wo alles gelandet ist, was das Spiel schreibt;

  3. die Datenbank selbst.

Innerhalb der Datenbank werden Namen ohne Rücksicht auf Großbuchstaben verglichen, mit beiden Arten von Schrägstrich und relativ zur Wurzel des Spiels. Ein führender Ordnername, der so heißt wie das Spiel selbst, wird ignoriert, also finden MyGame/art/spaceship.png, art/spaceship.png und DIR .. "art/spaceship.png" alle dieselbe Datei.

Daraus folgen zwei Regeln, und wenn du dem Buch gefolgt bist, hältst du dich schon an beide. Benutze DIR für alles, was du lädst, damit ein Name nie davon abhängt, wo Singe gestartet wurde. Und schreib nur unterhalb von singeGetDataPath(), wo saveSet die Dinge schon ablegt — ein gepacktes Spiel wird schreibgeschützt geöffnet und nie beschrieben, also funktioniert ein Spiel, das neben sich selbst speichert, lose und scheitert gepackt.

Zwei Namen gehen mit Absicht woandershin. Alles, was mit Singe/ anfängt, bleibt im echten Dateisystem, also funktioniert dofile("Singe/Framework.singe") weiter, und der Datenordner ebenso. Und ein Name mit .. darin, der versucht, aus dem Spiel herauszuklettern, führt überhaupt nirgendwohin: io.open gibt nil zurück und eine Meldung, die sagt, dass der Name aus dem Spiel hinausreicht, und spriteLoad und seine Verwandten melden die Datei als fehlend.

Der lose Ordner gewinnt trotzdem

Den ersten Ort in der Liste wirst du jeden Tag benutzen. Ein Ordner, der so heißt wie die gepackte Datei und neben ihr liegt, schlägt die gepackten Kopien Datei für Datei.

MyGame.game        das gepackte Spiel
MyGame/            ein Ordner mit einer geänderten Datei darin

Leg eine einzige korrigierte art/spaceship.png hinein, und das gepackte Spiel läuft mit deinem neuen Bild und allem anderen aus der Datenbank. Nichts muss neu gepackt werden, um eine Änderung auszuprobieren, und du kannst deinen ganzen Arbeitsordner dort liegen lassen, während du das Spiel fertig machst. So moddet auch ein Spieler eins, und das kannst du für ein Feature halten oder nicht.

Daraus folgen zwei Dinge. Prüf dein Spiel einmal, während dieser Ordner einen anderen Namen hat, sonst lieferst du eine Datei aus, die nur auf dem Rechner funktioniert, der den Ordner hat. Und wisse, dass Packen nichts versteckt: --unpack ist eine dokumentierte Option, und jeder kann sie ausführen. Pack dein Spiel, weil es dann eine einzige Datei ist, nicht weil es dann eine verschlossene ist.

Ein veröffentlichtes Spiel patchen

Jemand hat dein Spiel, in einem Skript steckt ein Fehler, und du willst ihm nicht noch einmal vierzig Megabyte schicken.

Singe --patch MyGame.game fixes

fixes ist ein Ordner, der wie das Spiel aufgebaut ist — dieselben Namen an denselben Stellen — und nur die Dateien enthält, die sich geändert haben. Dateien, die der Patch nicht nennt, bleiben unangetastet. Die ganze Änderung ist eine einzige Transaktion, also lässt ein unterbrochener Patch das Spiel genau so, wie es war, statt halb ersetzt.

Ein Patch kann als eigene Datei reisen, gemacht mit dem Packer:

Singe --pack fixes MyGame-1.0.2.patch
Singe --patch MyGame.game MyGame-1.0.2.patch

Eine .patch-Datei braucht keine games.dat, kann nicht gestartet werden, und das Menü ignoriert sie. Sie kann außerdem eine Tabelle removed(path) mitbringen, die Dateien nennt, die gelöscht werden sollen, für das Artwork, das du durch etwas mit einem anderen Namen ersetzt hast. So oder so prüft Singe das gepatchte Spiel danach genauso, wie es ein neues prüft, also kann ein Patch deine games.dat nicht auf eine Datei zeigen lassen, die nicht mehr da ist.

Und um alles wieder herauszuholen:

Singe --unpack MyGame.game MyGameUnpacked

Was der Packer ablehnt

Der Packer baut nicht aus allem Möglichen ein Spiel, und jede Ablehnung betrifft etwas, das später kaputtgehen würde. Er lehnt einen Ordner ohne games.dat in seiner Wurzel ab. Er lehnt eine Framework.singe ab, eine controls.dat, alles, was auf exe, sh, bat oder cmd endet, und eine Datei ohne Endung, deren Name mit singe anfängt — mit anderen Worten eine Kopie der Engine oder ihrer Hilfsdateien, die sich in deinen Spielordner verirrt hat. Er lehnt zwei Dateien ab, deren Namen sich nur in Großbuchstaben unterscheiden, weil die Suche sie nicht auseinanderhalten kann. Er lehnt einen Eintrag auf oberster Ebene ab, der so heißt wie der Ordner selbst. Und er prüft deine games.dat, bevor er festschreibt: Jeder Eintrag braucht ein SCRIPT, und jedes SCRIPT, VIDEO, CABINET, MARQUEE und ATTRACT, das sie nennt, muss eine Datei sein, die wirklich darin liegt. Ein falscher Pfad wird mit dem Titel des Eintrags gemeldet, und nichts wird geschrieben.

Jede Beschwerde nennt die Datei, und du bekommst eine Liste davon statt nur der ersten, sodass dir ein einziger Lauf alles sagt, was zu beheben ist.

Was hineingehört und was draußen bleibt

Sieh in deinen Spielordner. Manches darin ist das Spiel, und manches ist, wie das Spiel entstanden ist.

Ausliefern: das Skript und alles, was es lädt, die games.dat, das Artwork, das das Menü zeigt (CABINET, MARQUEE und den ATTRACT-Clip), deine Credits- und Lizenzdateien und eine Readme, wenn du eine hast.

Draußen lassen: die Zeichnungen, aus denen du das Artwork exportiert hast, die Aufnahmen des Sounds, die du nicht benutzt hast, deine Notizen, Testskripte, Screenshots, alles, was old oder backup heißt, den Ordner data mit deinen eigenen Spielständen und deinen eigenen Highscores darin und alles, was ein Fremder nicht lesen soll. All das lässt sich bestens packen, und genau das ist das Problem: Es geht mit dem Spiel hinaus, und es ist für jeden nur ein --unpack entfernt.

Der zuverlässige Weg herauszufinden, was du tatsächlich ausgeliefert hast, ist, es in einen leeren Ordner zu entpacken und nachzusehen. Mach das einmal bei jeder Veröffentlichung. Es dauert eine Minute, und es ist die einzige Prüfung, die sieht, was du vergessen hast, statt was du im Kopf hast.

Credits und Lizenzen

Wenn irgendeine Grafik, ein Sound, Musik oder eine Schriftart in deinem Spiel von jemand anderem gemacht wurde, lieferst du dessen Arbeit aus, und die Bedingungen, unter denen er sie hergegeben hat, sind eine Pflicht und keine Höflichkeit. Das ist keine Formsache, und es geht nicht um Anwälte: Ein Mensch hat dieses Ding gemacht und dafür um eine bestimmte Sache gebeten, meistens um seinen Namen.

Führ Buch, während du arbeitest, nicht erst am Ende. Eine reine Textdatei im Spielordner mit einer Zeile pro Stück: was die Datei ist, woher sie kommt, wer sie gemacht hat, welche Lizenz und was diese Lizenz verlangt. Es nebenbei aufzuschreiben dauert Sekunden. Es in der Nacht vor einer Veröffentlichung aus dem Browserverlauf zu rekonstruieren ist genau der Weg, auf dem Credits verloren gehen.

Ein paar Dinge, die du wissen solltest, bevor du sie brauchst. „Kostenlos herunterladen“ ist keine Lizenz; such nach den eigentlichen Bedingungen. Creative Commons BY heißt, dass du die verlangte Namensnennung angeben musst, und es gibt keine Ausnahme für Spiele. CC0 und gemeinfreie Werke verlangen nichts, und trotzdem jemanden zu nennen kostet dich eine Zeile. Schriftarten haben ihre eigenen Lizenzen, und manche erlauben das Einbetten, andere nicht. Musik aus einem Video darfst du fast nie benutzen. Alles, was ein Werkzeug erzeugt hat, ist nur so sauber wie die Bedingungen des Werkzeugs.

Dann bring die Credits irgendwo unter, wo ein Spieler sie erreichen kann, und zwar im Spiel. Nicht nur in einer Textdatei daneben — ein gepacktes Spiel ist eine einzige Datei, und die Textdatei steckt darin, wo niemand nachsieht. Das Skript am Ende dieser Lektion ist dieser Bildschirm.

Singes eigene Singe/LICENSES ist die Form, die du übernehmen solltest: eine Zeile pro Bibliothek, mit ihrer Version, ihrer Lizenz und ihrer Herkunft. Die Liste deines Spiels wird kürzer sein, und die Aufgabe ist dieselbe.

Eine Versionsnummer, die etwas bedeutet

Dein Spiel wird eine zweite Veröffentlichung haben. Die erste bleibt da draußen, solange es das Internet gibt, und irgendwer wird dir einen Fehlerbericht dazu schicken, ohne eine Ahnung, welche Version er hat.

Also such dir eine Nummer aus, setz sie dorthin, wo ein Spieler sie lesen kann, und benutze nie eine zweimal. Drei Teile sind die übliche Form — 1.0.2 — und was die Teile bedeuten, zählt weniger, als dass sie immer nur steigen. Erhöh den letzten für eine Korrektur, den mittleren für etwas Neues, den ersten, wenn du ein anderes Spiel gemacht hast. Was immer du wählst, schreib es in deine Readme, damit sich dein zukünftiges Ich auch daran hält.

games.dat hat keinen Schlüssel für die Version, also trägst du die Nummer selbst. Setz sie als Konstante ins Skript, zeig sie auf dem Credits-Bildschirm und setz sie in den Namen dessen, was du verschickst (MyGame-1.0.2.game, MyGame-1.0.2.patch). Dann nennt der Fehlerbericht die Version auf dem Bildschirm, und du weißt, um welche Dateien es geht.

Auf einem Rechner testen, der nicht deiner ist

Dein Rechner ist der schlechteste Ort überhaupt, um eine Veröffentlichung zu testen. Er hat die Schriftarten, die du installiert hast, den Ordner, an dem du gearbeitet hast, die Speicherdatei mit deinen Einstellungen darin und die Engine in dem Zustand, in dem ein Monat Arbeit sie hinterlassen hat.

Der Mindesttest, der Reihe nach:

  1. Entpack die Veröffentlichung in einen leeren Ordner und lies die Dateiliste.

  2. Kopier nur die .game-Datei in einen anderen Ordner, mit einer frischen Kopie von Singe und sonst nichts, und starte sie aus dem Menü, so wie ein Spieler es tun wird.

  3. Lösch den Ordner data dieses Ordners und starte es noch einmal. Das ist ein erster Start auf einem neuen Rechner: keine gespeicherten Einstellungen, keine Highscores, kein angemeldetes Konto. Ein Spiel, das erst beim zweiten Start funktioniert, ist ein häufiger Fehler, und so findest du ihn.

  4. Gib es einer Person, die es nie gesehen hat, und sieh zu, ohne zu helfen.

Dann teste den Rechner genauso wie das Spiel. Er wird eine andere Bildschirmform haben, also sieh dir dein Spiel im Fenster und im Vollbild an. Vielleicht hat er überhaupt kein 3D-Gerät, und darum hat das Menü einen zweiten Renderer. Die Seite System Information der Service-Tools listet die Engine-Version, das Betriebssystem, den Prozessor, den Renderer, die Decoder und den Datenordner auf einem Bildschirm auf; ein Foto dieser Seite beantwortet den größten Teil eines Fehlerberichts, und wenn du das deinen Spielern in deiner Readme sagst, ersparst du dir eine Woche Raterei.

Das Skript

Ein Bildschirm mit Credits und Version. Er ist schnell geschrieben, und er ist der Teil des Auslieferns, den die meisten Spiele falsch machen.

dofile("Singe/Framework.singe")

local GAME_NAME    = "Rock Dodger"
local GAME_VERSION = "1.0.2"

local CREDITS = {
    "Written and drawn by   <your name here>",
    "",
    "Music                  \"Night Drive\" by A. Composer",
    "                       Creative Commons BY 4.0",
    "                       example.org/night-drive",
    "",
    "Explosion              freesound.org user \"thud\"",
    "                       Creative Commons CC0",
    "",
    "Font                   FreeSansBold",
    "                       GPL with the font exception",
    "",
    "Engine                 Singe " .. SINGE_VERSION_STRING,
    "                       GPL version 3",
    "                       See Singe/LICENSES for the",
    "                       libraries Singe is built on.",
    "",
    "Thank you for playing.",
}

local FIRST_ROW = 4
local ROWS      = 10

local scroll = 0


local function scrollBy(lines)
    local most = #CREDITS - ROWS

    if most < 0 then
        most = 0
    end
    scroll = scroll + lines
    if scroll < 0 then
        scroll = 0
    end
    if scroll > most then
        scroll = most
    end
end


function onInputPressed(what)
    if what == SWITCH_UP then
        scrollBy(-1)
    elseif what == SWITCH_DOWN then
        scrollBy(1)
    elseif what == SWITCH_BUTTON1 then
        scroll = 0
    end
end


function onOverlayUpdate()
    local line = nil

    overlayClear()
    overlayPrint(2, 0, GAME_NAME .. "  version " .. GAME_VERSION)
    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then
            overlayPrint(2, FIRST_ROW + row, line)
        end
    end

    overlayPrint(2, FIRST_ROW + ROWS + 1, "Saves go to:")
    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())
    overlayPrint(2, 17, "Up and down scroll.  Button 1 goes back to the top.")

    return OVERLAY_UPDATED
end

Ersetze jede Zeile von CREDITS durch die Wahrheit über dein eigenes Spiel. Die Platzhalter sind da, um die Form zu zeigen: was es ist, wer es gemacht hat, welche Lizenz und woher es kommt.

Was gerade passiert ist

local GAME_VERSION = "1.0.2"

Ein Ort, ganz oben, in Großbuchstaben, weil sich der Wert nie ändert, während das Spiel läuft. Alles, was die Version zeigt, liest diesen Wert, also ist das Erhöhen eine einzige Änderung statt einer Suche.

    "Music                  \"Night Drive\" by A. Composer",

Diese Backslashes sind die Escape-Sequenz aus Lektion eins: ein doppeltes Anführungszeichen, das zum Text gehört, statt den String zu beenden. Titel haben Anführungszeichen, und darum stößt eine Credits-Liste gleich in ihrer ersten Zeile darauf.

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then

Zehn Bildschirmzeilen zeigen zehn Zeilen aus einer Liste, die länger als zehn ist. scroll sagt, wie weit das Fenster in der Liste nach unten gerückt ist. Das + 1 gibt es, weil Lua eine Liste ab eins zählt und die Bildschirmzeilen ab null, und das if line then gibt es, weil das Ende der Liste nil ist — über das Ende einer Tabelle hinaus zu lesen ist in Lua kein Fehler, es gibt dir einfach nichts, aber nichts auszugeben wäre einer.

    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

Drei Fakten, die ein Fehlerbericht braucht und die ein Spieler sonst nicht finden kann: deine Version in der Zeile darüber, die Version der Engine und die ID des Spiels. SINGE_VERSION_STRING ist eine globale Variable, die die Engine setzt, bevor dein Skript läuft. or "none" deckt den Fall ab, dass das Spiel keinen Eintrag in games.dat hat, sodass die Zeile etwas ausgibt, statt an einem nil abzustürzen.

    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())

Wohin dieses Spiel schreibt. Bei einem gepackten Spiel ist das der einzige Ort, an dem überhaupt etwas geschrieben wird, und es ist der Ordner, den ein Spieler löscht, um sauber neu anzufangen. Ihn anzuzeigen macht aus „Wo sind meine Spielstände?“ eine Frage, auf die du nie antworten musst.

Wenn dieser Pfad rechts über den Bildschirm hinausläuft, ist nichts kaputt: overlayPrint lässt die Zeichen weg, die über den Rand gehen würden. Das Standard-Overlay ist sechzig Zeichenzellen breit.

Probier es aus

  1. Pack es. Leg dieses Skript in deinen Spielordner, führ --pack aus und starte die .game-Datei. Dann entpack sie in einen leeren Ordner und lies die Liste dessen, was herauskam.

  2. Überschreib eine Datei. Leg neben der gepackten Datei einen Ordner an, der so heißt wie sie ohne die Endung, und leg eine geänderte Datei hinein. Starte das gepackte Spiel und sieh zu, wie deine lose Datei gewinnt.

  3. Mach einen Patch. Ändere die Version in 1.0.3, leg nur das Skript in einen Ordner fixes, pack ihn als .patch und spiel ihn in das Spiel ein, das du schon gemacht hast. Prüf die Version auf dem Bildschirm.

  4. Stell den Packer auf die Probe. Benenn deine games.dat kurz um und versuch zu packen. Dann benenn sie zurück, lass einen ihrer SCRIPT-Namen auf eine Datei zeigen, die es nicht gibt, und versuch es noch einmal. Zwei verschiedene Ablehnungen, beide bevor irgendetwas geschrieben wird.

  5. Schreib die echten Credits. Geh den Ordner deines Spiels Datei für Datei durch und schreib eine Zeile für jede, die du nicht selbst gemacht hast. Wenn du dich nicht erinnern kannst, woher etwas kommt, ist das die Antwort auf die Frage, ob du es ausliefern solltest.

Mach es absichtlich kaputt

Starte Singe einmal innerhalb deines Spielordners, sodass die Engine ihre Hilfsdateien dort entpackt, und pack ihn dann:

Singe --pack MyGame MyGame.game
!!! MyGame has Framework.singe:  Singe/Framework.singe
!!! MyGame has sh file:  Menu.sh

Nichts wird geschrieben. Jede Zeile nennt eine Datei, die er nicht nimmt, und warum, und du bekommst sie vielleicht in der anderen Reihenfolge oder noch andere dazu. In deinem Spiel liegt eine Kopie des eigenen Hilfsordners der Engine, und daneben das Startskript, das die Engine geschrieben hat, weil du Singe irgendwann von dort aus gestartet hast. Ein Spiel darf nie eins von beiden mitbringen: Die Hilfsdateien gehören zu dem Singe, das der Spieler gerade benutzt, nicht zu deinem Spiel, und eine gepackte Framework.singe würde statt seiner geladen. Unter Windows nennt die zweite Zeile stattdessen Menu.bat.

Lösch den Ordner Singe und Menu.sh (oder Menu.bat) aus deinem Spiel, halte deinen Spielordner als einen Ordner neben dem Programm Singe statt um es herum, und pack noch einmal. Das ist derselbe Aufbau, den Lektion dreizehn beschrieben hat, und dieser Fehler ist das, was passiert, wenn er verrutscht.

Was du gelernt hast

  • Singe --pack folder name.game macht aus einem Spielordner eine einzige Datei, und wer diese Datei neben das Programm Singe kopiert, hat sie installiert.

  • Jeder Dateiname in einem gepackten Spiel wird zuerst in einem losen Ordner gesucht, dann im Datenordner, dann in der Datenbank.

  • Ein loser Ordner, der so heißt wie die gepackte Datei, überschreibt sie Datei für Datei, und so arbeitest du weiter — und so lieferst du eine kaputte Veröffentlichung aus, wenn du vergisst, dass er da ist.

  • Lade mit DIR und schreib nur unterhalb von singeGetDataPath(), sonst funktioniert dein Spiel lose und scheitert gepackt.

  • --patch ersetzt Dateien in einem veröffentlichten Spiel in einer einzigen Transaktion; --unpack schreibt alles wieder heraus.

  • Der Packer lehnt Engine-Dateien ab, Namenskonflikte und eine games.dat, die auf Dateien zeigt, die er nicht hat.

  • Entpack deine eigene Veröffentlichung und lies, was darin ist, bevor du sie irgendwohin schickst.

  • Die Grafiken und Sounds anderer Leute kommen mit Bedingungen, und sie zu erfüllen heißt: ein Credits-Bildschirm im Spiel.

  • Eine Versionsnummer steigt immer nur, und sie gehört auf den Bildschirm.

  • Teste auf einem Rechner, der nicht deiner ist, und fang ganz ohne Ordner data an.

Beim nächsten Mal

Eine Datei, installiert, mit Credits und nummeriert. Die letzte Lektion steckt sie in eine Holzkiste mit einem Münzschlitz und ohne Tastatur, und das ändert mehr an deinem Spiel, als du denkst.

Lektion 31: Im Automaten

Die fertige Lektion

Zwischen einem Spiel und einem Arcade-Automaten gibt es einen Unterschied, und es ist nicht das Holz. Ein Automat schaltet sich morgens selbst ein, spielt vor einem leeren Raum, nimmt eine Münze von jemandem, der nie ein Wort darüber gelesen hat, und läuft um Mitternacht immer noch, ohne dass jemand eine Tastatur angefasst hat, weil es keine Tastatur gibt. Alles in dieser Lektion kommt daher.

Du brauchst keinen Automaten, um irgendetwas davon zu machen. Ein Stick und zwei Knöpfe auf einem Schreibtisch oder ein Gamepad reichen, um jeden Fehler in dieser Lektion zu finden, und das meiste, was du hier lernst, macht ein Spiel auch auf einem Desktop besser.

Es gibt keine Tastatur

Fang mit dem an, was fehlt, denn genau das macht Spiele kaputt.

Ein Automat hat einen Stick, ein paar Knöpfe, eine Münztür, einen Startknopf und irgendwo im Inneren einen kleinen Schalter, an den ein Betreiber herankommt. Das ist alles. Kein Esc, keine Buchstaben, keine Maus, keine Möglichkeit zu tippen. Also:

  • Jedes Menü in deinem Spiel muss mit hoch, runter und einem Knopf erreichbar sein. Wenn irgendein Bildschirm in deinem Spiel „Drück Y, um weiterzumachen“ sagt, funktioniert er in einem Automaten nicht.

  • Initialen eingeben heißt drei Knöpfe und ein Buchstabe, der durchläuft, kein Textfeld. Darum haben Arcade-Spiele Namen aus drei Buchstaben.

  • Eine Aufforderung, die eine Taste über ihren Buchstaben nennt, ist falsch. Sag „Knopf 1“ oder zeichne den Knopf.

  • Es gibt keinen Ausweg. Ein Spieler kann nicht beenden, und er sollte es auch nicht können.

Geh dein Spiel einmal durch, Bildschirm für Bildschirm, und frag bei jedem: Käme jemand mit einem Stick und einem Knopf hier durch? Dieser Durchgang durch dein eigenes Spiel ist mehr wert als der Rest dieser Lektion.

controls.cfg

Seit Lektion drei liest du Eingaben als SWITCH_UP, SWITCH_BUTTON1, SWITCH_COIN1 und den Rest, und du hast nicht ein einziges Mal gesagt, welche Taste das ist. Genau darum geht es bei ihnen. Irgendwo zwischen dem Mikroschalter im Automaten und deinem onInputPressed liegt eine Datei, die das entscheidet, und dein Spiel ist an diesem Gespräch nicht beteiligt.

Die Datei ist controls.cfg. Sie ist Lua, wie dein Skript, und eine Liste von Tabellen — eine pro Schalter — mit allem, was ihn auslösen kann:

INPUT_1P_START = { SCANCODE.MAIN_1, GAMEPAD_0.BUTTON_START }
INPUT_1P_COIN  = { SCANCODE.MAIN_5, GAMEPAD_0.BUTTON_LEFT_BUMPER }
INPUT_ACTION_1 = { SCANCODE.LCTRL, GAMEPAD_0.BUTTON_A }
INPUT_UP       = { SCANCODE.UP, GAMEPAD_0.DPAD_UP, GAMEPAD_0.AXIS_LEFT_Y_U }

Jeder INPUT_-Name in der Datei wird zum passenden SWITCH_-Wert in deinem Spiel: INPUT_ACTION_1 ist der SWITCH_BUTTON1, auf den du die ganze Zeit prüfst, und INPUT_1P_COIN ist SWITCH_COIN1. Jeder Eintrag in einer Tabelle löst denselben Schalter aus, also ist es einem Spiel egal, ob der Spieler die Taste gedrückt hat, den Knopf am Pad oder den Stick bewegt hat.

Du musst nicht die ganze Datei schreiben. Singe fängt mit seinen eigenen Standardwerten an und liest controls.cfg der Reihe nach an vier Orten — dem Skriptordner des Spiels, dem Ordner, in dem Singe gestartet wurde, dem Ordner über dem Datenordner des Spiels und dem Datenordner des Spiels — und jede Datei, die es findet, überschreibt, was vorher kam, Eintrag für Eintrag. So hat ein Automat ganz oben eine Datei für den ganzen Rechner, und ein Spiel, das einen zusätzlichen Knopf braucht, hat eine eigene Datei mit vier Zeilen. Im Ordner Singe liegt eine controls.cfg.example, die du kopieren kannst.

DEAD_ZONE steht auch darin: wie weit sich ein Stick bewegen muss, bevor er als gedrückt zählt, in den rohen Einheiten, die die Hardware meldet, wobei voller Ausschlag 32767 ist. Der Standard ist 15000. Ein abgenutzter Stick, der driftet, braucht eine größere Zahl, und DEAD_ZONES stellt eine Achse nach der anderen ein, für den einen Stick, der müde ist. Der Abschnitt des Handbuchs über das Anpassen der Steuerung deckt das alles ab.

Jedes Gerät ist ein Gamepad

Die Knöpfe eines Arcade-Automaten sind an eine Encoder-Platine angeschlossen, die der Computer als eine Art Joystick sieht, und die hat nichts mit einem Xbox-Pad gemein. Singe schreibt für so ein Gerät selbst eine Belegung und öffnet es dann als GAMEPAD_0, sodass es controls.cfg und dein Spiel genau so erreicht wie ein erkanntes Pad. Es gibt eine einzige Gerätefamilie und kein zweites Vokabular, das du lernen musst.

Die Belegung, die es erfindet, ist eine direkte: Die Knöpfe der Platine werden der Reihe nach zu BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y und so weiter. Wenn die Knöpfe deines Automaten nicht in dieser Reihenfolge verdrahtet sind, kommen sie an den falschen Stellen heraus, und die Korrektur liegt nicht in deinem Spiel: --program schreibt die Belegung, die Singe geschrieben hat, in einer Form in den Trace, die du bearbeiten und als gamecontrollerdb.txt neben das Spiel legen kannst.

Wenn ein Knopf „nichts tut“, beantwortet das Tool Input Test des Menüs die Frage in fünf Sekunden. Es zeigt jedes Gerät, das die Engine sehen kann, und den letzten Schalter, den ein Spiel bekommen hätte. Entweder kommt der Schalter an, und dein Spiel ignoriert ihn, oder er kommt nie an, und das Problem ist die Belegung oder das Kabel.

Vier Schalter gehören nicht dir

Die meisten Schalter gehen direkt an dein Spiel. Vier nicht: Um Pause, Beenden, Screenshot und das Umschalten des Mausfangs kümmert sich die Engine selbst.

Pause ist wirklich nützlich, und zwar umsonst. Solange die Engine sie in der Hand hat, friert die Taste, die INPUT_PAUSE zugeordnet ist, alles ein — die Disc, jedes Video, jeden Sound und dein Skript. Sie zeichnet ihre eigene Anzeige und taut beim nächsten Druck alles wieder auf. Alles, wovon dein Spiel dachte, es werde gehalten, wird ordentlich losgelassen und danach wieder gedrückt, sodass ein Stick, der während einer Pause gehalten wird, nie hängen bleibt.

Beenden ist der Schalter, den du wegnimmst, und das macht ein späterer Abschnitt.

Münzen, Credits und Start

Ein Arcade-Automat hat eine Form, die älter ist als jeder von uns, und Spieler kennen sie, ohne dass man es ihnen sagt:

  1. Attract-Modus. Niemand ist da. Der Automat zeigt, was er ist, lässt INSERT COIN blinken und verlangt nichts.

  2. Credit. Eine Münze kommt als SWITCH_COIN1 an. Münzen werden zu Credits, zu dem Kurs, den der Betreiber eingestellt hat — nicht immer eins zu eins.

  3. Spiel. SWITCH_START1 gibt einen Credit aus und startet.

  4. Game Over. Kurz die Punktzahl und dann von selbst zurück in den Attract-Modus. Niemand drückt etwas, um hinauszukommen; der Spieler ist schon gegangen.

Zwei Details, die Leute falsch machen. Münzen werden gezählt, nicht ausgegeben: Bei zwei Münzen pro Credit muss eine Münze dasitzen und auf ihren Partner warten, und ein Spieler, der eine eingeworfen hat und gegangen ist, hat sie der nächsten Person hinterlassen. Und der Automat muss selbst den Weg zurück in den Attract-Modus finden, denn das Letzte, was ein Spieler tut, ist, mit dem Spielen aufzuhören.

Hinter dem Service-Schalter

Hinter der Münztür gibt es einen Knopf, den der Spieler nie sieht und den der Betreiber ständig benutzt. Er ist SWITCH_SERVICE, und die Engine reicht ihn direkt an dich weiter.

Ein Betreiber, der dein Service-Menü öffnet, erwartet, ungefähr in dieser Reihenfolge, Folgendes vorzufinden:

  • den Preis — Münzen pro Credit und eine Freispiel-Einstellung für einen Automaten zu Hause oder auf einer Messe;

  • die Schwierigkeit, weil ein Automat in einer Bar und ein Automat in einer Spielhalle verschiedene Antworten brauchen;

  • eine Möglichkeit, die Highscore-Tabelle zu löschen, das mit Abstand meistgewünschte Ding auf dieser Liste;

  • was der Automat ist, damit eine Störungsmeldung Fakten enthält — die Engine-Version, der Bildschirm, wo die Daten liegen;

  • einen Ausweg, ohne irgendetwas auszuschalten.

Alles, was ein Betreiber ändert, muss überstehen, dass der Strom wegfällt, und in einer Spielhalle heißt das: mitten in einem Spiel, ohne Vorwarnung, weil jemand einen Stecker zieht. saveSet schreibt am Ende des Frames, und das ist früh genug für eine Punktzahl und nicht früh genug für eine Einstellung, die jemand gerade verstellt hat. saveFlush() schreibt sofort, und genau für ein Service-Menü ist es gedacht.

Die eigenen Service-Tools des mitgelieferten Menüs, hinter demselben Schalter, solltest du kennen, denn sie sind auf jedem Automaten, auf dem dein Spiel laufen wird: der Input Test, die Tests für Sound und Lightgun, die Bildgeometrie, die Audioverzögerung, das Online-Konto und eine Seite, die die gespeicherten Daten eines einzelnen Spiels löscht. Dein Service-Menü muss sie nicht nachbauen.

Ein Automat, der sich selbst startet und nie beendet

Der Automat wird an der Steckdose eingeschaltet. Niemand meldet sich an. Nach einer Minute oder so muss ein Spiel auf dem Bildschirm sein und dort bleiben.

Dass Singe beim Einschalten startet, ist die Aufgabe deines Betriebssystems und nicht die von Singe — der Rechner startet die Menu.sh oder Menu.bat, die die Engine neben deine Spiele schreibt, oder direkt dein Spiel. Deine Aufgabe ist, was den Rest des Tages passiert.

Nimm die Beenden-Taste weg:

singeSetQuitKeyEnabled(false)

Die Engine ignoriert dann den Schalter, der INPUT_QUIT zugeordnet ist, und liefert ihn dir als SWITCH_QUIT wie jeden anderen, sodass du erst fragen, erst speichern oder gar nichts tun kannst. Der Schließen-Knopf des Fensters beendet immer, egal was du einstellst, und das wird gleich wichtig.

Dann gehört eine Handvoll Optionen dem Automaten statt deinem Skript, und die kommen in eine settings.cfg neben den Spielen — dieselben Namen wie die Befehlszeilenoptionen, nur ohne die Bindestriche:

fullscreen  = true
screen      = 2
idleexit    = 900
startsilent = true

idleexit beendet nach so vielen Sekunden ohne jede Eingabe, für einen Automaten, der den Bildschirm an ein Menü oder ein Frontend zurückgeben soll. startsilent startet stumm, bis jemand etwas anfasst, und so ist ein Raum voller Automaten erträglich. Es gibt noch mehr; die Abschnitte des Handbuchs über Einstellungen und die Befehlszeile listen jede einzelne auf.

Artwork um das Bild

Ein echter Automat hat ein gedrucktes Bezel (einen Bildschirmrahmen) um den Bildschirm: Artwork mit einem Loch darin, durch das das Spiel zu sehen ist. Singe zeichnet eines für dich.

Singe --bezel cabinet.png MyGame.game

Die Datei wird in einem Ordner bezels im Spiel gesucht — ein gepacktes Spiel kann sein eigenes mitbringen — und dann in einem Ordner bezels im Datenordner, sodass ein Spieler sein eigenes Artwork auf ein Spiel legen kann, ohne es anzufassen. Neben der Grafik, nach ihr benannt, sagt eine kleine Lua-Datei, wohin das Bild kommt, in den eigenen Pixeln des Artworks:

-- bezels/cabinet.cfg
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }

Weil diese Zahlen die eigenen des Artworks sind, bleiben sie bei jeder Fenstergröße richtig: Grafik und Loch skalieren zusammen. Ohne eine solche Datei behält das Bild das ganze Fenster, so wie es das immer getan hat.

Standardmäßig liegt das Artwork hinter allem, und dein Spiel verdeckt das Loch. --bezelflip setzt es stattdessen nach vorn, sodass nur seine Transparenz das Spiel durchlässt, und das willst du für weiche oder geformte Ränder — und dann liegt auch dein Overlay darunter, wenn du nichts anderes sagst:

if mainBezelLoaded() then
    setOverlayOnTop(true)
end

mainBezelLoaded() sagt dir außerdem, ob es überhaupt Artwork gibt, und so entscheidet ein Spiel, seinen eigenen Rahmen zu zeichnen, wenn keins da ist.

Ein Monitor auf der Seite

Viele Arcade-Monitore sind hochkant eingebaut. Dreh die ganze Darstellung:

Singe --rotate=90 MyGame.game

Das Bild, das Overlay, jede GUI, eine 3D-Szene und die Partikel drehen sich alle zusammen, und die Positionen von Maus und Lightgun werden zurückgedreht, sodass ein Klick immer noch dort landet, wo der Spieler ihn sieht. Eine Vierteldrehung vertauscht außerdem die Form der Fläche, sodass ein hohes Fenster gefüllt wird, statt mit Letterbox zu einem Streifen zu schrumpfen.

Nur 0, 90, 180 und 270 werden angenommen. Ein Skript kann es während des Laufs mit vldpSetRotate ändern, das für alles andere false antwortet, statt dein Spiel zu beenden, und vldpGetRotate() liest es zurück — und das gehört auf einen Service-Bildschirm, denn „das Bild liegt auf der Seite“ und „der Monitor liegt auf der Seite“ sind verschiedene Störungen.

Was die Drehung nicht tut, ist, dein Spiel umzuschreiben. Ein Spiel, das für einen breiten Bildschirm gezeichnet und um neunzig Grad gedreht wurde, ist ein breites Spiel auf der Seite. Für einen hohen Bildschirm zu entwerfen heißt, für einen hohen Bildschirm zu entwerfen.

Das Skript

Die ganze Form: Attract-Modus, Münze, Credit, Spiel, Game Over, Service und ein Beenden, das nachfragt. Das Spiel in der Mitte ist ein Knopf und ein Timer von fünfzehn Sekunden, denn diesmal geht es nicht um das Spiel — sondern um den Automaten drumherum.

dofile("Singe/Framework.singe")

local ROUND_MS  = 15000
local MENU      = { "Coins per credit", "Difficulty", "Free play", "Clear high score", "Exit service" }
local HARDNESS  = { "Easy", "Normal", "Hard" }

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)
local best           = saveGet("best", 0)

local state    = "attract"
local goBackTo = "attract"
local coins    = 0
local credits  = 0
local score    = 0
local endsAt   = 0
local item     = 1
local saying   = ""
local hasBezel = false


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


local function canStart()
    return freePlay or credits > 0
end


local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end


local function startGame()
    if not freePlay then
        credits = credits - 1
    end
    score  = 0
    endsAt = singeGetTicks() + ROUND_MS
    state  = "play"
end


local function endGame()
    if score > best then
        best = score
        saveSet("best", best)
    end
    saveFlush()
    endsAt = singeGetTicks() + 5000
    state  = "over"
end


local function settingOf(which)
    if which == 1 then
        return tostring(coinsPerCredit)
    elseif which == 2 then
        return HARDNESS[difficulty]
    elseif which == 3 then
        if freePlay then
            return "on"
        end
        return "off"
    elseif which == 4 then
        return tostring(best)
    end
    return ""
end


local function adjust(step)
    if item == 1 then
        coinsPerCredit = wrap(coinsPerCredit + step, 1, 4)
        saveSet("coinsPerCredit", coinsPerCredit)
    elseif item == 2 then
        difficulty = wrap(difficulty + step, 1, #HARDNESS)
        saveSet("difficulty", difficulty)
    elseif item == 3 then
        freePlay = not freePlay
        saveSet("freePlay", freePlay)
    end
    saveFlush()
end


local function serviceInput(what)
    if what == SWITCH_UP then
        item = wrap(item - 1, 1, #MENU)
    elseif what == SWITCH_DOWN then
        item = wrap(item + 1, 1, #MENU)
    elseif what == SWITCH_LEFT then
        adjust(-1)
    elseif what == SWITCH_RIGHT then
        adjust(1)
    elseif what == SWITCH_BUTTON1 then
        if item == 4 then
            best = 0
            saveSet("best", 0)
            saveFlush()
            saying = "High score cleared."
        elseif item == 5 then
            state = goBackTo
        end
    elseif what == SWITCH_BUTTON2 or what == SWITCH_SERVICE then
        state = goBackTo
    end
end


function onInputPressed(what)
    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

    if state == "confirm" then
        if what == SWITCH_BUTTON2 then
            state = goBackTo
        end
        return
    end

    if state == "service" then
        serviceInput(what)
        return
    end

    if what == SWITCH_SERVICE then
        goBackTo = state
        saying   = ""
        state    = "service"
        return
    end

    if what == SWITCH_COIN1 then
        insertCoin()
        return
    end

    if state == "play" then
        if what == SWITCH_BUTTON1 then
            score = score + 10 * difficulty
        end
        return
    end

    if what == SWITCH_START1 and canStart() then
        startGame()
    end
end


local function drawAttract()
    overlayPrint(2, 2, "ROCK DODGER")
    if canStart() then
        overlayPrint(2, 4, "PRESS START")
    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end
    overlayPrint(2, 6, "High score  " .. best)
end


local function drawService()
    overlayPrint(2, 0, "SERVICE MENU")
    for row, name in ipairs(MENU) do
        if row == item then
            overlayPrint(1, row + 1, ">")
        end
        overlayPrint(3, row + 1, name)
        overlayPrint(24, row + 1, settingOf(row))
    end
    overlayPrint(2, 8, saying)
    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())
    if hasBezel then
        overlayPrint(2, 11, "Bezel artwork loaded.")
    else
        overlayPrint(2, 11, "No bezel artwork.")
    end
    overlayPrint(2, 12, singeGetDataPath())
    overlayPrint(2, 16, "Up/Down choose.  Left/Right change.  Button 1 does it.")
    overlayPrint(2, 17, "Button 2 or the service switch leaves.")
end


function onOverlayUpdate()
    overlayClear()

    if state == "play" and singeGetTicks() >= endsAt then
        endGame()
    elseif state == "over" and singeGetTicks() >= endsAt then
        state = "attract"
    end

    if state == "service" then
        drawService()
    elseif state == "confirm" then
        overlayPrint(2, 2, "QUIT THIS GAME?")
        overlayPrint(2, 4, "Quit again to quit.  Button 2 stays.")
    elseif state == "play" then
        overlayPrint(2, 2, "SCORE  " .. score)
        overlayPrint(2, 3, "TIME   " .. ((endsAt - singeGetTicks()) // 1000))
        overlayPrint(2, 5, "Button 1 scores.  " .. HARDNESS[difficulty] .. ".")
    elseif state == "over" then
        overlayPrint(2, 2, "GAME OVER")
        overlayPrint(2, 4, "You scored " .. score .. ".")
        overlayPrint(2, 6, "High score  " .. best)
    else
        drawAttract()
    end

    if state ~= "service" then
        overlayPrint(2, 17, "CREDITS " .. credits .. "   COINS " .. coins .. "/" .. coinsPerCredit)
    end

    return OVERLAY_UPDATED
end


singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()
if hasBezel then
    setOverlayOnTop(true)
end

Starte es und drück 5 für eine Münze, 1 für Start und 9 für den Service-Schalter — das sind die Standardwerte in der mitgelieferten controls.cfg. Dann drück Esc und lies, was da steht, bevor du sie noch einmal drückst.

Was gerade passiert ist

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)

Die Einstellungen des Betreibers werden einmal gelesen, ganz oben, mit einem vernünftigen Wert für einen Automaten, der noch nie eingerichtet wurde. saveGet mit einem zweiten Argument gibt diesen Wert zurück, wenn nichts gespeichert wurde, und so unterscheidet man einen ersten Start von einem späteren.

local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end

Münzen rein, Credits raus, zu dem Kurs, den der Betreiber eingestellt hat. Das while statt eines if ist keine Vorsicht vor unmöglichen Eingaben — es ist der Betreiber, der den Preis von vier Münzen auf eine senkt, während drei Münzen darin sitzen.

    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

Der Beenden-Schalter erreicht dein Spiel nur wegen des singeSetQuitKeyEnabled(false) ganz unten im Skript. Beim ersten Drücken wird gefragt; beim zweiten Drücken, vom Fragebildschirm aus, rufst du selbst singeQuit() auf. goBackTo merkt sich, wo der Spieler war, sodass ein Nein ihn zurück in sein Spiel bringt statt auf den Attract-Bildschirm.

Dieser Block steht als Erstes in der Funktion und endet mit return, sodass nichts anderes den Schalter verschlucken kann. Jeder andere Zustand des Spiels wird darunter behandelt.

    if state == "service" then
        serviceInput(what)
        return
    end

Wieder dieselbe Form. Solange das Service-Menü offen ist, gehört ihm jeder Schalter — der Stick steuert nicht das Spiel darunter, eine Münze landet nicht mitten in einer Einstellung. Ein if, früh, mit einem return. Jeder Bildschirm, der über einem anderen liegt, braucht das, und ein Spiel, das drei davon bekommt und das nicht hat, erzeugt Fehler, die man kaum beschreiben kann.

        saveSet("coinsPerCredit", coinsPerCredit)
    ...
    saveFlush()

Setzen, dann flushen. Ohne den Flush passiert das Schreiben am Ende des Frames, und das ist schnell, aber nicht sofort. Ein Betreiber verstellt eine Einstellung und zieht zehn Sekunden später den Stecker, und das ist die eine Stelle in einem Spiel, an der das wirklich passiert.

    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end

Das Blinken. singeGetTicks() sind die Millisekunden seit dem Start der Engine, // teilt und wirft den Rest weg, also ändert sich die Zahl alle vierhundert Millisekunden, und % 2 lässt sie zwischen null und eins wechseln. Keine Variable, kein Timer, nichts zurückzusetzen: Die Uhr hat schon gezählt.

    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())

Die Hälfte der Service-Seite, die dem Betreiber gehört. Eine Version, eine Drehung, ob es Artwork gibt und wo die Daten liegen. Nichts davon ist für den Spieler, und all das wirst du dir wünschen, wenn dich jemand wegen eines Automaten anruft, der dreihundert Meilen entfernt steht.

singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()

Ganz unten, außerhalb jeder Funktion, sodass es einmal läuft, wenn das Skript geladen wird. Keins von beiden muss in jedem Frame passieren, und mainBezelLoaded kann sich nicht ändern, während das Spiel läuft.

Probier es aus

  1. Ändere den Preis. Öffne das Service-Menü, stell Münzen pro Credit auf zwei und wirf eine Münze ein. Sieh zu, wie der Credit nicht erscheint, und behalte den Münzzähler in der untersten Zeile im Auge. Dann beende das Spiel, starte es noch einmal und sieh, dass der Preis geblieben ist.

  2. Spiel umsonst. Schalte Freispiel ein und prüf, dass Start ohne Münzen funktioniert und dass die Credits nicht negativ werden.

  3. Füg eine Seite hinzu. Leg eine zweite Seite mit Service-Informationen hinter Knopf 3 — die Felder von singeGetSystemInfo() sind ein guter Anfang, und der Eintrag in der Referenz listet sie alle auf.

  4. Dreh den Bildschirm. Starte es mit --rotate=90 und sieh dir dein Layout an. Dann mach die Service-Seite in dieser Drehung lesbar, was schwerer ist, als es klingt, und genau die Arbeit, die ein hochkant stehender Automat verlangt.

  5. Nimm die Tastatur weg. Steck sie aus oder versprich dir, sie nicht anzufassen, und spiel jeden Bildschirm mit einem Pad durch. Alles, was du nicht erreichst, ist ein Fehler.

Mach es absichtlich kaputt

Lösch den Block mit SWITCH_QUIT aus onInputPressed, lass singeSetQuitKeyEnabled(false), wo es ist, und starte es.

Jetzt beendet nichts mehr. Esc tut nichts, Q tut nichts, und dein Spiel hat keinen Ausweg, und das ist genau das, worum du gebeten hast. Das ist kein Absturz, und es gibt keine Meldung; die Engine hat genau das getan, was man ihr gesagt hat.

Schließ das Fenster mit seinem Schließen-Knopf. Das funktioniert immer, egal was ein Skript sagt, und es ist die Tür, die du dir offen gelassen hast. Im Vollbild bringt dich Alt-Enter zuerst zurück in ein Fenster.

Das hier lohnt es sich zu spüren. Die Beenden-Taste abzuschalten ist das Einzige in diesem Buch, das dich mit einem Programm zurücklassen kann, aus dem du nicht herauskommst, und die Gewohnheit, die das verhindert, ist einfach: Schreib den Ausweg in derselben Sitzung, in der du die Beenden-Taste abschaltest, nie später.

Was du gelernt hast

  • Ein Automat hat keine Tastatur, also muss jeder Bildschirm im Spiel mit einem Stick und einem Knopf funktionieren.

  • controls.cfg legt Tasten, Pad-Knöpfe und Stick-Richtungen auf die SWITCH_-Namen, die dein Spiel schon benutzt, und dein Spiel erfährt nie, was davon gedrückt wurde.

  • Vier Dateien mit Belegungen werden der Reihe nach gelesen, und jede überschreibt die vorige, sodass es eine Datei für den ganzen Automaten und eine pro Spiel geben kann.

  • Jedes Gerät, das Singe öffnet, ist ein Gamepad, auch eine Arcade-Encoder-Platine, und das Tool Input Test sagt, was ankommt.

  • Die Engine behält Pause, Beenden, Screenshot und Mausfang für sich; der Rest gehört dir.

  • Münzen werden zum Kurs des Betreibers in Credits umgezählt, und ein Automat kehrt von selbst in den Attract-Modus zurück.

  • SWITCH_SERVICE ist der Schalter des Betreibers, und dahinter liegen der Preis, die Schwierigkeit, eine Möglichkeit, die Punkte zu löschen, und was der Automat ist.

  • saveFlush() schreibt eine Einstellung sofort, denn ein Automat verliert ohne Vorwarnung den Strom.

  • singeSetQuitKeyEnabled(false) gibt den Beenden-Schalter an dein Spiel. Schreib den Ausweg im selben Moment.

  • Ein Bezel ist Artwork mit einem Loch darin, und --rotate dreht die ganze Darstellung für einen hochkant stehenden Monitor.

Das Ende

Das sind einunddreißig Lektionen, und du kannst ein Spiel schreiben.

Kein perfektes und noch kein großes, aber der Abstand zwischen hier und einem von beiden ist Zeit und Übung, nicht noch ein Buch. Du hast mit fünf Zeilen angefangen, die ein Wort auf einen schwarzen Bildschirm gesetzt haben. Jetzt weißt du, was eine Variable ist, wofür eine Funktion da ist, wie man zeichnet, wie man ein Geräusch macht, wie man merkt, dass sich zwei Dinge berührt haben, wie man eine Punktzahl irgendwo aufbewahrt, wo sie überlebt, wie man Film als Welt laufen lässt, wie man ein Modell in einen Raum mit einem Licht darauf stellt und wie man das Ganze einem Fremden in die Hand gibt.

Was du jetzt brauchst, ist die Singe-Referenz, nicht dieses Buch. Sie ist das Nachschlagewerk zu jeder Funktion, jedem Argument und jedem Rückgabewert, und sie ist das, was du beim Arbeiten tatsächlich offen haben wirst. Sie liegt diesem Buch bei, als Reference.pdf und Reference.html. Lies den Eintrag, bevor du den Aufruf benutzt; in den meisten steht ein Hinweis auf den Fehler, den Leute damit machen.

Lies auch die Skripte, die mit Singe kommen. Singe/Menu.singe, Singe/Tools.singe und Singe/Framework.singe sind keine Vorführungen, die zum Lesen geschrieben wurden — sie sind das Menü und die Service-Tools, die du die ganze Zeit benutzt hast, und sie tun echte Arbeit mit denselben Funktionen, die du auch hast. Herauszufinden, wie das Programm von jemand anderem etwas macht, ist eine eigene Fähigkeit, und diese Skripte sind ein freundlicher Ort, sie zu üben.

Und dann gibt es Forge, ein eigenes Werkzeug mit einem eigenen Buch, um ein Spiel zu beschreiben, statt es zu schreiben. Das ist ein anderer Weg. Du brauchst es nicht, aber es ist da.

Das nächste Spiel gehört dir. Mach zuerst das kleine, mach es fertig und stell es vor jemanden hin. Fertigmachen ist der Teil, von dem dir niemand sagt, dass er der schwere ist, und es ist der einzige Teil, der aus einem Ordner voller Skripte ein Spiel macht, das jemand gespielt hat.

Geh und bau es.