# Confetti Burst — `confetti-burst@1.0.0`

A cannon fires hundreds of tumbling paper confetti in the party colours: they fly, flutter and drift down. One-shot, seeded and exact.

A celebration: a cannon at the bottom of the frame fires hundreds of pieces of paper confetti. Each piece is a small rectangle, ribbon or disc with its own colour, speed and spin; it flies on an arc with air drag, tumbles in 3D (it thins to a line when edge-on and darkens on its underside) and flutters down. Choose the number of pieces, the colours (party, gold, pastel or mono), the launch (one cannon, two corner cannons or a shower from above), the power, the seed and the backdrop colour.

- Kind: effect; status: published; digest sha256:bcd7c26c0267f6c44112b0049428e8e69d9bcf8419ca5d2b1709cf43d069d8c3
- Role: Effect overlay (Canvas 2D): the celebration moment for wins, launches and milestones.
- Implementation: canvas2d; entry `src/confetti-burst.js`
- Files: https://aipixelwizard.com/registry/confetti-burst/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/confetti-burst.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/confetti-burst/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/confetti-burst/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `apw-runtime@1.0.0` (demo) — Demo harness. The reusable source has no dependencies.

## Exports
- `createConfettiBurst({ pieces?, palette?, at?, mode?, power?, seed? }) => { draw(ctx, info, width, height), revealDuration }` — Canvas 2D effect layer driven by info.time (seconds); draws on top of the canvas.
- `PALETTES: { party, gold, pastel, mono }` — Confetti colour sets.

## Parameters
- `pieces` (integer 60–900, default 420) — Pieces
- `palette` (select one of party | gold | pastel | mono, default "party") — Colours
- `mode` (select one of cannon | twin | rain, default "cannon") — Launch
- `power` (number 0.6–1.5, default 1) — Power
- `seed` (integer 1–999, default 21) — Seed
- `background` (color, default "#1b1530") — Backdrop

## Composition
- Inputs: Canvas 2D context, info.time (seconds), width, height.
- Outputs: Draws the confetti on top of the canvas; does not clear it.
- Coordinates: Positions are fractions of the canvas; the cannon is at the bottom centre (or the corners), the shower starts above the top edge; sizes scale with the smaller side.
- Lighting: None; undersides are drawn darker.
- Timing: Pure function of time since the burst and a seeded number per piece; revealDuration says when the last piece has gone.
- Works with: kinetic-title, gradient-background
- Each piece follows v(t) = v0 e^(−kt) with a terminal fall speed, so frames can be rendered in any order.

## Output and loop
- 1080×1080, 30 fps, 6 s, procedural
- Seamless loop: no — Not a loop: the burst fires at 0.6 s and the pieces fall out of frame.
- Verified 2026-10-08 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (Canvas 2D); deterministic: yes

## Use it
New project: Create the burst once, then each frame draw your picture and call burst.draw(ctx, { time: frame / fps }, width, height).

Existing project: Copy src/confetti-burst.js. Call draw on your existing 2D canvas after the rest of the frame.

Reuse ideas:
- Win moment: Party cannon.
- Premium launch: Gold, two cannons.
- Soft greeting: Pastel shower.

## Limitations
- Pieces do not collide or pile up on the ground; they leave the frame.
- The 3D tumble is simulated by squashing flat shapes, not true 3D.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Original code written for AI Pixel Wizard in October 2026, to the catalog quality bar (docs/QUALITY.md).