São disponibilizadas funções utilitárias para o ajudar a trabalhar com o espaço de jogo do Roll20 de forma coerente. Pode chamar uma função utilitária a partir de qualquer ponto dos seus scripts (por exemplo, no interior de qualquer callback de evento). A referência completa às funções encontra-se em «Mod Scripts: Documentação das Funções».
Underscore.js
Tem acesso à biblioteca Underscore.js (através do objeto global _ ) para facilitar o trabalho. O Underscore disponibiliza funções auxiliares para operações como _.each (para percorrer um conjunto de objetos). Consulte a documentação do Underscore para obter mais informações.
Registo
log(mensagem)
Pode utilizar esta função para registar a saída na Consola de Saída do Mod, na página do Editor de Scripts. Útil para depurar os seus scripts e compreender melhor o que se passa no interior do Mod Script Sandbox.
on("change:graphic", function(obj) {
log("Detetada alteração no objeto com ID: " + obj.id);
});Apenas para o Mod Script Sandbox v1.5. Sempre que possível, as mensagens de erro incluem um objeto de contexto que identifica o objeto do Roll20 em causa, por exemplo:
ERRO: a função toBelow() deve ser chamada com um objeto gráfico, de texto ou de percurso do Roll20. Chamado com [Personagem do Roll20 -NM0tVij02hIfnoTdihc].
Encomenda de objetos
toFront(obj) e toBack(obj)
Estas duas funções irão deslocar um objeto na superfície de trabalho para a frente (ou para trás) da camada em que se encontra atualmente. Tenha em atenção que deve passar um objeto efetivo, como, por exemplo, aquele que recebe numa chamada de retorno de evento ou ao chamar as funções getObj ou findObjs.
toAbove(obj, target) e toBelow(obj, target)
Apenas para o Mod Script Sandbox v1.5. Coloque o objeto imediatamente acima ou abaixo do alvo na ordem de sobreposição. O alvo pode ser um objeto gráfico, de texto, de caminho ou «pathv2», ou ainda o identificador de um desses objetos. Os métodos toFront e toBack recebem o próprio objeto. Esses mesmos tipos dispõem também de métodos de instância toFront(), toBack(), toAbove(target) e toBelow(target).
Números aleatórios
número aleatório inteiro (máximo)
Devolve um número inteiro aleatório compreendido entre 1 e max, utilizando o mesmo gerador que os dados do Roll20. Utilize isto para os dados. Math.floor(Math.random() * max) + 1 apresenta uma distribuição uniforme para os tamanhos dos dados que as pessoas realmente lançam; o enviesamento modular é um problema diferente (inteiro % n).
Math.random()
Pode chamar a função Math.random() normalmente nos seus scripts de modificação, tendo a certeza de que os resultados serão aleatórios, uma vez que a função Math.random() «padrão» do JavaScript foi substituída pelo PRNG criptograficamente seguro que está na base do Roll20. Assim, os scripts existentes que utilizam Math.random() podem ser utilizados, sabendo-se que os resultados são, de facto, tão próximos do aleatório quanto é possível obter num computador.
Para um lançamento de dados, opte por utilizar o `randomInteger(max)`. É o mesmo gerador que o motor de dados utiliza.
O jogador é o GM
éGM(identificador do jogador)
Indica se esse jogador é, neste momento, um GM. Segue-se às promoções e à opção «voltar a entrar como jogador» sem necessidade de reiniciar. playerIsGM("API") é falso: a mensagem de chat enviada pelo script utiliza o ID de jogador «API», que não corresponde a um jogador no jogo.
Personagem
setDefaultTokenForCharacter(personagem, token)
Define o token padrão para o objeto Character fornecido com os detalhes do objeto Token fornecido. Ambos os objetos devem já existir. Isso substituirá qualquer token padrão atualmente associado ao personagem.
Efeitos Especiais (FX)
spawnFx(x, y, tipo, pageid)
Gera um efeito breve na localização x,y do tipo. Se omitir o «pageid» ou passar o valor «undefined», será utilizada, por predefinição, a página em que os jogadores se encontram atualmente (o «playerpageid» no objeto «Campaign»).
No caso dos efeitos integrados, o tipo deve ser uma cadeia de caracteres e corresponder a uma das seguintes opções: cor-do-feixe, cor-da-bomba, cor-do-sopro, cor-das-bolhas, cor-da-queimadura, cor-da-explosão, cor-da-detonação, cor-do-brilho, cor-do-míssil, cor-da-nova, cor-da-salpicadura
Em que «cor», no texto acima, pode ser uma das seguintes: ácido, sangue, encanto, morte, fogo, gelo, sagrado, magia, lodo, fumo, água
No caso de efeitos personalizados, «type» deve corresponder ao ID do objeto custfx do efeito personalizado.
spawnFxBetweenPoints(ponto1, ponto2, tipo, pageid)
Funciona da mesma forma que o `spawnFx`, mas, em vez de um único ponto, deve indicar dois pontos, no formato {x: 100, y: 100}. Por exemplo: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"). Os efeitos de feixe, respiração e salpicos deslocam-se entre os dois pontos. As coordenadas correspondem a píxeis da página, com o mesmo espaçoà esquerda e na parte superior que os elementos gráficos. As coordenadasx/y das janelas e portas utilizam o eixo invertido e não correspondem a estas coordenadas.
Os seguintes tipos de efeitos devem utilizar sempre o `spawnFxBetweenPoints` em vez do ` spawnFx`: `beam-color`, `breath-color`, ` splatter-color`
Apenas para o Mod Script Sandbox v1.5. Os efeitos do tipo «viga» apontam diretamente para o ponto 2 (foi corrigido um erro no cálculo do ângulo).
spawnFxWithDefinition(x, y, definição, id da página)
Cria um efeito personalizado ad hoc nos pontos x e y. A definição é um objeto JavaScript, não uma cadeia de caracteres JSON. A forma é idêntica à de uma definição «Custom FX ». Se omitir o «pageid» ou passar um valor indefinido, será utilizada a página atual dos jogadores (Campaign().get("playerpageid")).
Listas de reprodução da Jukebox
reproduzirJukeboxPlaylist(playlistid)
Recolhe o ID da pasta (obtido através da propriedade _jukeboxfolder no objeto Campanha) da lista de reprodução e dará início à reprodução dessa lista de reprodução para todos os participantes do jogo.
interromper a reprodução da lista de reprodução da jukebox
Não requer quaisquer argumentos e irá interromper qualquer lista de reprodução que esteja a ser reproduzida neste momento.
Diversos
sendPing(esquerda, topo, id da página, id do jogador, mover tudo, visível para)
Envia um sinal de ping para a mesa (o mesmo que manter o botão do rato premido). «esquerda» e «cima » referem-se aos píxeis da página. É necessário indicar o «pageid ». O «playerid» é opcional e constitui o quarto argumento: o jogador a quem o ping é atribuído. Se o omitir ou passar um valor falso, o ping é atribuído a «api» (amarelo).
Passe «true» à função «moveAll» para deslocar os jogadores até esse ponto. O parâmetro «visibleTo» limita quem vê o ping: um ID de jogador, um conjunto de IDs ou uma cadeia de caracteres delimitada por vírgulas. Omita-o ou passe «», para enviar um ping a todos.
Os atrasos do `setTimeout` no exemplo abaixo são anulados se a sandbox for reiniciada.
on("chat:message", function(msg) {
if (msg.type !== "api" || msg.content.indexOf("!pingtest") !== 0) return;
var players = findObjs({_type: "player"});
if (players.length < 1) return;
var player1 = players[0].id;
var player2 = players.length > 1 ? players[1].id : player1;
var allPlayerIDs = players.map(function(player) { return player.id; });
var pageid = Campaign().get("playerpageid");
// pageid é o terceiro argumento; playerid é o quarto. O valor «null» atribui o ping a «api».
sendPing(300, 300, pageid, null, true);
setTimeout(function() {
// "" para que o «visibleTo» também envie um ping a todos
sendPing(1500, 500, pageid, msg.playerid, true, "");
}, 1000);
setTimeout(function() {
sendPing(1200, 500, pageid, null, true, player1);
}, 2000);
setTimeout(function() {
sendPing(900, 100, pageid, player2, true, [player1, player2]);
}, 3000);
setTimeout(function() {
sendPing(300, 300, pageid, player1, true, allPlayerIDs.join());
}, 4000);
});Uma observação sobre distâncias e grades no Roll20
Numa grelha quadrada, uma unidade equivale a 70 píxeis. O valor «snapping_increment» da página corresponde ao número de unidades que cada espaço da grelha representa, «scale_number» é a distância de uma unidade e «scale_units» é o nome da unidade (geralmente «ft»). Os valores predefinidos são: 1 unidade = 5 pés = 1 quadrado = 70 píxeis. Um GM pode definir 1 unidade como 10 pés, ou cada quadrado como 2 unidades (140 píxeis).
As grelhas hexagonais não utilizam esse quadrado de 70 píxeis. As posições das janelas e portas utilizam um eixo Y invertido; as posições àesquerda/em cima no gráfico não o fazem.