Aether

Recipes

Common workflows and patterns for using Aether to debug Unity issues.

Is My Unit Hovering Above the Board?

Problem: A game piece appears to be floating above the board.

Solution:

  1. Get Current State

    1@aether snapshot

  2. Check Transform

    • Look for the unit's Transform component in the snapshot
    • Verify Y position value
    • Check if it matches expected board height

  3. Check Recent Events

    1@aether tail 10
    • Look for position changes
    • Check for physics events
    • Verify collision events

  4. Create Mark for Analysis

    1@aether mark "Unit floating issue"

  5. Package for Deep Analysis

    1@aether package last_mark
ℹ️Pro Tip

Pro tier capsules will identify suspects - objects most likely causing the issue.

Why Did This Click Get Swallowed?

Problem: A UI button click doesn't trigger the expected action.

Solution:

  1. Mark Before Click

    1@aether mark "Before button click"

  2. Perform the Click

  3. Get Recent Events

    1@aether tail 5
    • Look for click events
    • Check for UI events
    • Verify event handlers

  4. Get Clip

    1@aether getClip {clip_id_from_mark}
    • Review full context around the click
    • Check UI state changes
    • Verify event propagation

  5. Package for Analysis

    1@aether package last_mark

Why Did the AI Choose That Action?

Problem: An AI agent made an unexpected decision.

Solution:

  1. Snapshot Before Decision

    1@aether snapshot
    • Capture game state before AI acts
    • Note relevant objects and states

  2. Mark Decision Point

    1@aether mark "AI decision point"

  3. Get Context After

    1@aether tail 10
    • See what happened after decision
    • Check state changes
    • Verify AI's reasoning context

  4. Package Complete Context

    1@aether package last_mark
    • Review capsule for full timeline
    • Check Pro tier suspect analysis
    • Understand AI's decision context

Performance Spike: What Happened Last Frame?

Problem: Sudden frame time spike, need to understand cause.

Solution:

  1. Mark Spike Moment

    1@aether mark "Performance spike"

  2. Get Recent Events

    1@aether tail 2
    • Focus on last 2 seconds
    • Look for heavy operations
    • Check for instantiation/destruction

  3. Snapshot Current State

    1@aether snapshot
    • Check object count
    • Verify component counts
    • Look for expensive operations

  4. Package for Analysis

    1@aether package last_mark
    • Review timeline for spike cause
    • Check Pro tier performance suspects

Debugging NullReferenceException

Problem: NullReferenceException occurs, need to find the null object.

Solution:

  1. Package Error Immediately

    1@aether package last_error

  2. View Capsule

    1@aether viewCapsule

  3. Review Error Details

    • Check stack trace in capsule
    • Review Pro tier suspects (if Pro)
    • Check source file links

  4. Get Context Before Error

    1@aether tail 10
    • See events leading to error
    • Check object state changes
    • Verify object lifecycle

Understanding State Changes

Problem: Need to understand how game state changed over time.

Solution:

  1. Mark Initial State

    1@aether mark "Initial state"

  2. Perform Actions

  3. Mark Final State

    1@aether mark "Final state"

  4. Compare States

    1@aether getClip {initial_clip_id} 2@aether getClip {final_clip_id}
    • Compare object states
    • Review state changes
    • Check component property changes

  5. Package for Analysis

    1@aether package last_mark

Best Practices

  1. Mark Early: Create marks before issues occur when possible
  2. Package Immediately: Create capsules right after errors
  3. Use Pro Features: Leverage suspect analysis for faster debugging
  4. Combine Tools: Use snapshot + tail + mark for complete context
  5. Review Capsules: Always review capsules for insights

Next Steps

PreviousTools Reference
NextTroubleshooting