API: Objetos

Nota:La propiedadidde un objeto es un ID único a nivel global: ningún objeto debería tener el mismo, incluso entre diferentes tipos de objetos. Además, dado que el id de un objeto se accede con frecuencia y nunca cambia, hay un acceso directo disponible en el que puedes acceder a él usandoobj.iden lugar deobj.get("_id")si lo deseas (cualquiera de las dos opciones funcionará).

Pathv2 (Jumpgate Tabletop)

The shape property has the following values:

• "pol" - Polyline. A straight line is drawn between each consecutive point. If the starting point and ending point are the same, it creates a closed shape.
• "free" - Freehand. A curve is drawn using the points as guides. If the starting point and ending point are the same, it creates a closed shape.
• "eli" - Ellipse. An ellipse is draw using the points to set a bounding box. Only the first two points are used.
• "rec" - Rectangle. A rectangle is draw using the points to set a bounding box. Only the first two points are used.

The points property is a JSON string containing an array of points. Points are represented as a two position array of an x and y location. A triangle from (0,0) to (0,70) to (70,0), and back to (0,0) would be represented as "[[0,0],[0,70],[70,0],[0,0]]".

The x and y properties position the PathV2 object on the page. They specify where the center of the drawing should be. For some shapes (ellipses and rectangles), that is pretty easy to figure out. For more complex shapes (polylines and freehands), you will need to find the minimum and maximum values from the points property and use the point equidistant between them.

Path (Classic Tabletop)

Para obtener más información sobre el formato de los datos del camino_path, consulta la sección sobre caminos.

Ventana

Nota: La ventana y la puerta utilizan un eje invertido en comparación con otros tipos de objetos. Por ejemplo, una variable superior que sería 100 para otro objeto es y -100 para ventana o puerta.

Ejemplo

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!cw') {
        const currentPageID = Campaign().get('playerpageid');
        const win = createObj('window', {
            x: 70,
            y: -70,
            pageid: currentPageID,
            path: {
		        handle0: {
        			x: -70,
        			y: 0,
        		},
        		handle1: {
        			x: 35,
        			y: 0,
        		},
        	},
            color: '#000000'
        });
    }

    if (msg.type === 'api' && msg.content === '!mw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.set({
           x: 240,
           y: -139
        });
    }

    if (msg.type === 'api' && msg.content === '!dw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.remove();
    }
});

Puerta

Nota: La ventana y la puerta utilizan un eje invertido en comparación con otros tipos de objetos. Por ejemplo, una variable superior que sería 100 para otro objeto es y -100 para la ventana o puerta.

Texto

Gráfico (Token/Mapa/Carta/etc.)

Ejemplo de Marcadores de fichas

{
          "id":59, // el id de la base de datos para el
          "name":"Bane", // el nombre (no único) del marcador
          "tag":"Bane::59", // cómo se referencia realmente el token
          // esto incluirá el id para marcadores personalizados, pero no
          // para marcadores predeterminados.
          "url":"https://s3.amazonaws.com/files.d20.io/images/59/yFnKXmhLTtbMtaq-Did1Yg/icon.png?1575153187"

          // ^la url para la imagen del marcador de fichas
          }

Notas Importantes Sobre Personajes y Fichas Conectados

Tenga en cuenta que para los tokens que están vinculados a Caracteres, el campocontroladopordel token queda anulado por el campocontroladopordel Carácter.

Para las barras de tokens (por ejemplo,bar1_valueybar1_max) en las que el token está vinculado a un Atributo (por ejemplo,bar1_linkestá configurado), al establecer un valor en la barra se actualizarán automáticamente también los valorescurrenty/omaxdel Atributo subyacente, por lo que no tendrá que configurar ambos manualmente.

