Editor

Baked lighting in the editor

EditorPreview

Editor docs

The editor bakes light probes for a LightProbeVolume and assigns lightmaps to mesh renderers, with the engine's own baker and loaders. The editor is a preview.

Preview: Bake Light Probes shipped on 9 November 2026. The Include direct light option and the lightmap field's asset filter shipped on 15 November 2026 with the editor's move to engine 0.19.0, and the bake in the scene view, the Sky option and the list of what a bake left out the same day with its move to 0.20.0. None of these has been through an end-to-end test pass or been tried in a running editor yet.

Baking light probes#

A LightProbeVolume component lights PBR materials from a baked .probes.json grid instead of the environment's diffuse light. Create one with + → Light Probe Volume in the Hierarchy; its box is the entity's position and scale.

The Inspector's Bake Probes button, or Edit → Bake Light Probes, bakes a .probes.json for the selected volume with the engine's bakeLightProbes: one bounce of the scene's lights, on the CPU. The file is written next to the scene (or over the volume's own file when it already names one) and the volume's probes field is pointed at it, in one undo step; undo keeps the file. The bake reads the scene with its unsaved edits. The Light probes example runs the same bake in a browser.

The bake runs the bakeLightProbes of the engine in your project, so what it traces and which lights it stores follow the project's engine version, as below.

Where the bake runs#

In the scene view, when the project's engine is 0.20.0 or newer and the scene view is up. The scene view's own engine bakes the live scene, so the bake sees prefab instances, glTF models and the scene's environment. The strip shows a progress bar ("Baking 120 of 512 probes (23%) into …") and a Cancel button, and any edit to the scene during the bake stops it ("The scene changed during the light-probe bake, which stopped it; nothing was written."). The scene view bakes at most 16,384 probes: a larger grid is refused before it starts, with a hint to raise the spacing or shrink the volume.

In the background otherwise: on an older engine, with no scene view, or when an agent bakes and no editor window is open. A separate process runs the project's engine over the scene's lights, mesh renderers and models, with prefab instances left out (the result counts them). On engine 0.20.0 it traces glTF models too. It has no environment to read, so an Environment sky bakes black there, and the result says so ("no environment sky was available, so the sky is black").

After a bake, the strip lists what was left out, one line per object with its component and the reason, at most 20 lines; the same list goes to the Console as a warning. Nothing left out casts or bounces light.

Sky#

Sky beside Bake Probes sets what a ray that leaves the scene returns:

SkyWhat a ray that hits nothing returns
Environment (default)The scene's environment, as the scene view draws it; black in the background bake
NoneBlack
ColourThe colour you pick beside the menu

Edit → Bake Light Probes follows the menu's last choice, which is not remembered between launches.

Include direct light#

The bake leaves out the light a probe receives straight from directional, point and spot lights, because those lights still light the scene in real time and a volume would count them twice. It keeps the light they bounce off surfaces. A ray that leaves the scene returns the sky.

Hemispheric lights depend on the project's engine. On 0.19.0 the probes keep a hemispheric light's sky and ground as well, so it lights a volume about twice. From engine 0.20.0 a hemispheric light that still draws follows the same rule as the others, and only its bounce is baked: re-baking a scene lit by one comes out darker than before, unless the light's Bake mode is baked (below).

Tick Include direct light beside Bake Probes to bake that direct light in too, for a scene that turns those lights off at run time. Edit → Bake Light Probes follows the box's last setting. The box starts unticked each time the editor starts. It is bakeLightProbes's directLight: "include" (the default is "exclude", from engine 0.19.0).

A project still on ignifx 0.18.0 ignores the box: its bake always includes direct light. From engine 0.20.0 the box applies to realtime lights only (see Bake mode).

Bake mode#

From engine 0.20.0 a Light has a Bake mode field in the Inspector (Light.bakeMode), which the editor shows from the project's own component schemas:

Bake modeDrawn at run timeWhat the probes store
realtime (default)YesIts bounce; its direct light too when Include direct light is ticked
mixedYesIts bounce only, whatever the box says
bakedNoIts direct light and its bounce

