DarwinBotsManual
Open the app EspañolES

Operators by family

An overview of the DNA operators grouped by family: what each one takes from and leaves on each stack, and the most common ones with an example.

DNA is written in reverse Polish notation: the data comes first and then the operator that uses it. 3 4 add pushes a 3, pushes a 4, and add pops both and leaves a 7. There are no parentheses and no precedence: the order of the words is the order of the calculations.

Operators work on two stacks, the integer one and the boolean one (they are explained in The integer and boolean stacks). Depending on which stack they touch and what they do, they are grouped into families. Each family has its own page in the reference, with the complete table of its operators and their cost:

FamilyTakes fromLeaves onWhat for
Basicintegersintegersarithmetic and stack handling
Advancedintegersintegersangles, distances, roots, trigonometry
Bitwiseintegersintegersworking with the bits of a number
Comparisonsintegersbooleanasking questions (greater, equal, close…)
Logicbooleanbooleancombining answers (and, or, not)
Writing to memoryintegersmemorystoring values and giving commands
Flow——marking where each gene starts and ends

There are also bare numbers and memory reads such as *.eye5, which only push a value: Numbers and reads covers them and Numbers and addresses explains them.

How to read the descriptions

On this page the stack is written a b, with b on top of everything (the last one to go in). So a b sub computes a − b: 10 3 sub gives 7.

No operator ever fails. If the integer stack is empty, popping from it gives 0; if the boolean one is empty, it counts as true. Each stack has 101 slots; if it fills up, the oldest value is lost without warning. A misused operator doesn't break the bot: it does something, even if it isn't what you wanted.

The operators of the first five families run inside a gene, both in the condition (after cond) and in the body (after start or else). Outside a gene, for example before the first cond, they do nothing. The writing ones, on the other hand, run only in the body.

Basic

These are the arithmetic and the tools for arranging the stack. All of them pop their operands from the integer stack and leave the result right there.

A few oddities worth knowing, because that is how 2.48.32 behaved:

An example with rnd and mod: the bot changes heading at random every 20 cycles of life (.robage) and always moves forward. A full turn is 1256 angle units, so 1256 rnd is any direction at all.

' Changes heading at random every 20 cycles and moves forward
cond
*.robage 20 mod 0 =
start
1256 rnd .setaim store
stop

cond
start
10 .up store
stop

Advanced

More elaborate calculations, almost all of them meant for getting around the world:

The Bestiary bot 4-d_Swarmer uses angle with .refxpos and .refypos (the position of what it is looking at) to turn toward a vegetable: *.refxpos *.refypos angle .setaim store. It looks just as good with a fixed point: this bot aims at (3000, 2500) and moves toward it (if it doesn't brake, it overshoots).

' Aims at the point (3000, 2500) and moves toward it
cond
start
3000 2500 angle .setaim store
10 .up store
stop

Bitwise

They treat the number as 32 bits. &, | and ^ do the bitwise and, or and exclusive or of the top two; ~ inverts all the bits; << and >> shift the bits one place (multiplying or dividing by 2, and >> keeps the sign: -5 >> gives −3); ++ and -- add or subtract 1.

They are useful for keeping several flags in a single cell. *740 4 | 740 store turns on the bit with value 4 in cell 740, and *740 4 & gives 4 if it is on or 0 if it isn't.

Comparisons

These are the questions of the DNA. Each one pops integers from the integer stack and leaves one result, true or false, on the boolean one. With a b on the stack:

OperatorIt is true if…
< · >a is less than · greater than b
<= · >=a is less than or equal to · greater than or equal to b
= · !=a is equal to · different from b
%= · !%=b is · is not within 10% of a
~= · !~=with a b d: b is · is not within d% of a

100 105%= is true and 100 115%= is false; 100 115 20 ~= is true. An inherited oddity: if a is negative, %= and ~= always give false.

In a gene's condition you can put several comparisons in a row: on reaching start, all of them are required to be true. This bot moves forward only while it has more than 1000 energy (.nrg):

' Moves forward while it has more than 1000 energy
cond
*.nrg 1000 >
start
10 .up store
stop

A comparison can also go in the body, and then it decides whether the writes that follow it are carried out; that is Inline conditions.

Logic

They work only on the boolean stack. and, or and xor combine the top two results; not inverts the top; true and false push a constant. And the boolean stack has its own set of tools: dupbool, dropbool, swapbool, overbool and clearbool.

Since start already joins all the conditions with an and, or is the one you write most: without it there is no direct way to ask for “this or that”.

' Moves forward if cell 740 is 0 or cell 741 is 0
cond
*740 0 =
*741 0 =
or
start
10 .up store
stop

If an operand is missing, it counts as true (the empty boolean stack is true). That is why not on the empty stack gives false, and a cond start with no conditions always runs its body.

Writing to memory

These are the only ones that change anything outside the stacks: they write to the bot's memory, and writing to certain addresses is giving a command (move, shoot, reproduce). The most common is store: 10 .up store stores 10 at the address of .up and the bot moves forward. There are variants that operate on what is already in the cell: inc and dec add or subtract 1, addstore adds a value, negstore changes its sign, and so on up to fourteen.

They run only in a gene's body and only if the top of the boolean stack is true (or it is empty). Address 0 writes nothing. All the details, including how the written value is clipped, are in Writing to memory.

Flow

They don't calculate anything: they mark the structure. cond opens a gene and its condition, start opens the body that runs if the condition came out true, else the one that runs if it came out false, and stop closes the gene. end ends the reading of the DNA; the loader adds it by itself at the end, so you don't need to write it. How they combine is in Genes: cond, start, else and stop.

Unlike the rest, these markers always run, even in a gene that is being skipped, and each one charges its cost.

A Bestiary trick: calculations instead of conditions

Some authors write entire bots without conditions, using arithmetic. The trick relies on the fact that dividing by zero gives 0: x dup div is 1 if x is not zero and 0 if it is. And x dup div 1 sub abs is the other way around: 1 if x is zero. Multiplying by that “turns on” or “turns off” a value. Bardus, by Moonfisher, takes the idea to the extreme: the whole bot is a single store on one very long line.

A small version: move forward 10 if the central eye (.eye5) sees nothing, and stay still if it sees something.

' Moves forward only if the central eye sees nothing, no conditions
cond
start
*.eye5 dup div 1 sub abs 10 mult .up store
stop

It is harder to read than the cond version, so when you are starting out, stick with that one. What each operator costs is covered in Execution and costs.