Además, cuando se modifique el atributo (o la barra de fichas) en el juego, oirá un eventochange:attribute(y específico de la propiedad, por ejemplochange:attribute:current), seguido de un eventochange:graphic(ychange:graphic:bar1_value). Puedes elegir responder a cualquiera de los eventos, pero los valores de la barra subyacente aún no se actualizarán cuando se active el evento del atributo, ya que se activa primero.

Notas importantes sobre los marcadores de estado

A partir del 6 de agosto de 2013, la forma en que se manejan los marcadores de estado en las fichas ha cambiado. La propiedad "statusmarkers" del objeto Gráfico ahora es una lista separada por comas de todos los colores/íconos de los marcadores de estado que deberían estar activos en la ficha. El formato es el siguiente:

//Separado por comas (usa join para crear o split para convertir en una matriz). 
//Si un ícono/color de estado va seguido de un símbolo "@", el número después de 
//@ se mostrará como insignia en el ícono
statusmarkers = "rojo,azul,calavera,muerto,marrón@2,verde@6"

Aunque puede acceder directamente a la propiedadstatusmarkers, para mantener la compatibilidad con los scripts existentes y proporcionar una forma sencilla de trabajar con los marcadores de estado sin necesidad de escribir código para manejar la división y el análisis sintáctico de la cadena usted mismo, proporcionamos un conjunto de propiedades "virtuales" en el objeto que puede establecer/obtener para trabajar con los marcadores de estado. Cada marca de estado tiene una propiedad "estado_<markername>". Por ejemplo:

obj.get("estado_rojo"); //Devolverá falso si la marca no está activa, verdadero si lo está y una cadena (por ejemplo, "2" o "5") si actualmente hay un distintivo configurado en la marca
obj.get('estado_marcadorazul'); //Sigue siendo compatible con la retrocompatibilidad y es equivalente a hacer obj.get("estado_azul");
obj.set("estado_rojo", falso); //eliminaría la marca
obj.set("estado_calavera", "2"); //configuraría un distintivo de "2" en el icono de calavera y lo agregaría al token si aún no está activo.

Tenga en cuenta que estas propiedades virtuales no tienen eventos, por lo que debe utilizarchange:graphic:statusmarkerspara escuchar los cambios en los marcadores de estado de una ficha, y por ejemplochange:graphic:status_redNO es un evento válido y nunca se disparará.

La lista completa de marcas de estado disponibles (en el mismo orden en que aparecen en la bandeja de marcas):

"rojo", "azul", "verde", "marrón", "morado", "rosa", "amarillo", "muerto", "calavera", "adormilado", "media corazón", "media neblina", "prohibición", "caracol", "rayo brillante", "llave de tuercas", "corazón encadenado", "rayo químico", "zona de la muerte", "bebe esto", "grieta en el filo", "máscara de ninja", "cronómetro", "red de pesca", "sobremarcha", "fuerte", "puño", "candado", "tres hojas", "ala esponjosa", "golpeado", "pisada", "con flechas", "aura", "dolor de espalda", "bandera negra", "ojo sangrante", "escudo con rayo", "corazón roto", "telaraña", "escudo roto", "bandera voladora", "radiactivo", "trofeo", "cráneo roto", "orbe congelado", "bomba rodante", "torre blanca", "atraco", "gritando", "granada", "torreta de vigilancia", "todo para uno", "traje de ángel", "blanco de tiro con arco"

Página

Campaña

 Orden de turno

El orden de turno es una cadena JSON que representa la lista de órdenes de turno actuales. Es un conjunto de objetos. Actualmente, el orden de turno solo puede contener objetos de una página a la vez: el ID de página actual para el orden de turno es el atributo "initiativepage". Asegúrate de mantenerlos sincronizados o podrías obtener resultados extraños.

Para trabajar con el orden de turno, debes usarJSON.parse()para obtener un objeto que represente el estado actual del orden de turno (NOTA: Asegúrate de que no sea una cadena vacía""primero... si lo es, inicialízalo tú mismo con un conjunto vacío). Aquí tienes un ejemplo de objeto de orden de turno:

