Boom Island

Build **"Boom Island"**: a real-time, interactive 3D **tiny floating island diorama** (a harbour village, a lighthouse, a windmill, a stone bridge, a watchtower, palm trees, a pirate ship in the bay and two dozen tiny islanders) that people destroy with a toolbox of **eight wildly different, physically real tools**: a **giant finger**, a **ship's cannon**, **dynamite**, a **laser**, **meteors**, a **tornado**, a **black hole** and a **freeze ray**. Every building **fractures into real pieces** that **lean, topple, tumble, splash and pile up**, with **instant slow-motion replays** and **synthesised sound**, as ONE self-contained HTML file.

It should feel like the best sandcastle you ever built, and the joy of wrecking it: a tower that leans for a heartbeat before it goes, a clean laser cut where the top half slowly slides off, a demolition that drops a lighthouse straight into its own footprint, tiny islanders running for their lives. Each tool must feel completely different in the hand, and no two collapses may look the same.

## 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:** buildings that stand perfectly still at rest; fracture exactly where hit into convincing chunks; collapse under their own weight when support is lost (lean, hesitate, fall); debris that tumbles, bounces, lands and goes back to sleep without jitter; the **Finger**, **Cannon** and **Dynamite** tools; Rebuild; the demo mode.
2. **Must work, and feel great:** **Laser**, **Meteor**, **Tornado**, **Black hole**, **Freeze**, **Quake**; the islanders; **Replay**; chain reactions and the scoring; splashes; sound; the control card; the Easter egg.
3. **Polish:** dust clouds, sparks, drifting smoke, scorch marks, sea ripples, molten glow on laser cuts, frost creeping over frozen buildings, slow motion on big collapses, the rebuild fly-in.

Never ship a feature half-working: if something can't be done well, leave it out cleanly. Seven great tools beat eight with a broken one.

