ygopro-msg-encode 1.0.2 → 1.0.4

package/COMPOSITE_FIELDS_AUDIT.md

@@ -0,0 +1,275 @@
+# 复合字段审计报告
+
+本文档记录了对所有 CTOS、STOC、MSG 协议的复合字段（使用位运算的字段）审计结果。
+
+## 审计范围
+
+- **CTOS 协议**: 19 个
+- **STOC 协议**: 24 个
+- **MSG 协议**: 100+ 个
+
+## 审计方法
+
+1. 检查 `/home/nanahira/ygo/ygopro/gframe/network.h` 中的协议定义
+2. 检查 `/home/nanahira/ygo/ygopro/gframe/duelclient.cpp` 中的解析代码
+3. 检查 `/home/nanahira/ygo/ygopro/ocgcore/playerop.cpp` 中的 MSG 协议
+4. 搜索位运算操作符：`<<`, `>>`, `& 0xf`, `& 0x0f`, `& 0xf0`
+
+---
+
+## 发现的复合字段
+
+### 1. STOC_TypeChange.type ✅ 已添加 getter/setter
+
+**结构**: `uint8_t`
+
+**位运算**:
+- 低 4 位 (0x0F): 玩家位置 (0-7)
+- 高 4 位 (0xF0): 房主标志 (0x10 = 房主)
+
+**源码**: `duelclient.cpp:645-646`
+```cpp
+selftype = pkt->type & 0xf;
+is_host = ((pkt->type >> 4) & 0xf) != 0;
+```
+
+**实现**:
+- ✅ `get/set playerPosition`: 低 4 位
+- ✅ `get/set isHost`: 高 4 位 (boolean)
+
+---
+
+### 2. STOC_HS_PlayerChange.status ✅ 已添加 getter/setter
+
+**结构**: `uint8_t`
+
+**位运算**:
+- 低 4 位 (0x0F): 玩家状态 (PlayerChangeState 或位置 0-7)
+- 高 4 位 (0xF0): 玩家位置 (0-3)
+
+**源码**: `duelclient.cpp:991-992`
+```cpp
+unsigned char pos = (pkt->status >> 4) & 0xf;
+unsigned char state = pkt->status & 0xf;
+```
+
+**实现**:
+- ✅ `get/set playerPosition`: 高 4 位
+- ✅ `get/set playerState`: 低 4 位
+
+---
+
+### 3. MSG_START.playerType ✅ 已添加 getter/setter
+
+**结构**: `uint8_t`
+
+**位运算**:
+- 低 4 位 (0x0F): 玩家编号 (0-3)
+- 高 4 位 (0xF0): 观战者标志 (0x10 = 观战者)
+
+**源码**: `duelclient.cpp:1429-1432`
+```cpp
+int playertype = BufferIO::Read<uint8_t>(pbuf);
+mainGame->dInfo.isFirst = (playertype & 0xf) ? false : true;
+if(playertype & 0xf0)
+    mainGame->dInfo.player_type = 7;  // Observer
+```
+
+**实现**:
+- ✅ `get/set playerNumber`: 低 4 位
+- ✅ `get/set observerFlag`: 高 4 位
+
+---
+
+## 不是复合字段的情况
+
+### STOC_ErrorMsg.code (条件复合)
+
+**注意**: 这个字段**不是**固定的复合字段，只在特定条件下使用位运算。
+
+当 `msg == DECKERROR` 时：
+- 高 4 位 (28-31): 卡组错误类型 (DeckErrorType)
+- 低 28 位 (0-27): 卡片 ID
+
+**源码**: `single_duel.cpp:358`
+```cpp
+scem.code = deckerror;  // deckerror = (deckError << 28) | cardId
+```
+
+**为什么不添加 getter/setter**:
+- 这是条件性的，不是该字段的固定含义
+- 在其他 `msg` 值下，`code` 有不同的含义
+- 用户需要根据 `msg` 字段自己解析
+
+---
+
+### get_info_location() 返回值
+
+**不是协议字段**: `get_info_location()` 是 C++ 函数返回的**临时值**，不是协议定义的一部分。
+
+**位运算** (card.cpp:444):
+```cpp
+return c | (l << 8) | (s << 16) | (ss << 24);
+```
+
+**在 TypeScript 中**: 这些信息被拆分为独立字段，不需要位运算：
+```typescript
+@BinaryField('u8', 0) controller: number;
+@BinaryField('u8', 1) location: number;
+@BinaryField('u8', 2) sequence: number;
+@BinaryField('u8', 3) position: number;
+```
+
+---
+
+### MSG 协议中的临时变量
+
+**不是协议字段**: MSG 协议中很多位运算用于解析**客户端响应**，不是协议定义本身。
+
+**例子** (playerop.cpp:70-71):
+```cpp
+int32_t t = (uint32_t)returns.ivalue[0] & 0xffff;
+int32_t s = (uint32_t)returns.ivalue[0] >> 16;
+```
+
+这是服务器端对客户端响应的解析，不是发送给客户端的协议字段。
+
+---
+
+## CTOS 协议审计结果
+
+检查了所有 19 个 CTOS 协议：
+
+- ✅ CTOS_PlayerInfo - 无复合字段
+- ✅ CTOS_CreateGame - 无复合字段
+- ✅ CTOS_JoinGame - 无复合字段
+- ✅ CTOS_LeaveGame - 无数据
+- ✅ CTOS_Kick - 无复合字段（简单 enum）
+- ✅ CTOS_HandResult - 无复合字段（简单 enum）
+- ✅ CTOS_TPResult - 无复合字段（简单 enum）
+- ✅ CTOS_UpdateDeck - 无复合字段
+- ✅ CTOS_Response - 无复合字段
+- ✅ CTOS_Surrender - 无数据
+- ✅ CTOS_Chat - 无复合字段
+- ✅ CTOS_HS_ToObserver - 无数据
+- ✅ CTOS_HS_ToDuelist - 无数据
+- ✅ CTOS_HS_Ready - 无数据
+- ✅ CTOS_HS_NotReady - 无数据
+- ✅ CTOS_HS_Start - 无数据
+- ✅ CTOS_TimeConfirm - 无数据
+- ✅ CTOS_RequestField - 无数据
+- ✅ CTOS_ExternalAddress - 无复合字段
+
+**结论**: CTOS 协议中**没有**复合字段。
+
+---
+
+## STOC 协议审计结果
+
+检查了所有 24 个 STOC 协议：
+
+- ✅ STOC_GameMsg - 无复合字段（封装 MSG）
+- ✅ STOC_ErrorMsg - code 是条件复合（见上文）
+- ✅ STOC_SelectHand - 无数据
+- ✅ STOC_SelectTP - 无数据
+- ✅ STOC_HandResult - 无复合字段
+- ✅ STOC_TPResult - 无复合字段
+- ✅ STOC_ChangeSide - 无数据
+- ✅ STOC_WaitingSide - 无数据
+- ✅ STOC_DeckCount - 结构化对象（已改进）
+- ✅ STOC_CreateGame - 无数据
+- ✅ STOC_JoinGame - 无复合字段
+- ✅ **STOC_TypeChange** - ✅ 已添加 getter/setter
+- ✅ STOC_LeaveGame - 无复合字段
+- ✅ STOC_DuelStart - 无数据
+- ✅ STOC_DuelEnd - 无数据
+- ✅ STOC_Replay - 无复合字段
+- ✅ STOC_TimeLimit - 无复合字段
+- ✅ STOC_Chat - 无复合字段（player_type 是条件性的）
+- ✅ STOC_HS_PlayerEnter - 无复合字段
+- ✅ **STOC_HS_PlayerChange** - ✅ 已添加 getter/setter
+- ✅ STOC_HS_WatchChange - 无复合字段
+- ✅ STOC_TeammateSurrender - 无数据
+- ✅ STOC_FieldFinish - 无数据
+- ✅ STOC_SRVPRO_ROOMLIST - 无复合字段
+
+**结论**: STOC 协议中有 **2 个复合字段**，已全部添加 getter/setter。
+
+---
+
+## MSG 协议审计结果
+
+检查了所有需要客户端响应的 MSG 协议（18 个）和其他主要 MSG 协议：
+
+- ✅ **MSG_START** - ✅ 已添加 getter/setter (playerType)
+- ✅ MSG_SELECT_BATTLECMD - 无复合字段
+- ✅ MSG_SELECT_IDLECMD - 无复合字段
+- ✅ MSG_SELECT_EFFECTYN - 无复合字段
+- ✅ MSG_SELECT_YESNO - 无复合字段
+- ✅ MSG_SELECT_OPTION - 无复合字段
+- ✅ MSG_SELECT_CARD - 无复合字段
+- ✅ MSG_SELECT_CHAIN - 无复合字段
+- ✅ MSG_SELECT_PLACE - 无复合字段
+- ✅ MSG_SELECT_POSITION - 无复合字段
+- ✅ MSG_SELECT_TRIBUTE - 无复合字段
+- ✅ MSG_SELECT_COUNTER - 无复合字段
+- ✅ MSG_SELECT_SUM - 无复合字段
+- ✅ MSG_SELECT_DISFIELD - 无复合字段
+- ✅ MSG_SORT_CARD - 无复合字段
+- ✅ MSG_ANNOUNCE_RACE - 无复合字段
+- ✅ MSG_ANNOUNCE_ATTRIB - 无复合字段
+- ✅ MSG_ANNOUNCE_CARD - 无复合字段
+- ✅ MSG_ANNOUNCE_NUMBER - 无复合字段
+- ✅ 其他 MSG (80+) - 无复合字段（信息显示类消息）
+
+**注意**: MSG 协议中的位运算主要用于：
+1. 临时变量解析（如 `returns.ivalue[0]` 的拆分）
+2. C++ 函数返回值（如 `get_info_location()`）
+3. 这些不是协议字段定义本身
+
+**结论**: MSG 协议中只有 **1 个复合字段** (MSG_START.playerType)，已添加 getter/setter。
+
+---
+
+## 总结
+
+### 复合字段统计
+
+- **CTOS**: 0 个复合字段
+- **STOC**: 2 个复合字段（已全部添加 getter/setter）
+- **MSG**: 1 个复合字段（已添加 getter/setter）
+- **总计**: 3 个复合字段，✅ 已全部添加 getter/setter
+
+### 实现的 getter/setter
+
+1. ✅ `YGOProStocTypeChange`
+   - `playerPosition` (get/set)
+   - `isHost` (get/set)
+
+2. ✅ `YGOProStocHsPlayerChange`
+   - `playerPosition` (get/set)
+   - `playerState` (get/set)
+
+3. ✅ `YGOProMsgStart`
+   - `playerNumber` (get/set)
+   - `observerFlag` (get/set)
+
+### 测试结果
+
+- ✅ 所有 101 个测试通过
+- ✅ 构建成功
+- ✅ 类型检查通过
+
+---
+
+## 审计完成日期
+
+2026-02-02
+
+## 参考源码
+
+- `/home/nanahira/ygo/ygopro/gframe/network.h` - 协议定义
+- `/home/nanahira/ygo/ygopro/gframe/duelclient.cpp` - 客户端解析
+- `/home/nanahira/ygo/ygopro/gframe/single_duel.cpp` - 服务器端发送
+- `/home/nanahira/ygo/ygopro/gframe/tag_duel.cpp` - 服务器端发送
+- `/home/nanahira/ygo/ygopro/ocgcore/playerop.cpp` - MSG 协议定义

