Jongl V14.0: specification

Date of issue of this Guide: 22-jul-2006

What is JONGL?

JONGL is a juggling simulation program. You can watch patterns with one or more jugglers throwing almost anything from balls to chain saws. While the jugglers are doing their pattern you can watch the scene from any view you like using the mouse. Don't forget to try the mouse buttons. Jongl is free software.

Controlling the program

Format of the files read in

Listings of external files


Changes from V13.0 to V14.0


Changes from V12.0 to V13.0


Changes from V9.0 to V12.0


Changes from V8.0.1 to V9.0


Changes from V8.0 to V8.0.1

See the Jongl 8.0.1 specification.


Changes from V7.0 to V8.0

Many thanks go to David Byers for his large pattern directory (I added it without change) and to Radieschen and Eva for their patterns, too.

Changes from V6.6 to V7.0

See the Jongl 7.0 specification.

Known limitations of the current version

Known bugs

Planned things for the next releases


Controlling the program

With the Mouse, with the Keyboard or using the command line.

Mouse

There is a menue popping up when you click the right mouse button. Its content depends on the current pattern, operating system and current object type (old or VRML).

With the mouse the position of the observer is being moved on concentric circles around the geometric center of all objects. As a consequence you view actions with high patterns from a higher position. (See option Z=).

Fullscreen mode:

Mouse left/right Observer moves left/right
Mouse up/down: Observer moves up/down
Mouse up/down and
- left mouse button Observer moves away/toward from/to object
- middle mouse button
or
CTRL and left mouse button
Observer's view angle increases/decreases
If the scene rotates too quickly, reduce 3D mouse speed in the GUI, register tab Settings.

Editor mode:

left mouse button move object along X and Y
SHIFT + left mouse button move object along Z
middle mouse button
or
CTRL and left mouse button
rotate object around Z
See explanations about Editor mode. Note that mouse control is along the *absolute* coordinate system. Depending on your current point of view your results might be really strange. Press r to reset the view point.

Keyboard

Quite a lot of keys have been assigned to more or less useful functions. (This might be not up-to-date. Start Jongl and press ? or select Help from the menu to get current settings.)

This is the keyboard layout for the 3D mode:

SPACE stops the motion of the observer. Makes it easier to stop the observer during a three-dimensional manoeuvre quickly and at the desired position.
RETURN or ENTER returns to the pattern menue, so you can select a different pattern without having to leave the program
ESC enables you to get out of this program as fast as possible
? shows what all the keys are supposed to do for you
a Place an arrow at the current object
b switches mouse control from rotation to LINEAR movement and back. You can move on tracks other than the concentric spheres, in all six directions of space:
 Pressing left mouse key:
 Move left/right:        Observer moves left/right
 Mouse forward/back:     Observer moves forward/back

 Pressing right mouse key:
 Mouse forward/back:     Observer moves up/down