## 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 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. Collapses are computed, never canned.
- 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)`, `tap(x, y)` and `drag(points)` in normalised screen coordinates (using the current tool), `hold(x, y, seconds)`, `detonate()`, `quake(strength, seconds)`, `rebuild()`, `replay()`, `set(name, value)` for every slider and switch, and `state()` returning `{ backend, tool, destruction, buildingsDown, bodiesAwake, bodiesTotal, debrisInSea, charges, frozen, islandersDown, bestChain, bestShot, replaying, fps }`.

## The island

- A round **floating island** about 40 m across, seen as a diorama from a three-quarter view above: a green top with sandy paths and grass, beaches, a cut-away rocky underside with layered strata and dangling roots, floating over a calm turquoise sea that fills the frame edge to edge. In a square frame the island fills about 70% of the width.
- **Buildings and props**, all built procedurally from simple shapes and **pre-fractured at start**:
  - a striped red-and-white **lighthouse** on a rocky point, tall enough to topple dramatically, with a glowing rotating lamp;
  - a **harbour village** of 6 to 8 houses with plaster walls, timber frames, tiled roofs, chimneys and glass windows;
  - a **windmill** with turning sails (the sails keep spinning as a falling body when knocked off);
  - a **stone arch bridge** over a small creek (knock out the keystone and the arch fails);
  - a wooden **watchtower** on four stilts;
  - a **pier** with barrels and crates;
  - 8 to 12 **palm trees** (trunk segments plus fronds) that snap and fall;
  - a **pirate ship** anchored in the bay, rocking on the waves, which can be holed and sink.
- **Structure:** each building is a stack of **pieces** (wall panels, floor slabs, roof sections, columns, tower drums, stilts), and each piece is pre-fractured into **4 to 20 convex chunks** (seeded Voronoi or slicing) that start welded together as one rigid body. Touching pieces are joined by **breakable welds** with a strength. Pieces carry the load of the pieces above them, so knocking out a column matters.

## The islanders

- About **24 tiny islanders** (around 1.2 m tall, simple chunky capsule bodies with round heads, bright clothes, no faces beyond two dot eyes) who stroll the paths, stand on the pier, fish off the rocks and wave from windows.
- When anything breaks or explodes near them they **panic and run** away from the danger with a quick waddle and arms up, along the paths when they can; a tiny synthesised "aah!" in a few different pitches. They avoid craters and debris.
- A blast, a falling chunk or the finger **knocks them over**: they tumble as small rigid bodies (cartoon, never gory, no blood), lie dazed for a moment with little spinning stars, then **get up and keep running**. In the water they bob, swim to shore and climb out shaking off. They never die; they are part of the fun, not a target score.
- Rebuild walks them back to their places.

## Physics

- **Rigid bodies with real stacking:** convex chunks (or boxes approximating them), impulse-based or XPBD, gravity, restitution, static and kinetic friction, a broadphase (spatial hash or sweep-and-prune).
- **Resting contact is the hard part.** An untouched island must stand forever with **no jitter, no sinking, no creep and no slow collapse**. Every body starts **asleep** and only wakes from an impact, a tool or a woken neighbour; settled debris goes back to sleep within about 2 seconds. A fully settled scene costs almost nothing.
- **Fracture:** an impulse above a piece's threshold breaks the welds near the impact point; the chunks closest to the hit detach as their own bodies with the right velocities, the rest stays welded. Bigger hits break more. One small hit never turns a whole building to dust.
- **Collapse under load:** a piece that loses the support below it becomes dynamic and falls: a tower **leans, hesitates, then topples** as a mostly intact upper section that breaks apart when it lands. Track **chains**: a falling building that breaks another counts as a chain link.
- **The sea:** debris that falls off the island splashes (particle burst plus an expanding ripple ring); wood floats and drifts for a while, stone sinks, then pieces are removed. The ship sinks bow first after 3 hits.
- **The island** is static, but explosions and meteors carve shallow **craters** in the grass top (a terrain height dent plus scorch), never through the island.
- **Budgets:** about 1,500 to 3,000 chunks in total, a cap on awake bodies (fade out the smallest, farthest debris first), no body ever tunnels through the ground or flies off at absurd speed. **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 eight tools, keys `1` to `8`. The default tool is Finger. 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**, and support mouse, pen and touch. Each tool has its own cursor or 3D marker on the island showing exactly where it will act.

### 1 Finger
- A huge soft cartoon fingertip comes down from the sky. **Tap** pokes: a firm push at that point (topple a palm, knock over an islander, nudge a chimney off). **Drag** on any loose piece, chunk, whole building section or islander to **pick it up** through a capped spring and **throw** it with the release velocity. **Flick** (a fast short drag) flicks things hard. Press and hold on top of a building to **press down** and crush it slowly from above.

### 2 Cannon
- The pirate ship fires. Tap a target: the ship turns, fires a heavy cannonball on a real ballistic arc (smoke puff, recoil), and the ball **punches through**: thin walls get a clean hole, columns and stilts get knocked out so what stood on them collapses. The ball keeps some speed and can hit a second thing. Hold to fire a 5-ball **broadside** spread around the target.

### 3 Dynamite
- **Controlled demolition.** Tap pieces to stick red dynamite sticks on them (up to 12, each with a small number badge showing firing order). Then press the big **Detonate** button (or `Enter`): the charges fire in order with a short delay between them (the **Delay** slider, 0 to 0.5 s), each a small sharp blast that blows out its piece. Placed well, a lighthouse **drops straight into its own footprint** like a real demolition; placed badly, it falls the wrong way. A double tap places a single charge and detonates it at once. `Backspace` removes the last charge.

### 4 Laser
- **Drag a line across the screen** to fire a bright beam along it: everything the line crosses is **cut along that plane** (the plane through the camera and the drawn line). Split every chunk the plane crosses into two convex halves with a clean flat cut face (clip the convex hull by the plane; fall back to cutting along chunk boundaries only if that fails), break the welds across the cut, and let gravity do the rest: the top half of a tower **slowly slides off along the cut**. Cut faces **glow molten orange** and cool to dark over 3 seconds; sparks and a thin smoke line follow the beam.

### 5 Meteor
- Tap a point: after a falling whistle, a glowing meteor streaks in from the sky with a smoke trail and hits with a **big explosion**, a deep crater, a shockwave ring and a dust cloud. Drag to rain a **meteor shower** along the path. A 1.5-second cooldown ring around the cursor.

### 6 Tornado
- Press and drag to steer a **tornado** across the island: a twisting translucent funnel of dust and debris. It **lifts** loose debris, palms, roof tiles and islanders into a rising spiral, tears weak pieces off buildings it passes, and flings things out at the top. Release: it weakens and drops everything it carries over about a second. Use a simple vortex force field (tangential plus inward plus updraft, falling off with radius and height).

### 7 Black hole
- Tap a point above the island to open a small black hole for about 3 seconds: a black sphere with a bright ring and lensing-style distortion around it. It **pulls** everything awake towards it with increasing force, ripping chunks off nearby buildings and **squeezing debris into a tumbling ball**, then **collapses with a pop** that throws everything outwards. Hold to keep it open longer (up to 6 s). Islanders are never swallowed: they are spat out first, spinning.

### 8 Freeze
- Tap a building (or drag across several): a freeze beam turns it to **ice**: frost creeps over it in about 0.5 s and it becomes glassy, translucent blue. Frozen pieces are **brittle**: any later hit, fall or blast **shatters** them into many small, sharp, glassy shards with a crystal tinkle instead of breaking into chunks. Frozen islanders become little ice statues that thaw after 4 seconds. Rebuild thaws everything.

### Quake (not a tool)
- Hold the **Quake** button in the card or the `Q` key to shake the island with rising strength while held, waking everything: weak buildings crumble first, tall ones sway and fall, islanders stumble. Releasing fades it out over a second. **Quake strength** slider.

## Replay, scoring and Easter egg

- **Replay** (`P`, and a button that appears briefly after any big event): instantly replays the last **5 seconds** in **slow motion** (½ speed) with an automatic cinematic camera that orbits slowly around the action, then returns to live. Record body transforms (awake bodies only, at about 30 Hz into a ring buffer) and interpolate on playback, so replays are exact. Tools are disabled during a replay; a tap ends it.
- **Rebuild** (`R`): every piece flies back into place in reverse, a satisfying 1.5-second rewind with a whoosh, ending in exactly the starting island (cut chunks merge back, ice thaws, craters fill, islanders walk home).
- **Destruction %:** the share of the island's starting building mass no longer welded in place, shown live. **Best shot:** the largest destruction % gained from one tool action. **Best chain:** the longest chain of buildings knocking each other down. A small **"chain x3"** counter pops up next to the action as chains happen.
- Toasts (top centre, once each): "First crack", "Timber!", "The lighthouse is down", "Perfect demolition" (the lighthouse falls within its own footprint), "Clean cut" (a laser cut drops a top section of 5+ m), "Ship sunk", "Chain x3", "Into the void" (black hole with 100+ chunks), "Brr" (shatter a frozen building), "One shot, 25%", "Nothing left standing" (95%+).
- **Easter egg:** after the island has been flattened (95%+) **three times** in a session, a giant golden **rubber duck** floats into the bay. Hitting it with any tool sets off a confetti explosion, every islander cheers, and a toast says "Quack." 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.**

- **Finger:** a soft boop on poke, a whoosh on throw. **Cannon:** a sharp boom, a short whistle in flight, an impact crunch. **Dynamite:** a fuse fizz while placing, then a fast tight series of cracks, then the rumble of the collapse.
- **Laser:** a high, rising electric hum while the beam sweeps, a sizzle where it cuts, a grinding slide as the top section moves. **Meteor:** a falling whistle, then a deep thump with a sub-bass sweep and a long rumbling tail. **Tornado:** a roaring wind that rises with speed, with debris clatter inside. **Black hole:** a deep rising drone and a suction whoosh, then a pop. **Freeze:** a crackling frost, then glassy tinkles when frozen pieces shatter.
- **Breaking:** stone grinds and cracks, wood splinters and snaps, roof tiles clatter, window glass tinkles; pitched and filtered by material and chunk size. **Debris landing:** thuds and clatters, pooled and thinned so a big collapse never piles up voices. **Water:** splashes and plops by size. **Islanders:** tiny "aah!"s and a cheer, made from formant-filtered tones, never more than three at once.
- **Replay:** a soft tape-slow-down sweep in and a speed-up out. **Rebuild:** a rising reverse whoosh. **Ambient:** soft waves and seagulls on their own **Ambience** slider.

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.
- A **mute button** with a speaker icon, sound on by default, `M` toggles it.

## Camera and keys

- **Camera:** right-drag or two fingers orbit around the island within limits (never below the sea); the wheel or a pinch zooms from the default view down to street level; a small **camera shake** on big explosions (scaled by size); double-click the sky or press `0` to reset the view.
- **Keyboard:** `1` to `8` tools, `Enter` detonate, `Backspace` remove last charge, `Q` hold to quake, `P` replay, `R` rebuild, `C` Cinema, `M` mute, Space pauses or resumes, `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, sunny miniature, like a tilt-shift photo of a toy diorama, not a grey physics demo.

