Character, vehicle, and PID controllers

Controllers compute motion/corrections or apply forces; they do not replace Step. More...

Data Structures
struct	R2CharacterLength
	CharacterLength counterpart: relative=1 scales with character height, relative=0 uses world units. More...
struct	R2CharacterAutostep
	Copy of the automatic stepping settings. More...
struct	R2CharacterMovement
	Allowed character motion and ground-contact state. More...
struct	R2CharacterCollision
	Collision recorded during character movement. More...
struct	R2PidGains
	Per-axis proportional, integral, and derivative controller gains. More...
struct	R2PdController
	Stateless proportional-derivative controller: a PID controller without integral term, stored as a plain value. More...
struct	R2VelocityCorrection
	Linear and angular velocity correction computed by a controller. More...
struct	R2CharacterControllerSettings
	Copy of character sliding, slope, and snapping settings. More...

Macros
#define	R2_AXES_MASK_LIN_X   1
	Controller axis bit: translation along X.
#define	R2_AXES_MASK_LIN_Y   2
	Controller axis bit: translation along Y.
#define	R2_AXES_MASK_ANG_Z   32
	Controller axis bit: rotation about Z (the only rotation axis in 2D).

Typedefs
typedef struct R2KinematicCharacterController	R2KinematicCharacterController
	Controller plus reusable collision output from the last move_shape call.
typedef struct R2PidController	R2PidController
	PID controller with persistent integral state.
typedef struct R2CharacterLength	R2CharacterLength
	CharacterLength counterpart: relative=1 scales with character height, relative=0 uses world units.
typedef struct R2CharacterAutostep	R2CharacterAutostep
	Copy of the automatic stepping settings.
typedef struct R2CharacterMovement	R2CharacterMovement
	Allowed character motion and ground-contact state.
typedef struct R2CharacterCollision	R2CharacterCollision
	Collision recorded during character movement.
typedef struct R2PidGains	R2PidGains
	Per-axis proportional, integral, and derivative controller gains.
typedef struct R2PdController	R2PdController
	Stateless proportional-derivative controller: a PID controller without integral term, stored as a plain value.
typedef struct R2VelocityCorrection	R2VelocityCorrection
	Linear and angular velocity correction computed by a controller.
typedef struct R2CharacterControllerSettings	R2CharacterControllerSettings
	Copy of character sliding, slope, and snapping settings.

Functions
struct R2KinematicCharacterController *	r2NewKinematicCharacterController (void)
	Allocate a character controller with native defaults; release it with r2FreeKinematicCharacterController.
R2Status	r2FreeKinematicCharacterController (struct R2KinematicCharacterController *controller)
	Release an owned kinematic character controller.
R2Status	r2KinematicCharacterController_SetUp (struct R2KinematicCharacterController *controller, struct R2Vector up)
	Set the up direction; it must be finite and nonzero and is normalized on input.
R2Status	r2KinematicCharacterController_SetOffset (struct R2KinematicCharacterController *controller, struct R2CharacterLength offset)
	Set the collision separation margin; use a positive absolute or relative character length.
R2Status	r2KinematicCharacterController_SetSlide (struct R2KinematicCharacterController *controller, R2Bool enabled)
	Enable or disable sliding along obstacles.
R2Status	r2KinematicCharacterController_SetSlopes (struct R2KinematicCharacterController *controller, R2Real max_climb_angle, R2Real min_slide_angle)
	Set the maximum climb angle and minimum slide angle, in radians.
R2Status	r2KinematicCharacterController_SetAutostep (struct R2KinematicCharacterController *controller, R2Bool enabled, struct R2CharacterLength max_height, struct R2CharacterLength min_width, R2Bool include_dynamic_bodies)
	Configure automatic stepping over obstacles.
R2Status	r2KinematicCharacterController_SetSnapToGround (struct R2KinematicCharacterController *controller, R2Bool enabled, struct R2CharacterLength distance)
	Configure downward ground snapping.
struct R2Vector	r2KinematicCharacterController_Up (const struct R2KinematicCharacterController *controller)
	Return the normalized up direction.
struct R2CharacterLength	r2KinematicCharacterController_Offset (const struct R2KinematicCharacterController *controller)
	Return the collision separation margin.
struct R2CharacterAutostep	r2KinematicCharacterController_Autostep (const struct R2KinematicCharacterController *controller)
	Return the automatic stepping settings.
