Variables y Directivas

Las variables son el estado del juego del mundo. La IA lee los valores actuales cada turno y escribe directivas entre corchetes en su respuesta para actualizarlas.

Esquema de Variable

{
  "id": "health",
  "name": "Health",
  "type": "number",
  "defaultValue": 100,
  "min": 0,
  "max": 100,
  "description": "Player's physical health",
  "behaviorRules": "0 = death. 1-20 = critical. 20-50 = wounded. 50-80 = bruised. 80-100 = healthy. Decrease on physical damage: punch -5 to -10, slash -15 to -25, fall -20 to -40. Rest +5, healing +10 to +30. Max change per turn: 30."
}

Tipos de Variable

number

Valores numéricos con límites opcionales min/max.

Sintaxis de directiva:

[health: set 50]       → establecer a 50
[health: +10]          → sumar 10 (alias: add)
[health: -15]          → restar 15 (alias: subtract)
[health: *2]           → multiplicar por 2 (alias: multiply)
[gold: 100]            → set implícito (sin operador)

string

Valores de texto.

Sintaxis de directiva:

[location: set "dark forest"]
[mood: set "suspicious"]
[notes: append " Found a clue."]

boolean

Banderas verdadero/falso.

Sintaxis de directiva:

[has-key: toggle]        → alterna entre true ↔ false
[met-elder: set true]
[quest-active: set false]

json

Estructuras complejas — objetos y arrays. Soporta actualizaciones anidadas por dot-path.

Sintaxis de directiva:

[inventory: push {"name": "Iron Sword", "damage": 10}]
[inventory: delete 0]
[inventory: set [{"name": "Potion", "qty": 3}]]

[npcs.aria.affinity: +5]
[npcs.aria.mood: set "happy"]
[npcs: merge {"aria": {"trust": 80}}]
[quest-log: push {"id": "q1", "status": "active"}]
[config: delete "deprecated-key"]

Operaciones por dot-path:

• [root.nested.field: op value] — actualiza un campo anidado dentro de una variable JSON
• Crea automáticamente objetos intermedios si no existen
• Acceso por índice de array: [inventory.0.durability: -1]

Todas las operaciones

Operación	Tipos	Sintaxis	Comportamiento
set	todos	[id: set value] o [id: value]	Reemplaza el valor
add / +	number	[id: +10] o [id: add 10]	Incrementa
subtract / -	number	[id: -5] o [id: subtract 5]	Decrementa
multiply / *	number	[id: *2] o [id: multiply 2]	Escala
toggle	boolean	[id: toggle]	Alterna true/false
append	string	[id: append " text"]	Concatena
merge	json (objeto)	[id: merge {"key": "val"}]	Merge superficial
push	json (array)	[id: push "item"] o [id: push {...}]	Agrega al array
delete	json	[id: delete "key"] o [id: delete 0]	Elimina clave/índice

Directivas de Audio

El audio se activa a través de un formato de directiva separado:

[audio: track-id play]
[audio: track-id stop]
[audio: track-id crossfade 2.5]
[audio: track-id volume 0.5]
[audio: track-id play chain:next-track]

Reglas de comportamiento

El campo behaviorRules es texto en lenguaje natural que se inyecta en el prompt del sistema de la IA como un bloque <behavior-rules>. Le enseña a la IA cuándo y cómo actualizar la variable.

Las reglas de comportamiento efectivas incluyen:

• Qué significa cada rango de valor narrativamente
• Qué dispara los cambios (y en qué dirección)
• Pautas de magnitud (cuánto cambiar)
• Límites (cambio máximo por turno, límites absolutos)
• Relaciones con otras variables

Ejemplo — Variable JSON compleja:

"behaviorRules": "Array of party members. Push new object when recruiting: {\"name\": \"...\", \"class\": \"...\", \"trust\": 50}. Update trust via dot-path: [allies.0.trust: +5]. To remove an ally, use a Behavior with an UpdateVariable JSON Patch action, or overwrite the whole array with [allies: set [...]]. Trust below 20 = may betray."

Convenciones de ID

• Los IDs deben ser únicos dentro del mundo
• Los IDs que consisten en letras, números y guiones bajos son accesibles como macros de variable — por ejemplo, player_health es alcanzable como {{player_health}} en las entradas. Los IDs que contienen - no son reconocidos por el resolvedor de macros, así que prefiere snake_case (o camelCase) para cualquier variable que planees referenciar mediante la sintaxis de macro de doble llave.
• El analizador de directivas de variable (usado dentro de respuestas de IA) sí acepta - en los IDs, así que los IDs en kebab-case siguen funcionando en directivas como [player-health: +5].
• Evita las palabras reservadas: audio, user, char, time, date