Concepts of RoboCom

An Introduction by Dennis C. Bemmann

About this document

This document explains the basic concepts of RoboCom. You can use it in two ways:

Note: even if you hate reading manuals, I strongly recommend reading this text sooner or later. It contains essential information you will need for your RoboCom programs, and it's not likely that you will figure out everything by yourself.

The game

RoboCom is 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!

The board

The game takes place on a square board which conists of square fields (like a chess board!). Typical sizes are between 16*16 and 32*32 fields.

The board is relative and a torus: there are no absolute coordinates for any field. A robot which leaves the board at one side will emerge again on the opposite side. Therefore there is no way for the robot to find out where it is -- such an information would be meaningless since all fields are identical and there are no borders. A robot can, however, find out how large the board is.

The game starts

When the game starts, every program begins with a single robot which is placed on a random field, facing a random direction. This robot contains all of the program's code.

Usually, the initial robots of each program will build more robots and give them certain programs.

Directions and reference fields

Robots can communicate with their environment. In addition to the instructions that affect the robot itself, its data and its program, a robot can also affect the field it is facing. This field is called the robot's reference field.

Each robot has a head that faces one direction, and thus determines the reference field. It also determines the direction in which the robot walks when moving. A robot can turn its head in order to face a different direction.

Note: When multitasking is enabled, the robot has one head for each task. The tasks need not face the same direction.

A robot's heads are visualized by small triangles.

Mobility

When building a robot, the builder decides whether the new robot should be mobile or not. Mobile robots can move across the board. Immobile robots stay on the same field for all their lives, but they can be built faster.

Note: an immobile robot can not be "mobilized" once it is built. Mobility is determined upon the creation of a robot.

Activity

Robots can be temporarily deactivated. That means they get into a state in which they do not execute program code and thus simply do nothing. An inactive robot does not act, however it still continues existing and can also be re-activated again.

Note: an active robot can deactivate itself. Of course, an inactive robot cannot activate itself, because it does not execute any code. A robot can activate and deactivate other robots.

Note: RoboCom interpreters visualize that a robot is inactive by crossing it out with an X.

Code banks

The program code of a robot is organized in so-called code banks. A bank can contain up to 1000 instructions and each robot can have up to 50 banks.

Most programs are based on cooperation between multiple robots which perform different actions. Since the first robot is alone at first and yet needs to build more robots, it also has to program them for their purposes. Thus, the first robot must contain all code which any robot of the program's team is ever going to execute - even if the first robot will never execute this code itself. Code banks were introduced to logically separate different programs and to make them exchangeable as whole logical units.

The term "running bank" refers to the bank of a robot which is currently being executed. There are various instructions which enable a robot to jump from one to another bank and to copy a bank from one robot to another.

Note: Robots with more banks usually require more time to be created.

Instructions

Each code bank consists of a list of instructions. They control the robot's actions.

There are about 30 different instructions: arithmetic and comparison instructions, jumps (which make the program continue at a different point), movement instructions, scans (have the robot look around), code transfer instruction (put some of your code banks into other robots) and the create instruction (which builds a new robot).
This page describes all instructions in detail.

Instruction sets

Some instructions are more complex than others. It is possible to build robots which can only execute a subset of the instructions. Building robots with limited capabilities takes less cycles than building omnipotent robots and can therefore save time if you don't need the full functionality.

Instructions are classified in so-called instruction sets. A robot can execute all instructions that are part of its instruction set.

There are three instruction sets:

In RoboCom Workshop, the instruction set of each robot is visualized by its black border: a higher instruction set means more border.

Note: each instruction set also contains all instructions from instruction sets lower than itself.

Note: for a list of all instructions and what sets they belong to, please see the Instruction reference.

Parameters

