Best practices

Browser games have a few quirks that are easy to miss. These best practices will help you avoid the most common issues.

Shader stutter

WebGL and WebGPU shaders are compiled the first time they're drawn, which causes visible frame hitches. Warm them up during your loading screen by rendering every material off-screen before the game starts — in Unity call ShaderVariantCollection.WarmUp(), in Godot instantiate materials in a preload scene. See Shader stutter for the full cause, warmup strategies, and how to reproduce stutter during development (including the macOS Metal-cache gotcha).

The Escape key

Pressing Escape exits fullscreen and releases pointer lock before your game code sees the keypress. Don't use Escape as your pause key. Instead, listen for the browser events:

document.addEventListener("fullscreenchange", () => {
  if (!document.fullscreenElement) game.pause();
});
document.addEventListener("pointerlockchange", () => {
  if (!document.pointerLockElement) game.showMenu();
});

Audio on Safari

Safari won't play any audio until the user interacts with the page. You need to resume the audio context on the first click or tap:

document.addEventListener("click", () => {
  if (audioContext.state === "suspended") audioContext.resume();
}, { once: true });

If you're using Unity, switch audio clips to Compressed in Memory instead of "Decompress on Load" — it uses dramatically less memory. Also use AAC/M4A instead of OGG since Safari doesn't support OGG natively.

Memory in long sessions

WebAssembly memory can only grow, never shrink. Games that load and unload assets over a long play session will fragment memory until the tab eventually crashes.

• Load assets in groups that get unloaded together
• Monitor memory with Chrome DevTools or Unity's Profiler
• Test 30+ minute sessions, not just quick launches

Before you launch

A quick checklist to run through before publishing:

• Title, description, screenshots, and tags are set
• Production build uploaded with debug flags off
• Tested on wavedash.com in Chrome, Firefox, and Safari
• SDK features work (leaderboards, achievements, saves, multiplayer)
• Audio plays correctly after first interaction
• Load time and frame rate are acceptable