ORGANISM INSTRUCTION REFERENCE

CMOVE

move a cell relative to the organism

Move the cell that executes this instruction relative to the organism.

1. If there are not 2 elements on the data stack, then skip this instruction.
2. Remove the (x, y) coordinates from the stack.
3. Normalize the coordinates.
4. Examine the destination square (as indicated by the offsets) and see if it is vacant. If not, return 0.
5. Check that the organism is propery connected after the move. If not return 0.
6. Else, Move the cell to the new location and return 1.
7. A CMOVE of (0,0) always fails and returns 0.

RETURNS:

• 0 - cell could not be moved.
• 1 - success.

ENERGY: Does not require any energy.

CMOVE MODE BITS:

move entire organism

Move entire organism by one square in the up, down, left, right, or diagonal direction.

1. If there are not 2 elements on the data stack, then skip this instruction.
2. Remove the (x, y) coordinates from the stack.
3. Normalize the coordinates.
4. Examine every square that we may be moving to to make sure it is empty, or contains one of our cells.
5. If the move is possible, reposition every cell in our organism by the (x, y) offset.
6. A move using vector (0, 0) always fails, and returns 0.

RETURNS:

• 0 - move failed.
• n - success. where n is the number of cells moved.

ENERGY: Does not require any energy.

OMOVE MODE BITS:

rotate organism

Rotate the organism by 45 degree units around the cell that executes this instruction. The rotate direction is given by 'n'. A positive 'n' rotates the organism clock-wise 45 degrees. A negative 'n' rotates the organism 45 degrees counter-clockwise.

If 'n' is zero don't rotate the organism and return 0.

1. If there is not 1 element on the data stack, then skip this instruction.
2. Remove the rotation amount n from the stack.
3. Translate all cells in the organism to the new location, and check that the spot is vacant (or contains cells from this organism). If not, return 0.
4. Else, rotate organism and return 1.
5. A rotation value of 0 does nothing, and returns 0.

RETURNS:

• 0 - organism could not be rotated.
• r - 'r' is the number of cells that were rotated.

ENERGY: Does not require any energy.

ROTATE MODE BITS:

eat energy from surrounding cells

Eat stuff at (x, y) from this cell. Return 'n' the amount of energy eaten.

1. Normalize the (x, y) coordinates.
2. Try to eat whatever is at this location:
3. Organic material (white squares) will be eaten and all its energy transferred to this organism.
4. Spores (blue squares) will be eaten and all their energy transferred to this organism. Even spores created by this organism will be eaten (so be careful!).
5. Depending on the modes, living tissue from other creatures will be eaten like this:

• The living tissue must be from ANOTHER organism, not itself. The cell cannot eat itself!
• The cell being eaten must not already be flagged as dead (not already red).
• The cell being eaten is then flagged as dead (red square).
• 1/x units of energy (where x is the number of cells in the organism being eaten) will be removed from the organism we ate, and transferred to this organism.
• any remainder from the integer "1/x" calculation is also removed from the organism we ate and transferred to us.

RETURNS:

• 0 - nothing was eaten
• n - the amount of energy we were able to eat.

ENERGY: Does not require any energy.

EAT MODE BITS:

give/take energy to neighboring cell

send the energy to the cell at normalized coordinate (x,y). negative 'e' values take from that cell. If there isn't enough energy to perform the transfer (too little energy compared to 'e')) then don't do anything.

RETURNS: Returns the number of units of energy given/taken. 0 is returned if the operation failed.

ENERGY:

SEND-ENERGY MODE BITS:

create spore and reproduce

Create new spore (or fertilize an existing spore).

When a spore is fertilized, the original genetic program used to create the spore, and the genetic program from the organism that fertilized the spore will be first merged. Then the resulting genetic program is MUTATED. Then a new organism is born. It will begin execution at the first instruction of code block 0 (main). It will be given 'e' units of energy, which is the sum of the energy specified with the first and second MAKE-SPORE instructions.

MAKE-SPORE Energy: This setting is available on the Strain Modes tab. The value represents the minimum amount of energy required to create a spore. If 'e' is not big enough, then this instruction will return 0. A minimum of '1' units of energy is always required to create the initial spore.

