Game Performance Profiler

Game Performance Profiler

Use this skill when the main question is "what packet do we trust, which bottleneck family is most likely, and what is the next capture or review artifact worth producing?"

The job is not to dump generic optimization advice. The job is to normalize the current packet, choose one operating mode, name one primary bottleneck family, recommend the smallest next capture that can improve confidence, and return one profiling artifact teams can actually act on.

Read references/mode-selection-and-route-outs.md before handling an unfamiliar request shape. Read references/capture-packets-and-benchmark-routes.md before designing a reproducible pass. Read references/device-review-and-steam-deck.md before trusting editor numbers for handheld or target-device review. Read references/profiling-patterns.md before classifying weak or ambiguous evidence. Read references/escalation-ladder.md before jumping from screenshots or stat packets to deeper engine or GPU tools.

When to use this skill

• Unity or Unreal projects with low FPS, frame-time spikes, hitches, or performance regressions where the bottleneck is not yet isolated
• Profiler screenshots, stat unit / stat gpu output, Unreal Insights traces, overlay captures, route notes, or benchmark complaints that need interpretation
• Steam Deck, handheld, mobile, console, VR, or low-spec review requests where packaged-on-device behavior matters more than editor impressions
• Requests for a profiling plan, benchmark route, device review packet, CPU/GPU split note, or escalation choice instead of immediate code edits
• Mixed performance packets where the next owner is still unclear and the first job is choosing between quick packet, deeper trace, or neighboring game skill

When not to use this skill

• The main issue is a Unity/Unreal build, cook, package, editor, or CI failure with no runtime frame-time diagnosis yet → use game-build-log-triage
• The main issue is generic web/app/service performance rather than engine-specific runtime capture interpretation → use performance-optimization
• The real task is broad milestone or production coordination across bugs, playtest notes, launch goals, and roadmap tradeoffs → use bmad-gds
• The packet is mainly playtest/demo/community feedback and the question is fix-first prioritization → use game-demo-feedback-triage
• The next move is already a deep implementation change with a confirmed cause; route to the implementation skill after producing the profiling brief

Instructions

Step 1: Frame the packet

Capture the minimum useful context before diagnosing anything.

Record:

• engine: Unity | Unreal | Unknown
• target: PC | Steam Deck / handheld | console | mobile | VR | low-spec laptop | unknown
• environment: editor | packaged/dev build | release/shipping build | unknown
• symptom: low average FPS | intermittent hitch | traversal hitch | combat spike | loading stall | thermal drift | unknown
• evidence available: profiler screenshot, trace/capture file, stat-command screenshot, overlay screenshot, video, benchmark notes, reproduction steps
• reproduction shape: exact scene, save slot, encounter, traversal path, menu, cutscene, or unknown
• quality variables: resolution, preset, frame cap, upscaler state, power mode, battery state if relevant

Quick frame:

Engine: Unreal
Target: Steam Deck
Environment: packaged build unknown
Symptom: traversal hitch after two minutes in market square
Evidence: `stat unit` screenshot + overlay photo
Repro: route not yet fixed

Rule: if the packet is thin, keep confidence low and make the next capture smaller, not broader.

Step 2: Choose one primary mode

Use references/mode-selection-and-route-outs.md.

Pick exactly one primary mode:

• quick-triage-packet
• bottleneck-classification
• benchmark-route-plan
• device-review
• tool-escalation

Rule: one primary mode, optional secondary note. Do not try to handle every mode at once.

Step 3: Name the likely bottleneck family before proposing fixes

Choose one primary family and an optional secondary family.

Primary families:

• cpu-gameplay-scripting
• cpu-render-thread-draw-call-pressure
• gpu-rendering-shaders-postfx
• memory-gc-allocation-churn
• loading-streaming-io
• physics-animation-simulation
• platform-config-thermal-device-specific
• unknown-needs-better-capture

Good bottleneck statements:

• "The strongest signal points to streaming / IO hitching during traversal, not steady-state GPU load."
• "The packet suggests GC/allocation spikes during combat more than rendering saturation."
• "This looks device/config-bound because the team is still relying on editor impressions instead of packaged-on-target evidence."

Avoid: "performance is bad overall."

Step 4: Recommend the smallest next capture

Pick the cheapest capture that can materially separate the likely causes.

Typical next captures:

• one better Unity Profiler CPU/GPU/Memory packet from a representative player build
• one stat unit + stat gpu pair on the exact Unreal repro route
• one fixed traversal route with warm-up and repeat counts
• one packaged-on-device capture instead of more editor screenshots
• one deeper trace (Unreal Insights, GPU Visualizer, Frame Debugger, or external GPU tool) only after the first packet justifies it

Rule: prefer engine-native captures before vendor GPU tools unless the packet is already clearly render-path specific.

Step 5: Make route and device context explicit

If reproducibility is missing, define the smallest repeatable pass.

Specify:

• save slot / checkpoint / scene
• start point and traversal path
• warm-up pass count
• measured repeat count or duration
• graphics preset / frame cap / power mode
• whether the packet is editor-only, packaged-only, or target-device

Do not treat "the market area feels bad" as a durable benchmark route.

Step 6: Return one profiling brief

Always return one concise artifact with this shape:

# Game Performance Profiling Brief

## Scope
- Mode: ...
- Engine: ...
- Target: ...
- Environment: ...
- Symptom: ...
- Confidence: high | medium | low

## Evidence packet
- What exists now: ...
- What's missing: ...
- Editor vs packaged / device note: ...

## Primary bottleneck hypothesis
- Bucket: ...
- Why it fits: ...
- Evidence: ...

## Secondary hypothesis
- Bucket: ...
- Why it still matters: ...

## Next capture
1. ...
2. ...
3. ...

## Benchmark route / device review
- Repro route or save: ...
- Repeat / warm-up guidance: ...
- Device or packaged-build checks: ...

## Escalation path
- Stay with quick packet | move to engine profiler | escalate to GPU tool
- Why: ...

## Recommended next artifact
- Choose one: quick triage packet | profiling plan | benchmark route brief | CPU/GPU split note | memory/GC checklist | streaming hitch checklist | device review brief

## What not to do yet
- 1-3 bullets that prevent premature optimization or blind rewrites

Output format

Required qualities:

• classify the bottleneck before talking about fixes
• separate evidence from hypothesis
• recommend the next capture, route, or device review step instead of a giant backlog
• make editor-vs-packaged and packet-vs-trace boundaries explicit
• keep the report roughly 300-550 words unless the user asks for more
• use engine-native terms such as Unity Profiler, Frame Debugger, Unreal Insights, stat unit, stat gpu, frame time, draw-call pressure, GC, streaming, and packaged build

Examples

Example 1: Unity combat spike

Input: "Our Unity game drops from 120 to 45 FPS in combat. We have Profiler screenshots and someone suspects GC spikes. Triage what to look at first."

Expected shape: classify around memory-gc-allocation-churn or cpu-gameplay-scripting, keep the current screenshots as a real packet, recommend the smallest next capture, and avoid jumping to rendering advice first.

Example 2: Unreal open-world traversal hitch

Input: "Unreal is fine indoors but frame time explodes in our open world area. Help me triage whether this is CPU, GPU, streaming, or shaders."

Expected shape: use bottleneck-classification or benchmark-route-plan, recommend stat unit / stat gpu or Unreal Insights as appropriate, and define a reproducible traversal route instead of guessing fixes.

Example 3: Steam Deck review packet

Input: "We need a Steam Deck performance review plan before our demo release. The editor feels rough but we have not profiled the packaged build on device yet."

Expected shape: choose device-review, keep confidence limited, prioritize packaged-on-device evidence, and return a device review brief or benchmark route brief.

Example 4: Route-out to build failure triage

Input: "Our Unreal packaged build crashes during cook and we do not even have runtime numbers yet."

Expected shape: route to game-build-log-triage instead of pretending this is already a profiling problem.

Best practices

1. Start from the packet the team already has instead of demanding an ideal trace immediately. 2. Name one primary bottleneck family before discussing optimizations. 3. Treat reproducibility as part of the diagnosis, not an optional extra. 4. Prefer packaged-on-device evidence over editor impressions when the release target is a handheld or constrained machine. 5. Escalate from screenshot/stat packets to engine-native profilers before jumping to GPU-vendor tooling. 6. Recommend one next artifact, not a giant optimization backlog. 7. Keep route-outs explicit so game-performance work does not sprawl into build triage, generic app tuning, or production coordination.

References

• Unity Profiler
• Unity Frame Debugger
• Unreal Performance and Profiling Overview
• Unreal stat commands
• Unreal Insights
• GPUOpen Unreal Engine Performance Guide
• Steam Deck docs

Capture Packets and Benchmark Routes

Use this reference when the current evidence is too vague to classify a bottleneck confidently.

Quick triage packet

Capture the smallest shareable packet first:

• target device / hardware
• editor vs packaged build
• one stat unit / stat gpu / overlay / profiler screenshot
• exact scene, save slot, menu, or route name
• quality preset, frame cap, resolution, and upscaler state
• one sentence describing the symptom shape: steady low FPS, traversal hitch, combat spike, load spike, or thermal drift

Benchmark route brief

When screenshots are not enough, define a repeatable pass: 1. start point / save slot / map 2. fixed traversal path or camera move 3. warm-up pass count 4. measured repeat count 5. expected frame-time budget or FPS target 6. where to capture screenshots or traces

Why this matters

• Performance complaints are often location-specific, not global.
• Screenshot-only evidence is faster to share but too weak without route/build/device context.
• Repeatable routes let QA, engineering, and production compare builds without arguing about whether they tested the same thing.

Bad packets to avoid

• "the market area feels bad" with no route or settings
• editor-only measurements when the decision is about packaged or target-device behavior
• a single screenshot with no build number, device, or repro steps

