1. Centro de ayuda de Roll20
  2. Automatizaciones
  3. Scripts de mods (API)

Scripts de mod: Documentación de funciones

Roll20 pone a su disposición una serie de funciones que no forman parte del JavaScript básico ni de ninguna otra biblioteca.

Los juegos pueden ejecutar Mod Script Sandbox v1.0 (Campaign().sandboxVersion === «1.0») o v1.5 («1.5»). Funciones disponibles únicamente en Mod Script Sandbox v1.5. No funcionan en la versión 1.0.

Variables globales

Variable Descripción
_ Este es el objeto de espacio de nombres de la biblioteca Underscore.js.
estado Las propiedades del objeto de estado se mantendrán entre sesiones de juego.

_ (Guión bajo)

Este es el objeto de espacio de nombres de la biblioteca Underscore.js. Underscore tiene muchas funciones para la manipulación de colecciones.

estado

Las propiedades del objeto de estado se mantendrán entre sesiones de juego. El mismo objeto de estado también se comparte entre todos los scripts Mod de una campaña, por lo que se recomienda encarecidamente que, al escribir valores en el estado, reduzca al mínimo su huella para evitar conflictos de nombres. Nota: el estado se serializa con JSON, por lo que no puede almacenar funciones u objetos con referencias cíclicas.

Funciones globales

Tipo de retorno Función Descripción
Objeto Roll20 Campaña Obtiene el objeto único Campaign Roll20.
Objeto Roll20 crearObj Crea un nuevo objeto Roll20.
Matriz de objetos de Roll20 filtrarObjs Obtiene todos los objetos Roll20 que superan una prueba de predicado.
Matriz de objetos de Roll20 findObjs Obtiene todos los objetos Roll20 con propiedades que coinciden con un conjunto determinado de atributos.
Matriz de objetos de Roll20 obtenerTodosLosObjetos Obtiene todos los objetos Roll20 de la campaña.
varía obtenerAtributoPorNombre Obtiene el valor actual o máximo de un atributo del objeto Roll20.
varía getComputed Solo para Mod Script Sandbox v1.5. Obtiene una propiedad calculada de Beacon.
varía getSheetDefaultValue Obtiene el valor predeterminado de una ficha de personaje para un nombre de atributo.
varía getSheetItem Obtiene un elemento de la hoja (atributo; en la v1.5 también Beacon / user.*).
Objeto Roll20 getObj Obtiene un objeto Roll20 específico.
registro Registra un mensaje en la consola de salida de Mod.
en Registra un controlador de eventos.
onSheetWorkerCompleted Registra un controlador de eventos de una sola vez que se ejecutará una vez que se haya completado una pila completa de scripts de Sheet Worker.
ejecutarAcción Solo para Mod Script Sandbox v1.5. Realiza una acción de la hoja de Beacon.
Booleano jugadorEsGM Comprueba si un jugador tiene actualmente privilegios de GM.
playJukeboxLista de reproducción Comience a reproducir una lista de reproducción del jukebox.
Número entero aleatorio Genera un valor entero aleatorio.
enviarChat Envía un mensaje de chat.
enviarPing Envía un ping similar a mantener pulsado el botón izquierdo del ratón.
setAttrs Establece uno o varios atributos de un personaje.
setComputed Solo para Mod Script Sandbox v1.5. Establece una propiedad calculada de Beacon en la que se puede escribir.
setSheetItem Establece un elemento de hoja (atributo; en la versión 1.5 también Beacon / user.*).
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.
detenerJukeboxLista de reproducción Detiene todas las listas de reproducción que se están reproduciendo actualmente en el jukebox.
«toAbove» Solo para Mod Script Sandbox v1.5. Coloca un objeto inmediatamente encima de otro en la misma capa.
Atrás Coloca un gráfico, un texto, una ruta o una ruta v2 por debajo de los demás objetos de su capa.
a continuación Solo para Mod Script Sandbox v1.5. Coloca un objeto justo debajo de otro en la misma capa.
al frente Mueve un gráfico, un texto, una ruta o una ruta v2 por encima de los demás objetos de su capa. Pase el objeto, no un identificador.
Ayudas para las cartas shuffleDeck, cardInfo, recallCards, dealCardsToTurn, drawCard, pickUpCard, takeCardFromPlayer, playCardToTable, giveCardToPlayer — véase «Objetos: Baraja».

