{
  "schemaVersion": 1,
  "id": "clockwork-butterfly",
  "version": "1.0.0",
  "status": "published",
  "kind": "object",
  "title": "Clockwork Butterfly",
  "summary": "A brass steampunk butterfly with open-work wings, gears and a wound spring, beating its wings without running down. Loops perfectly.",
  "description": "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.",
  "role": "Object (3D, three.js): a delicate mechanical hero object for steampunk, craft, nature and fantasy content.",
  "collections": [
    "satisfying",
    "chrome-glass",
    "hypnotic-loops"
  ],
  "tags": [
    "butterfly",
    "clockwork",
    "steampunk",
    "brass",
    "automaton",
    "gears",
    "wings",
    "mechanical",
    "loop",
    "3d"
  ],
  "synonyms": [
    "mechanical butterfly",
    "brass butterfly",
    "steampunk insect",
    "automaton",
    "clockwork insect",
    "gear butterfly"
  ],
  "useCases": [
    "A steampunk, fantasy or craft title scene",
    "A product-style loop for a watchmaker or jeweller",
    "A nature-meets-technology story"
  ],
  "featured": null,
  "publishedAt": "2026-10-06",
  "implementation": {
    "target": "three",
    "runtime": "browser",
    "language": "javascript",
    "module": "esm",
    "entry": "src/clockwork-butterfly.js",
    "exports": [
      {
        "name": "createClockworkButterfly",
        "signature": "createClockworkButterfly({ metal?, beats?, seed? }) => { group, setProgress(progress), dispose() }",
        "description": "The butterfly as a group (wingspan 6, body along z, facing +z); add it with an environment map and a light."
      },
      {
        "name": "METALS",
        "signature": "METALS: { brass, gold, silver, copper }",
        "description": "Metal finishes."
      }
    ],
    "reusable": [
      "src/clockwork-butterfly.js"
    ],
    "demo": "demo.js",
    "harness": "index.html"
  },
  "dependencies": [
    {
      "id": "three",
      "version": "0.185.1",
      "reason": "Renderer, geometry and shader materials."
    },
    {
      "id": "chrome-material",
      "version": "1.1.0",
      "scope": "demo",
      "reason": "Studio environment light, backdrop and contact shadow."
    },
    {
      "id": "apw-runtime",
      "version": "1.0.0",
      "scope": "demo",
      "reason": "Demo harness."
    }
  ],
  "params": [
    {
      "key": "metal",
      "label": "Metal",
      "type": "select",
      "default": "brass",
      "options": [
        {
          "value": "brass",
          "label": "Brass"
        },
        {
          "value": "gold",
          "label": "Gold"
        },
        {
          "value": "silver",
          "label": "Silver"
        },
        {
          "value": "copper",
          "label": "Copper"
        }
      ]
    },
    {
      "key": "beats",
      "label": "Wing beats",
      "help": "Beats per loop.",
      "type": "integer",
      "min": 1,
      "max": 8,
      "step": 1,
      "default": 4
    },
    {
      "key": "seed",
      "label": "Seed",
      "type": "integer",
      "min": 1,
      "max": 999,
      "step": 1,
      "default": 3
    },
    {
      "key": "background",
      "label": "Backdrop",
      "type": "color",
      "default": "#1b2a2a"
    },
    {
      "key": "orbit",
      "label": "Camera drift",
      "type": "boolean",
      "default": true
    }
  ],
  "presets": [
    {
      "id": "default",
      "label": "Brass, four beats",
      "params": {}
    },
    {
      "id": "gold",
      "label": "Gold, slow",
      "params": {
        "metal": "gold",
        "beats": 2,
        "background": "#241a28"
      }
    },
    {
      "id": "silver",
      "label": "Silver, quick",
      "params": {
        "metal": "silver",
        "beats": 7,
        "background": "#12202e"
      }
    },
    {
      "id": "copper",
      "label": "Copper",
      "params": {
        "metal": "copper",
        "seed": 8,
        "background": "#201814"
      }
    }
  ],
  "output": {
    "width": 1080,
    "height": 1080,
    "fps": 30,
    "durationSeconds": 12,
    "posterSeconds": 1,
    "alpha": false,
    "motion": "procedural",
    "loop": {
      "seamless": true,
      "cycleSeconds": 12,
      "method": "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."
    },
    "seed": {
      "param": "seed",
      "behavior": "Seed shapes the wings' outline and window pattern: same seed, same butterfly."
    }
  },
  "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.",
    "compatibleWith": [
      "chrome-material",
      "orbit-camera",
      "kinetic-title",
      "number-reveal"
    ],
    "notes": [
      "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."
    ]
  },
  "reuse": [
    "Steampunk title: Brass, four beats.",
    "Jeweller's loop: Gold, slow.",
    "Fantasy opener: Silver, quick."
  ],
  "integration": {
    "newProject": "Create a WebGLRenderer with shadows and a studio environment (see chrome-material), add createClockworkButterfly().group and call butterfly.setProgress(progress) each frame.",
    "existingProject": "Copy src/clockwork-butterfly.js; add butterfly.group to your scene with an environment map and a light."
  },
  "performance": {
    "notes": "About 40 meshes and one shadow map with anti-aliasing. A few milliseconds a frame on an integrated Intel GPU.",
    "limits": "Software WebGL renders in about a second a frame."
  },
  "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": {
    "spdx": "MIT",
    "notice": "Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.",
    "thirdParty": []
  },
  "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.",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2026-10-05",
      "notes": "Initial release."
    }
  ]
}