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 Frame and Sequence within each stream and capture window. Event and draw-command sequence numbers advance independently.
  • resolve body, collider, and joint IDs through the same GravitasWorldContext that 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:

  • ScalarA and ScalarB for fixed-point payload values.
  • DataA and DataB for 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.

Source Map