Come usare lo scripting in Questsmith

Lo scripting permette ai creatori di personalizzare l esperienza del giocatore oltre quanto supportato dall editor di scenario.

In Questsmith, gli script sono collegati agli scenari e condivisi dalle avventure avviate da quello scenario, mentre ogni avventura mantiene il proprio stato di gioco separato.

Supporto scenario e visibilita

• Gli script sono disponibili per scenari di avvio semplice e creatore personaggio.
• Gli scenari padre a scelta multipla non possono avere script, ma le loro opzioni si.
• Solo il creatore dello scenario puo vedere e modificare gli script.
• Gli script di scenari pubblicati possono essere sottoposti a moderazione per conformita alle linee guida.

Panoramica interfaccia scripting

Apri scripting dal fondo della scheda Dettagli mentre modifichi uno scenario supportato.

• Libreria: Helper e costanti condivise disponibili agli altri script.
• Input: Viene eseguito durante l hook di ciclo di vita onInput.
• Contesto: Viene eseguito durante l hook di ciclo di vita onModelContext.
• Output: Viene eseguito durante l hook di ciclo di vita onOutput.

Per gli script non di libreria, l ultima riga deve chiamare modifier(text).

Pannello test script

• Input: Payload di test modificabile per simulare il comportamento dello script.
• Invia: Invia script + libreria + input al server per l esecuzione.
• Output: Mostra testo restituito, stop, log, state e storyCards.

Pannello log console

• Mostra i log recenti delle tue avventure di playtest avviate da quello scenario.
• Fluisce in tempo reale, utile con schede divise (editor + playtest).
• I log vengono conservati per 15 minuti.

Hook del ciclo di vita

L API di scripting espone tre hook, ciascuno eseguito in una sandbox isolata.

• onInput
• onModelContext
• onOutput

Limiti runtime: 16 MB di memoria e timeout di 2 secondi per hook.

Parametri disponibili

Puoi riferirti a questi valori direttamente nello scope dello script:

• text: Input del giocatore, testo di contesto modello o testo di output a seconda dell hook.
• history: Array di azioni recenti con text/rawText/type.
• storyCards: Array di carte avventura (alias legacy worldInfo ancora supportato).
• state: Oggetto persistente per memoria script personalizzata tra i turni.
• info: Metadati di supporto come actionCount, characterNames, maxChars, memoryLength.

Note sull oggetto state

• Modifica state direttamente (nessun helper necessario).
• state.memory supporta override di context, authorsNote e frontMemory.
• state.placeholders memorizza valori domanda/risposta dei placeholder scenario e persiste tra i turni.
• state.message puo essere mostrato ai giocatori in base al supporto client.

Funzioni disponibili

• log
• addStoryCard
• removeStoryCard
• updateStoryCard

Contratto di ritorno

Gli script dovrebbero restituire un oggetto, di solito:

return { text: 'Nuovo testo' }
return { stop: true }

• text: Sostituisce il flusso testo dell hook (input, contesto modello o output).
• stop: Interrompe la progressione del ciclo. Usalo con attenzione e intenzione.

Comportamento errori importante

• Restituire testo vuoto in onInput genera un errore script visibile al giocatore.
• Restituire testo vuoto in onModelContext si comporta come se lo script non fosse stato eseguito.
• Restituire testo vuoto in onOutput genera un errore script personalizzato visibile al giocatore.
• Restituire stop in onOutput non e consigliato.

Esempio minimo di script input

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

  if (text.includes('afferra una spada')) {
    state.items = ['sword']
    state.memory = { context: 'Hai una spada.' }
    state.message = 'Hai ottenuto una spada!'
    log('Aggiunta una spada al giocatore')
    modifiedText = text + '\nOra hai anche una spada!'
  }

  return { text: modifiedText }
}

modifier(text)

Casi d uso pratici

• Parser comandi (comandi giocatore personalizzati).
• Tracciamento inventario o stato in state.
• Regolazioni dinamiche di memory, authorsNote e frontMemory.
• Post-elaborazione contesto e barriere di sicurezza.
• Inserimento/rimozione automatica di Story Cards in base agli eventi.

Buone pratiche

1. Inizia con script piccoli e testa ogni hook separatamente.
2. Mantieni script deterministici ed evita calcoli pesanti.
3. Usa Libreria per logica e costanti riutilizzabili.
4. Difenditi da campi non definiti (history, placeholders, valori info).
5. Preferisci modifiche additive a riscritture complete quando possibile.
6. Usa Console Log durante playtest live e riproduci i problemi in modo minimo.

Per problemi di script o richieste funzionalita, usa il canale Discord bug/richieste funzionalita e includi passaggi riproducibili quando possibile.