Skip to content

neunato/siteswap.js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

49 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

siteswap.js

Parse, examine and manipulate juggling patterns in JavaScript.

Supported environments: Node 6.5+, Chrome, Firefox, Edge, Safari, Opera.

Usage

Siteswap( string, notation = "compressed" )

  • string - siteswap string or throws array.
  • notation - notation(s) used to parse string. See supported notations.
new Siteswap("753")
new Siteswap("[43]14")
new Siteswap("(4,2x)*")
new Siteswap("7,5,3", "standard")
new Siteswap("<3p,3,3|3p,3,3>", "passing")
new Siteswap("<(4xp,4x)|(4xp,4x)>", "passing")
new Siteswap(`B3,A3,A3
              C3,B3,B3
              A3,C3,C3`, "multihand")

The following properties/functions are exposed:

.valid » boolean showing if the siteswap is valid.

.error » error message (set to invalid siteswaps).

.input » passed arguments (set to invalid siteswaps).

.notation » notation used to parse the siteswap.

.degree » number of hands used per beat.

.props » number of props the pattern requires.

.multiplex » greatest number of props released together from a single hand.

.greatestValue » greatest throw value.

.period » length of one cycle.

.fullPeriod » length of one coloured cycle (one which distinguishes props).

.groundState » boolean showing if the siteswap is ground state or excited.

.prime » boolean showing if the siteswap is prime (cannot be decomposed).

.throws » array of tosses like { from: int, to: int, value: int } three levels deep representing the throw sequence. .throws[1][0][3] is the fourth (multiplex) toss of the first hand during the second throw of the sequence.

.states » array of states representing the number of props in hands over time. .states[1][0][3] is the number of props in the first hand, four beats after the second throw is made.

.strictStates » array of states representing positions of specific props within hands over time. .states[1][0][3][2] is the id of the third ball in the first hand, four beats after the second throw is made.

.orbits » array of siteswap's orbits which are themselves Siteswaps.

.composition » array of prime Siteswaps the siteswap is consisted of.

.equals( siteswap ) » returns a boolean showing if the siteswap's .throws match those of any rotation of siteswap.

.rotate( count = 1 ) » returns a new Siteswap obtained by rotating the throw sequence by count beats to the right.

.toString( notation = this.notation ) » returns a string representing the siteswap in a given notation.

.log() » outputs all the siteswap properties in a human friendly form to console.


Invalid siteswaps only have .valid, .error, and .input properties set.

Example

const siteswap = new Siteswap("753")
siteswap.valid                      // true
siteswap.notation                   // "compressed:async"
siteswap.degree                     // 1
siteswap.props                      // 5
siteswap.multiplex                  // 1
siteswap.greatestValue              // 7
siteswap.period                     // 3
siteswap.fullPeriod                 // 12
siteswap.groundState                // true
siteswap.prime                      // true
siteswap.throws                     // [
                                    //  [[{ "value": 7, "from": 0, "to": 0 }]],
                                    //  [[{ "value": 5, "from": 0, "to": 0 }]],
                                    //  [[{ "value": 3, "from": 0, "to": 0 }]]
                                    // ]
siteswap.states                     // [
                                    //  [[1,1,1,1,1]],
                                    //  [[1,1,1,1,0,0,1]],
                                    //  [[1,1,1,0,1,1]]
                                    // ]
siteswap.strictStates               // [
                                    //  [[[1],[2],[3],[4],[5]]],
                                    //  [[[2],[3],[4],[5],[],[],[1]]],
                                    //  [[[3],[4],[5],[],[2],[1]]],
                                    //  [[[4],[5],[3],[2],[1]]],
                                    //  [[[5],[3],[2],[1],[],[],[4]]],
                                    //  [[[3],[2],[1],[],[5],[4]]],
                                    //  [[[2],[1],[3],[5],[4]]],
                                    //  [[[1],[3],[5],[4],[],[],[2]]],
                                    //  [[[3],[5],[4],[],[1],[2]]],
                                    //  [[[5],[4],[3],[1],[2]]],
                                    //  [[[4],[3],[1],[2],[],[],[5]]],
                                    //  [[[3],[1],[2],[],[4],[5]]]
                                    // ]
siteswap.composition                // [this]
siteswap.orbits                     // [new Siteswap("750"), new Siteswap("003")]
siteswap.toString()                 // "753"
siteswap.toString("standard:async") // "7,5,3"

Notations

standard

  • shorthand for ["standard:async", "standard:sync"]

standard:async

  • throw values > 9 are written as numbers: 11 is eleven ball cascade
  • throw values are separated: 1,1 is one ball cascade
5
11,1
[4,3],1,4

standard:sync

  • throw values are doubled
  • throw values > 9 are written as numbers: (10x,10x) is a ten ball wimpy pattern
  • throw values are separated: ([4,4],4)
(4,4)
(4,2x)(2x,4)
([2x,2x],0)*

compressed

  • shorthand for ["compressed:async", "compressed:sync"]

compressed:async

  • throw values > 9 are written as alphabetical letters: b is eleven ball cascade
  • throw values are not separated: 11 is one ball cascade
5
b1
[43]14

compressed:sync

  • throw values are doubled
  • throw values > 9 are written as alphabetical letters: (ax,ax) is a ten ball wimpy pattern
  • multiplex throw values are not separated: ([44],4)
  • hands are optionally separated: ([44],4) ([44]4)
(44)
(4,4)
(4,2x)(2x,4)
([2x2x],0)*

passing

  • shorthand for ["passing:async", "passing:sync"]

passing:async

  • jugglers' actions are separated like < … | … | … > and respect the standard:async rules
  • a pass is denoted with p when there are two jugglers: <3p|3p>
  • a pass is denoted with pN when there are two or more jugglers: <3p2|3p3|3p1>
<3|3>
<3p|3p>
<3p2|3p1>
<3p2|3p3|3p1>
<[3,3p],3,3|3p,3,3>

passing:sync

  • jugglers' actions are separated like < … | … | … > and respect the standard:sync rules
  • a pass is denoted with p when there are two jugglers: <(4xp,4)|(4,4xp)>
  • a pass is denoted with pN when there are two or more jugglers: <(4xp2,4)|(4,4xp1)>
<(4,2x)*|(4x,4x)>
<(4p,4)|(4p,4)>
<(4p2,4)|(4p1,4)>
<([6x,4p],4)(4,6x)|([4x,4p],6)(6,4x)>

multihand

  • throws are grouped by hands in rows
  • tosses are comma separated: A5,A3
  • a toss is denoted with the target hand (A,B,C...) and throw value: A3, or
  • a toss is denoted with the relative target hand and throw value in parentheses: (-1,3)
A6,A4

B3
C3
D3
A3

[A4,B3],A4,A1
[A3,B5],B3,B1

(0,6)(0,4)

( 1,4)( 1,2)[(0,3)( 1,3)]
(-1,1)(-1,5)[(0,3)(-1,3)]

All notations support multiplex throws using the [ ] syntax.

All choices (like comma/space as separator) must be consistently applied.

To do

  • Siteswap and transition generator.
  • Custom hand rhythm. Like two hands in one handed patterns.
  • Combining siteswaps of different degrees.

License

MIT License