API: Objetos

Existem vários tipos diferentes de objetos que são usados em toda a API do Roll20. Aqui está uma lista rápida de cada um, o que é e quais propriedades ele contém (junto com os valores padrão). Como regra geral, propriedades que começam com um sublinhado (_) sãosomente leiturae não podem ser alteradas. Você deve acessar propriedades em objetos usandoobj.get("propriedade")e definir novos valores usandoobj.set("propriedade", novovalor)ouobj.set({property: newvalue, property2: newvalue2}).

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).


Trilha

Propriedade Valor Padrão Notas
_id  

Um ID único para este objeto. Globalmente único em todos os
objetos neste jogo. Somente leitura.

_type "path" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto
. Somente leitura.
_pageid    ID da página em que o objeto está. Somente leitura.
_path    A JSON string describing the lines in the path. Read-only, except when creating a new path. See the section on Paths for more information.
fill "transparent" Fill color. Use the string "transparent" or a hex color as a string, for example "#000000"
stroke "#000000" Stroke (border) color.
rotação 0 Rotação (em graus).
camada "" Camada atual, uma das opções "gmlayer", "objetos", "mapa" ou "paredes". A camada de paredes é usada para iluminação dinâmica, e caminhos na camada de paredes bloquearão a luz.
espessura_do_traço 5  
largura 0  
altura 0  
topo 0 Coordenada Y para o centro do caminho
# left 0 Coordenada X para o centro do caminho
scaleX 1  
scaleY 1  
controlledby ""

Lista de IDs de jogadores separados por vírgula que podem controlar o caminho. Os jogadores controladores podem excluir o caminho. Se o caminho foi criado por um jogador, esse jogador é automaticamente incluído na lista.

Todos os Jogadores são representados por ter 'todos' na lista.

barrierType "wall"

Dynamic Lighting Barrier type options include "wall", "oneWay", and "transparent"

oneWayReversed false

boolean

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.

Propriedade Valor Padrão Notas
_id   A unique ID for this object. Globalmente único em todos os objetos deste jogo. Somente leitura.
_type "window" Somente leitura.
cor   Uma cor hexadecimal do caminho.
x 0 Coordenada central da porta no eixo x.
y 0 Coordenada central da porta no eixo y.
isOpen false Determines whether a player can move through this window.
isLocked false Prevents players from being able to interact with the window.
path   Represented as two handles (handle0 and handle1) each with x and y coordinates.

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.

Propriedade

Valor Padrão

Notas

_id

 

Um ID único para este objeto. Globalmente único em todos os objetos deste jogo. Somente leitura.

_type

“door”

Somente leitura.

cor

 

Uma cor hexadecimal do caminho.

x

0

Centro de coordenadas da porta no eixo x.

y

0

Centro de coordenadas da porta no eixo y.

isOpen

false

Determina se um jogador pode atravessar essa porta.

isLocked

falso

Impede que os jogadores possam interagir com a porta.

isSecret

falso

Remove um ícone de porta da visão do jogador e funciona como uma barreira.

caminho

 

Representado como duas alças (alça0 e alça1), cada uma com coordenadas x e y.


Texto

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único em todos os objetos deste jogo. Somente leitura.
_type "text" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
_pageid   ID da página em que o objeto está. Somente leitura.
top 0  
left 0  
largura 0  
altura 0  
texto ""  
tamanho_da_fonte 16 Para obter os melhores resultados, mantenha os tamanhos predefinidos no menu de edição: 8, 10, 12, 14, 16, 18, 20, 22, 26, 32, 40, 56, 72, 100, 200, 300.
rotação 0  
cor "rgb(0, 0, 0)"  
família_de_fonte "Arial" Se isto não for definido, quando alterar mais tarde o valor da propriedade "text", o font_size diminuirá para 8. Valores possíveis (maiúsculas não importam): "Arial", "Patrick Hand", "Contrail One", "Shadows Into Light" e "Candal". Especificar um nome inválido resulta no uso de uma fonte sem serifa monoespaçada sem nome.
camada "" "gmlayer", "objects", "map" ou "walls".
controlledby "" Lista separada por vírgulas de IDs de jogadores que podem controlar o texto. Os jogadores que controlam podem excluir o texto. Se o texto foi criado por um jogador, esse jogador é automaticamente incluído na lista.

