API: Documentación de funciones

Variables globales

_ (Guión bajo)

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

estado

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

Funciones globales

Campaña

Parámetros

Sin parámetros

Devoluciones

El objeto Roll20 de campaña única.

Ejemplos

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

crearObj

Parámetros

TYPE(String) El tipo de objeto Roll20 que se va a crear. Solo se pueden crear «gráfico», «texto», «ruta», «carácter», «habilidad», «atributo», «folleto», «tabla desplegable», «elemento de tabla» y «macro». ATTRIBUTOS (objeto) Los valores iniciales que se utilizarán para las propiedades del objeto Roll20.

Devoluciones

El objeto Roll20 que se ha creado.

Ejemplos

Al crear un objeto Roll20 que tiene un objeto padre (como crear un objeto Roll20 de atributo, que es un objeto hijo de un objeto Roll20 de personaje), debe proporcionar el identificador del objeto padre enlos atributos.

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

Al crear un objeto Roll20 de ruta, debe proporcionar un valor para la propiedad de solo lectura_path. Esta es una excepción a la regla que impide establecer el valor de las propiedades de solo lectura al crear objetos 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 Roll20 para repartir, no puede establecer el texto ni 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'
});

filtrarObj

Parámetros

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

Devoluciones

Una matriz de objetos Roll20 que han superado 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 (objeto) Una colección de pares clave:valor para emparejar con objetos Roll20 en la campaña. OPTIONS (objeto, opcional) Si options.caseInsensitive es verdadero, las comparaciones de cadenas entre objetos Roll20 y atributos no distinguirán entre mayúsculas y minúsculas.

Devoluciones

Una matriz de objetos Roll20 con propiedades que coinciden conlos atributos.

Ejemplos

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

obtenerTodosLosObjetos

Parámetros

Sin parámetros

Devoluciones

Una matriz de todos los objetos Roll20 de la campaña.

Ejemplos

var todo = getAllObjs();

obtenerAtributoPorNombre

Parámetros

CHARACTER_ID (cadena) El identificador del objeto Roll20 del personaje que es el padre del objeto Roll20 del atributo cuyo valor desea obtener. ATTRIBUTE_NAME(cadena) El nombre del objeto Roll20 del atributo cuyo valor desea obtener. VALUE_TYPE(cadena, opcional) «current» o «max» (el valor predeterminado es «current» si se omite).

Devoluciones

La propiedadactualomáximadel atributo correspondiente. Si no se establece la propiedad deseada, se utilizará el valor predeterminado especificado en la hoja de personajes (si existe uno).

Ejemplos

var personaje = getMyCharacter(),
    fuerza = getAttrByName(personaje.id, 'fuerza'),
    fuerza_máx = getAttrByName(personaje.id, 'fuerza', 'máx');

getObj

Parámetros

TYPE(String) El tipo de objeto Roll20 que se desea obtener. ID(String) El identificador único del objeto Roll20 que se desea obtener.

Devoluciones

El objeto Roll20 especificado.

Ejemplos

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

registro

Parámetros

MESSAGE (varía) El mensaje que se publicará en la consola Mod (API). El parámetro del mensaje se transformará en una cadena con JSON.stringify.

Devoluciones

(Nulo)

Ejemplos

