game-client
Skill26 starsChanged yesterdayMITView on GitHub
Builds the browser client of a game in TypeScript under Bun, on plain Canvas/WebGL, Phaser, PixiJS, or Three.js and React Three Fiber: choosing the stack, the frame loop, hidden-tab pause and resync, keyboard, pointer, touch and gamepad input, audio unlock, canvas sizing, context loss, asset cleanup and performance budgets. Use when starting or fixing the part of a web game that runs in the player's browser: picking a rendering stack, wiring input or the render loop, a blurry or stretched canvas, silent audio, a game that jumps or leaks after switching tabs or scenes, or code written for Phaser 3, PixiJS 7 or an older three.js.
In this repository46 other files it gives its agents.
- asaasSkill
- betterauth-integrationSkill
- bullmq-game-queuesSkill
- character-design-narrativeSkill
- ci-cd-gameSkill
- claude-agent-sdkSkill
- database-performance-tuningSkill
- elevenlabs-sound-musicSkill
- foundry-vtt-devSkill
- game-anti-cheatSkill
- game-backend-architectureSkill
- game-blenderSkill
- game-design-fundamentalsSkill
- game-architectSkill
- game-balanceSkill
- game-buildSkill
- game-expandSkill
- game-loreSkill
- game-questSkill
- game-reviewSkill
- game-devSkill
- game-economy-designSkill
- game-godotSkill
- game-localizationSkill
- gameplay-analyticsSkill
- game-save-loadSkill
- game-state-syncSkill
- game-unitySkill
- judgeSkill
- level-designSkill
- matchmaking-systemSkill
- mmo-designSkill
- monitoring-game-opsSkill
- nuvemshop-sdkSkill
- openclaw-genieSkill
- postgres-game-schemaSkill
- procedural-genSkill
- quest-mission-designSkill
- quest-narrative-coherenceSkill
- react-animationsSkill
- redis-game-patternsSkill
- skill-progression-treesSkill
- story-structure-gameSkill
- stripe-game-paymentsSkill
- ui-ux-gameSkill
- worldbuildingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 86
Use texture atlases so sprites batch.
- Distinctive: line 94
No allocation in the frame loop: reuse vectors and arrays (R3F pitfalls).
- Very specific: line 95
Keep getError and getParameter out of the frame loop: they stall the calling thread.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Game Client
The client draws the world and collects input. In a multiplayer game the server owns the state (game-backend-architecture) and game-state-sync owns prediction, reconciliation and interpolation. This skill owns everything between those and the screen.
Checked against phaser 4.2.1, pixi.js 8.23.0, three 0.187.0 and @react-three/fiber 9.8.2 (bun pm view <pkg> version, 2026-11-14). An agent trained on an older major writes code that no longer runs; each stack's reference file lists those traps.
Choose the stack
The "what it is" column uses each project's own words. The "fits" and "avoid" columns are this skill's rule.
| Stack | What it is | Fits when | Avoid when |
| Plain web (Canvas 2D, WebGL2, WebGPU) | Browser APIs; you write the loop, input, loader and batcher | Few sprites, a custom renderer, a tool, a tight bundle | You find yourself writing a sprite batcher or scene graph |
| Phaser 4 | "A fast, free, and fun open source HTML5 game framework" with scenes, a loader, Arcade and Matter physics, input, cameras, tilemaps, tweens | A 2D game where you want the engine to own scenes, input and physics | You need 3D (v4 removed Mesh and Plane), or only a renderer under your own loop |
| PixiJS 8 | "Just a rendering engine" for 2D; sound, UI and layout are add-ons | A 2D game where you own the structure and want a fast batched renderer | You want scenes, physics and gamepad input built in |
| Three.js | "An easy-to-use, lightweight, cross-browser, general-purpose 3D library" | 3D with many server entities updated every snapshot | A 2D game |
| React Three Fiber | "A React renderer for three.js" | 3D inside an existing React app, mostly long-lived objects | Entities that spawn and despawn every snapshot (mounting compiles materials) |
Load one reference file for the chosen stack and skip the others.
Set up with Bun and TypeScript
- Plain web:
bun ./index.htmlserves and bundles the page with hot reloading;bun build ./index.html --outdir=distbuilds it. Details inreferences/web.md. - Phaser and PixiJS: scaffold with
bun create @phaserjs/game@latestorbun create pixi.js my-app --template bundler-vite. Their templates bundle with Vite; keep Vite and use Bun as package manager and runtime. No vendor source covers Bun's own bundler, so this is this skill's rule. - Three.js: install
threeand@types/threeat the same version. R3F: add@react-three/fiberand match React's major (fiber 9 needs React 19). - TypeScript: browser code needs
"DOM"inlib. Bun's recommended tsconfig lists only"ESNext". Give the client its own tsconfig so server code does not see DOM globals (this skill's rule).
Loop and timing
- The simulation runs on a fixed step.
ClientGameLoopingame-state-syncowns it: an accumulator overrequestAnimationFrame, a 250 ms cap per frame, prediction on each tick, and analphabetween the last two ticks. Do not write a second fixed-step loop. requestAnimationFramefollows the display rate, so a 120 Hz screen calls it twice as often as a 60 Hz one. Anything moved per frame moves by elapsed time, never a fixed amount.- Which loop owns the frame (this skill's rule):
- Plain web:
ClientGameLoopdoes. Set itsonRender(state, alpha)and draw there. - Phaser, PixiJS, Three.js, R3F: the engine runs the only frame loop. Never call
ClientGameLoop.start()and leaveonRenderunset. In the engine's per-frame hook, before it renders, callloop.step(now): it runs the due fixed ticks and returns the alpha. Then readloop.getRenderState()(previous and current state by reference, no copy) and the snapshot bracket fromgame-state-sync, and write transforms onto display objects. Each reference file names the hook.
- Plain web:
- The renderer reads state and never writes it. The WebSocket handler writes server state into the loop (
handleServerUpdate) and never touches display objects.
Pause and resync when the tab is hidden
Most browsers stop requestAnimationFrame in a background tab, while the server keeps simulating. Simulating the whole gap on return "can be a problem for long drops" (MDN). This skill's rule:
- On
visibilitychangeto hidden: stop the client loop, clear held input, suspend audio. - On visible: do not replay the gap. Drop stale interpolation snapshots, request a full snapshot, then restart the loop. When the snapshot carrying the server tick arrives, align the tick with
syncTick;handleServerUpdatealready adopts the server's tick when the client is behind.ClientGameLoop.start()resets the frame clock and the accumulator, so the first frame back runs no burst of ticks.
boilerplate/visibility-resync.ts does this for any loop with start() and stop(). In engine-driven mode, pass it gate = engineDrivenLoop(loop) from the same file and write the engine callback as if (!gate.paused) loop.step(now). The gate pauses stepping while the tab is hidden and during the resync, and resets the clock both ways, so the first step() back runs no catch-up ticks. The pause matters because Phaser resumes its loop, and the PixiJS ticker never stops, before the full snapshot arrives. Engine loops handle their own clocks: Phaser pauses its loop and emits RESUME, PixiJS does not pause its ticker itself (the browser throttles its frames), three.js Timer.connect(document) avoids the big delta. They do not resync with your server.
Input
- Keys by
KeyboardEvent.code, the physical key: WASD stays in place on an AZERTY layout. Usekeyonly for text entry such as chat. - Track held keys from
keydownandkeyup, and ignore events withrepeatset. OS auto-repeat is not a press. - Clear held keys on window
blurand on hidden: a key released while the window has no focus sends nokeyup(this skill's rule). - Pointer Events cover mouse, pen and touch with one model and a
pointerIdeach. CallsetPointerCaptureonpointerdownso a drag that leaves the canvas still delivers itspointerup. Treatpointercancellikepointerup(this skill's rule). - Touch gestures: set
touch-action: noneon the canvas so the browser does not pan or zoom. Window, document and body listeners fortouchstartandtouchmoveare passive by default and cannot callpreventDefault(); attach to the canvas. Pinch is the distance between two touch pointers. - Gamepads: poll
navigator.getGamepads()once per tick and read pads by index. Re-read the list on every poll rather than keeping aGamepadobject (this skill's rule).mapping === 'standard'means the standard button layout. Firefox exposes a pad only after the user presses something on it with the page visible. - Sample input inside
captureInputonce per tick, and turn it into a command with the tick and sequence number (game-state-sync). Send intents, never positions.
boilerplate/input-manager.ts implements all of this with no framework. It reads keys on window, ignores keys typed into text fields, and blocks arrow and Space defaults only while the canvas has focus (it gives the canvas tabindex 0 and focuses it on pointerdown), so buttons and page scrolling keep their keys. Phaser has its own keyboard, pointer and gamepad input; use that. With PixiJS, which has pointer events but no keyboard or gamepad input, keep the boilerplate's keyboard and gamepad parts. three.js has no input layer at all; use the whole boilerplate.
Audio unlock
An AudioContext created before a user gesture starts suspended; call resume() from a gesture and check state. Only some events count as activation: keydown, mousedown, pointerup from touch or pen, and touchend. A touch pointerdown does not count, so a "tap to start" button must listen for pointerup or click. The same rule applies to fullscreen and pointer lock. boilerplate/audio-unlock.ts resumes a context on the first qualifying gesture; it rejects and removes its listeners if the context is closed or its AbortSignal aborts. For music and effects themselves, see elevenlabs-sound-music.
Canvas size and devicePixelRatio
devicePixelRatiois the ratio of physical to CSS pixels. A canvas whose buffer matches its CSS size looks blurry on a 2x screen.- Size the drawing buffer from
ResizeObserverwith{ box: 'device-pixel-content-box' }, which gives exact device pixels; fall back to CSS size timesdevicePixelRatio. Cap the ratio: the three.js manual warns against blindly using the device ratio, and R3F clamps itsdprto[1, 2]by default. boilerplate/canvas-size.tsdoes this for plain web and three.js, re-applies on adevicePixelRatiochange (zoom, another monitor) through amatchMediaresolution query, and takes an optionalmaxSizecap. Its callback receives the buffer size in device pixels and must not touch the canvas's CSS size. With three.js:renderer.setPixelRatio(1), then in the callbackrenderer.setSize(w, h, false),camera.aspect = w / h,camera.updateProjectionMatrix(). ThefalsestopssetSizefrom writing the CSS size; without it the CSS box grows, the observer fires again, and on a 2x screen the buffer grows without end.- Phaser and PixiJS size their own canvas; use their options instead (see the reference files).
Context loss
- WebGL can lose its context, for example when the GPU runs out of memory. By default a lost context never comes back. In
webglcontextlost, callevent.preventDefault()and stop rendering; onwebglcontextrestored, re-create every texture, buffer, shader and program. - WebGPU: watch
device.lost, a promise that resolves when the device is lost, then rebuild. - Phaser, PixiJS and three.js own their GL objects; check each vendor skill before adding your own handler.
Assets: load and free
- Load per scene or screen, behind a loading screen with progress. Phaser has
this.load.on('progress'), PixiJS bundles withonProgress, three.js aLoadingManager. - GPU memory is not garbage collected for you. Free what a scene loaded when it ends: three.js
dispose()on geometries, materials and textures; PixiJSAssets.unloadanddestroy({ children: true }); Phaserthis.textures.remove(key), since its caches are global; plain webImageBitmap.close()and explicit WebGL deletes. - Pass one
AbortSignalto every listener a scene adds, and abort it when the scene ends (this skill's rule; thesignaloption ofaddEventListenerremoves them all). - Use texture atlases so sprites batch. Keep textures at or under 4096 px per side unless you query the GPU limit: larger ones fail on some mobile GPUs (PixiJS skill).
Performance budgets
- Frame budget: one display refresh, 16.7 ms at 60 Hz and 8.3 ms at 120 Hz. Measure on the weakest target device.
- Draw calls: a few hundred at most (Phaser rendering guide; R3F says 1000 is the very maximum). Instance or batch repeated objects.
- Batches: PixiJS batches up to 16 textures, depending on hardware; alternating blend modes split batches, so group children by blend mode (PixiJS skill).
- Text that changes every frame (ping, score, HP) goes in bitmap text; canvas text re-uploads a texture on each change (Phaser, PixiJS).
- No allocation in the frame loop: reuse vectors and arrays (R3F pitfalls). Pool entities that spawn often; R3F's pitfalls page says to re-pool objects to spare the garbage collector.
- Keep
getErrorandgetParameterout of the frame loop: they stall the calling thread.
Plain web
You own the loop, scenes and batching. Read references/web.md for Bun's HTML server, scene cleanup with AbortController, pointer lock and fullscreen, image decoding, and WebGPU status.
Phaser
Use the matching skill in node_modules/phaser/skills/<topic>/SKILL.md if it is installed, otherwise https://docs.phaser.io. What differs: delta is smoothed and clamped, scene operations are queued, caches are global, and listeners survive scene restarts. The official Bun template phones home through log.js. Read references/phaser.md for timing, cleanup, the interpolation hook and Phaser 3 traps.
PixiJS
Use the pixijs skill if it is installed (it ships in node_modules/pixi.js/skills/pixijs), otherwise https://pixijs.com/8.x/guides. What differs: await app.init(), no scene manager, no keyboard or gamepad input, no fixed step, and the ticker does not pause itself in a hidden tab. Read references/pixijs.md for ticker priorities, cleanup, the interpolation hook and PixiJS 7 traps.
Three.js and React Three Fiber
Use the threejs-fundamentals skill if it is installed, otherwise https://threejs.org/docs/llms.txt; for R3F the r3f-fundamentals skill if it is installed, otherwise https://r3f.docs.pmnd.rs/. What differs: setAnimationLoop, Timer instead of the deprecated Clock, manual dispose(), and in R3F no setState in useFrame. Read references/three.md for the plain-or-R3F choice, the interpolation hook and version traps.
Pitfalls
- Stepping the simulation once per
requestAnimationFrame: speed then depends on the screen's refresh rate. - Replaying a hidden tab's gap on return, or resuming without resyncing with the server.
KeyboardEvent.keyfor movement: it breaks on non-QWERTY layouts.- Unlocking audio or requesting fullscreen from a touch
pointerdown. - A canvas buffer at CSS size on a 2x screen, or an uncapped ratio on a 3x phone.
- No
preventDefault()inwebglcontextlost: the context never returns. - Removing objects from the scene and assuming their GPU memory is freed.
- Phaser
Text, PixiJSText: updating them every frame re-uploads a texture. - Code from an older major: Phaser 3, PixiJS 7,
THREE.Clock, R3F 8 types. Check the version traps in the reference file.
Files
boilerplate/input-manager.ts: copy when you need keyboard bycode, pointers with capture, pinch distance and gamepad polling without a framework.boilerplate/visibility-resync.ts: copy when the client loop must pause in a hidden tab and resync with the server on return.boilerplate/audio-unlock.ts: copy when a Web Audio context must resume on the first qualifying gesture.boilerplate/canvas-size.ts: copy when a plain-web or three.js canvas must track its CSS size in device pixels.references/web.md: read when the stack is plain Canvas, WebGL or WebGPU.references/phaser.md: read when the stack is Phaser 4.references/pixijs.md: read when the stack is PixiJS 8.references/three.md: read when the stack is Three.js or React Three Fiber.references/sources.md: read when you need the page behind a rule or want to re-check a version.
Related skills
game-state-sync: the fixed-stepClientGameLoop, prediction, reconciliation and snapshot interpolation this client plugs into.game-backend-architecture: the authoritative server, WebSocket rooms and tick loop the client talks to.ui-ux-game: HUD, menus, onboarding and accessibility drawn on top of the canvas.elevenlabs-sound-music: producing the sound effects and music the client plays.level-design: the levels the client loads and renders.game-save-load: saving and restoring client and player state.game-localization: translated text, fonts and layout in the client.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