Whenever you are lost, press 'r' or 'R'. (One of the more essential inputs to remember.)
c Change objects. The program loads all objects. The user may choose one of them which then will be juggled.
d Distance shading. Objects getting darker when they are farther away.
e Set speed to 0%. The presentation stands still and will resume 100% speed when you press 'w'.
E Set speed to 50%. (See 'e' and 'w'.)
f Show flightpaths of objects. Press 'f' again to switch the same flightpath off. Press TAB to select the next object and f to see its flightpath. All flightpaths off with 'R' or 'F'. 'a' shows the current object.
FSwitch off all flight paths.
g Glowball mode.
h make hardcopies. The current screen is dumped into a file. The destination directory is specified in the jongl.prefs. It MUST end with a '/' or '\'.
i simulates infrared vision equipment. The sun is switched off (automatically) and a blurred and strange-coloured picture is shown. Very funny in connection with 'v'. Lots of activity in the presentation will improve the effect.
j Spread juggling props on the floor. Just to simulate convention feeling.
J Toggle JonglRemoteControl window.
k Vomiting mode. You are flying 50 cm (1.6404199 feet for you non- Europeans) behind an object chosen at random. Why this is called the vomiting mode, will become apparent latest during the sharp turns while the object is in hand. Press TAB to go to the next object.
K Toggle coordinate system which is useful for debugging new patterns.
l Switch to next language.
m Toggle mirror mode (reflections on the ground).
M Toggle height scale. One line is 1 metre. The red lines are 5, 10 and 15 metres.
n Toggle fog mode.
o Allows to move the sun in azimuth and elevation, in other words, the direction and the angle above the horizon from which the sun is shining. This will change direction and shape of the shadow.
O Same as 'o', but with light cone.
p Present POSITION of the view point (B=..) and of the observer (G=..) is inserted in the pattern file. When the program is started again, the performance will be seen with this new viewing angle. (Explanation of the parameters see further down, under 'pattern files'.) If you changed the juggled objects interactively, the chosen kind of object will be saved, too. After insertion of the parameters the program continues to run.
P Save last siteswap pattern in jongl notation. The destination directory can be specified with siteswapsavedir = ... in the jongl.prefs.
q Toggles flight queues. Or you can call it motion blur. Fucking slow.
r RESET for view point. (if you have fiddled around too much with the above functions...)
R RESET for everything. (if you have fiddled around even more)
s Switches shadows on the ground.
S Switches shading of the jugglers and objects.
t Toggle FPS and Speed display.
u Toggle the status line.
v Keep an eye on one object while the position of the observer remains unchanged. The object is first chosen at random but may be changed step by step with TAB.
In addition feel free to change the observer's position using the mouse... until you are lost!
Or you may, before starting this mode, press a function key on the numeric pad and have one of the jugglers keep an eye on one of the objects.
w Reset speed to 100%. (See 'E' and 'e'.)
W Toggle full screen mode.
x (not Windoze) export animation in one of the following formats (use pop up menu to select)
MPEG or FLI or AnimGIF.
The destination directory can be set via 'hardcopy=' in jongl.prefs
X export Raytracing data for POVRAY. The destination directory can be set in jongl.prefs.
y Show additional information in additional window.
zChanges objects into letters or characters or vice versa. Useful for debugging. (Will be explained later.)
Z Toggles inline comments. If this pattern contains inline comments you can see a short text at some objects on some flight paths. (Currently, this is very rarely used.)
1...9,0 on the main keyboard puts juggler number n into the center. The observer may then wander around each of the jugglers while they are passing. Switch off with 'r' or 'b'.
F1 .. F10 beams you into the head of the selected juggler. This will prepare you for the feeling that you will have when juggling 15 chain saws all by yourself...
TAB switches from object to object while "keeping an eye on" it. (See 'a', 'k' and 'v' and 'f')
+ - play animation faster / slower by 10%
> < play animation faster / slower by 1%

It is up to the user to find out how many of these modes he can handle simultaneously.
(NKP means numeric keypad)

Keyboard layout in editor mode:

eToggle between editor mode and viewpoint mode
jAdd a static object to the scene.
JAdd a juggler to the scene.
rReset view. For best control while moving objects.
0Set current object to height Z=0.
TABGo to next object.
DELDelete current object.

Most of the 3D mode keyboard assignments still work in editor mode.


Exporting hardcopies and animations

Currently (Jongl V14.0) this feature does not work using Windows, because I am not able to get proper hardcopies from the OpenGL subsystem.
Featurekey shortcutset path in jongl.prefs with
Hardcopyhhardcopy=
MPEG2x(1)tmp=
Animated GIFx(1)tmp=
FLI Animationx(1)tmp=
Povray Datashift-Xpovout=

All of these capabilities are accessible via the "Export" pop up menu, too.

The size of the resulting snapshot or animation equals the current size of the 3d window. The speed of the animation will be the speed of the realtime 3D display (e.g. [100%]).

When exporting animations, be sure to read this first. It will save lots of time and disk space.

Some of these features may be deactivated depending on your operating system.

(1): Use jongl.prefs parameter anim= to set which of these 3 formats will be written when the key x is being pressed.

There are more parameters in jongl.prefs which control animation export.
One of these is as which stands for "animation scale". David Byers (who implemented this) explains it:
If you use as, every frame is scaled using pnmscale, so the result is an antialiased version of the original frame. For example, if you specify as=50, then it is equivalent to 4x oversampling of the scene. This oversampling is pretty important if you're scaling down to a very small size, like I do for the videos for Isaac Orr. If you scale the image by just making the 3D window smaller, then the end quality of the image is far, far worse.

If you use as be sure to set a compatible window size in jongl.prefs, because Jongl makes no attempt to resize the 3D window.


Parameters for the command line

You can start Jongl with the following parameters. All of these parameters are optional; the sequence doesn't matter.

jongl [-<object number>] [-<object name>] [--<s22j parameter>] [+<prefs parameter>] [<pattern>]

