Marble Works

Executive Summary

Marble Works is a browser recreation of a wooden tilt maze. You guide a steel marble from START to FINISH by moving a mouse or trackpad: the center of the playfield is level, and movement toward an edge tilts the board. Three original mazes—First Steps, Crossgrain, and Switchback—share one game engine while presenting different levels of challenge.

The game was made through a partnership between human direction and Generative AI. The human set the product goal, feel, constraints, and standard for play. Generative AI helped turn those decisions into a design, implementation plan, code, tests, and revision candidates. Human review remained decisive wherever “correct” depended on judgment: whether the board felt physical, the controls felt fair, the scene stayed readable, and the result was worth playing.

Before You Play

Choose a maze from the Collection Cabinet. Move the pointer to the center of the game window to level and arm the board. Move toward an edge to tilt; the timer starts when you leave the center zone. A fall returns the marble and timer to START. Reaching FINISH records a personal best in this browser when storage is available.

All three launch mazes are available from the beginning. There are no lives, checkpoints, accounts, leaderboards, or cloud saves.

Controls and Accessibility

• Use a mouse or trackpad to steer. The game reads pointer position inside the playfield; clicking and dragging are not required.
• Press Space to level the board. Steering remains neutral until the pointer returns to the center zone.
• Press Escape to pause and open controls for Resume, Restart, sound, sensitivity, and Return to Collection Cabinet.
• Menus and buttons support keyboard focus, visible focus treatment, and semantic labels. The primary steering mechanic does not provide keyboard steering.
• The supported play area is at least 960 × 640 CSS pixels. Smaller windows keep the Collection Cabinet available but suspend play and ask you to resize. Mobile and touch play are not supported in this release.
• Reduced-motion preferences shorten decorative transitions without changing the simulation. Sound can be muted and is never required to understand game state.
• Best times and preferences stay in local browser storage. If storage is blocked or unavailable, the game remains playable with in-memory defaults.

How We Made This with Generative AI

We began with the physical experience we wanted: the patience of balancing a steel marble on a cared-for wooden toy. The human described the control idea, original-maze requirement, visual direction, restart rules, and need for interchangeable boards. Generative AI helped organize those choices into explicit system boundaries for levels, input, simulation, physics, rendering, interface, audio, persistence, and diagnostics.

The work proceeded in small test-first slices. For each behavior, we described what a player or another system should observe, watched a test fail, implemented the smallest useful change, and checked the complete game again. The AI accelerated decomposition, code generation, test construction, and comparisons across the codebase. Browser captures and deterministic diagnostics made the discussion concrete: instead of arguing from intent, we could inspect what the marble, board, camera, controls, and overlays did.

Generative AI did not supply taste, approve its own work, or decide when the controls felt right. Human direction chose the experience; automated checks protected agreed behavior; human play and visual review decided whether the implementation delivered it.

The Gory Details

One definition, several consumers. Each maze is a validated MazeDefinition containing board dimensions, START, FINISH, holes, and wall segments. That same record builds the Collection Cabinet miniature, the Three.js board, and the Rapier collision world. This removed a common failure mode in games: a preview that looks plausible but does not match the playable level. It also means a future expert maze can be added as content instead of as a second engine.

Physics and presentation have different jobs. Rapier owns the authoritative marble simulation at a fixed 60 Hz step. The collision board stays stable in its local coordinate system; tilt changes the effective gravity applied to the marble. Three.js rotates the visible board and transforms the rendered marble to match. Keeping rules in simulation and appearance in rendering made movement deterministic enough to test without making the scene feel mechanical.

The pointer needed a contract, not a direct mapping. Raw pointer position would make corners stronger than edges, amplify tiny hand movements near center, and start the game tilted after clicking a menu. The final input path uses a circular dead zone, a response curve, smoothing, diagonal clamping, sensitivity control, and a safety cap. Loading, falling, pausing, focus loss, and pressing Space all return through a center-arming state. Those rules took several revisions because safety and responsiveness pull in opposite directions.

The physical illusion depended on small corrections. Early implementation was not the finish line. We prevented play before a maze finished loading, restored viewport state after WebGL context recovery, hardened failures so they produced a readable surface, stabilized menu interaction and stored preferences, and made fatal errors announce once. Later browser review exposed issues that unit tests could not judge: alignment between physics and rendered space, finish-marker legibility at camera distance, control sensitivity, and wall contacts that felt too sticky. The final rail treatment guides glancing motion with low friction instead of adding a stronger rebound.

Failure paths were designed as gameplay. A hole capture suspends input, presents the fall, levels the board, resets the physics body and timer, and requires center arming again. A finish freezes the completion time before persistence updates. Storage, audio, renderer, and maze-validation failures each have bounded fallbacks so one unavailable browser capability does not create a blank screen or corrupt an active run.

Tests cover rules; people cover feel. Unit and simulation tests cover maze validation, state transitions, timing, storage, input mapping, renderer boundaries, collision behavior, and resource cleanup. Browser tests drive the real Three.js and Rapier game through selection, centering, tilt, wall contact, falling, pause, winning, reload, resize, and corrupted storage. Screenshot checks protect the Collection Cabinet and representative game states at supported viewports. Even that evidence cannot decide whether a maze is satisfying. Human play review remained the final test for pacing, legibility, fairness, and delight.

The reusable lesson is not that Generative AI can produce a game in one pass. It is that a human can make creative intent inspectable—through data contracts, observable states, small tests, and rendered evidence—so AI assistance becomes easier to direct, challenge, and improve.