# Architecture: Bounce Road > Part of [AGENTS.md](../AGENTS.md) and the [Architecture index](./AGENTS-architecture.md): project guidance for AI coding agents. Bounce Road's files under `src/web-console/public/activities/`. The other games and the rules every game follows are in [Activities](./AGENTS-architecture-activities.md). How it fits together: a **stage** is a theme (its look and what it lays on the road) in a slot (how hard: length, holes, rivals), so a run can deal the themes in a new order and stay fair. Every third stage is a boss stage in that boss's arena; fifteen stages make a lap. Rules never draw and drawing never decides: `bounce.js` refills one view object a frame and `bounce-draw.js` draws from it. | File | Role | |---|---| | `public/activities/bounce.js` | the cars, the hazards against them, the gadgets, the scoring and the round, as plain exported functions over a round on a road scrolling up a 72 unit wide field, 90 units of it on the board (it re-exports every rule of `bounce-road.js` and `bounce-rivals.js`, so a suite imports one module). `newRound(seed, random, shuffle)` (the game passes `shuffle` true; the suites leave it off for the classic stage order), `advance` in 4 ms slices over `round.input` (a jump press first, then a `fire`, your `move`, the rivals' `think` and `move`, the pads, the bumps, the barriers, the hazards, `threats`, the ground, progress and traffic). **Driving:** `move`, `jump`, `land` (a landing on a rival flattens it for its points times the chain up to `MAX_CHAIN`; a truck's or the Supply truck's roof is `HAUL_POINTS` and a trampoline; a Spike's roof is a life; a boss takes a hit, `hurtBoss`), `collide` (side knocks split by mass, end on speed passed forward, a heavy back at `CRASH_CLOSE` a crash, a Slasher's blades out a crash, Mega wheels or a Fever flatten on touch), `stunt` (points times `comboOf(streak)`, doubled in a Fever, and it fills the Fever), `lose` (a Bubble saves instead), `underBanner`. **Power-ups** (`POWERS`): Spring, Bubble, Star magnet and a heart work as taken (`applyPower`); the ones with `uses` are gadgets (`GADGETS`: Nitro, Mega wheels, Rockets, Oil slick, Ground pound, Zapper), held one at a time in `you.held` until `usePower`. **The double tap:** `key("action")` jumps at once on the first press and sets `input.fire` on a second within `DOUBLE_TAP_MS` while a gadget is held (never on a repeat, never across a pause), so a jump never waits. **Weapons and the rivals' fire** (`threats`): `round.shots` (rockets: the first rival, boss or barrier in the way), `round.bolts` (a Blaster's: a knock and a slide, never a life), `round.bombs` (a Bomber's, blowing `BOMB_FUSE_MS` on), `round.lobs` (what a boss threw, landing `LOB_MS` on: a barrel lies there as a block, a bomb blows), `round.spills` (oil: yours spins a rival, a boss's takes your grip), the pull of a Magnet rival and the Robo-Vac. **Fever:** `round.fever` fills by `FEVER_GAIN` a stunt; full, `startFever` burns `FEVER_MS` of double points; a life lost halves the meter. **Lives and ranks:** a life every `LIFE_SCORE` points, for a flawless stage and for a boss; a stage line scores `STAGE_POINTS` times the stage, `TIME_POINTS` a second under par and `FLAWLESS_POINTS`, and ranks the stage S to C into `round.ranks`. **The boss hold:** while a boss is alive and the next stage is not yet built, `progress` calls `extendStage` instead of `ensureRoad`, so a boss stage lasts until its boss is beaten (on a road built far ahead, as the suites do, the boss gets away at the line instead). **Road things it settles:** boost strips, ramps, slicks, conveyors (`BELT_PUSH`), spring pads, cones and blocks, bumpers (`BUMPER_POINTS`, a kick, never a life), trains, balls, rollers, sprinklers, drops, gusts, lasers and stompers; an icy or wet stage (`spec.ice`) has less grip everywhere. **The game contract** with `release()`, `cheat(on)`, the events each frame turns into sounds, sparks, floats and banners (`handle`), a power-up's name flashed near the top of the field for `TOAST_MS` (`fx.toast`), the pills (`hudOf`: stage, lives, effects with their timers, the gadget held as `TAP x2: NAME`, the Fever meter, a boss's hp), and the music: `MUSIC_TRACKS` (the twenty chip tracks, a radio in random order), `dealMusic(random, last)` and `MUSIC_HEAT` (the intensity the game asks for: 0.5 on the road, 0.8 while a boss lives, 1 in a Fever), each track played through (`music()` says `"ended"`), a new deal after the last. Memo is the furthest stage reached. A read-only `round` getter is for the tests only. Tuned by scratch bots: a careful bot clears all fifteen classic stages with no rivals on every seed tried, 17 to 35 s a stage | | `public/activities/bounce-roads.js` | the stages as data and plain arithmetic (no imports): `FIELD_W`, `FIELD_H`, `ROW`, `MAX_HOLE`, `WORLD` (every third stage a boss), `CYCLE` (fifteen stages a lap), `MAX_RIVALS`; `THEMES` (fourteen plain themes and five boss arenas: each one's road widths, piece weights, bridges, flowerbeds, barrier and drop kinds, what its ball, roller and stomper are drawn as, `ice`, `dark`, `boss`, and a `tier` for where in a run it belongs), `REGULAR`, `BOSS_ORDER`, `ARENAS`, `TWISTS` (Rush hour, Gold rush, Lights out, Downpour, Supply drop, Turbo lane) with `TWIST_SHARE`, `KIND_FROM` (the slot each rival kind first comes in), `slotFor(n)` (a stage's difficulty from its place: length, par, pace, sharpness, rivals, kinds, crack and gap lengths), `stageSpec(n, id, twist)` (slot, then theme, then what the twist changes), `classicTheme(n)` and `STAGES` (the first lap of an unshuffled run). The place to tune the difficulty | | `public/activities/bounce-road.js` | the road, rules only: the jump math every hole is sized by (`airMs(v)`, `reach(v)`, `LONGEST_JUMP`, `JUMP_FAIR`, `TOP_SPEED`, `MAX_SPEED`); the run's plan, `planAt(road, n)` and `stageFor(n, road)` (with no road, or one made with no shuffle, the classic order; a shuffled road deals each lap from its seed: Chalk Lane first, ten of the plain themes roughly gentle to hard, the bosses in a new order with the Cat last on the first lap, a twist on some plain stages; built once a road) and `stageName`; `newRoad(seed, shuffle)` and `buildStage(road, n, random)` (a stage's rows from its own seed by its piece weights: straights, cracks, rivers on bridges, splits, ramps, chicanes, crumbling road, trains, swaying bridges, boost strips, slicks, balls, sprinklers, drops, gusts, conveyors, spring pads, bumpers, lasers, stompers and rollers; every hole after a `RUNUP` with a sign and no longer than `MAX_HOLE`; a boss stage opens with rockets on the road); `POWER_ROLL` and `rollPower(n, roll)` (which power-up, by stage); `extendStage(road, n, to)` (more of the last stage built, its line moving to the new end: the boss hold); the stunt pieces every theme lays (`WILD` in `bounce-roads.js`): `kicker` (a big ramp, `KICKER_AIR` the usual jump, over a chicane), `wall` (blocks right across the road), `trampoline` (three rows of spring pads) and `turbo` (a `TURBO_W` wide lane of boost strips); `ensureRoad`, `groundAt(road, x, d, t)`, `rowGone`, `spanAt`, `holesIn`, `firstAt`, `plainRow`, `safeSpot`; and where each timed thing is at a moment: `swayOff`, `drawLift`, `crumbleAt`, `trainAt`, `ballX` (a ball's and a roller's middle), `sprayAt`, `gustAt`, `laserAt` (on, and blinking `LASER_WARN_MS` before), `stomperAt` (down, the slice it lands in, and its shadow growing `STOMP_WARN_MS` before); plus `seeded`, `GROUND`, `MARK`, `SPAN` | | `public/activities/bounce-rivals.js` | the rivals, rules only: `RIVALS` (box, mass, speed, points, dodge, weight, car style, and the flags `behind`, `spiky`, `friend`, `boss` with `hp` and a `hint`), `BOSS_KINDS`, `isBoss`, `makeCar`, `think(round, car, ms, random)`, `spawnRival`, `pickKind` (weighted among the stage's kinds, a kind new to the stage more often, one of each special kind at a time), `lob` (a thing thrown at where you are heading). The plain kinds: the Zigzag weaves, the Brick holds your lane and brake-checks, the Frog hops at you, the Sneak drops cones, the Nudge and the Cop chase and shove (never by the water), the Hauler blocks, the Bruiser slams, the Racer passes and flees. The ones with a trick: the Blaster lines up ahead, glows for `AIM_MS` and fires a bolt back down the road; the Slasher pulls alongside, glints for `BLADE_WARN_MS`, then its blades are out for `BLADE_MS`; the Spike sits in your lane, a crash to land on; the Bomber drops bombs while you follow; the Phantom is out of reach for `PHASE_OFF_MS` of every cycle; the Splitter bursts into two Minis; the Magnet hugs an edge and holds your speed; the Supply truck (a friend) keeps ahead for a while, then drives off. The bosses: the Big Rig (`tanker`: lobs barrels, leaks oil), the Robo-Vac (`vac`: sweeps, warns `VAC_WARN_MS`, charges back at you, then drives back up the road through anything), the Whirlybird (`chopper`: `lift` 1 and `high` while it bombs out of reach, then down on the road for `CHOPPER_LOW_MS`), the Monster (hops to come down where you will be, drops tires) and the Cat (`cat`: slams like the Monster, then sweeps across the road for `CAT_SWIPE_MS`). A zapped or oil-spun rival coasts blind (no steering, tricks or hops). Every other rival is rubber-banded to stay near you, swerves from under your landing as sharply as its stage allows, keeps to the narrowest road just ahead, and hops any hole, barrier, coming train, laser or roller | | `public/activities/bounce-draw.js` | Bounce Road's drawing: `drawScene(ctx, view)` from one view object `bounce.js` refills each frame, in field units: the strip above the field in the page's colors with the pills (laid out by `hudLayout`: stage, lives, Spring, Bubble, Nitro and Mega with their timers, the chain and the combo with its timer; a pill that would run off the board starts a second row), the road a chunk of `CHUNK_ROWS` rows at a time, drawn off screen once per road and scale, a few kept and copied each frame (rows from `bounce-scenery.js`), the layers over it (`bounce-scenery.js`), the landing rings (yours in your highlight, a rival's in red, the Monster's its own size), the cars through `bounce-cars.js` (every shadow first, upright, then every body with its tumble: Planny in your highlight with his box in the page's panel color and his star eye, arms to the wheel, up in the air or cheering, down at the end; each rival kind in its own style and color, the Cop's siren while it chases, the Monster's dents and a star per life left above it, headlights at Night Lights), sparks, rings, the dark of Night Lights, the chain's big number, the stage bar beside the field, banners, and the start and end strip with the big final score and a dot per stage reached; every word kept on the field by `labelSpot`, and `readColors(canvas)`, `limbInk`, `inkOn`; decides nothing; since the arcade layer: a boss routed to its own drawer, the Whirlybird lifted over its shadow, a Phantom faded, your landing ring red and crossed over a Spike, the Fever meter along the strip, a boss's health bar across the top of the field, the title and over screens, a CRT scanline pass, and the dark whenever a stage's `dark` is set (Night Lights or a Lights out twist), with lasers, rockets, bolts and blasts drawn over it; it re-exports `CUSTOM_STYLES` | | `public/activities/bounce-extras.js` | the arcade layer's drawing, no rules: `CUSTOM_STYLES` (`vac`, `chopper`, `paw`: the three bosses that are not car styles) with `drawBossBody` and `drawBossShadow`; `drawCarExtras` (a Blaster's turret, a Slasher's blades, a Spike's spikes, a Bomber's rack, a Phantom's shimmer, a Magnet's horseshoe, the Supply truck's crate, zap sparks, an oil spin, a boss dazed); `drawPulls` (a Magnet's and the Robo-Vac's pull), `drawYouUnder` and `drawYouOver` (the Fever's rings, the Star magnet's ring, the gadget held); `drawSpills`, `drawThreatsLow` (bombs, a lob's shadow) and `drawThreatsHigh` (rockets, bolts, lobs in flight, pixel fireballs from `fx.booms`); `drawFever`, `drawBossBar`, `drawTitle` (the logo, PRESS SPACE, GAME OVER, the last fifteen rank badges) and `drawScanlines`. Words are drawn through a `label` handed in by `bounce-draw.js`, which it may not import | | `public/activities/bounce-cars.js` | Bounce Road's cars, drawing only and no imports: `drawCarBody(ctx, style, opts)` draws one top-down toy car about the origin, nose up, filling `w` by `h` field units exactly (tires on the box's corners), in one of `CAR_STYLES` (`STYLE_NAMES`: Planny's convertible with his star eye and arms to the wheel, hatch, sedan, coupe, muscle, pickup, van, box truck, police, racer, taxi, jeep, monster) with flat-fill shading worked out from `color` and `accent` (`shade`, `rgbOf`), and options for roll (`tilt`), a jump (`air`: it draws the shadow and the lift itself), a pancake (`squash`), night beams, a siren bar, damage, a boost flame and brake lights, all moving parts on `opts.clock`; `drawCarShadow` and `shadow: false` for a shadows-first pass in screen space; `carLength(style, w)` for a style's natural length and `carReach(style, opts)` (with `MARGINS`) for what reaches outside the box; plus the newer styles as data rows: armor, buggy, bubble, bus, mini, tow, supply and tanker | | `public/activities/bounce-scenery.js` | Bounce Road's scenery, drawing only: each stage's look in fixed colors (`LOOKS`: patio slabs, lawn stripes, kitchen tiles, garden, sand, a toy room's rug, a pond with lily pads, roof shingles, the night lawn with lamps and the Monster's dirt; `lookOf`, `stageColor`, `contrast`, `better`), `drawRow` (one row of the road in three passes over a chunk: the yard, the road's surface, the details: edges slanting from row to row, rivers, plank bridges with jagged broken ends, cracks, flowerbeds, rails across a crossing, cracked road over a pit, checkered stage lines, verge decor), and the layers drawn fresh each frame from the round's clock: `drawTimed` (a drawbridge lifting with its red lights, a swaying bridge where it is now, crumbled road gone to the pit), `drawPads` (running boost chevrons, ramps, slicks), `drawBlocks` (cones, toy blocks, pots, buckets, acorns and tires, knocked ones tumbling off), `drawStars`, `drawSigns` (a mark per hazard), `drawItems`, `drawHazardsLow` (crossing lights, the train, a rolling ball, a falling thing's growing shadow, a sprinkler's head), `drawHazardsHigh` (the jet, gust streaks, the thing still falling), `drawNight` and `drawFireflies`; decides nothing; plus the nine newer looks (bath, pinball, desk, ice, lava, garage, hall, attic, couch) with their patterns, lava drawn fresh each frame (`drawLava`), an icy sheen and rain (`drawSheen`, `drawRain`), conveyors, spring pads, bumpers, barrels, the balls by kind, rollers, lasers (`drawBeams`), stompers, the newer signs, and every power-up's mark (`itemMark`, `drawPickup`: a gadget is a square crate, the rest round) | | `public/activities/bounce-sfx.js` | its own sounds, merged into `tones.js`: `music` (the twenty tracks of `bounce-music.js`, its only import), `tones` (landings, the Monster, the siren, the crossing, a bumper, a rocket, oil, the ground pound, the Fever, a Slasher's blades, the Cat, the Robo-Vac's charge, a gadget loaded) and `hums` (your motor, the Monster, the Whirlybird's rotor, the Robo-Vac, crumbling road, a sprinkler); definitions only | | `public/activities/bounce-music.js` | its music, all synthesized (no mp3): `SCORES`, twenty short scores (`{ title, key, scale, bpm, kit, bass, arp, drums, A: { chords, lead }, B: { chords, lead } }`: `key` the tonic as a MIDI note for the bass, `chords` a scale degree a bar, `lead` eight bars of sixteen characters, `1` to `7` the scale's degrees, `a` to `g` an octave up, `A` to `G` an octave down, `-` a hold, `.` a rest), and `BOUNCE_MUSIC`, `bounceSong1` to `bounceSong20`, each score turned by `build()` into a `music.js` track when the file loads: a bass, a lead and an arpeggio on one of five chip kits (`KITS`), drums, an echo of the lead (`from` 0.7, a boss) and a harmony under it (`from` 0.9, a Fever), in the order intro, tune, tune with its arpeggio, second tune twice, break, both tunes again (56 bars, 73 to 88 seconds at 146 to 178 bpm, `rush` 14). The bar patterns are `BASS`, `ARP` and `DRUMS`. No imports | **Tests.** `scripts/test-web-console-activities-bounce.mjs` (driving, the road and its fairness, the stage plan, the older rivals, the bots), `scripts/test-web-console-activities-bounce-arcade.mjs` (gadgets, the Fever, ranks, the newer hazards and rivals, the bosses, the double tap, the music), `scripts/test-web-console-activities-bounce-game.mjs` (the game contract, pills, tones, drawing) and `scripts/test-web-console-activities-bounce-cars.mjs` (the car art). Changing only Bounce Road: run those four.