Dice+ SDK Reference

Getting Started

@dice-plus/sdk puts the Dice+ 3D dice tray and dice bag on your site. Both are iframes served by Dice+; the SDK creates them and gives you typed methods and events. Dice+ runs the physics, Rooms, the player's dice and Patreon sign-in. You build the controls and show the results.

Component What it is
DicePlusTray The dice tray: rolls notation, plays every roll in the player's Room, reports results
DicePlusBag The player's dice bag: their dice, stats, cloud backup and Patreon sign-in
rooms Helpers for Room Codes and Passcodes
Types Every type the SDK uses

Installation

npm install @dice-plus/sdk
import { DicePlusTray, DicePlusBag, rooms } from '@dice-plus/sdk';

Without a bundler, import the same module from the Dice+ site. /sdk/v1.js serves the latest 1.x release.

<script type="module">
  import { DicePlusTray } from 'https://dice-plus.missinglinkdev.com/sdk/v1.js';
</script>

The package ships TypeScript declarations for everything in this reference.

Access Key

Every site needs an Access Key. Request one at dice-plus.missinglinkdev.com/devs.

A refused key rejects ready and fires unauthorized.

Quick start

import { DicePlusTray } from '@dice-plus/sdk';

const tray = new DicePlusTray({
  apiKey: 'dp_your_key',
  container: document.body,
  identity: { name: 'Ari', color: '#e07a5f' },
});

tray.on('roll-result', ({ result, isOwn }) => {
  console.log(`${result.playerName} rolled ${result.result.totalValue}`);
});

await tray.ready;
await tray.roll({ diceNotation: '2d20kh1+5' });

Notation is the same as in the Dice+ extension: keep/drop, advantage, exploding and imploding dice, rerolls, pools, Fudge dice, table rolls and arithmetic. See Dice Notation.

Attribution

Embedding Dice+ is free. In return:

Keys that break these terms may be revoked.

Versions

The SDK follows semantic versioning. /sdk/v1.js tracks the latest 1.x, and SDK_VERSION exports the installed version. The embeds accept every 1.x SDK; if a release ever stops supporting yours, the embeds fire unauthorized with reason protocol.

import { SDK_VERSION } from '@dice-plus/sdk';

Owlbear Rodeo extensions

Building an Owlbear Rodeo extension rather than a website? You don't need the SDK: Dice+ in Owlbear Rodeo takes roll requests over OBR broadcast channels. See Extension Integration.

DicePlusTray

The dice tray. It fills an element you give it, see-through and click-through, so your page stays usable underneath. It rolls notation, plays every roll in the player's Room (including rolls from Owlbear Rodeo players), and reports each result.

const tray = new DicePlusTray({
  apiKey: 'dp_your_key',
  container: document.getElementById('table')!,
  settings: { settleTime: 'fast', sound: false },
  identity: { name: 'Ari', color: '#e07a5f' },
  dice: { default: { color: '#1d3557', numberColor: '#f1faee' } },
});

Constructor

new DicePlusTray(options: DicePlusTrayOptions)
Name Type Description
apiKey string Your Access Key
container HTMLElement The element the tray fills. Use document.body for a full-page overlay. Set to position: relative if it was static.
settings TraySettings Optional. Tray behaviour; anything left out uses the Dice+ default
identity TrayIdentity Optional. How the player appears to others in a Room
dice SiteDice Optional. Your look for die types the player has no dice for
theme EmbedTheme Optional. Your site's colors for the embed's UI. See Colors
baseUrl string Optional. Where the embeds are served from; only for testing a development build

Throws if container is missing.

Properties

Name Type Description
ready Promise<{ playerId: string }> Resolves once the tray has loaded and accepted your key; rejects with the refusal message otherwise. Calls made before it resolves are queued. playerId is this player's id in Rooms, stable for this browser on your site.

Methods

roll

roll(request: TrayRollRequest): Promise<{ rollId: string }>

Rolls dice for this player. Resolves with the roll's id as soon as the tray accepts it; the result arrives later as roll-result. Invalid notation resolves and then fires roll-error.

Name Type Description
request TrayRollRequest The notation and options for the roll

Rejects with A roll needs diceNotation. for empty notation, and That source is reserved. for source: 'dice-plus-fairness'.

const { rollId } = await tray.roll({ diceNotation: '1d20+7', source: 'attack' });
{ "rollId": "roll_1762891234567_k2x9q7a" }

