Koi Katana

Context

Koi Katana is my independent fishing and samurai game, built in TypeScript and Three.js for mobile browsers. I design the game and use coding agents to help implement it. The playable version is online and development is ongoing; the repository is private.

The problem

Gameplay changes cross several boundaries: input, rendering, combat rules, saved progress and shared multiplayer state. A change can pass a unit test while still feeling wrong on a phone or breaking an interaction between players.

What needed to change

Code-level checks alone do not establish that a player can complete a gameplay sequence. Browser verification also needs to be traceable: screenshots from an earlier build are weak evidence for a later change.

What I designed

The game combines a deterministic combat simulator, tests around the co-op protocol and saves, and browser scenarios that exercise the real game. The verification harness records the code revision, scenario, viewport and captured artifacts. An evidence check rejects failed runs, missing or altered artifacts, and code changes that invalidate the recorded run. This gives me inspectable evidence alongside implementation review.

Tradeoffs considered

• The initial JavaScript entry chunk has a 200 kB gzipped ceiling. Three.js and lazy-loaded features are separate chunks, so the ceiling is a constraint on startup code rather than the total download.
• Lazy loading helps control the entry chunk, but introduces asynchronous failure paths. Co-op loading tests cover a late module arrival, leaving before it arrives, and a newer request superseding an older one.
• Browser recordings make behaviour easier to inspect, but they only cover the scenario driven. The evidence report can state what was not exercised so that gaps remain visible.

Design budget

Evidence and outcomes

Reproducible combat

Replay checks compare seeded combat runs, including the game rules and simulator.

Traceable verification

Run manifests include the commit and artifact hashes. Evidence checks verify that the recorded run still applies.

Asynchronous regression coverage

Co-op loader tests exercise late arrivals, abandoned requests and replacement requests.

Lessons learned

• Check a feature at the boundary the player uses, as well as the boundary the code exposes.
• Verification evidence has a lifetime. A new implementation change can require a new browser run even if an earlier recording looked correct.
• Name the scope of a performance budget. An entry chunk ceiling does not describe every asset a player will download.