# Spinning Top — `spinning-top@1.0.0`

A painted tin top whirring on a polished floor, leaning, precessing and wandering in a small circle. Loops perfectly.

A painted tin top spinning on its steel tip on a polished floor: its coloured spiral flickers as it turns, it leans and precesses in a slow circle, wobbles with the nutation of a real gyroscope and wanders in a small orbit across the floor, a bright reflection of it below. Choose the paint (carnival, jade, mono or sunset), how fast it spins, how far it leans, how far it wanders, the backdrop and whether the camera drifts.

- Kind: object; status: published; digest sha256:5ddd85fb2711d8194b0f187b159df658c5b7cacc6940c777de17258fd097213f
- Role: Object (3D, three.js): a playful, hypnotic hero object for toys, nostalgia, physics and focus content.
- Implementation: three; entry `src/spinning-top.js`
- Files: https://aipixelwizard.com/registry/spinning-top/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/spinning-top.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/spinning-top/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/spinning-top/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
- `createSpinningTop({ finish?, spin?, lean?, wander? }) => { group, setProgress(progress), dispose() }` — The top (2.4 tall) as a group standing on its tip on y = 0; add it with an environment map and a shadow-casting light.
- `FINISHES: { carnival, jade, mono, sunset }` — Paint colours.

## Parameters
- `finish` (select one of carnival | jade | mono | sunset, default "carnival") — Paint
- `spin` (integer 8–80, default 36) — Spin: Whole turns about its own axis per loop.
- `lean` (number 0.4–1.8, default 1) — Lean
- `wander` (number 0–2, default 1) — Wander
- `background` (color, default "#1c2a3a") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Time within the loop; the paint, spin, lean, wander, backdrop and camera drift.
- Outputs: A full frame rendered in 3D with soft shadows and a glossy floor.
- Coordinates: The tip stands on y = 0 and wanders on an ellipse of radius up to 0.9; the top is 2.4 tall.
- Lighting: A warm key light with a shadow map and the studio environment on the clear-coated paint, steel and polished floor.
- Timing: setProgress(progress) sets the spin, lean and position; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- The lean's axis rotates twice per loop (precession) while its angle varies by ±15 % eleven times a loop (nutation); the spiral is drawn once on a canvas.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — The top spins a whole number of turns, precesses twice, wobbles eleven times and wanders once round its small circle per loop, 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 createSpinningTop().group and call top.setProgress(progress) each frame.

Existing project: Copy src/spinning-top.js; add top.group to your scene with an environment map and a shadow-casting light.

Reuse ideas:
- Toy brand title: Carnival top.
- Physics explainer: Jade and gold, slow.
- Hypnotic loop: Black and white blur.

## Limitations
- The motion is a prescribed gyroscope-like formula, not rigid-body dynamics: it never slows or falls.
- At high spin counts the spiral strobes at 30 frames a second.

## 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/physics-simulation/spinning-top (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original object: lathe-turned painted tin with a canvas spiral, precession and nutation as whole-cycle sines, a wandering tip on a glossy floor and an exact loop.