API: Objetos

Observação:A propriedadeidde um objeto é um ID globalmente único: nenhum dois objetos devem ter o mesmo, mesmo entre diferentes tipos de objetos. Além disso, como o id de um objeto é frequentemente acessado e nunca muda, há um atalho disponível onde você pode acessá-lo usandoobj.idem vez deobj.get("_id")se desejar (ambos funcionarão).

Pathv2 (Jumpgate Tabletop)

The shape property has the following values:

• "pol" - Polyline. A straight line is drawn between each consecutive point. If the starting point and ending point are the same, it creates a closed shape.
• "free" - Freehand. A curve is drawn using the points as guides. If the starting point and ending point are the same, it creates a closed shape.
• "eli" - Ellipse. An ellipse is draw using the points to set a bounding box. Only the first two points are used.
• "rec" - Rectangle. A rectangle is draw using the points to set a bounding box. Only the first two points are used.

The points property is a JSON string containing an array of points. Points are represented as a two position array of an x and y location. A triangle from (0,0) to (0,70) to (70,0), and back to (0,0) would be represented as "[[0,0],[0,70],[70,0],[0,0]]".

The x and y properties position the PathV2 object on the page. They specify where the center of the drawing should be. For some shapes (ellipses and rectangles), that is pretty easy to figure out. For more complex shapes (polylines and freehands), you will need to find the minimum and maximum values from the points property and use the point equidistant between them.

Path (Classic Tabletop)

For more information on the format of _path data, see the section on paths.

Window

Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.

Exemplo

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!cw') {
        const currentPageID = Campaign().get('playerpageid');
        const win = createObj('window', {
            x: 70,
            y: -70,
            pageid: currentPageID,
            path: {
		        handle0: {
        			x: -70,
        			y: 0,
        		},
        		handle1: {
        			x: 35,
        			y: 0,
        		},
        	},
            color: '#000000'
        });
    }

    if (msg.type === 'api' && msg.content === '!mw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.set({
           x: 240,
           y: -139
        });
    }

    if (msg.type === 'api' && msg.content === '!dw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.remove();
    }
});

Porta

Nota: A janela e a porta usam um eixo invertido em comparação com outros tipos de objetos. Por exemplo, uma variável superior que seria 100 para outro objeto é y -100 para janela ou porta.

Texto

Gráfico (Token/Mapa/Carta/etc.)

Ícones para marcadores Exemplo

{
          "id":59, // o id do banco de dados para o
          "name":"Bane", // o nome (não único) do marcador
          "tag":"Bane::59", // como o token é realmente referenciado
          // isso incluirá o id para marcadores personalizados, mas não
          // para marcadores padrão.
          "url":"https://s3.amazonaws.com/files.d20.io/images/59/yFnKXmhLTtbMtaq-Did1Yg/icon.png?1575153187"

          // ^a url para a imagem do marcador de token
          }

Notas Importantes Sobre Personagens + Tokens Vinculados

Observe que, para tokens que estão vinculados a Personagens, o campo controlledby no token é substituído pelo campo controlledby no Personagem.

Para barras de token (por exemplo, bar1_value e bar1_max) onde o token está vinculado a um Atributo (por exemplo, bar1_link está definido), definir um valor para a barra atualizará automaticamente o current e/ou os valores max do Atributo subjacente, para que você não precise definir ambos manualmente.

Além disso, quando o Atributo (ou barra de símbolos) é modificado no jogo, ouvirá um eventochange:attribute(e específico da propriedade, por exemplo,change:attribute:current), seguido de um eventochange:graphic(echange:graphic:bar1_value). Você pode escolher responder a qualquer um dos eventos, mas os valores da barra subjacentes ainda não serão atualizados quando o evento de atributo for acionado, pois ele é acionado primeiro.

Notas Importantes Sobre Marcadores de Status

A partir de 6 de agosto de 2013, a forma como os marcadores de status nos tokens são tratados mudou. A propriedade "statusmarkers" do objeto Gráfico agora é uma lista separada por vírgulas de todas as cores/ícones de marcadores de status que devem estar ativos no token. O formato é o seguinte:

//Separado por vírgulas (use join para criar ou split para transformar em uma matriz). 
//Se um ícone/cor de status for seguido por um símbolo "@", o número depois de 
//"@" será mostrado como crachá no ícone
statusmarkers = "red,blue,skull,dead,brown@2,green@6"

Embora possa aceder diretamente à propriedadestatusmarkers, para manter a compatibilidade com os scripts existentes e para proporcionar uma forma fácil de trabalhar com os marcadores de estado sem ter de escrever código para tratar da divisão e análise da cadeia de caracteres, fornecemos um conjunto de propriedades "virtuais" no objeto que pode definir/obter para trabalhar com os marcadores de estado. Cada marcador de estado tem uma propriedade "status_<markername>". Por exemplo:

obj.get("status_red"); //Retornará falso se o marcador não estiver ativo, verdadeiro se estiver, e uma cadeia (por exemplo, "2" ou "5") se existir atualmente um crachá definido no marcador
obj.get('status_bluemarker'); //Continua a ser suportado para efeitos de compatibilidade com versões anteriores e é equivalente a fazer obj.get("status_blue");
obj.set("status_red", false); //removeria o marcador
obj.set("status_skull", "2"); //colocaria um emblema "2" no ícone da caveira e adicioná-lo-ia ao token se ainda não estivesse ativo.

Tenha em atenção que estas propriedades virtuais não têm eventos, pelo que deve utilizarchange:graphic:statusmarkerspara ouvir as alterações aos marcadores de estado de um token e, por exemplo,change:graphic:status_redNÃO é um evento válido e nunca será ativado.

A lista completa de marcadores de status disponíveis (na mesma ordem em que aparecem na bandeja de marcadores):

"vermelho", "azul", "verde", "marrom", "roxo", "rosa", "amarelo", "morto", "crânio", "sonolento", "meio-coração", "meio-neblina", "interdição", "caracol", "raio-furacão", "chave-inglesa", "corrente-coração", "raio-químico", "zona-da-morte", "beba-me", "rachadura-borda", "máscara-ninja", "cronômetro", "rede-de-pesca", "sobrealimentação", "forte", "punho", "cadeado", "três-folhas", "asa-fofa", "espancado", "pisar", "seta", "aura", "dor-nas-costas", "bandeira-negra", "olho-sangrando", "escudo-raio", "coração-quebrado", "teia-de-aranha", "escudo-quebrado", "bandeira-voando", "radioativo", "troféu", "crânio-quebrado", "orbe-congelado", "bomba-rolante", "torre-branca", "agarrar", "gritando", "granada", "metralhadora-sentinela", "todos-por-um", "traje-de-anjo", "alvo-de-arco"

Página

Campanha

 Ordem de Turno

A ordem de turno é uma string JSON que representa a lista de ordem de turno atual. É uma matriz de objetos. Atualmente, a ordem de turno só pode conter objetos de uma única página por vez - o ID da página atual para a ordem de turno é o atributo "initiativepage". Certifique-se de mantê-los sincronizados ou você poderá obter resultados estranhos.

Para trabalhar com a ordem de turno, você vai querer usar JSON.parse() para obter um objeto que representa o estado atual da ordem de turno (NOTA: Verifique se não é uma string vazia "" primeiro... se for, inicialize-o você mesmo com uma matriz vazia). Aqui está um exemplo de objeto de ordem de turno:

[
    {
     "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //O ID do objeto gráfico. Se isso estiver definido, a lista de ordem de turno irá automaticamente buscar o nome e o ícone da lista com base no gráfico no jogo de tabuleiro.
     "pr":"0", //O valor atual para o item na lista. Pode ser um número ou texto.
     "custom":"" //Título personalizado para o item. Será ignorado se o ID for definido como um valor diferente de "-1".
    },
    {
     "id":"-1", //Para itens personalizados, o ID DEVE ser definido como "-1" (observe que isso é uma STRING, não um NÚMERO.
     "pr":"12",
     "custom":"Teste Personalizado" //O nome a ser exibido para itens personalizados.
    }
]

Para modificar a ordem de turno, edite o objeto de ordem de turno atual e então use JSON.stringify() para mudar o atributo na Campanha. Observe que a ordem da ordem de turno na lista é a mesma que a ordem do array, então por exemplo push() adiciona um item ao final da lista, unshift() adiciona no início, etc.

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTE: We check to make sure that the turnorder isn't just an empty string first. Se for, trate-o como um array vazio.
else turnorder = JSON.parse(Campaign().get("turnorder"));

//Adicione uma nova entrada personalizada ao final da ordem de turno.
turnorder.push({
    id: "-1",
    pr: "15",
    custom: "Contador de Turno"
});
Campaign().set("turnorder", JSON.stringify(turnorder));

Jogador

Macro

Tabela Rolável

Item da Tabela 

Personagem

Attribute

 Importante: Veja a nota abaixo sobre como trabalhar com Fichas de Personagem para obter informações sobre como os valores padrão da Ficha de Personagem afetam o uso dos Atributos.

Habilidade

Folheto

Nota: A API não tem acesso à hierarquia de pastas. Os documentos criados pela API serão colocados no nível raiz.

Baralhos

Observe que existem métodos auxiliares da API para "retirar", "distribuir" ou "embaralhar" cartas do Baralho. Vejapost do fórum de atualização da API de março de 2018.

Cartão

Mão

Note que cada jogador deve ter apenas UMA mão.

Faixa de Jukebox

Personalizado 3

Restrições de propriedade imgsrc e avatar

Embora agora seja possível editar as propriedades imgsrc e avatar, a fim de garantir a segurança de todos os usuários do Roll20, implementamos as seguintes restrições para essas propriedades:

• Você deve usar um arquivo de imagem que tenha sido carregado para a Biblioteca do Roll20 -- não um site externo (como o Imgur) e nem o Mercado do Roll20. Ele começará com 'https://s3.amazonaws.com/files.d20.io/images/' para imagens carregadas no servidor principal ou 'https://s3.amazonaws.com/files.staging.d20.io/images/' para imagens carregadas no servidor de desenvolvimento. Você pode visualizar a URL de origem de uma imagem usando as ferramentas de desenvolvedor do seu navegador.

• Você deve incluir a sequência de consulta na URL -- por exemplo, 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678', não apenas 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png'

• Para objetos gráficos (tokens), você deve usar o tamanho "thumb" da imagem. Deve parecer 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678'.

No futuro, poderemos adicionar uma ferramenta para que as imagens possam ser carregadas especificamente para uso com scripts Mod (API), mas por agora apenas utilize imagens carregadas na sua própria biblioteca. Note que se eliminar uma imagem da sua biblioteca, esta será removida de todos os Jogos que usem essa imagem, incluindo Jogos que utilizem os seus scripts Mod (API).

Usando os campos Notas, Notas do Mestre e Biografia Assíncrona

Para acessar os campos "notes", "gmnotes" ou "bio" em Personagens e Anotações, você deve passar uma função de retorno como segundo argumento para a função get(). Aqui está um exemplo:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
    log(bio); //faça algo com a biografia do personagem aqui.
});

Você pode definir o valor desses campos normalmente. Observe que atualmente (em 09/05/2016) há um bug com esses campos assíncronos, em que defini-los passando valores para createObj falha silenciosamente, deixando o objeto em um estado estranho. Você só deve definir esses valores usando .set até que esse problema seja resolvido. Detalhes sobre oFórum. Também há um bug (a partir de 05/11/2016) em que tentar definir tanto as propriedades de notas quanto gmnotes na mesma chamada set() resulta na segunda propriedade sendo definida erroneamente. Detalhes sobre oFórum.

Trabalhando com Fichas de Personagem

O recurso de Fichas de Personagem afeta o uso do tipo de objeto Atributos, porque as fichas têm a capacidade de especificar um valor padrão para cada atributo na ficha. No entanto, se o atributo estiver definido como o valor padrão, ainda não há um objeto de Atributo criado no jogo para esse Personagem. Nós fornecemos uma função de conveniência que oculta essa complexidade para você. Você deve usar essa função para obter o valor de um atributo daqui para frente, especialmente se souber que um jogo está usando uma Ficha de Personagem.

getAttrByName(character_id, attribute_name, value_type)

Basta especificar o ID do carácter, o nome(não o ID) do atributo (por exemplo, "HP" ou "Str") e, em seguida, se pretende o "current" ou "max" para value_type. Aqui está um exemplo:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); // o valor atual de str, por exemplo "12"
getAttrByName(character.id, "str", "max"); // o valor máximo de str, por exemplo "[[floor(@{STR}/2-5)]]"

Observe que os campos que possuem valores calculados automaticamente retornarão a fórmula em vez do resultado do valor. Você pode então passar essa fórmula para sendChat() para usar o motor de dados para calcular o resultado automaticamente.

Não se esqueça de consultar também a documentaçãoCharacter Sheetpara obter mais informações sobre como as Character Sheets interagem com a API.

getAttrByName irá apenas obter o valor do atributo, não o próprio objeto do atributo. Se você deseja referenciar propriedades do atributo além de "atual" ou "máximo", ou se você deseja alterar propriedades do atributo, você deve usar uma das outras funções acima, como findObjs.

