The R-Files

A Definitive RoboCom Reference by Florian Fischer

Intended audience

This document describes the exact results and all side effects of all RoboCom instructions, and how exactly a simulation is processed. To understand it, you should be quite familiar with most of the RoboCom concepts and you should have got some programming experience.
This document is mainly targeted at re-implementers of RoboCom who want to ensure that their interpreters are compatible with the original RoboCom interpreters. However, it may also help to find some possible optimizations for your bots, if you're an advanced RoboCom player. Last but not least, it can help you to find the bugs in your RoboCom programs (or even in the RoboCom interpreters) if something does not work as expected.

Typesetting conventions

To make reading this document easier, I have tried to keep to the following typesetting conventions:

Failure codes

In order to keep the instruction table below compact and yet precise, I am using failure codes there instead of error messages. Note that these are only the runtime errors which happen when an instruction is executed, not the load-time errors when it is read from the ROB file.
Following is a list of all the failure codes:

Code Description
ETElimination Trigger released
DHData Hunger (Bank 1 empty)
DZDivision by zero
IBInvalid bank number (e.g. in TRANS or BJUMP)
ISHigher Instruction Set required
MOMobility required
DIDIE executed
IPInvalid parameter (e.g. CREATE x,-1,x)
UENo more tasks left in a robot (Unemployment)
IDInstruction duration too high (i.e. > MaxInstrDur)

Processing One Cycle

In every simulation cycle, the RoboCom interpreter processes all of the bots on the board; the oldest one is processed first.
Each bot first switches to the next task (these are organized in a ring-like structure), if the current task is not seized.
Now, that task is processed. If the task executes a SLEEP and is not yet finished with it, the task immediately returns and the next task is processed as well. If that task sleeps as well, this is repeated until all tasks have been processed.
If the task, however, doesn't sleep, it processes the instruction as described below.
After all bots have been processed for the cycle, the RoboCom interpreter checks if all but one of the players have no longer got any bots. If so, it declares the simulation won for the remaining bots.
If, however, the Timeout'th cycle is reached, the simulation is declared a tie.

Processing One Instruction

Immediately after a instruction is loaded, the number of cycles it takes to execute is calculated. Some failures are already detected during this process; they may cause the bot to be destroyed. If the number of cycles calculated is greater than MaxInstrDur, the bot is destroyed as well (failure ID). Note that in the RC3 standard option set, the MaxCreateDur and MaxSleepDur options will prevent this from ever happening.

Now whenever the task to which the instruction belongs is activated again, it first augments the number of cycles used up for its current instruction. It then checks if its current instruction is ready to execute, i.e. if the number of cycles used up for it is greater than the number calculated when it was loaded. If that is the case, the amount of cycles it uses is calculated again (see above). (This was introduced to prevent the FAT cheat.) If the amount of cycles has changed, the task continues waiting. Otherwise, the instruction is executed. That may result in a failure and cause the destruction of the bot.

After the instruction was executed (but in the same cycle), a new instruction is attempted to be loaded. Depending on the executed instruction, the instruction pointer is now set to the next instruction (e.g. after a ADD) or to a entirely different (e.g. after a BJUMP). So the RoboCom interpreter first determines if the bot has got the bank the instruction pointer points to, and if that bank has got enough instructions for the instruction pointer.
If one of this is wrong, an auto-reboot is performed: i.e. the instruction pointer is set to the first instruction of the first bank of the bot. If the bot's first bank is empty, the bot is destroyed (Data hunger).
Otherwise, the new instruction is loaded and its required number of cycles is calculated (see above).

The Example Instruction

EXINST #dest, $src
The instruction's syntax. Note that the parameters are written as meaningful names (much like in a function declaration in a programming language) and that a # denotes that this parameter must be writable.
Requirements: The required language set for this instruction (Basic, Extended or Multitasking).
Number of cycles: This cell describes how the number of cycles the instruction takes is calculated. See also the common remarks above.
Failures: This cell specifies the failures which may occur when the number of cycles for this instruction is calculated.
Execution: This cell informs about the effects and side-effects when this instruction is executed.
Failures: This cell lists the failures which may occur when the instruction is exectued.
Remarks: This cell, if present, consists of any special notes and remarks to this instruction.