Most instructions take parameters which define exactly what they do. For example, the code transfer instruction TRANS takes two parameters: the source bank number (the code bank containing the code to be transferred, located in your bot) and the target bank number (located in the bot in front of yours, where you'd like to put the code).

In RoboCom, parameters can either be plain numbers, labels (locations in your program), constants (information about the robot or the game options) or variables (the robot's memory which can hold your calculation results).

Labels

Every label marks a location in your program code. Labels are usually used together with jumps to continue the program execution at a different point. Label names begin with an @ and each label can only be defined once. To define a label, the label is inserted within the instructions in a bank.

Have a look at a program implemented in 2 ways:
; RoboCom program  
Name Old  
Bank Main program
Add #1, 1  
Turn 1  
Jump -2  
; RoboCom program 
Name Now-with-label  
Bank Main program 
@Loop
Add #1, 1 
Turn 1 
Jump @Loop 
The programs behave identically: the robot increments its variable #1, turns 90 degrees to the right, and starts all over again. In the program Old the jump is implemented using Jump -2, which jumps 2 instructions backwards, i.e. to the Add instruction; in the program Now-with-label the same instruction is referred by the @Loop label, in Jump @Loop.

Constants and Variables

In RoboCom, constants are used to find out information about robots and simulation options. They all start with the $ sign. For example, the $Banks constant finds out how many code banks the robot running the program has, and the $Fields constant specifies the width (and height) of the board.
You can use these constants like any plain number in your program.

Variables can be used to store calculation or scanning results. Every robot has 20 normal numerical variables (called #1, #2, ..., #20) and its special #Active variable which determines its activity: if #Active is at least 1, the robot is active, otherwise it is not.

A few of the constants and variables of the robot on the reference field are also available: the so-called remotes. Remotes have names beginning with %. The available remotes are

%Banks   : the number of memory banks the remote robot has (constant).
%Mobile  : the remote robot's mobility (constant).
%InstrSet: the remote robot's instruction set (constant).
%Active  : the activity of the remote robot (can be modified).
These remotes correspond to the respective local variables or constants of the remote robot.
Note: It usually takes longer to access remote variables than local ones.

This page lists all constants and variables in RoboCom.

Comments


Comments can be added to a program to make it more readable. They are ignored by the interpreter. Comments begin with the ; character and can either be placed at the beginning of a line or after a statement. E.g.:
; This is a comment.
Add #4, 1 ; The variable #4 is incremented by 1.

Exceptions and errors

Errors can occur from time to time, either because a robot is executing a wrong program transferred to it by another robot, or because the programmer made a mistake. There are several categories of such situations:

Assembly errors

An assembly error occurs when the program contains an obvious mistake that can be detected at assembly time. For example when an instruction does not have enough parameters. A program cannot be loaded until all assembly errors have been corrected.

Tolerable exceptions

Tolerable exceptions are unexpected situations during runtime, which are handled according to certain rules. For example, if a robot tries to access remote variables when the reference field is empty, simply all values read will be 0 and all values written will be lost. The amount of time taken in this case is the same as with the proper execution of the instruction. An exception has no further consequences.

Fatal errors

Fatal errors occur during runtime when a robot tries to perform an illegal or impossible operation. These are not tolerated and therefore fatal: as a consequence the robot dies. For example, an immobile robot that tries to execute the MOVE instruction will die. If error reporting is switched on, an error message which describes the type of error in more detail will be generated.

Auto-Reboot

When during the execution of its program, a robot reaches an empty position in one of its memory banks, it reboots from the first instruction in the first bank. The program directly continues at that position. If the first bank is empty, the robot dies. The Glossary contains more detailed information on Auto-Reboot.

Data Hunger

If a robot, upon being activated the first time or after an auto-reboot, finds its first memory bank empty, it dies of "data hunger". Note that this works differently when Multitasking is enabled. The Multitasking FAQ contains more information on that topic.

Eliminations

When a robot variable overshoots or falls below a certain adjustable value after an ADD or SUB instruction, the so-called "elimination trigger" is released: the robot gets eliminated which means, it dies and is removed from the board. The Glossary contains more detailed information on Eliminations.

That's all.

Sounds complicated? Well, actually it's very very simple once you get used to it. If you want to write a simple program now, take a look at the quick-start tutorial.