Wavedash owns the fullscreen target so our overlay UI (achievements, friends, game info) stays on top of your game when a player goes fullscreen. Your game requests fullscreen through the SDK; Wavedash does the actual fullscreen call on the wrapping element.
Wavedash already exposes player-facing fullscreen controls on every game page, so most games don't need to call these methods at all. Design your game to look right in the embedded frame, and reach for requestFullscreen / toggleFullscreen only when fullscreen is intrinsic to the experience (e.g. a dedicated "play in fullscreen" button or a presentation mode).
Going fullscreen
Call requestFullscreen(true) from inside a click, keydown, or pointerdown handler. The browser requires a fresh user gesture to enter fullscreen, so it can't be triggered from a timer or async callback far from the original click.
button.addEventListener("click", async () => {
const ok = await Wavedash.requestFullscreen(true);
if (!ok) showRetryHint();
});
Both requestFullscreen and toggleFullscreen return Promise<boolean> — true if the host entered/exited fullscreen, false if the browser rejected (most commonly because the call ran outside a user gesture).
Pass false to leave fullscreen. toggleFullscreen() flips whichever state you're in.
await Wavedash.requestFullscreen(false);
await Wavedash.toggleFullscreen();
Checking state
isFullscreen() returns the current state, mirrored from the Wavedash host page.
if (Wavedash.isFullscreen()) {
hideHudChrome();
}
Because the real fullscreen element lives in the host document, reading document.fullscreenElement directly from inside the iframe would normally always be null. The SDK patches that getter so the standard browser API also reports the correct state.
Reacting to fullscreen changes
Subscribe to FULLSCREEN_CHANGED with .on() — the payload is typed and unwrapped:
Wavedash.on(Wavedash.Events.FULLSCREEN_CHANGED, (payload) => {
if (!payload.isFullscreen) game.pause();
});
Legacy compat: the SDK also dispatches a standard fullscreenchange event on document, so existing code that already uses the native browser API keeps working without changes.
document.addEventListener("fullscreenchange", () => {
if (!document.fullscreenElement) game.pause();
});
See Best practices for details on why Escape-to-exit-fullscreen needs special handling.