ygopro-msg-encode 1.0.2 → 1.0.3

package/ENUM_FIX_SUMMARY.md

@@ -0,0 +1,84 @@
+# GameRule 枚举修正总结
+
+## 问题
+
+之前错误地为 `HostInfo.rule` 字段创建了 `GameRule` 枚举，但实际上：
+
+1. **`rule` 字段是 UI 下拉列表的索引**（0-5），不是实际的 OT 值
+2. **实际的 OT 值**（1=OCG, 2=TCG, 4=OCG+TCG, 8=Traditional）是从 UI 索引映射过来的
+3. **在协议中传输的是索引值**，而不是 OT 值本身
+
+## 修正
+
+### 1. 删除了 `GameRule` 枚举 ✅
+
+从 `src/protos/network-enums.ts` 中删除：
+```typescript
+// 已删除
+export enum GameRule {
+  OCG_ONLY = 1,
+  TCG_ONLY = 2,
+  OCG_TCG = 4,
+  TRADITIONAL = 8,
+}
+```
+
+### 2. 将 `HostInfo.rule` 改回 `number` ✅
+
+```typescript
+export class HostInfo {
+  @BinaryField('u32', 0)
+  lflist: number;
+
+  @BinaryField('u8', 4)
+  rule: number; // Rule index (0-5), maps to OT values in UI
+
+  @BinaryField('u8', 5)
+  mode: GameMode;
+  
+  // ...
+}
+```
+
+### 3. 更新了文档 ✅
+
+- `README.md` - 移除了 `GameRule` 的引用
+- `ENUM_UPDATE.md` - 添加了 `HostInfo.rule` 保持为 `number` 的说明
+
+## UI 索引到 OT 值的映射（参考）
+
+从 `gframe/game.cpp` 中可以看到映射关系：
+
+| UI 索引 | OT 值 | 说明 |
+|---------|-------|------|
+| 0 | 1 | OCG Only (String 1483) |
+| 1 | 2 | TCG Only (String 1484) |
+| 2 | 8 | Traditional (String 1485) |
+| 3 | 4 | OCG + TCG (String 1486) |
+| 4+ | ? | 其他规则 |
+
+**注意**：协议中传输的是索引（0-5），不是 OT 值（1, 2, 4, 8）。
+
+## 保留的枚举
+
+以下枚举保持不变：
+
+1. `HandResult` - 猜拳结果
+2. `TurnPlayerResult` - 先后手选择
+3. `NetPlayerType` - 玩家类型/位置
+4. `GameMode` - 游戏模式
+5. `ErrorMessageType` - 错误消息类型
+6. `DeckErrorType` - 卡组错误类型
+7. `PlayerChangeState` - 玩家状态变化
+8. `RoomStatus` - 房间状态
+
+## 使用示例
+
+```typescript
+import { YGOProCtosCreateGame, GameMode } from 'ygopro-msg-encode';
+
+const createGame = new YGOProCtosCreateGame();
+createGame.info.mode = GameMode.MATCH;
+createGame.info.rule = 0; // UI 索引 0 (会映射到 OT=1, OCG Only)
+createGame.info.duel_rule = 5; // MASTER_RULE_2020
+```

package/ENUM_UPDATE.md

