# One quality tier and one look for the whole game (render.realism)

## What it is for

`render.realism` is a switch, not a renderer. You choose a quality tier (`performance`, `balanced` or `quality`) and, if you want,
a lighting look; when the game starts the kit hands the matching configuration to `world.lighting` and the matching level-of-detail
profile to `render.lod`. The tier sets the shadow map size, the number of point and spot lights, ambient occlusion, a light bloom
and a gentle colour grade, and the `render.lod` profile (`low`, `medium` or `high`). It draws nothing itself, never edits your
assets and decides nothing about your gameplay.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "render.realism" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "render.realism",
                              config: { "quality": "quality", "lighting": "golden_hour" } }
```

It requires `world.lighting`, `render.lod` and `game.engine`.

## First example

<!-- test: kits/render_realism/tests/render_realism.rs::the_default_is_balanced_and_keeps_the_look -->
With no configuration, the kit is on `balanced` and keeps the authored look: `render.realism.profile()` answers
`{ "quality": "balanced", "lighting": "preserve" }`, `render.lod.profile()` answers `"medium"`, and nothing is logged as an error.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `quality` | `performance`, `balanced`, `quality` | `balanced` | the tier: lighting budget and level-of-detail profile |
| `lighting` | `preserve`, `daylight`, `golden_hour`, `overcast`, `night` | `preserve` | the look; `preserve` keeps the light direction and colours you authored |

What each tier configures:

| Quality | `render.lod` profile | Shadow map | Point lights | Spot lights | Ambient occlusion |
|---|---|---|---|---|---|
| `performance` | `low` | 1024 | 2 | 0 | off |
| `balanced` | `medium` | 2048 | 3 | 1 | on, medium |
| `quality` | `high` | 4096 | 6 | 2 | on, high |

Any `lighting` other than `preserve` becomes the lighting preset of `world.lighting`. Both settings are moddable.

## Services, events, variables

The service `render.realism`:

- `profile()`: the effective configuration `{ quality, lighting }`.
- `plan(document, request)`: edits a whole scene document; it is served by the Studio, and the native kit host answers an error.

The kit emits no event and defines no variable.

## Hooks and modding

There are no hooks: the kit decides nothing of the game. A game or a mod chooses the tier and the look by changing `quality` and
`lighting`.

## Engines

The kit runs on the web and in the native host, where it calls `world.lighting.configure` and `render.lod.setProfile` once at
start. What the lighting and the levels of detail look like then depends on those two kits and on the engine.

## When it does not do what you expect

- Nothing changes: `world.lighting` or `render.lod` is missing. The kit logs an error and configures nothing, but `profile()` still
  answers.
- An invalid value for `quality` or `lighting`: the kit logs "Invalid render.realism configuration." and configures nothing.
- The light keeps its authored direction: `lighting` is `preserve`.
- `plan` answers an error outside the Studio: it is not served by the kit host.

## Limits

- Two settings only; for finer control, configure `world.lighting` and `render.lod` directly.
- It configures once at start; it does not react to the frame rate while playing.

## Versions

Kit version 1.1.0 (service contract 1.0.0). 1.1.0 attached the kit to `game.engine` and declared its settings moddable.