Here some examples:
> jongl Brings up a file selector -> select a pattern to start
> jongl 5 Starts pattern 5 (really this is file m/5)
> jongl +textures=0 Overwrites the parameter textures in jongl.prefs . Thus jongl will start without texturing. The file selector pops up.
> jongl -24 3_801 Starts pattern 3_801 (m/3_801) with object #24 (see list_of_objects to see which number belongs to which object)
> jongl -knife 6 Starts pattern 6 (m/6) with knifes (v/knife.wrl)
> jongl 66161 Starts Jongl with the siteswap pattern 66161. There is no file with the name "66161" therefore the converter s22j is called automatically.
> jongl --hcr 4.55.5 Starts the siteswap converter s22j with the parameters -hcr 4.55.5 and afterwards invokes Jongl.
> jongl order <n>Show all patterns of Jongl in order, every n seconds a new pattern.
> jongl random <n>Runs Jongl in random mode: a new pattern every n seconds.
> jongl benchmark1
> jongl benchmark2
> jongl benchmark3
starts one of 3 benchmarks to compute your computer's speed. Check out the complete benchmark list here.


Format of the files read in

All files are in the ASCII format. Any amount of whitespace may be included. Even empty lines are allowed (almost) everywhere, except within the definition of the pattern (after the *, see further down).

In this context we distinguish between Old Object files, VRML Objectfiles and Pattern files.

VRML Object files

Jongl V8.0 supports VRML objects and old objects; Jongl V9.0 and newer support only VRML objects. Jongl should be able to read VRML output written by the following software: AC3D, Cinema4D, Wings3D V0.98.29, PTstereo; 3ds max works partly. If you need support for another programs output, please let me know.
There is no complete support of the very complex VRML syntax. Personally I use AC3D which is a very good shareware 3D editor with a reasonable price. It is able to export VRML2 files and Jongl is able to read them. There is support for colors and normals and textures. See the lists_of_people and jongl.prefs for details about displaying VRML objects.

Making your own objects:

Have a look at the objects in the v/ directory. The names of the objects have to match those in list_of_objects except for the added extension .wrl.
Jongl needs some data which is not present in the VRML code: This data comes in a comment and starts with JONGLDATA followed by one or more of the following items:

Flying objects:

commandexamplelegal valuesmeaning
gg=-0.2(float) numberTells Jongl that a juggler grips this object at -0.2 m below the center (0/0/0)
rr=10 or 1Means that this object is rotating when thrown (like a club)

tt=b b (ball)
c (club)
r (ring)
Specifies the catch type. Currently there are two possible usages for this:
a) You define a ball which is NOT made of a Sphere. To specify the radius of this ball, use the r= option. See the object file v/ball_standard.wrl.
b) For non rotating objects it is important to set the t=b and r= parameters. See v/beermug.wrl.
randomcolorrandomcolor
randomcolor=1
optional (int) 1..4Use random color for this object. If a parameter is given, then use the same random color for more faces of the current object (see v/renegade_ring.wrl)

Jugglers:

commandexamplelegal valuesmeaning
hairhairno parameters neededUse random skin color. Use this if you want the hair color to be automatically generated.

skinskinno parameters neededUse random skin color. This is mandatory for all parts of the body where you can see the skin.

textex=backfront, back or colorUse texture defined in list_of_shirts: frontBitmap or backBitmap.

Or use shirtcolor defined in one of theses textures. This is to be used in parts of the shirt which do not contain a logo, e.g. the arms.

Using your own textures:

Jongl is able to read textures in PNG and binary PPM formats.

This product includes software developed by Greg Roelofs and contributors for the book, "PNG: The Definitive Guide," published by O'Reilly and Associates.

The PNG may contain an alpha channel. That is useful to make e.g. trees. The width and height of the texture have to be a power of 2 and they should not be larger than 256 pixels. (Or Voodoo cards are not able to display them.) However the texture does not have to be a square.

See the file list_of_shirts.EJC for an explanation about how to make your own shirts and publish them.

Here is a list of limitations of the Jongl parser:

If you prefer a VRML editor which writes files not compatible with Jongl, please send some object files. If possible, I will add support for those, too.
The AC3D objects are available for download at the platform independent section of the Jongl download site.
I recommend to include the Jongl comments (see above) in the names of the objects (e.g. Blade JONGLDATA r=1). Again, one unit equals one metre.

Pattern files

A pattern file defines the pattern to be juggled. Its contents are thus the basics of the input. The pattern files are kept in the directory m/. When you start jongl with a pattern file which starts with a number (0 ... 9) then jongl assumes you want to see a pattern from the directory m/ (e.g. > jongl 5). If the pattern name doesn´t start with a number, jongl doesn´t change the path of the pattern file (eg. > jongl /zip/patterns/5).

