API: Documentação da função

Variáveis globais

_ (Sublinhado)

Este é o objeto namespace para o Underscore.js . O Underscore possui diversas funções para manipulação de coleções.

estado

As propriedades do objeto de estado serão mantidas entre as sessões do jogo. O mesmo objeto de estado também é partilhado entre todos os scripts Mod (API) numa campanha, portanto, é altamente recomendável que, ao gravar valores no estado, minimize a sua pegada o máximo possível para evitar colisões de nomes. Observação: o estado é serializado com JSON, portanto, não é possível armazenar funções ou objetos com referências cíclicas.

Funções Globais

Campanha

Parâmetros

Sem parâmetros

Devoluções

O objeto Roll20 da campanha singleton.

Exemplos

var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('page', currentPageID);

criarObj

Parâmetros

TYPE(String) O tipo de objeto Roll20 a ser criado. Apenas 'gráfico', 'texto', 'caminho', 'caractere', 'habilidade', 'atributo', 'folheto', 'tabela rolante', 'item de tabela' e 'macro' podem ser criados. ATTRIBUTES(Objeto) Os valores iniciais a serem utilizados para as propriedades do objeto Roll20.

Devoluções

O objeto Roll20 que foi criado.

Exemplos

Ao criar um objeto Roll20 que possui um objeto pai (como criar um objeto Roll20 de atributo, que é filho de um objeto Roll20 de personagem), é necessário fornecer o id do pai nosatributos.

