Mahjong Scorer Plugin

Score a mahjong game in real time. Track players, seats, fans (faan), points, and running standings. English-focused with natural language hand description parsing.

Current Version: v0.1.0 — HK Old Style

Based on Hong Kong mahjong scoring rules.

Tools

Tool	Purpose
mahjong_start_game	Set up a new game: player names, seats, scoring config
mahjong_score_hand	Score a completed hand: faan -> points -> payment -> standings
mahjong_amend_hand	Fix the last hand: add forgotten items or replace entirely
mahjong_status	Show current standings and recent hand history
mahjong_end_game	End game: final results, hand-by-hand summary, clear state

Skill

The bundled skill (mahjong-scorer) teaches the assistant the game flow:

1. Collect player names/seats via form UI
2. Go on standby (10-20 min between hands)
3. Parse natural language hand descriptions into faan keys
4. Call the scoring tool and present results
5. Handle amendments ("actually that last hand was also concealed")
6. Report standings on request
7. End game with final summary

Scoring Rules

• Faan is the unit of hand value. Multiple categories stack.
• Min faan: 3 (default). Below = false win.
• Max faan: 13 (absolute cap). Some games cap at 10.
• Full Spicy: points = 2^faan
• Half Spicy: gentler curve from 4 faan onward
• Payment: Discarder pays all (default) or half. Self-pick = all pay 1.5x.
• Limit hands (10-13 faan) supersede wind/dragon/flower faan.

See skills/mahjong-scorer/references/hk-fan-table.md for the complete fan table.

File Structure

mahjong-scorer/
├── package.json
├── config.json
├── README.md
├── src/
│   ├── scoring-engine.ts    # Fan table, stacking rules, faan->points, payment calc
│   └── game-state.ts        # State persistence, round rotation, standings
├── tools/
│   ├── mahjong_start_game.ts
│   ├── mahjong_score_hand.ts
│   ├── mahjong_amend_hand.ts
│   ├── mahjong_status.ts
│   └── mahjong_end_game.ts
└── skills/
    └── mahjong-scorer/
        ├── SKILL.md
        └── references/
            └── hk-fan-table.md

Future Variations

Different mahjong rule sets can be shipped as new versions:

• v0.2.0: Japanese Riichi
• v0.3.0: Singapore
• v0.4.0: American NMJL
• etc.

Each version would extend the scoring engine with variant-specific fan tables and rules while keeping the same tool interface.