# A API do rpgdesk.js > Todas as funções do objeto RPG Desk e do documento, com os parâmetros e o que devolvem. Página: https://docs.rpgdesk.com/referencia/api/ 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](https://docs.rpgdesk.com/fichas/javascript/) e [Rolagens, chat e cartão](https://docs.rpgdesk.com/fichas/rolagens-e-chat/). ## 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 ```ts { 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 `` | | `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](https://docs.rpgdesk.com/fichas/webhooks/). > **Erros** > > Um pedido recusado rejeita a promessa com um erro (`RpgDeskError`), com a mensagem na língua do RPG Desk. Os erros que escapam do seu código vão para os **Erros da página**, na mesa, e para o **Registro**, no modo de teste.