Balls XML

General Overview

Every Gooball starts with the ball tag with a series of attributes (name, shape, mass...)
Inside the ball tag may live the following tags:
part : defines the balls appearence (usually the first part is the body image, followed by eyes and other features).
marker : definition of the cursor when pointing at a ball, or detaching it
shadow : a shadow image/overlay that only shows above geometry.
particles : defined for various states such as sleeping or falling, it adds a particle effect above or beneath the ball
strand : the parts other balls walk on, mainly the definition of the structures physics this ball will form
detachstrand : image and length of detaching visualisation.
splat : drops of this goo, shown when the player clicks on or releases this ball and when it dies.
sound : the soundeffects for various events (attach, throw, death...)
sinvariance : animations of the bodyparts in different states (walking, falling, sleeping...)

All these tags are (strictly) optional and which are present depends on the ball's type.
A ball with no part tags will be invisible, a ball with no sound tags will be silent... etc.
For descriptions of these tags, and more detailed explainations on their attributes... follow the links.

Balls also have a state which indicates what the ball is currently doing, and events which are things that can happen to a ball.

Contents

Core Attributes

These attributes are always (or usually) required for any normal functioning ball.

name : Required
This is the unique identifier for the ball type. It must be unique in the game. It should also exactly match the folder name in which the files are held, and the id entry in the resources file.
shape : Required : Examples: rectangle,100,100 circle,30 circle,50,0.25
This defines the shape and size of the solid part of the Goo Ball, it's geometry.
To specify a square or rectangular ball rectangle,{width},{height}
To specify a round ball circle,{diameter}
An optional variation number may be included as the final parameter. This number defines the variation in size of the balls and thickness of the strands. It can be in the range 0 -> 1, although values above 0.5 are not recommended.
If 0 is set (or is omitted) all balls will be exactly the size specified, If 1 is specified the balls will range randomly from (almost) 0 -> 2 x size The "original" balls used numbers in the range 0.1 -> 0.3
The variation can be included on both circle and rectangle balls.
mass : Required: Float : Examples 10,20,100,600
Defines the normal mass of the ball. See also towermass and dragmass
NB: Must be greater than 1 to avoid game engine crashes
strands : Required : Integer : Examples 0,1,2,3,4
The maximum number of strands this ball will attempt to connect when being attached to a structure.
This does not affect the number of strands which can subsequently be attached to it.
If 0, this goo will not attach to a structure.
If 1, this goo will attach to a structure with only 1 strand.
If 2 (or more), this goo will only attach if 2 (or more) strands can be formed.
material : {Material Name} : Default (unknown)
The material the ball is made of.
towermass : Required : Float : Examples 3,5,10,200
When a ball is "climbing" on a structure, it can have a different mass to when it is walking on the ground.
Most of the original balls have a towermass approx. 1/3 -> 1/10 of their normal mass
Note: This value can also be negative... with "interesting" results.
NB: Must be greater than 1 (or less than -1) to avoid game engine crashes
dragmass : Optional : Float
Defines the masss of the ball while the being dragged by the player.
Only used on Blocks and Windows balls, and only affects how the ball reacts while being dragged.
NB: Must be greater than 1 to avoid game engine crashes, "low" values (<5) cause a glitch when the ball is dragged near an open pipe.

Behaviour Attributes

These attributes govern the actions of the Goos when they are "left alone"

