This text describes the mass levelfile language. The first part is a
tutorial-like introduction. The second part is a complete reference.
(this file is generated from docs.py)

Currently data/default.mas loaded at startup, but you can give another
name as commandline option. Your file must be in the current or data
directory and have the .mas ending.

To get started, create a file called test.mas with this content:

TestMass: Mass   # use the built-in parent mass
  growRounds 400 # make them grow (masses start with only one pixel)
  speed 150      # slow enough to watch them grow
BlueTestMass: TestMass
  baseColor 40 40 255
  player 0
:TestMass -30 0  # place one on the field at x=-30, y=0
:TestMass 0 0
  growRounds 1200
:BlueTestMass +30 0

You will see three small masses in a row, the one in the middle
growing longer (and thus bigger). The right one is blue and owned by
player 0, so you can move it around.

The predefined keywords are case insensitive, your own names are not.
Global engine commands are important too. Try adding those:

viewportForce 32
viewportFriction 2
placeableMass1 BlueTestMass

If this did not make you sick, place some more blue player masses:
Enter debug/edit mode (press F2), move the mouse to an empty spot,
then press the 1 key. You may save the current situation to save.mas
by pressing F11.

Special commands:
include levelname   # does just that
SavedFrom levelname # for savegames; as include, but ignore placed bodies

TODO: write something about particles here

----------------------------------------------------------------------
All supported engine commands are listed below.

firstPersonMovement (default: false)
  [player movement] turn with left/right, accelerate with up/down (instead of
  bomberman style controls)

startHeading (default: 0)
  [player movement] when using firstPersonMovement, this is the initial heading

viewportForce (default: 20)
  [player movement] how strong the player moves his viewport himself (negative
  values possible)

viewportFriction (default: 40)
  [player movement] how much friction there is when the viewport moves

calculateInvisible (default: true)
  [engine] calculate/move all masses instead of only visible ones (aka
  FieldFreeze)

playerNeedsBodyMass (default: false)
  [goal] whether a player without a body mass (a mass with playerBody=true) is
  considered dead

playerDeathAction (default: exit)
  what happens if the player dies (exit, ignore or recreate) (FIXME: not yet
  implemented)

placeableMass1 (default: PlaceableMass1NotSet)
  mass class placeable while editing the level

placeableMass2 (default: PlaceableMass2NotSet)
  as above

placeableMass3 (default: PlaceableMass3NotSet)
  

placeableMass4 (default: PlaceableMass4NotSet)
  

placeableMass5 (default: PlaceableMass5NotSet)
  

placeableMass6 (default: PlaceableMass6NotSet)
  

placeableMass7 (default: PlaceableMass7NotSet)
  

placeableMass8 (default: PlaceableMass8NotSet)
  

placeableMass9 (default: PlaceableMass9NotSet)

----------------------------------------------------------------------
All supported mass attributes are listed below.

Note that some of those attributes might not be useful (or only in 
savegames), some cause others to be set every frame and some might 
be experimental (not work or slow down the whole game).

****************************
*** Flattening Algorithm ***
****************************

bufferMass (default: 0.0)
  height to be added to the mass as a whole

weakSHR (default: 4)
  parameter for move backward

normalSHR (default: 3)
  parameter for no movement

strongSHR (default: 2)
  parameter for move forward

minBorderHeight (default: 1.0)
  minimal border height

maxBorderHeight (default: 5.0)
  maximal border height

**************
*** Basics ***
**************

speed (default: 256)
  how often the mass is processed per (engine) frame

heading (default: -1)
  the direction (mass orientation), 128 means 180 degree, -1 random (choosen at
  creation)

velocity (default: 0)
  m->speed is how often the mass is calculated, this is for movement

lookDistance (default: 1)
  number of pixels to look for neighbour mass (for interfaces) ; 0 means don't
  (faster but neighbours are all threated as empty space)

