Scripts de modificação: Documentação das funções

28 de Setembro de 2026 14:51

O Roll20 disponibiliza uma série de funções que não fazem parte do JavaScript básico nem de qualquer outra biblioteca.

Os jogos podem utilizar o Mod Script Sandbox v1.0 (Campaign().sandboxVersion === "1.0") ou v1.5 ("1.5"). Funcionalidades disponíveis apenas na versão Mod Script Sandbox v1.5. não funcionam na versão 1.0.

Variáveis globais

Variável	Descrição:
`_`	Este é o objeto de espaço de nomes da biblioteca Underscore.js.
`estado`	As propriedades do objeto de estado serão mantidas entre as sessões do jogo.

_ (traço inferior)

Este é o objeto de espaço de nomes da biblioteca 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 de uma campanha; por isso, recomenda-se vivamente que, ao gravar valores no estado, minimize ao máximo a sua pegada, a fim de evitar conflitos 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

Tipo de retorno	Função	Descrição:
`Objeto Roll20`	`Campanha`	Obtém o objeto Campaign Roll20 singleton.
`Objeto Roll20`	`criarObj`	Cria um novo objeto Roll20.
`Matriz de objetos Roll20`	`filtrarObjs`	Obtém todos os objetos Roll20 que passam num teste de predicado.
`Matriz de objetos do Roll20`	`encontrarObjs`	Obtém todos os objetos Roll20 com propriedades que correspondem a um determinado conjunto de atributos.
`Matriz de objetos do Roll20`	`obterTodosObj`	Obtém todos os objetos Roll20 na campanha.
`varia`	`obterAtributoPorNome`	Obtém o valor atual ou máximo de um atributo do objeto Roll20.
`varia`	`getComputed`	Apenas para o Mod Script Sandbox v1.5. Obtém uma propriedade calculada do Beacon.
`varia`	`getSheetDefaultValue`	Obtém o valor predefinido de uma ficha de personagem para um determinado nome de atributo.
`varia`	`getSheetItem`	Recupera um elemento da folha (atributo; na v1.5, também Beacon / `user.*`).
`Objeto Roll20`	`obterObj`	Obtém um objeto Roll20 específico.
	`registro`	Regista uma mensagem na Consola de Saída do Mod.
	`no`	Regista um manipulador de eventos.
	`noSheetWorkerConcluído`	Regista um manipulador de eventos único para ser executado após a conclusão de uma pilha completa de scripts do Sheet Worker.
	`executarAção`	Apenas para o Mod Script Sandbox v1.5. Executa uma ação da folha do Beacon.
`Booleano`	`O jogador é o GM`	Verifica se um jogador possui atualmente privilégios de GM.
	`playJukeboxPlaylist`	Inicie a reprodução de uma lista de reprodução da jukebox.
`Número`	`número inteiro aleatório`	Gera um valor inteiro aleatório.
	`enviarChat`	Envia uma mensagem de chat.
	`enviarPing`	Envia um ping semelhante a manter pressionado o botão esquerdo do mouse.
	`setAttrs`	Define um ou mais atributos de um personagem.
	`setComputed`	Apenas para o Mod Script Sandbox v1.5. Define uma propriedade computada do Beacon que pode ser gravada.
	`setSheetItem`	Define um elemento da folha (atributo; na v1.5, também Beacon / `user.*`).
	`spawnFx`	Gera um emissor de partículas.
	`gerar efeito entre pontos`	Gera um emissor de partículas que se move de um ponto para outro.
	`gerarEfeitoComDefinição`	Gera um emissor de partículas que não é representado por um objeto FX Roll20.
	`Parar a lista de reprodução da Jukebox`	Interrompe todas as listas de reprodução atualmente em execução no jukebox.
	`paraCima`	Apenas para o Mod Script Sandbox v1.5. Coloca um objeto imediatamente acima de outro na mesma camada.
	`Voltar`	Desloca um elemento gráfico, texto, trajetória ou trajetória v2 para uma posição inferior em relação aos outros objetos da sua camada.
	`para abaixo`	Apenas para o Mod Script Sandbox v1.5. Coloca um objeto imediatamente abaixo de outro na mesma camada.
	`para a frente`	Desloca um elemento gráfico, texto, trajetória ou trajetória v2 para cima, colocando-o acima dos outros objetos da sua camada. Passe o objeto, e não um identificador.
	`Ajudantes de cartas`	`shuffleDeck`, `cardInfo`, `recallCards`, `dealCardsToTurn`, `drawCard`, `pickUpCard`, `takeCardFromPlayer`, `playCardToTable`, `giveCardToPlayer` — consulte Objetos: Baralho.