climber : true / false : Default = true
Will jump onto and climb on strands NB: Interacts with climbspeed to determine if ball actually climbs or not.
If climber set to false.. the ball will not climb or grab onto strands
If set to true (or omitted).. climbing behaviour is determined by climbspeed
antigrav : float : Default = Not antigrav
Antigrav force multiplier when this ball is attached and in a forcefield with antigrav=true
In a gravity field : Produces an upward (against gravity direction) force = antigrav * mass
eg. Balloon : mass=20 antigrav=4.5 produces a force of 90, just sufficient to lift 3xcommon balls mass=30)
In a force field : mass is irrelevant and will lift antigrav Goo Balls regardless of the type or mass.
eg. Balloon : antigrav=4.5 will lift a structure made of 4 balls of any type. Will not lift a structure of 5.
This value can also be negative, which makes the ball heavier when it is attached.
Has a special use on Ugly see Genetic Sorting Machine
isantigravunattached : true / false : Default = true
Antigravity force also applies when unattached
static : true / false : Default = false
The ball is fixed in position and cannot be moved. Used mostly for Anchors and Dispensers.
staticwhensleeping : true / false : Default = false
Fixed in position and immune to "kicking" when asleep
wakedist : float : Default = -∞ (no Wake)
Wakes sleeping Goos within the given distance
jump : float,float : Default = 0 (no jump)
Will jump in the air when they "walk" into another Goo Ball
The speed of the jump is random in the range given {min},{max}
jumponwakeup true / false : Default = false
Will jump in the air when woken, if jump values are specified.
autoattach true / false : Default = false
Attaches automatically. If strands>1 then requires 2 strands to attach
Will also form new strands (up to strands) with other attached balls after is it attached.
autodisable : true / false : Default = false
If set true, causes the ball to "freeze solid" once it stops moving, in effect locking it in place. The ball is automatically "unfrozen" if you pick it up and move it, or detach it from the tower.
Used only on Blocks and Windows in the original Balls
Causes the "floating block" effect when another block is removed quickly from a pile.
If visualdebug is enabled in a level, disabled / frozen ball show in red.
decay : float : Default = 0 (No Decay)
If specified, sets the "life span" of the Ball in seconds.
Once this time runs out the Ball will automatically die.
Timed from the ball's "creation", beginning of level, spawn / dispense, popping of its MOM

Movement Attributes

These attributes govern the Goo Balls motion

walkspeed : Float : Required
Nominal speed the Goo Ball will walk along the ground. Actual walking speed is affected by speedvariance
Set to 0 will prevent the ball from walking. Original Balls ranged from 0.05 -> 0.15
climbspeed : Float : Required
Nominal speed the Goo Ball will climb along strands. Actual climbing speed is affected by speedvariance
Set to 0 will prevent the ball from climbing. Original Balls ranged from 0.9 -> 2.8
speedvariance : Float : Required
The variation in speed of walking and climbing from the "nominal" value. Can be in the range 0 -> 1
Set to 0, all balls will walk / climb at exactly the same speed
Set to 1, some will not move, some will "race" at 2 x nominal speed
Original Balls used either 0 or 0.2
dampening : Float : Default=0
Dampening factor for falling / flying movement.
Used on balloon-type balls to reduce fast movement and make them "feel" like the have air resistance.
Values above about 0.2 cause a glitch when throwing the ball quickly.
Original Balls used values around 0.1
walkforce : Float : Default={unknown} but seems to work for most balls
Some balls require additional force to be able to "walk"
Set to 0 to prevent walking,
Bone are set to 3000, common and common_black (and others) are set to 500
common_albino is not set... but is still able to walk OK.
thrust : Float : Default = 0 (No Thrust)
If set, then when attached, the ball will extert a force on the structure.
The thrust value is the magnitude of the force. Its initial direction is set when it is attached to the structure. Specifically, If the ball attaches 2 strands to the structure, then the thrust will be along the bisector of those 2 strands. If the ball attaches any other number of strands, the initial thrust direction will be random.
The direction is also affected by whether the thrust value is positive or negative. Postive values will usually push on the structure, negative values will tend to pull Image showing Thrust Direction for >0 and <0
Normally, the direction of the thrust is then fixed. Even if the structure moves or rotates, the thrust will remain in its initial direction. However, if the ball is also detachable, and has quite a large maxlen for its detachstrand then the direction of the thrust can be changed. Image showing fixed direction and detaching
A thrust value of 7.5 will (just) make a mass=30 ball "weightless" in a gravity field of 10.

Player Interaction

These attributes control how the Goos respond to the Player.

