Runtime Introspection Layer

Context

Turian should expose its runtime state in a machine-readable form, allowing humans, CLI tools, IDEs, debuggers, automated tests, and LLM agents to inspect, diagnose, and modify a running game instance.

This is the foundational issue. The sibling issues build directly on top of it:

  • #49 (closed) Remote Debug Protocol — transport layer
  • #50 (closed) MCP Integration — AI agent adapter
  • #51 (closed) Knowledge Export / AI Context Generation — offline schema pack

Non-goals: replacing the editor UI · AI-generated gameplay logic · assisting Turian engine development itself · internet/cloud-hosted debugging

Description

Implement a reflection and runtime inspection system that exposes the engine state as structured data.

The introspection layer acts as the single source of truth for debugging, editor tooling, CLI automation, testing, and AI integration.

Capabilities

Entity Inspection

  • Enumerate worlds, scenes, entities
  • Inspect hierarchy
  • Query components, tags, and metadata

Component Reflection

Expose component type, fields, field types, field values, and mutability.

{
  "entity": "Player",
  "component": "Transform",
  "fields": {
    "position": [10, 5, 0],
    "rotation": [0, 90, 0],
    "scale": [1, 1, 1]
  }
}

Asset Inspection

Expose materials, textures, meshes, shaders, and loaded resources.

Runtime Metrics

Expose FPS, frame time, memory usage, allocations, draw calls, GPU timings, and ECS statistics.

Scene Queries

  • Entities with component X
  • Entities near position Y
  • Active cameras
  • Lights affecting object Z

Mutation Support

  • Modify component values
  • Spawn/destroy entities
  • Reload assets

Snapshot Support

Capture complete runtime snapshots serializable to JSON. Possible future use: bug reports, replay systems, AI debugging, regression testing.

Acceptance Criteria

  • Runtime state accessible through a unified API
  • Reflection metadata generated automatically where possible
  • Engine subsystems expose diagnostics consistently
  • Snapshots can be serialized to JSON
Edited by Bruno Massa