setSettings

setSettings(settings: TraySettings): Promise<void>

Changes the given settings and leaves the rest as they are.

Name Type Description
settings TraySettings The settings to change

Rejects with Wait for the roll to finish before switching headless mode. if headless changes while this player's roll is in the air.

await tray.setSettings({ clearDelaySeconds: 6, critEffects: { enabled: true, dice: ['d20'] } });

setIdentity

setIdentity(identity: TrayIdentity): Promise<void>

Changes the player's name and color. In a Room the other players see the change straight away.

Name Type Description
identity TrayIdentity The new name and color

setSiteDice

setSiteDice(dice: SiteDice | null): Promise<void>

Replaces your site's default dice look. See Dice look.

Name Type Description
dice SiteDice | null The new default, or null for the Dice+ standard dice

setTheme

setTheme(theme: EmbedTheme | null): Promise<void>

Replaces your site's colors for the tray's overlays, for example when your site switches between light and dark. See Colors.

Name Type Description
theme EmbedTheme | null The new colors, or null for the Dice+ look

getHistory

getHistory(): Promise<HistoryEntry[]>

Returns the player's recent rolls on your site, newest first, including other players' rolls in the Room. See HistoryEntry.

[
  {
    "id": "roll_1762891234567_k2x9q7a",
    "playerId": "web-3f1c9a52-7d4e-4b8a-9c21-5e0f6a7b8c9d",
    "playerName": "Ari",
    "rollTarget": "everyone",
    "timestamp": 1762891234567,
    "result": {
      "rollId": "roll_1762891234567_k2x9q7a",
      "diceNotation": "1d20+7",
      "totalValue": 23,
      "rollSummary": "[16] 16 + 7 = 23",
      "groups": [{ "diceType": "d20", "total": 16, "dice": [ … ] }]
    }
  }
]

latest

latest(name: 'room-state' | 'dice-availability' | 'history-changed'): RoomState | DiceAvailability | HistoryEntry[] | undefined

Returns the last value of a state event without waiting for the next one, or undefined if it hasn't fired yet. The return type follows name.

Name Type Description
name 'room-state' | 'dice-availability' | 'history-changed' The event
const room = tray.latest('room-state');
if (room && !room.solo) showRoomBadge(room.roomCode);
{ "d6": { "active": 6, "jailed": 0 }, "d20": { "active": 2, "jailed": 1 } }

on

on<E extends keyof DicePlusTrayEvents>(name: E, listener: (data: DicePlusTrayEvents[E]) => void): () => void

Listens for an event.

Name Type Description
name string The event name
listener (data) => void Called with the event's data

Returns a function that, when called, stops listening.

const stop = tray.on('rolling', ({ rolling }) => { rollButton.disabled = rolling; });

once

once<E extends keyof DicePlusTrayEvents>(name: E, listener: (data: DicePlusTrayEvents[E]) => void): () => void

As on, but stops listening after the first call. Returns a function that stops listening early.

destroy

destroy(): void

Removes the tray's iframe and every listener. Calls still waiting reject with The embed was destroyed.

Room Methods

A Room lets players on different sites and platforms roll together: your site, the Dice+ website, and Owlbear Rodeo tables whose GM opened them to other platforms. Everyone sees everyone's dice with the same physics.

Joining, creating and leaving reload the tray's iframe (never your page), and ready fires again when it's back. Calls in flight during the reload reject with The embed reloaded. The tray remembers its Room on your site for a few hours, and every tab of your site follows the same Room. Room changes arrive as room-state.

joinRoom

joinRoom(roomCode: string, passcode: string | null): Promise<void>

Joins a Room. A wrong Passcode shows up in room-state as status: 'closed' with closeReason: 'wrongPasscode'.

Name Type Description
roomCode string The Room Code; case, spaces and the dash are ignored
passcode string | null The six-digit Passcode, or null if the Room has none

Rejects with That is not a Dice+ Room Code. or A Passcode is six digits.

await tray.joinRoom('k7m2 qx9p', '483920');

createRoom

createRoom(): Promise<void>

Creates a Room with this browser as its Host and joins it. The new Room Code and Passcode arrive in room-state. Called while already Host of a Room, it moves to a new code and passcode, leaving everyone else in the old Room.

leaveRoom

leaveRoom(): Promise<void>

Leaves the Room and goes back to rolling alone.

setPasscode

