Entity callbacks

onSceneCreated and onSceneUpdate (pre-loop and loop) functions are not the only sort of callback functions available. Every different entity may have its own callback functions. Entity callback functions are automatically assigned to entities whenever the engine finds a matching function globally declared in the game script, for example ETHCallback_entity_name and ETHConstructorCallback_entity_name.

Entity update callback

Update callback functions are automatically called by the engine for each matching entity at every game frame. ETHCallback_ must always be the prefix for this kind of callback.

The engine will search for a callback function for every entity which is either loaded from the scene file or dynamically added to scene (through script code).

Consider the following example:

void main()
{
	// loads raccoon_city.esc
	LoadScene("scenes/raccoon_city.esc");
}

// This function will be automatically assigned to and
// executed for all entities named 'zombie' or 'zombie.ent'
void ETHCallback_zombie(ETHEntity @thisZombie)
{
	if (searchForBrains(@thisZombie) == FRESH_BRAIN)
	{
		eatBrain(@thisZombie)
	}
}

Considering the example above, if the scene raccoon_city.esc contains 20 entities named zombie.ent, the function ETHCallback_zombie(ETHEntity@) will be called 20 times for each zombie in scene during each frame.

Update callback functions must have as parameter an ETHEntity@ object handle as shown above, that object handle will always point to the current entity. If this function is executed 20 times per frame (to process all the 20 zombies in it), every time this is called in a frame, thisZombie will refer to a different zombie. Remember that an object handle declaration is followed by the @ operator on AngelScript.

Entity exclusive callback functions are great if the game needs entity specific behavior. The ETHEntity object has several methods to control every important property of the entity (position, angle, animation and much more).

Entity constructor callback

Unlike update callbacks, constructor callback functions are executed only once by the engine, and just before the first update callback function gets called. Its prefix is ETHConstructorCallback_, its type must be void and its parameter must be an ETHEntity@ object reference as well:

// initializes each zombie with HP and LEVEL
void ETHConstructorCallback_zombie(ETHEntity@ thisZombie)
{
	thisZombie.SetInt("hp", 100);
	thisZombie.SetUInt("level", 5);
}

Entity constructors are great to initialize custom variables and other meta data related to entities. The frame-animation sample illustrates its usage.

Notice that constructor callback functions are not necessarily called right after the entity is added to scene, but right before its update callback function is going to be called by the engine.