kookaburra-lighting-authoring

name

kookaburra-lighting-authoring

description

Authoring and extending Kookaburra Cut's v9 scene lighting - the three-layer LightingSpec (theme, project, scene), the sun, free lights and their World/Camera/Subject spaces, emissive light fixtures and repeat arrays, HDRI environments, lighting keyframes, presets, and the display transform (tone mapping + exposure). Use when asked to "light a scene", "add a light", "make a corridor", "add an HDRI", "change the environment", "add a lighting preset", "animate the lighting", "change tone mapping or exposure", or when touching src/engine/sceneLighting.ts, src/engine/fixtures.ts, src/engine/lightingState.ts, src/engine/renderSettings.ts, src/toolkit/lighting/, src/toolkit/stage/StageLights.tsx, or a sidecar's `lighting` block.

kookaburra-lighting-authoring

Lighting is per-scene AUTHORED DATA, not scene code. It lives in each scene's sidecar (scenes/<stem>.json) under lighting, is edited through the inspector's Lighting section, and renders through <SceneStage>. Scene TSX should never mount lights directly.

Read this first: determinism cannot see an orientation bug

Verify compares run to run, so a frame that renders consistently WRONG passes cleanly. Seven render bugs in this batch did exactly that: area lights emitting sideways out of their own tubes, rim lights aimed backwards at the lens, housings sitting across the aperture they were meant to back. Every one verified EQUAL.

Any change to a lighting render path needs a frame grab. That is what ws:lighting-audit exists for: 9 scenes (env mirror, housed props, the shadow cap, one per preset) staging the same four subjects, so only the lighting block varies. Re-shoot it after any lighting render-path change:

pnpm kookaburra:run --action export --project ws:lighting-audit --aspect 16:9 --codec libx264
# then pull mid-scene frames (1000ms scenes, 60fps) and LOOK at them

It is deliberately not in a gate. It is the human check the gate structurally cannot perform.

Fixture design matters: subjects must be matte solids that show falloff plus one glossy solid for reflections. A device alone is a bad test subject, because a handset is mostly its own unlit screen texture, so a completely broken light type still looks fine.

And measure as well as look. Whole-frame luminance is swamped by a large flat backdrop, so crop to the subjects: a dead accent rim showed up as saturation 10.7 against 18.0 on the matte sphere when the whole frame said the two were 0.99 similar.

The contract (why these rules exist)

• Null-for-legacy is non-negotiable. Absent at all three layers must resolve to the pre-v9 code path VERBATIM. ws:launch-2026 staying EQUAL is the proof.
• Three layers, whole-field replacement. theme.lighting → project.json lighting → the scene sidecar's lighting. Each PRESENT field fully replaces the one below, and lists (lights, fixtures, fills) replace WHOLESALE. There is no merge-by-id.
• Caps are identical in preview and export. MAX_SCENE_LIGHTS 16, MAX_SHADOW_CASTERS 4, FIXTURE_MAX_COUNT 64, SUN_ANGULAR_REFERENCE 8. They live in engine/sceneLighting.ts (format.ts re-exports them, but cannot own them: it imports the editor store, which reaches the theme registry, which imports the parsers, and that cycles). A cap that differed between the two paths would break determinism by definition.
• Never Math.random(). Fixture jitter draws from createSeededRandom (engine/rng.ts) keyed on a djb2 hash of the fixture id plus the instance index. The sequence is export contract: a different hash re-rolls every jittered corridor.
• The Kelvin fit is export contract. engine/kelvin.ts is Tanner Helland's fit, vendored and pinned with golden values. Swapping it for a library rebases every lit project.

Colour: kelvin | token | hex

Resolved in that order, then white. Kelvin is the primary control; colorToken names a theme colour (so a theme swap restyles the rig); color is a hex escape hatch. An unknown token warns and falls through rather than dropping the light.

Light spaces, and which way things point

Space	Meaning	Azimuth 0
world	Fixed in the scene	From the origin along +Z
camera	Rides the camera rigidly	The camera's +Z axis, BEHIND the lens (cameras look down -Z)
subject	Orbits what the camera looks at	From the subject TOWARD the camera (a front light)

Camera and subject space resolve at the compositor seam, per render target (engine/lightingState.ts, applyRelativeLights). A transition frame renders A and B with different cameras, so a shared resolve is right in preview and in solo export and wrong only on transition frames. Never resolve relative lights in a React effect.

No target means aim at the SUBJECT, not at the space's origin. This is the rule that kills camera-space rim lights if you get it wrong, because the camera-space origin IS the camera: a defaulted aim points every rim backwards at the lens and lights nothing. World space already has its origin at the subject and subject space is defined by it, so the default makes all three spaces agree that no target means aim at the thing. An explicit target still reads in the light's own space.

