Features

Yaku Detection

Complete yaku detection system supporting all standard Japanese mahjong winning hands

Hand Analysis

Automatic analysis of tile combinations and hand structures

Tenpai Detection

Fast detection of possible winning tiles and waiting patterns

Furiten Checking

Prevents illegal wins with comprehensive furiten detection

Technical Specifications

  • TypeScript implementation with full type safety
  • Comprehensive test coverage (80+ test cases)
  • Modular architecture for easy extension
  • Support for most standard yaku (1-han to yakuman, with limitations)
  • Red dora tile handling
  • Open/closed hand distinction
  • Multiple waiting pattern detection
  • Compatible with modern JavaScript environments

System Limitations

Important: This demo version has some limitations in yaku detection:

Not Implemented

  • Chankan (槍槓)
  • Ippatsu (一發)
  • Suukansanra (四槓散了)

Partially Supported

  • Tenhou (天和)
  • Chihou (地和)
  • Renhou (人和)
  • Double Riichi (兩立直)

Best Supported

  • Standard sequences & triplets
  • Color-based yaku
  • Terminal & honor patterns
  • Most 1-6 han yaku

Recommendation: Use standard 14-tile winning hands for the most accurate yaku detection.

Quick Start

Try the Hand Analyzer! Switch to the "Hand Analyzer" tab to input tile combinations and see yaku detection in action.

Input format examples:

  • 123m456p789s1122z - Mixed tiles with pairs
  • 111222333m44455p - Triplets and sequences
  • 19m19p19s1234567z - Terminals and honors

Interactive Hand Analyzer

Analysis Options

Predefined Examples

Click any example below to load it into the analyzer and see detailed yaku analysis.

Basic Yaku (1-2 Han)

Medium Yaku (2-3 Han)

High Value Hands (3-6 Han)

Yakuman Hands

Hand Generator

Generate different types of random hands for practice and exploration:

Learning Corner

Tip: Each example demonstrates different yaku patterns. After loading an example, switch to the "Hand Analyzer" tab to see the detailed breakdown of yaku, han value, and scoring.

Common Patterns Explained:

  • Pinfu: Four sequences and a simple wait (no points from groups or wait)
  • Tanyao: Only uses number tiles 2-8 (no terminals or honors)
  • Chinitsu: All tiles from one suit only (6 han if closed, 5 han if open)
  • Kokushi: One each of all terminals and honors plus one pair (Yakuman)
  • Suuankou: Four concealed triplets (Yakuman)

Custom Yaku Creator

Create your own custom yaku rules using the same format as the built-in yaku system. Define requirements, han values, and register them directly into the yaku registry.

📚 New Feature: Custom yakus now use the same format as built-in yakus from register.ts. Use the 🔍 Browse All Yakus button to see all registered yakus and manage them!
Custom Yaku Cache: Cache persists your custom yaku between sessions

Custom Yaku Examples

All Even Numbers

Detects hands with only even-numbered tiles (2,4,6,8)

Rainbow Hand

Requires tiles from all three number suits

Lucky Seven

Hand must contain at least 3 sevens

📋 Yaku Registry Requirements Format:

Custom yakus now use the same RonRequirements format as built-in yakus. See the Documentation tab for detailed examples and format reference.

Active Custom Yaku

No custom yaku defined yet. Create one above!

🎯 Yaku Registry System Documentation

New System! Custom yakus now use the same registry format as built-in yakus from register.ts. This ensures consistency and full compatibility with the yaku analysis engine.

📋 RonRequirements Format Reference

Custom yakus use the RonRequirements interface. Here are the main properties:

🔧 Main Properties
  • requires: Requirement[] - Array of tile/unit requirements
  • requireConcealed: boolean - Must be closed hand (menzen)
  • requireOpen: boolean - Must have open melds
  • requiredTsumo: boolean - Must be self-draw win
  • requiredLastRound: boolean - Must be last round
  • requiredFirstRound: boolean - Must be first round
  • isOr: boolean - Requirements are OR (instead of AND)
  • specialCondition: function - Custom validation logic
🧩 Requirement Object Properties
  • minUnits - Minimum required units (Koutsu, Shuntsu, etc.)
  • allowedSuits - Only these suits allowed
  • allowedNumbers - Only these numbers allowed
  • requiredSuits - Must contain these suits
  • requiredNumbers - Must contain these numbers
  • filteredNumbers - These numbers not allowed
  • unitRepeat - Same unit must repeat N times
  • dynamicRequirement - Dynamic conditions (Jihai, Bakaze)

📚 Examples from Built-in Yakus

Example 1: Simple Requirements (Tanyao)
{
  "requires": [
    {
      "filteredNumbers": [1, 9],
      "allowedSuits": ["MAN", "PIN", "SOU"]
    }
  ]
}

This yaku excludes terminals (1,9) and only allows number suits.

Example 2: Unit Requirements (Toitoihou - All Triplets)
{
  "requires": [
    {
      "minUnits": {
        "Koutsu": 4,
        "Toitsu": 1
      }
    },
    {
      "minUnits": {
        "Koutsu": 2,
        "Kantsu": 2
      }
    }
  ],
  "isOr": true
}

Requires either 4 triplets + 1 pair OR 2 triplets + 2 quads.

Example 3: Concealed Requirement (Pinfu)
{
  "requires": [
    {
      "minUnits": {
        "Shuntsu": 3,
        "Toitsu": 1,
        "RyanmenTatsu": 1
      },
      "requiredSuits": ["MAN", "PIN", "SOU"]
    }
  ],
  "requireConcealed": true
}

Requires sequences and must be concealed hand.

Example 4: Unit Repetition (Iipeikou - Two Identical Sequences)
{
  "requires": [
    {
      "minUnits": { "Shuntsu": 1 },
      "unitRepeat": 2
    }
  ],
  "requireConcealed": true
}

Requires the same sequence to appear twice, must be concealed.

Example 5: Dynamic Requirements (Jihai - Seat Wind)
{
  "requires": [
    {
      "minUnits": { "Koutsu": 1 },
      "dynamicRequirement": ["Jihai"]
    }
  ]
}

Requires triplet of player's seat wind (dynamic based on game state).

Example 6: Multiple Conditions with OR (Toitoihou - All Triplets)
{
  "requires": [
    {
      "minUnits": {
        "Koutsu": 4,
        "Toitsu": 1
      }
    },
    {
      "minUnits": {
        "Koutsu": 2,
        "Kantsu": 2
      }
    }
  ],
  "isOr": true
}

Accepts either 4 triplets + pair OR 2 triplets + 2 quads.

Example 7: Special Conditions (Last Round)
{
  "requiredLastRound": true,
  "requiredTsumo": true
}

Haitei Tsumo - must be last tile draw of the game.

Example 8: Mixed Conditions (Honroutou - Mixed Terminals)
{
  "requires": [
    {
      "allowedSuits": ["MAN", "PIN", "SOU"],
      "allowedNumbers": [1, 9]
    },
    {
      "allowedSuits": ["WIND", "DRAGON"],
      "allowedNumbers": [1, 2, 3, 4]
    }
  ]
}

Allows only terminals (1,9) and honor tiles.

🎮 Available Constants

MahjongSimpleUnits:
Shuntsu, Koutsu, Toitsu, Kantsu, RyanmenTatsu, Ippatsu
MahjongSuits:
MAN (0), PIN (1), SOU (2), WIND (3), DRAGON (4)
Numbers:
1-9 for number tiles, 1-4 for winds (E,S,W,N), 1-3 for dragons (Wh,Gr,Re)

🛠️ How to Create Custom Yaku

  1. Study Examples: Look at built-in yakus in the browser
  2. Define Requirements: Use the RonRequirements format
  3. Test JSON: Validate your JSON syntax
  4. Add Yaku: Use the Custom Yaku Creator
  5. Test & Verify: Try with different hands
  6. Save to Cache: Persist your custom yakus

📖 Quick Reference Guide

🎯 Common Patterns
  • All Same Type: allowedSuits: ["MAN"]
  • No Terminals: filteredNumbers: [1, 9]
  • Only Honors: allowedSuits: ["WIND", "DRAGON"]
  • Must be Concealed: requireConcealed: true
  • Same Sequence Twice: unitRepeat: 2
  • All Triplets: minUnits: { "Koutsu": 4 }
  • Self-Draw Only: requiredTsumo: true

💡 Pro Tips for Custom Yakus

✅ Best Practices
  • Start Simple: Begin with basic tile/suit restrictions
  • Test Thoroughly: Try different hand combinations
  • Use Built-in Examples: Study existing yakus for patterns
  • Validate JSON: Ensure proper syntax before adding
  • Name Clearly: Use descriptive names for custom yakus
⚠️ Common Mistakes
  • Forgetting quotes around string values
  • Using wrong suit names (use CAPS: MAN, PIN, SOU, WIND, DRAGON)
  • Invalid number ranges for different suits
  • Conflicting requirements (e.g., concealed + open)
  • Too restrictive conditions (impossible hands)
🎉 Ready to Create? Use the Yaku Browser above to view all existing yakus, then try the Custom Yaku Creator to make your own! Your custom yakus will integrate seamlessly with the analysis system.
⚠️ Important Notes:
  • Custom yakus are registered directly into the yaku system
  • They work exactly like built-in yakus during analysis
  • Use the Yaku Browser to manage all yakus
  • Invalid JSON will be rejected with error messages
  • Complex conditions may require specialCondition functions

