Vulkan Schnee 0.0.1 (22840dc8)
High-performance rendering engine
Loading...
Searching...
No Matches
Engine::Core::PhysicsEngine Class Reference

Owns the Bullet dynamics world and dispatches engine collision events. More...

#include <PhysicsEngine.h>

Collaboration diagram for Engine::Core::PhysicsEngine:

Classes

struct  ComponentPairKey
struct  PendingActorEvent
struct  PendingComponentEvent
struct  RuntimeBodySlot
struct  RuntimeCollisionSlot

Public Member Functions

 PhysicsEngine ()
 Creates a physics engine using the active collision profile registry.
 PhysicsEngine (Physics::CollisionProfileRegistry *collisionProfileRegistry)
 Creates a physics engine with an explicit collision profile registry.
 ~PhysicsEngine ()
 Removes remaining Bullet objects and destroys the Bullet world infrastructure.
void setCollisionProfileRegistry (Physics::CollisionProfileRegistry *collisionProfileRegistry)
 Sets the collision profile registry used by collision events and filtered queries.
Physics::CollisionProfileRegistry * getCollisionProfileRegistry () const
 Gets the collision profile registry assigned to this physics engine.
void onPhysicsComponentDestroyed (entt::registry &registry, entt::entity entity)
 Cleans up legacy ECS physics data when a SimulatesPhysics component is destroyed.
void update (double deltaTimeSeconds)
 Steps the physics simulation and queues collision events.
void dispatchQueuedCollisionEvents ()
 Dispatches collision events queued by the last PhysicsEngine::update() call.
Physics::PhysicsBodyHandle registerBody (Components::PhysicsBody *body)
 Registers a physics body component for handle-based lookup.
void unregisterBody (Physics::PhysicsBodyHandle handle)
 Unregisters a physics body handle and queues End events for active pairs that reference it.
Components::PhysicsBody * resolve (Physics::PhysicsBodyHandle handle) const
 Resolves a runtime body handle to a physics body component.
Physics::CollisionHandle registerCollision (Components::Collision *collision)
 Registers a collision component for handle-based lookup.
void unregisterCollision (Physics::CollisionHandle handle)
 Unregisters a collision handle and queues End events for active pairs that reference it.
Components::Collision * resolve (Physics::CollisionHandle handle) const
 Resolves a runtime collision handle to a collision component.
btDiscreteDynamicsWorld * getDynamicsWorld () const
 Gets the Bullet dynamics world used by this physics engine.
bool raycastClosest (const glm::vec3 &origin, const glm::vec3 &direction, float maxDistance, Physics::RaycastHit &outHit) const
 Casts a ray through the physics world and returns the closest hit, if any.
bool raycastClosest (const glm::vec3 &origin, const glm::vec3 &direction, float maxDistance, const Physics::PhysicsQueryFilter &filter, Physics::RaycastHit &outHit) const
 Casts a filtered ray through the physics world and returns the closest hit, if any.
bool sphereSweepClosest (const glm::vec3 &from, const glm::vec3 &to, float radius, Physics::RaycastHit &outHit, const btCollisionObject *ignoredObject=nullptr) const
 Sweeps a sphere through the physics world and returns the closest overlap hit, if any.
bool sphereSweepClosest (const glm::vec3 &from, const glm::vec3 &to, float radius, const Physics::PhysicsQueryFilter &filter, Physics::RaycastHit &outHit, const btCollisionObject *ignoredObject=nullptr) const
 Sweeps a filtered sphere through the physics world and returns the closest hit, if any.
bool sphereClosest (const glm::vec3 &position, float radius, Physics::RaycastHit &outHit, const btCollisionObject *ignoredObject=nullptr) const
 Tests a sphere at one position and returns the closest overlapping collision object, if any.
bool sphereClosest (const glm::vec3 &position, float radius, const Physics::PhysicsQueryFilter &filter, Physics::RaycastHit &outHit, const btCollisionObject *ignoredObject=nullptr) const
 Tests a filtered sphere and returns the closest overlapping collision object, if any.
btRigidBody * createRigidBody (const Physics::RigidBodyCreateInfo &info) const
 Creates and adds a rigid body to the physics world with default Bullet collision filters.