setPasscode(passcode: string | null): Promise<void>

Host only. Players already in the Room stay.

Name Type Description
passcode string | null A new six-digit Passcode, or null to let anyone with the Room Code in

Rejects with Only the Host can change the Passcode. or A Passcode is six digits.

setGm

setGm(playerId: string, gm: boolean): Promise<void>

Host only. Gives or takes the GM Tag, which receives 'dm' and 'gm_only' rolls. The Room ignores it from anyone else.

Name Type Description
playerId string The member's id
gm boolean Whether they have the GM Tag

Rejects with Not in a room. outside a Room.

kick

kick(playerId: string): Promise<void>

Host or GM. Removes a player from the Room. The Room ignores it from anyone else.

Name Type Description
playerId string The member's id

Rejects with Not in a room. outside a Room.

reconnect

reconnect(): Promise<void>

After the connection has given up (status: 'offline'), tries again now. The tray also retries on its own when the player next rolls or focuses the page.

requestLink

requestLink(playerId: string): Promise<void>

In an Owlbear Rodeo table's Room (kind: 'home'), asks one of its players to let this browser roll as them. They have about a minute to choose Allow in Owlbear Rodeo. If they allow it, the tray reloads as that player and room-state.linkedAs is set; otherwise link-refused fires.

Name Type Description
playerId string A player from room-state.linkCandidates
tray.on('room-state', room => {
  if (room.kind === 'home' && !room.linkedAs && !room.asNewPlayer) showPicker(room.linkCandidates);
});

cancelLinkRequest

cancelLinkRequest(): Promise<void>

Stops waiting for an answer to requestLink.

unlink

unlink(guestId: string): Promise<void>

Ends a link. This browser can end its own; the linked player, the Host or a GM can end anyone's.

Name Type Description
guestId string The linked device's id; room-state.you.id for this browser

answerLink

answerLink(guestId: string, allow: boolean): Promise<void>

Answers someone asking to roll as this player: the Dice+ browser extension, or another browser. While asks wait they are listed in room-state.linkAsks; show the first with Allow and Deny. An ask nobody answers lapses as a denial after 60 seconds, so a page that shows nothing simply turns them all down.

Name Type Description
guestId string linkAsks[n].guest.id
allow boolean true lets it roll as this player until this player, the Host or a GM unlinks it
tray.on('room-state', room => {
  const ask = room.linkAsks[0];
  if (ask) showLinkPrompt(`${ask.guest.name} wants to roll as you`, allow => tray.answerLink(ask.guest.id, allow));
});

chooseNewPlayer

chooseNewPlayer(): Promise<void>

Records that this player is new to the table rather than one of its Owlbear Rodeo players, so room-state.asNewPlayer is true and you needn't ask again.

Events

Listen with on and once.

Event Data
ready { playerId: string }
unauthorized UnauthorizedEvent
roll-result { result: DiceRollResult; isOwn: boolean }
roll-error DiceRollError
rolling { rolling: boolean }
dice-availability DiceAvailability
history-changed HistoryEntry[]
room-state RoomState
link-refused LinkRefusedEvent
notice NoticeEvent

ready

tray.on('ready', ({ playerId }) => { … });

The tray is up. Fires again each time the tray reloads (joining, leaving or linking in a Room).

unauthorized

tray.on('unauthorized', ({ reason, message }) => { … });

The tray refused your page and will not work. See UnauthorizedEvent.

roll-result

tray.on('roll-result', ({ result, isOwn }) => { … });

A roll finished. Fires for every roll this player sees: their own and everyone else's in the Room. Each one arrives once its dice have settled on this screen, so a total never shows before the dice land.

