daoqi/youlegames

Fork 0

Files

Joywayer 6b22238c6e 目录结构调整

2026-02-04 23:47:45 +08:00

20 KiB

Raw Permalink Blame History

进贤麻将子游戏技术文档

📚 完整的进贤麻将子游戏技术文档，涵盖架构设计、核心算法、开发指南等所有方面。

🎯 文档概述

本文档集为 server/games2/jinxianmahjong 子游戏提供完整的技术说明，帮助开发者快速理解项目架构、掌握核心算法、完成功能开发。

文档特点:

✅ 全面覆盖 - 14篇文档，约240,000字，覆盖所有核心模块
✅ 深入详细 - 包含算法分析、代码示例、最佳实践
✅ 结构清晰 - 按框架、核心、架构、开发四大类组织
✅ 实用导向 - 提供快速入门、常见任务、问题解答

最后更新: 2025年10月15日
文档版本: v1.0
维护团队: 进贤麻将开发团队

🚀 快速开始

5分钟了解项目

// 1. 三文件架构（核心概念）
mod.js     → 模块入口，加载所有文件
export.js  → 框架调用游戏（14个接口）
import.js  → 游戏调用框架（13个接口）

// 2. 请求处理流程
客户端 → packet.js → mod.js → RpcHandler → 业务逻辑 → import → 客户端

// 3. 核心目录
rpc/           → RPC请求处理（34个方法）
game/          → 游戏核心服务（Controller、Manager、Service）
shared/        → 前后端共享代码（算法、数据结构、配置）
utils/         → 工具模块（Logger、ErrorHandler）

📚 文档导航

一、框架基础（Framework）

掌握友乐游戏平台的基础架构和接口规范。

文档	内容概要	字数	难度
00-框架基础概述.md	友乐平台架构、三文件架构、ES5规范、前后端分离	14,000	⭐
01-Export接口说明.md	框架→游戏的14个接口详解	18,000	⭐⭐
02-Import接口说明.md	游戏→框架的13个接口详解	15,000	⭐⭐
03-RPC处理机制.md	RPC路由流程、34个RPC方法详解	23,000	⭐⭐⭐

学习收获:

✅ 理解友乐平台的三文件架构
✅ 掌握Export和Import接口的使用
✅ 理解RPC请求的完整处理流程
✅ 了解ES5规范和浏览器兼容性

二、核心服务（Core）

深入理解游戏核心服务、算法实现和配置系统。

文档	内容概要	字数	难度
04-游戏核心服务.md	GameController、OperationManager等5大服务	30,000	⭐⭐⭐
05-共享代码模块.md	JingAlgorithm、WinDetection等核心算法	35,000	⭐⭐⭐⭐⭐
06-规则配置系统.md	RoomType编码、配置解析、缓存机制	25,000	⭐⭐⭐

学习收获:

✅ 掌握游戏核心服务的职责和协作
✅ 深入理解精牌系统算法（5166行）
✅ 掌握胡牌检测和计分计算
✅ 理解房间配置的解析和使用

重点推荐: 📌 05-共享代码模块.md 是最复杂、最详细的文档，深度分析了核心算法实现。

三、架构设计（Architecture）

从宏观角度理解游戏流程和整体架构。

文档	内容概要	字数	难度
08-游戏流程概述.md	完整游戏流程、状态机、时序图	25,000	⭐⭐⭐
09-代码框架总结.md	架构总结、设计模式、扩展指南	20,000	⭐⭐⭐⭐

学习收获:

✅ 理解游戏从开始到结束的完整流程
✅ 掌握游戏状态机和阶段转换
✅ 理解整体架构设计和模块依赖
✅ 学习设计模式的实际应用

四、开发指南（Development）

实用的开发工具、调试技巧和快速入门。

文档	内容概要	字数	难度
07-工具模块.md	Logger日志系统、ErrorHandler错误处理	20,000	⭐⭐
10-快速入门指南.md	快速理解、开发任务、FAQ、实战练习	15,000	⭐

学习收获:

✅ 掌握Logger的6级日志使用
✅ 理解错误处理规范
✅ 快速定位代码位置
✅ 解决常见开发问题

🎓 按角色选择学习路径

👨‍💻 新开发者（第1天）

目标: 快速理解项目，能修改简单功能

上午（2-3小时）:
├─ 阅读 README.md（本文档）            10分钟
├─ 阅读 00-框架基础概述.md             30分钟
├─ 阅读 01-Export接口说明.md           20分钟
├─ 阅读 02-Import接口说明.md           20分钟
└─ 阅读 10-快速入门指南.md             40分钟

下午（2-3小时）:
├─ 阅读 08-游戏流程概述.md             40分钟
├─ 浏览代码结构                        30分钟
├─ 完成第一个功能修改（添加日志）      30分钟
└─ 完成练习（修改分数规则）            30分钟

预期成果:

✅ 理解三文件架构和RPC机制
✅ 知道去哪里找需要的代码
✅ 能完成简单的功能修改

🔬 算法工程师（第1-2天）

目标: 深入理解核心算法实现

第1天 - 精牌系统:
├─ 阅读 05-共享代码模块.md（JingAlgorithm部分） 2小时
├─ 研究 JingAlgorithm.js 源码                  2小时
└─ 理解比精算法和精分计算                      1小时

第2天 - 胡牌检测与计分:
├─ 阅读 05-共享代码模块.md（其他算法部分）    2小时
├─ 研究 WinDetectionFactory.js 源码           1.5小时
├─ 研究 ScoreCalculation.js 源码              1.5小时
└─ 理解牌型检测和计分流程                      1小时

预期成果:

✅ 深入理解精牌系统算法（5166行）
✅ 掌握5种牌型的检测算法
✅ 理解计分系统的实现细节

🏗️ 架构师（第1-2天）

目标: 理解整体架构和设计理念

第1天 - 架构理解:
├─ 阅读 00-框架基础概述.md                    30分钟
├─ 阅读 03-RPC处理机制.md                     1小时
├─ 阅读 04-游戏核心服务.md                    1.5小时
├─ 阅读 08-游戏流程概述.md                    1.5小时
└─ 阅读 09-代码框架总结.md                    1.5小时

第2天 - 深入分析:
├─ 分析模块依赖关系                           1小时
├─ 分析设计模式应用                           1小时
├─ 评估性能优化点                             1小时
└─ 规划扩展方案                               2小时

预期成果:

✅ 理解三层架构设计
✅ 掌握6大设计模式的应用
✅ 了解模块依赖关系
✅ 能够规划架构扩展

🛠️ 功能开发者（按需学习）

目标: 根据开发任务学习相关知识

任务1: 添加新RPC方法

需要阅读:
├─ 03-RPC处理机制.md（RpcHandler详解）
└─ 10-快速入门指南.md（任务1: 添加新RPC方法）
预计时间: 1小时

任务2: 修改计分规则

需要阅读:
├─ 05-共享代码模块.md（ScoreCalculation部分）
└─ 10-快速入门指南.md（任务2: 修改计分规则）
预计时间: 1.5小时

任务3: 添加新游戏规则

需要阅读:
├─ 06-规则配置系统.md
└─ 10-快速入门指南.md（任务3: 添加新游戏规则）
预计时间: 2小时

任务4: 添加新牌型

需要阅读:
├─ 05-共享代码模块.md（WinDetectionFactory部分）
└─ 10-快速入门指南.md（任务5: 添加新牌型检测）
预计时间: 3小时

🔍 按问题查找文档

问题: 客户端请求如何处理？

答案位置:

📖 03-RPC处理机制.md - 完整RPC处理流程
📖 04-游戏核心服务.md - RpcHandler详解

