How to add your own dice to the extension

This guide is written with non-programmers in mind. You can skip some of these steps if you're already familiar with GitHub and Chrome extension development. I encourage you to set everything up yourself, but if you end up creating some cool dice and can't figure out how to do the stuff with the code, let me know and we will figure something out. Please do try to figure it out by yourself first though, I believe in you 💪

1. Clone the repository

Download the code as a .zip file or clone it with git. I recommend the GitHub Desktop client.

2. Install the dependencies

You will need Node.js and NPM (comes bundled with Node.js), as well as Python 2.7.

After installing Node.js and Python, open up a command line and navigate to the folder you cloned the repository into. Then run the command npm install to install everything needed to build the project. It may take a while for the command to finish. It's okay if some warnings appear, as long as there are no errors.

3. Build the extension

You can now try to build the Chrome extension to make sure everything works. Use the command npm run build and wait for it to finish. If no errors show up and it looks something like the screenshot below, but with a lot more green text, then everything worked.

4. Install the extension in Chrome

Go to the url chrome://extensions/ and enable Developer mode in the top right corner. Then click the "Load Unpacked" button in the top left corner and select the build folder inside roll20-fancy-dice. You now have the development version of the extension installed and create a new build of the extension you can click the "Reload extension" button and then refresh Roll20 to use your new version.

4. Add a new dice from a template

Dice are defined in the roll20-fancy-dice/src/shared/custom-dice-types.js file, so if you want to see your dice in the extension you will have to add it here. The existing dice should make it fairly obvious how it should look. The three values you will need to set are:

• name, which is the visible name of the dice in the extension
• key, which is the name the extension will use to recognize the dice. Use something simple, all lowercase without spaces.
• useColor, which decides whether the user's Roll20 color will be applied to the dice. For most dice, this will probably be false. A user's Roll20 dice color tints the texture of a dice based on how light the underlying color is. So white will be the exact user-selected color, while black will just be black. Anything in between will be a darker version of the user's color. So the only time it makes sense setting useColor to true, is with greyscale textures with this in mind.
• You should also set the key of the new dice configuration you just made. This should just be the same as the key field but in uppercase.

That's all the code you will need to write and you're now ready to create the textures for the dice. In the roll20-fancy-dice/assets/custom-dice folder you will find a bunch of folders containing the textures for the various dice. Each custom skin for the dice has a number of sub-folders with the textures for each side of each size of dice. To create a new custom dice skin you will need to create or modify these texture files. I have personally used two different methods for different dice, either with the free 3D software Blender or with a Photoshop-compatible program such as PhotoShop or the free online tool Photopea. Below you will find a quick guide for both of these processes. I have also experimented with other methods such as taking photos of dice or scanning them, but I have so far been unsuccessful with these.

5.a Modify the dice with Blender

Blender is very nice for creating dice textures because we can utilize its shader editor to generate textures that wrap around the entire dice without any seems. This is much more tricky if you use conventional drawing software.

Create a copy of the roll20-fancy-dice/assets/custom-dice/blender folder and name it something like blender-backup. You will need it if you want to create multiple skins, as the process below overwrites the original files.

Now open up the roll20-fancy-dice/dice.blend file. Working with Blender is a complex topic all by itself and I won't pretend that I'm anywhere near being an expert. But you can somewhat easily get started experimenting, even if you don't know Blender that well. I recommend looking up a tutorial or two on the basics of the shader node editor before you dive in.

The way the Blender project is set up is with 3D models directly from Roll20 of all the dice. They each have a small shader assigned that just contains the texture for their number and then another node group with some inputs.

It's inside that Dice node group that the magic happens. All the dice are set up in a similar way to use this, meaning that you only have to make changes to the shader in a single place. This shader group contains a few nodes for blending layers together, as well a bunch of node groups for each of the various textures I have created in the past.

To create your own texture, I recommend just copy-pasting one of the groups that you like, make it a single-user copy (click the "2", see the gif below), connect it to the Emission node and then open it up and begin editing it.

If you like me don't know a lot about shaders then this part will likely be trial and error, but I encourage you to just fiddle around with the sliders and add some new nodes to create interesting combinations.

Once you have a result that you like, you need to bake the shader to the texture. This will overwrite the images in the textures folders, which is why you created a backup earlier. The steps to do this are outlined in the list below as well as in the screenshots under that.

1. Select all 8 dice models.
2. Open Render Properties and click Bake. Wait for a moment while the images bake. The dice will all turn black or something similar, that's because of the blending. Don't worry about it.
3. In the image viewer, click on Image > Save all images.

If everything went well, you should be able to view your textures in the various textures folders inside /roll20-fancy-dice/assets/custom-dice/blender.

5.b Modify the dice with Photoshop

Photoshop (or Photopea in my case) is nice and easy to work with and most people will find it more familiar than Blender's shaders. It does however come with some limitations out of the box. Simpler textures where the art is confined entirely within each side of the dice is nice and easy, but as soon as you want something that wraps around the entire dice without any seams, it becomes much more tricky. Still, I'm confident that it is possible to create some nice textures in this way, especially by someone who actually knows what they're doing.

There is not much to be said about this approach. Create a copy of the roll20-fancy-dice\assets\custom-dice\photoshop folder and give it the same name as you previously put in the key field. In the texture folder for each dice size, you will find a .psd file that you can use as a starting point for your textures. Make sure to save the finished results with the exact same names as the ones already found in the textures folder.

6. Test the extension

Create a new build of the extension, as described in an earlier section. Make sure to reload the extension in your browser and refresh Roll20 as well. You should now be able to select your dice in the extension. Give it a whirl, bask in its glory if everything worked, cry a little before you try to find the problem if it didn't. Please make sure it looks nice on all the different dice, from all sides.

7. Create a thumbnail

Create an appropriate thumbnail for the dice skin and place it inside the folder for the custom dice you created earlier, with the name thumbnail.png. I usually take a screenshot on a grey background (#eeeeee to match the extension background) and move the dice to an aesthetically pleasing locating in an image editing tool. You could maybe also create some kind of icon or something if that makes more sense, but I think it that it's nice if the thumbnails follow the same conventions.

8. Submit a Pull Request

Before you submit your changes, I would just like to take this opportunity to congratulate you on making it this far. I hope you had fun or at least learned something new. When you create the Pull Request, the changes you've made to the project will be proposed and the maintainer of the project will be able to approve or reject the request. I would like for the dice in the extension to maintain a certain standard of quality, so there may be situations where the proposed new dice doesn't quite make the cut. But that's alright, as you can now show your friends how to install your version of the extension. The server will still store your use of these new unofficial dice, so people with your version will be able to see them. People with the main version will just see the normal Roll20 dice. That being said, please do submit your dice, I would really love to see them and possibly get them into the main version.

You will need to create a fork, then commit and push your changes before you can create a Pull Request. You can do this in GitHub desktop like so:

After this, you can click Branch > Create pull request.

This will open up GitHub in your browser where you can then finalize the Pull Request. Once you've created the Pull Request, I'll try to get to it as soon as I have time.

And that's it. Thanks for reading and good luck!