Name Type Description
result DiceRollResult The roll and its outcome
isOwn boolean Rolled by this player
tray.on('roll-result', ({ result, isOwn }) => {
  log.add({ who: result.playerName, total: result.result.totalValue, mine: isOwn });
});
{
  "isOwn": true,
  "result": {
    "rollId": "roll_1762891234567_k2x9q7a",
    "playerId": "web-3f1c9a52-7d4e-4b8a-9c21-5e0f6a7b8c9d",
    "playerName": "Ari",
    "rollTarget": "everyone",
    "timestamp": 1762891234567,
    "source": "attack",
    "showResults": true,
    "result": {
      "rollId": "roll_1762891234567_k2x9q7a",
      "diceNotation": "2d20kh1+5",
      "totalValue": 21,
      "rollSummary": "[16] 16 + 5 = 21",
      "groups": [
        {
          "diceType": "d20",
          "total": 16,
          "dice": [
            {
              "diceId": "die-0",
              "rollId": "roll_1762891234567_k2x9q7a",
              "diceType": "d20",
              "value": 16,
              "kept": true,
              "isAdvantage": false,
              "isDisadvantage": false,
              "isNegative": false,
              "diceStyle": "sharp",
              "criticalSuccess": false,
              "criticalFailure": false
            },
            {
              "diceId": "die-1",
              "rollId": "roll_1762891234567_k2x9q7a",
              "diceType": "d20",
              "value": 4,
              "kept": false,
              "isAdvantage": false,
              "isDisadvantage": false,
              "isNegative": false,
              "diceStyle": "sharp",
              "criticalSuccess": false,
              "criticalFailure": false
            }
          ]
        }
      ]
    }
  }
}

roll-error

tray.on('roll-error', ({ rollId, error, warning }) => { … });

Fires for this player's own rolls only. Without warning, the roll failed (for example, invalid notation). With warning: true, the roll went ahead and error names what was ignored. See DiceRollError.

rolling

tray.on('rolling', ({ rolling }) => { … });

true when this player's own roll goes out, false when its dice settle. Useful for a "Rolling…" state, especially with a headless tray.

dice-availability

tray.on('dice-availability', counts => { … });

How many dice of each type the player's bag holds. Fires after ready and whenever the bag changes. Use it to disable buttons for die types the player can't roll. See DiceAvailability.

tray.on('dice-availability', counts => {
  for (const type of ['d4', 'd6', 'd8', 'd10', 'd12', 'd20'] as const) {
    buttons[type].disabled = (counts[type]?.active ?? 0) === 0;
  }
});
{
  "d4": { "active": 1, "jailed": 0 },
  "d6": { "active": 6, "jailed": 0 },
  "d8": { "active": 1, "jailed": 0 },
  "d10": { "active": 2, "jailed": 0 },
  "d12": { "active": 1, "jailed": 0 },
  "d20": { "active": 2, "jailed": 1 }
}

history-changed

tray.on('history-changed', entries => { … });

The roll history changed. The data is the full list, newest first. See HistoryEntry.

room-state

tray.on('room-state', room => { … });

Anything about the Room changed: connection status, members, the code, the passcode or the link. See RoomState.

{
  "solo": false,
  "status": "connected",
  "roomCode": "K7M2-QX9P",
  "passcode": "483920",
  "isHost": true,
  "kind": "web",
  "you": { "id": "web-3f1c9a52-7d4e-4b8a-9c21-5e0f6a7b8c9d", "name": "Ari", "color": "#e07a5f", "platform": "web", "host": true, "gm": false },
  "members": [
    { "id": "web-3f1c9a52-7d4e-4b8a-9c21-5e0f6a7b8c9d", "name": "Ari", "color": "#e07a5f", "platform": "web", "host": true, "gm": false },
    { "id": "web-8b2d4f60-1a3c-4e5f-9b7d-2c4e6f8a0b1c", "name": "Bryn", "color": "#3d5a80", "platform": "web", "host": false, "gm": false }
  ],
  "linkCandidates": [],
  "asNewPlayer": false,
  "linkAsks": []
}

link-refused

tray.on('link-refused', ({ player, reason }) => { … });

A requestLink didn't go through. See LinkRefusedEvent.

notice

tray.on('notice', ({ message, variant }) => { … });

A message the tray would otherwise show as a toast, such as "You were removed from the room." Show it or ignore it. See NoticeEvent.

Headless mode

const tray = new DicePlusTray({ apiKey, container, settings: { headless: true } });

For sites that show dice only on the VTT. A headless tray:

Pair it with rolling to show that a roll is in progress. Switch with setSettings({ headless }) between rolls; switching mid-roll rejects.

Dice look

The player's own dice bag always wins. Your look applies only to die types the player has no dice for, which is every type until they save a bag on your site. For a die type the bag doesn't cover, the first of these that applies is used:

  1. the roll's dice.byType[type]
  2. the roll's dice.default
  3. the site's dice.byType[type] (constructor or setSiteDice)
  4. the site's dice.default
  5. the Dice+ standard die
