Physics API

Overview

The Physics API provides engine-facing physics components for rigid body dynamics, collision detection, joints, and vehicle simulation. It wraps the Bezel physics backend with a high-level component-based interface.

This is an alpha API and may change in future versions.

Core Components

PhysicsWorld

The physics world manages the backend simulation state and owns all physics objects.

Methods

init

void

Initializes the backend physics system. Must be called before using any physics features.

update

void

Advances the physics simulation by dt seconds.Parameters:

dt (float): Delta time in seconds

setGravity

void

Sets the global gravity vector for the simulation.Parameters:

gravity (Position3d): Gravity acceleration vector

addBody

void

Adds a rigidbody to the simulation.Parameters:

body (std::shared_ptr<bezel::Rigidbody>): Rigidbody to add

raycast

RaycastResult

Performs a raycast query from origin in direction.Parameters:

origin (Position3d): Starting point of the ray
direction (Position3d): Direction vector
maxDistance (float): Maximum ray distance (default: 1000.0)
ignoreBodyId (uint32_t): Optional body ID to ignore

Returns: RaycastResult with hit information

raycastAll

RaycastResult

Performs a raycast that returns all hits along the ray.Parameters:

origin (Position3d): Starting point of the ray
direction (Position3d): Direction vector
maxDistance (float): Maximum ray distance
ignoreBodyId (uint32_t): Optional body ID to ignore

Returns: RaycastResult with all hits

overlap

OverlapResult

Tests if a collider overlaps with any bodies in the world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world reference
collider (std::shared_ptr<Collider>): Collider to test
position (Position3d): Test position
rotation (Rotation3d): Test rotation
ignoreBodyId (uint32_t): Optional body ID to ignore

Returns: OverlapResult with overlap information

sweep

SweepResult

Performs a sweep (moving cast) to predict movement.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world reference
collider (std::shared_ptr<Collider>): Collider to sweep
startPosition (Position3d): Start position
startRotation (Rotation3d): Start rotation
direction (Position3d): Movement direction
endPosition (Position3d&): End position output
ignoreBodyId (uint32_t): Optional body ID to ignore

Returns: SweepResult with first hit

sweepAll

SweepResult

Performs a sweep that returns all hits along the path.Parameters: Same as sweepReturns: SweepResult with all hits

Rigidbody Component

The Rigidbody component binds a Bezel rigidbody to a GameObject, enabling physics simulation.

Properties

body

std::shared_ptr<bezel::Rigidbody>

Underlying Bezel rigidbody instance.

sendSignal

std::string

Signal string sent by sensors on overlap/contact events.

isSensor

bool

Whether this rigidbody behaves as a sensor (trigger). Default: false

Collider Methods

addBoxCollider

void

Adds a box collider to the rigidbody.Parameters:

extents (Position3d): Half-extents of the box

addSphereCollider

void

Adds a sphere collider to the rigidbody.Parameters:

radius (float): Sphere radius

addCapsuleCollider

void

Adds a capsule collider to the rigidbody.Parameters:

radius (float): Capsule radius
height (float): Capsule height

addMeshCollider

void

Adds a mesh collider from the owning object’s mesh (if any).

Mesh colliders are more expensive than primitive colliders. Use primitives when possible.

Physics Properties

setMass

void

Sets the mass in kilograms.Parameters:

mass (float): Mass in kg

setFriction

void

Sets friction coefficient for contact resolution.Parameters:

friction (float): Friction coefficient (0.0 - 1.0)

setRestitution

void

Sets restitution (bounciness) coefficient.Parameters:

restitution (float): Bounciness (0.0 = no bounce, 1.0 = perfect bounce)

setMotionType

void

Sets the rigidbody’s motion type.Parameters:

motionType (MotionType): Motion type enum

MotionType values:

Static: Never moves
Dynamic: Affected by forces and gravity
Kinematic: Moved programmatically, not by physics

setDamping

void

Sets linear and angular damping coefficients.Parameters:

linearDamping (float): Linear damping coefficient
angularDamping (float): Angular damping coefficient

Force and Velocity Methods

applyForce

void

Applies a continuous force in world space.Parameters:

force (Position3d): Force vector

applyForceAtPoint

void

Applies a continuous force at a world-space point.Parameters:

force (Position3d): Force vector
point (Position3d): Application point in world space