draggable : true / false : Default = true
These balls can be picked up by player
detachable : true / false : Default = True
Can be detached from a structure
hingedrag : true / false : Default = false
If False (or omitted) the Goo Ball is grabbed by its centre point
If True the ball is grabbed by whereever it is clicked, and will rotate about that point.
Set True on Blocks and Window Balls
fling : {Max Arrow Length},{Force Multiplier} : Default = (no fling)
fling is what happens to Bit and Pilot balls when you grab them.
The first number sets the maximum length of the shooting arrow.
The second number is a multiplier to calculate the force when the player releases the mouse button.
Original Balls used 200,2.5, setting 2.5,200 gives the same speed, but the arrow is almost invisible.
Because the multiplier calculates a force, lighter balls go faster than heavier balls with the same settings.
The image for the shooting arrow is set by the detachstand tag
NB: Balls must draggable to use fling

Level Interaction

These attributes control how the Goos interact with various elements of the level.. pipes, spikes etc.

invulnerable : true / false : Default = false
These Goos are NOT killed by objects tagged 'mostlydeadly' but they are killed by objects tagged 'deadly'
suckable : true / false : Default = true
If set to false, these Goos cannot be collected by the pipe
autobounds : true / false : Default = true
If set to false, these Goos have NO effect on the autobounds / explored area.
autoboundsunattached : true / false : Default = false
These Goos affect the autobounds / explored area even when unattached
sticky : true / false : Default = false
These Goos are always Sticky, and will stick to all geometry objects except those tagged detaching
Used on AnchorSticky and AnchorStickyInvisible
stickyattached : true / false : Default = false
These Goos are Sticky when they are attached to a structure. Used on BombSticky and Pokey
stickyunattached : true / false : Default = false
These Goos are Sticky when they are not attached to a structure. Only used on BombSticky

Other Ball Interaction

These attributes govern how the Goos behave when they encounter other Goos.

grumpy : true / false : Default = false
When set to true this Goo will not accept strands.
collidewithattached : true / false : Default = false
When set to true this ball will collide with attached balls. Used on Beauty, Ugly, Blocks and Windows
collideattached : true / false : Default = false
When set to true, this ball will collide with other attached balls when it is attached
Used on Balloons and Pilot
stuckattachment : true / false : Default = false
Set to true, allows strands to attach to this ball when it is unattached .. if...
this ball is also sticky, or sticky at the moment (see stickyattached and stickyunattached)
and is currently "stuck" to something.
Set True on AnchorSticky and AnchorStickyInvisible
Set False on StickyBomb and Pokey so you can't attach to them when they are not attached.
fallingattachment : true / false : Default = false
When set true, allows strands to connect to this ball when it is unattached and falling.
Never used (set to true) on any original ball.
For more information, see this reference page.
stacking : true / false : Default = false
When set to true, these balls can be stacked. Used on Blocks and Windows
Note: Stacking behaviour breaks down in range of an open pipe, and the blocks slide through each other.
This attribute also has another function. When set to true, the ball will explode / shatter when it dies, as if it were a geometry instead of a Goo Ball.
maxattachspeed : float : Default = unknown (but less than 1000)
The maximum speed the ball can be moving be attached to a structure.
Set to 1000 for Balloons, Bone and Pokey (All other balls default)

Cosmetic Attributes

These attributes control the Goos look, but do not significantly affect game play.