tray.setSiteDice({
  default: { color: '#2a2a2a', numberColor: '#d4af37', font: 'norse' },
  byType: { d20: { color: '#7b1e1e', metalness: 0.4 } },
});

tray.roll({ diceNotation: '8d6', dice: { default: { color: '#ff6b00', numberColor: '#000000' } } });

Named dice. Notation can call a die by name, as in 1d12{Hope} + 1d12{Fear}, and byName gives those dice their look. A player whose bag has a die of that name rolls their own; everyone else gets yours. The roll's byName beats the site's for the same name. Dice the notation doesn't name never use these looks.

tray.roll({
  diceNotation: '1d12{Hope} + 1d12{Fear}',
  dice: { byName: { Hope: { color: '#d4a017' }, Fear: { color: '#5b2a86', numberColor: '#f4f1fa' } } },
});

Each result's group names its die in diceModel, so you can tell Hope from Fear.

Only the free fields of the standard material are used (StandardDiceStyle). Anything else is dropped and reported as a roll-error warning; the roll goes ahead.

DicePlusBag

The player's own dice bag: their dice and collections, stats and roll log, cloud backup, and Patreon sign-in. It fills its container; show it as a dialog, a side panel or inline. The tray picks up changes to the bag straight away.

const bag = new DicePlusBag({ apiKey: 'dp_your_key', container: dialog.querySelector('.body')! });
bag.on('close-requested', () => dialog.close());

Bag Constructor

new DicePlusBag(options: DicePlusBagOptions)
Name Type Description
apiKey string Your Access Key
container HTMLElement The element the bag fills; around 360×520 at the smallest, scrolling inside
theme EmbedTheme Optional. Your site's colors for the embed's UI. See Colors
baseUrl string Optional. Where the embeds are served from; only for testing a development build

Bag Properties

Name Type Description
ready Promise<{ playerId: string }> As on DicePlusTray

Bag Methods

premium

premium(): PremiumState | undefined

Returns the last premium-changed value, or undefined before it has fired.

setTheme, on, once and destroy

As on DicePlusTray: setTheme replaces the bag's colors, and on takes the bag's events.

Bag Events

Event Data
ready { playerId: string }, as on the tray
unauthorized UnauthorizedEvent, as on the tray
premium-changed PremiumState
close-requested {}

premium-changed

bag.on('premium-changed', ({ signedIn, isPremium }) => { … });

Fires after ready and whenever sign-in or membership changes. See PremiumState.

close-requested

bag.on('close-requested', () => { … });

The player pressed the bag's close button. Hide the bag if you show it as a dialog.

Colors

Both embeds take a few colors so they match your site. Most of the tray is see-through dice, so theme mostly matters for the bag. Dice keep their own look: the player's own dice, and yours from dice.

const theme = { mode: 'light', primary: '#5a2a1a', background: '#f5ecd7' } as const;
const bag = new DicePlusBag({ apiKey: 'dp_your_key', container, theme });
const tray = new DicePlusTray({ apiKey: 'dp_your_key', container: trayLayer, theme });

// Your site switched to dark
bag.setTheme({ mode: 'dark', primary: '#d8a47f', background: '#1c1612' });

Anything you leave out is worked out from what you give. Without mode, a light background means a light theme. Without surface, cards and menus sit a step off background. Without text, text is near-black or white to suit the mode. Button text on primary is black or white, whichever reads better. A field that isn't valid is ignored with a console warning, and that color falls back as if you had left it out. Readability is up to you: colors you give are used as they are.

rooms

Helpers that match the Dice+ Room Code and Passcode formats.

import { rooms } from '@dice-plus/sdk';

const id = rooms.normalizeRoomCode(input.value);   // 'k7m2 qx9p' → 'K7M2QX9P'
if (id) await tray.joinRoom(id, passcode);
Name Type Description
normalizeRoomCode (text: string) => string | null The Room id from what a player typed (case, spaces and the dash ignored), or null if it isn't a Room Code
formatRoomCode (id: string) => string 'K7M2QX9P' → 'K7M2-QX9P'
isPasscode (text: string) => boolean Whether text is six digits
linkAskMs number How long a requestLink waits for an answer (60000)
linkDenials number Refusals after which a player can't be asked again on this connection (3)

Types

TraySettings