@@ -0,0 +1,219 @@
+# 枚举类型更新总结
+
+本文档记录了将网络协议中的数字字段改为 TypeScript 枚举的更新。
+
+## 更新原则
+
+1. **仅更新网络协议相关的枚举**：CTOS 和 STOC 协议中的语义字段
+2. **不修改已有常量**：MSG 协议中的字段（如 `phase`、`position`、`location`、`reason`）已在 `OcgcoreCommonConstants` 中定义，保持使用常量
+3. **使用 TypeScript enum**：提供类型安全和更好的 IDE 支持
+
+## 新增枚举类型
+
+所有枚举定义在 `src/protos/network-enums.ts`：
+
+### 1. HandResult - 猜拳结果
+```typescript
+enum HandResult {
+  ROCK = 1,
+  SCISSORS = 2,
+  PAPER = 3,
+}
+```
+**使用位置**：`CTOS_HandResult.res`
+
+### 2. TurnPlayerResult - 先后手选择
+```typescript
+enum TurnPlayerResult {
+  SECOND = 0,
+  FIRST = 1,
+}
+```
+**使用位置**：`CTOS_TPResult.res`
+
+### 3. NetPlayerType - 玩家类型/位置
+```typescript
+enum NetPlayerType {
+  PLAYER1 = 0,
+  PLAYER2 = 1,
+  PLAYER3 = 2,
+  PLAYER4 = 3,
+  PLAYER5 = 4,
+  PLAYER6 = 5,
+  OBSERVER = 7,
+}
+```
+**使用位置**：
+- `CTOS_Kick.pos`
+
+### 4. ChatColor - 聊天消息颜色
+```typescript
+enum ChatColor {
+  LIGHTBLUE = 8,
+  RED = 11,
+  GREEN = 12,
+  BLUE = 13,
+  BABYBLUE = 14,
+  PINK = 15,
+  YELLOW = 16,
+  WHITE = 17,
+  GRAY = 18,
+  DARKGRAY = 19,
+}
+```
+**说明**：用于 `STOC_Chat.player_type` 字段，但该字段保持为 `number` 类型，因为它可以是玩家类型（0-7）或聊天颜色（8-19）
+
+### 5. GameMode - 游戏模式
+```typescript
+enum GameMode {
+  SINGLE = 0,
+  MATCH = 1,
+  TAG = 2,
+}
+```
+**使用位置**：`HostInfo.mode`
+
+### 6. ErrorMessageType - 错误消息类型
+```typescript
+enum ErrorMessageType {
+  JOINERROR = 1,
+  DECKERROR = 2,
+  SIDEERROR = 3,
+  VERERROR = 4,
+}
+```
+**使用位置**：`STOC_ErrorMsg.msg`
+
+### 7. DeckErrorType - 卡组错误类型
+```typescript
+enum DeckErrorType {
+  LFLIST = 1,
+  OCGONLY = 2,
+  TCGONLY = 3,
+  UNKNOWNCARD = 4,
+  CARDCOUNT = 5,
+  MAINCOUNT = 6,
+  EXTRACOUNT = 7,
+  SIDECOUNT = 8,
+  NOTAVAIL = 9,
+}
+```
+**说明**：用于解析 `STOC_ErrorMsg.code` 的高 4 位（当 `msg == DECKERROR` 时）
+
+### 8. PlayerChangeState - 玩家状态变化
+```typescript
+enum PlayerChangeState {
+  OBSERVE = 8,
+  READY = 9,
+  NOTREADY = 10,
+  LEAVE = 11,
+}
+```
+**说明**：用于解析 `STOC_HS_PlayerChange.status` 的低 4 位
+
+### 9. RoomStatus - 房间状态（SRVPro）
+```typescript
+enum RoomStatus {
+  WAITING = 0,
+  DUELING = 1,
+  SIDING = 2,
+}
+```
+**使用位置**：`STOC_SRVPRO_ROOMLIST.room_status`
+
+## 已更新的文件
+
+### CTOS 协议
+1. `src/protos/ctos/proto/hand-result.ts` - `res: HandResult`
+2. `src/protos/ctos/proto/tp-result.ts` - `res: TurnPlayerResult`
+3. `src/protos/ctos/proto/kick.ts` - `pos: NetPlayerType`
+
+### STOC 协议
+1. `src/protos/stoc/proto/error-msg.ts` - `msg: ErrorMessageType`
+2. `src/protos/stoc/proto/chat.ts` - `player_type: number` (可以是 NetPlayerType 0-7 或 ChatColor 8-19)
+3. `src/protos/stoc/proto/srvpro-roomlist.ts` - `room_status: RoomStatus`
+
+### 公共结构
+1. `src/protos/common/host-info.ts` - `mode: GameMode`
+
+**注意**：`HostInfo.rule` 保持为 `number` 类型，因为它是UI下拉列表的索引（0-5），而不是实际的OT值。
+
+### 主入口
+1. `index.ts` - 导出所有枚举类型
+
+## 未更改的字段
+
+以下字段已在 `OcgcoreCommonConstants` 中有常量定义，因此**不改为枚举**：
+
+### MSG 协议字段
+- `MSG_HINT.type` - 使用 `HINT_*` 常量
+- `MSG_CARD_HINT.type` - 使用 `HINT_*` 常量
+- `MSG_PLAYER_HINT.type` - 使用 `PHINT_*` 常量
+- `MSG_NEW_PHASE.phase` - 使用 `PHASE_*` 常量
+- `MSG_MOVE.reason` - 使用 `REASON_*` 常量
+- `MSG_POS_CHANGE.position` - 使用 `POS_*` 常量
+- `MSG_SELECT_POSITION.positions` - 使用 `POS_*` 常量
+- 所有包含 `location` 的字段 - 使用 `LOCATION_*` 常量（注：部分基础常量可能在 vendor 生成脚本中缺失）
+
+### HostInfo 字段
+- `HostInfo.duel_rule` - 使用 `MASTER_RULE3`, `NEW_MASTER_RULE`, `MASTER_RULE_2020` 等常量
+
+## 使用示例
+
+```typescript
+import { 
+  YGOProCtosHandResult, 
+  HandResult,
+  YGOProCtosCreateGame,
+  GameMode,
+  NetPlayerType,
+  YGOProCtosKick,
+} from 'ygopro-msg-encode';
+
+// 创建猜拳消息
+const handResult = new YGOProCtosHandResult();
+handResult.res = HandResult.ROCK;
+
+// 创建游戏
+const createGame = new YGOProCtosCreateGame();
+createGame.info.mode = GameMode.MATCH;
+createGame.info.rule = 0; // Rule index (0-5), maps to OT values in UI
+createGame.info.duel_rule = 5; // MASTER_RULE_2020 (from OcgcoreCommonConstants)
+
+// 踢出玩家
+const kick = new YGOProCtosKick();
+kick.pos = NetPlayerType.PLAYER2;
+```
+
+## 向后兼容性
+
+由于 TypeScript enum 在运行时就是 `number`，这些改动是**完全向后兼容**的：
+
+```typescript
+// 旧代码仍然可以工作
+handResult.res = 1; // OK
+
+// 但现在有类型检查和 IDE 自动补全
+handResult.res = HandResult.ROCK; // Better!
+handResult.res = 99; // TypeScript 会警告（如果启用严格模式）
+```
+
+## 类型安全改进
+
+```typescript
+// 之前：没有类型检查
+function handleHandResult(res: number) {
+  if (res === 1) { /* ... */ }
+}
+
+// 现在：类型安全
+function handleHandResult(res: HandResult) {
+  if (res === HandResult.ROCK) { /* ... */ }
+}
+
+// IDE 会提供自动补全和类型检查
+```
+
+## 测试
+
+所有现有测试均通过，枚举更改不影响二进制序列化/反序列化逻辑。

