scenario-unreal-lighting-rendering

Lighting and rendering in Unreal Engine 5.8

Expert lighting in Unreal is a calibrated camera, physical light values, and a renderer that sees the same scene you do; everything else is art direction layered on top and listed as such. Each step is proved with a representation view and a number before the lit image is trusted; noise is fixed in the system that owns it. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-unreal-expert (channels, review loop, 5.8 traps).

Status (2026-09-24): scripts/ue_light.py is not yet run in Unreal; 200 pure, 65 editor-layer and 20 procedure checks pass offline against a fake unreal. First editor run: tests/code/unreal-lighting-rendering/job_00_probe_lighting.py.

Stance (the expert delta)

• Camera before lights. Default auto exposure "childproofs" the engine: a 10 lux and a 100,000 lux sun look alike. Chrome ball at the subject, Exposure Compensation 0, Min/Max EV100 clamped to the conditions, then lights; emissive last (Gobey nlbJwMoj1Dg [00:02:38] [00:11:40]; Faucher BGoaPyfZlYg [00:01:34]). Judge through Game Settings exposure, never the viewport EV100 override (Gobey [00:21:56]).
• Physical values remove problems; cheats go on top and in the report. Real lumens removed about 80 percent of Lumen flicker (Argyriou Q1whHlGJB_o [00:14:41]); albedo is lighting, at most 0.8, floor 0.02 [added] (path tracer doc; Gobey [00:07:30]; Faucher X5zVhc5ahl0 [00:22:24]). Every light has a visible fixture and a source shaped like it (Faucher 0GYyHDuaPcg [00:15:14] [00:15:47]). Moons, fills and boosts are fine when listed (cheat_inventory): the path tracer will not show them.
• Emissive is the look, lights do the lighting. Small bright emissive is noisy, screen-space and clamped harder since 5.6 (r.Lumen.ScreenProbeGather.MaxRayIntensity 10): a neon sign gets a rect light fitted to its face, in front of it (Faucher 1e6oOiKh91U [00:12:30]; Gobey Q&A [00:37:33]; MegaLights doc). Under Lumen, small emissive meshes get Emissive Light Source, optionally a Lumen-only boost of 5 to 10 through a Ray Tracing Quality Switch [verify node] (Campbell BKaAzhMHJZ0 [00:14:09]); the path tracer ignores that switch and double counts a tube plus its light (path tracer doc).
• The renderer sees a proxy; look at it. Lumen Scene and Surface Cache (black = screen traces only, pink = no cards, often a one-mesh room), MegaLights shadow caster mismatch, VSM cached pages, each against the lit view from the same camera (Faucher [00:07:21] [00:06:42]; Lumen, MegaLights, VSM docs).
• MegaLights noise is stolen samples, not light count. Hidden lights take up to 20 percent of samples (50 after failed reprojection), a directional up to 50. Tight radius, cones, barn doors, no light inside geometry, clusters merged, the sun on deferred plus VSM (Narkowicz and Costa dmmN8_c8Tb0 [00:10:37] [00:16:40]). Alpha masks are ignored by its ray tracing by default (MegaLights doc).
• Shadow method follows what moves. Local lights stay ray traced in gameplay: every character crossing a VSM local light invalidates its pages, while ray tracing pays per visible pixel with free penumbras (Campbell [00:26:25] [00:31:42]). VSM for the sun and for content ray tracing cannot represent, with a written reason.
• A dark interior is a tone-mapper problem first; light before you grade. Toe 0.55 to 0.3 and Local Exposure Shadow Contrast 0.6 before any fill (Gobey [00:14:58] [00:15:32]); then the ladder: direct light, one light's indirect boost, Diffuse Color Boost, global exposure last (Faucher 0GYyHDuaPcg [00:08:14] [00:13:42]). Glossy surfaces need a direct light: Lumen indirect gives little specular (Faucher [00:10:28]).
• For the still, the path tracer is ground truth and samples are its only quality knob. On the deferred path, samples buy motion blur and anti-aliasing only; Lumen or shadow noise is fixed at the light or the PPV (Faucher X5zVhc5ahl0 [00:07:43]; fVg5ihB8Wdc [00:09:15]; Comly, demystifying-mrq).

Establish first

Input	Changes	Default when silent
Platform, frame rate	Lumen scalability, MegaLights, HWRT	console 60 fps: Lumen High; budgets from scenario-unreal-performance; Mac numbers are proxies
What this Mac runs (probe)	every plan	M5 Max, macOS 26.5.1: Lumen HWRT and MegaLights Experimental, Nanite and VSM Beta, path tracer supported (deltas file)
Deliverable	exposure mode, still plan	gameplay plus one still; direct delivery (tone-mapped PNG plus EXR)
Conditions the player walks between	EV100 bracket	CONDITIONS: interior 4, blue hour 6.5 [added], low sun 7, moonlit 1
Style	physical vs art-directed moon and sun	physical base; film moon and a 15 degree sun floor only for readability (Faucher; Oakley rX0wZZxpB-U [00:19:16])
Key cameras; glass and emissive fixtures in shot	fog scattering, cheats, glass and double-count audits	bookmarks from the brief; front layer only in a PPV around hero glass

Workflow

Editor Python via Epic's MCP server or ue_remote; import ue_light as L; full code in references/procedures.md. Screenshots are latent: one capture per call.

1. Probe and settings (P0, P1). probe(), render_settings_report, ini_patch after a backup; extended luminance range only in a new project. GATE: probe JSON read.
2. Calibrate the camera (P2). spawn_calibrator at the subject, then one unbound PPV_Global: apply_exposure(ppv, exposure_plan("gameplay", ("interior", "blue_hour"))), apply_look (Local Exposure mandatory with Lumen GI; Film only here). GATE: ppv_lint no fail; HDR view shows each target inside the clamps.
3. Exterior (P3). build_exterior_rig(exterior_rig_plan("blue_hour", key_camera_forward=...)): Sky Atmosphere, sun at 120,000 lux below the horizon, real-time Sky Light, volumetric fog with black inscattering, Scattering Distribution from the key camera's angle to the light (0.9 into it, 0 from the side: Faucher 1LfiYtKDsac [00:16:06]). Steady lamps scatter above 1 for halos, flickering ones 0. GATE: scene_lint clean; sun out of MegaLights.
4. Practicals, neon, openings (P4, P5). FIXTURES lumens and kelvin, radius from tight_attenuation_radius capped by the room, source radius, length or size matching the fixture, one rect per shelf, neon_sign_light in front of each sign, opening_rect_light for the window; emissive via emissive_for_stops, then emissive_strategy (Emissive Light Source, optional boost). GATE: light_lint no warn in the gameplay profile (fixture, shape, VSM, clusters), or a written reason.
5. Does the renderer see it (P7 to P9). Lumen views vs lit; room_shell_lint on pink; MegaLights dump and mismatch view; masked casters; VSM cached pages. GATE: no black or pink where light must bounce; no hidden light in the dump; VSM red share near 0; noise judged in motion.
6. Look (P10). Ambient shape first, then the focal hue, then "the promise of more": light leaving the frame, a lit side street (Oakley [00:07:34] [00:09:19] [00:08:44]); the shadow-lift ladder in order; grade last; white-balance direction by A/B screenshot. GATE: frame_report B3 to B8.
7. Review loop (P11, P12). Per bookmark: log_mark, capture, frame_report(frame, brief, log_text=log_since(...)), one change, logged in iterations.jsonl. The 5.8 exposure-range warning fails the frame; glossy regions must hold a highlight; walk the player path for adaptation. Timings use P12's measure preset (async compute, dynamic resolution off) and go to scenario-unreal-performance. GATE: no fail.
8. The still (P13). Scene audit first: Base Color buffer through albedo_check, emissive_fixture_pairs (A/B r.PathTracing.EnableEmissive 0, Indirect Emissive off), glass_lint. Then still_plan("path_traced", "final", glass=True, sky_atmosphere_visible=True, emissive_fixtures=...), mrg_lint clean, set_cine_camera_exposure (Manual metering, Apply Physical Camera Exposure), queue_mrg_still. Still-only cheats via still_only_light_plan on their own lighting channel. Offline: gray card within 1/3 stop on the linear EXR, compare_ground_truth, 100 percent crops; a render that differs from the viewport walks RENDER_DIFF_TRIAGE. GATE: C1 to C11 of critique.md.
9. Handoff (P14). lighting_manifest(path, ctx): lights, PPVs, lint, cheats, emissive pairs, masked casters, cvars.