blinkcolor : RGB Colour : Default = No Blink
If set to a valid RGB colour, the Goo balls will randomly blink their eyes in this colour
If Invalid or omitted the Goo Balls will no blink.
hideeyes : true / false : Default = true
Shrink and hide part marked as eye when cursor is "far away"
Set to false the eyes remain open and "alert" at all times.
alwayslookatmouse : true / false : Default = false
Set to true the pupils follow the cursor
Set to false the pupils follow the direction of movement or stay still.
statescales : {statename},{scalefactor} : Default = {All States},{1}
Allows the Goos to change size when they are in a particular state.
Multiple states and scales allowed attached,1.75, detaching,1.3, tank,1.0
Each state must be a valid recognised value [ state list ]
attenuationselect / deselect / drag / drop : {Time},{ScaleFactor},{ScaleFactor},{ScaleFactor}....
These attributes define how the ball changes size in response to mouse actions.
The first number is the duration (in seconds) of the animation
The rest are a list of scalefactors, the ball will smoothly change between all these factors in the given Time.
attenuationselect : "Mouse Over/Hover" : Default ~ 0.2,1,1.25
attenuationdeselect : "Mouse Out" : Default ~ 0.2,1.25,0.8,1
attenuationdrag : "Mouse Down" : Default ~ 0.2,1.75,1
attenuationdrop : "Mouse Up" : Default ~ 0.2,1,1
To prevent the ball from changing size in this way set all 4 attributes to 0,1,1 (Blocks and Windows)
isbehindstrands : true / false : Default = false
If set to true, the Goo Ball is displayed behind any strands. Used on Beauty, Ugly and UndeletePill
distantsounds : true / false : Default = true
If true or omitted, sounds reduce in volume when ball is far away
If false the sound is the same volume wherever you are in the level
Only used on UtilProductLauncherScreamer to produce the "Gun Rising" sound effect.

Burn Attributes

These attributes control whether the Goos are flammable, and how the behave when lit.

burntime : float : Default = 0 (No Burn)
Number of seconds between ignition and explosion / death. Set to 0 to make the ball non-flammable
detonateforce : float : Default = 0
breaking Force at Goo location when it explodes. Set to 0 the Goo will not "explode" and will just die.
detonateradius : float : Required if detonateforce > 0
The breaking force reduces linearly from detonateforce at the center to 0 at this distance.

* This is related to the 'break=?' tag of geometry... but Shhh!


If geometry in the level has the break=X tag, it will explode when that much force hits the center of the object.
explosionparticles : {particle effect} : Default={None}
Additional particle effect on explosion, the ball also dies so "death splat" will also display.
Must be a Point-Source Non-Repeating particle effect.
flammable : true /false : Unused/Irrelavant.
Completely overridden by burntime in determing flammability. Only set FALSE on water

Popping / MOM Attributes

These attributes control whether the Goos are "pop-able", and what they contain

contains : {Number},{BallType} : Default = None (Not pop-able)
this ball contains other balls, which will pop into when it touches an object with 'ballbuster' tag.
A ball can contain a number of different balls 16,BeautyProduct,2,BeautyProductEye
The game will crash if this attribute creates a circular reference of ball type
ie. A ball cannot contain itself and a parent ball cannot contain a child ball which contains the parent ball.
popduration : float : Default = 1 (or 2)
Time takens for the "mother" ball to shrink away to nothing. Gradually over this time it releases its child balls.
Original Balls set to around 0.25, but can be longer.
popparticles : {particle effect} : Required if contains is set
Particles emitted when the ball is "busted" (also replaces death SPLAT with this effect)
Must be a Point-Source Non-Repeating particle effect
popsound : {Sound Resource} : Required if contains is set
Sound to play on pop
popdelay : {min delay},{max delay} : Default=0,0
Gives a random delay between min and max (in seconds) between the ball being "busted" and it popping.
Note: popparticles display immediately on "busting", popsound plays after the delay.

Dispenser Attributes

spawn : {BallType} : Default= None (No dispense)
Creates / Dispenses a ball of the given type when it is clicked

FallingAttachment

If you got here, that means you played my level: Stranded.
If not, you might want to play it before you read this, it has

SPOILERS!!!

The falling attachment attribute, when set to true on a gooball, allows strands to attach to it when it is falling/thrown. This means you can start a level with no existing strands within the scene limits! This can be quite interesting...

The first thing I want to show you is a single stand ball with the fallingattachment attribute set to true. One gooball can be attached to the other when it is falling, like so:

However! The ball that was attached to remains in a detached state even though it has a strand! Here is what I mean:

This means that particular gooball can be sucked by the pipe, this can give some quite amusing results:

This is why:

The unattached with strand gooball is eligible to enter the pipe, so it does, and drags the attached gooball with it! This can cause crashes (though not necessarily).

Now, let's check out the gooball I used in the level, the DynamAttach. This is how the attachment works:

However, if one of the two on the structure gets sucked by the pipe, the game WILL crash!

This is why I set this gooball to not be suckable.

The fact this gooball can both have a strand AND be in a unattached state, means the structure can roll around, which is quite funny! Also, if you click then release the gooball on this mobile structure, it will switch to an attached state. You will have noticed both of these while playing the level.

I hope you enjoyed my little explanation on this attribute! I'm looking forward to see such gooballs from you!

Parts

<part>

These tags define the visible elements of the balls. A ball can contain any number of part tags.
Balls with no parts area invisible.

name : string : Required
This is the unique name for the part. It is usually "meaningful" like body or eye.
It is used as a reference for the sinanim tags.
image : list-of-{Image Resource} : Required
Image to use for this part.
If multiple images given in a comma-separated list then one is selected at random for each ball.
x & y : float or min,max : Required
x and y define the position of this part within the ball. Usually the "body" part is set to x=0 and y=0
They can each be a single number, in which case the part is place in a fixed position.
However, each of these attributes can specify a range instead. If 2 numbers are specified then they are treated as a min and max value. The position of the part on each ball will be set randomly within this range.
layer : Integer : Default = 0
Defines the drawing layer / order of this part. Higher values are drawn over the top of lower values.
Unlike depth in the level model.. this must be an integer number and cannot be negative.
state : list-of-{State Names} : Default {All States}
This is a comma-seperated list of all the ball states for which this part should be drawn.
If omitted, then this part is always drawn.
scale : Float : Default = 1
Allow the size of this part to be changed relative to the others.
rotate : true / false : Default = false
Specifies whether this part rotates about the centre of the ball as it walks / moves.
Usually set True, but often left false on body and hilite images.
stretch : {speed},{direction scale},{across scale} : Default = No Stretching
This defines how the part will stretch as the ball moves when it is falling or being dragged.
The first number is a speed. The amount of stretching varies from "no stretching" when the ball is not moving to "maximum stretching" when it is moving at this speed.
The second number is the maximum amount of stretching in the direction of motion
The third number is the maximum amount of stretching perpendicular to the direction of motion.
The original balls uses values like 24,1.5,0.75 and 16,2,0.5
These produce the effect of the balls "stream-lining" when they are moving quickly.
eye : true / false : Default = false
Specifies that this part is an eye, and tells the game that following attributes should also be used.
If this is set to false (or omitted) the following attributes are ignored.
pupil : {Image Resource} : Required (if eye is true)
The image for the pupil
pupilinset : Integer : Default = 0
The distance from the outside edge of the eye to the pupil.
If this value is too low (size of the pupil or less) then the pupil will appear outside the eye image.
If set to a large value the pupil remains fixed in the centre of the eye.
Original balls used values 12-14, except for large balls like Beauty which used values up to about 60
xrange and yrange : min,max : Default (no Motion)
These attributes specify the range of motion of the part when the ball is moving, or bouncing off things.
The values are specified relative to the ball the same as the part position / range (x,y)
If omitted the part remains in a fixed position on the ball.
These are normally used only on "eyes" to give the "googly-eye" look, however they can be used on any part.
eg Beauty's lips and Ivy's leaves.

Strands

<strand>

This tag is optional in a ball.
However without it the ball cannot create strands with other balls, even if the ball's strands attribute is set.