package/README.md

@@ -517,6 +517,34 @@ npm run clean
 - [Quick Reference](./QUICK_REFERENCE.md) - Quick API reference
 - [Tests Migration](./TESTS_MIGRATION.md) - Testing guide
 
+## Network Protocol Enums
+
+This library provides TypeScript enums for network protocol fields with semantic meaning:
+
+```typescript
+import { 
+  HandResult,           // Rock-paper-scissors result
+  TurnPlayerResult,     // First/second turn selection
+  NetPlayerType,        // Player position/type
+  ChatColor,            // Chat message colors
+  GameMode,             // Single/Match/Tag
+  ErrorMessageType,     // Error message types
+  RoomStatus,           // Room status (SRVPro)
+} from 'ygopro-msg-encode';
+
+// Example: Create a game with specific settings
+const createGame = new YGOProCtosCreateGame();
+createGame.info.mode = GameMode.MATCH;
+createGame.info.rule = 0; // Rule index (0-5), maps to OT values in UI
+
+// Example: Chat with color
+const chat = new YGOProStocChat();
+chat.player_type = ChatColor.RED; // Use color for system message
+chat.msg = "Welcome to the game!";
+```
+
+**Note**: MSG protocol fields (like `phase`, `position`, `location`, `reason`) use constants from `OcgcoreCommonConstants` instead of enums, as they are automatically generated from YGOPro's `common.h`.
+
 ## Dependencies
 
 - **Runtime Dependencies**:

package/STOC_CHAT_FIX.md

@@ -0,0 +1,156 @@
+# STOC_CHAT player_type 修正总结
+
+## 问题
+
+`STOC_Chat.player_type` 字段之前被定义为 `NetPlayerType` 枚举，但实际上该字段可以包含两种不同类型的值：
+
+1. **玩家类型**（0-7）：PLAYER1-6, OBSERVER
+2. **聊天颜色**（8-19）：用于系统消息或特殊格式的聊天
+
+## 修正
+
+### 1. 添加 ChatColor 枚举 ✅
+
+在 `src/protos/network-enums.ts` 中添加：
+
+```typescript
+/**
+ * Chat message colors (used in STOC_Chat.player_type)
+ */
+export enum ChatColor {
+  LIGHTBLUE = 8,
+  RED = 11,
+  GREEN = 12,
+  BLUE = 13,
+  BABYBLUE = 14,
+  PINK = 15,
+  YELLOW = 16,
+  WHITE = 17,
+  GRAY = 18,
+  DARKGRAY = 19,
+}
+```
+
+**来源**：`/home/nanahira/ygo/srvpro/data/constants.json` 中的 `COLORS` 定义
+
+### 2. 将 player_type 改回 number ✅
+
+```typescript
+export class YGOProStocChat extends YGOProStocBase {
+  static identifier = 0x19;
+
+  player_type: number; // NetPlayerType (0-7) or ChatColor (8-19)
+  msg: string;
+  
+  // ...
+}
+```
+
+**原因**：该字段可以是玩家类型或聊天颜色，使用联合类型更合适。
+
+### 3. 更新了文档 ✅
+
+- `README.md` - 添加了 `ChatColor` 的使用示例
+- `ENUM_UPDATE.md` - 说明了 `player_type` 保持为 `number` 的原因
+
+## 使用场景
+
+### 场景 1：玩家发送的聊天消息
+
+```typescript
+import { YGOProStocChat, NetPlayerType } from 'ygopro-msg-encode';
+
+const chat = new YGOProStocChat();
+chat.player_type = NetPlayerType.PLAYER1; // 或直接使用 0
+chat.msg = "Good game!";
+```
+
+在这种情况下，`player_type` 表示发送消息的玩家位置。
+
+### 场景 2：系统消息或特殊颜色
+
+```typescript
+import { YGOProStocChat, ChatColor } from 'ygopro-msg-encode';
+
+const chat = new YGOProStocChat();
+chat.player_type = ChatColor.RED; // 红色系统消息
+chat.msg = "Game will start in 10 seconds!";
+```
+
+在这种情况下，`player_type` 表示聊天消息的颜色。
+
+## duelclient.cpp 中的处理逻辑
+
+从源码可以看到：
+
+```cpp
+uint16_t chat_player_type = BufferIO::Read<uint16_t>(pdata);
+// ...
+int player = chat_player_type;
+auto play_sound = false;
+if(player < 4) {  // 玩家消息（0-3）
+    auto localplayer = mainGame->ChatLocalPlayer(player);
+    player = localplayer & 0xf;
+    if(!(localplayer & 0x10))
+        play_sound = true;
+    if(play_sound && mainGame->chkIgnore1->isChecked())
+        break;
+} else {  // 系统消息或特殊颜色（>= 4）
+    if(player == 8) { //system custom message.
+        // ...
+    }
+}
+```
+
+客户端根据 `player_type` 的值：
+- **< 4**：当作玩家消息处理
+- **>= 4**：当作系统消息或特殊格式处理（可能包含颜色信息）
+
+## 颜色值映射（参考）
+
+| 值 | 常量名 | 说明 |
+|----|--------|------|
+| 8 | LIGHTBLUE | 浅蓝色 |
+| 11 | RED | 红色 |
+| 12 | GREEN | 绿色 |
+| 13 | BLUE | 蓝色 |
+| 14 | BABYBLUE | 婴儿蓝 |
+| 15 | PINK | 粉色 |
+| 16 | YELLOW | 黄色 |
+| 17 | WHITE | 白色 |
+| 18 | GRAY | 灰色 |
+| 19 | DARKGRAY | 深灰色 |
+
+## 类型安全建议
+
+虽然 `player_type` 是 `number` 类型，但可以使用类型守卫来确保类型安全：
+
+```typescript
+function isPlayerType(value: number): value is NetPlayerType {
+  return value >= 0 && value <= 7 && value !== 6;
+}
+
+function isChatColor(value: number): value is ChatColor {
+  return value >= 8 && value <= 19;
+}
+
+// 使用
+const chat = new YGOProStocChat();
+chat.fromFullPayload(data);
+
+if (isPlayerType(chat.player_type)) {
+  console.log('Player message from:', NetPlayerType[chat.player_type]);
+} else if (isChatColor(chat.player_type)) {
+  console.log('System message with color:', ChatColor[chat.player_type]);
+} else {
+  console.log('Unknown player_type:', chat.player_type);
+}
+```
+
+## 总结
+
+`STOC_Chat.player_type` 是一个多用途字段：
+- ✅ 保持为 `number` 类型以支持两种不同的语义
+- ✅ 提供 `NetPlayerType` 和 `ChatColor` 枚举供参考
+- ✅ 用户可以根据值的范围判断其含义
+- ✅ 完全向后兼容，不影响现有代码

