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 Box2D 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 touch event is generated when two shapes collide with a speed faster than the hit speed 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	b2ContactData
	The contact data for two shapes. 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.

Collaboration diagram for b2SensorBeginTouchEvent:

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

b2SensorEndTouchEvent

struct b2SensorEndTouchEvent

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

Collaboration diagram for b2SensorEndTouchEvent:

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

b2SensorEvents

struct b2SensorEvents

Sensor events are buffered in the Box2D 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

Collaboration diagram for b2SensorEvents:

Data Fields
int32_t	beginCount	The number of begin touch events.
b2SensorBeginTouchEvent *	beginEvents	Array of sensor begin touch events.
int32_t	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.

Collaboration diagram for b2ContactBeginTouchEvent:

Data Fields
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.

Collaboration diagram for b2ContactEndTouchEvent:

Data Fields
b2ShapeId	shapeIdA	Id of the first shape.
b2ShapeId	shapeIdB	Id of the second shape.

b2ContactHitEvent

struct b2ContactHitEvent

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

Collaboration diagram for b2ContactHitEvent:

Data Fields
float	approachSpeed	The speed the shapes are approaching. Always positive. Typically in meters per second.
b2Vec2	normal	Normal vector pointing from shape A to shape B.
b2Vec2	point	Point where the shapes hit.
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

Collaboration diagram for b2ContactEvents:

Data Fields
int32_t	beginCount	Number of begin touch events.
b2ContactBeginTouchEvent *	beginEvents	Array of begin touch events.
int32_t	endCount	Number of end touch events.
b2ContactEndTouchEvent *	endEvents	Array of end touch events.
int32_t	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.

Collaboration diagram for b2BodyMoveEvent:

Data Fields
b2BodyId	bodyId
bool	fellAsleep
b2Transform	transform
void *	userData

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

Collaboration diagram for b2BodyEvents:

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

b2ContactData

struct b2ContactData

The contact data for two shapes.

By convention the manifold normal points from shape A to shape B.

See also

b2Shape_GetContactData() and b2Body_GetContactData()

Collaboration diagram for b2ContactData:

Data Fields
b2Manifold	manifold
b2ShapeId	shapeIdA
b2ShapeId	shapeIdB