API: Documentação de Funções

Variáveis globais

_ (Underscore)

Este é o objeto de espaço de nome para a bibliotecaUnderscore.js. Underscore possui muitas funções para manipulação de coleções.

estado

As propriedades do objeto de estado persistirão entre as sessões de jogo. O mesmo objeto de estado é partilhado entre todos os scripts Mod (API) numa campanha, por isso é fortemente recomendado que, ao escrever valores no estado, minimize o seu impacto o máximo possível para evitar colisões de nomes. Nota: o estado é serializado com JSON, portanto, você não pode armazenar funções ou objetos com referências cíclicas.

Funções Globais

Campanha

Parâmetros

Sem parâmetros

Retorna

O objeto de campanha único do Roll20.

Exemplos

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

createObj

Parâmetros

TYPE(String) O tipo de objeto Roll20 a ser criado. Somente 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' e 'macro' podem ser criados.ATTRIBUTES(Object) Os valores iniciais a serem usados para as propriedades do objeto Roll20.

Retorna

O objeto Roll20 que foi criado.

Exemplos

Ao criar um objeto Roll20 que possui um objeto pai (como criar um objeto de atributo Roll20, que é um filho de um objeto de personagem Roll20, você deve fornecer o id do pai em atributos.

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

Ao criar um objeto Roll20 de caminho, você deve fornecer um valor para a propriedade somente leitura_path. Isso é uma exceção à regra que impede você de definir o valor das 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 de anotação, você não pode definir o texto ou gmnotes 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'
});

filterObjs

Parâmetros

CALLBACK(Function) Uma função de predicado para testar todos os objetos Roll20. A função de retorno recebe um objeto Roll20 como parâmetro e deve retornar verdadeiro (para objetos Roll20 que serão incluídos no valor de retorno do filtroObjs) ou falso (para todos os outros objetos Roll20).

Retorna

Um array de objetos Roll20 que passaram no teste do 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'));
    });

findObjs

Parâmetros

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

Retornos

Uma matriz de objetos Roll20 com propriedades que correspondem aatributos.

Exemplos

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

getAllObjs

Parâmetros

Sem parâmetros

Retornos

Uma matriz de todos os objetos Roll20 na campanha.

Exemplos

var tudo = getAllObjs();

getAttrByName

Parâmetros

CHARACTER_ID(String) O id do caractere do objeto Roll20 que é o pai do atributo do objeto Roll20 do qual pretende o valor.ATTRIBUTE_NAME(String) O nome do atributo do objeto Roll20 do qual pretende o valor.VALUE_TYPE(String, opcional) Ou "current" ou "max" (a predefinição é "current" se for omitido).

Devoluções

A propriedadecurrentoumaxdo atributo adequado. Se a propriedade pretendida não estiver definida, será utilizado o valor predefinido especificado pela folha de características (se existir uma predefinição).

Exemplos

var character = getMyCharacter(),
    strength = getAttrByName(character.id, 'strength'),
    strength_max = getAttrByName(character.id, 'strength', 'max');

getObj

Parâmetros

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

Devoluções

O objeto Roll20 especificado.

Exemplos

on('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

log

Parâmetros

MENSAGEM(varia) A mensagem para publicar na consola Mod (API). O parâmetro da mensagem será transformado numa String com JSON.stringify.

Retorna

(Void)

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":"jogador","_lastpage":""}

em

Parâmetros

EVENT(String) Existem cinco tipos de evento: readychangeadddestroychat Com exceção de ready, todos os tipos de evento também devem ser emparelhados com um tipo de objeto. Para chat, isso é sempre mensagem. Para tudo o mais, isso é a propriedade type de um objeto Roll20. Além do tipo de objeto, eventos de change também podem opcionalmente especificar uma propriedade do objeto Roll20 especificado. As partes 2-3 do evento (tipo, objeto e opcionalmente propriedade) são separadas por dois pontos. Portanto, as strings de evento válidas incluem, mas não estão limitadas a "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character" e "destroy:handout". CALLBACK(Function) A função que será chamada quando o evento especificado for acionado. Os parâmetros passados dependem do tipo de evento: eventos ready não têm parâmetros de retorno. Eventos change têm um parâmetro obj, que é uma referência ao objeto Roll20 como ele existe após a mudança, e um parâmetro prev, que é um objeto JavaScript simples com propriedades correspondentes ao objeto Roll20 antes do evento de mudança. Eventos add têm um parâmetro obj, que é uma referência ao novo objeto Roll20. Eventos destroy têm um parâmetro obj, que é uma referência ao objeto Roll20 que não existe mais. Eventos chat têm um parâmetro msg, que contém os detalhes da mensagem que foi enviada para o chat.

Retorna

(Void)

Exemplos

Os eventos são disparados na ordem em que foram registrados, do mais específico para o menos específico. Neste exemplo, uma alteração à propriedadeleftde um objeto gráfico Roll20 resultará na chamada da funçãofunction3, seguida da funçãofunction1e da funçãofunction2.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

adicioneeventos tentarão disparar para objectos Roll20 que já estejam na campanha quando uma nova sessão começar. Para evitar esse comportamento, você pode esperar para registrar seuadicionarevento até que oevento readyseja acionado.

on ('add:graphic', function(obj) {
    // Quando a sessão começa, essa função será chamada para cada gráfico na campanha
    // Essa 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 os que já existem
    });
});