growRounds (default: 0)
  how many rounds the mass will grow; masses are usually boren with one pixel,
  which will not last long

growIfSmallerThan (default: 0)
  whenever the mass has fewer pixel than this count, grow

superGrow (default: false)
  grow much much faster (not linear)

shrink (default: 0.0)
  shrink that much per round

age (default: 0)
  automatically increases by one with each step

energy (default: 0)
  generic energy counter

pulse (default: 0)
  generic activity counter

energyAdd (default: -64)
  add that much energy each cycle (negative value means add one every -value
  cycles)

maxEnergy (default: 256)
  don't add energy if it there is already more than this limit

headingAdd (default: 0)
  add this value to the heading each round (or faster, see slowHeadingAdd
  below); -100 means a random value between -50 and +50

slowHeadingAdd (default: true)
  consider headingAdd only every 32 rounds instead every round

flatteningMovement (default: false)
  move according to m->heading and m->velocity, or just flatten?

expFlattening (default: true)
  do flattening using the strong exponential algorithm

convolveFlattening (default: false)
  do flattening using the convolution matrix algo

oldFlattening (default: false)
  do flattening using the old (fast but weak) algo

***************
*** Players ***
***************

player (default: -1)
  player id controling this mass, 0 first player, -1 no player; FIXME: resets
  both velocity and heading each cycle

attractPlayer (default: 128)
  if m->player is in range, attract his viewpoint

playerControl (default: direct)
  react on player input (if player is set); direct (move as commanded), swarm
  (circle around viewpoint and follow commands freely), ignore (no direct
  control)

wakeOnPlayer (default: false)
  the mass gets speed=256 the first time a player approximates

wakeOnTouch (default: false)
  the mass gets speed=256 the first time any mass with speed >50 approximates

playerFood (default: false)
  can a player simply eat this mass?

playerLightning (default: false)
  throw a lightning on player button2 (using 50 energy)

playerBody (default: false)
  this mass counts as a player body: special action may be taken when a player
  owns no more body mass

transformOnBodylessPlayer (default: )
  if set to a non-empty string, this mass will catch the first player without a
  playerBody and transform into the given mass type (which probably has
  playerBody set, thus giving the player a new body); as long as all players
  have a playerBody mass, nothing happens

transformationSavesPlayerid (default: true)
  when a transformation happens, all attributes are overwritten with the new
  ones, including player id; this is usually not wanted (except if the player
  should loose the mass)

attractBodylessPlayers (default: false)
  TODO attract players without a playerBody using attractPlayer

ignorePlayerDeath (default: false)
  if a player dies (lost his last playerBody), all other masses from this
  player will have player set to -1; this option prevents this

transformOnButton1 (default: )
  transform into the given class on button1 (does not check playerControl)

transformOnButton2 (default: )
  transform into the given class on button2 (does not check playerControl)

changePlayer (default: 0)
  when >0 and a mass with player != -1 is nearby, change the own player number;
  the value given is the number of cycles a player has to stay around
  exclusively; FIXME: how is "nearby" defined?

*************************
*** Visual Appearance ***
*************************

displayType (default: shadow)
  how to display the mass (shadow or flat)

baseColor (default: 255 255 255)
  basic mass color (RGB)

secondColor (default: 0 255 0)
  second mass color, for some effects (RGB)

borderColorHeight (default: 0.0)
  draw points lower than this with secondColor

drawElipsoid (default: false)
  draw a gray elipse that indicates the heading (must have a certein height
  before it becomes visible); SLOW!

drawSparks (default: false)
  draw a spark effect from time to time (a bright point gleaming for a short
  time over the hightest mass pixel)

foggy (default: false)
  mass generates fog clouds

************************************
*** Children and Transformations ***
************************************

childClass (default: ChildClassNotSet)
  what children masses this mass generates, self (lowercase) means clone, if
  more than one class is given (seperated with one space), one is picked
  randomly