Name Type Description
settleTime 'very-fast' | 'fast' | 'normal' | 'slow' | 'very-slow' How long dice tumble. Default 'normal'
clearDelaySeconds number Seconds the dice stay after a roll, 1–10. Default 3
sound boolean Dice sounds. Default true
settleFlash boolean Flash a die when it settles. Default true
resultAccent boolean Tint dice that rolled their minimum or maximum. Default true
critHighlight { enabled: boolean; dice?: CritDice } Mark the min and max of these dice critical without cs/cf. Default off
critEffects { enabled: boolean; dice?: CritDice; theme?: CritTheme } Effects for critical results. Default off
performance 'normal' | 'default-dice-only' | 'results-only' 'results-only' skips drawing other players' dice. Default 'normal'
graphicsQuality 'auto' | 'high' | 'balanced' | 'low' Default 'auto'
headless boolean See Headless mode. Default false

Every field is optional. The tray never uses settings a player saved anywhere else.

CritDice is 'all' or an array of 'd2', 'd3', 'd4', 'd6', 'd8', 'd10', 'd12', 'd20', 'd100'. CritTheme is 'classic', 'divine', 'arcane' or 'minimal'.

EmbedTheme

Name Type Description
mode 'light' | 'dark' Optional. The base theme. Left out, it follows background, else dark
primary string Optional. '#rrggbb': buttons, the active tab, selected chips and links
background string Optional. '#rrggbb': the panel behind everything
surface string Optional. '#rrggbb': cards, menus and dialogs
text string Optional. '#rrggbb': text; muted text is a faded version

TrayIdentity

Name Type Description
name string Up to 40 characters
color string '#rrggbb'

TrayRollRequest

Name Type Description
diceNotation string Dice notation, e.g. '4d6dl1', '2d20kh1+5', '4dF'
rollTarget RollTarget Optional. Who sees the roll. Default 'everyone'
rollId string Optional. Your own id, echoed on the result; one is generated if left out
source string Optional. Echoed on the result, e.g. 'strength-check'. Default 'sdk'
dice SiteDice Optional. Look for this roll's dice where the player has none

RollTarget

Value Who sees the dice and result
'everyone' The whole Room
'self' This player only; nothing leaves the browser
'dm' This player and the Room's GMs
'gm_only' The Room's GMs only

SiteDice

Name Type Description
default StandardDiceStyle Optional. For every die type
byType Partial<Record<DieType, StandardDiceStyle>> Optional. Per die type; beats default
byName Record<string, StandardDiceStyle> Optional. Dice the notation calls by name, as Hope in '1d12{Hope}'. Up to 20 names of up to 40 characters

DieType is 'd1', 'd2', 'd3', 'd4', 'd6', 'd8', 'd10', 'd12', 'd20', 'd100' or 'dF'. A d100 is thrown as two d10s and a Fudge die as a d6, so they take the d10 and d6 styles.

StandardDiceStyle

The free fields of the standard material. Every field is optional; anything left out keeps the default.

Name Type Description
color string Body color, '#rrggbb'
numberColor string Number color, '#rrggbb'
font 'standard' | 'norse' | 'aelfa' Number font
shape string A free shape for the die type, e.g. 'sharp', 'rounded'
roughness number 0–1
metalness number 0–1
opacity number 0–1
sheen number 0–1, glossy clear coat
numberDepth number 0–1, how deep the numbers are engraved

DiceRollResult

The same shape Owlbear Rodeo extensions receive on {source}/roll-result.

Name Type Description
rollId string The roll's id
playerId string Who rolled
playerName string Their display name
rollTarget RollTarget Who sees it
timestamp number When it was rolled, ms since the epoch
source string The request's source
showResults boolean Other players' Dice+ list the roll
result.rollId string The roll's id
result.diceNotation string The notation rolled
result.totalValue number The final total
result.rollSummary string e.g. "[13] 13 + 3 = 16"
result.groups RolledGroup[] One per dice term, in notation order
result.tally Record<string, number> Optional. Text Faces rolled, e.g. { "Skull": 2 }

RolledGroup

Name Type Description
diceType string 'd20', 'd6', 'd100', 'dF', …
dice RolledDie[] The group's dice
total number Kept dice, or successes for a pool
description string Optional. The label after #, e.g. 'Fire' in '3d6 # Fire'
diceModel string Optional. The bag die named in {}
tally Record<string, number> Optional. Text Faces among the kept dice
isNegative boolean Optional. Subtracted, as in '1d20 - 1d4'
isPool boolean Optional. A dice pool
isCondensed boolean Optional. A very large group (70+ dice) carrying totals only
condensedCount number Optional. How many dice a condensed group had