btRigidBody * createRigidBody (const Physics::RigidBodyCreateInfo &info, std::uint16_t collisionGroup, std::uint16_t collisionMask) const
 Creates and adds a rigid body to the physics world with explicit Bullet collision filters.
void removeRigidBody (btRigidBody *body) const
 Removes a rigid body from the physics world and deletes it.
void debugDrawAll () const
 Draws debug visualization of all collision shapes in the world.

Static Public Member Functions

static btCollisionShape * createBoxShape (const glm::vec3 &halfExtents)
 Creates a box collision shape.
static btCollisionShape * createSphereShape (float radius)
 Creates a sphere collision shape.
static btCollisionShape * createCapsuleShape (float radius, float height)
 Creates a capsule collision shape aligned to Bullet's Y axis.
static btCollisionShape * createPlaneShape (const glm::vec3 &surfaceNormal, float distanceFromOrigin)
 Creates an infinite static plane collision shape.
static btCollisionShape * createConvexHullShape (const std::vector< glm::vec3 > &vertices)
 Creates a convex hull collision shape from vertex positions.
static btCollisionShape * createTriangleMeshShape (const std::vector< glm::vec3 > &vertices, const std::vector< uint32_t > &indices, btTriangleMesh *&triangleMeshOut)
 Creates a static triangle mesh collision shape from vertices and triangle indices.
static btCompoundShape * createCompoundShape ()
 Creates an empty compound collision shape.

Private Member Functions

void collectCollisionEvents ()
void queueDirectedEvents (const ComponentPairKey &pair, Physics::CollisionEventType eventType)
void queueInvalidationEndEvents (Physics::PhysicsBodyHandle bodyHandle, Physics::CollisionHandle collisionHandle)
void buildActorEvents ()
bool bodyMatchesQueryFilter (const Components::PhysicsBody *body, const Physics::PhysicsQueryFilter &filter) const

Private Attributes

Physics::CollisionProfileRegistry * collisionProfileRegistry_ = nullptr
std::vector< RuntimeBodySlot > bodySlots_
std::vector< RuntimeCollisionSlot > collisionSlots_
std::uint32_t nextBodyId_ = 1
std::uint32_t nextCollisionId_ = 1
std::set< ComponentPairKey > previousComponentPairs_
std::vector< PendingComponentEvent > pendingLifetimeComponentEvents_
std::vector< PendingComponentEvent > pendingComponentEvents_
std::vector< PendingActorEvent > pendingActorEvents_
btBroadphaseInterface * broadphase
btCollisionConfiguration * collisionConfiguration
btCollisionDispatcher * dispatcher
btConstraintSolver * solver
btDiscreteDynamicsWorld * dynamicsWorld

Detailed Description

Owns the Bullet dynamics world and dispatches engine collision events.

PhysicsEngine creates Bullet world infrastructure, steps simulation, runs physics queries, and maps runtime physics handles back to engine components. Collision callbacks are collected during PhysicsEngine::update() and dispatched by PhysicsEngine::dispatchQueuedCollisionEvents().

Definition at line 85 of file PhysicsEngine.h.

Constructor & Destructor Documentation

◆ PhysicsEngine() [1/2]

Engine::Core::PhysicsEngine::PhysicsEngine ( )

Creates a physics engine using the active collision profile registry.

◆ PhysicsEngine() [2/2]

Engine::Core::PhysicsEngine::PhysicsEngine ( Physics::CollisionProfileRegistry * collisionProfileRegistry)
explicit

Creates a physics engine with an explicit collision profile registry.

Parameters
collisionProfileRegistryRegistry used for collision responses and query filters.

◆ ~PhysicsEngine()

Engine::Core::PhysicsEngine::~PhysicsEngine ( )

Removes remaining Bullet objects and destroys the Bullet world infrastructure.

Member Function Documentation

◆ bodyMatchesQueryFilter()

bool Engine::Core::PhysicsEngine::bodyMatchesQueryFilter ( const Components::PhysicsBody * body,
const Physics::PhysicsQueryFilter & filter ) const
nodiscardprivate

