API: Funciones de Utilidad

Se proporcionan funciones de utilidad para ayudarte a trabajar de manera consistente con el espacio de juego de Roll20. Puede llamar a una función de utilidad desde cualquier lugar en sus scripts (dentro de cualquier devolución de llamada de evento, por ejemplo).


Underscore.js

Tiene acceso a la biblioteca Underscore.js (a través del objeto global_) para facilitarle las cosas. Underscore proporciona funciones auxiliares para cosas como_.each(para iterar a través de una matriz de objetos). Consulte la documentación deUnderscorepara obtener más información.


Registro

log(mensaje)

Puede usar esta función para registrar la salida en la consola de la API en la página del Editor de Scripts. Útil para depurar tus scripts y tener un mejor control de lo que sucede dentro del sandbox de la API.

on("change:graphic", function(obj) {    
  log("Se escuchó cambio para ID de objeto: " + obj.id);
});

Orden de objetos

toFront(obj)ytoBack(obj)

Estas dos funciones moverán un objeto en la mesa de juego al frente (o detrás) de la capa en la que se encuentra actualmente. Ten en cuenta que debes pasar un objeto real, como el que recibes en una devolución de llamada de evento o llamando agetObjofindObjs.


Números aleatorios

randomInteger(max)

Utilice esta función para los dadosEsta función tiene en cuentaModulo Biaslo que garantiza que los números aleatorios resultantes también se distribuyan uniformemente entre 1 y MAX.

Devuelve un número entero aleatorio, siendo el valor más bajo 1 y el valor más altomax. Esta es la misma funcionalidad que Roll20 utiliza para ejecutar sus lanzamientos de dados, y se ha demostrado estadística y rigurosamente que estos números son aleatorios.

Math.random()

Puedes llamar a Math.random() como siempre en tus scripts de API, confiando en que los resultados serán aleatorios, porque el Math.random() "predeterminado" en Javascript ha sido reemplazado por el PRNG criptográficamente seguro que alimenta a Roll20. Por lo tanto, los scripts existentes que utilizan Math.random() pueden utilizarse sabiendo que los resultados son realmente tan aleatorios como es posible en una computadora.

No utilices Math.random() si se desea una distribución uniforme de números en un rango. Si bien Math.random() te da un buen número aleatorio, convertir ese número aleatorio en un rango con distribución uniforme (como un lanzamiento de dados) no es tan sencillo como hacer una multiplicación con un módulo o una llamada a floor. UtilizarandomInteger(max)para esos casos.


Jugador es GM

playerIsGM(playerid)

La función Jugador es GM devuelve una respuesta booleana sobre si un jugador en el juego es un GM o no. La función siempre devolverá la respuesta correcta dependiendo del momento actual, por lo que incluso si un GM elige volver a unirse como jugador o si un jugador es promovido a GM durante el juego, playerIsGM() responderá en consecuencia sin necesidad de borrar una caché o reiniciar el API sandbox.


Personaje

setDefaultTokenForCharacter( personaje, ficha )

Establece el token predeterminado para el objeto de personaje proporcionado con los detalles del objeto de token proporcionado. Ambos objetos deben existir previamente. Esto sobrescribirá cualquier token predeterminado asociado actualmente con el personaje.


Efectos Especiales (FX)

spawnFx(x, y, tipo, pageid)

Genera un efecto breve en la ubicación en x, y del tipo especificado. Si omites el pageid o pasas 'undefined', entonces se utilizará por defecto la página en la que se encuentran los jugadores ('playerpageid' en el objeto de Campaña).

Para los efectos integrados, el tipo debe ser una cadena y debe ser uno de los siguientes:beam-colorbomb-colorbreath-colorbubbling-colorburn-colorburst-colorexplode-colorglow-colormissile-colornova-colorsplatter-color

Donde "color" en lo anterior es uno de:ácido,sangre,encanto,muerte,fuego,escarcha,sagrado,magia,lodo,humo,agua

Para efectos personalizados, el tipo debe ser la identificación del objeto custfx para el efecto personalizado.

spawnFxBetweenPoints(punto1, punto2, tipo, pageid)

Funciona de la misma manera que spawnFx, pero en lugar de un solo punto pasas dos puntos, en el formato {x: 100, y: 100}. Por ejemplo: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"); El efecto "viajará" entre los dos puntos para los efectos que lo admitan (los mismos que permiten la agencia en el lado del cliente).