Numbers

Item	Value	Relative to, source
Sun, moon	120,000 lux at zenith (0.545 degrees); moon 0.26 lux	Epic sky doc
Look targets (EV100)	sunlit 14, cloudy 10, low sun 7, interior 4, moonlit 1, moonless -2	Gobey chart [00:12:02]; targets, not meter readings
Fixtures	candle 12 lm 1,900 K; decorative 300; interior 1,000; exterior 10,000; street 2,500 to 10,000 lm	Gobey chart; Argyriou [00:13:36]
Units	1 cd = 625 unitless = 12.6 lm (point) = 3.14 lm (rect) = 1.76 lm (spot, 44 degrees)	exposure doc
Exposure	EV100 = log2(N^2 / t x 100 / ISO); B = L / 2^(EV100 + comp); f/2.8, 1/50, ISO 800 is EV100 5.6	exposure doc
Auto exposure	Low 70 to 80, High 80 to 95 percent; Speed Up 3 above Speed Down 1	exposure doc; Gobey frame [00:21:52]
Local Exposure, Film	contrast 0.6 to 1 (default 0.8); Toe 0.55 default, 0.3 for dark interiors	exposure doc; Gobey
Albedo	0.02 [added] to 0.8 path traced, 0.9 Lumen	path tracer doc; Faucher 1e6oOiKh91U [00:13:35]
MegaLights	20 percent of samples to hidden lights (50 after failed reprojection); sun up to 50	SIGGRAPH [00:10:37] [00:16:40]
Path-traced still	1 temporal, spatial 256 draft to 1024 or more final; glass 10 bounces; Max Path Intensity default	path tracer doc; Faucher X5zVhc5ahl0 [00:16:47]
Deferred still	spatial only, odd (9 draft, 15 final, 31 thin bright), AA None above 8, Motion Blur Amount 0, warm-up 250	Faucher fVg5ihB8Wdc [00:06:01] [00:10:58]; 1e6oOiKh91U [00:09:56]

Quality gates

• Measurable: ppv_lint, light_lint, scene_lint, glass_lint, room_shell_lint, mrg_lint, cvar_lint without fail; frame_report on every bookmark with the log since capture (blank frames and the exposure-range warning fail); albedo_check on the Base Color buffer; gray card from linear EXRs; compare_ground_truth within a stop outside listed cheats; red_fraction on the VSM cache view; temporal_flicker on warm-ups. Thresholds marked [added] are calibrated per project on one approved frame.
• Visual: each bookmark full size and as a thumbnail beside its representation views; a camera move for noise; inner corners for leaks; glossy highlights; the still at 100 percent; in the order of references/critique.md.

Common mistakes

