Robot programming help
A robot program tells a robot what to do when mining. The program starts at the first line. If the program ends before the mining session is finished or the battery is depleted, the program is restarted. This process repeats until the end of the mining session.
A robot program can be changed at any time. However, the changes made will only be activated for a robot when the program is applied to that robot. That version of the program will then be active for the robot until a new version is applied to it.
In other words: After changing a program, always go to the 'Robots' page, make sure the program is selected and click the apply button on the bottom.
Statements
A robot program is a list of statements. Statements are separated by semicolons. Multiple statements can be grouped into one large statement by adding '{' and '}' around them.
Example
move(2);
while (mine());
This program moves the robot forward two positions and then continues mining until there is nothing to mine at the current location. Since the program is started again when the program completes, these steps are repeated until the mining session is over.
Robot actions
move()
Moves the robot forward or backward at the maximum speed until either the desired distance is traveled or a collision occurs.
| Syntax: | move(<value>) | |
| Parameter: | double | The distance to travel, negative to travel backwards. |
| Return value: | double | The actual distance traveled, always positive or zero. |
rotate()
Rotates the robot at the maximum rotation speed until either the desired rotation is reached or a collision occurs.
| Syntax: | rotate(<value>) | |
| Parameter: | int | The size of the rotation, in degrees (360 being a full turn). Use a positive value to turn right, negative to turn left. |
| Return value: | int | The actual size of the rotation. |
mine()
Try to mine minerals from the current robot location. Mining always digs the ground cell under the robot center and collects every ore type present on that cell. There is no way to mine only type 1 with mine() itself — use dumpB() / dumpC() afterward if you need to discard lower-value ore.
| Syntax: | mine() | |
| Return value: | int | The amount of ore mined. Returns 0 when the cell is empty, the container is full, or nothing can be extracted this cycle. |
The amount of ore mined each turn is limited by two factors:
- The mining unit installed in the robot. The total amount of ore mined in one cycle can never exceed the mining speed of the mining unit.
- The ore amount available on the robot location. For each type of ore, the amount of ore mined in one cycle can never exceed half the amount of ore available, rounded up.
dump()
Dumps ore from the robot ore container. Away from your spawn corner, dumped ore is placed on the ground under the robot and can be mined again. At your spawn corner (where the rally started: robot.xPos and robot.yPos are both 0), ore fills your personal depot up to the unlocked capacity for that ore type; any overflow is placed on the ground as usual. Depot capacity starts at 0 and is raised by achievements. At the end of the rally, depot contents and remaining container ore are added together for your mining result.
| Syntax: | dump() | Dump every ore type in the container. |
| Syntax: | dumpA() | Dump high-quality ore (same slot as robot.oreStoredA). |
| Syntax: | dumpB() | Dump medium-quality ore (same slot as robot.oreStoredB). |
| Syntax: | dumpC() | Dump low-quality ore (same slot as robot.oreStoredC). |
| Return value: | int | The actual amount of ore removed from the container (depot plus ground). |
dumpB() and dumpC() never remove anything when the mining area only has higher ore qualities available.
time()
Retrieves the number of mining cycles left until either the battery is depleted or the mining event is over.
| Syntax: | time() | |
| Return value: | int | The number of cycles left. |
Robot properties
Read-only values that describe the robot this program is running on. Part stats reflect the installed hardware and cannot be changed in code. Position and orientation are rally-relative: at the start of every mining run, robot.xPos and robot.yPos are 0 and robot.orientation is 135, regardless of which corner the robot spawns in.
Orientation 0 points north (toward the west map edge). Angles increase clockwise, matching rotate(positive). robot.xPos is the signed east/west distance from your rally start position (positive = east). robot.yPos is the signed north/south distance from your rally start position (positive = north).
| robot.forwardSpeed | double | Forward movement speed. |
| robot.backwardSpeed | double | Backward movement speed. |
| robot.rotateSpeed | int | Rotation speed in degrees per mining cycle. |
| robot.scanTime | int | CPU cycles required for a scan to complete. |
| robot.scanDistance | int | Maximum scan range of the installed ore scanner. |
| robot.oreCap | int | Maximum ore the robot can carry. |
| robot.oreStored | int | Total ore currently stored in the container. |
| robot.oreStoredA | int | Highest-quality ore currently stored in the container. |
| robot.oreStoredB | int | Medium-quality ore currently stored in the container. Always 0 when the area has only one ore type. |
| robot.oreStoredC | int | Lowest-quality ore currently stored in the container. Always 0 when the area has fewer than three ore types. |
| robot.maxCycles | int | Maximum mining cycles available per rally. |
| robot.miningSpeed | int | Ore mined per mine action. |
| robot.cpuSpeed | int | CPU cycles available per mining cycle. |
| robot.orientation | int | Current orientation in degrees. Starts at 135; 0 is north (west map edge). |
| robot.xPos | double | Signed east/west distance from the rally start position (positive = east). |
| robot.yPos | double | Signed north/south distance from the rally start position (positive = north). |
scan()
Starts scanning for ore in a direction relative to the robot using the installed ore scanner. The scan runs in the background and completes after the scanner's scan time (in CPU cycles). The ray uses the robot's position and orientation at the moment scan() starts, even if the robot moves or rotates before the scan finishes. Use oreDistance() or oreType() to read the result once the scan has finished. The scanner reports the nearest ore of any type along the ray. Outer lower-value ore can hide a richer heap further away on the same line of sight.
| Syntax: | scan([value]) | |
| Parameter: | int | Optional scan direction in degrees relative to the robot. 0 is in front of the robot, 90 is to the right. Defaults to 0. |
| Return value: | int | The number of CPU cycles until the scan completes (the scanner's scan time). Costs 1 CPU cycle to initiate. |
oreDistance()
Returns the distance to the nearest ore detected by the most recent scan. If a scan is still in progress, the call waits until the scan countdown finishes (which may span multiple mining cycles). When the robot is already standing on ore, the distance is 0.
| Syntax: | oreDistance() | |
| Return value: | double | The shortest distance to ore within scan distance, or -1 when no ore is found or scan() was never called. |
oreType()
Returns the ore quality index from the most recent scan. If a scan is still in progress, the call waits until the scan countdown finishes (which may span multiple mining cycles).
| Syntax: | oreType() | |
| Return value: | int | The ore quality index: 1 for the highest quality A ore type, 2 for the medium quality B and 3 for the low quality C. Returns 0 when scan() was never called or no ore was found. When multiple ore types are visible at the same distance, the richer ore type is returned. |
Flow control
if - else
Executes a statement only when a condition is met.
| Syntax: | if (<condition>) {<statements>} [ else {<statements>} ] | |
| <condition>: | bool | When the condition is true, the first list of statements is executed. Otherwise, the list of statements from the else-part is executed. |
while
Repeats execution of a statement for as long as a condition is met.
| Syntax: | while (<condition>) {<statements>} | |
| <condition>: | bool | When the condition is met, the statements are executed and the condition is evaluated again. This process repeats until the condition is not met. |
It is possible to replace the statements list by a semicolon. In that case, only the expression itself is evaluated until it fails. This can be useful when the expression contains a robot action. Example: while (mine()); repeats mining until there is nothing to mine at the current location.
do - while
Repeats execution of a statement for as long as a condition is met.
| Syntax: | do {<statements>} while (<condition>) | |
| <condition>: | bool | After the statements are executed, the condition is evaluated. If the condition is met, the statements are executed again. This process repeats until the condition is not met. |
The difference with 'while' is that the statements are executed at least once.
Expressions
Numeric expressions
| Operator | Example | Description |
|---|---|---|
| + | <value_1> + <value_2> | Adds the two values. |
| - | <value_1> - <value_2> | Subtract value_2 from value_1. |
| * | <value_1> * <value_2> | Multiplies the two values. |
| / | <value_1> / <value_2> | Divides value_1 by value_2. |
| % | <value_1> % <value_2> | Calculates the remainder when dividing value_1 by value_2. |
Compare expressions
| Operator | Example | Description |
|---|---|---|
| > | value_1 > value_2 | The result is true if and only if value_1 is larger then value_2. |
| >= | value_1 >= value_2 | The result is true if and only if value_1 is larger then or equal to value_2. |
| < | value_1 < value_2 | The result is true if and only if value_1 is smaller then value_2. |
| <= | value_1 <= value_2 | The result is true if and only if value_1 is smaller then or equal to value_2. |
| == | value_1 == value_2 | The result is true if and only if value_1 is equal to value_2. |
| != | value_1 != value_2 | The result is true if and only if value_1 is not equal to value_2. |
Binary expressions
| Operator | Example | Description |
|---|---|---|
| && | value_1 && value_2 | The result is true if and only if both value_1 and value_2 are true. |
| || | value_1 || value_2 | The result is true if and only if value_1 and/or value_2 is true. |
| ! | !value | The result is true if and only if value is false. |
Pre/post increment/decrement
| Operator | Example | Description |
|---|---|---|
| ++<variable> | ++moves | The value of the variable is incremented by one and the result value of the expression is the final value of the variable. |
| <variable>++ | moves++ | The value of the variable is incremented by one. The result value of the expression is the value of the variable BEFORE the increment. |
| --<variable> | --moves | The value of the variable is decremented by one and the result value of the expression is the final value of the variable. |
| <variable>-- | moves-- | The value of the variable is decremented by one. The result value of the expression is the value of the variable BEFORE the decrement. |
| <variable> += value | direction += 30 | Adds value to the variable, equivalent to direction = direction + value. |
| <variable> -= value | direction -= 30 | Subtracts value from the variable, equivalent to direction = direction - value. |
Variables
Variables can be used to store values. Later on in the program, the value can be changed or used in an expression.
The first step in using a variable is to declare it. After that, its value can be changed and it can be used in expressions.
Variable declaration
| Syntax: | <type> <name> = <value> | |
| Type: | int, double or bool. | int is used to store whole numbers. double is used to store real values such as 3.14. bool has two possible values: true and false. |
| Name: | A self chosen name for the variable. | The name can contain any number of upper and lower case characters and numbers, but is not allowed to start with a number. Also, the name may not be the same as existing commands such as 'while' and 'move'. |
| Value: | A fixed value of the right type or an expression. | When the value is not of the same type as the variable, the value is converted. |
Example:
int miningAmount = mine();
Variable assignment
| Syntax: | <name> = <value> | |
| Name: | The name of an existing variable. | |
| Value: | A fixed value of the right type or an expression. | When the value is not of the same type as the variable, the value is converted. |
Example:
miningAmount = mine();
Variable usage
Variables can be used instead of fixed values in expressions.
Variable scope
The variable is available in the block in which it was declared and each sub-block.