Pinata

Build **"Pinata"**: a real-time, interactive 3D papier-mache pinata hanging from a rope in a sunny backyard that people **swing a bat at**, **pull strings on**, **hit blindfolded**, **yank by the rope** and finally **break open**, so it **tears progressively** and **candy spills out** into a bouncing, rolling pile they can **sweep into a bowl**, with **synthesised sound** and a cheering crowd, as ONE self-contained HTML file.

It should feel like the best five seconds of a birthday party: the heavy thwack, the pinata swinging away and coming back, the first crack, the rattle of candy inside, and then the glorious burst. Every hit must feel physical and every break must be different.

## Priorities

Build it in this order, and finish each tier properly before starting the next. A polished tier 1 beats a broken everything.

1. **Must be excellent:** the bat swing and impact, the rope pendulum, progressive tearing of the shell (dents, cracks, hinged flaps, falling pieces), candy that rattles inside, pours out of real holes and settles into a pile; the demo mode.
2. **Must work:** the five tools, the four shapes, the fills, the crepe fringe, the crowd, sound, the control card, the fewest-hits challenge with toasts, the Easter egg.
3. **Polish:** glitter sparkle, the rope teaser, slow motion on the final break, footprints and candy wrappers glinting in the grass.

Never ship a feature half-working: if something from tier 3 can't be done well, leave it out cleanly.

## Deliverable

- One self-contained `.html` file with all JavaScript, WGSL, GLSL and CSS inline. Start the file with `<!doctype html>`, then `<meta charset="utf-8">` and a viewport meta tag.
- **No external requests of any kind**: no libraries, CDNs, web fonts, images, textures or audio files. Generate everything procedurally in code (sound included, see Sound). Use system font stacks.
- It must run inside a sandboxed iframe (`sandbox="allow-scripts allow-pointer-lock"`). Do not use `localStorage`, cookies, `alert`, pop-ups or top-level navigation, and wrap any storage access in `try/catch` (records may simply live in memory for the session).
- This must be a live simulation, not a video, a pre-baked animation, a static render or a 2D fake.
- If the URL has `?test=1`, expose `window.__toy` with functions to drive every tool and read the key state, for automated tests (no visible change): `setTool(n)`, `swing(fromX, fromY, toX, toY, speed)` in normalised screen coordinates, `pullString(i)`, `tugRope(amount)`, `sweep(points)`, `newPinata(shape)`, `setFill(kind)`, `set(name, value)` for every slider and switch, and `state()` returning `{ backend, tool, shape, fill, hits, integrity, broken, candyInside, candyOut, candyInBowl, candyAwake, ropeAngle, pinatasBroken, golden, fps }`.

## The backyard and the pinata

- A sunny backyard in late afternoon: a mown lawn, a painted wooden fence, a big tree whose low branch holds the rope, a string of paper bunting, a soft blue sky. A wide shallow ceramic **candy bowl** sits on the grass at the front left. Seen from a slightly low three-quarter view, as if you are one of the kids. In a square frame the pinata hangs in the upper middle at about head height, with plenty of lawn below it where the candy lands.
- **Shapes:** **Donkey** (the default: barrel body, four stubby legs, long ears, a tail of streamers), **Star** (a sphere with seven cones), **Unicorn** (horse body, gold horn, rainbow mane) and **Llama** (long neck, fluffy fringe, little saddle). About 50 to 70 cm long, built procedurally.
- **Construction:** each pinata is a thin hollow shell of layered papier-mache over cardboard, covered in rows of **crepe-paper fringe** in bright stripes (hot pink, orange, sunshine yellow, turquoise, lime). Torn edges show the inside: grey-brown fibrous cardboard edges with layered paper, a dark hollow interior, glue streaks. A small **trap door** with ribbons sits underneath (used by Pull strings).
- **Fills** (chosen before the break, applied to the next pinata or the current one if unbroken): **Candy** (the default: wrapped sweets with twisted ends, gumballs, lollipops, foil chocolate coins, jelly beans, about 300 to 500 pieces), **Confetti** (thousands of paper flakes), **Glitter** (sparkling flakes that catch the sun) and **Mini pinatas** (8 tiny pinatas of the same shape that bounce and can be hit too).

## Physics

