Raven::PhysicsWorld Class Reference

Owns and drives a single Jolt physics simulation scene. More...

#include <PhysicsWorld.h>

Public Member Functions
PULSAR_API	PhysicsWorld ()=default
PULSAR_API	~PhysicsWorld ()=default
PULSAR_API void	Init ()
	Initialises the Jolt PhysicsSystem using the global Pulsar configuration.
PULSAR_API void	Shutdown ()
	Removes all bodies from the simulation and releases Jolt resources.
PULSAR_API u32	CreateBody (u64 entityID, const BodyTransform &transform, const RigidBodyDesc &desc, const JPH::Shape *shape)
	Creates a rigid body for the given entity and registers it in the world.
PULSAR_API void	DestroyBody (u64 entityID)
	Removes the body associated with the given entity and frees its Jolt resources.
PULSAR_API u32	CreateMeshBody (u64 entityID, u32 bodyID, const BodyTransform &transform, const JPH::Shape *shape)
	Creates a static mesh body, optionally reusing a specific Jolt body ID.
PULSAR_API JPH::Ref< JPH::Shape >	CreateShape (const RigidBodyDesc &desc)
	Builds a Jolt collision shape from a RigidBodyDesc.
PULSAR_API void	Step ()
	Advances the simulation by one fixed time step.
PULSAR_API void	SyncTransform (u64 entityID, BodyTransform &outTransform) const
	Reads the current Jolt body state into a BodyTransform.
PULSAR_API void	SetTransform (u64 entityID, const BodyTransform &transform)
	Teleports a body to a new position and orientation without waking it.
PULSAR_API void	MoveKinematic (u64 entityID, const BodyTransform &transform, float dt)
	Drives a kinematic body to the target pose over the given time delta.
PULSAR_API bool	HasBody (u64 entityID) const
	Returns whether the world currently tracks a body for the given entity.
PULSAR_API void	AddImpulse (u64 entityID, const Crux::vec3 &impulse)
	Applies an instantaneous linear impulse to a body's centre of mass.
PULSAR_API void	AddForce (u64 entityID, const Crux::vec3 &force)
	Applies a continuous force to a body's centre of mass for the current sub-step.
PULSAR_API void	AddTorque (u64 entityID, const Crux::vec3 &torque)
	Applies a continuous torque to a body for the current sub-step.
PULSAR_API void	AddLinearVelocity (u64 entityID, const Crux::vec3 &velocity)
	Adds a delta to the current linear velocity.
PULSAR_API void	SetLinearVelocity (u64 entityID, const Crux::vec3 &velocity)
	Overwrites the linear velocity of a body.
PULSAR_API Crux::vec3	GetLinearVelocity (u64 entityID) const
	Returns the current linear velocity of a body.
PULSAR_API void	AddAngularImpulse (u64 entityID, const Crux::vec3 &impulse)
	Applies an instantaneous angular impulse to a body.
PULSAR_API void	SetAngularVelocity (u64 entityID, const Crux::vec3 &velocity)
	Overwrites the angular velocity of a body.
PULSAR_API Crux::vec3	GetAngularVelocity (u64 entityID) const
	Returns the current angular velocity of a body.
PULSAR_API void	SetGravityFactor (u64 entityID, float factor)
	Scales the global gravity vector for a single body.
PULSAR_API void	SetActive (u64 entityID, bool active)
	Activates or deactivates a body in the simulation.
template<typename Fn>
void	WithBody (u64 entityID, Fn &&fn) const
	Acquires a read lock on a body and invokes a callback with it.

Detailed Description

Owns and drives a single Jolt physics simulation scene.

Each scene (e.g. a game level) owns one PhysicsWorld. The world maps engine entity IDs to Jolt BodyID values and exposes a high-level API that hides Jolt internals from the rest of the engine.

Constructor & Destructor Documentation

PhysicsWorld()

PULSAR_API Raven::PhysicsWorld::PhysicsWorld ( )

default

~PhysicsWorld()

PULSAR_API Raven::PhysicsWorld::~PhysicsWorld ( )

default

Member Function Documentation

AddAngularImpulse()

void Raven::PhysicsWorld::AddAngularImpulse	(	u64	entityID,
		const Crux::vec3 &	impulse )

Applies an instantaneous angular impulse to a body.

Parameters

entityID	Entity to affect.
impulse	Angular impulse in world space (kg·m²/s).

AddForce()

void Raven::PhysicsWorld::AddForce	(	u64	entityID,
		const Crux::vec3 &	force )

Applies a continuous force to a body's centre of mass for the current sub-step.

Parameters

entityID	Entity to affect.
force	Force vector in world space (N).

AddImpulse()

void Raven::PhysicsWorld::AddImpulse	(	u64	entityID,
		const Crux::vec3 &	impulse )

Applies an instantaneous linear impulse to a body's centre of mass.

Parameters

entityID	Entity to affect.
impulse	Impulse vector in world space (kg·m/s).

AddLinearVelocity()

void Raven::PhysicsWorld::AddLinearVelocity	(	u64	entityID,
		const Crux::vec3 &	velocity )

Adds a delta to the current linear velocity.

Parameters

entityID	Entity to affect.
velocity	Velocity delta in world space (m/s).

AddTorque()

void Raven::PhysicsWorld::AddTorque	(	u64	entityID,
		const Crux::vec3 &	torque )

Applies a continuous torque to a body for the current sub-step.

Parameters

entityID	Entity to affect.
torque	Torque vector in world space (N·m).

CreateBody()

u32 Raven::PhysicsWorld::CreateBody	(	u64	entityID,
		const BodyTransform &	transform,
		const RigidBodyDesc &	desc,
		const JPH::Shape *	shape )

