Unified physics scene manager for rigid bodies, assemblies, ball simulators, and global forces. More...

#include <physics_world.hpp>

Classes
struct	MaterialInteraction
	Material-pair contact interaction override entry. More...

Public Member Functions
	PhysicsWorld (const PhysicsConfig &config=PhysicsConfig())
	Constructs a world with an initial configuration snapshot.
RigidBody &	createBody (double mass_kg)
	Creates and registers a dynamic rigid body.
RigidAssembly &	createAssembly ()
	Creates and registers a rigid assembly container.
EnvironmentalBoundary &	addBoundary ()
	Adds a new environmental boundary primitive.
std::vector< EnvironmentalBoundary > &	boundaries ()
	Mutable access to boundary storage.
const std::vector< EnvironmentalBoundary > &	boundaries () const
	Immutable access to boundary storage.
void	addGlobalForceGenerator (const std::shared_ptr< ForceGenerator > &generator)
	Registers a world-level force generator.
void	setMaterialInteraction (const MaterialInteraction &interaction)
	Registers or updates one material interaction override row.
void	clearMaterialInteractions ()
	Clears all material interaction override rows.
std::vector< RigidBody > &	bodies ()
	Mutable access to all rigid bodies currently registered in the world.
const std::vector< RigidBody > &	bodies () const
	Immutable access to all rigid bodies currently registered in the world.
std::vector< RigidAssembly > &	assemblies ()
	Mutable access to all rigid assemblies currently registered in the world.
const std::vector< RigidAssembly > &	assemblies () const
	Immutable access to all rigid assemblies currently registered in the world.
Gamepiece &	createGamepiece (const Gamepiece::Config &config=Gamepiece::Config(), const Gamepiece::Properties &properties=Gamepiece::Properties())
	Creates and registers a generic gamepiece.
BallPhysicsSim3D &	createBall (const Gamepiece::Config &config=Gamepiece::Config(), const Gamepiece::Properties &properties=Gamepiece::Properties())
	Backwards-compatible helper that creates a ball simulator.
std::vector< Gamepiece > &	gamepieces ()
	Mutable access to all registered gamepieces.
const std::vector< Gamepiece > &	gamepieces () const
	Immutable access to all registered gamepieces.
std::vector< Gamepiece > &	balls ()
	Backwards-compatible accessor name for registered balls (gamepieces).
const std::vector< Gamepiece > &	balls () const
	Backwards-compatible const accessor for registered balls (gamepieces).
void	step ()
	Advances simulation by exactly one fixed timestep.
std::size_t	stepCount () const
	Number of completed fixed-timestep iterations since construction/reset.
double	accumulatedSimTimeS () const
	Total accumulated simulation time in seconds.
PhysicsConfig &	config ()
	Mutable access to world configuration.
const PhysicsConfig &	config () const
	Read-only access to world configuration.
void	setGravity (double gx_mps2, double gy_mps2, double gz_mps2)
	Sets world gravity acceleration from scalar components.
void	gravity (double gx_mps2, double gy_mps2, double *gz_mps2) const
	Reads world gravity acceleration into optional scalar outputs.

Detailed Description

Unified physics scene manager for rigid bodies, assemblies, ball simulators, and global forces.

PhysicsWorld is the central orchestration object for the native simulation runtime. It owns all registered entities and advances them in lock-step using a fixed timestep from PhysicsConfig.

High-level responsibilities:

Manage entity lifetimes (bodies, assemblies, ball simulators, boundaries).
Apply global and per-body force models.
Resolve boundary contacts with configurable restitution and friction.
Apply optional aerodynamic drag and Magnus lift.
Enforce broad interaction filtering via layer/mask bitsets.
Provide material-pair interaction overrides for contact coefficients.

Determinism and ordering:

Simulation order is stable with respect to insertion order of entities.
Calling code should avoid mutating world topology while stepping.
Consistent inputs and step counts produce consistent outputs on the same build.

Constructor & Destructor Documentation

◆ PhysicsWorld()

frcsim::PhysicsWorld::PhysicsWorld ( const PhysicsConfig & config = PhysicsConfig() )

inlineexplicit

Constructs a world with an initial configuration snapshot.

Parameters

config Initial world settings copied into internal storage.

Member Function Documentation

◆ accumulatedSimTimeS()

double frcsim::PhysicsWorld::accumulatedSimTimeS ( ) const

inline

Total accumulated simulation time in seconds.

◆ addBoundary()

EnvironmentalBoundary & frcsim::PhysicsWorld::addBoundary ( )

Adds a new environmental boundary primitive.

Returns: Reference to the appended boundary.

Callers can then configure geometry, behavior, material id, and collision filters directly through the returned reference.

◆ addGlobalForceGenerator()

void frcsim::PhysicsWorld::addGlobalForceGenerator ( const std::shared_ptr< ForceGenerator > & generator )

Registers a world-level force generator.

Parameters

generator Shared pointer to a force generator implementation.

Force generators are evaluated during step and can apply additional forces to bodies independent of per-body material settings.

◆ assemblies() [1/2]

std::vector< RigidAssembly > & frcsim::PhysicsWorld::assemblies ( )

inline

Mutable access to all rigid assemblies currently registered in the world.

◆ assemblies() [2/2]

const std::vector< RigidAssembly > & frcsim::PhysicsWorld::assemblies ( ) const

inline

Immutable access to all rigid assemblies currently registered in the world.

◆ balls() [1/2]

std::vector< Gamepiece > & frcsim::PhysicsWorld::balls ( )

inline

Backwards-compatible accessor name for registered balls (gamepieces).

◆ balls() [2/2]

const std::vector< Gamepiece > & frcsim::PhysicsWorld::balls ( ) const

inline

Backwards-compatible const accessor for registered balls (gamepieces).