- **Sunlight** with a real **shadow map** that updates as pieces move; a cool sky fill and soft ambient occlusion in corners and debris piles.
- **Materials:** plaster walls, terracotta roof tiles, grey stone, warm timber, the red-and-white lighthouse stripes, glossy palm fronds, glass windows. **Fracture faces show the inside** (rough stone grain, splintered wood, brick behind plaster), laser cut faces are flat and smooth with a molten glow, ice is translucent with frosted edges and sharp highlights.
- **Effects:** an additive fireball fading to smoke, a fast shockwave ring, sparks, dust puffs where debris lands, smoke that drifts with the wind, scorch decals in craters, the tornado funnel (layered rotating dust sprites), the black hole's ring and screen-space distortion, frost creeping as an animated mask, splashes and ripple rings on the sea. All particles are instanced sprites from preallocated pools.
- **Sea:** a turquoise shaded water plane with soft waves, sparkle and a lighter shallow band around the island.
- **Post:** HDR with filmic tone mapping, bloom on fireballs, laser cuts and the lighthouse lamp, a gentle tilt-shift blur at the top and bottom of the frame, a light vignette. Keep the island itself crisp.
- Draw chunks with **instancing** (one draw per material, not per chunk). Laser cuts create new chunk geometry: allocate it from a preallocated pool, never new GPU buffers. Build all pipelines and preallocate every buffer at start; never create shaders or pipelines during interaction. Handle resize, DPR capped at 2.
- An automatic **quality scaler**: if the frame rate drops, reduce resolution, shadow size, particle counts 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, sunny interface that stays out of the way. The island is the hero, and the UI must never cover it on desktop or mobile.

