API: Objetos

Nota:La propiedadidde un objeto es un identificador único a nivel global: no debe haber dos objetos con el mismo identificador, ni siquiera entre objetos de tipos diferentes. Además, dado que se accede con frecuencia al identificador de un objeto y este nunca cambia, existe un atajo disponible que le permite acceder a él utilizandoobj.iden lugar deobj.get("_id")si lo desea (ambos funcionan).

Pathv2 (disponible en la última versión del motor VTT)

La propiedad shape tiene los siguientes valores:

• «pol»:polilínea. Se traza una línea recta entre cada punto consecutivo. Si el punto inicial y el punto final son iguales, se crea una forma cerrada.
• «libre»- A mano alzada. Se dibuja una curva utilizando los puntos como guías. Si el punto inicial y el punto final son iguales, se crea una forma cerrada.
• «eli» - Elipse. Se dibuja una elipse utilizando los puntos para establecer un cuadro delimitador. Solo se utilizan los dos primeros puntos.
• «rec»: rectángulo. Se dibuja un rectángulo utilizando los puntos para establecer un cuadro delimitador. Solo se utilizan los dos primeros puntos.

La propiedad points es una cadena JSON que contiene una matriz de puntos. Los puntos se representan como una matriz de dos posiciones con una ubicación x e y. Un triángulo desde (0,0) hasta (0,70) y desde (70,0) hasta (0,0) se representaría como «[[0,0],[0,70],[70,0],[0,0]]».

Las propiedades x eyposicionan el objeto PathV2 en la página. Especifican dónde debe estar el centro del dibujo. Para algunas formas (elipses y rectángulos), eso es bastante fácil de averiguar. Para formas más complejas (polilíneas y dibujos a mano alzada), deberá encontrar los valores mínimo y máximo de la propiedad de los puntosy utilizar el punto equidistante entre ellos.

Camino (Mesa clásica)

Para obtener más información sobre el formato de los datos de ruta, consulte la sección sobre rutas.

Ventana

Nota: Las ventanas y puertas 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 una 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: Las ventanas y puertas deutilizan 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 una ventana o puerta.

Texto

Gráfico (ficha/mapa/tarjeta/etc.)

Ejemplo de marcadores simbólicos

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

          // ^la URL de la imagen del marcador del token
          }

Notas importantes sobre los personajes vinculados + fichas

Tenga en cuenta que, en el caso de los tokens vinculados a personajes, el campocontrolledbydel token se sustituye por el campocontrolledbydel personaje.

En el caso de las barras de tokens (por ejemplo,bar1_valueybar1_max) en las que el token está vinculado a un atributo (por ejemplo,bar1_linkestá establecido), al establecer un valor para la barra se actualizarán automáticamente también los valoresactualesy/omáximosdel atributo subyacente, por lo que no es necesario establecer ambos manualmente.

Además, cuando se modifica el atributo (o barra de fichas) en el juego, se escuchará unevento change:attribute(y específico de la propiedad, por ejemplo,change:attribute:current), seguido de un eventochange:graphic(ychange:graphic:bar1_value). Puede elegir responder a cualquiera de los dos eventos, pero los valores de barra subyacentes aún no se actualizarán cuando se active el evento de atributo, ya que este se activa primero.

Notas importantes sobre los indicadores de estado

A partir del 6 de agosto de 2013, ha cambiado la forma en que se gestionan los marcadores de estado en los tokens. La propiedad «statusmarkers» del objeto gráfico es ahora una lista delimitada por comas de todos los colores/iconos de marcadores de estado que deben estar activos en el token. El formato es el siguiente:

Delimitado por comas (utilice «join» para crear o «split» para convertirlo en una matriz). 
//Si un icono/color de estado va seguido del símbolo «@», el número que aparece después de 
//«@» se mostrará como insignia en el icono
statusmarkers = «red,blue,skull,dead,brown@2,green@6»

Aunque puede acceder directamente a la propiedadstatusmarkers, para mantener la compatibilidad con los scripts existentes y facilitar el trabajo con los marcadores de estado sin necesidad de escribir código para dividir y analizar 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 marcador de estado tiene una propiedad «status_<markername>». Por ejemplo:

obj.get("status_red"); //Devolverá false si el marcador no está activo, true si lo está y una cadena (por ejemplo, "2" o "5") si actualmente hay una insignia establecida en el marcador
obj.get('status_bluemarker'); //Sigue siendo compatible con versiones anteriores y es equivalente a obj.get("status_blue");
obj.set("status_red", false); //eliminaría el marcador
obj.set("status_skull", "2"); //establecería una insignia de "2" en el icono de la calavera y la añadiría al token si aún no está activa.

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 un token y, por ejemplo,change:graphic:status_redNO es un evento válido y nunca se activará.

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

