# Fullscreen

Let your game request and toggle fullscreen through the Wavedash SDK

Source: https://docs.wavedash.com/sdk/fullscreen

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.

<Tip>
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).
</Tip>

## Going fullscreen

Call `requestFullscreen(true)` from inside a user-gesture handler (a click, keypress, or pointer event). 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 input.

<CodeGroup>
```gdscript Godot
func _on_fullscreen_button_pressed():
    var ok = await WavedashSDK.request_fullscreen(true)
    if not ok:
        show_retry_hint()
```

```csharp Unity
public async void OnFullscreenButtonClicked()
{
    bool ok = await Wavedash.SDK.RequestFullscreen(true);
    if (!ok) ShowRetryHint();
}
```

```javascript JavaScript
button.addEventListener("click", async () => {
  const ok = await Wavedash.requestFullscreen(true);
  if (!ok) showRetryHint();
});
```
</CodeGroup>

Both `requestFullscreen` and `toggleFullscreen` resolve to `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.

<CodeGroup>
```gdscript Godot
await WavedashSDK.request_fullscreen(false)
await WavedashSDK.toggle_fullscreen()
```

```csharp Unity
await Wavedash.SDK.RequestFullscreen(false);
await Wavedash.SDK.ToggleFullscreen();
```

```javascript JavaScript
await Wavedash.requestFullscreen(false);
await Wavedash.toggleFullscreen();
```
</CodeGroup>

## Checking state

`isFullscreen()` returns the current state, mirrored from the Wavedash host page.

<CodeGroup>
```gdscript Godot
if WavedashSDK.is_fullscreen():
    hide_hud_chrome()
```

```csharp Unity
if (Wavedash.SDK.IsFullscreen())
    HideHudChrome();
```

```javascript JavaScript
if (Wavedash.isFullscreen()) {
  hideHudChrome();
}
```
</CodeGroup>

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 the fullscreen-changed event to keep in-game UI in sync — the payload carries `isFullscreen`.

<CodeGroup>
```gdscript Godot
WavedashSDK.fullscreen_changed.connect(_on_fullscreen_changed)

func _on_fullscreen_changed(payload):
    if not payload.isFullscreen:
        pause_game()
```

```csharp Unity
Wavedash.SDK.OnFullscreenChanged += payload => {
    if (!(bool)payload["isFullscreen"]) PauseGame();
};
```

```javascript JavaScript
Wavedash.on(Wavedash.Events.FULLSCREEN_CHANGED, (payload) => {
  if (!payload.isFullscreen) game.pause();
});
```
</CodeGroup>

<Note>
**Legacy compat (web):** the SDK also dispatches a standard `fullscreenchange` event on `document`, so existing JavaScript that already uses the native browser API keeps working without changes.

```javascript
document.addEventListener("fullscreenchange", () => {
  if (!document.fullscreenElement) game.pause();
});
```
</Note>

See [Best practices](/tutorials/best-practices#the-escape-key) for details on why Escape-to-exit-fullscreen needs special handling.