# Graphics settings of the player (settings.graphics)

The Graphics tab of the Options screen: quality preset, resolution, window mode, VSync, frame rate limit, render scale, shadows,
anti-aliasing, view distance, field of view and brightness. Readable offline: `gripforge docs settings-graphics`, or the MCP tool
`gripforge_docs` (topic `settings-graphics`).

## What it is for

The kit is the player's graphics preferences, applied natively by each engine. Each option appears only where the target supports it.
Only what the player changed is applied, so the game keeps its own tuning until then. The choices are saved in the player settings
(`gripforge.settings/<project>/settings.graphics`), outside game saves, and applied again at the next start.

It is installed by default in every new game, with `ui.menu`, `input.remap`, `audio.core` and `i18n.text`. Remove it only when asked.
It requires `game.engine`; the tab lives in `ui.menu`.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "settings.graphics" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "settings.graphics",
                              config: { "defaults": { "preset": "medium", "fpsLimit": 60 }, "hidden": ["fov"] } }
```

Only the keys that differ from the defaults need to be written. The full reference is `gripforge kit api settings.graphics`.

## Options

| Option | Values | Web | Godot | Unity | Unreal |
| --- | --- | --- | --- | --- | --- |
| `preset` | `low`, `medium`, `high`, `ultra` (`custom` once an option is changed by hand) | yes | yes | yes | yes, with scalability |
| `resolution` | `native`, `1280x720`… | no | window size | `Screen.SetResolution` | game user settings |
| `windowMode` | `fullscreen`, `borderless`, `windowed` | fullscreen or windowed | display server | full screen mode | window mode |
| `vsync` | on, off | no | display server | v-sync count | game user settings |
| `fpsLimit` | unlimited, 30, 60, 120, 144, 240 | play loop | max fps | target frame rate | frame rate limit |
| `renderScale` | 50 to 100 % | pixel ratio | 3D scale of the viewport | URP render scale (hidden without URP) | resolution scale |
| `shadows` | off to ultra | shadow map on / size | lights and shadow atlas | quality shadows | shadow quality |
| `antialiasing` | `off`, `fxaa`, `msaa2`, `msaa4`, `taa` | no | MSAA, FXAA, TAA | MSAA | method and quality |
| `viewDistance` | 50 to 200 % | camera far and fog | camera far | camera far and LOD bias | view distance quality |
| `fov` | 80 to 130 % | camera field of view | camera field of view | camera field of view | camera manager |
| `brightness` | 50 to 150 % | exposure | environment brightness | light and ambient intensity | display gamma |

Presets set render scale, shadows, anti-aliasing and view distance: low is 70 %, off, off, 60 %; medium 85 %, medium, FXAA, 80 %; high
100 %, high, MSAA 2x, 100 %; ultra 100 %, ultra, MSAA 4x, 150 %. Changing one of them by hand switches to `custom`.

## Settings and defaults

| Key | Default | Meaning |
| --- | --- | --- |
| `defaults` | high preset, native resolution, windowed, VSync on, unlimited frame rate, render scale 100 % | what the tab shows before the player changes anything |
| `hidden` | `[]` | options never shown |
| `only` | `[]` | when set, only these options are shown (among those the target supports) |
| `resolutions` | `1280x720`, `1600x900`, `1920x1080`, `2560x1440`, `3840x2160` | offered besides native; engines keep those the screen can show |

## Rows from other kits

A kit adds rows to this tab by exposing, on its capability service, `graphicsFields(lang)`, `setGraphicsOption(id, value)` and
optionally `resetGraphicsOptions()`, and by calling `registerSection('<capability>')`. The rows appear before Restore defaults, with
ids `<capability>/<id>`, and are reset with the tab. `render.lod` (its level of detail profile) is looked up without registration.
Neither kit requires the other.

## Service, events, variables

Service `settings.graphics`: `get(field)`, `values()`, `chosen()` (what the player changed), `set(field, value)`, `setPreset(p)`,
`presets()`, `supported()`, `resolutions()`, `setResolutions(list)`, `reset()` (the engine settings the kit changed are restored),
`reload()`, `registerSection(capability)`, `sections()`; options tab `graphics` (`optionFields(lang)`, `setOption(id, value)`). Events:
`graphics.changed { changes, preset }`, `graphics.reset`. Variables: `graphics.preset`, `graphics.resolution`, `graphics.windowMode`,
`graphics.vsync`, `graphics.fpsLimit`, `graphics.renderScale`, `graphics.shadows`, `graphics.antialiasing`, `graphics.viewDistance`,
`graphics.fov`, `graphics.brightness`.

## Hooks and modding

A graphics option is the player's choice, not a decision of the game, so the kit declares no hook. A mod may override `defaults` (a
default preset, a frame rate limit) and `resolutions`; the values stay bounded by the config schema. `hidden` and `only` are not
moddable: the game decides which options the player gets. What the player chose always wins over the defaults, modded or not.

```json
{ "schema": "gripforge.mod/1", "id": "light_start", "name": "Light start", "version": "1.0.0",
  "requires": { "settings.graphics": "^1" }, "config": { "settings.graphics": { "defaults": { "preset": "medium" } } } }
```

## When it does not do what you expect

| Symptom | Cause and fix |
| --- | --- |
| An option is missing | the target does not support it (VSync and resolution on the web), or `hidden` / `only` removes it |
| The game ignores `defaults` | the player already changed that option: the saved choice wins; `reset()` clears it |
| The preset says `custom` | an option was changed by hand after choosing it |
| Render scale is missing on Unity | it needs URP |
| A kit's row is missing | the kit did not call `registerSection` |