Rigid-body simulation state attached to a Node. More...

#include <a3d/physics/PhysicsBody.h>

Public Types
enum class	Type : uint8_t { Static , Dynamic , Kinematic }
	Determines how a rigid body participates in simulation. More...

enum class	CenterOfMassCalculation : uint8_t { BoundsCenter }
	Selects the method used to automatically determine a dynamic body's center of mass. More...

Public Member Functions
	PhysicsBody (Type type)
	Creates a shape-less body of `type`. More...

	PhysicsBody (Type type, const std::shared_ptr< PhysicsShape > &shape)
	Creates a body of `type` using `shape`. More...

Type	type () const
	Returns the body type. More...

void	type (Type type)
	Validates the requested body type. More...

const std::shared_ptr< PhysicsShape > &	shape () const
	Returns the collision shape retained by this body, or nullptr if no shape is assigned. More...

void	shape (const std::shared_ptr< PhysicsShape > &shape)
	Replaces the collision shape retained by this body; nullptr removes it. More...

float	mass () const
	Returns the body mass. More...

void	mass (float mass)
	Sets the mass of a dynamic body. More...

math::vec3	momentOfInertia () const
	Returns the body's local principal-axis moment of inertia. More...

void	momentOfInertia (const math::vec3 &moment)
	Sets the local principal-axis moment of inertia when automatic calculation is disabled. More...

math::vec3	centerOfMass () const
	Returns the center-of-mass offset from the owning node's origin in local coordinates. More...

void	centerOfMass (const math::vec3 &offset)
	Sets a dynamic body's local center-of-mass offset and disables automatic calculation. More...

float	friction () const
	Returns the sliding-friction coefficient. More...

void	friction (float friction)
	Sets the sliding-friction coefficient. More...

float	rollingFriction () const
	Returns the rolling-friction coefficient. More...

void	rollingFriction (float friction)
	Sets the rolling-friction coefficient. More...

float	spinningFriction () const
	Returns the spinning-friction coefficient. More...

void	spinningFriction (float friction)
	Sets the spinning-friction coefficient. More...

float	restitution () const
	Returns the collision restitution coefficient. More...

void	restitution (float restitution)
	Sets the collision restitution coefficient. More...

math::vec3	linearVelocity () const
	Returns the body linear velocity in world coordinates. More...

void	linearVelocity (const math::vec3 &velocity)
	Sets the body linear velocity in world coordinates. More...

math::vec3	angularVelocity () const
	Returns the body angular velocity in radians per second. More...

void	angularVelocity (const math::vec3 &velocity)
	Sets the body angular velocity in radians per second. More...

math::vec3	linearFactor () const
	Returns the per-axis factor applied to linear motion. More...

void	linearFactor (const math::vec3 &factor)
	Sets the per-axis factor applied to linear motion. More...

math::vec3	angularFactor () const
	Returns the per-axis factor applied to angular motion. More...

void	angularFactor (const math::vec3 &factor)
	Sets the per-axis factor applied to angular motion. More...

float	linearDamping () const
	Returns the linear damping coefficient. More...

void	linearDamping (float damping)
	Sets the linear damping coefficient. More...

float	angularDamping () const
	Returns the angular damping coefficient. More...

void	angularDamping (float damping)
	Sets the angular damping coefficient. More...

float	linearSleepingThreshold () const
	Returns the linear-speed threshold used when deciding whether the body may rest. More...

void	linearSleepingThreshold (float threshold)
	Sets the linear-speed threshold used when deciding whether the body may rest. More...

float	angularSleepingThreshold () const
	Returns the angular-speed threshold used when deciding whether the body may rest. More...

void	angularSleepingThreshold (float threshold)
	Sets the angular-speed threshold used when deciding whether the body may rest. More...

void	applyForce (const math::vec3 &force, bool impulse)
	Applies a central force or impulse to a dynamic body. More...

void	applyForce (const math::vec3 &force, const math::vec3 &location, bool impulse)
	Applies a force or impulse at a world-space position on a dynamic body. More...

void	applyTorque (const math::vec3 &torque, bool impulse)
	Applies torque or a torque impulse to a dynamic body. More...

math::vec3	totalForce () const
	Returns the accumulated force for the current simulation step. More...

