Resolves robot-ball contact response. projectiles. More...

#include <ball_gamepiece_sim.hpp>

Classes
struct	FieldConfig
	Global field and contact tuning parameters. More...
struct	RobotState
	Per-robot state used by game piece interaction and collision routines. More...
struct	ExitTrajectoryParameters
	Exit trajectory and metadata used when launching a carried ball or a projectile. More...
struct	GamePieceInfo
	Registration record for a named game piece type. More...
struct	ProjectileEntity
	In-flight entity not currently represented by BallPhysicsSim3D. More...
struct	GoalZone
	Goal capture region and validation logic. More...
struct	BallEntity
	Grounded game piece entity with its own ball physics instance. More...

Public Types
enum class	GamePieceType { kBall , kFuel2026 , kCustom1 , kCustom2 , kCustom3 , kCustom4 }
using	FireCommand = ExitTrajectoryParameters
	Backward-compatible alias for older call sites.
using	RobotAddedCallback
	Callback type invoked when a robot is added to this simulator.

Public Member Functions
	BallGamepieceSim ()=default
	Constructs a simulator with default evergreen field bounds and contact tuning.
	BallGamepieceSim (const FieldConfig &field)
	Constructs a simulator with the provided field configuration.
void	setFieldConfig (const FieldConfig &field)
	Replaces field configuration while preserving dynamic simulation entities.
std::size_t	addRobot (const RobotState &robot)
	Adds a robot and returns its index.
void	setRobotAddedCallback (const RobotAddedCallback &callback)
	Sets a callback invoked whenever addRobot inserts a robot.
std::size_t	addBall (const BallPhysicsSim3D::BallState &state, const BallPhysicsSim3D::Config &config, const BallPhysicsSim3D::BallProperties &properties)
	Adds a grounded ball with explicit physics configuration.
std::size_t	addProjectile (const ProjectileEntity &projectile)
	Adds a projectile entity and returns its index.
GoalZone &	addGoalZone (const GoalZone &goal_zone)
	Adds a goal zone and returns a mutable reference to the stored copy.
GamePieceInfo &	registerGamePieceType (const GamePieceInfo &info)
	Registers or replaces a named game piece type.
void	clearGamePieceTypes ()
	Clears all registered game piece type definitions.
EnvironmentalBoundary &	addFieldElement (const EnvironmentalBoundary &boundary)
	Adds a field element and returns a mutable reference to the stored copy.
std::vector< RobotState > &	robots ()
	Mutable robot state list.
const std::vector< RobotState > &	robots () const
	Immutable robot state list.
std::vector< BallEntity > &	balls ()
	Mutable grounded-ball list.
const std::vector< BallEntity > &	balls () const
	Immutable grounded-ball list.
std::vector< BallEntity > &	gamepieces ()
const std::vector< BallEntity > &	gamepieces () const
GamePieceType	gamepieceType (std::size_t idx) const
std::string	gamepieceTypeName (std::size_t idx) const
bool	setGamepieceType (std::size_t idx, GamePieceType t)
bool	setGamepieceType (std::size_t idx, const std::string &n)
bool	removeGamepiece (std::size_t idx)
std::size_t	countGamepieces () const
GamePieceType	ballType (std::size_t ball_index) const
	Returns the registered type for a ball index.
std::string	ballTypeName (std::size_t ball_index) const
	Returns the registered type label for a ball index, or empty string if out of range.
bool	setBallType (std::size_t ball_index, GamePieceType type)
	Updates the type for an existing ball.
bool	setBallType (std::size_t ball_index, const std::string &type_name)
	Backward-compatible setter that accepts a type name.
bool	removeBall (std::size_t ball_index)
	Removes a ball by index and remaps carried-ball indices accordingly.
std::vector< ProjectileEntity > &	projectiles ()
	Mutable projectile list.
const std::vector< ProjectileEntity > &	projectiles () const
	Immutable projectile list.
std::vector< GoalZone > &	goals ()
	Mutable goal-zone list.
const std::vector< GoalZone > &	goals () const
	Immutable goal-zone list.
std::vector< EnvironmentalBoundary > &	fieldElements ()
	Mutable field-element list.
const std::vector< EnvironmentalBoundary > &	fieldElements () const
	Immutable field-element list.
std::size_t	countBalls () const
	Returns total grounded ball count (including scored-in-net balls).
std::size_t	countProjectiles () const
	Returns count of currently active projectiles.
std::size_t	countScoredBalls () const
	Returns count of grounded balls marked as scored in configured net volume(s).
