Como usar scripting en Questsmith
Usa scripts de escenario para controlar el comportamiento de entrada, contexto y salida mas alla de la interfaz del editor.
El scripting permite a los creadores personalizar la experiencia del jugador mas alla de lo que admite el editor de escenarios.
En Questsmith, los scripts se vinculan al escenario y se comparten entre las aventuras iniciadas desde ese escenario, mientras cada aventura mantiene su propio estado de juego separado.
Compatibilidad y visibilidad del escenario
- Los scripts estan disponibles para escenarios de inicio simple y de creador de personaje.
- Los escenarios padre de opcion multiple no pueden tener scripts, pero sus opciones si.
- Solo el creador del escenario puede ver y editar scripts.
- Los scripts de escenarios publicados pueden ser revisados por moderacion para validar el cumplimiento de normas.
Resumen de la interfaz de scripting
Abre scripting desde la parte inferior de la pestana Detalles mientras editas un escenario compatible.
- Biblioteca: Ayudantes y constantes compartidas disponibles para otros scripts.
- Entrada: Se ejecuta durante el gancho de ciclo de vida onInput.
- Contexto: Se ejecuta durante el gancho de ciclo de vida onModelContext.
- Salida: Se ejecuta durante el gancho de ciclo de vida onOutput.
En scripts que no son de biblioteca, la ultima linea debe llamar a modifier(text).
Panel de prueba de scripts
- Entrada: Carga de prueba editable para simular el comportamiento del script.
- Enviar: Envia script + biblioteca + entrada al servidor para su ejecucion.
- Salida: Muestra texto devuelto, stop, registros, state y storyCards.
Panel de registro de consola
- Muestra los registros recientes de tus propias aventuras de prueba iniciadas desde ese escenario.
- Se transmite en tiempo real y es util con pestanas divididas (editor + prueba).
- Los registros se conservan durante 15 minutos.
Ganchos de ciclo de vida
La API de scripting expone tres ganchos, cada uno en una sandbox aislada.
- onInput
- onModelContext
- onOutput
Limites de ejecucion: 16 MB de memoria y 2 segundos de tiempo maximo por gancho.
Parametros disponibles
Puedes referenciar estos valores directamente dentro del alcance del script:
- text: Entrada del jugador, texto de contexto del modelo o texto de salida segun el gancho.
- history: Arreglo de acciones recientes con text/rawText/type.
- storyCards: Arreglo de tarjetas de aventura (el alias heredado worldInfo sigue disponible).
- state: Objeto persistente para memoria de script personalizada entre turnos.
- info: Metadatos auxiliares como actionCount, characterNames, maxChars y memoryLength.
Notas sobre el objeto state
- Modifica state directamente (sin helper).
- state.memory admite reemplazos de context, authorsNote y frontMemory.
- state.placeholders guarda valores de pregunta/respuesta de placeholders del escenario y persiste entre turnos.
- state.message puede mostrarse a jugadores segun el soporte del cliente.
Funciones disponibles
- log
- addStoryCard
- removeStoryCard
- updateStoryCard
Contrato de retorno
Los scripts normalmente deben devolver un objeto como estos ejemplos:
return { text: 'Texto nuevo' }
return { stop: true }- text: Reemplaza el flujo de texto del gancho (entrada, contexto del modelo o salida).
- stop: Detiene el avance del bucle. Usalo con cuidado y de forma intencional.
Comportamiento importante de errores
- Devolver texto vacio en onInput lanza un error de script al jugador.
- Devolver texto vacio en onModelContext se comporta como si el script no se hubiera ejecutado.
- Devolver texto vacio en onOutput lanza un fallo de script personalizado al jugador.
- No se recomienda devolver stop en onOutput.
Ejemplo minimo de script de entrada
const modifier = (text) => {
let modifiedText = text
if (text.includes('agarra una espada')) {
state.items = ['sword']
state.memory = { context: 'Tienes una espada.' }
state.message = 'Has conseguido una espada!'
log('Se anadio una espada al jugador')
modifiedText = text + '\nAhora tambien tienes una espada!'
}
return { text: modifiedText }
}
modifier(text)Casos de uso practicos
- Analizadores de comandos (comandos personalizados del jugador).
- Seguimiento de inventario o estado dentro de state.
- Ajustes dinamicos de memory, authorsNote y frontMemory.
- Posprocesado de contexto y barreras de seguridad.
- Insercion o eliminacion automatica de Story Cards segun eventos.
Buenas practicas
- Empieza con scripts pequenos y prueba cada gancho por separado.
- Manten los scripts deterministas y evita computo pesado.
- Usa la biblioteca para logica y constantes reutilizables.
- Protegete ante campos indefinidos (history, placeholders, valores de info).
- Prefiere cambios aditivos en lugar de reescrituras completas cuando sea posible.
- Usa Console Log durante pruebas en vivo y reproduce problemas de forma minima.
Para problemas de scripts o solicitudes de funciones, usa el canal de errores/funciones de Discord e incluye pasos reproducibles cuando sea posible.