Eposic Archive: JavaScript D6 Dice Roller Documentation, The D6AnimGroup Class

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!

The D6AnimGroup class is used to animate multiple d6 dice.



There are several methods and properties defined in the D6AnimGroup class, not all of which are documented here. Those not documented here are not intended for public access, but are used internal to the class. The methods documented below are all those intended to be accessed by a developer making use of the D6AnimGroup class on a web page.

Note that use of the D6AnimGroup class requires use of the D6Animator class. You should familiarize yourself with the D6Animator class before you make use of the D6AnimGroup class.

The D6AnimGroup is very flexible, and its usage can be complicated if you try to do something extravagant. But if you learn how to use it properly, its use will allow you to create impressive dice rolling displays. Experiment with it some. Also look at the source code of this web page to see some example usage. (Look for the HTML code for the img tag with an id attribute equal to die1. That's where the example starts. It ends with the window.onload = roll; JavaScript statement.)

Writing this documentation was not easy, especially in trying to explain the structure of the array passed to the start method, which is also the same as the structure of the results instance property under certain conditions. So, I hope this documentation makes sense. If not, well, you don't have to use this class. The other classes allow you to do quite a lot. This class doesn't do anything that you can't build yourself using just the D6Animator class. What it does give you is the ability to group animators and start them all with one call to a single start method, and then have a single callback called when all of the animators in the group have finished. But the D6 class will do that job as well, if you simply want to roll some number of dice simultaneously.

Methods and Properties

D6AnimGroup(id, animators, isSequenced)

Constructor: Constructs a new D6AnimGroup object.

Arguments:
Description:

The constructor for D6AnimGroup creates a new object with methods useful for animating d6 dice as a group, either simultaneously or in sequence. If the id argument is not a string or is logically equivalent to false, the constructor creates an object, but it is not useful for animation purposes. If the id argument is a non-empty string, it must be a unique identifier for the newly created D6AnimGroup object.

The second argument, animators, is an array that contains any mix of D6Animator and D6AnimGroup objects. The elements of the array must start at index 0 and leave no gaps between any two indexes.

The third argument, isSequenced, specifies whether or not the animators array elements are invoked in sequence or simultaneousl. Note that if an element is itself a D6AnimGroup object, then it will have its own isSequenced property, which may be different than the isSequenced property of the object created by this constructor. This allows you to chain together various D6AnimGroup objects to create some complicated dice rolling sequences. Take a look at the source of this web page at the example usage of the D6AnimGroup class to create the example dice rolling sequence at the top of this page, and you will begin to get an idea of what can be done.

get(id)

Class method: Retrieves the existing D6AnimGroup object with the specified id.

Arguments:
Description:

Returns the D6AnimGroup object with the specified id, if it exists. If it does not exist, the return value is undefined.

For example, suppose you had created a D6AnimGroup object with an id of "group1". Then you could fetch it from elsewhere on your web page with a call such as this:

var group1 = D6AnimGroup.get("group1");

setCallback(callbackFunction, callbackData)

Instance method: Sets the end-of-animation callback function and data.

Arguments:
Description:

After creating a D6AnimGroup object but before calling its start method (see below), you can assign a callback function and callback data to the object via the setCallback method. If you assign such a callback function and callback data to the object, then when you next call the start method, the assigned callback function will be called when all animations in the group have finished. The assigned callback data will be passed as the sole argument of the callback function.

Note that this callback function is only passed the one argument when called. It is not passed the results of the dice rolls. To get the results of the dice rolls, you can pass the id of the D6AnimGroup in the callback data, then use the get class method to get the D6AnimGroup object. Once you have the D6AnimGroup object, the results of the dice rolls are available in the results instance property (see below).

start(results)

Instance method: Starts the animation of the animators in this group.

Arguments:
Description:

The start method causes the animation sequences defined by animators in the group to begin. The results array passed as the method argument defines the results of the various dice that are rolled in the group.

Calling the start method of a D6AnimGroup causes the start methods of all D6Animator and D6AnimGroup objects in the animators array (the second argument of the constructor) to be called, either simultaneously or one after the other (depending on the value of the isSequenced property of the D6AnimGroup object).

Note that if you do not pass an argument, or if you pass null or an empty array, then all results of all dice rolls involved will be randomly generated. You must then know what the structure of the results instance property will be once the results are generated. For the details about the structure of the results instance property, refer to the documentation for the results instance property below.

It is perfectly acceptable to predetermine some or all of the results that will be associated with the dice rolled. This requires you to construct a results array of the proper structure and pre-fill it. When would you want to pre-fill the results array? Well, you could be using a PHP program to generate results on the server, and then passing those results out to the web browser. The effect to the visitor to your site will be the same visually either way. So it's really up to you, as to whether or not you want results generated on the server, or allow them to be generated on the client. Either way, you need to understand the structure of the results array.

The structure of the results array you pass as the argument to the start method is the same as the structure of the results instance property, if you have predetermined the results of all dice involved in the group. Any element of the results array can be invalid or missing, and if it is, then the invalid or missing elements will be generated with the required structure. See the documentation for the results instance property below for details about the required structure.

clear()

Instance method: Clears the display of all dice rollers in the group.

Description:

If images are being used for any dice rollers in this group, this method causes the blank.gif image to be displayed. If text is being used for any dice rollers in this group, the text is replaced by the empty string, thus removing any text.

Calling the start method after calling the clear method will start the animations again as normal. To clear the display again after the animations finish, call the clear method again.

results

Instance property: The results of the dice rolls.

Description:

When the start method is called, the results for the last frame of each animation in the group is determined (randomly or via the argument passed in). The array of results are saved within the D6AnimGroup object as an instance property. It is updated each time that the start method is called, based on the results argument of the start method.

The results property is an array whose elements are numbers or other arrays. If an element is an array, its elements are numbers or other arrays that meet this same criteria. Which elements are numbers and which elements are arrays depends on the elements of the animators array that was passed as the second argument of this group's constructor. Each element of the results array is associated with the corresponding element in the animators array at the same index.

If an element in the animators array is a D6Animator object, then the corresponding element at the same index in the results array is an integer in the range 1 to 6.

If the element in the animators array is a D6AnimGroup object, then the element at the same index in the results array is an array. The elements of this array are determined in the same fashion as described above.

For example, suppose you have 9 D6Animator objects, named d1 through d9. Suppose you build five D6AnimGroups, named dg1 through dg5. Suppose dg1 contains d1 and d2; dg2 contains d3 and d4; dg3 contains d5, d6, and d7; dg4 contains dg1 and dg2; and dg5 contains d8, d9, dg3, and dg4. Suppose you then called dg5.start(). What would the results instance property of dg5 then look like?

If we let r1 through r9 represent the results of the animators d1 through d9, respectively, and rg1 through rg5 represent the results of the animator groups dg1 through dg5, then we can represent the results of the various groups thusly: 

rg1 = [r1, r2]
rg2 = [r3, r4]
rg3 = [r5, r6, r7]
rg4 = [rg1, rg2]
rg5 = [r8, r9, rg3, rg4]

By performing some simple substitutions, we can derive the structure of any of the results instance properties of any of the animator groups. In particular, here's the results instance property of dg5: 

rg5
  = [r8, r9, rg3,          rg4]
  = [r8, r9, [r5, r6, r7], [rg1,     rg2]]
  = [r8, r9, [r5, r6, r7], [r1, r2], [r3, r4]]

The construction of a results array appropriate for use in the start method of a given D6AnimGroup object can become quite complicated if D6Animator and D6AnimGroup objects are used to create an extravagant display of dice. For an example of mixing D6Animator and D6AnimGroup objects within one D6AnimGroup object, look at the example source code for the animations at the top of this web page. In the example, the middle die of the top row always rolls a one, and the first and third dice of the bottom row always roll sixes. The other three dice are randomly determined each time the page is loaded or the "Reroll" button is clicked.

If you look closely at the roll function defined in the source code of this web page, you will see how the results array (the argument of the start method) was defined to cause some dice results to be fixed and others to be generated each time the dice are rolled. Be sure to note where the dice images are positioned, which dice image is associated with which D6Animator object, and the ordering of elements of objects and results values in the various arrays.

JavaScript Animated D6 Dice Roller Documentation Home

Copyright ©2006, Michael K. Eidson

Eposic web dude Michael K. Eidson