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: ```htmlEquipamento
Herói
Atributos
Modificador:
Modificador:
Equipamento
`, `@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"` | ``, `