performance-development-guidelines

Clamp raw frame deltas with dt = Math.min(deltaMs / 1000, MAX_FRAME_DT), use fixed-step simulation with a cap on substeps per rendered frame, and drop stale accumulator backlog when the cap is reached so old time debt never carries forever.

Use persistent pools keyed by stable indices and hide surplus entries with setVisible(false) instead of creating or destroying game objects in steady-state loops. Allocate lazily only when an object can actually become visible, or preallocate with a measured upper bound.

localStorage is blocking, so serializing a full world snapshot with JSON.stringify stalls the main thread. Measure stringify size and time before increasing save cadence, and throttle autosaves to deliberate intervals.

Test that the accumulator stays bounded after long frames, pool sizes do not grow under repeated syncs, and expensive work like minimap redraws stays throttled. Red/green each regression by removing the fix, confirming failure, then restoring it.

Keep core gameplay rules in pure, Phaser-free modules covered by core tests, and limit Phaser code to rendering and input glue. This separation makes loop invariants cheap to test directly instead of relying on subjective visual symptoms.