API: Documentación de Funciones

Roll20 hace disponibles una serie de funciones que no forman parte del núcleo de JavaScript o alguna otra biblioteca.


Variables globales

Variable Descripción
_ Este es el objeto de espacio de nombres para la biblioteca Underscore.js.
estado Las propiedades del objeto estado persistirán entre las sesiones de juego.

_ (Underscore)

Este es el objeto de espacio de nombres para la biblioteca Underscore.js. Underscore tiene muchas funciones para la manipulación de colecciones.


estado

Las propiedades del objeto estado persistirán entre sesiones de juego. El mismo objeto estado también se comparte entre todos los scripts de API en una campaña, por lo que se recomienda encarecidamente que al escribir valores en el estado, se minimice su huella tanto como sea posible para evitar colisiones de nombres. Nota: el estado se serializa con JSON, por lo que no se pueden almacenar funciones u objetos con referencias cíclicas.


Funciones Globales

Tipo de retorno Función Descripción
Objeto Roll20 Campaña Obtiene el objeto Roll20 de la campaña única.
Objecto Roll20 crearObj Crea un nuevo objeto Roll20.
Array de objetos Roll20 de  filtrarObjs Obtiene todos los objetos Roll20 que pasan una prueba de predicado.
Array de objetos Roll20 de  buscarObjs Obtiene todos los objetos Roll20 con propiedades que coinciden con un conjunto dado de atributos.
Array de objetos Roll20 de  obtenerTodosObjs Obtiene todos los objetos Roll20 en la campaña.
varías getAttrByName Obtiene el valor actual o máximo de un objeto Roll20 de atributo.
objeto Roll20 getObj Obtiene un objeto Roll20 específico.
  u Registra un mensaje en la consola de la API.
  activado Registra un controlador de eventos.
  onSheetWorkerCompleted Registra un controlador de eventos único para ejecutarse después de que se complete una pila completa de Scripts de Trabajadores de Hojas.
Booleano playerIsGM Comprueba si un jugador actualmente tiene privilegios de GM.
  playJukeboxPlaylist Comienza a reproducir una lista de reproducción del jukebox.
Número randomInteger Genera un valor de entero aleatorio.
  sendChat Envía un mensaje de chat.
  sendPing Envía un ping similar a mantener presionado el botón izquierdo del ratón.
  spawnFx Genera un emisor de partículas.
  spawnFxBetweenPoints Genera un emisor de partículas que se mueve de un punto a otro.
  spawnFxWithDefinition Genera un emisor de partículas que no está representado por un objeto FX Roll20.
  stopJukeboxPlaylist Detiene todas las listas de reproducción del jukebox que se están reproduciendo en este momento.
  hacia atrás Mueve un objeto gráfico Roll20 debajo de todos los demás gráficos en la misma capa del tablero.
  hacia el frente Mueve un objeto gráfico Roll20 por encima de todos los demás gráficos en la misma capa del tablero.

Campaña

Parámetros

Sin parámetros

Devuelve

El objeto de campaña único de Roll20.

Ejemplos

var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('page', currentPageID);

createObj

Parámetros

TIPO(Cadena) El tipo de objeto de Roll20 a crear. Solo se pueden crear 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' y 'macro'.ATRIBUTOS(Objeto) Los valores iniciales que se utilizarán para las propiedades del objeto de Roll20.

Devuelve

El objeto de Roll20 que se creó.

Ejemplos

Al crear un objeto de Roll20 que tiene un objeto padre (por ejemplo, al crear un objeto de atributo de Roll20, que es un hijo de un objeto de personaje de Roll20), debes proporcionar el id del padre enattributes.