Los siguientes tipos de efectos siempre deben usar spawnFxBetweenPoints en lugar de spawnFx:del color del rayo,del color del aliento,del color del salpicón

spawnFxWithDefinition(x, y, definitionJSON, pageid)

Crea un efecto personalizado ad hoc utilizando el JSON de alguna definición de efecto en la ubicación x, y. Si omites el pageid o pasas 'undefined', entonces se utilizará por defecto la página en la que se encuentran los jugadores ('playerpageid' en el objeto Campaign).

definitionJSON es un objeto de JavaScript siguiendo la especificación JSON paraFX personalizados.


Lista de reproducción de la gramola

playJukeboxPlaylist(playlistid)

La función play recibe el ID de la carpeta (obtenlo de la propiedad "_jukeboxfolder" en el objeto Campaign) de la lista de reproducción, y comenzará a reproducir esa lista para todos en el juego.

stopJukeboxPlaylist()

La función stop no requiere ningún argumento y detendrá cualquier lista de reproducción que se esté reproduciendo actualmente.


Varios

sendPing(izquierda, arriba, id de página, (opcional) id de jugador, (opcional) moverTodo, (opcional) visiblePara)

Envía un "ping" a la mesa de juego (lo mismo que si un jugador mantuviera presionado el botón del mouse). Debes especificar las coordenadas de arriba/izquierda, y el id de página que se va a pingear. Opcionalmente puedes especificar el ID de un jugador que realizó el ping, si no lo haces se asumirá "api" y el ping será amarillo.

Puedes pasar "true" para la opción moverTodo si quieres mover las vistas de los jugadores a esa ubicación también.

Puedes configurar los ID de jugadores en visiblePara para los jugadores que pueden ver o ser movidos por el ping. Esto se presenta como un solo ID de jugador, un array o una cadena delimitada por comas.

on("chat:message", función(msg) {
  // Ingresa "!pingtest" en el chat para ejecutar la prueba
  if(msg.type == "api" && msg.content.indexOf("!pingtest") !== -1) {
 
    // para obtener un jugador específico, usa findObjs({_type: "player"})[i].id en lugar de null para el tercer parámetro
    jugadores = findObjs({_type: "player"});
    jugador1 = jugadores[1].id;
    jugador2 = jugadores[2].id;
 
    // Crea un array de IDs de todos los jugadores
    var todosLosIDsJugadores = jugadores.map(function(jugador) {
      return jugador['id'];
    });
 
    // Envía un ping a todos en esta página al mismo lugar.
    sendPing(300, 300, Campaign().get('playerpageid'), null, true);
    setTimeout(function() {
        // Ping everyone on this page to the same location
        sendPing(1500, 500, Campaign().get('playerpageid'), msg.playerid, true, "");
    }, 1000);
    setTimeout(function() {
        // Ping only the specified player to this location
        sendPing(1200, 500, Campaign().get('playerpageid'), null, true, player1);
    }, 2000);
    setTimeout(function() {
        // Ping an array of player IDs (player 1 and 2) to this location
        sendPing(900, 100, Campaign().get('playerpageid'), player2, true, [player1, player2]);
    }, 3000);
    setTimeout(function() {
        // Ping a comma-separated list supplied as a string to this location
        sendPing(300, 300, Campaign().get('playerpageid'), player1, true, allPlayerIDs.join());
    }, 4000);
 
  }
})
 

A Note on Distances and Grids in Roll20

In Roll20, a "unit" is always 70 pixels on the screen. The "unit" is the building block that distance and the grid are built on top of. By default:

  • 1 unidad = 5 pies
  • 1 unidad = 1 cuadro de la cuadrícula
  • Por lo tanto, 5 pies = 1 unidad = 1 cuadrado

Sin embargo, el GM puede cambiar tanto el tamaño de la cuadrícula como la escala de la distancia. Siempre hay 1 unidad de 70 píxeles, pero el GM podría cambiar la configuración de modo que ahora 1 unidad equivalga a 10 pies (lo que significa que 70 píxeles = 10 pies), o que cada espacio de la cuadrícula sea de 2 unidades (lo que significa que cada espacio de la cuadrícula ahora es de 140 píxeles).

¿Fue útil este artículo?
Usuarios a los que les pareció útil: 11 de 18