on('chat:message', function(msg) {
    log('Mensaje recibido de:');
    log(getObj('player', 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":""}

en

Parámetros

EVENT(Cadena) Hay cinco tipos de eventos: ready, change, add, destroy y chat. A excepción de ready, todos los tipos de eventos deben ir acompañados de un tipo de objeto. En el chat, siempre se trata de mensajes. Para todo lo demás, esta es la propiedad de tipo de un objeto Roll20. Además del tipo de objeto, changeevents también puede especificar opcionalmente una propiedad del objeto Roll20 especificado que se va a supervisar. Las dos o tres partes del evento (tipo, objeto y, opcionalmente, propiedad) se separan con dos puntos. Por lo tanto, las cadenas de eventos válidas incluyen, entre otras, «ready», «chat:message», «change:graphic», «change:campaign:playerpageid», «add:character» y «destroy:handout». CALLBACK(Función) La función que se invocará 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 y como existe después del cambio, y un parámetro prev, que es un objeto JavaScript antiguo 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.

Devoluciones

(Nulo)

Ejemplos

Los eventos se activan en el orden en que se registraron, y de más específico a menos específico. En este ejemplo, un cambio en la propiedadizquierdade un objeto gráfico Roll20 dará lugar a que se llame ala función3, seguida dela función1y luego dela función2.

on('change:graphic', función1);
on('change:graphic', función2);
on('change:graphic:left', función3);

La función «addevents» intentará activarse para los objetos Roll20 que ya se encuentran en la campaña cuando comience una nueva sesión. Para evitar este comportamiento, puede esperar a registrar su eventoaddhasta que se active el eventoready.

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

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

El parámetroprepara los eventosde cambiono es un objeto Roll20, sino un objeto JavaScript antiguo. Por lo tanto, no puede utilizar las funcionesgetoset, ni omitir los guiones bajos iniciales en las propiedades de solo lectura.

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

        id4 = prev.id,        // indefinido
        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 la mesa
});

Para los campos asíncronos de los objetos Roll20 de personajes y folletos (notas,notas del GM ybiografía), el parámetroprevno contendrá los datos que necesita. (En su lugar, tendrá un identificador numérico utilizado por el sistema). Si necesita acceder al valor anterior de uno de estos campos, tendrá que realizar un seguimiento por su cuenta:

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;

        // hacer cosas...

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

onSheetWorkerCompleted

Parámetros

CALLBACK (Función) La función que se invocará cuando se complete la «pila» actual de scripts de Sheet Worker.

Devoluciones

(Nulo)

Ejemplos

Esta función está pensada para ser llamada antes de setWithWorker. La funciónde devolución de llamadasolo se invocará una vez.

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];
    // hacer algo con calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

jugadorEsGM

Parámetros

PLAYER_ID(Cadena) El identificador del objeto Roll20 del jugador que se va a comprobar.

Devoluciones

verdaderosi el jugador tiene actualmente permisos de GM, ofalsoen caso contrario.

Ejemplos

Esta función es especialmente útil para limitar los comandos Mod (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;
        // ...
    }
});

playJukeboxLista de reproducción

Parámetros

PLAYLIST_ID (cadena) El identificador de la lista de reproducción que se va a reproducir.

Devoluciones

(Nulo)

Ejemplos

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

entero aleatorio

Parámetros

MAX(Número) El número máximo que se devolverá, incluido.

Devoluciones

Un número entero aleatorio entre 1 (incluido) ymáx.(incluido). Esta función tiene una mejor distribución queMath.random() y se recomienda su uso en lugar de esta última. Esta función no utiliza el Quantum Roll que utiliza el motor de dados, pero sí utiliza el mismo algoritmo pseudoaleatorio al que recurrirá el motor de dados si Quantum Roll no está disponible.

Ejemplos

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

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

sendChat Asíncrono

Parámetros

SPEAKINGAS(Cadena) El nombre que se adjuntará al mensaje que se envía. Si speakingAs tiene el formato jugador|id_jugador o personaje|id_personaje, el mensaje se enviará como ese jugador o personaje. De lo contrario, el mensaje utilizará el nombre dado como si un GM hubiera utilizado el comando /as. MESSAGE(String) El mensaje que se enviará al chat. CALLBACK(Función, opcional) Si se especifica callback, el resultado del mensaje de chat se le pasará a él en lugar de aparecer en el chat. El parámetro del método de devolución de llamada es una matriz de objetos de mensaje. OPTIONS (Objeto, opcional) Si options.noarchive es verdadero, el mensaje no se añadirá al archivo del chat. Si options.use3d es verdadero, las tiradas 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.

Devoluciones

(Nulo)

Ejemplos

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

Puede escribir fácilmente código para enviar un mensaje como el mismo jugador o personaje que activó un eventochat:message.

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

    if (personaje) sendChat('personaje|'+personaje.id, personaje.get('nombre')+mensaje);
    else sendChat('jugador|'+jugador.id, jugador.get('nombre de usuario')+mensaje);
});