Todos os jogadores são representados por ter 'todos' na lista.


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

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "gráfico" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
_subtype "token" Pode ser "token" (para tokens e mapas) ou "card" (para cartas). Somente leitura.
_cardid   Definido como um ID se o gráfico for uma carta. Somente leitura.
_pageid   ID da página em que o objeto está. Somente leitura.
imgsrc   A URL da imagem do gráfico. Veja a nota sobre imgsrc e restrições de avatar abaixo.
bar1_link   Definir como um ID se a Barra 1 estiver vinculada a um personagem.
bar2_link    
bar3_link    
representa   ID do personagem que este token representa.
esquerda 0 Número de pixels a partir da borda esquerda do mapa até o centro da imagem.
topo 0 Número de pixels a partir da borda superior do mapa até o centro da imagem.
largura 0 Largura da imagem, em pixels.
altura 0 Altura da imagem, em pixels.
rotação 0 A orientação do token em graus.
camada "" "gmlayer", "objetos", "mapa" ou "paredes".
isdrawing falso Esta propriedade é alterada a partir do menu de contexto Avançado.
flipv falso Virar verticalmente.
fliph falso Virar horizontalmente.
Nome "" O nome do token.
gmnotes "" Notas no token visíveis apenas para o Mestre.
controladopor "" Lista separada por vírgulas de IDs de jogadores que podem controlar o gráfico. Os jogadores controladores podem excluir o gráfico. Se o gráfico foi criado por um jogador, esse jogador é automaticamente incluído na lista.

Todos os Jogadores é representado por ter 'todos' na lista.

bar1_value "" Valor atual da Barra 1. Isso pode ser um número ou texto.
bar2_valor ""  
bar3_valor ""  
bar1_max "" Valor máximo da Barra 1. Se _valor e _max estiverem definidos, uma barra pode ser exibida acima do token mostrando a porcentagem da Barra 1.
bar2_max ""  
bar3_max ""  
aura1_raio "" Raio da aura, usando as unidades definidas nas configurações da página. Pode ser um número inteiro ou um número decimal. Definido como uma string vazia para limpar a aura.
aura2_radius ""  
aura1_color "#FFFF99" Uma cor hexadecimal ou a aura.
aura2_color "#59E594"  
aura1_square false A aura é um círculo ou um quadrado?
aura2_square false  
tint_color "transparente" Cor hexadecimal ou "transparente". Vai tingir a cor da imagem.
statusmarkers "" Uma lista separada por vírgulas dos statusmarkers ativos. Veja as notas abaixo para mais informações.
token_markers "" Uma matriz JSON stringificada contendo um objeto para cada marcador de token atualmente no jogo:. Você pode encontrar um exemplo abaixo.
showname falso Se o nome do token é mostrado.
showplayers_name falso Mostrar o nome para todos os jogadores.
showplayers_bar1 falso Mostrar a Barra 1 para todos os jogadores.
showplayers_bar2 false  
showplayers_bar3 false  
showplayers_aura1 false Show Aura 1 to all players.
showplayers_aura2 false  
playersedit_name true Permitir que os jogadores controladores editem o nome do token. Mostrar também a placa de identificação para os jogadores controladores, mesmo se showplayers_name for falso.
playersedit_bar1 verdadeiro Permitir que os jogadores controladores editem a Barra 1 do token. Mostrar também a Barra 1 para os jogadores controladores, mesmo se showplayers_bar1 for falso.
playersedit_bar2 verdadeiro  
playersedit_bar3 verdadeiro  
playersedit_aura1 true Allow controlling players to edit the token's Aura 1. Also shows Aura 1 to controlling players, even if showplayers_aura1 is false.
playersedit_aura2 true  
light_radius "" Dynamic lighting radius.
light_dimradius "" Start of dim light radius. Se light_dimradius for uma string vazia, o token emitirá luz intensa até a distância light_radius. Se light_dimradius tiver um valor, o token emitirá luz intensa até o valor light_dimradius e luz fraca a partir desse ponto até o valor light_radius.
light_otherplayers falso Mostrar a luz do token para todos os jogadores.
light_hassight falso A luz tem "visão" para controle dos jogadores para fins da configuração "Enforce Line of Sight".
light_angle "360" Ângulo (em graus) do ângulo da luz. Por exemplo, "180" significa que a luz só seria mostrada para a "metade" da "visão de campo".
light_losangle "360" Ângulo (em graus) do campo de visão da imagem (supondo que light_hassight esteja definido como verdadeiro)
lastmove "" O último movimento do token. É uma lista de coordenadas separadas por vírgula. Por exemplo, "300,400" significa que o token começou seu último movimento em left=300, top=400. Sempre é assumido que os valores atuais de top + left do token são o "ponto final" do último movimento. Os waypoints são indicados por múltiplos conjuntos de coordenadas. Por exemplo, "300,400,350,450,400,500" indicaria que o token começou em left=300, top=400, então definiu um waypoint em left=350, top=450, outro waypoint em left=400, top=500, e então terminou o movimento em suas coordenadas atuais de top + left.
light_multiplier "1" Multiplicador na efetividade das fontes de luz. Um multiplicador de dois permitiria que o token enxergasse duas vezes mais longe do que um token com um multiplicador de um, com a mesma fonte de luz.
adv_fow_view_distance "" The radius around a token where Advanced Fog of War is revealed.
light_sensitivity_multiplier 100 Multiplier on the effectiveness of light sources. A multiplier of 200 would allow the token to see twice as far as a token with a multiplier of 100, with the same light source.
night_vision_effect
  Changes the Night Vision Effect. Other options include “Dimming” and “Nocturnal”
