# Clockwork Butterfly — `clockwork-butterfly@1.0.0`

A brass steampunk butterfly with open-work wings, gears and a wound spring, beating its wings without running down. Loops perfectly.

A steampunk automaton: a butterfly of polished brass (or gold, silver, copper) with four open-work wings, each cut with round windows and set with a small turning gear, a segmented body with a wound spring and gears on its back, eyes of glass and curled antennae. Its wings beat in whole beats per loop, its gears turn in whole turns and it bobs gently as it hovers. Choose the metal, how many beats a loop holds, the seed, the backdrop and whether the camera drifts.

- Kind: object; status: published; digest sha256:736e82f3c85f12868d73441dc8c965e6ed90519eb87e56d4eb074480cc1c8683
- Role: Object (3D, three.js): a delicate mechanical hero object for steampunk, craft, nature and fantasy content.
- Implementation: three; entry `src/clockwork-butterfly.js`
- Files: https://aipixelwizard.com/registry/clockwork-butterfly/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/clockwork-butterfly.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/clockwork-butterfly/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/clockwork-butterfly/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and shader materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createClockworkButterfly({ metal?, beats?, seed? }) => { group, setProgress(progress), dispose() }` — The butterfly as a group (wingspan 6, body along z, facing +z); add it with an environment map and a light.
- `METALS: { brass, gold, silver, copper }` — Metal finishes.

## Parameters
- `metal` (select one of brass | gold | silver | copper, default "brass") — Metal
- `beats` (integer 1–8, default 4) — Wing beats: Beats per loop.
- `seed` (integer 1–999, default 3) — Seed
- `background` (color, default "#1b2a2a") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Time within the loop; the metal, beats, seed, backdrop and camera drift.
- Outputs: A full frame rendered in 3D with soft shadows and a studio environment.
- Coordinates: The body lies along z facing +z, the wings spread along x; the butterfly hovers about 2.6 above the floor.
- Lighting: A warm key light with a shadow map and the studio environment on the polished metal.
- Timing: setProgress(progress) sets every angle; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- Each wing is an extruded 2D outline with round windows cut out; the four hinge on the body and beat with a small lag between fore and hind.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — The wings beat in sines of a whole number of beats per loop, the gears turn in whole turns, the hover bob is a sine of whole cycles and the camera drift is a sine of the loop, so the last frame meets the first.
- Verified 2026-10-06 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer with shadows and a studio environment (see chrome-material), add createClockworkButterfly().group and call butterfly.setProgress(progress) each frame.

Existing project: Copy src/clockwork-butterfly.js; add butterfly.group to your scene with an environment map and a light.

Reuse ideas:
- Steampunk title: Brass, four beats.
- Jeweller's loop: Gold, slow.
- Fantasy opener: Silver, quick.

## Limitations
- The wings are flat plates: they do not bend or cast translucent colour.
- The body is simple spheres and a tube spring, not an anatomically detailed insect.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/objects-scenes/clockwork-butterfly (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original object: seeded open-work wings, gears and a wound spring beating in whole beats per loop.