Theoryfall.com

A cinematic game where players learn spatial reasoning by reconstructing 3D structures from three projections, built with Codex and GPT-5.6-Sol.

Comment

Inspiration

Mathematics was my favorite subject growing up, especially geometry (and algebra). Yet the three-dimensional problems in our school textbooks still lived on flat pages. We had to rotate solids mentally, infer hidden surfaces, and imagine connections from one or two drawings.

I wanted to inspect those shapes directly. I wanted to turn them, build my own answer, and see exactly where my reasoning went wrong.

Creating that experience would have been too difficult for a solo builder, but Codex and GPT-5.6 changed that. They helped me investigate the learning problem, reason about puzzle geometry, work with 3D assets, test design decisions, and coordinate an ambitious browser game.

Theoryfall is the learning experience I wish I’d had as a child: a place to reason about three-dimensional structures inside a three-dimensional world.

What it does

Theoryfall is a cinematic spatial-reasoning game built around one principle:

Three views. One truth.

Players enter a mechanical Foundry and reconstruct 3D structures from front, top, and side projections. They place and rotate pieces made from connected cubes, compare their construction with the evidence, and validate their proposed solution.

An incorrect proof produces useful feedback instead of a red X. Theoryfall shows which projection conflicts, where geometry is missing or excessive, or why the structure cannot function as one connected mechanism. The player must interpret that contradiction and revise the construction.

The prologue develops this idea across three levels:

  • Mirror Gate: coordinate all three projections
  • Blind Side: form a hypothesis while one projection is missing
  • Turning Crown: build inside a coordinate frame that physically rotates

Each successful proof activates part of the Foundry and advances the story of Rin and Elias, a mentor fragmented across seven projections. The puzzles and story share the same world, so learning never becomes a separate quiz layer.

Theoryfall does not claim a measured learning outcome yet. It demonstrates a concrete learning mechanic and creates a foundation for future playtesting and research.

How I built it

I built Theoryfall as a browser-native 3D game in TypeScript. Three.js and React Three Fiber render the Foundry, characters, puzzle pieces, projections, and activation sequences.

I separated the puzzle mathematics from the renderer. A pure geometry domain calculates rotations, occupied cells, projections, connectivity, and validation results. This separation lets the browser, automated tests, and server verification evaluate the same construction consistently.

XState manages the campaign and cinematic states. Cloudflare Workers and D1 support anonymous verified runs, the leaderboard, and the optional waitlist. Practice mode keeps the full campaign playable when those services are unavailable.

I developed the visual direction in Paper Design, promoted approved designs into interactive Storybook states, and then integrated them into the game. KayKit’s Creative Commons Zero assets supplied the base characters and environments. I created the puzzle geometry, staging, materials, effects, and interface around them.

Theoryfall makes no runtime GPT requests. The puzzles, hints, scoring, and story remain deterministic. AI supported the development process, while the player provides the reasoning.

How I used Codex and GPT-5.6

  • Product design: compared ideas, challenged excessive scope, and shaped the three-level learning progression
  • Puzzle engineering: derived coordinates, rotations, projection masks, alternate solutions, and solver fixtures
  • Production: inspected 3D assets, mapped responsive designs, structured implementation work, and supported integration
  • Quality control: generated tests, reviewed contradictions, investigated failures, and connected public claims to evidence

AI accelerated the work, but it did not determine the product. I made the decisions about the audience, educational boundaries, game structure, emotional direction, privacy model, and final experience.

Challenges I faced

The first challenge was preventing blind trial and error. Theoryfall limits the player to a small inventory of fused pieces, making mental rotation and planning more useful than filling the board with individual cubes.

The second challenge was explaining failure without revealing the answer. The feedback had to identify a contradiction while leaving the next hypothesis to the player.

The third challenge was connecting the learning mechanic to a human story. Rin, Elias, and the Foundry make each proof consequential without turning the game into a quiz or chatbot.

The final challenge was maintaining a readable 3D experience across screen sizes, input methods, browsers, performance tiers, interrupted sessions, and reduced-motion settings. Those constraints shaped the design from the beginning.

What I learned

Working with Codex at this scale taught me that speed depends on clear authority. Specifications, design references, fixtures, tests, and acceptance evidence helped Codex move quickly without silently changing the product.

Another thing that I was forced to learn was the time it requires to properly polish a product. Codex was able to create the initial product, but a lot of it was very unpolished. I decided to focus on the first level and hide the last two levels rather than ship unpolished levels in the end.

Built With

Share this project:

Updates