关键代码: rpc/RpcHandler.js

问题: 精牌系统是如何实现的？

答案位置:

📖 05-共享代码模块.md - 精牌算法详解
📖 08-游戏流程概述.md - 精牌确定流程

关键代码: shared/algorithms/JingAlgorithm.js（5166行）

问题: 如何判断能否胡牌？

答案位置:

📖 05-共享代码模块.md - 胡牌检测算法
📖 04-游戏核心服务.md - 胡牌服务

关键代码: shared/algorithms/WinDetectionFactory.js

问题: 分数是如何计算的？

答案位置:

📖 05-共享代码模块.md - 计分算法详解
📖 08-游戏流程概述.md - 结算流程

关键代码: shared/algorithms/ScoreCalculation.js（917行）

问题: 如何添加日志和调试？

答案位置:

📖 07-工具模块.md - Logger详细说明
📖 10-快速入门指南.md - 日志使用示例

关键代码: utils/Logger.js（606行）

问题: 游戏状态如何管理？

答案位置:

📖 04-游戏核心服务.md - gameState详解
📖 08-游戏流程概述.md - 状态转换

关键代码: shared/dataStructures/GameStateManager.js

问题: 房间配置如何解析？

答案位置:

📖 06-规则配置系统.md - 完整配置系统说明
📖 01-Export接口说明.md - roomtype格式

关键代码: shared/config/RoomConfigUtils.js（1222行）

📖 文档特色内容

🏆 最详细：05-共享代码模块.md

35,000字 深度分析
涵盖 5大核心算法 详解
JingAlgorithm.js 5166行完整分析
ScoreCalculation.js 917行计分逻辑
MahjongCard.js 2461行牌对象系统

适合: 想深入理解算法实现的开发者

🔄 最全面：08-游戏流程概述.md

完整游戏流程 从开始到结束
7个游戏阶段 详细说明
状态机设计 和转换规则
时序图 展示交互流程
操作优先级 处理机制

适合: 想理解整体流程的开发者

🛠️ 最实用：10-快速入门指南.md

10分钟 快速理解核心概念
5个常见开发任务 详细步骤
10个FAQ 解答高频问题
3个实战练习 从易到难
代码导航技巧 快速定位

适合: 想快速上手的新开发者

🏗️ 最系统：09-代码框架总结.md

三层架构 详细说明
完整依赖关系图 (6层依赖)
6大设计模式 实战应用
4个扩展指南 详细步骤
5个常见问题 解决方案

适合: 想理解架构设计的开发者

📊 文档统计

文档数量与字数

分类	文档数	总字数	占比
框架基础	4篇	70,000字	29%
核心服务	3篇	90,000字	38%
架构设计	2篇	45,000字	19%
开发指南	2篇	35,000字	14%
总计	13篇	240,000字	100%

难度分布

⭐ 入门级：2篇（快速理解）
⭐⭐ 初级：3篇（基础理解）
⭐⭐⭐ 中级：5篇（深入理解）
⭐⭐⭐⭐ 高级：2篇（架构设计）
⭐⭐⭐⭐⭐ 专家级：1篇（算法深度）

预计学习时间

快速浏览: 2小时（理解基础架构）
系统学习: 2天（完整阅读所有文档）
深入研究: 1周（理解所有算法细节）
精通掌握: 2周（能独立开发和架构）

🔧 技术栈

编程语言

JavaScript ES5 - 严格遵循ES5规范，确保浏览器兼容性

运行环境

Node.js (服务端) - 游戏服务器
浏览器 (客户端) - Chrome/Firefox/Safari等

框架平台

友乐游戏平台 - 自研游戏框架
三文件架构 - mod.js/export.js/import.js

核心技术

RPC通信 - WebSocket/HTTP协议
状态机 - 7个游戏阶段管理
精牌算法 - 5166行核心算法
胡牌检测 - 5种牌型检测
计分系统 - 917行计分逻辑