on('add:character', function(obj) {
    createObj('attribute', {
        name: 'Strength',
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Al crear un objeto de ruta en Roll20, debes proporcionar un valor para la propiedad de solo lectura_path. Esta es una excepción a la regla que impide establecer el valor de propiedades de solo lectura al crear objetos en Roll20.

createObj('path', {
    left: 7000,
    top: 140,
    width: 140,
    height: 140,
    layer: 'objects',
    path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

Al crear un objeto de documento en Roll20, no puedes establecer el texto o las notas del gm en el momento de la creación.

var handout = createObj('handout', {
    name: 'A Letter Addressed to You',
    inplayerjournals: 'all',
    archived: false
});
handout.set({
    notes: 'Notes can only be set after the handout is created',
    gmnotes: 'GM Notes can only be set after the handout is created'
});

filterObjs

Parámetros

CALLBACK(Function) Una función de predicado para probar todos los objetos de Roll20. La función de devolución de llamada recibe un objeto Roll20 como parámetro y debe devolver true (para objetos Roll20 que se incluirán en el valor de retorno de filterObjs) o false (para todos los demás objetos Roll20).

Devuelve

Una matriz de objetos Roll20 que pasaron la prueba del predicado.

Ejemplos

var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));
    });

findObjs

Parámetros

ATTRIBUTES(Object) Una colección de pares clave:valor para que coincida con objetos Roll20 en la campaña. OPTIONS(Object, opcional) Si options.caseInsensitive es true, las comparaciones de cadenas entre objetos Roll20 y atributos serán insensibles a mayúsculas y minúsculas.

Devuelve

Un array de objetos Roll20 con propiedades que coinciden conatributos.

Ejemplos

var npcs = findObjs({ type: 'character', controlledby: '' });

getAllObjs

Parámetros

Sin parámetros

Devuelve

Un array de todos los objetos Roll20 en la campaña.

Ejemplos

var everything = getAllObjs();

getAttrByName

Parámetros

CHARACTER_ID(String) El ID del objeto Roll20 de personaje que es el padre del objeto Roll20 de atributo del cual quieres obtener el valor.ATTRIBUTE_NAME(String) El nombre del objeto Roll20 de atributo del cual quieres obtener el valor.VALUE_TYPE(String, opcional) Ya sea "actual" o "máximo" (por defecto es "actual" si se omite).

Regresa

La propiedadactualomaxdel atributo apropiado. Si la propiedad deseada no está configurada, se utilizará en su lugar el valor predeterminado especificado por la hoja de personaje (si hay una configuración predeterminada).

Ejemplos

var character = getMyCharacter(),
    strength = getAttrByName(character.id, 'strength'),
    strength_max = getAttrByName(character.id, 'strength', 'max');

getObj

Parámetros

TIPO(String) El tipo de objeto Roll20 para obtener.ID(String) El ID único del objeto Roll20 para obtener.

Regresa

El objeto Roll20 especificado.

Ejemplos

on('chat:mensaje', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

registro

Parámetros

MENSAJE(varía) El mensaje que se enviará a la consola de la API. El parámetro del mensaje se transformará en un String con JSON.stringify.

Devuelve

(Vacío)

Ejemplos

on('chat:mensaje', function(msg) {
    log('Mensaje recibido de:');
    log(getObj('jugador', msg.playerid));
});
"Mensaje recibido de:"
{"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"player","_lastpage":""}

activado

Parámetros

EVENTO(String) Hay cinco tipos de eventos: ready, change, add, destroy, chatA excepción de ready, todos los tipos de eventos también deben ir acompañados de un tipo de objeto. Para chat, esto es siempre mensaje. Para todo lo demás, esto es la propiedad tipo de un objeto Roll20. Además del tipo de objeto, los eventos de cambio también pueden especificar opcionalmente una propiedad del objeto Roll20 especificado.Las partes 2-3 del evento (tipo, objeto y opcionalmente propiedad) están separadas por dos puntos. Por lo tanto, las cadenas de evento válidas incluyen pero no se limitan a "ready", "chat:mensaje", "change:gráfico", "change:campaña:playerpageid", "add:personaje" y "destroy:handout".LLAMADA(Función) La función que se llamará cuando se active el evento especificado. Los parámetros pasados dependen del tipo de evento: los eventos ready no tienen parámetros de devolución de llamada, los eventos change tienen un parámetro obj, que es una referencia al objeto Roll20 tal como existe después del cambio, y un parámetro prev, que es un objeto JavaScript simple con propiedades que coinciden con el objeto Roll20 antes del evento de cambio, los eventos add tienen un parámetro obj, que es una referencia al nuevo objeto Roll20, los eventos destroy tienen un parámetro obj, que es una referencia al objeto Roll20 que ya no existe, los eventos chat tienen un parámetro msg, que contiene los detalles del mensaje que se envió al chat.

Retorna

(Void)

Ejemplos

Los eventos se disparan en el orden en que se registraron y de más específico a menos específico. En este ejemplo, un cambio en la propiedadleftde un objeto Roll20 gráfico hará que se llame afunction3, seguida defunction1y luegofunction2.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

addlos eventos intentarán dispararse para los objetos Roll20 que ya estén en la campaña cuando se inicie una nueva sesión. Para evitar este comportamiento, puedes esperar a registrar tuañadirevento hasta que ocurra el eventolisto.

on('add:graphic', function(obj) {
    // Cuando comienza la sesión, esta función se llamará para cada gráfico en la campaña
    // Esta función también se llamará cada vez que se crea un nuevo objeto gráfico de Roll20
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // Esta función se llamará *solo* cuando se crea un nuevo objeto gráfico de Roll20, no para los que ya existen
    });
});

El parámetropre para eventoschange no es un objeto de Roll20, es un objeto de JavaScript antiguo. Como tal, no puedes usar las funcionesget oset, y no puedes omitir los guiones bajos iniciales en las propiedades de solo lectura.

en('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // todos son equivalentes
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id,        // no definido
        id5 = prev.get('id'), // undefined no es una función
        id6 = prev._id;       // correcto

    // ambos son equivalentes
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined no es una función
    prev.set({            // undefined no es una función
        left: 70
    });
    prev.left = 70;       // correcto, aunque no cambiará nada en el juego de mesa
});

Para los campos asíncronos de los objetos personaje y anotación de Roll20 (notasnotasgm, y biografía), el parámetro prev no contendrá los datos que necesitas. (En su lugar, tendrá un identificador numérico utilizado por el sistema.) Si necesitas acceder al valor anterior de uno de estos campos, tendrás que llevar un registro de ello tú mismo:

on('ready', function() {
    if (!state.example) state.example = { bioCache: {} };
});

on('change:character:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text;

        // do stuff...

        if (shouldRevertBio()) {
            obj.set('bio', state.example.bioCache[obj.id]);
        }
    });
});