std::size_t	fireProjectile (std::size_t robot_index, const ExitTrajectoryParameters &command, bool spawn_on_ground_after_touch=true, const std::function< void()> &hit_target_callback={})
	Spawns a projectile using robot pose and exit trajectory parameters.
void	step (double dt_s)
	Advances simulation by dt using configured internal substep count.
void	setSimulationSubsteps (int simulation_substeps)
	Sets simulation substeps per external step; values below 1 clamp to 1.
int	simulationSubsteps () const
	Returns current simulation substeps-per-step value.

Static Public Attributes
static constexpr std::size_t	kNoBall = static_cast<std::size_t>(-1)
static constexpr std::size_t	kNoGamepiece = kNoBall

Detailed Description

Resolves robot-ball contact response. projectiles.

Note: Thread-safe via internal std::recursive_mutex. All public methods that access or mutate ball state (position, velocity, etc.) are protected by locks. The step() method performs all simulation updates safely.

Velocity vectors are world-frame meters/second.
Robot yaw is radians about +Z.

Seasonal field/gamepiece presets are intentionally defined outside this class so this simulator remains reusable for custom games and offseason field variants.

Member Typedef Documentation

◆ FireCommand

using frcsim::BallGamepieceSim::FireCommand = ExitTrajectoryParameters

Backward-compatible alias for older call sites.

◆ RobotAddedCallback

using frcsim::BallGamepieceSim::RobotAddedCallback

Initial value:

std::function<void(std::size_t robot_index, const RobotState& robot)>

frcsim::BallGamepieceSim::RobotState

Per-robot state used by game piece interaction and collision routines.

Definition ball_gamepiece_sim.hpp:140

Callback type invoked when a robot is added to this simulator.

Member Enumeration Documentation

◆ GamePieceType

enum class frcsim::BallGamepieceSim::GamePieceType

strong

Built-in gamepiece type identifiers used by launch/projectile/registration APIs.

Enumerator
kBall
kFuel2026
kCustom1
kCustom2
kCustom3
kCustom4

Constructor & Destructor Documentation

◆ BallGamepieceSim() [1/2]

frcsim::BallGamepieceSim::BallGamepieceSim ( )

default

Constructs a simulator with default evergreen field bounds and contact tuning.

◆ BallGamepieceSim() [2/2]

frcsim::BallGamepieceSim::BallGamepieceSim ( const FieldConfig & field )

inlineexplicit

Constructs a simulator with the provided field configuration.

Parameters

field Initial field configuration.

Member Function Documentation

◆ addBall()

std::size_t frcsim::BallGamepieceSim::addBall	(	const BallPhysicsSim3D::BallState &	state,
		const BallPhysicsSim3D::Config &	config,
		const BallPhysicsSim3D::BallProperties &	properties )

inline

Adds a grounded ball with explicit physics configuration.

Parameters

state	Initial grounded ball state.
config	Ball physics configuration.
properties	Ball physical properties.

Returns: Index of the inserted ball entity.

◆ addFieldElement()

EnvironmentalBoundary & frcsim::BallGamepieceSim::addFieldElement ( const EnvironmentalBoundary & boundary )

inline

Adds a field element and returns a mutable reference to the stored copy.

Parameters

boundary Boundary to append.

Returns: Mutable reference to stored boundary.

◆ addGoalZone()

GoalZone & frcsim::BallGamepieceSim::addGoalZone ( const GoalZone & goal_zone )

inline

Adds a goal zone and returns a mutable reference to the stored copy.

Parameters

goal_zone Goal zone definition to append.

Returns: Mutable reference to stored goal zone.

◆ addProjectile()

std::size_t frcsim::BallGamepieceSim::addProjectile ( const ProjectileEntity & projectile )

inline

Adds a projectile entity and returns its index.

Parameters

projectile Projectile to append.

Returns: Inserted projectile index.

◆ addRobot()

std::size_t frcsim::BallGamepieceSim::addRobot ( const RobotState & robot )

inline

Adds a robot and returns its index.

Parameters

robot Robot state to insert.

Returns: Inserted robot index.

◆ balls() [1/2]

std::vector< BallEntity > & frcsim::BallGamepieceSim::balls ( )

inline

Mutable grounded-ball list.

Returns: Mutable ball vector reference.

◆ balls() [2/2]

const std::vector< BallEntity > & frcsim::BallGamepieceSim::balls ( ) const

inline

Immutable grounded-ball list.

Returns: Const ball vector reference.

◆ ballType()

GamePieceType frcsim::BallGamepieceSim::ballType ( std::size_t ball_index ) const

inline

Returns the registered type for a ball index.