- **Rope:** a chain of 16 to 24 segments (position-based or Verlet with distance constraints) tied to the branch, carrying the pinata as a **rigid body** hung by its back so it swings as a real pendulum, twists on the rope, and wobbles when hit off-centre. The rope never stretches or snaps sideways, and the pinata never clips through the branch or the ground.
- **The shell tears progressively.** Precompute at start a breakup of the shell into about 150 to 400 panels (Voronoi or seam-based), joined by **breakable hinges** with health. Each hit spreads damage around the impact point:
  - light damage leaves **dents** that stay (vertices pushed in, the fringe crumpled);
  - more damage opens **cracks**: visible dark tears along panel seams;
  - a panel holding by one hinge becomes a **flap** that swings and flutters on that hinge;
  - a panel with no hinges left **falls off** as its own rigid piece, tumbling and landing on the lawn;
  - holes grow from the damage; once the shell loses enough of itself (or one very hard hit lands on a weakened shell) it **splits** into 2 to 5 big chunks along its cracks: the **final break**.
- **Candy is real and inside the shell.** Before the break, the candy pieces are simulated inside, colliding with the shell's inner surface, so a hit makes them **rattle** and a turned pinata shifts its load. They pour out only through actual holes and open flaps, never spawned from nowhere. On the final break they burst out with the momentum of the hit.
- **Candy on the lawn:** spheres and capsules (wrapped sweets roll differently from coins, which slide, flip and settle flat). They bounce, roll, collide with each other and with fallen shell pieces, and **settle into a natural pile** under where the pinata was. Use a spatial hash for candy contacts and **sleeping** so a settled pile costs nothing and never jitters. No candy ever tunnels through the ground, the bowl or other candy.
- **Crepe fringe:** about 300 to 800 strips, each a short chain of 4 to 6 particles hinged to its panel, fluttering with motion and a gentle breeze. Hard hits **shed strips** that flutter down like leaves; strips stay with their panel when it falls off.
- **Toughness** slider: at medium swing speed a pinata takes about 3 hits (paper) to 12 hits (cardboard brick) to break.
- **Fixed simulation timestep** with bounded substeps, decoupled from frame rate. On a slow frame, drop simulation time rather than exploding.

## Tools

A tool picker with **Bat**, **Pull strings**, **Blindfold**, **Rope** and **Grab candy**, keys `1` to `5`. The default tool is Bat. A press that ends within 6 px and 450 ms counts as a tap. Right-drag or two fingers orbit the camera on every tool. Use pointer events with **pointer capture** so drags never drop, and support mouse, pen and touch.

### 1 Bat
- A wooden bat held from the bottom of the frame follows the pointer arc. **Drag to swing**: the bat moves with the drag, and its speed at contact sets the impact strength.
- Collide the swept bat (a capsule swept between frames, so fast swings never pass through) with the pinata. A slow swing only pushes it on its rope; a fast one thwacks it away with a dent, crack or tear at the exact point hit, sheds fringe and makes the candy inside rattle. A tap is a small poke.
- After a hit the pinata swings away and comes back on the rope, so timing the next swing matters.

### 2 Pull strings
- The pinata becomes a **pull-string pinata**: 10 ribbons in different colours hang from the trap door. Drag a ribbon down to pull it: it stretches the shell a little, then either **comes off in your hand** (wrong one, small sad sound, ribbon flutters to the grass) or is the one (chosen at random per pinata) that **swings the trap door open on its hinge** and lets the candy pour out in a stream.

### 3 Blindfold
- The bat, but blindfolded: the screen darkens to a soft fabric-edged vignette with a narrow dim slit, the view **spins three times** at the start and then sways gently, and the bat follows the pointer with a little lag so hits are harder to aim. The crowd laughs, gasps "oooh" at near misses and cheers at hits. A blindfold break counts as its own record. Switching tool takes the blindfold off.

### 4 Rope
- Drag the rope (anywhere on it) to **tug** it: a quick upward flick makes the pinata jump, a sideways drag swings it. A **Rope teaser** switch lets an invisible party host yank the pinata up and away from about one swing in four.

### 5 Grab candy
- Drag across the lawn to **sweep** candy with a soft hand: pieces slide and roll ahead of it and can be pushed into the bowl, where they stack with a clink. A tap picks up one piece and drops it in the bowl. The bowl counts what it holds.

## Challenge, milestones and Easter egg

- **Fewest hits:** each pinata counts the hits that land until the final break; the best (lowest) count per shape is kept for the session and shown in the readouts.
- Toasts (top centre, once each): "First crack!", "Candy's coming", "Smashed it in N hits", "Clean break: 3 hits or fewer", "Blind luck" (blindfold break), "Right string, first pull", "100 candies in the bowl", "Every shape broken".
- **Easter egg:** after **10 pinatas** have been broken in a session, the next new pinata is a **golden** one: gold-foil fringe, a soft sparkle, a heavier thud; it breaks into a shower of gold coins with a little fanfare and a toast "The golden pinata." Never hint at it in the UI.

## Sound

Every action has a **synthesised sound effect**, generated live with the **Web Audio API** (oscillators, filtered noise, envelopes). **No audio files, no samples, no external requests.**

