Bezel Physics Backend

Overview

Bezel provides a backend-agnostic interface for rigid bodies, colliders, joint constraints, and vehicle simulation. When BEZEL_NATIVE is not defined, this implementation is backed by Jolt Physics.

This is an alpha API and may change in future versions. Most users should use the high-level Atlas Physics API instead.

Core Types

PhysicsWorld

Physics world owning the backend simulation state.

Methods

init

void

Initializes the backend physics system.

update

void

Advances the physics simulation by dt seconds.Parameters:

dt (float): Delta time in seconds

addBody

void

Adds a rigidbody to the simulation.Parameters:

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

setGravity

void

Sets the global gravity vector.Parameters:

gravity (Position3d): Gravity acceleration vector

raycast

RaycastResult

Performs a raycast query.Parameters:

origin (Position3d): Ray origin
direction (Position3d): Ray direction
maxDistance (float): Maximum ray distance
ignoreBodyId (uint32_t): Optional body ID to ignore

raycastAll

RaycastResult

Performs a raycast returning all hits.Parameters: Same as raycast

overlap

OverlapResult

Tests if a collider overlaps with any bodies.Parameters:

world (std::shared_ptr<PhysicsWorld>): 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

sweep

SweepResult

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

world (std::shared_ptr<PhysicsWorld>): 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

sweepAll

SweepResult

Performs a sweep returning all hits.Parameters: Same as sweep

Rigidbody

Backend rigid body representation used by Atlas components.

Properties

position

Position3d

World-space position of the rigidbody.

rotation

Rotation3d

World-space rotation (Euler angles).

rotationQuat

glm::quat

World-space rotation (quaternion).

mass

float

Mass in kilograms. Default: 0.0

friction

float

Friction coefficient. Default: 0.5

restitution

float

Restitution (bounciness) coefficient. Default: 0.0

isSensor

bool

Whether this is a sensor (trigger). Default: false

sensorSignal

std::string

Signal emitted by sensor on contact.

linearVelocity

Position3d

Linear velocity vector.

angularVelocity

Position3d

Angular velocity vector.

maxLinearVelocity

float

Maximum linear velocity cap.

maxAngularVelocity

float

Maximum angular velocity cap.

linearDamping

float

Linear damping coefficient. Default: 0.05

angularDamping

float

Angular damping coefficient. Default: 0.1

collider

std::shared_ptr<Collider>

Collision shape attached to this rigidbody.

motionType

MotionType

Motion type (Static, Dynamic, or Kinematic).

Methods

create

void

Creates the rigidbody in the physics world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

destroy

void

Removes the rigidbody from the physics world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

setPosition

void

Sets the body’s world position and updates the backend.Parameters:

position (Position3d): New position
world (std::shared_ptr<PhysicsWorld>): Physics world

setRotation

void

Sets the body’s world rotation and updates the backend.Parameters:

rotation (Rotation3d): New rotation
world (std::shared_ptr<PhysicsWorld>): Physics world

setCollider

void

Replaces the collider used by this rigidbody.Parameters:

collider (std::shared_ptr<Collider>): New collider

setMaximumLinearVelocity

void

Sets maximum linear velocity.Parameters:

maxLinearVelocity (float): Maximum velocity

setMaximumAngularVelocity

void

Sets maximum angular velocity.Parameters:

maxAngularVelocity (float): Maximum angular velocity

getLinearVelocity

Velocity3d

Gets the current linear velocity.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

getAngularVelocity

Velocity3d

Gets the current angular velocity.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

getVelocity

Velocity3d

Gets the velocity at the rigidbody’s center.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

applyProperties

void

Applies all properties to the backend body.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

refresh

void

Refreshes the rigidbody state from the backend.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

raycast

RaycastResult

Performs a raycast from this rigidbody.Parameters:

direction (Position3d): Ray direction
maxDistance (float): Maximum distance
world (std::shared_ptr<PhysicsWorld>): Physics world
ignoreBodyId (uint32_t): Optional body to ignore

raycastAll

RaycastResult

Performs a raycast returning all hits.Parameters: Same as raycast

overlap

