Browser Game Stutter Diagnosis: A Frame-Time Evidence Workflow
Learn to read frame-time samples, not average FPS, to localize browser game stutter to CPU, GPU, render, or network causes.
Average FPS can hide uneven frame pacing. To investigate browser game stutter, capture the affected gameplay window, compare frame-time summaries with CPU and GPU measurements, and test one plausible cause at a time. GripForge's gripforge_performance tool analyzes supplied measurements or a recent workspace capture. It returns findings and recommendations; it does not change the game.
The distinction between measurements matters. A CPU submission timer is not a GPU timer, a network round-trip time is not a texture-download duration, and a stale multiplayer snapshot is not the same thing as an expired diagnostic capture.
1. Reproduce the symptom and record the conditions
Choose a repeatable event: entering an area, spawning enemies, triggering an effect or moving through a busy scene. Record the build version, viewport dimensions, quality setting and device used. Keep the tab visible and the game active during capture.
Collect measurements around the event rather than only during an idle menu. A clean idle capture cannot rule out a gameplay spike. For a before-and-after comparison, repeat the same path and trigger under comparable conditions; a different camera angle or resolution can change the workload.
The MCP documentation gives the tool contract. The general docs explain the surrounding game and asset workflows.
2. Supply sample windows with meaningful metrics
A report accepts 1–120 samples. Each sample needs fps or frameMs; the other measurements are optional. Include the report's game, version and viewport when available so a later comparison has context. Use measured values rather than filling unknown fields with zero.
Samples can summarize a window of frames. In the instrumented game, frameMs is a window mean and p95Ms is that window's 95th percentile. The latter is a threshold at or below which roughly 95% of the observed frame times fall; it is not the average duration of the slowest 5%.
The analyzer reports the worst supplied window p95. It does not reconstruct a combined frame-by-frame percentile from those summaries. If a short hitch remains unexplained, inspect a browser performance trace for the individual event as well.
| Field | Meaning and useful limit |
|---|---|
frameMs | Reported frame interval, potentially a window average |
p95Ms | 95th-percentile frame time for the supplied sample window |
cpuMs | Measured CPU frame work, including renderer submission |
submitMs | CPU scene traversal and driver submission; already included in cpuMs |
gpuMs | Valid measured GPU execution time when available |
drawCalls, triangles | Render counters that describe workload, without proving its bottleneck |
networkMs | Request round-trip time |
snapshotAgeMs | Time since the latest accepted authoritative game snapshot |
Do not add submitMs to cpuMs as if they were disjoint costs. Do not label submission time as GPU execution. Supply GPU timing only from a valid measurement; unavailable or invalid GPU results should remain absent or null.
3. Choose a current capture or an explicit report
gripforge_performance supports two evidence paths:
- Read the latest workspace capture, optionally identifying a specific kit. The capture is retained in the serving process for ten minutes and disappears on restart. A missing capture is not evidence of smooth performance.
- Pass an explicit
reportwith your recorded samples. This is analyzed without being retained as a new workspace capture. Keep your own copy if you need a later comparison.
The ten-minute capture retention period is separate from snapshotAgeMs. That metric describes the age of the authoritative multiplayer state received by the game, not how long the diagnostic report has been stored. Check the actual capture time when judging whether a diagnostic report is current.
4. Separate rendering hitches from network movement
If the whole image stalls, inspect frame intervals, CPU work, valid GPU timings and browser traces around the event. If rendering is smooth but remote players jump between positions, investigate request round-trip time, snapshot delivery and interpolation separately.
Both problems can happen together. Correlation in one capture suggests an experiment; it does not establish a cause. Render counters alone cannot prove the GPU is overloaded, and an absent GPU field cannot prove it is idle.
An explicit zero is also only as reliable as the instrumentation that supplied it. Do not infer zero network cost from a missing value, or assume that a rounded zero describes every request in the session.
5. Test one change and repeat the capture
| Evidence | Next experiment |
|---|---|
| High CPU work around a spawn wave | Profile animation updates, collision queries and allocations during that wave |
| High submission cost with many repeated props | Compare a scene with fewer draws or instanced props, keeping the camera path fixed |
| High valid GPU timing | Compare reduced render resolution or a simpler shadow pass, then measure again |
| High snapshot age while rendering stays smooth | Inspect server tick and snapshot delivery intervals and the client interpolation path |
| Hitches only when an area first appears | Use browser network and performance traces to inspect loading, decoding and main-thread work |
A smaller texture download may help a loading bottleneck without changing steady-state FPS. If texture payload is the measured problem, see optimizing browser scene loading while preserving original textures.
Acceptance checklist
- The capture includes the reproducible symptom, on the affected device and build.
- Viewport, quality and camera path are recorded for the comparison.
- Missing metrics remain distinguishable from measured values.
- CPU submission, GPU execution, request RTT and snapshot age are interpreted separately.
- The proposed change has been measured again under comparable conditions.
- A clean result is limited to that capture rather than presented as proof for every player's device.
FAQ
Does a missing GPU measurement mean GPU cost is zero?
No. It means GPU execution time was not supplied reliably. Use available timings and counters to choose further profiling, without declaring a GPU bottleneck from those counters alone.
Does the tool repair stutter automatically?
No. It returns evidence and recommendations. Apply a justified change through your normal development workflow, then capture again.
Can I compare reports more than ten minutes apart?
Yes. Keep explicit reports on your side and submit them for analysis. Verify that they describe comparable builds and conditions; avoiding the capture expiry does not make old measurements representative of a changed game.