Instructions

Common remarks:

ADD #val1, $val2
Requirements: Basic
Number of cycles: durAdd
Failures: (none)
Execution: Adds $val2 to $val1 and sets #val1 to the result.
Failures: ET If EnableElim is enabled and abs($val1) is, after the adding operation, in a different one of the ranges [0, ElimTrigger] and [ElimTrigger + 1, 32768] than it was before.

 

AJUMP $pos
Requirements: Extended
Number of cycles: durAJump
Failures: (none)
Execution: Modifies the task's instruction pointer so that the next executed instruction will be the $pos'th of the current bank (starting from 1). If $pos is negative or greater than the number of instructions in the current bank, the task will reboot. That may result in a DH (data hunger) failure.
Failures: (none)
Remarks: If a label is used as the parameter $pos, AJUMP always uses it as an absolute position.

 

BJUMP $bank, $instr
Requirements: Basic
Number of cycles: durBJump
Failures: (none)
Execution: Modifies the task's instruction pointer so that the next executed instruction will be the $instr'th of the bank $bank. If the bot does not have a $bank'th bank, or that bank does not have a $instr'th instruction, the task will reboot. That may result in a DH (data hunger) failure.
Failures: IB If $bank is smaller than 0 or $bank is greater than MaxBanks.
Remarks: If a label is used as the parameter $instr, BJUMP always uses it as an absolute position.

 

BREAK
Requirements: Multitasking
Number of cycles: durBreak
Failures: (none)
Execution: Deletes all tasks in this bot, except the executing task. (In other words: returns to single-tasking mode.)
Failures: (none)

 

COMP $val1, $val2
Requirements: Basic
Number of cycles: durComp
Failures: (none)
Execution: Compares $val1 and $val2. If their values are equal, skips the next instruction of the current bank and continues with the after next instruction.
Failures: (none)

 

CREATE $iset, $banks, $mobile
Requirements: Basic
Number of cycles: min{(durCreate1 + durCreate2 * $banks) * (durCreate3 if $mobile) + (durCreate3a if $mobile) + (durCreate4 if $iset=1) + (durCreate5 if $iset=2), MaxCreateDur}
Failures: IS If the bot does not have the super instruction set.
IP If $iset is smaller than 0 or greater than 2.
IP If $banks is smaller than 1 or greater than MaxBanks.
IP If $mobile is smaller than 0 or greater than 1.
Execution: If there is already a bot on the reference field, does nothing. If the bot's $Generation is greater or equal than MaxGeneration, does nothing. If the bot's owner player has at least MaxBotNum bots, does nothing.
Otherwise, creates a new bot with the given instruction set, number of banks and mobility on the reference field. The new bot is de-activated (0) and initially contains only empty banks. The new bot has initially got one task which heads to the same direction as this task. The new bot belongs to the same player than this bot and has a one higher $Generation.
Failures: IP If $iset is smaller than 0 or greater than 2.
IP If $banks is smaller than 1 or greater than MaxBanks.
IP If $mobile is smaller than 0 or greater than 1.

 

DIE
Requirements: Basic
Number of cycles: durDie
Failures: (none)
Execution: Emits the failure DI and thus destroys the bot.
Failures: (none)

 

DIV #val1, $val2
Requirements: Extended
Number of cycles: durDiv
Failures: (none)
Execution: Performs an integer division of $val1 by $val2 and sets #val2 to the result. (Example: The command sequence SET #1, 5 ¶ DIV #1, 3 will set #1 to 1.)
Failures: DZ If $val2 is 0.

 

