Directivas y Macros de IA
La IA escribe una historia. Dentro de esa historia van instrucciones cortas, como [health: -15] o [gold: +50], que el motor quita antes de que el jugador vea nada. El jugador lee una narración limpia mientras el estado del juego cambia entre bastidores.
Las macros funcionan al revés: son marcadores como {{char}} y {{user}} que pones en tus entradas y que el motor rellena antes de que la IA las lea.
Si aún no has leído Variables, empieza por ahí. Las directivas solo tienen sentido cuando entiendes lo que cambian.
Qué variables usan directivas
Las variables con el Seguimiento preciso activado (las variables nuevas de tipo Número e Interruptor lo traen activado) las cambia el ayudante de seguimiento después de cada respuesta, no las directivas. La IA las ve como de solo lectura, y cualquier directiva que escriba para ellas se descarta. Las directivas son la forma en que la IA cambia todo lo demás que tiene permitido escribir: variables con el Seguimiento preciso desactivado, de Texto sin Valores permitidos y de tipo Lista / tabla. Las variables con Acceso de la IA puesto en Solo lectura para la IA o Solo motor (oculta para la IA) también ignoran las directivas.
Por qué existen las directivas
En un RPG de mesa, el director de juego dice "el goblin te corta el brazo, recibes 15 de daño" y el jugador borra un número en su hoja. En Yumina, la IA es el director de juego y el motor es la hoja de personaje.
La IA podría simplemente escribir "el jugador ahora tiene 85 de salud", pero entonces necesitarías que el motor analizara lenguaje natural, descifrara qué variable cambió y calculara el nuevo valor. Eso es frágil y poco fiable.
En su lugar, la IA escribe un corchete estructurado al final de su narrativa:
La garra del goblin te rasguña el antebrazo, trazando una línea ardiente de dolor.
[health: -15]El motor ve [health: -15], resta 15, recorta a los límites min/max y elimina la directiva del texto. El jugador solo ve la historia, y el panel de estado se actualiza.
La IA nunca tiene que hacer las cuentas ni acordarse de los límites; de las dos cosas se encarga el motor.
Sintaxis de directivas
Toda directiva sigue el mismo patrón:
[variable-id: operation value]Tres partes dentro de los corchetes: qué Variable, qué hacer y con qué valor.
Las nueve operaciones
| Operación | Sintaxis | Ejemplo | Qué ocurre |
|---|---|---|---|
| Set | [var: set value] o [var: value] | [location: set "forest"] | Reemplaza el valor de la Variable por completo |
| Add | [var: add N] o [var: +N] | [gold: +50] | Suma N a una Variable numérica |
| Subtract | [var: subtract N] o [var: -N] | [health: -15] | Resta N a una Variable numérica |
| Multiply | [var: multiply N] o [var: *N] | [damage: *2] | Multiplica una Variable numérica por N |
| Toggle | [var: toggle] | [has-key: toggle] | Invierte un booleano (true pasa a false, false pasa a true) |
| Append | [var: append "text"] | [log: append ", found key"] | Añade texto al final de una Variable string |
| Merge | [var: merge {...}] | [stats: merge {"level": 2}] | Fusiona superficialmente un objeto en una Variable JSON |
| Push | [var: push {...}] | [inventory: push {"name": "Sword"}] | Añade un elemento al final de un array JSON |
| Delete | [var: delete "key"] o [var: delete N] | [config: delete "old-field"], [inventory: delete 0] | Elimina una clave de un objeto JSON (string entre comillas) o un elemento por índice de un array JSON (número). El valor después de delete es obligatorio: [var: delete] sin nada se degrada silenciosamente a un set implícito. |
Rutas dentro de variables JSON. [relations.chars.lin: merge {...}] escribe dentro de una variable JSON. Si la clave aún no existe, la escritura la crea: merge crea el objeto, push crea una lista de un elemento y add/subtract cuentan desde 0. Una ruta que pasa por un valor simple (hp.max cuando hp es un número) se omite en vez de sobrescribirse. Los elementos de un array se indican como list.0.hp o list[0].hp.
Reglas de sintaxis de valores
- Números: dígitos sin formato —
10,3.5,-7 - Strings: entre comillas dobles —
"forest","magic sword" - Booleanos: palabras clave sin formato —
true,false - JSON: objeto o array en línea —
{"level": 2},[1, 2, 3]
La trampa de la abreviatura
Esta es la fuente de confusión más común para nuevos creadores:
[health: -10] → resta 10 (abreviatura de subtract)
[health: +10] → suma 10 (abreviatura de add)
[health: *2] → multiplica por 2 (abreviatura de multiply)
[health: 10] → ESTABLECE health a 10 (set implícito, NO suma)El símbolo inicial (-, +, *) determina la operación. Sin símbolo significa set. Así que [health: 50] no suma 50: reemplaza el valor actual por 50.
Para establecer explícitamente un valor negativo (raro, pero posible), escribe [health: set -10].
Nombrado: ID o nombre visible
Las directivas pueden referenciar una Variable por su ID (player-hp) o su nombre visible (Player HP). El motor mantiene un mapa de nombre a ID y resuelve ambos. Los ID son más fiables, especialmente cuando los nombres visibles contienen espacios.
Rutas anidadas para Variables JSON
Cuando tienes una Variable JSON con estructura anidada, la IA puede apuntar a campos específicos usando notación de punto:
[relationships.aria.trust: +10]
[game-state.factions.ember-court.affinity: set 75]
[inventory.0.durability: -1]El motor navega la ruta automáticamente. Si los objetos intermedios no existen, los crea. Esto significa que la IA puede actualizar un campo en lo profundo de un objeto complejo sin tocar nada más.
Directivas de audio
El audio usa una sintaxis de corchetes similar — [audio: track-id action] — con acciones como play, stop, crossfade, volume y encadenamiento de pistas. Para la referencia completa de directivas de audio con ejemplos, consulta Diseño de audio.
El formato JSON Patch
Para operaciones complejas, especialmente eliminar elementos de arrays, el motor admite un formato JSON Patch envuelto en XML. Este es también el formato usado por mundos migrados desde SillyTavern.
<UpdateVariable target="inventory">
<JSONPatch>
[
{"op": "remove", "path": "/0"},
{"op": "replace", "path": "/1/durability", "value": 5}
]
</JSONPatch>
</UpdateVariable>Se admiten cuatro operaciones de patch:
| Operación | Qué hace | Ejemplo |
|---|---|---|
replace | Establece un valor en una ruta | {"op": "replace", "path": "/health", "value": 80} |
delta | Suma o resta (positivo suma, negativo resta) | {"op": "delta", "path": "/gold", "value": -50} |
insert | Añade un nuevo par clave-valor | {"op": "insert", "path": "/inventory/torch", "value": 1} |
remove | Elimina una clave o elemento de array | {"op": "remove", "path": "/0"} |
Las rutas usan barras inclinadas (/health, /inventory/0) que el motor convierte internamente a rutas con puntos.
Cuándo usar JSON Patch vs directivas con corchetes
La mayoría del tiempo, las directivas con corchetes son más simples y la IA las produce más fiablemente. JSON Patch es útil para dos casos específicos:
Eliminar elementos de array por índice:
[inventory: delete 0]funciona, pero{"op": "remove", "path": "/0"}de JSON Patch es el formato que algunos modelos de IA producen de manera más consistente al lidiar con arrays.Operaciones por lotes sobre una sola Variable: cuando necesitas actualizar varios campos en una Variable JSON a la vez, un único bloque JSON Patch es más limpio que cinco directivas con corchetes separadas.
Si estás escribiendo reglas de comportamiento para la IA, dile qué formato usar. La mayoría de los mundos se limitan exclusivamente a las directivas con corchetes. Solo introduce JSON Patch si necesitas específicamente eliminar elementos de array y la sintaxis con corchetes no funciona de manera fiable.
Cómo procesa el motor la salida de la IA
Cuando la IA devuelve una respuesta, el motor la pasa por una tubería de análisis antes de que el jugador vea nada. Conocer el orden te ayuda a depurar las directivas que no se detectan.
Paso 1: Eliminar etiquetas de pensamiento. Algunos modelos (como Gemini) emiten razonamiento interno en etiquetas <thinking>...</thinking>. El motor las elimina primero.
Paso 2: Extraer bloques JSON Patch. El motor busca bloques XML <UpdateVariable> y los convierte en operaciones de efecto internas. En esta etapa también se recogen las directivas que algunos modelos envuelven en un bloque de código json.
Paso 3: Extraer directivas de audio. Cualquier cosa que coincida con [audio: ...] se extrae y se encola para el sistema de audio.
Paso 4: Extraer directivas JSON. Se extraen las directivas con corchetes que llevan un valor JSON (set, merge, push, delete). Se analizan primero porque su contenido JSON podría tener caracteres que confunden a la regex más simple. Las imágenes [image: …] no se tocan.
Paso 5: Extraer directivas estándar. Todo lo que coincide con [var: op value]: las operaciones de add, subtract, set, toggle y demás operaciones simples.
Paso 6: Limpiar el texto. Todas las directivas extraídas se eliminan. Las líneas en blanco extra se colapsan. El resultado es texto narrativo limpio más una lista de efectos.
Después, sobre el texto limpio se ejecutan las reglas de Procesar la respuesta. El motor aplica los efectos (junto con lo que decidió el Seguimiento preciso) y comprueba los comportamientos. El jugador ve el texto limpio.
Por qué importa el orden de análisis
Las directivas JSON se extraen antes que las directivas estándar porque una directiva como [stats: merge {"health": 50, "mana": 30}] contiene dos puntos y números que la regex estándar malinterpretaría. Al manejar los patrones JSON primero, el motor evita falsas coincidencias.
Si una directiva no se reconoce, la causa más común es JSON mal formado: una llave sin pareja o una comilla faltante. El motor omite silenciosamente las directivas que no puede analizar en lugar de fallar.
Referencia completa → Especificación del mundo: Variables
Macros: texto dinámico en tus entradas
Las macros son marcadores que escribes en las entradas y que el motor reemplaza con valores reales antes de enviar a la IA. Se ven así: {{char}}, {{user}}, {{turnCount}}.
Escribes tus entradas una vez y se adaptan al contexto. Cambia el nombre del personaje y cada {{char}} se actualiza automáticamente. El jugador elige una persona y {{user}} la sigue.
Macros esenciales
| Macro | Se expande a | Salida de ejemplo |
|---|---|---|
{{char}} | Nombre del personaje actual | Luna |
{{user}} | Nombre del jugador (o nombre de la persona activa) | Kai |
{{turnCount}} | Número de turno actual | 42 |
Estas tres cubren la mayoría de los casos de uso. Usarás {{char}} y {{user}} en casi todas las entradas.
Macros de aleatoriedad
| Macro | Comportamiento | Ejemplo |
|---|---|---|
{{random::a::b::c}} | Elige una al azar cada vez | {{random::sunny::cloudy::rainy}} podría dar "cloudy" |
{{pick::a::b::c}} | Selección estable: mismo resultado dentro de un turno | {{pick::red::blue::green}} siempre da el mismo color en el mismo turno |
{{roll::NdS+M}} | Tirada de dados: N dados, S caras, más modificador M | {{roll::2d6+3}} podría dar 11 |
La diferencia entre random y pick: random vuelve a tirar cada vez que la macro se expande, así que la misma entrada expandida dos veces podría dar resultados diferentes. pick usa un hash estable basado en la posición de la macro en la entrada y el número de turno actual: da el mismo resultado cada vez dentro de un turno, pero puede cambiar al siguiente turno.
Usa random para variedad (clima, descripciones de multitudes). Usa pick cuando importa la consistencia dentro de un turno (el atuendo de un personaje debe ser el mismo si se referencia dos veces). Usa roll cuando quieres mecánicas basadas en dados a las que la IA pueda reaccionar.
Macros de tiempo y fecha
| Macro | Se expande a | Salida de ejemplo |
|---|---|---|
{{time}} | Hora actual (HH:MM) | 14:30 |
{{date}} | Fecha actual (formato local) | 13/5/2026 |
{{weekday}} | Día de la semana | martes |
{{isodate}} | Formato de fecha ISO | 2026-05-13 |
{{isotime}} | Formato de hora ISO | 14:30:00 |
{{idle}} | Tiempo desde el último mensaje del jugador | 5 minutos |
Estos son tiempo del mundo real, no tiempo dentro del juego. Útil para mundos que mezclan tiempo real y ficticio, o para mecánicas de detección de inactividad ("si el jugador no ha respondido en 10 minutos, el personaje envía un mensaje preocupado").
Macros de contexto
| Macro | Se expande a |
|---|---|
{{lastMessage}} | Texto completo del último mensaje |
{{lastUserMessage}} | Último mensaje del jugador |
{{lastCharMessage}} | Último mensaje del personaje |
{{model}} | Nombre del modelo de IA en uso |
Macros de persona del jugador
Los jugadores crean personas desde la página de Perfil → carrusel de personas: identidades con nombre, apariencia, personalidad e historia de fondo. Cuando una persona está activa, estas macros la usan:
| Macro | Se expande a |
|---|---|
{{persona_name}} | Nombre de la persona activa |
{{persona_appearance}} | Descripción física |
{{persona_personality}} | Rasgos de carácter |
{{persona_backstory}} | Historia y origen |
{{persona}} | Los cuatro campos combinados, más las entradas extra que tenga la persona |
Consejo: coloca {{persona}} en una entrada de Personaje y mundo llamada "Acerca del jugador" y la IA siempre sabrá a quién está interpretando el jugador. Cuando cambian de persona, la IA se pone al día automáticamente.
{{user}} usa el nombre de la persona activa, o el nombre de usuario del jugador si no hay ninguna activa. Si no se conoce ninguno de los dos, recurre al nombre de jugador por defecto de la carta y, si tampoco hay, a "Player".
Macros de utilidad
| Macro | Qué hace |
|---|---|
{{// comment text}} | Comentario. Se expande a nada: te permite dejar notas en las entradas sin enviar nada a la IA |
{{trim}} | Elimina espacios en blanco circundantes. Para control preciso de formato cuando las macros dejan huecos extraños |
Recurso de Variable
Si un nombre de macro no coincide con ninguna macro incorporada, el motor comprueba si coincide con un ID de Variable. Si tienes una variable con el ID mood y su valor actual es "suspicious", {{mood}} se expande a "suspicious". Solo funciona con IDs hechos de letras sin acentos, números y guiones bajos: {{player_hp}} funciona, {{player-hp}} no. Las variables que añades en el lienzo reciben un ID aleatorio con guiones, así que antes de usarla como macro ponle a la variable un ID sencillo en Avanzado, dentro de sus ajustes.
Si no coincide ni con una macro incorporada ni con una Variable, el motor deja {{xxx}} tal cual. Sin errores, sin fallos.
Patrones que funcionan
Combate con daño proporcional
Define health (número, 0-100) con reglas de comportamiento que especifiquen rangos de daño por tipo de arma. La IA escribe narrativa y luego añade la directiva:
La daga del bandido te alcanza en las costillas: un corte
superficial, pero quema. Retrocedes tambaleándote, manteniendo la guardia alta.
[health: -8]
Balanceas tu espadón en un arco amplio. El bandido intenta
esquivarlo pero recibe la hoja en el hombro. Grita.
[enemy-hp: -22]El jugador ve una escena de combate. Los números se encargan de la contabilidad.
Progresión de relación con entradas condicionales
Empareja una Variable numérica (aria-trust, 0-100) con entradas que dependen de umbrales (Lore condicional en el lienzo). La IA actualiza la confianza mediante directivas y el sistema de entradas ajusta automáticamente lo que la IA sabe sobre el comportamiento del personaje en cada etapa:
- Entrada "Aria — Cautelosa" (condición:
aria-trust < 30): formal, mantiene la distancia - Entrada "Aria — Calentándose" (condición:
aria-trust >= 30 AND < 60): comparte opiniones, sonrisa ocasional - Entrada "Aria — Cercana" (condición:
aria-trust >= 60): vulnerable, protectora, bromas privadas
La IA usa directivas para mover el número: [aria-trust: +5] después de una interacción amable. (Con el Seguimiento preciso activado, quien lo mueve es el ayudante de seguimiento.) El sistema de entradas decide qué versión de Aria ve la IA. Ninguno de los dos sistemas conoce al otro: se comunican a través de la Variable.
Descripciones de escena dinámicas con macros
Una entrada que se adapta al contexto:
{{char}} alza la vista cuando {{user}} entra en la habitación. La hora actual
es {{time}}, y el clima afuera está {{random::clear::overcast::drizzling}}.
El humor de {{char}} parece {{mood}} hoy.Si el personaje es Luna, el jugador es Kai, son las 2pm y la Variable mood es "tense", la IA recibe:
Luna alza la vista cuando Kai entra en la habitación. La hora actual es 14:00,
y el clima afuera está overcast.
El humor de Luna parece tense hoy.Chequeos de habilidad basados en dados
Pon esto en una entrada de instrucción del narrador:
Cuando {{user}} intente algo arriesgado, usa el resultado del tirado
para determinar el éxito. Tirada: {{roll::1d20}}. 15+ = éxito,
10-14 = éxito parcial, menos de 10 = fracaso.La IA recibe un número real y puede narrar en consecuencia, así que el resultado lo deciden los dados y no el criterio de la IA.
Errores comunes
Directivas en el lugar equivocado. El motor ya le dice a la IA que ponga las directivas al final de su respuesta. Si aun así un modelo las escribe en medio del texto, el análisis sigue funcionando, pero cuesta más depurarlo.
Esperar que la IA haga matemáticas. La IA escribe [health: -15]. El motor hace la resta. No escribas reglas de comportamiento como "calcula el nuevo valor de salud": la IA solo necesita emitir la directiva correcta y el motor maneja la aritmética, incluido el ajuste min/max.
Errores de sintaxis JSON en directivas. Una llave sin pareja o una comilla faltante hace que el motor omita silenciosamente la directiva. Si una directiva merge o push no se está aplicando, comprueba que la carga útil JSON sea válida. El motor no falla: simplemente continúa.
Confundir {{random}} con {{pick}}. Si el color de ojos de un personaje cambia cada vez que se expande la entrada, usaste random cuando querías pick. Usa pick para atributos estables, random para variedad intencional.
Sobreingeniería con JSON Patch. A menos que necesites específicamente eliminar elementos de arrays, quédate con las directivas con corchetes. Son más simples, la IA las produce de manera más consistente y son más fáciles de depurar.
Olvidar que {{user}} sigue a las personas. Si un jugador cambia de persona, {{user}} cambia al nombre de la nueva persona. Esto suele ser lo que quieres, pero ten cuidado si estás usando {{user}} de una forma que no debería cambiar a mitad de sesión.
Consulta también
- Diseñando el estado del juego — eligiendo tipos de Variable y escribiendo reglas de comportamiento
- Cómo escribir buenas entradas — usando
{{macros}}dentro de entradas y diseño de entradas condicionales - Diseño de audio — la referencia completa de directivas de audio
Sintaxis de directivas y especificaciones de operaciones → Especificación del mundo: Variables