Comment utiliser le script dans Questsmith

Le scripting permet aux createurs de personnaliser l experience joueur au-dela de ce que prend en charge l editeur de scenario.

Dans Questsmith, les scripts sont attaches aux scenarios et partages par les aventures lancees depuis ce scenario, tandis que chaque aventure conserve son propre etat de jeu separe.

Prise en charge et visibilite du scenario

• Les scripts sont disponibles pour les scenarios de demarrage simple et de createur de personnage.
• Les scenarios parents a choix multiples ne peuvent pas avoir de scripts, mais leurs options oui.
• Seul le createur du scenario peut voir et modifier les scripts.
• Les scripts de scenario publies peuvent etre moderes pour verifier le respect des regles.

Vue d ensemble de l interface de scripting

Ouvre le scripting en bas de l onglet Details pendant l edition d un scenario compatible.

• Bibliotheque: Aides et constantes partagees disponibles pour les autres scripts.
• Entree: S execute pendant le hook de cycle de vie onInput.
• Contexte: S execute pendant le hook de cycle de vie onModelContext.
• Sortie: S execute pendant le hook de cycle de vie onOutput.

Pour les scripts hors bibliotheque, la derniere ligne doit appeler modifier(text).

Panneau de test des scripts

• Entree: Charge utile de test modifiable pour simuler le comportement du script.
• Envoyer: Envoie script + bibliotheque + entree au serveur pour execution.
• Sortie: Affiche le texte renvoye, stop, les journaux, state et storyCards.

Panneau de journaux console

• Affiche les journaux recents de tes propres aventures de test lancees depuis ce scenario.
• Diffuse en temps reel, utile avec des onglets scindes (editeur + test).
• Les journaux sont conserves pendant 15 minutes.

Hooks de cycle de vie

L API de scripting expose trois hooks, chacun execute dans une sandbox isolee.

• onInput
• onModelContext
• onOutput

Limites d execution: 16 MB de memoire et 2 secondes de delai par hook.

Parametres disponibles

Tu peux referencer ces valeurs directement dans la portee du script:

• text: Entree joueur, texte de contexte du modele ou texte de sortie selon le hook.
• history: Tableau des actions recentes avec text/rawText/type.
• storyCards: Tableau de cartes d aventure (alias historique worldInfo toujours pris en charge).
• state: Objet persistant pour une memoire de script personnalisee entre les tours.
• info: Metadonnees d aide comme actionCount, characterNames, maxChars et memoryLength.

Notes sur l objet state

• Modifie state directement (aucun helper necessaire).
• state.memory prend en charge les remplacements de context, authorsNote et frontMemory.
• state.placeholders stocke les valeurs question/reponse des placeholders de scenario et persiste entre les tours.
• state.message peut etre affiche aux joueurs selon le support client.

Fonctions disponibles

• log
• addStoryCard
• removeStoryCard
• updateStoryCard

Contrat de retour

Les scripts doivent renvoyer un objet, le plus souvent:

return { text: 'Nouveau texte' }
return { stop: true }

• text: Remplace le flux texte du hook (entree, contexte modele ou sortie).
• stop: Interrompt la progression de la boucle. A utiliser avec intention et prudence.

Comportement d erreur important

• Retourner un texte vide dans onInput declenche une erreur de script pour le joueur.
• Retourner un texte vide dans onModelContext se comporte comme si le script n avait pas ete execute.
• Retourner un texte vide dans onOutput declenche un echec de script personnalise pour le joueur.
• Retourner stop dans onOutput n est pas recommande.

Exemple minimal de script d entree

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

  if (text.includes('prends une epee')) {
    state.items = ['sword']
    state.memory = { context: 'Tu as une epee.' }
    state.message = 'Tu as obtenu une epee !'
    log('Epee ajoutee au joueur')
    modifiedText = text + '\nTu as maintenant aussi une epee !'
  }

  return { text: modifiedText }
}

modifier(text)

Cas d usage pratiques

• Analyseurs de commandes (commandes joueur personnalisees).
• Suivi d inventaire ou d etat dans state.
• Ajustements dynamiques de memory, authorsNote et frontMemory.
• Post-traitement de contexte et garde-fous de securite.
• Insertion/suppression automatique de Story Cards selon les evenements.

Bonnes pratiques

1. Commence par de petits scripts et teste chaque hook separement.
2. Garde des scripts deterministes et evite les calculs lourds.
3. Utilise la Bibliotheque pour la logique et les constantes reutilisables.
4. Protege-toi contre les champs non definis (history, placeholders, valeurs info).
5. Prefere les modifications additives aux reecritures completes quand c est possible.
6. Utilise Console Log en test live et reproduis les problemes de facon minimale.

Pour les problemes de script ou demandes de fonctionnalite, utilise le canal Discord bugs/fonctionnalites et ajoute des etapes reproductibles si possible.