Scripts de mods: Eventos

Existen varios tipos diferentes de eventos a los que puede responder mediante on(event, callback). Existen cinco tipos de eventos: «ready», «change», «add», «destroy» y «chat». Salvo en el caso de «ready», el nombre incluye un tipo de objeto (o un mensaje, en el caso del chat), y «change» puede incluir una propiedad. Cada evento se activa una vez por cada objeto que sufra un cambio. Si se modifican varias propiedades del objeto al mismo tiempo, solo se activa un evento «global» (por ejemplo, «change:graphic»), además de cualquier evento específico de una propiedad que haya vinculado.

Parámetros de devolución de llamada

Cuando se escucha un evento, se crea una función denominada «callback» que se ejecuta cada vez que se produce dicho evento. La función de devolución de llamada recibe parámetros que le indican qué ha cambiado, de modo que pueda decidir qué hacer.

obj

El objeto que se modificó. Cualquier cambio que realice en este objeto también se guardará en el juego. Por lo tanto, si desea desplazar un objeto «Graphic» hacia la izquierda, deberá modificar la propiedad «left» de «obj» mediante el método «set».

• obj.get("property") devuelve el valor actual de la propiedad.
• obj.set("propiedad", "nuevo valor") establece un nuevo valor para la propiedad. Si va a modificar varias propiedades a la vez, puede pasar un objeto: obj.set({left: 10, top: 20}).

Anterior

Se trata de un objeto que recoge las propiedades del objeto «obj» tal y como eran antes de que se produjeran los cambios derivados de este evento. Resulta útil para determinar «en qué medida» ha cambiado una propiedad.

NOTA: «prev» no es un objeto de Roll20. Acceda a las propiedades mediante la notación entre corchetes o con punto: prev["bar1_value"] o prev._id. No puede utilizar los métodos «get» ni «set» con ella, y no puede omitir el guión bajo en las claves de solo lectura (prev.id no es lo mismo que prev._id).

En cuanto a los personajes y los documentos de apoyo, los campos «bio», «notas» y «notas del DJ» de «prev» son identificadores internos, no el texto. El carácter _defaulttoken también es un blob. «Graphic gmnotes » es una cadena de caracteres normal. Almacene usted mismo en la caché los valores anteriores de los blobs si los necesita.

Pedido de eventos

Los eventos se activan de forma sincrónica (cada función no se iniciará hasta que la anterior haya finalizado) en orden, desde el primero hasta el último vinculado, y también desde la propiedad específica hasta el objeto general. Entonces, dado lo siguiente:

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

Si la propiedad «left» del objeto cambiara, el orden sería: función 3, luego función 1 y, a continuación, función 2.

Si dispone de varios scripts en su campaña, estos se cargan en el mismo orden en que aparecen en la página de configuración de «Mod Scripts», de izquierda a derecha.

Nota: El método set() de un script no activa un evento de cambio para dicha propiedad. Si un jugador mueve una ficha, aparecerá «change:graphic». Si, a continuación, un script cambia a la izquierda mediante set(), ese cambio no activa el evento «change:graphic». Al crear un gráfico a partir de un script, se activa el evento change:graphic. La función sendChat() envía «chat:message», incluidos los mensajes que comienzan por «!».. Las propiedades «status_*» virtuales no activan sus propios eventos; debe escuchar el evento «change:graphic:statusmarkers».

listo

Este evento se activa una vez cada vez que se inicia el entorno de pruebas, una vez que se han cargado los datos de la campaña. Busque los objetos que ya existen solo cuando esté listo. Si configura la recepción de eventos «add» (como «add:graphic») antes de que se active «ready», también recibirá eventos «add» correspondientes a objetos que ya se encontraban en la campaña. Los scripts se cargan siguiendo el orden establecido en la configuración de «Mod Scripts», de izquierda a derecha; los controladores «ready» se ejecutan en el orden en que se han vinculado.

Parámetros de la función de devolución de llamada: ninguno

on("ready", function() {
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
});

Eventos de chat

chat:mensaje

Se activa cada vez que se recibe un nuevo mensaje de chat, incluidos los mensajes enviados mediante la función sendChat(). La función de llamada de retorno recibe un objeto «msg ». Los tipos de mensajes son: general, rollresult, gmrollresult, secretrollresult (/sr), supersecretrollresult (/ssr), emote, whisper, desc, direct y api. Mensajes que empiezan por ! tienen el tipo === «api» y no se muestran en el chat.