package/COMPOSITE_FIELDS_GUIDE.md

@@ -0,0 +1,303 @@
+# 复合字段使用指南
+
+本文档说明 YGOPro 协议中使用位运算或特殊结构的复合字段。
+
+## MSG_START.playerType
+
+### 字段结构
+
+`playerType` 是一个 `uint8_t` 字段，使用位运算编码了两种信息：
+
+- **低 4 位 (0x0F)**: 玩家编号
+- **高 4 位 (0xF0)**: 观战者标志
+
+### 可能的值
+
+| 值 | 十六进制 | 含义 |
+|----|----------|------|
+| 0 | 0x00 | 玩家 0（你先手） |
+| 1 | 0x01 | 玩家 1（对手先手） |
+| 16 | 0x10 | 观战者视角（观看玩家 0） |
+| 17 | 0x11 | 观战者视角（观看玩家 1，swapped） |
+
+### 使用示例
+
+#### 使用 getter/setter（推荐）
+
+```typescript
+import { YGOProMsgStart } from 'ygopro-msg-encode';
+
+const startMsg = new YGOProMsgStart();
+startMsg.fromPayload(data);
+
+// 读取低 4 位（玩家编号）
+const playerNumber = startMsg.playerNumber;  // 0-3
+const isFirst = startMsg.playerNumber === 0;
+
+// 读取高 4 位（观战者标志）
+const observerFlag = startMsg.observerFlag;  // 0x00 或 0x10
+const isObserver = startMsg.observerFlag !== 0;
+
+// 设置值
+startMsg.playerNumber = 1;      // 设置为玩家 1
+startMsg.observerFlag = 0x10;   // 设置为观战者
+
+// 组合判断
+if (isObserver) {
+  console.log(`You are watching player ${playerNumber}`);
+} else if (isFirst) {
+  console.log('You go first!');
+} else {
+  console.log('Opponent goes first!');
+}
+```
+
+#### 直接访问（也可以）
+
+```typescript
+// 直接读写 playerType
+startMsg.playerType = 0x11;  // 观战者视角，观看玩家 1
+
+// 手动位运算
+const playerNumber = startMsg.playerType & 0x0f;
+const observerFlag = startMsg.playerType & 0xf0;
+```
+
+### 源码参考
+
+```cpp
+// duelclient.cpp:1429-1432
+int playertype = BufferIO::Read<uint8_t>(pbuf);
+mainGame->dInfo.isFirst = (playertype & 0xf) ? false : true;
+if(playertype & 0xf0)
+    mainGame->dInfo.player_type = 7;  // Observer
+```
+
+---
+
+## STOC_DECK_COUNT 卡组数量
+
+### 字段结构
+
+使用嵌套对象结构存储双方玩家的卡组数量：
+
+- `player0DeckCount`: `YGOProStocDeckCount_DeckInfo` - 玩家 0 的卡组信息
+  - `main`: `int16_t` - 主卡组数量
+  - `extra`: `int16_t` - 额外卡组数量
+  - `side`: `int16_t` - 副卡组数量
+- `player1DeckCount`: `YGOProStocDeckCount_DeckInfo` - 玩家 1 的卡组信息
+  - `main`: `int16_t` - 主卡组数量
+  - `extra`: `int16_t` - 额外卡组数量
+  - `side`: `int16_t` - 副卡组数量
+
+### 使用示例
+
+#### 直接访问对象属性（推荐）
+
+```typescript
+import { YGOProStocDeckCount } from 'ygopro-msg-encode';
+
+const deckCount = new YGOProStocDeckCount();
+deckCount.fromFullPayload(data);
+
+// 访问玩家 0 的卡组数量
+console.log(`Your deck: Main=${deckCount.player0DeckCount.main}, Extra=${deckCount.player0DeckCount.extra}, Side=${deckCount.player0DeckCount.side}`);
+
+// 访问玩家 1 的卡组数量
+console.log(`Opponent: Main=${deckCount.player1DeckCount.main}, Extra=${deckCount.player1DeckCount.extra}, Side=${deckCount.player1DeckCount.side}`);
+```
+
+#### 设置卡组数量
+
+```typescript
+import { YGOProStocDeckCount, YGOProStocDeckCount_DeckInfo } from 'ygopro-msg-encode';
+
+const deckCount = new YGOProStocDeckCount();
+deckCount.player0DeckCount = new YGOProStocDeckCount_DeckInfo();
+deckCount.player1DeckCount = new YGOProStocDeckCount_DeckInfo();
+
+// 设置玩家 0
+deckCount.player0DeckCount.main = 40;
+deckCount.player0DeckCount.extra = 15;
+deckCount.player0DeckCount.side = 15;
+
+// 设置玩家 1
+deckCount.player1DeckCount.main = 42;
+deckCount.player1DeckCount.extra = 14;
+deckCount.player1DeckCount.side = 13;
+
+const payload = deckCount.toFullPayload();
+```
+
+### 源码参考
+
+```cpp
+// single_duel.cpp:485-490 (发送端)
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[0].main.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[0].extra.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[0].side.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[1].main.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[1].extra.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[1].side.size());
+
+// duelclient.cpp:541-548 (接收端)
+int deckc = BufferIO::Read<uint16_t>(pdata);
+int extrac = BufferIO::Read<uint16_t>(pdata);
+int sidec = BufferIO::Read<uint16_t>(pdata);
+mainGame->dField.Initial(0, deckc, extrac, sidec);
+deckc = BufferIO::Read<uint16_t>(pdata);
+extrac = BufferIO::Read<uint16_t>(pdata);
+sidec = BufferIO::Read<uint16_t>(pdata);
+mainGame->dField.Initial(1, deckc, extrac, sidec);
+```
+
+---
+
+## STOC_TYPE_CHANGE.type
+
+### 字段结构
+
+`type` 是一个 `uint8_t` 字段，使用位运算编码玩家位置和房主状态：
+
+- **低 4 位 (0x0F)**: 玩家位置 (0-7)
+- **高 4 位 (0xF0)**: 房主标志 (0x10 = 房主, 0x00 = 非房主)
+
+### 使用示例
+
+#### 使用 getter/setter（推荐）
+
+```typescript
+import { YGOProStocTypeChange } from 'ygopro-msg-encode';
+
+const typeChange = new YGOProStocTypeChange();
+typeChange.fromFullPayload(data);
+
+// 读取玩家位置
+const pos = typeChange.playerPosition;  // 0-7
+
+// 读取房主状态
+const isHost = typeChange.isHost;  // true/false
+
+// 设置值
+typeChange.playerPosition = 2;
+typeChange.isHost = true;  // 设置为房主
+```
+
+#### 直接访问（也可以）
+
+```typescript
+// 直接位运算
+const pos = typeChange.type & 0x0f;
+const isHost = ((typeChange.type >> 4) & 0x0f) !== 0;
+```
+
+### 源码参考
+
+```cpp
+// duelclient.cpp:645-646
+selftype = pkt->type & 0xf;
+is_host = ((pkt->type >> 4) & 0xf) != 0;
+```
+
+---
+
+## STOC_HS_PLAYER_CHANGE.status
+
+### 字段结构
+
+`status` 是一个 `uint8_t` 字段，使用位运算编码玩家位置和状态：
+
+- **低 4 位 (0x0F)**: 玩家状态 (PlayerChangeState 或位置 0-7)
+- **高 4 位 (0xF0)**: 玩家位置 (0-3)
+
+### 使用示例
+
+#### 使用 getter/setter（推荐）
+
+```typescript
+import { YGOProStocHsPlayerChange, PlayerChangeState } from 'ygopro-msg-encode';
+
+const playerChange = new YGOProStocHsPlayerChange();
+playerChange.fromFullPayload(data);
+
+// 读取玩家位置
+const pos = playerChange.playerPosition;  // 0-3
+
+// 读取状态
+const state = playerChange.playerState;
+if (state === PlayerChangeState.READY) {
+  console.log(`Player ${pos} is ready!`);
+}
+
+// 设置值
+playerChange.playerPosition = 1;
+playerChange.playerState = PlayerChangeState.READY;
+```
+
+#### 直接访问（也可以）
+
+```typescript
+// 直接位运算
+const pos = (playerChange.status >> 4) & 0x0f;
+const state = playerChange.status & 0x0f;
+```
+
+### 源码参考
+
+```cpp
+// duelclient.cpp:991-992
+unsigned char pos = (pkt->status >> 4) & 0xf;
+unsigned char state = pkt->status & 0xf;
+
+// single_duel.cpp:372 (设置值)
+scpc.status = (dp->type << 4) | (is_ready ? PLAYERCHANGE_READY : PLAYERCHANGE_NOTREADY);
+```
+
+---
+
+## 其他复合字段
+
+### STOC_ErrorMsg.code (当 msg == DECKERROR 时)
+
+复合字段（未提供辅助方法，使用位运算）：
+
+- **高 4 位**: 卡组错误类型 (DeckErrorType)
+- **低 28 位**: 卡片 ID
+
+```typescript
+if (errorMsg.msg === ErrorMessageType.DECKERROR) {
+  const errorType = (errorMsg.code >> 28) & 0xf;  // DeckErrorType
+  const cardId = errorMsg.code & 0x0fffffff;      // Card ID
+}
+```
+
+---
+
+## 设计原则
+
+这些复合字段的设计遵循以下原则：
+
+1. **节省带宽**：在一个字节中编码多个信息
+2. **向后兼容**：通过位运算扩展功能而不破坏现有结构
+3. **简单解析**：使用简单的位运算即可提取信息
+
+## 最佳实践
+
+1. **使用对象属性和 getter/setter**：优先使用结构化的对象属性（如 `player0DeckCount.main`）和 getter/setter（如 `startMsg.playerNumber`）
+2. **避免直接位运算**：除非有特殊需求，否则避免直接对 `playerType` 等字段进行位运算
+3. **类型安全**：利用 TypeScript 的类型系统和枚举来确保正确性
+
+```typescript
+// ✅ 推荐：使用 getter/setter
+if (startMsg.observerFlag !== 0) {
+  const watching = startMsg.playerNumber;
+}
+
+// ✅ 推荐：使用对象属性
+console.log(`Main deck: ${deckCount.player0DeckCount.main}`);
+
+// ⚠️ 可以但不推荐：直接位运算
+if (startMsg.playerType & 0xf0) {
+  const watching = startMsg.playerType & 0x0f;
+}
+```