[
    {
     "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //El ID del objeto gráfico. Si esto está configurado, la lista de orden de turno tomará automáticamente el nombre e icono de la lista basándose en el gráfico del juego de mesa.
     "pr":"0", //El valor actual del elemento en la lista. Puede ser un número o texto.
     "custom":"" //Título personalizado para el elemento. Será ignorado si el ID se establece a un valor diferente de "-1".
    },
    {
     "id":"-1", //Para elementos personalizados, el ID DEBE establecerse en "-1" (tenga en cuenta que esto es una CADENA, no un NÚMERO.
     "pr":"12",
     "custom":"Test Custom" //El nombre a mostrar para los elementos personalizados.
    }
]

Para modificar el orden de turno, edita el objeto del orden de turno actual y luego usaJSON.stringify()para cambiar el atributo en la Campaña. Ten en cuenta que el orden para el orden de turno en la lista es el mismo que el orden del arreglo, así que por ejemplopush()agrega un elemento al final de la lista,unshift()agrega al principio, etc.

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTA: Verificamos que turnorder no sea simplemente una cadena vacía primero. Si lo es, trátalo como un arreglo vacío.
else turnorder = JSON.parse(Campaign().get("turnorder"));

//Agregar una nueva entrada personalizada al final del orden de turno.
turnorder.push({
    id: "-1",
    pr: "15",
    custom: "Contador de Turnos"
});
Campaign().set("turnorder", JSON.stringify(turnorder));

Jugador

Macro

Tabla Lanzable

Tabla Artículo 

Personaje

Característica

 Importante: Consulta la nota a continuación sobre cómo funcionan las hojas de personaje para obtener información sobre cómo los valores predeterminados afectan el uso de los atributos.

Característica

Nota

Nota:La API no tiene acceso a la jerarquía de carpetas. Las notas creadas por la API se colocarán en el nivel raíz.

Mazos

Ten en cuenta que hay métodos auxiliares de la API para "robar", "repartir" o "mezclar" cartas del Mazo. Verpublicación del foro de actualización de API de marzo de 2018.

Carta

Mano

Tenga en cuenta que cada jugador sólo debe tener UNA mano.

Tema del Jukebox

Modificación Personalizada

Restricciones de las propiedades imgsrc y avatar

Si bien ahora puedes editar las propiedades imgsrc y avatar, para brindar seguridad a todos los usuarios de Roll20, hemos establecido las siguientes restricciones para estas propiedades:

• Debes usar un archivo de imagen que haya sido cargado en tu biblioteca de Roll20 - no un sitio externo (como Imgur), y no el Mercado Roll20. Comenzará con 'https://s3.amazonaws.com/files.d20.io/images/' para las imágenes cargadas en el servidor principal, o 'https://s3.amazonaws.com/files.staging.d20.io/images/' para las imágenes cargadas en el servidor de desarrollo. Puedes ver la URL de origen de una imagen utilizando las herramientas de desarrollo de tu navegador.

• Debes incluir la cadena de consulta en la URL, por ejemplo 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678', no solo 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png'

• Para objetos gráficos (tokens), debes usar el tamaño "thumb" de la imagen. Debe verse como 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678'.

En el futuro puede que agreguemos una herramienta para que las imágenes se puedan subir específicamente para usar con scripts de Mod (API), pero por ahora simplemente utiliza imágenes subidas a tu propia biblioteca. Ten en cuenta que si eliminas una imagen de tu biblioteca, será eliminada de todos los Juegos que utilicen esa imagen, incluidos los Juegos que utilicen tus scripts de Mod (API).

Usar los campos Notas, Notas del DJ y Biografía Asincrónicos

Para acceder a los campos "notes", "gmnotes" o "bio" en los Personajes y Tablas de mano, debes pasar una función de devolución de llamada como segundo argumento a la función get(). Aquí tienes un ejemplo:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
    log(bio); //haz algo con la biografía del personaje aquí.
});