O parâmetroprepara eventoschangenão é um objeto Roll20, é um objeto JavaScript antigo. Portanto, você não pode usar as funçõesgetouset, e não pode omitir os sublinhados iniciais em propriedades somente leitura.

on('change:graphic', function(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); // indefinido não é uma função
    prev.set({            // indefinido não é uma função
        left: 70
    });
    prev.left = 70;       // correto, embora não altere nada no jogo de tabuleiro
});

Para os campos assíncronos dos objetos character e handout do Roll20 (notes, gmnotes, e bio), o parâmetro prev não conterá os dados que você precisa. (Ele terá um identificador numérico usado pelo sistema em vez disso.) Se você precisar acessar o valor anterior de um desses campos, você terá que acompanhar isso 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;

        // do stuff...

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

onSheetWorkerCompleted

Parameters

CALLBACK(Function) The function that will be called when the current 'stack' of Sheet Worker Scripts completes.

Returns

(Void)

Examples

This function is intended to be called prior to setWithWorker. Thecallbackfunction will be called only once.

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];
    // do something with calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

playerIsGM

Parâmetros

PLAYER_ID(String) O id do objeto Roll20 do jogador para verificar.

Retornos

truese o jogador atualmente possui permissões de GM, oufalsecaso contrário.

Exemplos

Esta função é especialmente útil para limitar 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

Parameters

PLAYLIST_ID(String) The id of the playlist to start playing.

Returns

(Void)

Examples

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

randomInteger

Parameters

MAX(Number) The maximum number to return, inclusive.

Retornos

Um número inteiro aleatório entre 1 (inclusive) e max (inclusive). Esta função tem uma distribuição melhor do que Math.random(), e é recomendada em seu lugar. Esta função não utiliza o recurso de Rolo Quânticodo motor de dados, mas utiliza o mesmo algoritmo pseudoaleatório que o motor de dados usará se o Rolo Quântico não estiver disponível.

Exemplos

Porque essa função retorna um número inteiro de 1 amax, é ideal para gerar rapidamente um resultado de rolagem de dados se você não precisar da força total do mecanismo de dados dedo Roll20.

var d20Result = randomInteger(20); // aproximadamente equivalente a rolar um dado de 20 lados

sendChat Assíncrono

Parâmetros

SPEAKINGAS(String) O nome a ser anexado à mensagem sendo enviada. Se speakingAs estiver no formato player|player_id ou character|character_id, a mensagem será enviada como esse jogador ou personagem. Caso contrário, a mensagem usará o nome fornecido como se um Mestre tivesse usado o comando /as.MENSAGEM(String) A mensagem a ser enviada para o chat.CALLBACK(Funcion, 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 callback é um array de objetos de mensagem.OPÇÕES(Objeto, opcional) Se options.noarchive for true, a mensagem não será adicionada ao arquivo de 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 callback for especificado.

Retorna

(Void)

Exemplos

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

Você pode facilmente escrever código para enviar uma mensagem como o mesmo jogador ou personagem que acionou um evento chat:message.

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

    if (character) sendChat('character|'+character.id, character.get('name')+message);
    else sendChat('player|'+player.id, player.get('displayname')+message);
});

O parâmetrocallbacké útil se precisar de aproveitar o motor de dadosdo Roll20. Não há necessidade específica de um valor speakingAs ao usar o callback, já que a mensagem não aparecerá no chat.

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

options.noarchivefoi concebido principalmente para enviar aos jogadores menus feitos a partir de botões de comandoAPIsem obstruir o seu histórico de conversação.

