debugging-performance-issues

Diagnose frame hitches, memory leaks, and accumulator bugs in Phaser browser games.

Updated Jun 10, 2026
One-click install
npx skills add https://github.com/mudman1986/quarterless --skill debugging-performance-issues-mudman1986
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debugging-performance-issues
Source: https://github.com/mudman1986/quarterless/tree/main/.github/skills/debugging-performance-issues
Command: npx skills add https://github.com/mudman1986/quarterless --skill debugging-performance-issues-mudman1986

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Runtime slowdowns, stutter, and jumpy movement in browser games are hard to root-cause because symptoms like frame hitches can come from simulation backlog, render growth, memory leaks, or storage stalls. This Skill provides a measurement-first workflow that isolates the actual failure bucket before any code is edited. ## Core Features & Use Cases - Measurement-First Diagnosis: Add temporary page-side probes with page.evaluate to capture scene children counts, pool lengths, world entity arrays, snapshot sizes, and timed calls around world.tick and persistence. - Fixed-Step Accumulator Analysis: Inspect frame delta clamping and MAX_SUBSTEPS backlog handling to find stale accumulator debt that causes jumpy movement after hitches, tab refocus, or GC pauses. - Regression Test Workflow: Build focused mechanical regressions (e.g., feeding repeated long deltaMs values) and red/green them by reverting the fix to confirm the test fails for the intended reason. - Use Case: A Phaser game gets progressively jumpier during long play sessions. Use this Skill to prove object counts stay flat, identify stale accumulator backlog as the root cause, and ship a fix with a stable regression test. ## Quick Start Use the debugging-performance-issues skill to diagnose why the game stutters and gets slower over long play sessions.

Frequently Asked Questions about debugging-performance-issues

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug frame hitches and stutter in a Phaser game?

Start with temporary page-side probes using page.evaluate to capture scene.children.list.length, entity pool sizes, and timed calls around world.tick and rendering. Separate symptoms that grow over time from work that is constant but too expensive before editing any code.

What causes jumpy movement in fixed-step game loops?

Jumpy movement often comes from stale accumulator debt: long frames hit MAX_SUBSTEPS, but leftover time stays in the accumulator, so later frames keep spending the maximum simulation budget. The fix is discarding stale backlog after the substep budget is exhausted.

Why does my browser game get slower over time without a memory leak?

Flat object counts with worsening performance point to frame pacing or persistence issues rather than leaks. Check synchronous localStorage writes and JSON.stringify of large world snapshots, and measure write duration and snapshot byte size before changing save cadence.

How do I write a regression test for a game performance bug?

Assert the mechanical invariant directly rather than visual smoothness, which is too flaky for browser tests. For accumulator bugs, feed repeated long deltaMs values and assert stale backlog stays below one fixed step, then red/green the test by reverting the fix.

When should I compare git history during performance debugging?

Compare history when the bug is not visible on main. First find when the broken invariant appeared, then find the later commit that made it observable through hitches or heavier per-frame work, since the trigger commit is often not the root cause.