Device Review and Steam Deck Notes

Use this reference when handheld or target-device performance matters more than editor numbers.

Default device-review flow

1. confirm the packaged build on the target device 2. record graphics preset, frame cap, power mode, and any upscaler settings 3. run a fixed route or save-based benchmark pass 4. capture overlay screenshots or short videos at the worst point 5. decide whether the next artifact is a device review brief, benchmark route brief, or deeper profiler capture

Steam Deck / handheld emphasis

• Do not treat editor results as a proxy for Steam Deck behavior.
• Overlay screenshots and short videos are acceptable first-pass evidence.
• Power, battery, frame-cap, and quality-preset notes matter because they change the interpretation of the capture.
• If the problem only appears on device, keep confidence focused on platform-config-thermal-device-specific until a packaged-on-device pass exists.

Useful evidence fields

• device model
• OS / compatibility layer if relevant
• graphics preset / resolution / upscaler
• plugged in vs battery
• measured route and repeat count
• whether the issue worsens after a few minutes or long session

Escalation Ladder

Use this reference to decide when to stay with a quick packet and when to escalate.

Stage 1 — quick packet

Stay here when you only need to answer:

• is the complaint real on the target build/device?
• is the first signal CPU, GPU, memory, streaming, or platform/device specific?
• what route or context should the team capture next?

Typical tools:

• Unity Profiler screenshot attached to player
• Unreal stat unit / stat gpu
• Steam Deck overlay or MangoHud screenshot

Stage 2 — engine-native profiler

Move here when the quick packet is not enough to separate the likely bottleneck.

Typical tools:

• Unity Profiler modules
• Unity Profile Analyzer
• Unity Frame Debugger / Memory Profiler
• Unreal Insights
• Unreal GPU Visualizer or more focused stat captures

Stage 3 — graphics / vendor tools

Escalate here only when the engine-native signal still leaves a render/GPU mystery.

Typical tools:

• RenderDoc
• PIX
• Nsight

Rule of thumb

• Prefer the smallest capture that upgrades confidence.
• Do not jump to deep GPU tooling when the real missing piece is a reproducible route, packaged build, or device context.
• Do not stay at screenshot level forever if the team is already blocked on ownership or a likely root-cause family.

Mode Selection and Route-outs

Use this reference when the packet shape is clear enough to choose a mode, but not clear enough to start optimizing.

Primary modes

Fast mode picks

• Screenshot-only packet with no stable route yet → quick-triage-packet
• Enough evidence to say "this is probably streaming" or "this is probably GC" → bottleneck-classification
• "The market square gets bad after two minutes" with no fixed pass → benchmark-route-plan
• Steam Deck / handheld / console-style release review → device-review
• The team already has first-pass stats and is deciding between Unreal Insights, Frame Debugger, GPU Visualizer, RenderDoc, PIX, or Nsight → tool-escalation

Route-outs

Route out when the packet reveals a different owning problem:

• build, cook, package, editor launch, CI artifact, or toolchain failure → game-build-log-triage
• broad milestone / production coordination across game tasks → bmad-gds
• mixed playtest, demo, store, or community feedback prioritization → game-demo-feedback-triage
• generic app/service/browser/database tuning outside engine-specific runtime profiling → performance-optimization

Quick anti-patterns

• Treating editor-only numbers as final truth for Steam Deck or other target-device review
• Treating a stat unit screenshot as perfect proof instead of first-pass direction
• Jumping to RenderDoc / PIX / Nsight before engine-native evidence says the render path is the real ambiguity
• Mixing benchmark-route design, bottleneck classification, and implementation fixes into the same answer

Profiling Patterns Reference

Use this reference to normalize vague performance complaints into a few reusable bottleneck families.

Cross-engine first pass

1. Confirm target hardware and whether the measurement is from editor, packaged/dev build, or release/shipping build. 2. Lock a reproducible route: exact scene, level, encounter, traversal path, save slot, menu, or camera move. 3. Decide whether the first question is steady low FPS, intermittent hitching, or device-review confidence. 4. Choose the smallest capture that can separate CPU, GPU, memory, and streaming possibilities. 5. Recommend one next artifact after triage rather than a huge optimization backlog.

Bottleneck families

Recommended next artifacts by bucket

• cpu-gameplay-scripting → CPU/GPU split note or profiling plan
• cpu-render-thread-draw-call-pressure → benchmark route brief or render-cost checklist
• gpu-rendering-shaders-postfx → profiling plan with GPU capture path
• memory-gc-allocation-churn → memory/GC checklist
• loading-streaming-io → streaming hitch checklist
• platform-config-thermal-device-specific → device review brief
• unknown-needs-better-capture → quick triage packet

Minimum evidence request packet

• one representative screenshot or trace summary
• target hardware and build type
• exact repro route, save slot, or encounter
• observed frame-time or FPS range
• whether resolution/quality changes materially shift the issue
• whether the result is editor-only, packaged-only, or device-only