Advanced lighting in your game (render.raytrace) #

You declare the lighting mode of your game once; each engine applies it with its own tool. Readable offline: gripforge docs render-raytrace, or the MCP tool gripforge_docs (topic render-raytrace).

What it is for #

The kit decides whether the advanced lighting path (global illumination by ray tracing) is used, and publishes the answer; the engine applies it through its adapter: solari in the Bevy player, sdfgi in Godot, hdrp-rt in Unity, lumen in Unreal. The engine only reports facts (what it loaded, what the GPU supports); it never decides. The default is the raster rendering: a game that does not ask for anything draws as before. Where the advanced path cannot run (the web players have no ray tracing, an adapter is missing, the GPU is too old) the raster rendering takes over with a reason; the game never gets an error for it.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "render.raytrace" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "render.raytrace",
                              config: { "mode": "auto" } }

It requires game.engine. mode is off (default), auto (advanced where the engine reports it can) or on (asked for; the raster rendering still takes over, with the reason, where the engine cannot).

First example #

<!-- test: kits/game_engine/host/tests/render_raytrace.rs::raster_is_the_default_and_the_decision_follows_the_report --> With { "mode": "on" } and an engine that reported { engine: "bevy", target: "native", loaded: true, supported: true }, state() answers active: true, path: "raytraced", adapter: "solari", reason: "requested". If the same engine reports target: "webgpu", active is false and reason is "web-no-ray-tracing".

Configuration #

raster is what the engine changes of its own raster rendering while the advanced path is active; when it is not, the engine keeps its own settings and state().raster is empty. With the Godot adapter (sdfgi) state().raster only carries msaa and ssao: its global illumination lights the indirect light only, so the sun keeps its shadow maps and Godot keeps its probes and HDR. Every key is moddable.

The decision #

In this order: mode off gives raster (off); no report from the engine gives raster (engine-unreported); a web target gives raster (web-no-ray-tracing); an adapter that is not loaded gives raster (adapter-not-implemented for Unity and Unreal, adapter-missing otherwise); a GPU or a renderer that does not support it gives raster (gpu-unsupported, the engine's detail says why); auto on a GPU that emulates ray tracing (the report's hardware: false: Apple M1, M2) gives raster (gpu-software-ray-tracing; on and a tap of the hook still turn it on); otherwise the advanced path is active (requested for on, auto-capable for auto).

History resets #

The advanced path accumulates light over frames. After a camera cut, a sudden change of light or a new scene that history must restart, otherwise the image ghosts. The kit listens to the topics of resetOn, raises the history generation and emits raytrace.history.reset { generation, reason } (the reason is the topic). camera.cut and lighting.cut are generic topics: a camera kit, a lighting kit, your game or a mod emits them at the right moment. resetHistory(reason) does the same by hand.

Hook, mods, service #

A tap of the hook can never make active an engine that reported it cannot (not loaded, not supported, web).

Service render.raytrace: state(), setMode(mode), setProfile(partial | null), resetHistory(reason), reportEngine(report), engineReport().

state() answers { epoch, mode, active, path, adapter, reason, detail, profile, raster, history, adapters, engine }. path is raster or raytraced; adapters lists the adapter of each engine and whether it is implemented; engine is the last report or null.

Engines #

Godot #

The Godot adapter applies the decision with Godot's own global illumination, on the Forward+ renderer:

• profile.gi: "dynamic" (default): Environment.sdfgi_enabled with cascades, cellSize (sdfgi_min_cell_size), occlusion and bounce (sdfgi_bounce_feedback). Good for open and large scenes that change.
• "volume": a VoxelGI over the bounds of the scene, baked when it turns on (and again on a history reset). Good for small closed scenes.
• "baked": the LightmapGI nodes your game baked in the Godot editor are shown. Good for static scenes; nothing is baked at run time.
• raster.ssao: false turns SSAO and SSIL off, raster.msaa sets the viewport's 3D multisampling, profile.taa its TAA. When the module turns the advanced path off, every value the adapter changed is given back.
• History reset (history.generation): SDFGI is switched off for one frame so Godot rebuilds its cascades; a VoxelGI is baked again. Never guessed from the camera.

On the Compatibility or Mobile renderer (and in a web export) the adapter reports supported: false with the renderer in detail: the module answers raster. The decision, the report and the adapter's counters (technique, renderer, historyResets, voxelBakes) are in the debug snapshot under render.extra.raytrace.

When it does not do what you expect #

<!-- kit-services:begin -->

Services this kit uses (and that you can provide) #

This kit consumes no service from another kit. <!-- kit-services:end -->