on('add:character', function(obj) {
    createObj('attribute', {
        name: 'Strength',
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Ao criar um objeto Roll20 de caminho, é necessário fornecer um valor para a propriedade somente leitura_path. Esta é uma exceção à regra que impede a definição do valor de propriedades somente leitura ao criar objetos Roll20.

createObj('path', {
    left: 7000,
    top: 140,
    width: 140,
    height: 140,
    layer: 'objects',
    path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

Ao criar um objeto Roll20 para distribuição, não é possível definir o texto ou as notas do GM no momento da criação.

var handout = createObj('handout', {
    name: 'A Letter Addressed to You',
    inplayerjournals: 'all',
    archived: false
});
handout.set({
    notes: 'Notes can only be set after the handout is created',
    gmnotes: 'GM Notes can only be set after the handout is created'
});

filtrarObjs

Parâmetros

CALLBACK (Função) Uma função predicativa para testar todos os objetos Roll20. A função de retorno de chamada recebe um objeto Roll20 como parâmetro e deve retornar true (para objetos Roll20 que serão incluídos no valor de retorno filterObjs) ou false (para todos os outros objetos Roll20).

Devoluções

Uma matriz de objetos Roll20 que passaram no teste de predicado.

Exemplos

var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));
});

encontrarObjs

Parâmetros

ATRIBUTOS (Objeto) Uma coleção de pares chave:valor para corresponder aos objetos Roll20 na campanha. OPÇÕES (Objeto, opcional) Se options.caseInsensitive for verdadeiro, as comparações de cadeias de caracteres entre objetos Roll20 e atributos serão insensíveis a maiúsculas e minúsculas.

Devoluções

Uma matriz de objetos Roll20 com propriedades que correspondemaos atributos.

Exemplos

var npcs = findObjs({ type: 'character', controlledby: '' });

obterTodosObj

Parâmetros

Sem parâmetros

Devoluções

Uma matriz de todos os objetos Roll20 na campanha.

Exemplos

var tudo = obterTodosObjetos();

obterAtributoPorNome

Parâmetros

CHARACTER_ID(String) A identificação do objeto Roll20 do personagem que é o pai do objeto Roll20 do atributo cujo valor deseja obter. ATTRIBUTE_NAME(String) O nome do objeto Roll20 do atributo cujo valor você deseja obter. VALUE_TYPE(String, opcional) "current" ou "max" (o padrão é "current" se omitido).

Devoluções

A propriedadeatualoumáximado atributo apropriado. Caso a propriedade desejada não esteja definida, o valor padrão especificado pela ficha de personagem (se houver um padrão) será utilizado em seu lugar.

Exemplos

var personagem = getMyCharacter(),
    força = getAttrByName(personagem.id, 'força'),
    força_máxima = getAttrByName(personagem.id, 'força', 'máxima');

obterObj

Parâmetros

TYPE(String) O tipo de objeto Roll20 a ser obtido. ID(String) A identificação única do objeto Roll20 a ser obtido.

Devoluções

O objeto Roll20 especificado.

Exemplos

on('chat:message', função(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

registro

Parâmetros

MENSAGEM (varia) A mensagem a ser publicada no console Mod (API). O parâmetro da mensagem será transformado em uma String com JSON.stringify.

Devoluções

(Nulo)

Exemplos

on('chat:message', function(msg) {
    log('Mensagem recebida de:');
    log(getObj('player', msg.playerid));
});

Mensagem recebida de:
{"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"player","_lastpage":""}

no

Parâmetros

EVENTO(String) Existem cinco tipos de eventos: pronto, alteração, adição, destruição e chat. Com exceção do evento pronto, todos os tipos de eventos devem ser associados a um tipo de objeto. Para o chat, trata-se sempre de mensagens. Para todos os outros casos, esta é a propriedade de tipo de um objeto Roll20. Além do tipo de objeto, os eventos de alteração também podem especificar opcionalmente uma propriedade do objeto Roll20 especificado a ser observado. As duas ou três partes do evento (tipo, objeto e, opcionalmente, propriedade) são separadas por dois pontos. Portanto, as sequências de eventos válidas incluem, entre outras, "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character" e "destroy:handout". CALLBACK(Função) A função que será chamada quando o evento especificado for acionado. Os parâmetros passados dependem do tipo de evento: os eventos ready não possuem parâmetros de retorno de chamada. Os eventos change possuem um parâmetro obj, que é uma referência ao objeto Roll20 tal como existe após a alteração, e um parâmetro prev, que é um objeto JavaScript simples com propriedades correspondentes ao objeto Roll20 antes do evento de alteração.Os eventos add têm um parâmetro obj, que é uma referência ao novo objeto Roll20. Os eventos destroy têm um parâmetro obj, que é uma referência ao objeto Roll20 que não existe mais. Os eventos chat têm um parâmetro msg, que contém os detalhes da mensagem que foi enviada para o chat.

Devoluções

(Nulo)

Exemplos

Os eventos são disparados na ordem em que foram registados, do mais específico ao menos específico. Neste exemplo, uma alteração na propriedadeesquerdade um objeto gráfico Roll20 resultará na chamadada função3, seguida pelafunção1e, em seguida,pela função2.

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

Os eventos adicionadostentarão ser acionados para objetos Roll20 que já estão na campanha quando uma nova sessão for iniciada. Para evitar esse comportamento, é possível aguardar para registar o eventode adiçãoaté que o eventoprontoseja disparado.

on('add:graphic', function(obj) {
    // Quando a sessão começar, esta função será chamada para cada gráfico da campanha
    // Esta função também será chamada sempre que um novo objeto gráfico Roll20 for criado
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // Esta função será chamada *apenas* quando um novo objeto gráfico Roll20 for criado, não para aqueles que já existem
    });
});

O parâmetroprépara eventosde alteraçãonão é um objeto Roll20, mas sim um objeto JavaScript simples. Portanto, não é possível utilizar as funçõesgetouset, e não é possível omitir os sublinhados iniciais nas propriedades somente leitura.

on('change:graphic', função(obj, prev) {
    var id1 = obj.id, // todos os três são equivalentes
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id, // indefinido
        id5 = prev.get('id'), // indefinido não é uma função
        id6 = prev._id;       // correto

    // ambos são equivalentes
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined não é uma função
    prev.set({ // undefined não é uma função
        left: 70
    });
    prev.left = 70; // correto, embora não altere nada na mesa
});

Para os campos assíncronos dos objetos Roll20 de personagem e folheto (notas,gmnotes ebio), o parâmetroprevnão conterá os dados necessários. (Em vez disso, terá um identificador numérico utilizado pelo sistema.) Caso necessite aceder ao valor anterior de um destes campos, será necessário acompanhá-lo por conta própria:

on('ready', function() {
    if (!state.example) state.example = { bioCache: {} };
});

on('change:character:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text;

        // realizar ações...

        if (deveReverterBio()) {
            obj.set('bio', state.example.bioCache[obj.id]);
        }
    });
});

noSheetWorkerConcluído

Parâmetros

CALLBACK (Função) A função que será chamada quando a 'pilha' atual de Scripts do Sheet Worker for concluída.

Devoluções

(Nulo)

Exemplos

Esta função deve ser chamada antes de setWithWorker. A funçãode retorno de chamadaserá acionada apenas uma vez.

var myCharacter = ...,
    mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0];