First we define various optional parameters, then the mandatory positions of the people and finally the pattern.
It is IMPORTANT that spaces within one parameter are not allowed. Instead of dt = 0.234 you must write dt=0.234.
However I would like to introduce the convention that every pattern name starts with the number of objects and that it is divided into reasonable sections using underscores. The name of the pattern should not be chosen too long.
Pattern files can thus be compiled from the following components:

    Variable parameters with defaults 
                  Optional parameters 
                     Pattern comments 
            Positions of the jugglers 
                   Pattern definition 
                             Bouncing 
           Kind of throw, spin, angle 
If you want to write your own patterns, please have a look at the patterns in m/examples, because there are many patterns in the m directory which use more or less old syntax and should not be used to create new patterns.

Variable parameters with defaults

With these parameters you can influence the happenings. But it is not 
necessary to adjust them as they have already reasonable initial values.

a=6     Type of objects to be thrown around. (Numbering see the file
        'list_of_objects'.)

B=1.0,1.0,3.5,185.0   With this parameter you can define the position of
        the observer. The values describe the viewing angle from which you
        look at the scene
        If you have interactively achieved a nice viewing angle, just
        press 'P' and the above values are entered into the pattern file.
                      
dt=.25  Time elapsed between two lines of the pattern definition. With
        this parameter you can adjust the height of the throws, while
        the program is not yet able to do it itself.

eps=.95 Reflection quality of bouncing balls, standard is 5 % loss.
        (important: eps>0) We refer here to the loss of velocity during
        reflection. Height loss goes with the square of loss of velocity,
        as the potential energy m * g * h is equal to the kinetic energy
        (m * v squared)/2. If the cinetic energy is reduced by 5 %, then
        the ball reaches only 0.95 squared = 0.9025 of its initial height.
        So if you want the ball to spring back to half its initial height,
        eps is equal to the square root of 0.5 = 0.707.

g=9.81  Gravity constant in metres per second sqared. (Equivalent to
        32.2 feet per second squared which may sound more familiar to 
        you.) Positive values relate to acceleration downward.

G=x,y,z Sets the centre around which the view rotates.
        Mostly this value is set by the program itself after the user
        pressed P (see Keyboard)

l=1.2   Longer keep-in-hand times. According to the basic design of this
        program, the juggler would never hold an object in each of his
        hands at any one time but only alternating left and right. This 
        is not so in reality. Most of the time you have all your hands 
        full and only then do you throw something away, when you have to
        catch something shortly afterwards. In order to bring a bit of 
        reality into this simulation program, the duration of the keep-
        in-hand time can be adjusted. Default values are catching 20 % 
        earlier and throwing 20 % later (which logically adds up to a 
        total of 40 %). 

s=.1    Scatter of the throwing and catching motions. To make the juggling
        performance look more human (that is more imperfect), the motions
        vary within a cube with a side length of '2*s' around the proper
        catching and throwing position.

Z=0.0   With this parameter you can adjust the height of the observer
        above the floor. If you enter Z=0.0, then the 'eye' will be in
        the centre of that part of space that is occupied by static,
        throwing, flying, catching objects...      Sorry, there is an 
        explanation more simple than that: This parameter defines the
        height of the centre of the sphere on which the observer moves
        around. This centre can be changed to any value while the program
        runs, by pressing 'B'.
        After reading this long paragraph you are sure happy to see
        that Z= is obsolete and was replaced by G= (see above).

The values given in these examples are the default values in the program.

Parameters no longer needed

These parameters have been used prior to V6.0. Now they are ignored.
h=4     number of hands. 

o=6     number of objects.

