Events

World event types. More...

Data Structures
struct	b2SensorBeginTouchEvent
	A begin touch event is generated when a shape starts to overlap a sensor shape. More...
struct	b2SensorEndTouchEvent
	An end touch event is generated when a shape stops overlapping a sensor shape. More...
struct	b2SensorEvents
	Sensor events are buffered in the world and are available as begin/end overlap event arrays after the time step is complete. More...
struct	b2ContactBeginTouchEvent
	A begin touch event is generated when two shapes begin touching. More...
struct	b2ContactEndTouchEvent
	An end touch event is generated when two shapes stop touching. More...
struct	b2ContactHitEvent
	A hit event is generated when two shapes collide with a speed faster than the hit event threshold. More...
struct	b2ContactEvents
	Contact events are buffered in the Box2D world and are available as event arrays after the time step is complete. More...
struct	b2BodyMoveEvent
	Body move events triggered when a body moves. More...
struct	b2BodyEvents
	Body events are buffered in the Box2D world and are available as event arrays after the time step is complete. More...
struct	b2JointEvent
	Joint events report joints that are awake and have a force and/or torque exceeding the threshold. More...
struct	b2JointEvents
	Joint events are buffered in the world and are available as event arrays after the time step is complete. More...

Detailed Description

World event types.

Events are used to collect events that occur during the world time step. These events are then available to query after the time step is complete. This is preferable to callbacks because Box2D uses multithreaded simulation.

Also when events occur in the simulation step it may be problematic to modify the world, which is often what applications want to do when events occur.

With event arrays, you can scan the events in a loop and modify the world. However, you need to be careful that some event data may become invalid. There are several samples that show how to do this safely.

---

Data Structure Documentation

b2SensorBeginTouchEvent

struct b2SensorBeginTouchEvent

A begin touch event is generated when a shape starts to overlap a sensor shape.

Data Fields
b2ShapeId	sensorShapeId	The id of the sensor shape.
b2ShapeId	visitorShapeId	The id of the shape that began touching the sensor shape.

b2SensorEndTouchEvent

struct b2SensorEndTouchEvent

An end touch event is generated when a shape stops overlapping a sensor shape.

Normally this event is generated from simulation movement. However, this event can also be generated from API interactions: setting the body transform, destroying a body or shape, or changing a filter. You will also get an end event if the sensor is destroyed. Therefore you should always confirm the shape id is valid using b2Shape_IsValid.

Data Fields
b2ShapeId	sensorShapeId	The id of the sensor shape. Warning this shape may have been destroyed See also b2Shape_IsValid
b2ShapeId	visitorShapeId	The id of the shape that stopped touching the sensor shape. Warning this shape may have been destroyed See also b2Shape_IsValid

b2SensorEvents

struct b2SensorEvents

Sensor events are buffered in the world and are available as begin/end overlap event arrays after the time step is complete.

Note: these may become invalid if bodies and/or shapes are destroyed

Data Fields
int	beginCount	The number of begin touch events.
b2SensorBeginTouchEvent *	beginEvents	Array of sensor begin touch events.
int	endCount	The number of end touch events.
b2SensorEndTouchEvent *	endEvents	Array of sensor end touch events.

b2ContactBeginTouchEvent

struct b2ContactBeginTouchEvent

A begin touch event is generated when two shapes begin touching.

Data Fields
b2ContactId	contactId	The transient contact id. This contact may be destroyed automatically when the world is modified or simulated. Use b2Contact_IsValid before using this id.
b2ShapeId	shapeIdA	Id of the first shape.
b2ShapeId	shapeIdB	Id of the second shape.

b2ContactEndTouchEvent

struct b2ContactEndTouchEvent

An end touch event is generated when two shapes stop touching.

You will get an end event if you do anything that destroys contacts previous to the last world step. These include things like setting the transform, destroying a body or shape, or changing a filter or body type.

Data Fields
b2ContactId	contactId	Id of the contact. Warning this contact may have been destroyed See also b2Contact_IsValid
b2ShapeId	shapeIdA	Id of the first shape. Warning this shape may have been destroyed See also b2Shape_IsValid
b2ShapeId	shapeIdB	Id of the second shape. Warning this shape may have been destroyed See also b2Shape_IsValid

b2ContactHitEvent

struct b2ContactHitEvent

A hit event is generated when two shapes collide with a speed faster than the hit event threshold.

This may be reported for speculative contacts that have a confirmed impulse.

Data Fields
float	approachSpeed	The speed the shapes are approaching. Always positive. Typically in meters per second.
b2ContactId	contactId	Id of the contact. Warning this contact may have been destroyed See also b2Contact_IsValid
b2Vec2	normal	Normal vector pointing from shape A to shape B.
b2Pos	point	Point where the shapes hit. This is a mid-point between the two surfaces. It could be a speculative point where the shapes were not touching at the beginning of the time step. The point is reconstructed after the step, so when both bodies are moving it may trail the impact by up to one step of motion.
b2ShapeId	shapeIdA	Id of the first shape.
b2ShapeId	shapeIdB	Id of the second shape.

b2ContactEvents

struct b2ContactEvents

Contact events are buffered in the Box2D world and are available as event arrays after the time step is complete.

Note: these may become invalid if bodies and/or shapes are destroyed

Data Fields
int	beginCount	Number of begin touch events.
b2ContactBeginTouchEvent *	beginEvents	Array of begin touch events.
int	endCount	Number of end touch events.
b2ContactEndTouchEvent *	endEvents	Array of end touch events.
int	hitCount	Number of hit events.
b2ContactHitEvent *	hitEvents	Array of hit events.

b2BodyMoveEvent

struct b2BodyMoveEvent

Body move events triggered when a body moves.

Triggered when a body moves due to simulation. Not reported for bodies moved by the user. This also has a flag to indicate that the body went to sleep so the application can also sleep that actor/entity/object associated with the body. On the other hand if the flag does not indicate the body went to sleep then the application can treat the actor/entity/object associated with the body as awake. This is an efficient way for an application to update game object transforms rather than calling functions such as b2Body_GetTransform() because this data is delivered as a contiguous array and it is only populated with bodies that have moved.

Note

If sleeping is disabled all dynamic and kinematic bodies will trigger move events.

Data Fields
b2BodyId	bodyId	The id of the body that moved.
bool	fellAsleep	Did the body fall asleep this time step?
b2WorldTransform	transform	The world transform of the body.
void *	userData	The body user data.

b2BodyEvents

struct b2BodyEvents

Body events are buffered in the Box2D world and are available as event arrays after the time step is complete.

Note: this data becomes invalid if bodies are destroyed

Data Fields
int	moveCount	Number of move events.
b2BodyMoveEvent *	moveEvents	Array of move events.

b2JointEvent

struct b2JointEvent

Joint events report joints that are awake and have a force and/or torque exceeding the threshold.

The observed forces and torques are not returned for efficiency reasons.

Data Fields
b2JointId	jointId	The joint id.
void *	userData	The user data from the joint for convenience.

b2JointEvents

struct b2JointEvents

Joint events are buffered in the world and are available as event arrays after the time step is complete.

Note: this data becomes invalid if joints are destroyed

Data Fields
int	count	Number of events.
b2JointEvent *	jointEvents	Array of events.