DarwinBotsManual
Open the app EspañolES

The DNA editor

The DNA tab of a bot's profile: the text with colors and autocomplete, the gene view and the tiles mode, the warnings about what the engine reads differently, the step-by-step stack of each gene, versions, Test, Evolve and the gene Lab.

The DNA editor is the DNA tab of each bot's profile (see Bots: library and profile). There you write the bot's program, see what the engine will read differently than it looks, save versions and test each change against the previous one without leaving the page.

This page explains the tool. How to write a DNA is in the language chapter, starting with The structure of a bot.

Your own bots and forum bots

Only your bots can be edited. Forum bots (the Bestiary) open in read mode, with the notice “Forum bots are read-only: to change this one, duplicate it as your own bot”. You can still read them, go through them gene by gene, test them and look at the Lab.

To modify one:

  1. Click Duplicate to edit, at the top right.
  2. Type the Name of the new bot, or leave it empty: it gets the same name with “ 2” at the end.
  3. Click Duplicate. The copy opens, already editable.

The top bar

From left to right:

ControlWhat it is
Text, By gene and TilesThe three ways of viewing the DNA (text, gene by gene or tiles).
v3The last saved version.
unsavedShows up when the text has changed since that version.
4 warningsHow many warnings there are below the text.
StackTurns the step-by-step stack viewer on or off. In Tiles it doesn't change the view: there the stack appears when you hover over a tile.
LabSwitches the right-hand panel to the one with Bestiary genes.
Version note and Save v4Save the text as a new version (see Versions).

To the right of the text, in Text and By gene, are the Stack panel (if you turned it on), the Test panel and, on your own bots, Evolve and Versions. In Tiles that spot is taken by the Palette (see The tiles): Stack, Test and Evolve don't show, and Versions stays below. With the Lab turned on, in any mode, that spot is taken by the genes panel, and the stack, the palette, Test, Evolve and Versions don't show until you turn the Lab off: the Stack button stays in the bar, but the panel waits.

Text mode

It is an ordinary text field, with line numbers and colors. Typing, selecting, copying, pasting and undoing work as in any browser field. Long lines aren't wrapped: the text scrolls sideways.

The colors tell each class of word apart:

A word that doesn't fit in any class stays uncolored: it is usually a mistake, and the matching warning says so.

The colors follow the rules of the engine's loader. For example, a line that starts with def is painted as a definition even if it says defensa, because that is how the engine reads it (see Variables with def).

Undo

