A API do rpgdesk.js

O rpgdesk.js cria o objeto global RPGDesk. Quase tudo devolve uma promessa (Promise): use await ou .then(). As chamadas feitas antes de conectar esperam a conexão. Para aprender com exemplos, veja JavaScript na ficha e Rolagens, chat e cartão.

RPG Desk


`RPGDesk.connect()`	conecta (ao RPG Desk ou ao modo de teste) e devolve o contexto, com o `doc`
`RPGDesk.context`	o contexto, depois de conectar (antes, `null`)
`RPGDesk.doc`	o documento, depois de conectar (antes, `null`)
`RPGDesk.version`	a versão do rpgdesk.js (`'1.0.0'`)
`RPGDesk.on(evento, fn)`	ouve um evento da mesa; devolve a função que para de ouvir
`RPGDesk.bind(elemento)`	liga os atributos `data-…` de um pedaço da página criado à mão

O contexto

{
  kind: 'sheet' | 'table',
  item: { id: string, name: string, type: string, ownerId: string | null },
  me: { id: string, nick: string, role: 'gm' | 'player' | 'spectator', isOwner: boolean },
  room: { id: string, name: string, system: string },
  language: 'pt' | 'en',
  test: boolean,                       // fora do RPG Desk, no modo de teste
  plugin: { id: string, version: string },
  doc: Doc,
}

Eventos

Evento	`fn` recebe	Quando
`'players'`	a lista de jogadores (como `RPGDesk.room.players()`)	alguém entra, sai ou muda
`'library'`	os itens da biblioteca (como `RPGDesk.room.library()`)	a biblioteca muda
`'me'`	o novo `me`	o papel da pessoa muda
`'language'`	`'pt'` ou `'en'`	a pessoa troca a língua do RPG Desk
`'theme'`	as variáveis do tema	as cores da mesa mudam

O documento (`doc`)


`doc.get(caminho)`	o valor: texto, número, `true`/`false`, um objeto (grupo) ou `undefined`. `doc.get('')` dá o documento inteiro
`doc.set(caminho, valor)`	grava. Um objeto grava campo a campo; `null` apaga. Devolve uma promessa
`doc.update({ caminho: valor, … })`	grava vários campos num lote
`doc.batch(() => { … })`	o que for gravado dentro da função vai num lote só, aplicado inteiro ou recusado inteiro
`doc.watch(caminho, fn, { now })`	avisa a cada mudança no caminho ou dentro dele: `fn(valor, { local })`. Devolve a função que para
`doc.compute(alvo, [fontes], fn)`	campo calculado: grava `fn(...valores das fontes)` no alvo quando uma fonte muda neste navegador, se a pessoa pode escrever no alvo. `undefined` não grava. Devolve a função que para
`doc.canWrite(caminho)`	se a pessoa pode escrever ali
`doc.list(caminho)`	a lista no caminho (veja abaixo)
`doc.restrict(caminho, 'gm' \| 'owner' \| null)`	só mestres: a parte passa a ser só dos mestres, só do dono e dos mestres, ou de todos de novo
`doc.on('rejected', fn)`	avisa quando uma gravação é recusada: `fn(mensagem)`. Devolve a função que para

Os caminhos são textos ('pv.atual') ou listas (['npcs', '#' + id, 'pv']); #id aponta um item de lista.

Listas

doc.list(caminho) devolve:


`items()`	os itens, em ordem: `[{ id, …campos }]`
`length`	quantos itens
`add(valor?, posição?)`	cria um item (no fim, ou na posição) e devolve o `id` dele na hora
`remove(id)`	apaga o item
`move(id, posição)`	muda o item de lugar
`item(id)`	o item: `{ id, get(campo), set(campo, valor), watch(campo, fn, { now }), remove() }`
`watch(fn, { now })`	avisa a cada mudança na lista ou nos itens: `fn(itens, { local })`

Dados e chat


`RPGDesk.dice.roll(expressão, { label })`	rola na mesa (com os dados 3D, no chat de todos). Devolve `{ expression, total, items, successes }`
`RPGDesk.chat.send(texto, { kind, name })`	manda ao chat. `kind`: `'chat'`, `'action'`, `'laugh'`, `'narrator'` ou `'npc'` (com `name`)
`RPGDesk.chat.local(texto)`	uma linha no chat só de quem está vendo

Os items de uma rolagem: { kind: 'dice', sign, faces, results }, { kind: 'fudge', sign, results } ou { kind: 'value', sign, value }. successes só existe nas rolagens com >.

A mesa e o cartão


`RPGDesk.room.players()`	quem está na mesa: `[{ id, nick, role, avatar, mainCharacterId }]`
`RPGDesk.room.library()`	os itens da biblioteca que a pessoa vê: `[{ id, name, kind, type, ownerId, parentId }]`
`RPGDesk.room.on('players' \| 'library', fn)`	o mesmo que `RPGDesk.on`
`RPGDesk.card.setBar(índice, valor, máximo, { userId })`	a barra do cartão: o índice vai de 0 (a Barra 1) a 3. Na ficha, o cartão é o do dono; na tabela, passe o `userId`. Máximo 0 tira a barra
`RPGDesk.card.setLine(índice, texto, { userId })`	a linha do cartão: o índice vai de 0 a 3; até 120 caracteres

Interface


`RPGDesk.ui.toast(texto, tipo)`	um aviso. `tipo`: `'info'`, `'success'` ou `'error'`
`RPGDesk.ui.confirm(texto, { title })`	uma pergunta de sim ou não: `true` ou `false`
`RPGDesk.ui.prompt(texto, inicial)`	pede um texto: o texto, ou `null` se a pessoa cancelar
`RPGDesk.ui.menu(itens, onde)`	um menu do RPG Desk. `itens`: `{ id, label, disabled?, danger? }` ou `{ separator: true }`; `onde`: o `MouseEvent` ou `{ x, y }`. Devolve o `id` escolhido ou `null`
`RPGDesk.ui.openItem(id)`	abre uma ficha ou cena da biblioteca
`RPGDesk.ui.openLink(url)`	abre um site `http(s)` noutra aba, depois de a pessoa confirmar: `true` se abriu
`RPGDesk.ui.copy(texto)`	copia para a área de transferência
`RPGDesk.ui.download(nome, dados, tipo)`	oferece um arquivo para baixar: `dados` é um texto, `Blob` ou `ArrayBuffer` (até 20 MB)

Arquivos, preferências e estado da tela


`RPGDesk.files.pickImage()`	abre a escolha de imagem do RPG Desk: `{ id }` ou `null`
`RPGDesk.files.url(id)`	um endereço para mostrar o arquivo num `<img>`
`RPGDesk.storage.get(chave)`, `set(chave, valor)`, `keys()`	as preferências da pessoa, neste navegador, para o seu plugin (até 1 MB)
`RPGDesk.view.get(chave)`, `set(chave, valor)`	o estado da tela desta ficha; `get` responde na hora (sem promessa)

Webhooks


`RPGDesk.webhooks.send(nome, dados)`	manda os dados ao webhook declarado no manifesto, pelo servidor. Devolve `{ ok, status, body, error }`

Veja os códigos de error em Webhooks na ficha.