Physics Queries

Engine::Core::PhysicsEngine exposes immediate Bullet queries for gameplay code. Use these from actor logic when you need hit information without waiting for rigid body collision callbacks.

API

Query	Function	Use case
Ray trace	raycastClosest(origin, direction, maxDistance, hit)	Hitscan weapons, line of sight, placement checks
Sphere overlap	sphereClosest(position, radius, hit, ignoredObject)	Detect one object inside a radius at the current frame
Sphere trace	sphereSweepClosest(from, to, radius, hit, ignoredObject)	Continuous projectile overlap and other CCD-style checks

All three functions return true when they hit something and fill Engine::Physics::RaycastHit.

RaycastHit::getPhysicsBody() converts the Bullet collision object user pointer back to the engine PhysicsBody component.

Ray Trace Demo

Use a ray trace when the query has no volume.

#include "Engine/Physics/PhysicsEngine.h"
 
Engine::Physics::RaycastHit hit;
 
const glm::vec3 origin = getActorLocation();
const glm::vec3 direction = getForwardVector();
 
if (physics->raycastClosest(origin, direction, 100.0f, hit)) {
    auto* body = hit.getPhysicsBody();
    auto* actor = body ? body->getHitActor() : nullptr;
}

direction does not need to be normalized. hit.distance is the distance from origin to hit.point.

Sphere Overlap Demo

Use a sphere overlap when the sphere is already at the position you want to test.

#include "Engine/Physics/PhysicsEngine.h"
 
Engine::Physics::RaycastHit hit;
 
const glm::vec3 center = getActorLocation();
constexpr float radius = 0.5f;
 
if (physics->sphereClosest(center, radius, hit)) {
    auto* body = hit.getPhysicsBody();
    auto* actor = body ? body->getHitActor() : nullptr;
}

sphereClosest() uses Bullet contactTest() with a temporary sphere object. hit.distance stores the contact penetration depth for the selected overlap. hit.fraction is 0.0f because the query does not move.

Sphere Trace Demo

Use a sphere trace when the sphere moves during the frame.

#include "Engine/Physics/PhysicsEngine.h"
 
Engine::Physics::RaycastHit hit;
 
const glm::vec3 from = previousProjectilePosition;
const glm::vec3 to = nextProjectilePosition;
constexpr float projectileRadius = 0.1f;
 
if (physics->sphereSweepClosest(from, to, projectileRadius, hit)) {
    auto* body = hit.getPhysicsBody();
    auto* actor = body ? body->getHitActor() : nullptr;
 
    destroyActor();
}

sphereSweepClosest() uses Bullet convexSweepTest(). It checks the full movement from from to to, so fast projectiles do not skip thin targets between frames.

Ignoring Self

Pass the projectile body as ignoredObject when the query object already has collision in the world.

const btCollisionObject* ignored = projectilePhysicsBody->getRigidBody();
 
if (physics->sphereSweepClosest(from, to, projectileRadius, hit, ignored)) {
    destroyActor();
}

ignoredObject is optional. Use nullptr or omit the argument when the query has no world collision body.

Source Files

• Engine/include/Engine/Physics/PhysicsEngine.h - query API declarations
• Engine/src/Engine/Physics/PhysicsEngine.cpp - Bullet query implementation