A baked light reaches the scene only through the probes: its intensity is held at 0 and it casts no real-time shadow. The Inspector notes under such a light: "Baked lights are dark until the scene's light probes are baked." Use it for fill lights you want baked once, and keep the lights that must move, flicker or cast sharp shadows realtime or mixed. Re-bake after you change a light's bake mode.

What the bake traces#

On engine 0.19.0, only meshes whose triangles the engine keeps on the CPU cast and bounce light. Primitives, including the Box, Sphere, Plane, Ground and Cylinder the Hierarchy's Create menu makes, and glTF models are skipped, and the bake's result counts them.

From engine 0.20.0 the bake traces primitives too, so a scene built from the Create menu's 3D objects casts and bounces light into its probes, and glTF models (Model components) too. Prefab instances are in a bake in the scene view and left out of one in the background. Every enabled mesh renderer is traced, moving ones included: disable a renderer that should not be in the bake (or move the object out of the scene) while you bake.

Lightmaps#

Beta in the engine. A MeshRenderer's lightmap samples a baked .lightmap.json, a small file that names a texture, through the mesh's second UV set (or its first, with uv2 off). In add mode the texture adds baked light; in shadowmap mode it multiplies the shading, as a baked shadow mask under real-time lights.

In the Inspector, the lightmap field's asset slot takes only lightmap assets (.lightmap.json), so a texture or material dropped on it is refused. The engine draws a lightmap only on a static entity with a PBR material; when you set one on an entity that is not static, the MeshRenderer section says so (the engine logs IGX-0735). Tick Static in the Inspector's header.

The engine has no lightmap baker yet, and neither does the editor: the texture comes from an outside tool or from code (createLightmapAsset). The Lightmaps example shows a baked floor shadow, and the lightmap guide the code.

Atlas placement#

One lightmap texture can serve many static renderers. A .lightmap.json lists an entry per renderer with a scale and an offset, and from engine 0.20.0 the engine moves that renderer's second UV set into its square of the shared texture. Placement needs uv2 on and a mesh that has a second UV set, such as a mesh built in code with MeshAsset.fromData and uvs2. The Create menu's primitives have no second UV set. Without one, or with uv2 off, the renderer logs IGX-0735 and samples the whole texture, as it did on 0.19.0 for every entry other than the identity.

Reflection probes#

+ → Reflection Probe in the Hierarchy makes a ReflectionProbe: a cube map of the scene around the entity that nearby shiny PBR materials reflect. It is captured by the engine at run time, not baked by the editor. Its Inspector fields are the component's own: size, refreshMode, boxProjection and the rest.

From engine 0.20.0 a probe also has Blend distance (blendDistance, in metres). Once two or more probes with a boxProjection box have captured and one has a blend distance above 0, lit PBR materials blend up to four of them per pixel, each fading out over the last blend distance metres inside its box, instead of switching to the nearest probe at a hard edge. Probes without a box take no part, and a probe that captures every frame turns blending off. The Reflection probes example shows a single probe.

Agents#

ignifx_bake_light_probes bakes a volume as Edit → Bake Light Probes does, with optional spacing, rays, directLight ("include" or "exclude") and sky ("environment", the default, "none", or a linear colour { r, g, b }). It bakes in the scene view when the editor window can, else in the background, and its result names the route, the sky and what was left out (skips). See Agents and MCP.

Known limitations#

  • On engine 0.19.0 the bake skips primitives and glTF models (above), so a scene built from the Create menu's 3D objects bakes only its lights.
  • The background bake leaves prefab instances out and bakes an Environment sky black.
  • The scene view bakes at most 16,384 probes and refuses a larger grid; it does not hand it to the background bake (which takes up to 65,536).
  • Reloading the editor window during a bake in the scene view fails the bake (nothing is written); it is not retried in the background. Bake again.
  • There is no per-renderer way to keep a mesh out of a bake other than disabling it.
  • Include direct light and Sky are not remembered between launches.
  • The Inspector's lightmap field, the box, the Sky menu, the bake in the scene view and the list of what a bake left out have not been tried in a running editor.