No caso de o atributo solicitado não existir,getAttrByName()retornaráindefinido.

Criando Objetos

createObj(type, attributes)

Nota: atualmente você pode criar objetos 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' e 'macro'.

Você pode criar um novo objeto no jogo usando a funçãocreateObj. Você deve passar o tipo do objeto (um dos valores válidos_typeda lista de objetos acima), bem como um objetoattributescontendo uma lista de propriedades para o objeto. Observe que, se o objeto tiver um objeto pai (por exemplo, atributos e habilidades pertencem a personagens, gráficos, textos e caminhos pertencem a páginas, etc.), você deve passar o ID do pai na lista de propriedades (por exemplo, você deve incluir a propriedadecharacteridao criar um atributo). Também observe que, mesmo ao criar novos objetos, você não pode definir propriedades somente leitura, elas serão automaticamente definidas para o valor padrão. A única exceção a isso é ao criar um Caminho, você deve incluir a propriedade 'path', mas ela não pode ser modificada uma vez que o caminho é criado inicialmente.

createObjretornará o novo objeto, então você pode continuar trabalhando com ele.

//Crie um novo atributo de Força em todos os Personagens que são adicionados ao jogo.
on("add:character", function(obj) {
    createObj("attribute", {
        name: "Strength",
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Excluindo Objetos

object.remove()

Observação: atualmente você pode excluir objetos 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' e 'macro'.

Você pode excluir objetos de jogo existentes usando a função .remove(). A função .remove() funciona em todos os objetos que você pode criar com a função createObj. Você chama a função diretamente no objeto. Por exemplo,mycharacter.remove();.

Objetos Globais

Existem vários objetos que estão disponíveis globalmente em qualquer lugar do seu script.

Campanha() (função)

Uma função que devolve o objetoCampaign. Como só há uma campanha, esse global sempre aponta para a única campanha no jogo. Útil para verificar se um objeto está na página ativa usandoCampaign().get("playerpageid").

estado

A variávelstateé um objeto no âmbito global que é acessível a todos os scripts em execução num jogo. Pode aceder ao objetostatea partir de qualquer função ou retorno de chamada em qualquer altura, bastando para isso utilizar a variável global denominadastate. Além disso, o objetostateé mantido entre execuções da caixa de areia, pelo que pode utilizá-lo para armazenar informações que pretende ter em execuções futuras do seu script.

Nota:Você deve usar o objeto de estado para armazenar informações que são necessárias apenas pela API, pois elas não são enviadas para os computadores dos jogadores e não aumentam o tamanho do arquivo do seu jogo. Armazene valores que são necessários no jogo nas propriedades dos objetos Roll20.

Tipos Armazenáveis

O objetostatesó é capaz de persistir tipos de dados simples, tal como suportado pela normaJSON.

Aviso:Embora as funções pareçam funcionar quando armazenadas no estado inicialmente, elas desaparecerão na primeira vez que o estadofor restaurado da persistência, como em uma reinicialização da sandbox.

• Nota: Isto inclui objetos Roll20 que você obtém de eventos ou das funções findObjs(), getObj(), filterObjs(), createObj(), etc.

Lembretes Importantes

O estado do objeto é compartilhado entre todos os scripts em um ambiente isolado. Para evitar que outros scripts sejam quebrados, é importante seguir algumas diretrizes simples:

• Nunca atribua diretamente ao objeto estado raiz.

estado = { break: 'all the things' };  // NUNCA FAÇA ISSO!!!

• Evite usar variáveis locais chamadas estado em seus scripts. Embora isso funcione, será confuso para os usuários futuros de seus scripts e poderá causar problemas se o código for editado descuidadamente.

function turn(){
    var state = Campaign().get('turnorder');  // Má prática, evite isso!
    // ...
}

• Sempre coloque suas propriedades abaixo de pelo menos uma propriedade de namespace. Certifique-se de usar uma propriedade de namespace suficientemente descritiva. Evite nomes como script ou settings. É melhor usar o nome do seu módulo ou o seu próprio nome ou apelido.

if( ! state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module: 'meu módulo', ok: 'isso está bom!', count: 0 };
}
state.MyModuleNamespace.count++;

Exemplo de Uso

Este é um exemplo de trabalho que utiliza adequadamente o objetostate.

on('ready',function() {
    "use strict";

    // Verifique se a propriedade com namespace existe, criando-a se ela não existir
    if( ! state.MyModuleNS ) {
        state.MyModuleNS = {
            version: 1.0,
            config: {
                color1: '#ff0000',
                color2: '#0000ff'
            },
            count: 0
        };
    }

    // Usando as propriedades de estado para configurar uma mensagem no chat. 
    sendChat(
        'Test Module',
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
            'State test'+
        '</span> '+
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
            'Script v'+state.MyModuleNS.version+' started '+(++state.MyModuleNS.count)+' times!'+
        '</span>'
    );
});

Encontrando/Filtrando Objetos

A API fornece várias funções auxiliares que podem ser usadas para encontrar objetos.

getObj(type, id)
Esta função obtém um único objeto se passar o _type do objeto e o _id. É melhor usar esta função em vez das outras funções de busca sempre que possível, pois é a única que não precisa percorrer toda a coleção de objetos.

on("change:graphic:represents", function(obj) {
    if(obj.get("represents") != "") {
       var character = getObj("character", obj.get("represents"));
    }
});

findObjs(attrs)

Passe esta função uma lista de atributos e ela retornará todos os objetos que correspondem como um array. Observe que isso opera em todos os objetos de todos os tipos em todas as páginas - então você provavelmente deseja incluir pelo menos um filtro para _type e _pageid se estiver trabalhando com objetos de jogo de mesa.

var currentPageGraphics = findObjs({                              
  _pageid: Campaign().get("playerpageid"),                              
  _type: "graphic",                          
});
_.each(currentPageGraphics, function(obj) {    
  //Faça algo com obj, que está na página atual e é um gráfico.
});

Você também pode passar um segundo argumento opcional que contém um objeto com uma lista de opções, incluindo:

• caseInsensitive (verdadeiro/falso): Se verdadeiro, as propriedades de string serão comparadas sem levar em consideração a caixa da string

var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});
//Retorna todos os tokens com um nome de 'target', 'Target', 'TARGET', etc.

filterObjs(callback)

Executará a função de retorno de chamada fornecida em cada objeto e, se a função de retorno de chamada retornar verdadeiro, o objeto será incluído no array de resultado. Atualmente, não é aconselhável usar filterObjs() para a maioria dos propósitos - devido ao fato de que findObjs() possui algum índice embutido para melhorar a velocidade de execução, quase sempre é melhor usar findObjs() para obter objetos do tipo desejado primeiro e, em seguida, filtrá-los usando o método .filter() nativo para arrays.

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;    
  else return false;
});
//Results é um array de todos os objetos que estão no canto superior esquerdo do jogo de tabuleiro.