FARSCAN #type, #dist, $maxDist
Requirements: Extended
Number of cycles: durFarScan + durFarScanPerField * $maxDist
Failures: IS If the bot does not have the advanced instruction set.
IP If $maxDist is less than zero.
Execution: Scans up to $maxDist fields in the executing task's direction and places type (own / enemy, like SCAN) and distance of the closest bot in #type and #dist. If no robot is found on any of the fields, #type and #dist are set to 0. If #type and #dist are the same variable (e.g. FARSCAN #1,#1,10), the result is #dist.
Failures: IP If $maxDist is less than zero.

 

GCOMP $val1, $val2
Requirements: Extended
Number of cycles: durGComp
Failures: (none)
Execution: Compares $val1 and $val2. If $val1 is greater or equal than $val2, skips the next instruction of the current bank and continues with the after next instruction.
Failures: (none)

 

INIT $bank, $instr
Requirements: Multitasking
Number of cycles: durInit
Failures: (none)
Execution: If MaxTasks is 1, does nothing.
Creates a new task and makes it start at position $bank:$instr. If were not yet MaxTasks tasks in the bot (before creating the new one), the new task is simply appended to the task list. Otherwise, the oldest task which is not the executing task is removed first. If the executing task is seized, the new task is paused as well. The new task heads to the same direction as the executing task.
Failures: IB If $bank is smaller than 0 or $bank is greater than MaxBanks.
Remarks: If a label is used as the parameter $instr, INIT always uses it as an absolute position.

 

JUMP $pos
Requirements: Basic
Number of cycles: durJump
Failures: (none)
Execution: Modifies the task's instruction pointer so that the next executed instruction will be $pos instructions from the current instruction position of the current bank. (Example: JUMP 0 results in an endless loop, since the next instruction executed will be the current one, i.e. the JUMP 0, and so on.) If the jump results in an instruction position which is invalid for this bank (e.g. negative or too large), the task will reboot. That may result in a DH (data hunger) exception.
Failures: (none)

 

LCOMP $val1, $val2
Requirements: Extended
Number of cycles: durLComp
Failures: (none)
Execution: Compares $val1 and $val2. If $val1 is less or equal than $val2, skips the next instruction of the current bank and continues with the after next instruction.
Failures: (none)

 

MAX #val1, $val2
Requirements: Extended
Number of cycles: durMax
Failures: (none)
Execution: Sets #val1 to the greater one of the values $val1 and $val2.
Failures: (none)

 

MIN #val1, $val2
Requirements: Extended
Number of cycles: durMin
Failures: (none)
Execution: Sets #val1 to the smaller one of the values $val1 and $val2.
Failures: (none)

 

MOD #val1, $val2
Requirements: Extended
Number of cycles: durMod
Failures: (none)
Execution: Computes the remainder of the integer division of $val1 by $val2 and stores it in #val1. (Example: The command sequence SET #1, 5 ¶ MOD #1, 3 will set #1 to 2.)
Failures: DZ If $val2 is 0.

 

MOVE
Requirements: Basic
Number of cycles: durMove
Failures: MO If the bot is not mobile.
Execution: If the reference field of the executing task is free, moves the bot to it. Otherwise, this instruction does nothing.
Failures: (none)

 

MUL #val1, $val2
Requirements: Extended
Number of cycles: durMul
Failures: (none)
Execution: Multiplies $val1 by $val2 and sets #val1 to the result.
Failures: (none)

 

NCOMP $val1, $val2
Requirements: Extended
Number of cycles: durNComp
Failures: (none)
Execution: Compares $val1 and $val2. If their values are not equal, skips the next instruction of the current bank and continues with the after next instruction.
Failures: (none)

 

QUIT
Requirements: Multitasking
Number of cycles: durQuit
Failures: (none)
Execution: Deletes this task. The other tasks are continued normally. If this task was seized, the other tasks are resumed.
Failures: UE If the executing task is the only task in a bot.

 

RANDOM #dest, $start, $length
Requirements: Extended
Number of cycles: durRandom
Failures: (none)
Execution: Sets #dest to a random value between (including) $start and (including) ($start + $length).
Failures: IP If $length is less than zero.

 