bar_location   Adjusts the location of the token bars. As opções incluem 'overlap_top', 'overlap_bottom', 'bottom'
compact_bar
  Ajusta se a barra é compacta ou não. Outra opção é compacta.
lockMovement falso Uma opção para travar um Gráfico no lugar. Valor booleano verdadeiro ou falso

Í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

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único em todos os objetos deste jogo. Somente leitura.
_type "página" Pode ser usado para identificar o tipo de objeto ou procurar pelo objeto. Somente leitura.
_zorder "" Lista de IDs separadas por vírgulas que especificam a ordem dos objetos na página. toFront and toBack (and their associated context menu items) can re-order this list. Somente leitura.
Nome "" Título da página.
showgrid true Mostrar a grade no mapa.
showdarkness false Mostrar neblina de guerra no mapa.
showlighting false Usar iluminação dinâmica.
largura 25 Largura em unidades.
altura 25 Altura em unidades.
incremento_de_redução 1 Tamanho de um espaço de grelha em unidades.
opacidade da grelha 0.5 Opacidade das linhas de grelha.
opacidade do nevoeiro 0.35 Opacidade do nevoeiro de guerra para o GM.
cor de fundo "#FFFFFF" Cor hexadecimal do fundo do mapa.
cor da grelha "#C0C0C0" Hexadecimal color of the grid lines.
grid_type "square" One of "square", "hex", or "hexr". (hex corresponds to Hex(V), and hexr corresponds to Hex(H))
scale_number 5 The distance of one unit.
scale_units "ft" O tipo de unidades a serem usadas para a escala.
gridlabels falso Mostrar rótulos de grade para grade hexagonal.
diagonaltype "foure" Um dos "foure", "pitagórico" (euclidiano), "threefive" ou "manhattan".
arquivado falso Se a página foi colocada em armazenamento de arquivo.
lightupdatedrop false Only update Dynamic Lighting when an object is dropped.
lightenforcelos falso Imponha a linha de visão para os objectos.
lightrestrictmove falso Não permita que objectos com visão se desloquem através das paredes do Dynamic Lighting.
lightglobalillum falso Se for verdade, em qualquer sítio onde uma ficha possa "ver", presume-se que há uma luz brilhante presente.
gatilho da jukeboxtrigger   Controla a reprodução da página ao carregar. As opções incluem 'nonestopall' ou o id-da-faixa