◆ buildActorEvents()

void Engine::Core::PhysicsEngine::buildActorEvents ( )
private

◆ collectCollisionEvents()

void Engine::Core::PhysicsEngine::collectCollisionEvents ( )
private

◆ createBoxShape()

btCollisionShape * Engine::Core::PhysicsEngine::createBoxShape ( const glm::vec3 & halfExtents)
static

Creates a box collision shape.

Parameters
halfExtentsHalf-size of the box on each local axis, in meters.
Returns
New Bullet collision shape. The caller owns the shape.

◆ createCapsuleShape()

btCollisionShape * Engine::Core::PhysicsEngine::createCapsuleShape ( float radius,
float height )
static

Creates a capsule collision shape aligned to Bullet's Y axis.

Parameters
radiusCapsule radius in meters.
heightCapsule cylinder height in meters.
Returns
New Bullet collision shape. The caller owns the shape.

◆ createCompoundShape()

btCompoundShape * Engine::Core::PhysicsEngine::createCompoundShape ( )
static

Creates an empty compound collision shape.

Returns
New Bullet compound shape. The caller owns the shape.

◆ createConvexHullShape()

btCollisionShape * Engine::Core::PhysicsEngine::createConvexHullShape ( const std::vector< glm::vec3 > & vertices)
static

Creates a convex hull collision shape from vertex positions.

Parameters
verticesVertex positions used to build the hull.
Returns
New Bullet collision shape. The caller owns the shape.

◆ createPlaneShape()

btCollisionShape * Engine::Core::PhysicsEngine::createPlaneShape ( const glm::vec3 & surfaceNormal,
float distanceFromOrigin )
static

Creates an infinite static plane collision shape.

Parameters
surfaceNormalPlane normal.
distanceFromOriginPlane distance from world origin along surfaceNormal.
Returns
New Bullet collision shape. The caller owns the shape.

◆ createRigidBody() [1/2]

btRigidBody * Engine::Core::PhysicsEngine::createRigidBody ( const Physics::RigidBodyCreateInfo & info) const
nodiscard

Creates and adds a rigid body to the physics world with default Bullet collision filters.

The created body owns a Bullet motion state. Remove it with PhysicsEngine::removeRigidBody() unless the engine removes it through ECS physics cleanup.

Parameters
infoRigid body creation parameters.
Returns
New Bullet rigid body added to the world.

◆ createRigidBody() [2/2]

btRigidBody * Engine::Core::PhysicsEngine::createRigidBody ( const Physics::RigidBodyCreateInfo & info,
std::uint16_t collisionGroup,
std::uint16_t collisionMask ) const
nodiscard

Creates and adds a rigid body to the physics world with explicit Bullet collision filters.

The created body owns a Bullet motion state. Remove it with PhysicsEngine::removeRigidBody() unless the engine removes it through ECS physics cleanup.

Parameters
infoRigid body creation parameters.
collisionGroupBullet collision group assigned to the body.
collisionMaskBullet collision mask assigned to the body.
Returns
New Bullet rigid body added to the world.

◆ createSphereShape()

btCollisionShape * Engine::Core::PhysicsEngine::createSphereShape ( float radius)
static

Creates a sphere collision shape.

Parameters
radiusSphere radius in meters.
Returns
New Bullet collision shape. The caller owns the shape.

◆ createTriangleMeshShape()

btCollisionShape * Engine::Core::PhysicsEngine::createTriangleMeshShape ( const std::vector< glm::vec3 > & vertices,
const std::vector< uint32_t > & indices,
btTriangleMesh *& triangleMeshOut )
static

Creates a static triangle mesh collision shape from vertices and triangle indices.

The returned BVH shape references triangleMeshOut. Keep the triangle mesh alive until the shape is destroyed.

Parameters
verticesVertex positions used by indexed triangles.
indicesTriangle index list. Every three indices define one triangle.
triangleMeshOutReceives the allocated Bullet triangle mesh. The caller owns it.
Returns
New Bullet collision shape. The caller owns the shape.

◆ debugDrawAll()

void Engine::Core::PhysicsEngine::debugDrawAll ( ) const