Creates a rigid body for the given entity and registers it in the world.

Parameters

entityID	Unique engine entity identifier.
transform	Initial world-space position and orientation.
desc	Motion type, material properties, and mass.
shape	Pre-built Jolt collision shape (must remain valid for the body's lifetime).

Returns

The Jolt body ID packed as a u32 via GetIndexAndSequenceNumber.

CreateMeshBody()

u32 Raven::PhysicsWorld::CreateMeshBody	(	u64	entityID,
		u32	bodyID,
		const BodyTransform &	transform,
		const JPH::Shape *	shape )

Creates a static mesh body, optionally reusing a specific Jolt body ID.

Parameters

entityID	Unique engine entity identifier.
bodyID	Desired Jolt body ID packed as u32, or 0xFFFFFFFF to let Jolt assign one.
transform	Initial world-space position and orientation.
shape	Pre-built triangle mesh or other static Jolt shape.

Returns

The final Jolt body ID packed as a u32.

CreateShape()

JPH::Ref< JPH::Shape > Raven::PhysicsWorld::CreateShape

(

const RigidBodyDesc &

desc

)

Builds a Jolt collision shape from a RigidBodyDesc.

Parameters

desc	Descriptor whose Shape, HalfExtent, Radius, and HalfHeight fields are used.

Returns

A ref-counted Jolt shape. Never null on valid input.

DestroyBody()

void Raven::PhysicsWorld::DestroyBody

(

u64

entityID

)

Removes the body associated with the given entity and frees its Jolt resources.

Parameters

entityID

Entity whose body should be destroyed. No-op if not found.

GetAngularVelocity()

Crux::vec3 Raven::PhysicsWorld::GetAngularVelocity

(

u64

entityID

)

const

Returns the current angular velocity of a body.

Parameters

entityID

Entity to query.

Returns

Angular velocity in world space (rad/s), or zero vector if not found.

GetLinearVelocity()

Crux::vec3 Raven::PhysicsWorld::GetLinearVelocity

(

u64

entityID

)

const

Returns the current linear velocity of a body.

Parameters

entityID

Entity to query.

Returns

Linear velocity in world space (m/s), or zero vector if not found.

HasBody()

bool Raven::PhysicsWorld::HasBody

(

u64

entityID

)

const

Returns whether the world currently tracks a body for the given entity.

Parameters

entityID

Entity to query.

Returns

true if a body exists.

Init()

void Raven::PhysicsWorld::Init

(

)

Initialises the Jolt PhysicsSystem using the global Pulsar configuration.

Must be called after Pulsar::Init and before any body-creation calls.

MoveKinematic()

void Raven::PhysicsWorld::MoveKinematic	(	u64	entityID,
		const BodyTransform &	transform,
		float	dt )

Drives a kinematic body to the target pose over the given time delta.

Parameters

entityID	Entity to move. Must have BodyMotionType::Kinematic.
transform	Target world-space position and Euler rotation.
dt	Time delta used to derive the implicit velocity (seconds).

SetActive()

void Raven::PhysicsWorld::SetActive	(	u64	entityID,
		bool	active )

Activates or deactivates a body in the simulation.

Parameters

entityID	Entity to configure.
active	true to activate, false to put to sleep.

SetAngularVelocity()

void Raven::PhysicsWorld::SetAngularVelocity	(	u64	entityID,
		const Crux::vec3 &	velocity )

Overwrites the angular velocity of a body.

Parameters

entityID	Entity to affect.
velocity	New angular velocity in world space (rad/s).

SetGravityFactor()

void Raven::PhysicsWorld::SetGravityFactor	(	u64	entityID,
		float	factor )

Scales the global gravity vector for a single body.

Parameters

entityID	Entity to configure.
factor	Multiplier applied to world gravity (0 = weightless, 1 = full gravity).

SetLinearVelocity()

void Raven::PhysicsWorld::SetLinearVelocity	(	u64	entityID,
		const Crux::vec3 &	velocity )

Overwrites the linear velocity of a body.

Parameters

entityID	Entity to affect.
velocity	New linear velocity in world space (m/s).

SetTransform()

void Raven::PhysicsWorld::SetTransform	(	u64	entityID,
		const BodyTransform &	transform )

Teleports a body to a new position and orientation without waking it.

Parameters

entityID	Entity to reposition.
transform	Desired world-space position and Euler rotation.

Shutdown()

void Raven::PhysicsWorld::Shutdown

(

)

Removes all bodies from the simulation and releases Jolt resources.

Step()

void Raven::PhysicsWorld::Step

(

)

Advances the simulation by one fixed time step.

Uses PhysicsConfiguration::FixedTimeStep and PhysicsConfiguration::MaxSubSteps from the global Pulsar configuration.

SyncTransform()

void Raven::PhysicsWorld::SyncTransform	(	u64	entityID,
		BodyTransform &	outTransform ) const

Reads the current Jolt body state into a BodyTransform.

Parameters

entityID	Entity to query.
outTransform	Receives the world-space position and Euler rotation. Unchanged if not found.

WithBody()

template<typename Fn>

void Raven::PhysicsWorld::WithBody ( u64 entityID, Fn && fn ) const

inline

Acquires a read lock on a body and invokes a callback with it.

The callback is skipped if the entity has no registered body or if the lock cannot be acquired. The lock is released before the function returns.

Template Parameters

Fn	Callable with signature void(const JPH::Body&).

Parameters

entityID	Entity whose body to access.
fn	Callback receiving the locked JPH::Body reference.

---

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

• Pulsar/src/Pulsar/World/PhysicsWorld.h
• Pulsar/src/Pulsar/World/PhysicsWorld.cpp