Variables globales
Variable | Descripción |
---|---|
_ |
Este es el objeto de espacio de nombres para la biblioteca Underscore.js. |
estado |
Las propiedades del objeto estado persistirán entre las sesiones de juego. |
_ (Underscore)
Este es el objeto de espacio de nombres para la biblioteca Underscore.js. Underscore tiene muchas funciones para la manipulación de colecciones.
estado
Las propiedades del objeto estado persistirán entre sesiones de juego. El mismo objeto de estado también se comparte entre todos los scripts de Mod (API) en una campaña, por lo que se recomienda encarecidamente que al escribir valores en el estado, minimices tu huella tanto como sea posible para evitar colisiones de nombres. Nota: el estado se serializa con JSON, por lo que no se pueden almacenar funciones u objetos con referencias cíclicas.
Funciones Globales
Tipo de retorno | Función | Descripción |
---|---|---|
Objeto Roll20 | Campaña |
Obtiene el objeto Roll20 de la campaña única. |
Objecto Roll20 | crearObj |
Crea un nuevo objeto Roll20. |
Array de objetos Roll20 de | filtrarObjs |
Obtiene todos los objetos Roll20 que pasan una prueba de predicado. |
Array de objetos Roll20 de | buscarObjs |
Obtiene todos los objetos Roll20 con propiedades que coinciden con un conjunto dado de atributos. |
Array de objetos Roll20 de | obtenerTodosObjs |
Obtiene todos los objetos Roll20 en la campaña. |
varías | getAttrByName |
Obtiene el valor actual o máximo de un objeto Roll20 de atributo. |
objeto Roll20 | getObj |
Obtiene un objeto Roll20 específico. |
u |
Registra un mensaje en la consola de Mod (API). | |
activado |
Registra un controlador de eventos. | |
onSheetWorkerCompleted |
Registra un controlador de eventos único para ejecutarse después de que se complete una pila completa de Scripts de Trabajadores de Hojas. | |
Booleano | playerIsGM |
Comprueba si un jugador actualmente tiene privilegios de GM. |
playJukeboxPlaylist |
Comienza a reproducir una lista de reproducción del jukebox. | |
Número | randomInteger |
Genera un valor de entero aleatorio. |
sendChat |
Envía un mensaje de chat. | |
sendPing |
Envía un ping similar a mantener presionado el botón izquierdo del ratón. | |
spawnFx |
Genera un emisor de partículas. | |
spawnFxBetweenPoints |
Genera un emisor de partículas que se mueve de un punto a otro. | |
spawnFxWithDefinition |
Genera un emisor de partículas que no está representado por un objeto FX Roll20. | |
stopJukeboxPlaylist |
Detiene todas las listas de reproducción del jukebox que se están reproduciendo en este momento. | |
hacia atrás |
Mueve un objeto gráfico Roll20 debajo de todos los demás gráficos en la misma capa del tablero. | |
hacia el frente |
Mueve un objeto gráfico Roll20 por encima de todos los demás gráficos en la misma capa del tablero. |
Campaña
Parámetros
Sin parámetros
Devuelve
El objeto de campaña único de Roll20.
Ejemplos
var currentPageID = Campaign().get('playerpageid'), currentPage = getObj('page', currentPageID);
createObj
Parámetros
TIPO(Cadena) El tipo de objeto de Roll20 a crear. Solo se pueden crear 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' y 'macro'.ATRIBUTOS(Objeto) Los valores iniciales que se utilizarán para las propiedades del objeto de Roll20.
Devuelve
El objeto de Roll20 que se creó.
Ejemplos
Al crear un objeto de Roll20 que tiene un objeto padre (por ejemplo, al crear un objeto de atributo de Roll20, que es un hijo de un objeto de personaje de Roll20), debes proporcionar el id del padre enattributes
.
on('add:character', function(obj) { createObj('attribute', { name: 'Strength', current: 0, max: 30, characterid: obj.id }); });
Al crear un objeto de ruta en Roll20, debes proporcionar un valor para la propiedad de solo lectura_path
. Esta es una excepción a la regla que impide establecer el valor de propiedades de solo lectura al crear objetos en 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 de documento en Roll20, no puedes establecer el texto o 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' });
filterObjs
Parámetros
CALLBACK(Function) Una función de predicado para probar todos los objetos de Roll20. La función de devolución de llamada recibe un objeto Roll20 como parámetro y debe devolver true (para objetos Roll20 que se incluirán en el valor de retorno de filterObjs) o false (para todos los demás objetos Roll20).
Devuelve
Una matriz de objetos Roll20 que pasaron 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(Object) Una colección de pares clave:valor para que coincida con objetos Roll20 en la campaña. OPTIONS(Object, opcional) Si options.caseInsensitive es true, las comparaciones de cadenas entre objetos Roll20 y atributos serán insensibles a mayúsculas y minúsculas.
Devuelve
Un array de objetos Roll20 con propiedades que coinciden conatributos
.
Ejemplos
var npcs = findObjs({ type: 'character', controlledby: '' });
getAllObjs
Parámetros
Sin parámetros
Devuelve
Un array de todos los objetos Roll20 en la campaña.
Ejemplos
var everything = getAllObjs();
getAttrByName
Parámetros
CHARACTER_ID(String) El ID del objeto Roll20 de personaje que es el padre del objeto Roll20 de atributo del cual quieres obtener el valor.ATTRIBUTE_NAME(String) El nombre del objeto Roll20 de atributo del cual quieres obtener el valor.VALUE_TYPE(String, opcional) Ya sea "actual" o "máximo" (por defecto es "actual" si se omite).
Regresa
La propiedadactual
omax
del atributo apropiado. Si la propiedad deseada no está configurada, se utilizará en su lugar el valor predeterminado especificado por la hoja de personaje (si hay una configuración predeterminada).
Ejemplos
var character = getMyCharacter(), strength = getAttrByName(character.id, 'strength'), strength_max = getAttrByName(character.id, 'strength', 'max');
getObj
Parámetros
TIPO(String) El tipo de objeto Roll20 para obtener.ID(String) El ID único del objeto Roll20 para obtener.
Regresa
El objeto Roll20 especificado.
Ejemplos
on('chat:mensaje', function(msg) { var sendingPlayer = getObj('player', msg.playerid); });
registro
Parámetros
MENSAJE (varía) El mensaje a publicar en la consola de Mod (API). El parámetro mensaje se transformará en un String con JSON.stringify.
Devuelve
(Vacío)
Ejemplos
on('chat:mensaje', function(msg) { log('Mensaje recibido de:'); log(getObj('jugador', 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":""}
activado
Parámetros
EVENTO(String) Hay cinco tipos de eventos: ready, change, add, destroy, chatA excepción de ready, todos los tipos de eventos también deben ir acompañados de un tipo de objeto. Para chat, esto es siempre mensaje. Para todo lo demás, esto es la propiedad tipo de un objeto Roll20. Además del tipo de objeto, los eventos de cambio también pueden especificar opcionalmente una propiedad del objeto Roll20 especificado.Las partes 2-3 del evento (tipo, objeto y opcionalmente propiedad) están separadas por dos puntos. Por lo tanto, las cadenas de evento válidas incluyen pero no se limitan a "ready", "chat:mensaje", "change:gráfico", "change:campaña:playerpageid", "add:personaje" y "destroy:handout".LLAMADA(Función) La función que se llamará 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 como existe después del cambio, y un parámetro prev, que es un objeto JavaScript simple 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.
Retorna
(Void)
Ejemplos
Los eventos se disparan en el orden en que se registraron y de más específico a menos específico. En este ejemplo, un cambio en la propiedadleft
de un objeto Roll20 gráfico hará que se llame afunction3
, seguida defunction1
y luegofunction2
.
on('change:graphic', function1); on('change:graphic', function2); on('change:graphic:left', function3);
addlos eventos intentarán dispararse para los objetos Roll20 que ya estén en la campaña cuando se inicie una nueva sesión. Para evitar este comportamiento, puedes esperar a registrar tuañadirevento hasta que ocurra el eventolisto.
on('add:graphic', function(obj) { // Cuando comienza la sesión, esta función se llamará para cada gráfico en la campaña // Esta función también se llamará cada vez que se crea un nuevo objeto gráfico de Roll20 }); on('ready', function() { on('add:graphic', function(obj) { // Esta función se llamará *solo* cuando se crea un nuevo objeto gráfico de Roll20, no para los que ya existen }); });
El parámetropre
para eventoschange no es un objeto de Roll20, es un objeto de JavaScript antiguo. Como tal, no puedes usar las funcionesget
oset
, y no puedes omitir los guiones bajos iniciales en las propiedades de solo lectura.
en('change:graphic', function(obj, prev) { var id1 = obj.id, // todos son equivalentes id2 = obj.get('id'), id3 = obj.get('_id'), id4 = prev.id, // no definido 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 el juego de mesa });
Para los campos asíncronos de los objetos personaje y anotación de Roll20 (notas
, notasgm
, y biografía
), el parámetro prev
no contendrá los datos que necesitas. (En su lugar, tendrá un identificador numérico utilizado por el sistema.) Si necesitas acceder al valor anterior de uno de estos campos, tendrás que llevar un registro de ello tú mismo:
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; // do stuff... if (shouldRevertBio()) { obj.set('bio', state.example.bioCache[obj.id]); } }); });
onSheetWorkerCompleted
Parameters
CALLBACK(Function) The function that will be called when the current 'stack' of Sheet Worker Scripts completes.
Returns
(Void)
Examples
This function is intended to be called prior to setWithWorker. Thecallback
function will be called only once.
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]; // do something with calculatedAttr.get('current'); }); mySourceAttr.setWithWorker({ current: 5 });
playerIsGM
Parámetros
PLAYER_ID(String) El id del objeto Roll20 del jugador para verificar.
Devuelve
true
si el jugador actualmente tiene permisos de GM, o false
de lo contrario.
Ejemplos
Esta función es especialmente útil para limitar los comandos de Mod (API) al uso por parte del 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; // ... } });
playJukeboxPlaylist
Parámetros
PLAYLIST_ID(String) El id de la lista de reproducción que se va a empezar a reproducir.
Devuelve
(Vacío)
Ejemplos
var playlists = JSON.parse(Campaign().get('jukeboxfolder')), myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName); playJukeboxPlaylist(myPlaylist.id);
randomInteger
Parámetros
MAX(Número) El número máximo a devolver, inclusive.
Retorna
Un número entero aleatorio entre 1 (inclusive) y max
(inclusive). Esta función tiene una mejor distribución que Math.random()
, y se recomienda utilizarla en su lugar. Esta función no utiliza la función Quantum Roll de de la misma manera que el motor de dados, pero utiliza el mismo algoritmo seudorandom que el motor de dados utilizará como último recurso si Quantum Roll no está disponible.
Ejemplos
Dado que esta función devuelve un número entero de 1 amáx
, es ideal para generar rápidamente el resultado de una tirada de dados si no necesita toda la potencia del motor de dadosde Roll20.
var d20Result = randomInteger(20); // aproximadamente equivalente a lanzar un dado de 20 caras
sendChat Asíncrono
Parámetros
SPEAKINGAS(String) El nombre que se adjuntará al mensaje enviado. Si speakingAs está en formato player|player_id o character|character_id, el mensaje se enviará como ese jugador o personaje. De lo contrario, el mensaje usará el nombre proporcionado como si un DJ hubiera utilizado el comando /as.MENSAJE(String) El mensaje que se enviará al chat.CALLBACK(Function, opcional) Si se especifica callback, el resultado del mensaje de chat se pasará a él en lugar de aparecer en el chat. El parámetro del método de callback es una matriz de objetos de mensajes.OPTIONS(Object, opcional) Si options.noarchive es verdadero, el mensaje no se agregará al archivo de chat. Si options.use3d es verdadero, los lanzamientos 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.
Devuelve
(Vacío)
Ejemplos
sendChat('Ejemplo', 'Este es un ejemplo simple.');
Puedes escribir fácilmente código para enviar un mensaje como el mismo jugador o personaje que activó un evento de chat.
on('chat:message', function(msg) { var character = findObjs({ type: 'character', name: msg.who })[0], player = getObj('player', msg.playerid), message = ' dijo algo'; if (character) sendChat('character|'+character.id, character.get('name')+message); else sendChat('player|'+player.id, player.get('displayname')+message); });
El parámetrocallback
es útil si necesita aprovechar el motor de dadosde Roll20. No es especialmente necesario un valorspeakingAs
cuando se utiliza la llamada de retorno, ya que el mensaje no aparecerá en el chat de todos modos.
sendChat('', '/r 2d20k1+'+strengthMod, function(ops) { var msg = ops[0]; // ... });
options.noarchive
está diseñado principalmente para enviar a los jugadores menús hechos con botones de comando de la APIsin atascar su historial de chat.
sendChat('System', '[Borrar cambios](!clear)\n[Añadir ficha](!add)\n[Ver muestra](!view)\n[Guardar diseño](!save)', null, { noarchive: true });
sendPing
Parámetros
IZQUIERDA(número) La coordenada x donde colocar la marca.ARRIBA(número) La coordenada y donde colocar la marca.PAGE_ID(cadena) El ID del objeto Roll20 de la página en la que colocar la marca.PLAYER_ID(cadena, opcional) La marca usará el color del jugador especificado. Si se omite player_id, la marca será amarilla.MOVEALL(booleano, opcional) Si moveAll es true, las vistas de todos los jugadores en la página correspondiente se centrarán en la marca.
Nota:En este momento, solo los GM tendrán sus vistas centradas si moveAll
es true
. Este comportamiento está documentadoaquí
Devuelve
(Vacío)
Ejemplos
on('chat:mensaje', 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); // centre a todos en el token seleccionado } });
spawnFx
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.TIPO(Cadena) El tipo de emisor de partículas a colocar. Para los efectos incorporados, debe ser "tipo-color", donde tipo es uno de bomba, burbujeo, quemadura, estallido, explosión, resplandor, misil o nova y color es uno de ácido, sangre, encanto, muerte, fuego, escarcha, sagrado, magia, limo, humo o agua. Para efectos personalizados, esto debería ser el id del objeto FX de Roll20. Nota: los tipos de haz, aliento y salpicadura no se pueden usar con spawnFx. Ver spawnFxBetweenPoints en su lugar. PAGE_ID(String, opcional) El id del objeto de página de Roll20 en el que colocar el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.
Regresa
(Void)
Ejemplos
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxBetweenPoints
Parámetros
START(Object) El punto de inicio para el emisor de partículas. El punto debe estar en el formato { x: número, y: número }. END(Object) El punto final para el emisor de partículas. El punto debe estar en el formato { x: número, y: número }. TYPE(String) El tipo de emisor de partículas que se va a colocar. Para efectos incorporados, esto debería ser "tipo-color", donde el tipo es uno de rayo, bomba, aliento, burbujeante, quemar, explosión, resplandor, misil, nova o salpicadura, y el color es uno de ácido, sangre, encanto, muerte, fuego, escarcha, sagrado, mágico, limo, humo o agua. Para efectos personalizados, esto debería ser el id del objeto FX Roll20 de la página. PAGE_ID (String, opcional) El id del objeto de la página Roll20 para colocar el emisor de partículas. Si se omite, se usará Campaign().get('playerpageid') en su lugar.
Devuelve
(Void)
Ejemplos
spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');
spawnFxWithDefinition
Parámetros
LEFT(Number) La coordenada x para colocar el emisor de partículas. TOP(Number) La coordenada y para colocar el emisor de partículas. DEFINITION(Object) Las características del emisor de partículas para colocar. Consulte Custom FX para obtener una lista de propiedades posibles y las propiedades de los tipos y colores de emisores de partículas predeterminados. Mira la biblioteca de efectos FX para algunos efectos personalizados que los usuarios de Roll20 han creado. PAGE_ID (String, opcional) El id de la página Roll20 en la que se colocará el emisor de partículas. Si se omite, se utilizará Campaign().get('playerpageid') en su lugar.
Devuelve
(Void)
Ejemplos
// estos dos son equivalentes spawnFx(1400, 1400, 'bubbling-acid'); spawnFxWithDefinition(1400, 1400, { maxParticles: 200, tamaño: 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] });
stopJukeboxPlaylist
Parámetros
Sin parámetros
Devuelve
(Vacío)
Ejemplos
stopJukeboxPlaylist();
toBack
Parámetros
OBJ(OBJETO Roll20) El objeto Roll20 para enviar al fondo de su capa.
Devuelve
(Vacío)
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)); }); } });
toFront
Parametros
OBJ(objeto de Roll20) El objeto Roll20 para llevar al frente de su capa.
Devuelve
(Vacío)
Ejemplos
on('ready', function() { on('add:graphic', function(obj) { toFront(obj); }); });