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.
Download the code as a .zip file or clone it with git. I recommend the GitHub Desktop client.
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.
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.
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.
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 befalse. 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 settinguseColortotrue, 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
keyfield 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.
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.
- Select all 8 dice models.
- Open
Render Propertiesand clickBake. 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. - 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.
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.
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.
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.