General Format

All commands to the animator are in the form of simple text commands. The animator parses this input string and, if it understands the input, proceeds to lay out and animate the juggling pattern. Every animation parameter that is changeable can be set with one of the available commands. The applet includes some preferences panels for modifying things, but these are just for convenience and, again, don't add to the functionality of the animator input commands.

The input string is comprised of a series of semicolon-separated settings in the form variable=setting.

There are just two required settings: One indicating a mode, the other indicating the pattern to animate. If you type mode=siteswap;pattern=552 into the animator, for example, you will get the siteswap pattern 552 animated at full speed. That's basically all there is to it. Additional optional settings allow you to tailor the animation, if you want. The available settings are described below.


When animating simple siteswaps, it gets tiring to keep typing "mode=siteswap;pattern=" as in the example above. Therefore there is a shortcut: If your input string contains no '=' characters, the parser will assume you've only given a pattern. It then decides whether to use siteswap or syncsiteswap mode, automatically generates the string "mode=[sync]siteswap;pattern=[your input];slowdown=2.0", and then sends this to the animator. Note that patterns inputted in this manner will be displayed at half of normal speed.


Required Settings

The animation mode, currently must be set to either siteswap or syncsiteswap. No default.
Pattern to animate, in either siteswap or sync siteswap notation, depending on the mode setting. See below for more information regarding the pattern format. No default.

Animation Settings

Size of border around juggling pattern, in pixels. Default is 0. (optional)
Factor by which to slow down time. Default is 1.0, full speed. (optional)
Frames per second on the screen. Default is 20.0. (optional)
Should the animation start paused (true/false)? Default is false. (optional)
Should the animator double-buffer to improve quality, at the expense of increased memory usage (true/false)? Default is true. (optional)

Physical Settings

Acceleration of gravity, in meters per second per second. Default is 9.8. (optional)
Throws per second made by juggler. Default is 4.5. (optional)
Throwing position from centerline of body for both hands, in meters. Default is 0.25. (optional)
Throwing position for right hand only, overrides throwx above. Default is 0.25. (optional)
As above, for the left hand. This will usually be a negative number, in meters. Default is -0.25. (optional)
Catching position from centerline of body for both hands, in meters. Default is 0.5. (optional)
Catching position for right hand only, overrides catchx above. Default is 0.5. (optional)
As above, for the left hand. This will typically be a negative number. Default is -0.5. (optional)
Ball diameter, in meters. Default is 0.1. (optional)
Fraction of a ball's energy retained after bouncing off the ground (how much of its dropped height does it return to?). Default is 0.9. (optional)
Distance in meters below catch/throw position that balls are "scooped" to on the carry. Negative numbers mean to scoop down. Default is -0.2. (optional)
Time (in units of throws) that a caught ball spends in a hand. A dwell of 1.0 means that each hand is full half the time. Default is 1.0. (optional)
Ken Matsuoka's "Height Ratio" parameter from his JuggleMaster program, included here for compatibility with his pattern files. This overrides the tps setting above; ordinarily you should use tps instead. No default. (optional)
Ken Matsuoka's "Dwell Ratio" parameter, also included for compatibility. This overrides the dwell setting above and should normally not be used. No default. (optional)
Supports Ken Matsuoka's "style" settings, which are instructions for moving the hands. If this setting is included then the catchx and throwx parameters listed above are overridden (ignored). See below for a description of this format. No default. (optional)
Overrides the default colors of the balls. See below for a description of the "colors" format. (optional)

The "pattern" Setting Format

The animator expects this setting to be in the generalized siteswap notation described in the notation documentation page, with a few caveats:

  • The input is case-sensitive. Lower-case letters are used for throw values ('a'=10, etc.). Upper-case is used for throw modifiers, which come after the throw they modify.

  • A lower-case letter is always a throw value, with the exception of the letter 'x', which denotes crossing throws in syncsiteswap mode.

  • The two-person passing mode used by the siteswap generator is not currently recognized by the animator.

  • There are currently two recognized throw modifiers:
    Lift-bounce the preceding throw. If this is not possible, do a force-bounce instead (you can't lift-bounce 1's when juggling at a normal pace, for example).
    Force-bounce the preceding throw.

    The "mat_style" Setting Format

    This setting allows you to specify the coordinates of each catch and throw within the plane of juggling. Imagine a coordinate system with the x axis going from left to right in front of you (positive direction is to your right), and y axis going up and down (positive is up). Ken uses the following units of measurement: Each grid tick along the x axis is 2.5 centimeters, and each on the y axis is 5 cm. The origin is at "normal" catching height, at the centerline of your body.

    The setting consists of a string of coordinate pairs in the form {catchx,catchy}{throwx,throwy} where each pair is assigned to a throw in the siteswap pattern. If a pair corresponds to a left-handed throw, the catchx and throwx values are automatically negated. Also, the number of pairs specified need not be equal to the number of throws in the siteswap -- it just loops back to the beginning when it gets to the end of the pairs.

    For example, Ken's standard style for the 3 ball cascade is {13,0}{4,0}, which means to catch at 13*2.5 = 32.5 cm from the centerline (at no elevation) and throw at 4*2.5 = 10 cm from the centerline (also at no elevation). His version of Mills Mess is {-1,0}{-12,0}{0,0}{12,0}{1,0}{-12,0} if you care to puzzle that one out.

    The "colors" Setting Format

    Each color is defined by its red, green, blue components on a 0-255 scale. Thus if this setting is equal to {255,0,0}, the animator will use red balls.

    If you define several colors, they will be assigned to the balls in a cyclical manner. For example, {255,0,0}{0,255,0} means that Ball 1 is red, ball 2 is green, ball 3 is red, ball 4 is green, and so on.

    Colors can also be specified by name; for example the above color setting could be replaced by {red}{green} to get the same effect. Recognized color names include: black, blue, cyan, gray, green, magenta, orange, pink, red, white, yellow.