PhaseDiagnostic.hpp File Reference

Per-tick player physics telemetry for diagnosing phase-through bugs. More...

#include <cstdint>
#include <entt/entt.hpp>
#include <glm/vec3.hpp>
#include <string_view>

Include dependency graph for PhaseDiagnostic.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Namespaces
namespace	physics
	Pure physics math — no ECS types, no registry.
namespace	physics::diag

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

Functions
PhaseFlag	physics::diag::operator| (PhaseFlag a, PhaseFlag b) noexcept
PhaseFlag &	physics::diag::operator|= (PhaseFlag &a, PhaseFlag b) noexcept
bool	physics::diag::any (PhaseFlag a) noexcept
void	physics::diag::setEnabled (bool on) noexcept
	Enable / disable telemetry.
bool	physics::diag::isEnabled () noexcept
void	physics::diag::recordFrame (const PlayerFrame &frame) noexcept
	Append a player's per-tick frame to the open CSV log.
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.
void	physics::diag::consumeAnnotation (entt::entity entity, char(&out)[48]) noexcept
	Drain any queued annotation for entity into out, then clear it.
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).

Detailed Description

Per-tick player physics telemetry for diagnosing phase-through bugs.

When enabled, every player's per-tick collision state is appended to a CSV file in the working directory: position before / after depen / after bump loop, velocity, movement mode, wallrun side, jump count, depen statistics, and a free-form annotation slot for "interesting" events (wallrun-enter, double-jump, depen-cancelled, suspected-phase, …).

The detector flags rows where the actual per-tick position delta significantly exceeds the expected delta (velocity * dt) — that's the "player teleported through geometry" signature. Other flagged conditions: depen finding overlap but unable to push (vector cancel), depen needing > 20 units of push (deeper than a normal grazing penetration), bump loop consuming all 4 iterations (player was wedged).

Output goes to phase-diag.csv in the binary's working directory. Open in any spreadsheet; sort / filter by the flags column to find the bug moment. Append-mode: a single play session produces one continuous log; deletion is the user's responsibility.