1. If there are not 3 elements on the data stack, then skip this instruction.
2. Remove energy 'e' from the stack. (this is the amount of energy that this organism will give up and transfer to the new spore).
3. Remove the (x, y) coordinates from the stack.
4. Normalize the coordinates.
5. For new spores, if energy 'e' is less than or equal to 0, then return 0.
6. For fertilizing an existing spore, if energy 'e' is less than 0, then return 0.
7. If energy 'e' is more than the amount of energy this organism has, then return 0.
8. If the location indicated by the normalized (x, y) coordinates is not vacant or is not a spore, then return 0.
9. If the location is blank, then create the first spore. Transfer 'e' units of energy from this organism and give it to the new spore. Return 1.
10. If the location is a spore then fertilize the existing spore. Transfer 'e' units of energy from this organism to the fertilized spore. Return -1.

RETURNS:

• 0 - could not make spore.
• 1 - created spore.
• -1 - fertilized existing spore.

ENERGY: Requires 'e' units of energy.

MAKE-SPORE MODE BITS:

add a new cell to the organism

Add a new cell to this organism. The new cell inherits the data stack, call stack and registers of the parent cell. The parent and child can check the return value to determine which one they are.

GROW Energy: This field is available on the Strain Modes tab. It sets the minimum amount of energy required to grow a cell. Each organism has a total amount of energy. If total energy divided by the number of cells isn't equal or greater to this value, then the GROW operation will fail.

GROW Max Size: This field is available on the Strain Modes tab. It sets the maximum number of cells that an organism can be. If this value is 0, then there is no maximum.

1. If there are not 2 elements on the data stack, then skip this instruction.
2. Remove the (x, y) coordinates from the stack.
3. Normalize the coordinates.
4. If the location specified by the coordinates is not blank, then return 0.
5. Compute the amount of energy needed to grow (this is the sum of the data stack size and the call stack size).
6. If organims does not have enough energy to GROW a new cell, then return 0.
7. Create new cell at location specified. Clone this cells data and call stack (as well as registers, and so on).
8. For the cell executing the GROW instruction return 1.
9. For the new cell, just created, make it appear as if it returned -1.

RETURNS:

• 0 - could not grow
• 1 - grow succeeded (the cell that executed the GROW instruction)
• -1 - grow succeeded (the new cell)

ENERGY: Requires GROW Energy units of energy.

GROW MODE BITS:

create organic block

Create organic block at (x,y) offset with energy e.

1. Normalize the (x, y) ccoordinated, if the offset if not vacant return s=0.
2. If organism doesn't have enough energy return s=0.
3. If organic already exists, append 'e' energy to it and return s=e
4. If blank exists then create new organic block with energy 'e'. return s=e

RETURNS: 0 Returns the amount of energy that was d

ENERGY: The energy 'e' is deducted from the organisms (or cells) energy.

MAKE-ORGANIC MODE BITS:

grow another cell

Grow a new cell at (x,y) normalized offset. The new cell inherits the context of the cell which executed the GROW.CB instruction. However, it will begin execution at code block 'cb'. Respects the Grow Max Size setting. If the number of cells is already at the max size, then GROW.CB will not succeed. Unprotected code cannot specify a protected code block number for cb.

RETURNS:

• 0 - could not create cell
• 1 - new cell created

ENERGY: Respects the Grow Energy setting. If adding this cell would cause the total amount of energy per cell to drop below the Grow Energy amount, then GROW.CB fails.

shift a line of cells relative to the organism

This instruction is similar to CMOVE except a group of cells move (or shift position in space) along a vector. If the shape of the organism after the CSHIFT operation would violate the connectivity of the organism then this instruction fails.

RETURNS: Returns the number of cells that shifted.

ENERGY: Does not require energy.

CSHIFT MODE BITS:

spawn a new organism of a particular strain

Spawn a new organism at the (x,y) normalized offset. Give it 'e' units of energy. Start running at code block 'cb. The identity of the new organism will be strain 'strain'. The cellular state of the spawned organism will inherit the cell executing this instruction. Unprotected code cannot specify a protected code block number for cb.

RETURNS: returns 1 if the spawn was successful, else 0.

ENERGY:'e' units of energy are required.

SPAWN MODE BITS:

create (or clear) a barrier block

Creates a barrier block at the x y normalized offet. If the location already contains a barrier block, then this instruction will clear the barrier.

RETURNS:

• 0 - could not create barrier
• 1 - could create barrier

ENERGY:

MAKE-BARRIER MODE BITS:

excrete a value onto the grid

excrete a value onto the grid

RETURNS:

ENERGY:

EXUDE MODE BITS:

read a value from the grid

read a value from the grid that was previously EXUDE'd.

RETURNS:

ENERGY:

look along a line

