riichi-mahjong 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# riichi-mahjong
+
+一个 **日本麻将（日麻）计算引擎**，用于手牌解析、役种计算、符数与番数计算、点数计算和和牌判定。已通过 **Tenhou.net 2009–2024 年历年真实对局数据测试**，累计处理 **19,960,236 手对局**。
+
+---
+
+## 功能
+
+- 针对 **微信小程序** 优化的 **日麻计算引擎**：
+  - 明副露和暗手牌处理
+  - 全部标准役种与役满
+  - 宝牌（Dora）与里宝牌（Ura Dora）指示牌计算
+  - 支持立直、两立直、一发、岭上开花、海底/河底、抢杠、天和、地和
+  - 支持复合役满和双倍役满
+- 精确 **和牌点数计算**：番数、符数、最终点数
+- 使用 **UMD 打包**，适合直接在 **微信小程序** 中 `import` 使用
+
+---
+
+## 安装
+
+```bash
+npm install riichi-mahjong
+```
+
+## 使用示例
+
+```ts
+import calc, { ETile, WindType } from "riichi-mahjong";
+
+// ===== 调用 calc() 执行计算 =====
+const result: CalcResult = calc(
+  {
+    // 闭合手牌（未副露）
+    closedTiles: [ETile.P1, ETile.P1],
+    // 副露牌组 [是否明副露, 牌数组]
+    openParts: [
+      [true, [ETile.M1, ETile.M2, ETile.M3]],
+      [true, [ETile.M4, ETile.RED_M5, ETile.M6]],
+      [true, [ETile.M7, ETile.M8, ETile.M9]],
+      [true, [ETile.M1, ETile.M2, ETile.M3]],
+    ],
+  },
+  {
+    // ===== 和牌判定相关选项 =====
+    roundWind: WindType.EAST,           // 场风
+    seatWind: WindType.EAST,            // 自风
+    doraIndicators: [] as ETile[],      // 宝牌指示牌
+    uraDoraIndicators: [] as ETile[],   // 里宝牌指示牌（立直后有效）
+
+    // 立直相关 
+    isRiichi: false,            // 是否立直
+    isDoubleRiichi: false,      // 是否两立直
+    isIppatsu: false,           // 是否一发
+
+    // 牌型特殊状态
+    isTsumo: false,             // 是否自摸
+    isRinshan: false,           // 是否岭上开花
+    isHaiteiHoutei: false,      // 是否海底捞月/河底捞鱼
+    isChankan: false,           // 是否抢杠
+    isTenhou: false,            // 是否天和
+    isChiihou: false,           // 是否地和
+
+    // 役满选项
+    isCompositeYakumanAllowed: false,   // 是否允许复合役满
+    isDoubleYakuman: false,             // 是否允许双倍役满
+  }
+);
+
+// ===== 可选：使用内部工具进行细粒度控制 =====
+// - class HandResolver：解析手牌 { closedTiles, openParts }
+// - yakuCalculator()：根据 HandResolver 的结果计算役种与点数
+// - calcScore()：根据番、符、庄/闲等信息计算最终点数
+```
+
+## 结算结果
+
+```ts
+/**
+ * 计算结果类型
+ */
+type CalcResult = CalcResultWin | CalcResultLose;
+
+/**
+ * 没有和牌
+ */
+interface CalcResultLose {
+  isWin: false;                         // 是否和牌
+  message: "NOT_WINNING" | "NO_YAKU";   // 消息
+}
+
+/**
+ * 和牌
+ */
+interface CalcResultWin {
+  isWin: true;              // 是否和牌
+  message: "WINNING";       // 消息
+  data: YakuCalcResult;     // 计算结果数据
+}
+
+/**
+ * 和牌计算结果数据类型
+ */
+interface YakuCalcResult {
+  yaku: Yaku[];         // 役种数组
+  dora: Dora[];         // 宝牌数组
+  han: number;          // 番数
+  fu: Fu;               // 符数
+  score: ScoreResult;   // 点数
+  hand: WinningHand;    // 牌型
+}
+```