**Top left:** small caps `POKEABLE · SPECIMEN 013`, a large italic serif heading on two lines: *Boom* / *Island.*, and caption lines: "It took ages to build." / "It takes one second to break." / "Go on."

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

**Toolbar (bottom centre):** the eight tools as a row of big round tool buttons with small drawn icons (a finger, a cannon, a dynamite stick, a laser beam, a meteor, a tornado, a black hole, a snowflake) and key numbers, the active one lifted and ringed in a **fiery orange** accent. On phones it scrolls sideways. When Dynamite is active and charges are placed, a big red **Detonate** button with the charge count pops up beside it.

**Right panel: control card "Demolition"**

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, 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.

- Sliders: **Power** (scales every tool's force), **Delay** (dynamite), **Quake strength**, **Building strength** (sandcastle to concrete: scales every weld threshold), **Gravity**, **Ambience**, **Sound** (master volume).
- Buttons: **Quake** (hold), **Replay**, **Rebuild**, **Mute**.
- Switches: **Slow-mo boom** (big explosions and collapses play at ¼ speed for about 1.5 s, then ease back), **Slow motion** (¼ speed always), **Wind**, **Islanders** (on by default).
- A **Pause / Resume** pill.

**Bottom left:** a one-line hint that changes with the tool:
- Finger: "Tap to poke. Drag to pick up and throw."
- Cannon: "Tap a target. Hold for a broadside."
- Dynamite: "Place charges, then Detonate."
- Laser: "Draw a line to slice through anything."
- Meteor: "Tap to call a meteor. Drag for a shower."
- Tornado: "Drag to steer the tornado."
- Black hole: "Tap to open a black hole. Hold for longer."
- Freeze: "Freeze it. Then break it."

Under it, live readouts computed from the simulation: **destruction** (%), **buildings down**, **best shot**, **best chain**, **debris** (awake / total). Values update smoothly, not every frame.

**Bottom right:** a collapsible **"How it breaks"** panel, 4 to 6 plain-English lines on the pre-fractured chunks and breakable welds, load and support, plane cuts, force fields (tornado, black hole), sleeping bodies and the synthesised sounds.

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

Respect `prefers-reduced-motion`: soften UI transitions, skip camera shake, and snap back on Rebuild instead of the fly-in. 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.
- One **fixed demo quality preset** (no quality scaler), default strength and gravity, wind on, islanders on.
- **Sound is completely off:** never create an `AudioContext`.
- A fixed camera at the default view, the whole island filling the square frame with sea around it.
- **Deterministic:** fixed seed for the fracture pattern, the islanders and every impulse, 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.4 s:** the island floats in and settles with a tiny bob; windmill sails turning, the ship rocking, islanders strolling.
  - **0.4 s:** the ship fires; the cannonball arcs across the bay.
  - **0.9 s:** it **punches through the base of the lighthouse**: chunks burst out, the tower leans, islanders start running.
  - **1.2 to 2.0 s:** the lighthouse **topples** across two houses, breaking apart as it lands; a chain reaction, dust rolling over the roofs, chunks splashing into the sea, a couple of islanders tumbling.
  - **2.0 to 3.2 s:** debris tumbles down the cliffs and settles; smoke drifts; the islanders get up.
  - **3.2 to 4.0 s:** **Rebuild**: every piece flies back into place and the islanders hop back to their spots, ending in exactly the starting pose so the loop restarts cleanly.
- Recorded in a slow software renderer: **the hit, the lean and the fall must read clearly at 15 fps**. Keep counts modest in demo (about 800 chunks, fewer particles).
- `?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:
- Leave the island untouched for a minute at every Building strength and Gravity setting: nothing jitters, sinks, creeps or falls.
- Use every tool on every building, gently and at full Power: each tool feels distinct, breaks happen where hit, unsupported parts fall, towers lean before they go, chains happen, debris settles and sleeps, nothing tunnels through the ground or flies off at absurd speed.
- Laser: cut the lighthouse, a house and the bridge at several angles: clean flat cut faces, the top slides off along the cut, no gaps or overlaps at the cut, no frame hitch. Dynamite: drop the lighthouse into its own footprint. Freeze then shatter a house. Steer the tornado through the village. Open a black hole over the debris and release it.
- Flatten the whole island: the frame rate holds, the awake-body cap works, debris in the sea floats or sinks and disappears; Replay plays the last 5 s exactly; Rebuild restores everything.
- Islanders run from danger, tumble, get up, swim to shore, never get stuck inside geometry and never vanish.
- Every slider and switch at both extremes, plus pause and resume, Slow-mo boom, Cinema, keys `1` to `8`, `Enter`, `Backspace`, `Q`, `P`, `R`, `C`, `M`, Space, `0`, and resizing to phone width.
- Sink the ship, flatten the island three times and find the duck.
- Sound: every tool has its own sound, nothing plays before the first gesture, mute, ambience and master volume work, a big collapse 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 lean before the fall, the clean laser cut and the satisfying demolition first. It should make people hit Rebuild just to try the next tool.