Look along a normalized (x, y) direction vector. Return the thing it found, and the distance.

NOTE: The LOOK Mode settings apply to all the vision instructions such as NEAREST / FARTHEST, HOTTEST / COLDEST, and SMALLEST / BIGGEST.

1. If there are not 2 elements on the data stack, then skip this instruction.
2. Remove the (x, y) coordinates from the stack and normalize the coordinate.
3. Look along the direction vector until something is found (or the edge of the universe is reached).
4. Ignore any cell that happens to be from the same organism as us.
5. Push the type of thing ('what' value) on the data stack. (WHAT value Key: 1=cell, 2=spore, 4=organic material, 8=barrier).
6. Push the distance ('dist' value) on the data stack. A distance of 1 means the thing seen is touching this cell.

RETURNS:

• what dist - before reaching the end of the vector something was found. "something" is one of ORGANIC MATERIAL, SPORE, or living cell.
• 0 0 - when then (x, y) vector was (0, 0).

What values:

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

ENERGY: Does not use energy.

LOOK MODE BITS:

find nearest object

Looks in all 8 directions and return the (x, y) direction vector that corresponds to the thing with the smallest distance (and matches a 'mask' value). The returned (x,y) vector is not normalized, so it might return (-6,6) instead of (-1,1).

mask values are the same as what values. If any bit matches the what from LOOK'ing along that vector then we match.

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

1. If there is not 1 element on the data stack, then skip this instruction.
2. remove 'mask' value from data stack.
3. strip all bits from the mask, except first 4 bits (e.g. 000001111)
4. if mask bits are all 0, then return the vector (0, 0)
5. Look in all 8 directions, beginning with a RANDOM direction and proceeding in a clock-wise direction.
6. Keep track of the closest thing seen (whose 'what' value is set in the bit-mask)
7. Return the (x, y) direction vector.
8. If nothing matched the bit-mask, then (0, 0) is returned.

RETURNS:

• x y - the direction vector that is nearest and matches the 'mask'
• 0 0 - nothing matched the 'mask'

ENERGY: Does not use energy.

find farthest object

Looks in all 8 directions and return the (x, y) direction vector that corresponds to the thing with the largest distance (and matches a 'mask' value). The returned (x,y) vector is not normalized, so it might return (-6,6) instead of (-1,1).

mask values are the same as what values. If any bit matches the what from LOOK'ing along that vector then we match.

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

1. If there is not 1 element on the data stack, then skip this instruction.
2. remove 'mask' value from data stack.
3. strip all bits from the mask, except first 4 bits (e.g. 000001111)
4. if mask bits are all 0, then return the vector (0, 0)
5. Look in all 8 directions, beginning with a RANDOM direction and proceeding in a clock-wise direction.
6. Keep track of the farthest thing seen (whose 'what' value is set in the bit-mask)
7. Return the (x, y) direction vector.
8. If nothing matched the bit-mask, then (0, 0) is returned.

RETURNS:

• x y - the direction vector that is farthest and matches the 'mask'
• 0 0 - nothing matched the 'mask'

ENERGY: Does not use energy.

see the size of something

Report the size (number of cells) of the object seen along the normalized vector (x,y) from this cell.

RETURNS: The number of cells (the 'size') in the organism seen along (x,y). Also returns the distance.

ENERGY:

find the biggest thing in view

Look in all 8 directions. Return a non-normalized (x,y) vector to the biggest thing. This is the organism consisting of the most number of cells. The returned (x,y) vector is not normalized, so it might return (-6,6) instead of (-1,1).

mask values are the same as what values. If any bit matches the what from LOOK'ing along that vector then we match.

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

find the smallest thing in view

Look in all 8 directions. Return a non-normalized (x,y) vector to the smallest thing. This is the organism with the least number of cells. The returned (x,y) vector is not normalized, so it might return (-6,6) instead of (-1,1).

mask values are the same as what values. If any bit matches the what from LOOK'ing along that vector then we match.

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

get the energy of cell seen along (x,y)

Get the energy of cell seen along (x,y). This is per cell. For organisms we divide the total energy the organism has by the number of cells the organism has.

RETURNS:

• energy dist - the energy and distance
• 0 0 - nothing with energy found

ENERGY:

find the most energetic cell in view

Look in all 8 directions. Return a non-normalized (x,y) vector to the hottest thing. This is the organism with the most energy per cell. The returned (x,y) vector is not normalized, so it might return (-6,6) instead of (-1,1).