Campanha

Parâmetros

Sem parâmetros

Devoluções

O objeto Roll20 da campanha singleton.

Exemplos

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

Campaign().sandboxVersion é «1.0» ou «1.5». Campaign().nodeVersion é a cadeia de caracteres que indica a versão do Node.js. Apenas para o Mod Script Sandbox v1.5. sheetName, computedSummary e actionSummary. Consulte Objetos: Campanha.

`criarObj`

Parâmetros

TIPO (String) O tipo de objeto Roll20 a criar. Pode criar «graphic», «text», «path», «pathv2», «character», «ability», «attribute», «handout», «rollabletable», «tableitem», «macro», «card», «deck», «custfx», «window», «door» e «pin». Apenas para o Mod Script Sandbox v1.5. 'pageFolder'.

ATRIBUTOS (Objeto) Os valores iniciais a utilizar nas propriedades do objeto Roll20.

Devoluções

O objeto Roll20 que foi criado.

Exemplos

Ao criar um objeto Roll20 que tenha um objeto pai (como, por exemplo, ao criar um objeto Roll20 do tipo «atributo», que é um objeto filho de um objeto Roll20 do tipo «personagem»), deve indicar o ID do objeto pai na secção «atributos».

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

Ao criar um caminho, indique o caminho (armazenado como _path) e o ID da página. O caminho sem o sublinhado corresponde ao nome atribuído no momento da criação. A partir daí, fica apenas para leitura.

