A Definitive RoboCom Reference by Florian Fischer
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.
To make reading this document easier, I have tried to keep to the following typesetting conventions:
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 |
---|---|
ET | Elimination Trigger released |
DH | Data Hunger (Bank 1 empty) |
DZ | Division by zero |
IB | Invalid bank number (e.g. in TRANS or BJUMP) |
IS | Higher Instruction Set required |
MO | Mobility required |
DI | DIE executed |
IP | Invalid parameter (e.g. CREATE x,-1,x) |
UE | No more tasks left in a robot (Unemployment) |
ID | Instruction duration too high (i.e. > MaxInstrDur) |
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.
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).
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. |
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) |