NovelML-Syntaxreferenz

In diesem Dokument werden die grundlegende Syntax von NovelML und seine Ausführung erläutert.

Eine ausführliche Erläuterung der einzelnen Tags finden Sie in der „Suika3-Tag-Referenz“.

1. NovelML ist eine Liste von Engine-Befehlen, die „Tags“ genannt werden.

NovelML ist eine Liste von Tags. Ein Tag ist ein Befehl für die Engine.

Jedes Tag weist die Engine an, etwas zu tun
Tags werden einzeln in der Reihenfolge ausgeführt, in der sie erscheinen
Nachdem ein Tag ausgeführt wurde, ist es „fertig“ und die „Ausführungsposition“ wird fortgesetzt

Wenn Sie dasselbe Tag erneut schreiben, wird es bei jeder Ausführung dasselbe tun.

2. Die Ausführung erfolgt von oben nach unten

NovelML wird Tag für Tag vom Anfang der Datei bis zum Ende ausgeführt.

Die Ausführung erfolgt normalerweise vorwärts
Es gibt nur eine aktuelle Ausführungsposition

[text text="Hello"]
[text text="World"]

In diesem Fall:

Hello wird angezeigt
Dann wird World angezeigt

3. Alles muss als Tags geschrieben werden

In NovelML muss jede Zeile ein Tag sein.

Das gesamte Szenario wird mithilfe von Tags geschrieben
Auch Text muss das Tag [text] verwenden

[text text="It's a beautiful day."]

4. Tags, die warten, und Tags, die nicht warten

Es gibt zwei Hauptarten von Tags:

Tags, die ausgeführt werden und sofort zum nächsten Tag wechseln
Tags, die auf Benutzereingaben oder den Abschluss eines Vorgangs warten

Zu den gängigen „Warten“-Tags gehören:

text (wartet auf einen Klick)
click (wartet auf einen Klick)
wait (wartet eine angegebene Zeit)
video (wartet, bis die Wiedergabe beendet ist)

Diese Tags unterbrechen die Ausführung ohne besondere Syntax.

4.1 Tags, die im Hintergrund (asynchron) ausgeführt werden

Einige Tags werden möglicherweise im Hintergrund ausgeführt (asynchron).

Typische Beispiele:

anime
move

Diese Tags:

Erstellen und starten Sie eine Animation oder Bewegung
Wenn async="true" angegeben ist, wartet die Engine nicht, bis der Vorgang abgeschlossen ist, und fährt sofort mit dem nächsten Tag fort

Aus diesem Grund werden möglicherweise Tags nach einem async="true"-Tag ausgeführt, während die Animation noch abgespielt wird.

Damit können Sie Dinge tun wie:

Verschieben Sie einen Hintergrund oder ein Zeichen
Während gleichzeitig Text angezeigt oder andere Effekte ausgeführt werden

5. Tags, die den Ausführungsfluss ändern

Normalerweise erfolgt die Ausführung von oben nach unten, aber einige Tags ändern sich, wo die Ausführung fortgesetzt wird.

5.1 Etiketten

[label start]

Eine Beschriftung markiert eine benannte Position im Szenario
Das Ausführen eines Labels allein bewirkt nichts

5.2 Sprünge

[goto name="start"]

6. Bedingte Verzweigung (if / elseif / else)

[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[endif]

Nur der erste passende Block wird ausgeführt
Nicht ausgewählte Blöcke werden komplett übersprungen
Sie können elseif null oder mehrmals schreiben
else ist optional

7. Variablen und Variablenerweiterung

7.1 Variablen festlegen

Verwenden Sie das Tag [set], um eine Variable festzulegen.

[set name="player_name" value="Alice"]

Alle Variablen sind Strings
Zahlen und boolesche Werte werden ebenfalls als Zeichenfolgen gespeichert

7.2 Variable Erweiterung

Sie können die Variablenerweiterung innerhalb von Tag-Werten und Text verwenden.

[text text="${player_name} stands up"]

${...} wird zur Laufzeit durch den Variablenwert ersetzt
Die Erweiterung erfolgt wenn das Tag ausgeführt wird

[set name="x" value="1"]
[text text="${x}"]
[set name="x" value="2"]
[text text="${x}"]

In diesem Beispiel ist die Ausgabe 1 und dann 2.

8. Makros sind Blöcke, die Sie als Einheit ausführen können

Mit Makros können Sie mehrere Tags gruppieren und gemeinsam ausführen.

[defmacro name="greet"]
  [text text="Hello"]
[endmacro]

[callmacro name="greet"]

9. Dateien wechseln (laden)

[load file="scene2.txt" label="start"]

file= ist obligatorisch und label= ist optional.

10. Was passiert am Ende einer Datei?

Bei Ausführung:

Erreicht das Ende der Datei und
Es passieren keine weiteren goto- oder load-Tags

Dann endet die Szenarioausführung.

Auf einigen Plattformen (zum Beispiel iOS oder Spielekonsolen) darf die App jedoch nicht beendet werden.

Daher wird empfohlen, dass Ihr Szenario ausdrücklich:

Springt zurück zum Titel mit goto, oder
Lädt eine Titelszene mit load

anstatt automatisch zu enden.

11. Wie dieses Dokument mit anderen Dokumenten zusammenpasst

Dieses Dokument soll begleiten:

Tag-Referenz: erklärt, was jedes Tag bewirkt
Dieses Dokument: erklärt, wie ein Szenario abläuft

Einzelheiten zu einzelnen Tags finden Sie in der „Tag-Referenz“.