math::vec3	totalTorque () const
	Returns the accumulated torque for the current simulation step. More...

void	clearForces ()
	Clears accumulated forces and torques without changing the body's velocities. More...

void	ccdEnabled (bool enabled)
	Enables or disables continuous collision detection for this body. More...

bool	ccdEnabled () const
	Returns whether continuous collision detection is enabled. More...

void	ccdMotionThreshold (float distance)
	Sets the motion-distance threshold used by continuous collision detection; negative values become zero. More...

float	ccdMotionThreshold () const
	Returns the configured continuous-collision motion threshold. More...

void	ccdSweptSphereRadius (float radius)
	Sets the swept-sphere radius used by continuous collision detection; negative values become zero. More...

float	ccdSweptSphereRadius () const
	Returns the configured continuous-collision swept-sphere radius. More...

bool	affectedByGravity () const
	Returns whether this body is affected by its PhysicsWorld gravity. More...

void	affectedByGravity (bool affectedByGravity)
	Sets whether this body is affected by its PhysicsWorld gravity. More...

bool	allowsResting () const
	Returns whether the body is allowed to enter the resting state automatically. More...

void	allowsResting (bool allowsResting)
	Sets whether the body may enter the resting state automatically. More...

bool	resting () const
	Returns whether the body is currently resting. More...

void	resting (bool resting)
	Forces the body into or out of the resting state. More...

bool	autocalculatesCenterOfMass () const
	Returns whether the center of mass is calculated automatically. More...

void	autocalculatesCenterOfMass (bool autocalculate)
	Enables or disables automatic center-of-mass calculation. More...

CenterOfMassCalculation	centerOfMassCalculation () const
	Returns the method used for automatic center-of-mass calculation. More...

void	centerOfMassCalculation (CenterOfMassCalculation calculation)
	Sets the method used for automatic center-of-mass calculation. More...

bool	autocalculatesMomentOfInertia () const
	Returns whether the moment of inertia is calculated automatically from mass and collision shape. More...

void	autocalculatesMomentOfInertia (bool autocalculate)
	Enables or disables automatic moment-of-inertia calculation. More...

Static Public Member Functions
static std::unique_ptr< PhysicsBody >	StaticBody ()
	Creates a shape-less static body. More...

static std::unique_ptr< PhysicsBody >	StaticBody (const std::shared_ptr< PhysicsShape > &shape)
	Creates a static body using `shape`. More...

static std::unique_ptr< PhysicsBody >	DynamicBody ()
	Creates a shape-less dynamic body. More...

static std::unique_ptr< PhysicsBody >	DynamicBody (const std::shared_ptr< PhysicsShape > &shape)
	Creates a dynamic body using `shape`. More...

static std::unique_ptr< PhysicsBody >	KinematicBody ()
	Creates a shape-less kinematic body. More...

static std::unique_ptr< PhysicsBody >	KinematicBody (const std::shared_ptr< PhysicsShape > &shape)
	Creates a kinematic body using `shape`. More...

Detailed Description

Rigid-body simulation state attached to a Node.

A Node owns its PhysicsBody, while the body retains its PhysicsShape with shared ownership so a shape may be reused by multiple bodies. Dynamic bodies are driven by simulation, kinematic bodies are moved explicitly through their Node transform, and static bodies represent fixed collision geometry.

When a body without an explicit shape is attached to a Node, A3D attempts to derive a suitable collision shape from the node's mesh or hierarchy. Automatically derived shapes are rebuilt when the owning Node's Mesh changes; explicitly assigned shapes are left unchanged.

Definition at line 39 of file PhysicsBody.h.

Member Enumeration Documentation

◆ CenterOfMassCalculation

enum class a3d::PhysicsBody::CenterOfMassCalculation : uint8_t

strong

Selects the method used to automatically determine a dynamic body's center of mass.

Enumerator
BoundsCenter	Uses the center of the collision shape's local bounds.

Definition at line 52 of file PhysicsBody.h.

◆ Type

enum class a3d::PhysicsBody::Type : uint8_t

strong

Determines how a rigid body participates in simulation.