onSheetWorkerCompleted(function() {
    var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // realizar uma ação com calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

O jogador é o GM

Parâmetros

PLAYER_ID(String) A identificação do objeto Roll20 do jogador a ser verificado.

Devoluções

verdadeirose o jogador tiver permissões de GM, oufalsocaso contrário.

Exemplos

Esta função é especialmente útil para restringir os comandos Mod (API) ao uso do GM.

on('chat:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...
    
);

playJukeboxPlaylist

Parâmetros

PLAYLIST_ID(String) O ID da lista de reprodução a ser iniciada.

Devoluções

(Nulo)

Exemplos

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);

número inteiro aleatório

Parâmetros

MAX(Número) O número máximo a ser retornado, inclusive.

Devoluções

Um número inteiro aleatório entre 1 (inclusive) emax(inclusive). Esta função apresenta uma distribuição mais adequada do queMath.random() e é recomendada em vez desta. Esta função não utiliza o Quantum Roll utilizado pelo mecanismo de dados, mas utiliza o mesmo algoritmo pseudoaleatório que o mecanismo de dados utilizará caso o Quantum Roll não esteja disponível.

Exemplos

Como esta função retorna um número inteiro de 1 amax, ela é ideal para gerar rapidamente o resultado de um lançamento de dados, caso não seja necessário utilizar toda a capacidade do mecanismo de dados do Roll20. ..

var d20Result = randomInteger(20); // aproximadamente equivalente a lançar um dado de 20 faces

enviarChat Assíncrono

Parâmetros

SPEAKINGAS(String) O nome a ser anexado à mensagem que está a ser enviada. Se speakingAs estiver no formato jogador|jogador_id ou personagem|personagem_id, a mensagem será enviada como esse jogador ou personagem. Caso contrário, a mensagem utilizará o nome fornecido como se um GM tivesse utilizado o comando /as. MESSAGE(String) A mensagem a ser enviada para o chat. CALLBACK(Função, opcional) Se callback for especificado, o resultado da mensagem do chat será passado para ele em vez de aparecer no chat. O parâmetro do método de retorno de chamada é uma matriz de objetos de mensagem. OPTIONS (Objeto, opcional) Se options.noarchive for verdadeiro, a mensagem não será adicionada ao arquivo do chat. Se options.use3d for verdadeiro, os lançamentos de dados na mensagem utilizarão o recurso de dados 3D. As opções não são aplicáveis se for especificada uma chamada de retorno.

Devoluções

(Nulo)

Exemplos

enviarChat('Exemplo', 'Este é um exemplo simples.');

É possível escrever facilmente um código para enviar uma mensagem como o mesmo jogador ou personagem que desencadeou um eventochat:message.

on('chat:message', function(msg) {
    var character = findObjs({ type: 'character', name: msg.who }) [0],
        player = getObj('player', msg.playerid),
        message = 'disse algo';

    if (personagem) sendChat('personagem|'+personagem.id, personagem.get('nome')+mensagem);
    else sendChat('jogador|'+jogador.id, jogador.get('nome de exibição')+mensagem);
});

O parâmetrode retorno de chamadaé útil se você precisar utilizar o mecanismo de dados do Roll20. mecanismo de dados. Não há necessidade específica de um valorspeakingAsao utilizar ocallback, uma vez que a mensagem não aparecerá no chat de qualquer forma.

sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});

options.noarchivefoi concebido principalmente para enviar aos jogadores menus criados a partir de botões de comando API sem sobrecarregar o histórico de chat.

sendChat('Sistema', '[Limpar alterações](!clear)\n[Adicionar mosaico](!add)\n[Ver amostra](!view)\n[Guardar layout](!save)', null, { noarchive: true });

enviarPing

Parâmetros

LEFT(Número) A coordenada x para posicionar o ping. TOP(Número) A coordenada y para posicionar o ping. PAGE_ID(String) O ID do objeto Roll20 da página onde o ping será posicionado. PLAYER_ID(String, opcional) O ping utilizará a cor do jogador especificado. Se player_id for omitido, o ping será amarelo. MOVEALL(Boolean, opcional) Se moveAll for verdadeiro, todos os jogadores na página apropriada terão as suas visualizações centradas no ping.

Observação:neste momento, apenas os GMs terão as suas visualizações centralizadas semoveAllforverdadeiro. Este comportamento está documentado aqui

Devoluções

(Nulo)

Exemplos