Campaña

Parámetros

Sin parámetros

Devoluciones

El objeto Roll20 de campaña única.

Ejemplos

var currentPageID = Campaign().get('playerpageid'),
  currentPage = getObj('page', currentPageID);

Campaign().sandboxVersion es «1.0» o «1.5». Campaign().nodeVersion es la cadena que indica la versión de Node.js. Solo para Mod Script Sandbox v1.5. sheetName, computedSummary y actionSummary. Véase «Objetos: Campaña».

crearObj

Parámetros

TIPO (cadena de caracteres) El tipo de objeto de Roll20 que se va a crear. Puede crear «gráfico», «texto», «trayectoria», «trayectoria v2», «carácter», «habilidad», «atributo», «folleto», «tabla desplazable», «elemento de tabla», «macro», «carta», «baraja», «efecto personalizado», «ventana», «puerta» y «marcador». Solo para Mod Script Sandbox v1.5. «pageFolder».

ATRIBUTOS (Objeto) Los valores iniciales que se utilizarán para las propiedades del objeto de Roll20.

Devoluciones

El objeto Roll20 que se ha creado.

Ejemplos

Al crear un objeto de Roll20 que tenga un objeto padre (como, por ejemplo, al crear un objeto de Roll20 de tipo «atributo», que es un objeto hijo de un objeto de Roll20 de tipo «personaje»), debe indicar el identificador del objeto padre en los atributos.

on('ready', function() {
  on('add:character', function(obj) {
    createObj('attribute', {
      name: 'Fuerza',
      current: 0,
      max: 30,
      characterid: obj.id
    });
  });
});

Al crear una ruta, indique la ruta (almacenada como _path) y el identificador de página (pageid). La ruta sin el guión bajo es el nombre que tenía en el momento de su creación. A partir de ese momento, solo se puede leer.

