Unofficial Pixels integration for Demiplane Nexus

This project aims to integrate the Pixels electronic dice (https://www.gamewithpixels.com/) with Demiplanes character sheets for TTRPGs.

Demiplane offers character sheets for a range of TTRPG system, including the option to roll simulated dice on those character sheets.

Pixels electronic dice are physical dice that can (among other things) establish a Bluetooth LE connection to an application running on a computer, tablet, or smartphone. When that connection is established, they can send roll results to whatever application they are connected to.

By combining the two projects, we can have digital character sheets for a number of TTRPG systems, roll physical dice for whatever roll is happening and the character sheet will handle any calculations required for the roll.

Requirements

This integration has a few requirements to work.

Supported browsers

The following browsers are supported by the integration:

Note

The integration will not work on Firefox or Safari, since neither of those support the experimental Web Bluetooth API.

This isn’t likely to change any time soon. The specification draft is handled by the W3C Web Bluetooth Community Group and a number of concerns have been raised about it over the years. Specifically, Mozilla has decided not to implement Web Bluetooth in Firefox (see a discussion about the issue here, a statement about their position here) and Apple has decided against implementing in WebKit (which powers Safari) for security reasons (see a discussion about it here their stance on Anti-Fingerprinting).

Supported operating system

The integration has been tested on the following operating systems:

macOS
Ubuntu Linux
Windows
Android (with the Kiwi Browser on a tablet, in Desktop mode)

Warning

The integration does not work on iOS at this time. This is due to Apple (currently) requiring that all browsers use the WebKit engine, which does not support Web Bluetooth.

This may change in the future, but right now that’s the way things are.

An account with Demiplane

To use Demiplane Nexus, you must register for an account with them. Both free and paid accounts are supported by this integration.

Pixels dice

To use the integration, you should have at least one Pixels die. Pixels dice are available as:

d4
d6 (both with number and pipped)
d8
d10
d00 (also sometimes called D%s or percentile dice)
d12
d20
Fudge Dice (sometimes called dF for short)

Tampermonkey (or another browser plugin which supports userscripts)

The integration is built as a so called userscript.

This means that you need a browser extension such as Tampermonkey, which will inject the userscript into a suitable website (in this case: a character sheet on Demiplane Nexus).

Supported game systems on Demiplane

The integration has built to be usable for any game system offered by Demiplane. It has been successfully tested with the following systems:

Alien RPG
Avatar Legends
Daggerheart (including limited critical roll handling)
Pathfinder 2E (including limited critical roll handling)

Hot to use the integration

If you’re new to using this integration, here is some (hopefully) useful information to get you started.

Setup

Open the URL https://github.com/blalasaadri/pixels-demiplane-nexus-integration/raw/main/userscripts/index.prod.user.js in a supported browser with a plugin such as Tampermonkey installed. You will be prompted to install the userscript in Tampermonkey.

Important

If you had a character sheet open on Demiplane, you will have to reload that page after installing the userscript.

Bluetooth in your browser

Depending on your operating system, you may have to enable some functions in your browser before you can start using the integration.

Enabling Bluetooth on Linux

On Linux, you will have to open the supported browser you want to use and go to chrome://flags/#enable-web-bluetooth. Here make sure, that the value is set to Enabled.

Automatic reconnects (all desktop operating systems)

The integration supports reconnecting to dice when a character sheet is reloaded (within reason).

To allow for this, go to chrome://flags/#enable-web-bluetooth-new-permissions-backend and ensure that the value is set to Enabled.

Note	This does not work in the Kiwi Browser for Android, it seems that the configuration flag does not exist there. Other mobile browsers that support userscripts may work.

If this is enabled, when a character sheet is loaded the integration will try to find any dice that were connected the previous time it was used.

Using the integration on Demiplane Nexus

Once Bluetooth is set up and the integration is installed, open the character sheet you want to use the integration with on Demiplane Nexus.

In many cases, a menu entry called Pixels Dice [caret down] should appear at in the top bar.

Example of the Pixels Dice menu for a Pathfinder 2E character

Example of the Pixels Dice menu for an Avatar Legends character

If this entry does not appear, you may have to reload the character sheet.

The Pixels Menu before anything has been set up

Connecting Pixels dice

In the Pixels Menu, click on the button Connect Pixels die in the Dice Settings area to start connecting your pixels dice.

The Dice Settings menu

A window will open which will scan for and then show all Pixels dice it can find.

Tip

If your die is not showing up in this window, please ensure the following:

Your Pixels die is either not in the charger or it is in the charger but the lid is open.
Your Pixels die is active (e.g. the lights have been on recently). If you are unsure, move the die around a bit.
Your Pixels die is charged. If the battery is empty, it won’t work. That’s what the charger is for. 😛
Your Pixels die is not close to a magnet. Magnets are used to put Pixels dice to sleep (there is one in the lid of the charger), and if they’re asleep they won’t show up here.

Once you have connected (at least) one die, a few things in the Pixels Menu will change.

Example of the Pixels Menu, once a die with the name "My Pixels Die" has been connected

Under Dice Settings, the checkbox for enable for character is automatically enabled. (See Enabling and disabling the integration for specific characters for more about this.)
The icons of the type of dice you have connected will switch from a white logo to a rainbow logo. (See Enabling and disabling the integration for certain dice sizes for more about this.)
Under the icon for the die type you just connected, it will list the name of the connected die. That way you can always see, which dice are currently connected.

Enabling and disabling the integration or parts of it

In the following two sections, options for enabling and disabling either the complete integration or parts of it will be discussed.

Enabled in this context means, that the integration will expect rolls (either all rolls or those of a certain die size) to be made with Pixels dice.

Disabled means the opposite, so rolls (either all rolls or those of a certain die size) will be made by the Demiplane virtual dice.

Enabling and disabling the integration for specific characters

Since Demiplane Nexus supports a number of different game systems that use a variety of dice, it may not make sense to enable the integration for every character you have.

For this reason, there is the enable for character checkbox in the Dice Settings area of the Pixels Menu.

The Dice Settings menu with "enabled for character" active

The checkbox will automatically be enabled for the current character once you connect a die while on the character sheet. You can however enable or disable it manually at any time.

Enabling and disabling the integration for certain dice sizes

In addition to enabling and disabling the whole integration, you can also enable or disable certain die types. When both the integration and a certain die type are enabled, the integration will expect all rolls of that die type to be made with Pixels dice.

Whether a die type is currently enabled or disabled can be seen with by the icon used.

Die type is inactive	Die type is active

Whenever you connect a die, that die type will automatically be enabled. By clicking on the icon (which is on a button), you can manually enable or disable the die type in question.

Example 1. Example of having certain die types enabled

For this example, say you have enabled d20s and connected at least one d20 Pixel.

You then are required to make a roll of 1d20 + 1d4 + 2.

The pixels integration will ask you to roll the connected d20 and will roll the d4 with the Demiplane virtual dice. Once both has happened, it will show you the combined result of your roll.

Requested roll notifications

When the integration is waiting for a Pixels roll (in a supported game system), a notification will show up.

The exact design of the notification will depend on the game system, but it will look something like this:

Example of a notification when waiting for 1d20 to be rolled in a Pathfinder 2E game

Note

If you have not made any rolls with this character in this browser yet (or have cleared the data for this website), no popup will show up. This is because to be as consistent as possible with the design of the game, the integration copies and modifies an existing notification. If there is no existing notification to copy, that won’t work.

The integration will still be waiting for the roll, it just has no way of telling you what it is waiting for.

It is therefore recommended, that if you have such a character, you roll any selection of dice before enabling the integration.

Once the roll has been made, the roll request notification will be replaced with the regular Demiplane Nexus roll information notification.

Testing the integration

For most users, the above explanation should be everything they need to use the integration.

The following is for those of you, who want to test the integration, possibly without having all necessary Pixels dice at hand.

Chrome DevTools

The integration comes with a number of commands available in the browsers DevTools. To use them, open the DevTools in the browser tab in which you have your character sheet open.

Then select the tab Console in the DevTools.

Tip	All of the commands provided by the integration start with `pixelsIntegration.` and tab completion is supported.

Debug mode

The integration has a debug mode, which when active will cause a lot of information to be logged to the console. This does not change the behaviour of the integration.

`pixelsIntegration.isDebugModeEnabled()`	Will return `true` if debug mode is enabled and `false` otherwise.
`pixelsIntegration.enableDebugMode()`	Will switch the integration’s debug on and then return `true`.
`pixelsIntegration.disableDebugMode()`	Will switch the integration’s debug off and then return `false`.
`pixelsIntegration.toggleDebugMode()`	Will switch the integration’s debug mode on or off. Will return `true` if the debugging mode has been switched on, and `false` if it has been switched off.

Connecting a Pixels die

You can trigger the connection to a Pixels die via a command. The result will be the same as when using the button in the Pixels Menu.

pixelsIntegration.connectToPixelsDie()

Start the connection process of a Pixels die.

Enabling and disabling things

For a character

The integration can be enabled and disabled via console commands. This does the same as explained in Enabling and disabling the integration for specific characters.

You have the following related commands available to you in the browser console:

Enabling the integration per character sheet

`pixelsIntegration.isEnabledForCharacter(<characterId>)`	Will return `true` if the integration is enabled or `false` if it isn’t.
`pixelsIntegration.enableForCharacter(<characterId>)`	Will enable the integration for the provided character. Always returns `true`.
`pixelsIntegration.disableForCharacter(<characterId>)`	Will disable the integration for the provided character. Always returns `false`.
`pixelsIntegration.toggleEnabledForCharacter(<characterId>)`	Will switch the integration on or off. Returns `true` if the integration has been switched on, and `false` if it has been switched off.

The <characterId> parameter is an optional string for all of these functions. It refers to the last part of the URL, e.g. 1234abcd-56ef-01ab-23cd-456789efabcde. If not provided by the user, the currently opened character sheet will be used.

Examples of enabling and disabling the integration

// Enable the integration for the current character
pixelsIntegration.enableForCharacter()
// Output
true

// Enable the integration for a specific character
pixelsIntegration.enableForCharacter('1234abcd-56ef-01ab-23cd-456789efabcde');
// Output
true

// Check whether the integration is active for the current character
pixelsIntegration.isEnabledForCharacter()
// Output
true

// Toggle whether the integration is enabled for a specific character
pixelsIntegration.toggleEnabledForCharacter('1234abcd-56ef-01ab-23cd-456789efabcde');
// Output
false

// Check whether the integration is active for a specific character
pixelsIntegration.isEnabledForCharacter('1234abcd-56ef-01ab-23cd-456789efabcde')
// Output
false

Per die type

The integration can be enabled and disabled for specific die types, as explained in Enabling and disabling the integration for certain dice sizes.

Note	Disabling the integration per character always has priority over enabling it per die type. So the integration may be enabled for certain die types but will not wait for Pixels to be rolled, if the integration is disabled for a character.

You have the following related commands available to you in the browser console:

Enabling the integration per character sheet

`pixelsIntegration.isEnabledForDieType(<dieType>)`	Will return `true` if the integration is enabled for the give die type or `false` if it isn’t.
`pixelsIntegration.enableForDieType(<dieType>)`	Will enable the integration for the provided die type. Always returns `true`.
`pixelsIntegration.disableForDieType(<dieType>)`	Will disable the integration for the provided die type. Always returns `false`.
`pixelsIntegration.toggleForDieType(<dieType>)`	Will switch the integration on or off for the give die type . Returns `true` if the integration has been switched on, and `false` if it has been switched off.

The <dieType> parameter is required, and can be one of the following:

The possible types are:

'd4'`	for d4s
`'d6'` or `'d6pipped'`	for d6s (both enable both numbered and pipped d6s)
`'d8'`	for d8s
`'d10'`	for d10s
`'d00'`	for d00s
`'d20'`	for d20s
`'dF'` or `'d6fudge'`	for fudge dice

Examples for enabling and disabling the integration for given dice

// Check, whether the integration is enabled for d20s
pixelsIntegration.isEnabledForDieType('d20')
// Output
false

// Enable the integration for d20s
pixelsIntegration.enableForDieType('d20')
// Output
true

// Check, whether the integration is enabled for fudge dice
pixelsIntegration.isEnabledForDieType('dF')
// Output
false

// Try to disable the integration for fudge dice (even though it already is)
pixelsIntegration.disableForDieType('dF')
// Output
false

// Toggle the integration for d6s
pixelsIntegration.toggleForDieType('d6')
// Output
true

Expected rolls

When the pixels integration is active for both a character and a die type, and a roll with that die type is requested by Demiplane Nexus, you can check which rolls are currently expected as follows:

pixelsIntegration.listExpectedRolls()

List the rolls that are currently expected.

Example for displaying requested rolls

// Request the currently requested rolls, after a d4 and a d20 have been requested
pixelsIntegration.listExpectedRolls()
// Output
{
    "d4": 1,
    "d6": 0,
    "d8": 0,
    "d10": 0,
    "d00": 0,
    "d12": 0,
    "d20": 1,
    "dF": 0
}

// After rolling a d20, the output will change
pixelsIntegration.listExpectedRolls()
// Output
{
    "d4": 1,
    "d6": 0,
    "d8": 0,
    "d10": 0,
    "d00": 0,
    "d12": 0,
    "d20": 0,
    "dF": 0
}

Rolling virtual dice

If you don’t (yet) have (enough) Pixels dice but want to test the integration nevertheless, there is a way to roll so called virtual dice instead. These don’t rely on the Demiplane rolling mechanism but instead do the same thing an actual Pixels die would do.

You have the following related commands available to you in the browser console:

`pixelsIntegration.rollVirtualD4(<count>)`	Used to roll a single d4.
`pixelsIntegration.rollVirtualD6(<count>)`	Used to roll a single d6.
`pixelsIntegration.rollVirtualD8(<count>)`	Used to roll a single d8.
`pixelsIntegration.rollVirtualD10(<count>)`	Used to roll a single d10.
`pixelsIntegration.rollVirtualD00(<count>)`	Used to roll a single d00 (percentile die).
`pixelsIntegration.rollVirtualD12(<count>)`	Used to roll a single d12.
`pixelsIntegration.rollVirtualD20(<count>)`	Used to roll a single d20.
`pixelsIntegration.rollVirtualDF(<count>)`	Used to roll a single dF (fudge die).

The <count> parameter is optional and can be used to define the number of dice of that type to be rolled. By default (if no value or a value smaller than 1 is given) a single die is rolled.

Examples for rolling virtual dice

// Roll 1d6
pixelsIntegration.rollVirtualD6()
// Output:
[
    {
        "success": true,
        "diceSize": 6,
        "face": 2,
        "dieType": "d6",
        "dieColorway": "virtual",
        "dieName": "Virtual d6",
        "dieId": -6
    }
]

// Roll 2d20
pixelsIntegration.rollVirtualD20(2)
// Output:
[{
        "success": true,
        "diceSize": 20,
        "face": 4,
        "dieType": "d20",
        "dieColorway": "virtual",
        "dieName": "Virtual d20",
        "dieId": -20
    },
    {
        "success": true,
        "diceSize": 20,
        "face": 2,
        "dieType": "d20",
        "dieColorway": "virtual",
        "dieName": "Virtual d20",
        "dieId": -20
    }
]

Legalese

In the SVG images, the font Barlow by Jeremy Tribby is used. This font is licensed under the Open Font License.

The brands "Demiplane" and "Demiplane Nexus" are trademarks of the Demiplane Corporation.

Pixels electronic dice are produced by Systemic Games, who hold all related rights.

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.husky		.husky
.vscode		.vscode
assets		assets
documentation/images		documentation/images
plugins		plugins
src		src
userscripts		userscripts
webpack		webpack
.gitignore		.gitignore
LICENSE		LICENSE
README.adoc		README.adoc
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Unofficial Pixels integration for Demiplane Nexus

Requirements

Supported browsers

Supported operating system

An account with Demiplane

Pixels dice

Tampermonkey (or another browser plugin which supports userscripts)

Supported game systems on Demiplane

Hot to use the integration

Setup

Bluetooth in your browser

Enabling Bluetooth on Linux

Automatic reconnects (all desktop operating systems)

Using the integration on Demiplane Nexus

Connecting Pixels dice

Enabling and disabling the integration or parts of it

Enabling and disabling the integration for specific characters

Enabling and disabling the integration for certain dice sizes

Requested roll notifications

Testing the integration

Chrome DevTools

Debug mode

Connecting a Pixels die

Enabling and disabling things

For a character

Per die type

Expected rolls

Rolling virtual dice

Legalese

About

Languages

License

blalasaadri/pixels-demiplane-nexus-integration

Folders and files

Latest commit

History

Repository files navigation

Unofficial Pixels integration for Demiplane Nexus

Requirements

Supported browsers

Supported operating system

An account with Demiplane

Pixels dice

Tampermonkey (or another browser plugin which supports userscripts)

Supported game systems on Demiplane

Hot to use the integration

Setup

Bluetooth in your browser

Enabling Bluetooth on Linux

Automatic reconnects (all desktop operating systems)

Using the integration on Demiplane Nexus

Connecting Pixels dice

Enabling and disabling the integration or parts of it

Enabling and disabling the integration for specific characters

Enabling and disabling the integration for certain dice sizes

Requested roll notifications

Testing the integration

Chrome DevTools

Debug mode

Connecting a Pixels die

Enabling and disabling things

For a character

Per die type

Expected rolls

Rolling virtual dice

Legalese

About

Resources

License

Stars

Watchers

Forks

Languages