Events

World event types. More...

Data Structures
struct	b3SensorBeginTouchEvent
	A begin-touch event is generated when a shape starts to overlap a sensor shape. More...
struct	b3SensorEndTouchEvent
	An end touch event is generated when a shape stops overlapping a sensor shape. More...
struct	b3SensorEvents
	Sensor events are buffered in the world and are available as begin/end overlap event arrays after the time step is complete. More...
struct	b3ContactBeginTouchEvent
	A begin-touch event is generated when two shapes begin touching. More...
struct	b3ContactEndTouchEvent
	An end touch event is generated when two shapes stop touching. More...
struct	b3ContactHitEvent
	A hit touch event is generated when two shapes collide with a speed faster than the hit speed threshold. More...
struct	b3ContactEvents
	Contact events are buffered in the world and are available as event arrays after the time step is complete. More...
struct	b3BodyMoveEvent
	Body move events triggered when a body moves. More...
struct	b3BodyEvents
	Body events are buffered in the world and are available as event arrays after the time step is complete. More...
struct	b3JointEvent
	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. More...
struct	b3JointEvents
	Joint events are buffered in the world and are available as event arrays after the time step is complete. More...
struct	b3ContactData
	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 Box3D 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

b3SensorBeginTouchEvent

struct b3SensorBeginTouchEvent

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

Collaboration diagram for b3SensorBeginTouchEvent:

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

b3SensorEndTouchEvent

struct b3SensorEndTouchEvent

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

These include things like setting the transform, destroying a body or shape, or changing a filter. You will also get an end event if the sensor or visitor are destroyed. Therefore you should always confirm the shape id is valid using b3Shape_IsValid.

Collaboration diagram for b3SensorEndTouchEvent:

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

b3SensorEvents

struct b3SensorEvents

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

Collaboration diagram for b3SensorEvents:

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

b3ContactBeginTouchEvent

struct b3ContactBeginTouchEvent

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

Collaboration diagram for b3ContactBeginTouchEvent:

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

b3ContactEndTouchEvent

struct b3ContactEndTouchEvent

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.

Collaboration diagram for b3ContactEndTouchEvent:

Data Fields
b3ContactId	contactId	Id of the contact. Warning this contact may have been destroyed See also b3Contact_IsValid
b3ShapeId	shapeIdA	Id of the first shape. Warning this shape may have been destroyed See also b3Shape_IsValid
b3ShapeId	shapeIdB	Id of the first shape. Warning this shape may have been destroyed See also b3Shape_IsValid

b3ContactHitEvent

struct b3ContactHitEvent

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

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

Collaboration diagram for b3ContactHitEvent:

Data Fields
float	approachSpeed	The speed the shapes are approaching. Always positive. Typically in meters per second.
b3ContactId	contactId	Id of the contact. Warning this contact may have been destroyed See also b3Contact_IsValid
b3Vec3	normal	Normal vector pointing from shape A to shape B.
b3Pos	point	Point where the shapes hit at the beginning of the time step. This is a mid-point between the two surfaces. It could be at speculative point where the two shapes were not touching at the beginning of the time step.
b3ShapeId	shapeIdA	Id of the first shape.
b3ShapeId	shapeIdB	Id of the second shape.
uint64_t	userMaterialIdA	User material on shape A.
uint64_t	userMaterialIdB	User material on shape B.

b3ContactEvents

struct b3ContactEvents

Contact events are buffered in the 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 b3ContactEvents:

Data Fields
int	beginCount	Number of begin touch events.
b3ContactBeginTouchEvent *	beginEvents	Array of begin touch events.
int	endCount	Number of end touch events.
b3ContactEndTouchEvent *	endEvents	Array of end touch events.
int	hitCount	Number of hit events.
b3ContactHitEvent *	hitEvents	Array of hit events.

b3BodyMoveEvent

struct b3BodyMoveEvent

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 b3Body_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 b3BodyMoveEvent:

Data Fields
b3BodyId	bodyId	The body id.
bool	fellAsleep	Did the body fall asleep this time step?
b3WorldTransform	transform	The body transform.
void *	userData	The body user data.

b3BodyEvents

struct b3BodyEvents

Body events are buffered in the 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 b3BodyEvents:

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

b3JointEvent

struct b3JointEvent

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.

Collaboration diagram for b3JointEvent:

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

b3JointEvents

struct b3JointEvents

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

Collaboration diagram for b3JointEvents:

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

b3ContactData

struct b3ContactData

The contact data for two shapes.

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

See also

b3Shape_GetContactData() and b3Body_GetContactData()

Collaboration diagram for b3ContactData:

Data Fields
b3ContactId	contactId	The contact id. You may hold onto this to track a contact across time steps. This id may become orphaned. Use b3Contact_IsValid before using it for other functions.
int	manifoldCount	The number of contact manifolds. For mesh and height-field collision there can be multiple manifolds.
const struct b3Manifold *	manifolds	The contact manifold. This points to internal data and may become invalid. Do not store this pointer.
b3ShapeId	shapeIdA	The first shape id.
b3ShapeId	shapeIdB	The second shape id.