- **Swing:** a whoosh whose pitch and loudness follow the bat speed.
- **Hit:** a deep cardboard **thwack** (low thump plus a short noise burst), papery and crunchier as the shell weakens, plus the candy **rattle** inside.
- **Tearing:** crackly rips when cracks open, a flap flutter, a soft thud when a piece lands.
- **Final break:** a big crunch, then the candy rain: a cascade of tiny clicks pitched by piece type (plastic ticks, foil chinks, soft thuds on grass).
- **Rope:** a creak on big swings and tugs. **Pull strings:** a ribbon zip, a pop when one comes off, a hinge creak when the trap door opens.
- **Bowl:** ceramic clinks as candy lands. **Crowd:** a murmur, "oooh" gasps and cheers made from formant-filtered noise, claps, and laughter for the Blindfold, all on their own **Crowd volume** slider. **Golden pinata:** a short bright fanfare.

Rules:
- Create the `AudioContext` only on the first user gesture and never before. Resume a `suspended` context on interaction, and wrap every audio call in `try/catch` so a failure can never break the toy.
- A master gain into a compressor, no clipping. Cap simultaneous voices at about 16 (candy clicks are pooled and thinned, never piled up).
- A **mute button** with a speaker icon, sound on by default, `M` toggles it.

## Camera and keys

- **Camera:** right-drag or two fingers orbit within limits (never below the lawn, never behind the fence); the wheel or a pinch zooms from the default view down to a close-up of the pinata; double-click the sky or press `0` to reset the view.
- **Keyboard:** `1` to `5` tools, `N` new pinata, `S` cycles shape, `F` cycles fill, `C` Cinema, `M` mute, Space pauses or resumes, `R` resets (new pinata, lawn cleared, bowl emptied), `0` resets the view.

## Rendering

**WebGPU (WGSL) when available, with an automatic WebGL2 (GLSL) fallback that looks the same.** Detect at start; if WebGPU is missing or adapter or device creation fails, use WebGL2. Show which one runs in the status pill: `WEBGPU · LIVE` or `WEBGL2 · LIVE`. No libraries: write both paths yourself, sharing the scene data and the simulation.

Aim for a bright, warm party photo, not a cartoon and not a grey physics demo.

- **Sunlight** with a real **shadow map**: the pinata, rope, fringe and candy cast soft shadows on the lawn; a cool sky fill and soft ambient occlusion where candy piles up.
- **Crepe fringe:** instanced thin strips, two-sided, with light shining through them when backlit and a crinkled paper sheen.
- **Shell:** matte paper on the outside, fibrous torn edges with visible layers, a dark interior visible through holes and cracks.
- **Candy:** glossy wrappers with sharp highlights, foil coins with metallic reflections, translucent gumballs and jelly beans. Glitter sparkles as tiny view-dependent glints.
- **Lawn:** dense, slightly varied grass (instanced or shaded), with candy nestling into it; the fence, tree and bunting soft in the background.
- **Post:** HDR with filmic tone mapping, gentle bloom on foil and glitter, a light vignette. Keep the image crisp.
- Build all pipelines and preallocate every buffer (candy, panels, fringe, particles) at start; never create shaders, pipelines or geometry during interaction (precompute the panel breakup for all four shapes up front or in a short startup step). Handle resize, DPR capped at 2.
- An automatic **quality scaler**: if the frame rate drops, reduce resolution, shadow size, fringe strip count and post effects before ever touching the physics feel.
- Only if neither WebGPU nor WebGL2 exists, show a clear, well-designed message explaining why the toy can't run.

## Interface

A light, party-bright interface that stays out of the way. The pinata is the hero, and the UI must never cover it on desktop or mobile.

**Top left:** small caps `POKEABLE · SPECIMEN 010`, a large italic serif heading on two lines: *Whack the* / *Pinata.*, and caption lines: "Swing hard." / "It's full of candy." / "Everyone's watching."

**Top right:** a small live status dot with `WEBGPU · LIVE` or `WEBGL2 · LIVE`, a **speaker icon button** (`ON` / `MUTED`), and `PAUSED` when paused.

**Right panel: control card "Party"**

A **floating control card** about 240px wide with 20px corners, a soft off-white fill, a soft drop shadow and no hairline borders, in the plain system sans-serif. A bold sentence-case title, bold sentence-case section labels, tools as rounded tiles with small drawn icons and key numbers (the active one tinted and ringed in a **hot pink** accent), chunky sliders (6px rounded track filled with the accent, round white thumb) with live values in small rounded monospace chips, secondary buttons as light-grey chips without borders, on/off switches (label left, switch right), and **Pause / Resume** as a solid dark full-width pill. The card collapses to a small button; on narrow screens it becomes a bottom sheet with rounded top corners.

