# Snow Globe — `snow-globe@1.0.0`

A glass snow globe on a wooden pedestal: shaken once, the snow swirls and settles round a tiny winter scene. Loops perfectly.

A snow globe on a turned wooden pedestal, in a dark, cosy room whose lights show upside down in the glass. Inside, a tiny winter scene under a sphere of liquid glass: a log cabin with glowing windows, a decorated Christmas tree with presents, or a snowman by a lamp post. The globe is picked up and shaken once: the flakes lift, swirl and drift back down onto the snow, and by the end of the loop it is at rest again. Or leave it still and let the snow fall gently for ever. A brass plaque on the front carries your own words. Choose the scene, the wood, the colour of the liquid, the amount of snow and how hard it is shaken, and the room's lights: golden, Christmas or cool.

- Kind: object; status: published; digest sha256:5519ab0fb96cabe4b2bf2dc81de2333851ec60f9565b563dd1ebd10d5098cc5a
- Role: Hero object (Three.js 3D): a festive, nostalgic snow globe for holiday content.
- Implementation: three; entry `src/snow-globe.js`
- Files: https://aipixelwizard.com/registry/snow-globe/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/snow-globe.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/snow-globe/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/snow-globe/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 physical glass (transmission).; `chrome-material@1.1.0` (demo) — Studio environment light and the contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createSnowGlobe({ scene?, base?, plaque?, snow?, tint?, seed?, anisotropy? }) => { group, sphere, height, lift(progress), update(time, loopSeconds, { mode?, shake? }), dispose() }` — The whole globe as a THREE.Group (1 unit = 10 cm, standing on y = 0). update(time, loopSeconds) shakes it once and lets the snow settle, or just lets it fall.
- `createBokehBackdrop(theme?, seed?) => { mesh, dispose() }` — A backdrop of out-of-focus lights made of opaque material, so the glass can refract it.
- `BASES: { walnut, mahogany, ebony }` — Pedestal finishes.
- `SCENES: ['cabin', 'tree', 'snowman']` — The tiny scenes inside.

## Parameters
- `scene` (select one of cabin | tree | snowman, default "cabin") — Scene inside
- `mode` (select one of shake | snowfall, default "shake") — Snow
- `plaque` (text, default "Winter Dreams") — Plaque: The words engraved on the brass plaque.
- `base` (select one of walnut | mahogany | ebony, default "walnut") — Pedestal
- `snow` (number 0.3–1.6, default 1) — Amount of snow
- `shake` (number 0–1.5, default 1) — Shake
- `tint` (color, default "#e6f1ff") — Liquid
- `lights` (select one of warm | christmas | cool, default "warm") — Room lights
- `table` (color, default "#1c1512") — Table
- `seed` (integer 1–999, default 3) — Seed: Changes the flakes, the wood grain and the lights behind.

## Composition
- Inputs: Time within the loop; the scene, snow mode, plaque text, pedestal, liquid colour and room lights.
- Outputs: A THREE.Group: pedestal, plaque, glass globe, the tiny scene and the flakes, standing on y = 0.
- Coordinates: 1 unit = 10 cm. The globe's sphere has a radius of 2.05 and is centred 2.73 above the table; the pedestal is 4 across.
- Lighting: Physical glass and brass: needs scene.environment. The tiny scene carries its own warm lights. The glass refracts opaque meshes only, so a backdrop (createBokehBackdrop) must be opaque to show through it.
- Timing: update(time, loopSeconds) is a pure function of time; frames render in any order. lift(progress) gives the shake's lift for a contact shadow.
- Works with: chrome-material, orbit-camera, kinetic-title
- The plaque text is treated as private: not stored in shared packs unless you choose to include it.
- Everything inside the globe, flakes included, is opaque: three.js transmission refracts only opaque objects.
- The plaque is drawn with the system serif font.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — Shaken: the snow starts and ends at rest on the ground and the shake is zero before and after it. Snowfall: every flake falls through the globe a whole number of times and sways in whole cycles. Either way 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: Set scene.environment (createStudioEnvironment from Chrome Material works), add a createBokehBackdrop mesh behind, add createSnowGlobe().group and call update(time, loopSeconds) each frame.

Existing project: Copy src/snow-globe.js. Add the group to your scene (scale it to suit), keep what is behind the globe opaque, and call update(seconds, loopSeconds) every frame.

Reuse ideas:
- Holiday greeting: Christmas tree with your family name or a wish on the plaque, Christmas lights.
- Seasonal promotion: Cabin in a blizzard behind your offer.
- Looping background: Snowman, gentle snowfall, camera drift on, behind a quote.

## Limitations
- The flakes are simple opaque points, not snowflakes: they are tiny at normal size.
- The shake is choreographed, not simulated: flakes never collide with the scene.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.
- three.js 0.185.1: MIT (https://github.com/mrdoob/three.js)

Provenance: Adapted from the owner's threejs-sketches/objects-scenes/snow-globe (MIT), rebuilt for AI Pixel Wizard in October 2026: a refracting glass sphere on a turned wooden pedestal with a brass plaque, three tiny scenes, a choreographed shake and settle (or an endless snowfall), a refractable bokeh room, and the frame/time contract.