Character, vehicle, and PID controllers

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

Data Structures
struct	R3CharacterLength
	CharacterLength counterpart: relative=1 scales with character height, relative=0 uses world units. More...
struct	R3CharacterAutostep
	Copy of the automatic stepping settings. More...
struct	R3CharacterMovement
	Allowed character motion and ground-contact state. More...
struct	R3CharacterCollision
	Collision recorded during character movement. More...
struct	R3PidGains
	Per-axis proportional, integral, and derivative controller gains. More...
struct	R3PdController
	Stateless proportional-derivative controller: a PID controller without integral term, stored as a plain value. More...
struct	R3VelocityCorrection
	Linear and angular velocity correction computed by a controller. More...
struct	R3CharacterControllerSettings
	Copy of character sliding, slope, and snapping settings. More...
struct	R3WheelTuning
	Wheel suspension/friction parameters. More...
struct	R3WheelState
	Copy of the current wheel pose, suspension, and contact state. More...

Macros
#define	R3_AXES_MASK_LIN_X   1
	Controller axis bit: translation along X.
#define	R3_AXES_MASK_LIN_Y   2
	Controller axis bit: translation along Y.
#define	R3_AXES_MASK_LIN_Z   4
	Controller axis bit: translation along Z.
#define	R3_AXES_MASK_ANG_X   8
	Controller axis bit: rotation about X.
#define	R3_AXES_MASK_ANG_Y   16
	Controller axis bit: rotation about Y.
#define	R3_AXES_MASK_ANG_Z   32
	Controller axis bit: rotation about Z (the only rotation axis in 2D).

Typedefs
typedef struct R3DynamicRayCastVehicleController	R3DynamicRayCastVehicleController
	Vehicle controller borrowing its chassis world.
typedef struct R3KinematicCharacterController	R3KinematicCharacterController
	Controller plus reusable collision output from the last move_shape call.
typedef struct R3PidController	R3PidController
	PID controller with persistent integral state.
typedef struct R3CharacterLength	R3CharacterLength
	CharacterLength counterpart: relative=1 scales with character height, relative=0 uses world units.
typedef struct R3CharacterAutostep	R3CharacterAutostep
	Copy of the automatic stepping settings.
typedef struct R3CharacterMovement	R3CharacterMovement
	Allowed character motion and ground-contact state.
typedef struct R3CharacterCollision	R3CharacterCollision
	Collision recorded during character movement.
typedef struct R3PidGains	R3PidGains
	Per-axis proportional, integral, and derivative controller gains.
typedef struct R3PdController	R3PdController
	Stateless proportional-derivative controller: a PID controller without integral term, stored as a plain value.
typedef struct R3VelocityCorrection	R3VelocityCorrection
	Linear and angular velocity correction computed by a controller.
typedef struct R3CharacterControllerSettings	R3CharacterControllerSettings
	Copy of character sliding, slope, and snapping settings.
typedef struct R3WheelTuning	R3WheelTuning
	Wheel suspension/friction parameters.
typedef struct R3WheelState	R3WheelState
	Copy of the current wheel pose, suspension, and contact state.

Functions
struct R3KinematicCharacterController *	r3NewKinematicCharacterController (void)
	Allocate a character controller with native defaults; release it with r3FreeKinematicCharacterController.
R3Status	r3FreeKinematicCharacterController (struct R3KinematicCharacterController *controller)
	Release an owned kinematic character controller.
R3Status	r3KinematicCharacterController_SetUp (struct R3KinematicCharacterController *controller, struct R3Vector up)
	Set the up direction; it must be finite and nonzero and is normalized on input.
R3Status	r3KinematicCharacterController_SetOffset (struct R3KinematicCharacterController *controller, struct R3CharacterLength offset)
	Set the collision separation margin; use a positive absolute or relative character length.
R3Status	r3KinematicCharacterController_SetSlide (struct R3KinematicCharacterController *controller, R3Bool enabled)
	Enable or disable sliding along obstacles.
R3Status	r3KinematicCharacterController_SetSlopes (struct R3KinematicCharacterController *controller, R3Real max_climb_angle, R3Real min_slide_angle)
	Set the maximum climb angle and minimum slide angle, in radians.
