Bell Current

Premise and audience

Pilot a night courier skiff through a city of tidal bells. Ring on the beat to open locks, choose a channel, and carry a growing melody to the sea.

Build a human-playable browser game. The user delegated the surprise concepts and assigned two builds to Claude Code and two to Codex. This project’s builder is codex.

The first satisfying move

At the first fork, the player sees a buoy pulse twice, chooses the narrow channel, and rings as its gold circle closes. The lock opens, the skiff draws a luminous wake, and a new bell joins the music. The player understands the next fork without opening a help panel.

Core loop

Read the next lock and route cue, choose a channel, ring at its marked beat, recover from an early or late tap, then finish the passage and compare timing and delivery grades.

Playtime and progression

Target: 10 to 15 minutes for a first clear. This is a design target until playtesting supplies evidence.

Passage Active target New demand
First Light 60 seconds Visible straight locks and forgiving recovery
Forked Water 75 seconds Two routes with distinct reward and risk
Brass Steps 75 seconds Alternating strong and weak beats
Undertow 90 seconds Brief rests with explicit visual count-in
Lantern Bend 90 seconds Route choice while a lock sequence continues
Double Tide 90 seconds Paired notes with generous separation
The Quiet Mile 105 seconds Combine known patterns with fewer guide pulses
Sea Bell 105 seconds A composed finale that recalls earlier motifs

Add a playable teaching passage of about 45 seconds. Normal completion of the eight passages plus teaching targets 12 to 14 minutes. Permit stage replay and timing mastery. Avoid perfect-play requirements and repeated restarts of the whole campaign.

References and lessons

Controls

Keyboard: Left and Right or A and D choose a channel, Space rings, Escape pauses. Pointer and touch: separate left, bell, and right buttons support the same actions. Enter and standard focus navigation operate menus.

Art direction

Top-down illustrated canal charts, rounded stone islands, fine contour lines, brass mechanisms, and a skiff with a legible prow. Draw restrained reflections and expanding bell rings. Use Georgia for chapter titles and a system sans face for timing and controls. Keep moving decoration outside the lock timing target.

Palette: Ink water #102637, jade channels #357E83, ivory stone #F4EAD2, brass beat cues #E5B45A, and coral mistakes #DB786A. Use shape and labels alongside cue colors.

Use a responsive Canvas 2D playfield with DOM menus and controls. Define the logical board or world dimensions once, transform pointer coordinates through the view, and preserve geometry on resize. Draw a representative active screen before expanding the asset family. Store the approved capture and provenance in this project.

Sound and motion

Compose an original bell, bass, and soft percussion score with three musical movements and eight passage arrangements. Schedule audio ahead against AudioContext.currentTime. Derive game beat position from that clock. Provide a visual metronome, volume controls, mute, latency calibration, and an assist timing window. Do not add hit-stop to the rhythm clock.

Scale effects to the action. Make routine feedback brief. Keep decorative motion from masking threats or interrupting player control.

Experience finish list

Browser build

Use native JavaScript with Canvas 2D and Web Audio. Keep editable source in src/game.html and produce dist/game.html with python3 tools/build.py. Embed HTML, CSS, JavaScript, and the game’s own visual and sound assets. Do not require local companion files or a running development server to play the release. Avoid runtime dependencies for this project.

The build should be reproducible and remain under 5,000,000 bytes. The exact dist/game.html must pass local browser checks and then the AOG hosted smoke test.

Relevant skills

Read skills from /root/aog/.agents/skills. Begin with router, then use audio-design, input-systems, game-feel, game-ui-ux, save-systems, create-game-assets. Use last-20-percent to inspect the full player experience. Follow stop-slop and deslopify for prose. Load the pinned agents-of-games skill before publication.

Scope boundaries and risk

Out of scope: A song editor, licensed songs, online scores, multiplayer, and a campaign longer than the eight planned passages.

Primary risk: Audio output latency could make visually correct taps feel wrong. Prove scheduler, calibration, and recovery in the opening before authoring the remaining passages.

Verification and release

  1. Build dist/game.html and record its SHA-256. Test that exact file, not an alternate debug build. Keep the final HTML under 5,000,000 bytes as a conservative interpretation of the platform’s 5 MB limit.
  2. Implement the listed build and test commands. Capture actual output and exit codes in verification. A missing script is unfinished work, not a reason to weaken the command.
  3. Run browser tests using the shared Python Playwright installation. Exercise keyboard, pointer, and real touch events. Watch page exceptions, console errors, and failed requests. Verify pause, settings, saved progress, failure, restart, and final success.
  4. Complete the authored campaign using player controls. Read-only state and reproducible action fixtures are acceptable. Direct progress writes, teleports, invulnerability, or hidden solved-state setters cannot stand in for a playable route. Keep action evidence and distinguish complete-run tests from targeted diagnostic tests.
  5. Capture title, opening play, middle play, a difficult late challenge, failure, final success, and narrow and wide layouts. Open and inspect every representative image with an image tool. Record image names and specific findings in verification/REPORT.md. Fix defects and repeat affected checks.
  6. Check the opening, middle, and late game for fair cues and meaningful decisions. Record the intended playtime separately from observed test time. Do not claim a human playtime measurement from a fast automated replay.
  7. Update DESIGN.md with implementation facts. Keep the user’s genre and playtime decisions intact. Explain any meaningful balance or content changes with evidence.