Puedes establecer el valor de estos campos de forma normal. Ten en cuenta que actualmente (a partir del 2016/05/09) hay un error con estos campos asincrónicos, mediante el cual establecerlos mediante la asignación de valores a createObj falla silenciosamente, dejando el objeto en un estado extraño. Debes establecer estos valores usando .set hasta que se resuelva este problema. Detalles en el foro. También hay un error (a partir de 2016/11/05) donde intentar establecer tanto las propiedades de notas y gmnotes en la misma llamada set() hace que la segunda propiedad en la llamada se establezca erróneamente. Detalles en el foro.

Trabajando con Hojas de Personaje

La función de Hojas de Personaje afecta el uso del tipo de objeto Atributos, ya que las hojas tienen la capacidad de especificar un valor predeterminado para cada atributo en la hoja. Sin embargo, si el atributo se establece en el valor predeterminado, aún no se ha creado un objeto de Atributo real en el juego para ese Personaje. Proporcionamos una función de conveniencia que oculta esta complejidad de ti. Deberías usar esta función para obtener el valor de un atributo en adelante, especialmente si sabes que un juego está utilizando una Hoja de Personaje.

getAttrByName(character_id, attribute_name, value_type)

Simplemente especifica el ID del personaje, el nombre (no ID) del atributo (por ejemplo, "HP" o "Str"), y luego si deseas el valor "actual" o "máximo" para el tipo de valor. Aquí tienes un ejemplo:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); // el valor actual de str, por ejemplo "12"
getAttrByName(character.id, "str", "max"); // el valor máximo de str, por ejemplo "[[floor(@{STR}/2-5)]]"

Ten en cuenta que los campos que tienen valores auto-calculados devolverán la fórmula en lugar del resultado del valor. Luego puedes pasar esa fórmula a sendChat() para usar el motor de dados y calcular el resultado automáticamente.

Asegúrate de también consultar laGuía de la Hoja de Personajepara obtener más información sobre cómo interactúan las Hojas de Personaje con la API.

getAttrByNamesóloobtendrá el valor del atributo, no el objeto atributo en sí. Si deseas hacer referencia a propiedades del atributo que no sean "actual" o "máximo", o si deseas cambiar propiedades del atributo, debes usar una de las otras funciones mencionadas anteriormente, como findObjs.

En el caso de que el atributo solicitado no exista,getAttrByName()devolveráundefined.

Creando Objetos

createObj(type, attributes)

Nota: actualmente puedes crear objetos 'gráfico', 'texto', 'ruta', 'personaje', 'habilidad', 'atributo', 'apunte', 'tabla lanzable', 'elemento de tabla', y 'macro'.

Puedes crear un nuevo objeto en el juego usando la funcióncreateObj. Debes especificar el tipo del objeto (uno de las propiedades_type válidas de la lista de objetos de arriba), así como también un objetoattributes que contiene una lista de propiedades para el objeto. Tenga en cuenta que si el objeto tiene un objeto padre (por ejemplo, los atributos y las habilidades pertenecen a los personajes, los gráficos, los textos y los trazados pertenecen a las páginas, etc.), debe pasar el ID del padre en la lista de propiedades (por ejemplo, debe incluir la propiedadcharacteridal crear un atributo). También ten en cuenta que incluso al crear nuevos objetos, no puedes establecer propiedades de solo lectura, estas se establecerán automáticamente en su valor predeterminado. La única excepción a esto es al crear un Camino, debes incluir la propiedad 'path', pero no se puede modificar una vez que el camino se haya creado inicialmente.

createObj devolverá el nuevo objeto, para que puedas seguir trabajando con él.