Parameters

ball_index Ball index to query.

Returns: Type, or kBall when index is invalid.

◆ ballTypeName()

std::string frcsim::BallGamepieceSim::ballTypeName ( std::size_t ball_index ) const

inline

Returns the registered type label for a ball index, or empty string if out of range.

◆ clearGamePieceTypes()

void frcsim::BallGamepieceSim::clearGamePieceTypes ( )

inline

Clears all registered game piece type definitions.

◆ countBalls()

std::size_t frcsim::BallGamepieceSim::countBalls ( ) const

inline

Returns total grounded ball count (including scored-in-net balls).

Returns: Grounded ball count.

◆ countGamepieces()

std::size_t frcsim::BallGamepieceSim::countGamepieces ( ) const

inline

Returns total grounded gamepiece count.

◆ countProjectiles()

std::size_t frcsim::BallGamepieceSim::countProjectiles ( ) const

inline

Returns count of currently active projectiles.

Returns: Active projectile count.

◆ countScoredBalls()

std::size_t frcsim::BallGamepieceSim::countScoredBalls ( ) const

inline

Returns count of grounded balls marked as scored in configured net volume(s).

Returns: Scored ball count.

◆ fieldElements() [1/2]

std::vector< EnvironmentalBoundary > & frcsim::BallGamepieceSim::fieldElements ( )

inline

Mutable field-element list.

Returns: Mutable boundary vector reference.

◆ fieldElements() [2/2]

const std::vector< EnvironmentalBoundary > & frcsim::BallGamepieceSim::fieldElements ( ) const

inline

Immutable field-element list.

Returns: Const boundary vector reference.

◆ fireProjectile()

std::size_t frcsim::BallGamepieceSim::fireProjectile	(	std::size_t	robot_index,
		const ExitTrajectoryParameters &	command,
		bool	spawn_on_ground_after_touch = true,
		const std::function< void()> &	hit_target_callback = {} )

inline

Spawns a projectile using robot pose and exit trajectory parameters.

Parameters

robot_index	Robot index used as launch source.
command	Launch parameters.
spawn_on_ground_after_touch	If true, touchdown spawns a grounded ball.
hit_target_callback	Callback fired on goal hit.

Returns: Projectile index, or kNoBall when robot index is invalid.

◆ gamepieces() [1/2]

std::vector< BallEntity > & frcsim::BallGamepieceSim::gamepieces ( )

inline

Backwards-compatible gamepiece aliases to aid migration. Mutable gamepiece list.

◆ gamepieces() [2/2]

const std::vector< BallEntity > & frcsim::BallGamepieceSim::gamepieces ( ) const

inline

Immutable gamepiece list.

◆ gamepieceType()

GamePieceType frcsim::BallGamepieceSim::gamepieceType ( std::size_t idx ) const

inline

Returns the registered type for a gamepiece index.

◆ gamepieceTypeName()

std::string frcsim::BallGamepieceSim::gamepieceTypeName ( std::size_t idx ) const

inline

Returns the registered type label for a gamepiece index.

◆ goals() [1/2]

std::vector< GoalZone > & frcsim::BallGamepieceSim::goals ( )

inline

Mutable goal-zone list.

Returns: Mutable goal vector reference.

◆ goals() [2/2]

const std::vector< GoalZone > & frcsim::BallGamepieceSim::goals ( ) const

inline

Immutable goal-zone list.

Returns: Const goal vector reference.

◆ projectiles() [1/2]

std::vector< ProjectileEntity > & frcsim::BallGamepieceSim::projectiles ( )

inline

Mutable projectile list.

Returns: Mutable projectile vector reference.

◆ projectiles() [2/2]

const std::vector< ProjectileEntity > & frcsim::BallGamepieceSim::projectiles ( ) const

inline

Immutable projectile list.

Returns: Const projectile vector reference.

◆ registerGamePieceType()

GamePieceInfo & frcsim::BallGamepieceSim::registerGamePieceType ( const GamePieceInfo & info )

inline

Registers or replaces a named game piece type.

Parameters

info	Type definition to insert or overwrite.

Returns: Mutable reference to stored registration.

◆ removeBall()

bool frcsim::BallGamepieceSim::removeBall ( std::size_t ball_index )

inline

Removes a ball by index and remaps carried-ball indices accordingly.

Parameters

ball_index Ball index to remove.

Returns: true when removal succeeded.

◆ removeGamepiece()

bool frcsim::BallGamepieceSim::removeGamepiece ( std::size_t idx )

inline

Removes a gamepiece by index.

◆ robots() [1/2]

