Pixels App Guide - GameWithPixels/PixelsApp GitHub Wiki

Table Of Contents

Get Started
Connect To Your Dice
Customize Your Dice
    Home Screen
    Profiles Screen
        Edit A Profile
        Edit A Rule
        Activate A Profile
    Animations Screen
        Previewing On Die
        Animation Types
            Simple Flashes
            Colorful Rainbow
            Gradient
            Color Design
            Gradient With Greyscale Design
Menu
    Designs
    Audio Clips
    Import JSON Animation
    Export Logs
    Restore Default Settings
Thesaurus

Get Started

The official Pixels app that lets you connect to your Pixels electronic dice.

You may download the app for iPhone on the Apple App Store and the .apk file for Android phones from the GitHub's releases page (eventually we will publish it on the Play Store).

The app has a toolbar on the bottom that gives you access to the most used features. Some extra functionality is available from the menu button located on the top left corner.

Home screen with menu button and toolbar pointed out by orange arrows.

Connect To Your Dice

Go to the Dice Bag screen (right most icon in the toolbar). Be sure to have Bluetooth turned on and give permission to the app to use it. This can be found in your device settings.

Note: on Android it will ask permission to access your location, this is a required permission to scan for Bluetooth devices. The Pixels app is not using your location in any way.

Tap the "+" button located on the bottom right of the screen. The app will use Bluetooth to scan and find any dice that are turned on and within range. The available dice not already paired with the app will appear on this screen.

Select one or more dice that you want to connect to and tap on "Pair Selected Dice". You do not need to do this every time your run the app, once a die is added to your dice bag the app will connect to it automatically.

Scanning screen showing a list of 3 dice with the first one selected and a button at the bottom to pair the selected dice.

If no die appears, please check the following:

  • Bluetooth is turned on in your phone settings
  • You have given permission to the app to use Bluetooth on iOS and to access the device's location on Android
  • Die is charged and out of the case (rolling it should light it up)
  • Die is nearby your phone

Customize Your Dice

The app comes with several predefined animations. You may start to use them right away or create new ones.

Home Screen

To activate an existing profile on your dice, go to the Home screen and tap on a profile. Then select the dice for which you want to activate the profile.

The Home screen will also let you activate presets, which are described later in the documentation.

Profiles Screen

From this screen you can add, edit, and delete profiles.

Profiles screen showing a list of 3 different profiles with their name, description and a 3D rendering of a die playing the animation.

Tap on a profile to edit it, or on the "+" button to create a new one.

To reveal more options such as duplicate or delete a profile, tap on the expand button located on the right side of the profile's name.

Expanded profile showing more options, with the expand button pointed out by orange arrows

Edit A Profile

A profile defines when and how a dice will light up. It is made of a series of rules. Each rule has a condition (the "When" block) and a series of actions (the "Then" and "And" blocks).

Profile editing screen showing an activate button and a list of rules with a condition and one or more actions.

Anytime something relevant happens (new orientation detected, the die is picked up, etc.) the die will scan through its list of rules and check if any apply. If it finds a rule with a matching condition, the die will then trigger the corresponding action (or list of actions). Please note that if multiple rules have their condition met by the same event (example: roll is equal to 20), the die will only activate the action(s) for the highest rule in the list.

The flowchart below shows the steps to get to the first rule with a condition that matches roll is equal to 15.

Event Flowchart

Note: the last condition is "roll is less or equal to 20" but as the condition above is "roll is greater than 1" it will never get triggered for anything greater than 1.

Tap on the profile's name or description to edit them.

Tap on the "+" button to create a new rule.

To reveal more options such as move up or down, duplicate or delete a rule, tap on the expand button located on the right side of the rule item.

To save your changes, tap on the check mark at the top right corner of the screen.

Save button made of a check mark in a round shape.

To go back to the Profiles screen without saving, tap on the arrow at the top left corner of the screen.

Edit A Rule

A condition describing when to activate the associated series of actions. For example, the condition can be "die is picked up" or "die roll is less than 3".

Edit Rule screen showing a condition and 2 actions.

Each action will either play an animation or an audio clip. Optionally for animations, you may specify on which face it should play.

To save your changes, tap on the check mark at the top right corner of the screen.

To go back to the Profile screen without saving, tap on the arrow at the top left corner of the screen.