Campanha

Propriedade Valor Padrão Notas
_id "root" Um ID único para este objeto. Globalmente único em todos os objetos deste jogo. Somente leitura.
_type "campanha" Pode ser usado para identificar o tipo de objeto ou procurar o objeto — no entanto, observe que há apenas um objeto de Campanha e ele pode ser acessado via Campanha(). Só de leitura.
ordem de rotação "" Uma cadeia JSON da ordem dos turnos. Veja abaixo.
iniciativapágina falso ID da página utilizada para o localizador quando a janela de ordem de turno está aberta. Quando definido parafalse, a janela de ordem de turno fecha-se.
playerpageid falso ID da página em que o marcador do jogador está definido. Os jogadores veem esta página por padrão, a menos que seja substituída por páginas específicas do jogador.
páginas específicas do jogador falso Um objeto (NÃO UMA STRING JSON) no formato: {"player1_id": "page_id", "player2_id": "page_id" ... } Qualquer jogador definido para uma página neste objeto substituirá o playerpageid.
_journalfolder "" Uma string JSON que contém dados sobre a estrutura de pastas do jogo. Somente leitura.
_jukeboxfolder "" Uma string JSON que contém dados sobre a estrutura da lista de reprodução da jukebox do jogo. Somente leitura.

 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

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "jogador" Pode ser utilizado para identificar o tipo de objeto ou para procurar o objeto. Só de leitura.
_d20userid   ID do utilizador - em todo o site. Por exemplo, a página de utilizador do jogador na wiki é /Usuário:ID, onde ID é o mesmo valor armazenado em _d20userid. Só de leitura.
_nome de exibição "" O nome de apresentação atual do jogador. Pode ser alterado na página de definições do utilizador. Só de leitura.
online falso Só de leitura.
página inicial "" O ID da página da última página que o jogador viu como GM. Esta propriedade não é actualizada para jogadores ou GMs que se tenham juntado como jogadores. Só de leitura.
_macrobar "" Cadeia de caracteres delimitada por vírgulas das macros na barra de macros do jogador. Só de leitura.
falando como "" O ID do jogador ou personagem que o jogador selecionou no menu suspenso "Como". Quando definido como uma string vazia, o jogador está falando como ele mesmo. Quando definido como um personagem, o valor é "personagem|ID", onde ID é o ID do personagem. Quando o Mestre está falando como outro jogador, o valor é "jogador|ID", onde ID é o ID do jogador.
cor "#13B9F0" A cor do quadrado pelo nome do jogador, assim como a cor das suas medições no mapa, seus círculos de ping, etc.
mostrarmacrobarra falso Se a barra de macro do jogador está sendo exibida.

Macro

Propriedade Valor Padrão Notas
_id   Um ID único para esse objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "macro" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
_playerid   O ID do jogador que criou esta macro. Só de leitura.
nome "" O nome da macro.
ação "" O texto da macro.
visível para "" Lista delimitada por vírgulas de IDs de jogadores que podem ver a macro, para além do jogador que a criou.

Todos os jogadoresé representado por "todos" na lista.

istokenaction falso Esta macro é uma ação de token que deve aparecer quando os tokens são selecionados?

 


Tabela Rolável

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "rollabletable" Pode ser usado para identificar o tipo de objeto ou procurar o objeto. Somente leitura.
Nome "nova-tabela"  
mostrarjogadores verdadeiro  

Item da Tabela 

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos neste jogo. Somente leitura.
_type "itemdetabela" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
_rollabletableid "" ID da tabela a qual este item pertence. Somente leitura.
avatar "" URL para uma imagem usada para o item da tabela. Veja a nota sobre restrições de avatar e imgsrc abaixo.
nome ""  
peso 1 Peso do item da tabela em comparação com os outros itens na mesma tabela. Simplificando, um item com peso 3 tem três vezes mais chances de ser selecionado ao rolar na tabela do que um item com peso 1.

