CBOT Language

The CBOT language is very close in structure and syntax to C++ and Java. It has been adapted for the specific

The CoLoBoT code editor window.

purposes of Colobot, and for an efficient pedagogical approach.

This language is made up of instructions (see below), blocks, functions, classes, variables, arrays, expressions and conditions.

Instructions

In the legacy versions of the program editor, an instruction in the CBOT language is always displayed on an orange background. If an instruction doesn't have an orange background, this means that it has been misspelled. Instruction names are always written in lower case.

In Gold Edition the program editor changes the text color of a syntax, whereas before the syntax would be highlighted with a color representative of the type.

Types in the CBOT language

The type of a variable appears with a green background or highlight.

int

float

bool

string

point

object

void

Constants

Constants, like categories, are displayed with a red background or highlight.

Instructions in the CBOT language

Instructions will be displayed with a blue background or highlight.

extern	Indicate the main function
if	Choice structure
else if	Consequence of if and else syntax, alternative if
else	Alternative choice structure
for	Loop structure
while	Control structure
do	Control structure
break	Exit from a loop
continue	Continues the loop
return	Exit from a function
sizeof	Size of an array

do ... while

You can have do ... while loops.

   do {
       // things
   } while (stuff());

Operators in the CBOT language

Operators, like instructions, will be displayed with a blue background or highlight.

+	addition
-	subtraction
*	multiplication
/	division
%	modulus (only for int type)
or	Boolean or with short-circuiting
and	Boolean and with short-circuiting
not	Boolean not
==	Equal
!=	Not equal
>	Greater than
<	Less than
>=	Greater than or equal to
<=	Less than or equal to
? :	The ternary operator .

Specific instructions for bots

These instructions will appear with an amber background or highlight.

radar	Object detection
search	Object detection
direction	Calculates a rotation angle
distance	Calculates a distance
distance2d	Calculates a distance
wait	Waits
move	Moves forward or backward
turn	Turns
goto	Goes to a given position
motor	Direct motor control
jet	Direct jet engine control
message	Displays a message
retobject	Returns an object from array
errmode	Error treatment control
abstime	Returns the absolute time
ipf	Sets execution speed
pendown	Begin leaving a trail behind the bot
penup	Stop leaving a trail behind the bot
penwidth	Change the trail's width
pencolor	Change the trail's height

Instructions about topology

space	Calculates a free space
topo	Returns the altitude of a point
flatground	Returns radius of a flat area

Instructions specific to some bots

grab	Picks up an object
drop	Puts down an object
sniff	Sounds the subsoil
thump	Overturns alien insects
recycle	Recycles a derelict object
shield	Extends or withdraws the shield
fire	Fires the cannon
aim	Vertical angle of the cannon
build	Constructs a building

Specific instructions for exchange posts

receive	Receives information
send	Sends new information
testinfo	Tests if information exists
deleteinfo	Deletes existing information

Specific instructions for classes

class	Class declararion
public	Declares a public function
private	Declares a private class member
static	Declares a static class member
synchronized	Prevents simultaneous execution
new	Creates a new instance
this	Reference to the current instance
extends	Extends a class
super	Grants access to the parent class

Specific instructions for strings

strlen	Gets string length
strleft	Extracts left part
strright	Extracts right part
strmid	Extracts center part
strfind	Finds a substring
strval	Converts string to number
strupper	Converts to upper case
strlower	Converts to lower case

Mathematical Functions

Like instructions, the mathematical functions will be shown with an amber background or highlight.

abs(value)	absolute value of an argument
sin(angle)	sine
cos(angle)	cosine
tan(angle)	tangent
asin(value)	arcsine
acos(value)	arccosine
atan(value)	arctangent
sqrt(value)	square root
pow(x, y)	x to the power y ($x^{y}$)
rand()	random number in range between 0 and 1

Specific instructions for files

Like instructions for bots, file instructions will appear with an amber background or highlight.

open	Opens a file
close	Closes a file
writeln	Writes line to a file
readln	Reads line from a file
eof	Tests if end of file
deletefile	Deletes a file

Tricks and notes

See what happens when you try these.

Some functions to mess around with and see what they do (if they even work):

   produce - Create a bot, building, or object.
   cmdline - Seems similar to Python's sys.argv. Used by aliens, but probably useless for player-made robots. Called with a single int. See colobot/data/ai/lady01.txt for an example.
   ismovie - Detects if a cutscene is playing.
   repeat - Repeats code, does not currently work.
   drive - (?)

Object Properties

All objects have at least some of the following properties:

• object.category - this is probably so you can do stuff like target.category == AlienAnt
• object.position - position in x/y of the object
• object.orientation - presumably yaw, all angles are in degrees.
• object.pitch
• object.roll
• object.energyLevel - the amount of energy left in the battery, from 1 to 0. Float. May work only on batteries. For robots try robot.energyCell.energyLevel
• object.shieldLevel
• object.temperature - temperature of the jet engine. 0 is cool, 1 is overheated.
• object.altitude - height above the ground. Same as (object.position.z - topo(object.position)) .

• object.lifeTime - time since creation of the object. Float. In seconds.
• object.energyCell - the object in a robot's battery holder, or none if there's nothing there.
• object.load - the entity that the object is carrying, if it's a grabber or wasp.
• object.dead - whether the object is dead/dying or not (bool).
• object.busy - test if an object is busy.
• object.factory - instruct a bot factory to create a new bot
• object.research - Instructs a research center to perform a research program.
• object.takeoff - Instructs the spaceship to take off.

Robot Attributes

• You can get the thing a grabber is holding with this.load. It'll probably be null if there's nothing being held.
• You can get the entity in the battery slot with this.energyCell.

Context Assignment

It's possible to have a variable assignment inside of another context, like in C. For example:

   extern void object::Main() {
       object target;
       
       while ((target = radar()) != null) {
           // do things
       }
   }

Note the second parentheses. This example is the equivalent of running:

   extern void object::Main() {
       object target = radar();
       
       while (target != null) {
           // do things
           target = radar();
       }
   }

Limitations

You can't use array literals. This won't work:

object enemy = radar({AlienAnt, AlienSpider});

Instead, you need to do:

object[] enemyClasses = {AlienAnt, AlienSpider};
object enemy = radar(enemyClasses);

There's no polymorphism in CBOT, so functions need to be redefined for every type that you want to use them on. For example:

float addOne(float num) { return num + 1; }
float addOne(int   num) { return num + 1; }

Notes

• Attempting to cancel a build() function by stopping the program will cause the titanium cube to count as being used, but the physical item will still persist in the world, unable to be interacted with or destroyed in any way.
• Entering the produce(); instruction will never show a colored background in the legacy versions, and will not be represented with a colored font in Colobot: Gold Edition (as of 0.1.12-alpha).

See also

Types and categories.