«rojo», «azul», «verde», «marrón», «morado», «rosa», «amarillo», «muerto», «calavera», «somnoliento», «medio corazón», «media neblina», «interdicción», «caracol», «hélice de rayo», «llave inglesa», «corazón encadenado», «perno químico», «zona mortal», «bébame», «grieta en el borde», «máscara ninja», «cronómetro», «red de pesca», «sobremarcha», «fuerte», «puño», «candado», «tres hojas», «ala esponjosa», «apaleado», «pisada», «flecha», «aura», «dolor de espalda», «bandera negra», «ojo sangrante», «escudo de perno», «corazón roto», «telaraña», «escudo roto», «bandera ondeando», «radioactivo», «trofeo», «cráneo roto», «orbe congelado», «bomba rodante», «torre blanca», «agarrar», «gritar», «granada», «ametralladora», «todos 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 actual del orden de turno. Es una matriz 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úrese de mantenerlos sincronizados o podría obtener resultados extraños.

Para trabajar con el orden de turno, deberá utilizarJSON.parse()para obtener un objeto que represente el estado actual del orden de turno (NOTA: compruebe primero que no sea una cadena vacía""... si lo es, inicialícela usted mismo con una matriz vacía). Aquí hay un ejemplo de objeto de orden de turno:

[
    {
     "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //El ID del objeto gráfico. Si se configura esta opción, la lista de turnos extraerá automáticamente el nombre y el icono para la lista basándose en el gráfico de la mesa.
     "pr":"0", //El valor actual del elemento de la lista. Puede ser un número o texto.
     "custom":"" //Título personalizado para el artículo. Se ignorará si el ID se establece en un valor distinto de «-1».
    },
    {
     "id":"-1", //Para los elementos personalizados, el ID DEBE establecerse en "-1" (tenga en cuenta que se trata de una CADENA, no de un NÚMERO).
     "pr":"12",
     "custom":"Prueba personalizada" //El nombre que se mostrará para los elementos personalizados.
    }
]

Para modificar el orden de turno, edite el objeto de orden de turno actual y, a continuación, utiliceJSON.stringify()para cambiar el atributo en la campaña. Tenga en cuenta que el orden de los turnos en la lista es el mismo que el orden de la matriz, por lo que, por ejemplo,push()añade un elemento al final de la lista,unshift()lo añade al principio, etc.

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTA: Primero comprobamos que el turnorder no sea solo una cadena vacía. Si es así, trátelo como una matriz vacía.
else turnorder = JSON.parse(Campaign().get("turnorder"));

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

Jugador

Macro

Tablas para tiradas

Elemento de tabla 

Personaje

Atributo

 Importante: Consulte la nota siguiente sobre cómo trabajar con hojas de personaje para obtener información sobre cómo los valores predeterminados de las hojas de personaje afectan al uso de los atributos.

Habilidad

Nota

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

Cubierta

Tenga en cuenta que hay métodos API auxiliares para «robar», «repartir» o «barajar» cartas del mazo. Véasela publicación del foro sobre la actualización de la API de marzo de 2018.

Tarjeta

Mano

Tenga en cuenta que cada jugador solo debe tener UNA mano.

Pista de Jukebox

Efectos especiales personalizados

Restricciones de las propiedades imgsrc y avatar

Aunque ahora puede editar las propiedadesimgsrcyavatar, con el fin de garantizar la seguridad de todos los usuarios de Roll20, hemos establecido las siguientes restricciones para dichas propiedades:

• Debe utilizar un archivo de imagen que haya subido a su biblioteca Roll20, no a un sitio externo (como Imgur) ni al mercado Roll20. Comenzará con«https://s3.amazonaws.com/files.d20.io/images/»para las imágenes subidas al servidor principal, o«https://s3.amazonaws.com/files.staging.d20.io/images/»para las imágenes subidas al servidor de desarrollo. Puede ver la URL de origen de una imagen utilizando las herramientas de desarrollo de su navegador.

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

• Para los objetos gráficos (tokens), debe utilizar el tamaño «miniatura» de la imagen. Debería aparecer como«https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678».

En el futuro, es posible que añadamos una herramienta para que se puedan cargar imágenes específicamente para su uso con scripts Mod (API), pero por ahora utilice las imágenes cargadas en su propia biblioteca. Tenga en cuenta que si elimina una imagen de su biblioteca, se eliminará de todos los juegos que utilicen esa imagen, incluidos los juegos que utilicen sus scripts Mod (API).

Uso de los campos Notas, GMNotas y Biografía Asíncrono

