API: Funções de Utilidade

Funções de utilidade são fornecidas para ajudá-lo a trabalhar consistentemente com o espaço de jogo Roll20. Você pode chamar uma função de utilidade de qualquer lugar em seus scripts (dentro de qualquer retorno de chamada de evento, por exemplo).


Underscore.js

Tem acesso à biblioteca Underscore.js (através do objeto global_) para ajudar a tornar as coisas mais fáceis. O Underscore fornece funções auxiliares para coisas como_.each(para iterar através de um array de objectos). Consulte a documentação doUnderscorepara obter mais informações.


Logging

log(mensagem)

Pode utilizar esta função para registar a saída na consola do Mod (API) na página do Editor de Scripts. Útil para depurar os seus scripts e compreender melhor o que está a acontecer dentro da sandbox do Mod (API).

on("change:graphic", function(obj) {    
  log("Ouviu a alteração para o ID do objeto: " + obj.id);
});

Ordenação de Objetos

toFront(obj)andtoBack(obj)

Essas duas funções moverão um objeto no jogo de tabuleiro para a frente (ou para trás) da camada em que ele está atualmente. Observe que você deve passar um objeto real, como aquele que você recebe em um retorno de chamada de evento ou chamandogetObjoufindObjs.


Números Aleatórios

randomInteger(max)

Utilize esta função para dados!Esta função tem em conta oModulo Biasque assegura que os números aleatórios resultantes também estão uniformemente distribuídos entre 1 e MAX.

Retorna um número inteiro aleatório, com o valor mais baixo sendo 1 e o valor mais alto sendomax. Essa é a mesma funcionalidade que o Roll20 usa para gerar seus lançamentos de dados, e esses números foram estatisticamente e rigorosamente comprovados como sendo aleatórios.

Math.random()

Pode chamar Math.random() como de costume nos seus scripts do Mod (API), confiando que os resultados serão aleatórios, pois o Math.random() "padrão" em Javascript foi substituído pelo PRNG criptograficamente seguro que alimenta o Roll20. Portanto, scripts existentes que usam Math.random() podem ser usados sabendo que os resultados são realmente tão próximos de aleatórios quanto possível em um computador.

Não use Math.random() se for desejada uma distribuição uniforme de números em um intervalo. Embora Math.random() forneça um número aleatório tão bom quanto o Roll20 pode gerenciar, a matemática para transformar esse número aleatório em um intervalo com distribuição uniforme (como um lançamento de dados) não é tão direta quanto a multiplicação com um módulo ou uma chamada de floor. UserandomInteger(max)para esses casos.


Player Is GM

playerIsGM(playerid)

A função Player Is GM retorna uma resposta booleana sobre se um jogador no jogo é um GM ou não. A função sempre irá retornar a resposta correta dependendo do momento atual, então mesmo que um MD escolha voltar a juntar-se como jogador ou um jogador seja promovido a MD a meio do jogo, playerIsGM() irá responder adequadamente sem necessidade de limpar um cache ou reiniciar a sandbox do Mod (API).


Personagem

setDefaultTokenForCharacter(character, token)

Define o token padrão para o Objeto de Personagem fornecido com os detalhes do Objeto de Token fornecido. Ambos os objetos devem existir previamente. Isso irá sobrescrever qualquer token padrão atualmente associado ao personagem.


Efeitos Especiais (FX)

spawnFx(x, y, tipo, pageid)

Cria um efeito breve na localização em x,y do tipo especificado. Se você omitir o pageid ou passar 'undefined', então a página em que os jogadores estão atualmente ('playerpageid' no objeto de Campanha) será usada por padrão.

Para efeitos incorporados, o tipo deve ser uma string e ser um dos seguintes:cor-raiocor-bombacor-soprocor-borbulhantecor-queimarcor-explosãocor-explodircor-brilhocor-míssilcor-novacor-salpicar

Onde "cor" acima é um dos:ácido,sangue,encanto,morte,fogo,gelo,sagrado,mágica,lodo,fumaça,água

Para efeitos personalizados, o tipo deve ser o ID do objeto custfx para o efeito personalizado.

spawnFxBetweenPoints(ponto1, ponto2, tipo, pageid)