createObj('path', {
  pageid: Campaign().get('playerpageid'),
  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 «folleto» en Roll20, no es posible configurar el texto ni las notas del director de juego en el momento de la creación.

var handout = createObj('handout', {
  name: 'Una carta dirigida a usted',
  inplayerjournals: 'all',
  archived: false
});
handout.set('notes', 'Las notas solo se pueden configurar una vez creado el material de clase.');
handout.set('gmnotes', 'Configure las notas del director de juego en una llamada independiente de las notas.');

filtrarObj

Parámetros

CALLBACK (Función) Una función predicativa que se aplica a 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 los objetos Roll20 que se incluirán en el valor de retorno de `filterObjs`) o «false» (para todos los demás objetos Roll20).

Devoluciones

Una matriz de objetos Roll20 que han superado la prueba del predicado.

findObjs

Parámetros

ATRIBUTOS (Objeto) Una colección de pares clave:valor que se corresponden con los objetos de Roll20 en la campaña.

OPTIONS (objeto, opcional)

  • caseInsensitive: si el valor es «true», las comparaciones de cadenas no distinguen entre mayúsculas y minúsculas.
  • startsWith: si el valor es «true», los valores de cadena coinciden como prefijo.
  • tagMatch — al buscar coincidencias con etiquetas: «all» (por defecto; el objeto tiene todas las etiquetas indicadas), «any» (al menos una), «only» (exactamente el conjunto indicado).

Devoluciones

Una matriz de objetos de Roll20 cuyas propiedades coinciden con los atributos. En las claves se puede omitir el guión bajo inicial: tanto «type » como «_type» son válidos.

Ejemplos

var npcs = findObjs({ type: 'character', controlledby: '' });
var knights = findObjs({ type: 'character', name: 'Sir' }, { startsWith: true });

obtenerTodosLosObjetos

Parámetros

Sin parámetros

Devoluciones

Una matriz de todos los objetos Roll20 de la campaña.

obtenerAtributoPorNombre

Parámetros

CHARACTER_ID (cadena de caracteres) El identificador del personaje. ATTRIBUTE_NAME (cadena de caracteres) El nombre del atributo. VALUE_TYPE (cadena, opcional) «current» o «max» (el valor por defecto es «current»).

Devoluciones

La propiedad «current » o «max ». Si no se especifica, se utilizará el valor predeterminado de la ficha de personaje (si lo hay).

getComputed

Solo para Mod Script Sandbox v1.5. (En la versión 1.0, este nombre corresponde a un stub que no realiza ninguna operación.)

Parámetros

Un objeto: { characterId, property, args?, playerId? }.

Al utilizar una ficha de personaje de Beacon, obtiene el valor de una propiedad calculada. Enumere los nombres con Campaign().computedSummary. El «playerId» es opcional; algunas funciones de Beacon (por ejemplo, las consultas «roll») lo requieren.

getSheetDefaultValue

Parámetros

ATTRIBUTE_NAME (cadena de caracteres), VALUE_TYPE (cadena de caracteres, opcional) : «current» o «max».

Devoluciones

El valor predeterminado de la hoja para ese campo, no el valor real del carácter.

getSheetItem

Parámetros

getSheetItem(characterId, property, valtype?, options?) — asíncrono (Promise).

En la versión 1.0, esto sustituye a «getAttrByName». Solo para Mod Script Sandbox v1.5. En las hojas de Beacon también se leen propiedades calculadas y atributos personalizados denominados «user.*».

getObj

Parámetros

TIPO (cadena), ID (cadena)

Devoluciones

El objeto Roll20 especificado.

on('chat:message', function(msg) {
  var sendingPlayer = getObj('player', msg.playerid);
});

registro

Parámetros

MENSAJE (varía) Publicado en la consola de salida del módulo. Convertido con JSON.stringify.

Solo para Mod Script Sandbox v1.5. Los mensajes de error suelen incluir un objeto de contexto, como [Personaje de Roll20 -id].

en

Parámetros

EVENTO (cadena de caracteres) Existen cinco tipos de evento: «ready», «change», «add», «destroy» y «chat». Salvo en el caso de «ready», asigne un tipo de objeto al evento. En el caso del chat, ese tipo es siempre «mensaje». Los eventos de cambio también pueden indicar una propiedad, un identificador de objeto o ambos: change:graphic:left, change:graphic:ID, change:graphic:ID:left. Los gráficos también activan eventos de subtipo, como «change:token » y «change:dicetoken». Consulte la sección «Eventos».

Los eventos «ready » de la función CALLBACK no tienen parámetros de devolución de llamada. Los eventos de cambio cuentan con un parámetro «obj» (el objeto de Roll20 tras el cambio) y un parámetro «prev» (un objeto de JavaScript sin formato que contiene las propiedades anteriores al cambio). Las funciones «add events» tienen un parámetro «obj» (el nuevo objeto). Los eventos «destroy» tienen un parámetro «obj» (el objeto que ya no existe). Los eventos de chat cuentan con un parámetro «msg» (detalles del mensaje).

Devoluciones

(Nulo)

Los eventos se activan en el orden en que se registraron, y de más específico a menos específico. En este ejemplo, cualquier cambio en la propiedad «left» de un objeto gráfico de Roll20 provocará que se llame a la función 3, seguida de la función 1 y, a continuación, de la función 2.

on('change:graphic', función1);
on('change:graphic', función2);
on('change:graphic:left', función3);

La función «Añadir eventos» intentará activarse para los objetos de Roll20 que ya se encuentren en la campaña cuando comience una nueva sesión. Para evitar este comportamiento, puede esperar a registrar su evento «add » hasta que se active el evento «ready ».

on('add:graphic', function(obj) {
  // Cuando comience la sesión, se llamará a esta función para cada gráfico de la campaña
});
on('ready', function() {
  on('add:graphic', function(obj) {
    // Esta función se llamará *únicamente* cuando se cree un nuevo objeto gráfico de Roll20
  });
});

El parámetro «prev» de los eventos de cambio no es un objeto de Roll20. No puede utilizar «get» ni «set», y tampoco puede omitir los guiones bajos iniciales en las propiedades de solo lectura. Utilice «prev._id», no «prev.id».

En los campos «blob» de los personajes y de los documentos de apoyo (biografía, notas, notas del director de juego) y en el campo _defaulttoken del personaje, «prev» no es el texto. «Graphic gmnotes » es una cadena de caracteres normal. Almacene usted mismo en la caché los valores anteriores de los blobs si los necesita.

onSheetWorkerCompleted

Parámetros

CALLBACK (Función) Se invoca cuando finaliza la pila actual de scripts de Sheet Worker. Debe llamarse antes de «setWithWorker». Solo se ejecuta una vez. La función de devolución de llamada puede recibir { workersExecuted: boolean }.

ejecutarAcción

Solo para Mod Script Sandbox v1.5. (En la versión 1.0, este nombre es un stub sin funcionalidad.)

Parámetros

{ characterId, acción, args?, playerId? }

Realiza una acción de la hoja de Beacon. Enumere los nombres con Campaign().actionSummary. El «playerId» es opcional; algunas funciones de Beacon lo requieren. Si el nombre no corresponde a una acción de Beacon, la versión 1.5 podría recurrir a una habilidad de personaje con ese nombre mediante sendChat.

jugadorEsGM

Parámetros

PLAYER_ID (cadena de caracteres)

Devoluciones

es verdadero si el jugador tiene actualmente permisos de GM.

Resulta especialmente útil para restringir el uso de los comandos de Mod Script exclusivamente a los GM. Mantenga «msg.type !== 'api'» tal y como está escrito; ese es el tipo de mensaje de comando.

playJukeboxLista de reproducción

Parámetros

PLAYLIST_ID (cadena de caracteres) El identificador de la lista de reproducción cuya reproducción se va a iniciar.

entero aleatorio

Parámetros

MAX (Número) Máximo inclusivo.

Devoluciones

Un número entero aleatorio comprendido entre 1 y max. Es preferible utilizar esto en lugar de Math.random() para obtener rangos similares a los de unos dados.

sendChat asíncrono

Parámetros

SPEAKINGAS (cadena): un nombre, o jugador|id_jugador / personaje|id_personaje. MENSAJE (cadena de caracteres). CALLBACK (función, opcional): los resultados se envían a la función de devolución de llamada en lugar de aparecer en el chat. OPCIONES (Objeto, opcional) noarchive, use3d.

Consulte «Mod Scripts: Chat» para ver los botones de comando ([etiqueta](!command)).

enviarPing

Parámetros

IZQUIERDA, ARRIBA, PAGE_ID, PLAYER_ID (opcional), MOVEALL (opcional), VISIBLETO (opcional). Si se omite el «player_id», el ping aparece en amarillo. Si moveAll es «true», las vistas se centran en el punto de ping. «visibleTo» puede ser un identificador de jugador, una lista de identificadores o una cadena delimitada por comas.

setAttrs

Parámetros

CHARACTER_ID (cadena de caracteres), ATTRIBUTE_OBJ (objeto de nombre → valor). Los nombres que terminan en _max establecen el valor máximo. Se admiten $n nombres. options.silent utiliza «set » en lugar de «setWithWorker».

setComputed

Solo para Mod Script Sandbox v1.5.

{ characterId, property, args?, playerId? } — establece una propiedad calculada de Beacon en la que se puede escribir. Consulte Campaign().computedSummary.

setSheetItem

setSheetItem(identificadorDeCarácter, propiedad, valor, tipoDeValor?, opciones?) — asíncrono. En la versión 1.0 se establecen los atributos. Solo para Mod Script Sandbox v1.5. Asimismo, las propiedades calculadas de Beacon y los atributos personalizados «user.* ». Entre las opciones se incluyen «createAttr», «withWorker» y «allowThrow».

spawnFx

Parámetros

IZQUIERDA (Número) La coordenada x en la que se colocará el emisor de partículas. TOP (Número) La coordenada y. TIPO (cadena de caracteres) Para los efectos integrados, «tipo-color», donde «tipo» puede ser «bomba», «burbuja», «quemadura», «estallido», «explosión», «brillo», «misil» o «nova», y «color» puede ser «ácido», «sangre», «encanto», «muerte», «fuego», «hielo», «sagrado», «magia», «limo», «humo» o «agua». En el caso de los efectos personalizados, el identificador de un objeto ` custfx `. Nota: los efectos «beam», «breath» y «splatter» no se pueden utilizar con «spawnFx»; consulte «spawnFxBetweenPoints». PAGE_ID (cadena de caracteres, opcional); el valor por defecto es Campaign().get('playerpageid').

spawnFx(1400, 1400, 'burbujas de ácido');

spawnFxBetweenPoints

Parámetros

START (Objeto) { x, y }. END (Objeto) { x, y }. TYPE (cadena de caracteres) como spawnFx, además de «beam», «breath» y «splatter». PAGE_ID (cadena de caracteres, opcional).

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

Solo para Mod Script Sandbox v1.5. Los efectos de tipo «viga» apuntan directamente al punto final (se ha corregido un error en el cálculo de ángulos).

spawnFxWithDefinition

Parámetros

IZQUIERDA, ARRIBA, DEFINICIÓN (objeto que describe el emisor), PAGE_ID (opcional). Consulte el artículo «Efectos personalizados en los objetos» para conocer los nombres de las propiedades.

spawnFxWithDefinition(1400, 1400, {
  maxParticles: 200,
  size: 15,
  sizeRandom: 3,
  lifeSpan: 20,
  lifeSpanRandom: 5,
  speed: 7,
  speedRandom: 2,
  gravity: { x: 0,01, y: 0,65 },
  ángulo: 270,
  ánguloAleatorio: 35,
  tasaDeEmisión: 1,
  colorInicial: [0, 35, 10, 1],
  colorInicialAleatorio: [0, 10, 10, 0,25],
  colorFinal: [0, 75, 30, 0],
  colorFinalAleatorio: [0, 20, 20, 0]
});

detenerJukeboxLista de reproducción

Detiene todas las listas de reproducción del jukebox que se estén reproduciendo en ese momento.

detenerJukeboxListaDeReproducción();

Ayudas para las cartas

Disponible en ambas versiones de prueba. Encontrará toda la información en «Mod Scripts: Objetos (Cubierta)».

  • shuffleDeck(deckid, descartar, nuevoOrden)
  • cardInfo(configuración)
  • recallCards(deckid, type)
  • repartirCartasPorTurnos(idBaraja)
  • drawCard(idBaraja, idCarta)
  • pickUpCard(idDeLaTarjeta, deLaPilaDe Descartes)
  • takeCardFromPlayer(playerid, options)
  • playCardToTable(cardid, settings)
  • giveCardToPlayer(id_carta, id_jugador)

establecerTokenPredeterminadoParaPersonaje

CARÁCTER (objeto de carácter), TOKEN (objeto gráfico). Ambos deben existir ya. Escribe el blob _defaulttoken del personaje a partir del token. Esta es la forma de establecer ese campo; la función set() no lo hace.

«toAbove»

Solo para Mod Script Sandbox v1.5.

Parámetros

OBJ (gráfico, texto, trazado o trazado v2), TARGET (objeto o identificador).

Coloca el objeto «obj» justo encima del «target» en la misma capa.

Atrás / Adelante

OBJ debe ser un gráfico, un texto, una ruta o una ruta v2. Pase el objeto, no un identificador. En la versión 1.5, estas funciones son considerablemente más rápidas, y esos tipos también disponen de métodos de instancia toFront() y toBack().

a continuación

Solo para Mod Script Sandbox v1.5.

Coloca el objeto «obj» inmediatamente debajo del elemento de destino (objeto o identificador) en la misma capa.

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