Worlds and stepping

Create a world, configure integration, step, and serialize it. More...

Data Structures
struct	R2IntegrationParameters
	Plain configuration data; initialize defaults, edit, then apply. More...

Typedefs
typedef struct R2Bytes	R2Bytes
	Immutable owned byte buffer.
typedef struct R2World	R2World
	Sole owner of simulation state.
typedef struct R2IntegrationParameters	R2IntegrationParameters
	Plain configuration data; initialize defaults, edit, then apply.

Functions
struct R2IntegrationParameters	r2DefaultIntegrationParameters (void)
	Return native default integration parameters.
struct R2IntegrationParameters	r2IntegrationParameters (const struct R2World *world)
	Return a copy of all world integration settings.
R2Status	r2SetIntegrationParameters (struct R2World *world, const struct R2IntegrationParameters *data)
	Copies validated values; does not expose a writable alias to Rust memory.
size_t	r2ActiveRigidBodies (const struct R2World *world, struct R2RigidBodyHandle *buffer, size_t capacity)
	Copies the island manager's active body handles.
R2Real	r2TimeStep (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::dt.
R2Status	r2SetTimeStep (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::dt.
R2Real	r2MinCcdDt (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::minCcdDt.
R2Status	r2SetMinCcdDt (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::minCcdDt.
R2Real	r2LengthUnit (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::lengthUnit.
R2Status	r2SetLengthUnit (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::lengthUnit.
R2Real	r2WarmstartCoefficient (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::warmstartCoefficient.
R2Status	r2SetWarmstartCoefficient (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::warmstartCoefficient.
R2Real	r2NormalizedAllowedLinearError (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::normalizedAllowedLinearError.
R2Status	r2SetNormalizedAllowedLinearError (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::normalizedAllowedLinearError.
R2Real	r2NormalizedMaxCorrectiveVelocity (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::normalizedMaxCorrectiveVelocity.
R2Status	r2SetNormalizedMaxCorrectiveVelocity (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::normalizedMaxCorrectiveVelocity.
R2Real	r2NormalizedPredictionDistance (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::normalizedPredictionDistance.
R2Status	r2SetNormalizedPredictionDistance (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::normalizedPredictionDistance.
R2Real	r2NormalizedMaxLinearVelocity (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::normalizedMaxLinearVelocity.
R2Status	r2SetNormalizedMaxLinearVelocity (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::normalizedMaxLinearVelocity.
R2Real	r2NormalizedContactRecycleDistance (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::normalizedContactRecycleDistance.
R2Status	r2SetNormalizedContactRecycleDistance (struct R2World *world, R2Real value)
	Set the world setting documented by R2IntegrationParameters::normalizedContactRecycleDistance.
size_t	r2NumSolverIterations (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::numSolverIterations.
R2Status	r2SetNumSolverIterations (struct R2World *world, size_t value)
	Set the world setting documented by R2IntegrationParameters::numSolverIterations.
size_t	r2NumInternalPgsIterations (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::numInternalPgsIterations.
R2Status	r2SetNumInternalPgsIterations (struct R2World *world, size_t value)
	Set the world setting documented by R2IntegrationParameters::numInternalPgsIterations.
size_t	r2NumInternalStabilizationIterations (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::numInternalStabilizationIterations.
R2Status	r2SetNumInternalStabilizationIterations (struct R2World *world, size_t value)
	Set the world setting documented by R2IntegrationParameters::numInternalStabilizationIterations.
size_t	r2MaxCcdSubsteps (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::maxCcdSubsteps.
R2Status	r2SetMaxCcdSubsteps (struct R2World *world, size_t value)
	Set the world setting documented by R2IntegrationParameters::maxCcdSubsteps.
R2Bool	r2ContactClustering (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::contactClustering.
R2Status	r2SetContactClustering (struct R2World *world, R2Bool value)
	Set the world setting documented by R2IntegrationParameters::contactClustering.
R2Bool	r2ContactRecycling (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::contactRecycling.
R2Status	r2SetContactRecycling (struct R2World *world, R2Bool value)
	Set the world setting documented by R2IntegrationParameters::contactRecycling.
R2Bool	r2FrictionInBiasPass (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::frictionInBiasPass.
R2Status	r2SetFrictionInBiasPass (struct R2World *world, R2Bool value)
	Set the world setting documented by R2IntegrationParameters::frictionInBiasPass.
R2Bool	r2WarmstartJoints (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::warmstartJoints.
R2Status	r2SetWarmstartJoints (struct R2World *world, R2Bool value)
	Set the world setting documented by R2IntegrationParameters::warmstartJoints.
struct R2SpringCoefficients	r2ContactSoftness (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::contactSoftness.
R2Status	r2SetContactSoftness (struct R2World *world, struct R2SpringCoefficients value)
	Set the world setting documented by R2IntegrationParameters::contactSoftness.
struct R2SpringCoefficients	r2StaticContactSoftness (const struct R2World *world)
	Return the world setting documented by R2IntegrationParameters::staticContactSoftness.
R2Status	r2SetStaticContactSoftness (struct R2World *world, struct R2SpringCoefficients value)
	Set the world setting documented by R2IntegrationParameters::staticContactSoftness.
struct R2Vector	r2Gravity (const struct R2World *world)
	Return the world-space gravitational acceleration.
R2Status	r2SetGravity (struct R2World *world, struct R2Vector value)
	Set the world-space gravitational acceleration.
R2Status	r2Step (struct R2World *world, const struct R2PhysicsHooks *hooks, const struct R2EventCollector *events)
	Advance simulation by one timestep.
R2Status	r2DetectCollisions (struct R2World *world, const struct R2PhysicsHooks *hooks, const struct R2EventCollector *events)
	Refresh collision detection without advancing simulation.
struct R2ByteView	r2Bytes_Data (const struct R2Bytes *bytes)
	Borrow snapshot bytes without copying; valid until r2FreeBytes.
R2Status	r2FreeBytes (struct R2Bytes *bytes)
	Release an owned snapshot byte buffer.
struct R2Bytes *	r2SerializeWorld (const struct R2World *world)
	Return owned snapshot bytes; release them with r2FreeBytes.
struct R2World *	r2DeserializeWorld (const uint8_t *data, size_t count)
	Restore ONLY trusted snapshots produced by the identical Rapier build.
R2Status	r2SetNumThreads (struct R2World *world, size_t num_threads)
	Configures a dedicated pool for this world's parallel work.
R2Status	r2ClearThreadPool (struct R2World *world)
	Removes the world's dedicated pool.
size_t	r2NumThreads (const struct R2World *world)
	Size of the world's dedicated pool, or zero if a parallel build has no dedicated pool configured.
R2Status	r2SetCountersEnabled (struct R2World *world, R2Bool enabled)
	Enable or disable the native pipeline profiling counters.
double	r2StepTimeMs (const struct R2World *world)
	Native engine time of the most recent step, in milliseconds, as in the Rust testbed.
struct R2World *	r2DeserializeRigidState (const uint8_t *data, size_t count)
	Read ONLY trusted legacy rigid-world snapshots from debug_deserialize3.rs, produced by the identical Rapier build.
struct R2VolumeMeshParameters	r2NewVolumeMeshParameters (R2Real cell_size)
	Return volume-meshing settings for the supplied cell size; this POD value requires no destructor.
size_t	r2QuarantinedRigidBodies (const struct R2World *world, struct R2RigidBodyHandle *buffer, size_t capacity)
	Copy the rigid bodies quarantined by the most recent Step because their pose or velocity became non-finite (NaN or infinite).
size_t	r2QuarantinedColliders (const struct R2World *world, struct R2ColliderHandle *buffer, size_t capacity)
	Copy the colliders quarantined by the most recent Step because their own pose or shape became non-finite, independently of their parent.
size_t	r2QuarantinedSoftBodies (const struct R2World *world, struct R2SoftBodyHandle *buffer, size_t capacity)
	Copy the soft bodies quarantined by the most recent Step because a particle position or velocity became non-finite.
struct R2World *	r2NewWorld (void)
	Create an owned world.
R2Status	r2FreeWorld (struct R2World *world)
	Free a world.

Detailed Description

Create a world, configure integration, step, and serialize it.

Setters change the named setting for subsequent operations.

Typedef Documentation

R2Bytes

typedef struct R2Bytes R2Bytes

Immutable owned byte buffer.

Release with the matching FreeBytes function.

R2IntegrationParameters

typedef struct R2IntegrationParameters R2IntegrationParameters

Plain configuration data; initialize defaults, edit, then apply.

No destructor.

R2World

typedef struct R2World R2World

Sole owner of simulation state.

Handles belong to the world that created them. Ordinary reads may overlap. A mutation or step requires exclusive access. Destruction must be externally synchronized with all users of this pointer.

Function Documentation

r2ActiveRigidBodies()

size_t r2ActiveRigidBodies	(	const struct R2World *	world,
		struct R2RigidBodyHandle *	buffer,
		size_t	capacity )

Copies the island manager's active body handles.

See also

Arrays and output buffers

r2Bytes_Data()

struct R2ByteView r2Bytes_Data

(

const struct R2Bytes *

bytes

)

Borrow snapshot bytes without copying; valid until r2FreeBytes.

Never free the returned data pointer.

r2ClearThreadPool()

R2Status r2ClearThreadPool

(

struct R2World *

world

)

Removes the world's dedicated pool.

A parallel build then uses the calling context's Rayon pool (normally the global pool), not a single worker. Returns R2_UNSUPPORTED in a build without the parallel feature.

r2ContactClustering()

R2Bool r2ContactClustering

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::contactClustering.

r2ContactRecycling()

R2Bool r2ContactRecycling

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::contactRecycling.

r2ContactSoftness()

struct R2SpringCoefficients r2ContactSoftness

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::contactSoftness.

r2DefaultIntegrationParameters()

struct R2IntegrationParameters r2DefaultIntegrationParameters

(

void

)

Return native default integration parameters.

This POD value owns no resources.

r2DeserializeRigidState()

struct R2World * r2DeserializeRigidState	(	const uint8_t *	data,
		size_t	count )

Read ONLY trusted legacy rigid-world snapshots from debug_deserialize3.rs, produced by the identical Rapier build.

This is not a stable interchange format.

Import trusted legacy Rust testbed rigid-state bytes into a new owned world. Release with r2FreeWorld; see Snapshots.

r2DeserializeWorld()

struct R2World * r2DeserializeWorld	(	const uint8_t *	data,
		size_t	count )

Restore ONLY trusted snapshots produced by the identical Rapier build.

Snapshots are not a stable file format.

r2DetectCollisions()

R2Status r2DetectCollisions	(	struct R2World *	world,
		const struct R2PhysicsHooks *	hooks,
		const struct R2EventCollector *	events )

Refresh collision detection without advancing simulation.

Hooks and events may be NULL; events are appended to the collector.

r2FreeBytes()

R2Status r2FreeBytes

(

struct R2Bytes *

bytes

)

Release an owned snapshot byte buffer.

NULL is allowed. Do not pass borrowed pointers or free the object twice.

r2FreeWorld()

R2Status r2FreeWorld

(

struct R2World *

world

)

Free a world.

NULL is allowed. Rejects destruction from an active callback. The caller must prevent other threads from starting calls during destruction.

r2FrictionInBiasPass()

R2Bool r2FrictionInBiasPass

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::frictionInBiasPass.

r2Gravity()

struct R2Vector r2Gravity

(

const struct R2World *

world

)

Return the world-space gravitational acceleration.

r2IntegrationParameters()

struct R2IntegrationParameters r2IntegrationParameters

(

const struct R2World *

world

)

Return a copy of all world integration settings.

r2LengthUnit()

R2Real r2LengthUnit

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::lengthUnit.

r2MaxCcdSubsteps()

size_t r2MaxCcdSubsteps

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::maxCcdSubsteps.

r2MinCcdDt()

R2Real r2MinCcdDt

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::minCcdDt.

r2NewVolumeMeshParameters()

struct R2VolumeMeshParameters r2NewVolumeMeshParameters

(

R2Real

cell_size

)

Return volume-meshing settings for the supplied cell size; this POD value requires no destructor.

r2NewWorld()

struct R2World * r2NewWorld

(

void

)

Create an owned world.

Release it with FreeWorld.

r2NormalizedAllowedLinearError()

R2Real r2NormalizedAllowedLinearError

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::normalizedAllowedLinearError.

r2NormalizedContactRecycleDistance()

R2Real r2NormalizedContactRecycleDistance

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::normalizedContactRecycleDistance.

r2NormalizedMaxCorrectiveVelocity()

R2Real r2NormalizedMaxCorrectiveVelocity

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::normalizedMaxCorrectiveVelocity.

r2NormalizedMaxLinearVelocity()

R2Real r2NormalizedMaxLinearVelocity

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::normalizedMaxLinearVelocity.

r2NormalizedPredictionDistance()

R2Real r2NormalizedPredictionDistance

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::normalizedPredictionDistance.

r2NumInternalPgsIterations()

size_t r2NumInternalPgsIterations

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::numInternalPgsIterations.

r2NumInternalStabilizationIterations()

size_t r2NumInternalStabilizationIterations

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::numInternalStabilizationIterations.

r2NumSolverIterations()

size_t r2NumSolverIterations

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::numSolverIterations.

r2NumThreads()

size_t r2NumThreads

(

const struct R2World *

world

)

Size of the world's dedicated pool, or zero if a parallel build has no dedicated pool configured.

Returns one for a build without the parallel feature.

r2QuarantinedColliders()

size_t r2QuarantinedColliders	(	const struct R2World *	world,
		struct R2ColliderHandle *	buffer,
		size_t	capacity )

Copy the colliders quarantined by the most recent Step because their own pose or shape became non-finite, independently of their parent.

Rapier disabled them; re-enable them with Collider_SetEnabled once fixed. The list is cleared at the start of every Step and may hold handles removed since.

See also

Arrays and output buffers

r2QuarantinedRigidBodies()

size_t r2QuarantinedRigidBodies	(	const struct R2World *	world,
		struct R2RigidBodyHandle *	buffer,
		size_t	capacity )

Copy the rigid bodies quarantined by the most recent Step because their pose or velocity became non-finite (NaN or infinite).

Rapier disabled them, restored their last valid pose when known, and zeroed their velocities and forces; re-enable them with RigidBody_SetEnabled once the cause is fixed. The list is cleared at the start of every Step and may hold handles removed since.

See also

Arrays and output buffers

r2QuarantinedSoftBodies()

size_t r2QuarantinedSoftBodies	(	const struct R2World *	world,
		struct R2SoftBodyHandle *	buffer,
		size_t	capacity )

Copy the soft bodies quarantined by the most recent Step because a particle position or velocity became non-finite.

Rapier disabled them and zeroed their velocities but left the non-finite positions: fix them with SoftBody_SetParticlePosition before SoftBody_SetEnabled. The list is cleared at the start of every Step and may hold handles removed since.

See also

Arrays and output buffers

r2SerializeWorld()

struct R2Bytes * r2SerializeWorld

(

const struct R2World *

world

)

Return owned snapshot bytes; release them with r2FreeBytes.

See Snapshots for restoration and handle lifetimes.

r2SetContactClustering()

R2Status r2SetContactClustering	(	struct R2World *	world,
		R2Bool	value )

Set the world setting documented by R2IntegrationParameters::contactClustering.

r2SetContactRecycling()

R2Status r2SetContactRecycling	(	struct R2World *	world,
		R2Bool	value )

Set the world setting documented by R2IntegrationParameters::contactRecycling.

r2SetContactSoftness()

R2Status r2SetContactSoftness	(	struct R2World *	world,
		struct R2SpringCoefficients	value )

Set the world setting documented by R2IntegrationParameters::contactSoftness.

r2SetCountersEnabled()

R2Status r2SetCountersEnabled	(	struct R2World *	world,
		R2Bool	enabled )

Enable or disable the native pipeline profiling counters.

Enabling returns R2_UNSUPPORTED if the library was built without the profiler feature.

r2SetFrictionInBiasPass()

R2Status r2SetFrictionInBiasPass	(	struct R2World *	world,
		R2Bool	value )

Set the world setting documented by R2IntegrationParameters::frictionInBiasPass.

r2SetGravity()

R2Status r2SetGravity	(	struct R2World *	world,
		struct R2Vector	value )

Set the world-space gravitational acceleration.

r2SetIntegrationParameters()

R2Status r2SetIntegrationParameters	(	struct R2World *	world,
		const struct R2IntegrationParameters *	data )

Copies validated values; does not expose a writable alias to Rust memory.

r2SetLengthUnit()

R2Status r2SetLengthUnit	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::lengthUnit.

r2SetMaxCcdSubsteps()

R2Status r2SetMaxCcdSubsteps	(	struct R2World *	world,
		size_t	value )

Set the world setting documented by R2IntegrationParameters::maxCcdSubsteps.

r2SetMinCcdDt()

R2Status r2SetMinCcdDt	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::minCcdDt.

r2SetNormalizedAllowedLinearError()

R2Status r2SetNormalizedAllowedLinearError	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::normalizedAllowedLinearError.

r2SetNormalizedContactRecycleDistance()

R2Status r2SetNormalizedContactRecycleDistance	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::normalizedContactRecycleDistance.

r2SetNormalizedMaxCorrectiveVelocity()

R2Status r2SetNormalizedMaxCorrectiveVelocity	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::normalizedMaxCorrectiveVelocity.

r2SetNormalizedMaxLinearVelocity()

R2Status r2SetNormalizedMaxLinearVelocity	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::normalizedMaxLinearVelocity.

r2SetNormalizedPredictionDistance()

R2Status r2SetNormalizedPredictionDistance	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::normalizedPredictionDistance.

r2SetNumInternalPgsIterations()

R2Status r2SetNumInternalPgsIterations	(	struct R2World *	world,
		size_t	value )

Set the world setting documented by R2IntegrationParameters::numInternalPgsIterations.

r2SetNumInternalStabilizationIterations()

R2Status r2SetNumInternalStabilizationIterations	(	struct R2World *	world,
		size_t	value )

Set the world setting documented by R2IntegrationParameters::numInternalStabilizationIterations.

r2SetNumSolverIterations()

R2Status r2SetNumSolverIterations	(	struct R2World *	world,
		size_t	value )

Set the world setting documented by R2IntegrationParameters::numSolverIterations.

r2SetNumThreads()

R2Status r2SetNumThreads	(	struct R2World *	world,
		size_t	num_threads )

Configures a dedicated pool for this world's parallel work.

Zero selects Rayon's default. Takes effect on the next step. Reconfiguration must not race with a step or callback. Returns R2_UNSUPPORTED in builds without the parallel feature; keeps the previous pool when constructing the new one fails. The pool is not included in snapshots.

r2SetStaticContactSoftness()

R2Status r2SetStaticContactSoftness	(	struct R2World *	world,
		struct R2SpringCoefficients	value )

Set the world setting documented by R2IntegrationParameters::staticContactSoftness.

r2SetTimeStep()

R2Status r2SetTimeStep	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::dt.

r2SetWarmstartCoefficient()

R2Status r2SetWarmstartCoefficient	(	struct R2World *	world,
		R2Real	value )

Set the world setting documented by R2IntegrationParameters::warmstartCoefficient.

r2SetWarmstartJoints()

R2Status r2SetWarmstartJoints	(	struct R2World *	world,
		R2Bool	value )

Set the world setting documented by R2IntegrationParameters::warmstartJoints.

r2StaticContactSoftness()

struct R2SpringCoefficients r2StaticContactSoftness

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::staticContactSoftness.

r2Step()

R2Status r2Step	(	struct R2World *	world,
		const struct R2PhysicsHooks *	hooks,
		const struct R2EventCollector *	events )

Advance simulation by one timestep.

Hooks and events may be NULL. Events are appended to the collector, which is never cleared automatically. This call invalidates all borrowed set-element pointers.

r2StepTimeMs()

double r2StepTimeMs

(

const struct R2World *

world

)

Native engine time of the most recent step, in milliseconds, as in the Rust testbed.

Enable counters before stepping. Excludes C callbacks outside the step, rendering, and dispatch into a dedicated thread pool; remains unchanged while paused.

r2TimeStep()

R2Real r2TimeStep

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::dt.

r2WarmstartCoefficient()

R2Real r2WarmstartCoefficient

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::warmstartCoefficient.

r2WarmstartJoints()

R2Bool r2WarmstartJoints

(

const struct R2World *

world

)

Return the world setting documented by R2IntegrationParameters::warmstartJoints.