Juggling Engine

What the Controls panel does

The Controls panel drives the Animator: enter a siteswap, choose the prop type, optionally load a trick, mark special moves per beat, and fine-tune playback, colors, dwell and holds.

The Animator accepts asynchronous, synchronous, crossing, multiplex, hybrid, MRN-style and multi-member notation patterns. Multi-member notation is a generalization of standard siteswap notation: the same throw grammar can describe not only hands, but also feet and head slots in one pattern. The editable special-move buttons are generated from the current siteswap, so the available buttons change when the pattern changes.

Click any blue example in this guide to load it into the Animator.

Trick section

• Siteswap: type or paste the pattern to animate. Examples include 9555, 744744, b97531, (8,6x)*, [65]22, ([8x4],2)*, 64y5-2y22-20, (4,4,2,2,0), ([64],4,[22],0,2) and (4,3)!(4x,0)!(0,0)!(1,0)!*.
• Tricks: opens the trick picker and loads a prepared Animator configuration, including siteswap, prop, dwell, holds, colors and special moves when the trick defines them.
• Prop type: choose Balls, Clubs or Rings. The selected prop changes the 3D object and filters special throws to the moves that support that prop.

Siteswap notation supported here

• Vanilla / asynchronous: one throw per beat, such as 3, 441 or b97531.
• Synchronous: paired throws in parentheses, such as (4,4) or (8,6x)*.
• Multiplex: several objects released together, written with brackets, such as [43]23.
• Hybrid / mixed: combines sync, crossings, multiplexes and transitions, such as ([8x4],2)*.
• Multi-member notation: hands, feet and head can be written in the same siteswap. Async patterns use top-level dashes, for example 64y5-2y22-20. Sync patterns add extra comma fields inside each pair, for example (4,4,2,2,0).
• MRN: uses ! to split beat groups with independent timing, for example (4,3)!(4x,0)!(0,0)!(1,0)!*.
• x means crossing to the other hand, * mirrors a sync half, and letters continue values above 9: a = 10, b = 11, etc.

Multi-member examples

Special Moves switch

• Off: the siteswap plays with the normal Animator body and prop paths.
• On: beat buttons appear for the editable throw/body-move slots in the current pattern.
• Async patterns: each beat normally has one editable hand slot.
• Sync patterns: each beat can expose separate left-hand and right-hand slots.
• Multiplexes: compatible multiplex throws can still be marked with special throws.
• Body-source sections: when the pattern includes hands, legs or head/body sections, the editor exposes compatible hand, foot and head/body buttons.

Using a beat button

• Click a beat button to open the special option picker.
• The picker groups compatible choices into Special throws, Special moves and Special animations.
• Only options that work with the current prop and the selected body member are shown.
• Select the same active option again to clear it, or choose another option to replace it.
• Use the small gear on a special throw to tune rotations, release direction and hand-path offsets.

Special throws

Special throws change the hand path and, for clubs/rings, may also change prop orientation or spin. The visible choices depend on the selected prop.

• All props: Outside Throw (OT), Outside Front (OF), Inside Front / DIPS (IF), Backcrosses (BX), Reverse Backcrosses (BXR), Inside Throw (IT), Over Head (OH), Over the Arm Crossed (OAX), Under the Arm Crossed (UAX) and Centered Outside Throw (OTX).
• Clubs: Outside Helicopter Throw (OHT), Club Helicopter Throw (CHT) and Club Inside Helicopter Throw (CIHL). Club-specific versions of over-head, outside-front, inside-front and backcross/reverse-backcross paths are applied automatically where needed.
• Rings: Pancakes (PAN) and Outside Sideways Pancake (OSP). Ring-specific over-head, outside-front, inside-front and backcross/reverse-backcross paths are applied automatically where needed.

Special moves

Special moves are body rotations that can be attached to compatible hand slots.

• 360: SS, duration 2 beats.
• 720: DS, duration 4 beats.
• 1080: TS, duration 6 beats.
• 1440: QS, duration 8 beats.
• Direction: reverse variants are available where supported. A reversed backflip is shown as a frontflip.

Special animations

Special animations are helper body/limb poses used by spin, grab and still modes.

• Spins: Spin Preparation Left/Right (SPL, SPR), Spin Still Left/Right (SSL, SSR), and Spin Out Left/Right (SOL, SOR).
• Arms / grabs: Arm Preparation (AP), Arm Close (AC), Arms Global (AG), Arm Out (AO), plus pure-2 grab helpers for Standard, Front2side, Front2front, Side2front and Front2back modes.
• Stills: floor-hold helpers for Standard (S2F), Front2side (F2F), Front2front (FFF), Side2front (SFF) and Front2back (FBF).

Automatic animation modes

• custom: keeps your manual special-move selections.
• spins: builds spin rectangles for compatible 2 and 0 throws.
• spins + legs animation: adds automatic leg animation to the spin rectangles.
• spins + arms animation: adds automatic arm animation to the spin rectangles.
• spins + full animation: combines spin rectangles with automatic arms, legs and body preparation.
• Natural leg modes: custom, standard, front2side kick, front2front kick, side2front kick and front2back kick.

Throw rotation, prop direction and offsets

• Rotations: choose auto, 0 to 9, or negative values -1 to -4 for reverse rotation counts.
• Prop rotation direction: choose auto, +x, -x, +y, -y, +z or -z.
• Prop release direction: use the same auto / axis choices to set how the prop leaves the hand.
• Offsets: drag Catch, Halfway and Throw points to change the hand path. X moves left/right, Y moves up/down and Z changes depth.
• Apply / cancel: click the check button to apply the gear-modal changes, or close/click outside to cancel.

Advanced Options switch