onSheetWorkerCompleted

Parameters

CALLBACK(Function) The function that will be called when the current 'stack' of Sheet Worker Scripts completes.

Returns

(Void)

Examples

This function is intended to be called prior to setWithWorker. Thecallbackfunction will be called only once.

var myCharacter = ...,
    mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0];

onSheetWorkerCompleted(function() {
    var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // do something with calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

 


playerIsGM

Parámetros

PLAYER_ID(String) El id del objeto Roll20 del jugador para verificar.

Devuelve

true si el jugador actualmente tiene permisos de GM, o false de lo contrario.

Ejemplos

Esta función es especialmente útil para limitar los comandos de API al uso de GM.

on('chat:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...
    }
});

playJukeboxPlaylist

Parámetros

PLAYLIST_ID(String) El id de la lista de reproducción que se va a empezar a reproducir.

Devuelve

(Vacío)

Ejemplos

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);

randomInteger

Parámetros

MAX(Número) El número máximo a devolver, inclusive.

Retorna

Un número entero aleatorio entre 1 (inclusive) y max (inclusive). Esta función tiene una mejor distribución que Math.random(), y se recomienda utilizarla en su lugar. Esta función no utiliza la función Quantum Roll de de la misma manera que el motor de dados, pero utiliza el mismo algoritmo seudorandom que el motor de dados utilizará como último recurso si Quantum Roll no está disponible.

Ejemplos

Dado que esta función devuelve un número entero de 1 amáx, es ideal para generar rápidamente el resultado de una tirada de dados si no necesita toda la potencia del motor de dadosde Roll20.

var d20Result = randomInteger(20); // aproximadamente equivalente a lanzar un dado de 20 caras

sendChat Asíncrono

Parámetros

SPEAKINGAS(String) El nombre que se adjuntará al mensaje enviado. Si speakingAs está en formato player|player_id o character|character_id, el mensaje se enviará como ese jugador o personaje. De lo contrario, el mensaje usará el nombre proporcionado como si un DJ hubiera utilizado el comando /as.MENSAJE(String) El mensaje que se enviará al chat.CALLBACK(Function, opcional) Si se especifica callback, el resultado del mensaje de chat se pasará a él en lugar de aparecer en el chat. El parámetro del método de callback es una matriz de objetos de mensajes.OPTIONS(Object, opcional) Si options.noarchive es verdadero, el mensaje no se agregará al archivo de chat. Si options.use3d es verdadero, los lanzamientos de dados en el mensaje utilizarán la función de dados 3D. Las opciones no son aplicables si se especifica la devolución de llamada.

Devuelve

(Vacío)

Ejemplos

sendChat('Ejemplo', 'Este es un ejemplo simple.');

Puedes escribir fácilmente código para enviar un mensaje como el mismo jugador o personaje que activó un evento de chat.

on('chat:message', function(msg) {
    var character = findObjs({ type: 'character', name: msg.who })[0],
        player = getObj('player', msg.playerid),
        message = ' dijo algo';

    if (character) sendChat('character|'+character.id, character.get('name')+message);
    else sendChat('player|'+player.id, player.get('displayname')+message);
});

El parámetrocallbackes útil si necesita aprovechar el motor de dadosde Roll20. No es especialmente necesario un valorspeakingAscuando se utiliza la llamada de retorno, ya que el mensaje no aparecerá en el chat de todos modos.

sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});

options.noarchiveestá diseñado principalmente para enviar a los jugadores menús hechos con botones de comando de la APIsin atascar su historial de chat.

sendChat('System', '[Borrar cambios](!clear)\n[Añadir ficha](!add)\n[Ver muestra](!view)\n[Guardar diseño](!save)', null, { noarchive: true });