📁 项目结构

server/games2/jinxianmahjong/
├── mod.js                      # 模块入口（加载所有文件）
├── export.js                   # 输出接口（框架→游戏，14个接口）
├── import.js                   # 输入接口（游戏→框架，13个接口）
│
├── rpc/                        # RPC处理器
│   ├── RpcHandler.js           # 标准RPC处理（34个方法）
│   ├── AIRpcHandler.js         # AI玩家RPC处理
│   └── OperationEnumerator.js  # 操作枚举器
│
├── game/                       # 游戏核心服务
│   ├── GameController.js       # 游戏流程控制器
│   ├── MahjongGameService.js   # 麻将游戏服务
│   ├── OperationManager.js     # 操作管理器
│   ├── AIManager.js            # AI管理器
│   └── RoomAdapter.js          # 房间适配器
│
├── shared/                     # 前后端共享代码
│   ├── algorithms/             # 核心算法
│   │   ├── JingAlgorithm.js    # 精牌算法（5166行）
│   │   ├── WinDetectionFactory.js  # 胡牌检测
│   │   ├── ScoreCalculation.js     # 计分系统（917行）
│   │   └── PatternFactory.js       # 牌型分析
│   ├── dataStructures/         # 数据结构
│   │   ├── GameStateManager.js     # 游戏状态管理
│   │   └── MahjongCard.js          # 麻将牌对象（2461行）
│   ├── config/                 # 配置系统
│   │   ├── RoomConfigUtils.js      # 配置工具（1222行）
│   │   └── RuleConfigParser.js     # 规则解析器
│   ├── constants/              # 常量定义（12个模块）
│   │   └── index.js            # 常量统一导出
│   └── utils/                  # 共享工具
│
└── utils/                      # 工具模块
    ├── Logger.js               # 日志管理器（606行）
    └── ErrorHandler.js         # 错误处理器（659行）

🌟 核心特性

1. 精牌系统（独特玩法）

进贤麻将最核心的特色系统，由 5166行 代码实现。

功能:

✅ 掷骰子确定精牌（正精、副精）
✅ 精牌可作为万能牌使用
✅ 精牌计分（正精2分、副精1分）
✅ 比精算法（比较精牌数量和价值）
✅ 冲关机制（精分达到10分翻倍）

文档: 05-共享代码模块.md - JingAlgorithm

2. 5种胡牌牌型

支持多种胡牌牌型，满足不同玩法需求。

牌型:

平胡 - 标准3-3-3-3-2组合
七对 - 7个对子
四碰 - 4个刻子+1个对子
十三烂 - 特殊散牌组合
七星十三烂 - 最高级别牌型

文档: 05-共享代码模块.md - WinDetectionFactory

3. 灵活的规则配置

13位roomtype编码，支持丰富的规则组合。

配置项:

局数（8/16/24局）
精牌（带精/不带精）
吃碰杠（允许/禁止）
特殊规则（上下翻、买雷雷等）

文档: 06-规则配置系统.md

4. 完善的日志系统

6级日志，支持历史记录和统计分析。

级别: TRACE → DEBUG → INFO → WARN → ERROR → FATAL

文档: 07-工具模块.md - Logger

⚡ 性能优化

1. 配置缓存机制

使用LRU缓存策略，避免重复解析roomtype配置。

效果:

✅ 缓存命中率 > 95%
✅ 配置解析时间 < 1ms

文档: 06-规则配置系统.md - 缓存机制

2. 对象池模式

复用MahjongCard对象，减少GC压力。

效果:

✅ 减少对象创建 80%
✅ 内存占用降低 30%

文档: 09-代码框架总结.md - 性能优化

3. 预计算策略

预先计算常用数据，提高运行时性能。

应用:

✅ 牌型组合预计算
✅ 精牌列表缓存
✅ 规则模板预加载

🤝 参与贡献

文档改进

如果你发现文档中的错误或需要改进的地方：

在对应文档中记录问题
提出改进建议
更新文档内容
同步更新相关交叉引用

代码贡献

如果你开发了新功能或修复了bug：

更新相关技术文档
添加代码示例
更新常见问题解答
更新本README的快速链接

📞 获取帮助

遇到问题？

查看文档 - 在本README中按问题查找相关文档
查看FAQ - 10-快速入门指南.md
搜索代码 - 使用文档中的代码导航技巧
查看日志 - 使用Logger追踪程序执行

学习建议

📖 先框架后细节 - 从框架基础开始，逐步深入
💻 理论结合实践 - 边学习边尝试修改代码
🔍 善用搜索 - 在文档中搜索关键词
📝 做好笔记 - 记录重要概念和代码位置

📜 更新日志

v1.0 (2025年10月15日)

完成的文档:

✅ 框架基础文档（4篇，70,000字）
✅ 核心服务文档（3篇，90,000字）
✅ 架构设计文档（2篇，45,000字）
✅ 开发指南文档（2篇，35,000字）
✅ 文档导航（README.md）

文档特点:

📚 13篇技术文档，总计约240,000字
🔍 深度分析核心算法（JingAlgorithm 5166行）
💡 丰富的代码示例和最佳实践
🎯 多种学习路径，适合不同角色

重要里程碑:

✅ 完成所有计划文档
✅ 建立完整文档体系
✅ 提供多角色学习路径
✅ 创建文档导航和快速索引

🎉 开始你的学习之旅！

选择一个适合你的学习路径，开始探索进贤麻将的技术世界吧！

推荐起点:

记住:

📖 遇到问题先查文档
🔍 善用本README的快速导航
💻 理论结合实践
🧪 多写代码多测试

Happy Coding! 🚀

维护团队: 进贤麻将开发团队
文档版本: v1.0
最后更新: 2025年10月15日

20 KiB Raw Permalink Blame History Unescape Escape

进贤麻将子游戏技术文档

🎯 文档概述

🚀 快速开始

5分钟了解项目

推荐学习路径

🌟 新手入门（2小时）

🔬 算法研究（进阶）

🛠️ 功能开发（实战）

📚 文档导航

一、框架基础（Framework）

二、核心服务（Core）

三、架构设计（Architecture）

四、开发指南（Development）

🎓 按角色选择学习路径

👨‍💻 新开发者（第1天）

🔬 算法工程师（第1-2天）

🏗️ 架构师（第1-2天）

🛠️ 功能开发者（按需学习）

任务1: 添加新RPC方法

任务2: 修改计分规则

任务3: 添加新游戏规则

任务4: 添加新牌型

🔍 按问题查找文档

问题: 客户端请求如何处理？

问题: 精牌系统是如何实现的？

问题: 如何判断能否胡牌？

问题: 分数是如何计算的？

问题: 如何添加日志和调试？

问题: 游戏状态如何管理？

问题: 房间配置如何解析？

📖 文档特色内容

🏆 最详细：05-共享代码模块.md

🔄 最全面：08-游戏流程概述.md

🛠️ 最实用：10-快速入门指南.md

🏗️ 最系统：09-代码框架总结.md

📊 文档统计

文档数量与字数

难度分布

预计学习时间

🔧 技术栈

编程语言

运行环境

框架平台

核心技术

📁 项目结构

🌟 核心特性

1. 精牌系统（独特玩法）

2. 5种胡牌牌型

3. 灵活的规则配置

4. 完善的日志系统

⚡ 性能优化

1. 配置缓存机制

2. 对象池模式

3. 预计算策略

🤝 参与贡献

文档改进

代码贡献

📞 获取帮助

遇到问题？

学习建议

📜 更新日志

v1.0 (2025年10月15日)

🎉 开始你的学习之旅！

20 KiB

Raw Permalink Blame History