q=0     Quick presentation. Normally off, if needed set q=1 (=on).
        Accelerates the graphics during the times of high life on the
        screen. (To be more precise: People become juggling coat hangers
        and all that's left of the tile floor is its edge.) If further
        acceleration is needed, the flying objects can be reduced to
        just a few points and lines. This has been moved to jongl.prefs.

t=32    number of lines in the pattern.

u=5     Frames per phase. To make the motions look more easy flowing,
        every phase defined in the pattern (see below) is divided into
        several frames. Here is where you define the number of frames.
        The value depends on the processor and on the complexity of the
        scene. Too many frames will result in a slow motion movie. 

Optional parameters

These are parameters without default values, because there are no 
reasonable default values.

    Different objects in one pattern   for juggling experts
                         Hand macros   for different hand positions
           Additional static objects   for miscellaneous junk
     Controlling animation rendering   for vastly reduced rendering times and file sizes

                                  up   to Pattern files


Different objects in one pattern

O=6 1#21 2#6 3#4

This parameter replaces both 'o=' and 'a='. It allows you to get a mixture of objects into the air. In the above example we have six objects, in fact once no. 21 (axe), followed by twice no. 6 (ball) and thrice no. 4 (club). The numbers have to match, in this case: 6=1+2+3. The sequence of objects is determined by the sequence of their appearance in the pattern definition, as the following example shows:

-a
d-
-b
e-
-c
f-
....
In this case the object with the letter 'a' would be a axe, 'd' and 'b' would be balls and 'e', 'c' and 'f' would be clubs. You see, the program takes the objects in the sequence as they appear in the pattern file, not by alphabet or by the value of the figures.

Hand macros

With hand macros, different hand positions can be defined for single throws.

Example:
@A p 0 .5 1     

or

@B P 0 .6 1  0 .3 1    
The letter @ is the leading letter for a macro definition of the hand position. (Just remember: @ = "at" indicates the position.)

The letter immediately behind @ is the command for calling up the macro. I recommend to use upper case letters as opposed to the lower case letters normally used for the pattern.
The following letter is either a small or a capital p. Then follows, as described further down, the definition of the hand position (no matter, whether left or right). That means we can define separately a catching position and a throwing position.

IMPORTANT: The position(s) of the juggler(s) as defined below have to be added nevertheless. Each hand macro may only be used by one hand. -> 3_Boston_Mess requires two different hand macros for the center position; one for each hand throwing there.

According to the basic program each hand always repeats the same motion, regardless where it throws what. This command provides different hand motions for different throws, e.g. Splits or Tennis or Boston Mess.

Example: '4_Spagat' which would be '4_Splits' in english

h=2 o=4 t=4 dt=.22 u=6 s=.1 
p 0
0  .6 1        %  Here we define the outer positions
0 -.6 1
*
1 A2
-  -
B3 4
-  -

Relative Hand macros

Starting with V9.0 you can use relative values to define the positions of the hands. Just add a rel between the first two parameters:
@L rel P .1 0 1  .1 .4 1
@R rel P .1 0 1  .1 -.4 1
The point 0/0/0 is at floor height between the hands of the juggler. It is the same point where the juggler is being placed by the program.
With some amount of skill and patience you can even achieve lead tricks...

Additional static objects

It is possible to define additional objects which do not move:

z=2
o/basic/Bierkiste
  90
  -2 0 0
o/basic/Giraffe
  0
  2.1 0 0
Behind 'z=' we fill in how many objects we want, then comes the path for the file to be read in (in object format as described above). Next is the rotation around the z axis in degrees which allows us to adjust the object as desired, and finally the x,y,z coordinates where the object is located.

Presently static objects can only be defined after the positions (p or P) of the people have been defined!

As mentioned earlier, the object names have not all been translated.


Reduce animation rendering time and file size

r=2 Set repeat value. This describes how many pattern lines are required until all flying objects have exactly the same positions and directions as before. This is to reduce animation rendering time and produced file size, typically by about 90%. It is useful for MPEG-, GIF- and raytracing-animations. See example files 'm/7_2cnt_sng_trp' and 'm/8_PPS'. It also implies an automatic 's=0' to get smooth cyclic movements.
Be sure to deselect objects in random color, otherwise the object colors will switch from one color to another.
See Exporting hardcopies and animations for more information about this.

Pattern comments

Two types of COMMENTS may be included in pattern files: those which will
be shown on the screen and those which are only comments to the program.

! Anything behind an exclamation mark will be shown when the program runs.

% Comments behind a percent sign only serve for orientation in the
% program and will not appear during the performance.

Comments have to end at the end of a line, but they do not have to start 
at the beginning of a line. In the pattern definition they must be to the 
right of the definition. Example see further down.

Positions of the jugglers

There are three possibilities to define the POSITIONS of the jugglers: 'j', 'p' and 'P'.
In most cases you want to use 'j' which is much shorter but not that flexible.

Example:

j 15 1.2 -0.4 0 c r
means that the juggler is rotated by +15° around Z. He stands at (X=1.2 m; Y=-0.4 m; Z=0.0 m). The left hand throws cascade (c), the right throws reverse cascade (r). The complete list of valid keys is:

keythrow standard positions for left hand: X / Y
catch throw
bbackcross -0.2 / 0.6-0.8 / -0.2
ccascade0 / 0.4 0 / 0.2
C or rreverse cascade0 / 0.2 0 / 0.4
ffountain0 / 0.3 0 / 0.3
Sreverse shoulder-0.87 / 0.3 -0.2 / 0.3
I hope this list will grow longer. More use of these keys is at Kind of throw, spin and angle. Invert Y to get positions of right hand.

More details can be achieved with the p commands: The small 'p' is the simpler version in which the hands are catching and throwing at the same position. With 'P' different catching and throwing positions can be defined, which allows for instance to distinguish between cascade and backward cascade.

The next parameters after 'p' or 'P' are the rotation angle about the Z axis (in degrees) and then the 3D coordinates of the position. With a rotation angle of 0° the juggler looks straight ahead in the +X direction, +Y is to the left and +Z is upward. With 90° the juggler looks in the +Y direction.

Please note that the mean value of the Z coordinates of the hands of each juggler should be as close to 1 as possible, because that is where the program puts them. Furthermore the body will be put in the middle between
left and right hand. This will cause problems if you want, for instance, to define "Splits". In this case you define either both inner hands or both outer hands normally and the other two with '@' (see further above).

Examples:
p 0
  -1  .5 1
  -1 -.5 1
*

P 0
  -1  .5 1.2  -1  .2 .8
  -1 -.5 1.2  -1 -.2 .8
  180
   1 -.5 1.2   1 -.2 .8
   1  .5 1.2   1  .2 .8
*
As you see, the definition of the positions is concluded with an '*'.

Now we come to the Pattern definition.

Pattern definition

The pattern is defined in exactly as many columns as hands are involved. You may include as many spaces between the letters as you wish, but NO EMPTY LINES AND NO LINES WITH COMMENTS ONLY ARE ALLOWED!
A simple example is one juggler doing a cascade with three balls:
 a-  ! left hand throws object 'a'
 -2
 E-
 -a  % right hand catches 'a'
 2-
 -E
The dash '-' means that at this point in time the relevant hand is empty. The columns refer from left to right alternating to the left and right hand(s). (Important for writing passing patterns!)
You may choose almost any letter for the objects; all letters except '-', '&', '!', '%', '*', '/' and '\' are allowed. That's why the example looks so weird. However I recommend for use in patterns the sequence 1,2,3,4,5,6,7, 8,9,a,b,c,d,e,f,g... Capital letters should be saved for macros (@), to maintain a bit of transparency. Don't use anything else but numbers and lowercase letters; we may need them for any later program expansions...
You see also examples how to use comments. The program will not show comments which are to the right of the pattern definition.

You always need a '-' between two different objects in one hand:

- a
- b
This was wrong!

- a
- - 
- b
Thats correct!

Bouncing

In real life there are two types of BOUNCING: throwing the balls upward (lift bouncing) or throwing the balls downward (force bouncing). Both types are covered by this program. It is also possible to have the ball bounce more than once before catching it again.
For bouncing we have to introduce by two additional letters, '/' and '\'.
Throwing upward: '/'. Example:
 - 1
  /2-
  - 3
  1 -
  - 2
  3 -
In this case object 2 is thrown upward for one bounce.
The notation for throwing downward (force bouncing) is: '\'. Multiple bounces are noted by multiplying the relevant letters.
Example: Bounce shower:
  1-
  -\\1
  2-
  -\\2
  3-
  -\\3
Every ball from the right hand is thrown downward and bounces twice.
IMPORTANT: BOUNCING DOES NOT WORK WITH ANY ARBITRARY PARAMETERS! The program shifts the parameters if it is not possible to calculate suitable initial velocities with the inputs given. First it reduces the number of bounces, and if that is still not enough, it goes from lift to force bounce. If you don't want that, increase the dt= value in the pattern file.
If you want to bounce non-integer throws (like 5.5), you have to add the bounce prefix to *every* line, including the holds. See a piece of 13_1cnt_BouncePass for this:
  
  .
  .
  /1 /8  - /b
   - /8 /5 /b
  /2 /8 /5  -
  /2  - /5 /c
  /2 /9  - /c
  .
  .
Bouncing in combination with hand macros works only if they are given in the right order: 1st the bounce prefix, then the handmacro:
  .
  .
  /L2 \5
   -  -
  \1 /R3
   -  -
  .
  .

Kind of throw, spin, angle

These are new to V7.0.

Let's have a look at this rather complicated looking pattern: The scissor pattern is a sync 4 club pattern in which a backcross and a "frontcross" are thrown in sync. After a left backcross follows a right backcross. The frontcross flies parallel to the jugglers body.
This pattern here has (for demonstration only) 4 different spins on the clubs, i.e. a flat, a single, a double and a triple.

! scissors with 4 clubs
dt=0.350 a=14 
j 15 0 0 0 c c
*
(b0)1       (z90*0)2
 -           -
(*1z-90)3   (b1)4
 -           -
(b2)2       (z90*2)1
 -           -
(*3z-90)4   (b3)3
 -           -
As you have noticed, the parameters are in round brackets in front of the corresponding throw. To be legal, a set of parameters must consist of 1 character and a trailing number.

characteractionnumberexamples
b,c,C,f,r,Skind of throw (see here)number of spins or * for default(b*), (f2)
zrotation of club around Z axis (points up)angle in degrees (front=0,left=90)(z-90)
*use default kind of thrownumber of spins(*0)

You see, (*3z-90) means: use default kind of throw (*) (which in this case is cascade, because of j 15 0 0 0 c c ), throw a triple (3) and point the club to the right (z-90) before the throw.

For another example, see: 11_2cnt_3_Person_Show


Multiplex and wrap around

Multiplex is deactivated since V6.0. Wrap around was deactivated in V7.0.

Here we have a more complicated example with some new commands:

'm/8_MPlex_Pass'

 *
   8 1&2   - 3
   8   -   5 3&4
 7&8   6   5 -
   -   6 5&1 2
   3 4&6   - 2
   3   -   7 2&8
 5&3   1   7 -
   -   1 4&7 6
 *
 12345678
 18475362

You may notice between one and two new features:

a) Multiplex.    With the letter '&' you can hold more than one object at a
                 time in one hand. To be more precise: as many as you want.
You may catch them at different times and throw them away together (which 
is realistic) or not (which is unrealistic). 
        
b) Wrap around.  This is shorthand writing for patterns which look as if 
                 they repeat themselves after a short time, but then they
have different object numbers. Understood? Well, take passing in four-
count (pass every second right hand one). If you write down how long it 
takes until all the objects are again where they started, then you realize 
that you have to do a lot of writing! It is much easier with wrap around: 

 *
 -1 -4
 2- 5-
 -3 -6
 4- 1-
 -2 -5
 3- 6-
 -4 -1
 5- 2-
 *
 123456
 561234
In detail:

Behind the pattern definition we have another '*'. The next line lists all the objects used in the pattern in any arbitrary sequence. The line below shows the replacements of the relevant objects. Let's look at the example: In the first line after the lower '*' the first figure is 1. The figure below that is 5. This means as soon as object number 1 drops out of the bottom of the pattern file, it comes back in at the top of the file as number 5. Object number 5 will be replaced by object number 3, and so on. This wrap-around trick saves ages of typing work. You only need to note each throw at least once and then concentrate on the wrap- around table.

See also 10_H_Mult_bounce with the notation '/4&R9' and think about it!


3D Editor

Starting with Jongl 9.0 there is an editor where you can interactively set the juggling scene. Invoke the editor using the pop up menu (right mouse button) and select Program->Start Editor or press CTRL-e.

