# mahjong

**Repository Path**: humbledaddy/mahjong

## Basic Information

- **Project Name**: mahjong
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 在线麻将平台

支持多种麻将玩法、3-4 人同桌对战的在线麻将项目（框架版）。

## 玩法

| ID | 名称 | 说明 |
| --- | --- | --- |
| `kawuxing` | 卡五星 | 湖北襄阳三人麻将，万筒索 108 张，无字牌，不可吃 |
| `sichuan` | 四川麻将 | 血战到底，万筒索 108 张，无字牌，不可吃，缺一门，3-4 人 |
| `wuhan` | 武汉麻将 | 红中癞子杠，红中作癞子，不可吃 |
| `riichi` | 日本麻将 | 立直麻将，136 张含赤五，支持吃碰杠、立直、宝牌 |

> 各玩法的番型、计分、癞子、宝牌等细节仍在细化中，当前为可运行的框架。

## 技术栈

- **monorepo**：npm workspaces（`shared` / `server` / `client`）
- **shared**：牌面定义、游戏类型、Socket.IO 通信协议（前后端共用）
- **server**：Node.js + TypeScript + Express + Socket.IO，内置可插拔的玩法引擎
- **client**：React + TypeScript + Vite + socket.io-client

## 目录结构

```
mahjong/
├── shared/          # 共用类型与常量（牌、协议、对局状态）
├── server/
│   └── src/
│       ├── index.ts           # 入口：HTTP + Socket.IO
│       ├── lobby.ts           # 房间列表管理
│       ├── room.ts            # 单个房间（成员、准备、开局）
│       ├── transport/socket.ts# Socket.IO 事件路由
│       └── game/
│           ├── engine.ts      # 对局引擎（摸牌、出牌、鸣牌、和牌）
│           ├── evaluate.ts    # 和牌判定（4 面子 + 1 对 / 七对子）
│           └── rules/         # 玩法插件（可扩展）
│               ├── ruleset.ts # Ruleset 接口
│               ├── base.ts    # 通用基础规则
│               ├── kawuxing.ts
│               ├── sichuan.ts
│               ├── wuhan.ts
│               └── riichi.ts
└── client/
    └── src/
        ├── state/useMahjong.ts # 连接与状态管理
        ├── components/         # 大厅 / 房间 / 对局 / 牌
        └── lib/socket.ts       # 类型化 Socket.IO 封装
```

## 快速开始

```bash
# 安装依赖（在 mahjong/ 目录）
npm install

# 开发模式（构建 shared，并启动 server:3001 + client:5173）
npm run dev
```

打开 http://localhost:5173 ，输入昵称，创建房间或输入房间号加入。

## 其它脚本

```bash
npm run build       # 构建全部产物
npm run typecheck   # 类型检查
npm run start       # 生产模式启动服务器（托管 client/dist）
```

## 架构说明

- **玩法可插拔**：每种麻将实现 `Ruleset` 接口（`server/src/game/rules/ruleset.ts`），
  通过 `registerRuleset` 注册后即可被大厅选择。新增玩法只需新建一个继承 `BaseRuleset` 的类。
- **引擎与规则分离**：`engine.ts` 只负责通用的摸牌/出牌/鸣牌/和牌流程，
  具体牌型、番型、计分由 `Ruleset` 决定。
- **通信协议**：所有事件定义在 `shared/src/protocol.ts`，前后端共享类型。

## 待细化（TODO）

- 各玩法的番型、计分规则（当前 `score` 为占位实现）
- 癞子（武汉麻将）的和牌判定
- 川麻「血战到底」多人先后胡牌、流局处理
- 日麻宝牌、立直、振听等
- 断线重连、观战、房间密码