Code macros: the API

What a code macro can read, which functions it has and every action it can ask for, with its arguments.

A code macro is a piece of JavaScript that does not touch the world: it reads table data and returns a list of actions, the same ones used by the steps of easy mode and by event zones. The usual engine runs them, with your permissions, exactly as if you had pressed them by hand. This page is the reference for what the code can read and the actions it can ask for; it comes from the engine itself. How to create a macro is in Macro builder and how it is used at the table in Macros at the table.

How it runs

The code runs in an isolated environment, with no access to the browser, the network, timers or other people's data. Dice are rolled by the house engine: when the script asks for a roll, the table resolves it and the script runs again from the start with that result, so there is no clock or randomness of its own inside. That is why there are caps:

At most 24 distinct rolls per macro (each one costs a pass).
At most 60 actions returned; the rest are dropped and the log says so.
A time cap per pass; if it is exceeded, the macro stops and warns.
Anything not in the action catalog is dropped and named in the warning.

Functions

The ones that always exist inside the code:

Function	What it does
`dados('2d6+3')`	Rolls that expression with the house engine and returns `{ total, detalle, formula }`. It posts nothing to the chat; for that, use the `tirar` action.
`azar()`	A number from 0 to 1 from the same source (`Math.random` is the same thing).
`hacer(tipo, arguments)`	Asks for an action by name. Every catalog action also has a shortcut with that same name: `mensaje({ texto: 'Hello' })`.
`ficha.get('atributos.dex')`	Reads a sheet value by path, ignoring accents and case. If it does not exist it returns `undefined` and notes it in the log; it never makes a value up.
`ficha.tiene(path)`	Tells whether the sheet has that datum.
`inventario()`	The sheet inventory: `{ id, nombre, cantidad, peso, peso_total, equipado, categoria }`.
`cuantos('Potion')`	How many units of an item are carried, by name.
`dinero()` · `dinero('gold')`	All the money, or one currency.
`console.log(...)`	Writes to the macro log (up to 100 lines).

Data it can read

Read-only variables; changing them changes nothing outside the macro.

Variable	What it holds
`yo`	Whoever launches the macro.
`token`	Their token on the map.
`tokens`	The tokens of the scene.
`objetivo`	The marked target.
`ficha`	The sheet of whoever launches it.
`campana`	Campaign data.
`escena`	The current scene.
`combate`	The combat, if there is one.
`muros`	Walls and doors.
`luces`	Lights.
`zonas`	Event zones.
`jugadores`	Who is at the table.

Actions it can ask for

Each row is a name used as a function (dano({ formula: '2d6' })) or with hacer('dano', ...). The third column gives the argument names. The ones not listed here are only written by hand in a text macro.

The table

Name	What it does	Arguments
`mensaje`	say something in the chat	`texto`
`tirar`	roll dice	`formula`, `etiqueta`, `detalle`
`fx`	play a visual effect	`efecto`, `escala`, `permanente`
`pausar`	pause the game (notice to the table)	`texto`
`texto_flotante`	floating text over the map	`texto`
`sonar`	play a sound effect	`url`
`musica`	change the music list	`lista`
`experiencia`	launch an experience to the table	`biblioteca`, `url`, `titulo`
`momento`	launch a scene moment	`momento`
`presentar_app`	present a puzzle (and wait)	`app_id`
`mostrar_entrada`	show a World entry to the table	`entrada`
`revelar_contenedor`	reveal a container (loot) to the table	`contenedor`
`mostrar_escena`	show a scene (image or video)	`url`, `titulo`, `bucle`, `modo`
`reproducir_pista`	play a music track	`lista`, `pista`
`poner_escena`	put a scene live	`escena`
`cartas`	move cards from a deck	`baraja`, `accion`, `cantidad`
`carta_jugar`	play a card from my hand	`baraja`, `carta`
`carta_descartar`	discard cards from my hand	`baraja`, `carta`, `cantidad`
`carta_zona`	take a card from my hand to a zone	`baraja`, `carta`, `zona`
`carta_girar`	turn or straighten table cards	`baraja`, `carta`, `modo`
`carta_mostrar`	show a card from my hand to the table	`baraja`, `carta`
`carta_dar`	give a card to another player	`baraja`, `carta`
`tirada_cartas`	roll with cards	`baraja`, `cantidad`, `de`, `agregacion`, `despues`, `etiqueta`
`carta_receta`	card recipe	`baraja`, `receta`

The map

