web-game-performance-and-testing
Use when working on any browser game (Phaser, PixiJS, three.js, Babylon.js, PlayCanvas, Excalibur, KAPLAY) - requestAnimationFrame with clamped delta and visibility pause, zero-allocation frame loops, measuring in DevTools, bundle and asset size budgets, Vitest with seeded RNG and injected time, and a seeded Playwright smoke test with console capture.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- web-game-performance-and-testing
- source
- informed by the MDN, Chrome DevTools, Vite, Vitest and Playwright documentation; own wording
- category
- performance
- tech_stack
- Web 2D
- description
- Use when working on any browser game (Phaser, PixiJS, three.js, Babylon.js, PlayCanvas, Excalibur, KAPLAY) - requestAnimationFrame with clamped delta and visibility pause, zero-allocation frame loops, measuring in DevTools, bundle and asset size budgets, Vitest with seeded RNG and injected time, and a seeded Playwright smoke test with console capture.
03 SKILL.md 正文
Web Game Performance and Testing
Overview
A browser game shares a thread with the page, a garbage collector with every closure, and a download budget with the player's patience. It is also the easiest kind of game for you to verify end to end on this machine: the build, the unit tests and a real browser run are all available. Use them.
Core principle: No allocations in the frame loop, a measured bundle, rules tested in Vitest with injected time and a seed, and one seeded Playwright smoke test that fails on console errors.
The frame loop in the browser
- Drive it with
requestAnimationFrame(or the engine's loop built on it); neversetInterval. - Browsers throttle or stop rAF in hidden tabs: clamp the delta (≤ 0.25 s), pause the simulation on
document.visibilitychange, and resume without a catch-up burst. - Fixed-step simulation with an accumulator and interpolated rendering (game-loop-and-time); engines with built-in physics steps (Phaser Arcade) already do this for bodies.
- Audio needs a user gesture: create or
resume()theAudioContexton the first click/key/tap. - On touch devices the canvas sets
touch-action: noneso gestures do not scroll or zoom the page.
No garbage in the loop
// ❌ allocates every frame: new vectors, arrays, closures
function update(dt: number) {
const dir = new THREE.Vector3().subVectors(target.position, enemy.position).normalize();
enemies.filter((e) => e.alive).forEach((e) => e.step(dt));
hud.setText(`Score: ${score}`);
}
// ✅ reuses module-level temporaries; plain loops; updates text only on change
const tmp = new THREE.Vector3();
let shownScore = -1;
function update(dt: number) {
tmp.subVectors(target.position, enemy.position).normalize();
for (let i = 0; i < enemies.length; i++) if (enemies[i].alive) enemies[i].step(dt);
if (score !== shownScore) { shownScore = score; hud.setText(`Score: ${score}`); }
}
Pool bullets, particles and damage numbers; prefer typed arrays (Float32Array) for large particle or boid sets; avoid Array.prototype.map/filter/forEach with fresh closures in hot paths.
Measure
- Chrome DevTools Performance: record 5–10 s of the changed scene, read frame times and the Bottom-up tab; look for GC events (
Minor GC) in the frame track. - Memory: heap snapshot before entering and after leaving a level — growth means a leak (undisposed textures, listeners left on a global emitter, pooled objects never released).
- Engine counters:
renderer.info(three.js), Babylon Inspector statistics, PixiJS devtools, Phaser's debug FPS. - In code:
performance.mark/performance.measurearound a system to get numbers into a test or log. - Never take frame-rate numbers from headless Chromium — it renders WebGL in software. Report numbers from a real browser profile, or say you could not.
Bundle and assets
- Read the build output:
npm run buildlists chunk sizes; addrollup-plugin-visualizeronly if the repository already has it. - Keep the engine and the first scene in the initial chunk; split later levels with dynamic
import(). - Textures: atlases and compressed formats (KTX2 for 3D, WebP/AVIF for 2D); audio: compressed (OGG/Opus plus an AAC/M4A fallback where Safari needs it).
- Respect the repository's size budget; without one, report the initial JS gzip size and the first-scene asset weight in the closing message when you changed either.
Vitest for rules
// src/logic/rng.ts
export function mulberry32(seed: number) {
return () => { seed |= 0; seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
}
// src/logic/spawner.test.ts
import { describe, it, expect } from "vitest";
import { Spawner } from "./spawner";
import { mulberry32 } from "./rng";
describe("Spawner", () => {
it("spawns one wave every 5 seconds regardless of step size", () => {
const a = new Spawner({ waveEverySeconds: 5 }, mulberry32(1));
const b = new Spawner({ waveEverySeconds: 5 }, mulberry32(1));
for (let i = 0; i < 600; i++) a.step(1 / 60);
for (let i = 0; i < 300; i++) b.step(1 / 30);
expect(a.wavesSpawned).toBe(2);
expect(b.wavesSpawned).toBe(2);
});
it("is deterministic for a seed", () => {
const run = () => { const s = new Spawner({ waveEverySeconds: 1 }, mulberry32(42)); for (let i = 0; i < 180; i++) s.step(1 / 60); return s.positions(); };
expect(run()).toEqual(run());
});
});
- Rules never import the engine, so tests run in Node without a canvas. Don't mock Phaser or three.js to test a scene — move the rule out.
- Time is a parameter; where a module genuinely uses timers,
vi.useFakeTimers()andvi.advanceTimersByTime(ms). - Babylon scene logic can run under
NullEnginein Vitest.
Playwright smoke test (seeded)
// e2e/smoke.spec.ts
import { test, expect } from "@playwright/test";
test("boots, takes input, no console errors", async ({ page }) => {
const errors: string[] = [];
page.on("pageerror", (e) => errors.push(e.message));
page.on("console", (m) => { if (m.type() === "error") errors.push(m.text()); });
await page.goto("/?seed=42&scene=Level1&debug=1");
await expect(page.locator("canvas")).toBeVisible();
await expect.poll(() => page.evaluate(() => (window as any).__GAME__?.ready)).toBe(true);
await page.keyboard.press("Space");
await expect.poll(() => page.evaluate(() => (window as any).__GAME__?.player.jumps)).toBe(1);
await page.screenshot({ path: "test-results/level1-after-jump.png" });
expect(errors).toEqual([]);
});
- A
window.__GAME__read-only debug handle exposed only in debug/dev builds lets tests assert state instead of guessing from pixels. - Fixed seed and a direct scene parameter make runs reproducible. Pixel comparisons (
toHaveScreenshot) only with the loop paused on a deterministic frame and a tolerance; GPU differences make exact matches flaky. - Run it the way the repository does (
npx playwright test); if Playwright is not set up and not installed, use the browser tools and say what the smoke run would have covered (game-visual-self-review).
Common Mistakes
setIntervalloops; unclamped delta after a background tab.- Temporaries allocated per frame in vector math.
- Unit tests importing the engine and failing for lack of WebGL.
- Smoke tests without a seed, flaking on random spawns.
- Judging performance from a headless browser.
Red Flags
newinside the rAF callback or a system'supdate.- A Playwright test with no
pageerrorlistener. - A bundle that grew by hundreds of KB for a small feature, unmentioned in the closing message.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns