The rpgdesk.js API

rpgdesk.js creates the global RPGDesk object. Almost everything returns a Promise: use await or .then(). Calls made before connecting wait for the connection. To learn with examples, see JavaScript on the sheet and Rolls, chat and card.

RPG Desk


`RPGDesk.connect()`	connects (to RPG Desk or to test mode) and returns the context, with the `doc`
`RPGDesk.context`	the context, once connected (before that, `null`)
`RPGDesk.doc`	the document, once connected (before that, `null`)
`RPGDesk.version`	rpgdesk.js’s version (`'1.0.0'`)
`RPGDesk.on(event, fn)`	listens to a room event; returns the function that stops listening
`RPGDesk.bind(element)`	connects the `data-…` attributes of a piece of the page built by hand

The context

{
  kind: 'sheet' | 'table',
  item: { id: string, name: string, type: string, ownerId: string | null },
  me: { id: string, nick: string, role: 'gm' | 'player' | 'spectator', isOwner: boolean },
  room: { id: string, name: string, system: string },
  language: 'pt' | 'en',
  test: boolean,                       // outside RPG Desk, in test mode
  plugin: { id: string, version: string },
  doc: Doc,
}

Events

Event	`fn` receives	When
`'players'`	the list of players (like `RPGDesk.room.players()`)	someone joins, leaves or changes
`'library'`	the library items (like `RPGDesk.room.library()`)	the library changes
`'me'`	the new `me`	the person’s role changes
`'language'`	`'pt'` or `'en'`	the person switches RPG Desk’s language
`'theme'`	the theme variables	the room’s colors change

The document (`doc`)


`doc.get(path)`	the value: text, number, `true`/`false`, an object (group) or `undefined`. `doc.get('')` gives the whole document
`doc.set(path, value)`	writes. An object writes field by field; `null` deletes. Returns a promise
`doc.update({ path: value, … })`	writes several fields in one batch
`doc.batch(() => { … })`	whatever is written inside the function goes in a single batch, applied whole or refused whole
`doc.watch(path, fn, { now })`	tells you about each change on the path or inside it: `fn(value, { local })`. Returns the function that stops it
`doc.compute(target, [sources], fn)`	computed field: writes `fn(...source values)` to the target when a source changes in this browser, if the person can write to the target. `undefined` does not write. Returns the function that stops it
`doc.canWrite(path)`	whether the person can write there
`doc.list(path)`	the list at the path (see below)
`doc.restrict(path, 'gm' \| 'owner' \| null)`	game masters only: the part becomes game master only, owner and game masters only, or everyone’s again
`doc.on('rejected', fn)`	tells you when a write is refused: `fn(message)`. Returns the function that stops it

Paths are texts ('hp.current') or arrays (['npcs', '#' + id, 'hp']); #id points to a list item.

Lists

doc.list(path) returns:


`items()`	the items, in order: `[{ id, …fields }]`
`length`	how many items
`add(value?, position?)`	creates an item (at the end, or at the position) and returns its `id` right away
`remove(id)`	deletes the item
`move(id, position)`	moves the item
`item(id)`	the item: `{ id, get(field), set(field, value), watch(field, fn, { now }), remove() }`
`watch(fn, { now })`	tells you about each change in the list or its items: `fn(items, { local })`

Dice and chat


`RPGDesk.dice.roll(expression, { label })`	rolls in the room (with the 3D dice, in everyone’s chat). Returns `{ expression, total, items, successes }`
`RPGDesk.chat.send(text, { kind, name })`	sends to the chat. `kind`: `'chat'`, `'action'`, `'laugh'`, `'narrator'` or `'npc'` (with `name`)
`RPGDesk.chat.local(text)`	a line in the chat of whoever is looking only

A roll’s items: { kind: 'dice', sign, faces, results }, { kind: 'fudge', sign, results } or { kind: 'value', sign, value }. successes only exists in rolls with >.

The room and the card


`RPGDesk.room.players()`	who is in the room: `[{ id, nick, role, avatar, mainCharacterId }]`
`RPGDesk.room.library()`	the library items the person sees: `[{ id, name, kind, type, ownerId, parentId }]`
`RPGDesk.room.on('players' \| 'library', fn)`	the same as `RPGDesk.on`
`RPGDesk.card.setBar(index, value, max, { userId })`	the card’s bar: the index goes from 0 (Bar 1) to 3. On a sheet, the card is the owner’s; on a table, pass the `userId`. A maximum of 0 removes the bar
`RPGDesk.card.setLine(index, text, { userId })`	the card’s line: the index goes from 0 to 3; up to 120 characters

Interface


`RPGDesk.ui.toast(text, type)`	a notice. `type`: `'info'`, `'success'` or `'error'`
`RPGDesk.ui.confirm(text, { title })`	a yes-or-no question: `true` or `false`
`RPGDesk.ui.prompt(text, initial)`	asks for a text: the text, or `null` if the person cancels
`RPGDesk.ui.menu(items, where)`	a RPG Desk menu. `items`: `{ id, label, disabled?, danger? }` or `{ separator: true }`; `where`: the `MouseEvent` or `{ x, y }`. Returns the chosen `id` or `null`
`RPGDesk.ui.openItem(id)`	opens a sheet or scene from the library
`RPGDesk.ui.openLink(url)`	opens an `http(s)` site in another tab, after the person confirms: `true` if it opened
`RPGDesk.ui.copy(text)`	copies to the clipboard
`RPGDesk.ui.download(name, data, type)`	offers a file to download: `data` is a text, `Blob` or `ArrayBuffer` (up to 20 MB)

Files, preferences and screen state


`RPGDesk.files.pickImage()`	opens RPG Desk’s image picker: `{ id }` or `null`
`RPGDesk.files.url(id)`	an address to show the file in an `<img>`
`RPGDesk.storage.get(key)`, `set(key, value)`, `keys()`	the person’s preferences, in this browser, for your plugin (up to 1 MB)
`RPGDesk.view.get(key)`, `set(key, value)`	this sheet’s screen state; `get` answers right away (no promise)

Webhooks


`RPGDesk.webhooks.send(name, data)`	sends the data to the webhook declared in the manifest, through the server. Returns `{ ok, status, body, error }`

See the error codes in Webhooks on the sheet.