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.


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