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.
| Syntax: | mine() | |
| Return value: | int | The amount of ore mined. |
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.
ore()
Retrieve the amount of ore stored in the robot ore container.
| Syntax: | ore(<value>) | |
| Parameter: | int | The ore type to retrieve the amount for. |
| Return value: | int | The amount of the specified type of ore stored inside the robot ore container. |
The ore type can be one of the following values:
- 0 for the total amount of ore.
- 1 for the high quality ore.
- 2 for the medium quality ore. Will always return 0 when only 1 type of ore is available in the mining area.
- 3 for the low quality ore. Will always return 0 when only 1 or 2 types of ore are available in the mining area.
dump()
Dumps the specified type of ore from the robot ore container.
| Syntax: | dump(<value>) | |
| Parameter: | int | The ore type to dump. |
| Return value: | int | The actual amount of ore dumped. |
The ore type can be one of the following values:
- 0 for all the types of ore.
- 1 for the high quality ore.
- 2 for the medium quality ore. Will never dump anything when only 1 type of ore is available in the mining area.
- 3 for the low quality ore. Will never dump anything when only 1 or 2 types of ore are available in the mining area.
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. |
scan()
Scans for ore in a direction relative to the robot using the installed ore scanner. This is a CPU action; the number of CPU instructions consumed depends on the scan speed of the ore scanner.
| 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 | 0 when no ore is detected within scan distance. Otherwise returns the ore quality index used by ore() and dump(): 1 for the highest quality ore type, 2 for the next quality, and so on. 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. |
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. |
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.