package/UTF16_STRING_FIX.md

@@ -0,0 +1,190 @@
+# UTF-16 字符串字段修复总结
+
+## 问题
+
+多个网络协议中的字段被错误地定义为 `u16` 数组（`number[]`），但实际上它们应该是 UTF-16 字符串（`string`）。
+
+这些字段在源码 `network.h` 中都定义为 `uint16_t name[20]` 或 `uint16_t pass[20]`，表示 UTF-16 编码的字符串，而不是整数数组。
+
+## 修复的字段
+
+### 1. CTOS_PlayerInfo (`src/protos/ctos/proto/player-info.ts`)
+
+**修复前**:
+```typescript
+@BinaryField('u16', 0, 20)
+name: number[];
+```
+
+**修复后**:
+```typescript
+@BinaryField('utf16', 0, 20)
+name: string;
+```
+
+### 2. CTOS_JoinGame (`src/protos/ctos/proto/join-game.ts`)
+
+**修复前**:
+```typescript
+@BinaryField('u16', 8, 20)
+pass: number[];
+```
+
+**修复后**:
+```typescript
+@BinaryField('utf16', 8, 20)
+pass: string;
+```
+
+### 3. CTOS_CreateGame (`src/protos/ctos/proto/create-game.ts`)
+
+**修复前**:
+```typescript
+@BinaryField('u16', 20, 20)
+name: number[];
+
+@BinaryField('u16', 60, 20)
+pass: number[];
+```
+
+**修复后**:
+```typescript
+@BinaryField('utf16', 20, 20)
+name: string;
+
+@BinaryField('utf16', 60, 20)
+pass: string;
+```
+
+### 4. STOC_HS_PlayerEnter (`src/protos/stoc/proto/hs-player-enter.ts`)
+
+**修复前**:
+```typescript
+@BinaryField('u16', 0, 20)
+name: number[];
+```
+
+**修复后**:
+```typescript
+@BinaryField('utf16', 0, 20)
+name: string;
+```
+
+## 测试文件修复
+
+同时更新了 `tests/ctos-stoc.spec.ts` 中的相关测试：
+
+**修复前**:
+```typescript
+playerInfo.name = Array.from({ length: 20 }, (_, i) =>
+  i < 4 ? 0x0041 + i : 0,
+); // "ABCD"
+```
+
+**修复后**:
+```typescript
+playerInfo.name = 'ABCD';
+```
+
+## 源码参考
+
+根据 `gframe/network.h` 的定义：
+
+```cpp
+struct CTOS_PlayerInfo {
+    uint16_t name[20]{};  // UTF-16 string, 20 characters max
+};
+
+struct CTOS_CreateGame {
+    HostInfo info;
+    uint16_t name[20]{};  // UTF-16 string, 20 characters max
+    uint16_t pass[20]{};  // UTF-16 string, 20 characters max
+};
+
+struct CTOS_JoinGame {
+    uint16_t version{};
+    // byte padding[2]
+    uint32_t gameid{};
+    uint16_t pass[20]{};  // UTF-16 string, 20 characters max
+};
+
+struct STOC_HS_PlayerEnter {
+    uint16_t name[20]{};  // UTF-16 string, 20 characters max
+    uint8_t pos{};
+    // byte padding[1]
+};
+```
+
+所有这些 `uint16_t array[20]` 字段都是用于存储 UTF-16 编码的字符串，最多 20 个字符（包括 null 终止符）。
+
+## 使用示例
+
+### 修复前（错误）:
+```typescript
+const playerInfo = new YGOProCtosPlayerInfo();
+playerInfo.name = [0x0041, 0x0042, 0x0043, 0x0044, 0, 0, ...]; // "ABCD"
+```
+
+### 修复后（正确）:
+```typescript
+const playerInfo = new YGOProCtosPlayerInfo();
+playerInfo.name = 'ABCD'; // 直接使用字符串
+
+const createGame = new YGOProCtosCreateGame();
+createGame.name = 'MyGame';
+createGame.pass = 'password123';
+
+const joinGame = new YGOProCtosJoinGame();
+joinGame.version = 0x1353;
+joinGame.gameid = 12345;
+joinGame.pass = 'password123';
+```
+
+## 二进制格式
+
+UTF-16 字符串在二进制中的存储方式：
+- 每个字符占 2 字节（UTF-16LE 编码）
+- 字符串以 null 终止符（`\0`, `0x0000`）结尾
+- 固定长度字段会被 null 字符填充到指定长度
+
+例如，字符串 `"ABCD"` 在 20 字符的字段中：
+```
+41 00 42 00 43 00 44 00 00 00 00 00 ... (共 40 字节)
+ A     B     C     D    \0   \0   ...
+```
+
+## 向后兼容性
+
+这个修复是**破坏性变更**，因为字段类型从 `number[]` 改为了 `string`。
+
+**升级指南**：
+```typescript
+// 旧代码
+playerInfo.name = [0x0041, 0x0042, 0x0043, 0x0044, ...];
+
+// 新代码
+playerInfo.name = 'ABCD';
+
+// 如果需要从旧格式转换
+const oldName = [0x0041, 0x0042, 0x0043, 0x0044, 0, ...];
+const newName = String.fromCharCode(...oldName.filter(c => c !== 0));
+playerInfo.name = newName;
+```
+
+## 验证
+
+所有测试通过：
+- ✅ Binary serialization/deserialization tests
+- ✅ CTOS/STOC protocol tests
+- ✅ Round-trip encoding/decoding tests
+
+## 总结
+
+共修复了 **4 个文件** 中的 **5 个字段**：
+1. `CTOS_PlayerInfo.name` - 玩家名称
+2. `CTOS_JoinGame.pass` - 游戏密码
+3. `CTOS_CreateGame.name` - 游戏名称
+4. `CTOS_CreateGame.pass` - 游戏密码
+5. `STOC_HS_PlayerEnter.name` - 玩家名称
+
+所有字段都从 `@BinaryField('u16', ..., 20)` + `number[]` 改为 `@BinaryField('utf16', ..., 20)` + `string`。