• Off: keeps the compact advanced controls hidden and uses the current/default Animator settings.
• On: opens the compact Prop Settings, Playback, Timing Settings and Holds cards directly inside the Controls panel.

Prop Settings

• Random props: randomly distributes balls, clubs and rings across the detected objects.
• Random props off: every object uses the single prop chosen in the main prop buttons beside the Siteswap field.
• Main prop buttons: clicking Balls, Clubs or Rings beside Siteswap turns Random props off and applies that prop to all objects.
• Random colors: automatically assigns different colors to the detected objects.
• Object buttons: click an object symbol/number to open the prop and color modal for that object.
• Prop Type card: choose whether the selected object is a Ball, Club or Ring.
• Prop Apply to all: in the Prop Type card, apply the selected prop type to every object instead of only the selected object.
• Colors card: choose the selected object color from the color palette.
• Color Apply to all: in the Colors card, apply the selected color to every object instead of only the selected object.
• Validate: click the check button to confirm the prop/color changes and close the modal.
• Cancel: click the close button, click outside the modal or press Esc to close the modal without applying the temporary changes.
• Source: the number of object controls is detected from the current siteswap/object count.

Playback

• Allow Impulse: lets the body add impulse/momentum to throws. Turning it off keeps the animation more rigid and mechanical.
• Collision Detection: enables object collision checks so props react when their paths intersect.
• Realistic Throws: uses a more physical throw style for a less perfectly geometric animation.

Timing Settings

• TPS: throws per second. The input accepts 0.1 to 20 in steps of 0.1.
• Hands: changes the hand dwell percentage.
• Legs: changes the foot/leg dwell percentage.
• Head: changes the head/forehead dwell percentage.
• Range: dwell values are selectable from 5% to 95% in 5% steps.

Holds

• Hold 2: treats compatible 2 throws as held/carried objects instead of normal tosses.
• Hold 3x: treats compatible crossing 3x throws as holds when the pattern allows it.

What this panel does

The Siteswap Generator searches for valid patterns that match the template and filters you set, then lets you preview, animate, add, or export the results.

It works with vanilla / asynchronous, synchronous, multiplex, mixed, and multi-member hands+feet siteswaps.

For multi-member generation, enable Hands and Feet in Props & range. The generator can build patterns where hands and feet juggle the same siteswap structure together, with throws assigned to both members.

Recommended workflow

• Start with a broad template such as ??? or 5??.
• Set Props & range: number of props for hands/feet and throw range for hands.
• Optionally set a Base siteswap as the reference used to determine whether generated results are ground or excited relative to it.
• Use height limits and exclusions to narrow the results.
• Click Generate, then click a result to send it to the simulator.
• For an excited result, click its state pill to preview or select transition throws between the base siteswap and that result.

Field: Siteswap

Use this field as a search template: keep the throws you know, and use ? where the generator should fill in a throw.

For asynchronous patterns, write one stream of throws. Use ? for any valid throw and ?s when marked positions must match. Multiplexes use square brackets, for example [5?]??.

For synchronous patterns, write pairs in parentheses. Use ? for any throw, ?x for crossing, ?i for same-hand, and ?s, ?xs, or ?is when marked throws must be equal. Multiplexes can be placed inside a sync slot, for example ([??],?)(2,?).

For multi-member hands+feet asynchronous siteswaps, separate member streams with -. The first stream is hands; the second stream is feet. Example: ???-??? or [??]??-???.

Multi-member tip: to add or combine feet with any hands siteswap, enter the hand siteswap, then - and ? placeholders for the feet. For example, 645-??? generates variations of 645 with added foot throws.

For multi-member hands+feet synchronous siteswaps, use sync tuples with four slots: (left hand,right hand,left foot,right foot). Example without multiplexes: (?,?,?,?)(4,4,0,0). Example with multiplexes: ([??],?,[??],?)(4,4,0,0).

Field: Props & range

Sets the average number of props in each generated result and the throw range used for ? positions.

With Hands only, the props value applies to the hand siteswap and the range controls hand throw heights. With Hands and Feet, props defines the total props shared by the multi-member hands+feet pattern, while the range controls the hand throws the generator may insert.

Every fixed value already typed in the Siteswap field affects the remaining ? slots: fixed throws consume part of the target average, so the generator only fills ? with values that still satisfy the selected props and range.

Field: Base siteswap

Sets the reference siteswap used to determine whether each generated result is ground or excited relative to it. This is what tells the generator whether transition throws are needed between the generated siteswap and the base siteswap to form a complete sequence.

Field: Expressions to exclude

Remove unwanted results by listing fragments or expressions separated by ;. This is useful for filtering out throws, structures, or whole families of patterns you do not want in the output.

• Exclude 0 to avoid holds.
• Exclude 2 to avoid non-crossing carry-style beats; 2x still remains allowed.
• Exclude x to keep only non-crossing patterns when that fits your search.

Fields: Minimum and maximum height

Restrict the throw values allowed in the generated results. Lower ranges keep patterns more compact and quicker; higher ranges allow taller, more spread-out patterns.

Results list

• Click a result: sends it to the Controls panel and starts the animation.
• Download (⬐): exports the generated list as a text file.
• Filter pill (all → ground → excited): cycles through the result filter. all shows every result, ground shows only results in the same state as the base siteswap, and excited shows only results that need transition throws.
• State toggle pill: shows or hides the state pattern shown under each result.
• State badge: shows whether the result is grounded (same state as the base siteswap) or excited (different state, so transition throws are needed).

Useful search ideas

• Start with short templates, then tighten the filters.
• Keep the height range narrow to reduce very large result sets.
• Use a familiar base siteswap as the reference when checking whether generated results need transitions to connect back to it.
• Combine fixed throws and ? to guide the generator without overconstraining it.