OverlapResult

Tests overlap with a collider.Parameters:

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

sweep

SweepResult

Performs a sweep to predict movement.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world
collider (std::shared_ptr<Collider>): Collider to sweep
direction (Position3d): Movement direction
endPosition (Position3d&): End position output
ignoreBodyId (uint32_t): Optional body to ignore

sweepAll

SweepResult

Performs a sweep returning all hits.Parameters: Same as sweep

Colliders

Base Collider

Base interface for all collision shapes.

getMinExtent

float

Returns the smallest extent used for broad-phase heuristics.

BoxCollider

Axis-aligned box collider defined by half-extents.

BoxCollider

constructor

Creates a box collider.Parameters:

halfExtents (Position3d): Half-extents of the box (width/2, height/2, depth/2)

halfExtents

Position3d

Half-extents of the box.

SphereCollider

Sphere collider defined by radius.

SphereCollider

constructor

Creates a sphere collider.Parameters:

radius (float): Sphere radius

radius

float

Sphere radius.

CapsuleCollider

Capsule collider defined by radius and height.

CapsuleCollider

constructor

Creates a capsule collider.Parameters:

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

radius

float

Capsule radius.

height

float

Capsule height.

MeshCollider

Triangle mesh collider defined by indexed geometry.

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

MeshCollider

constructor

Creates a mesh collider.Parameters:

vertices (std::vector<Position3d>): Vertex positions
indices (std::vector<uint32_t>): Triangle indices

vertices

std::vector<Position3d>

Vertex positions.

indices

std::vector<uint32_t>

Triangle indices.

Joints

Base Joint

Base interface for constraint-style joints.

parent

JointChild

Parent joint endpoint (Rigidbody* or WorldBody).

child

JointChild

Child joint endpoint (Rigidbody* or WorldBody).

space

Space

Whether anchor is in local or global space.

anchor

Position3d

Joint anchor position.

breakForce

float

Force threshold to break the joint. 0 = unbreakable.

breakTorque

float

Torque threshold to break the joint. 0 = unbreakable.

create

void

Creates the joint in the provided world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

breakJoint

void

Breaks the joint by disabling its underlying constraint.

FixedJoint

Joint that locks relative translation and rotation.

create

void

Creates the fixed joint in the provided world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

HingeJoint

Joint that constrains rotation around a hinge axis.

axis1

Normal3d

Hinge axis for parent body. Default: up vector

axis2

Normal3d

Hinge axis for child body. Default: up vector

limits

AngleLimits

Optional angular limits for the hinge.

motor

Motor

Optional motor to drive the hinge.

create

void

Creates the hinge joint in the provided world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

SpringJoint

Joint that behaves like a distance constraint with optional spring.

anchorB

Position3d

Second anchor position.

restLength

float

Rest length of the spring. Default: 1.0

useLimits

bool

Whether to use min/max length limits. Default: false

minLength

float

Minimum distance constraint.

maxLength

float

Maximum distance constraint.

spring

Spring

Spring parameters for the joint.

create

void

Creates the spring joint in the provided world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

Vehicle Simulation

Vehicle

High-level vehicle wrapper around Jolt’s VehicleConstraint.

chassis

Rigidbody*

Pointer to the vehicle chassis rigidbody.

settings

VehicleSettings

Vehicle configuration including wheels, engine, transmission.

create

void

Creates the vehicle constraint in the world.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

destroy

void

Destroys the vehicle constraint.Parameters:

world (std::shared_ptr<PhysicsWorld>): Physics world

isCreated

bool

Returns whether the vehicle has been created.

setDriverInput

void

Sets driver input controls.Parameters:

forward (float): Forward/reverse [-1, 1]
right (float): Steering [-1, 1]
brake (float): Brake [0, 1]
handBrake (float): Handbrake [0, 1]

VehicleSettings

Configuration structure for vehicle simulation.

Normal3d

Up direction vector. Default: (0, 1, 0)

forward

Normal3d

Forward direction vector. Default: (0, 0, 1)

maxPitchRollAngleDeg

float

Maximum pitch/roll angle in degrees. Default: 180.0