What Are Custom Yaku? 🤔

Custom yaku are user-defined scoring patterns that go beyond traditional mahjong rules. With our JSON-based system, you can:

  • ✅ Create unique scoring patterns
  • ✅ Experiment with new mahjong variants
  • ✅ Learn about pattern recognition
  • ✅ Share your creations with others
  • ✅ No programming knowledge required!

Step-by-Step Tutorial 📖

Step 1: Understanding Registry Format

Custom yakus use the same RonRequirements format as built-in yakus from the registry system:

Example - No Terminals:
{
  "requires": [
    {
      "filteredNumbers": [1, 9],
      "allowedSuits": ["MAN", "PIN", "SOU"]
    }
  ]
}

What this means: Hand cannot contain 1s or 9s (terminals), and only number suits are allowed.

Step 2: Registry Properties Explained

🎯 allowedNumbers

Only these numbers are allowed

"allowedNumbers": [2,4,6,8]
🌈 requiredSuits

Hand must contain these suits

"requiredSuits": ["MAN","PIN","SOU"]
🔢 minUnits

Minimum required tile units

"minUnits": {"Koutsu": 3}
👑 requireConcealed

Hand must be concealed (menzen)

"requireConcealed": true
🚫 filteredNumbers

These numbers are not allowed

"filteredNumbers": [1,9]
🔚 requiredTsumo

Must be won by self-draw

"requiredTsumo": true

Step 3: Creating Your First Custom Yaku

  1. Go to the Custom Yaku tab
  2. Enter a name for your yaku (e.g., "No Terminals")
  3. Set the han value (1-13)
  4. Paste or type your RonRequirements definition
  5. Click "Add Custom Yaku"
  6. Test it with sample hands!
💡 Pro Tip: Use the "Browse Yaku Library" button to see pre-made examples and learn from them!

Step 4: Testing and Managing Your Yaku

  • Test Button: Quickly test your yaku against the current hand in the analyzer
  • Edit Function: Click "Edit" on any yaku to modify it
  • Remove Option: Delete yaku you no longer need
  • Integration: All custom yaku automatically appear in hand analysis results

Advanced Examples & Best Practices 🎨

Example 1: Complex Pattern - "Lucky Sevens"

A yaku that requires multiple 7s in the hand:

{
  "requires": [
    {
      "requiredNumbers": [7],
      "allowedSuits": ["MAN", "PIN", "SOU"]
    }
  ]
}

Example 2: Suit Restriction - "No Circles"

A pattern that excludes pin (circle) tiles completely:

{
  "requires": [
    {
      "allowedSuits": ["MAN", "SOU", "WIND", "DRAGON"]
    }
  ]
}

🏆 Best Practices

  • Start Simple: Begin with basic patterns before creating complex rules
  • Test Thoroughly: Use various hand combinations to verify your yaku works correctly
  • Reasonable Han Values: Keep han values balanced (1-3 for common patterns, 4+ for rare ones)
  • Clear Names: Use descriptive names that explain what the yaku does
  • Follow Registry Format: Use the same RonRequirements format as built-in yakus
  • Study Examples: Check the documentation examples to understand the registry format

Built-in Yaku Reference

1 Han

  • Riichi
  • Menzen Tsumo
  • Pinfu
  • Tanyao
  • Yakuhai
  • Ippatsu
  • Rinshan Kaihou
  • Chankan
  • Haitei
  • Houtei

2 Han

  • Double Riichi
  • Chitoitsu
  • Chanta
  • Ittsu
  • Sanshoku Doujun
  • Sanshoku Doukou
  • Sankantsu
  • Toitoi
  • Sanankou
  • Shousangen
  • Honroutou

3 Han

  • Honitsu
  • Junchan
  • Ryanpeikou

6 Han

  • Chinitsu

Yakuman

  • Kokushi Musou
  • Suuankou
  • Daisangen
  • Shousuushii
  • Daisuushii
  • Tsuuiisou
  • Chinroutou
  • Ryuuiisou
  • Chuuren Poutou
  • Suukantsu
  • Tenhou
  • Chiihou

Tile Format Guide

Number Tiles

  • 1-9m - Manzu (Characters)
  • 1-9p - Pinzu (Circles)
  • 1-9s - Souzu (Bamboo)

Honor Tiles

  • 1z - East Wind
  • 2z - South Wind
  • 3z - West Wind
  • 4z - North Wind
  • 5z - White Dragon
  • 6z - Green Dragon
  • 7z - Red Dragon