# Shadows of your models: modes in the passport

Choose how each model casts its shadow, once, in its passport; every engine (web, Godot, Unity, Unreal) applies the same
choice. Readable offline: `gripforge docs shadows`, or the MCP tool `gripforge_docs` (topic `shadows`).

## What it is for

A shadow is the most expensive thing a small object can ask of the renderer: each caster is drawn again from the light.
The module `render.shadows` (installed and on in every game, a module apart from `render.lod` and `render.optimize`)
decides, per model, whether it casts a live shadow, a spot on the ground, a shadow drawn once, or none — so that a scene
with thousands of pebbles, leaves and props keeps its frame rate without losing the shadows that are seen.

## The modes

| Mode | What the model does |
|---|---|
| `auto` (default) | the engines choose from the size of the model: under 0.3 m `disabled` (grass, pebbles), under 1.5 m `dynamic` (small scenery), else `enabled` |
| `enabled` | always a live shadow |
| `disabled` | never a shadow |
| `dynamic` | a live shadow while the frames are on time; cut while they are late (under 50 per second for two seconds), given back after a calm while |
| `cached` | drawn again only when the model or the light moves (engines without that: `enabled`) |
| `blob` | no live shadow, a dark spot on the ground under the model (small movers, crowds) |
| `baked` | the fixed scenery drawn once into a static shadow map while the scene loads (engines without that: `enabled`) |

Defaults by archetype, never by game: a character or a vehicle is `enabled` (never deduced from its size).

## The passport section

```json
{ "kits": { "shadows": { "mode": "dynamic", "fallback": "blob" } } }
```

| Key | Meaning |
|---|---|
| `mode` | one of the modes above (default `auto`) |
| `fallback` | `blob`: a `dynamic` shadow that is cut becomes a blob instead of vanishing |
| `force` | `auto` takes `enabled`: not deduced from the size, never cut |
| `archetype` | the archetype whose default mode it takes (`characters`, `vehicles`, `props`, `vegetation`, `structures`) |

A game keeps only the keys that depart from the defaults, in its own `asset_passports` documents (key by key over the
global passport); nothing is copied. Never write a shadow setting model by model in a game: change the passport.

## Settings of the module

The kit `render.shadows` holds the settings the engines read in one `state()` (view `render.shadows.state`), GripForge's
defaults first, the game's config over them, then the mods, then what the debug panel (F3) switches at run time:

| Setting | Meaning | Default |
|---|---|---|
| `enabled` | the whole module (false: every shadow stays live, as the files say) | true |
| `disabledBelow` | a model under this diameter (metres) casts no shadow when nothing else says otherwise | 0.3 |
| `dynamicBelow` | under this diameter its shadow is dynamic, over it live | 1.5 |
| `bakeScenery` | the fixed scenery with no mode of its own goes into the baked map | false |
| `lightStep` | degrees the light turns before the baked map is made again | 0.5 |

```json
{ "dynamicBelow": 2.5, "rules": { "grass": { "mode": "disabled" }, "crowd": { "mode": "blob" } } }
```

An entity departs from the defaults by (each over the previous) the passport section, the rules (config `rules`, the
registry `shadow_rules` a mod extends), the tags `shadows.<mode>` (`shadows.off` = disabled), `setEntity` at run time and
the hook `render.shadows.entity`. A mod changes any of it: `{ "requires": { "render.shadows": "^1" }, "config":
{ "render.shadows": { "bakeScenery": true } } }`. `gripforge` and the MCP tools list the kit like the others
(`gripforge kits`, `gripforge_kit_info`) and install or configure it by its id.

## In the game copy

The build writes the resolved mode into the `gf_lod` extras of every mesh of the copy (`shadow`, `shadowFallback`), which
the engines read through the shared library (`gfo_shadow_mode`). `gripforge lod` makes the same copy on your machine, with
the same key: a model whose shadow mode changes is a new copy.