wheels

std::vector<VehicleWheelSettings>

Array of wheel configurations.

controller

VehicleControllerSettings

Engine, transmission, and differential settings.

maxSlopeAngleDeg

float

Maximum slope angle the vehicle can climb. Default: 80.0

VehicleWheelSettings

Configuration for individual vehicle wheels.

position

Position3d

Wheel position relative to chassis.

suspensionDirection

Normal3d

Suspension direction. Default: (0, -1, 0)

steeringAxis

Normal3d

Steering axis. Default: (0, 1, 0)

wheelUp

Normal3d

Wheel up direction. Default: (0, 1, 0)

wheelForward

Normal3d

Wheel forward direction. Default: (0, 0, 1)

suspensionMinLength

float

Minimum suspension length. Default: 0.3

suspensionMaxLength

float

Maximum suspension length. Default: 0.5

suspensionFrequencyHz

float

Suspension spring frequency. Default: 1.5

suspensionDampingRatio

float

Suspension damping ratio. Default: 0.5

radius

float

Wheel radius. Default: 0.3

width

float

Wheel width. Default: 0.1

maxSteerAngleDeg

float

Maximum steering angle in degrees. Default: 70.0

maxBrakeTorque

float

Maximum brake torque. Default: 1500.0

maxHandBrakeTorque

float

Maximum handbrake torque. Default: 4000.0

Enums and Helper Types

MotionType

Static

enum

Body never moves.

Dynamic

enum

Body is affected by forces and gravity.

Kinematic

enum

Body is moved programmatically, not by physics.

Space

Local

enum

Coordinates are in local space.

Global

enum

Coordinates are in world/global space.

SpringMode

FrequencyAndDamping

enum

Spring defined by frequency (Hz) and damping ratio.

StiffnessAndDamping

enum

Spring defined by stiffness and damping coefficients.

Example Usage

auto world = std::make_shared<bezel::PhysicsWorld>();
world->init();

auto chassis = std::make_shared<bezel::Rigidbody>();
chassis->mass = 1200.0f;
chassis->setCollider(std::make_shared<bezel::BoxCollider>(Position3d{1.0f, 0.5f, 2.0f}));
chassis->create(world);

bezel::Vehicle vehicle;
vehicle.chassis = chassis.get();
vehicle.settings.wheels.resize(4);
vehicle.create(world);

// Each frame
vehicle.setDriverInput(1.0f, 0.0f, 0.0f, 0.0f);
world->update(dt);

Core

Graphics

Physics

Audio

Rendering Backend

Environment

Utilities

Overview

Core Types

PhysicsWorld

Methods

Rigidbody

Properties

Methods

Colliders

Base Collider

BoxCollider

SphereCollider

CapsuleCollider

MeshCollider

Joints

Base Joint

FixedJoint

HingeJoint

SpringJoint

Vehicle Simulation

Vehicle

VehicleSettings

VehicleWheelSettings

Enums and Helper Types

MotionType

Space

SpringMode

Example Usage

Build docs developers (and LLMs) love

Core

Graphics

Physics

Audio

Rendering Backend

Environment

Utilities

​Overview

​Core Types

​PhysicsWorld

​Methods

​Rigidbody

​Properties

​Methods

​Colliders

​Base Collider

​BoxCollider

​SphereCollider

​CapsuleCollider

​MeshCollider

​Joints

​Base Joint

​FixedJoint

​HingeJoint

​SpringJoint

​Vehicle Simulation

​Vehicle

​VehicleSettings

​VehicleWheelSettings

​Enums and Helper Types

​MotionType

​Space

​SpringMode

​Example Usage

Build docs developers (and LLMs) love

Overview

Core Types

PhysicsWorld

Methods

Rigidbody

Properties

Methods

Colliders

Base Collider

BoxCollider

SphereCollider

CapsuleCollider

MeshCollider

Joints

Base Joint

FixedJoint

HingeJoint

SpringJoint

Vehicle Simulation

Vehicle

VehicleSettings

VehicleWheelSettings

Enums and Helper Types

MotionType

Space

SpringMode

Example Usage