Draws debug visualization of all collision shapes in the world.

Iterates through all rigid bodies and calls PhysicsBody debug drawing for bodies with engine user data. Does nothing when collision debug drawing is disabled.

◆ dispatchQueuedCollisionEvents()

void Engine::Core::PhysicsEngine::dispatchQueuedCollisionEvents ( )

Dispatches collision events queued by the last PhysicsEngine::update() call.

Component collision callbacks run before actor-level physics body callbacks. Events are copied before dispatch, so callbacks can modify collision subscriptions safely.

◆ getCollisionProfileRegistry()

Physics::CollisionProfileRegistry * Engine::Core::PhysicsEngine::getCollisionProfileRegistry ( ) const
nodiscard

Gets the collision profile registry assigned to this physics engine.

Returns
Registry pointer, or nullptr when the engine uses the active registry fallback.

◆ getDynamicsWorld()

btDiscreteDynamicsWorld * Engine::Core::PhysicsEngine::getDynamicsWorld ( ) const
nodiscard

Gets the Bullet dynamics world used by this physics engine.

Returns
Pointer to the physics world.

◆ onPhysicsComponentDestroyed()

void Engine::Core::PhysicsEngine::onPhysicsComponentDestroyed ( entt::registry & registry,
entt::entity entity )

Cleans up legacy ECS physics data when a SimulatesPhysics component is destroyed.

Parameters
registryRegistry that owns the destroyed component.
entityEntity that owned the destroyed component.

◆ queueDirectedEvents()

void Engine::Core::PhysicsEngine::queueDirectedEvents ( const ComponentPairKey & pair,
Physics::CollisionEventType eventType )
private

◆ queueInvalidationEndEvents()

void Engine::Core::PhysicsEngine::queueInvalidationEndEvents ( Physics::PhysicsBodyHandle bodyHandle,
Physics::CollisionHandle collisionHandle )
private

◆ raycastClosest() [1/2]

bool Engine::Core::PhysicsEngine::raycastClosest ( const glm::vec3 & origin,
const glm::vec3 & direction,
float maxDistance,
const Physics::PhysicsQueryFilter & filter,
Physics::RaycastHit & outHit ) const
nodiscard

Casts a filtered ray through the physics world and returns the closest hit, if any.

A valid filter profile limits hits by resolved collision response. Bodies without engine PhysicsBody user data pass the filter. Returns false when maxDistance is not positive or direction has zero length.

Parameters
originWorld-space ray origin.
directionRay direction. Does not need to be normalized.
maxDistanceMaximum ray length in meters.
filterCollision profile filter used by the query.
outHitFilled with world-space hit data when the function returns true.
Returns
True when the ray hits an accepted collision object.

◆ raycastClosest() [2/2]

bool Engine::Core::PhysicsEngine::raycastClosest ( const glm::vec3 & origin,
const glm::vec3 & direction,
float maxDistance,
Physics::RaycastHit & outHit ) const
nodiscard

Casts a ray through the physics world and returns the closest hit, if any.

Returns false when maxDistance is not positive or direction has zero length.

Parameters
originWorld-space ray origin.
directionRay direction. Does not need to be normalized.
maxDistanceMaximum ray length in meters.
outHitFilled with world-space hit data when the function returns true.
Returns
True when the ray hits a collision object.

◆ registerBody()

Physics::PhysicsBodyHandle Engine::Core::PhysicsEngine::registerBody ( Components::PhysicsBody * body)
nodiscard

Registers a physics body component for handle-based lookup.

Parameters
bodyPhysics body component to register.
Returns
Runtime handle used by collision events and queries.

◆ registerCollision()

Physics::CollisionHandle Engine::Core::PhysicsEngine::registerCollision ( Components::Collision * collision)
nodiscard

Registers a collision component for handle-based lookup.

Parameters
collisionCollision component to register.
Returns
Runtime handle used by collision events.

◆ removeRigidBody()

void Engine::Core::PhysicsEngine::removeRigidBody ( btRigidBody * body) const

Removes a rigid body from the physics world and deletes it.

The body's motion state is deleted before the body is deleted. Passing nullptr is ignored.

