Skripting in Questsmith verwenden

Skripting ermoeglicht es Erstellern, das Spielerlebnis ueber die Funktionen des Szenario-Editors hinaus anzupassen.

In Questsmith werden Skripte an Szenarien gebunden und von allen Abenteuern genutzt, die aus diesem Szenario gestartet werden. Jedes Abenteuer behaelt dabei seinen eigenen separaten Spielzustand.

Szenario-Unterstuetzung und Sichtbarkeit

• Skripte sind fuer Szenarien vom Typ Simple Start und Character Creator verfuegbar.
• Uebergeordnete Mehrfachauswahl-Szenarien koennen keine Skripte haben, ihre Optionen jedoch schon.
• Nur der Szenario-Ersteller kann Skripte ansehen und bearbeiten.
• Veroeffentlichte Szenario-Skripte koennen auf Richtlinienkonformitaet moderiert werden.

Ueberblick ueber die Skriptoberflaeche

Oeffne Skripting unten im Tab Details, waehrend du ein unterstuetztes Szenario bearbeitest.

• Bibliothek: Geteilte Helfer und Konstanten, die anderen Skripten zur Verfuegung stehen.
• Eingabe: Laeuft im onInput-Lifecycle-Hook.
• Kontext: Laeuft im onModelContext-Lifecycle-Hook.
• Ausgabe: Laeuft im onOutput-Lifecycle-Hook.

Bei Nicht-Bibliotheks-Skripten muss die letzte Zeile modifier(text) aufrufen.

Skript-Testbereich

• Eingabe: Bearbeitbare Testnutzlast zur Simulation des Skriptverhaltens.
• Senden: Sendet Skript + Bibliothek + Eingabe zur Ausfuehrung an den Server.
• Ausgabe: Zeigt zurueckgegebenen Text, stop, Logs, state und storyCards.

Konsole-Log-Bereich

• Zeigt aktuelle Logs aus deinen eigenen Playtest-Abenteuern, die aus diesem Szenario gestartet wurden.
• Wird in Echtzeit gestreamt und ist mit geteilten Tabs (Editor + Playtest) besonders nuetzlich.
• Logs werden 15 Minuten lang gespeichert.

Lifecycle-Hooks

Die Scripting-API stellt drei Hooks bereit, die jeweils in einer isolierten Sandbox laufen.

• onInput
• onModelContext
• onOutput

Laufzeitgrenzen: 16 MB Speicher und 2 Sekunden Timeout pro Hook.

Verfuegbare Parameter

Du kannst diese Werte direkt im Skript-Scope verwenden:

• text: Spielereingabe, Modellkontexttext oder Ausgabetext - je nach Hook.
• history: Array mit letzten Aktionen inklusive text/rawText/type.
• storyCards: Array mit Abenteuerkarten (der alte Alias worldInfo bleibt unterstuetzt).
• state: Persistentes Objekt fuer benutzerdefinierten Skriptspeicher ueber mehrere Zuege hinweg.
• info: Hilfsmetadaten wie actionCount, characterNames, maxChars und memoryLength.

Hinweise zum state-Objekt

• state kann direkt geaendert werden (kein Helfer noetig).
• state.memory unterstuetzt Ueberschreibungen fuer context, authorsNote und frontMemory.
• state.placeholders speichert Platzhalter-Frage-/Antwortwerte des Szenarios und behaelt sie ueber Zuege hinweg.
• state.message kann je nach Client-Unterstuetzung fuer Spieler angezeigt werden.

Verfuegbare Funktionen

• log
• addStoryCard
• removeStoryCard
• updateStoryCard

Rueckgabe-Vertrag

Skripte sollten ein Objekt zurueckgeben, am haeufigsten:

return { text: 'Neuer Text' }
return { stop: true }

• text: Ersetzt den Hook-Textstrom (Eingabe, Modellkontext oder Ausgabe).
• stop: Haelt den Schleifenfortschritt an. Verwende es bewusst und mit Vorsicht.

Wichtiges Fehlerverhalten

• Leerer Rueckgabetext in onInput loest einen Skriptfehler fuer den Spieler aus.
• Leerer Rueckgabetext in onModelContext verhaelt sich so, als waere das Skript nicht gelaufen.
• Leerer Rueckgabetext in onOutput loest einen benutzerdefinierten Skriptfehler fuer den Spieler aus.
• stop in onOutput zurueckzugeben wird nicht empfohlen.

Minimales Eingabe-Skriptbeispiel

const modifier = (text) => {
  let modifiedText = text

  if (text.includes('Nimm ein Schwert')) {
    state.items = ['sword']
    state.memory = { context: 'Du hast ein Schwert.' }
    state.message = 'Du hast ein Schwert erhalten!'
    log('Schwert zum Spieler hinzugefuegt')
    modifiedText = text + '\nDu hast jetzt ausserdem ein Schwert!'
  }

  return { text: modifiedText }
}

modifier(text)

Praktische Anwendungsfaelle

• Befehlsparser (eigene Spielerbefehle).
• Inventar- oder Statusverfolgung in state.
• Dynamische Anpassungen von memory, authorsNote und frontMemory.
• Kontext-Nachbearbeitung und Sicherheitsleitplanken.
• Automatisches Einfuegen oder Entfernen von Story Cards anhand von Ereignissen.

Best Practices

1. Beginne mit kleinen Skripten und teste jeden Hook getrennt.
2. Halte Skripte deterministisch und vermeide aufwendige Berechnungen.
3. Nutze die Bibliothek fuer wiederverwendbare Logik und Konstanten.
4. Sichere dich gegen undefinierte Felder ab (history, placeholders, info-Werte).
5. Bevorzuge additive Aenderungen statt kompletter Textumschreibungen, wenn moeglich.
6. Nutze Console Log waehrend Live-Playtests und reproduziere Probleme moeglichst minimal.

Bei Skriptproblemen oder Funktionswuenschen nutze den Discord-Kanal fuer Fehler/Funktionswuensche und gib nach Moeglichkeit reproduzierbare Schritte an.