RPG Desk: creating sheets and reference. The Creating sheets and Reference sections of the RPG Desk documentation: everything used to write sheets and room tables in HTML, CSS and JavaScript with rpgdesk.js.
# Creating sheets
> Room sheets and tables made with HTML, CSS and JavaScript, by hand or with help from an AI.
Page: https://docs.rpgdesk.com/en/fichas/
In RPG Desk, a sheet is a web page: **HTML** for the fields, **CSS** for the looks and, if needed, **JavaScript** for the math. **rpgdesk.js**, RPG Desk’s library, connects the page to the room:
- what the player writes is kept in the room and shows up right away for the game master;
- roll buttons roll in the chat, with the 3D dice, for everyone;
- only the sheet’s owner and the game masters write; others only read, and rpgdesk.js locks the fields by itself;
- parts of the sheet can be for the game master only, and they never even reach the players.
The sheet below is working. Type in the fields and click **Roll Strength**:
*Working example:* [Minimal sheet](https://docs.rpgdesk.com/exemplos/en/minimal-sheet.html)
It does not have a single line of JavaScript: each field has a `data-field` attribute, and each roll button, a `data-roll`.
## Three ways to make one
**With an AI**
Copy RPG Desk’s guide to the AI (ChatGPT, Claude, Gemini…), describe the sheet and install the file it gives back. See [Create with an AI](https://docs.rpgdesk.com/en/fichas/com-ia/).
**By hand, in one file**
One `.html` file, with the manifest inside and the two rpgdesk.js lines. Start with the [tutorial](https://docs.rpgdesk.com/en/fichas/primeira-ficha/).
**In a package**
Several files (HTML, CSS, JavaScript, images, fonts) in a `.zip`, with more than one sheet or table. See [Packages with several files](https://docs.rpgdesk.com/en/fichas/pacotes/).
## From file to room
1. **Test it in the browser:** open the sheet’s file (double-click it). Outside RPG Desk, rpgdesk.js enters **test mode**, with the data in the browser and a band in the corner to switch roles.
2. **Install it in the room:** as game master, in **Room settings → Plugins → Install plugin…**, choose the `.html` (or the `.zip`). RPG Desk checks the file and tells you what to fix, if anything.
3. **Use it:** the sheet shows up in **New sheet…**, in the library.
> **Tip**
>
> Sheets and tables are the same thing inside. A **room table** (an NPC list, a calendar) is the same kind of page, which sits below the library for the whole room. See [Room tables](https://docs.rpgdesk.com/en/fichas/tabelas/).
## In this section
[Your first sheet](https://docs.rpgdesk.com/en/fichas/primeira-ficha/): The tutorial: from an empty file to the sheet installed in the room.
[Create with an AI](https://docs.rpgdesk.com/en/fichas/com-ia/): The guide for the AI, the request and how to fix what comes back wrong.
[Fields, lists and tabs](https://docs.rpgdesk.com/en/fichas/campos/): Everything you do with HTML attributes alone.
[JavaScript on the sheet](https://docs.rpgdesk.com/en/fichas/javascript/): The document, computed fields and lists from code.
[Rolls, chat and card](https://docs.rpgdesk.com/en/fichas/rolagens-e-chat/): Rolling, talking in the chat and filling in the player's bars.
[Private parts](https://docs.rpgdesk.com/en/fichas/partes-privadas/): What only the game master or only the owner sees.
[Room tables](https://docs.rpgdesk.com/en/fichas/tabelas/): Pages for the whole room: NPCs, initiative, travel maps.
[Looks](https://docs.rpgdesk.com/en/fichas/visual/): rpgdesk.css, the theme colors and narrow screens.
[Packages with several files](https://docs.rpgdesk.com/en/fichas/pacotes/): The .zip with manifest.json, images and fonts.
[Test and develop](https://docs.rpgdesk.com/en/fichas/desenvolvimento/): Test mode, development mode and page errors.
[Webhooks on the sheet](https://docs.rpgdesk.com/en/fichas/webhooks/): Sending data to Zapier, Make or IFTTT.
[New versions](https://docs.rpgdesk.com/en/fichas/versoes/): Updating the sheet without losing the players' data.
[Examples](https://docs.rpgdesk.com/en/fichas/exemplos/): Ready-made sheets and a table, to use and study.
For details, the [Reference](https://docs.rpgdesk.com/en/referencia/) has the manifest, the attributes, the rpgdesk.js API, the verifier and the limits.
# Your first sheet
> The tutorial: from an empty file to a sheet with fields, rolls, a list and a computed field, tested in the browser and installed in the room.
Page: https://docs.rpgdesk.com/en/fichas/primeira-ficha/
In this tutorial you make a simple sheet, for the game “Quick Adventure”: name, level, two attributes with a computed modifier, a roll button for each and a gear list. All you need is a text editor (Notepad will do; VS Code is better) and the browser.
## 1. The skeleton
Create a file called `my-sheet.html` with this:
`my-sheet.html`
```html
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:
```html
Gear
```
The `` is the mold for each item. Inside it, `data-field="name"` is the **item’s** name, not the character’s. `data-list-add` adds an empty item; `data-list-remove` removes its item.
## 7. Done
Putting it all together, the sheet looks like this:
*Working example:* [Quick Adventure](https://docs.rpgdesk.com/exemplos/en/first-sheet.html)
`my-sheet.html`
```html
Hero
Attributes
Modifier:
Modifier:
Gear
```
## 8. Install it in the room
1. Enter your room as game master and open **Room settings → Plugins**.
2. **Install plugin…** and choose `my-sheet.html`.
3. RPG Desk checks the file. If a problem shows up, the dialog says how to fix it (see [The verifier](https://docs.rpgdesk.com/en/referencia/verificador/)). With no errors, click **Install**.
4. In the library, **New item → New sheet…** shows the **Hero** system, from **Quick Adventure**.
Changed the sheet? Bump the `version` in the manifest (`1.0.1`) and install it again: RPG Desk updates the plugin, and the sheets already created keep their data. See [New versions](https://docs.rpgdesk.com/en/fichas/versoes/).
> **What next?**
>
> - Tabs, images, checkboxes and richer lists: [Fields, lists and tabs](https://docs.rpgdesk.com/en/fichas/campos/).
> - Health on the player’s card: [Rolls, chat and card](https://docs.rpgdesk.com/en/fichas/rolagens-e-chat/#the-players-card).
> - Notes only the game master sees: [Private parts](https://docs.rpgdesk.com/en/fichas/partes-privadas/).
# Create with an AI
> Making the sheet for your system with help from an AI: RPG Desk's guide, the request, testing and how to fix what comes back wrong.
Page: https://docs.rpgdesk.com/en/fichas/com-ia/
You do not need to know how to code to have a sheet for your system. A chat AI (ChatGPT, Claude, Gemini…) writes the whole sheet, if it knows RPG Desk’s rules. Those rules are in the **AI guide**: you paste the guide at the start of the conversation and describe the sheet.
## The AI guide
Two ways to get the guide:
- **In RPG Desk:** inside your room, as game master, in **Room settings → Plugins**, click **Copy instructions for AI**. The guide goes to the clipboard, in RPG Desk’s language and with your server’s rpgdesk.js address.
- **Here on the site:** [download the guide in English](https://docs.rpgdesk.com/_sdk/1/ai-guide.md) or [in Portuguese](https://docs.rpgdesk.com/_sdk/1/guia-ia.md), and paste the file’s content.
*Screenshot:* The Install plugin and Copy instructions for AI buttons, in Settings, Plugins.
The guide explains to the AI the file format, the environment’s rules (no internet, libraries only inside the package), the attributes and the rpgdesk.js API, and includes a complete example.
## The documentation for the AI
The guide sums up the rules. For the AI to look up the details (every attribute, the rpgdesk.js API, the verifier codes), this documentation also comes in text files made for AI, following the [llms.txt](https://llmstxt.org) standard:
- [`llms-fichas.txt`](https://docs.rpgdesk.com/en/llms-fichas.txt): the Creating sheets and Reference sections in a single file. It is what helps most to write sheets: if the AI accepts files, attach it to the conversation along with the guide.
- [`llms-full.txt`](https://docs.rpgdesk.com/en/llms-full.txt): the whole documentation.
- [`llms.txt`](https://docs.rpgdesk.com/en/llms.txt): the index, with a link to every page. If the AI can open web addresses, send it this one: it finds the rest from there.
Every page of the site also comes in Markdown: replace the slash at the end of the address with `.md` (`/en/fichas/campos/` becomes `/en/fichas/campos.md`).
## Ask for the sheet
1. Open a new conversation with the AI.
2. Paste the guide and, right after it, describe the sheet. The more concrete, the better:
```text
Make the sheet for my system, "Blades of the Backlands".
- Identity: name, origin, trade, level (1 to 10) and a portrait.
- Attributes: Strength, Agility, Mind and Courage, from 1 to 5. Each one with a
button that rolls 2d6 + the attribute.
- Health: current and maximum (maximum = 10 + Strength x 2, computed). Health
goes to bar 1 on the player's card.
- Skills: a list with name and bonus, and a button that rolls 2d6 + bonus.
- Inventory: a list with item and quantity.
- A "GM" tab, for game masters only, with notes.
Colors: sand and leather tones. It has to fit a narrow space.
```
3. Ask for **the whole `.html` file**. Save the answer in a file with the `.html` extension (`backlands.html`).
## Test it
Open the file in the browser (double-click it). Outside RPG Desk, the sheet enters **test mode**: fill in the fields, click the roll buttons and look at the **Log**, on the band in the corner. Switch the **Role** to **Another player** and check that the fields lock. See [Test and develop](https://docs.rpgdesk.com/en/fichas/desenvolvimento/).
Something wrong or missing? Tell the AI what happened, in detail (“the Agility button rolls 1d20, not 2d6”; “the portrait does not show up”), and ask for the whole file again.
## Install and fix
Install it in **Room settings → Plugins → Install plugin…**. RPG Desk checks the file first:
*Screenshot:* The install dialog with two errors and a warning, each with how to fix it, and the Copy report button.
- If problems show up, click **Copy report** and paste it in the conversation with the AI: the report says what is wrong, on which line and how to fix it, in a text the AI understands.
- Once installed, if the sheet shows a **Page errors** badge (the triangle in the corner), click it, then **Copy errors**, and paste that in the conversation too.
*Screenshot:* A sheet with the Page errors panel open, showing a TypeError, and the Copy errors and Clear buttons.
> **Tips**
>
> - Ask for one thing at a time: first the basic sheet, then the tabs, then the math.
> - Remind the AI to bump the `version` with each change (`1.0.0`, `1.0.1`…): that way RPG Desk knows it is an update. See [New versions](https://docs.rpgdesk.com/en/fichas/versoes/).
> - If the conversation got long and the AI started forgetting the rules, open another conversation, paste the guide and the current file, and carry on from where you stopped.
> - The AI does not see the screen. A screenshot of the problem, when the AI accepts images, helps a lot.
# Fields, lists and tabs
> Everything you do with HTML attributes alone: fields of every kind, computed texts, images, lists, tabs and what each role sees.
Page: https://docs.rpgdesk.com/en/fichas/campos/
rpgdesk.js connects the page’s `data-…` attributes by itself, including on elements that show up later (the items of a list, for example). A whole sheet can be made without JavaScript. The complete table is in [HTML attributes](https://docs.rpgdesk.com/en/referencia/atributos/).
The sheet below uses almost everything on this page: the portrait, the fields, the computed modifiers, the tabs, the inventory list and the GM tab. Switch the **Role** on the band in the corner to see what each person sees.
*Working example:* [Generic D20](https://docs.rpgdesk.com/exemplos/en/generic-d20.html)
## The document and paths
Each sheet has a **document**: its fields and their values, kept in the room. Each field has a **path**:
- `name`, `level`, `strength`: standalone fields;
- `attributes.strength`, `hp.current`, `hp.max`: fields inside a group, separated by periods.
The naming rules:
- **unaccented** letters, numbers and `_`, starting with a letter or `_`;
- case does not matter: `Strength` and `strength` are the same field;
- up to 64 characters per name and 12 levels of groups;
- names that start with `_rpgdesk` belong to RPG Desk.
The verifier flags a wrong name before installing. See [The verifier](https://docs.rpgdesk.com/en/referencia/verificador/).
## Fields: `data-field`
It goes on an ``, `
```
| Field | What it saves |
| -------------------------------------------- | ---------------------------------------------------------- |
| text, `
```
`data-role` alone only hides the button; the manifest’s `private` is what keeps the secret. Test it in test mode, switching the **Role** to **Another player**: the tab disappears, and `RPGDesk.doc.get('gm')` gives `undefined`.
## On tables: `doc.restrict`
Room tables have no owner, and the manifest’s `private` does not apply to them (the verifier warns you). On a table, the game master hides parts from code, on the spot:
```js
await doc.restrict(['npcs', '#' + id], 'gm'); // this NPC becomes game master only
await doc.restrict(['npcs', '#' + id], null); // back to everyone
```
`doc.restrict(path, 'gm' | 'owner' | null)` only works for game masters. It is what the examples’ NPC table does with the **Hidden from players** checkbox: see [Room tables](https://docs.rpgdesk.com/en/fichas/tabelas/).
> **Note**
>
> A private part disappears for whoever loses it: if the game master hides an NPC, it leaves the players’ screens right away. When it goes back to everyone, it shows up again.
# Room tables
> Pages for the whole room, open as a tab for everyone: an NPC list, initiative, a calendar. How to declare them, who writes and an annotated example.
Page: https://docs.rpgdesk.com/en/fichas/tabelas/
A **room table** is a page like a sheet, with two differences:
- there is **one per room**, and it stays open for everyone, as a tab;
- **only game masters write**; players see it.
They are for what belongs to the room, not to a character: the campaign’s NPCs, a calendar, the travel map, the factions’ reputation.
## Declare it
In the manifest, replace `"sheets"` with `"tables"`:
```json
"tables": [{ "type": "com.yourname.system.npcs", "title": "NPCs" }]
```
A single `.html` file brings one sheet **or** one table. A [package](https://docs.rpgdesk.com/en/fichas/pacotes/) can bring both, with one HTML for each.
## In the room
1. Install the plugin in **Room settings → Plugins**.
2. In the **… tables** group, below the plugin, click **Enable**.
3. The table opens for everyone as a tab that doesn’t come into view, next to the other tables (or in the last space used): click its name to see it.
Disabling it closes the table for everyone and keeps the data: enabling it again brings everything back as it was.
## In code
- `kind` is `'table'`, and `item.ownerId` is `null` (the table has no owner).
- The manifest’s `private` does not apply to tables: hide parts with `doc.restrict` (see [Private parts](https://docs.rpgdesk.com/en/fichas/partes-privadas/#on-tables-docrestrict)).
- The game master’s controls get `data-role="gm"`: for players, the fields already lock by themselves, but the create and delete buttons disappear.
- To change a player’s card, say whose: `RPGDesk.card.setBar(0, 7, 12, { userId })`, with the `id` from `await RPGDesk.room.players()`.
## Example: the NPC list
*Working example:* [Room NPCs](https://docs.rpgdesk.com/exemplos/en/npc-table.html)
The example is a list where each NPC has a name, HP, initiative, notes and a button to roll initiative, all with HTML attributes. The JavaScript does two things:
```js
RPGDesk.connect().then(({ doc, me }) => {
const npcs = doc.list('npcs');
const empty = document.getElementById('empty');
// "No NPCs yet." disappears when the list has items
npcs.watch((items) => { empty.hidden = items.length > 0; }, { now: true });
if (me.role !== 'gm') return;
// "Hidden from players": the NPC becomes game master only
const seen = new Map();
npcs.watch((items, { local }) => {
for (const npc of items) {
const hidden = npc.hidden === true;
if (seen.get(npc.id) === hidden) continue;
seen.set(npc.id, hidden);
if (local) doc.restrict(['npcs', '#' + npc.id], hidden ? 'gm' : null);
}
}, { now: true });
});
```
- Only the browser of the game master who checked the box (`local`) calls `restrict`: the other game masters with the table open do not repeat the request.
- The hidden NPC really disappears for players: the server does not even send it.
> **Tip**
>
> In test mode, the table opens with the **GM** role. Switch to **Another player** on the band to see how players see it.
# Looks
> rpgdesk.css, the ready-made classes, the room's theme colors, fonts, images and how to make the sheet fit a narrow space.
Page: https://docs.rpgdesk.com/en/fichas/visual/
## rpgdesk.css
The skeleton’s second line loads `rpgdesk.css`:
```html
```
It is optional and gives the sheet RPG Desk’s look: the dark background, the fields, the buttons (roll buttons highlighted), the tabs, the lists and the fonts (Roboto, Lato and Inconsolata). Without it, the page starts raw, and the looks are all yours.
The ready-made classes:
| Class | What it does |
| ------------ | ------------------------------------------ |
| `rd-row` | a row that wraps when it runs out of space |
| `rd-col` | a column |
| `rd-grid` | a grid of cards that adapts to the width |
| `rd-card` | a box with a background and a border |
| `rd-grow` | takes up the space left in a row |
| `rd-primary` | the highlighted button |
| `rd-muted` | subdued text |
## The theme colors
rpgdesk.js receives the room’s colors and sets them as CSS variables. Use the variables, and your sheet matches the rest of the room:
```css
.box {
background: var(--rd-bg-2);
border: 1px solid var(--rd-line);
color: var(--rd-text);
}
.highlight { color: var(--rd-accent); }
```
| Variable | What it is |
| ------------------------------------------------------ | ----------------------------------------- |
| `--rd-text` | the text |
| `--rd-muted` | subdued text |
| `--rd-accent`, `--rd-accent-hover`, `--rd-accent-text` | the accent color, on hover and as text |
| `--rd-bg`, `--rd-bg-2`, `--rd-bg-3` | the backgrounds, from darkest to lightest |
| `--rd-line` | borders and lines |
| `--rd-error` | errors |
| `--rd-font`, `--rd-title-font` | the text and heading fonts |
| `--rd-radius` | the corner rounding |
The room theme’s raw colors also arrive, with the `--rd-` prefix (such as `--rd-dominant-color` and `--rd-face-color`). The list is in [Looks (CSS reference)](https://docs.rpgdesk.com/en/referencia/css/).
## Narrow and wide screens
The sheet opens in a room space, which can be about **350 px** wide or the whole screen (in a window of its own). Make the sheet adapt:
- use `rd-row` (or `flex-wrap: wrap`) on rows of fields;
- use grids with `repeat(auto-fill, minmax(150px, 1fr))` instead of fixed columns;
- do not fix large widths in pixels;
- the page scrolls by itself: do not put `overflow: hidden` on the `body`.
Test by narrowing the browser window in test mode.
## Images and fonts
The sheet has no internet access: images and fonts from outside do not load.
- **Small drawings:** SVG inside the HTML, or `data:` addresses.
- **The character’s portrait:** ``, which the person chooses in RPG Desk.
- **Your own images and fonts:** put the files in a [package](https://docs.rpgdesk.com/en/fichas/pacotes/) and use relative paths (``, `@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"` | ``, `
`, `@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: ``, ``, `