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
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
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
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.
register.ts.
Use the 🔍 Browse All Yakus button to see all registered yakus and manage them!
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
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 requirementsrequireConcealed: boolean- Must be closed hand (menzen)requireOpen: boolean- Must have open meldsrequiredTsumo: boolean- Must be self-draw winrequiredLastRound: boolean- Must be last roundrequiredFirstRound: boolean- Must be first roundisOr: 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 allowedallowedNumbers- Only these numbers allowedrequiredSuits- Must contain these suitsrequiredNumbers- Must contain these numbersfilteredNumbers- These numbers not allowedunitRepeat- Same unit must repeat N timesdynamicRequirement- 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
- Study Examples: Look at built-in yakus in the browser
- Define Requirements: Use the RonRequirements format
- Test JSON: Validate your JSON syntax
- Add Yaku: Use the Custom Yaku Creator
- Test & Verify: Try with different hands
- 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)
- 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:
{
"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
- Go to the Custom Yaku tab
- Enter a name for your yaku (e.g., "No Terminals")
- Set the han value (1-13)
- Paste or type your RonRequirements definition
- Click "Add Custom Yaku"
- Test it with sample hands!
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