std::vector< RobotState > & frcsim::BallGamepieceSim::robots ( )

inline

Mutable robot state list.

Returns: Mutable robot vector reference.

◆ robots() [2/2]

const std::vector< RobotState > & frcsim::BallGamepieceSim::robots ( ) const

inline

Immutable robot state list.

Returns: Const robot vector reference.

◆ setBallType() [1/2]

bool frcsim::BallGamepieceSim::setBallType	(	std::size_t	ball_index,
		const std::string &	type_name )

inline

Backward-compatible setter that accepts a type name.

Parameters

ball_index	Ball index to modify.
type_name	Type label ("Ball" supported).

Returns: true if parsed and applied.

◆ setBallType() [2/2]

bool frcsim::BallGamepieceSim::setBallType	(	std::size_t	ball_index,
		GamePieceType	type )

inline

Updates the type for an existing ball.

Parameters

ball_index	Ball index to modify.
type	Replacement type.

Returns: true if the ball index was valid and updated.

◆ setFieldConfig()

void frcsim::BallGamepieceSim::setFieldConfig ( const FieldConfig & field )

inline

Replaces field configuration while preserving dynamic simulation entities.

Parameters

field New field configuration.

◆ setGamepieceType() [1/2]

bool frcsim::BallGamepieceSim::setGamepieceType	(	std::size_t	idx,
		const std::string &	n )

inline

Backward-compatible setter that accepts a type name for a gamepiece.

◆ setGamepieceType() [2/2]

bool frcsim::BallGamepieceSim::setGamepieceType	(	std::size_t	idx,
		GamePieceType	t )

inline

Updates the type for an existing gamepiece.

◆ setRobotAddedCallback()

void frcsim::BallGamepieceSim::setRobotAddedCallback ( const RobotAddedCallback & callback )

inline

Sets a callback invoked whenever addRobot inserts a robot.

Parameters

callback Callback invoked after insertion.

◆ setSimulationSubsteps()

void frcsim::BallGamepieceSim::setSimulationSubsteps ( int simulation_substeps )

inline

Sets simulation substeps per external step; values below 1 clamp to 1.

Parameters

simulation_substeps Requested substep count.

◆ simulationSubsteps()

int frcsim::BallGamepieceSim::simulationSubsteps ( ) const

inline

Returns current simulation substeps-per-step value.

Returns: Substep count.

◆ step()

void frcsim::BallGamepieceSim::step ( double dt_s )

inline

Advances simulation by dt using configured internal substep count.

Parameters

dt_s	External timestep in seconds.

Member Data Documentation

◆ kNoBall

std::size_t frcsim::BallGamepieceSim::kNoBall = static_cast<std::size_t>(-1)

staticconstexpr

Sentinel index representing no carried ball.

◆ kNoGamepiece

std::size_t frcsim::BallGamepieceSim::kNoGamepiece = kNoBall

staticconstexpr

Sentinel index representing no carried gamepiece.

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

src/main/driver/include/frcsim/gamepiece/ball_gamepiece_sim.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ FireCommand

◆ RobotAddedCallback

Member Enumeration Documentation

◆ GamePieceType

Constructor & Destructor Documentation

◆ BallGamepieceSim() [1/2]

◆ BallGamepieceSim() [2/2]

Member Function Documentation

◆ addBall()

◆ addFieldElement()

◆ addGoalZone()

◆ addProjectile()

◆ addRobot()

◆ balls() [1/2]

◆ balls() [2/2]

◆ ballType()

◆ ballTypeName()

◆ clearGamePieceTypes()

◆ countBalls()

◆ countGamepieces()

◆ countProjectiles()

◆ countScoredBalls()

◆ fieldElements() [1/2]

◆ fieldElements() [2/2]

◆ fireProjectile()

◆ gamepieces() [1/2]

◆ gamepieces() [2/2]

◆ gamepieceType()

◆ gamepieceTypeName()

◆ goals() [1/2]

◆ goals() [2/2]

◆ projectiles() [1/2]

◆ projectiles() [2/2]

◆ registerGamePieceType()

◆ removeBall()

◆ removeGamepiece()

◆ robots() [1/2]

◆ robots() [2/2]

◆ setBallType() [1/2]

◆ setBallType() [2/2]

◆ setFieldConfig()

◆ setGamepieceType() [1/2]

◆ setGamepieceType() [2/2]

◆ setRobotAddedCallback()

◆ setSimulationSubsteps()

◆ simulationSubsteps()

◆ step()

Member Data Documentation

◆ kNoBall

◆ kNoGamepiece