Enumerator
Static	Fixed collision body that does not respond dynamically to forces.
Dynamic	Simulation-driven body affected by forces, gravity, and collisions.
Kinematic	Explicitly moved body that participates in collisions without dynamic motion.

Definition at line 45 of file PhysicsBody.h.

Constructor & Destructor Documentation

◆ PhysicsBody() [1/2]

a3d::PhysicsBody::PhysicsBody ( Type type )

explicit

Creates a shape-less body of type.

◆ PhysicsBody() [2/2]

a3d::PhysicsBody::PhysicsBody	(	Type	type,
		const std::shared_ptr< PhysicsShape > &	shape
	)

Creates a body of type using shape.

Exceptions

std::logic_error	if `shape` is incompatible with `type`, or if collision geometry must be created and its source has expired or cannot produce a valid collision shape.
std::invalid_argument	if `shape` is derived from a Mesh with no elements.

Member Function Documentation

◆ affectedByGravity() [1/2]

bool a3d::PhysicsBody::affectedByGravity ( ) const

Returns whether this body is affected by its PhysicsWorld gravity.

◆ affectedByGravity() [2/2]

void a3d::PhysicsBody::affectedByGravity ( bool affectedByGravity )

Sets whether this body is affected by its PhysicsWorld gravity.

◆ allowsResting() [1/2]

bool a3d::PhysicsBody::allowsResting ( ) const

Returns whether the body is allowed to enter the resting state automatically.

◆ allowsResting() [2/2]

void a3d::PhysicsBody::allowsResting ( bool allowsResting )

Sets whether the body may enter the resting state automatically.

Kinematic bodies cannot enable resting.

Exceptions

std::logic_error if allowsResting is true for a kinematic body.

◆ angularDamping() [1/2]

float a3d::PhysicsBody::angularDamping ( ) const

Returns the angular damping coefficient.

◆ angularDamping() [2/2]

void a3d::PhysicsBody::angularDamping ( float damping )

Sets the angular damping coefficient.

◆ angularFactor() [1/2]

math::vec3 a3d::PhysicsBody::angularFactor ( ) const

Returns the per-axis factor applied to angular motion.

◆ angularFactor() [2/2]

void a3d::PhysicsBody::angularFactor ( const math::vec3 & factor )

Sets the per-axis factor applied to angular motion.

◆ angularSleepingThreshold() [1/2]

float a3d::PhysicsBody::angularSleepingThreshold ( ) const

Returns the angular-speed threshold used when deciding whether the body may rest.

◆ angularSleepingThreshold() [2/2]

void a3d::PhysicsBody::angularSleepingThreshold ( float threshold )

Sets the angular-speed threshold used when deciding whether the body may rest.

◆ angularVelocity() [1/2]

math::vec3 a3d::PhysicsBody::angularVelocity ( ) const

Returns the body angular velocity in radians per second.

◆ angularVelocity() [2/2]

void a3d::PhysicsBody::angularVelocity ( const math::vec3 & velocity )

Sets the body angular velocity in radians per second.

◆ applyForce() [1/2]

void a3d::PhysicsBody::applyForce	(	const math::vec3 &	force,
		bool	impulse
	)

Applies a central force or impulse to a dynamic body.

Parameters

force	world-space force vector, or impulse vector when `impulse` is true.
impulse	when true, applies `force` as an instantaneous impulse instead of a continuous force.

Exceptions

std::logic_error if the body is not dynamic.

◆ applyForce() [2/2]

void a3d::PhysicsBody::applyForce	(	const math::vec3 &	force,
		const math::vec3 &	location,
		bool	impulse
	)

Applies a force or impulse at a world-space position on a dynamic body.

Parameters

force	world-space force vector, or impulse vector when `impulse` is true.
location	world-space application position.
impulse	when true, applies `force` as an instantaneous impulse instead of a continuous force.

Exceptions

std::logic_error if the body is not dynamic.

◆ applyTorque()

void a3d::PhysicsBody::applyTorque	(	const math::vec3 &	torque,
		bool	impulse
	)

Applies torque or a torque impulse to a dynamic body.

Parameters

torque	torque vector, or angular impulse when `impulse` is true.
impulse	when true, applies `torque` as an instantaneous angular impulse.

Exceptions

std::logic_error if the body is not dynamic.

