ATR3 Robot Programming Tutorial

This tutorial is meant to show you how to program your first robot with ATR3. This is not a comprehensive documentation! It is only meant to get you comfortable with the environment so you may experiment further on your own. For more detailed information, read the ATR3.HTM file that was placed on your computer when you installed ATR3.


Understanding the Language

The programming language ATR3 uses is very similar to assembly code, which is extremely low level. I'll just quickly introduce the main aspects of the language so we can start designing.


Commands are small groups of letters that tell the compiler what the next line means. So for example, this text:

jmp @main

will tell the compiler to jump to the @main label and continue from there (more on labels below). All the commands are listed and explained in the ATR3 documentation, so we'll not list them here. The basic idea is that a command, followed by one or two arguments (such as variables, labels, or ports) makes up an instruction for the compiler.


A label looks like this, and is placed before a command:


So in context that line might look something like this:

@shoot out 40 0

A label always starts with a "@" symbol which is immediately followed by a series of letters. These usually spell a word that indicates what the portion of code does, like "shoot" or "turn". However, it can be whatever you want, as long as it's made up of letters.


Variables are locations in the robots memory that can have numbers stored in them. In ATR3 numbers may not have decimal digits, and can only be between -32768 and 32767. To declare a variable, use this code:

#var varname

This makes a variable named "varname". When you want to use it, you must refer to it as:


So in a line of code it might look like:

out 10 <varname>

