Scripts de modificação: Eventos

Existem vários tipos diferentes de eventos aos quais pode responder utilizando on(event, callback). Existem cinco tipos de eventos: ready, change, add, destroy e chat. Com exceção de «ready», o nome inclui um tipo de objeto (ou mensagem, no caso do chat), e «change» pode incluir uma propriedade. Cada evento é acionado uma vez por cada objeto que sofre uma alteração. Se mais do que uma propriedade do objeto for alterada ao mesmo tempo, apenas um evento «global» (por exemplo, change:graphic) é acionado, além de quaisquer eventos específicos de propriedade que tenha associado.

Parâmetros de retorno de chamada

Quando escuta um evento, cria uma função conhecida como «callback», que é executada sempre que o evento ocorre. A função de retorno recebe parâmetros que indicam o que mudou, para que possa decidir o que fazer.

obj

O objeto que foi alterado. Quaisquer alterações que você fizer neste objeto também serão salvas no jogo. Portanto, se pretender deslocar um objeto «Graphic» para a esquerda, deverá modificar a propriedade «left» do «obj» utilizando o comando «set».

• obj.get("property") devolve o valor atual da propriedade.
• obj.set("propriedade", "novo valor") define um novo valor para a propriedade. Se pretender alterar várias propriedades de uma só vez, pode passar um objeto: obj.set({left: 10, top: 20}).

anterior

Trata-se de um objeto que contém as propriedades do «obj» tal como se encontravam antes de terem sido efetuadas quaisquer alterações decorrentes deste evento. Útil para determinar «em que medida» um imóvel sofreu alterações.

NOTA: «prev» não é um objeto do Roll20. Aceda às propriedades utilizando a notação entre parênteses ou com ponto: prev["bar1_value"] ou prev._id. Não é possível chamar os métodos get / set nessa chave, nem omitir o sublinhado nas chaves de leitura exclusiva (prev.id não é prev._id).

No que diz respeito às personagens e aos documentos de apoio, os campos «bio», «notas» e «notas do mestre» na versão anterior são identificadores internos, não o texto propriamente dito. A variável _defaulttoken é também um blob. O gráfico «gmnotes» é uma cadeia de caracteres comum. Guarde na cache os valores anteriores dos blobs, caso precise deles.

Ordenação de eventos

Os eventos são disparados de forma síncrona (cada função só é executada depois de a anterior ter terminado) por ordem, desde a primeira propriedade vinculada até à última, e também desde a propriedade específica até ao objeto geral. Considerando o seguinte:

on("alteração:gráfico", função1);
on("alteração:gráfico", função2);
on("alteração:gráfico:esquerda", função3);

Se a propriedade «left» do objeto fosse alterada, a ordem seria: função3, depois função1 e, por fim, função2.

Se tiver vários scripts na sua campanha, estes são carregados na mesma ordem em que aparecem na página de definições «Mod Scripts», da esquerda para a direita.

Nota: O método set() de um script não dispara um evento de alteração para essa propriedade. Se um jogador mover uma ficha, é-lhe apresentado o elemento «change:graphic». Se, posteriormente, um script alterar o valor de «left» com a função set(), essa alteração não aciona o evento «change:graphic». A criação de um gráfico a partir de um script ativa o evento change:graphic. A função sendChat() aciona o chat:message, incluindo as mensagens que começam com !. As propriedades «status_*» virtuais não disparam os seus próprios eventos; esteja atento a «change:graphic:statusmarkers».

pronto

Este evento é acionado uma vez sempre que a sandbox é iniciada, após o carregamento dos dados da campanha. Procure os objetos que já existem apenas quando estiver pronto. Se definir uma ligação para receber eventos de adição (tais como «add:graphic») antes de o evento «ready» ser disparado, receberá também eventos de adição relativos a objetos que já se encontravam na campanha. Os scripts são carregados pela ordem definida nas definições do Mod Scripts, da esquerda para a direita; os handlers «ready» são executados pela ordem em que foram associados.

Parâmetros de callback: nenhum

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

Eventos de chat

chat:mensagem

É acionado sempre que é recebida uma nova mensagem de chat, incluindo as mensagens enviadas através da função sendChat(). A função de retorno recebe um objeto `msg`. Os tipos de mensagem incluem: geral, rollresult, gmrollresult, secretrollresult (/sr), supersecretrollresult (/ssr), emote, sussurro, desc, direta e API. Mensagens que começam por ! têm o tipo === «api» e não são apresentadas no chat.