◆ autocalculatesCenterOfMass() [1/2]

bool a3d::PhysicsBody::autocalculatesCenterOfMass ( ) const

Returns whether the center of mass is calculated automatically.

◆ autocalculatesCenterOfMass() [2/2]

void a3d::PhysicsBody::autocalculatesCenterOfMass ( bool autocalculate )

Enables or disables automatic center-of-mass calculation.

Enabling recomputes the center of mass. Disabling preserves the current offset for subsequent manual adjustment.

Exceptions

std::logic_error if automatic calculation is enabled for a non-dynamic body.

◆ autocalculatesMomentOfInertia() [1/2]

bool a3d::PhysicsBody::autocalculatesMomentOfInertia ( ) const

Returns whether the moment of inertia is calculated automatically from mass and collision shape.

◆ autocalculatesMomentOfInertia() [2/2]

void a3d::PhysicsBody::autocalculatesMomentOfInertia ( bool autocalculate )

Enables or disables automatic moment-of-inertia calculation.

◆ ccdEnabled() [1/2]

bool a3d::PhysicsBody::ccdEnabled ( ) const

Returns whether continuous collision detection is enabled.

◆ ccdEnabled() [2/2]

void a3d::PhysicsBody::ccdEnabled ( bool enabled )

Enables or disables continuous collision detection for this body.

◆ ccdMotionThreshold() [1/2]

float a3d::PhysicsBody::ccdMotionThreshold ( ) const

Returns the configured continuous-collision motion threshold.

◆ ccdMotionThreshold() [2/2]

void a3d::PhysicsBody::ccdMotionThreshold ( float distance )

Sets the motion-distance threshold used by continuous collision detection; negative values become zero.

◆ ccdSweptSphereRadius() [1/2]

float a3d::PhysicsBody::ccdSweptSphereRadius ( ) const

Returns the configured continuous-collision swept-sphere radius.

◆ ccdSweptSphereRadius() [2/2]

void a3d::PhysicsBody::ccdSweptSphereRadius ( float radius )

Sets the swept-sphere radius used by continuous collision detection; negative values become zero.

◆ centerOfMass() [1/2]

math::vec3 a3d::PhysicsBody::centerOfMass ( ) const

Returns the center-of-mass offset from the owning node's origin in local coordinates.

◆ centerOfMass() [2/2]

void a3d::PhysicsBody::centerOfMass ( const math::vec3 & offset )

Sets a dynamic body's local center-of-mass offset and disables automatic calculation.

Exceptions

std::logic_error if the body is not dynamic.

◆ centerOfMassCalculation() [1/2]

CenterOfMassCalculation a3d::PhysicsBody::centerOfMassCalculation ( ) const

Returns the method used for automatic center-of-mass calculation.

◆ centerOfMassCalculation() [2/2]

void a3d::PhysicsBody::centerOfMassCalculation ( CenterOfMassCalculation calculation )

Sets the method used for automatic center-of-mass calculation.

If automatic calculation is enabled, the center of mass is recomputed.

Exceptions

std::logic_error if the body is not dynamic.

◆ clearForces()

void a3d::PhysicsBody::clearForces ( )

Clears accumulated forces and torques without changing the body's velocities.

◆ DynamicBody() [1/2]

static std::unique_ptr< PhysicsBody > a3d::PhysicsBody::DynamicBody ( )

static

Creates a shape-less dynamic body.

◆ DynamicBody() [2/2]

static std::unique_ptr< PhysicsBody > a3d::PhysicsBody::DynamicBody ( const std::shared_ptr< PhysicsShape > & shape )

static

Creates a dynamic body using shape.

Exceptions

std::logic_error	if `shape` is incompatible with a dynamic body, or if collision geometry must be created and its source has expired or cannot produce a valid collision shape.
std::invalid_argument	if `shape` is derived from a Mesh with no elements.

◆ friction() [1/2]

float a3d::PhysicsBody::friction ( ) const

Returns the sliding-friction coefficient.

◆ friction() [2/2]

void a3d::PhysicsBody::friction ( float friction )

Sets the sliding-friction coefficient.

◆ KinematicBody() [1/2]

static std::unique_ptr< PhysicsBody > a3d::PhysicsBody::KinematicBody ( )

