Hero
``` Three parts: - **The manifest**, the ` ``` `doc.compute` saves `str_mod` whenever `strength` changes. It is the right way to keep computed values: see [JavaScript on the sheet](https://docs.rpgdesk.com/en/fichas/javascript/#computed-fields). ## 6. A list For the gear, a list where each item has its own fields: ```htmlGear
Hero
Attributes
Modifier:
Modifier:
Gear
`, `@font-face { src: url('fonts/mine.woff2') }`).
> **Note**
>
> rpgdesk.js hides things with the `hidden` attribute (tabs and `data-role`) and makes sure it beats your CSS: a `display: grid` on the section does not make a hidden tab reappear.
# Packages with several files
> The plugin as a .zip: manifest.json, several sheets and tables, separate CSS and JavaScript, images, fonts and sounds.
Page: https://docs.rpgdesk.com/en/fichas/pacotes/
A single `.html` file handles one sheet. Use a **package** (a `.zip`) when the plugin has:
- more than one sheet, or sheets and tables together;
- the CSS and JavaScript in separate files;
- images, fonts or sounds of its own.
## What goes in the package
The RPG Desk Basic Sheet, for example:
- basic-sheet.zip
- manifest.json the manifest, at the root
- sheet.html the sheet
- style.css
- sheet.js
- portrait.svg the portrait’s silhouette
`manifest.json` has the same fields as the single file’s manifest and, on each sheet or table, the `entry`, its HTML:
`manifest.json`
```json
{
"rpgdesk": 1,
"id": "br.rpgdesk.basic-sheet",
"name": { "en": "RPG Desk Basic Sheet", "pt": "Ficha Básica do RPG Desk (inglês)" },
"version": "1.0.0",
"author": "RPG Desk",
"description": "A sheet for any system: attributes, skills, attacks, inventory and notes, with health and energy on the player's card.",
"sdk": 1,
"sheets": [
{
"type": "br.rpgdesk.basic-sheet.character",
"title": { "en": "Character", "pt": "Personagem" },
"entry": "sheet.html",
"private": { "gm": "gm" }
}
]
}
```
- Each entry HTML loads rpgdesk.js (and, if you want, `rpgdesk.css`) in its ``, as in the single file. The manifest does not go inside the HTML.
- The other files come in through relative paths: ``, ``, ``.
- The `"$schema"` in the manifest (optional) gives you the editor’s help: `“$schema”: “https://docs.rpgdesk.com/_sdk/1/manifest.schema.json”`.
- The `"icon"` (optional) is a `.png` or `.svg` from the package.
Every field is in [The manifest](https://docs.rpgdesk.com/en/referencia/manifesto/).
*Working example:* [RPG Desk Basic Sheet](https://docs.rpgdesk.com/exemplos/en/basic-sheet/sheet.html) ([Download the .zip](https://docs.rpgdesk.com/exemplos/en/basic-sheet.zip))
## Build the .zip
1. Put the files in a folder, with `manifest.json` at its root.
2. Select **the contents** of the folder (not the folder) and compress them: on Windows, right-click → **Send to → Compressed (zipped) folder**.
3. Install the `.zip` in **Room settings → Plugins → Install plugin…**.
> **Tip**
>
> Compressed the folder instead of its contents? RPG Desk notices, uses what is inside the folder and warns you. Next time, compress the contents.
## Accepted files
`.html` `.htm` `.css` `.js` `.mjs` `.json` `.txt` `.md` `.png` `.jpg` `.jpeg` `.webp` `.gif` `.svg` `.woff2` `.woff` `.ttf` `.otf` `.mp3` `.ogg` `.wav`
- The package has up to 10 MB and 500 files.
- Paths are case-sensitive: `Portrait.png` is not `portrait.png`.
- The page reads the package’s own files, even with `fetch('data/spells.json')`. The internet, no.
## Libraries
Libraries such as [Alpine.js](https://alpinejs.dev) and jQuery work, as long as their file goes inside the package. A ``.
- The verifier gives no warnings for a library’s code: a file in `vendor/`, or code that starts with the `/*!` license comment. See [The verifier](https://docs.rpgdesk.com/en/referencia/verificador/).
- With Alpine, use `x-data`, `x-show` and `x-for` for the screen (tabs, showing and hiding) and `data-field` for the data. Don’t put `x-model` and `data-field` on the same field: both would write the same value.
- jQuery’s `$.ajax` and `$.getJSON` read the package’s files (`$.getJSON('data/spells.json')`), but not the internet.
# Test and develop
> Test mode outside RPG Desk, development mode inside the room and page errors.
Page: https://docs.rpgdesk.com/en/fichas/desenvolvimento/
Three tools help you make and fix a sheet: **test mode**, to test without RPG Desk; **development mode**, to test inside the room without reinstalling after each change; and **page errors**, to find what broke.
## Test mode
Open the sheet’s file straight in the browser (double-click it, or drag it onto a tab). Without RPG Desk around it, rpgdesk.js enters test mode:
*Screenshot:* The sheet in test mode: the fields filled in and the band with the Sheet owner role, the log open with two rolls and the Clear data button.
- everything works: fields, lists, tabs, math and rolls (rolled in the browser);
- the data is kept in the browser, and comes back when you reload the page;
- the band in the corner has:
- **Role**: **GM**, **Sheet owner** or **Another player**. Switch to see what each one sees and can change;
- **Log**: rolls, chat messages, notices, card bars, (pretend) webhooks and errors. The orange number counts the errors and the refused writes;
- **Clear data**: starts the sheet from scratch.
The band speaks the browser’s language. The live sheets on this site are in test mode too.
> **Note**
>
> In test mode, the image picker opens the computer’s files, and the chosen images last until you close the page.
## Development mode
To see the sheet **inside the room** while you write it, without installing it again after each change:
1. Install the plugin in the room once.
2. Serve the sheet’s folder with a local server. For example, with Node installed: `npx serve --cors .` (it shows the address, like `http://localhost:3000`).
3. In **Room settings → Plugins**, click **Development** on the plugin and type the address of the sheet’s HTML, like `http://localhost:3000/my-sheet.html`. Click **Save**.
*Screenshot:* The Development screen of the RPG Desk Basic Sheet, with the address http\://localhost:5174/index.html for the Character sheet and the Save button.
- Sheets of that type now come from your computer, **only in your browser**: everyone else in the room keeps the installed version. The sheet shows “Development:” and the address at the top.
- Saved the file? Reload the sheet (close and reopen the tab, or **Reload** if it stops).
- **Turn off**, on the same screen, goes back to the installed version.
- If the page uses `
```
On the other side, a Zap with the **Catch Hook** trigger and an action that sends a message to a Discord channel, using `data.character` and `data.total`.
> **Limits**
>
> Up to 20 sends per minute on each open sheet (beyond that, `send` fails with an error) and 30 per minute in the whole room. The data goes as JSON, up to 16 KB; the service’s answer comes back up to 64 KB. In test mode, nothing goes out: the **Log** shows what would be sent.
# New versions
> Updating the sheet in the room without losing the players' data: the version, what must not change and how to migrate a renamed field.
Page: https://docs.rpgdesk.com/en/fichas/versoes/
## Publish a new version
1. Change the sheet and bump the manifest’s `version`: `1.0.0` → `1.0.1` for a fix, `1.1.0` for something new, `2.0.0` for a big change.
2. In **Room settings → Plugins**, install the file again. The dialog shows **Update**: “Updates the installed version 1.0.0 to 1.0.1. Sheets keep their data.”
3. Whoever has the sheet open starts seeing the new version.
If the version is lower than the installed one, the dialog warns you first (sometimes that is exactly it: going back to a version that worked).
## What must not change
- **The plugin’s `id`:** with another `id`, it is another plugin.
- **The `type` of each sheet and table:** the room’s sheets are of a type. If the type changes, the old sheets are left without a plugin (“No plugin in this room edits sheets of type…”) until the old type comes back.
Each type belongs to a single plugin in the room: a second plugin cannot bring a type that already belongs to another.
## The data
The data lives in each sheet’s document, under the fields’ names. The new version finds everything the previous one saved under the same names.
- **A new field** starts empty.
- **A field you removed from the page** is still kept, it just does not show up.
- **A renamed field** starts empty, and the data stays under the old name. To bring the data to the new name, do a small migration in JavaScript:
```js
RPGDesk.connect().then(({ doc, me, item }) => {
// from "hit_points" (version 1.0) to "hp.current" (version 1.1); only one person migrates:
// the sheet's owner, or a game master, if the sheet has no owner
const migrates = me.isOwner || (!item.ownerId && me.role === 'gm');
const old = doc.get('hit_points');
if (migrates && old !== undefined && doc.canWrite('hp.current')) {
doc.update({ 'hp.current': old, hit_points: null });
}
});
```
> **Tip**
>
> Only one person migrates: that way the game master and the player, with the sheet open at the same time, do not write twice. It is the same care the RPG Desk Basic Sheet takes when it creates a new sheet’s attributes.
## Remove the plugin
Removing a plugin does not delete the sheets: they stay in the library, read-only, until the plugin is installed again. Its tables are disabled, with their data kept.
# Examples
> Ready-made, working sheets and a table: use them in your room, study the code or hand them to an AI as a starting point.
Page: https://docs.rpgdesk.com/en/fichas/exemplos/
All the examples below work in test mode, right here on the page. On each one:
- **Download** gets the file (the `.html`, or the package’s `.zip`), ready to install in your room in **Room settings → Plugins → Install plugin…**;
- **Open in a new tab ↗** opens the sheet on its own.
> **Tip**
>
> Want to study the code? Open the downloaded file in an editor, or, in the opened tab, press **Ctrl + U** to see the source code.
## Minimal sheet
HTML only: fields and rolls, without a single line of JavaScript.
*Working example:* [Minimal sheet](https://docs.rpgdesk.com/exemplos/en/minimal-sheet.html)
## Quick Adventure
The [tutorial](https://docs.rpgdesk.com/en/fichas/primeira-ficha/)’s sheet: fields, computed modifiers, rolls and a list.
*Working example:* [Quick Adventure](https://docs.rpgdesk.com/exemplos/en/first-sheet.html)
## Generic D20
The portrait, the tabs, the inventory list, the modifiers, health on the card’s bar and a GM-only tab (a [private part](https://docs.rpgdesk.com/en/fichas/partes-privadas/)). It is the complete example from the AI guide.
*Working example:* [Generic D20](https://docs.rpgdesk.com/exemplos/en/generic-d20.html)
## RPG Desk Basic Sheet
A [package](https://docs.rpgdesk.com/en/fichas/pacotes/) with HTML, CSS, JavaScript and an image: attributes, skills, attacks with hit and damage, an inventory with the total load, notes, health and energy on the card’s bars and the GM’s notes. It works for any system.
*Working example:* [RPG Desk Basic Sheet](https://docs.rpgdesk.com/exemplos/en/basic-sheet/sheet.html) ([Download the .zip](https://docs.rpgdesk.com/exemplos/en/basic-sheet.zip))
## Room NPCs
A [room table](https://docs.rpgdesk.com/en/fichas/tabelas/): the NPCs, with HP, initiative and notes, and the **Hidden from players** box, which really hides the NPC.
*Working example:* [Room NPCs](https://docs.rpgdesk.com/exemplos/en/npc-table.html)
# Reference
> For quick lookup: the plugin manifest, the HTML attributes, the rpgdesk.js API, the CSS, the verifier, the limits, the chat commands, rolls, shortcuts and formatting.
Page: https://docs.rpgdesk.com/en/referencia/
The reference is for quick lookup, when you already know what you want to do and need the detail. To learn, start with [Creating sheets](https://docs.rpgdesk.com/en/fichas/) or [In the room](https://docs.rpgdesk.com/en/mesa/).
## Sheets and plugins
[The manifest](https://docs.rpgdesk.com/en/referencia/manifesto/): Each field, what it accepts and what RPG Desk checks.
[HTML attributes](https://docs.rpgdesk.com/en/referencia/atributos/): data-field, data-list, data-roll, data-tabs and the others.
[The rpgdesk.js API](https://docs.rpgdesk.com/en/referencia/api/): Every function of the RPG Desk object and the document.
[Looks (CSS)](https://docs.rpgdesk.com/en/referencia/css/): The classes and variables of rpgdesk.css and the theme.
[The verifier](https://docs.rpgdesk.com/en/referencia/verificador/): Each problem the installation points out and how to fix it.
[Limits](https://docs.rpgdesk.com/en/referencia/limites/): Sizes, amounts and how many times per minute.
## The room
[Chat commands](https://docs.rpgdesk.com/en/referencia/comandos/): /r, /me, /nick, /cls and the others.
[Rolls](https://docs.rpgdesk.com/en/referencia/rolagens/): The grammar of rolls and how successes count.
[Chat formatting](https://docs.rpgdesk.com/en/referencia/formatacao/): The markup, the colors and the emoji.
[Keyboard shortcuts](https://docs.rpgdesk.com/en/referencia/atalhos/): The scene, the chat and the windows.
# The manifest
> Each field of a RPG Desk plugin's manifest, what it accepts and what the verifier checks.
Page: https://docs.rpgdesk.com/en/referencia/manifesto/
The manifest tells RPG Desk what the plugin is. It goes:
- **in a single `.html` file**, inside the ``: ``;
- **in a `.zip` package**, in the `manifest.json` file, at the root.
It is JSON: double quotes, no comments and no comma after the last item. The JSON Schema, for your editor’s help, is at `https://docs.rpgdesk.com/_sdk/1/manifest.schema.json` (use it in `"$schema"`).
## Example
```json
{
"rpgdesk": 1,
"id": "com.yourname.system",
"name": { "pt": "Meu Sistema", "en": "My System" },
"version": "1.2.0",
"author": "Your name",
"description": "My System's sheet and NPC table.",
"sdk": 1,
"icon": "icon.svg",
"sheets": [
{ "type": "com.yourname.system.sheet", "title": "Character", "entry": "sheet.html", "private": { "gm": "gm" } }
],
"tables": [
{ "type": "com.yourname.system.npcs", "title": "NPCs", "entry": "npcs.html" }
],
"webhooks": [
{ "name": "rolls", "description": "Every roll from the sheet", "example": { "total": 17 } }
]
}
```
## The fields
| Field | Required | What it is |
| ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpgdesk` | yes | the manifest format’s version: `1` |
| `id` | yes | the plugin’s identifier: lowercase letters, numbers, `.`, `-` and `_`, starting with a letter or number (up to 120). Use a reversed domain: `com.yourname.system` |
| `name` | yes | the plugin’s name (up to 120), as one text or per language (see below) |
| `version` | yes | major.minor.patch, like `1.0.0`. Bump it with each change |
| `sdk` | yes | rpgdesk.js’s major version: `1` |
| `author` | no | who made it (up to 120) |
| `description` | no | what the plugin brings (up to 1000). It shows up when installing and in the plugin list |
| `sheets` | one of the two | the sheets (see below) |
| `tables` | one of the two | the room tables (see below) |
| `webhooks` | no | the webhooks the plugin uses (see below) |
| `icon` | no | a `.png` or `.svg` from the package |
| `$schema` | no | the JSON Schema’s address, for the editor |
A field RPG Desk does not know triggers a warning, and is ignored.
## Sheets and tables
`sheets` and `tables` are lists. Each item:
| Field | What it is |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | the sheet or table’s data type: it starts with the plugin’s `id` and a period (`com.yourname.system.sheet`), with the same characters as the `id` (up to 120). Do not change it after publishing |
| `title` | the name shown in **New sheet…** or on the table’s tab (up to 120), as one text or per language |
| `entry` | **packages only:** the sheet or table’s HTML, inside the package (`sheet.html`). In a single file, the entry is the file itself |
| `private` | **sheets only:** the private parts, `{ "path": "gm" \| "owner" }`. See [Private parts](https://docs.rpgdesk.com/en/fichas/partes-privadas/) |
- The plugin needs at least one sheet or table, and has at most 20.
- A single `.html` file brings **one** sheet or **one** table.
- Each `type` appears once.
## Webhooks
`webhooks` is a list (up to 20). Each item:
| Field | What it is |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| `name` | the name the page uses in `RPGDesk.webhooks.send(name, data)`: lowercase letters, numbers, `-` and `_` (up to 40) |
| `description` | what the webhook sends, for the game master (up to 300) |
| `example` | optional: a sample of the data, up to 4 KB as JSON |
See [Webhooks on the sheet](https://docs.rpgdesk.com/en/fichas/webhooks/).
## Texts in two languages
`name` and `title` accept one text per language:
```json
"name": { "pt": "Ficha Básica do RPG Desk", "en": "RPG Desk Basic Sheet" }
```
Each person sees the one in their RPG Desk language; without theirs, Portuguese is used, then English, then the first one. The keys are language codes: `pt`, `en`, `pt-BR`.
> **Note**
>
> The `description` and the page’s texts have no per-language version in the manifest: to translate the page, use the context’s `language`. See [JavaScript on the sheet](https://docs.rpgdesk.com/en/fichas/javascript/#a-sheet-in-two-languages).
# HTML attributes
> Every data-* attribute rpgdesk.js connects by itself: fields, texts, images, lists, rolls, tabs and roles.
Page: https://docs.rpgdesk.com/en/referencia/atributos/
rpgdesk.js connects these attributes by itself when the page loads, and also on elements that come in later. Inside a list’s ``, paths are relative to the item. To learn with examples, see [Fields, lists and tabs](https://docs.rpgdesk.com/en/fichas/campos/).
| Attribute | Where it goes | What it does |
| ------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `data-field="path"` | ``, `