childTime (default: 0)
  if not zero, create a child mass all that many cycles; negative values, eg
  -80 mean a child is generated each turn with probability 1:80

childCount (default: -1)
  number of children this mass can generate, -1 unlimited

childDistance (default: 50)
  in which distance a child is born (0 mass center, -200 means 200 pixels in
  the oposite of the choosen direction)

childDirection (default: 0)
  if the parent heading is used to place the child, this value is added

childDirectionAlternating (default: false)
  if set, childDirection := -childDirection after the child is created

childInside (default: false)
  if set, children are born by cutting a part of the parent mass; in this case
  childDistance is interpreted relative (0 center, 256 or -256 mass border)

childRandomDistance (default: false)
  if set, childDistance is taken as a maximum and the actual distance is
  choosen randomly

childRandomDirection (default: false)
  if set, children are born in a random direction, ignoring the parent's
  heading

childSetHeading (default: true)
  if true, the children's heading is set to point away from its parent mass
  after creation

childTakesMassFromParent (default: false)
  if set, the parent does not get the initial child mass back (most relevant if
  childInside is set)

childAndParentSwapped (default: false)
  if true the parent gets the body of the child and vice versa (consequently
  the child will not have to grow but maybe the parent)

transformClass (default: TransformClassNotSet)
  what mass to transform into if a transformation is tiggered, see childClass
  for allowed values; note that a transformation will reset most values
  (including age but not heading)

transformAt (default: never)
  when to transform into another class (never, age, random, energy, size,
  touch); see also transformArgument

transformArgument (default: 0)
  compare value for transformAt: age, random (probability 1:value), size (in
  pixels) or energy; ignored for: never, touch

*****************
*** Particles ***
*****************

particleReceptor1 (default: false)
  particle receptor 1; a particle can set this flag when it hits the mass

particleReceptor2 (default: false)
  particle receptor 2; as above.

particleReceptor3 (default: false)
  particle receptor 3; as above.

particleResetTime (default: 0)
  how many turns (age) pass until the particle receptors are reset; 0 means
  disable; FIXME: used only and always together with
  transformOnParticle_minAge?

transformOnParticle (default: 0)
  Transform if the given particle receptor number (1, 2, 3) is set. Negative
  numbers (-1, -2, -3) will transform if particle is not present.

transformOnParticle_transformClass (default: )
  transform into the given class

transformOnParticle_minAge (default: 5)
  transform only if older than the given age

transformOnParticle_maxAge (default: 0)
  transform only if younger than the given age (0 means no limit)

******************
*** Algorithms ***
******************

vivid (default: 0)
  how vivid the mass is; causes random movements in it

vivid2 (default: 0)
  same as vivid, but other algo (uses shapepoints, which is a bit slow, don't
  overuse)

sickness (default: 0)
  if nonzero, the mass will shrink from random pixels taken away (no good idea
  while growing); FIXME: this has more complicated threshold constants,
  document them.

destructive (default: 0)
  how much mass it steals from its surrounding FIXME: does it work? how?

decreaseSpeed (default: 0)
  decrease speed by that value each turn (value>0) or by one with probability
  1:-value (value<0)

minSpeed (default: 1)
  never decrease speed lower than this; speed 0 is possible but might cause
  stale references

isWall (default: false)
  enables wall code (join other walls, adapt to speed of other walls)

isProjectil (default: false)
  FIXME: what does this?

isMazeWall (default: false)
  FIXME: what does this?

isCoinMass (default: false)
  FIXME: what does this?

isLightningMass (default: false)
  make the mass throw lightnings on proximity (needs 80 energy)

lightningResistance (default: false)
  lightning does not affect this mass; a small smoke cloud might be generated
  instead

isNetworkMass (default: false)
  FIXME: planned?

speedPerturb (default: false)
  randomly change the speed a bit (use this to avoid identical masses to grow
  up exactly simultanous; this property disables itself after some time)