Parameters
bodyRigid body to remove and destroy.

◆ resolve() [1/2]

Components::Collision * Engine::Core::PhysicsEngine::resolve ( Physics::CollisionHandle handle) const
nodiscard

Resolves a runtime collision handle to a collision component.

Parameters
handleCollision handle to resolve.
Returns
Collision component pointer, or nullptr when the handle is invalid or stale.

◆ resolve() [2/2]

Components::PhysicsBody * Engine::Core::PhysicsEngine::resolve ( Physics::PhysicsBodyHandle handle) const
nodiscard

Resolves a runtime body handle to a physics body component.

Parameters
handleBody handle to resolve.
Returns
Physics body pointer, or nullptr when the handle is invalid or stale.

◆ setCollisionProfileRegistry()

void Engine::Core::PhysicsEngine::setCollisionProfileRegistry ( Physics::CollisionProfileRegistry * collisionProfileRegistry)

Sets the collision profile registry used by collision events and filtered queries.

Parameters
collisionProfileRegistryRegistry pointer. Passing nullptr falls back to the active registry.

◆ sphereClosest() [1/2]

bool Engine::Core::PhysicsEngine::sphereClosest ( const glm::vec3 & position,
float radius,
const Physics::PhysicsQueryFilter & filter,
Physics::RaycastHit & outHit,
const btCollisionObject * ignoredObject = nullptr ) const
nodiscard

Tests a filtered sphere and returns the closest overlapping collision object, if any.

A valid filter profile limits hits by resolved collision response. Bodies without engine PhysicsBody user data pass the filter. Returns false when radius is not positive.

Parameters
positionWorld-space position of the sphere center.
radiusSphere radius in meters.
filterCollision profile filter used by the query.
outHitFilled with world-space hit data when the function returns true.
ignoredObjectOptional collision object to ignore, usually the querying body itself.
Returns
True when the sphere overlaps an accepted collision object.

◆ sphereClosest() [2/2]

bool Engine::Core::PhysicsEngine::sphereClosest ( const glm::vec3 & position,
float radius,
Physics::RaycastHit & outHit,
const btCollisionObject * ignoredObject = nullptr ) const
nodiscard

Tests a sphere at one position and returns the closest overlapping collision object, if any.

Returns false when radius is not positive. The hit distance is the penetration depth reported by Bullet.

Parameters
positionWorld-space position of the sphere center.
radiusSphere radius in meters.
outHitFilled with world-space hit data when the function returns true.
ignoredObjectOptional collision object to ignore, usually the querying body itself.
Returns
True when the sphere overlaps a collision object.

◆ sphereSweepClosest() [1/2]

bool Engine::Core::PhysicsEngine::sphereSweepClosest ( const glm::vec3 & from,
const glm::vec3 & to,
float radius,
const Physics::PhysicsQueryFilter & filter,
Physics::RaycastHit & outHit,
const btCollisionObject * ignoredObject = nullptr ) const
nodiscard

Sweeps a filtered sphere through the physics world and returns the closest hit, if any.

A valid filter profile limits hits by resolved collision response. Bodies without engine PhysicsBody user data pass the filter. Returns false when radius is not positive or from and to are the same position.

Parameters
fromWorld-space start position of the sphere center.
toWorld-space end position of the sphere center.
radiusSphere radius in meters.
filterCollision profile filter used by the query.
outHitFilled with world-space hit data when the function returns true.
ignoredObjectOptional collision object to ignore, usually the querying body itself.
Returns
True when the swept sphere hits an accepted collision object.

◆ sphereSweepClosest() [2/2]

bool Engine::Core::PhysicsEngine::sphereSweepClosest ( const glm::vec3 & from,
const glm::vec3 & to,
float radius,
Physics::RaycastHit & outHit,
const btCollisionObject * ignoredObject = nullptr ) const
nodiscard

Sweeps a sphere through the physics world and returns the closest overlap hit, if any.

Returns false when radius is not positive or from and to are the same position.

