873 lines
22 KiB
Markdown
873 lines
22 KiB
Markdown
# 快速入门指南
|
||
|
||
## 📋 文档概述
|
||
|
||
本文档为进贤麻将子游戏提供快速入门指南,帮助开发者:
|
||
- **快速理解** - 10分钟理解项目核心结构
|
||
- **快速定位** - 知道去哪里找需要的代码
|
||
- **快速上手** - 掌握常见开发任务的实现方法
|
||
- **快速解决** - 查找常见问题的解决方案
|
||
|
||
**文档目标**: 让新开发者能在**2小时内**理解项目结构并完成第一个功能修改。
|
||
|
||
---
|
||
|
||
## 🚀 10分钟快速理解
|
||
|
||
### 核心概念速览
|
||
|
||
#### 1️⃣ 三文件架构 (最重要!)
|
||
|
||
```
|
||
mod.js → 模块入口,加载所有文件
|
||
export.js → 框架调用游戏的14个接口
|
||
import.js → 游戏调用框架的13个接口
|
||
```
|
||
|
||
**记住**:
|
||
- 框架要执行游戏逻辑 → 调用 `export` 接口
|
||
- 游戏要通知客户端 → 调用 `import` 接口
|
||
|
||
#### 2️⃣ 请求处理流程
|
||
|
||
```
|
||
客户端发送操作
|
||
↓
|
||
packet.js 路由到 mod.js
|
||
↓
|
||
RpcHandler 处理请求
|
||
↓
|
||
GameController 执行逻辑
|
||
↓
|
||
import 发送响应给客户端
|
||
```
|
||
|
||
#### 3️⃣ 核心目录结构
|
||
|
||
```javascript
|
||
games2/jinxianmahjong/
|
||
├── mod.js, export.js, import.js // 三文件架构
|
||
├── rpc/RpcHandler.js // 客户端请求处理(34个RPC方法)
|
||
├── game/
|
||
│ ├── GameController.js // 游戏流程控制(开始、发牌、结算)
|
||
│ ├── OperationManager.js // 操作管理(吃碰杠胡验证)
|
||
│ └── MahjongGameService.js // 胡牌检测和计分
|
||
├── shared/
|
||
│ ├── algorithms/ // 算法(精牌、胡牌检测、计分)
|
||
│ ├── dataStructures/ // 数据结构(牌对象、状态管理)
|
||
│ ├── config/ // 配置解析
|
||
│ └── constants/ // 常量定义(12个模块)
|
||
└── utils/ // 工具(Logger、ErrorHandler)
|
||
```
|
||
|
||
### 关键文件速查表
|
||
|
||
| 需求 | 去哪里找 | 核心文件 |
|
||
|------|---------|----------|
|
||
| **客户端请求如何处理?** | `rpc/` | RpcHandler.js |
|
||
| **游戏怎么开始的?** | `game/` | GameController.js |
|
||
| **怎么判断能否胡牌?** | `shared/algorithms/` | WinDetectionFactory.js |
|
||
| **精牌怎么计算的?** | `shared/algorithms/` | JingAlgorithm.js |
|
||
| **分数怎么算的?** | `shared/algorithms/` | ScoreCalculation.js |
|
||
| **游戏状态怎么管理?** | `shared/dataStructures/` | GameStateManager.js |
|
||
| **房间配置怎么解析?** | `shared/config/` | RoomConfigUtils.js |
|
||
| **如何发送消息给客户端?** | 根目录 | import.js |
|
||
| **框架如何调用游戏?** | 根目录 | export.js |
|
||
|
||
---
|
||
|
||
## 📖 学习路径
|
||
|
||
### 路径1: 新手入门 (推荐顺序)
|
||
|
||
```
|
||
第1步: 理解架构
|
||
↓
|
||
阅读 00-框架基础概述.md
|
||
理解三文件架构和RPC机制
|
||
预计时间: 30分钟
|
||
|
||
第2步: 理解接口
|
||
↓
|
||
阅读 01-Export接口说明.md
|
||
阅读 02-Import接口说明.md
|
||
理解框架与游戏的交互
|
||
预计时间: 30分钟
|
||
|
||
第3步: 理解流程
|
||
↓
|
||
阅读 08-游戏流程概述.md
|
||
理解游戏从开始到结束的完整流程
|
||
预计时间: 40分钟
|
||
|
||
第4步: 动手实践
|
||
↓
|
||
完成一个简单的功能修改
|
||
(例如: 添加日志、修改分数)
|
||
预计时间: 20分钟
|
||
```
|
||
|
||
**总计**: 2小时入门
|
||
|
||
### 路径2: 算法研究 (进阶开发者)
|
||
|
||
```
|
||
1. 阅读 05-共享代码模块.md (核心算法详解)
|
||
2. 研究 JingAlgorithm.js (精牌系统)
|
||
3. 研究 WinDetectionFactory.js (胡牌检测)
|
||
4. 研究 ScoreCalculation.js (计分系统)
|
||
```
|
||
|
||
### 路径3: 功能开发 (实战导向)
|
||
|
||
```
|
||
1. 阅读 03-RPC处理机制.md (理解请求处理)
|
||
2. 阅读 04-游戏核心服务.md (理解服务层)
|
||
3. 阅读 09-代码框架总结.md (理解架构设计)
|
||
4. 开始功能开发
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 常见开发任务
|
||
|
||
### 任务1: 添加新的RPC方法
|
||
|
||
**场景**: 需要处理客户端的新操作请求
|
||
|
||
**步骤**:
|
||
|
||
```javascript
|
||
// 1. 在 rpc/RpcHandler.js 中添加方法
|
||
RpcHandler.prototype.player_new_operation = function(pack, room, callback) {
|
||
var playerId = pack.playerid;
|
||
var data = pack.data;
|
||
|
||
// 验证操作
|
||
var validation = this._validateOperation(room.gameState, playerId, data);
|
||
if (!validation.valid) {
|
||
return callback({ error: validation.error });
|
||
}
|
||
|
||
// 执行操作
|
||
var result = this._performOperation(room.gameState, playerId, data);
|
||
|
||
// 广播消息
|
||
room.import.broadcast(room, {
|
||
type: 'new_operation',
|
||
playerId: playerId,
|
||
data: result
|
||
});
|
||
|
||
callback({ success: true, data: result });
|
||
};
|
||
|
||
// 2. 在 mod.js 中注册RPC方法
|
||
mod_jinxianmahjong.player_new_operation = function(pack) {
|
||
var room = this.getRoom(pack.roomcode);
|
||
return this.rpcHandler.player_new_operation(pack, room, function(result) {
|
||
return result;
|
||
});
|
||
};
|
||
```
|
||
|
||
**相关文档**: [03-RPC处理机制.md](../framework/03-RPC处理机制.md)
|
||
|
||
---
|
||
|
||
### 任务2: 修改计分规则
|
||
|
||
**场景**: 需要调整某种牌型的分数
|
||
|
||
**步骤**:
|
||
|
||
```javascript
|
||
// 在 shared/algorithms/ScoreCalculation.js 中修改
|
||
ScoreCalculation.calculateWinScore = function(winResult, gameState) {
|
||
var scores = {
|
||
baseScore: 0,
|
||
bonusScore: 0,
|
||
jingScore: 0,
|
||
totalScore: 0
|
||
};
|
||
|
||
// 修改牌型分数
|
||
var pattern = winResult.bestPattern;
|
||
switch (pattern.type) {
|
||
case 'pinghu':
|
||
scores.baseScore = pattern.hasJing ? 4 : 8;
|
||
break;
|
||
case 'qidui':
|
||
scores.baseScore = pattern.hasJing ? 8 : 64;
|
||
break;
|
||
case 'custom_pattern': // 新增牌型
|
||
scores.baseScore = 16;
|
||
break;
|
||
// ...
|
||
}
|
||
|
||
// 计算精分
|
||
scores.jingScore = JingAlgorithm.calculateJingScore(
|
||
gameState.players[winResult.winnerId].handCards,
|
||
gameState.jingInfo
|
||
);
|
||
|
||
// 总分
|
||
scores.totalScore = scores.baseScore + scores.bonusScore + scores.jingScore;
|
||
|
||
return scores;
|
||
};
|
||
```
|
||
|
||
**相关文档**: [05-共享代码模块.md](../core/05-共享代码模块.md#scorecalculation-计分系统)
|
||
|
||
---
|
||
|
||
### 任务3: 添加新的游戏规则
|
||
|
||
**场景**: 需要支持新的房间配置选项
|
||
|
||
**步骤**:
|
||
|
||
```javascript
|
||
// 1. 在 shared/config/RoomConfigUtils.js 中添加解析
|
||
RoomConfigUtils.parse = function(roomtype) {
|
||
// ...现有解析逻辑
|
||
|
||
// 新增规则位解析(假设使用第14位)
|
||
var enableNewRule = roomtype.charAt(13) === '1';
|
||
|
||
return {
|
||
// ...现有配置
|
||
specialRules: {
|
||
enableNewRule: enableNewRule, // 新规则
|
||
// ...其他规则
|
||
}
|
||
};
|
||
};
|
||
|
||
// 2. 在游戏逻辑中使用规则
|
||
// game/OperationManager.js
|
||
OperationManager.validateOperation = function(gameState, operation) {
|
||
// 检查新规则
|
||
if (gameState.rules.specialRules.enableNewRule) {
|
||
// 执行特殊验证逻辑
|
||
}
|
||
|
||
// ...其他验证
|
||
};
|
||
```
|
||
|
||
**相关文档**: [06-规则配置系统.md](../core/06-规则配置系统.md)
|
||
|
||
---
|
||
|
||
### 任务4: 添加日志和调试信息
|
||
|
||
**场景**: 需要追踪代码执行流程
|
||
|
||
**步骤**:
|
||
|
||
```javascript
|
||
var Logger = require('./utils/Logger.js');
|
||
|
||
// 在任何需要调试的地方添加日志
|
||
function someFunction(param) {
|
||
Logger.info('函数开始执行', { param: param });
|
||
|
||
try {
|
||
// 业务逻辑
|
||
Logger.debug('中间状态', { state: currentState });
|
||
|
||
// 更多逻辑
|
||
Logger.info('操作成功', { result: result });
|
||
|
||
return result;
|
||
} catch (error) {
|
||
Logger.error('操作失败', {
|
||
error: error.message,
|
||
stack: error.stack
|
||
});
|
||
throw error;
|
||
}
|
||
}
|
||
|
||
// 查看日志历史
|
||
var history = Logger.getHistory();
|
||
console.log('最近100条日志:', history.slice(-100));
|
||
|
||
// 查看日志统计
|
||
var stats = Logger.getStatistics();
|
||
console.log('错误数量:', stats.ERROR);
|
||
```
|
||
|
||
**相关文档**: [07-工具模块.md](07-工具模块.md#logger-日志管理器)
|
||
|
||
---
|
||
|
||
### 任务5: 添加新的牌型检测
|
||
|
||
**场景**: 需要支持新的胡牌牌型
|
||
|
||
**步骤**:
|
||
|
||
```javascript
|
||
// 在 shared/algorithms/WinDetectionFactory.js 中添加
|
||
WinDetectionFactory.detectWin = function(handTiles, jingInfo, gameState) {
|
||
var patterns = [];
|
||
|
||
// ...现有牌型检测
|
||
|
||
// 添加新牌型检测
|
||
var customPatternResult = this._checkCustomPattern(handTiles, jingInfo);
|
||
if (customPatternResult.canWin) {
|
||
patterns.push({
|
||
type: 'custom_pattern',
|
||
name: '自定义牌型',
|
||
hasJing: customPatternResult.hasJing,
|
||
baseScore: 32,
|
||
description: '特殊组合牌型',
|
||
combinations: customPatternResult.combinations
|
||
});
|
||
}
|
||
|
||
return {
|
||
canWin: patterns.length > 0,
|
||
patterns: patterns,
|
||
bestPattern: this._selectBestPattern(patterns)
|
||
};
|
||
};
|
||
|
||
// 实现检测逻辑
|
||
WinDetectionFactory._checkCustomPattern = function(handTiles, jingInfo) {
|
||
// 实现牌型检测算法
|
||
// 返回 { canWin: boolean, hasJing: boolean, combinations: [...] }
|
||
};
|
||
```
|
||
|
||
**相关文档**: [05-共享代码模块.md](../core/05-共享代码模块.md#windetectionfactory-胡牌检测工厂)
|
||
|
||
---
|
||
|
||
## 🔍 代码导航技巧
|
||
|
||
### 技巧1: 快速查找功能入口
|
||
|
||
```javascript
|
||
// 想知道某个操作是如何处理的?
|
||
// 1. 找到客户端发送的RPC方法名,例如: "player_discard"
|
||
// 2. 在 rpc/RpcHandler.js 中搜索该方法
|
||
// 3. 阅读该方法的实现
|
||
|
||
// 示例: 查找出牌操作
|
||
// → 搜索 "player_discard"
|
||
// → 找到 RpcHandler.prototype.player_discard
|
||
// → 理解处理流程
|
||
```
|
||
|
||
### 技巧2: 追踪数据流
|
||
|
||
```javascript
|
||
// 数据流追踪顺序:
|
||
// 1. 客户端发送 → packet.js
|
||
// 2. 路由到模块 → mod.js
|
||
// 3. RPC处理 → rpc/RpcHandler.js
|
||
// 4. 业务逻辑 → game/GameController.js 或其他服务
|
||
// 5. 状态更新 → shared/dataStructures/GameStateManager.js
|
||
// 6. 响应发送 → import.js → 客户端接收
|
||
```
|
||
|
||
### 技巧3: 查找算法实现
|
||
|
||
```javascript
|
||
// 想知道某个算法是如何实现的?
|
||
// 1. 确定算法类型(精牌/胡牌检测/计分等)
|
||
// 2. 到 shared/algorithms/ 目录查找
|
||
// 3. 查看对应的算法文件
|
||
|
||
// 示例算法文件:
|
||
// - JingAlgorithm.js → 精牌相关算法
|
||
// - WinDetectionFactory.js → 胡牌检测
|
||
// - ScoreCalculation.js → 计分计算
|
||
// - PatternFactory.js → 牌型分析
|
||
```
|
||
|
||
### 技巧4: 理解配置选项
|
||
|
||
```javascript
|
||
// 想知道某个规则位的含义?
|
||
// 1. 打开 shared/config/RoomConfigUtils.js
|
||
// 2. 查看 parse() 方法
|
||
// 3. 找到对应位的解析代码
|
||
|
||
// 或者查看 shared/constants/RoomConstants.js
|
||
// 查看所有规则的定义和说明
|
||
```
|
||
|
||
---
|
||
|
||
## ❓ 常见问题解答 (FAQ)
|
||
|
||
### Q1: 如何查看游戏当前状态?
|
||
|
||
**A**: 游戏状态保存在 `room.gameState` 对象中
|
||
|
||
```javascript
|
||
// 在任何有 room 对象的地方
|
||
console.log('当前阶段:', room.gameState.phase);
|
||
console.log('当前玩家:', room.gameState.currentPlayer);
|
||
console.log('庄家:', room.gameState.dealer);
|
||
console.log('精牌信息:', room.gameState.jingInfo);
|
||
|
||
// 查看玩家手牌
|
||
var player = room.gameState.players[0];
|
||
console.log('玩家0手牌:', player.handCards);
|
||
console.log('玩家0分数:', player.score);
|
||
```
|
||
|
||
**相关文档**: [04-游戏核心服务.md](../core/04-游戏核心服务.md#gamestate-游戏状态对象)
|
||
|
||
---
|
||
|
||
### Q2: 如何判断一个操作是否合法?
|
||
|
||
**A**: 使用 `OperationManager` 进行验证
|
||
|
||
```javascript
|
||
var OperationManager = require('./game/OperationManager.js');
|
||
|
||
// 验证出牌操作
|
||
var validation = OperationManager.validateDiscard(
|
||
gameState,
|
||
playerId,
|
||
tileCode
|
||
);
|
||
|
||
if (!validation.valid) {
|
||
console.error('操作不合法:', validation.error);
|
||
return { error: validation.error };
|
||
}
|
||
|
||
// 验证吃牌操作
|
||
var validation = OperationManager.validateChow(
|
||
gameState,
|
||
playerId,
|
||
tiles
|
||
);
|
||
```
|
||
|
||
**相关文档**: [04-游戏核心服务.md](../core/04-游戏核心服务.md#operationmanager-操作管理器)
|
||
|
||
---
|
||
|
||
### Q3: 精牌系统是如何工作的?
|
||
|
||
**A**: 精牌系统由 `JingAlgorithm.js` 实现
|
||
|
||
```javascript
|
||
var JingAlgorithm = require('./shared/algorithms/JingAlgorithm.js');
|
||
|
||
// 1. 确定精牌
|
||
var jingInfo = JingAlgorithm.determineJingCards(
|
||
flippedCard, // 翻开的牌
|
||
diceResult // 骰子结果
|
||
);
|
||
// 返回: { zhengJing: '5m', fuJing: '6m' }
|
||
|
||
// 2. 计算精分
|
||
var jingScore = JingAlgorithm.calculateJingScore(
|
||
handCards,
|
||
jingInfo
|
||
);
|
||
|
||
// 3. 检查是否比精
|
||
var biJingResult = JingAlgorithm.checkBiJing(
|
||
winnerCards,
|
||
loserCards,
|
||
jingInfo
|
||
);
|
||
```
|
||
|
||
**相关文档**: [05-共享代码模块.md](../core/05-共享代码模块.md#jingalgorithm-精牌算法)
|
||
|
||
---
|
||
|
||
### Q4: 如何发送消息给客户端?
|
||
|
||
**A**: 使用 `import` 接口
|
||
|
||
```javascript
|
||
// 1. 发送给单个玩家
|
||
room.import.sendToPlayer(playerId, {
|
||
cmd: 'game_update',
|
||
data: { /* ... */ }
|
||
});
|
||
|
||
// 2. 广播给所有玩家
|
||
room.import.broadcast(room, {
|
||
cmd: 'player_operation',
|
||
data: { /* ... */ }
|
||
});
|
||
|
||
// 3. 广播给除某玩家外的其他玩家
|
||
room.import.broadcastExcept(room, excludePlayerId, {
|
||
cmd: 'player_discard',
|
||
data: { /* ... */ }
|
||
});
|
||
```
|
||
|
||
**相关文档**: [02-Import接口说明.md](../framework/02-Import接口说明.md)
|
||
|
||
---
|
||
|
||
### Q5: gameState 和 room 有什么区别?
|
||
|
||
**A**:
|
||
- **room**: 框架层的房间对象,包含玩家列表、房间配置等
|
||
- **gameState**: 游戏层的状态对象,包含游戏逻辑相关的数据
|
||
|
||
```javascript
|
||
// room 对象(框架层)
|
||
room.roomcode // 房间号
|
||
room.roomtype // 房间配置
|
||
room.players // 玩家列表(框架格式)
|
||
|
||
// gameState 对象(游戏层)
|
||
room.gameState.phase // 游戏阶段
|
||
room.gameState.players // 玩家状态(游戏格式)
|
||
room.gameState.jingInfo // 精牌信息
|
||
room.gameState.currentPlayer // 当前玩家
|
||
|
||
// gameState 保存在 room 对象中
|
||
// 通过 room.gameState 访问
|
||
```
|
||
|
||
---
|
||
|
||
### Q6: 如何添加错误处理?
|
||
|
||
**A**: 使用 `ErrorHandler` 统一处理
|
||
|
||
```javascript
|
||
var ErrorHandler = require('./utils/ErrorHandler.js');
|
||
|
||
try {
|
||
// 可能出错的代码
|
||
someRiskyOperation();
|
||
} catch (error) {
|
||
// 记录错误
|
||
ErrorHandler.handle(error, {
|
||
context: 'someRiskyOperation',
|
||
severity: 'high',
|
||
playerId: playerId,
|
||
roomcode: roomcode
|
||
});
|
||
|
||
// 返回错误信息
|
||
return {
|
||
success: false,
|
||
error: 'OPERATION_FAILED',
|
||
message: error.message
|
||
};
|
||
}
|
||
|
||
// 查看错误统计
|
||
var stats = ErrorHandler.getStatistics();
|
||
console.log('错误分类统计:', stats.byCategory);
|
||
```
|
||
|
||
**相关文档**: [07-工具模块.md](07-工具模块.md#errorhandler-错误处理器)
|
||
|
||
---
|
||
|
||
### Q7: 如何理解游戏阶段(phase)?
|
||
|
||
**A**: 游戏有7个主要阶段
|
||
|
||
```javascript
|
||
// 游戏阶段常量
|
||
GAME_PHASES = {
|
||
WAITING: 'waiting', // 等待玩家准备
|
||
DEALING: 'dealing', // 发牌阶段
|
||
JING_DETERMINING: 'jing_determining', // 确定精牌
|
||
PLAYING: 'playing', // 游戏进行中
|
||
RESPONDING: 'responding', // 等待玩家响应
|
||
ROUND_END: 'round_end', // 单局结束
|
||
GAME_END: 'game_end' // 游戏结束
|
||
};
|
||
|
||
// 状态转换示例
|
||
// WAITING → DEALING → JING_DETERMINING → PLAYING → ROUND_END
|
||
```
|
||
|
||
**相关文档**: [08-游戏流程概述.md](../architecture/08-游戏流程概述.md#游戏状态机)
|
||
|
||
---
|
||
|
||
### Q8: 如何修改房间配置解析?
|
||
|
||
**A**: 修改 `RoomConfigUtils.parse()` 方法
|
||
|
||
```javascript
|
||
// shared/config/RoomConfigUtils.js
|
||
RoomConfigUtils.parse = function(roomtype) {
|
||
// roomtype 是13位字符串,例如: "1311111110000"
|
||
|
||
// 解析各位配置
|
||
var config = {
|
||
roundCount: this._parseRoundCount(roomtype[0]),
|
||
useJing: roomtype[1] === '1',
|
||
allowChiPengGang: roomtype[2] === '1',
|
||
// ...更多配置
|
||
};
|
||
|
||
return config;
|
||
};
|
||
```
|
||
|
||
**相关文档**: [06-规则配置系统.md](../core/06-规则配置系统.md)
|
||
|
||
---
|
||
|
||
### Q9: 如何追踪某个牌的来源?
|
||
|
||
**A**: 使用 `MahjongCard` 的 `sourceInfo` 属性
|
||
|
||
```javascript
|
||
// 每张牌都有来源信息
|
||
var card = {
|
||
code: '3m',
|
||
uniqueId: 'card_1234567890',
|
||
sourceInfo: {
|
||
sourceType: 'dealt', // dealt/drawn/discarded等
|
||
playerId: 'player1',
|
||
timestamp: 1234567890,
|
||
round: 1
|
||
}
|
||
};
|
||
|
||
// 检查牌的来源
|
||
if (card.sourceInfo.sourceType === 'dealt') {
|
||
console.log('这张牌是发牌时获得的');
|
||
} else if (card.sourceInfo.sourceType === 'drawn') {
|
||
console.log('这张牌是摸牌时获得的');
|
||
}
|
||
```
|
||
|
||
**相关文档**: [05-共享代码模块.md](../core/05-共享代码模块.md#mahjongcard-麻将牌对象)
|
||
|
||
---
|
||
|
||
### Q10: 如何查看所有可用的常量?
|
||
|
||
**A**: 查看 `shared/constants/index.js`
|
||
|
||
```javascript
|
||
var Constants = require('./shared/constants/index.js');
|
||
|
||
// 12个常量模块
|
||
console.log(Constants.GameConstants); // 游戏常量
|
||
console.log(Constants.OperationTypes); // 操作类型
|
||
console.log(Constants.ErrorMessages); // 错误消息
|
||
console.log(Constants.RoomConstants); // 房间常量
|
||
console.log(Constants.ScoreConstants); // 分数常量
|
||
console.log(Constants.TimeoutConstants); // 超时常量
|
||
// ... 更多常量模块
|
||
|
||
// 使用常量
|
||
var GAME_PHASES = Constants.GameConstants.GAME_PHASES;
|
||
var ERROR_INVALID_OPERATION = Constants.ErrorMessages.INVALID_OPERATION;
|
||
```
|
||
|
||
**相关文档**: [06-规则配置系统.md](../core/06-规则配置系统.md#常量系统)
|
||
|
||
---
|
||
|
||
## 📚 进阶学习资源
|
||
|
||
### 完整文档列表
|
||
|
||
#### 框架基础
|
||
1. [00-框架基础概述.md](../framework/00-框架基础概述.md) - 友乐平台架构和ES5规范
|
||
2. [01-Export接口说明.md](../framework/01-Export接口说明.md) - 框架调用游戏的14个接口
|
||
3. [02-Import接口说明.md](../framework/02-Import接口说明.md) - 游戏调用框架的13个接口
|
||
4. [03-RPC处理机制.md](../framework/03-RPC处理机制.md) - 客户端请求处理流程
|
||
|
||
#### 核心服务
|
||
5. [04-游戏核心服务.md](../core/04-游戏核心服务.md) - GameController等5大核心服务
|
||
6. [05-共享代码模块.md](../core/05-共享代码模块.md) - 精牌算法等核心算法详解
|
||
7. [06-规则配置系统.md](../core/06-规则配置系统.md) - 房间配置和规则解析
|
||
|
||
#### 架构设计
|
||
8. [08-游戏流程概述.md](../architecture/08-游戏流程概述.md) - 完整游戏流程和状态机
|
||
9. [09-代码框架总结.md](../architecture/09-代码框架总结.md) - 架构设计和设计模式
|
||
|
||
#### 开发工具
|
||
10. [07-工具模块.md](07-工具模块.md) - Logger和ErrorHandler使用指南
|
||
|
||
### 外部参考资料
|
||
|
||
- `docs/important/game/进贤麻将规则手册.md` - 完整游戏规则
|
||
- `docs/important/game/进贤麻将技术设计要点.md` - 技术设计细节
|
||
- `docs/important/server/服务器子游戏开发要求.md` - 开发规范
|
||
- `docs/analysis/JingAlgorithm核心算法分析.md` - 精牌算法深度分析
|
||
|
||
---
|
||
|
||
## 🎯 学习检查清单
|
||
|
||
完成以下检查项,确保你已经掌握了基础知识:
|
||
|
||
### 基础理解 ✅
|
||
- [ ] 理解三文件架构(mod.js/export.js/import.js)
|
||
- [ ] 知道RPC请求的处理流程
|
||
- [ ] 了解游戏的7个阶段
|
||
- [ ] 知道gameState对象的结构
|
||
- [ ] 理解精牌系统的基本概念
|
||
|
||
### 代码定位 ✅
|
||
- [ ] 能快速找到RPC方法的实现位置
|
||
- [ ] 知道算法文件在哪个目录
|
||
- [ ] 知道如何查看游戏配置的解析
|
||
- [ ] 能找到日志和错误处理的工具类
|
||
|
||
### 实践能力 ✅
|
||
- [ ] 能添加一条日志语句
|
||
- [ ] 能修改一个计分规则
|
||
- [ ] 能添加一个简单的RPC方法
|
||
- [ ] 能查看和理解gameState的内容
|
||
|
||
### 问题解决 ✅
|
||
- [ ] 遇到错误知道如何查看日志
|
||
- [ ] 知道如何验证操作是否合法
|
||
- [ ] 知道如何发送消息给客户端
|
||
- [ ] 知道去哪里查找算法实现
|
||
|
||
---
|
||
|
||
## 💪 实战练习
|
||
|
||
### 练习1: 添加一条日志 (难度: ⭐)
|
||
|
||
**任务**: 在玩家出牌时添加日志记录
|
||
|
||
```javascript
|
||
// 在 rpc/RpcHandler.js 的 player_discard 方法中
|
||
RpcHandler.prototype.player_discard = function(pack, room, callback) {
|
||
var Logger = require('../utils/Logger.js');
|
||
|
||
// 添加这行日志
|
||
Logger.info('玩家出牌', {
|
||
playerId: pack.playerid,
|
||
tile: pack.data.tile,
|
||
roomcode: room.roomcode
|
||
});
|
||
|
||
// ...原有代码
|
||
};
|
||
```
|
||
|
||
### 练习2: 修改七对分数 (难度: ⭐⭐)
|
||
|
||
**任务**: 将有精七对的分数从8分改为10分
|
||
|
||
```javascript
|
||
// 在 shared/algorithms/ScoreCalculation.js 中找到
|
||
case 'qidui':
|
||
scores.baseScore = pattern.hasJing ? 8 : 64; // 原来
|
||
|
||
// 修改为
|
||
case 'qidui':
|
||
scores.baseScore = pattern.hasJing ? 10 : 64; // 修改后
|
||
```
|
||
|
||
### 练习3: 添加操作验证 (难度: ⭐⭐⭐)
|
||
|
||
**任务**: 添加一个验证,禁止玩家在特定情况下出某张牌
|
||
|
||
```javascript
|
||
// 在 game/OperationManager.js 中
|
||
OperationManager.validateDiscard = function(gameState, playerId, tileCode) {
|
||
// 原有验证...
|
||
|
||
// 添加自定义验证
|
||
if (gameState.rules.specialRules.forbidSpecialCard) {
|
||
if (tileCode === '1m') { // 禁止出1万
|
||
return {
|
||
valid: false,
|
||
error: 'FORBIDDEN_CARD',
|
||
message: '当前规则禁止出这张牌'
|
||
};
|
||
}
|
||
}
|
||
|
||
return { valid: true };
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 快速链接
|
||
|
||
### 核心文件直达
|
||
- [mod.js](../../games2/jinxianmahjong/mod.js) - 模块入口
|
||
- [export.js](../../games2/jinxianmahjong/export.js) - Export接口
|
||
- [import.js](../../games2/jinxianmahjong/import.js) - Import接口
|
||
- [RpcHandler.js](../../games2/jinxianmahjong/rpc/RpcHandler.js) - RPC处理器
|
||
- [GameController.js](../../games2/jinxianmahjong/game/GameController.js) - 游戏控制器
|
||
|
||
### 算法文件直达
|
||
- [JingAlgorithm.js](../../games2/jinxianmahjong/shared/algorithms/JingAlgorithm.js) - 精牌算法
|
||
- [WinDetectionFactory.js](../../games2/jinxianmahjong/shared/algorithms/WinDetectionFactory.js) - 胡牌检测
|
||
- [ScoreCalculation.js](../../games2/jinxianmahjong/shared/algorithms/ScoreCalculation.js) - 计分系统
|
||
|
||
### 工具文件直达
|
||
- [Logger.js](../../games2/jinxianmahjong/utils/Logger.js) - 日志工具
|
||
- [ErrorHandler.js](../../games2/jinxianmahjong/utils/ErrorHandler.js) - 错误处理
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
### 遇到问题时的步骤
|
||
|
||
1. **查看日志**: 检查Logger输出,了解程序执行流程
|
||
2. **查看文档**: 在对应的文档中查找相关说明
|
||
3. **搜索代码**: 在项目中搜索相关关键词
|
||
4. **查看示例**: 参考其他类似功能的实现
|
||
5. **调试代码**: 添加日志语句追踪执行流程
|
||
|
||
### 文档导航
|
||
|
||
- **概念不清楚** → 查看框架基础文档(00-03)
|
||
- **不知道怎么实现** → 查看核心服务文档(04-06)
|
||
- **不理解流程** → 查看游戏流程文档(08)
|
||
- **想了解设计** → 查看架构总结文档(09)
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2025年10月15日
|
||
**维护者**: 进贤麻将开发团队
|
||
|
||
---
|
||
|
||
## 🎉 开始你的开发之旅!
|
||
|
||
现在你已经掌握了快速入门的所有知识,可以开始实际开发了!
|
||
|
||
**建议的第一步**:
|
||
1. 选择一个感兴趣的功能
|
||
2. 找到对应的代码位置
|
||
3. 添加一些日志了解执行流程
|
||
4. 尝试做一个小修改
|
||
5. 测试验证你的修改
|
||
|
||
**记住**:
|
||
- 📖 遇到问题先查文档
|
||
- 🔍 善用搜索找代码
|
||
- 📝 多写日志帮助理解
|
||
- 🧪 改完代码记得测试
|
||
|
||
祝你开发愉快! 🚀
|