Diagnostic Adapters
A host adapter turns the data in context.Diagnostics into an overlay, a log
entry, or a replay timeline. Build it in the host, sample, or tooling project.
The core provides deterministic events and debug draw commands. The adapter
chooses the renderer, log format, or storage.
Quick Read
The diagnostic ray capture contains a line from
x = -2 to x = 4 and a query event with two hits. A host can use either
stream or copy both for later playback.
| Host task | Consume | Output |
|---|---|---|
| Show the ray in an overlay | Draw commands | A line between the two endpoints |
| Inspect the hit result on a server | Typed events | Hit count, closest collider ID, and distance |
| Inspect the capture after the step | Both streams | A host-owned copy for the timeline |
Consume the capture after the deterministic frame or diagnostic window. For a timeline that displays object labels, retain those labels while the registrations are still valid. Read Diagnostics for capture setup and payload reference.
Adapter Boundary
An adapter should:
- consume diagnostics after the deterministic frame or debug capture window has finished.
- preserve
FrameandSequencewithin each stream and capture window. Event and draw-command sequence numbers advance independently. - resolve body, collider, and joint IDs through the same
GravitasWorldContextthat produced the payload, while the referenced registrations are active. - translate fixed-point values at the edge when the host renderer or log format requires floats or text.
- call
context.Diagnostics.Clear()after consumption when the host wants a per-frame stream.
An adapter should not:
- mutate
SolidBody,SolidBody2D, collider, partition, query, or constraint state while consuming diagnostics. - make authoritative simulation decisions from diagnostic payloads.
- treat a collider ID as a permanent identity. IDs are context-local and can be reused after deactivation or reset.
- add engine-specific renderer, file-system, networking, or editor dependencies to the Gravitas core library.
The examples below use these imports:
using System;
using FixedMathSharp;
using Gravitas;
using Gravitas.Diagnostics;
Debug Draw Adapter
A draw visitor translates each command into the host's drawing API. For the
captured ray, the Line command reaches VisitLine, which passes the two
endpoints and the color to the host. The host sink owns unit conversion,
colors, and display duration.
public interface IHostDebugDrawSink
{
void DrawLine(Vector3d start, Vector3d end, GravitasDiagnosticColor color);
void DrawPoint(Vector3d center, Fixed64 radius, GravitasDiagnosticColor color);
void DrawWireSphere(Vector3d center, Fixed64 radius, GravitasDiagnosticColor color);
void DrawWireBox(Vector3d center, Vector3d halfExtents, FixedQuaternion rotation, GravitasDiagnosticColor color);
void DrawWireCylinder(Vector3d center, Fixed64 radius, Fixed64 height, FixedQuaternion rotation, GravitasDiagnosticColor color);
void DrawWireCone(Vector3d center, Fixed64 radius, Fixed64 height, FixedQuaternion rotation, GravitasDiagnosticColor color);
void DrawWireCapsule(Vector3d center, Fixed64 radius, Fixed64 axisLength, FixedQuaternion rotation, GravitasDiagnosticColor color);
void DrawWireTriangle(Vector3d a, Vector3d b, Vector3d c, GravitasDiagnosticColor color);
}
public sealed class HostDebugDrawAdapter : GravitasDebugDrawCommandVisitor
{
private readonly IHostDebugDrawSink _sink;
public HostDebugDrawAdapter(IHostDebugDrawSink sink)
{
_sink = sink;
}
public override void VisitLine(in GravitasLineDebugDrawView view) =>
_sink.DrawLine(view.Start, view.End, view.Color);
public override void VisitRay(in GravitasRayDebugDrawView view) =>
_sink.DrawLine(view.Start, view.End, view.Color);
public override void VisitPoint(in GravitasPointDebugDrawView view) =>
_sink.DrawPoint(view.Center, view.Radius, view.Color);
public override void VisitWireSphere(in GravitasWireSphereDebugDrawView view) =>
_sink.DrawWireSphere(view.Center, view.Radius, view.Color);
public override void VisitWireBox(in GravitasWireBoxDebugDrawView view) =>
_sink.DrawWireBox(view.Center, view.HalfExtents, view.Rotation, view.Color);
public override void VisitWireCylinder(in GravitasWireCylinderDebugDrawView view) =>
_sink.DrawWireCylinder(
view.Center,
view.Radius,
view.Height,
view.Rotation,
view.Color);
public override void VisitWireCone(in GravitasWireConeDebugDrawView view) =>
_sink.DrawWireCone(
view.Center,
view.Radius,
view.Height,
view.Rotation,
view.Color);
public override void VisitWireCapsule(in GravitasWireCapsuleDebugDrawView view) =>
_sink.DrawWireCapsule(
view.Center,
view.Radius,
view.AxisLength,
view.Rotation,
view.Color);
public override void VisitWireTriangle(in GravitasWireTriangleDebugDrawView view) =>
_sink.DrawWireTriangle(view.PointA, view.PointB, view.PointC, view.Color);
public void Flush(GravitasWorldContext context) =>
context.Diagnostics.DispatchDrawCommandsTo(this);
}
Create the adapter with the host sink, then call Flush(context) after
capture. Dispatch visits the buffered commands in order. Clear the capture
once every consumer has finished.
2D debug draw in mixed mode is emitted as finite 3D slab geometry. Use
ColliderDimension and Collider2DType to style embedded 2D geometry
separately from normal 3D colliders.
Mesh and compound capture can emit many commands. Reserve draw-command capacity before a capture-heavy run and avoid full mesh capture every frame in normal gameplay.
Structured Log Adapter
A server can log the ray event through VisitRayQuery. In the two-sphere
example, the view exposes a hit count of 2 plus the nearest collider's ID
and distance. The event visitor reads those named values and passes the
original frame and sequence to the log sink.
public interface IHostDiagnosticLogSink
{
void Write(
long frame,
int sequence,
GravitasDiagnosticEventKind kind,
string payload);
}
public sealed class HostDiagnosticLogAdapter : GravitasDiagnosticEventVisitor
{
private readonly IHostDiagnosticLogSink _sink;
public HostDiagnosticLogAdapter(IHostDiagnosticLogSink sink)
{
_sink = sink;
}
public override void VisitForceDelta(in GravitasForceDeltaDiagnosticView view) =>
_sink.Write(
view.Frame,
view.Sequence,
view.Event.Kind,
$"body={view.BodyId} force={view.Force} accelDelta={view.AccelerationDelta}");
public override void VisitRayQuery(in GravitasRayQueryDiagnosticView view) =>
_sink.Write(
view.Frame,
view.Sequence,
view.Event.Kind,
$"hit={view.Hit} count={view.HitCount} " +
$"collider={view.HitColliderId} distance={view.Distance}");
public override void VisitContact(in GravitasContactDiagnosticView view) =>
_sink.Write(
view.Frame,
view.Sequence,
view.Event.Kind,
$"a={view.ColliderAId} b={view.ColliderBId} depth={view.Depth}");
public override void VisitMixedContact(in GravitasMixedContactDiagnosticView view) =>
_sink.Write(
view.Frame,
view.Sequence,
view.Event.Kind,
$"3d={view.Collider3DId} 2d={view.Collider2DId} depth={view.Depth}");
public void Flush(GravitasWorldContext context) =>
context.Diagnostics.DispatchEventsTo(this);
}
For production logs, prefer a structured payload object over ad hoc strings. The
important rule is that adapters consume semantic typed views instead of decoding
ScalarA, ScalarB, DataA, and DataB directly.
Replay Timeline Adapter
To revisit the ray later, copy the line command and query event before the sink is cleared. Keep the copies alongside the authoritative replay frame as presentation data. The example copies each stream in capture order:
public readonly struct DiagnosticFrameCapture
{
public DiagnosticFrameCapture(
long frame,
GravitasDiagnosticEvent[] events,
GravitasDebugDrawCommand[] drawCommands)
{
Frame = frame;
Events = events;
DrawCommands = drawCommands;
}
public long Frame { get; }
public GravitasDiagnosticEvent[] Events { get; }
public GravitasDebugDrawCommand[] DrawCommands { get; }
}
public static class DiagnosticTimelineCapture
{
public static DiagnosticFrameCapture Capture(GravitasWorldContext context)
{
ReadOnlySpan<GravitasDiagnosticEvent> events =
context.Diagnostics.Events;
ReadOnlySpan<GravitasDebugDrawCommand> drawCommands =
context.Diagnostics.DrawCommands;
return new DiagnosticFrameCapture(
context.FrameCount,
events.ToArray(),
drawCommands.ToArray());
}
}
For a window spanning multiple frames, use each event or command's own
Frame stamp when placing it on the timeline. The outer capture's Frame
records when the host took the copy.
The array allocation belongs to the tooling edge. Long-running replay tools should pool or stream capture storage when diagnostics are enabled for many frames.
Generic Payload Policy
The event struct intentionally uses generic numeric fields:
ScalarAandScalarBfor fixed-point payload values.DataAandDataBfor integer payload values.
The generic payload table in Diagnostics is the storage
contract. GravitasDiagnosticEventVisitor and typed event views are the
preferred adapter-facing decode surface. Lower-level TryAs... helpers are
useful for one-off filters over known event kinds, not for full adapter
dispatch.
Draw commands follow the same pattern: GravitasDebugDrawCommand stays compact,
while GravitasDebugDrawCommandVisitor exposes typed draw views for renderer
adapters. Do not overload an event or draw kind with undocumented meanings.