Activate A Profile

To activate a profile on a die, go to the home screen, tap on a profile and select a die.

Note: after modifying a profile on the app, you will need to re-activate it on your dice to synchronize the changes.

Animations Screen

This feature was previously named Pattern, screenshots haven't been updated.

From this screen you can add, edit, and delete animations.

An animation defines how your dice LEDs will light up. There are several types of animations, each type having its own set of parameters. You can have the die light up with any combination of colors.

Animations screen showing a 2 columns list of animations with their names and a 3D rendering of a die playing the animation.

Tap on an animation to edit it, or on the "+" button to create a new one.

To reveal more options such as duplicate or delete an animation, tap on the expand button located on the right side of the animation's name.

Previewing On Die

Try out the animation on your die by tapping the Play button and selecting your die.

Preview button made of a triangle play shape and a faint die outline.

Animation Types

Simple Flashes

Available options:

  • Duration: number of seconds the effect will play
  • Face Mask: the numbers that will light up
  • Color: color of the flashes
  • Override color based on face: the color will depend on the face that is up
  • Repeat Count: number of times to make it flash
  • Fading Sharpness: low value will make the LEDs transition quickly from off to lit up, high value will make them light up slowly

Colorful Rainbow

Available options:

  • Duration: number of seconds the effect will play
  • Face Mask: the numbers that will light up
  • Repeat Count: number of rainbow cycles
  • Fading Sharpness: low value will make the LEDs transition quickly from off to lit up, high value will make them light up slowly
  • Traveling order: makes the rainbow to start with a different color on each LED

Gradient

Available options:

  • Duration: number of seconds the effect will play
  • Face Mask: the numbers that will light up
  • Gradient: list of custom selected colors that will be played one after another

Color Design

This feature was previously named Color LED Pattern, screenshots haven't been updated.

Available options:

  • Duration: number of seconds the effect will play
  • Color Design: visual description of how to light up each individual LED over time (each line of the image shows the color of a LED over time)
  • Traveling Order: makes the design to start at a different position on each LED

Gradient With Greyscale Design

This feature was previously named Gradient LED Pattern, screenshots haven't been updated.

Available options:

  • Duration: number of seconds the effect will play
  • Greyscale Design: visual description of the brightness for each individual LED over time (each line of the image shows the brightness of a LED over time)
  • Gradient: list of custom selected colors that will be played one after another
  • Override color based on face: the color will depend on the face that is up

Menu

Menu showing a list of options such as Designs and Audio Clips. The app version is displayed at the bottom.

The menu gives access to a few more options. The app version is also shown at the bottom right corner.

Designs

From this screen you can add, edit, and delete color designs.

You can import color designs from an image, with each line of the image showing how the corresponding LED will light up over time.

An image should be designed assuming the die has its higher face number up. In that case the bottom line of the image is for face 1, second line from bottom for face 2, etc.

Here is an example file for D20 color design:

Colorful image of design with 20 lines and 400 rows.

Note that for a D10, face 0 should be treated has a 10.

The image needs to be in PNG format, have no more than 20 pixels in height and 2000 pixels in width.

Audio Clips

From this screen you can add, delete and listen to Audio Clips.

You can import your own files, supported format are Wave, Mp3 and Ogg Vorbis.

Note: to hear audio be sure that your phone is not on silent mode.

Import JSON Animation

This lets you import your own animation(s) from a JSON file. This is only for people who are familiar with both the JSON format and the data structure of animations.

Export Logs

Use this option whenever you encounter a problem that you want to report to the developers. It will ask you to save a zip file with all the recent logs from the app. Please attached this zip file to your bug report.

Restore Default Settings

Restore the app to its original settings. All modifications to profiles and animations will be lost!

Thesaurus

  • Dice Bag:
    All dice paired with the application.

    • Animation:
      Description of how the dice LED should light up.

      • Gradient:
        Custom list of colors that will be played one after the other.

      • Color and Greyscale Designs: Images used to describe how each LED will light up over time. Each line represents a LED.

  • Profile:
    A list of rules.

    • Rule:
      A condition with a list of actions. The condition describes for which event the actions should be triggered.

    • Action:
      An animation or an audio clip to play.

    • Audio clip:
      A sound played by the app.

  • Preset:
    A list of associations between dice and profiles.