Parâmetros de callback: msg

Consulte «Mod Scripts: Chat» para obter a lista completa das propriedades «msg» e para saber como tratar os resultados dos lançamentos.

Eventos da campanha

O objeto «campaign» suporta os atributos «change:campaign » e «change:campaign:PROPERTY» para qualquer propriedade da campanha. A seguir, apresentam-se os eventos que a maioria dos scripts monitoriza:

alteração:campanha:identificador da página do jogador

Disparado sempre que a página em que os jogadores estão atualmente é alterada.

alteração:campanha:ordem de jogada

Disparado sempre que a ordem de turno da campanha é alterada.

alteração: campanha: página da iniciativa

Disparado sempre que a ordem do turno é ocultada ou exibida para uma página. Este pode não ser o mesmo que o ID da página atualmente ativa. Se este valor estiver definido como «false» (incluindo se um script de modificação o definir como «false»), a ordem de jogada será encerrada para todos os GMs/jogadores. Definir um ID de página válido irá abri-la para todos os GMs/jogadores.

Eventos de Objetos

Cada tipo de objeto suporta:

• adicionar:TIPO
• alteração:TIPO
• alteração:TIPO:PROPRIEDADE
• destruir:TIPO

Também pode associar a um ID de objeto específico: change:TIPO:ID, change:TIPO:ID:PROPRIEDADE e destroy:TIPO:ID.

Consulte «Mod Scripts: Objetos» para conhecer as propriedades de cada tipo.

alteração:gráfico

É acionado sempre que um objeto gráfico (praticamente qualquer objeto presente no tabuleiro, incluindo fichas, mapas e cartas) sofre uma alteração.

Nota: Os objetos gráficos criados por scripts irão desencadear este evento no momento da sua criação.

Parâmetros de callback: obj, prev

on("change:graphic", function(obj, prev) {
  //Faça algo com «obj» aqui. "prev" é uma lista de valores anteriores.
  // Observe que "obj" e "prev" são tipos diferentes de objetos.
  // para trabalhar com obj, é necessário utilizar obj.get("name");
  // para trabalhar com prev, pode-se utilizar prev["name"];
});

alteração:gráfico:(propriedade)

Também é possível associar um evento a cada propriedade específica do objeto. Portanto, se tiver um script que pretenda executar apenas quando a rotação mudar, deve proceder da seguinte forma:

on("change:graphic:rotation", function(obj, prev) {
  //Defina sempre a rotação de volta a 0, para que ninguém possa rodar os objetos.
  obj.set("rotação", 0);
});

adicionar:gráfico

Acionado sempre que um objeto gráfico é adicionado à mesa pela primeira vez. Será também chamado para os objetos existentes quando a mesa for iniciada, caso se associe a este evento fora do evento «ready ».

Parâmetros da função de retorno: obj

var started = false;
on("add:graphic", function(obj) {
  if (!started) return;
  // Apenas elementos gráficos adicionados após a finalização da inicialização.
});
on("ready", function() {
  started = true;
});

destruir:gráfico

É acionado sempre que um objeto gráfico é removido da superfície da mesa.

Parâmetros da função de retorno: obj

Subtipos gráficos

Os gráficos também disparam eventos utilizando o seu _subtype. Os mapas utilizam o subtipo «token ».

O «cartão» é simultaneamente um tipo de objeto do Roll20 e um subtipo gráfico; por isso, os manipuladores para o evento «change:card» e eventos semelhantes têm de esclarecer o tipo de objeto (por exemplo, obj.get("_type")) para se certificarem de que estão a ser acionados para o tipo correto de objeto.

Todos os tipos de objetos

Todos os tipos abaixo suportam add:TYPE, change:TYPE, change:TYPE:PROPERTY e destroy:TYPE.

Apenas para o Mod Script Sandbox v1.5. Os objetos `pageFolder ` dispõem dos eventos `add:pageFolder`, ` change:pageFolder`, `destroy:pageFolder` e de eventos de propriedade, tais como `change:pageFolder:name`. As páginas também disparam os eventos change:page:_placement e change:page:_path quando a hierarquia do menu da página se altera.

Jumpgate / Os tipos de objetos mais recentes do motor VTT (pathv2, pin, window, door) são funcionalidades do motor VTT, e não da versão sandbox. Um jogo da versão 1.0 na mais recente versão do motor VTT ainda possui esses tipos de objetos e os respetivos eventos.