Shadows
Usage guide of the render.shadows module: the shadow modes (auto, enabled, disabled, dynamic, cached, blob, baked), the passport section kits.shadows, archetype defaults, the game keeping only its departures, and how the game copy carries the mode to the four engines.
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 #
{ "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 |
{ "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.