◆ bodies() [1/2]

std::vector< RigidBody > & frcsim::PhysicsWorld::bodies ( )

inline

Mutable access to all rigid bodies currently registered in the world.

◆ bodies() [2/2]

const std::vector< RigidBody > & frcsim::PhysicsWorld::bodies ( ) const

inline

Immutable access to all rigid bodies currently registered in the world.

◆ boundaries() [1/2]

std::vector< EnvironmentalBoundary > & frcsim::PhysicsWorld::boundaries ( )

inline

Mutable access to boundary storage.

Returns: Reference to the internal boundary vector.

Warning: Mutating the container while stepping is undefined at the API level.

◆ boundaries() [2/2]

const std::vector< EnvironmentalBoundary > & frcsim::PhysicsWorld::boundaries ( ) const

inline

Immutable access to boundary storage.

Returns: Const reference to the internal boundary vector.

◆ clearMaterialInteractions()

void frcsim::PhysicsWorld::clearMaterialInteractions ( )

Clears all material interaction override rows.

After calling this, contact response falls back to default body/boundary material coefficients.

◆ config() [1/2]

PhysicsConfig & frcsim::PhysicsWorld::config ( )

inline

Mutable access to world configuration.

Returns: Reference to internal config object used by future steps.

◆ config() [2/2]

const PhysicsConfig & frcsim::PhysicsWorld::config ( ) const

inline

Read-only access to world configuration.

Returns: Const reference to internal config object.

◆ createAssembly()

RigidAssembly & frcsim::PhysicsWorld::createAssembly ( )

Creates and registers a rigid assembly container.

Returns: Reference to the newly added assembly owned by this world.

◆ createBall()

BallPhysicsSim3D & frcsim::PhysicsWorld::createBall	(	const Gamepiece::Config &	config = Gamepiece::Config(),
		const Gamepiece::Properties &	properties = Gamepiece::Properties() )

Backwards-compatible helper that creates a ball simulator.

Internally this delegates to createGamepiece and returns a reference to the underlying BallPhysicsSim3D base so existing callers continue to function.

◆ createBody()

RigidBody & frcsim::PhysicsWorld::createBody ( double mass_kg )

Creates and registers a dynamic rigid body.

Parameters

mass_kg Body mass in kilograms. Non-positive values are sanitized by RigidBody.

Returns: Reference to the newly added body owned by this world.

◆ createGamepiece()

Gamepiece & frcsim::PhysicsWorld::createGamepiece	(	const Gamepiece::Config &	config = Gamepiece::Config(),
		const Gamepiece::Properties &	properties = Gamepiece::Properties() )

Creates and registers a generic gamepiece.

Parameters

config	Environment and behavior configuration for the gamepiece when it uses spherical hitboxes. Future hitbox types may be added.
properties	Physical properties for the simulated gamepiece.

Returns: Reference to the newly added gamepiece.

◆ gamepieces() [1/2]

std::vector< Gamepiece > & frcsim::PhysicsWorld::gamepieces ( )

inline

Mutable access to all registered gamepieces.

◆ gamepieces() [2/2]

const std::vector< Gamepiece > & frcsim::PhysicsWorld::gamepieces ( ) const

inline

Immutable access to all registered gamepieces.

◆ gravity()

void frcsim::PhysicsWorld::gravity	(	double *	gx_mps2,
		double *	gy_mps2,
		double *	gz_mps2 ) const

inline

Reads world gravity acceleration into optional scalar outputs.

Parameters

gx_mps2	Optional output pointer for gravity x in m/s^2.
gy_mps2	Optional output pointer for gravity y in m/s^2.
gz_mps2	Optional output pointer for gravity z in m/s^2.

Any pointer may be null, allowing callers to request only selected axes.

◆ setGravity()

void frcsim::PhysicsWorld::setGravity	(	double	gx_mps2,
		double	gy_mps2,
		double	gz_mps2 )

inline

Sets world gravity acceleration from scalar components.

Parameters

gx_mps2	Gravity x component in meters per second squared.
gy_mps2	Gravity y component in meters per second squared.
gz_mps2	Gravity z component in meters per second squared.

Calling this method also enables gravity in PhysicsConfig, making the new vector effective for subsequent step calls.

◆ setMaterialInteraction()

void frcsim::PhysicsWorld::setMaterialInteraction ( const MaterialInteraction & interaction )

Registers or updates one material interaction override row.

Parameters

interaction Interaction record to insert or replace.

◆ step()

void frcsim::PhysicsWorld::step ( )

Advances simulation by exactly one fixed timestep.

The step procedure applies configured forces, integrates rigid-body states, resolves supported contact responses, updates assemblies, and advances all ball simulators. Internal counters for step count and simulated time are incremented after successful completion.

◆ stepCount()

std::size_t frcsim::PhysicsWorld::stepCount ( ) const

inline

Number of completed fixed-timestep iterations since construction/reset.

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

src/main/driver/include/frcsim/physics_world.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PhysicsWorld()

Member Function Documentation

◆ accumulatedSimTimeS()

◆ addBoundary()

◆ addGlobalForceGenerator()

◆ assemblies() [1/2]

◆ assemblies() [2/2]

◆ balls() [1/2]

◆ balls() [2/2]

◆ bodies() [1/2]

◆ bodies() [2/2]

◆ boundaries() [1/2]

◆ boundaries() [2/2]

◆ clearMaterialInteractions()

◆ config() [1/2]

◆ config() [2/2]

◆ createAssembly()

◆ createBall()

◆ createBody()

◆ createGamepiece()

◆ gamepieces() [1/2]

◆ gamepieces() [2/2]

◆ gravity()

◆ setGravity()

◆ setMaterialInteraction()

◆ step()

◆ stepCount()