Now you have a different pop up menu; the flying objects are hidden. Currently you can add or delete some jugglers and move them around. The pop up menu enables you to change the hand movements for each hand separately. See Kind of Throw. The real movements of the juggler's arms change when you leave the editor.
Also, you may add some static objects like a ladder or a beercase. Optionally you can place jugglers on top of these static objects.
The keyboard layout slightly changes in editor mode. Mouse control is explained here.

I recommend the following procedure:

Now you have a juggling pattern with jugglers positioned exactly where you wanted them to be.

You might want to place the jugglers in an existing pattern somewhere else. Just invoke jongl with that pattern, use the editor to move them around and select Save Scene And Quit.


Listings of external files

Here comes a list of external files (which was up-to-date at some point in time way back) which is needed by JONGL:
jongl.prefsV9 contains settings
lists_of_people defines different types of jugglers
list_of_objects all kinds of throwable parts
pano/ (dir) contains data for panoramas

jongl.prefsV9

Starting with Jongl V9.0 you don't need to change this file by hand. There is a GUI which enables you to choose everything you need without using an editor. The bit outdated content of the file jongl.prefs is described here. But probably nobody wants to know this.

lists_of_people

Due to the different types of objects (old ones and VRML), we need a couple of different lists for jugglers. Advantage: when you create a new juggler, you do not have to create the same juggler in the other object format or with less polygons (quick mode).

nice objectsquick objects
old objectslist_of_Oldjugglerslist_of_OldQjugglers
VRML objectslist_of_VRMLjugglerslist_of_VRMLQjugglers

Example for list_of_Oldjugglers or list_of_OldQjugglers :