RESUME
Requirements: Multitasking
Number of cycles: durResume
Failures: (none)
Execution: Continues execution of all other tasks. (In other words: returns to multi-tasking mode.) The other tasks are resumed at exactly the same bank, instruction and even number of cycles waited for their active instruction than they were before the seizing.
If there are no tasks except this one, or the tasks are already resumed, does nothing.
Failures: (none)
Remarks: See also SEIZE.

 

RTRANS $src, $dest
Requirements: Extended
Number of cycles: durRTrans1 + durRTrans2 * (number of instructions in the reference bot's bank $src, or 0 if there is no reference bot)
Failures: IS If the bot does not have the advanced instruction set.
IB If $src is smaller than 1 or greater than MaxBanks.
IB If $dest is smaller than 1 or greater than the bot's number of banks.
Execution: Transfers the $src'th bank of the bot on the reference field to the $dest'th bank of this bot, overwriting all contents of that bank. If there is no bot on the reference field or the reference bot does not have a $src'th bank, simply does nothing. (Note: Even negative values of $src do not cause the bot's destruction.)
Failures: IB If $src is smaller than 1 or greater than MaxBanks.
IB If $dest is smaller than 1 or greater than the bot's number of banks.

 

SCAN #dest
Requirements: Basic
Number of cycles: durScan
Failures: IS If the bot does not have the advanced instruction set.
Execution: Scans the executing task's reference field and sets #dest to the type of bot which is found there:
#dest becomes 0 if the reference field is empty, 1 if the bot on the reference field belongs to a different player than this bot, and 2 if it belongs to the same player.
Failures: (none)

 

SEIZE
Requirements: Multitasking
Number of cycles: durSeize
Failures: (none)
Execution: Pauses all tasks, except the executing task. (In other words: temporarily returns to single-tasking mode.)
If there are no tasks except this one, or this task is already seized, does nothing.
Failures: (none)
Remarks: See also RESUME.

 

SET #dest, $src
Requirements: Basic
Number of cycles: durSet
Failures: (none)
Execution: Sets #dest to the value of $src.
Failures: (none)

 

SLEEP $cycles
Requirements: Extended
Number of cycles: min($cycles, MaxSleepDur) (but at least 1 if $cycles is a local, and durRemoteAcc if $cycles is a remote variable)
Failures: (none)
Execution: This instruction does nothing at all. However, while a task sleeps, it does not use up any cycles, i.e. they are given to the other tasks.
Failures: (none)
Remarks: Unlike other instructions, which are executed after they have used up their number of cycles, when a task sleeps, it proceeds with the next instruction after the SLEEP the first time when the sleeping task is called again after the its number of cycles have passed in absolute game time.

 

SUB #val1, $val2
Requirements: Basic
Number of cycles: durSub
Failures: (none)
Execution: Subtracts $val2 from $val1 and sets #val1 to the result.
Failures: ET If EnableElim is enabled and abs($val1) is, after the subtraction, in a different one of the ranges [0, ElimTrigger] and [ElimTrigger + 1, 32768] than it was before.

 

TRANS $src, $dest
Requirements: Basic
Number of cycles: durTrans1 + durTrans2 * (number of instructions in bank $src)
Failures: IS If the bot does not have the advanced instruction set.
IB If $src is smaller than 1 or greater than the bot's number of banks.
Execution: Transfers the $src'th bank of this bot to the $dest'th bank of bot on the reference field, overwriting all contents of that bank. If there is no bot on the reference field or the reference bot does not have a $dest'th bank, simply does nothing. (Note: Even negative values of $dest do not cause the bot's destruction.)
Failures: IB If $src is smaller than 1 or greater than the bot's number of banks.

 

TURN $dir
Requirements: Basic
Number of cycles: durTurn
Failures: (none)
Execution: Turns the bot left (if $dir is 0) or right (otherwise) by 90 degrees.
Failures: (none)