Para acceder a los campos «notes», «gmnotes» o «bio» en Personajes y Fichas, debe pasar una función de devolución de llamada como segundo argumento a la función get(). Aquí tiene un ejemplo:

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

Puede establecer el valor de estos campos como de costumbre. Tenga en cuenta que actualmente (a fecha de 09/05/2016) existe un error con estos campos asíncronos, por el que al configurarlos pasando valores a createObj falla silenciosamente, dejando el objeto en un estado extraño. Solo debe establecer estos valores utilizando .set hasta que se resuelva este problema. Detalles sobre el foro. También hay un error (a fecha de 05/11/2016) por el que, al intentar establecer las propiedades notes y gmnotes en la misma llamada a set(), la segunda propiedad de la llamada se establece de forma errónea. Detalles sobre el foro.

Trabajar con hojas de personaje

La función Hojas de personajes afecta al uso del tipo de objeto Atributos, ya que las hojas tienen la capacidad de especificar un valor predeterminado para cada atributo de la hoja. Sin embargo, si el atributo se establece en el valor predeterminado, aún no se ha creado un objeto Atributo real en el juego para ese personaje. Ofrecemos una función práctica que le oculta esta complejidad. Debe utilizar esta función para obtener el valor de un atributo en el futuro, especialmente si sabe que un juego utiliza una hoja de personaje.

getAttrByName(id_carácter, nombre_atributo, tipo_valor)

Simplemente especifique el ID del personaje, elnombre(no el ID) del atributo (por ejemplo, «HP» o «Str») y, a continuación, si desea el «actual» o el «máximo» para value_type. Aquí tiene 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)]]»

Tenga en cuenta que los campos que tienen valores calculados automáticamente devolverán la fórmula en lugar del resultado del valor. A continuación, puede pasar esa fórmula a sendChat() para utilizar el motor de dados y calcular el resultado automáticamente.

Asegúrese de consultar también la hoja de personaje para obtener más información sobre cómo interactúan las hojas de personaje con la API.

getAttrByNamesoloobtendrá el valor del atributo, no el objeto del atributo en sí. Si desea hacer referencia a propiedades del atributo distintas de «current» o «max», o si desea cambiar las propiedades del atributo, debe utilizar una de las otras funciones anteriores, comofindObjs.

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

Creación de objetos

createObj(tipo, atributos)

Nota: actualmente puede crear objetos «gráfico», «texto», «ruta», «carácter», «habilidad», «atributo», «folleto», «tabla desplegable», «elemento de tabla» y «macro».

Puede crear un nuevo objeto en el juego utilizando la funcióncreateObj. Debe pasar el tipo del objeto (una de las propiedades_typeválidas de la lista de objetos anterior), así como un objetode atributosque contenga una lista de propiedades para el objeto. Tenga en cuenta que si el objeto tiene un objeto padre (por ejemplo, los atributos y habilidades pertenecen a los personajes, los gráficos, los textos y las rutas 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). Tenga en cuenta también que, incluso al crear nuevos objetos, no puede establecer propiedades de solo lectura, ya que se establecerán automáticamente con su valor predeterminado. La única excepción a esto es cuando se crea una ruta, en cuyo caso debe incluir la propiedad «path», pero esta no se puede modificar una vez creada la ruta.

createObjdevolverá el nuevo objeto, para que pueda continuar 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: "Strength",
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Eliminación de objetos

objeto.eliminar()

Nota: actualmente puede eliminar objetos «gráfico», «texto», «ruta», «carácter», «habilidad», «atributo», «folleto», «tabla desplegable», «elemento de tabla» y «macro».

Puede eliminar objetos de juego existentes utilizando la función.remove(). La función .remove() funciona con todos los objetos que puede crear con la función createObj. Usted llama a la función directamente en el objeto. Por ejemplo,miPersonaje.eliminar();.

Objetos globales

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

Campaña() (función)

Función que devuelve el objetoCampaña. Dado que solo hay una campaña, este global siempre apunta a la única campaña del juego. Útil para comprobar si un objeto se encuentra en la página activa utilizandoCampaign().get("playerpageid").

estado

La variablede estadoes un objeto en el ámbito global al que pueden acceder todos los scripts que se ejecutan en un juego. Puede acceder al objetostatedesde cualquier función o callback en cualquier momento simplemente utilizando la variable global denominadastate. Además, el objetode estadose mantiene entre las ejecuciones del Sandbox, por lo que puede utilizarlo para almacenar información que desee tener en futuras ejecuciones de su script.

Nota:Debe utilizar el objeto de estado para almacenar información que solo necesita la API, ya que no se envía a los ordenadores de los jugadores y no aumenta el tamaño del archivo del juego. Almacene los valores que se necesitan en el juego en las propiedades de los objetos Roll20.