Personagem

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos neste jogo. Somente leitura.
_type "personagem" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
avatar "" URL para uma imagem usada para o personagem. Veja a nota sobre restrições de avatar e imgsrc abaixo.
nome ""  
bio "" A biografia do personagem. Veja a nota abaixo sobre o acesso aos campos Notas, GMNotes e bio.
gmnotes "" Notas sobre o personagem visíveis apenas pelo GM. Veja a nota abaixo sobre o acesso aos campos Notas, GMNotes e bio.
arquivado falso  
emjornaisdojogador "" Lista separada por vírgulas de ID de jogadores que podem visualizar este personagem. Use "all" para dar a todos os jogadores a capacidade de visualizar.

Todos os Jogadores é representado por ter 'all' na lista.

controlledby "" Lista separada por vírgulas de IDs de jogadores que podem controlar e editar este personagem. Use "all" para dar a todos os jogadores a capacidade de editar.

Todos os Jogadores é representado por ter 'all' na lista.

_defaulttoken "" Uma string JSON que contém os dados do token padrão do personagem, se um estiver definido. Note that this is a "blob" similar to "bio" and "notes", so you must pass a callback function to get(). Read-only.

Attribute

Propriedade Valor Padrão Notas
_id   A unique ID for this object. Globally unique across all objects in this game. Read-only.
_type "attribute" Can be used to identify the object type or search for the object. Read-only.
_characterid "" ID do personagem a que este atributo pertence. Somente leitura. Obrigatório ao usarcreateObj.
nome "Sem título"  
atual "" O valor atual do atributo pode ser acessado no chat e macros com a sintaxe@{Character Name|Attribute Name}ou em habilidades com a sintaxe@{Attribute Name}.
máx "" O valor máximo do atributo pode ser acessado no chat e macros com a sintaxe@{Character Name|Attribute Name|max}ou em habilidades com a sintaxe@{Attribute Name|max}.

 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

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "habilidade" Pode ser usado para identificar o tipo de objeto ou procurar pelo objeto. Somente leitura.
_characterid "" O personagem a que essa habilidade pertence. Somente leitura. Obrigatório ao usarcreateObj.
nome "Untitled_Ability"  
descrição "" A descrição não aparece na interface da ficha do personagem.
ação "" O texto da habilidade.
istokenaction false Esta habilidade é uma ação de token que deve aparecer quando tokens vinculados ao seu personagem pai são selecionados?

Folheto

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos neste jogo. Somente leitura.
_type "handout" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
avatar "" URL para uma imagem usada para o handout. Veja a nota sobre restrições de avatar e imgsrc abaixo.
nome "Mysterious Note"  
anotações "" Contém o texto no folheto. Veja a nota abaixo sobre o uso de Anotações e Anotações do Mestre.
gmnotes "" Contém o texto no folheto que apenas o Mestre vê. Veja a nota abaixo sobre o uso de Anotações e Anotações do Mestre.
inplayerjournals "" Lista separada por vírgulas de ID de jogadores que podem ver este folheto. Use "all" para exibir para todos os jogadores.

Todos os Jogadores são representados ao ter 'todos' na lista.

arquivado falso  
controladopor "" Lista delimitada por vírgulas de IDs de jogadores que podem controlar e editar este documento.

Todos os Jogadores são representados ao ter 'todos' na lista.

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.