//Crear un nuevo atributo de Fuerza en cualquier Personaje que se añada al juego.
on("add:character", function(obj) {
    createObj("attribute", {
        name: "Fuerza",
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Eliminar Objetos

object.remove()

Nota: actualmente puedes eliminar los objetos 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' y 'macro'.

Puedes eliminar objetos de juego existentes usando la función .remove(). La función .remove() funciona en todos los objetos que puedes crear con la función createObj. Llamas a la función directamente en el objeto. Por ejemplo,mycharacter.remove();.

Objetos Globales

Hay varios objetos que están disponibles globalmente en cualquier parte de tu script.

Campaign() (función)

Una función que devuelve el objetoCampaign. Dado que solo hay una campaña, este global siempre apunta a la única campaña en el juego. Útil para hacer cosas como verificar si un objeto está en la página activa usandoCampaign().get("playerpageid").

estado

La variablestatees un objeto de ámbito global al que pueden acceder todos los scripts que se ejecuten en un juego. Puede acceder al objetostatedesde cualquier función o llamada de retorno en cualquier momento con sólo utilizar la variable global denominadastate. Además, elestadose persiste entre ejecuciones delSandbox, por lo que puedes usarlo para almacenar información que deseas tener en ejecuciones futuras de tu script.

Nota:Debería utilizar el objeto de estado para almacenar información que sólo necesite la API, ya que no se envía a los ordenadores de los jugadores y no aumenta el tamaño de su archivo de juego. Almacene los valores necesarios en el juego en las propiedades de los objetos Roll20.

Tipos almacenables

El objeto de estadosólo es capaz de persistir tipos de datos simples, tal y como admite el estándarJSON.

Advertencia:Aunque las funciones parecerán funcionar cuando se almacenen en el estado inicialmente, desaparecerán la primera vez que el estadose restaure desde la persistencia, como en un reinicio de la caja de arena.

• Nota: Esto incluye objetos Roll20 que obtienes de eventos o las funciones encontrarObjs(), obtenerObj(), filtrarObjs(), crearObj(), etc.

Recordatorios importantes

El objetostatese comparte entre todos los scripts de una caja de arena. Para evitar romper otros scripts, es importante seguir algunas pautas simples:

• Nuncaasignar directamente a la raízestadoobjeto.

estado = { break: 'all the things' };  // ¡¡¡NUNCA HAGAS ESTO!!!

• Eviteutilizando variables locales denominadasstateen sus scripts. Si bien esto funcionará, será confuso para los usuarios posteriores de tus scripts y podría causar problemas si se edita descuidadamente el código.

function turn(){
    var state = Campaign().get('turnorder');  // Mala práctica, evítala!
    // ...
}

• Siempre coloca tus propiedades debajo de al menos una propiedad de espacio de nombres. Asegúrate de usar una propiedad de espacio de nombres lo suficientemente descriptiva. Evita nombres como script o ajustes. Es mejor usar el nombre de tu módulo o tu propio nombre o identificador.

if( ! state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module: 'mi módulo', bien: '¡esto está bien!', cuenta: 0 };
}
state.MyModuleNamespace.cuenta++;

Ejemplo de uso

Este es un ejemplo de trabajo que utiliza elestadodel objeto correctamente.

on('ready',function() {
    "use strict";

    // Verifica si la propiedad con namespace existe, creándola si no existe
    if( ! state.MyModuleNS ) {
        state.MyModuleNS = {
            versión: 1.0,
            configuración: {
                color1: '#ff0000',
                color2: '#0000ff'
            },
            conteo: 0
        };
    }

    // Utilizando las propiedades del estado para configurar un mensaje en el chat. 
    sendChat(
        'Test Module',
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
            'Prueba de Estado'+
        '</span> '+
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
            'Script v'+state.MyModuleNS.version+' iniciado '+(++state.MyModuleNS.count)+' veces!'+
        '</span>'
    );
});

Encontrar/Filtrar Objetos

La API proporciona varias funciones auxiliares que se pueden usar para encontrar objetos.

getObj(tipo, id)
Esta función obtiene un solo objeto si se pasa el _tipo del objeto y el _id. Es mejor usar esta función en lugar de las otras funciones de búsqueda siempre que sea posible, ya que es la única que no tiene que iterar a través de toda la colección de objetos.

on("change:graphic:represents", function(obj) {
    if(obj.get("represents") != "") {
       var character = getObj("character", obj.get("represents"));
    }
});

findObjs(attrs)

Pasa esta función una lista de atributos y devolverá todos los objetos que coincidan como un array. Ten en cuenta que esto opera en todos los objetos de todos los tipos en todas las páginas, así que probablemente quieras incluir al menos un filtro para _type y _pageid si estás trabajando con objetos de juego de mesa.

var currentPageGraphics = findObjs({                              
  _pageid: Campaign().get("playerpageid"),                              
  _type: "graphic",                          
});
_.each(currentPageGraphics, function(obj) {    
  //Hacer algo con obj, que está en la página actual y es un gráfico.
});

También puedes pasar un segundo argumento opcional que contenga un objeto con una lista de opciones, incluyendo:

• caseInsensitive(verdadero/falso): Si es verdadero, las propiedades de cadena se compararán sin tener en cuenta la mayúsculas y minúsculas de la cadena

var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});
//Devuelve todos los tokens con un nombre de 'target', 'Target', 'TARGET', etc.

filterObjs(callback)

Ejecutará la función de devolución de llamada proporcionada en cada objeto, y si la devolución de llamada devuelve verdadero, el objeto se incluirá en el array de resultados. Actualmente, no se recomienda utilizar filterObjs() para la mayoría de los casos, debido a que findObjs() tiene un índice incorporado para mejorar la velocidad de ejecución, es casi siempre mejor usar findObjs() para obtener objetos del tipo deseado primero, y luego filtrarlos utilizando el método .filter() nativo para arrays.

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;    
  else return false;
});
//Results es un array de todos los objetos que están en la esquina superior izquierda del tablero.

