web-games – Design & UI skill for AI agents

Web Browser Game Development

> Framework selection and browser-specific principles. For stack choice details see game-development/engine-selection.

---

1. Framework Selection

Decision Tree

What type of game?
│
├── 2D Game
│   ├── Full game engine features? → Phaser 4
│   ├── Fast prototype / jam?      → Kaplay
│   ├── Raw rendering power?       → PixiJS 8
│   └── Tiny / no dependency?      → Raw Canvas / WebGL
│
├── 3D Game
│   ├── Full engine (physics, XR)? → Babylon.js
│   └── Rendering focused?         → Three.js
│
├── Hybrid (DOM UI + canvas moments)
│   └── Custom shell + guest viewport
│       (Canvas/Kaplay/Phaser/Pixi inside a region/modal)
│
└── Narrative-first
    └── Ink (inkjs) or Twine export + DOM host

Comparison

| Framework | Type | Best For |

|-----------|------|----------|

| Raw Canvas / WebGL | 2D / low-level | Small scope, full control |

| Kaplay | 2D toolkit | Rapid prototypes |

| Phaser 4 | 2D engine | Full game features |

| PixiJS 8 | 2D renderer | Rendering, custom systems |

| Three.js | 3D renderer | Visualizations, lightweight 3D |

| Babylon.js | 3D engine | Full engine, XR |

Hybrid shell + guest

Use when chrome is HTML (menus, inventories, text, dashboards) but bursts of play need a canvas:

1. Mount guest in a container; pass context in.

2. Run a local game loop in the guest.

3. Return results (score, pass/fail); destroy guest (RAF, listeners, GL context as needed).

Do not let the guest own global app routing unless the product *is* a full-screen game.

---

2. WebGPU Adoption

Runtime support

WebGPU support depends on browser version, OS, adapter, driver and secure context; do not infer availability from a browser-name table or a historical global percentage. See [MDN WebGPU](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API).

Decision

• New GPU-heavy projects: Use WebGPU with WebGL fallback
• Broad legacy / simple 2D: Start with WebGL or Canvas 2D
• Feature detection: Check navigator.gpu, handle a null requestAdapter() result, device creation failures and device loss; offer a tested fallback

---

3. Performance Principles

Browser Constraints

| Constraint | Strategy |

|------------|----------|

| Local files require user-granted access or selected file input | Respect permissions; bundle public assets |

| Tab throttling | Pause when hidden (visibilitychange) |

| Mobile data limits | Compress assets |

| Audio autoplay | Require user interaction |

Optimization Priority

1. Asset compression - KTX2, Draco, WebP

2. Lazy loading - Load on demand

3. Object pooling - Avoid GC

4. Draw call batching - Reduce state changes

5. Web Workers - Offload heavy computation

---

4. Asset Strategy

| Type | Format |

|------|--------|

| Textures | KTX2 + Basis Universal (or WebP/PNG for simple 2D) |

| Audio | WebM/Opus (fallback: MP3) |

| 3D Models | glTF + Draco/Meshopt |

| Phase | Load |

|-------|------|

| Startup | Core assets, <2MB |

| Gameplay | Stream on demand |

| Background | Prefetch next level |

---

5. PWA for Games

Benefits: offline play, install, fullscreen, optional push.

Installation: requirements vary by browser; use an appropriate web app manifest and secure context. A service worker is useful for offline behavior but is not universally an installation prerequisite. Explicitly implement and test cache/version updates and offline recovery; installation alone does not provide offline gameplay. [Installability guidance](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable).

---

6. Audio Handling

• Create/resume AudioContext on first click/tap
• Prefer Web Audio API; reuse decoded AudioBuffers, but create a new AudioBufferSourceNode for each playback (source nodes are one-shot); preload common SFX
• Compress with WebM/Opus when possible

---

7. Anti-Patterns

| ❌ Don't | ✅ Do |

|----------|-------|

| Load all assets upfront | Progressive loading |

| Ignore tab visibility | Pause when hidden |

| Block on audio load | Lazy load audio |

| Skip compression | Compress everything |

| Assume fast connection | Handle slow networks |

| Leave canvas engines running off-screen | Tear down guests |

---

> Remember: Browser is the most accessible platform. Respect its constraints.

When to Use

Use when building HTML5/WebGL/WebGPU games, choosing a browser runtime, or wiring hybrid DOM+canvas guests.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.