Criar fichas e referência do RPG Desk. As seções Criar fichas e Referência da documentação do RPG Desk: tudo o que se usa para escrever fichas e tabelas da mesa em HTML, CSS e JavaScript com o rpgdesk.js.
# Criar fichas
> Fichas e tabelas da mesa feitas em HTML, CSS e JavaScript, à mão ou com ajuda de uma IA.
Página: https://docs.rpgdesk.com/fichas/
No RPG Desk, uma ficha é uma página web: **HTML** para os campos, **CSS** para o visual e, se precisar, **JavaScript** para as contas. O **rpgdesk.js**, a biblioteca do RPG Desk, liga a página à mesa:
- o que o jogador escreve fica guardado na mesa e aparece na hora para o mestre;
- os botões de rolagem rolam no chat, com os dados 3D, para todos;
- só o dono da ficha e os mestres escrevem; os outros só leem, e o rpgdesk.js trava os campos sozinho;
- partes da ficha podem ser só do mestre, e elas nem chegam aos jogadores.
A ficha abaixo está funcionando. Escreva nos campos e clique em **Rolar Força**:
*Exemplo funcionando:* [Ficha mínima](https://docs.rpgdesk.com/exemplos/ficha-minima.html)
Ela não tem nenhuma linha de JavaScript: cada campo tem um atributo `data-field`, e cada botão de rolagem, um `data-roll`.
## Três jeitos de fazer
**Com uma IA**
Copie o guia do RPG Desk para a IA (o ChatGPT, o Claude, o Gemini…), descreva a ficha e instale o arquivo que ela devolver. Veja [Criar com uma IA](https://docs.rpgdesk.com/fichas/com-ia/).
**À mão, num arquivo só**
Um arquivo `.html`, com o manifesto dentro e as duas linhas do rpgdesk.js. Comece pelo [tutorial](https://docs.rpgdesk.com/fichas/primeira-ficha/).
**Num pacote**
Vários arquivos (HTML, CSS, JavaScript, imagens, fontes) num `.zip`, com mais de uma ficha ou tabela. Veja [Pacotes com vários arquivos](https://docs.rpgdesk.com/fichas/pacotes/).
## Do arquivo à mesa
1. **Teste no navegador:** abra o arquivo da ficha (dois cliques). Fora do RPG Desk, o rpgdesk.js entra no **modo de teste**, com os dados no navegador e uma faixa no canto para trocar de papel.
2. **Instale na mesa:** como mestre, em **Configurações da mesa → Plugins → Instalar plugin…**, escolha o `.html` (ou o `.zip`). O RPG Desk confere o arquivo e diz o que consertar, se for o caso.
3. **Use:** a ficha aparece em **Nova ficha…**, na biblioteca.
> **Dica**
>
> Fichas e tabelas são a mesma coisa por dentro. Uma **tabela da sala** (uma lista de NPCs, um calendário) é uma página igual, que fica embaixo da biblioteca para a mesa toda. Veja [Tabelas da sala](https://docs.rpgdesk.com/fichas/tabelas/).
## Nesta seção
[A primeira ficha](https://docs.rpgdesk.com/fichas/primeira-ficha/): O tutorial: do arquivo vazio à ficha instalada na mesa.
[Criar com uma IA](https://docs.rpgdesk.com/fichas/com-ia/): O guia para a IA, o pedido e como consertar o que vier errado.
[Campos, listas e abas](https://docs.rpgdesk.com/fichas/campos/): Tudo o que se faz só com atributos no HTML.
[JavaScript na ficha](https://docs.rpgdesk.com/fichas/javascript/): O documento, os campos calculados e as listas pelo código.
[Rolagens, chat e cartão](https://docs.rpgdesk.com/fichas/rolagens-e-chat/): Rolar, falar no chat e preencher as barras do jogador.
[Partes privadas](https://docs.rpgdesk.com/fichas/partes-privadas/): O que só o mestre ou só o dono vê.
[Tabelas da sala](https://docs.rpgdesk.com/fichas/tabelas/): Páginas para a mesa toda: NPCs, iniciativa, mapas de viagem.
[Visual](https://docs.rpgdesk.com/fichas/visual/): O rpgdesk.css, as cores do tema e as telas estreitas.
[Pacotes com vários arquivos](https://docs.rpgdesk.com/fichas/pacotes/): O .zip com manifest.json, imagens e fontes.
[Testar e desenvolver](https://docs.rpgdesk.com/fichas/desenvolvimento/): O modo de teste, o modo de desenvolvimento e os erros da página.
[Webhooks na ficha](https://docs.rpgdesk.com/fichas/webhooks/): Mandar dados para o Zapier, o Make ou o IFTTT.
[Novas versões](https://docs.rpgdesk.com/fichas/versoes/): Atualizar a ficha sem perder os dados dos jogadores.
[Exemplos](https://docs.rpgdesk.com/fichas/exemplos/): Fichas e uma tabela prontas, para usar e estudar.
Para consultar os detalhes, a [Referência](https://docs.rpgdesk.com/referencia/) tem o manifesto, os atributos, a API do rpgdesk.js, o verificador e os limites.
# A primeira ficha
> O tutorial: do arquivo vazio a uma ficha com campos, rolagens, uma lista e um campo calculado, testada no navegador e instalada na mesa.
Página: https://docs.rpgdesk.com/fichas/primeira-ficha/
Neste tutorial você faz uma ficha simples, a do jogo “Aventura Rápida”: nome, nível, dois atributos com o modificador calculado, um botão de rolar para cada um e uma lista de equipamento. Você só precisa de um editor de texto (o Bloco de Notas serve; o VS Code é melhor) e do navegador.
## 1. O esqueleto
Crie um arquivo chamado `minha-ficha.html` com isto:
`minha-ficha.html`
```html
Herói
```
Três partes:
- **O manifesto**, o `
```
`doc.compute` grava `mod_forca` sempre que `forca` muda. É o jeito certo de guardar valores calculados: veja [JavaScript na ficha](https://docs.rpgdesk.com/fichas/javascript/#campos-calculados).
## 6. Uma lista
Para o equipamento, uma lista em que cada item tem os seus campos:
```html
Equipamento
```
O `` é o molde de cada item. Dentro dele, `data-field="nome"` é o nome **do item**, não o do personagem. `data-list-add` acrescenta um item vazio; `data-list-remove` tira o item dele.
## 7. Pronto
Juntando tudo, a ficha fica assim:
*Exemplo funcionando:* [Aventura Rápida](https://docs.rpgdesk.com/exemplos/primeira-ficha.html)
`minha-ficha.html`
```html
Herói
Atributos
Modificador:
Modificador:
Equipamento
```
## 8. Instalar na mesa
1. Entre na sua mesa como mestre e abra **Configurações da mesa → Plugins**.
2. **Instalar plugin…** e escolha o `minha-ficha.html`.
3. O RPG Desk confere o arquivo. Se aparecer um problema, o diálogo diz como consertar (veja [O verificador](https://docs.rpgdesk.com/referencia/verificador/)). Sem erros, clique em **Instalar**.
4. Na biblioteca, **Novo item → Nova ficha…** mostra o sistema **Herói**, da **Aventura Rápida**.
Mudou a ficha? Suba a `version` no manifesto (`1.0.1`) e instale de novo: o RPG Desk atualiza o plugin, e as fichas já criadas mantêm os dados. Veja [Novas versões](https://docs.rpgdesk.com/fichas/versoes/).
> **E agora?**
>
> - Abas, imagens, caixas de marcar e listas mais ricas: [Campos, listas e abas](https://docs.rpgdesk.com/fichas/campos/).
> - A vida no cartão do jogador: [Rolagens, chat e cartão](https://docs.rpgdesk.com/fichas/rolagens-e-chat/#o-cart%C3%A3o-do-jogador).
> - Notas que só o mestre vê: [Partes privadas](https://docs.rpgdesk.com/fichas/partes-privadas/).
# Criar com uma IA
> Fazer a ficha do seu sistema com ajuda de uma IA: o guia do RPG Desk, o pedido, o teste e como consertar o que vier errado.
Página: https://docs.rpgdesk.com/fichas/com-ia/
Você não precisa saber programar para ter a ficha do seu sistema. Uma IA de conversa (o ChatGPT, o Claude, o Gemini…) escreve a ficha inteira, se ela souber as regras do RPG Desk. Essas regras estão no **guia para IA**: você cola o guia no começo da conversa e descreve a ficha.
## O guia para IA
Dois jeitos de pegar o guia:
- **No RPG Desk:** dentro da sua mesa, como mestre, em **Configurações da mesa → Plugins**, clique em **Copiar instruções para IA**. O guia vai para a área de transferência, na língua do RPG Desk e com o endereço do rpgdesk.js do seu servidor.
- **Aqui no site:** [baixe o guia em português](https://docs.rpgdesk.com/_sdk/1/guia-ia.md) ou [em inglês](https://docs.rpgdesk.com/_sdk/1/ai-guide.md), e cole o conteúdo do arquivo.
*Captura de tela:* Os botões Instalar plugin e Copiar instruções para IA, em Configurações, Plugins.
O guia explica à IA o formato do arquivo, as regras do ambiente (sem internet, bibliotecas só dentro do pacote), os atributos, a API do rpgdesk.js e traz um exemplo completo.
## A documentação para a IA
O guia resume as regras. Para a IA consultar os detalhes (todos os atributos, a API do rpgdesk.js, os códigos do verificador), esta documentação também existe em arquivos de texto feitos para IA, no padrão [llms.txt](https://llmstxt.org):
- [`llms-fichas.txt`](https://docs.rpgdesk.com/llms-fichas.txt): as seções Criar fichas e Referência num arquivo só. É o que mais ajuda para escrever fichas: se a IA aceita arquivos, anexe-o à conversa junto com o guia.
- [`llms-full.txt`](https://docs.rpgdesk.com/llms-full.txt): a documentação inteira.
- [`llms.txt`](https://docs.rpgdesk.com/llms.txt): o índice, com um link para cada página. Se a IA consegue abrir endereços da internet, mande o endereço dele: ela acha o resto a partir daí.
Cada página do site também existe em Markdown: troque a barra do fim do endereço por `.md` (`/fichas/campos/` vira `/fichas/campos.md`).
## Pedir a ficha
1. Abra uma conversa nova com a IA.
2. Cole o guia e, logo depois, descreva a ficha. Quanto mais concreto, melhor:
```text
Faça a ficha do meu sistema, "Lâminas do Sertão".
- Identidade: nome, origem, ofício, nível (1 a 10) e um retrato.
- Atributos: Força, Agilidade, Mente e Coragem, de 1 a 5. Cada um com um botão
que rola 2d6 + o atributo.
- Vida: atual e máxima (máxima = 10 + Força x 2, calculada). A vida vai para a
barra 1 do cartão do jogador.
- Perícias: uma lista com nome e bônus, e um botão de rolar 2d6 + bônus.
- Inventário: uma lista com item e quantidade.
- Uma aba "Mestre", só para os mestres, com anotações.
Cores: tons de areia e couro. Tem que caber num espaço estreito.
```
3. Peça **o arquivo `.html` inteiro**. Salve a resposta num arquivo com a extensão `.html` (`sertao.html`).
## Testar
Abra o arquivo no navegador (dois cliques). Fora do RPG Desk, a ficha entra no **modo de teste**: preencha os campos, clique nos botões de rolar e veja o **Registro**, na faixa do canto. Troque o **Papel** para **Outro jogador** e confira se os campos travam. Veja [Testar e desenvolver](https://docs.rpgdesk.com/fichas/desenvolvimento/).
Algo errado ou faltando? Diga à IA o que aconteceu, com detalhes (“o botão de Agilidade rola 1d20, não 2d6”; “o retrato não aparece”), e peça o arquivo inteiro de novo.
## Instalar e consertar
Instale em **Configurações da mesa → Plugins → Instalar plugin…**. O RPG Desk confere o arquivo antes:
*Captura de tela:* O diálogo de instalação com dois erros e um aviso, cada um com como consertar, e o botão Copiar relatório.
- Se aparecerem problemas, clique em **Copiar relatório** e cole na conversa com a IA: o relatório diz o que está errado, em que linha e como consertar, num texto que a IA entende.
- Já instalada, se a ficha mostrar um aviso de **Erros da página** (o triângulo no canto), clique nele, em **Copiar erros**, e cole na conversa também.
*Captura de tela:* Uma ficha com o painel Erros da página aberto, mostrando um TypeError, e os botões Copiar erros e Limpar.
> **Dicas**
>
> - Peça uma coisa de cada vez: primeiro a ficha básica, depois as abas, depois as contas.
> - Lembre a IA de subir a `version` a cada mudança (`1.0.0`, `1.0.1`…): assim o RPG Desk sabe que é uma atualização. Veja [Novas versões](https://docs.rpgdesk.com/fichas/versoes/).
> - Se a conversa ficou longa e a IA começou a esquecer as regras, abra outra conversa, cole o guia e o arquivo atual, e continue de onde parou.
> - A IA não vê a tela. Uma captura do problema, quando a IA aceita imagens, ajuda muito.
# Campos, listas e abas
> Tudo o que se faz só com atributos no HTML: campos de todos os tipos, textos calculados, imagens, listas, abas e o que cada papel vê.
Página: https://docs.rpgdesk.com/fichas/campos/
O rpgdesk.js liga sozinho os atributos `data-…` da página, inclusive nos elementos que aparecem depois (os itens de uma lista, por exemplo). Uma ficha inteira pode ser feita sem JavaScript. A tabela completa está em [Atributos no HTML](https://docs.rpgdesk.com/referencia/atributos/).
A ficha abaixo usa quase tudo desta página: o retrato, os campos, os modificadores calculados, as abas, a lista do inventário e a aba do mestre. Troque o **Papel** na faixa do canto para ver o que cada um vê.
*Exemplo funcionando:* [D20 Genérico](https://docs.rpgdesk.com/exemplos/d20-generico.html)
## O documento e os caminhos
Cada ficha tem um **documento**: os campos e os valores dela, guardados na mesa. Cada campo tem um **caminho**:
- `nome`, `nivel`, `forca`: campos soltos;
- `atributos.forca`, `pv.atual`, `pv.max`: campos dentro de um grupo, separados por ponto.
As regras dos nomes:
- letras **sem acento**, números e `_`, começando por letra ou `_`: `forca`, não `força`;
- maiúsculas não contam: `Forca` e `forca` são o mesmo campo;
- até 64 caracteres por nome e 12 níveis de grupo;
- nomes que começam com `_rpgdesk` são do RPG Desk.
O verificador avisa de um nome errado antes de instalar. Veja [O verificador](https://docs.rpgdesk.com/referencia/verificador/).
## Campos: `data-field`
Vai num ``, `
```
| Campo | O que grava |
| -------------------------------------------- | ----------------------------------------------------- |
| texto, `
```
O `data-role` sozinho só esconde o botão; quem garante o segredo é o `private` do manifesto. Teste no modo de teste, trocando o **Papel** para **Outro jogador**: a aba some, e `RPGDesk.doc.get('mestre')` dá `undefined`.
## Nas tabelas: `doc.restrict`
As tabelas da sala não têm dono, e o `private` do manifesto não vale nelas (o verificador avisa). Numa tabela, o mestre esconde partes pelo código, na hora:
```js
await doc.restrict(['npcs', '#' + id], 'gm'); // este NPC passa a ser só dos mestres
await doc.restrict(['npcs', '#' + id], null); // volta a ser de todos
```
`doc.restrict(caminho, 'gm' | 'owner' | null)` só funciona para os mestres. É o que a tabela de NPCs dos exemplos faz com a caixa **Oculto dos jogadores**: veja [Tabelas da sala](https://docs.rpgdesk.com/fichas/tabelas/).
> **Nota**
>
> Uma parte privada some para quem a perde: se o mestre esconde um NPC, ele sai da tela dos jogadores na hora. Quando volta a ser de todos, reaparece.
# Tabelas da sala
> Páginas para a mesa toda, abertas como aba para todos: uma lista de NPCs, a iniciativa, um calendário. Como declarar, quem escreve e um exemplo comentado.
Página: https://docs.rpgdesk.com/fichas/tabelas/
Uma **tabela da sala** é uma página como a ficha, com duas diferenças:
- há **uma por mesa**, e ela fica aberta para todos, como uma aba;
- **só os mestres escrevem**; os jogadores veem.
Servem para o que é da mesa, não de um personagem: os NPCs da campanha, um calendário, o mapa de viagem, a reputação das facções.
## Declarar
No manifesto, troque `"sheets"` por `"tables"`:
```json
"tables": [{ "type": "com.seunome.sistema.npcs", "title": "NPCs" }]
```
Um arquivo `.html` único traz uma ficha **ou** uma tabela. Um [pacote](https://docs.rpgdesk.com/fichas/pacotes/) pode trazer as duas coisas, com um HTML para cada.
## Na mesa
1. Instale o plugin em **Configurações da mesa → Plugins**.
2. No grupo **Tabelas de…**, embaixo do plugin, clique em **Ativar**.
3. A tabela abre para todos como uma aba que não fica à vista, junto das outras tabelas (ou no último espaço usado): clique no nome dela para vê-la.
Desativar fecha a tabela para todos e guarda os dados: ativar de novo traz tudo como estava.
## No código
- `kind` é `'table'`, e `item.ownerId` é `null` (a tabela não tem dono).
- O `private` do manifesto não vale nas tabelas: esconda as partes com `doc.restrict` (veja [Partes privadas](https://docs.rpgdesk.com/fichas/partes-privadas/#nas-tabelas-docrestrict)).
- Os controles do mestre ficam com `data-role="gm"`: para os jogadores, os campos já ficam travados sozinhos, mas os botões de criar e apagar somem.
- Para mexer no cartão de um jogador, diga de quem: `RPGDesk.card.setBar(0, 7, 12, { userId })`, com o `id` de `await RPGDesk.room.players()`.
## Exemplo: a lista de NPCs
*Exemplo funcionando:* [NPCs da mesa](https://docs.rpgdesk.com/exemplos/tabela-npcs.html)
O exemplo é uma lista em que cada NPC tem nome, PV, iniciativa, notas e um botão de rolar a iniciativa, tudo com atributos no HTML. O JavaScript faz duas coisas:
```js
RPGDesk.connect().then(({ doc, me }) => {
const npcs = doc.list('npcs');
const vazio = document.getElementById('vazio');
// "Nenhum NPC ainda." some quando a lista tem itens
npcs.watch((itens) => { vazio.hidden = itens.length > 0; }, { now: true });
if (me.role !== 'gm') return;
// "Oculto dos jogadores": o NPC passa a ser só dos mestres
const visto = new Map();
npcs.watch((itens, { local }) => {
for (const npc of itens) {
const oculto = npc.oculto === true;
if (visto.get(npc.id) === oculto) continue;
visto.set(npc.id, oculto);
if (local) doc.restrict(['npcs', '#' + npc.id], oculto ? 'gm' : null);
}
}, { now: true });
});
```
- Só o navegador do mestre que marcou a caixa (`local`) chama o `restrict`: os outros mestres com a tabela aberta não repetem o pedido.
- O NPC oculto some de verdade para os jogadores: o servidor nem manda.
> **Dica**
>
> No modo de teste, a tabela abre com o papel **Mestre**. Troque para **Outro jogador** na faixa para ver como os jogadores veem.
# Visual
> O rpgdesk.css, as classes prontas, as cores do tema da mesa, fontes, imagens e como fazer a ficha caber num espaço estreito.
Página: https://docs.rpgdesk.com/fichas/visual/
## O rpgdesk.css
A segunda linha do esqueleto carrega o `rpgdesk.css`:
```html
```
Ele é opcional e dá à ficha o visual do RPG Desk: o fundo escuro, os campos, os botões (os de rolagem em destaque), as abas, as listas e as fontes (Roboto, Lato e Inconsolata). Sem ele, a página começa crua, e o visual é todo seu.
As classes prontas:
| Classe | O que faz |
| ------------ | -------------------------------------------- |
| `rd-row` | uma linha que quebra quando falta espaço |
| `rd-col` | uma coluna |
| `rd-grid` | uma grade de cartões que se ajusta à largura |
| `rd-card` | uma caixa com fundo e borda |
| `rd-grow` | ocupa o espaço que sobra numa linha |
| `rd-primary` | o botão de destaque |
| `rd-muted` | o texto discreto |
## As cores do tema
O rpgdesk.js recebe as cores da mesa e as põe como variáveis CSS. Use as variáveis, e a sua ficha combina com o resto da mesa:
```css
.caixa {
background: var(--rd-bg-2);
border: 1px solid var(--rd-line);
color: var(--rd-text);
}
.destaque { color: var(--rd-accent); }
```
| Variável | O que é |
| ------------------------------------------------------ | ----------------------------------------------- |
| `--rd-text` | o texto |
| `--rd-muted` | o texto discreto |
| `--rd-accent`, `--rd-accent-hover`, `--rd-accent-text` | a cor de destaque, ao passar o mouse e em texto |
| `--rd-bg`, `--rd-bg-2`, `--rd-bg-3` | os fundos, do mais escuro ao mais claro |
| `--rd-line` | as bordas e as linhas |
| `--rd-error` | os erros |
| `--rd-font`, `--rd-title-font` | as fontes do texto e dos títulos |
| `--rd-radius` | o arredondamento dos cantos |
As cores cruas do tema da mesa também chegam, com o prefixo `--rd-` (como `--rd-dominant-color` e `--rd-face-color`). A lista está em [Visual (referência)](https://docs.rpgdesk.com/referencia/css/).
## Telas estreitas e largas
A ficha abre num espaço da mesa, que pode ter uns **350 px** de largura ou a tela inteira (numa janela própria). Faça a ficha se ajustar:
- use `rd-row` (ou `flex-wrap: wrap`) nas linhas de campos;
- use grades com `repeat(auto-fill, minmax(150px, 1fr))` em vez de colunas fixas;
- não fixe larguras grandes em pixels;
- a página rola sozinha: não ponha `overflow: hidden` no `body`.
Teste estreitando a janela do navegador no modo de teste.
## Imagens e fontes
A ficha não acessa a internet: imagens e fontes de fora não carregam.
- **Desenhos pequenos:** SVG dentro do HTML, ou endereços `data:`.
- **O retrato do personagem:** ``, que a pessoa escolhe no RPG Desk.
- **Imagens e fontes próprias:** ponha os arquivos num [pacote](https://docs.rpgdesk.com/fichas/pacotes/) e use caminhos relativos (``, `@font-face { src: url('fontes/minha.woff2') }`).
> **Nota**
>
> O rpgdesk.js esconde com o atributo `hidden` (as abas e o `data-role`) e garante que ele vença o seu CSS: um `display: grid` na seção não faz uma aba escondida reaparecer.
# Pacotes com vários arquivos
> O plugin em .zip: o manifest.json, várias fichas e tabelas, CSS e JavaScript separados, imagens, fontes e sons.
Página: https://docs.rpgdesk.com/fichas/pacotes/
Um arquivo `.html` só dá conta de uma ficha. Use um **pacote** (um `.zip`) quando o plugin tiver:
- mais de uma ficha, ou fichas e tabelas juntas;
- o CSS e o JavaScript em arquivos separados;
- imagens, fontes ou sons próprios.
## O que vai no pacote
A Ficha Básica do RPG Desk, por exemplo:
- ficha-basica.zip
- manifest.json o manifesto, na raiz
- ficha.html a ficha
- estilo.css
- ficha.js
- retrato.svg a silhueta do retrato
O `manifest.json` tem os mesmos campos do manifesto do arquivo único e, em cada ficha ou tabela, o `entry`, o HTML dela:
`manifest.json`
```json
{
"rpgdesk": 1,
"id": "br.rpgdesk.ficha-basica",
"name": { "pt": "Ficha Básica do RPG Desk", "en": "RPG Desk Basic Sheet" },
"version": "1.0.0",
"author": "RPG Desk",
"description": "Ficha para qualquer sistema: atributos, perícias, ataques, inventário e anotações.",
"sdk": 1,
"sheets": [
{
"type": "br.rpgdesk.ficha-basica.personagem",
"title": { "pt": "Personagem", "en": "Character" },
"entry": "ficha.html",
"private": { "mestre": "gm" }
}
]
}
```
- Cada HTML de entrada carrega o rpgdesk.js (e, se quiser, o `rpgdesk.css`) no ``, como no arquivo único. O manifesto não vai dentro do HTML.
- Os outros arquivos entram por caminhos relativos: ``, ``, ``.
- O `"$schema"` no manifesto (opcional) dá a ajuda do editor: `“$schema”: “https://docs.rpgdesk.com/_sdk/1/manifest.schema.json”`.
- O `"icon"` (opcional) é um `.png` ou `.svg` do pacote.
Todos os campos estão em [O manifesto](https://docs.rpgdesk.com/referencia/manifesto/).
*Exemplo funcionando:* [Ficha Básica do RPG Desk](https://docs.rpgdesk.com/exemplos/ficha-basica/ficha.html) ([Baixar o .zip](https://docs.rpgdesk.com/exemplos/ficha-basica.zip))
## Montar o .zip
1. Ponha os arquivos numa pasta, com o `manifest.json` na raiz dela.
2. Selecione **o conteúdo** da pasta (não a pasta) e compacte: no Windows, botão direito → **Enviar para → Pasta compactada**.
3. Instale o `.zip` em **Configurações da mesa → Plugins → Instalar plugin…**.
> **Dica**
>
> Compactou a pasta em vez do conteúdo? O RPG Desk percebe, usa o que está dentro da pasta e avisa. Da próxima vez, compacte o conteúdo.
## Arquivos aceitos
`.html` `.htm` `.css` `.js` `.mjs` `.json` `.txt` `.md` `.png` `.jpg` `.jpeg` `.webp` `.gif` `.svg` `.woff2` `.woff` `.ttf` `.otf` `.mp3` `.ogg` `.wav`
- O pacote tem até 10 MB e 500 arquivos.
- Os caminhos diferenciam maiúsculas e minúsculas: `Retrato.png` não é `retrato.png`.
- A página lê os arquivos do próprio pacote, até com `fetch('dados/magias.json')`. A internet, não.
## Bibliotecas
Bibliotecas como a [Alpine.js](https://alpinejs.dev) e o jQuery funcionam, desde que o arquivo delas vá dentro do pacote. Um ``.
- O verificador não dá avisos para o código de uma biblioteca: um arquivo em `vendor/`, ou um código que começa com o comentário de licença `/*!`. Veja [O verificador](https://docs.rpgdesk.com/referencia/verificador/).
- Com a Alpine, use `x-data`, `x-show` e `x-for` para a tela (abas, mostrar e esconder) e `data-field` para os dados. Não ponha `x-model` e `data-field` no mesmo campo: os dois escreveriam no mesmo valor.
- O `$.ajax` e o `$.getJSON` do jQuery leem os arquivos do pacote (`$.getJSON('dados/magias.json')`), mas não a internet.
# Testar e desenvolver
> O modo de teste fora do RPG Desk, o modo de desenvolvimento dentro da mesa e os erros da página.
Página: https://docs.rpgdesk.com/fichas/desenvolvimento/
Três ferramentas ajudam a fazer e consertar uma ficha: o **modo de teste**, para testar sem o RPG Desk; o **modo de desenvolvimento**, para testar dentro da mesa sem reinstalar a cada mudança; e os **erros da página**, para achar o que quebrou.
## O modo de teste
Abra o arquivo da ficha direto no navegador (dois cliques, ou arrastando para uma aba). Sem o RPG Desk em volta, o rpgdesk.js entra no modo de teste:
*Captura de tela:* A ficha no modo de teste: os campos preenchidos e a faixa com o papel Dono da ficha, o registro aberto com duas rolagens e o botão Limpar dados.
- tudo funciona: os campos, as listas, as abas, as contas e as rolagens (sorteadas no navegador);
- os dados ficam guardados no navegador, e voltam ao recarregar a página;
- a faixa no canto tem:
- **Papel**: **Mestre**, **Dono da ficha** ou **Outro jogador**. Troque para ver o que cada um vê e pode mudar;
- **Registro**: as rolagens, as mensagens de chat, os avisos, as barras do cartão, os webhooks (de mentira) e os erros. O número laranja conta os erros e as gravações recusadas;
- **Limpar dados**: começa a ficha do zero.
A faixa fala a língua do navegador. As fichas ao vivo deste site também estão no modo de teste.
> **Nota**
>
> No modo de teste, a escolha de imagem abre os arquivos do computador, e as imagens escolhidas valem até fechar a página.
## O modo de desenvolvimento
Para ver a ficha **dentro da mesa** enquanto você a escreve, sem instalar de novo a cada mudança:
1. Instale o plugin na mesa uma vez.
2. Sirva a pasta da ficha com um servidor local. Por exemplo, com o Node instalado: `npx serve --cors .` (ele mostra o endereço, como `http://localhost:3000`).
3. Em **Configurações da mesa → Plugins**, clique em **Desenvolvimento** no plugin e escreva o endereço do HTML da ficha, como `http://localhost:3000/minha-ficha.html`. Clique em **Salvar**.
*Captura de tela:* A tela Desenvolvimento da Ficha Básica do RPG Desk, com o endereço http\://localhost:5174/index.html para a ficha Personagem e o botão Salvar.
- As fichas desse tipo passam a vir do seu computador, **só no seu navegador**: os outros na mesa continuam com a versão instalada. A ficha mostra “Desenvolvimento:” e o endereço no alto.
- Salvou o arquivo? Recarregue a ficha (feche e abra a aba, ou **Recarregar** se ela parar).
- **Desligar**, na mesma tela, volta à versão instalada.
- Se a página usa `
```
Do outro lado, um Zap com o gatilho **Catch Hook** e a ação de mandar uma mensagem num canal do Discord, usando `data.personagem` e `data.total`.
> **Limites**
>
> Até 20 envios por minuto em cada ficha aberta (passou disso, o `send` falha com um erro) e 30 por minuto na mesa toda. Os dados vão em JSON, até 16 KB; a resposta do serviço volta até 64 KB. No modo de teste, nada sai: o **Registro** mostra o que seria mandado.
# Novas versões
> Atualizar a ficha na mesa sem perder os dados dos jogadores: a versão, o que não pode mudar e como migrar um campo renomeado.
Página: https://docs.rpgdesk.com/fichas/versoes/
## Publicar uma versão nova
1. Mude a ficha e suba a `version` do manifesto: `1.0.0` → `1.0.1` para um conserto, `1.1.0` para algo novo, `2.0.0` para uma mudança grande.
2. Em **Configurações da mesa → Plugins**, instale o arquivo de novo. O diálogo mostra **Atualizar**: “Atualiza a versão 1.0.0 instalada para 1.0.1. As fichas mantêm os dados.”
3. Quem estiver com a ficha aberta passa a ver a versão nova.
Se a versão for menor que a instalada, o diálogo avisa antes (às vezes é isso mesmo: voltar a uma versão que funcionava).
## O que não pode mudar
- **O `id` do plugin:** com outro `id`, é outro plugin.
- **O `type` de cada ficha e tabela:** as fichas da mesa são de um tipo. Se o tipo muda, as fichas antigas ficam sem plugin (“Nenhum plugin da mesa edita fichas do tipo…”) até o tipo antigo voltar.
Cada tipo é de um plugin só na mesa: um segundo plugin não pode trazer um tipo que já é de outro.
## Os dados
Os dados ficam no documento de cada ficha, pelos nomes dos campos. A versão nova encontra tudo o que a anterior gravou com os mesmos nomes.
- **Um campo novo** começa vazio.
- **Um campo que você tirou da página** continua guardado, só não aparece.
- **Um campo renomeado** começa vazio, e o dado continua no nome antigo. Para levar o dado ao nome novo, faça uma pequena migração no JavaScript:
```js
RPGDesk.connect().then(({ doc, me, item }) => {
// de "pontos_vida" (versão 1.0) para "pv.atual" (versão 1.1); uma pessoa só faz a migração:
// o dono da ficha, ou um mestre, se a ficha não tem dono
const migra = me.isOwner || (!item.ownerId && me.role === 'gm');
const antigo = doc.get('pontos_vida');
if (migra && antigo !== undefined && doc.canWrite('pv.atual')) {
doc.update({ 'pv.atual': antigo, pontos_vida: null });
}
});
```
> **Dica**
>
> Uma pessoa só migra: assim o mestre e o jogador, com a ficha aberta ao mesmo tempo, não gravam duas vezes. É o mesmo cuidado da Ficha Básica do RPG Desk ao criar os atributos de uma ficha nova.
## Remover o plugin
Remover um plugin não apaga as fichas: elas ficam na biblioteca, sem poder ser editadas, até o plugin ser instalado de novo. As tabelas dele são desativadas, com os dados guardados.
# Exemplos
> Fichas e uma tabela prontas, funcionando: use na sua mesa, estude o código ou entregue a uma IA como ponto de partida.
Página: https://docs.rpgdesk.com/fichas/exemplos/
Todos os exemplos abaixo funcionam no modo de teste, aqui na página. Em cada um:
- **Baixar** traz o arquivo (o `.html`, ou o `.zip` do pacote), pronto para instalar na sua mesa em **Configurações da mesa → Plugins → Instalar plugin…**;
- **Abrir em nova aba ↗** abre a ficha sozinha.
> **Dica**
>
> Quer estudar o código? Abra o arquivo baixado num editor, ou, na aba aberta, aperte **Ctrl + U** para ver o código-fonte.
## Ficha mínima
Só HTML: campos e rolagens, sem uma linha de JavaScript.
*Exemplo funcionando:* [Ficha mínima](https://docs.rpgdesk.com/exemplos/ficha-minima.html)
## Aventura Rápida
A ficha do [tutorial](https://docs.rpgdesk.com/fichas/primeira-ficha/): campos, modificadores calculados, rolagens e uma lista.
*Exemplo funcionando:* [Aventura Rápida](https://docs.rpgdesk.com/exemplos/primeira-ficha.html)
## D20 Genérico
O retrato, as abas, a lista do inventário, os modificadores, a vida na barra do cartão e uma aba só do mestre (uma [parte privada](https://docs.rpgdesk.com/fichas/partes-privadas/)). É o exemplo completo do guia para IA.
*Exemplo funcionando:* [D20 Genérico](https://docs.rpgdesk.com/exemplos/d20-generico.html)
## Ficha Básica do RPG Desk
Um [pacote](https://docs.rpgdesk.com/fichas/pacotes/) com HTML, CSS, JavaScript e imagem: atributos, perícias, ataques com acerto e dano, inventário com a carga somada, anotações, a vida e a energia nas barras do cartão e as notas do mestre. Serve para qualquer sistema.
*Exemplo funcionando:* [Ficha Básica do RPG Desk](https://docs.rpgdesk.com/exemplos/ficha-basica/ficha.html) ([Baixar o .zip](https://docs.rpgdesk.com/exemplos/ficha-basica.zip))
## NPCs da mesa
Uma [tabela da sala](https://docs.rpgdesk.com/fichas/tabelas/): os NPCs, com PV, iniciativa e notas, e a caixa **Oculto dos jogadores**, que esconde o NPC de verdade.
*Exemplo funcionando:* [NPCs da mesa](https://docs.rpgdesk.com/exemplos/tabela-npcs.html)
# Referência
> Para consulta: o manifesto dos plugins, os atributos no HTML, a API do rpgdesk.js, o CSS, o verificador, os limites, os comandos do chat, as rolagens, os atalhos e a formatação.
Página: https://docs.rpgdesk.com/referencia/
A referência é para consulta rápida, quando você já sabe o que quer fazer e precisa do detalhe. Para aprender, comece por [Criar fichas](https://docs.rpgdesk.com/fichas/) ou por [Usando a mesa](https://docs.rpgdesk.com/mesa/).
## Fichas e plugins
[O manifesto](https://docs.rpgdesk.com/referencia/manifesto/): Cada campo, o que aceita e o que o RPG Desk confere.
[Atributos no HTML](https://docs.rpgdesk.com/referencia/atributos/): data-field, data-list, data-roll, data-tabs e os outros.
[A API do rpgdesk.js](https://docs.rpgdesk.com/referencia/api/): Todas as funções do objeto RPG Desk e do documento.
[Visual (CSS)](https://docs.rpgdesk.com/referencia/css/): As classes e as variáveis do rpgdesk.css e do tema.
[O verificador](https://docs.rpgdesk.com/referencia/verificador/): Cada problema que a instalação aponta e como consertar.
[Limites](https://docs.rpgdesk.com/referencia/limites/): Tamanhos, quantidades e quantas vezes por minuto.
## A mesa
[Comandos do chat](https://docs.rpgdesk.com/referencia/comandos/): /r, /me, /nick, /cls e os outros.
[Rolagens](https://docs.rpgdesk.com/referencia/rolagens/): A gramática das rolagens e como os sucessos contam.
[Formatação do chat](https://docs.rpgdesk.com/referencia/formatacao/): As marcações, as cores e os emoji.
[Atalhos do teclado](https://docs.rpgdesk.com/referencia/atalhos/): A cena, o chat e as janelas.
# O manifesto
> Cada campo do manifesto de um plugin do RPG Desk, o que aceita e o que o verificador confere.
Página: https://docs.rpgdesk.com/referencia/manifesto/
O manifesto diz ao RPG Desk o que o plugin é. Ele vai:
- **num arquivo `.html` único**, dentro do ``: ``;
- **num pacote `.zip`**, no arquivo `manifest.json`, na raiz.
Ele é JSON: aspas duplas, sem comentários e sem vírgula depois do último item. O JSON Schema, para o editor ajudar, está em `https://docs.rpgdesk.com/_sdk/1/manifest.schema.json` (use em `"$schema"`).
## Exemplo
```json
{
"rpgdesk": 1,
"id": "com.seunome.sistema",
"name": { "pt": "Meu Sistema", "en": "My System" },
"version": "1.2.0",
"author": "Seu nome",
"description": "Ficha e tabela de NPCs do Meu Sistema.",
"sdk": 1,
"icon": "icone.svg",
"sheets": [
{ "type": "com.seunome.sistema.ficha", "title": "Personagem", "entry": "ficha.html", "private": { "mestre": "gm" } }
],
"tables": [
{ "type": "com.seunome.sistema.npcs", "title": "NPCs", "entry": "npcs.html" }
],
"webhooks": [
{ "name": "rolagens", "description": "Cada rolagem da ficha", "example": { "total": 17 } }
]
}
```
## Os campos
| Campo | Obrigatório | O que é |
| ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpgdesk` | sim | a versão do formato do manifesto: `1` |
| `id` | sim | o identificador do plugin: minúsculas, números, `.`, `-` e `_`, começando por letra ou número (até 120). Use um domínio invertido: `com.seunome.sistema` |
| `name` | sim | o nome do plugin (até 120), num texto ou por língua (veja abaixo) |
| `version` | sim | maior.menor.correção, como `1.0.0`. Suba a cada mudança |
| `sdk` | sim | a versão maior do rpgdesk.js: `1` |
| `author` | não | quem fez (até 120) |
| `description` | não | o que o plugin traz (até 1000). Aparece na instalação e na lista de plugins |
| `sheets` | um dos dois | as fichas (veja abaixo) |
| `tables` | um dos dois | as tabelas da sala (veja abaixo) |
| `webhooks` | não | os webhooks que o plugin usa (veja abaixo) |
| `icon` | não | um `.png` ou `.svg` do pacote |
| `$schema` | não | o endereço do JSON Schema, para o editor |
Um campo que o RPG Desk não conhece gera um aviso, e é ignorado.
## Fichas e tabelas
`sheets` e `tables` são listas. Cada item:
| Campo | O que é |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | o tipo de dado da ficha ou tabela: começa com o `id` do plugin e um ponto (`com.seunome.sistema.ficha`), com os mesmos caracteres do `id` (até 120). Não mude depois de publicar |
| `title` | o nome que aparece em **Nova ficha…** ou na aba da tabela (até 120), num texto ou por língua |
| `entry` | **só no pacote:** o HTML da ficha ou tabela, dentro do pacote (`ficha.html`). No arquivo único, a entrada é o próprio arquivo |
| `private` | **só nas fichas:** as partes privadas, `{ "caminho": "gm" \| "owner" }`. Veja [Partes privadas](https://docs.rpgdesk.com/fichas/partes-privadas/) |
- O plugin precisa de pelo menos uma ficha ou tabela, e tem no máximo 20.
- Um arquivo `.html` único traz **uma** ficha ou **uma** tabela.
- Cada `type` aparece uma vez.
## Webhooks
`webhooks` é uma lista (até 20). Cada item:
| Campo | O que é |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `name` | o nome que a página usa em `RPGDesk.webhooks.send(nome, dados)`: minúsculas, números, `-` e `_` (até 40) |
| `description` | o que o webhook manda, para o mestre (até 300) |
| `example` | opcional: um exemplo dos dados, até 4 KB em JSON |
Veja [Webhooks na ficha](https://docs.rpgdesk.com/fichas/webhooks/).
## Textos em duas línguas
`name` e `title` aceitam um texto por língua:
```json
"name": { "pt": "Ficha Básica do RPG Desk", "en": "RPG Desk Basic Sheet" }
```
Cada pessoa vê o da língua do RPG Desk dela; sem o dela, vale o português, depois o inglês, depois o primeiro. As chaves são códigos de língua: `pt`, `en`, `pt-BR`.
> **Nota**
>
> A `description` e os textos da página não têm versão por língua no manifesto: para traduzir a página, use o `language` do contexto. Veja [JavaScript na ficha](https://docs.rpgdesk.com/fichas/javascript/#uma-ficha-em-duas-l%C3%ADnguas).
# Atributos no HTML
> Todos os atributos data-* que o rpgdesk.js liga sozinho: campos, textos, imagens, listas, rolagens, abas e papéis.
Página: https://docs.rpgdesk.com/referencia/atributos/
O rpgdesk.js liga estes atributos sozinho quando a página carrega, e também nos elementos que entram depois. Dentro do `` de uma lista, os caminhos são relativos ao item. Para aprender com exemplos, veja [Campos, listas e abas](https://docs.rpgdesk.com/fichas/campos/).
| Atributo | Onde vai | O que faz |
| ------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `data-field="caminho"` | ``, `
`, `@font-face { src: url('fontes/minha.woff2') }`).
> **Nota**
>
> O rpgdesk.js esconde com o atributo `hidden` (as abas e o `data-role`) e garante que ele vença o seu CSS: um `display: grid` na seção não faz uma aba escondida reaparecer.
# Pacotes com vários arquivos
> O plugin em .zip: o manifest.json, várias fichas e tabelas, CSS e JavaScript separados, imagens, fontes e sons.
Página: https://docs.rpgdesk.com/fichas/pacotes/
Um arquivo `.html` só dá conta de uma ficha. Use um **pacote** (um `.zip`) quando o plugin tiver:
- mais de uma ficha, ou fichas e tabelas juntas;
- o CSS e o JavaScript em arquivos separados;
- imagens, fontes ou sons próprios.
## O que vai no pacote
A Ficha Básica do RPG Desk, por exemplo:
- ficha-basica.zip
- manifest.json o manifesto, na raiz
- ficha.html a ficha
- estilo.css
- ficha.js
- retrato.svg a silhueta do retrato
O `manifest.json` tem os mesmos campos do manifesto do arquivo único e, em cada ficha ou tabela, o `entry`, o HTML dela:
`manifest.json`
```json
{
"rpgdesk": 1,
"id": "br.rpgdesk.ficha-basica",
"name": { "pt": "Ficha Básica do RPG Desk", "en": "RPG Desk Basic Sheet" },
"version": "1.0.0",
"author": "RPG Desk",
"description": "Ficha para qualquer sistema: atributos, perícias, ataques, inventário e anotações.",
"sdk": 1,
"sheets": [
{
"type": "br.rpgdesk.ficha-basica.personagem",
"title": { "pt": "Personagem", "en": "Character" },
"entry": "ficha.html",
"private": { "mestre": "gm" }
}
]
}
```
- Cada HTML de entrada carrega o rpgdesk.js (e, se quiser, o `rpgdesk.css`) no ``, como no arquivo único. O manifesto não vai dentro do HTML.
- Os outros arquivos entram por caminhos relativos: ``, ``, `