Clockwork Picnic
Premise and audience
Build miniature clockwork kitchens for a traveling picnic. Route ingredients through brass conveyors and tiny preparation stations, then watch a complete recipe arrive on patterned plates.
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 claude.
The first satisfying move
The player spots that a toast slice reaches the jam station one tick before the berries. They move one elbow belt, step the machine once, and see both ingredients arrive together. The kitchen runs without a jam, plates glide onto a gingham cloth, and the completion screen offers a smaller footprint to try next.
Core loop
Read the recipe and tool budget, place and rotate machinery, run or step the kitchen, inspect a jam, revise with undo, then deliver the required plates and move to the next commission.
Playtime and progression
Target: about one hour for a first clear. This is a design target until playtesting supplies evidence.
| Chapter |
Commissions |
Main tools |
First-play estimate |
| First Basket |
6 |
Straight belts, elbows, and simple fruit plates |
6 minutes |
| Toast Service |
6 |
Slicer, toaster, and ordered recipes |
12 minutes |
| Tea for Twelve |
6 |
Combiners and clocked gates |
18 minutes |
| The Grand Picnic |
6 |
Bridges, mixed recipe flow, and constrained layouts |
24 minutes |
Twenty-four authored boards aim for an hour of first-time planning, with roughly 50 to 75 minutes across players. Do not force that duration with slow simulation. Provide step, normal, and fast speeds. Optional footprint and tick medals add mastery after a first solution. Add two escalating hints per board and save the player’s current machine.
References and lessons
- Opus Magnum: the official page describes building machines and seeking simpler, faster, or more compact solutions. Borrow deterministic execution and optional optimization after solving. Use ingredient routing and recipe stations rather than copying its alchemy arms.
- Mini Motorways: borrow clean route readability and the ability to revise a constrained network. Puzzle boards here have fixed recipes and a definite success state.
- Reference scope differs. Opus Magnum supports open-ended optimization and a larger campaign. This game targets about one hour through 24 compact commissions. Simultaneous ticks, board snapshots, and fixture replays are our implementation choices, not claims about either game’s code.
Controls
Pointer and touch: select a tool then select a cell, select again to rotate when appropriate, and use visible rotate, erase, undo, run, pause, and step buttons. Keyboard: arrows move the board cursor, number keys choose tools, Enter places, R rotates, Delete erases, Z undoes, Space runs or pauses, and Escape opens the menu. Do not require hover, right click, or dragging for any action.
Art direction
An oblique-looking flat tabletop built with clear top-down grid logic. Draw brass rollers, enameled preparation machines, patterned dishes, and cloth chapter borders. Keep routes unobscured by shadows. Use Georgia recipe titles and compact sans tool labels. Give each chapter a different table setting.
Palette: Warm parchment #F5E8CD, gingham red #B4544C, brass #B68A42, leaf green #517660, and ink #343B42. Ingredients need distinctive shapes and small labels, not color alone.
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
Use gentle mechanical ticks, small ceramic plate notes, a dry jam indicator, and a short original completion phrase. Faster simulation should not multiply sounds without limit. Provide mute, separate gains, and a reduced-motion option.
Scale effects to the action. Make routine feedback brief. Keep decorative motion from masking threats or interrupting player control.
Experience finish list
- A player can start within two actions. Teach the central mechanic through the first playable challenge and contextual cues. Show the current goal during play.
- Build title, settings, stage selection or campaign continuation, pause, failure, retry, and a specific final victory screen. Menus must retain clear focus and return to the correct prior screen.
- Preserve gameplay geometry when resizing. Verify 1440 by 900, 1920 by 1080, 2560 by 1080, 390 by 844, and 844 by 390 viewports. Adapt layout for portrait without hiding required controls or hazards. Keep pointer and touch targets at least 44 CSS pixels.
- Use readable text, keyboard focus, non-color status cues, a visual alternative to important sounds, reduced motion, and mute. Pause on lost focus where continued play would punish the player.
- Include designed original art and coordinated motion from the first checkpoint. Keep an art manifest with source and license notes for any external assets. Do not leave placeholder geometry or copied reference art in the final build.
- Keep the game usable when browser storage is unavailable. Save failures must not crash or prevent a new game. Never reset stored progress without an explicit reset control.
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 puzzle, level-design, game-ui-ux, input-systems, game-feel, audio-design, 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 general programming language, custom recipe editor, Steam Workshop, online leaderboards, and a factory sandbox with no ending.
Primary risk: A large puzzle count could hide repeated or unsolvable layouts. Prove deterministic transport and three different solved boards, then maintain validated reference solutions while expanding the campaign.
Verification and release
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Read /root/aog/.aog-credentials at publish time without echoing secrets. Use the existing agent account.
- Upload the final DESIGN.md, then create one new public game with accurate controls, category, and HUMAN target audience. Save the returned game ID immediately in releases/latest.json before continuing.
- Upload the verified dist/game.html, review validation warnings, and create version 1.0.0 with a factual changelog. Persist release ID, listing URL, playable HTML URL, plan URL, and artifact hash. Reuse saved IDs during retries.
- Implement python3 tests/hosted_smoke.py –release releases/latest.json. Open the hosted build, start it, exercise its core input, check errors, capture screenshots/hosted.png, and inspect the image.
- Update README.md and the build summary with working links. If a platform failure blocks release, preserve the tested build and exact failure, retain any IDs already returned, and report publication as incomplete.
- Leave the factory spec in active for independent review. A published listing alone does not make the spec accepted.
Implementation facts
Recorded by the builder from the shipped code and tests. The genre, the 24 board campaign, and the one hour target above are unchanged.
- Engine: src/engine.js runs in the browser and in Node. Each tick resolves in fixed phases: spawn, intent, wait resolution, collision check, move, machine work, win check, stall check. Every piece holds one ingredient. Bridges hold one per axis. Combiners hold one of each half until the partner arrives. A blocked ingredient waits in place. A jam is declared only when nothing can ever move again or when an ingredient has nowhere legal to go (wrong side, off the board, into a wall, spill off a belt end, or the wrong ingredient for the next plate slot). The kitchen then freezes with the cell marked and a sentence explaining the cause. Ingredients are never deleted or reordered.
- Clock gates open on ticks that are multiples of the board period. Crates release their first ingredient at tick 1 and then every N ticks as printed on the crate.
- Tools by chapter: belts and elbows (chapter 1), slicer then toaster (chapter 2), combiner then clock gate (chapter 3), bridge (chapter 4). Each new tool appears alone on its introduction board. No board offers more than seven tool kinds.
- Content: 24 boards, 35 reference constructions, 11 boards with two constructions. Each board has two hints and a part and tick medal goal met by at least one reference. Planning estimates per chapter are 6, 12, 18, and 24 minutes as planned. They remain design estimates. The automated full playthrough takes about ten minutes because it replays known answers, so it says nothing about human planning time.
- Saves: localStorage key clockwork-picnic-save stores completed boards, best parts and ticks, the unfinished layout of every board, hint progress, settings, and whether the ending was seen. A failed or blocked storage call falls back to memory with a visible note.
- Layout: the board scales to fit the stage at every size. In portrait the tray and actions move below the board, the recipe queue wraps, and crate counts move to the crate’s top corner on small cells so they never cover ingredient tags.
- Art and audio are drawn and synthesized in code. No external assets are used. See assets/README.md for the art and audio manifest.