Yodoku

A tranquil puzzle game.

Comment

Yodoku Project Story

Inspiration

I've made games before, but I've always been slow to finish them. I had one game that was 90% done and still took me several years to release.

The problem wasn't the core game. That part was fun. It was the last 10%: tutorials, transitions, saving, settings, platform bugs, accessibility, and all the other things that turn a working game into something I actually feel good about shipping. That work matters, but it can be hard to stay excited about it.

With Codex, I can get through that part now. I can focus on how I want the game to feel, then use Codex to build and refine things like the tutorial and scene transitions instead of letting them sit on a list for years.

For Build Week, I wanted to finish a puzzle game quickly without dreading that last 10%. The result is Yodoku, a tranquil logic game with 9,999 puzzles. Every board has one clear solution and can be solved without guessing. I wanted it to feel calm from the first move to the last, without frustration.

What it does

The rules are simple:

  1. Place one lantern in each colored region.
  2. No two lanterns can share a row or column.
  3. Lanterns can't touch, even diagonally.

The campaign ranges from 4x4 to 10x10. It starts small, introduces larger boards and unusual garden shapes over time, and mixes difficult puzzles with easier recovery levels. Every puzzle has one solution and is verified to be solvable logically without guessing.

Yodoku also has a hands-on tutorial, hints that explain the next deduction, swipe marking, hold and double-tap controls, haptics, original synthesized sounds, light and dark themes, and reduced-motion support. Progress is saved on the device, so the game doesn't require an account or an internet connection.

How I built it

Yodoku is built with Flutter, Flame, and Dart, plus some Kotlin and Swift for platform-specific behavior. The rules, solver, hints, and puzzle generator are deterministic. The expensive generation work happens offline; the app reconstructs the puzzle being played from a small committed recipe.

I didn't just build Yodoku. I started by using Codex to plan Game Factory, a monorepo for making more games after this one. It keeps reusable pieces for audio, haptics, saving, cloud sync, UI, testing, and level generation in one place, alongside repository-owned tooling. Yodoku is the first game built on it.

I used Codex with GPT-5.6 Sol Ultra throughout the project. It helped with research, architecture, implementation, tests, debugging, and platform details in languages I don't use every day. I still made the game and product calls. I decided how calm it should feel, how the gestures should work, what was too busy, which sounds were annoying, and when something simply didn't feel right. Then I gave Codex that feedback and kept iterating.

GPT-5.6 Sol Ultra has honestly been kind of amazing. I used to spend a lot of time writing long PRDs and trying to predict every step an agent would need. Now a small prompt can get surprisingly far. It inspects the code, tries something, runs the tests, catches mistakes, and keeps going until the task is actually done.

I've also used Codex Remote constantly. I'm traveling right now. A lot of Yodoku was built with my laptop sitting in a hotel room while I sent Codex work from my phone. I could check a result, give feedback, or start the next task without being at my desk. It's wonderful.

The puzzle generator became its own project

Building a generator that can make a puzzle is one thing. Building 9,999 puzzles that are unique, varied, fair, and ordered into a campaign is much harder.

At one point the full generator took almost 15 minutes to run. I asked Codex to create a separate worktree and figure out why. The first useful thing it did was measure the problem instead of guessing. A 250-level run took about 12 seconds and performed 20,905 full logical analyses. More than 16,000 of those puzzles stalled, needed guessing, and were thrown away. Most of the expensive work was being spent on puzzles we would never use.

Codex added a cheaper no-guess check before the full solver analysis. It also found places where the generator repeatedly scanned the whole board and changed them to update only the cells that were affected.

The first version wasn't correct. It used integer bit masks, which worked on small boards but couldn't safely represent every cell on 9x9 and 10x10 boards. New comparison tests caught that before the generator wrote any content. Codex replaced the bit masks with size-independent arrays and reran the parity tests.

After that, the 1,000-level benchmark went from 94 seconds to 20 seconds, and it reproduced the existing 1,000-puzzle prefix exactly. That last part mattered as much as the speedup. A faster deterministic generator isn't useful if it quietly gives you a different campaign.

