盛永裕介

Posted on May 4

Adding a 17-stage promotion exam system to my hanafuda game in one session

#godot #gamedev #csharp #gamedesign

I shipped Shin KoiKoi v0.1.0 two days ago — a free, polished hanafuda Koi-Koi card game built solo with Godot 4.6 .NET in 2 days. (Earlier post: the v0.1.0 release log)

For v0.1.1 I added a 17-stage promotion exam system that turns the existing rank progression from "MMO experience grind" into something closer to the real Japanese kyū/dan exam tradition. Here's how I designed and shipped it in one Claude pair-programming session.

The problem with auto-promotion

The v0.1.0 rank system was a flat 18-tier ladder (9-Kyū → ... → 1-Kyū → Shodan → ... → 8-Dan → Meijin) with auto-promotion the moment your accumulated Rank Points (RP) crossed the next threshold.

It worked, but it was emotionally flat. Levelling up felt like noise — a number ticked over and you got a new badge. Real Japanese tradition (Go, Shōgi, martial arts) gates the dan ranks behind promotion exams: a defined match format you have to clear to advance. That's where the prestige comes from.

So v0.1.1 reproduces that pattern in code.

The 17-stage design

Each transition has its own rules — difficulty, total rounds, required wins, optional special condition. The hurdle scales with rank: easy at the bottom, brutal at the top.

Promotion	AI Difficulty	Rounds	Wins	Special Condition
9-Kyū → 8-Kyū	Easy	1	1	—
8-Kyū → 7-Kyū	Easy	3	2	—
7-Kyū → 6-Kyū	Normal	3	2	—
6-Kyū → 5-Kyū	Normal	5	3	—
5-Kyū → 4-Kyū	Normal	5	3	Trigger ≥1 yaku
4-Kyū → 3-Kyū	Normal	7	4	—
3-Kyū → 2-Kyū	Normal	7	4	Average score ≥5
2-Kyū → 1-Kyū	Hard	5	3	—
1-Kyū → Shodan	Hard	7	4	Succeed Koi-Koi ≥1
Shodan → 2-Dan	Hard	7	5	—
2-Dan → 3-Dan	Hard	9	5	Trigger ≥5 yaku total
3-Dan → 4-Dan	Hard	9	6	—
4-Dan → 5-Dan	Hard	11	6	Win 1 round with 7+ points
5-Dan → 6-Dan	Hard	11	7	Goko or Ino-Shika-Cho ≥1
6-Dan → 7-Dan	Hard	13	8	Average score ≥7
7-Dan → 8-Dan	Hard	15	9	Koi-Koi success rate ≥50%
8-Dan → Meijin	Hard	15	10	Trigger yaku in 3 consecutive rounds

The bottom of the table is a 30-second exam; the top is a 30-minute marathon with a stat condition that punishes greedy-but-imprecise play. In testing the Meijin condition is the killer — the consecutive-yaku check resets on any round where you don't trigger one.

The data model

The whole catalogue lives as a static immutable list. Each exam is a record of a record's worth of facts:

public sealed record PromotionExam(
    Rank From, Rank To,
    AiDifficulty Difficulty,
    int TotalRounds,
    int RequiredWins,
    SpecialCond? Special);

public enum SpecialCond
{
    None,
    YakuOnce, AvgScore5, KoiKoiOnce, YakuTotal5,
    SevenScoreOnce, GokoOrInoshikacho, AvgScore7,
    KoiKoiSuccess50, YakuTriple,
}

The state object accumulates per-round facts and computes pass/fail when the rounds are exhausted:

public sealed class PromotionExamState
{
    public int RoundsPlayed { get; set; }
    public int RoundsWon { get; set; }
    public int TotalScore { get; set; }
    public int YakuTriggeredTotal { get; set; }
    public int CurrentYakuStreak { get; set; }
    public int MaxYakuStreak { get; set; }
    // ... etc.

    public void RecordRound(bool won, int roundScore, int yakuCount,
                            bool calledKoiKoi, bool koiKoiSucceeded)
    {
        RoundsPlayed++;
        if (won) RoundsWon++;
        TotalScore += Math.Max(0, roundScore);
        YakuTriggeredTotal += yakuCount;
        // ... and a streak tracker that's the actually tricky bit:
        if (yakuCount > 0)
        {
            CurrentYakuStreak++;
            MaxYakuStreak = Math.Max(MaxYakuStreak, CurrentYakuStreak);
        }
        else CurrentYakuStreak = 0;  // ← reset is the whole point
    }

    public bool Passed(PromotionExam exam)
    {
        if (RoundsWon < exam.RequiredWins) return false;
        return exam.Special switch
        {
            SpecialCond.YakuTriple        => MaxYakuStreak >= 3,
            SpecialCond.KoiKoiSuccess50   => KoiKoiCalled >= 2 && (KoiKoiSucceeded * 100 / KoiKoiCalled) >= 50,
            SpecialCond.GokoOrInoshikacho => GokoOrInoshikachoSeen,
            // ... 9 conditions total
            _ => true,
        };
    }
}

Two lessons from doing this:

The streak tracker writes itself wrong if you're not careful. First draft only updated CurrentYakuStreak; I forgot to track MaxYakuStreak, so passing the exam required ending the test on a yaku trigger. Tests caught it immediately.
Edge cases needed dedicated tests. Like: KoiKoiSuccess50 with KoiKoiCalled = 0 would be 0 / 0. So I require ≥2 calls before the 50% condition is even checked.

Game flow integration

The hardest part wasn't the exam logic — it was wiring it into the existing game flow without breaking the v0.1.0 normal-game RP loop.

Normal game win
  → ApplyRankPointsDelta()
  → if next rank's threshold reached → ExamUnlocked = true
  → "Promotion exam unlocked!" toast

Title screen reload
  → RefreshExamButton() shows "★ {NextRank} Exam Start" button

Player taps button
  → ExamStartDialog (badge + requirement + special condition)
  → OnStart → temporarily override Difficulty + TotalRounds → start GameScreen

Inside the exam
  → OnExamRoundFinished() per round (record win/score/yaku/koikoi)
  → Normal RP gain SKIPPED while exam is active

Exam game ends
  → OnExamGameEnded() → state.Passed(exam)
  → If passed: bump CurrentRankIndex, clear ExamUnlocked
  → If failed: lock retry until 1 normal-game win

The "lock retry until 1 normal-game win" rule is design-by-frustration-prevention. Without it, a player who fails the Meijin exam (a 30-minute test) could just immediately try again, then again, then again. Forcing a normal game in between gives both a cooldown and a feeling of "earning back the right to try."

Testing strategy

Wrote 15 test methods covering 30 assertions before any UI work:

private static void Test_SpecialYakuTriple_NotConsecutive()
{
    var exam = new PromotionExam(Rank.Dan8, Rank.Meijin, AiDifficulty.Hard, 15, 10, SpecialCond.YakuTriple);
    var st = new PromotionExamState();
    // 10 wins but yaku triggers spread out (never 3 consecutive)
    for (int i = 0; i < 15; i++)
    {
        int yaku = (i % 2 == 0) ? 1 : 0;
        st.RecordRound(i < 10, 7, yaku, false, false);
    }
    Assert(!st.Passed(exam), "Spread-out yaku should fail YakuTriple");
}

This caught my streak-tracker bug instantly. Tests that exercise both the success and failure path of every special condition turned out to be the difference between "I think it works" and "I know it works."

Localization in 6 languages

The game ships in 6 languages (Japanese, English, German, French, Spanish, Hindi). I needed to add 17 new locale keys covering exam UI, the 9 special conditions, success/failure messages.

["exam.cond.yaku_triple"] = new(
    "3 戦連続で役発動",
    "Trigger yaku in 3 consecutive rounds",
    De: "Yaku in 3 aufeinanderfolgenden Runden",
    Fr: "Déclencher yaku dans 3 manches consécutives",
    Es: "Yaku en 3 rondas consecutivas",
    Hi: "लगातार 3 राउंड में याकु"),

I also wrote a Python script that audits all 223 locale keys for missing translations across all 6 languages — found 8 keys that were ja-only or ja+en-only and patched them. v0.1.1 ships with 100% locale coverage now.

key_re = re.compile(r'\["([^"]+)"\]\s*=\s*new\(', re.MULTILINE)
for m in key_re.finditer(content):
    args = extract_args_with_paren_balance(m)
    for lang in ['De', 'Fr', 'Es', 'Hi']:
        if not re.search(rf'\b{lang}:', args):
            missing[lang.lower()].append(m.group(1))

(The naïve [^)]+ regex doesn't work because some translations contain parentheses. Always paren-balance.)

Numbers from this session

Lines added: ~600 (PromotionExam.cs + UserStats hooks + UI dialog + locale keys)
Lines moved: ~400 (extracted Main.cs settings UI to a partial class)
Tests added: 30 (PromotionExamTests + edge cases for KoiKoiGameTests)
Total test count now: 236 (from 184)
Build warnings: 0 (the partial-class refactor accidentally introduced 4 dead-code warnings from BuildFlags.IsOfflineOnly const branches; fixed with #pragma warning disable CS0162 rather than restructuring code that needs to come back when online MP ships)
Time to ship: ~3 hours, mostly Claude pair-programming

What's in v0.1.1 in total

Beyond the exam system, this version also includes:

Full 6-language locale audit (8 missing keys patched)
Edge-case test suite expansion (Test_EmptyCapturesNoYaku, Test_SakeCupCountsAsBothTaneAndPair, etc.)
Settings file corruption auto-repair (try/catch + value clamping + corrupted-file backup)
Keyboard navigation (Tab/Enter/Esc/F11 fullscreen)
macOS GIF demo, OGP metadata, bilingual press kit
Trailer script and Reddit/HN draft for cross-posting

Try it

Download Shin KoiKoi v0.1.1 (free) — Mac, Windows, Linux. Single player only for now; online matchmaking is still pending free server capacity at Oracle Cloud (which has been "Out of host capacity" for the entire weekend; the retry script is at attempt 64 of 96 as I write this).

If anyone wants to read about the exam catalog data design, the streak-tracker test suite, or the Godot partial class split that kept the refactor cheap, I'll happily write follow-up posts. Reply or DM with what you'd want.

Solo dev: hogwartz.inc. Pair programming: Anthropic Claude. Engine: Godot 4.6.2 .NET. Built with respect for the traditional game and the player's time.

DEV Community