A bot that moves
Your first bot from scratch, step by step: the minimal gene that moves forward, how to aim and turn, and a complete bot that roams the world turning every so often.
We're going to write your first bot from start to finish. We begin with the smallest DNA that does anything, add turning, and end with a bot that roams the world: it always moves forward and every so often turns to a new heading. Each step adds one piece to the DNA and tells you what you should see. The full theory of the language is in The structure of a bot and Genes: cond, start, else and stop; here we write.
Step 1: open a new bot
- Go to the Bots section, in the top bar.
- Click + New bot and give it a name (for example, “Walker”).
- The profile opens, on the DNA tab: that's the editor. As you type, it colors each class of word, autocompletes the names of the sysvars and immediately warns you about words that the engine would read differently from how they look (see The DNA editor).
There's no need to save all the time: the editor keeps a draft of what you type. To record it as a version, use the Save v… button at the top, with its Version note if you like.
Step 2: the gene that moves forward
Every bot that does anything has at least one gene, a piece of DNA with this shape. Type:
' My first bot: always moves forward
cond
start
10 .up store
stopcondopens the gene and starts the condition section. Betweencondandstartwe put nothing, and a gene with no conditions always runs.startopens the body: what the gene does.10 .up storeis a command. Numbers pile up like plates: first the 10, then the address.up(which is 1).storepops the top two and writes the value underneath at the address on top: it leaves 10 in.up. That's why you writevalue address store, never the other way around (the stack rules are in The integer and boolean stacks and Writing to memory).stopcloses the gene.
And .up is the sysvar that asks for a push forward, toward where the bot is pointing. Writing to its memory is the only way a bot has of acting: moving, turning, shooting and reproducing are always stores.
Note that .up goes without an asterisk: it's the address, a number. To read what's in that cell you need the asterisk, *.up (the mix-up is a classic: Common mistakes).
Step 3: seed it and watch it
- In the bot's profile, click Seed: the seeding dialog opens.
- Leave Number of bots at 5 and Starting energy at 3000, and pick a Color that stands out.
- Pick Seed into the current run if you have a world running (if there isn't one, the button is disabled), or New scenario with these, which opens it in Experiment so you can start it from there.
What you should see: the five bots head forward, faster and faster. When we ran this DNA with the engine, the speed of one of them, cycle by cycle, was this:
| Cycle | 1 | 2 | 3 | 4 | 5 | 6 | 7 onward |
|---|---|---|---|---|---|---|---|
| Speed | 7 | 13 | 20 | 26 | 33 | 40 | 40 |
Two things to understand what you saw:
.upisn't a speed: it's a push. Each one is added to the speed the bot already had, so by pushing every cycle it accelerates up to the simulation's cap (40 by default; the bot reads it in.maxvel). And since this world doesn't brake, if it stopped pushing it would keep gliding all the same (Physics).- The command is carried out in the same cycle and isn't kept. First the DNA of all the bots runs; then, in the forces and collisions phase, the engine gathers the push you asked for, and in movement it applies it and sets the cell back to 0. That's why the gene runs every cycle and asks for the push again. The whole order of the cycle is in The cycle and the order of actions.
If a bot doesn't move, it's almost always one of three typing slips, and all three are covered in Frequently asked questions: the store written backwards, a misspelled sysvar, or the missing start.
To look at it up close, click on a bot. In the inspector, the Summary has Genes active this cycle (here, gene 1 in all of them) and the Memory tab lets you query any cell: in .up you'll always see 0, because the engine has already used it; .aim tells you the heading (see The inspector).
Step 4: aim and turn
A bot also has a heading: the direction it points and the direction .up pushes. It's read in .aim, on a scale where one full turn is 1256 units: 0 is the right of the screen, 314 is up, 628 is left and 942 is down. Each bot is born pointing in any direction.
There are two ways to turn it, and you'll see both in every Bestiary bot:
.setaimturns to an absolute heading: you write where you want it to point and it stays there. It accepts any number (it uses the remainder of dividing by 1256) and only acts if the requested heading differs from the current one..aimsxand.aimdxturn by an amount: 50 per cycle to the left or the right, respectively.
Try changing the body of the gene like this:
' Always aims up and moves forward
cond
start
314 .setaim store
10 .up store
stopIn our run, it turned to 314 in the first cycle and from then on it goes up; writing 314 over and over doesn't make it shake. Note, though: the push is computed with the heading from before the turn, so the first push goes the old way and only in the next cycle does it move toward where it asked. And since nothing brakes it, the speed it had from the start keeps dragging it a little sideways while it climbs.
Now, turning at random. rnd replaces the number on top of the stack with one drawn between 0 and that number, both included: 1256 rnd gives any possible heading.
' New random heading every cycle
cond
start
1256 rnd .setaim store
stopRun it, and it walks like a drunk: every cycle it heads off in a different direction and barely gains speed. It's useful for seeing that turning is just one more store; to really explore, it's better to turn every so often, not all the time.
Step 5: the complete bot
This tutorial's bot always moves forward and every so often changes heading: a long straight stretch, a turn, another straight stretch. It takes two genes:
' A bot that moves: goes forward and turns every so often
' Gene 1: always pushes forward
cond
start
10 .up store
stop
' Gene 2: once in so many times, a new random heading
cond
20 rnd 0 =
start
1256 rnd .setaim store
stop
endGene 1 is the usual one. Gene 2 now has conditions, and takes advantage of the fact that in the condition section everything runs except stores: 20 rnd draws a number between 0 and 20, and 0 = asks whether 0 came up. It comes up one time in 21 on average; the rest of the time, the body doesn't run and the bot keeps going straight. When it does come up, the body picks a new random heading. To make it turn more often, lower the 20; to make it turn less, raise it.
When we ran it for 120 cycles, it kept its speed at the cap and turned about five times: it went straight for a stretch, changed heading, kept going, turned again… What it doesn't do is dodge the edges: when it reached a wall it kept pushing against it and sliding sideways until it got a heading that took it away. If you want it to turn when it touches the edge, add a gene that turns while .edge is 1: the example is in Movement.
This “move forward and turn” skeleton is the one the Bestiary's explorers have used for over twenty years. Jez's First bot 4G (March 2004), for example, turns 150 to the right every cycle while it sees nothing, and when it sees something it moves forward and shoots; a fourth gene of his also turns if what it sees turns out to be one of its own: your bot plus a pair of eyes, a shot and a relative-dodger. The eyes are added in the next tutorial.
What to try next
- Speed and friction. The cap of 40 and the efficiency of the push are world settings, and friction, fluid or gravity completely change how a bot slides. The mechanism is in Physics and you play with the values in Experiment.
- Energy and costs. In the built-in scenarios, except the league matches, moving costs nothing. But where costs are turned on they're really charged: with the F1 rules every push, every turn and every DNA instruction costs energy, and a bot that only moves forward can starve to death. How each thing is charged is in Energy, body and waste (and watch out: the editor's quick test, Test, uses the F1 rules by default).
- The next step: give it eyes and something to hunt, in A bot that looks for food.