Jak uzywac skryptow w Questsmith

Skrypty pozwalaja tworca dostosowac doswiadczenie gracza wykraczajac poza to, co oferuje edytor scenariusza.

W Questsmith skrypty sa przypisane do scenariusza i wspoldzielone przez przygody uruchomione z tego scenariusza, a kazda przygoda zachowuje oddzielny stan gry.

Obsluga scenariuszy i widocznosc

• Skrypty sa dostepne dla scenariuszy prostego startu i kreatora postaci.
• Nadrzedne scenariusze wielokrotnego wyboru nie moga miec skryptow, ale ich opcje juz tak.
• Tylko tworca scenariusza moze przegladac i edytowac skrypty.
• Skrypty opublikowanych scenariuszy moga byc moderowane pod katem zgodnosci z zasadami.

Przeglad interfejsu skryptow

Otworz skrypty na dole karty Szczegoly podczas edycji obslugiwanego scenariusza.

• Biblioteka: Wspolne helpery i stale dostepne dla innych skryptow.
• Wejscie: Uruchamia sie podczas hooka cyklu zycia onInput.
• Kontekst: Uruchamia sie podczas hooka cyklu zycia onModelContext.
• Wyjscie: Uruchamia sie podczas hooka cyklu zycia onOutput.

W skryptach innych niz biblioteka ostatnia linia musi wywolywac modifier(text).

Panel testowania skryptu

• Wejscie: Edytowalny ladunek testowy do symulacji zachowania skryptu.
• Wyslij: Wysyla skrypt + biblioteka + wejscie na serwer do wykonania.
• Wyjscie: Pokazuje zwrocony tekst, stop, logi, state i storyCards.

Panel logow konsoli

• Wyswietla ostatnie logi z twoich przygod testowych uruchomionych z tego scenariusza.
• Dziala w czasie rzeczywistym, przydatne przy podzielonych kartach (edytor + test).
• Logi sa przechowywane przez 15 minut.

Hooki cyklu zycia

API skryptow udostepnia trzy hooki, kazdy dziala w odizolowanej sandboxie.

• onInput
• onModelContext
• onOutput

Limity wykonania: 16 MB pamieci i limit czasu 2 sekundy na hook.

Dostepne parametry

Te wartosci mozna odwolac bezposrednio w zakresie skryptu:

• text: Wejscie gracza, tekst kontekstu modelu lub tekst wyjscia zalezne od hooka.
• history: Tablica ostatnich akcji z text/rawText/type.
• storyCards: Tablica kart przygody (stary alias worldInfo nadal obslugiwany).
• state: Trwaly obiekt dla wlasnej pamieci skryptu miedzy turami.
• info: Metadane pomocnicze, np. actionCount, characterNames, maxChars, memoryLength.

Uwagi o obiekcie state

• Modyfikuj state bezposrednio (bez helpera).
• state.memory obsluguje nadpisania context, authorsNote i frontMemory.
• state.placeholders przechowuje wartosci pytan/odpowiedzi placeholderow scenariusza i utrzymuje je miedzy turami.
• state.message moze byc pokazany graczom zalezne od wsparcia klienta.

Dostepne funkcje

• log
• addStoryCard
• removeStoryCard
• updateStoryCard

Kontrakt zwracania

Skrypt powinien zwracac obiekt, najczesciej:

return { text: 'Nowy tekst' }
return { stop: true }

• text: Zastepuje strumien tekstu hooka (wejscie, kontekst modelu albo wyjscie).
• stop: Zatrzymuje postep petli. Uzywaj ostroznie i swiadomie.

Wazne zachowanie bledow

• Zwrocenie pustego tekstu w onInput wywoluje blad skryptu widoczny dla gracza.
• Zwrocenie pustego tekstu w onModelContext zachowuje sie jak brak uruchomienia skryptu.
• Zwrocenie pustego tekstu w onOutput wywoluje niestandardowa awarie skryptu widoczna dla gracza.
• Zwrocenie stop w onOutput nie jest zalecane.

Minimalny przyklad skryptu wejscia

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

  if (text.includes('chwyc miecz')) {
    state.items = ['sword']
    state.memory = { context: 'Masz miecz.' }
    state.message = 'Zdobyto miecz!'
    log('Dodano miecz graczowi')
    modifiedText = text + '\nMasz teraz takze miecz!'
  }

  return { text: modifiedText }
}

modifier(text)

Praktyczne zastosowania

• Parsery komend (wlasne komendy gracza).
• Sledzenie ekwipunku lub statusu w state.
• Dynamiczne korekty memory, authorsNote i frontMemory.
• Postprocessing kontekstu i zabezpieczenia.
• Automatyczne dodawanie/usuwanie Story Cards zalezne od zdarzen.

Dobre praktyki

1. Zaczynaj od malych skryptow i testuj kazdy hook osobno.
2. Utrzymuj skrypty deterministyczne i unikaj ciezkich obliczen.
3. Uzywaj Biblioteki dla logiki i stalych wielokrotnego uzytku.
4. Zabezpieczaj sie przed niezdefiniowanymi polami (history, placeholders, wartosci info).
5. Gdy to mozliwe, wybieraj modyfikacje addytywne zamiast pelnych przepisek.
6. Uzywaj Console Log podczas testow na zywo i odtwarzaj problemy w minimalnej formie.

W sprawie problemow ze skryptami lub prosb o funkcje uzyj kanalu Discord bledy/funkcje i dolacz kroki reprodukcji, jesli to mozliwe.