# Fullscreen in your game (display.fullscreen)

## What it is for

The game in fullscreen: enter, leave and toggle, a rebindable key (F11), an optional start in fullscreen, an on-screen button and an Options entry. The kit decides and the host executes: the web page puts the game container (HUD included) in fullscreen, the native player switches its window. A browser only grants fullscreen on a player gesture, so a refused request is reported and sent again at the next gesture. The choice is saved in the player settings, outside game saves. It is installed by default in every new game.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "display.fullscreen" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "display.fullscreen",
                              config: { "atStart": false, "button": false } }
```

Needs `input.actions`, `game.engine`; installing the kit brings them along. Optional: `settings.graphics` (its display mode goes through this kit) and `ui.menu` (a Display tab in Options).

## First example

<!-- test: kits/game_engine/host/tests/parity.rs::rust_host_matches_the_typescript_traces (fixture display.fullscreen.flow) -->
The kit asks, the host answers. With the web page or the native window attached, the host reports what really happened, whoever caused it (the kit, the browser's Escape key, the window manager).

```text
call display.fullscreen.enter()          -> the request goes to the host
host  hostChanged(true)                  -> event fullscreen.changed { fullscreen: true }
call display.fullscreen.isFullscreen()   -> true
key   F11                                -> toggle() -> the host is asked to leave
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `atStart` | `false` | Ask for fullscreen when the game starts (on the web, sent at the first click or key). |
| `remember` | `true` | Save the player's choice and restore it at the next start (it then wins over `atStart`). |
| `button` | `false` | Show the kit's own fullscreen button in a corner of the game. |
| `menu` | `true` | Without `settings.graphics`, add a Display tab with the toggle to the Options of `ui.menu`. |

## Services, events, variables

- Service `display.fullscreen`: `enter()`, `exit()`, `toggle()`, `set(on)`, `isFullscreen()`, `wanted()`, `armed()`, `available()`, `state()`, `reload()`. Host side: `attach(port)`, `hostChanged(on)`, `hostRefused(reason)`, `gesture()`, `hostCalls()`.
- Events: `fullscreen.changed` (`fullscreen`), `fullscreen.refused` (`reason`: unavailable, gesture or denied; `armed`: true when it will be sent again at the next gesture). It listens to `graphics.changed`.
- Variables: `display.fullscreen`, `display.fullscreen_available`.

## Hooks and modding

This kit has no hook: it decides nothing of the game. A game or a mod changes its behaviour through the settings.

## Limits

Web: the Fullscreen API on the game container. Native player: its window. Godot, Unity and Unreal: a component applies the mode with the engine's own window settings and reads it back every frame; the window itself needs a display.

## Versions

Kit 1.1.0 (1.1.0 declared the settings moddable, no change of behaviour); service `display.fullscreen` 1.0.0. It relies on `input.actions` ^1 and `game.engine` ^1.