static

Creates a shape-less kinematic body.

◆ KinematicBody() [2/2]

static std::unique_ptr< PhysicsBody > a3d::PhysicsBody::KinematicBody ( const std::shared_ptr< PhysicsShape > & shape )

static

Creates a kinematic body using shape.

Exceptions

std::logic_error	if `shape` is incompatible with a kinematic body, or if collision geometry must be created and its source has expired or cannot produce a valid collision shape.
std::invalid_argument	if `shape` is derived from a Mesh with no elements.

◆ linearDamping() [1/2]

float a3d::PhysicsBody::linearDamping ( ) const

Returns the linear damping coefficient.

◆ linearDamping() [2/2]

void a3d::PhysicsBody::linearDamping ( float damping )

Sets the linear damping coefficient.

◆ linearFactor() [1/2]

math::vec3 a3d::PhysicsBody::linearFactor ( ) const

Returns the per-axis factor applied to linear motion.

◆ linearFactor() [2/2]

void a3d::PhysicsBody::linearFactor ( const math::vec3 & factor )

Sets the per-axis factor applied to linear motion.

◆ linearSleepingThreshold() [1/2]

float a3d::PhysicsBody::linearSleepingThreshold ( ) const

Returns the linear-speed threshold used when deciding whether the body may rest.

◆ linearSleepingThreshold() [2/2]

void a3d::PhysicsBody::linearSleepingThreshold ( float threshold )

Sets the linear-speed threshold used when deciding whether the body may rest.

◆ linearVelocity() [1/2]

math::vec3 a3d::PhysicsBody::linearVelocity ( ) const

Returns the body linear velocity in world coordinates.

◆ linearVelocity() [2/2]

void a3d::PhysicsBody::linearVelocity ( const math::vec3 & velocity )

Sets the body linear velocity in world coordinates.

◆ mass() [1/2]

float a3d::PhysicsBody::mass ( ) const

Returns the body mass.

◆ mass() [2/2]

void a3d::PhysicsBody::mass ( float mass )

Sets the mass of a dynamic body.

Exceptions

std::logic_error	if the body is not dynamic.
std::invalid_argument	if `mass` is less than or equal to zero.

◆ momentOfInertia() [1/2]

math::vec3 a3d::PhysicsBody::momentOfInertia ( ) const

Returns the body's local principal-axis moment of inertia.

◆ momentOfInertia() [2/2]

void a3d::PhysicsBody::momentOfInertia ( const math::vec3 & moment )

Sets the local principal-axis moment of inertia when automatic calculation is disabled.

◆ resting() [1/2]

bool a3d::PhysicsBody::resting ( ) const

Returns whether the body is currently resting.

◆ resting() [2/2]

void a3d::PhysicsBody::resting ( bool resting )

Forces the body into or out of the resting state.

◆ restitution() [1/2]

float a3d::PhysicsBody::restitution ( ) const

Returns the collision restitution coefficient.

◆ restitution() [2/2]

void a3d::PhysicsBody::restitution ( float restitution )

Sets the collision restitution coefficient.

◆ rollingFriction() [1/2]

float a3d::PhysicsBody::rollingFriction ( ) const

Returns the rolling-friction coefficient.

◆ rollingFriction() [2/2]

void a3d::PhysicsBody::rollingFriction ( float friction )

Sets the rolling-friction coefficient.

◆ shape() [1/2]

const std::shared_ptr< PhysicsShape > & a3d::PhysicsBody::shape ( ) const

Returns the collision shape retained by this body, or nullptr if no shape is assigned.

◆ shape() [2/2]

void a3d::PhysicsBody::shape ( const std::shared_ptr< PhysicsShape > & shape )

Replaces the collision shape retained by this body; nullptr removes it.

A non-null shape assigned through this function is treated as explicit and is not automatically replaced when the owning Node's Mesh changes.

Exceptions

std::logic_error	if `shape` does not support this body's type, or if collision geometry must be created and its source has expired or cannot produce a valid collision shape.
std::invalid_argument	if `shape` is derived from a Mesh with no elements.

◆ spinningFriction() [1/2]

float a3d::PhysicsBody::spinningFriction ( ) const