package/DECK_COUNT_EXPLANATION.md

@@ -0,0 +1,124 @@
+# STOC_DECK_COUNT 字段说明
+
+## 概述
+
+`STOC_DECK_COUNT` 协议在换边（Side Deck）阶段发送，用于告知客户端双方玩家的卡组数量信息。
+
+## 字段结构
+
+协议包含两个 `YGOProStocDeckCount_DeckInfo` 对象：
+
+### player0DeckCount
+
+- `main` (int16_t) - 玩家 0 的主卡组数量
+- `extra` (int16_t) - 玩家 0 的额外卡组数量
+- `side` (int16_t) - 玩家 0 的副卡组数量
+
+### player1DeckCount
+
+- `main` (int16_t) - 玩家 1 的主卡组数量
+- `extra` (int16_t) - 玩家 1 的额外卡组数量
+- `side` (int16_t) - 玩家 1 的副卡组数量
+
+## 二进制布局
+
+| 偏移 | 类型 | 字段 |
+|------|------|------|
+| 0 | int16_t | player0DeckCount.main |
+| 2 | int16_t | player0DeckCount.extra |
+| 4 | int16_t | player0DeckCount.side |
+| 6 | int16_t | player1DeckCount.main |
+| 8 | int16_t | player1DeckCount.extra |
+| 10 | int16_t | player1DeckCount.side |
+
+## 源码参考
+
+### 服务器端发送 (single_duel.cpp:485-490)
+
+```cpp
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[0].main.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[0].extra.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[0].side.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[1].main.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[1].extra.size());
+BufferIO::Write<uint16_t>(pbuf, (short)pdeck[1].side.size());
+```
+
+### 客户端接收 (duelclient.cpp:541-548)
+
+```cpp
+int deckc = BufferIO::Read<uint16_t>(pdata);
+int extrac = BufferIO::Read<uint16_t>(pdata);
+int sidec = BufferIO::Read<uint16_t>(pdata);
+mainGame->dField.Initial(0, deckc, extrac, sidec);
+deckc = BufferIO::Read<uint16_t>(pdata);
+extrac = BufferIO::Read<uint16_t>(pdata);
+sidec = BufferIO::Read<uint16_t>(pdata);
+mainGame->dField.Initial(1, deckc, extrac, sidec);
+```
+
+## 使用示例
+
+### 读取卡组数量
+
+```typescript
+import { YGOProStocDeckCount } from 'ygopro-msg-encode';
+
+const deckCount = new YGOProStocDeckCount();
+deckCount.fromFullPayload(data);
+
+// 访问玩家 0 的卡组数量
+console.log(`Player 0: Main=${deckCount.player0DeckCount.main}, Extra=${deckCount.player0DeckCount.extra}, Side=${deckCount.player0DeckCount.side}`);
+
+// 访问玩家 1 的卡组数量
+console.log(`Player 1: Main=${deckCount.player1DeckCount.main}, Extra=${deckCount.player1DeckCount.extra}, Side=${deckCount.player1DeckCount.side}`);
+
+// 简洁写法
+const { main, extra, side } = deckCount.player0DeckCount;
+console.log(`Your deck: ${main}+${extra}+${side}`);
+```
+
+### 设置卡组数量
+
+```typescript
+import { YGOProStocDeckCount, YGOProStocDeckCount_DeckInfo } from 'ygopro-msg-encode';
+
+const deckCount = new YGOProStocDeckCount();
+
+// 初始化对象
+deckCount.player0DeckCount = new YGOProStocDeckCount_DeckInfo();
+deckCount.player1DeckCount = new YGOProStocDeckCount_DeckInfo();
+
+// 设置玩家 0 的卡组数量
+deckCount.player0DeckCount.main = 40;
+deckCount.player0DeckCount.extra = 15;
+deckCount.player0DeckCount.side = 15;
+
+// 设置玩家 1 的卡组数量
+deckCount.player1DeckCount.main = 42;
+deckCount.player1DeckCount.extra = 14;
+deckCount.player1DeckCount.side = 13;
+
+const payload = deckCount.toFullPayload();
+```
+
+## 使用场景
+
+这个协议主要在以下场景使用：
+
+1. **换边阶段前**：告知客户端双方当前的卡组配置
+2. **匹配赛（Match）中**：在第二局或第三局开始前发送，让玩家知道对手是否更换了副卡组
+
+## 注意事项
+
+1. **对象初始化**：使用前需要创建 `YGOProStocDeckCount_DeckInfo` 实例
+2. **数值范围**：每个值都是 `int16_t`（-32768 到 32767），但实际使用时应该是非负整数
+3. **玩家索引**：Player 0 通常是先手，Player 1 通常是后手（但需要根据 `MSG_START` 确认）
+4. **副卡组融合怪兽**：在某些服务器配置下（`DUEL_FLAG_SIDEINS`），副卡组中的融合/同调/超量/连接怪兽会被计入额外卡组数量
+5. **类型安全**：使用对象属性访问提供更好的类型检查和 IDE 自动补全
+
+## 相关协议
+
+- `STOC_CHANGE_SIDE` (0x07) - 通知客户端进入换边阶段
+- `STOC_WAITING_SIDE` (0x08) - 等待对手换边
+- `CTOS_UPDATE_DECK` (0x02) - 客户端发送更新后的卡组