Colobot Wiki
Advertisement

A function, simply put, is an instruction created by you.

Main function[]

You probably already know how to create a function. Every program in CBOT must have a main function, which looks like this:

extern void object::ProgramName()
{


	// instructions


}

Nothing but a name can be changed in the main function. The keyword extern distinguishes the main function from others.

Basic use[]

With functions you can divide your program into several parts. Each of them will execute a specific task. For example, see the following program:

extern void object::Remote()
{
	send("order", 1, 100);
	wait(5);
	send("order", 3, 100);
	wait(5);
	send("order", 2, 100);
	wait(5);
	send("order", 4, 100);
	wait(5);
}

Send and wait are repeated several times. So it would be a good thing if we created a function that executes these two instructions:

void SendToPost(float op)
{
	send("order", op, 100);
	wait(5);
}


extern void object::Remote()
{
	SendToPost(1);
	SendToPost(3);
	SendToPost(2);
	SendToPost(4);
}

Now the program is much easier to read. It is a good practice to split the program into several functions with self-describing names.

Syntax[]

result_type FunctionName(optional_parameters)
{
	body
}

Result type should be void if the function does not give any. Body is just a set of instructions. Function name must be created with the exact same rules applied to variables.

Parameters[]

A function can have parameters:

void Example(int a, float x, string s)
{
	message(a);
	message(x);
	message(s);
}

The Example function will receive an integer a, a floating point number x and a string s. Parameters are "passed by value", that is the values of parameter variables in a function are copies of the values the caller specified as variables. If you pass an int to a function, its parameter is a copy of whatever value was being passed as the argument, and the function can change its parameter value without affecting values in the code that invoked the function.

If you pass a class instance or an array as parameter to a function, the function only receives a reference to the instance or the array. That means if you modify the instance or the array in the function, the instance or the array that has been specified by the caller will be actually modified.

Result[]

A function can also return a result with the return instruction. Therefore the function must be declared no longer as void but as an other type:

float Average(float a, float b)
{
	return (a+b)/2;
}


extern void object::Test( )
{
	float value;
	value = Average(2, 6);
	message(value);  // will display 4
}

Some other examples:

float Pi()
{
	return 3.1415;
}

string Sign(float a)
{
	if (a > 0)  return "positive";
	if (a < 0)  return "negative";
	return "null";
}

Overloading[]

You can declare several functions with the same name but different parameters:

float Pythagoras(float a, float b)
{
	return sqrt((a*a)+(b*b));
}
float Pythagoras(float a, float b, float c)
{
	return sqrt((a*a)+(b*b)+(c*c));
}

CBOT will call either the one or the other function depending on the parameters passed. They must be distinguishable, i.e. you can't declare two functions with the same name and parameter types in the exact same order, e.g. declaring int Pythagoras(float b, float a) will result in error. Note that result type does not matter.

Public Functions[]

You can also declare a function public so it can be used by other bots.

object::[]

Declaring a function as a part of the object namespace gives it access to this pointer, in other words, to all available properties of the robot which the program is run on.

void object::Example()
{
	message(this.category);
}

Default Parameters[]

Last function parameters can have default values that can be omitted when calling.

float Add(float a = 0.0, float b = 0.0)
{
	return a + b;
}

// Somewhere in the main program...
Add(); // Will return 0.0
Add(2.0); // Will return 2.0
Add(2.0, 3.0); // Will return 5.0
// ...

Default Parameters and Overloading[]

Functions with default parameters still can be overloaded, one must only ensure that function calls are not ambiguous. For example, consider the following code:

float Add(float a = 0.0, float b = 0.0)
{
	return a + b;
}


string Add(string a = "", string b = "")
{
	return a + b;
}

// Somewhere in the main program...
Add(); // Compilation error: ambiguous call
Add(""); // Ok
Add(0.0); // Ok
// ...

Note that in the above example overloading causes the first default parameter to be useless as caller needs to pass it anyway in order to distinguish the two functions.

Notes[]

  • For a public function to be able to be called the bot containing the function must be present (not destroyed).
Advertisement