(Just in case you're wondering, this sets the robots throttle to the value stored in varname.)

Input and Output

This brings us to input and output: how do you get information about the robot's environment and then tell the robot what to do?

To do these things we must use what are called "ports". Ports are basically numbers we pass to the "in" or "out" commands to specify what we want to know, or what we want to change. So in the previous example:

out 10 <varname>

This tells the robot to set port 10 (the throttle) to the value of varname. If we wanted to know what the current throttle setting was, we could write:

in 8 <varname>

This would get the input from the throttle (port 8 for input) and store that value in the varname variable.


Commenting your robot program is extremely important: it helps you and other humans know what the program is doing. A comment looks like this:

//This text is overlooked by the compiler

In context, it might look like:

out 10 100 //Full speed ahead

The importance of commenting your code cannot be stressed enough! If you leave comments out, let's just say you'll be sorry when you come back to modify the program and you can't tell what is going on.

You can put anything you want as a comment, as long as it starts with "//". Anything on the line after that will be disregarded by the compiler.

Designing a Strategy

Now for the fun part: thinking up how your robot is going to decimate the competition. What weapon do you want to use? How do you want the robot to behave? You can't just have the robot go straight and shoot; it would soon run into the corner and start to self destruct.

For the sake of simplicity, we are going to create a very simple robot strategy: turn in a circle until you see another robot, then shoot your laser at it while moving towards it. Let's break this down:

  • Move forward & turn
  • Do I see a robot?
    • Yes
      • Fire laser
      • Turn back so I am going straight again
  • Start over

This is indeed the simplest strategy that has any chance of working, and it works relatively well. Let's implement it and then see how we can improve upon it later.

Equipping your Robot

The first thing we need to do is type up the code that tells the compiler what the robot looks like and what it has on it. Before you get carried away and start thinking of killer robots that have hundreds of weapons, remember: a robot can only haul so much weight. If you want several weapons, you'll have to give up other things, like good armor or a fast engine.

NOTE: I have created an application to aid in the creation of the equipment code. It has a few bugs, like the weight calculator being a few pounds off sometimes, but it is a great tool and easy to use. You can download it here.

Name and Colors

The first thing to do is name our robot and give it a color. Open ATR3 and type this in the big text box on the right:

#name Killbot

#color $777777 //Grey robot

This will tell the compiler two things:

  1. The robot's name is Killbot
  2. The robot's color is grey

You can change the name by changing "Killbot" to something else, but you may only use letters or the "_" symbol (which will be turned into a space by the compiler).

Now what the heck does that color code mean? Simple: it looks like this, under the hood:


In other words, the first pair of digits are a hex value from 0 - 255 representing the blue amount, the second pair of digits are a hex value from 0 - 255 representing the green amount, and the third pair of digits are a hex value from 0 - 255 representing the red amount.

Another option you have is a separate turret color: you might want, say, a yellow hull and a white turret, for example. If so, include this code after the other code:

#tcolor $0000FF //Red turret

P.S. Note the use of the comments.

Hull and Material

The next part of the program is called the equipment section. This is where we define what our robot is made out of. Start with this:


Next we need to pick what hull we want to use and what material it should be made of. There are lots of hulls and lots of materials, and if you want a complete list you can look in the documentation. For simplicity, we'll just use a triangular hull made from Iridium, the strongest material available:

hull 0 4 //Triangle, size class 4
material 19 //Iridium

This means that we are using the triangular hull (hull 0) of size class 4 (which carries 400 lbs.), and that it is made from Iridium (material 19).


If you want your robot to be able to move and turn you'll need to give it an engine. Again, there are lots of engines available, but we are going to use the E444, which has a max speed of 4, acceleration of 4, and max turn speed of 4. Add this code:

engine 7 //E444

We put a "7" because that's the ID of the E444 (look in the documentation for the IDs of the other engines. The IDs of all the hulls and materials are there too, as well as the IDs for everything else).


In order to mount weapons or scanners on our robot, we will need a turret. Since this robot just has one weapon and one scanner both facing the same direction, we'll use a single slot turret. Type this code:

turret 0 //Single slot

This tells the compiler we want the turret with a single slot (turret 0), which has one slot at position 0.


Woohoo! Let's add a laser to this baby. Type this in:

weapon 8 0 //Laser at direction 0

This places a laser (weapon 8) on the turret at the slot facing direction 0.


There are lots of different ways for a robot to find out where the other robots are, but let's just do the easiest one and use a D-F-Arc scanner (D means it returns the distance to the nearest robot, F means the arc is fixed, and cannot be changed during runtime). Enter this code:

scanner 11 0 //D-F-Arc at direction 0
arcd 3 0 //Distance = 300
arcw 6 0 //Arc width = 6

This means that a D-F-Arc scanner (scanner 11) will be placed in the slot facing 0, and that this scanner will be able to detect robots in an arc the extends 300 units, and spans 12 (6 in each direction).

Weighing In

Alright, let's close the equipment section:


Now the full code should look like this (unless you changed something, like the name):

#name Killbot

#color $777777 //Grey robot

hull 0 4 //Triangle, size class 4
material 19 //Iridium
engine 7 //E444
turret 0 //Single slot
weapon 8 0 //Laser at direction 0
scanner 11 0 //D-F-Arc at direction 0
arcd 3 0 //Distance = 300
arcw 6 0 //Arc width = 6

Right click the Compile button and make sure "Weigh" is selected; then click the Compile button. You should see a window that says this:


Robot Current Weight: 356

Robot Maximum Weight: 400

Perfect! Now if you want you can go back and add, say, a faster engine, but let's leave it be for now.

Programming the Robot

Here comes the interesting part. Now is the time to go back to that strategy we had. Let's start by putting it all in comments (put this under the equipment section):


//Turret straight
//Full speed ahead

@main //Turn
//Anybody there?
//Nope, start over

//Turn straight
jmp @main //Start over

You'll notice we only coded the parts that have to be there; everything else is just comments. Let's start filling it all in.

The first thing to do is set the turret pointing straight ahead and then start moving forward. Replace those comments with this code:

out 30 0 //Turret straight
out 10 100 //Full speed ahead

There we go. Now if you run the robot it will point the laser straight forward and start moving. Let's make it turn now:

@main out 11 3 //Turn

This makes the robot turn 3 every cycle. If you try running the program now, it will go straight forward and turn in a rather tight circle. Time to implement scanning:

in 50 ax //Scan
cmp ax -1 //Anybody there?

This reads the value of port 50 (the scanner) into memory (at location ax). The next line then compares the value in memory to -1, the value the scanner returns if it can't see any robot. Now we need to make a decision:

je @main //Nope, start over

This will jump to the @main label if the value in memory equals -1 (the command stands for "jump if equal"). Any code after this will only be executed if the value in memory and -1 are not equal. Therefore, the shoot code should come next:

out 40 0 //Shoot

This outputs the value 0 to port 40, which happens to be the laser. Next we need to turn straight:

out 11 -3 //Turn straight

Now all the code (except the equipment section) should look like this:


out 30 0 //Turret straight
out 10 100 //Full speed ahead

@main out 11 3 //Turn
in 50 ax //Scan
cmp ax -1 //Anybody there?
je @main //Nope, start over

out 40 0 //Shoot
out 11 -3 //Turn straight
jmp @main //Start over

Tada! This code works. If your code is different, just copy and paste the above code, instead of doing all the intermediate steps all over again.

Into the Arena!

There are still a few minor things you need to do before entering the arena. Here they are, step-by-step:

  • Click the Save Robot button and give your robot a filename (like "Killbot")
  • Click the Send to List button to place your robot in the robot list, or click the Add Robot(s) button and select the file you just saved your robot to
  • Check the checkbox next to your robot's name in the robot list
  • Check the box of another robot as well (Don't have any? This dummy robot works great for testing, and there are lots more on the robots page)
  • Click the Start Battle button
  • Turn the speed down to, say, 0% (it's still pretty fast)
  • Click the Start Match button

Now you can watch your robot go crazy destroying the dummies (or other robots) you put in the arena.


After watching a few matches, you might notice a few things that could be improved:

  • The robot always slams into the other robot, damaging itself
  • The robot dies pretty darn fast

The reason for the second one is simple, but hidden: the laser heats up with use, and after it gets too hot the robot will start to take damage, or even explode. This can be fixed pretty easily. Replace this code:

out 40 0 //Shoot
out 11 -3 //Turn straight

With this code:

in 40 ax //Get the temperature
cmp ax 270 //Is the laser too hot?
jge @turn //Yes, turn back straight though
out 40 0 //Shoot
@turn out 11 -3 //Turn straight

Now the robot will check the temperature of the laser: if it's too hot, it'll skip shooting. Now try your robot.

You'll notice that although we've fixed the second problem, the first still exists: the robot self-destructs by ramming into its target. We leave this to you to fix. If you have any trouble, try taking a look at the code in the Marauder robot; it implements a nearly identical strategy.

Further Learning

The best way to learn more about programming is to look at other robots, read the documentation, and most of all, program lots and lots of robots. Have fun! I'll see you in the arena.

Did we miss something?

If you notice that I got something wrong or left something out, please notify me immediately through the contact page; you'll get credit on this tutorial.