Aether

GTML

GTML (Game Telemetry Markup Language) is the structured format Aether uses to represent Unity runtime state.

What is GTML?

GTML is a JSON-based format that captures:

  • Game Objects: Hierarchy, components, properties
  • Events: Custom events, console logs, exceptions
  • UI State: Canvas hierarchy, UI element states
  • Performance: Frame times, memory usage
  • Timeline: Temporal ordering of events
ℹ️Not a Log Format

GTML is not a replacement for Unity's logging system. It's a structured representation designed for AI consumption.

GTML Structure

A GTML snapshot looks like:

1{ 2 "version": "1.0", 3 "timestamp": 1234567890, 4 "frame": 1234, 5 "scene": "MainScene", 6 "objects": [ 7 { 8 "id": "obj_123", 9 "name": "Player", 10 "active": true, 11 "components": [ 12 { 13 "type": "Transform", 14 "position": { "x": 0, "y": 1, "z": 0 }, 15 "rotation": { "x": 0, "y": 0, "z": 0 } 16 }, 17 { 18 "type": "Rigidbody", 19 "velocity": { "x": 0, "y": 0, "z": 0 } 20 } 21 ] 22 } 23 ], 24 "events": [ 25 { 26 "type": "log", 27 "level": "info", 28 "message": "Player spawned", 29 "timestamp": 1234567890, 30 "frame": 1234 31 } 32 ], 33 "ui": { 34 "canvases": [ 35 { 36 "name": "MainCanvas", 37 "active": true, 38 "elements": [] 39 } 40 ] 41 } 42}

Key Features

Bounded Representation

GTML snapshots are bounded to prevent token bloat:

  • Max Objects: 25 objects per snapshot
  • Max Components: 40 components per object
  • Max Depth: Depth 4 hierarchy
  • Max Fields: 40 fields per component
ℹ️Surgical Snapshots

Aether focuses on "suspect" objects - those most relevant to the current context. This keeps snapshots small and focused.

Temporal Ordering

Events are ordered by:

  1. Frame number (primary)
  2. Timestamp (secondary)

This allows AI to understand causality and sequence.

Type Safety

GTML uses strongly-typed schemas:

  • Component types match Unity's type system
  • Property types are preserved
  • Null values are explicit

GTML vs Logs

Traditional Logs

1[10:30:15] Player clicked button 2[10:30:16] CardNameNormalizer.Normalize() called 3[10:30:16] ERROR: NullReferenceException

Problems:

  • Unstructured text
  • No object state
  • No relationships
  • Hard to parse

GTML Snapshots

1{ 2 "events": [ 3 { "type": "click", "target": "button_123", "frame": 100 }, 4 { "type": "method_call", "method": "Normalize", "object": "CardNameNormalizer", "frame": 101 }, 5 { "type": "exception", "message": "NullReferenceException", "frame": 101 } 6 ], 7 "objects": [ 8 { "id": "CardNameNormalizer", "components": [...] } 9 ] 10}

Benefits:

  • Structured data
  • Full object state
  • Explicit relationships
  • Easy to parse

Using GTML

Via MCP Tools

GTML is returned by:

  • aether_snapshot - Current state snapshot
  • aether_tail - Recent events as GTML
  • aether_getClip - Event clip as GTML
  • aether_package - Capsule contains GTML

Programmatically

Access GTML in Unity:

1using Aether.Runtime.Core; 2 3// Use the Aether MCP tools to retrieve GTML snapshots. 4 5// Serialize to JSON 6string gtmlJson = JsonUtility.ToJson(snapshot);

GTML Schema

The full GTML schema includes:

  • Metadata: Version, timestamp, frame, scene
  • Objects: Game object hierarchy
  • Components: Component data
  • Events: Timeline of events
  • UI: UI state
  • Performance: Metrics

See the Tools Reference for complete schema documentation.

Best Practices

  1. Use Snapshots Sparingly: Request snapshots only when needed
  2. Focus on Suspects: Let Aether identify relevant objects
  3. Leverage Timeline: Use event ordering to understand causality
  4. Combine with Capsules: Use capsules for complete context

Limitations

GTML is designed for AI consumption, not human reading:

  • Not Human-Readable: Optimized for parsing, not display
  • Bounded: May not include all objects
  • Snapshot-Based: Represents a moment, not continuous stream
  • Unity-Specific: Tied to Unity's object model

Next Steps

PreviousCapsules
NextTools Reference