JavaScript Animated D6 Dice Roller Code
This page is in the Eposic Archive. Web pages in the Eposic Archive are possibly out of date and will not be maintained, but are being retained for historical purposes. Thank you for visiting Eposic!
Part Five: An Example Mini-Adventure!
Perhaps you've already tried the 'online diversion' on this site. I'm referring to The Phantom's Bane. If you haven't tried it yet, feel free to take a little break now and give it a try. It's not a real sophisticated game, but it does give you an idea of what you can do with the dice roller.
I'm not going to explain all of the code for The Phantom's Bane. That would be overkill for this article. Instead, I'm going to focus on the uses I made of the D6 class and its methods.
So I'll present here portions of the code, and talk about just those portions. But feel free to view the source for the game in your browser if you want to try to pick the whole thing apart!
I've got the dice images installed on my site at the URL
/rpg/diceimages. I've had them installed there
for some time now; I use them in another program on the
site, and intend to leave them right where they are.
I decided to install The Phantom's Bane in the
directory /diversions/mini-adventure. This
means that I have to configure The Phantom's Bane
to pick up the dice images from some directory other than
the one where the game resides. This configuration
needs to be done before the dice can be created. The code
I call to configure the game to pick up the images from
the correct URL for my site is as follows:
1 D6.setBaseUrl('/rpg/diceimages/');
That one line configures the game to pick up the dice images
from the /rpg/diceimages directory.
Having configured the dice images directory, we proceed to create the dice. Here's the line of JavaScript code I used for that:
1 D6.dice(4, rolldice, null, useImages, "none");
You'll notice that we have five arguments in this call to D6.dice. The first three arguments we've seen before; they are, from left to right, the number of dice to display, the callback, and the callback data. The fourth argument is a boolean value designating whether or not to use images when animating the dice. If not supplied, the variable defaults to true. If you don't like the performance of image-based animations, pass false as this fourth argument, and the animations will be based on ascii text.
The fifth argument is the label to use for the button that is clicked to roll the dice, or the keyword 'none' if no button is to be automatically generated. Note: If the fifth argument is not passed, or if it is passed but logically evaluates to boolean false, the label defaults to the string "Roll Dice".
Since we've used the keyword 'none' for the fifth argument, the D6.dice method will not generate the code for the button. We do this simply because we want multiple buttons in the game, and each of them will need to be programmed to do something specific within the context of the current situation. And we don't always want to have a button available that will roll the dice; at times perhaps none of the choices require dice to be rolled.
When dice are to be rolled in the game, we make the following call:
1 D6.roll();
Any button on the page can be set up to make this call when the button is clicked.
We make the above call any time we want the dice to be rolled.
This will roll the dice, then call our callback, in this case,
rolldice, as specified in the D6.dice call shown
earlier. Note: The rolldice callback in this game is
set up as an intermediary to call the callback that we really
want to call, and to pass to that callback the callback data
that we're really interested in. If you're interested in the
details, feel free to peruse the source code of the game.
The last bit of code from The Phantom's Bane that I'll mention here is the code for hiding or showing the dice. There are times during our game that we would just as soon not display the dice. Here's the code to hide all the dice:
1 D6.diceToShow(0);
You may recall that in our call to D6.dice above, we passed the value 4 as the first argument. This creates 4 dice. However, the D6.diceToShow method can restrict the number of dice that are shown. The argument to D6.diceToShow specifies the number of dice to show. Thus, passing the argument 0 hides all the dice.
There are a few times in The Phantom's Bane when we only want to display two dice. Fine. You know now that the code to show only two dice is:
1 D6.diceToShow(2);
Note that the D6.diceToShow method can not cause more dice to be displayed than the number of dice created by the call to D6.dice. So when you call D6.dice, be sure to create as many dice as you'll be needing at the maximum. You can then show only the dice that you're using at any given time by calling D6.diceToShow with the appropriate argument.
When the argument to D6.diceToShow is a positive number X, the left most X dice are the ones shown. These dice correspond to the first X low-indexed elements in the results array in the callback. For instance, if X is 2, then results[0] and results[1] contain the values rolled for the two visible dice.
That's all for this tutorial. There is still more to the dice roller package. There are four low-level classes used by the D6 class. If the D6 class doesn't do for you what you want, look to the low-level classes. If you're interested, read The JavaScript Animated D6 Dice Roller Documentation, which documents two of the low-level classes which you might find useful, and gives more documentation on the D6 class itself.
Thanks for visiting, and reading! I hope you find the JavaScript Animated D6 Dice Roller package interesting, and maybe even a bit useful.
