API: Eventos

Parâmetros de retorno de chamada

Quando se escuta um evento, cria-se uma função conhecida comocallback, que é executada sempre que o evento ocorre. A função de retorno de chamada recebe vários parâmetros que são objetos que fornecem as informações que você deseja saber sobre o evento, para que possa decidir o que fazer.

Os parâmetros de retorno de chamada para cada evento variam, mas incluem:

obj

O objeto que foi alterado. Quaisquer alterações que você fizer neste objeto também serão salvas no jogo. Portanto, se desejar mover um objeto gráfico para a esquerda, modifique a propriedadeesquerdadoobjusingset.

• obj.get("propriedade")retorna o valor atual da propriedade.
• obj.set("propriedade", "novovalor")define um novo valor para a propriedade. Caso esteja a alterar várias propriedades de uma só vez, é possível passar um objeto:obj.set({left: 10, top: 20});

anterior

Este é um objeto das propriedades doobj, tal como eram antes de quaisquer alterações terem sido feitas devido a este evento. Útil para determinar "quanto" uma propriedade mudou.

NOTA:Este é um objeto básico, portanto, você acessa as propriedades usando a notação de colchetes:prev["bar1_value"], NÃO usando as funções set ou get.

Ordenação de eventos

Os eventos são disparados de forma síncrona (o que significa que cada função não será iniciada até que a anterior tenha sido concluída) na ordem da primeira ligação à última ligação, e também de uma propriedade específica a um 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 propriedadeleftdos objetos for alterada, a ordem será function3, depois function1 e, por fim, function2.

Além disso, caso tenha vários scripts na sua campanha, eles serão carregados na mesma ordem em que aparecem na página Scripts da campanha, da esquerda para a direita.

Observação: os eventos são acionados apenas por alterações feitas pelos jogadores ou pelo GM que está conduzindo o jogo. Os eventos não serão acionados por alterações na API. Portanto, se um jogador mover uma peça na mesa, receberá um evento «alteração:gráfico». Se você modificar a propriedade do mesmo gráfico em um script Mod (API), não será acionado um evento "change:graphic".

Eventos da campanha

pronto

Este evento é acionado após todos os dados atuais da campanha terem sido carregados. Portanto, se desejar encontrar uma lista de todos os objetos em uma campanha ou um objeto específico que já esteja na campanha, certifique-se de procurá-lo somente após o evento pronto ser acionado. Além disso, se ligar paraadicionareventos (comoadd:graphic) antes do eventoreadyser disparado, receberá eventos add para objetos que já estavam presentes na campanha.

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

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 estiver definido comofalso (incluindo se um script Mod (API) o definir como falso), encerrará a ordem de jogada para todos os GMs/jogadores. Definir um ID de página válido irá abri-la para todos os GMs/jogadores.

Eventos de Objetos

alteração:gráfico

Ativado sempre que um objeto gráfico (que é praticamente qualquer tipo de objeto na mesa, incluindo fichas, mapas e cartas) é alterado.

Observação: os objetos gráficos criados pela API acionarão este evento ao serem criados.

Parâmetros de retorno de chamada: obj, prev

on("change:graphic", função(obj, prev) {    
  //Realizar uma ação 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 deseja executar apenas quando arotaçãomudar, deve fazer o seguinte:

on("change:graphic:rotation", function(obj, prev) {    
  //Sempre redefina a rotação para 0, para que ninguém possa girar objetos.    
  obj.set("rotação", 0);
});

adicionar:gráfico

Acionado sempre que um objeto gráfico é adicionado à mesa pela primeira vez. Também será chamado para objetos existentes quando o tabletop for iniciado, caso você vincule a este eventoforado eventoready.

Parâmetros de retorno de chamada: obj

on("add:graphic", function(obj) {
  //Será chamado para todos os novos gráficos, incluindo aqueles que já existiam no início da sessão de jogo.
});

var started = false;

on("ready", function() {
  on("add:graphic", function(obj) {
    //Será chamado apenas para novos objetos adicionados, uma vez que os objetos existentes já foram carregados antes do evento ready ser disparado.
  });
  //Também é possível definir uma variável e ignorar eventos de adição até que ela seja verdadeira.
  iniciado = verdadeiro;
});

destruir:gráfico

Acionado sempre que um objeto gráfico é removido da mesa.

Parâmetros de retorno de chamada: obj

Outros tipos de objetos

Existem também eventos para todos os outros tipos de objetos e subtipos, tais como:

alterar:caminho, adicionar:caminho, eliminar:caminho, alterar:texto, adicionar:texto, eliminar:texto, alterar:token, adicionar:token, eliminar:token, alterar:cartão, adicionar:cartão, eliminar:cartão

Consulte a referência Objetos para obter uma lista completa de todos os tipos e subtipos de objetos.