applyImpulse

void

Applies an instantaneous impulse in world space.Parameters:

impulse (Position3d): Impulse vector

setLinearVelocity

void

Sets the rigidbody’s linear velocity.Parameters:

velocity (Position3d): Velocity vector

addLinearVelocity

void

Adds to the rigidbody’s linear velocity.Parameters:

velocity (Position3d): Velocity to add

setAngularVelocity

void

Sets the rigidbody’s angular velocity.Parameters:

velocity (Position3d): Angular velocity vector

addAngularVelocity

void

Adds to the rigidbody’s angular velocity.Parameters:

velocity (Position3d): Angular velocity to add

setMaxLinearVelocity

void

Sets the maximum linear velocity.Parameters:

maxLinearVelocity (float): Maximum velocity

setMaxAngularVelocity

void

Sets the maximum angular velocity.Parameters:

maxAngularVelocity (float): Maximum angular velocity

getLinearVelocity

Velocity3d

Returns the current linear velocity.

getAngularVelocity

Velocity3d

Returns the current angular velocity.

getVelocity

Velocity3d

Returns the velocity at the rigidbody’s center.

Query Methods

Query methods are async-style: the request is queued and results are reported via Component::onQueryReceive(QueryResult&).

raycast

void

Performs a raycast from the rigidbody’s position.Parameters:

direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance (default: 1000.0)

raycastAll

void

Performs a raycast that returns all hits.Parameters:

direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance (default: 100.0)

raycastWorld

void

Performs a raycast from a custom origin.Parameters:

origin (Position3d): Ray origin
direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance (default: 1000.0)

raycastWorldAll

void

Performs a raycast from a custom origin returning all hits.Parameters:

origin (Position3d): Ray origin
direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance

raycastTagged

void

Performs a raycast that only hits bodies with specified tags.Parameters:

tags (std::vector<std::string>): Tags to filter by
direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance (default: 1000.0)

raycastTaggedAll

void

Performs a tagged raycast returning all hits.Parameters:

tags (std::vector<std::string>): Tags to filter by
direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance

overlap

void

Tests if the existing collider overlaps with any bodies.

overlapSphere

void

Tests sphere overlap at rigidbody’s position.Parameters:

radius (float): Sphere radius

overlapBox

void

Tests box overlap at rigidbody’s position.Parameters:

extents (Position3d): Box half-extents

overlapCapsule

void

Tests capsule overlap at rigidbody’s position.Parameters:

radius (float): Capsule radius
height (float): Capsule height

overlapSphereWorld

void

Tests sphere overlap at a custom position.Parameters:

position (Position3d): Test position
radius (float): Sphere radius

overlapBoxWorld

void

Tests box overlap at a custom position.Parameters:

position (Position3d): Test position
extents (Position3d): Box half-extents

overlapCapsuleWorld

void

Tests capsule overlap at a custom position.Parameters:

position (Position3d): Test position
radius (float): Capsule radius
height (float): Capsule height

predictMovement

void

Predicts movement using the existing collider.Parameters:

endPosition (Position3d): Target position

predictMovementSphere

void

Predicts movement using a sphere collider.Parameters:

endPosition (Position3d): Target position
radius (float): Sphere radius

predictMovementBox

void

Predicts movement using a box collider.Parameters:

endPosition (Position3d): Target position
extents (Position3d): Box half-extents

predictMovementCapsule

void

Predicts movement using a capsule collider.Parameters:

endPosition (Position3d): Target position
radius (float): Capsule radius
height (float): Capsule height

Tagging Methods

hasTag

bool

Returns true if the rigidbody has the provided tag.Parameters:

tag (std::string): Tag to check

addTag

void

Adds a tag for filtering and game logic.Parameters:

tag (std::string): Tag to add

removeTag

void

Removes a previously added tag.Parameters:

tag (std::string): Tag to remove

Sensor Component

Convenience sensor rigidbody that defaults isSensor to true. Inherits all methods from Rigidbody.

setSignal

void

Sets the signal string emitted when the sensor is triggered.Parameters:

signal (std::string): Signal identifier

Vehicle Component

Vehicle component backed by Bezel’s vehicle implementation with full suspension and drivetrain simulation.

Properties

settings

bezel::VehicleSettings

Vehicle configuration including wheels, engine, transmission, and differentials.