R2Status	r2KinematicCharacterController_SetNormalNudgeFactor (struct R2KinematicCharacterController *controller, R2Real value)
	Set the small distance by which sliding motion is pushed along hit normals to avoid getting stuck; it must be finite and nonnegative.
R2Real	r2KinematicCharacterController_NormalNudgeFactor (const struct R2KinematicCharacterController *controller)
	Return the normal nudge factor set by SetNormalNudgeFactor.
struct R2CharacterMovement	r2KinematicCharacterController_MoveShape (const struct R2World *world, const struct R2QueryOptions *options, struct R2KinematicCharacterController *controller, R2Real dt, const R2SharedShape *shape, struct R2Pose pose, struct R2Vector desired_translation)
	Computes movement without moving any collider.
size_t	r2KinematicCharacterController_Collisions (const struct R2KinematicCharacterController *controller, struct R2CharacterCollision *buffer, size_t capacity)
	Copy collisions recorded by the most recent MoveShape call.
R2Status	r2KinematicCharacterController_SolveCharacterCollisionImpulses (const struct R2KinematicCharacterController *controller, const R2SharedShape *shape, R2Real dt, R2Real mass, const struct R2QueryOptions *options)
	Applies impulses to the dynamic bodies hit by the most recent MoveShape call.
struct R2PidController *	r2NewPidController (void)
	Allocate a PID controller with Rapier's defaults: kp = 60, ki = 1 and kd = 0.8 on every axis, all axes controlled, and zero integrals.
R2Status	r2FreePidController (struct R2PidController *controller)
	Release an owned pid controller.
struct R2PidGains	r2PidController_Gains (const struct R2PidController *controller)
	Return a copy of the proportional, integral, and derivative gains.
R2Status	r2PidController_SetGains (struct R2PidController *controller, struct R2PidGains gains)
	Replace the proportional, integral, and derivative gains.
R2Status	r2PidController_SetAxes (struct R2PidController *controller, uint32_t axes)
	Set the controlled axes, a combination of R2_AXES_MASK_* bits.
uint32_t	r2PidController_Axes (const struct R2PidController *controller)
	Return the controlled axes as R2_AXES_MASK_* bits.
R2Status	r2PidController_ResetIntegrals (struct R2PidController *controller)
	Reset to zero the linear and angular errors accumulated by the integral term.
struct R2PdController	r2DefaultPdController (void)
	Return Rapier's default PD controller: kp = 60 and kd = 0.8 on every axis, all axes controlled.
struct R2VelocityCorrection	r2PdController_RigidBodyCorrection (const struct R2PdController *controller, struct R2RigidBodyHandle body, struct R2Pose target_pose, struct R2Vector target_linvel, R2AngVector target_angvel)
	Compute the velocity change bringing the body toward the target pose and velocities.
struct R2VelocityCorrection	r2PidController_RigidBodyCorrection (struct R2PidController *controller, R2Real dt, struct R2RigidBodyHandle body, struct R2Pose target_pose, struct R2Vector target_linvel, R2AngVector target_angvel)
	Compute a velocity correction, preserving the body's state and updating PID integrals.
struct R2CharacterControllerSettings	r2KinematicCharacterController_Settings (const struct R2KinematicCharacterController *controller)
	Return a copy of slide, slope, and ground-snap settings.

Detailed Description

Controllers compute motion/corrections or apply forces; they do not replace Step.

Keep referenced worlds and bodies alive for controller operations.

Macro Definition Documentation

R2_AXES_MASK_ANG_Z

#define R2_AXES_MASK_ANG_Z   32

Controller axis bit: rotation about Z (the only rotation axis in 2D).

R2_AXES_MASK_LIN_X

#define R2_AXES_MASK_LIN_X   1

Controller axis bit: translation along X.

R2_AXES_MASK_LIN_Y

#define R2_AXES_MASK_LIN_Y   2

Controller axis bit: translation along Y.

Typedef Documentation

R2CharacterAutostep

typedef struct R2CharacterAutostep R2CharacterAutostep

Copy of the automatic stepping settings.

R2CharacterCollision

typedef struct R2CharacterCollision R2CharacterCollision

Collision recorded during character movement.

R2CharacterControllerSettings

typedef struct R2CharacterControllerSettings R2CharacterControllerSettings

