Macros de código: la API
Qué puede leer una macro de código, qué funciones tiene y todas las acciones que puede pedir, con sus argumentos.
Una macro de código es un trozo de JavaScript que no toca el mundo: lee datos de la mesa y devuelve una lista de acciones, las mismas que usan los pasos del modo fácil y las zonas de evento. Quien las ejecuta es el motor de siempre, con tus permisos, igual que si las hubieras pulsado a mano. Esta página es la referencia de lo que el código puede leer y de las acciones que puede pedir; sale del propio motor. Cómo se crea una macro está en Creador de macros y cómo se usa en la mesa en Macros en la mesa.
Cómo se ejecuta
El código corre en un entorno aislado, sin acceso al navegador, a la red, a temporizadores ni a datos de otras personas. Tirar dados se hace con el motor de la casa: cuando el script pide una tirada, la mesa la resuelve y el script se vuelve a ejecutar desde el principio con ese resultado, así que dentro no hay reloj ni azar propios. Por eso hay topes:
- Como mucho 24 tiradas distintas por macro (cada una cuesta una pasada).
- Como mucho 60 acciones devueltas; el resto se descarta y el registro lo dice.
- Un tope de tiempo por pasada; si se supera, la macro se detiene y avisa.
- Lo que no esté en el catálogo de acciones se descarta y se nombra en el aviso.
Funciones
Las que siempre existen dentro del código:
| Función | Qué hace |
|---|---|
dados('2d6+3') | Tira esa expresión con el motor de la casa y devuelve { total, detalle, formula }. No publica nada en el chat; para eso, la acción tirar. |
azar() | Un número de 0 a 1 del mismo origen (Math.random es lo mismo). |
hacer(tipo, argumentos) | Pide una acción por su nombre. Cada acción del catálogo tiene además su atajo con ese mismo nombre: mensaje({ texto: 'Hola' }). |
ficha.get('atributos.dex') | Lee un valor de la ficha por ruta, sin tildes ni mayúsculas. Si no existe devuelve undefined y lo anota en el registro; nunca inventa un valor. |
ficha.tiene(ruta) | Dice si la ficha tiene ese dato. |
inventario() | El inventario de la ficha: { id, nombre, cantidad, peso, peso_total, equipado, categoria }. |
cuantos('Poción') | Cuántas unidades lleva de un objeto, por nombre. |
dinero() · dinero('oro') | Todo el dinero, o el de una moneda. |
console.log(...) | Escribe en el registro de la macro (hasta 100 líneas). |
Datos que puede leer
Variables de solo lectura; cambiarlas no cambia nada fuera de la macro.
| Variable | Qué trae |
|---|---|
yo | Quien lanza la macro. |
token | Su token en el mapa. |
tokens | Los tokens de la escena. |
objetivo | El objetivo marcado. |
ficha | La ficha de quien lanza. |
campana | Datos de la campaña. |
escena | La escena en curso. |
combate | El combate, si lo hay. |
muros | Los muros y puertas. |
luces | Las luces. |
zonas | Las zonas de evento. |
jugadores | Quién está en la mesa. |
Acciones que puede pedir
Cada fila es un nombre que se usa como función (dano({ formula: '2d6' })) o con hacer('dano', ...). La tercera columna da los nombres de sus argumentos. Las que no aparecen aquí se escriben solo a mano en una macro de texto.
La mesa
| Nombre | Qué hace | Argumentos |
|---|---|---|
mensaje | decir algo en el chat | texto |
tirar | tirar dados | formula, etiqueta, detalle |
fx | lanzar un efecto visual | efecto, escala, permanente |
pausar | pausar la partida (aviso a la mesa) | texto |
texto_flotante | texto flotante sobre el mapa | texto |
sonar | sonar un efecto | url |
musica | cambiar la lista de música | lista |
experiencia | lanzar una experiencia a la mesa | biblioteca, url, titulo |
momento | lanzar un momento de la escena | momento |
presentar_app | presentar un puzzle (y esperar) | app_id |
mostrar_entrada | enseñar una entrada del Mundo a la mesa | entrada |
revelar_contenedor | revelar un contenedor (botín) a la mesa | contenedor |
mostrar_escena | mostrar una escena (imagen o vídeo) | url, titulo, bucle, modo |
reproducir_pista | reproducir una pista de música | lista, pista |
poner_escena | poner una escena en vivo | escena |
cartas | mover cartas de una baraja | baraja, accion, cantidad |
carta_jugar | jugar una carta de mi mano | baraja, carta |
carta_descartar | descartar cartas de mi mano | baraja, carta, cantidad |
carta_zona | llevar una carta de mi mano a una zona | baraja, carta, zona |
carta_girar | girar o enderezar cartas de la mesa | baraja, carta, modo |
carta_mostrar | enseñar una carta de mi mano a la mesa | baraja, carta |
carta_dar | dar una carta a otro jugador | baraja, carta |
tirada_cartas | hacer una tirada de cartas | baraja, cantidad, de, agregacion, despues, etiqueta |
carta_receta | hacer una receta de la baraja | baraja, receta |
El mapa
| Nombre | Qué hace | Argumentos |
|---|---|---|
abrir_puerta | abrir una puerta | muro |
cerrar_puerta | cerrar una puerta | muro |
cerrar_con_llave | cerrar una puerta con llave | muro |
animacion | encender o apagar una animación del mapa | prop, accion |
cambiar_planta | cambiar de planta | planta |
oscuridad | cambiar la oscuridad de la escena | nivel |
clima | cambiar el clima de la escena | clima, intensidad |
pantalla | efecto de pantalla (destello, temblor, fundido, viñeta…) | efecto, fuerza, segundos, color |
luz | encender o apagar una luz | luz, intensidad |
ocultar_token | ocultar un token | — |
mostrar_token | mostrar un token | — |
mover_token | mover un token a una casilla | x, y |
cambiar_fondo | cambiar el fondo del mapa | url |
cambiar_mapa | llevar a la mesa a otro mapa | mapa |
mover_camara | traer la vista de todos a un punto | donde, x, y |
crear_token | crear un token | nombre, clase, x, y, cantidad, pv, ca, tamano |
borrar_token | quitar un token del mapa | — |
actualizar_token | cambiar datos de un token | nombre, pv, pv_max, ca, tamano, visible, rotacion |
crear_muro | crear un muro o una puerta | x1, y1, x2, y2, puerta |
actualizar_muro | cambiar un muro o una puerta | muro, puerta, color, grosor |
borrar_muro | quitar un muro o una puerta | muro |
crear_luz | crear una luz | x, y, radio, intensidad, color |
actualizar_luz | cambiar una luz | luz, radio, intensidad, color |
borrar_luz | quitar una luz | luz |
niebla | revelar u ocultar niebla | modo, x, y, radio, ancho, alto |
capa_visible | mostrar u ocultar una capa en mi vista | capa, visible |
centrar_token | centrar mi vista en una criatura | token_id |
Combate y ficha
| Nombre | Qué hace | Argumentos |
|---|---|---|
usar_accion | usar una acción tuya | accion |
dano | hacer daño | formula, tipo_dano, efecto |
curar | curar | formula, efecto |
condicion | aplicar una condición | condicion |
quitar_condicion | quitar una condición | condicion |
empezar_combate | empezar el combate | grupo, modo |
pedir_tirada | pedir una tirada | texto, salvacion, cd, formula, tipo_dano |
ficha_poner | poner un valor en la ficha | campo, valor |
ficha_sumar | sumar (o restar) a un valor de la ficha | campo, valor |
inventario_dar | dar un objeto | nombre, cantidad, peso, limite_peso |
inventario_quitar | quitar un objeto | nombre, cantidad |
dinero_sumar | sumar (o restar) dinero | cantidad, moneda |
esperar_turno | esperar un turno (y seguir) | hasta, ronda |
siguiente_turno | pasar al siguiente turno | sentido |
anadir_a_combate | meter en el combate | — |
quitar_de_combate | sacar del combate | — |
Control del guion
| Nombre | Qué hace | Argumentos |
|---|---|---|
armar_zona | armar otra zona | zona |
desarmar_zona | desarmar otra zona | zona |
revelar_zona | revelar una zona a la mesa | zona |
disparar_zona | disparar otra zona | zona |
ejecutar_macro | ejecutar una macro | macro |
si | si se cumple… (y si no…) | cond, entonces, sino |
repetir | repetir varias veces | veces, acciones |
esperar | esperar un rato | segundos |
esperar_evento | esperar a que pase algo | evento, si, segundos, si_no_llega |
var_poner | guardar una variable | nombre, alcance, modo, valor |
preguntar | preguntar a alguien | pregunta, forma, opciones, campos, elegir_min, elegir_max, min, max, clave, destino, segundos, si_no_responde |
Un ejemplo
Tirar un ataque y, si impacta, hacer daño:
var ataque = dados('1d20+5');
mensaje({ texto: 'Ataque: ' + ataque.total });
if (ataque.total >= 15) {
dano({ formula: '1d8+3', tipo_dano: 'cortante' });
}Problemas frecuentes
«Esta macro pide más de 24 tiradas.» Reparte las tiradas en varias macros o usa una sola expresión de dados (4d6kh3).
«La ficha no tiene…» La ruta no existe en tu sistema; mira el registro de la macro y los nombres reales de los campos.
«Una acción se descarta.» Su nombre no está en el catálogo; el aviso la nombra.
Véase también
Creador de macros, Macros en la mesa, Zonas de evento: que el mapa haga cosas solo, Comandos del chat y dados, Fórmulas y funciones.