After local verification passes, load /root/aog/.agents/skills/agents-of-games/SKILL.md and follow /root/aog/AGENTS.md for automatic publishing. The user already authorized AOG publishing.

Implementation facts

Codex implemented this plan with native Canvas 2D, DOM controls, and Web Audio. Editable source lives in src/game.html. The build copies those bytes to dist/game.html without runtime assets or network dependencies.

The campaign contains 735 active seconds, plus a three-second count-in and a short settlement after each passage. This supports the 10 to 15 minute target. Automated completion time is control evidence, not a measured first human session.

The authored manifest in verification/content-manifest.json lists 472 primary locks and 137 optional brass echoes across the teaching passage and eight deliveries. Source patterns live in the HTML content block. tools/author_campaign.py preserves the six later passage arrangements as editable data. It changes content only when invoked.

Passage Implemented variation
Harbor School Straight gates, one paired introduction, unlimited practice damage
First Light Three straight gates per phrase with changing safe banks
Forked Water Alternating bank choices, echo notes on the brass channel
Brass Steps Offbeat half-beat positions and staircase aqueducts
Undertow One-note and two-note phrases separated by explicit rests
Lantern Bend Late seventh-beat locks continue while the next fork opens for selection
Double Tide Four-note phrases form pairs with varied internal spacing
The Quiet Mile Earlier motifs return with only a downbeat guide pulse
Sea Bell Straight, offbeat, rest, and paired motifs form a final arrangement

AudioContext.currentTime drives judgment, visuals, and the 25 ms scheduling loop. The loop schedules 140 ms ahead. Original synthesized bell partials, soft sine percussion, and bass patterns form three movements and the passage arrangements. Successful rings add an octave response. Master and score buses have separate controls. The master uses squared gain and a compressor with headroom. A hardware listening session and perceived latency measurement remain outside automated verification.

SAFE accepts ±165 ms. BRASS accepts ±110 ms and scores 65 percent more per successful note. Assist accepts ±250 ms. A new key or pointer edge triggers each ring. A 280 ms guard rejects dense retriggers, while off-target taps damage the hull. Seven hull knocks end a delivery. The teaching passage permits practice after damage. Clear rings within 65 ms earn 100 base points, other accepted rings earn 70. Grades use damage and precise hits. Stored best score and best grade improve independently.

Each fork opens for selection 2.5 seconds before its phrase begins and commits 1.1 seconds before its first note. Both routes reach the next passage. BRASS adds the visible echo notes. Selecting the next fork can overlap the previous phrase’s last note. The current gate remains on its committed bank while the skiff prepares for the next channel. Brass echo misses explain the route demand. The next-fork label names the safer bank.

Timing offset spans minus 250 to plus 250 ms. Positive values accept a physically later tap. The test pulse runs every 750 ms and reports average tap offset. Muted play retains target circles, REST labels, route labels, and the beat indicator. Assist mode locks at count-in and saves to a separate ledger. Changes in Settings apply to the next passage.

Pause suspends the audio context. Calibration can resume that context, so returning from Settings adds the elapsed settings time to the passage origin before suspending again. A fresh retry recreates the timeline and starts another three-second count-in. Blur and document hiding pause active play.

Versioned JSON storage contains unlocks, best score and grade per mode, and settings. Loading validates ranges and record fields. Storage exceptions retain an in-memory playable session and display a save notice. Progress resets only through the explicit confirmation control.

Canvas geometry uses CSS dimensions and one device-pixel transform. DOM controls retain their CSS size on resize. The static chart renders to a cached canvas, while lock cues render at about 30 frames per second. Input judgment continues to use the audio clock. Reduced motion removes wake response rings and skiff sway. The art manifest records original vector and audio provenance.

The read-only bellObserver.snapshot API returns copied state for verification. It has no actions, setters, clock controls, damage bypass, or completion shortcut. Campaign tests send keyboard directions and rings through Playwright. Additional tests use mouse and touchscreen controls. Tests preserve actual action times and judged offsets.

Recorded assumptions

Route choice commits per phrase, rather than on every note. This keeps one direction choice readable while the player performs paired notes. SAFE and BRASS both finish each delivery. BRASS increases timing demand and adds echoes.

The harbor lesson permits continued practice after damage. Deliveries use the seven-knock failure threshold. This teaches recovery before failure can require a restart.

System Georgia and sans fonts supply chapter titles and control text. All illustrated art and audio use original code-native vectors and synthesis, with no external media.