Copy of character sliding, slope, and snapping settings.

R2CharacterLength

typedef struct R2CharacterLength R2CharacterLength

CharacterLength counterpart: relative=1 scales with character height, relative=0 uses world units.

R2CharacterMovement

typedef struct R2CharacterMovement R2CharacterMovement

Allowed character motion and ground-contact state.

R2KinematicCharacterController

typedef struct R2KinematicCharacterController R2KinematicCharacterController

Controller plus reusable collision output from the last move_shape call.

Kinematic character controller and its last collision list. Release with the matching Free function.

R2PdController

typedef struct R2PdController R2PdController

Stateless proportional-derivative controller: a PID controller without integral term, stored as a plain value.

Initialize with r2DefaultPdController.

R2PidController

typedef struct R2PidController R2PidController

PID controller with persistent integral state.

Stateful proportional-integral-derivative controller. Release with the matching Free function.

R2PidGains

typedef struct R2PidGains R2PidGains

Per-axis proportional, integral, and derivative controller gains.

R2VelocityCorrection

typedef struct R2VelocityCorrection R2VelocityCorrection

Linear and angular velocity correction computed by a controller.

Function Documentation

r2DefaultPdController()

struct R2PdController r2DefaultPdController

(

void

)

Return Rapier's default PD controller: kp = 60 and kd = 0.8 on every axis, all axes controlled.

This POD value owns no resources.

r2FreeKinematicCharacterController()

R2Status r2FreeKinematicCharacterController

(

struct R2KinematicCharacterController *

controller

)

Release an owned kinematic character controller.

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

r2FreePidController()

R2Status r2FreePidController

(

struct R2PidController *

controller

)

Release an owned pid controller.

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

r2KinematicCharacterController_Autostep()

struct R2CharacterAutostep r2KinematicCharacterController_Autostep

(

const struct R2KinematicCharacterController *

controller

)

Return the automatic stepping settings.

When disabled, enabled is 0 and the other fields hold Rapier's defaults.

r2KinematicCharacterController_Collisions()

size_t r2KinematicCharacterController_Collisions	(	const struct R2KinematicCharacterController *	controller,
		struct R2CharacterCollision *	buffer,
		size_t	capacity )

Copy collisions recorded by the most recent MoveShape call.

See also

Arrays and output buffers

r2KinematicCharacterController_MoveShape()

struct R2CharacterMovement r2KinematicCharacterController_MoveShape	(	const struct R2World *	world,
		const struct R2QueryOptions *	options,
		struct R2KinematicCharacterController *	controller,
		R2Real	dt,
		const R2SharedShape *	shape,
		struct R2Pose	pose,
		struct R2Vector	desired_translation )

Computes movement without moving any collider.

Use the returned translation to set the character target. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r2KinematicCharacterController_NormalNudgeFactor()

R2Real r2KinematicCharacterController_NormalNudgeFactor

(

const struct R2KinematicCharacterController *

controller

)

Return the normal nudge factor set by SetNormalNudgeFactor.

r2KinematicCharacterController_Offset()

struct R2CharacterLength r2KinematicCharacterController_Offset

(

const struct R2KinematicCharacterController *

controller

)

Return the collision separation margin.

r2KinematicCharacterController_SetAutostep()

R2Status r2KinematicCharacterController_SetAutostep	(	struct R2KinematicCharacterController *	controller,
		R2Bool	enabled,
		struct R2CharacterLength	max_height,
		struct R2CharacterLength	min_width,
		R2Bool	include_dynamic_bodies )

Configure automatic stepping over obstacles.

enabled = 0 disables it.

r2KinematicCharacterController_SetNormalNudgeFactor()

R2Status r2KinematicCharacterController_SetNormalNudgeFactor	(	struct R2KinematicCharacterController *	controller,
		R2Real	value )

Set the small distance by which sliding motion is pushed along hit normals to avoid getting stuck; it must be finite and nonnegative.

Large values cause bumps when sliding on flat ground.

r2KinematicCharacterController_SetOffset()

R2Status r2KinematicCharacterController_SetOffset	(	struct R2KinematicCharacterController *	controller,
		struct R2CharacterLength	offset )

Set the collision separation margin; use a positive absolute or relative character length.

r2KinematicCharacterController_SetSlide()

