Snapshot

Save and restore the full simulation state of a world as a byte image. More...

Functions
int	b2World_GetSnapshot (b2WorldId worldId, uint8_t *image, int capacity)
	Write a snapshot of the world's simulation state into a caller-owned buffer.
bool	b2World_RestoreFromSnapshot (b2WorldId worldId, const uint8_t *image, int size)
	Restore a world's simulation state from a snapshot image.
b2WorldId	b2CreateWorldFromSnapshot (const uint8_t *image, int size, int workerCount)
	Create a new world from a snapshot image.

Detailed Description

Save and restore the full simulation state of a world as a byte image.

Unlike a recording, which is a stream of API events, a snapshot is a single instant. Useful for rollback, undo, and deterministic save games. Call between world steps.

A snapshot carries only simulation state. Application hooks are not included. So callbacks and user data are not preserved. However, if you apply a snapshot to an existing world then the callbacks stay.

All the ids remain valid when a world is restored in place: b2BodyId, b2ShapeId, b2JointId, b2ChainId, and b2ContactId.

Function Documentation

b2CreateWorldFromSnapshot()

b2WorldId b2CreateWorldFromSnapshot	(	const uint8_t *	image,
		int	size,
		int	workerCount )

Create a new world from a snapshot image.

This is mainly useful for replay. Callbacks are reset to default.

Parameters

image	A snapshot image produced by b2World_GetSnapshot
size	Size of image in bytes
workerCount	Worker count for the new world. 0 uses the serial single-worker fallback.

Returns

The new world id, or b2_nullWorldId on failure.

b2World_GetSnapshot()

int b2World_GetSnapshot	(	b2WorldId	worldId,
		uint8_t *	image,
		int	capacity )

Write a snapshot of the world's simulation state into a caller-owned buffer.

Call once with image == NULL to get the required size, then again with a buffer of at least that size. Must be called at a step boundary.

Parameters

worldId	The world to snapshot
image	Destination buffer, or NULL to query the size
capacity	Size of image in bytes, ignored when querying

Returns

The number of bytes the snapshot needs. If it exceeds capacity nothing is written. Returns 0 if the world is mid-step.

b2World_RestoreFromSnapshot()

bool b2World_RestoreFromSnapshot	(	b2WorldId	worldId,
		const uint8_t *	image,
		int	size )

Restore a world's simulation state from a snapshot image.

The b2WorldId and ids held from this same world stay valid for objects that existed at the snapshot instant. Callbacks and threading configuration are preserved. User data on shapes, bodies, and joints is nulled.

Parameters

worldId	The world to restore into
image	A snapshot image produced by b2World_GetSnapshot
size	Size of image in bytes

Returns

true on success. On a rejected image (bad magic, version, or layout) the world is left unchanged. A corrupt payload detected after the rebuild begins returns false and leaves the world unusable, so the caller must destroy it.