Quick-start tutorial

By Dennis C. Bemmann

Note

This text assumes that you have RoboCom Workshop 3.x. If you are using an earlier version, the programming will be about the same, however the interpreter's environment will be slightly different.

So what is RoboCom?

A programming game! Your task is to program little robots which can move, communicate with others and build more robots. The challenge is to put the others robots out of action using brains, not force: write a virus and infect them. Or re-program them to work for you!

Some basics of the game and its IDE

(IDE = integrated development environment)
We want to see a simulation, no? So open a new one (click the Sim button in the toolbar at the top). Yes, do it right now! There is an area with many tiny squares, we call it the board. This is where the robots "live". If you walk out one side, you come in again at the opposite side. Math freaks call this a torus.

Left of the board and just below the tool bar, you see the control bars which allow you to control the simulation. With the upper-rightest button on these bars you can turn the visibility of the board on and off, but you might want to leave it turned on for now, since you want to see what happens.

Some robots

A click on the "Programs" banner opens the program selection dialog. Here you can select which programs you want to have in your simulation. The left box shows all programs found on disk and the right one shows which ones you want to load. Should you not see ANY programs, you have to set the correct path in the Preferences dialog (Prefs button). Now load the two example programs "Black Jacks" and "Pesticide!".

You will see two robots appear on the board - yes, those little colored things are robots. You can see an arrow pointing into one direction on them: this is the direction they are facing - let's say their head. The field in front of a robot is called the "reference field" (whoa, cool word!). They can scan it, move there or build new robots there. In the control bar you can see which programs are loaded and how many robots each program has (currently one).

Some action

Now start the simulation (use the buttons in the control bar that look like the transport controls of a tape recorder). You'll notice that most of the speeds are quite slow (designed for debugging robots). The speed of the three-arrow-button can be configured with the slider next to it. You will see that new robots are produced, run across the board and so on.

Visualisation of robot properties