Funciona da mesma forma que spawnFx, mas em vez de um único ponto, você passa dois pontos, no formato {x: 100, y: 100}. Por exemplo: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"); O efeito "viajará" entre os dois pontos para efeitos que suportam isso (os mesmos que permitem agência no lado do cliente).

Os seguintes tipos de efeito devem sempre usar spawnFxBetweenPoints em vez de spawnFx:cor-do-raio,cor-da-respiração,cor-do-espirro

spawnFxWithDefinition(x, y, definitionJSON, pageid)

Cria um efeito personalizado ad hoc usando o JSON para alguma definição de efeito na localização x, y. Se você omitir o pageid ou passar 'undefined', então a página em que os jogadores estão atualmente ('playerpageid' no objeto Campaign) será usada por padrão.

definitionJSON é um objeto javascript seguindo a especificação JSON paraCustom FX.


Lista de reprodução da Jukebox

playJukeboxPlaylist(playlistid)

A função play recebe o ID da pasta (obtido da propriedade "_jukeboxfolder" no objeto Campaign) da lista de reprodução e começará a reproduzir essa lista de reprodução para todos no jogo.

stopJukeboxPlaylist()

A função stop não requer nenhum argumento e interromperá qualquer lista de reprodução que esteja sendo reproduzida atualmente.


Diversificada

sendPing(left, top, pageid, (optional) playerid, (optional) moveAll, (optional) visibleTo)

Envia um "ping" para a mesa de jogo (o mesmo que se um jogador segurasse o botão do mouse). Você deve especificar as coordenadas superiores/esquerdas e o ID da página a ser pingada. Você pode opcionalmente especificar o ID de um jogador que realizou o ping - se você não o fizer, será assumido "api" e o ping será amarelo.

Você pode passar "true" para a opção moveAll se quiser mover as visualizações dos jogadores para essa localização também.

Você pode definir os IDs dos jogadores em visibleTo para os jogadores que podem ver ou ser movidos pelo ping. Isso é apresentado como um único ID de jogador, um array ou uma string delimitada por vírgulas.

on("chat:message", function(msg) {
  // Insira "!pingtest" no chat para executar o teste
  if(msg.type == "api" && msg.content.indexOf("!pingtest") !== -1) {
 
    // para obter um jogador específico, use findObjs({_type: "player"})[i].id em vez de null para o terceiro parâmetro
    jogadores = findObjs({_type: "player"});
    jogador1 = jogadores[1].id;
    jogador2 = jogadores[2].id;
 
    // Crie uma matriz de IDs de todos os jogadores
    var todosIDsJogadores = jogadores.map(function(jogador) {
      return jogador['id'];
    });
 
    // Ping todos nesta página para o mesmo local.
    sendPing(300, 300, Campaign().get('playerpageid'), null, true);
    setTimeout(function() {
        // Ping everyone on this page to the same location
        sendPing(1500, 500, Campaign().get('playerpageid'), msg.playerid, true, "");
    }, 1000);
    setTimeout(function() {
        // Ping only the specified player to this location
        sendPing(1200, 500, Campaign().get('playerpageid'), null, true, player1);
    }, 2000);
    setTimeout(function() {
        // Ping an array of player IDs (player 1 and 2) to this location
        sendPing(900, 100, Campaign().get('playerpageid'), player2, true, [player1, player2]);
    }, 3000);
    setTimeout(function() {
        // Ping a comma-separated list supplied as a string to this location
        sendPing(300, 300, Campaign().get('playerpageid'), player1, true, allPlayerIDs.join());
    }, 4000);
 
  }
})
 

A Note on Distances and Grids in Roll20

In Roll20, a "unit" is always 70 pixels on the screen. The "unit" is the building block that distance and the grid are built on top of. By default:

  • 1 unidade = 5 pés
  • 1 unidade = 1 quadrado da grade
  • Portanto, 5 pés = 1 unidade = 1 quadrado

No entanto, o GM pode alterar tanto o tamanho da grade quanto a escala da distância. 1 unidade sempre tem 70 pixels, mas o GM pode alterar as configurações para que 1 unidade seja agora 10 pés (ou seja, 70 pixels = 10 pés), ou que cada espaço da grade seja 2 unidades (ou seja, cada espaço da grade agora é 140 pixels).

Este artigo foi útil?
Utilizadores que acharam útil: 12 de 19