Tipos almacenables

El objetode estadosolo es capaz de conservar tipos de datos simples, tal y como admite el estándar JSON .

Advertencia:aunque las funciones parecerán funcionar cuando se almacenen en el estado inicial, desaparecerán la primera vez que se restaureel estadodesde la persistencia, como por ejemplo al reiniciar el entorno de pruebas.

• Nota:Esto incluye los objetos Roll20 que se obtienen de eventos o de las funcionesfindObjs(),getObj(),filterObjs(),createObj(), etc.

Recordatorios importantes

El objetode estadose comparte entre todos los scripts de un entorno aislado. Para evitar dañar otros scripts, es importante seguir unas sencillas pautas:

• Nunca asigne directamente al objetode estadoraíz.

state = { break: 'all the things' };  // ¡¡¡NUNCA HAGA ESTO!!!

• Evite utilizar variables locales llamadasstateen sus scripts. Aunque esto funcionará, resultará confuso para los usuarios posteriores de sus scripts y podría causar problemas si el código se edita sin cuidado.

función turn(){
    var state = Campaign().get('turnorder');  // ¡Mala práctica, evítela!
    // ...
}

• Siempre coloquen sus propiedades debajo de al menos una propiedad de espacio de nombres. Asegúrese de utilizar una propiedad de espacio de nombres suficientemente descriptiva. Evite nombres comoscriptosettings. Lo mejor es utilizar el nombre de su módulo o su propio nombre o apodo.

if( ! state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module: 'my module', ok: 'this is fine!', count: 0 };
}
state.MyModuleNamespace.count++;

Ejemplo de uso

Este es un ejemplo práctico que utiliza el objetode estadode forma adecuada.

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

    // Compruebe si existe la propiedad del espacio de nombres y, si no existe, créela.
    if( ! state.MyModuleNS ) {
        state.MyModuleNS = {
            version: 1.0,
            config: {
                color1: '#ff0000',
                color2: '#0000ff'
            },
            count: 0
        };
    }

    // Uso de las propiedades de estado para configurar un mensaje para el chat. 
    sendChat(
        'Módulo de prueba',
        '<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>'
    );
});

Buscar/filtrar objetos

La API proporciona varias funciones auxiliares que se pueden utilizar para buscar objetos.

getObj(type, id)
Esta función obtiene un único objeto si se le pasa el _type del objeto y el _id. Siempre que sea posible, es mejor utilizar esta función en lugar de otras funciones de búsqueda, 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(atributos)

Pase a esta función una lista de atributos y le devolverá todos los objetos que coincidan como una matriz. Tenga en cuenta que esto funciona con todos los objetos de todos los tipos en todas las páginas, por lo que probablemente desee incluir al menos un filtro para _type y _pageid si está trabajando con objetos de mesa.

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

También puede pasar un segundo argumento opcional que contenga un objeto con una lista de opciones, entre las que se incluyen:

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

var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});
//Devuelve todos los tokens con el nombre «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 la matriz de resultados. Actualmente, no es recomendable utilizar filterObjs() para la mayoría de los fines, ya que findObjs() tiene una indexación integrada para mejorar la velocidad de ejecución, por lo que casi siempre es mejor utilizar findObjs() para obtener primero los objetos del tipo deseado y, a continuación, filtrarlos utilizando el método nativo .filter() para matrices.

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;    
  else return false;
});
//Results es una matriz de todos los objetos que se encuentran en la esquina superior izquierda de la mesa.

obtenerTodosLosObjetos()

Devuelve una matriz con todos los objetos del juego (de todos los tipos). Equivalente a llamar a filterObjs y simplemente devolvertruepara cada objeto.

getAttrByName(id_carácter, nombre_atributo, tipo_valor)

Obtiene el valor de un atributo, utilizando el valor predeterminado de la hoja de personaje si el atributo no está presente. value_typees un parámetro opcional que puede utilizar para especificar «current» (actual) o «max» (máximo).

getAttrByNamesoloobtendrá el valor del atributo, no el objeto del atributo en sí. Si desea hacer referencia a propiedades del atributo distintas de «current» o «max», o si desea cambiar las propiedades del atributo, debe utilizar una de las otras funciones anteriores, comofindObjs.

Para las secciones repetidas, puede utilizar el formatorepeating_section_$n_attribute, dondenes el número de fila repetida (empezando por cero). Por ejemplo,repeating_spells_$2_namedevolverá el valor denamede la tercera fila derepeating_spells.

Puede lograr un comportamiento equivalente agetAttrByName conlo siguiente:

// current y max dependen completamente del atributo y del sistema de juego
// en cuestión; no hay ninguna función disponible para determinarlos automáticamente
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');
    }
}