Name	What it does	Arguments
`abrir_puerta`	open a door	`muro`
`cerrar_puerta`	close a door	`muro`
`cerrar_con_llave`	lock a door	`muro`
`animacion`	turn a map animation on or off	`prop`, `accion`
`cambiar_planta`	change floor	`planta`
`oscuridad`	change the scene darkness	`nivel`
`clima`	change the scene weather	`clima`, `intensidad`
`pantalla`	screen effect (flash, shake, fade, vignette...)	`efecto`, `fuerza`, `segundos`, `color`
`luz`	turn a light on or off	`luz`, `intensidad`
`ocultar_token`	hide a token	—
`mostrar_token`	show a token	—
`mover_token`	move a token to a square	`x`, `y`
`cambiar_fondo`	change the map background	`url`
`cambiar_mapa`	take the table to another map	`mapa`
`mover_camara`	bring everyone's view to a point	`donde`, `x`, `y`
`crear_token`	create a token	`nombre`, `clase`, `x`, `y`, `cantidad`, `pv`, `ca`, `tamano`
`borrar_token`	remove a token from the map	—
`actualizar_token`	change token data	`nombre`, `pv`, `pv_max`, `ca`, `tamano`, `visible`, `rotacion`
`crear_muro`	create a wall or door	`x1`, `y1`, `x2`, `y2`, `puerta`
`actualizar_muro`	change a wall or door	`muro`, `puerta`, `color`, `grosor`
`borrar_muro`	remove a wall or door	`muro`
`crear_luz`	create a light	`x`, `y`, `radio`, `intensidad`, `color`
`actualizar_luz`	change a light	`luz`, `radio`, `intensidad`, `color`
`borrar_luz`	remove a light	`luz`
`niebla`	reveal or hide fog	`modo`, `x`, `y`, `radio`, `ancho`, `alto`
`capa_visible`	show or hide a layer in my view	`capa`, `visible`
`centrar_token`	center my view on a creature	`token_id`

Combat and sheet

Name	What it does	Arguments
`usar_accion`	use one of your actions	`accion`
`dano`	deal damage	`formula`, `tipo_dano`, `efecto`
`curar`	heal	`formula`, `efecto`
`condicion`	apply a condition	`condicion`
`quitar_condicion`	remove a condition	`condicion`
`empezar_combate`	start combat	`grupo`, `modo`
`pedir_tirada`	ask for a roll	`texto`, `salvacion`, `cd`, `formula`, `tipo_dano`
`ficha_poner`	set a value on the sheet	`campo`, `valor`
`ficha_sumar`	add to (or subtract from) a sheet value	`campo`, `valor`
`inventario_dar`	give an item	`nombre`, `cantidad`, `peso`, `limite_peso`
`inventario_quitar`	take an item away	`nombre`, `cantidad`
`dinero_sumar`	add (or subtract) money	`cantidad`, `moneda`
`esperar_turno`	wait for a turn (and go on)	`hasta`, `ronda`
`siguiente_turno`	move to the next turn	`sentido`
`anadir_a_combate`	add to combat	—
`quitar_de_combate`	take out of combat	—

Script control

Name	What it does	Arguments
`armar_zona`	arm another zone	`zona`
`desarmar_zona`	disarm another zone	`zona`
`revelar_zona`	reveal a zone to the table	`zona`
`disparar_zona`	trigger another zone	`zona`
`ejecutar_macro`	run a macro	`macro`
`si`	if... (and otherwise...)	`cond`, `entonces`, `sino`
`repetir`	repeat several times	`veces`, `acciones`
`esperar`	wait a while	`segundos`
`esperar_evento`	wait for something to happen	`evento`, `si`, `segundos`, `si_no_llega`
`var_poner`	store a variable	`nombre`, `alcance`, `modo`, `valor`
`preguntar`	ask someone	`pregunta`, `forma`, `opciones`, `campos`, `elegir_min`, `elegir_max`, `min`, `max`, `clave`, `destino`, `segundos`, `si_no_responde`

An example

Roll an attack and, on a hit, deal damage:

var ataque = dados('1d20+5');
mensaje({ texto: 'Attack: ' + ataque.total });
if (ataque.total >= 15) {
  dano({ formula: '1d8+3', tipo_dano: 'slashing' });
}

Common problems

"This macro asks for more than 24 rolls." Split the rolls across several macros or use a single dice expression (4d6kh3).

"The sheet has no..." The path does not exist in your system; check the macro log and the real field names.

"An action is dropped." Its name is not in the catalog; the warning names it.