kookaburra-lighting-authoring
Skill10 starsChanged 2 days agoApache-2.0View on GitHub
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.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- kookaburra-background-authoringSkill
- kookaburra-brand-packsSkill
- kookaburra-commitSkill
- kookaburra-export-presetsSkill
- kookaburra-pr-descriptionsSkill
- kookaburra-releaseSkill
- kookaburra-scene-authoringSkill
- kookaburra-skill-creatorSkill
- kookaburra-video-editingSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Verify compares run to run, so a frame that renders consistently WRONG passes cleanly.
- Very specific: line 135
Add <id> <slug>_1k.exr to the MAP in scripts/prepare-hdri.sh.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 themIt 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-2026staying EQUAL is the proof. - Three layers, whole-field replacement.
theme.lighting→project.jsonlighting→ the scene sidecar'slighting. 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_LIGHTS16,MAX_SHADOW_CASTERS4,FIXTURE_MAX_COUNT64,SUN_ANGULAR_REFERENCE8. They live inengine/sceneLighting.ts(format.tsre-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 fromcreateSeededRandom(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.tsis 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.
CapsuleGeometryis 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. Theneon-corridorpreset 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.
CylinderGeometryandCapsuleGeometryare 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
- 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 - Add
<id> <slug>_1k.exrto theMAPinscripts/prepare-hdri.sh. pnpm assets:hdri: it SKIPS anything already committed, and bakes the picker thumbnail intosrc/assets/hdri-thumbs/<id>.jpgviascripts/hdri-thumb.py.- Register the id in
BUNDLED_HDRI(engine/environments.ts) with a?urlimport, add the picker tile inLightingSection.tsx, and record the slug insrc/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:
- Components mount only while the inspector's Lighting drill is open (never true in an autorun).
- 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