forward

float

Forward/reverse input in range [-1, 1]. Positive = forward, negative = reverse.

right

float

Steering input in range [-1, 1]. Positive = right, negative = left.

brake

float

Brake input in range [0, 1]. 0 = no brake, 1 = full brake.

handBrake

float

Hand brake input in range [0, 1]. 0 = no handbrake, 1 = full handbrake.

Methods

requestRecreate

void

Requests a full rebuild of the internal vehicle constraint. Use after modifying settings.

Query Result Types

RaycastHit

position

Position3d

World-space impact position.

normal

Normal3d

Surface normal at the impact point.

distance

float

Distance from ray origin to the hit point.

object

GameObject*

Atlas-side object that owns the rigidbody, when known.

rigidbody

bezel::Rigidbody*

Underlying Bezel rigidbody pointer, when known.

didHit

bool

Whether the query produced a valid hit.

RaycastResult

hits

std::vector<RaycastHit>

All hits (for RaycastAll variants).

hit

RaycastHit

Primary hit (for Raycast variants).

closestDistance

float

Convenience distance for the nearest impact.

OverlapHit

contactPoint

Position3d

World-space contact point.

penetrationAxis

Point3d

Axis along which penetration occurs.

penetrationDepth

float

Signed penetration depth.

object

GameObject*

Atlas-side owner object, when known.

rigidbody

bezel::Rigidbody*

Underlying Bezel rigidbody pointer, when known.

OverlapResult

hits

std::vector<OverlapHit>

All overlap hits.

hitAny

bool

Whether any overlap occurred.

SweepHit

position

Position3d

World-space impact position.

normal

Normal3d

Surface normal at the impact point.

distance

float

Distance traveled before impact.

percentage

float

Impact fraction along the sweep in [0, 1].

object

GameObject*

Atlas-side owner object, when known.

rigidbody

bezel::Rigidbody*

Underlying Bezel rigidbody pointer, when known.

SweepResult

hits

std::vector<SweepHit>

All sweep hits (for “All” variants).

closest

SweepHit

Closest hit for convenience.

hitAny

bool

Whether any hit occurred.

endPosition

Position3d

End position of the sweep when no hit blocks the movement.

Example Usage

// Create a dynamic rigidbody
auto rb = std::make_shared<Rigidbody>();
rb->setMotionType(MotionType::Dynamic);
rb->setMass(5.0f);
rb->addBoxCollider({0.5f, 0.5f, 0.5f});
rb->setFriction(0.8f);

// Optional tagging for filtered queries
rb->addTag("Player");

// Trigger a raycast query (results delivered via onQueryReceive)
rb->raycast({0.0f, -1.0f, 0.0f}, 100.0f);

// For sensors, emit signals on contact
auto sensor = std::make_shared<Sensor>();
sensor->addSphereCollider(1.0f);
sensor->setSignal("EnteredTrigger");

Core

Graphics

Physics

Audio

Rendering Backend

Environment

Utilities

Overview

Core Components

PhysicsWorld

Methods

Rigidbody Component

Properties

Collider Methods

Physics Properties

Force and Velocity Methods

Query Methods

Tagging Methods

Sensor Component

Vehicle Component

Properties

Methods

Query Result Types

RaycastHit

RaycastResult

OverlapHit

OverlapResult

SweepHit

SweepResult

Example Usage

Build docs developers (and LLMs) love

Core

Graphics

Physics

Audio

Rendering Backend

Environment

Utilities

​Overview

​Core Components

​PhysicsWorld

​Methods

​Rigidbody Component

​Properties

​Collider Methods

​Physics Properties

​Force and Velocity Methods

​Query Methods

​Tagging Methods

​Sensor Component

​Vehicle Component

​Properties

​Methods

​Query Result Types

​RaycastHit

​RaycastResult

​OverlapHit

​OverlapResult

​SweepHit

​SweepResult

​Example Usage

Build docs developers (and LLMs) love

Overview

Core Components

PhysicsWorld

Methods

Rigidbody Component

Properties

Collider Methods

Physics Properties

Force and Velocity Methods

Query Methods

Tagging Methods

Sensor Component

Vehicle Component

Properties

Methods

Query Result Types

RaycastHit

RaycastResult

OverlapHit

OverlapResult

SweepHit

SweepResult

Example Usage