Aether

Capsules

Capsules are compressed, AI-readable artifacts that package runtime context for debugging and analysis.

What Are Capsules?

A Capsule is a self-contained snapshot of a specific moment or event in your Unity runtime. It includes:

  • Timeline: Events leading up to and following the moment
  • Game State: Relevant object states and component data
  • Errors: Stack traces and exception context
  • Analysis: AI-generated insights and suspect identification (Pro)
ℹ️Flight Recorder Analogy

Think of a Capsule like a flight recorder (black box). It captures everything needed to understand what happened, without requiring you to narrate the bug.

Why Capsules Save Tokens

Traditional debugging requires the AI to:

  1. Ask for logs
  2. Parse unstructured text
  3. Request more context
  4. Repeat until understanding

Token cost: High (multiple round trips, large context windows)

Capsules provide:

  1. Structured, compressed context
  2. Pre-analyzed suspects
  3. Direct source links
  4. Complete timeline in one artifact

Token cost: Low (single artifact, targeted context)

Capsule Structure

A typical capsule contains:

1{ 2 "id": "capsule_abc123", 3 "timestamp": "2024-01-15T10:30:00Z", 4 "type": "error", 5 "summary": "NullReferenceException in CardNameNormalizer", 6 "timeline": [ 7 { "time": -5.2, "event": "Player clicked card" }, 8 { "time": -2.1, "event": "CardNameNormalizer.Normalize() called" }, 9 { "time": 0.0, "event": "Exception thrown" } 10 ], 11 "errors": [ 12 { 13 "message": "NullReferenceException", 14 "stackTrace": "...", 15 "source": { "file": "CardNameNormalizer.cs", "line": 47 } 16 } 17 ], 18 "suspects": [ 19 { 20 "object": "CardNameNormalizer", 21 "confidence": "High", 22 "reason": "Exception source matches suspect" 23 } 24 ] 25}

When to Use Capsules

Use capsules for:

  • Bug Reports: Package complete context for AI analysis
  • Performance Issues: Capture frame spikes with full context
  • Unexpected Behavior: Document "what happened" vs "what should happen"
  • AI Decision Debugging: Understand why the AI chose a specific action
✅Best Practice

Create a capsule immediately after encountering a bug, before attempting fixes. This preserves the exact state for analysis.

Creating Capsules

Via MCP Tool

1@aether package last_error

Or for a specific mark:

1@aether package last_mark

Programmatically

Capsules are automatically created when:

  • An error occurs (if auto-capture enabled)
  • A mark is created with aether_mark
  • Manually via aether_package tool

Capsule Types

Error Capsules

Created automatically when errors occur. Includes:

  • Exception details
  • Stack trace
  • Game state at error time
  • Timeline of events leading to error

Mark Capsules

Created from marks. Includes:

  • Context before/after the mark
  • Custom label/description
  • Screenshot (if enabled)
  • Full game state

Session Capsules

Created for entire play sessions. Includes:

  • Complete event timeline
  • All errors and warnings
  • Performance metrics
  • Full game state history

Pro Features

Pro tier capsules include:

  • Ranked Suspects: AI-analyzed likely causes
  • Source Links: Direct links to suspect code
  • Richer Compression: More context in smaller size
  • Confidence Scores: How certain the analysis is

Viewing Capsules

Via MCP Tool

1@aether viewCapsule

Via Capsule Viewer

Capsules are saved as HTML files that can be opened in a browser:

1{DataDirectory}/Aether/Capsules/capsule_{id}.html

Best Practices

  1. Create Early: Generate capsules immediately after bugs
  2. Use Marks: Create marks at key moments for later analysis
  3. Review Suspects: Check Pro tier suspect analysis
  4. Share Context: Capsules are perfect for sharing with AI or team

Next Steps

  • Learn about GTML - the format capsules use
  • See Tools Reference for capsule creation commands
  • Check Recipes for common capsule workflows
PreviousCore Concepts
NextGTML