Ctrl+Z (the browser's undo) undoes what you typed and also what the buttons do while you are in text mode: completing a sysvar, using Fix on a warning, adding a gene from the Lab or restoring a version. Each one goes into the undo history as if you had typed it. What you change in the gene view (turning a gene off or on) doesn't. In Tiles the undo is a different one, specific to that mode: see Undo in Tiles.

Sysvar autocomplete

When you type a dot followed by letters (.ey, or *.ey to read), a list opens with up to 12 matching names. Each one shows its address; your def variables appear first and say private.

The list puts the exact name first, then the ones that start with what you typed and finally the ones that contain it. With .aim typed, .aim goes before .aimdx.

KeyWhat it does
↓ / ↑Move through the list.
TabAccepts the picked name.
EnterAlso accepts, unless what you typed is already a full name: then it closes the list and inserts the line break. So typing .up and pressing Enter leaves .up.
EscapeCloses the list.

A click on a name in the list also accepts it. Inside a comment the list doesn't appear.

Autocomplete is only for names with a dot. Operators and commands are typed out in full: if one ends up misspelled, a warning marks it.

The step-by-step stack

The Stack button in the bar opens a viewer that shows, step by step, how the engine runs the gene under the cursor: what is left on the number stack and on the true-or-false stack after each word, and what each store writes. It shows at a glance why a condition gives what it gives, without guessing from reading the DNA. How the two stacks work is in The integer and boolean stacks.

The panel appears on the right, above Test and Versions. The button stays on or off in this browser: when you come back, it is as you left it. In Tiles the panel doesn't appear; the stack still shows when you hover over a tile (see The tiles).

The panel shows:

The header says which gene it is (Gene 2, with its name if it has a comment line above it) and whether the condition came out true or false. If the gene has an else, it also says which branch ran.

The table has one row per word of the gene:

ColumnWhat it shows
WordThe word from the DNA, with its colors.
IntegersThe number stack after that word. If there are more than 8, a “+k” counts the ones that don't fit.
BooleansThe true-or-false stack: ✓ true, ✗ false.
NoteWhat happened: “writes up (1) ← 50” on a store that wrote; “does not run with these values” on the first row of a block the engine doesn't run.

Grey rows are the ones the engine doesn't run with the example values: for example, the body of the start when the condition is false. The engine doesn't run that body, so there is no stack to show. To see it, change the example values until the condition is true.

Example values

A gene can read sysvars with an asterisk, like *.eye5. Their value depends on the bot in the simulation, so the viewer needs one. Below the stack's title there is a field for each vocabulary sysvar the gene reads, starting at 0. Change it to see how the condition changes.

These values:

From the inspector, the DNA tab can open the editor with the bot's real memory as example values: Open in the editor takes the DNA to a new bot, with the stack turned on and the values the bot had at that moment, only for the sysvars the DNA reads. Those values live in the session: they aren't saved as the bot's examples until you change one. If you change one, the whole table (with the other values from the inspector) becomes that bot's examples.

With *.eye5 at 80, this gene's condition is true, and the store writes 50 into .up, address 1:

cond *.eye5 50 > start 50 .up store stop
WordIntegersBooleansNote
*.eye580
>✓
storewrites up (1) ← 50

With *.eye5 at 30, the condition is false: the start doesn't run, and its block shows in grey.

The hover summary

Without typing anything, hover over a sysvar or an operator in the text: a card appears with its summary from the manual and the Open in the manual link, which opens its page in another tab. It is useful for reading what .shootval does without leaving the editor. Comments give no card, and if the site's manual isn't available, it doesn't appear (the editor works the same).

Warnings

The engine rejects almost nothing: a word it doesn't understand is 0, silently, and the bot loads anyway (see Common mistakes). That is why the editor checks the text as you type, with the same rules and the same word tables the engine uses when it loads a bot, and shows you below the text every word the engine will read differently than it looks.

Each warning has three parts:

The check waits until you stop typing for a moment. If the engine couldn't load, the editor says so (“The DNA check is not available”) and there are no warnings.

These are all the warnings, with an example of each:

ExampleWarningWhat it means
.upp“.upp is not a sysvar: the engine reads it as 0. Did you mean .up?”A name with a dot that doesn't exist, similar to a sysvar. Fix puts in the suggested name.
.zzqq“.zzqq is not a sysvar and has no def: the engine reads it as 0.”A name with a dot that doesn't look like anything.
.50“.50 is not a sysvar […]. Did you mean address 50? Addresses go without a dot.”A number with a dot. Fix removes the dot (*.50 becomes *50).
.otra, with its def further down“.otra is defined further down: the engine reads the DNA in order and here it is 0. Move the def up.”The engine resolves names as it reads: a later def doesn't work. See Variables with def.
.Paso, with def paso“.Paso does not match its def: private variables are case-sensitive and here it is 0.”Sysvars are not case-sensitive; your variables are.
up“up is 0: missing dot? .up”The name of a sysvar without the dot. Fix adds it.
swapp“swapp is not a command or a number: it is 0. Did you mean swap?”A word one letter away from a command, or with two neighboring letters swapped (sotre), only for words of 4 letters or more. If two commands fit, it suggests the one that starts the same: stor gives store, not stop.
hola“hola is not a command or a number: it is 0 (text without the ' comment mark?).”Any other loose word. Often it is a comment missing its '.
store with an invisible character in the middle“… has an invisible character: it is not recognized as store and is 0.”It happens when copying from web pages or word processors. Fix cleans it.
ññ“… has invisible or encoding characters: it is 0.”Letters outside basic English, or a broken encoding.
50store“50store reads as 50: “store” is lost (missing space?).”A number with something stuck to it. The engine takes the number and discards the rest. Fix inserts the space.
def nrg 5“The private variable nrg hides the sysvar .nrg in the whole bot.”A variable with the name of a sysvar wins over it across the whole DNA. See Variables with def.
defensa 50“Every line that starts with “def” is a definition: defensa defines the variable nsa. […]”The engine reads as def any line that starts with those letters. If it was text, it is missing the '.
def x .up“The value of a def must be a number: in def x, “.up” reads as 0.”The value of a def is written with digits. See Variables with def.
A DNA with def that starts with 10“With defs, the first word (10) is not flow control and is lost.”A quirk inherited from the original. See The structure of a bot.
40000, or def pasos with no value“The engine rejects this DNA (error 6: a number outside ±32767 or a malformed def).”The only case where the bot doesn't load. See The structure of a bot.

This DNA puts several of those mistakes together:

def paso 30
cond
*.nrgg 100 >
start
.paso .up store
30 .upp store
30 up store
10 50store
stop
end

The editor marks *.nrgg (suggests *.nrg), .upp (suggests .up), up (missing the dot) and 50store (missing a space). Fixed:

def paso 30
cond
*.nrg 100 >
start
.paso .up store
30 .up store
30 .up store
10 50 store
stop
end

Below the engine's warnings come the Lab's, which are explained in its section.

The gene view

By gene shows the DNA as a table, one row per gene:

ColumnWhat it shows
GeneThe gene's number, counted the way the engine counts it (see Genes: cond, start, else and stop).
NameThe comment line right above the gene, if there is one. If not, “(unnamed)”.
OriginWhere the gene came from, if it came from the Lab: “← Bot name, gene 4”.
Activeyes or no. A click toggles it.

Each gene expands to show its code, and a button at the top collapses or expands all of them. Genes with warnings carry a mark with the count.

Turning a gene off turns it into a comment: each of its lines starts with '#off . The engine doesn't run it, but it stays in the text and turns back on with a click. It is useful for trying out what happens without a gene without having to delete it:

' Move
cond
start
10 .up store
stop
' Turn
'#off cond
'#off *.eye5 0 =
'#off start
'#off 30 .aimdx store
'#off stop
end

Here the “Turn” gene is off: the bot only moves.

The tiles

Tiles shows the same DNA split into words: each word is a tile, and the tiles are grouped by gene, just like in By gene. It's for changing, inserting and moving words without rewriting the whole line.

The text is still the source. Each action in Tiles replaces words in the text, and when you go back to Text the DNA is the same. Tile actions don't touch comments or indentation: they change the word or the place of the tile and leave the rest of the line as it was. The exception is comment lines, def lines and the lines of disabled genes, which are edited whole with one click.

Each gene is a card with its number, its name and its origin. Inside, each line of code is a row of tiles. Between two tiles there's a +: a slot where a word fits. The + signs are faint and show clearly when you hover over the line. On the left, each zone of the gene gets its label (condition, body, else). Lines outside every gene go in a card called Outside genes, and a disabled gene looks dimmed.

GestureWhat happens
Click a tileIt turns into a field with its word. Type the new one: suggestions appear below, which you go through with ↑ and ↓. Enter or Tab applies it; Esc cancels.
Delete with the field emptyDeletes the tile, and the extra space.
Click a +An empty field opens there. Enter inserts the word.
Enter on the last tile of a lineOpens a new line with the same indentation, with the cursor on its +.
Drag a tile onto a +Moves it there. While you drag, the target + is highlighted. If you drop outside every +, nothing happens.
Click a comment line, a def line or a disabled gene's lineIt's edited whole: the whole line changes.

The palette

In Tiles, the right-hand panel is the Palette, with the words you can put in the DNA. It has a search box at the top and these collapsible groups: the sysvars, grouped by theme (each one appears as .x and as *.x); the operators, by use (flow, arithmetic and comparison, logic, stack and stores); and Your defs, with the DNA's private variables. The search filters all the groups at once.

A click on a word puts it in the DNA, at the last + you touched or where the last action left the cursor. If you haven't touched any yet, it goes at the end of the text. Dragging it onto a + puts it there. The palette doesn't know which gene you're in: in Tiles there's no "gene under the cursor", so the word goes where the last + points or at the end. Hovering over a word shows its summary from the manual, as in the hover summary.

With the Palette in the side panel, Stack and Test don't show. To test the DNA, go back to Text or By gene. Versions stays visible on your bots.

The stack when you hover over a tile

Hovering over a tile shows a box with the stacks left after that word: the numbers, and the trues and falses with ✓ and ✗, as in the step-by-step stack viewer. The stack is worked out even when the Stack button is off, and the button doesn't change anything in this mode.

Only words that the engine runs with the example values have a stack. In the body of a start that doesn't run, hovering shows nothing. Nor does it show anything if the DNA doesn't load or the trace doesn't match the text. The example values are changed in the stack viewer, in Text or By gene.

Undo in Tiles

Ctrl+Z undoes and Ctrl+Y (or Ctrl+Shift+Z) redoes, with the focus on the view. While you're editing a tile they don't act: the field has its own undo.

This undo is specific to the mode. It saves the DNA after each Tiles action (changing, inserting, moving or deleting a tile, putting in a palette word, and also restoring a version or recovering a draft). What you do in Tiles doesn't go into the undo of Text. The history is emptied when you change mode or bot: when you come back to Tiles, it starts from the text there is.

What Tiles doesn't do

Saving versions

Your bots keep their complete history. To save:

  1. If you want, type a Version note (“turns faster”, “without the shooting gene”).
  2. Click Save v4 (the number is that of the version about to be created).

A version stores the exact text: a change in a comment or in the indentation is also a change. If you didn't touch anything, the app doesn't create another version and tells you so.

What you haven't saved isn't lost

While you type, the editor keeps a draft of the bot in this browser. If you switch tabs, pick another bot or reload the page, when you come back you find your changes with the notice “You have unsaved changes from last time: they were restored”, and a Discard the changes button in case you don't want them.

If in the meantime the bot changed somewhere else (for example, you restored a version from the profile), the editor doesn't mix anything: it offers you Recover the changes or Discard the changes. And if you try to close the page with unsaved changes, the browser asks you to confirm.

The Versions panel

The panel on the right lists the versions, from newest to oldest, with their note and their date:

Test

Test runs your bot without drawing it, at full speed, and tells you how it did. If it has an earlier version, it runs that one too with the same seeds, so the comparison is fair.

FieldWhat it isDefault
CopiesHow many identical bots are seeded (from 1 to 50).10
CyclesHow long each run lasts (from 10 to 200,000).5000
SeedsHow many runs, each with different chance (from 1 to 16).3
RulesF1: the F1 league settings, with costs. No costs: the values the classic interface starts with.F1
SeedThe first seed; the others derive from it. With the same one, the test gives the same result.1
ScenarioWith algae: 15 algae to eat. Alone (no algae): your copies by themselves.With algae

The button says what is being tested and against what:

The test runs in the background: you can keep editing, switch bots or close the editor, and it keeps going. While it runs you see the percentage and a Cancel button. When it finishes, the panel shows a table with the two versions side by side, averaged over the seeds:

RowWhat it measures
SurviveHow many of the initial copies are still alive at the end.
Offspring per copyDirect offspring of each founding copy, on average (without grandchildren).
Births per copy (with grandchildren)All the births of the species, divided by the copies.
Alive at the endThe size of the population when it finishes.
Mean energyThe energy per living bot when it finishes.
ExtinctionsIn how many seeds the species disappeared.

Each test is recorded in the bot's history.

Evolve

Evolve takes variants of your DNA with the engine's mutations, tests each one—and the base—with the same seeds, and shows you which one did best. It helps you see whether a random change helps or hurts the bot. It only shows on your own bots, below Test, and it doesn't show in Tiles mode or with the Lab turned on, just like Test (see the top bar).

Each variant is one pass of the engine's mutations over the base DNA, with the type and intensity you chose. They are the ones described in Mutations: in life, the point mutations (mutation types), and in reproduction, the changes the DNA suffers when it is copied to the child. The engine's rates say how often each one happens. Four types that are off in a new simulation (a second point mutation, a second copy error, translocation and amplification) don't run here, nor do the Delta mutations, which change the bot's rates and not its DNA. The variants are generated in disposable sims of the engine, not in your simulation: your bot doesn't change until you adopt one.

The fields of the panel:

FieldWhat it isDefault
VariantsHow many variants you ask for, from 1 to 16. There may be fewer (see below).8
IntensityHow often the DNA mutates. With 4× the engine's rates are divided by 4, and with 16× by 16: a rate of 5000 becomes 1250 at 4× and 312.5 at 16×. At 1× the bot's rates apply as they are.1×
MutationsIn life and in reproduction, Only in life or Only in reproduction: which family of mutations runs.In life and in reproduction
Copies and CyclesAs in Test: how many identical bots are seeded and how long each run lasts.10 and 5000

The scenario, the rules and the seeds of each test are the Test defaults: with algae, F1 rules and three seeds. The panel doesn't show them.

Each round draws a random seed, shown below the button together with the intensity.

When you click Generate and test, the engine builds the variants and the test of the base and of each one goes into the job queue. While the engine builds them the button says Generating…. With the queue running you see the percentage and Cancel, as in Test. You can keep editing or switch bots: the round stays in the queue, and each bot shows its own last round.

When it ends, the table shows the Base (your DNA, highlighted) and one row per variant, numbered from 1:

ColumnWhat it measures
Genes changedHow many genes of the base the variant changed: changed, added and removed.
SurviveHow many of the copies from the start are still alive at the end, averaged over the seeds.
Offspring per copyDirect children of each copy, on average (as in Test).
Mean energyEnergy per living bot at the end.

The variants are sorted by Survive and, on a tie, by Offspring per copy. Each one has three buttons:

Fewer variants may come out than you asked for: the ones that end up equal to the original DNA or to each other are discarded. If the engine doesn't produce any distinct one, the panel says: “The engine produced no distinct variants; raise the intensity.”

The variants you don't adopt aren't saved as versions. The round stays in the bot's history, under Quick tests, with the Evolution chip. When it ends, the jobs chip in the top bar leads to Compare (see background jobs).

The Lab

The Lab is for building a bot out of other bots' genes. When you turn it on, the right-hand panel becomes Bestiary genes, with the genes of all the forum bots.

There are two ways to search:

self-contained only leaves just the genes that don't use own memory: they can be transplanted without dragging dependencies along or overwriting other genes' addresses.

Each gene in the list says which bot it is from, how many words it has, whether it uses own memory and which capabilities it contributes. A click on the gene shows its code below the list; the + button adds it to the end of your DNA. The gene remembers where it came from: you see it in the Origin column of the gene view and it is saved with each version.

Lab warnings

Putting together genes from different bots has traps, and the Lab warns about them below the text, with a one-click fix when there is one:

WarningWhat is going onFix
“Gene 3 (from X) reads address 52, which in its bot is written by gene 1.”The gene depends on a piece of data that, in its original bot, another gene prepared.+ gene 1: adds the missing gene.
“Address 60 is used by X, Y for different things […].”Two genes from different bots use the same memory cell for different things.Remap addresses: moves those of the following genes to free addresses, starting at 971-990.
“Gene 2 (from X) uses literal gene numbers in .delgene/.mkvirus that no longer point to the genes of its bot.”When moved, the gene numbers written by hand point to another gene (see .delgene and .mkvirus).Renumber, or add the missing genes.
“No gene reproduces: the bot will leave no offspring.”Informational.—
“No gene gets energy (neither hunting nor photosynthesis).”Informational.—

The last two only appear when the whole DNA comes from the Bestiary: for genes you wrote yourself, the Lab doesn't know what capabilities they have.

On a forum bot the Lab can be browsed, but + is off and the fixes don't appear: first you have to duplicate it.