Eposic Archive: JavaScript Animated D6 Dice Roller Documentation, The D6Animator 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 D6Animator class is used to animate a single d6 die.
There are several methods and properties defined in the D6Animator 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 D6Animator class on a web page.
Methods and Properties
- D6Animator(id, baseUrl, bankKey) Constructor
- get(id) Class method
- baseUrl Class property
- setInterval(interval) Instance method
- setCallback(callbackFunction, callbackData) Instance method
- start(result) Instance method
- clear() Instance method
- result Instance property
D6Animator(id, baseUrl, bankKey)
Constructor: Constructs a new D6Animator object.
Arguments:
- id - The id of the target img node for an animation based on images, or the id of the target span node (or other node that can contain text) for an animation based on ascii text. If not supplied, creates a dummy object. Optional (but required if either baseUrl or bankKey are supplied)
- baseUrl - The URL to the directory where the dice images reside. Defaults to the value of the class property D6Animator.baseUrl. Optional (but required if bankKey is supplied)
- bankKey - The key that identifies the image bank to use for the images associated with this D6Animator object. Defaults to the value of id. Optional
Description:
The constructor for D6Animator creates a new object with methods useful for animating a single d6 die. If the id argument is undefined, not a string, or 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 equal to the id attribute of an img node or some other node that can contain text. If the identified node is not an img node, then ascii text will be used to simulate animated images (several numbers will flash by in sequence, finally settling on a single number). In this case, the baseUrl and bankKey arguments are ignored if supplied.
If the identified node is an img node, the image source of that node can be manipulated by methods of the D6Animator class to animate a single d6 die. The bankKey argument specifies which image bank contains the dice images. If there is no existing image bank with the specified key, a new image bank is created, using the specified baseUrl to locate the dice images for the image bank.
By using the same bankKey for multiple D6Animator objects, you can cause the same set of images to be re-used. This reduces the load time for downloading all of the images when multiple D6Animator objects are used in a web page. Some web browsers will cache the images and reuse similar images regardless of what values you use for bankKey. Other browsers, including IE6, seem not to cache the dice images, and use of the bankKey argument will make a huge difference in how fast the browser loads all of the dice images.
If the specified image bank already exists, then baseUrl is ignored. If the specified image bank does not exist, the dice images are loaded into the image bank. The URL of each image pulled into the image bank is constructed by appending the base name of the image to the baseUrl argument. If the baseUrl is not the empty string and represents the directory where the dice images reside, then it should end with a slash (/), as the slash will not be added.
The base names of the dice images are as follows:
| Base Name | Description |
|---|---|
blank.gif | A blank image |
die-#.gif | The die with the specified number (#) of pips on its face. Example: die-1.gif is the base name of the image file that shows one pip on the face. |
dices-#.gif | A die tilted at an angle, showing two faces on the horizontal axis. The specified number (#) of pips can be seen coming into view on the left face. The right face is in shadow, so that the number of pips can not be distinguished. Example: dices-3.gif is the base name of the image file that shows a die with three pips on the left side coming into view. |
dicet-#.gif | A die tilted at an angle, showing two faces on the vertical axis. The specified number (#) of pips can be seen coming into view on the top face. The bottom face is in shadow, so that the number of pips can not be distinguished. Example: dicet-5.gif is the base name of the image file that shows a die with five pips on the top side coming into view. |
Thus, each image bank holds 19 images: A blank image, six images showing one face, six images showing two faces (one with pips, the other one shadowed) on the horizontal axis, and six images showing two faces (one with pips, the other one shadowed) on the vertical axis. You can find a set of appropriate images in Part 1 of the JavaScript Animated D6 Dice Roller Tutorial.
If you want to use two different sets of dice, you need to place them in two different directories on your web server. Each set must use the base file names as shown in the table above. The baseUrl arguments will then distinguish between the two sets.
For example, say you have one set of white dice and one set of red dice. Under the root directory of your web server, you could place the white dice in a subdirectory called white and the red dice in a subdirectory called red. The baseUrl for the white dice would then be /white and the baseUrl for the red dice would then be /red. If you had multiple white dice on a single web page, you could use "white" as the bankKey for the D6Animator object for each white die. The bankKey argument for a red die would have to be something different than the bankKey argument for a white die; "red" would seem a natural bankKey for a red die. If you had multiple red dice on the web page, you could use "red" as the bankKey for each red die. You would thus have two image banks, one for the white dice and one for the red dice. Each white die would use the white image bank, and each red die would use the red image bank.
get(id)
Class method: Retrieves or creates a D6Animator object with the specified id.
Arguments:
- id - The id of a D6Animator object to be retrieved or created. Required
Description:
Returns the D6Animator object with the specified id, if it exists. Otherwise, a new D6Animator object is created, using the specified id as the id of the newly constructed D6Animator object, and using default values for the other two arguments to the constructor.
For example, suppose you had created a D6Animator object with an id of "die1". Then you could fetch it from elsewhere on your web page with a call such as this:
var die1 = D6Animator.get("die1");
baseUrl
Class property: The default URL where dice images reside.
Description:
You can set the D6Animator.baseUrl class property and it will be used as the default URL for locating dice images. This class property is used as the default only in the constructor; changes to this class property have no effect on an existing object.
setInterval(interval)
Instance method: Sets the time interval between frames of the animation.
Arguments:
- interval - The number of milliseconds to wait between frames of the animation. Defaults to 50 milliseconds for images, or 10 milliseconds for text. Optional
Description:
Animation of the dice is done by displaying one frame (image or text), waiting some period of time, and then displaying the next frame. This method sets the period of time to wait between frame displays.
setCallback(callbackFunction, callbackData)
Instance method: Sets the end-of-animation callback function and data.
Arguments:
- callbackFunction - The function to be called when the animation sequence ends. Required
- callbackData - The sole argument for the callback function. Optional
Description:
After creating a D6Animator 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 the animation finishes. 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 result of the die roll. To get the result of the die roll, you can pass the id of the die roller in the callback data, then use the get class method to get the D6Animator object. Once you have the D6Animator object, the result of the die roll is available in the result instance property.
start(result)
Instance method: Starts the die animation.
Arguments:
- result - The result to display on the final frame of the animation, if the supplied argument is a value between 1 and 6, inclusive. If result is not a number in the range 1 to 6, inclusive, then a random value is determined for the final frame. It is recommended that you pass in a numeric value in the range 0 to 6, where 0 represents the need for the D6Animator object to randomly generate a value for the last frame, whereas a value from 1 to 6 represents the actual value that will be displayed in the last frame. Optional
Description:
The start method causes the animation sequence to begin. The result of the die roll will be displayed as the final frame of the animation sequence. This result may be predetermined or pseudo-randomly determined. To have the animation sequence display in the final frame a given result in the range 1 to 6, inclusive, pass that value as the argument of the start method. To have a pseudo-randomly determined number display in the final frame on a particular animation sequence, you can simply not pass in a result argument, or you can pass in a value that logically equates to false, or any number that is not in the range 1 to 6, inclusive.
clear()
Instance method: Clears the dice roller display.
Description:
If images are being used for the dice animation, this method causes the blank.gif image to be displayed. If text is being used instead of images, the text is replaced by the empty string, thus removing any text.
Calling the start method after calling the clear method will start the animation again as normal. To clear the dice display again after the animation finishes, call the clear method again.
result
Instance property: The result of a die roll.
Description:
When the start method is called, a result for the last frame of the animation is determined (randomly or via the argument passed in). This result is saved within the D6Animator object as an instance property. It is updated each time that the start method is called.