Propriedade Valor Padrão Notas
_id "" id do baralho
_type "baralho"  
nome "" nome do baralho
_currentDeck "" uma lista separada por vírgulas de cartas que estão atualmente no baralho (incluindo aquelas que foram jogadas na mesa/mãos). Muda quando o baralho é embaralhado.
_currentIndex -1 o índice atual do nosso lugar no baralho, 'qual carta será retirada em seguida?'
_currentCardShown true mostrar a carta atual no topo do baralho
showplayers true mostrar o baralho para os jogadores
playerscandraw true os jogadores podem comprar cartas?
avatar "" o 'verso' das cartas deste baralho
visível falso mostrar o baralho no tabuleiro (o baralho está atualmente visível?)
jogadores_veemcartas verdadeiro os jogadores podem ver o número de cartas nas mãos dos outros jogadores?
jogadores_veemfrentedascartas falso os jogadores podem ver a frente das cartas ao olhar nas mãos de outros jogadores?
gm_seenumcards verdadeiro o GM pode ver o número de cartas na mão de cada jogador?
gm_seefrontofcards falso o GM pode ver a frente das cartas ao olhar nas mãos de cada jogador?
cartasinfinite falso há um número 'infinito' de cartas neste baralho?
_cardSequencer -1 usado internamente para avançar o baralho ao retirar cartas.
cartasjogadas "faceup" como as cartas deste baralho são jogadas na mesa? 'faceup' ou 'facedown'.
altura padrão "" qual é a altura padrão para as cartas jogadas na mesa?
largura predefinida ""  
modo de descarte "nenhum" que tipo de pilha de descarte tem este baralho? 'none' = não há pilha de descarte, 'choosebacks' = permite que os jogadores vejam as costas das cartas e escolham uma, 'choosefronts' = veja as frentes e escolha, 'drawtop' = compra a carta descartada mais recentemente, 'drawbottom' = compra a carta descartada mais antiga.
_discardPile "" qual é a pilha de descarte atual para este baralho? lista de cartões delimitada por vírgulas. Estas são cartas que foram removidas do jogo e não serão colocadas de volta no baralho até que uma retirada seja efectuada.

Cartão

Propriedade Valor Padrão Notas
nome "" Nome do cartão
avatar "" Frente do cartão
_deckid "" ID do baralho
_tipo "cartão"  
_id ""  

Mão

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

Propriedade Valor Padrão Notas
currentHand "" lista separada por vírgula de cartas atualmente na mão. Observe que isso não é mais apenas leitura. Idealmente, isso deve ser ajustado apenas com as funções do baralho de cartas.
_type "mão"  
_parentid "" ID do jogador a quem a mão pertence
_id ""  
currentView "porbaralho" quando o jogador abre a mão, a visualização é 'porbaralho' ou 'porcarta'?

Faixa de Jukebox

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "jukeboxtrack" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
jogando falso Booleano usado para determinar se a faixa está tocando ou não. Configurando isso como "verdadeiro" e softstop como "falso" toca uma faixa.
softstop falso Booleano usado para determinar se uma faixa não repetida terminou pelo menos uma vez. Isso deve ser definido como "falso" para garantir que uma faixa seja reproduzida.
título "" O rótulo visível para a faixa na guia jukebox.
volume 30 O nível de volume da faixa. Note que isso deve ser definido como um número inteiro (não uma string), ou você pode quebrar a funcionalidade. Valores de 0 a 100 (porcentagem).
loop falso A faixa deve ser repetida? Defina como verdadeiro se sim.

Personalizado 3

Propriedade Valor Padrão Notas
_id   Um ID único para este objeto. Globalmente único entre todos os objetos deste jogo. Somente leitura.
_type "custfx" Pode ser usado para identificar o tipo de objeto ou pesquisar o objeto. Somente leitura.
nome "" O nome visível para o FX na listagem de FX.
definição {} Objeto JavaScript descrevendo o FX.

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:


No futuro, podemos adicionar uma ferramenta para que imagens possam ser carregadas especificamente para uso com scripts de API, mas por enquanto, apenas use imagens carregadas em sua própria biblioteca. Observe que se você excluir uma imagem de sua biblioteca, ela será removida de todos os Jogos que usam essa imagem, incluindo Jogos que usam seus scripts de 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.

Tipo Exemplos Descrição
Booleano verdadeiro falso O valor verdadeiro ou falso.
Número 123.5 10 1.23e20 Any number format supported by Javascript. Floating-Point or Integer.
String 'Hello Fantasy' "oh, and World" A standard string of text.
Array [ 1, 2, 3, 4 ] [ 'A','B','C'][1, 2, ['bob', 3], 10, 2.5] Uma coleção ordenada de qualquer um dos tipos, incluindo outras matrizes.
Objeto { key: 1, value: 'roll20' } Um objeto simples de chave/valor com chaves de string e qualquer um dos tipos como valor, incluindo outros objetos.

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

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');
    }
}
Este artigo foi útil?
Utilizadores que acharam útil: 19 de 21