# 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
<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8">
  <script type="application/rpgdesk+json" id="rpgdesk-manifest">
  {
    "rpgdesk": 1,
    "id": "com.seunome.aventura",
    "name": "Aventura Rápida",
    "version": "1.0.0",
    "author": "Seu nome",
    "sdk": 1,
    "sheets": [{ "type": "com.seunome.aventura.ficha", "title": "Herói" }]
  }
  </script>
  <script src="https://docs.rpgdesk.com/_sdk/1/rpgdesk.js"></script>
  <link rel="stylesheet" href="https://docs.rpgdesk.com/_sdk/1/rpgdesk.css">
</head>
<body>
  <h1>Herói</h1>
</body>
</html>
```

Três partes:

- **O manifesto**, o `<script type="application/rpgdesk+json">`: diz ao RPG Desk o que o arquivo é. O `id` identifica o seu plugin (use um “domínio invertido”, com o seu nome); o `type` da ficha começa com o `id` e um ponto; a `version` sobe a cada mudança. Ele precisa ser JSON válido: aspas duplas e nada de vírgula depois do último item. Todos os campos estão em [O manifesto](https://docs.rpgdesk.com/referencia/manifesto/).
- **As duas linhas do rpgdesk.js:** o script, que liga a página ao RPG Desk, e o `rpgdesk.css`, que dá o visual do RPG Desk (ele é opcional).
- **O corpo:** a ficha em si.

## 2. Os campos

Troque o `<body>` por isto:

```html
<body>
  <h1>Herói</h1>
  <div class="rd-row">
    <label class="rd-grow">Nome <input data-field="nome"></label>
    <label>Nível <input type="number" data-field="nivel" min="1"></label>
  </div>

  <h2>Atributos</h2>
  <div class="rd-row">
    <label>Força <input type="number" data-field="forca"></label>
  </div>
  <div class="rd-row">
    <label>Destreza <input type="number" data-field="destreza"></label>
  </div>
</body>
```

O atributo `data-field` liga o campo ao **documento** da ficha: o que se escreve ali fica guardado na mesa com o nome do campo (`nome`, `nivel`, `forca`). Um `type="number"` grava um número. Os nomes dos campos usam letras sem acento, números e `_`: `forca`, não `força`.

`rd-row` e `rd-grow` são classes do `rpgdesk.css`: uma linha que quebra quando falta espaço, e um campo que ocupa o espaço que sobra.

## 3. Testar no navegador

Salve e abra o arquivo no navegador (dois cliques). Fora do RPG Desk, o rpgdesk.js entra no **modo de teste**: os campos funcionam, os dados ficam guardados no navegador, e uma faixa no canto mostra o modo de teste.

*Captura de tela:* A ficha aberta direto no navegador, no modo de teste: os campos preenchidos e, no canto, a faixa com o papel Dono da ficha e o registro de duas rolagens.

Na faixa:

- **Papel** troca entre **Mestre**, **Dono da ficha** e **Outro jogador**. Como outro jogador, os campos ficam travados: só o dono e os mestres escrevem na ficha;
- **Registro** mostra as rolagens, as mensagens e os erros;
- **Limpar dados** apaga o que você escreveu.

## 4. Rolar

Ponha um botão depois de cada atributo:

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

O `data-roll` é a rolagem, e `{forca}` vira o número do campo `forca`. O `data-label` é o nome da rolagem no chat; nele, `{nome}` vira o texto do campo `nome`. No modo de teste, a rolagem aparece no **Registro**; na mesa, no chat, para todos.

## 5. Um campo calculado

Em muitos jogos, o atributo dá um modificador: (atributo − 10) ÷ 2, arredondado para baixo. Mostre o modificador com `data-text` e role com ele:

```html
<label>Força <input type="number" data-field="forca"></label>
<span>Modificador: <b data-text="mod_forca"></b></span>
<button data-roll="1d20 + {mod_forca}" data-label="Força de {nome}">Rolar Força</button>
```

E calcule com três linhas de JavaScript, antes do `</body>`:

```html
<script>
  // o modificador: (atributo - 10) / 2, arredondado para baixo
  const modificador = (valor) => Math.floor(((Number(valor) || 10) - 10) / 2);
  RPGDesk.connect().then(({ doc }) => {
    doc.compute('mod_forca', ['forca'], modificador);
    doc.compute('mod_destreza', ['destreza'], modificador);
  });
</script>
```

`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
<h2>Equipamento</h2>
<ul data-list="equipamento">
  <template>
    <li class="rd-row">
      <input class="rd-grow" data-field="nome" placeholder="Item">
      <button data-list-remove>×</button>
    </li>
  </template>
</ul>
<button data-list-add="equipamento">+ Item</button>
```

O `<template>` é 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
<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8">
  <script type="application/rpgdesk+json" id="rpgdesk-manifest">
  {
    "rpgdesk": 1,
    "id": "com.seunome.aventura",
    "name": "Aventura Rápida",
    "version": "1.0.0",
    "author": "Seu nome",
    "sdk": 1,
    "sheets": [{ "type": "com.seunome.aventura.ficha", "title": "Herói" }]
  }
  </script>
  <script src="https://docs.rpgdesk.com/_sdk/1/rpgdesk.js"></script>
  <link rel="stylesheet" href="https://docs.rpgdesk.com/_sdk/1/rpgdesk.css">
</head>
<body>
  <h1>Herói</h1>
  <div class="rd-row">
    <label class="rd-grow">Nome <input data-field="nome"></label>
    <label>Nível <input type="number" data-field="nivel" min="1"></label>
  </div>

  <h2>Atributos</h2>
  <div class="rd-row">
    <label>Força <input type="number" data-field="forca"></label>
    <span>Modificador: <b data-text="mod_forca"></b></span>
    <button data-roll="1d20 + {mod_forca}" data-label="Força de {nome}">Rolar Força</button>
  </div>
  <div class="rd-row">
    <label>Destreza <input type="number" data-field="destreza"></label>
    <span>Modificador: <b data-text="mod_destreza"></b></span>
    <button data-roll="1d20 + {mod_destreza}" data-label="Destreza de {nome}">Rolar Destreza</button>
  </div>

  <h2>Equipamento</h2>
  <ul data-list="equipamento">
    <template>
      <li class="rd-row">
        <input class="rd-grow" data-field="nome" placeholder="Item">
        <button data-list-remove>×</button>
      </li>
    </template>
  </ul>
  <button data-list-add="equipamento">+ Item</button>

  <script>
    // o modificador: (atributo - 10) / 2, arredondado para baixo
    const modificador = (valor) => Math.floor(((Number(valor) || 10) - 10) / 2);
    RPGDesk.connect().then(({ doc }) => {
      doc.compute('mod_forca', ['forca'], modificador);
      doc.compute('mod_destreza', ['destreza'], modificador);
    });
  </script>
</body>
</html>
```

## 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/).