Mistake	Looks like	Fix
Lighting under default auto exposure	any value "looks fine"; flicker	exposure_plan, comp 0, then physical lights
Neon lit by emissive only	splotchy, crawling GI	rect light per sign; Emissive Light Source
Tube plus its light in a path-traced still	fixtures glow twice as bright as Lumen	A/B r.PathTracing.EnableEmissive 0; Indirect Emissive off
Sky light or exposure raised for a small window	splotches, flat gray interior	opening_rect_light sized to the opening
Many small lights, big radii, a sun indoors under MegaLights	noise and ghosting in motion	tight bounds, merge clusters, sun on VSM
Local lights on VSM over moving characters	constant invalidation, cost spikes	ray-traced shadows; VSM only with a reason
Grilles or plants under MegaLights	solid shadows once off-screen	model the holes, or EvaluateMaterialMode 1
One mesh for the whole room	pink surface cache, screen-space GI	split walls, floors, ceilings; Max Lumen Mesh Cards
Fill lights to rescue a dark interior; grading first	flat, view-dependent GI	toe and local exposure, then the ladder; grade last
Glossy bar top lit only by Lumen	dry, dead surface	a direct light it can reflect
More MRG samples for Lumen noise; even or mixed deferred samples	noise unchanged, blur on a still	NOISE_TRIAGE, still_plan, mrg_lint
HDRIBackdrop in a path-traced still	double lighting	remove it; Sky Light cubemap plus r.PathTracing.VisibleLights 2, which does nothing under Reference Atmosphere
Render differs from the viewport, cvars pasted	"the render is broken"	RENDER_DIFF_TRIAGE: Global Game Overrides first
Still-only rim left in the level	the cheat lights gameplay	own lighting channel, indirect 0, in the shot sequence

Handoffs

• Receives from scenario-unreal-world-building: the level, modular walls, floors and ceilings 10 cm or thicker, correct mobility, room volumes tagged room, fixture meshes tagged fixture:<name>, emissive meshes tagged emissive. From scenario-unreal-materials: masters exposing EmissiveIntensity (and LumenEmissiveScale behind a Ray Tracing Quality Switch), albedo 0.02 to 0.8, IOR glass on Surface ForwardShading. From scenario-unreal-vfx: particle lights (shadows off, Allow MegaLights).
• Delivers to scenario-unreal-cinematics: the lit level, lighting_manifest.json, the exposure plan (EV100, ISO and shutter for their aperture), still_plan presets, MRG variables, still-only cheat plans. To scenario-unreal-performance: light counts, shadow methods, measured passes. To scenario-unreal-materials and scenario-unreal-world-building: albedo, glass, masked-caster and room-shell fixes.

UE 5.8 notes

• MegaLights Production Ready (lighting channels, cloud shadows, mismatch views); directional lights excluded unless r.MegaLights.DirectionalLights 1; r.MegaLights.Debug, r.MegaLights.DownsampleMode.
• Lumen Lite at Medium (Beta); SSGI deprecated; RTGI gone since 5.4; detail tracing deprecated; r.Lumen.HeightFog 1 default.
• r.EyeAdaptation.CachedLightingPreExposure (default 4) unifies pre-exposure, with an on-screen warning when exposure leaves the supported range.
• ACES 2.0 is the SDR path; OCIO 2.5.1; grading scopes ShowFlag.VisualizeColorGrading.
• Path tracer on Mac (macOS 26.4+); back-face culling always on; HDRIBackdrop incompatible; Reference Atmosphere ignores Sky Lights.
• Movie Render Graph Production Ready: Basic config by default, Light Modifier, layer warm-ups, DWAA/DWAB EXR.
• Python: the Rotator's positional order is roll, pitch, yaw, so ue_light passes keywords [verify].

References

• references/procedures.md: P0 to P14, full code, each block with its test id and status. Load before writing lighting code.
• references/critique.md: setup, frame, render and budget rubrics mapped to code findings. Load at every gate.
• references/expert-notes.md: depth per expert with timestamps, disagreements and deciding conditions.
• references/gui-paths.md: menus and editors for a computer-use agent or a human.
• references/sources.md: every source, credential, URL, best timestamps, revision history.
• scripts/ue_light.py: the toolkit; its docstring lists every call and where it runs.