El parámetrocallbackes útil si necesita aprovechar el motor de dados de Roll20. motor de dados. No hay ninguna necesidad especial de utilizar el valorspeakingAsal utilizar ladevolución de llamada, 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 reproductores menús creados a partir de botones de comando API sin saturar su historial de chat.

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

enviarPing

Parámetros

LEFT(Número) La coordenada x donde colocar el ping. TOP(Número) La coordenada y donde colocar el ping. PAGE_ID(Cadena) El identificador del objeto Roll20 de la página donde colocar el ping. PLAYER_ID(Cadena, opcional) El ping utilizará el color del jugador especificado. Si se omite player_id, el ping será amarillo. MOVEALL (Booleano, opcional) Si moveAll es verdadero, todos los jugadores de la página correspondiente tendrán sus vistas centradas en el ping.

Nota:En este momento, solo los GM tendrán sus vistas centradas simoveAllesverdadero. Este comportamiento está documentado aquí.

Devoluciones

(Nulo)

Ejemplos

on('chat:message', 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); // centrar a todos en el token seleccionado
    }
});

spawnFx

Parámetros

LEFT(Número) La coordenada x para colocar el emisor de partículas. TOP(Número) La coordenada y para colocar el emisor de partículas. TYPE(Cadena) El tipo de emisor de partículas que se va a colocar. Para los efectos incorporados, debería ser «tipo-color», donde tipo es uno de los siguientes: bomba, burbujeante, quemadura, estallido, explosión, resplandor, misil o nova, y color es uno de los siguientes: ácido, sangre, encanto, muerte, fuego, hielo, sagrado, magia, limo, humo o agua. Para efectos personalizados, este debe ser el identificador del objeto FX Roll20. Nota: los tipos beam, breath y splatter no se pueden utilizar con spawnFx. Véase spawnFxBetweenPoints en su lugar. PAGE_ID(cadena, opcional) El identificador del objeto Roll20 de la página en el que colocar el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.

Devoluciones

(Nulo)

Ejemplos

spawnFx(1400, 1400, 'burbujas de ácido');

spawnFxBetweenPoints

Parámetros

START(Objeto) El punto de partida del emisor de partículas. El punto debe tener el formato { x: número, y: número }.END(Objeto) El punto final para el emisor de partículas. El punto debe tener el formato { x: número, y: número }. TIPO(Cadena) El tipo de emisor de partículas que se va a colocar. Para los efectos incorporados, debería ser «tipo-color», donde el tipo es uno de los siguientes: rayo, bomba, aliento, burbujeo, quemadura, estallido, explosión, resplandor, misil, nova, o salpicadura y color es uno de ácido, sangre, encanto, muerte, fuego, hielo, sagrado, magia, limo, humo o agua. Para efectos personalizados, este debería ser el identificador del objeto FX Roll20. PAGE_ID (cadena, opcional) El identificador del objeto Roll20 de la página en el que colocar el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.

Devoluciones

(Nulo)

Ejemplos

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

spawnFxWithDefinition

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. DEFINICIÓN(Objeto) Las características del emisor de partículas que se va a colocar. Consulte Efectos personalizados para obtener una lista de las propiedades posibles y las propiedades de los tipos y colores predeterminados del emisor de partículas. Consulte la biblioteca FX para ver algunos efectos personalizados que han creado los usuarios de Roll20. PAGE_ID(cadena, opcional) El identificador del objeto Roll20 de la página en la que se colocará el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.

Devoluciones

(Nulo)

Ejemplos

// estos dos son equivalentes
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxWithDefinition(1400, 1400, {
    maxParticles: 200,
    size: 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]
});

detenerJukeboxLista de reproducción

Parámetros

Sin parámetros

Devoluciones

(Nulo)

Ejemplos

detenerJukeboxListaDeReproducción();

Atrás

Parámetros

OBJ (objeto Roll20) El objeto Roll20 que se enviará al fondo de su capa.

Devoluciones

(Nulo)

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));
        });
    }
});

al frente

Parámetros

OBJ (objeto Roll20) El objeto Roll20 que se va a colocar en primer plano de su capa.

Devoluciones

(Nulo)

Ejemplos

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});