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 key is tied to the origins you list, such as
https://sheets.example.com. localhost, any subdomain of it (such asapp.localhost) and127.0.0.1work on any port with any valid key, for development.- The key isn't a secret. The embeds check it together with the origin the browser reports for your page, so a copied key doesn't work on another site.
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:
- Pages that use the embeds show "Dice powered by Dice+" with links to
https://dice-plus.missinglinkdev.comandhttps://patreon.com/MissingLinkDev, where players can see it. - The dice bag's footer stays visible when you show the bag.
- Dice+ dice, materials and models aren't resold, and Premium features aren't put behind your own paywall.
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
| 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:
- runs the physics in real time with no canvas, so everyone else in the Room sees the dice tumble and land as usual;
- draws nothing, plays no sound and needs no WebGL, so it loads no dice models or textures;
- doesn't draw other players' rolls;
- holds every
roll-resultabout 1.5 seconds after its dice settle, roughly when they land on the screens replaying them.
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:
- the roll's
dice.byType[type] - the roll's
dice.default - the site's
dice.byType[type](constructor orsetSiteDice) - the site's
dice.default - 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());
- Fairness test. With a tray on the same page, the bag offers Test fairness for each die, and its throws roll in your tray.
- Storage is per site. Browsers partition storage by site, so the player's bag and sign-in on your site are separate from the Dice+ website. Signing in with Patreon brings their cloud bag along.
- Sign-in. Patreon sign-in opens a popup from inside the bag. Your page can't start sign-in or sign out.
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 |