- Tools: **Bat**, **Pull strings**, **Blindfold**, **Rope**, **Grab candy**.
- **Shape** chips: Donkey, Star, Unicorn, Llama. **Fill** chips: Candy, Confetti, Glitter, Mini pinatas.
- Sliders: **Toughness** (paper to cardboard), **Crowd volume**, **Sound** (master volume).
- Buttons: **New pinata**, **Reset**, **Mute**.
- Switches: **Slow-mo break** (the final break plays at ¼ speed for about 1.5 s, then eases back), **Slow motion** (¼ speed always), **Rope teaser**.
- A **Pause / Resume** pill.

**Bottom left:** a one-line hint that changes with the tool:
- Bat: "Drag to swing. Faster hits harder."
- Pull strings: "Pull a ribbon. Only one opens the door."
- Blindfold: "Swing blind. Listen to the crowd."
- Rope: "Tug the rope. Make it dance."
- Grab candy: "Sweep the candy into the bowl."

Under it, live readouts computed from the simulation: **hits**, **shell** (% intact), **candy out**, **in bowl**, **best** (fewest hits for this shape). Values update smoothly, not every frame.

**Bottom right:** a collapsible **"How it breaks"** panel, 4 to 6 plain-English lines on the rope pendulum, the panels and breakable hinges, the candy inside, the settling pile and the synthesised sounds.

Toasts appear top centre. **Cinema** (`C`): hides every piece of UI and the cursor (the bat stays); a tap without a drag, `C` or Esc brings it back.

Respect `prefers-reduced-motion`: soften UI transitions, skip the blindfold spin and camera shake. The toy still responds fully.

## Demo mode (required)

If the URL has `?demo=1`, auto-play a 4-second loop with no user input: the object drops in, wobbles, gets poked or sliced once, then settles.

For this toy that means:
- **Hide all UI** and the cursor. The bat is visible, swung by the demo.
- One **fixed demo quality preset** (no quality scaler), the Donkey, Candy fill, default toughness, no crowd.
- **Sound is completely off:** never create an `AudioContext`.
- A fixed camera at the default view, the pinata and the lawn below it filling the square frame.
- **Deterministic:** fixed seed for the panel breakup, the candy and every split, no randomness. Restart every 4.0 s of real time from the identical state. Drive the simulation from real elapsed time with the fixed timestep, so the loop lasts 4 s even at low frame rates. Start moving within 1 second.
- Timeline:
  - **0.0 to 0.6 s:** the pinata swings gently on its rope, fringe fluttering.
  - **0.6 s:** the first swing from the right lands: a thwack, the pinata swings away, a visible dent and crack, a few fringe strips fly off.
  - **1.0 to 1.6 s:** it swings back towards the bat.
  - **1.6 s:** the second swing **splits it open** into chunks; candy bursts out.
  - **1.6 to 3.2 s:** candy rains, bounces and rolls into a pile on the lawn; chunks and fringe land around it.
  - **3.2 to 4.0 s:** the pile and pieces shrink away in a quick sparkle while a fresh pinata lowers in on the rope and bobs, ending in exactly the starting pose and swing, so the loop restarts cleanly.
- Recorded in a slow software renderer: **the dent, the split and the candy burst must read clearly at 15 fps**. Keep counts modest in demo (about 200 candies, fewer fringe strips).
- `?demo=1&t=<seconds>` freezes the demo at that time (for screenshots).

## Before you finish

Self-check against this list and fix anything that fails:
- Swing slowly, fast, from both sides and at the edges: slow swings push, fast ones dent, crack and tear exactly where hit; the bat never passes through the pinata; flaps hinge, pieces fall, and every break looks different.
- Candy rattles inside, pours only through real holes, settles into a pile that never jitters, and never falls through the lawn or the bowl.
- Every tool, shape, fill, slider and switch at both extremes, plus New pinata, Reset, pause and resume, Slow-mo break, Cinema, keys `1` to `5`, `N`, `S`, `F`, `C`, `M`, Space, `R`, `0`, and resizing to phone width.
- Pull every ribbon, break one blindfolded, sweep 100 candies into the bowl, break 10 pinatas and find the golden one.
- Sound: every action has its effect, nothing plays before the first gesture, mute, crowd and master volume work, a candy rain never clips.
- `?demo=1` matches the timeline, loops cleanly, shows no UI and plays no sound; `?test=1` exposes `window.__toy`.
- No console errors on WebGPU AND on WebGL2 (force the fallback to test it), and it stays smooth on a mid-range phone.

Put the thwack, the swing on the rope and the candy burst first. It should make people swing again just to see how it breaks this time.