createObj('path', {
  pageid: Campaign().get('playerpageid'),
  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 «handout» no Roll20, não é possível definir o texto nem as notas do mestre no momento da criação.

var handout = createObj('handout', {
  name: 'Uma carta endereçada a si',
  inplayerjournals: 'all',
  archived: false
});
handout.set('notes', 'As notas só podem ser definidas após a criação do material didático.');
handout.set('gmnotes', 'Defina as gmnotes numa chamada separada das notas.');

filtrarObjs

Parâmetros

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

Devoluções

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

encontrarObjs

Parâmetros

ATRIBUTOS (Objeto) Uma coleção de pares chave:valor para corresponder aos objetos do Roll20 na campanha.

OPÇÕES (Objeto, opcional)

caseInsensitive — se for «true», as comparações de cadeias de caracteres não distinguem maiúsculas de minúsculas.
startsWith — se for verdadeiro, os valores de cadeia de caracteres correspondem como prefixo.
tagMatch — na correspondência de etiquetas: «all» (predefinição; o objeto possui todas as etiquetas indicadas), «any» (pelo menos uma), «only» (exatamente o conjunto indicado).

Devoluções

Uma matriz de objetos Roll20 cujas propriedades correspondem aos atributos. As chaves podem omitir o sublinhado inicial: tanto «type» como «_type» são válidos.

Exemplos

var npcs = findObjs({ type: 'character', controlledby: '' });
var knights = findObjs({ type: 'character', name: 'Sir' }, { startsWith: true });

obterTodosObj

Parâmetros

Sem parâmetros

Devoluções

Uma matriz de todos os objetos Roll20 na campanha.

obterAtributoPorNome

Parâmetros

CHARACTER_ID (String) O identificador da personagem. ATTRIBUTE_NAME (String) O nome do atributo. VALUE_TYPE (Cadeia de caracteres, opcional) «current» ou «max» (o valor predefinido é «current»).

Devoluções

A propriedade «current » ou «max ». Caso não seja definido, é utilizada a predefinição da ficha de personagem (se existir).

getComputed

Apenas para o Mod Script Sandbox v1.5. (Na versão 1.0, este nome corresponde a um stub sem funcionalidade.)

Parâmetros

Um objeto: { characterId, property, args?, playerId? }.

Ao utilizar uma ficha de personagem do Beacon, obtém o valor de uma propriedade calculada. Enumere os nomes com Campaign().computedSummary. O «playerId» é opcional; algumas funcionalidades do Beacon (por exemplo, consultas «roll») exigem-no.

getSheetDefaultValue

Parâmetros

ATTRIBUTE_NAME (Cadeia de caracteres), VALUE_TYPE (Cadeia de caracteres, opcional) «current» ou «max».

Devoluções

O valor predefinido da folha para esse campo, e não o valor real do caractere.

getSheetItem

Parâmetros

getSheetItem(characterId, property, valtype?, options?) — assíncrono (Promise).

Na versão 1.0, isto envolve o getAttrByName. Apenas para o Mod Script Sandbox v1.5. Nas folhas Beacon, também são lidas propriedades calculadas e atributos personalizados com o nome user.*.

obterObj

Parâmetros

TIPO (Cadeia de caracteres), ID (Cadeia de caracteres)

Devoluções

O objeto Roll20 especificado.

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

registo

Parâmetros

MENSAGEM (varia) Apresentada na consola de saída do Mod. Convertido com JSON.stringify.

Apenas para o Mod Script Sandbox v1.5. As mensagens de erro incluem frequentemente um objeto de contexto, como [Personagem do Roll20 -id].

no

Parâmetros

EVENTO (String) Existem cinco tipos de evento: ready, change, add, destroy, chat. Exceto no caso de «ready», associe o evento a um tipo de objeto. No caso do chat, esse tipo é sempre «mensagem». Os eventos de alteração também podem indicar uma propriedade, um identificador de objeto ou ambos: change:graphic:left, change:graphic:ID, change:graphic:ID:left. Os gráficos também disparam eventos de subtipo, tais como «change:token » e «change:dicetoken». Consulte a secção «Eventos».

Os eventos «CALLBACK (Função) ready» não têm parâmetros de callback. Os eventos de alteração têm um parâmetro «obj» (o objeto Roll20 após a alteração) e um parâmetro «prev» (um objeto JavaScript simples com as propriedades anteriores à alteração). Os eventos «add» têm um parâmetro «obj» (o novo objeto). Os eventos «destroy» têm um parâmetro «obj» (o objeto que já não existe). Os eventos de chat têm um parâmetro «msg» (detalhes da mensagem).

Devoluções

(Nulo)

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 propriedade «left» de um objeto gráfico do Roll20 fará com que a função 3 seja chamada, seguida da função 1 e, em seguida, da função 2.

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

A função «Adicionar eventos» tentará ser acionada para os objetos do Roll20 que já se encontrem na campanha quando uma nova sessão tiver início. Para evitar este comportamento, pode aguardar até que o evento «ready» seja acionado para registar o seu evento «add ».

on('add:graphic', function(obj) {
  // Quando a sessão tiver início, esta função será chamada para cada elemento gráfico da campanha
});
on('ready', function() {
  on('add:graphic', function(obj) {
    // Esta função será chamada *apenas* quando for criado um novo objeto gráfico Roll20
  });
});

O parâmetro «prev» para eventos de alteração não é um objeto Roll20. Não pode utilizar «get» nem «set», nem pode omitir os sublinhados iniciais nas propriedades de leitura exclusiva. Utilize «prev._id», e não «prev.id».

No caso dos campos «blob» de personagens e de folhetos (biografia, notas, notas do mestre) e do campo _defaulttoken da personagem, o valor «prev» não corresponde ao texto. O gráfico «gmnotes» é uma cadeia de caracteres comum. Guarde na cache os valores anteriores dos blobs, caso precise deles.

noSheetWorkerConcluído

Parâmetros

CALLBACK (Função) É chamada quando a pilha atual de scripts do Sheet Worker é concluída. Destinado a ser chamado antes de «setWithWorker». É executado apenas uma vez. A função de retorno pode receber { workersExecuted: boolean }.

executarAção

Apenas para o Mod Script Sandbox v1.5. (Na versão 1.0, este nome é um stub sem funcionalidade.)

Parâmetros

{ characterId, action, args?, playerId? }

Executa uma ação da folha do Beacon. Enumere os nomes com Campaign().actionSummary. O «playerId» é opcional; algumas funcionalidades do Beacon exigem-no. Se o nome não corresponder a uma ação do Beacon, a v1.5 poderá recorrer a uma habilidade de personagem com esse nome através do sendChat.

O jogador é o GM

Parâmetros

PLAYER_ID (Cadeia de caracteres)

Devoluções

verdadeiro se o jogador tiver, neste momento, permissões de GM.

É particularmente útil para restringir os comandos do Mod Script ao uso exclusivo dos GM. Mantenha «msg.type !== 'api'» tal como está escrito — trata-se do tipo de mensagem de comando.

playJukeboxPlaylist

Parâmetros

PLAYLIST_ID (String) O identificador da lista de reprodução cuja reprodução se pretende iniciar.

número inteiro aleatório

Parâmetros

MAX (Número) Máximo inclusivo.

Devoluções

Um número inteiro aleatório entre 1 e max. Prefira esta função em vez de Math.random() para intervalos semelhantes aos de um dado.

sendChat Assíncrono

Parâmetros

SPEAKINGAS (String) Um nome, ou jogador|id_do_jogador / personagem|id_da_personagem. MENSAGEM (String). CALLBACK (Função, opcional) — os resultados são transmitidos à função de callback, em vez de aparecerem no chat. OPÇÕES (Objeto, opcional) noarchive, use3d.

Consulte «Mod Scripts: Chat» para obter informações sobre os botões de comando ([label](!command)).

enviarPing

Parâmetros

ESQUERDA, PARTE SUPERIOR, PAGE_ID, PLAYER_ID (opcional), MOVEALL (opcional), VISIBLETO (opcional). Se o «player_id» for omitido, o ping é amarelo. Se moveAll for verdadeiro, as visualizações ficam centradas no ponto de referência. O parâmetro «visibleTo» pode ser um ID de jogador, um conjunto de IDs ou uma cadeia de caracteres delimitada por vírgulas.

setAttrs

Parâmetros

CHARACTER_ID (cadeia de caracteres), ATTRIBUTE_OBJ (objeto do tipo nome → valor). Os nomes que terminam em _max definem o valor máximo. São suportados $n nomes são permitidos. O `options.silent ` utiliza o método ` set` em vez de ` setWithWorker`.

setComputed

Apenas para o Mod Script Sandbox v1.5.

{ characterId, property, args?, playerId? } — define uma propriedade computada Beacon gravável. Consulte Campaign().computedSummary.

setSheetItem

setSheetItem(characterId, property, value, valtype?, options?) — assíncrono. Na versão 1.0, define os atributos. Apenas para o Mod Script Sandbox v1.5. Além disso, propriedades computadas do Beacon e atributos personalizados «user.* ». As opções incluem createAttr, withWorker e allowThrow.

spawnFx

Parâmetros

ESQUERDA (Número) A coordenada x na qual se deve colocar o emissor de partículas. TOP (Número) A coordenada y. TIPO (String) Para efeitos integrados, «tipo-cor», em que «tipo» pode ser «bomba», «bolhas», «queimadura», «explosão», «brilho», «míssil» ou «nova» e «cor» pode ser «ácido», «sangue», «encanto», «morte», «fogo», «gelo», «sagrado», «magia», «lodo», «fumo» ou «água». No caso de efeitos personalizados, o identificador de um objeto custfx. Nota: os efeitos «beam», «breath» e «splatter» não podem ser utilizados com o «spawnFx» — consulte «spawnFxBetweenPoints». PAGE_ID (cadeia de caracteres, opcional) tem como valor predefinido Campaign().get('playerpageid').

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

gerar efeito entre pontos

Parâmetros

START (Objeto) { x, y }. END (Objeto) { x, y }. TYPE (String) como spawnFx, além de beam, breath e splatter. PAGE_ID (cadeia de caracteres, opcional).

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

Apenas para o Mod Script Sandbox v1.5. Os efeitos do tipo «viga» apontam diretamente para o ponto final (foi corrigido um erro no cálculo do ângulo).

gerarEfeitoComDefinição

Parâmetros

ESQUERDA, PARTE SUPERIOR, DEFINIÇÃO (objeto que descreve o emissor), PAGE_ID (opcional). Consulte o artigo «Efeitos personalizados nos objetos» para conhecer os nomes das propriedades.

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

Parar a lista de reprodução da Jukebox

Interrompe todas as listas de reprodução da jukebox que estão a ser reproduzidas neste momento.

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

Ajudantes de cartas

Disponível em ambas as versões de sandbox. Encontrará todos os detalhes em «Mod Scripts: Objetos (Convés)».

shuffleDeck(deckid, discard, newOrder)
cardInfo(configurações)
recallCards(deckid, type)
dealCardsToTurn(deckid)
drawCard(deckid, cardid)
pickUpCard(cardid, fromDiscard)
takeCardFromPlayer(playerid, options)
playCardToTable(cardid, settings)
giveCardToPlayer(cardid, playerid)

setDefaultTokenForCharacter

CARÁCTER (objeto de carácter), TOKEN (objeto gráfico). Ambos têm de já existir. Grava o blob _defaulttoken da personagem a partir do token. Esta é a forma de definir esse campo; a função set() não o faz.

paraCima

Apenas para o Mod Script Sandbox v1.5.

Parâmetros

OBJ (gráfico, texto, caminho ou caminho v2), TARGET (objeto ou id).

Coloca o objeto imediatamente acima do alvo, na mesma camada.

para trás / para a frente

OBJ deve ser um gráfico, texto, percurso ou pathv2. Passe o objeto, e não um identificador. Na versão 1.5, estes são substancialmente mais rápidos, e esses tipos também dispõem de métodos de instância toFront() / toBack().

para abaixo

Apenas para o Mod Script Sandbox v1.5.

Coloca o objeto «obj» imediatamente abaixo do destino (objeto ou ID) na mesma camada.