R2Status r2KinematicCharacterController_SetSlide	(	struct R2KinematicCharacterController *	controller,
		R2Bool	enabled )

Enable or disable sliding along obstacles.

r2KinematicCharacterController_SetSlopes()

R2Status r2KinematicCharacterController_SetSlopes	(	struct R2KinematicCharacterController *	controller,
		R2Real	max_climb_angle,
		R2Real	min_slide_angle )

Set the maximum climb angle and minimum slide angle, in radians.

r2KinematicCharacterController_SetSnapToGround()

R2Status r2KinematicCharacterController_SetSnapToGround	(	struct R2KinematicCharacterController *	controller,
		R2Bool	enabled,
		struct R2CharacterLength	distance )

Configure downward ground snapping.

enabled = 0 disables it.

r2KinematicCharacterController_Settings()

struct R2CharacterControllerSettings r2KinematicCharacterController_Settings

(

const struct R2KinematicCharacterController *

controller

)

Return a copy of slide, slope, and ground-snap settings.

r2KinematicCharacterController_SetUp()

R2Status r2KinematicCharacterController_SetUp	(	struct R2KinematicCharacterController *	controller,
		struct R2Vector	up )

Set the up direction; it must be finite and nonzero and is normalized on input.

r2KinematicCharacterController_SolveCharacterCollisionImpulses()

R2Status r2KinematicCharacterController_SolveCharacterCollisionImpulses	(	const struct R2KinematicCharacterController *	controller,
		const R2SharedShape *	shape,
		R2Real	dt,
		R2Real	mass,
		const struct R2QueryOptions *	options )

Applies impulses to the dynamic bodies hit by the most recent MoveShape call.

Use the same shape, dt and query options as that call; NULL options use the default filter. Unlike MoveShape, the options' predicate is called once per collider of the world before the impulses are applied, while the world is locked for writing: it may only use Read* functions.

r2KinematicCharacterController_Up()

struct R2Vector r2KinematicCharacterController_Up

(

const struct R2KinematicCharacterController *

controller

)

Return the normalized up direction.

r2NewKinematicCharacterController()

struct R2KinematicCharacterController * r2NewKinematicCharacterController

(

void

)

Allocate a character controller with native defaults; release it with r2FreeKinematicCharacterController.

r2NewPidController()

struct R2PidController * r2NewPidController

(

void

)

Allocate a PID controller with Rapier's defaults: kp = 60, ki = 1 and kd = 0.8 on every axis, all axes controlled, and zero integrals.

Release with r2FreePidController.

r2PdController_RigidBodyCorrection()

struct R2VelocityCorrection r2PdController_RigidBodyCorrection	(	const struct R2PdController *	controller,
		struct R2RigidBodyHandle	body,
		struct R2Pose	target_pose,
		struct R2Vector	target_linvel,
		R2AngVector	target_angvel )

Compute the velocity change bringing the body toward the target pose and velocities.

Neither the body nor the controller is modified.

r2PidController_Axes()

uint32_t r2PidController_Axes

(

const struct R2PidController *

controller

)

Return the controlled axes as R2_AXES_MASK_* bits.

r2PidController_Gains()

struct R2PidGains r2PidController_Gains

(

const struct R2PidController *

controller

)

Return a copy of the proportional, integral, and derivative gains.

r2PidController_ResetIntegrals()

R2Status r2PidController_ResetIntegrals

(

struct R2PidController *

controller

)

Reset to zero the linear and angular errors accumulated by the integral term.

r2PidController_RigidBodyCorrection()

struct R2VelocityCorrection r2PidController_RigidBodyCorrection	(	struct R2PidController *	controller,
		R2Real	dt,
		struct R2RigidBodyHandle	body,
		struct R2Pose	target_pose,
		struct R2Vector	target_linvel,
		R2AngVector	target_angvel )

Compute a velocity correction, preserving the body's state and updating PID integrals.

r2PidController_SetAxes()

R2Status r2PidController_SetAxes	(	struct R2PidController *	controller,
		uint32_t	axes )

Set the controlled axes, a combination of R2_AXES_MASK_* bits.

Gains are unchanged; unknown bits are rejected.

r2PidController_SetGains()

R2Status r2PidController_SetGains	(	struct R2PidController *	controller,
		struct R2PidGains	gains )

Replace the proportional, integral, and derivative gains.