DarwinBotsManual
Open the app EspañolES

The structure of a bot

A bot is a text file with its DNA: genes one after another, comments, def and words separated by spaces.

A DarwinBots bot is a text file. Inside it is its DNA: a program written with words separated by spaces, which the engine reads once, when loading the bot, and turns into a list of tokens. From then on the text no longer matters: every cycle the bot runs that list from start to finish (the details are in Execution and costs and The cycle and the order of actions).

This page shows you the general shape of a bot. What the file looks like on the inside (line endings, headers, what's lost when exporting) is in The .txt format.

A minimal bot

This is a complete bot. You can paste it into the The DNA editor and seed it:

' My first bot: always moves forward
cond
start
10 .up store
stop

It moves forward every cycle, faster and faster. Line by line:

A start with no cond in front also works and always runs: start 10 .up store stop does the same as the bot above.

Genes, one after another

A real bot has several genes, written one after the other. They don't nest: cond, start, else and stop are flat markers that switch execution on and off while the bot goes through its list. The usual form is this:

cond
  *.nrg 5000 >
start
  50 .repro store
stop

cond
  *.nrg 1000 <
start
  10 .up store
stop

The first gene reproduces when energy goes above 5000; the second pushes forward when it drops below 1000. The exact rules for each marker, including an inherited quirk of else, are in Genes: cond, start, else and stop.

Two things worth knowing right away:

Comments

There are two ways to comment:

/******************/
/* REPRODUCTION */
/******************/

cond
*.nrg
5000
>
start
50
.repro
store
stop

In the middle of a line, the slash comments nothing: stop // done leaves two extra words (// and done) that the loader turns into zeros. The fragment above also shows that line breaks have no meaning: writing one word per line or the whole gene on a single line gives the same bot.

def, at the start

A line that starts with def gives a name to a memory address:

' Counter: pushes for 5 cycles and then coasts
def pasos 50

cond
  *.pasos 5 <
start
  10 .up store
  .pasos inc   ' adds 1 to address 50
stop

From the def on, writing .pasos is the same as writing 50, and *.pasos reads what's at that address. The bot pushes for five cycles, address 50 reaches 5 and the gene stops running; the bot keeps moving by inertia.

def lines go at the top, before the first place where you use the name: the loader resolves each name at the moment it reads it, and one defined further down is 0. The value has to be a number; def mov .up doesn't copy the address of .up, it leaves mov at 0. All of this, in more detail, in Variables with def.

The words of the DNA

Outside of comments and def lines, the loader splits each line at spaces (and tabs) and turns each word into a token. There are only a few kinds:

What you writeWhat it isExample
A numberIt's pushed as is10, -5
* and a numberReads that memory address and pushes what's in it*50
. and a nameThe address of a sysvar (or of a def): it's a number.up is 1
*. and a nameReads that sysvar*.nrg
An operatorDoes arithmetic, compares or writesadd, >, store
A flow markerOrganizes the genescond, start, else, stop, end

Numbers go from −32768 to 32767; one with decimals is rounded to the nearest integer (on a tie, to the even one: 2.5 is 2). More on addresses and ranges in Numbers and addresses, and the operators grouped by family in Operators by family.

Note that .up without an asterisk reads nothing: it's only the address number, ready for a store to use. To read the contents you need the *. A loose * also reads: .nrg * is the same as *.nrg (see *).

Uppercase and lowercase

Operators, flow markers and sysvar names are recognized regardless of case: COND *.NRG 1000 > START 10 .Up STORE STOP is a valid bot. The names you invent with def, on the other hand, are case-sensitive: if you defined pasos, .Pasos isn't the same thing.

What the loader rejects

Almost nothing. The loader doesn't reject words: any word it doesn't recognize is turned into the number 0, and a .name that doesn't exist is 0 too. A typo loads without complaint and does something else:

' Deliberate error: .upp doesn't exist
cond
start
10 .upp store
stop

Here .upp is 0 and the store writes nowhere: the bot doesn't move. That's why the The DNA editor checks the DNA and warns you about words it doesn't recognize, with a suggestion (in this case, .up). The list of usual stumbles is in Common mistakes.

The whole bot is rejected, and doesn't enter the simulation, in only two cases:

Genes without a stop, an extra stop or stray conditions load anyway and run under the usual rules.

An inherited quirk: the first token and def

DarwinBots 2.48.32 has a quirk that the port preserves: if the bot has any def and its first token is not a flow marker (cond, start, else or stop), that first token is lost on loading. For example:

def pasos 50
5 cond start 10 .up store stop

That 5 disappears. Since what comes before the first cond never runs, the bot behaves the same; what changes is the count of its DNA: .dnalen says 7 instead of 8 (it also counts the final end), and the Mutations work on the already-trimmed list. The editor warns you when it happens. The fix is simple: start the code with cond or start, as almost all bots do.