getAllObjs()

Devuelve una matriz de todos los objetos en el Juego (todos los tipos). Equivalente a llamar a filterObjs y simplemente devolver verdadero para cada objeto.

getAttrByName(character_id, attribute_name, value_type)

Obtiene el valor de un atributo, utilizando el valor predeterminado de la hoja de personaje si el atributo no está presente. value_type es un parámetro opcional, que puedes usar para especificar "actual" o "máx".

getAttrByNamesóloobtendrá el valor del atributo, no el objeto atributo en sí. Si deseas hacer referencia a propiedades del atributo que no sean "actual" o "máx", o si deseas cambiar propiedades del atributo, debes usar una de las otras funciones anteriores, como findObjs.

Para secciones repetidas, puedes usar el formatorepeating_section_$n_attribute, dondenes el número de fila repetida (comenzando desde cero). Por ejemplo,repeating_spells_$2_nameretornará el valor denamede la tercera fila derepeating_spells.

Puedes lograr el comportamiento equivalente agetAttrByNamecon el siguiente:

// current and max are completely dependent on the attribute and game system
// in question; there is no function available for determining them automatically
function myGetAttrByName(character_id,
                         attribute_name,
                         attribute_default_current,
                         attribute_default_max,
                         value_type) {
    attribute_default_current = attribute_default_current || '';
    attribute_default_max = attribute_default_max || '';
    value_type = value_type || 'current';

    var attribute = findObjs({
        type: 'attribute',
        characterid: character_id,
        name: attribute_name
    }, {caseInsensitive: true})[0];
    if (!attribute) {
        attribute = createObj('attribute', {
            characterid: character_id,
            name: attribute_name,
            current: attribute_default_current,
            max: attribute_default_max
        });
    }

    if (value_type == 'max') {
        return attribute.get('max');
    } else {
        return attribute.get('current');
    }
}