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:
| Family | Takes from | Leaves on | What for |
|---|---|---|---|
| Basic | integers | integers | arithmetic and stack handling |
| Advanced | integers | integers | angles, distances, roots, trigonometry |
| Bitwise | integers | integers | working with the bits of a number |
| Comparisons | integers | boolean | asking questions (greater, equal, close…) |
| Logic | boolean | boolean | combining answers (and, or, not) |
| Writing to memory | integers | memory | storing 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.
- Calculations:
add(sum),sub(subtraction),mult(product),div(division),mod(remainder),abs(absolute value),sgn(sign: −1, 0 or 1) andrnd(a random number between 0 and the top value, both included). - Stack handling:
dupduplicates the top,dropthrows it away,swapexchanges the top two,overcopies the second one to the top (a b → a b a) andclearempties the stack. *reads memory at the address on top:740 *is the same as*740, but the address can be calculated.
A few oddities worth knowing, because that is how 2.48.32 behaved:
divdoesn't truncate: it rounds to the nearest integer and, on a tie, to the even one.7 2 divgives 4,5 2 divgives 2 and100 7 divgives 14. Dividing by zero gives 0.modkeeps the sign of the dividend:-7 3 modgives −1 and7 -3 modgives 1.dupon an empty stack pushes two zeros.
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
stopAdvanced
More elaborate calculations, almost all of them meant for getting around the world:
angletakes a pointx yand gives the angle from the bot to that point, in the same units as.aim(0 to 1256).distgives the distance to the point.anglecmpcompares two angles and gives the signed difference, between −628 and 628: how far you need to turn, with the sign telling you which way.sinandcostake an angle in those units and return the sine or cosine multiplied by 32000:314 sin(a quarter turn) gives 32000.sqr(square root; 0 if the number isn't positive),pow(power:2 10 powgives 1024; the exponent is limited to ±10),root(27 3 rootgives 3),logx(logarithm in baseb:1000 10 logxgives 3) andpyth(3 4 pythgives 5, the hypotenuse).ceilsets a ceiling andfloora floor:x 100 ceilleavesxbut never more than 100, andx 0 floorleaves it but never less than 0.debugintanddebugboolleave a trace for debugging, which thedebugcommand in the The inspector console displays. They charge no energy and almost never change the stack (debugboolon an empty boolean stack pushes a true).
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
stopBitwise
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:
| Operator | It 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
stopA 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
stopIf 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
stopIt 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.