Se proporcionan funciones de utilidad para ayudarle a trabajar con el espacio de juego de Roll20 de forma coherente. Puede llamar a una función de utilidad desde cualquier parte de sus scripts (por ejemplo, dentro de cualquier función de retorno de llamada de un evento). La referencia completa de las funciones se encuentra en «Mod Scripts: Documentación de funciones».
Underscore.js
Tiene acceso a la biblioteca Underscore.js (a través del objeto global _ ) para facilitarle el trabajo. Underscore ofrece funciones auxiliares para tareas como _.each (para recorrer un array de objetos). Consulte la documentación de Underscore para obtener más información.
Registro
log(mensaje)
Puede utilizar esta función para registrar la salida en la «Consola de salida de módulos» de la página del Editor de scripts. Resulta útil para depurar sus scripts y comprender mejor lo que ocurre en el entorno de pruebas de scripts de mods.
on("change:graphic", function(obj) {
log("Se ha detectado un cambio en el objeto con ID: " + obj.id);
});Solo para Mod Script Sandbox v1.5. Siempre que sea posible, los mensajes de error incluyen un objeto de contexto que identifica el objeto de Roll20 en cuestión, por ejemplo:
ERROR: La función toBelow() debe invocarse con un objeto gráfico, de texto o de trazado de Roll20. Se ha llamado con [personaje de Roll20 -NM0tVij02hIfnoTdihc].
Pedido de objetos
toFront(obj) y toBack(obj)
Estas dos funciones trasladarán un objeto situado sobre la mesa al primer plano (o al fondo) de la capa en la que se encuentre en ese momento. Tenga en cuenta que debe pasar un objeto real, como por ejemplo uno que reciba en una llamada de retorno de un evento o al llamar a getObj o findObjs.
toAbove(obj, target) y toBelow(obj, target)
Solo para Mod Script Sandbox v1.5. Coloque el objeto inmediatamente por encima o por debajo del elemento de destino en el orden de superposición. El objetivo puede ser un objeto gráfico, de texto, de trazado o de trazado v2, o bien el identificador de uno de dichos objetos. Las funciones «toFront » y «toBack» toman el propio objeto. Esos mismos tipos también disponen de métodos de instancia toFront(), toBack(), toAbove(target) y toBelow(target).
Números aleatorios
enteroAleatorio(máximo)
Devuelve un número entero aleatorio comprendido entre 1 y max, utilizando el mismo generador que los dados de Roll20. Utilícelo para los dados. Math.floor(Math.random() * max) + 1 se distribuye de manera uniforme para los tamaños de dados con los que se suele jugar; el sesgo modular es un problema distinto (entero % n).
Math.random()
Puede llamar a Math.random() como de costumbre en sus scripts de mod, con la seguridad de que los resultados serán aleatorios, ya que la función «predeterminada» Math.random() de JavaScript ha sido sustituida por el generador de números aleatorios pseudorandom (PRNG) criptográficamente seguro que utiliza Roll20. Por lo tanto, los scripts existentes que utilizan Math.random() pueden emplearse con la certeza de que los resultados son realmente tan aleatorios como es posible conseguir en un ordenador.
Para lanzar un dado, utilice preferiblemente ` randomInteger(max)`. Es el mismo generador que utiliza el motor de dados.
El jugador es el GM
jugadorEsGM(idJugador)
Devuelve si ese jugador es actualmente un GM. Permite realizar ascensos y «reincorporarse como jugador» sin necesidad de reiniciar el juego. playerIsGM("API") es falso: el chat enviado mediante script utiliza el identificador de jugador «API», que no corresponde a ningún jugador del juego.
Personaje
setDefaultTokenForCharacter(personaje, token)
Establece el token predeterminado para el objeto Character proporcionado con los detalles del objeto Token proporcionado. Ambos objetos deben existir ya. Esto sobrescribirá cualquier token predeterminado asociado actualmente con el personaje.
Efectos especiales (FX)
spawnFx(x, y, tipo, idpágina)
Genera un efecto breve en la posición ( x,y ) del tipo indicado. Si omite el «pageid» o pasa un valor «undefined», se utilizará por defecto la página en la que se encuentran actualmente los jugadores (playerpageid en el objeto «Campaign»).
En el caso de los efectos integrados, el tipo debe ser una cadena de caracteres y corresponder a uno de los siguientes: color-del-rayo, color-de-la-bomba, color-del-aliento, color-de-las-burbujas, color-de-la-quema, color-de-la-explosión, color-del-resplandor, color-del-misil, color-de-la-nova, color-de-la-salpicadura
Donde «color», en lo anterior, puede ser uno de los siguientes: ácido, sangre, encanto, muerte, fuego, escarcha, sagrado, mágico, limo, humo o agua
Para los efectos personalizados, «type» debe ser el identificador del objeto «custfx» correspondiente al efecto personalizado.
spawnFxBetweenPoints(punto1, punto2, tipo, idpágina)
Funciona igual que `spawnFx`, pero en lugar de un único punto, se pasan dos puntos, con el formato {x: 100, y: 100}. Por ejemplo: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"). Los efectos de haz, respiración y salpicadura se desplazan entre ambos puntos. Las coordenadas corresponden a píxeles de la página; el espacioa la izquierda yarriba es el mismo que el de los gráficos. Las coordenadasx/y de ventanas y puertas utilizan el eje invertido y no se corresponden con estas coordenadas.
Los siguientes tipos de efectos deben utilizar siempre «spawnFxBetweenPoints» en lugar de «spawnFx»: «beam-color», «breath-color» y «splatter-color»
Solo para Mod Script Sandbox v1.5. Los efectos de tipo «viga» apuntan directamente al punto 2 (se ha corregido un error en el cálculo de ángulos).
spawnFxWithDefinition(x, y, definition, pageid)
Crea un efecto personalizado ad hoc en las coordenadas x e y. La definición es un objeto de JavaScript, no una cadena JSON. La forma es la misma que la de una definición de «Custom FX ». Si omite «pageid» o pasa un valor no definido, se utilizará la página actual de los jugadores (Campaign().get("playerpageid")).
Listas de reproducción de Jukebox
playJukeboxPlaylist(playlistid)
Toma el ID de la carpeta (que se obtiene de la propiedad _jukeboxfolder del objeto Campaign) de la lista de reproducción y comenzará a reproducirla para todos los jugadores.
detenerJukeboxListaDeReproducción()
No requiere ningún argumento y detendrá cualquier lista de reproducción que se esté reproduciendo en ese momento.
Varios
sendPing(izquierda, arriba, idPágina, idJugador, moverTodo, visiblePara)
Envía un «ping» a la superficie de la mesa (lo mismo que mantener pulsado el botón del ratón). «izquierda» y «arriba » se refieren a píxeles de la página. Es necesario indicar el «pageid ». «playerid» es opcional y constituye el cuarto argumento: el jugador al que se atribuye el ping. Si lo omite o pasa un valor falso, el ping se atribuirá a «api» (amarillo).
Pase «true» a «moveAll» para desplazar a los jugadores hasta ese punto. «visibleTo» limita quién puede ver el ping: un identificador de jugador, una lista de identificadores o una cadena separada por comas. Omítalo o introduzca «» para enviar un mensaje a todos.
Los retrasos de `setTimeout` del ejemplo que figura a continuación se borran si se reinicia el entorno de pruebas.
on("chat:message", function(msg) {
if (msg.type !== "api" || msg.content.indexOf("!pingtest") !== 0) return;
var players = findObjs({_type: "player"});
if (players.length < 1) return;
var player1 = players[0].id;
var player2 = players.length > 1 ? players[1].id : player1;
var allPlayerIDs = players.map(function(player) { return player.id; });
var pageid = Campaign().get("playerpageid");
// «pageid» es el tercer argumento; «playerid» es el cuarto. El atributo «null» asigna el ping a «api».
sendPing(300, 300, pageid, null, true);
setTimeout(function() {
// «» en «visibleTo» también envía un ping a todos
sendPing(1500, 500, pageid, msg.playerid, true, "");
}, 1000);
setTimeout(function() {
sendPing(1200, 500, pageid, null, true, player1);
}, 2000);
setTimeout(function() {
sendPing(900, 100, pageid, player2, true, [player1, player2]);
}, 3000);
setTimeout(function() {
sendPing(300, 300, pageid, player1, true, allPlayerIDs.join());
}, 4000);
});Una nota sobre distancias y cuadrículas en Roll20
En una cuadrícula cuadrada, una unidad equivale a 70 píxeles. El parámetro «snapping_increment» de la página indica el número de unidades que ocupa cada casilla de la cuadrícula; «scale_number» es la distancia que mide una unidad, y «scale_units» es el nombre de la unidad (a menudo «ft»). Los valores predeterminados son: 1 unidad = 5 pies = 1 cuadrado = 70 píxeles. Un director de juego puede establecer que 1 unidad equivalga a 10 pies, o que cada casilla equivalga a 2 unidades (140 píxeles).
Las cuadrículas hexagonales no utilizan ese cuadrado de 70 píxeles. Las posiciones de las ventanas y las puertas utilizan un eje Y invertido; las de la parte izquierda ysuperior del gráfico, no.