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:
- Click Duplicate to edit, at the top right.
- Type the Name of the new bot, or leave it empty: it gets the same name with “ 2” at the end.
- Click Duplicate. The copy opens, already editable.
The top bar
From left to right:
| Control | What it is |
|---|---|
| Text, By gene and Tiles | The three ways of viewing the DNA (text, gene by gene or tiles). |
v3 | The last saved version. |
| unsaved | Shows up when the text has changed since that version. |
| 4 warnings | How many warnings there are below the text. |
| Stack | Turns 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. |
| Lab | Switches the right-hand panel to the one with Bestiary genes. |
| Version note and Save v4 | Save 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:
- flow-control ones (
cond,start,else,stop,end); - the other commands and operators (
add,store,>…); - sysvars and your
defvariables (.up,*.eye5); - numbers, and separately, reads of an address written as a number (
*50); deflines, whole;- comments, in italics, and struck through the disabled genes;
- underlined with a wavy line, the words that a warning marks.
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.
| Key | What it does |
|---|---|
| ↓ / ↑ | Move through the list. |
| Tab | Accepts the picked name. |
| Enter | Also 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. |
| Escape | Closes 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:
- In Text, the gene where the cursor is. An
elseopens a gene of its own, so theelsebranch shows in its own gene and not next to thestartbranch. - In By gene, the gene you last unfolded.
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:
| Column | What it shows |
|---|---|
| Word | The word from the DNA, with its colors. |
| Integers | The number stack after that word. If there are more than 8, a “+k” counts the ones that don't fit. |
| Booleans | The true-or-false stack: ✓ true, ✗ false. |
| Note | What 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:
- Are kept in this browser, for this bot. They don't go into the bot, they are not part of its versions and they don't travel with a file. Since they don't touch the bot, they can also be changed on forum bots.
- Only sysvars in the vocabulary get a field (
*.eye5,*.nrg…).defvariables (*.paso) have no field: the viewer doesn't know the address the engine assigns to them, so in the trace they are 0.
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| Word | Integers | Booleans | Note |
|---|---|---|---|
*.eye5 | 80 | ||
> | ✓ | ||
store | writes 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:
- Where: “Line 12 · gene 3”, or “Whole DNA” if it is about the entire file. A click takes you to that line. Line numbers with warnings are also marked.
- What is going on, with the word and, if it repeats, how many times (“(3 times)”).
- Fix, when there is a safe repair: it replaces that word with the suggested one throughout the DNA, outside comments.
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:
| Example | Warning | What 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
endThe 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
endBelow 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:
| Column | What it shows |
|---|---|
| Gene | The gene's number, counted the way the engine counts it (see Genes: cond, start, else and stop). |
| Name | The comment line right above the gene, if there is one. If not, “(unnamed)”. |
| Origin | Where the gene came from, if it came from the Lab: “← Bot name, gene 4”. |
| Active | yes 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
endHere 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.
| Gesture | What happens |
|---|---|
| Click a tile | It 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 empty | Deletes the tile, and the extra space. |
| Click a + | An empty field opens there. Enter inserts the word. |
| Enter on the last tile of a line | Opens 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 line | It'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
- It doesn't reorder whole genes. You drag tiles, not genes. To turn a gene off, use By gene.
- There's no tap-a-tile-then-tap-the-slot mode. On a touch screen, drag the tile with your finger onto the +. The palette works the same way: a tap puts the word in, and dragging it puts it where you let go.
Saving versions
Your bots keep their complete history. To save:
- If you want, type a Version note (“turns faster”, “without the shooting gene”).
- 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:
- Restore brings back an earlier version by saving it as a new version: the history is never lost. If you have unsaved changes, it asks first (with Restore anyway you go ahead); in text mode, those changes come back with Ctrl+Z.
- Compare shows how two versions differ: the starting one and the ending one, which you pick in the two dropdowns. The comparison goes gene by gene: it counts the equal, changed, added and removed genes, and shows the changed ones side by side.
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.
| Field | What it is | Default |
|---|---|---|
| Copies | How many identical bots are seeded (from 1 to 50). | 10 |
| Cycles | How long each run lasts (from 10 to 200,000). | 5000 |
| Seeds | How many runs, each with different chance (from 1 to 16). | 3 |
| Rules | F1: the F1 league settings, with costs. No costs: the values the classic interface starts with. | F1 |
| Seed | The first seed; the others derive from it. With the same one, the test gives the same result. | 1 |
| Scenario | With algae: 15 algae to eat. Alone (no algae): your copies by themselves. | With algae |
The button says what is being tested and against what:
- With no unsaved changes: Test v4 against v3. If the bot has only one version, Test v1 runs with no comparison.
- With unsaved changes: Test changes against the last saved version.
- On a forum bot: Test this DNA, with no comparison.
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:
| Row | What it measures |
|---|---|
| Survive | How many of the initial copies are still alive at the end. |
| Offspring per copy | Direct 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 end | The size of the population when it finishes. |
| Mean energy | The energy per living bot when it finishes. |
| Extinctions | In 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:
| Field | What it is | Default |
|---|---|---|
| Variants | How many variants you ask for, from 1 to 16. There may be fewer (see below). | 8 |
| Intensity | How 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× |
| Mutations | In life and in reproduction, Only in life or Only in reproduction: which family of mutations runs. | In life and in reproduction |
| Copies and Cycles | As 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:
| Column | What it measures |
|---|---|
| Genes changed | How many genes of the base the variant changed: changed, added and removed. |
| Survive | How many of the copies from the start are still alive at the end, averaged over the seeds. |
| Offspring per copy | Direct children of each copy, on average (as in Test). |
| Mean energy | Energy 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:
- View diff opens the gene-by-gene comparison between the editor's current text and the variant, with the same view as Compare in the versions.
- Adopt brings into your text only the genes the variant changed; the rest keep their text and comments. Comments inside a changed gene are lost. The text becomes an unsaved change, and the version note suggests something like “evolution: variant 3 (seed 1234, intensity 4×)”. Adopt doesn't save a version: if you like the result, save it like any other change. In text mode, Ctrl+Z undoes it.
- Another round from this one generates a new round with that variant as the base, without adopting it in the editor. The new round's table says “Base: variant n from the previous round.” View diff and Adopt keep comparing against the editor's current text, so after another round they show the accumulated changes, not only those of that round.
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:
- by capability: you pick one (venom, photosynthesis, sexual reproduction…) and the genes that have it appear, from any bot. Filter by bot… narrows it by name.
- from one bot: you type the bot's name and all its genes appear.
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:
| Warning | What is going on | Fix |
|---|---|---|
| “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.