R3Status	r3KinematicCharacterController_SetAutostep (struct R3KinematicCharacterController *controller, R3Bool enabled, struct R3CharacterLength max_height, struct R3CharacterLength min_width, R3Bool include_dynamic_bodies)
	Configure automatic stepping over obstacles.
R3Status	r3KinematicCharacterController_SetSnapToGround (struct R3KinematicCharacterController *controller, R3Bool enabled, struct R3CharacterLength distance)
	Configure downward ground snapping.
struct R3Vector	r3KinematicCharacterController_Up (const struct R3KinematicCharacterController *controller)
	Return the normalized up direction.
struct R3CharacterLength	r3KinematicCharacterController_Offset (const struct R3KinematicCharacterController *controller)
	Return the collision separation margin.
struct R3CharacterAutostep	r3KinematicCharacterController_Autostep (const struct R3KinematicCharacterController *controller)
	Return the automatic stepping settings.
R3Status	r3KinematicCharacterController_SetNormalNudgeFactor (struct R3KinematicCharacterController *controller, R3Real value)
	Set the small distance by which sliding motion is pushed along hit normals to avoid getting stuck; it must be finite and nonnegative.
R3Real	r3KinematicCharacterController_NormalNudgeFactor (const struct R3KinematicCharacterController *controller)
	Return the normal nudge factor set by SetNormalNudgeFactor.
struct R3CharacterMovement	r3KinematicCharacterController_MoveShape (const struct R3World *world, const struct R3QueryOptions *options, struct R3KinematicCharacterController *controller, R3Real dt, const R3SharedShape *shape, struct R3Pose pose, struct R3Vector desired_translation)
	Computes movement without moving any collider.
size_t	r3KinematicCharacterController_Collisions (const struct R3KinematicCharacterController *controller, struct R3CharacterCollision *buffer, size_t capacity)
	Copy collisions recorded by the most recent MoveShape call.
R3Status	r3KinematicCharacterController_SolveCharacterCollisionImpulses (const struct R3KinematicCharacterController *controller, const R3SharedShape *shape, R3Real dt, R3Real mass, const struct R3QueryOptions *options)
	Applies impulses to the dynamic bodies hit by the most recent MoveShape call.