getAllObjs()

Retorna uma matriz de todos os objetos no Jogo (todos os tipos). Equivalente a chamar filterObjs e apenas retornarverdadeiropara cada objeto.

getAttrByName(character_id, attribute_name, value_type)

Obtém o valor de um atributo, usando o valor padrão da ficha de personagem se o atributo não estiver presente. value_typeé um parâmetro opcional, que você pode usar para especificar "atual" ou "máximo".

getAttrByNameiráapenasobter o valor do atributo, não o objeto atributo em si. Se você deseja referenciar propriedades do atributo além de "atual" ou "máximo", ou se deseja alterar propriedades do atributo, você deve usar uma das outras funções acima, comofindObjs.

Para seções repetidas, você pode usar o formatorepeating_section_$n_attribute, ondené o número da linha repetida (começando com zero). Por exemplo,repeating_spells_$2_namedevolverá o valor denameda terceira linha derepeating_spells.

Você pode obter o comportamento equivalente agetAttrByNameusando o seguinte:

// current and max are completely dependent on the attribute and game system
// in question; there is no function available for determining them automatically
function myGetAttrByName(character_id,
                         attribute_name,
                         attribute_default_current,
                         attribute_default_max,
                         value_type) {
    attribute_default_current = attribute_default_current || '';
    attribute_default_max = attribute_default_max || '';
    value_type = value_type || 'current';

    var attribute = findObjs({
        type: 'attribute',
        characterid: character_id,
        name: attribute_name
    }, {caseInsensitive: true})[0];
    if (!attribute) {
        attribute = createObj('attribute', {
            characterid: character_id,
            name: attribute_name,
            current: attribute_default_current,
            max: attribute_default_max
        });
    }

    if (value_type == 'max') {
        return attribute.get('max');
    } else {
        return attribute.get('current');
    }
}