RolledDie

Name Type Description
diceId string The die's id
rollId string The roll's id
diceType string The die type
value number What it counts for, after face values, Fudge, min/max and sign
kept boolean Counted in the total (not dropped by kh/kl/dh/dl)
isAdvantage boolean An advantage die
isDisadvantage boolean A disadvantage die
faces number[] Optional. The physical face(s) it landed on; a compounding chain lists each
diceStyle string Optional. The die's shape
customName string Optional. The bag die's name
label string Optional. A Text Face's text; value then counts for nothing
wasExploded, fromExplosion, wasRerolled, imploded, groupDropped, isNegative boolean Optional. How rules touched the die
wasMinimum, wasMaximum, criticalSuccess, criticalFailure boolean Optional. Min, max and critical marks
success, failure boolean Optional. Pools
isFudge boolean Optional. A Fudge die
tablePartValues number[] Optional. Table rolls (T notation), highest place first

DiceRollError

Name Type Description
rollId string The roll's id
error string What went wrong, or what was ignored
notation string The notation requested
warning true Optional. The roll still went ahead; part of the request was ignored

DiceAvailability

Partial<Record<DieType, { active: number; jailed: number }>>

Name Type Description
[dieType].active number Dice of this type in the player's rotation
[dieType].jailed number Dice of this type set aside

HistoryEntry

Name Type Description
id string The roll's id
playerId string Who rolled
playerName string Their display name
rollTarget RollTarget Who saw it
timestamp number When it was rolled
result DiceRollResult['result'] The outcome, as in DiceRollResult

RoomState

Name Type Description
solo boolean Not in a Room
status 'connecting' | 'connected' | 'reconnecting' | 'offline' | 'closed' 'offline': gave up reconnecting for now; see reconnect
isHost boolean This browser created the Room
members RoomMemberState[] Everyone in the Room
linkCandidates RoomMemberState[] In an Owlbear Rodeo table's Room: players this browser may ask to roll as
asNewPlayer boolean Joined an Owlbear Rodeo table's Room as a new player
linkAsks LinkAskState[] Others asking to roll as this player, oldest first; answer with answerLink
roomCode string Optional. As players type it, e.g. 'K7M2-QX9P'
passcode string | null Optional. Host: the Room's Passcode (null when off). Others: the one they joined with
kind 'web' | 'home' Optional. 'home': an Owlbear Rodeo table's Room
you RoomMemberState Optional. This browser
closeReason string Optional. Why the Room closed: 'kicked', 'wrongPasscode', 'tooManyAttempts', 'full', 'outdated', 'replaced', …
passcodeChanged boolean Optional. The Passcode was refused after this browser had been let in: the Host changed it
linkedAs { playerId: string; name: string; color: string } Optional. This browser rolls as another player

LinkAskState

Name Type Description
guest { id: string; name: string; color: string } Who is asking
platform string 'extension': the Dice+ browser extension. 'web': another browser
at number When it arrived (ms since the epoch); it lapses 60 seconds later

RoomMemberState

Name Type Description
id string The member's id
name string Display name
color string '#rrggbb'
platform string 'web', 'obr', 'extension' (the Dice+ browser extension, always linked to a player), …
host boolean Created the Room
gm boolean Has the GM Tag
linkedTo string Optional. A device rolling as another player: that player's id

UnauthorizedEvent

Name Type Description
reason 'missing' | 'unknown' | 'revoked' | 'origin' | 'protocol' origin: this page's origin isn't on the key. protocol: this SDK version is no longer supported
message string A sentence to show a developer

LinkRefusedEvent

Name Type Description
player string The player who was asked
reason string One of the values below
Reason Meaning
'denied' The player said no
'timeout' The player didn't answer
'offline' The player isn't in the Room now
'busy' A request is already waiting
'cooldown' Asked the same player again too soon (wait about 10 s)
'blocked' That player said no rooms.linkDenials times
'unavailable' The Room isn't an Owlbear Rodeo table's

NoticeEvent

Name Type Description
message string The message
variant 'DEFAULT' | 'INFO' | 'ERROR' | 'SUCCESS' | 'WARNING' Its kind

PremiumState

Name Type Description
signedIn boolean Signed in with Patreon in this site's Dice+
isPremium boolean A paying patron: premium materials, shapes, fonts and unlimited dice