Area lights have no .target in three, so they aim by rotating themselves (aimSelf → lookAt). Directional and spot lights aim through a real target Object3D. Point lights do not aim at all.

Fixtures

Emissive geometry that also lights. The trick is MeshBasicMaterial with toneMapped={false} and a colour scaled past 1.0, so it crosses the bloom threshold instead of being compressed by the display transform. Consequences worth stating to the user:

• A fixture needs bloom to read hot. The section says so; it never auto-enables bloom.
• Fixtures ignore exposure and the tone-mapping curve. They are emitters, not surfaces (a stated decision in docs/decisions.md).
• Area-paired forms light only Standard and Physical materials. Troika text and shader backgrounds ignore them. That is three's LTC limitation, not a bug.
• Over-budget fixtures THIN, they do not truncate. A corridor lit only at the near end looks broken; every second tube looks deliberate.

Axis conventions (get these wrong and the fixture lights the wrong way)

three's RectAreaLight puts width on local +X, height on local +Y, and emits along local −Z (WebGLLights.js). Every fixture convention here follows from that:

• Cores run along local X. CapsuleGeometry is built on Y and rotated onto X (fixtureGeometry), so a tube's length matches the emitter's width axis with no correction on the light itself. Box forms (strip, led-strip) are already long on X.
• Unrotated, a fixture emits toward −Z, which faces the camera in a default stage. That is the right default for a practical prop standing in shot.
• A ceiling batten is rotationDeg: [-90, 0, 0]: the core stays along X and the emission swings from −Z down to −Y. The neon-corridor preset is the reference.
• Housings sit on the side OPPOSITE the emission (behind, on −Z for a camera-facing fixture) and must never enclose the core. A housing bigger than its core on every axis simply swallows the light, and a housing built on the wrong primitive axis ends up across the aperture. CylinderGeometry and CapsuleGeometry are both built on Y: if you want either lying flat behind a ring, rotate it, or use a torus in the same plane as the ring.

Keyframes

lighting.keys + lighting.segments, sampled in SCENE-LOCAL time exactly like the camera track, and editable from the inspector's animation rows. Sparse poses interpolate against the resolved base, so a key setting only sun.intensity leaves everything else alone. Colours interpolate through KELVIN when both endpoints define it. Interpolating an orbit key against a position key is undefined: the rule is to hold the FROM endpoint.

This reverses the pre-v9 "scene motion of light is out of scope" line. The rule that survives, restated in docs/determinism.md: every lighting value is a pure function of the resolved timeline position; nothing reads the wall clock and nothing accumulates across frames.

Adding a bundled HDRI

1. Download the 1k EXR into the HDRI working folder (Poly Haven, CC0): https://dl.polyhaven.org/file/ph-assets/HDRIs/exr/1k/<slug>_1k.exr
2. Add <id> <slug>_1k.exr to the MAP in scripts/prepare-hdri.sh.
3. pnpm assets:hdri: it SKIPS anything already committed, and bakes the picker thumbnail into src/assets/hdri-thumbs/<id>.jpg via scripts/hdri-thumb.py.
4. Register the id in BUNDLED_HDRI (engine/environments.ts) with a ?url import, add the picker tile in LightingSection.tsx, and record the slug in src/assets/hdri/README.md.

Never re-convert a committed .hdr. The Blender build is a determinism boundary, so re-running the script over an existing file silently changes its bytes and rebases every project lighting through it. --force exists for a deliberate rebase and needs its own gate.

A user .hdr/.exr in a project's assets/ works too. A missing one THROWS at resolve time rather than degrading to no reflections: warning instead would ship a differently lit export that verify would happily certify (the AssetBoundary lesson). Bundled sources degrade and warn.

Preview-only surfaces

Light helpers and gizmos must never reach an exported frame, and the failure is SILENT: a helper drawn into both verify runs is EQUAL and passes. Two independent guards, both required:

1. Components mount only while the inspector's Lighting drill is open (never true in an autorun).
2. Everything sits on HELPER_LAYER (engine/lightEditStore.ts), which the export camera explicitly disables and the preview driver enables per frame.

Autoruns never open the inspector, so the mount gate hides the layer gate. Screenshot or export WITH the section open before trusting either.

Gates

Per change: showcase-tour Verify ×2 in 16:9. Feature work also verifies ws:lighting-spike-fable, and any render-path change re-shoots ws:lighting-audit by eye. Current baselines live in docs/determinism.md.

ws: fixtures live in ~/Kookaburra Cut/, NOT the repo, so they are shared across worktrees: a parallel session editing one silently changes another's baseline with no commit to blame. Gate hard on bundled projects (projects/showcase-tour), which are per-worktree and immune, and treat shared ws: hashes as advisory when more than one worktree is live.

Plan and rationale: ~/Documents/Projects/Personal/Kookaburra Cut/Post Go Live Improvements/3.