# Billiard Break — `billiard-break@1.0.0`

The cue strikes, a rack of numbered balls bursts across the green baize, then rolls back to the rack. Loops perfectly.

A pool table at a slant under a lamp: the cue draws back and strikes, the white ball runs into the racked triangle and fifteen numbered balls burst across the cloth, bounce off the cushions and slow to a stop; then they roll back one by one into the rack and the cue ball returns to its spot, ready for the next break. Choose the cloth (green, blue, red or black), how hard the break is, the seed, the backdrop and whether the camera drifts.

- Kind: object; status: published; digest sha256:c5d653355d38984cc223ad56000d942fad0327af37b918afcd72451d428e1c7f
- Role: Object (3D, three.js): a satisfying, punchy scene for games, sport, bar and energy content.
- Implementation: three; entry `src/billiard-break.js`
- Files: https://aipixelwizard.com/registry/billiard-break/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/billiard-break.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/billiard-break/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/billiard-break/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 materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createBilliardTable({ cloth?, power?, seed? }) => { group, setProgress(progress), dispose() }` — The table, cue and sixteen balls as a group (10 × 5, cloth on y = 0); the loop is 14 seconds. Add it with an environment map and a light.
- `CLOTHS: { green, blue, red, black }` — Cloth colours.

## Parameters
- `cloth` (select one of green | blue | red | black, default "green") — Cloth
- `power` (number 0.5–1.6, default 1) — Power: How hard the break is.
- `seed` (integer 1–999, default 3) — Seed
- `background` (color, default "#14181f") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Time within the loop; the cloth, power, seed, backdrop and camera drift.
- Outputs: A full frame rendered in 3D with soft shadows.
- Coordinates: The cloth lies on y = 0, 10 along x and 5 along z; the rack stands at x = 2.4 and the cue ball at x = -3.3.
- Lighting: A key light with a shadow map and the studio environment on the glossy balls.
- Timing: setProgress(progress) sets every ball; frames render in any order. The loop's 14 seconds are the cue (0 to 1.5 s), the break (1.9 s), the balls at rest (about 8.8 s), the return (10.6 to 12.8 s) and a pause.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- x(t) = x0 + (v/k)(1 - e^(-kt)), folded into the cushions by a triangle wave; balls roll by the distance travelled.

## Output and loop
- 1080×1080, 30 fps, 14 s, procedural
- Seamless loop: yes — After the strike every ball's place is a closed form of the time (friction-slowed travel folded back by the cushions), then all balls ease back to the rack and the cue ball to its spot before the loop ends, so the last frame meets the first.
- Verified 2026-10-05 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 createBilliardTable().group and call table.setProgress(progress) each frame; use a 14-second loop.

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

Reuse ideas:
- Game-night title: Green baize, a clean break.
- Energetic reveal: Blue cloth, hard break.
- Quiet loop: A soft break.

## Limitations
- The balls do not collide with one another or fall into pockets: they scatter on divergent paths and may pass through each other.
- The rack's order is fixed; there is no cue-ball English.

## 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/billiard-break (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original scene: a closed-form, cushion-folded scatter, numbered balls drawn on canvas, a cue strike and a return to the rack for an exact loop.