Parámetros de la llamada de retorno: msg

Consulte «Mod Scripts: Chat» para ver la lista completa de propiedades de «msg» y el manejo de los resultados de las tiradas.

Eventos de la campaña

El objeto «campaign» admite «change:campaign » y «change:campaign:PROPERTY» para cualquier propiedad de la campaña. A continuación se enumeran aquellos que la mayoría de los scripts tienen en cuenta:

cambio:campaña:id de la página del jugador

Se activa cada vez que cambia la página en la que se encuentran ustedes.

cambio:campaña:orden de turno

Se activa cada vez que cambia el orden de turno de la campaña.

cambio:campaña:página de la iniciativa

Se activa cada vez que se oculta o se muestra el orden de turno de una página. Es posible que no coincida con el ID de la página actualmente activa. Si se establece en «false» (incluso si un script de modificación lo establece en «false»), se cerrará el orden de turno para todos los GM y jugadores. Si se establece un ID de página válido, se abrirá para todos los GM/jugadores.

Eventos de objetos

Cada tipo de objeto admite:

• añadir:TIPO
• cambio:TIPO
• cambio:TIPO:PROPIEDAD
• destruir:TIPO

También puede vincularse a un identificador de objeto específico: change:TIPO:ID, change:TIPO:ID:PROPIEDAD y destroy:TIPO:ID.

Consulte «Mod Scripts: Objetos» para conocer las propiedades de cada tipo.

cambio:gráfico

Se activa cada vez que cambia un objeto gráfico (prácticamente cualquier objeto que se encuentre sobre la mesa de juego, incluidos fichas, mapas y cartas).

Nota: Los objetos gráficos creados mediante scripts activarán este evento en el momento de su creación.

Parámetros de la función de devolución de llamada: obj, prev

on("change:graphic", function(obj, prev) {
  //Haga algo con «obj» aquí. «prev» es una lista de valores anteriores.
  // Tenga en cuenta que «obj» y «prev» son TIPOS diferentes de objetos.
  // para trabajar con obj, debe utilizar obj.get("name");
  // para trabajar con prev, puede utilizar prev["name"];
});

cambio:gráfico:(propiedad)

También puede vincularse a un evento para cada propiedad específica del objeto. Por lo tanto, si tiene un script que desea ejecutar únicamente cuando cambie la rotación, debería hacer lo siguiente:

on("change:graphic:rotation", function(obj, prev) {
  //Establezca siempre la rotación en 0, de modo que nadie pueda girar los objetos.
  obj.set("rotation", 0);
});

añadir:gráfico

Se activa cada vez que se añade un objeto gráfico a la mesa por primera vez. También se invocará para los objetos existentes cuando se inicie la mesa virtual, si se establece una vinculación con este evento fuera del evento «ready ».

Parámetros de la función de devolución de llamada: obj

var started = false;
on("add:graphic", function(obj) {
  if (!started) return;
  // Solo se incluyen los gráficos añadidos una vez que esté todo listo.
});
on("ready", function() {
  started = true;
});

destruir:gráfico

Se activaba cada vez que se retiraba un objeto gráfico de la superficie de la mesa.

Parámetros de la función de devolución de llamada: obj

Subtipos gráficos

Los gráficos también disparan eventos utilizando su _subtype. Los mapas utilizan el subtipo «token ».

La «card» es tanto un tipo de objeto de Roll20 como un subtipo gráfico, por lo que los controladores para el evento «change:card» y otros similares deben aclarar el tipo de objeto (por ejemplo, mediante obj.get("_type")) para asegurarse de que se activan para el tipo de objeto correcto.

Todos los tipos de objetos

Todos los tipos que se indican a continuación admiten add:TYPE, change:TYPE, change:TYPE:PROPERTY y destroy:TYPE.

Solo para Mod Script Sandbox v1.5. Los objetos `pageFolder ` disponen de eventos `add:pageFolder`, `change:pageFolder`, `destroy:pageFolder` y eventos de propiedad como ` change:pageFolder:name`. Las páginas también activan los eventos «change:page:_placement » y «change:page:_path» cuando cambia la jerarquía del menú de la página.

Jumpgate / Los últimos tipos de objetos del motor VTT (pathv2, pin, window, door) son funciones del motor VTT, no de la versión «sandbox». Un juego de la versión 1.0 que utilice el motor VTT más reciente sigue contando con esos tipos de objetos y sus eventos.