For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sound

Audio assets, one volume controller for mute, pause, ads and the platform audio state, and browser autoplay.

Sound is required — music, effects for actions and interface sounds — and so is its control: a mute button, silence during ads and in the background, and respect for the platform's own mute. Both missing sound and sound that keeps playing when it should not are among the most common reasons a game is sent back. The rules are in section 3.3 of the User Experience Requirements and item 2.1.6 of the Advertising and Payments Requirements.

Get good audio

  • Use recorded or professionally produced sound: a licensed or free (CC0) sound library, a composer, or a dedicated audio generation tool. Sound synthesized in code — procedural Web Audio tones, including those an AI coding agent writes — is not accepted (item 3.3.2).

  • Choose sounds in one style, normalize their loudness, and keep effects short so they do not pile up.

  • Give the game a music track for menus and one for gameplay at least; loop it without an audible gap.

  • Ship compressed files: OGG or MP3 for music, short OGG/MP3 or an audio sprite for effects. Never ship WAV — it multiplies the download size and the load time.

  • Load the music after game_ready instead of before it: the player should not wait for a soundtrack to start playing (see Performance & Optimization).

One volume controller

Most sound bugs come from several places muting and unmuting the game independently. Keep one controller that owns the master volume and computes it from all the reasons the game must be silent:

Reason
Where it comes from

The player pressed the mute button

the game's own setting, saved through Storage

The platform muted the game

platform.isAudioEnabled at startup, then AUDIO_STATE_CHANGED

The platform paused the game

A full-screen ad is open

interstitial state and rewarded state opened until closed, rewarded or failed

The page is hidden

document.visibilitychange

The game is audible only when none of these applies. When the last reason goes away, the controller restores the volume — and it never turns sound on just because one of the reasons cleared while another still holds.

  • Read platform.isAudioEnabled once at startup, before any sound plays: the event only reports later changes (item 3.3.4). A game reloaded while the platform is muted must stay silent.

  • Stop the game loop together with the sound when the game is paused by the platform or by an ad (item 2.1.6).

  • The mute button (item 3.3.3) controls only the player's own reason; it is shown on the main menu and in the pause menu.

Browser autoplay

Browsers block audio until the player interacts with the page. Create or resume the AudioContext (or call your engine's audio unlock) in the first pointerdown/keydown handler, and do not try to play music on the loading screen before that. On iOS, resume the context again when the page becomes visible — Safari can leave it suspended after the page was in the background.

Check before uploading

  • The game is silent from the first frame when started with the platform muted, and after a reload in that state.

  • Sound stops when the tab is hidden or the browser is minimized, and comes back when the player returns (item 3.3.5).

  • Sound and gameplay stop during every interstitial and rewarded ad and resume after it.

  • The mute button works, and its state survives a reload.

Last updated