.................................................
9
RedYellowJuggler
BlueJuggler
Charlie
CharlieWithHat
Blondie
Punk
Peter
JugglerWithSkirt
MichelinMan

Skeleton   (Problems with Tesselation on Mesa)

Roboter_B
................................................

The first line shows the number of jugglers. The next lines contain one file name each from the directory 'o/basic' or 'v/basic'.

There is a way to manipulate the program: If you don't want to see some types of jugglers, move them to the end of the list and reduce the value in the first line such that only those people can be selected by the program who are welcome to the user.

The files which control VRML jugglers differ a bit (Example for list_of_VRMLjugglers or list_of_VRMLQjugglers):

.................................................
2   # jugglers without textures
redJuggler
greenJuggler
1   # juggler with static texture
EschenbachJuggler
1   # parametric juggler with different textures 
TShirtJuggler
1   # parametric juggler with winter clothes, no textures
winterJuggler
.................................................

First part: 3 jugglers without textures.
Second part: 2 jugglers with fixed textures. That means, that exactly these textures are on these jugglers.
Third part: 1 juggler whose textures are computed by a random selection from list_of_shirts. See the comment directly in that file for more information about that. Fourth part: Data for jugglers wearing winter clothes.

list_of_objects

An example for a list of objects is this:
.................................................
0:  cube           
1:  flag           
2:  ring_simple    
3:  ring           
4:  cluster        
5:  club_standard  
6:  ball_random    
7:  hat            
8:  racket         
9:  guitar         
10: beercase       
11: pancake        
12: bouncingball   
13: basketball     
14: club_wood       
15: torch
16: stick          
17: knife          
18: chainsaw       
19: pottedplant    
20: plate          
21: axe            
22: threepikes     
23: club_3colours  
24: club_fine      
25: coffin
26: baton          
27: club_quick          
28: beermug        
29: bomb           
30: club_random
31: ball_yellow       )    
32: ball_beige        )
33: ball_dark_green   )   colours
34: ball_light_red    )
35: ball_pink         )   1
36: ball_light_blue   )
37: ball_light_grey   )   through
38: ball_white        )
39: ball_orange       )   15
40: ball_brown        ) 
41: ball_light_green  )
42: ball_dark_red     )
43: ball_purple       )
44: ball_dark_blue    )
45: ball_dark_grey    )
46: bottle                  
47: ring_random             
48: child
49: renegade_ring           
50: ball_yellow_l       )   
51: ball_beige_l        )
52: ball_dark_green_l   )   colours
53: ball_light_red_l    )
54: ball_pink_l         )   1
55: ball_light_blue_l   )
56: ball_light_grey_l   )   through
57: ball_white_l        )
58: ball_orange_l       )   15
59: ball_brown_l        ) 
60: ball_light_green_l  )
61: ball_dark_red_l     )
62: ball_purple_l       )
63: ball_dark_blue_l    )
64: ball_dark_grey_l    )
65: bigring                 
66: pizza                   
-1: EOF
.................................................
The figures indicate line numbers. The texts are the file names of the objects in the directories 'o' (old objects) and 'v' (VRML objects). Since the program assumes that the second string in each line is the file name, it is important not to use any spaces in the object names.
Note that the VRML objects need a extension .wrl which does not show up in the list_of_objects.

pano/ (dir)

This directory contains the data for the panoramas. Use the following file format and Jongl is able to use it without any other change.
pano/  [1]
  Chessboard/  [2]
    Karoboden.wrl  [3]
    properties.dat  [4]
    thumb.gif  [5]
    ... [6]
		
[1] All the files go into the directory pano/ which is in the Jongl directory.
[2] You may name the folder of your panorama as you like.
[3] This contains the VRML data. The name must not be changed. I suggest
you use one of the files of this name in the Jongl distribution.
[4] Optional file. The name must not be changed. Each line of this text file
contains one value. Possible values are (without double quotes):
	"no textures"  (this panorama uses no textures)
	"winter"  (juggler wear winter clothes)
	"g=3.71"  (change gravity; in m/s²; used in mars pano)
	
[5] Contains a screen shot of the panorama in GIF, size 70x70 pixels.
This will be shown in the select window in the Jongl GUI, register tab "Settings".
[6] You may add more files, e.g. containing PNG images for the panorama.
Ludwig Klam made a lot of nice panoramas. Get them for free from his homepage.

The end. Check www.jongl.de for new versions.
Please send your thoughts, bug reports and money orders to w e r n e r   a t   j o n g l   d o t   d e