{
  "schemaVersion": 1,
  "id": "rolling-ball-sculpture",
  "version": "1.0.0",
  "status": "published",
  "kind": "object",
  "title": "Rolling-Ball Sculpture",
  "summary": "A brass kinetic sculpture: a wheel lifts chrome balls that roll down a spiral and back across a walnut base. Loops perfectly.",
  "description": "A desk-sized kinetic sculpture in polished metal: a wheel with eight cradles lifts chrome balls one by one and tips each onto a pair of rails at the top; the balls roll down a spiral round a column and back across the front of the base into the wheel again, speeding up where the track is steep and easing off on the gentle stretches, while the rails cast thin shadows on the wood. Choose the metal (brass, copper, steel or black), the base (walnut, oak or black), the number of balls and the backdrop.",
  "role": "Hero object (Three.js 3D): a satisfying perpetual-motion machine for intros, loops and backgrounds.",
  "collections": [
    "satisfying",
    "hypnotic-loops",
    "chrome-glass"
  ],
  "tags": [
    "kinetic sculpture",
    "rolling ball",
    "marble run",
    "perpetual motion",
    "brass",
    "chrome balls",
    "satisfying",
    "machine",
    "desk toy",
    "loop",
    "3d"
  ],
  "synonyms": [
    "rolling ball sculpture",
    "ball machine",
    "marble machine",
    "kinetic art",
    "rube goldberg",
    "ball track",
    "perpetual motion machine",
    "executive desk toy"
  ],
  "useCases": [
    "A satisfying loop for engineering, design or productivity content",
    "A calm background behind a talking head or a title",
    "A metaphor for process, flow and teamwork in explainers"
  ],
  "featured": null,
  "publishedAt": "2026-10-06",
  "implementation": {
    "target": "three",
    "runtime": "browser",
    "language": "javascript",
    "module": "esm",
    "entry": "src/rolling-ball-sculpture.js",
    "exports": [
      {
        "name": "createBallSculpture",
        "signature": "createBallSculpture({ metal?, base?, balls?, loopSeconds?, seed? }) => { group, loopSeconds, wheelTime, trackLength, bounds, ballAt(tau), update(time), dispose() }",
        "description": "The sculpture as a THREE.Group (1 unit = 10 cm, standing on y = 0). update(time) poses the wheel and every ball; the machine repeats exactly every loopSeconds."
      },
      {
        "name": "METALS",
        "signature": "METALS: { brass, copper, steel, black }",
        "description": "Finishes for the rails, wheel and posts."
      },
      {
        "name": "BASES",
        "signature": "BASES: { walnut, black, oak }",
        "description": "Finishes for the base."
      }
    ],
    "reusable": [
      "src/rolling-ball-sculpture.js"
    ],
    "demo": "demo.js",
    "harness": "index.html"
  },
  "dependencies": [
    {
      "id": "three",
      "version": "0.185.1",
      "reason": "Renderer, geometry and physical materials."
    },
    {
      "id": "chrome-material",
      "version": "1.1.0",
      "scope": "demo",
      "reason": "Studio environment light, backdrop, floor 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": "copper",
          "label": "Copper"
        },
        {
          "value": "steel",
          "label": "Polished steel"
        },
        {
          "value": "black",
          "label": "Black"
        }
      ]
    },
    {
      "key": "base",
      "label": "Base",
      "type": "select",
      "default": "walnut",
      "options": [
        {
          "value": "walnut",
          "label": "Walnut"
        },
        {
          "value": "oak",
          "label": "Oak"
        },
        {
          "value": "black",
          "label": "Black"
        }
      ]
    },
    {
      "key": "balls",
      "label": "Balls",
      "type": "integer",
      "min": 8,
      "max": 16,
      "step": 1,
      "default": 12
    },
    {
      "key": "background",
      "label": "Backdrop",
      "type": "color",
      "default": "#1d2430"
    },
    {
      "key": "orbit",
      "label": "Camera drift",
      "type": "boolean",
      "default": true
    },
    {
      "key": "seed",
      "label": "Seed",
      "help": "Changes the wood grain.",
      "type": "integer",
      "min": 1,
      "max": 999,
      "step": 1,
      "default": 5
    }
  ],
  "presets": [
    {
      "id": "default",
      "label": "Brass on walnut",
      "params": {}
    },
    {
      "id": "copper",
      "label": "Copper on oak, warm studio",
      "params": {
        "metal": "copper",
        "base": "oak",
        "balls": 10,
        "background": "#3a2a20"
      }
    },
    {
      "id": "steel",
      "label": "Steel on black, cool studio",
      "params": {
        "metal": "steel",
        "base": "black",
        "balls": 16,
        "background": "#2c3540"
      }
    },
    {
      "id": "noir",
      "label": "Black and chrome",
      "params": {
        "metal": "black",
        "base": "walnut",
        "background": "#77716a"
      }
    }
  ],
  "output": {
    "width": 1080,
    "height": 1080,
    "fps": 30,
    "durationSeconds": 12,
    "posterSeconds": 4,
    "alpha": false,
    "motion": "procedural",
    "loop": {
      "seamless": true,
      "cycleSeconds": 12,
      "method": "Every ball makes exactly one circuit per loop, the balls are evenly spaced in time, and the wheel turns a whole number of cradles per loop (one per ball), so the last frame meets the first."
    },
    "seed": {
      "param": "seed",
      "behavior": "Seed picks the wood grain."
    }
  },
  "composition": {
    "inputs": "Time in seconds; the metal, base and number of balls.",
    "outputs": "A THREE.Group: base, wheel, rails, posts and balls, standing on y = 0.",
    "coordinates": "1 unit = 10 cm. The base is 5.6 wide and 2.5 deep; the sculpture is 4.05 tall. The wheel turns about the z axis at x = 1.2, y = 2.25.",
    "lighting": "Physical metal: needs scene.environment to look like metal; a shadow-casting key light draws the rails' shadows on the base.",
    "timing": "update(time) is a pure function of time; frames render in any order. ballAt(tau) gives a ball's position tau seconds into its circuit.",
    "compatibleWith": [
      "chrome-material",
      "orbit-camera",
      "kinetic-title"
    ],
    "notes": [
      "The speed along the track follows its slope and bends, scaled so the descent fits the time the wheel leaves for it.",
      "With more balls the wheel turns faster and the balls follow more closely."
    ]
  },
  "reuse": [
    "Process explainer: Brass on walnut behind a title about how your pipeline works.",
    "Satisfying loop: Steel on black with 16 balls, camera drift on, for a full-screen loop.",
    "In your own scene: add the group to a desk scene and call update(seconds)."
  ],
  "integration": {
    "newProject": "Set scene.environment (createStudioEnvironment from Chrome Material works), add createBallSculpture().group and a shadow-casting light, and call update(time) each frame.",
    "existingProject": "Copy src/rolling-ball-sculpture.js. Add the group to your scene, scale it, and call update(seconds) every frame."
  },
  "performance": {
    "notes": "About two hundred small meshes built once (rails, ties, posts, spokes); only the wheel and the balls move. Smooth at 1080p on laptop GPUs.",
    "limits": "Shadows from the thin rails are the main cost; lower the shadow map size on slow devices. Software WebGL (no GPU) renders slowly."
  },
  "limitations": [
    "The balls follow the track by design rather than a physics simulation: they never collide or jump.",
    "The track layout is fixed; the parameters change its materials and the number of balls."
  ],
  "license": {
    "spdx": "MIT",
    "notice": "Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.",
    "thirdParty": [
      {
        "name": "three.js",
        "version": "0.185.1",
        "license": "MIT",
        "url": "https://github.com/mrdoob/three.js"
      }
    ]
  },
  "provenance": "Adapted from the owner's threejs-sketches/mechanical-kinetic/perpetual-motion (MIT), rebuilt for AI Pixel Wizard in October 2026 as a finished kinetic sculpture: a cradled lift wheel, twin rails with a guarded spiral, ties, posts and column, a walnut base, slope-driven ball speeds, an exact loop and the frame/time contract.",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2026-10-05",
      "notes": "Initial release."
    }
  ]
}