game-performance— agent skill

You are an autonomous game performance analysis agent. Do NOT ask the user questions. Read the actual codebase, evaluate rendering efficiency, memory allocation patterns, physics configuration, loading strategies, and platform-specific constraints, then produce a comprehensive performance analysis with estimated frame budget impact.

TARGET: $ARGUMENTS

If arguments are provided, use them to focus the analysis (e.g., "rendering", "physics", "memory", "loading", "mobile"). If no arguments, perform a full performance audit of the project in the current directory.

============================================================ PHASE 1: ENGINE AND TARGET DETECTION ============================================================

Step 1.1 -- Detect Game Engine

Scan for engine markers:

• Unity: ProjectSettings/, .unity, .prefab, Assembly-CSharp
• Unreal: .uproject, Source/, Content/, .uasset
• Godot: project.godot, .tscn, .gd
• Phaser/PixiJS/Three.js: package.json with framework dependency
• Custom engine: look for game loop, renderer, entity system

Step 1.2 -- Determine Frame Budget

Based on target platform and FPS target:

• 60 FPS target → 16.67ms per frame budget
• 30 FPS target → 33.33ms per frame budget
• VR (90 FPS) → 11.11ms per frame budget
• Mobile → typically 16.67ms with thermal throttling concerns

Subdivide budget:

• Rendering: 40-60% of budget
• Game logic: 20-30% of budget
• Physics: 10-20% of budget
• Audio: 5% of budget
• UI: 5-10% of budget

============================================================ PHASE 2: RENDERING PERFORMANCE ============================================================

Step 2.1 -- Draw Call Analysis

Scan for draw call inefficiencies:

BATCHING ISSUES:

• Are similar materials combined? (dynamic batching, static batching, SRP batcher)
• Are sprites using texture atlases instead of individual textures?
• Are there unnecessary material instances (unique materials per object)?
• Are transparent objects sorted to minimize overdraw?

OVERDRAW:

• Are there overlapping transparent/semi-transparent objects?
• Is there unnecessary full-screen post-processing?
• Are particle systems creating excessive layered transparency?
• Are UI elements overlapping the game world without culling?

SHADER COMPLEXITY:

• Are shaders using appropriate LOD for target platform?
• Are there heavy per-pixel operations (real-time shadows on mobile)?
• Are shader variants being compiled at runtime (causing hitches)?
• Are there unnecessary shader features enabled (fog, lightmaps on hidden objects)?

Step 2.2 -- Texture and Asset Analysis

Scan for memory-heavy assets:

• Textures exceeding recommended sizes for target platform
• Mobile: max 2048x2048, prefer 1024x1024
• PC: max 4096x4096
• Uncompressed textures (should use DXT/ETC2/ASTC)
• Textures without mipmaps for 3D objects
• Textures with mipmaps for UI (wasted memory)
• Duplicate textures or near-identical variants
• Audio files not using appropriate compression (WAV vs OGG/MP3)

Step 2.3 -- LOD Strategy (3D only)

Check Level of Detail implementation:

• Do complex meshes have LOD levels?
• Are LOD transition distances appropriate?
• Is impostoring used for very distant objects?
• Are LOD transitions causing visible popping?
• Are particle effects reducing complexity at distance?

============================================================ PHASE 3: MEMORY AND GARBAGE COLLECTION ============================================================

Step 3.1 -- Allocation Pattern Analysis

Scan for per-frame allocations (GC pressure):

COMMON OFFENDERS:

• String concatenation in update loops (use StringBuilder/StringBuffer)
• LINQ queries in hot paths (allocates iterators)
• Boxing of value types (int -> object)
• Delegate/closure allocations in callbacks
• new Vector3/Vector2 in loops (use ref or cache)
• List.Add without pre-allocated capacity
• Dictionary lookups with struct keys (boxing)
• Coroutine allocations (use cached WaitForSeconds)
• Foreach on non-List collections (allocates enumerator)

ENGINE-SPECIFIC:

• Unity: GetComponent calls in Update (cache the reference)
• Unity: Find/FindObjectOfType in Update (never acceptable)
• Unity: Camera.main accessor (caches internally in newer versions, but verify)
• Unreal: NewObject in Tick (use object pooling)
• Godot: get_node in _process (cache the reference with @onready)

Step 3.2 -- Object Pooling Audit

Check for missing object pools:

• Projectiles/bullets (spawned and destroyed frequently)
• Particle effects (reuse vs recreate)
• Enemy spawning (pool vs instantiate)
• Audio sources (SFX pooling)
• UI elements (scroll view items, damage numbers)
• Network messages (buffer reuse)

For each pool found, verify:

• Pool has reasonable max size
• Objects are properly reset on return
• Pool grows gracefully (not all-at-once)
• Pool does not leak (objects returned after use)

Step 3.3 -- Memory Leak Detection

Scan for common leak patterns:

• Event subscriptions without unsubscribe (OnDestroy/Dispose)
• Static references to scene objects
• Cached textures/assets never released
• Unbounded lists/dictionaries that only grow
• Circular references preventing garbage collection

============================================================ PHASE 4: PHYSICS AND UPDATE OPTIMIZATION ============================================================

Step 4.1 -- Physics Configuration

Check physics settings:

• Fixed timestep value (too small = expensive, too large = tunneling)
• Max allowed timestep (prevents spiral of death)
• Physics layers and collision matrix (minimize unnecessary checks)
• Collision shape complexity (prefer primitives over mesh colliders)
• Continuous collision detection usage (only where needed)

Step 4.2 -- Update Loop Organization

Audit update/tick methods:

• Is work distributed across frames (not everything in one Update)?
• Are expensive operations on timers/intervals (not every frame)?
• Is spatial partitioning used for proximity queries (quadtree/octree/grid)?
• Are raycasts minimized and cached where possible?
• Are AI calculations spread across multiple frames?
• Is culling implemented for off-screen entities?

Step 4.3 -- Spatial Partitioning

Check for spatial data structures:

• Quadtree (2D) or Octree (3D) for spatial queries
• Grid-based spatial hashing for uniform-size entities
• BVH (Bounding Volume Hierarchy) for complex scenes
• Chunk-based loading for large worlds

If none exist and the game has many entities (>100), flag as missing.

============================================================ PHASE 5: LOADING AND STREAMING ============================================================

Step 5.1 -- Scene/Level Loading

Check loading patterns:

• Synchronous loading (blocks main thread — causes freezes)
• Async loading with progress feedback
• Additive scene loading (load pieces, not everything)
• Asset streaming for open-world (load/unload based on proximity)
• Loading screen implementation quality

Step 5.2 -- Asset Loading Strategy

Evaluate asset management:

• Are assets loaded on demand or all at startup?
• Is there an asset manifest/preload list?
• Are unused assets unloaded after scene transitions?
• Is texture streaming used for large textures (3D)?
• Are asset bundles/addressables used for DLC/update content?

============================================================ PHASE 6: PLATFORM-SPECIFIC CONCERNS ============================================================

Step 6.1 -- Mobile Performance (if mobile target)

Check for:

• Thermal throttling awareness (reduce quality over time)
• Battery drain considerations (CPU/GPU usage)
• Fill rate budget (mobile GPUs are fill-rate limited)
• Minimum spec compatibility (older devices)
• Texture compression format (ASTC for both iOS and Android)
• Audio compression (mono SFX, stereo music, low sample rate)

Step 6.2 -- Web Performance (if web target)

Check for:

• Bundle size analysis (total download size)
• Asset loading waterfall (parallel vs sequential)
• WebGL context loss handling
• Memory limits (browser tab memory cap)
• Web Worker usage for heavy computation
• WASM usage for performance-critical code

Step 6.3 -- Console Performance (if console target)

Check for:

• Memory budget adherence (platform-specific limits)
• Certification requirements (frame rate minimums)
• Loading time limits (platform TRC/XR requirements)
• Storage I/O patterns (HDD vs SSD optimization)

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),

note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT ============================================================

Game Performance Analysis

Project: {name}

Engine: {detected engine}

Target Platform: {platform(s)}

Frame Budget: {ms}ms ({fps} FPS target)

Performance Summary

Critical Findings

Memory Profile Estimate

• Texture memory: {estimate}
• Mesh memory: {estimate} (3D only)
• Audio memory: {estimate}
• Script data: {estimate}
• Total estimate: {total} (budget: {platform limit})

Object Pooling Status

Frame Budget Breakdown (estimated)

Optimization Priority

1. {highest impact fix with estimated FPS improvement}
2. {second highest}
3. {third highest}

NEXT STEPS:

• "Run /game-code-review to audit architecture patterns that affect performance."
• "Run /game-qa to verify optimizations do not break functionality."
• "Run /game-launch to run the full launch readiness pipeline."

DO NOT:

• Do NOT run profiling tools — this is a static code analysis only.
• Do NOT optimize prematurely — flag issues but note which are theoretical vs certain.
• Do NOT recommend engine changes (Unity to Unreal) — work within the existing engine.
• Do NOT ignore mobile/web constraints when those are target platforms.
• Do NOT estimate exact frame times — use ranges and relative severity.
• Do NOT modify code — this is an analysis skill. Report findings only.

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /game-performance — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.