DarwinBotsManual
Open the app EspañolES

The integer and boolean stacks

The DNA computes with two stacks, one of numbers and one of true or false: how much they hold, what happens when they fill up or run empty, and when they start from zero.

The DarwinBots DNA is a stack-based language: there are no variables or parentheses, and every word leaves something on a stack or takes it off. If you have ever used an RPN calculator, you already know the idea: operands first, then the operation.

There are two stacks, and each word knows which one it works with:

StackHoldsFilled byEmptied by
Integernumbersbare numbers, reads such as *.nrg, operators such as addoperators, conditions and stores
Booleantrue or falseconditions such as >, true, falselogic operators such as and, the start of a gene, dropbool

The integer stack

A number written in the DNA is pushed. An operator pops the ones it needs and pushes the result. A store pops an address and a value and writes to the bot's memory. This bot adds 3 and 4 and stores the 7 at address 50, a free memory cell:

cond
start
  3 4 add 50 store
stop

Step by step, the integer stack ends up like this (top on the right):

WordStack afterwards
33
43 4
add7
507 50
store(empty): it wrote 7 to address 50

Order matters in operations that aren't commutative: 10 3 sub is 10 − 3, and *.nrg 1000 > asks whether the energy is greater than 1000. The rule is always the same: the one lower down is the first operand. That is why a store is written value address store, with the address on top.

The integer stack can hold numbers much larger than memory can (up to about two billion); the clipping to ±32000 only happens when storing. We cover it in Numbers and addresses.

The boolean stack

Conditions pop two numbers from the integer stack and push a result onto the boolean one. *.nrg 1000 > pops the energy and the 1000 and pushes true or false. The logic operators (and, or, not, xor) work only on the boolean stack.

Several conditions in a row between cond and start are combined with an implicit and: start does the and of everything on the boolean stack and leaves it empty. For an or you have to write it. In this bot the first condition is true and, of the other two, only one is; with or the gene runs and writes 9 to address 57:

cond
  1 1 =
  2 2 = 3 4 = or
start
  9 57 store
stop

Everything about a gene's conditions is in Genes: cond, start, else and stop, and the operators one by one are in Operators by family.

Size: 101 slots

Each stack has room for 101 values. If you push one more, the stack doesn't raise an error: the oldest value is lost, the one at the bottom, and the new one goes in on top.

We checked this by pushing a 1000 and then 101 ones: when you add everything up, the result is 101, not 1101, because the 1000 at the bottom fell off when the last 1 went in. In practice you won't reach 101 except through a bug (a number that gets pushed on every pass and nobody pops), but it is worth knowing that it gives no warning.

Popping from an empty stack

There is no error when popping from an empty stack either. Each stack has its own rule:

For example, this bot pushes nothing before the store: it pops the address 52 fine, but the value comes off the empty stack and is 0. If address 52 held another number, it ends up at 0:

cond
start
  52 store
stop

And by the rule of empty = true:

Some stack operators have asymmetries inherited from DarwinBots 2.48.32 that the port preserves as they are:

OperatorWith an empty stackWith a single value
duppushes two zerosduplicates it
dupbooldoes nothingduplicates it
overdoes nothingpushes a 0 on top
overbooldoes nothingpushes true on top
swap, swapbooldo nothingdo nothing

When they are emptied

At the start of each bot's turn, in every cycle, both stacks start empty. Nothing passes from one cycle to the next through the stacks: whatever you want to remember you have to store in memory (see Free and epigenetic memory). This bot leaves a 7 on the stack at the end of its turn; in the next cycle the store doesn't find it and writes 0 to address 50:

cond
start
  50 store
  7
stop

Within a single cycle, however, the integer stack is not emptied between genes. A number left over in one gene can be used by the next. Here the first gene pushes a 7 and the second stores it at address 51:

start
  7
stop

start
  51 store
stop

It works, but it makes the bot fragile: if the first gene doesn't run, the second finds something else. It is better for each gene to leave the stack as it found it.

The boolean stack has two moments of cleanup:

An oddity: the boolean that survives

A gene that begins directly with start (without cond) doesn't clear the boolean stack. If the previous gene left a false on top, that false blocks the stores of the new gene, even though the gene runs. In this bot address 51 is never written:

start
  1 2 = 3 50 store
stop

start
  4 51 store
stop

Opening the second gene with cond is enough for the boolean stack to start clean and the 4 to be stored. The false keeps ruling in all the genes that come after, until the next cond. This is behavior from the original DarwinBots that the port keeps so that old bots behave the same. If you write genes with conditions in the body, open every gene with cond, or end the body with clearbool.

Conditions inside the body

A condition can also be evaluated between start and stop. It doesn't decide whether the gene runs, but the top of the boolean stack governs all the stores that follow: if it is false, they don't write; if it is true or the stack is empty, they do. The store looks at the top without popping it, so the same result keeps ruling until you pop it with dropbool, cover it with another condition, or empty the stack with clearbool.

cond
start
  1 2 > 7 53 store
  dropbool
  8 54 store
stop

Since 1 is not greater than 2, the 7 isn't stored in 53; after the dropbool the stack is left empty (true) and the 8 is stored in 54. Careful: the condition only stops the stores. The numbers and operators in the body run all the same.

The Bestiary bot “Alga_Pair 1.1.1” uses this technique in one line: it counts one more generation only in the cycle in which it is born (when .robage is 0) and immediately discards the condition so it doesn't stop the rest of the gene:

def generation 971

cond
start
  .generation *.robage 0 = inc dropbool
stop

Note that inc is also a store, which is why the condition stops it. The full technique, with more examples, is in Inline conditions.

Summary

Integer stackBoolean stack
Size101 values101 values
On overflowthe oldest is lostthe oldest is lost
Popping when emptygives 0counts as true
Emptiedat the start of the bot's turnat the start of the turn, at every cond and when start decides
Passes from one gene to the nextyes, within the same cycleonly if the next gene doesn't open with cond
Passes to the next cyclenono