Inspector Operations

The Inspector is the spine of 3Lens. All tools route through selection and entity inspection. Use these commands to examine entities in detail.

When to Use

• Examining a specific entity (mesh, material, texture, shader)
• Understanding entity dependencies and relationships
• Tracing cost attribution paths
• Selecting entities programmatically via query

Commands

Inspect an Entity

# Basic entity inspection
3lens inspect <entityId>

# Include additional data
3lens inspect <entityId> --include edges,cost,diffs

# Output as JSON
3lens inspect <entityId> --format json

Output includes:

• Identity: type, id, origin
• Dependencies: incoming/outgoing edges
• Cost attribution: weighted blame chains
• Lifecycle + diffs: creation, updates, disposal

Select by Query

# Select top GPU cost entities
3lens inspect --query "top_gpu_cost" --limit 5

# Select materials using a specific texture
3lens inspect --query "materials_using_texture:tex123"

The 5 Inspector Questions

Every entity inspection should answer:

1. What is this? (type, properties, origin)
2. What does it depend on? (incoming edges)
3. What depends on it? (outgoing edges)
4. How much does it cost? (attributed metrics with blame chain)
5. How has it changed? (diffs over time/traces)

Entity ID Format

Entity IDs follow a stable, namespaced format:

<type>:<namespace>:<identifier>

Examples:
  mesh:scene:Player_Avatar
  material:default:PBR_Metal_01
  texture:loaded:albedo_diffuse.png
  shader:compiled:StandardPBR_v123

Agent Use Cases

1. Root cause analysis: "Inspect entity mesh:scene:Player to find why it's expensive"
2. Dependency tracking: "Show all materials that depend on this texture"
3. Cost attribution: "Trace the blame chain for this GPU hotspot"
4. Bulk selection: "Select all entities matching this query"

Additional Resources

• For detailed command syntax, see [.cursor/commands/](../../commands/)
• For Inspector contract, see [.cursor/contracts/inspector.md](../../../.cursor/contracts/inspector.md)
• For entity graph rules, see [.cursor/contracts/entity-graph.md](../../../.cursor/contracts/entity-graph.md)
• Inspector is runtime/UI; see addon-inspector for implementation
• Contract: [attribution.md](../../../.cursor/contracts/attribution.md)
• Contract: [fidelity.md](../../../.cursor/contracts/fidelity.md)