Then I looked at the early levels and had a much less technical complaint: several of them looked like basically the same puzzle. They had one huge color region surrounded by tiny one-cell gardens. Codex traced that back to the campaign rules and turned my visual complaint into something the generator could enforce. Dominant garden shapes now have to be spaced out, and a challenge puzzle must be followed soon by an easier recovery puzzle.

The first full regeneration ran for 3 minutes 24 seconds and then failed the final pacing check because one challenge didn't have a proper recovery level. That was annoying, but it was also exactly what the safety check was supposed to do. It stopped before writing any files. Codex moved the recovery rule into the selection process, tested smaller batches again, and reran the campaign. The next run generated and verified all 9,999 levels in 3 minutes 21 seconds.

This work became pull request #14.

Other challenges

The hardest part was still finishing. The puzzle mechanic came first, but the game needed a tutorial that didn't feel like a wall of text, useful hints, scene transitions, reliable saves, settings, animation, sound, and native behavior that felt right on both Android and iOS. Codex made it realistic to keep working through that list.

Making the game feel calm was also more technical than I expected. It came down to lots of small choices: gesture thresholds, animation timing, sound volume, copy length, navigation speed, visual density, and reduced motion. Any one of those could make the game feel busier or more frustrating.

For example, the toolbar Back button worked correctly on Android, but the system's predictive Back gesture skipped part of the title transition. I found it while testing on a real device. Codex followed the two different navigation paths, fixed the native behavior, and added a regression test so it wouldn't come back.

I also wanted to be honest about what existed before Build Week. Game Factory and an early Yodoku prototype were already in the repository. I preserved commit 687e3aa as the exact baseline. It had the core rules, a small 4x4-to-7x7 campaign, an early tutorial, the original sounds, and memory-only progress.

During Build Week, I expanded that into the full campaign, guided hints, persistent saves, animated title and completion scenes, accessibility work, native polish, generator optimization, and a much larger test suite. By the deadline, I had published Yodoku on Google Play.

What I'm proud of

  • 9,999 deterministic puzzles, all uniquely solvable without guessing
  • A hint system that explains the reasoning instead of giving away an answer
  • Original sounds and artwork that can be reproduced from checked-in tools
  • A game that works offline and doesn't ask the player to create an account
  • 414 Yodoku tests and 675 tests across the repository on the verified product snapshot
  • Actually finishing the tutorial, transitions, persistence, platform polish, accessibility work, and all the other things I used to leave until later

What I learned

The puzzle itself was the fun part. Codex made the biggest difference after it worked, when I still had to build the tutorial, transitions, saves, platform fixes, and tests.

In practice, the work went in loops. I told Codex what I wanted, it investigated and built a version, tests caught technical mistakes, and playing it on my phone caught the things that simply felt wrong. Then I sent that feedback back and we did another pass.

The generator work was a good example. Codex didn't magically produce the perfect solution. It measured the slow version, tried something, caught a bug in that attempt, replaced it, proved the output still matched, and later translated my complaint that several puzzles looked the same into a rule it could test. That feels much more useful to me than a one-shot code generator.

Most importantly, the final 10% doesn't feel like a graveyard anymore. I can keep pushing until the game is something I want other people to play.

Relevant Codex sessions

  • Primary /feedback thread: 019f5507-f077-7e50-9277-4df4ea17f4f6 — Game Factory and the first version of Yodoku were built here. It began before Build Week, so I documented the pre-event baseline separately.
  • Campaign and generator: 019f6c11-331b-7d12-baf3-1ddc58b3d423 — The 9,999-puzzle campaign, generator optimization, and visual-variety changes described above.

The complete dated session inventory is in the Build Week log.

What's next

Now that Yodoku is on Google Play, I want to learn from players, finish the iOS release, and complete the remaining cloud-save qualification. I want to keep the same promise: a calm puzzle with one clear solution, no guessing, and no frustration.

Built With

Share this project:

Updates