struct R3PidController *	r3NewPidController (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.
R3Status	r3FreePidController (struct R3PidController *controller)
	Release an owned pid controller.
struct R3PidGains	r3PidController_Gains (const struct R3PidController *controller)
	Return a copy of the proportional, integral, and derivative gains.
R3Status	r3PidController_SetGains (struct R3PidController *controller, struct R3PidGains gains)
	Replace the proportional, integral, and derivative gains.
R3Status	r3PidController_SetAxes (struct R3PidController *controller, uint32_t axes)
	Set the controlled axes, a combination of R3_AXES_MASK_* bits.
uint32_t	r3PidController_Axes (const struct R3PidController *controller)
	Return the controlled axes as R3_AXES_MASK_* bits.
R3Status	r3PidController_ResetIntegrals (struct R3PidController *controller)
	Reset to zero the linear and angular errors accumulated by the integral term.
struct R3PdController	r3DefaultPdController (void)
	Return Rapier's default PD controller: kp = 60 and kd = 0.8 on every axis, all axes controlled.
struct R3VelocityCorrection	r3PdController_RigidBodyCorrection (const struct R3PdController *controller, struct R3RigidBodyHandle body, struct R3Pose target_pose, struct R3Vector target_linvel, R3AngVector target_angvel)
	Compute the velocity change bringing the body toward the target pose and velocities.
struct R3VelocityCorrection	r3PidController_RigidBodyCorrection (struct R3PidController *controller, R3Real dt, struct R3RigidBodyHandle body, struct R3Pose target_pose, struct R3Vector target_linvel, R3AngVector target_angvel)
	Compute a velocity correction, preserving the body's state and updating PID integrals.
struct R3CharacterControllerSettings	r3KinematicCharacterController_Settings (const struct R3KinematicCharacterController *controller)
	Return a copy of slide, slope, and ground-snap settings.
struct R3WheelTuning	r3DefaultWheelTuning (void)
	Return native default wheel tuning.
struct R3DynamicRayCastVehicleController *	r3NewDynamicRayCastVehicleController (struct R3RigidBodyHandle chassis)
	Allocate a vehicle controller bound to its chassis body.
R3Status	r3FreeDynamicRayCastVehicleController (struct R3DynamicRayCastVehicleController *controller)
	Release an owned dynamic ray cast vehicle controller.
size_t	r3DynamicRayCastVehicleController_AddWheel (struct R3DynamicRayCastVehicleController *controller, struct R3Vector connection, struct R3Vector direction, struct R3Vector axle, R3Real rest_length, R3Real radius, const struct R3WheelTuning *tuning)
	Append a wheel and return its zero-based index.
R3Status	r3DynamicRayCastVehicleController_SetAxes (struct R3DynamicRayCastVehicleController *controller, size_t up, size_t forward)
	Set the chassis up/forward axis indices (0 = X, 1 = Y, 2 = Z).
R3Status	r3DynamicRayCastVehicleController_SetWheelControls (struct R3DynamicRayCastVehicleController *controller, size_t index, R3Real steering, R3Real engine_force, R3Real brake)
	Set a wheel engine force, brake force, and steering angle in radians.
R3Status	r3DynamicRayCastVehicleController_UpdateVehicle (struct R3DynamicRayCastVehicleController *controller, R3Real dt, const struct R3QueryOptions *options)
	Ray-cast wheel contacts and apply vehicle forces for dt seconds.
R3Real	r3DynamicRayCastVehicleController_CurrentVehicleSpeed (const struct R3DynamicRayCastVehicleController *controller)
	Return signed chassis speed along its forward direction.
size_t	r3DynamicRayCastVehicleController_Wheels (const struct R3DynamicRayCastVehicleController *controller, struct R3WheelState *buffer, size_t capacity)
	Copy current wheel state in wheel insertion order.

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

R3_AXES_MASK_ANG_X

#define R3_AXES_MASK_ANG_X   8

Controller axis bit: rotation about X.

R3_AXES_MASK_ANG_Y

#define R3_AXES_MASK_ANG_Y   16

Controller axis bit: rotation about Y.

R3_AXES_MASK_ANG_Z

#define R3_AXES_MASK_ANG_Z   32

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

R3_AXES_MASK_LIN_X

#define R3_AXES_MASK_LIN_X   1

Controller axis bit: translation along X.

R3_AXES_MASK_LIN_Y

#define R3_AXES_MASK_LIN_Y   2

Controller axis bit: translation along Y.

R3_AXES_MASK_LIN_Z

#define R3_AXES_MASK_LIN_Z   4

Controller axis bit: translation along Z.

Typedef Documentation

R3CharacterAutostep

typedef struct R3CharacterAutostep R3CharacterAutostep

Copy of the automatic stepping settings.

R3CharacterCollision

typedef struct R3CharacterCollision R3CharacterCollision

Collision recorded during character movement.

R3CharacterControllerSettings

typedef struct R3CharacterControllerSettings R3CharacterControllerSettings

Copy of character sliding, slope, and snapping settings.

R3CharacterLength

typedef struct R3CharacterLength R3CharacterLength

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

R3CharacterMovement

typedef struct R3CharacterMovement R3CharacterMovement

Allowed character motion and ground-contact state.

R3DynamicRayCastVehicleController

typedef struct R3DynamicRayCastVehicleController R3DynamicRayCastVehicleController

Vehicle controller borrowing its chassis world.

Release with the matching Free function.

R3KinematicCharacterController

typedef struct R3KinematicCharacterController R3KinematicCharacterController

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.

R3PdController

typedef struct R3PdController R3PdController

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

Initialize with r3DefaultPdController.

R3PidController

typedef struct R3PidController R3PidController

PID controller with persistent integral state.

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

R3PidGains

typedef struct R3PidGains R3PidGains

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

R3VelocityCorrection

typedef struct R3VelocityCorrection R3VelocityCorrection

Linear and angular velocity correction computed by a controller.

R3WheelState

typedef struct R3WheelState R3WheelState

Copy of the current wheel pose, suspension, and contact state.

R3WheelTuning

typedef struct R3WheelTuning R3WheelTuning

Wheel suspension/friction parameters.

Initialize with r3DefaultWheelTuning.

Function Documentation

r3DefaultPdController()

struct R3PdController r3DefaultPdController

(

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.

r3DefaultWheelTuning()

struct R3WheelTuning r3DefaultWheelTuning

(

void

)

Return native default wheel tuning.

This POD value owns no resources.

r3DynamicRayCastVehicleController_AddWheel()

size_t r3DynamicRayCastVehicleController_AddWheel	(	struct R3DynamicRayCastVehicleController *	controller,
		struct R3Vector	connection,
		struct R3Vector	direction,
		struct R3Vector	axle,
		R3Real	rest_length,
		R3Real	radius,
		const struct R3WheelTuning *	tuning )

Append a wheel and return its zero-based index.

Connection, suspension direction, and axle are in chassis-local coordinates.

r3DynamicRayCastVehicleController_CurrentVehicleSpeed()

R3Real r3DynamicRayCastVehicleController_CurrentVehicleSpeed

(

const struct R3DynamicRayCastVehicleController *

controller

)

Return signed chassis speed along its forward direction.

r3DynamicRayCastVehicleController_SetAxes()

R3Status r3DynamicRayCastVehicleController_SetAxes	(	struct R3DynamicRayCastVehicleController *	controller,
		size_t	up,
		size_t	forward )

Set the chassis up/forward axis indices (0 = X, 1 = Y, 2 = Z).

r3DynamicRayCastVehicleController_SetWheelControls()

R3Status r3DynamicRayCastVehicleController_SetWheelControls	(	struct R3DynamicRayCastVehicleController *	controller,
		size_t	index,
		R3Real	steering,
		R3Real	engine_force,
		R3Real	brake )

Set a wheel engine force, brake force, and steering angle in radians.

r3DynamicRayCastVehicleController_UpdateVehicle()

R3Status r3DynamicRayCastVehicleController_UpdateVehicle	(	struct R3DynamicRayCastVehicleController *	controller,
		R3Real	dt,
		const struct R3QueryOptions *	options )

Ray-cast wheel contacts and apply vehicle forces for dt seconds.

Does not step the world. NULL options use the default filter. The chassis colliders are always excluded, in addition to the filter's own exclusions. The options' predicate is called once per collider of the world before the update, while the world is locked for writing: it may only use Read* functions.

r3DynamicRayCastVehicleController_Wheels()

size_t r3DynamicRayCastVehicleController_Wheels	(	const struct R3DynamicRayCastVehicleController *	controller,
		struct R3WheelState *	buffer,
		size_t	capacity )

Copy current wheel state in wheel insertion order.

See also

Arrays and output buffers

r3FreeDynamicRayCastVehicleController()

R3Status r3FreeDynamicRayCastVehicleController

(

struct R3DynamicRayCastVehicleController *

controller

)

Release an owned dynamic ray cast vehicle controller.

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

r3FreeKinematicCharacterController()

R3Status r3FreeKinematicCharacterController

(

struct R3KinematicCharacterController *

controller

)

Release an owned kinematic character controller.

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

r3FreePidController()

R3Status r3FreePidController

(

struct R3PidController *

controller

)

Release an owned pid controller.

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

r3KinematicCharacterController_Autostep()

struct R3CharacterAutostep r3KinematicCharacterController_Autostep

(

const struct R3KinematicCharacterController *

controller

)

Return the automatic stepping settings.

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

r3KinematicCharacterController_Collisions()

size_t r3KinematicCharacterController_Collisions	(	const struct R3KinematicCharacterController *	controller,
		struct R3CharacterCollision *	buffer,
		size_t	capacity )

Copy collisions recorded by the most recent MoveShape call.

See also

Arrays and output buffers

r3KinematicCharacterController_MoveShape()

struct R3CharacterMovement r3KinematicCharacterController_MoveShape	(	const struct R3World *	world,
		const struct R3QueryOptions *	options,
		struct R3KinematicCharacterController *	controller,
		R3Real	dt,
		const R3SharedShape *	shape,
		struct R3Pose	pose,
		struct R3Vector	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.

r3KinematicCharacterController_NormalNudgeFactor()

R3Real r3KinematicCharacterController_NormalNudgeFactor

(

const struct R3KinematicCharacterController *

controller

)

Return the normal nudge factor set by SetNormalNudgeFactor.

r3KinematicCharacterController_Offset()

struct R3CharacterLength r3KinematicCharacterController_Offset

(

const struct R3KinematicCharacterController *

controller

)

Return the collision separation margin.

r3KinematicCharacterController_SetAutostep()

R3Status r3KinematicCharacterController_SetAutostep	(	struct R3KinematicCharacterController *	controller,
		R3Bool	enabled,
		struct R3CharacterLength	max_height,
		struct R3CharacterLength	min_width,
		R3Bool	include_dynamic_bodies )

Configure automatic stepping over obstacles.

enabled = 0 disables it.

r3KinematicCharacterController_SetNormalNudgeFactor()

R3Status r3KinematicCharacterController_SetNormalNudgeFactor	(	struct R3KinematicCharacterController *	controller,
		R3Real	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.

r3KinematicCharacterController_SetOffset()

R3Status r3KinematicCharacterController_SetOffset	(	struct R3KinematicCharacterController *	controller,
		struct R3CharacterLength	offset )

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

r3KinematicCharacterController_SetSlide()

R3Status r3KinematicCharacterController_SetSlide	(	struct R3KinematicCharacterController *	controller,
		R3Bool	enabled )

Enable or disable sliding along obstacles.

r3KinematicCharacterController_SetSlopes()

R3Status r3KinematicCharacterController_SetSlopes	(	struct R3KinematicCharacterController *	controller,
		R3Real	max_climb_angle,
		R3Real	min_slide_angle )

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

r3KinematicCharacterController_SetSnapToGround()

R3Status r3KinematicCharacterController_SetSnapToGround	(	struct R3KinematicCharacterController *	controller,
		R3Bool	enabled,
		struct R3CharacterLength	distance )

Configure downward ground snapping.

enabled = 0 disables it.

r3KinematicCharacterController_Settings()

struct R3CharacterControllerSettings r3KinematicCharacterController_Settings

(

const struct R3KinematicCharacterController *

controller

)

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

r3KinematicCharacterController_SetUp()

R3Status r3KinematicCharacterController_SetUp	(	struct R3KinematicCharacterController *	controller,
		struct R3Vector	up )

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

r3KinematicCharacterController_SolveCharacterCollisionImpulses()

R3Status r3KinematicCharacterController_SolveCharacterCollisionImpulses	(	const struct R3KinematicCharacterController *	controller,
		const R3SharedShape *	shape,
		R3Real	dt,
		R3Real	mass,
		const struct R3QueryOptions *	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.

r3KinematicCharacterController_Up()

struct R3Vector r3KinematicCharacterController_Up

(

const struct R3KinematicCharacterController *

controller

)

Return the normalized up direction.

r3NewDynamicRayCastVehicleController()

struct R3DynamicRayCastVehicleController * r3NewDynamicRayCastVehicleController

(

struct R3RigidBodyHandle

chassis

)

Allocate a vehicle controller bound to its chassis body.

The chassis world must outlive the controller. Release with r3FreeDynamicRayCastVehicleController.

r3NewKinematicCharacterController()

struct R3KinematicCharacterController * r3NewKinematicCharacterController

(

void

)

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

r3NewPidController()

struct R3PidController * r3NewPidController

(

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 r3FreePidController.

r3PdController_RigidBodyCorrection()

struct R3VelocityCorrection r3PdController_RigidBodyCorrection	(	const struct R3PdController *	controller,
		struct R3RigidBodyHandle	body,
		struct R3Pose	target_pose,
		struct R3Vector	target_linvel,
		R3AngVector	target_angvel )

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

Neither the body nor the controller is modified.

r3PidController_Axes()

uint32_t r3PidController_Axes

(

const struct R3PidController *

controller

)

Return the controlled axes as R3_AXES_MASK_* bits.

r3PidController_Gains()

struct R3PidGains r3PidController_Gains

(

const struct R3PidController *

controller

)

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

r3PidController_ResetIntegrals()

R3Status r3PidController_ResetIntegrals

(

struct R3PidController *

controller

)

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

r3PidController_RigidBodyCorrection()

struct R3VelocityCorrection r3PidController_RigidBodyCorrection	(	struct R3PidController *	controller,
		R3Real	dt,
		struct R3RigidBodyHandle	body,
		struct R3Pose	target_pose,
		struct R3Vector	target_linvel,
		R3AngVector	target_angvel )

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

r3PidController_SetAxes()

R3Status r3PidController_SetAxes	(	struct R3PidController *	controller,
		uint32_t	axes )

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

Gains are unchanged; unknown bits are rejected.

r3PidController_SetGains()

R3Status r3PidController_SetGains	(	struct R3PidController *	controller,
		struct R3PidGains	gains )

Replace the proportional, integral, and derivative gains.