type : 'spring' or 'rope' or 'rigid' : Required
This specifies what "real world" object the strand acts like.
Set to spring it will act like a spring and will resist being stretched or compressed.
Set to rope it will resist being stretched, but will simply collapse if compressed
Most of the original strands are set to spring, only Balloons, Pilot and Water are set to rope
NB: rigid type is valid, however so far it does not appear to function correctly, the strands are not rigid at all. If you want to experiment with 'rigid' strands you must also set the mass attribute.
image : {Image Resource} : Required
The image of the strand
inactiveimage : {Image Resource} : Required
The image used to show where the new strands will be added
minlen : Float : Default = 0
This is the minimum "natural" length of a strand.
If the new strand is shorter than this length when it is created the strand will expand to reach this minimum length.
The original balls use a value approx. 1/2 of maxlen1
NB: Must be LESS than both maxlen attributes... otherwise errors occur in the game.
maxlen2 : Float : Default = 0 (No strands can be created)
The maximum length of a new strand between the ball being "dragged" and another attached ball.
Strands can be created "slightly" longer but they will shrink down over a few seconds. (see also shrinklen)
maxlen1 : Float : Default = 0 (Ball-Ball strands cannot be created)
The maximum length of a new strand which connects two balls that are both already attached.
ie. where a new strand is made between two balls, but the ball you were holding "disappears".
The Original balls had values of approx. 0.7 * maxlen2. Values substantially different to this will cause "unfamiliar" building behaviour, but that's not necessarily a bad thing.
shrinklen : Float : Default = 140
Once the strand is connected will attempt to shrink to this length.
If this value is set to less than minlen the strands will shrink, but will not go shorter than minlen
Used "noticably" on Pokey balls
thickness : Float : Default = {1/2 Ball Size}
This can be used to limit or reduce the thickness of the displayed strand image.
Setting a large value will not increase the thickness of the strand beyond about 1/2 the size of the ball, as set by the shape attribute.
The actual thickness of the strand also depends on the size and type of the ball it is connecting to.
springconstmax and springconstmin : Float : Range 0 to about 20
Defines the spring constant of the strand. The original balls used values around (6-10).
Low values (1 to 5) produce weak and wobbly strands.
High Values (11-20) produce very strong solid strands.
Values above 20 cause the "Shaking Bug" to occur, even with only a few balls attached.
The operation of these values is quite complex and can produce "unexpected" behaviour. The original balls used the same value for both min and max, it is highly recommended that you do the same.
* See Note below for a full description how these attributes actually function.
walkable : true / false : Default = True
Determines if balls can climb along the strands and will "land" on them when dropped or thrown.
dampfac : Float : Default = 0
Dampening Factor that applies to the strand's length.
Set to low values (<0.1) strands will continue to wobble for a long time after they are attached or hit by a flying ball.
Set to high values (>0.7) this wooble is reduce very quickly.
Most original balls used values around 0.9 Balloons used 0.002
maxforce : Float : Default = 0 (Strands almost always break immediately)
This sets the maximum force a strand can provide before it breaks.
If the force on the strand rises above this value then the strand will begin to stretch very easily and quickly.
If the force remains above this value for 1 second, the strand will break.
Most original balls were set to 600 or 800, Balloons are 200, Ivy's 300
burnspeed : Float : Default = 0 (No Burn)
Sets the speed at which the strand burns along its length.
If set to a low value (<1) then the strand burns slowly. When the ball that started them burning explodes the strands disappear. If that happens before the fire reaches the other end of the strand the next ball will not light.
ignitedelay : Float : Default = 0
The delay (in seconds) between the ball catching fire, and the strand beginning to burn.
NB: Must be less than burntime of the ball.
burntimage : {Image Resource} : Default {Strand Image}
As the strand burns its image is replace by this image.
If omitted the normal strand image is used, and the strand does not change appearance as it burns.
fireparticles : {Point-Source Particle Effect} : Required
Specifies the particle effect to use as the strand burns.
NB: If omitted the strand will NOT burn
rope : true / false : Unused / Unknown
Set true on water (but not Pilot or Balloons)
Appears to have no effect. Possibly a precursor to type
geom : true / false : Unused / Unknown
Set False on Drained and DrainedISH

<detachstrand>

This tag specifies attributes about detaching and flinging. It is required for balls to be detachable.

