Rolagens, chat e cartão

Rolagens

Sem JavaScript, um botão com data-roll rola na mesa:

<button data-roll="1d20 + {mod_forca}" data-label="Força de {nome}">Força</button>

No data-roll, {caminho} vira o número do campo (vazio vira 0). Um negativo fica certo: 1d20 + {mod} com -2 rola 1d20 - 2.
No data-label, {caminho} vira o texto do campo.
Dentro de uma lista, os caminhos são do item: data-roll="1d20 + {bonus}".

Pelo JavaScript, a rolagem devolve o resultado:

const r = await RPGDesk.dice.roll('2d6+3', { label: 'Dano do machado' });
r.total;      // 11
r.items;      // [{ kind: 'dice', sign: 1, faces: 6, results: [5, 3] }, { kind: 'value', sign: 1, value: 3 }]
r.successes;  // só nas rolagens de sucessos ('5d10 > 7'): quantos

As rolagens são as mesmas do chat (veja Rolagens) e aparecem no chat para todos, com os dados 3D. Quem rola é o servidor, não a página.

Chat

await RPGDesk.chat.send('ataca o orc com o machado', { kind: 'action' });
await RPGDesk.chat.send('Ninguém passa!', { kind: 'npc', name: 'Guardião' });
await RPGDesk.chat.local('Só você vê esta linha.');

kind: 'chat' (o padrão), 'action' (como o /me), 'laugh', 'narrator' ou 'npc' (com o name do NPC). local escreve uma linha no chat só de quem está vendo.

O cartão do jogador

Os cartões em Participantes têm barras (vida, energia…) e linhas de texto. A ficha preenche as do dono dela:

RPGDesk.card.setBar(0, 18, 22);        // a barra 1: 18 de 22
RPGDesk.card.setBar(1, 9, 12);         // a barra 2
RPGDesk.card.setLine(0, 'Envenenado'); // a linha 1

O número da barra começa em 0: setBar(0, …) é a Barra 1 das regras de jogo da mesa, e setBar(3, …), a última. As linhas também vão de 0 a 3. Quantas aparecem, os nomes e as cores, quem decide é o mestre.
Os valores são arredondados. Máximo 0 tira a barra.
Todos com a ficha aberta rodam o mesmo código; o RPG Desk só aceita o pedido de quem pode mudar aquele cartão (o dono e os mestres). Para os outros, a chamada não faz nada.

O jeito comum é acompanhar a vida e mandar para a barra:

doc.watch('pv', (pv) => {
  if (pv && typeof pv === 'object') RPGDesk.card.setBar(0, Number(pv.atual) || 0, Number(pv.max) || 0);
}, { now: true });

Numa tabela da sala, que não tem dono, diga de quem é o cartão: RPGDesk.card.setBar(0, 7, 12, { userId }).

Avisos, perguntas e menus

Dentro do RPG Desk, alert, confirm e prompt não funcionam. Use os do RPG Desk:

RPGDesk.ui.toast('Ficha salva!');                         // 'info', 'success' ou 'error'
const sim = await RPGDesk.ui.confirm('Apagar o inventário?');      // true ou false
const nome = await RPGDesk.ui.prompt('Nome do item?', 'Corda');    // o texto, ou null
const escolha = await RPGDesk.ui.menu(
  [{ id: 'atacar', label: 'Atacar' }, { separator: true }, { id: 'apagar', label: 'Apagar', danger: true }],
  evento,                                                // o clique (MouseEvent) ou { x, y }
);                                                       // o id escolhido, ou null

E mais:

RPGDesk.ui.openLink(url): abre um site noutra aba, depois de a pessoa confirmar;
RPGDesk.ui.copy(texto): copia para a área de transferência;
RPGDesk.ui.download('ficha.json', texto): oferece um arquivo para baixar (até 20 MB);
RPGDesk.ui.openItem(id): abre uma ficha ou cena da biblioteca.

Imagens

const escolhida = await RPGDesk.files.pickImage();   // { id } ou null
if (escolhida) await doc.set('retrato', escolhida.id);
img.src = await RPGDesk.files.url(doc.get('retrato'));

pickImage abre a escolha de imagem do RPG Desk (do computador ou das imagens da mesa). Guarde o id no documento; files.url dá um endereço para o <img>. Com data-image, o rpgdesk.js faz isso sozinho (veja Imagens).

Preferências e estado da tela

RPGDesk.storage.get(chave) e RPGDesk.storage.set(chave, valor): preferências da pessoa, neste navegador, para o seu plugin (até 1 MB). O localStorage não funciona dentro do RPG Desk.
RPGDesk.view.get(chave) e RPGDesk.view.set(chave, valor): o estado da tela desta ficha (a aba aberta, um filtro), até 100 KB. Sobrevive quando a ficha muda de espaço ou vai para uma janela própria.

Os dados do personagem vão no documento (doc), nunca no storage: o storage não chega aos outros.