How to Make a Custom Dieroller - OpenRPG Documentation

If you've been using OpenRPG for a while, you may have discovered the joy of dierollers. With these, you can do all sorts of things to simplify your rolling experience, especially for complicated rolling systems that include re-rolling certain numbers, comparing rolls to a target value, and so on and so forth. But what if you want a roller for the system you use, and there isn't one built in? This guide will hopefully help you out with that.

Step 1: Make Sure You Can't Do It with the Default Rollers

You can save yourself a whole lot of work if you figure out how to use the current dierollers to suit your ends. For example, if you wanted to roll 5d6, rerolling on sixes, and compare the results to a target number of 4, counting the number of successes greater than or equal to 4, you can do that straight out of the box with the std roller:

[5d6.open(6).vs(4)] -> [4,[6, 5],4,1,5] = (4)

List of Functions Inluded in the standard (std) roller

.ascending()

Arranges the dice rolled from lowest to highest and then totals them.
```
[5d6.ascending()] -> [2,2,5,5,6] = (20) 
```

.descending()

Arranges the dice rolled from highest to lowest and then totals them.
```
[5d6.descending()] -> [5,4,3,3,2] = (17) 
```

.takeHighest(num)

Takes only the highest num rolls and totals them.
```
[5d6.takeHighest(2)] -> [6,4] = (10)
```

.takeLowest(num)

Takes only the lowest num rolls and totals them.
```
[5d6.takeLowest(2)] -> [1,3] = (4)
```

.extra(num)

Rolls an extra die if the number rolled is greater than or equal to num, then totals all the dice.
```
[5d6.extra(5)] -> [[5, 4],[6, 3],3,1,3] = (25)
```

.open(num)

Rolls an extra die if the number rolled is greater than or equal to num, and rolls again if that roll is greater than or equal to num.
```
[5d6.open(5)] -> [4,2,4,[5, 4],[6, 6, 6, 1]] = (38)
```

.minroll(num)

Re-rolls any dice that are less than num, then totals up only the rolls greater than or equal to num.
```
[5d6.minroll(3)] -> [5,3,6,3,5] = (22)
```

.each(num)

Adds num to each die roll individually, then totals up the modified values.
```
[5d6.each(-1)] -> [[3, -1],[5, -1],[4, -1],[3, -1],[2, -1]] = (12)
```

.vs(num)

Counts the number of rolls greater than or equal to num.
```
[5d6.vs(4)] -> [6,3,1,4,1] = (2)
```

Step 2: Figure out how your roller works

Before you can go and start coding your roller and working on all that stuff, you need to get an idea of how it works. Now, I'm not saying that you need to know how every bit of code will work, since that sort of stuff is hard to figure out before you start coding, at least if you're like me. (-mDuo13) Rather, what I suggest here is that you make sure you totally understand how your system's dice work, and what sort of functions you're going to need. Come up with a plan of action: how will dice react by default? What extended functions will you allow? That sort of thing.

Step 3: Start coding

There's a file "HOWTO.txt" in the openrpg1/orpg/dieroller folder. If it's too vague and too short for you (as it is for me) then you'll have to spend some time studying the dierollers as you code your own. As I myself become more familiar and more comfortable with making dierollers, I'll explicate the process in much more detail here, including good practices to make your roller more easily modified, to allow dice functions to be combined, and so forth. It will still require some expertise in Python to code your roller, though: hopefully you can pick up enough to figure it out.

Step 4: Add your roller to the list of valid dierollers

This part is pretty easy. There are two steps, and both of them involve the file "utils.py" in openrpg1/orpg/dieroller, so open up that file in IDLE or your other text editor of choice.

First, you need to import your dieroller: On approximately line 33, there's a chunk of code that looks a bit like this:

   1 from die import *
   2 # add addtional rollers here
   3 from wod import *
   4 from d20 import *
   5 from hero import *
   6 from shadowrun import *
   7 from hackmaster import *
   8 from wodex import *
   9 from srex import *

What you need to do should be pretty obvious: add your roller below. The word that you put in, such as "wod" or "hero" should be the same as the name of your dieroller's filename, minus the ".py" part: for example, my file, "mduo.py" will be imported like this:

   1 from mduo import *

The other step is also easy. There is a list of valid rollers a couple lines down from that, that looks something like this:

   1 rollers = ['std','wod','d20','hero','shadowrun','hackmaster','srex','wodex']

Just add the name of your roller in there somewhere, in quotes and separated by commas like above. For example, with my "mduo" roller again:

   1 rollers = ['std','wod','d20','hero','shadowrun','hackmaster','srex','wodex','mduo']

Step 5: Test and Troubleshoot

Once you've modified utils.py, you'll have to restart OpenRPG and check to see if your roller works. The first step is to change the roller you're using with the /dieroller command, as I have done for my mduo roller here:

/dieroller mduo

The next step is to roll some dice. Hopefully you know how to do that by now. Once you've gotten an idea of what works and doesn't work in your roller, you can go back to your files and make some changes. Remember, though, you'll have to restart OpenRPG for any changes you make to take effect.

If you're getting "bad dice format" errors, or OpenRPG just isn't returning what you want it to, try running OpenRPG through start.py (the console version) instead of start.pyw, if you use it, and look in your console window for error messages. If you're not getting any, try putting some print statements into your code, and see if they show up. If they don't, then that section of your code isn't running: see if you can isolate the problem.

Good luck!