mask values are the same as what values. If any bit matches the what from LOOK'ing along that vector then we match.

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

find the least energetic cell in view

Look in all 8 directions. Return a non-normalized (x,y) vector to the coldest thing. This is the organism with the least energy per cell. The returned (x,y) vector is not normalized, so it might return (-6,6) instead of (-1,1).

mask values are the same as what values. If any bit matches the what from LOOK'ing along that vector then we match.

• 1 = Cell
• 2 = Spore
• 4 = Organic Material
• 8 = Barrier
• 16 = Self
• 32 = Strain 0
• 64 = Strain 1
• 128 = Strain 2
• 256 = Strain 3
• 512 = Strain 4
• 1024 = Strain 5
• 2048 = Strain 6
• 4096 = Strain 7

Query the MOOD of one of my cells

Every cell has its own "MOOD" register. This instruction queries another cell using an (x, y) vector. This vector is not normalized which allows the cell to query any other cell within its own organism (not just adjacent cells). For example, if cell 2 executed the following instructions:

0 0 MOOD   ; returns -23
-1 0 MOOD   ; returns 123
-1 1 MOOD   ; returns 33
99 99 MOOD   ; returns 0

If a bogus (x, y) is specified then 0 is pushed on the data stack. We can query our own mood by specifying (0, 0).

RETURNS:

ENERGY: Does not use energy.

Set MOOD register to a value

The cell executing this instruction will set its own mood register. It is not possible to set others. The purpose of the mood register is for a cell it advertise its "mood" to other cells in the organism. For example, if cell 3 executed these instructions:

0 0 MOOD 1 + MOOD!

Then cell 3's mood would be increased by 1. So it would be set to 34.

RETURNS:

ENERGY: Does not use energy.

broadcast a message to our cells

This instruction takes the value off of the top of the data stack and sets the message register for every cell in our organism. If interrupts are enabled every cell, except the cell executing this instruction, will be interrupted.

RETURNS:

ENERGY: Does not use energy.

BROADCAST MODE BITS:

Set the MESSAGE register of one of my cells

This instruction takes 3 arguments. An (x, y) vector and a value 'm'. The vector is NOT normalized so that the cell can send a message 'm' to any other cell in the same organism (not just adjacent cells). For example, if cell 1 exectuted this these two instructions:

100     1 0 SEND   ; set cell 2's message register to 100
-46812  0 1 SEND   ; set cell 3's message register to -46812
0       0 0 SEND   ; set out message register to 0.
12   -99 99 SEND   ; does nothing because (-99, 99) is bogus

A SEND operation using bogus coordinates will be ignored.

RETURNS:

ENERGY: Does not use energy.

SEND MODE BITS:

recieve message

The RECV instruction just pushes a copy of our message register on top of the data stack.

RETURNS:

ENERGY: Does not use energy.

broadcast a message to another organism

Broadcast a message to another organism. Send the message 'm' outward in all 8 directions. If a cell is reached, then set it's MESSAGE register to be 'm'.

RETURNS: The number of cells that recieved the message.

ENERGY:

SHOUT MODE BITS:

send a message along a line to another organism

The (x,y) normalized direction vector will be used to send the message 'm'. If a cell is reached, then set it's MESSAGE register to be 'm'.

RETURNS: Returns non-zero on success. The returned value is the distance to the cell that successfully recieved the message, or 0 if no message delivered.

ENERGY:

SAY MODE BITS:

read MOOD register from a cell from another organism

Listen along the normalized vector (x,y). If another cell was found return its MOOD register and distance.

RETURNS: Returns the mood and distance value, or 0 0 if nothing heard.

ENERGY:

LISTEN MODE BITS:

read an entire code block from another cell or spore

Read code block 'cb' from the cell or spore located at the normalized (x,y) coordinates. Place the result into 'cbme'. It is not possible to grow the number of code blocks of a program with this instruction. The destination code block 'cbme' must already exist.

Unprotected code cannot READ if 'cb' or 'cbme' is protected. Unprotected code cannot read a protected instruction.

RETURNS: On success, the length of the code block read is returned. On failure, a negative error code is returned.

• -1: no such cb
• -2: no such cbme
• -3: invalid coordinates
• -4: bad protection for cb
• -5: bad protection for cbme
• -6: bad strains
• -7: spore not allowed
• -8: cell not allowed
• -9: self not allowed
• -10: target cell unreadable
• -11: bad instruction mapping
• -12: protected instructions

ENERGY:

READ MODE BITS:

write an entire code block to another cell or spore

