Diagnostics
Enable context.Diagnostics to see what a query, collision, or solver step
reported. The context records deterministic data for drawing, logs, and replay
tools. The host decides how to present it.
Diagnostics are disabled by default. Disabled hooks return before touching
buffers. While enabled, the context appends events and draw commands to
pre-sized SwiftList buffers.
Quick Read
Consider the ray in Query Services. It travels
from x = -2 to x = 4 and hits two spheres. With capture enabled,
Query3D.RaycastAll records a RayQuery event. The event reports the hit
count and the closest collider. To draw the segment, also call CaptureLine
with the same endpoints.
flowchart TB
accTitle: Capturing and consuming a ray query
accDescr: RaycastAll records one event for the two-hit query. CaptureLine records a draw command for the segment. The host reads both streams and clears the buffers after consumption.
Query["RaycastAll"] -->|"Two hits"| Event["RayQuery event"]
Capture["CaptureLine"] -->|"Ray endpoints"| Draw["Line command"]
Event --> Host["Host reads both streams"]
Draw --> Host
Host --> Clear["Clear after reading"]
Use the entry point to capture a window. Read the typed views to interpret events and the draw commands to add geometry to an overlay. Diagnostic Adapters shows how a host can draw, log, or retain the same capture.
Entry Point
Reserve capacity before capturing the frame or diagnostic window. In this
example, context is the configured world, and start, end, mask, and
hits come from the two-sphere ray.
using Gravitas.Diagnostics;
context.Diagnostics.Enable(eventCapacity: 512, drawCommandCapacity: 256);
context.Query3D.RaycastAll(start, end, mask, hits);
context.Diagnostics.CaptureLine(start, end, GravitasDiagnosticColor.Cyan);
foreach (GravitasDiagnosticEvent diagnosticEvent in context.Diagnostics.Events)
{
// Translate to logs, overlays, replay markers, or host telemetry.
}
foreach (GravitasDebugDrawCommand command in context.Diagnostics.DrawCommands)
{
// Translate to host-specific lines, meshes, gizmos, or debug shapes.
}
context.Diagnostics.Clear();
To capture a full step, enable the sink before running Simulate() and
LateSimulate(), then consume the buffers after the step.
Events and DrawCommands are read-only spans over the sink's live backing
storage. Consume them before further capture, clearing, disabling, or resetting
the sink. Copy values into host-owned storage when retaining a frame; the
replay timeline adapter shows
that boundary.
Enable(...) reserves capacity to avoid resize spikes when expected event
counts are known. Clear() empties both streams and resets their sequence
counters while keeping allocated buffers. Disable() clears and stops capture.
Event Stream
GravitasDiagnosticEvent is a compact generic payload. The common fields are:
| Field | Meaning |
|---|---|
Frame |
Owning context's long frame count when captured. |
Sequence |
Capture order inside the current buffer. |
Kind |
Event payload type. |
BodyId, JointId |
Context-local IDs, or -1 when not applicable. |
ColliderAId, ColliderBId |
Context-local collider IDs, or -1 when not applicable. |
ColliderADimension, ColliderBDimension |
Collider runtime surface: ThreeD, TwoD, or None. |
ColliderAType, ColliderBType |
3D collider shape types when present. |
ColliderA2DType, ColliderB2DType |
2D collider shape types when present. |
Start, End |
Query segment, previous/current velocity, or other vector pair. |
PointA, PointB |
Contact points, hit point, acceleration delta, or shape-specific point data. |
Vector |
Force, torque, velocity delta, query normal, contact normal, or impulse direction. |
ScalarA, ScalarB |
Event-specific fixed-point values. |
DataA, DataB |
Event-specific integer values. |
Hit |
Whether the event represents a successful hit/contact. |
The stream is scoped to one context. Collider, body, and joint IDs are not
global and must be resolved through the same context that produced the event.
Events, draw commands, and all typed views preserve the full 64-bit frame stamp.
Host log/replay schemas should preserve that width as well; sequence numbers and
buffer counts remain bounded int values.
Event Families
| Family | Event kinds | Typical use |
|---|---|---|
| Body deltas | ForceDelta, TorqueDelta, LinearVelocityDelta, AngularVelocityDelta |
Inspect force/torque application and response velocity changes. |
| Queries | GroundProbe, RayQuery, CircleQuery, MixedQuery, QuerySummary |
Inspect hit counts, layer masks, probe shape, reducer quality, and mixed query results. |
| Contacts and response | Contact, ResponseImpulse, MixedContact, MixedResponseImpulse, MixedResponseIsland |
Inspect manifolds, impulse magnitude, island iteration behavior, and mixed response. |
| Constraints | JointRegistered, JointRemoved, JointImpulse, JointLimitReached |
Inspect joint ownership, solve metrics, limits, motors, and collision policy. |
| Ragdolls | RagdollActivated |
Inspect activation state, link count, and joint count. |
QuerySummary reports eligible top-level exact reducer attempts, accepted hits,
fallback hits, and rejected conservative candidates. Mixed query diagnostics use
it to show exact-versus-conservative query quality beside ordinary MixedQuery
hit events.
Typed Views And Dispatch
Use a typed view to read event fields by name. For the ray, a
GravitasRayQueryDiagnosticView exposes HitCount, HitColliderId, and
Distance for the nearest hit. A GravitasDiagnosticEventVisitor dispatches
each event to the matching handler. For example, to read mixed contacts:
using Gravitas.Diagnostics;
public sealed class MyDiagnosticAdapter : GravitasDiagnosticEventVisitor
{
public override void VisitMixedContact(in GravitasMixedContactDiagnosticView contact)
{
// contact.Collider3DId, contact.Collider2DId,
// contact.HasPoint3D, contact.Point3D,
// contact.HasPoint2D, contact.Point2D,
// contact.Normal3DTo2D, contact.Depth
}
}
With the existing context, create the adapter and dispatch the captured events:
MyDiagnosticAdapter adapter = new();
context.Diagnostics.DispatchEventsTo(adapter);
Available views cover the event stream:
GravitasForceDeltaDiagnosticViewGravitasTorqueDeltaDiagnosticViewGravitasVelocityDeltaDiagnosticViewGravitasGroundProbeDiagnosticViewGravitasRayQueryDiagnosticViewGravitasCircleQueryDiagnosticViewGravitasQuerySummaryDiagnosticViewGravitasContactDiagnosticViewGravitasResponseImpulseDiagnosticViewGravitasMixedQueryDiagnosticViewGravitasMixedContactDiagnosticViewGravitasMixedResponseImpulseDiagnosticViewGravitasMixedResponseIslandDiagnosticViewGravitasJointDiagnosticViewGravitasRagdollDiagnosticView
GravitasGroundProbeDiagnosticView exposes both 3D and 2D probe metadata. Use
Mode for 3D GroundProbeMode, Mode2D for 2D GroundProbeMode2D, and
dimension/type properties to route shape payloads. 2D probe points are stored in
the X/Z debug plane: event X is planar X, event Z is planar Y, and event Y is
zero.
Contact and mixed-query views expose HasPoint* flags because canonical surface
anchors can describe a valid hit whose absolute world coordinate is outside the
Fixed64 scalar domain. Point fields are zero when their matching flag is
false; adapters should omit that marker while still reporting the contact,
normal, depth, or query distance.
The views are read-only wrappers over the event value. Visitors and views do not
change capture storage, event ordering, diagnostic buffering, or disabled path
cost. Lower-level TryAs... helpers remain available for one-off filters over
known event kinds.
Solver And Query Counters
Some diagnostics are service-local counters instead of event-buffer entries:
- CCD island and handoff work on
GravitasPhysicsServiceandGravitasPhysics2DServiceLastContinuousCollisionIslandCountLastContinuousCollisionIslandIterationCountLastContinuousCollisionIslandLimitReached
- Body time of impact (TOI) work on
SolidBodyandSolidBody2DLastContinuousCollisionToiIterationCountLastContinuousCollisionToiIterationLimitReached
- Batch queries on
Query2D,Query3D, andQueryMixedLastBatchRequestCountLastBatchHitCountLastBatchCandidateCountLastBatchMeshTriangleCandidateCountonQueryMixed
These counters are deterministic frame-local state for tuning, tests, host telemetry, and benchmark triage. They are not serialized replay state.
Each active Joint3D and Joint2D also exposes LastSolveMetrics, a
deterministic snapshot from the most recent solver pass. It reports row count,
anchor error, limit error, motor error, cached impulse, fresh impulse, motor
impulse, and clamped row count. These values mirror JointImpulse diagnostic
views and are measurement state, not extra tuning knobs.
Draw Commands
Each GravitasDebugDrawCommand describes a primitive the host can draw.
The line in the ray example carries the start, end, and color. A host adapter
passes those values to its drawing API.
| Kind | Required payload |
|---|---|
Line |
Start, End, Color |
Ray |
Start, End, Color |
Point |
Center, Radius, Color |
WireSphere |
Center, Radius, Color |
WireBox |
Center, HalfExtents, Rotation, Color |
WireCapsule |
Center, Radius, AxisLength, Rotation, Color |
WireCylinder |
Center, Radius, Height, Rotation, Color |
WireCone |
Center, Radius, Height, Rotation, Color |
WireTriangle |
PointA, PointB, PointC, Color |
Host renderers can consume draw commands through
GravitasDebugDrawCommandVisitor and
context.Diagnostics.DispatchDrawCommandsTo(...).
Use explicit capture helpers for host-driven overlays:
context.Diagnostics.CaptureCollider(collider, GravitasDiagnosticColor.Cyan);
context.Diagnostics.CaptureMixedCollider(collider2D, GravitasDiagnosticColor.Cyan);
context.Diagnostics.CaptureJoint(joint, GravitasDiagnosticColor.Yellow);
context.Diagnostics.CaptureLine(start, end, GravitasDiagnosticColor.Yellow);
context.Diagnostics.CaptureRay(origin, direction, maxDistance, GravitasDiagnosticColor.Green);
context.Diagnostics.CapturePoint(point, Fixed64.Half, GravitasDiagnosticColor.Red);
CaptureCollider(...) emits one command for primitive colliders and one
WireTriangle command per materializable mesh triangle. Mesh geometry remains
canonical in its rigid local frame; presentation triangles whose absolute
vertices cross the Fixed64 coordinate boundary are skipped deterministically
instead of affecting simulation. Compound colliders emit one command per
internal part using the owning compound collider ID and ColliderType
Compound.
CaptureMixedCollider(LSCollider2D, ...) emits the finite 2D slab/prism used by
mixed collision. Circles draw as vertical wire cylinders, AABBs as wire boxes,
and polygons as top, bottom, and vertical slab edges. Commands are tagged with
GravitasColliderDimension.TwoD.
CaptureJoint(Joint3D, ...) emits anchors, anchor-error line, and active
angular axes for hinge, cone-twist, and fixed joints.
CaptureJoint(Joint2D, ...) emits planar anchors, anchor-error line, and
prismatic slider axis where applicable.
Performance Rules
- Leave diagnostics disabled in normal hot-path measurements unless the measurement is about diagnostics.
- Reserve realistic capacities with
Enable(...)before capture-heavy runs. - Call
Clear()once the host consumes a frame or diagnostic window. - Do not project diagnostics through
SwiftCollections.Observablein authoritative simulation paths without tests and benchmarks for ordering and notification cost. - Add benchmarks when new event hooks or draw commands touch collision, partitioning, queries, body integration, or response paths.
Boundaries
- Diagnostics are same-thread context buffers.
- Event storage is intentionally generic. Add a documented event kind or typed view when a subsystem needs richer diagnostics.
- Draw commands are wire/debug descriptions, not mesh generation utilities.
- Hosts remain responsible for rendering, logging, persistence, and replay UI.