sendChat('System', '[Limpar alterações](!clear)\n[Adicionar azulejo](!add)\n[Ver exemplo](!view)\n[Salvar layout](!save)', null, { noarchive: true });

sendPing

Parâmetros

ESQUERDA(Número) A coordenada x para colocar o ping.TOPO(Número) A coordenada y para colocar o ping.PAGE_ID(Texto) O id do objeto Roll20 da página para colocar o ping.PLAYER_ID(Texto, opcional) O ping usará a cor do jogador especificado. Se player_id for omitido, o ping será amarelo.MOVEALL(Booleano, opcional) Se moveAll for true, todos os jogadores na página apropriada terão suas visualizações centradas no ping.

Observação: Neste momento, apenas os GMs terão suas visualizações centradas se moveAll for true. Este comportamento é documentado aqui

Retornos

(Vazio)

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); // center everyone on the selected token
    }
});

spawnFx

Parâmetros

LEFT(Número) A coordenada x para colocar o emissor de partículas.TOP(Número) A coordenada y para colocar o emissor de partículas.TYPE(String) O tipo de emissor de partículas para colocar. Para efeitos integrados, isso deve ser "tipo-cor", onde tipo é um dos bomb, bubbling, burn, burst, explode, glow, missile, ou nova e cor é um dos acid, blood, charm, death, fire, frost, holy, magic, slime, smoke, ou water. Para efeitos personalizados, este deve ser o id do objeto FX Roll20. Nota: os tipos de feixe, sopro e respingo não podem ser usados com spawnFx. Consulte spawnFxBetweenPoints em vez disso. PAGE_ID (String, opcional) O id do objeto de página Roll20 para colocar o emissor de partículas. Se omitido, Campaign().get('playerpageid') será usado em vez disso.

Retorna

(Void)

Exemplos

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

spawnFxBetweenPoints

Parâmetros

START (Objeto) O ponto de partida para o emissor de partículas. O ponto deve estar no formato { x: número, y: número }. END (Objeto) 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, isso deve ser "tipo-cor", onde tipo é um dos feixe, bomba, respiração, borbulhante, queimar, estourar, explodir, brilhar, míssil, nova ou respingar e cor é um dos ácido, sangue, charme, morte, fogo, gelo, sagrado, mágico, lodo, fumaça ou água. Para efeitos personalizados, isso deve ser o id do objeto FX Roll20.PAGE_ID(String, opcional) O id da página do objeto Roll20 para colocar o emissor de partículas. Se omitido, Campaign().get('playerpageid') será usado em seu lugar.

Retorna

(Void)

Exemplos

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

spawnFxWithDefinition

Parâmetros

ESQUERDA(Número) A coordenada x para colocar o emissor de partículas. TOPO(Número) A coordenada y para colocar o emissor de partículas. DEFINIÇÃO(Objeto) As características do emissor de partículas para colocar. Veja Custom FX para uma lista de propriedades possíveis e as propriedades dos tipos e cores padrão do emissor de partículas. Veja a Biblioteca de Efeitos para alguns efeitos personalizados criados pelos usuários do Roll20. PAGE_ID (String, opcional) O id da página do objeto Roll20 para colocar o emissor de partículas. Se omitido, será usado Campaign().get('playerpageid') em seu lugar.

Retorna

(Void)

Exemplos

// estes dois são equivalentes
spawnFx (1400, 1400, 'ácido-borbulhante');
spawnFxWithDefinition (1400, 1400, {
    maxParticles: 200,
    size: 15,
    sizeRandom: 3,
    lifeSpan: 20,
    lifeSpanRandom: 5,
    speed: 7,
    speedRandom: 2,
    gravity: { x: 0.01, y: 0.65 },
    angle: 270,
    angleRandom: 35,
    emissionRate: 1,
    startColour: [0, 35, 10, 1],
    startColourRandom: [0, 10, 10, 0.25],
    endColour: [0, 75, 30, 0],
    endColourRandom: [0, 20, 20, 0]
});

pararJukeboxPlaylist

Parâmetros

Sem parâmetros

Devoluções

(Vazio)

Exemplos

pararJukeboxPlaylist();

paraVoltar

Parâmetros

OBJ(objeto Roll20) O objeto Roll20 a enviar para a parte de trás da sua camada.

Devoluções

(Vazio)

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));
        });
    }
});

toFront

Parâmetros

OBJ(Objeto Roll20) O objeto Roll20 para trazer para a frente de sua camada.

Retorna

(Void)

Exemplos

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});