image : {Image Resource} : Default {None}
The strand image to display as the user tries to detach the ball
For balls with fling set (Bit, Pilot), this specifies the image to use for the direction arrow.
maxlen : Float : Default = 0
The distance the player must pull the ball, before it actually detaches.
Low values (or 0 or ommited) makes the balls detach immediately, annoying when accidentally clicked.
High Values will cause the detach-strand to pull (a lot) on the structure before the ball detaches.
Original balls used 60. Has no effect on fling balls.

* How the springconst attributes actually work

These attributes allow balls to have a range of different spring constants, however whilst the variation is predictable to the designer, it can appear almost random to the player and makes building structures rather frustrating.

When a strand is created, the spring constant is set based on the initial / "natural" length of the strand.
If the initial length is LESS than the minlen attribute - The spring constant is set to springconstmax
If the initial length is GREATER than the maxlen2 attribute - The spring
constant is set to springconstmin
Between minlen and maxlen2 the spring constant varies linearly from springconstmax to springconstmin
This produces some odd, perhaps "interesting", behaviour if max and min are set to substantially different values, however it makes the result on any strand very hard for the player to predict, and thus makes building "difficult"
As mentioned above, 2DBoy set max and min to the same value, which makes the spring constant "constant", whatever length the strand is.

Other effects

<marker>

Defines the graphics use for the mouse cursor when selecting and dragging Goo Balls.

drag : {Image Resource} : Required
Image displayed when selecting or dragging a Goo Ball
Required even if the ball is not draggable
detach : {Image Resource} : Required
Image displayed when attempting to detach a Goo Ball from a structure.
Required even if the ball is not detachable (or even attachable)
rotspeed : Float : Default = 0 (No rotation)
Rotation speed of the marker (radians per second)
Original balls used 2 or -2, except for Window Balls which used 0

<particles>

Adds a particle effect to the ball in the give state.
In the original balls these tags are used mostly for sleeping ZZzz effects and "onfire" burning.

effect : {Point-Source Particle Effect} : Required
The particle effect to display.
state : list-of-{State Names} : Required (You must specify at least one state)
The name of a state, or a comma-separated list of several states, for which this effect will be displayed.
overball : true / false : default = false
If set to true, the particle effect will be drawn over the ball.
Is set to false, the effect will be drawn behind the ball.

<shadow>

Image displayed around / behind the ball when it is on (or near) geometry objects.
Only the parts of the image actually over the geometry are displayed.

image : {Image resource} : Required
The image to display.
additive : true / false : Default = false
Set to true, will make white shadow images act as a "glow" rather than a shadow.
Only used on albino balls and timebugs

<sound>

Sounds that are played when something happens to the ball.

event : {Event Name} : Required
The name of the event for which the sound should be played
sounds : list-of-{Sound Resource} : Required
A sound, or a comma-separated list of several, to be played when the event occurs.
If more than one sound is given, one will be randomly selected.

<splat>

image : list-of-{Image Resource} : Required
An image, or a comma-separated list of several, which are fly out from the ball when it is picked up or dropped by the player, or when it dies.
If the ball is a 'MOM' then the popparticles effect is show instead when it dies.

States and Events

States

These are named "states" in which the balls can exist. They describe what the ball is currently doing.

attached Attached to a structure
climbing Moving along a strand
detaching Being detached, but has not been actually removed from the structure
dragging Being held by the player
falling Falling or Flying.. not held by player, not sitting on geometry.
pipe Moving along inside the pipe
sleeping Asleep
standing On geometry, but not walking.
stuck Is a "sticky" ball and is stuck to geometry
stuck_attached Stuck to geometry and attached to a structure
stuck_detaching Stuck to geometry and being detached from a structure
tank In the tank (Final Stats screen)
walking On geometry and walking along.

There is one additional state onfire which can only be used in a particles tag.

Events

These are named events which can happen to the balls. They describe what happened to it.

