Contact callbacks

Contact callbacks are useful to retrieve more detailed data from entity body contacts that happen in the Box2D simulator. This kind of entity callback is very similar to standard entity callback functions, they must be void, and include the prefix ETH<contact-event>Callback_ followed by the entity name. There are three kinds of contact callback, each one can be used to gather data from a specific contact event:

Begin Contact event

This is called every time another simulated entity-body begins to overlap the entity to which the callback function is assigned. This is called for sensors and non-sensors. Example:

void ETHBeginContactCallback_tnt_barrel(
	ETHEntity@ thisEntity,
	ETHEntity@ other,
	vector2 contactPointA,
	vector2 contactPointB,
	vector2 contactNormal)
{
	if (other.GetEntityName() == "bullet.ent")
	{
		// a 'bullet.ent' hit the TNT barrel, that must result in an explosion
		explodeMyBarrel(thisEntity);
	}
}

Pre Solve Contact event

This is called after collision detection, but before collision resolution. This gives you a chance to disable the contact based on the current configuration. For example, you can implement a one-sided platform using this callback and calling DisableContact. The contact will be re-enabled each time through collision processing, so you will need to disable the contact every time-step. The pre-solve event may be fired multiple times per time step per contact due to continuous collision detection. Example:

void ETHPreSolveContactCallback_one_sided_platform(
	ETHEntity@ thisEntity,
	ETHEntity@ other,
	vector2 contactPointA,
	vector2 contactPointB,
	vector2 contactNormal)
{
	ETHPhysicsController@ controller = other.GetPhysicsController();
	if (controller.GetLinearVelocity().y < -0.5f)
		DisableContact();
}

The example above enables single-sided collision for every entity named one_sided_platform or one_sided_platform.ent.

End Contact event

This is called every time another entity-body ceases to overlap the entity to which this callback function is assigned to. This is called for sensors and non-sensors.

void ETHEndContactCallback_platform(
	ETHEntity@ thisEntity,
	ETHEntity@ other,
	vector2 contactPointA,
	vector2 contactPointB,
	vector2 contactNormal)
{
	if (other.GetEntityName() == "character.ent")
		print("Our character is no longer stepping on this platform!");
}

Important remarks

• Do not delete entities from inside contact callback functions. If you need to remove an entity  after a contact event, use custom data to flag the entity and destroy it from its regular entity callback function.
• Contact callback functions may return up to two intersection points, in world space, and a normalized vector that describes the surface normal for the contact.
• The entity reference other will always point to the other entity object that triggered the contact event.
• Both thisEntity and other must have their physics simulation properties enabled in the Entity Editor in order to enable contact callback events. More about that.