Some robots have a yellow X on them. This just means they are currently de-activated (refer: the #active variable). Deactivated robots are still alive but not doing anything. They're just relaxing. However they are not dead since they can be activated again by other robots). Robots which do in fact die, disappear from the board immediately. Like the Black Jacks, which should be gone soon... such is fate.

By the way: did you notice that the robots have a black border, and others don't? This is because they have different capabilites, let's say they are different types of robots (refer: instruction sets).

You can reset the simulation by clicking on the double-arrow button in the Programs panel. You'll probably find out quickly how the rest in the control bar works.

Over to you

Ready for doing your own stuff now? Okay, so open a new editor (take the built-in editor by clicking on Edit), choose a blank template and type in (or simply copy) the following lines:
Published Name Tutorminator 1.0
Published Author Robert Robot
Published Country Nomansland
Published Language RC300

; My first RoboCom program!
This is general information about the program: its name (Tutorminator), its author's name (Robert Robot) and his home country (Nomansland). If you're not Robert Robot or you live elsewhere, you may (of course) change those details. RC300 is the RoboCom language standard we are using.

By the way: there are much more of these so-called headers that allow you to save for example your e-mail address, a funny comment and much more information with your program. There is a whole document about them.

Text behind a semicolon is just comments and ignored by the interpreter. Let's now write the actual program:
Bank Main
  @Loop
  Turn 0
  Create 1, 1, 1
  Jump @Loop
The first line (with Bank in it) explains to the interpreter that a new code bank begins here. In RoboCom, program code is organized in so-called banks. A bank can contain up to 1000 instructions and a robot can have quite a lot of banks (to be exact: up to 50, but that's unimportant for now). Main is the name of this bank.

@Loop is a label, like everything that starts with @. You can refer to labels in jumps (you'll see that in a minute). So the program execution will start with the instruction Turn 0. This tells the robots to turn around 90 degrees. If the parameter (the number behind it) is 0, it will turn left, otherwise right. So our robot will turn left in this case.

Then it reaches the instruction Create 1, 1, 1. Create means: build a new robot, so our robot will build another one on its reference field (remember that word?). The parameters of the Create instruction specify, what kind of robot shall be built. Consult the manual if you want to know more about this. By the way: parameters are always separated by a comma.

The next instruction is a Jump. That tells the robot that the program execution goes on elsewhere. The parameter after Jump is the number of instructions to jump forward. So if we wanted to Jump to the Turn instruction, this would be -2 (two instructions back). Instead this mysterious label stands here again. In fact, it represents a number (RoboCom will count the distance to the label declaration) and... hey, it's also -2! (no, not -3, we count instructions and nothing else: @Loop itself is a label). So, the robot will continue with the Turn instruction (and turn left again).

Now let's see if it works. Save the program as tuto.rob and load it into the simulation (smart guys and girls know how to do that). Oops, there are still the other robots? Well, take them out of the simulation (in the program selection dialog) - we just want to see the Tutorminator alone for now. After starting the simulation, you'll see: it really turns left and builds robots.

And you learned another thing: new robots (that have just been built) are always inactive. This is logical because they don't have a program. They are just empty. However, robots NEED a program to survive! If we would just activate them now, they would die of a Data Hunger.

Building more robots

There is another reason why new robots are inactive at first: we need to give them a program before we activate them. Let's change our Tutorminator program so that it looks like this:
Published Name Tutorminator 2.0
Published Author Robert Robot
Published Country Nomansland
Published Language RC300

Bank Main         ; Daddy Tutorminator's program
  @Loop
  Turn 0            ; turn around, that's cool
  Create 1, 2, 1    ; build a mobile child with 2 banks
  Trans 2, 1        ; transfer RunAround into the first bank
                    ; the second bank is left empty
  Set %active, 1    ; activate our baby
  Jump @Loop        ; ...and start over

Bank RunAround    ; Program for the runners
  @Run
  Move              ; one field ahead
  Scan #1           ; what's in front of me?
  Comp #1, 1        ; is it an opponent
  Jump @NoOpponent  ; no, let's examine it
  Trans 2, 1        ; yes! Overwrite his first bank with my empty one!
  Turn 0            ; turn left
  Jump @Run         ; and keep on moving

  @NoOpponent      ; so what's there actually?
  Comp #1, 0        ; a free field?
  Turn 0            ; ìf not (if it's a friend), turn left
  Jump @Run         ; and now in every case: run

It works! But how?

This program almost explains itself, doesn't it? Okay here you go: a short summary. Please consult the manual for an exact description of how the instructions work.

The first robot runs the Main bank. It turns left, then builds a robot with advanced instruction set (1) and 2 banks which is mobile (1). This child gets the RunAround bank (the second bank of it's daddy) copied to it's first bank.

Remote values and time management

Now, the child gets activated: we're setting the variable %active to 1. While variables with the # character are always variables of the robot itself, the % character specifies that this is a remote value. Remotes are the variables and constants of the robot on the reference field, i.e. the new-built child. After activating the child, our main robot starts over and builds more, while the child already starts moving.

Note that robots of the same program can act at the same time. In contrast to some other games (like CoreWar), multiple robots do not have to share one timetable - in fact, every robot acts in every cycle. In other words: if you build many robots, their programs don't get slower. The program in a robot always executes at the same speed, regardless of how many robots there are.

The RunAround bank

The runner first moves a field ahead. Then it scans its reference field and stores the result in variable #1. A robot has twenty 16bit integer variables (#1 to #20) for whatever use. The scan returns 0 for a free field, 1 for an opponent robot or 2 for a friend (robot of the same player). The Comp instruction compares if two values are equal. If they are, the next instruction is skipped. So in our case, if there was an opponent robot, the program continues with the trans instruction, otherwise (if there was no opponent detected), the program jumps elsewhere for further examination. Opponents get the second bank copied in their first one. Since we never stored any program in the second bank of a runner, it should still be empty and thus erase the opponent's first bank. The rest is obvious.

Epilogue

I'm lazy, you know. But with this information you should be able to code pretty good bots if you only think a bit. It's recommended however, to take a look in the long manual to find out about predefined constants and some more stuff. But don't worry, that's easy. The best tip I can give you is: look at other bots and find out how they work. Also the built-in debugger is very helpful. If a program seems complicated, you can still very easily get key information about it by running it: see what structures it builds, what kind of robots its uses and which banks they usually run in. And now get your editor going and hit the charts with your creations!

Tips for your RoboCom program