Write code block 'cbme' to another cell or spore. The cell is located at the normalized (x, y) offset from this cell. The destination code block number is given by 'cb'. It is not possible to grow the number of code blocks of a program. The destination code block 'cb' must already exist.

Unprotected code cannot WRITE if 'cb' or 'cbme' is protected. Unprotected code cannot write a protected instruction.

RETURNS: On success, the length of the code block written is returned. On failure, a negative error code is returned.

• -1: no such cb
• -2: no such cbme
• -3: invalid coordinates
• -4: bad protection for cb
• -5: bad protection for cbme
• -6: bad strains
• -7: spore not allowed
• -8: cell not allowed
• -9: self not allowed
• -10: target cell unwriteable
• -11: bad instruction mapping
• -12: protected instructions

ENERGY:

WRITE MODE BITS:

get energy of organism

Get our organisms overall energy.

RETURNS:

ENERGY:

return age of organism

Fetch the organisms "age" field (which is the number of elapsed simulation step) and push this value on our data stack.

RETURNS:

The age of the organism

ENERGY: Does not use energy.

number of cells

Push the number of cells that comprise this organism on our data stack.

RETURNS:

number of cells in this organism

ENERGY: Does not use energy.

check for our cells

Determine if a neighboring cell location contains our cell or not.

1. On the data stack should be two values. If not, we ignore this instruction.
2. The two values are popped off the stack (they are NOT normalized). This forms an (x, y) vector that refers to one of our nearby grid locations.
3. If we have a cell at this (x, y) offset, then this instruction returns 1. Else 0 will be returned.
4. The vector (0,0) is allowed, and always returns 1.

RETURNS:

• 1 - at offset (x, y) is one of our cells.
• 0 - at offset (x, y) it NOT one of our cells.

ENERGY: Does not use energy.

Returns a bitmask with a '1' bit set for a neighor in that direction.

RETURNS: A bit mask representing the surrounding neighbors.

• bit-0 - North neighbor. Offset (0, 1)
• bit-1 - North East neighbor. Offset (1, 1)
• bit-2 - East neighbor. Offset (1, 0)
• bit-3 - South East neighbor. Offset (1, -1)
• bit-4 - South neighbor. Offset (0, -1)
• bit-5 - South West neighbor. Offset (-1, -1)
• bit-6 - West neighbor. Offset (-1, 0)
• bit-7 - North West neighbor. Offset (-1, 1)

ENERGY:

get current position

Returns the absolute grid coordinates for the cell executing this instruction.

RETURNS:

ENERGY:

get universe-wide global variable

Get universe-wide global variable. This is a common global that all CELL's can query with this instruction.

RETURNS:

ENERGY:

set universe-wide global variable

Set universe-wide global variable. This is a common global that all CELL's can write to with this instruction.

RETURNS:

ENERGY:

get strain-wide global variable

Get strain-wide global variable. Each strain has its own S0 global variable. This instruction allows the strain specific variable to be queried.

This variable can be used by a swarm of organisms, from the same strain, to coordinate their activies.

RETURNS:

ENERGY:

set strain-wide global variable

Set strain-wide global variable. Each strain has its own S0 global variable. This instruction allows the strain specific variable to be written to.

This variable can be used by a swarm of organisms, from the same strain, to coordinate their activies.

RETURNS:

ENERGY:

total population

Return the current population.

RETURNS: The total population of the universe. This is the total number or organisms.

ENERGY:

strain population

Return the current population of my strain.

RETURNS: The population (number of organisms) for my strain.

ENERGY:

read keyboard

Get the keyboard character being pressed. Or 0 if nothing is being pressed.

RETURNS: Returns the ascii character code. Returns 0 if no key is pressed.

ENERGY:

KEY-PRESS MODE BITS:

get mouse position

Query the mouse position. The mouse position is a coordinate in the universe coordinate space. This position was set externally by the user right clicking on a grid location when in 'MOUSE-POS' mode. See the KEY-PRESS instruction modes to configure interrupts for the mouse position.

RETURNS: Returns a coordinate in the universe which was set by the user clicking in the grid when in MOUSE-POS mode. Returns (-1,-1) if no position set.

ENERGY:

compute vector distance

Computes the maximum of ABS(x) and ABS(y).

RETURNS:

ENERGY:

pick random value between two values

pick random value between two values

RETURNS:

ENERGY:

return random value between MIN_INT and MAX_INT

return random value between MIN_INT and MAX_INT.

RETURNS:

ENERGY: