Koi-Koi

Type: Software Status: In Progress Deadline: 2026-03-08 Created: 2026-03-01

What is this?

A browser-based implementation of Koi-Koi, the classic Japanese card game played with a Hanafuda (flower card) deck. Player vs AI, with full yaku scoring, koi-koi push-your-luck mechanic, and multi-round play.

Where is it located?

http://davidtingle.com/koi-koi/

Motivation

Hanafuda is a beautiful card game with simple mechanics but deep strategy. A web version lets me play anytime and serves as a showcase microsite project.

What does success look like?

  • Full Koi-Koi rules: deal, play/match by month, capture, 12 standard yaku
  • Koi-koi decision (push luck) vs stop (bank points)
  • Simple but competent AI opponent
  • Beautiful card art (Louie Mantia SVG deck, CC BY-SA 4.0)
  • Smooth card interactions: hover lift, selected glow, matchable pulse
  • Multi-round scoring
  • Responsive (desktop + mobile)
  • Standalone microsite feel (Microsite.astro layout)

Technical

  • Stack: Astro page, vanilla TypeScript/CSS (no build deps beyond Astro)
  • Repo: ~/projects/davidtingle.com/ (personal site repo)
  • Deploy target: davidtingle.com/koi-koi
  • Card assets: 48 SVGs at /hanafuda/ (Louie Mantia, CC BY-SA 4.0)
  • Layout: Microsite.astro (back link, “djt” brand, theme toggle)
  • Intended users: Personal use; publicly accessible

Design

Data model

  • 48-card deck: Card { id, month, monthIndex, category (bright/animal/ribbon/plain), name, svgFile }
  • 12 yaku with test functions and point values
  • Module-level game state: deck, hands, field, captures, scores, turn phase

UI layout (vertical stack)

  • Score bar (You / AI / Round)
  • AI captures (small cards by category)
  • AI hand (face-down)
  • Field (face-up) + draw pile
  • Player hand (face-up, clickable)
  • Player captures (small cards by category)
  • Status text + modal overlay for yaku/decisions

Turn flow (state machine)

hand-play → hand-match → draw → draw-match → yaku-check → koi-koi-decision → round-end

AI logic

  • Prefer yaku-completing captures > high-value captures > dump lowest card
  • Koi-koi if score ≤ 3, stop if ≥ 7, coin flip 4-6
  • 300-600ms delays for visual pacing