Returns the spinning-friction coefficient.

◆ spinningFriction() [2/2]

void a3d::PhysicsBody::spinningFriction ( float friction )

Sets the spinning-friction coefficient.

◆ StaticBody() [1/2]

static std::unique_ptr< PhysicsBody > a3d::PhysicsBody::StaticBody ( )

static

Creates a shape-less static body.

◆ StaticBody() [2/2]

static std::unique_ptr< PhysicsBody > a3d::PhysicsBody::StaticBody ( const std::shared_ptr< PhysicsShape > & shape )

static

Creates a static body using shape.

Exceptions

std::logic_error	if `shape` is incompatible with a static body, or if collision geometry must be created and its source has expired or cannot produce a valid collision shape.
std::invalid_argument	if `shape` is derived from a Mesh with no elements.

◆ totalForce()

math::vec3 a3d::PhysicsBody::totalForce ( ) const

Returns the accumulated force for the current simulation step.

◆ totalTorque()

math::vec3 a3d::PhysicsBody::totalTorque ( ) const

Returns the accumulated torque for the current simulation step.

◆ type() [1/2]

Type a3d::PhysicsBody::type ( ) const

Returns the body type.

◆ type() [2/2]

void a3d::PhysicsBody::type ( Type type )

Validates the requested body type.

Changing a body's type after construction is not currently supported.

Exceptions

std::logic_error if type differs from the current type.

The documentation for this class was generated from the following file:

a3d/physics/PhysicsBody.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ CenterOfMassCalculation

◆ Type

Constructor & Destructor Documentation

◆ PhysicsBody() [1/2]

◆ PhysicsBody() [2/2]

Member Function Documentation

◆ affectedByGravity() [1/2]

◆ affectedByGravity() [2/2]

◆ allowsResting() [1/2]

◆ allowsResting() [2/2]

◆ angularDamping() [1/2]

◆ angularDamping() [2/2]

◆ angularFactor() [1/2]

◆ angularFactor() [2/2]

◆ angularSleepingThreshold() [1/2]

◆ angularSleepingThreshold() [2/2]

◆ angularVelocity() [1/2]

◆ angularVelocity() [2/2]

◆ applyForce() [1/2]

◆ applyForce() [2/2]

◆ applyTorque()

◆ autocalculatesCenterOfMass() [1/2]

◆ autocalculatesCenterOfMass() [2/2]

◆ autocalculatesMomentOfInertia() [1/2]

◆ autocalculatesMomentOfInertia() [2/2]

◆ ccdEnabled() [1/2]

◆ ccdEnabled() [2/2]

◆ ccdMotionThreshold() [1/2]

◆ ccdMotionThreshold() [2/2]

◆ ccdSweptSphereRadius() [1/2]

◆ ccdSweptSphereRadius() [2/2]

◆ centerOfMass() [1/2]

◆ centerOfMass() [2/2]

◆ centerOfMassCalculation() [1/2]

◆ centerOfMassCalculation() [2/2]

◆ clearForces()

◆ DynamicBody() [1/2]

◆ DynamicBody() [2/2]

◆ friction() [1/2]

◆ friction() [2/2]

◆ KinematicBody() [1/2]

◆ KinematicBody() [2/2]

◆ linearDamping() [1/2]

◆ linearDamping() [2/2]

◆ linearFactor() [1/2]

◆ linearFactor() [2/2]

◆ linearSleepingThreshold() [1/2]

◆ linearSleepingThreshold() [2/2]

◆ linearVelocity() [1/2]

◆ linearVelocity() [2/2]

◆ mass() [1/2]

◆ mass() [2/2]

◆ momentOfInertia() [1/2]

◆ momentOfInertia() [2/2]

◆ resting() [1/2]

◆ resting() [2/2]

◆ restitution() [1/2]

◆ restitution() [2/2]

◆ rollingFriction() [1/2]

◆ rollingFriction() [2/2]

◆ shape() [1/2]

◆ shape() [2/2]

◆ spinningFriction() [1/2]

◆ spinningFriction() [2/2]

◆ StaticBody() [1/2]

◆ StaticBody() [2/2]

◆ totalForce()

◆ totalTorque()

◆ type() [1/2]

◆ type() [2/2]