physics::diag Namespace Reference

Classes
struct	PlayerFrame
	One row of telemetry — captured per player per tick. More...
struct	DepenContact
	One row of depen-contact telemetry. More...

Enumerations
enum class	PhaseFlag : uint32_t {   None = 0 , Grounded = 1u << 0 , WallRunning = 1u << 1 , Sliding = 1u << 2 ,   Climbing = 1u << 3 , LedgeGrabbing = 1u << 4 , GrappleActive = 1u << 5 , DoubleJumped = 1u << 6 ,   GravityFlipped = 1u << 7 , DepenCancelled = 1u << 8 , DeepPenetration = 1u << 9 , BumpExhausted = 1u << 10 ,   SuspectedPhase = 1u << 11 }
	Bitfield flags attached to each logged row — auto-detected. More...

Functions
uint64_t	hashPhysicsState (const Registry &registry) noexcept
	Compute a deterministic hash of physics-relevant ECS state.
void	setEnabled (bool on) noexcept
	Enable / disable telemetry.
bool	isEnabled () noexcept
void	annotate (entt::entity entity, std::string_view label) noexcept
	Attach a text annotation to the NEXT frame recorded for the given entity.
void	consumeAnnotation (entt::entity entity, char(&out)[48]) noexcept
	Drain any queued annotation for entity into out, then clear it.
void	recordFrame (const PlayerFrame &frame) noexcept
	Append a player's per-tick frame to the open CSV log.
void	recordDepenContact (const DepenContact &contact) noexcept
	Append one depen-contact row to its own CSV log (depen-trace-<timestamp>.csv in the working dir).
PhaseFlag	operator| (PhaseFlag a, PhaseFlag b) noexcept
PhaseFlag &	operator|= (PhaseFlag &a, PhaseFlag b) noexcept
bool	any (PhaseFlag a) noexcept

Enumeration Type Documentation

PhaseFlag

enum class physics::diag::PhaseFlag : uint32_t

strong

Bitfield flags attached to each logged row — auto-detected.

Enumerator
None
Grounded
WallRunning
Sliding
Climbing
LedgeGrabbing
GrappleActive
DoubleJumped
GravityFlipped
DepenCancelled	Depen found overlaps but the aggregated push direction cancelled out (rare; either trapped between mirrored surfaces or arithmetic underflow). The player is left inside geometry.
DeepPenetration	Depen had to push the player by >20 u in one tick — the player was deep inside geometry before depen.
BumpExhausted	The bump loop consumed all 4 iterations and still had remainingTime > 0 — the player was grinding against complex geometry that couldn't be resolved in 4 sweeps.
SuspectedPhase	Actual per-tick position delta exceeded velocity * dt by > 2× + 5 u — the player likely tunnelled through geometry.

Function Documentation

annotate()

void physics::diag::annotate ( entt::entity entity, std::string_view label )

noexcept

Attach a text annotation to the NEXT frame recorded for the given entity.

Used by MovementSystem hooks (wallrun enter / exit, double-jump fired, etc.) to correlate movement events with collision state in the log.

any()

bool physics::diag::any ( PhaseFlag a )

inlinenoexcept

consumeAnnotation()

void physics::diag::consumeAnnotation ( entt::entity entity, char(&) out[48] )

noexcept

Drain any queued annotation for entity into out, then clear it.

Internal — called by recordFrame to copy the pending note into the row about to be written. Exposed for unit tests.

Here is the caller graph for this function:

hashPhysicsState()

uint64_t physics::diag::hashPhysicsState ( const Registry & registry )

nodiscardnoexcept

Compute a deterministic hash of physics-relevant ECS state.

Includes: Position, Velocity, Orientation, AngularVelocity, RigidBody accumulators (treating sleeping bodies the same as awake ones).

Order-independent across thread scheduling: entities are sorted by stable id before bytes are folded into the hash.

isEnabled()

bool physics::diag::isEnabled ( )

nodiscardnoexcept

Here is the caller graph for this function:

operator|()

PhaseFlag physics::diag::operator| ( PhaseFlag a, PhaseFlag b )

inlinenoexcept

operator|=()

PhaseFlag & physics::diag::operator|= ( PhaseFlag & a, PhaseFlag b )

inlinenoexcept

recordDepenContact()

void physics::diag::recordDepenContact ( const DepenContact & contact )

noexcept

Append one depen-contact row to its own CSV log (depen-trace-<timestamp>.csv in the working dir).

Called from the trimesh depen kernel only for "suspicious" contacts (depth ≫ R) so the log stays small. Lazy file open; thread-safe via a separate mutex from the per-tick frame log. No-op when telemetry is disabled.

Here is the caller graph for this function:

recordFrame()

void physics::diag::recordFrame ( const PlayerFrame & frame )

noexcept

Append a player's per-tick frame to the open CSV log.

Opens the log lazily on first call. Thread-safe (single global mutex on the write path — diagnostic only, no perf concern).

Here is the call graph for this function:

Here is the caller graph for this function:

setEnabled()

void physics::diag::setEnabled ( bool on )

noexcept

Enable / disable telemetry.

When disabled, every recordFrame call is a wait-free no-op. Toggle from DebugUI.

Here is the caller graph for this function: