kookaburra-background-authoring
Skill10 starsChanged 2 days agoApache-2.0View on GitHub
Ships a new animated background for Kookaburra Cut end to end, shader (2D) or scene3d (world-space 3D look), whether ported from paper-design/shaders or written from scratch. Covers the ShaderBackgroundDef anatomy, GLSL3 + determinism patches (PCG hash, engine-owned uniforms, noise texture), the scene3d look contract, the 9 AA colour presets, the look lab contact sheets (tools/look-lab), preview-lab fixtures and incremental thumbnail regeneration. Use when asked to "add a background", "new animated background", "new shader background", "new 3D background", "port a paper-design shader", "add or change background presets", "look lab", "contact sheet of a 3D look", or when touching src/toolkit/stage/shaders/, src/toolkit/stage/scene3d/ or tools/look-lab/.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- kookaburra-brand-packsSkill
- kookaburra-commitSkill
- kookaburra-export-presetsSkill
- kookaburra-lighting-authoringSkill
- 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, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Foreground first: Every preset colour stop must hold WCAG AA alone against the preset's text colour (black for light, white for dark), …
- Very specific: line 48
If ported, record the attribution: Add the source file to src/toolkit/stage/shaders/NOTICE.md plus a bullet per behavioural adaptation.
≈ “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-background-authoring
Ship a new animated background: one GLSL3 effect, nine AA-safe presets, committed preview
thumbnails, all deterministic. Colour rules live in docs/backgrounds.md; templates for every
file live in this skill's REFERENCE.md.
When to use
- Adding a new shader background (vendored port or original GLSL)
- Adding or re-tuning a shader's colour presets
- Editing anything under
src/toolkit/stage/shaders/
The contract (why these rules exist)
- Determinism. Backgrounds render on the export path, so every fragment op must be
bit-reproducible across runs. Driver-defined float tricks (
fract(sin())hashes) break byte-identical export; the house PCG integer hash does not. - Foreground first. Every preset colour stop must hold WCAG AA alone against the preset's
text colour (black for light, white for dark), because the fill animates under the text.
Bands, counts and naming voice:
docs/backgrounds.md.
Instructions
- Create the def at
src/toolkit/stage/shaders/<name>.tsexporting aShaderBackgroundDef(skeleton in REFERENCE.md). The fragment is a GLSL3 body: no#versionorprecisionlines (three prepends them), but it MUST declare and write its ownout vec4 fragColor;. This three version does not aliasgl_FragColorfor GLSL3 custom shaders; forgetting the declaration renders black, not an error. - Patch out float-hash randomness. Replace any
fract(sin(dot(...)))style hash with the PCG-style integer hash fromsrc/engine/transitionShader.ts(hash01), keeping the source function's name and signature so the rest of the fragment stays untouched. Floorvec2inputs throughivec2before theuvec2cast (float-to-uint is undefined for negatives). - Leave engine-owned uniforms out of
uniforms().u_time,u_resolution,u_scale,u_rotation,u_offsetX/Yandu_linearOutare written by the engine quad. If the effect needs texture noise, setnoise: true, keep thesampler2D u_noiseTexturedeclaration and exclude it too; the engine attaches the sharedDataTexturefromnoiseTexture.ts. Never embed a new image; decode to raw bytes at vendor time likeNOISE_B64. The fragment writes display-domain colour raw, which the canvas and the compositor's display targets keep as is; the engine wrapsmain()(shaders/wrap.ts) so any hardware-sRGB target receives linear light instead (wrap.test.tspins the rewrite markers). - Register it in
src/toolkit/stage/shaders/index.ts: add toSHADER_BACKGROUNDSand toSHADER_BACKGROUND_IDS(the inspector's display order). - If ported, record the attribution. Add the source file to
src/toolkit/stage/shaders/NOTICE.mdplus a bullet per behavioural adaptation. Original GLSL needs no NOTICE entry. - Author the 9 presets in
presets.ts:p1top5light,p6top9dark, Australian nature names unique across the pack, every stop inside the luminance bands (light >= 0.30, dark <= 0.125), muted saturation, speeds around 0.3 to 0.5. Keep 2.5:1 to 3:1 between each preset's darkest and lightest stop (flatter than that and the motion disappears) and give every preset its own parameter personality, not just a hue swap. Set the def'scolorSlots[].fallbackto thep6colours; a vitest pins the match. - Add the preview fixtures in a NEW
fixtures/preview-lab-bg-<shader>/project (the option-previews action discovers lab projects by directory prefix; a vitest guards the pairing): onebg-<shader>pair (the type card's motion clip), onebg-<shader>-lightpair (the light-theme card, mirroring p1) and ninebgp-<shader>-p1..p9pairs (preset tiles), each a trivial.tsxplus a sidecar whosebackgroundblock mirrors the preset exactly (templates in REFERENCE.md). Register all eleven in the lab's ownproject.json.optionPreviews.test.tsfails on any drift between fixtures and presets. Validate, then regenerate thumbnails.
pnpm build && pnpm test && pnpm lint # fix and rerun until clean pnpm kookaburra:run --action option-previews # renders ONLY stale sets (manifest diff)The run hashes fixtures against
src/assets/option-previews/manifest.jsonand captures only stale sets, so a new shader renders its own eleven sets in its own small lab project;--allforces a full re-record (engine-change refreshes). Never bumpOPTION_PREVIEW_VERSIONfor one look: it marks every set stale (see REFERENCE.md).Then eyeball the new stills in
src/assets/option-previews/. Verify proves determinism, not correctness; a black tile means a missingout vec4 fragColor;or a bad uniform.- Gate it. A new shader is a new render code path: run the standard gate pair from
CLAUDE.md (feature-matched project Verify x2 in 16:9, plus
ws:launch-202616:9 EQUAL as the null-for-legacy proof). Preset colour changes alone are data and need no Verify.
3D looks (scene3d)
World-space animated backgrounds live in src/toolkit/stage/scene3d/ (registry index.ts,
presets presets.ts); the contract is in docs/backgrounds.md ("3D backgrounds"). The same
shipping flow applies, with these differences:
- A look is a React component receiving
{ colors, params, speed, backing }(backingis the resolved backing as one hex: mix fades toward it, REFERENCE.md), mounted inside the scene's identity group. Motion comes fromuseTimeline()only (commit-phase CPU updates or whole-group transforms); seeded randomness viacreateSeededRandomwith a fixed seed. New looks live one per folder (looks/<id>/index.tsexportinglookandpresets) and are discovered, so never editindex.tsorpresets.tsto add one (REFERENCE.md, "3D look folder"). Glow slots (glow: true, at most 2) may reach 0.30 in dark presets. - Stay OUT of the content volume (x/y roughly +-4/+-2, z -6..9): keep-out clearances and
distance fades, tag the root
userData.kookaburraBg3d(the perf probe'sno-bg3dpass). Floors want a small stage-courtesy clearing (~4u), not a content-radius ring. Never setrenderOrderin a look: the host (Scene3dBackdrop) stampsSCENE3D_RENDER_ORDERon every renderable so backgrounds draw behind content at any camera angle. - Unlit looks hold exact colours (
toneMapped: false);lit: truelooks use standard materials with anABSTRACT_EMISSIVEfloor so they read on unlit scenes. - Presets carry geometry
colorsplus a flatbackinghex; bands and AA apply to ALL of them (scene3d/presets.test.ts). Keepp1stops at or above 0.315: the Theme tile retints p1 for light themes and Sunrise's text token needs that floor for AA (scene3d/themePreset.test.ts). Generate the fixtures withnode scripts/gen-bg3d-preview-labs.ts <look-id>instead of writing them by hand; its static poses carry the REQUIREDsegments: []besidekeys(without it the block drops). - Thin 1px lines vanish at tile size and can whisper at 4K: densify geometry and push dark
lines toward the 0.125 cap before reaching for preview tricks; eyeball at BOTH scales via
an
ws:spike screenshot. - Iterate in the look lab (
node tools/look-lab/sheet.mjs --look <id>, a sheet in about 10 s, REFERENCE.md "Look lab"), then confirm with one or two autorun screenshots at the end.
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.

