From meta-vr
Analyzes Meta Quest and Horizon OS VR performance using Perfetto traces — frame timing, CPU/GPU bottlenecks, render pass analysis. Use when profiling frame drops, jank, or thermal issues on Quest devices.
How this skill is triggered — by the user, by Claude, or both
Slash command
/meta-vr:hz-perfetto-debugThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill when investigating VR performance issues on Meta Quest devices:
Use this skill when investigating VR performance issues on Meta Quest devices:
These are the hard deadlines for each refresh rate. If a frame exceeds its target, the compositor must reproject or the user sees a stale frame.
| Refresh Rate | Frame Time Budget | Notes |
|---|---|---|
| 120 Hz | 8.3 ms | Supported on Quest 2, Quest 3, Quest 3S |
| 90 Hz | 11.1 ms | Supported on Quest 2, Quest Pro, Quest 3, Quest 3S |
| 72 Hz | 13.9 ms | Default on all Quest devices |
| 60 Hz | 16.7 ms | Media apps only (Quest 2); interactive apps must use 72 Hz+ |
Missing a frame deadline by even 1 ms causes a stale frame (reprojection). Stale frames above 10% of total frames indicate a serious performance problem.
Perfetto tracing is powered by the metavr CLI. Invoke via npx — no install required:
npx -y metavr --version
Examples below use the bare metavr command for brevity; if it is not installed globally, replace metavr with npx -y metavr. Connect your Quest via USB with developer mode enabled before capturing traces.
# Capture a 5-second trace from the currently running VR app
metavr perf capture
# Specify duration and target app
metavr perf capture --duration 10000 --app com.example.myapp
# Enable GPU render stage tracing for detailed pass analysis
metavr perf capture --gpu-render-stage
# Enable XR runtime metrics
metavr perf capture --xr-runtime
# Custom output name
metavr perf capture -o my-session-name
The capture auto-detects the foreground VR app if --app is not specified. CPU scheduling and GPU metrics tracing are enabled by default. The trace is pulled to your local machine automatically.
metavr perf traces
Returns .pftrace files sorted by modification time (newest first). Searches standard directories including ~/Documents, ~/Downloads, and the current working directory.
metavr perf load <trace-file>
Loads and processes the trace for analysis. Accepts a hex session ID, filename (with or without .pftrace extension), or a full/relative path.
metavr perf context
Returns a structured performance analysis including:
metavr perf query <session-id> "SELECT ts, dur, name FROM slice WHERE name LIKE '%PlayerLoop%' LIMIT 20"
Executes arbitrary SQL against the loaded Perfetto trace database. All Perfetto tables are available: slice, thread_track, thread, process, counter, counter_track, args, sched_slice, and more.
metavr perf thread-state <session-id> <utid>
# With time range
metavr perf thread-state <session-id> <utid> --start-ts 1000000 --end-ts 5000000000
Returns a thread state breakdown showing how much time the thread spent running, sleeping, blocked, or waiting for CPU. Useful for identifying whether a thread is CPU-bound, I/O-bound, or starved.
metavr perf gpu-counters <session-id> --start-ts 100,200,300 --end-ts 150,250,350
Returns GPU metric counters (mean, standard deviation, quantiles) for GPU frame ranges. Requires at least 20 frames for statistical accuracy. Metrics include texture fetch rates, shader ALU capacity, vertex processing, and fragment shading statistics.
Follow these steps in order for a thorough performance investigation.
Before analyzing, confirm the trace is usable:
SELECT
(MAX(ts) - MIN(ts)) / 1e9 AS duration_seconds,
COUNT(*) AS total_slices
FROM slice
If the trace has fewer than 1000 slices or is under 1 second, it may not contain enough data for meaningful analysis. Capture a new trace with metavr perf capture.
Find the application process (not system services):
SELECT upid, pid, name
FROM process
WHERE name NOT LIKE 'com.oculus%'
AND name NOT LIKE '/system%'
AND name NOT LIKE 'com.android%'
AND name IS NOT NULL
ORDER BY pid
For known apps, filter directly by package name.
Look for engine-specific markers:
| Engine | Key Markers |
|---|---|
| Unity | PlayerLoop, UnityMain, PhaseSync, PostLateUpdate.FinishRendering |
| Unreal | UGameEngine::Tick, FEngineLoop::Tick, RHI Thread |
| Native OpenXR | xrWaitFrame, xrBeginFrame, xrEndFrame without engine markers |
Identify the threads that matter for VR rendering:
SELECT t.utid, t.tid, t.name, p.name AS process_name
FROM thread t
JOIN process p USING(upid)
WHERE p.name = '<target-process>'
ORDER BY t.name
Critical threads to locate:
| Thread | Purpose |
|---|---|
| Main thread (UnityMain / GameThread) | Game logic, physics, scripts |
| Render thread (UnityGfx / RenderThread) | Draw call submission |
| GPU completion (GPU completion / RHI Thread) | GPU fence waiting |
| Worker threads (Job.Worker / TaskGraph) | Parallel workloads |
Once you have a thread's utid, use metavr perf thread-state <session-id> <utid> to get a quick breakdown of its running/sleeping/blocked time.
Find frame start/end markers to segment per-frame analysis:
PlayerLoop slices on the main thread define frame boundariesFEngineLoop::Tick slices on the game threadxrWaitFrame to xrEndFrame sequencesFind what consumes the most time per frame:
SELECT name, COUNT(*) AS call_count, SUM(dur)/1e6 AS total_ms, AVG(dur)/1e6 AS avg_ms
FROM slice
WHERE track_id IN (
SELECT id FROM thread_track WHERE utid = <main_thread_utid>
)
GROUP BY name
ORDER BY total_ms DESC
LIMIT 20
Functions called excessively per frame can indicate batching issues:
SELECT name, COUNT(*) AS calls
FROM slice
WHERE track_id IN (
SELECT id FROM thread_track WHERE utid = <utid>
)
AND dur < 100000
GROUP BY name
HAVING calls > 1000
ORDER BY calls DESC
See the GPU analysis reference for detailed render pass breakdown, surface analysis, and GPU counter interpretation.
| Concept | Description |
|---|---|
| Slice | A timed span of execution (function call, frame, render pass). Has ts (start), dur (duration), name, and track_id. |
| Track | A timeline lane. Thread tracks hold slices for a specific thread. Counter tracks hold metric values over time. |
| Thread (utid) | Unique thread ID within the trace. Use utid (not tid) for joins — tid can be reused. |
| Process (upid) | Unique process ID within the trace. Use upid (not pid) for joins. |
| Timestamps | All timestamps are in nanoseconds. Divide by 1e6 for milliseconds, 1e9 for seconds. |
| Counter | A time-series metric (GPU utilization, clock frequency, temperature). Stored in the counter table. |
| Args | Key-value metadata attached to slices. Accessed via the args table joined on arg_set_id. |
| Metric | Target | Warning | Critical |
|---|---|---|---|
| Frame time (90 Hz) | < 11.1 ms | > 11.1 ms | > 16.7 ms |
| Stale frame rate | < 5% | > 10% | > 25% |
| Main thread utilization | < 80% of budget | > 80% | > 95% |
| GPU utilization | < 85% of budget | > 85% | > 95% |
| Frame variance (std dev) | < 1 ms | > 2 ms | > 4 ms |
| Draw calls per frame | < 100 | > 200 | > 500 |
PlayerLoop. This is normal and intentional — do NOT flag as wasted time.SetPass call counts, which indicate materials are not being batched.UObject::ProcessEvent. High counts indicate Blueprints should be converted to C++.__StaticExec suffix in trace names.surface#0 are not descriptive — correlate them with the resolution and MSAA level to identify what they render.UnityMain may appear as UnityMai or similar.utid (not tid) when joining thread-related tables in SQL queries.For detailed guides on specific topics, see:
npx claudepluginhub meta-quest/agentic-tools --plugin meta-vrProfiles Meta Quest / Horizon OS app CPU performance via simpleperf: workload classification, hotspot recording, kernel overhead. Use when diagnosing CPU-, memory-, or I/O-bound bottlenecks.
Profiles QML/Qt Quick 2D applications using qmlprofiler, parses .qtd traces, and analyzes hotspots for frame-time, memory, and pixmap-cache performance.
Opens and inspects Metal GPU .gputrace files using the gpudebug CLI. Covers draw calls, render encoders, pipeline state, resource bindings, textures, buffers, and shader source.