Parameters
fromWorld-space start position of the sphere center.
toWorld-space end position of the sphere center.
radiusSphere radius in meters.
outHitFilled with world-space hit data when the function returns true.
ignoredObjectOptional collision object to ignore, usually the querying body itself.
Returns
True when the swept sphere hits a collision object.

◆ unregisterBody()

void Engine::Core::PhysicsEngine::unregisterBody ( Physics::PhysicsBodyHandle handle)

Unregisters a physics body handle and queues End events for active pairs that reference it.

Parameters
handleBody handle returned by PhysicsEngine::registerBody().

Invalid, stale, and already unregistered handles are ignored.

◆ unregisterCollision()

void Engine::Core::PhysicsEngine::unregisterCollision ( Physics::CollisionHandle handle)

Unregisters a collision handle and queues End events for active pairs that reference it.

Parameters
handleCollision handle returned by PhysicsEngine::registerCollision().

Invalid, stale, and already unregistered handles are ignored.

◆ update()

void Engine::Core::PhysicsEngine::update ( double deltaTimeSeconds)

Steps the physics simulation and queues collision events.

Bullet receives deltaTimeSeconds with up to 10 fixed substeps at 1/120 second. This function queues Begin, Stay, and End events but does not call user callbacks. Call PhysicsEngine::dispatchQueuedCollisionEvents() after the step to invoke callbacks.

Parameters
deltaTimeSecondsElapsed frame time in seconds.

Member Data Documentation

◆ bodySlots_

std::vector<RuntimeBodySlot> Engine::Core::PhysicsEngine::bodySlots_
private

Definition at line 481 of file PhysicsEngine.h.

◆ broadphase

btBroadphaseInterface* Engine::Core::PhysicsEngine::broadphase
private

Definition at line 490 of file PhysicsEngine.h.

◆ collisionConfiguration

btCollisionConfiguration* Engine::Core::PhysicsEngine::collisionConfiguration
private

Definition at line 491 of file PhysicsEngine.h.

◆ collisionProfileRegistry_

Physics::CollisionProfileRegistry* Engine::Core::PhysicsEngine::collisionProfileRegistry_ = nullptr
private

Definition at line 480 of file PhysicsEngine.h.

◆ collisionSlots_

std::vector<RuntimeCollisionSlot> Engine::Core::PhysicsEngine::collisionSlots_
private

Definition at line 482 of file PhysicsEngine.h.

◆ dispatcher

btCollisionDispatcher* Engine::Core::PhysicsEngine::dispatcher
private

Definition at line 492 of file PhysicsEngine.h.

◆ dynamicsWorld

btDiscreteDynamicsWorld* Engine::Core::PhysicsEngine::dynamicsWorld
private

Definition at line 494 of file PhysicsEngine.h.

◆ nextBodyId_

std::uint32_t Engine::Core::PhysicsEngine::nextBodyId_ = 1
private

Definition at line 483 of file PhysicsEngine.h.

◆ nextCollisionId_

std::uint32_t Engine::Core::PhysicsEngine::nextCollisionId_ = 1
private

Definition at line 484 of file PhysicsEngine.h.

◆ pendingActorEvents_

std::vector<PendingActorEvent> Engine::Core::PhysicsEngine::pendingActorEvents_
private

Definition at line 488 of file PhysicsEngine.h.

◆ pendingComponentEvents_

std::vector<PendingComponentEvent> Engine::Core::PhysicsEngine::pendingComponentEvents_
private

Definition at line 487 of file PhysicsEngine.h.

◆ pendingLifetimeComponentEvents_

std::vector<PendingComponentEvent> Engine::Core::PhysicsEngine::pendingLifetimeComponentEvents_
private

Definition at line 486 of file PhysicsEngine.h.

◆ previousComponentPairs_

std::set<ComponentPairKey> Engine::Core::PhysicsEngine::previousComponentPairs_
private

Definition at line 485 of file PhysicsEngine.h.

◆ solver

btConstraintSolver* Engine::Core::PhysicsEngine::solver
private

Definition at line 493 of file PhysicsEngine.h.


The documentation for this class was generated from the following file:
  • /workspace/magerbeton/gl3-vulkan/code/Engine/include/Engine/Physics/PhysicsEngine.h