16 KiB
Architecture: Bounce Road
Part of AGENTS.md and the Architecture index: 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.
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.