Script: Callbacks and Timers
This page assumes that you know the basics about scripting.
You probably reached a stage where you asked yourself "okay, I know how things work in theory - but how do I actually bring them alive?". You might want your object to interact with others or to do certain things on certain events.
Callbacks
Callbacks are functions in your scripts that are called automatically when something special happens and which you can use to react to certain events. A common example is an object that explodes when it collides with the landscape, you would use the callback func Hit(int x_velocity, int y_velocity) for that. That function is called whenever your object hits the landscape (but not other objects!). To use a callback, you can simply write a function with the name of the callback into your script like that:
func Hit(int x, int y)
{
Explode(100);
return;
}
Note that some callbacks also expect return values that define the reaction of your object. Take func RejectEntrance(object into_object) that you can use to prevent your object from being picked up, for example you might want your object to be non-collectable when it is on fire:
func RejectCollect()
{
if (OnFire()) return true;
else return false;
}
Note that I omitted the parameter object into_object. The callback is still called. If you don't need certain parameters, you can leave them out.
If you want a callback that is called repeatedly every few frames, you can use the AddTimer(string name, int interval) function to add a custom callback:
/* script of a mine */
// called on object creation
func Initialize()
{
AddTimer("Check", 30);
}
// our custom callback
func Check()
{
// explode when a moving object is near
if (ObjectCount(Find_Distance(20), Find_OCF(OCF_HitSpeed1)) > 0)
Explode(30);
}
inheritance and _inherited()
When you read through some of the original scripts, you will find something weird like return _inherited(...) at the end of some callbacks. The function _inherited() is used to call the same function of the parent object when your object #includes another one. So for example when you write an extension to the Clonk, you might want that the original Clonk-script still receives the function call:
// CatchBlow is called when an object takes a hit
func CatchBlow(int level)
{
if (level > 10) Sound("Hurt*");
return _inherited(level, ...);
}
The three dots ... stand for all the other parameters that you did not assign a name. So if you have a named parameter you still have to write it manually into the _inherited-call. In the above example I omitted the object by parameter of CatchBlow.
List of Callbacks
You can find a list of some of the callbacks here: C4Script Reference
Due to historic reasons there are (currently) not all existing callbacks listed. If you are looking for a certain callback that you are sure to exist, you can go into our IRC channel and ask ;)