experimentalBorderPoints (default: false)
  experimental new faster border point algorithm

baseLineGrowth (default: 0.0)
  grow mass around a line (through mass center, direction of heading) that much
  for each pixel

baseLineGrowth_start (default: 0.0)
  extra-height to add to startpoint

baseLineGrowth_end (default: 0.0)
  extra-height to add to endpoint

baseLineGrowth_step (default: 256)
  distance between the pixels of the line (256 = 1 pixel)

baseLineGrowth_randomStepStart (default: 0)
  if set, the first step is not always in the mass center, but still on the
  line (probably useful with big step size)

baseLineGrowth_setHeight (default: 0)
  if set, the height is not added but re-set (if baseLineGrowth > 0)

cell (default: false)
  enable cell functions (rules similar to game of life, get input from nearest
  neighbours)

cell_activation (default: 1)
  cell activation status (0 or 1, or -1 for random; resets baseColor to
  hardcoded values for now)

swarm (default: false)
  enable simple swarm algorithm (resets baseColor to hardcoded values for now)
  FIXME: needs tuning, not of much use yet

swarm_pulse (default: 0)
  used to call other swarm members (energy is spent to increase if something is
  happening, then decrease quickly back to zero)

*****************
*** Debugging ***
*****************

debugTest (default: false)
  does whatever I want it to (don't use)

----------------------------------------------------------------------
All supported particle attributes are listed below.

speed (default: 256)
  how often the particle is processed per (engine) frame

age (default: 0)
  automatically increases by one with each step

x (default: 0)
  current x-position on the field

y (default: 0)
  current y-position on the field

heading (default: -1)
  the direction (for moving or whatever), 128 means 180 degree, -1 random
  (choosen at creation)

velocity (default: 0)
  m->speed is how often the particle is calculated, this is for movement

radius (default: 0)
  radius of some actions

invisible (default: false)
  invisible to other particles (speedup for many particles not interested in
  collision detection); FIXME: rename this option: whether the particle is
  invisible on the screen is something completely different

headingAdd (default: 0)
  add this value to the heading each round (or faster, see slowHeadingAdd
  below); -100 means a random value between -50 and +50

slowHeadingAdd (default: false)
  consider headingAdd only every 32 rounds instead every round

restartAge (default: 0)
  if > 0, the particle is restarted after the given age. Restarting means: x, y
  are set randomly on the field, heading is randomized and age reset to zero.
  If < 0, it restarts with a probability 1:-value each turn.

markOnMassCollision (default: 0)
  if nonzero and this particle is touching a mass (only center pixel is
  checked), the mass will have particleReceptorN set to true. N may be 1, 2, or
  3.

restartOnMassCollision (default: false)
  if true, after a collision with a mass the particle is restarted, the same
  way in restartAge (see above). Useful eg. for background radiation particles.

addBufferMass (default: 0.0)
  add (negative: remove) that much mass to the bufferMass of the mass in
  collision with; each turn, if the collision lasts

addMass (default: 0.0)
  add (negative: remove) that much mass directly to nearby pixels.

maxMassCollisions (default: 0)
  if > 0, this value is decremented after a collision and the particle is
  destroyed after it decrements to zero

ttl (default: 0)
  time to live; if > 0, this value is decreased each turn. When it is decreased
  to zero, the particle is removed.

baseColor (default: 255 255 255)
  particle color used for some effects

sparks (default: false)
  draw sparks using baseColor

childClass (default: ChildClassNotSet)
  what children particles this particle generates, self (lowercase) means
  clone, if more than one class is given (seperated with one space), one is
  picked randomly

childTime (default: 0)
  if not zero, create a child particle all that many cycles; negative values,
  eg -80 mean a child is generated each turn with probability 1:80

childCount (default: -1)
  number of children this particle can generate, -1 unlimited

debugColor (default: 255 255 255)
  particle color in debug mode

debugTest (default: false)
  do whatever I'm testing today (don't use)