sendPing

Parámetros

IZQUIERDA(número) La coordenada x donde colocar la marca.ARRIBA(número) La coordenada y donde colocar la marca.PAGE_ID(cadena) El ID del objeto Roll20 de la página en la que colocar la marca.PLAYER_ID(cadena, opcional) La marca usará el color del jugador especificado. Si se omite player_id, la marca será amarilla.MOVEALL(booleano, opcional) Si moveAll es true, las vistas de todos los jugadores en la página correspondiente se centrarán en la marca.

Nota:En este momento, solo los GM tendrán sus vistas centradas si moveAlles true. Este comportamiento está documentadoaquí

Devuelve

(Vacío)

Ejemplos

on('chat:mensaje', function(msg) {
    var obj;
    if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) {
        if (!msg.selected) return;
        obj = getObj(msg.selected[0]._type, msg.selected[0]._id);
        sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true); // centre a todos en el token seleccionado
    }
});

spawnFx

Parámetros

IZQUIERDA(Número) La coordenada x para colocar el emisor de partículas.ARRIBA(Número) La coordenada y para colocar el emisor de partículas.TIPO(Cadena) El tipo de emisor de partículas a colocar. Para los efectos incorporados, debe ser "tipo-color", donde tipo es uno de bomba, burbujeo, quemadura, estallido, explosión, resplandor, misil o nova y color es uno de ácido, sangre, encanto, muerte, fuego, escarcha, sagrado, magia, limo, humo o agua. Para efectos personalizados, esto debería ser el id del objeto FX de Roll20. Nota: los tipos de haz, aliento y salpicadura no se pueden usar con spawnFx. Ver spawnFxBetweenPoints en su lugar. PAGE_ID(String, opcional) El id del objeto de página de Roll20 en el que colocar el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.

Regresa

(Void)

Ejemplos

spawnFx(1400, 1400, 'bubbling-acid');

spawnFxBetweenPoints

Parámetros

START(Object) El punto de inicio para el emisor de partículas. El punto debe estar en el formato { x: número, y: número }. END(Object) El punto final para el emisor de partículas. El punto debe estar en el formato { x: número, y: número }. TYPE(String) El tipo de emisor de partículas que se va a colocar. Para efectos incorporados, esto debería ser "tipo-color", donde el tipo es uno de rayo, bomba, aliento, burbujeante, quemar, explosión, resplandor, misil, nova o salpicadura, y el color es uno de ácido, sangre, encanto, muerte, fuego, escarcha, sagrado, mágico, limo, humo o agua. Para efectos personalizados, esto debería ser el id del objeto FX Roll20 de la página. PAGE_ID (String, opcional) El id del objeto de la página Roll20 para colocar el emisor de partículas. Si se omite, se usará Campaign().get('playerpageid') en su lugar.

Devuelve

(Void)

Ejemplos

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

spawnFxWithDefinition

Parámetros

LEFT(Number) La coordenada x para colocar el emisor de partículas. TOP(Number) La coordenada y para colocar el emisor de partículas. DEFINITION(Object) Las características del emisor de partículas para colocar. Consulte Custom FX para obtener una lista de propiedades posibles y las propiedades de los tipos y colores de emisores de partículas predeterminados. Mira la biblioteca de efectos FX para algunos efectos personalizados que los usuarios de Roll20 han creado. PAGE_ID (String, opcional) El id de la página Roll20 en la que se colocará el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.

Devuelve

(Void)

Ejemplos

// estos dos son equivalentes
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxWithDefinition(1400, 1400, {
    maxParticles: 200,
    tamaño: 15,
    sizeRandom: 3,
    lifeSpan: 20,
    lifeSpanRandom: 5,
    speed: 7,
    speedRandom: 2,
    gravity: { x: 0.01, y: 0.65 },
    angle: 270,
    angleRandom: 35,
    emissionRate: 1,
    startColour: [0, 35, 10, 1],
    startColourRandom: [0, 10, 10, 0,25],
    endColour: [0, 75, 30, 0],
    endColourRandom:   [0, 20, 20, 0]
});

stopJukeboxPlaylist

Parámetros

Sin parámetros

Devuelve

(Vacío)

Ejemplos

stopJukeboxPlaylist();

toBack

Parámetros

OBJ(OBJETO Roll20) El objeto Roll20 para enviar al fondo de su capa.

Devuelve

(Vacío)

Ejemplos

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg.selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});

toFront

Parametros

OBJ(objeto de Roll20) El objeto Roll20 para llevar al frente de su capa.

Devuelve

(Vacío)

Ejemplos

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});
 
¿Fue útil este artículo?
Usuarios a los que les pareció útil: 6 de 11