on('chat:message', function(msg) {
    var obj;
    if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) {
        if (!msg.selected) return;
        obj = getObj(msg.selected[0]._type, msg.selected[0]._id);
        sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true); // centralizar todos no token selecionado
    }
});

spawnFx

Parâmetros

ESQUERDA(Número) A coordenada x para posicionar o emissor de partículas. TOPO(Número) A coordenada y para posicionar o emissor de partículas. TIPO(String) O tipo de emissor de partículas a ser posicionado. Para efeitos incorporados, isto deve ser "tipo-cor", onde tipo é um dos seguintes: bomba, borbulhante, queimadura, explosão, brilho, míssil ou nova, e cor é um dos seguintes: ácido, sangue, encanto, morte, fogo, gelo, sagrado, magia, lodo, fumo ou água. ou água. Para efeitos personalizados, este deve ser o ID do objeto FX Roll20. Observação: os tipos beam, breath e splatter não podem ser utilizados com spawnFx. Consulte spawnFxBetweenPoints em vez disso. PAGE_ID(String, opcional) A identificação do objeto Roll20 da página onde o emissor de partículas deve ser colocado. Caso seja omitido, Campaign().get('playerpageid') será utilizado em seu lugar.

Devoluções

(Nulo)

Exemplos

spawnFx(1400, 1400, 'ácido borbulhante');

gerar efeito entre pontos

Parâmetros

START(Objeto) O ponto inicial para o emissor de partículas. O ponto deve estar no formato { x: número, y: número }.END(Object) O ponto final para o emissor de partículas. O ponto deve estar no formato { x: número, y: número }. TIPO(String) O tipo de emissor de partículas a ser colocado. Para efeitos incorporados, isto deve ser "tipo-cor", onde o tipo é um dos seguintes: feixe, bomba, sopro, borbulhante, queimadura, explosão, brilho, míssil, nova, ou salpico e cor é um dos seguintes: ácido, sangue, feitiço, morte, fogo, gelo, sagrado, magia, lodo, fumo ou água. Para efeitos personalizados, este deve ser o id do objeto FX Roll20. PAGE_ID(String, opcional) O id do objeto Roll20 da página onde o emissor de partículas deve ser colocado. Caso seja omitido, Campaign().get('playerpageid') será utilizado em seu lugar.

Devoluções

(Nulo)

Exemplos

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

gerarEfeitoComDefinição

Parâmetros

ESQUERDA(Número) A coordenada x para posicionar o emissor de partículas.TOPO(Número) A coordenada y para posicionar o emissor de partículas.DEFINIÇÃO(Objeto) As características do emissor de partículas a ser posicionado. Consulte Efeitos personalizados para obter uma lista das propriedades possíveis e as propriedades dos tipos e cores padrão do emissor de partículas. Consulte a Biblioteca FX para alguns efeitos personalizados criados pelos utilizadores do Roll20. PAGE_ID(String, opcional) O ID do objeto Roll20 da página onde o emissor de partículas será colocado. Caso seja omitido, Campaign().get('playerpageid') será utilizado em seu lugar.

Devoluções

(Nulo)

Exemplos

// estes dois são equivalentes
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxWithDefinition(1400, 1400, {
    maxParticles: 200,
    size: 15,
    sizeRandom: 3,
    lifeSpan: 20,
    lifeSpanRandom: 5,
    speed: 7,
    speedRandom: 2,
    gravity: { x: 0.01, y: 0.65 },
    ângulo: 270,
    ângulo aleatório: 35,
    taxa de emissão: 1,
    cor inicial:       [0, 35, 10, 1],
    cor inicial aleatória: [0, 10, 10, 0.25],
    endColour:         [0, 75, 30, 0],
    endColourRandom:   [0, 20, 20, 0]
});

Parar a lista de reprodução da Jukebox

Parâmetros

Sem parâmetros

Devoluções

(Nulo)

Exemplos

interromper a reprodução da lista de reprodução da Jukebox;

Voltar

Parâmetros

OBJ(Objeto Roll20) O objeto Roll20 a ser enviado para o fundo da sua camada.

Devoluções

(Nulo)

Exemplos

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg.selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});

para a frente

Parâmetros

OBJ(Objeto Roll20) O objeto Roll20 a ser trazido para a frente da sua camada.

Devoluções

(Nulo)

Exemplos

on('ready', função() {
    on('add:graphic', função(obj) {
        toFront(obj);
    });
});