attach Attaches to a structure
attachcloser Attaches to a structure and is closer to the pipe
bounce Bounces when hitting geometry
collidediff Collides with a different type of ball
collidegeom Collides with a geometry object
collidesame collides with the same type of ball
death dies
deathfall Unknown
detached Is detached from a structure
detaching Is clicked ready for detaching
detonate Explodes after being on fire
drop Is dropped (at low speed) by the player.. not thrown
exit Enters the pipe
extinguish Unknown may be unused
ignite Catches fire
land Lands on geometry, but does not bounce.
marker the player moves the mouse over this ball (Hover)
pickup The player clicks the ball to grab it.
snap a strand snaps, also used for Pilot and Bit "launch" **
suction in range of the pipe
throw Released travelling at speed

**Note
Balls with "fling" capability use the snap event to specify the sound when the ball is launched.
The sounds played as the arrow changes size are hardcoded to SOUND_GLOBAL_FLING0 -> 9
It is "unclear" what specifies the sound to play when a Pilot strand snaps.

Animations

Advanced - Not for the faint hearted

Bringing balls to life!

Without animations balls seem rather lifeless and flat. They do not wobble or stretch or do anything that makes them appear to be made of Goo.
Obviously it is sometimes desirable to have them appear "lifeless", Bones, Bombs, Blocks etc...
But for balls made of Goo the animations are really the thing that brings them to life!

<sinvariance>

The tags hold information about the variation of the aniamtions (from ball to ball) and contain sinanim tags which actually describe the animations.

When each ball is created, the game selects a random value for each of the variance attributes [0 -> variance]
This is then applied to all the corresponding attributes in each of sinamin tags the sinvariance contains.

Setting all the variance attributes to 0, will make every ball animate in exactly the same way, at exactly the same time. This looks a bit odd.

You should take care that the variance values are less than the values set in the sinanim tags.
If the variance is equal (or greater than) the sinamin value this can result is very strange effects, such as negative scaling.. where the ball shrinks to a point, then expands again as its mirror image, then shrinks to a point and expands back to its normal appearance.

amp : Float : Required : "Sane" Range 0 -> 1
The amplitude variance
Original Balls used values from 0 -> 0.1
freq : Float : Required
The frequency variance in Hz (oscillations per second)
Original Balls used values from 0 -> 1.5
shift : Float : Required : Range 0 -> 1
The phase shift variance, 0.5 = 180° 1 = 360°
Original Balls mostly used 0, but some have 0.5 or 0.8

<sinanim>

These tags define elements of the balls animation. Each element is a simple sinusoidal oscillation, but when several are combined (correctly) the resultinf animation can be quite complex.

part : list-of-{Part Name} : Required
The name or names of the ball <part>s to which this animation is applied
state : list-of-{State Name} : Required
The state, or a comma-separated list of several, for which this animation is applied
For your sanity, we recommend that you select the same state / states for every sinanim within a sinvariance
type : scale or translate : Required
The type of animation
axis : x or y : Required
The axis, relative to the ball's default upright position, along which the animation is applied
amp : Float : Required
The default amplitude of the oscillation, the actual amplitude will be modified by the variance.
For scale type animations this is the scale factor amplitude
For translate type animations this is a pixel distance and can be positive or negative.
freq : Float : Required
The default frequency of the oscillation in Hz, the actual frequency will be modified by the variance
shift : Float : Required : Range 0 -> 1
The default phase shift for this oscillation, the actual phase shift will be modified by the variance.
The shift is in the range 0 = 0° 1 = 360°

Experimention is the key to understanding

These are not easy concepts to understand, and its difficult to explain how these animations will work and the effects they will produce when combined.

Your best bet is...
Take an original ball... simplify it, so it has only a single sinvariance and sinanim.
Set the sinvariance values to 0, and have try out some values in the sinanim.

Once you think you've "got" that, add some variance, or a second sinanim tag... and play with that...

Eventually you'll "get it", and be able to produce all sorts of weird and wonderful things.

Alternatively.. just clone an existing ball, and keep whatever 2DBoy had set! Wink