ygopro-msg-encode 1.0.1

package/.eslintignore

@@ -0,0 +1,4 @@
+webpack.config.js
+dist/*
+build/*
+*.js

package/.eslintrc.js

@@ -0,0 +1,25 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: 'tsconfig.json',
+    tsconfigRootDir : __dirname, 
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint/eslint-plugin'],
+  extends: [
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended',
+  ],
+  root: true,
+  env: {
+    node: true,
+    jest: true,
+  },
+  ignorePatterns: ['.eslintrc.js'],
+  rules: {
+    '@typescript-eslint/interface-name-prefix': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+  },
+};

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/AGENTS.md

@@ -0,0 +1,12 @@
+# 项目规范
+
+- 所有二进制协议相关的类，必须继承于 PayloadBase 类
+- 使用 @BinaryField 装饰器定义二进制协议字段，并使用 fillBinaryFields 和 toBinaryFields 函数进行序列化和反序列化
+- protos 目录下是各种协议类型的定义，有 msg stoc ctos 三种，每种有 proto/ 目录（每个文件是一个消息类型）和 registry.ts 文件（用于注册消息类型），还有 base.ts 文件（用于定义消息基类）
+- 每写一个类，要在 registry 里面加一行，注册这个类
+- 对应 YGOPro 的 ocgcore/common.h 的常量已经在 src/vendor 里面放好了，这是系统自动维护的。请不要抄任何 common.h 已有常量，而是用这里的。
+
+## 参考
+
+- YGOPro ocgcore: /home/nanahira/ygo/ygopro/ocgcore
+- YGOPro 源代码: /home/nanahira/ygo/ygopro/gframe

package/CHANGES.md

@@ -0,0 +1,270 @@
+# MSG 类重构变更说明
+
+## 主要修改
+
+### 1. 基类修改 - 添加 MSG Identifier
+
+**文件**: `src/protos/msg/base.ts`
+
+修改了 `YGOProMsgBase` 的 `fromPayload` 和 `toPayload` 方法：
+
+- **toPayload()**: 第一个字节写入 MSG identifier
+- **fromPayload()**: 
+  - 验证第一个字节是否与 identifier 一致
+  - 从第二个字节开始解析数据
+
+**手动实现修改**: `src/protos/msg/proto/update-card.ts` 同样进行了修改
+
+### 2. 小类重命名和导出
+
+所有嵌套的小类都已：
+- 重命名为 `{主类名}_{小类名}` 格式
+- 改为 `export` 导出
+
+#### 修改的文件列表：
+
+**使用 1/2 或对称命名改为小类的文件**（共 9 个）：
+- `card-target.ts` - 改用 `YGOProMsgCardTarget_CardLocation` (card1/card2)
+- `cancel-target.ts` - 改用 `YGOProMsgCancelTarget_CardLocation` (card1/card2)
+- `swap.ts` - 改用 `YGOProMsgSwap_CardLocation` (card1/card2)
+- `move.ts` - 改用 `YGOProMsgMove_CardLocation` (previous/current)
+- `pos-change.ts` - 改用 `YGOProMsgPosChange_CardLocation` (card + previousPosition/currentPosition)
+- `attack.ts` - 改用 `YGOProMsgAttack_CardLocation` (attacker/defender)
+- `battle.ts` - 改用 `YGOProMsgBattle_CardLocation` + `YGOProMsgBattle_CardStats` (attacker/defender，嵌套 location + atk/def)
+- `equip.ts` - 改用 `YGOProMsgEquip_CardLocation` (equip/target)
+- `shuffle-set-card.ts` - 改用 `YGOProMsgShuffleSetCard_CardLocation` + `YGOProMsgShuffleSetCard_SetCardInfo` (oldLocation/newLocation)
+
+**导出小类的文件**：
+- `confirm-decktop.ts` → `YGOProMsgConfirmDeckTop_CardInfo`
+- `confirm-extratop.ts` → `YGOProMsgConfirmExtraTop_CardInfo`
+- `confirm-cards.ts` → `YGOProMsgConfirmCards_CardInfo`
+- `select-card.ts` → `YGOProMsgSelectCard_CardInfo`
+- `select-tribute.ts` → `YGOProMsgSelectTribute_CardInfo`
+- `select-unselect-card.ts` → `YGOProMsgSelectUnselectCard_CardInfo`
+- `sort-card.ts` → `YGOProMsgSortCard_CardInfo`
+- `select-counter.ts` → `YGOProMsgSelectCounter_CardInfo`
+- `select-sum.ts` → `YGOProMsgSelectSum_CardInfo`
+- `select-chain.ts` → `YGOProMsgSelectChain_ChainInfo`
+- `select-battlecmd.ts` → `YGOProMsgSelectBattleCmd_ActivatableInfo`, `YGOProMsgSelectBattleCmd_AttackableInfo`
+- `select-idlecmd.ts` → `YGOProMsgSelectIdleCmd_SimpleCardInfo`, `YGOProMsgSelectIdleCmd_ActivatableInfo`
+- `shuffle-set-card.ts` → `YGOProMsgShuffleSetCard_SetCardInfo`
+
+### 3. 字段重构
+
+#### 前（使用 1/2 命名）：
+```typescript
+export class YGOProMsgCardTarget extends YGOProMsgBase {
+  @BinaryField('u8', 0) controller1: number;
+  @BinaryField('u8', 1) location1: number;
+  @BinaryField('u8', 2) sequence1: number;
+  @BinaryField('u8', 3) controller2: number;
+  @BinaryField('u8', 4) location2: number;
+  @BinaryField('u8', 5) sequence2: number;
+}
+```
+
+#### 后（使用小类）：
+```typescript
+export class YGOProMsgCardTarget_CardLocation {
+  @BinaryField('u8', 0) controller: number;
+  @BinaryField('u8', 1) location: number;
+  @BinaryField('u8', 2) sequence: number;
+}
+
+export class YGOProMsgCardTarget extends YGOProMsgBase {
+  @BinaryField(() => YGOProMsgCardTarget_CardLocation, 0)
+  card1: YGOProMsgCardTarget_CardLocation;
+  
+  @BinaryField(() => YGOProMsgCardTarget_CardLocation, 3)
+  card2: YGOProMsgCardTarget_CardLocation;
+}
+```
+
+### 示例 2: 嵌套小类
+
+#### 前（使用扁平命名）：
+```typescript
+export class YGOProMsgBattle extends YGOProMsgBase {
+  @BinaryField('u8', 0) attackerController: number;
+  @BinaryField('u8', 1) attackerLocation: number;
+  @BinaryField('u8', 2) attackerSequence: number;
+  @BinaryField('u8', 3) attackerPosition: number;
+  @BinaryField('i32', 4) attackerAtk: number;
+  @BinaryField('i32', 8) attackerDef: number;
+  @BinaryField('u8', 12) defenderController: number;
+  // ... 类似的 defender 字段
+}
+```
+
+#### 后（使用嵌套小类）：
+```typescript
+export class YGOProMsgBattle_CardLocation {
+  @BinaryField('u8', 0) controller: number;
+  @BinaryField('u8', 1) location: number;
+  @BinaryField('u8', 2) sequence: number;
+  @BinaryField('u8', 3) position: number;
+}
+
+export class YGOProMsgBattle_CardStats {
+  @BinaryField(() => YGOProMsgBattle_CardLocation, 0)
+  location: YGOProMsgBattle_CardLocation;
+  
+  @BinaryField('i32', 4) atk: number;
+  @BinaryField('i32', 8) def: number;
+}
+
+export class YGOProMsgBattle extends YGOProMsgBase {
+  @BinaryField(() => YGOProMsgBattle_CardStats, 0)
+  attacker: YGOProMsgBattle_CardStats;
+  
+  @BinaryField(() => YGOProMsgBattle_CardStats, 12)
+  defender: YGOProMsgBattle_CardStats;
+  
+  @BinaryField('u8', 24) battleDamageCalc: number;
+}
+```
+
+## 二进制格式变化
+
+### 前：
+```
+[字段数据...]
+```
+
+### 后：
+```
+[MSG_IDENTIFIER (1 byte)][字段数据...]
+```
+
+所有 MSG 的序列化数据现在第一个字节都是 MSG identifier，解析时会验证该字节。
+
+## 测试更新
+
+`tests/msg.spec.ts` 已更新以适配新的二进制格式：
+- 期望长度增加 1 字节（identifier）
+- 验证第一个字节是正确的 MSG identifier
+- 添加了 identifier 验证测试
+
+## 向后兼容性
+
+⚠️ **破坏性变更**：由于二进制格式改变，此修改与旧版本不兼容。
+
+## 新增消息类型
+
+### MSG_START (4)
+开始决斗的消息，包含：
+- playerType: 玩家类型
+- duelRule: 决斗规则
+- startLp0/startLp1: 双方起始 LP
+- player0/player1: 双方卡组和额外卡组数量
+
+### MSG_WAITING (3)
+等待消息，无字段
+
+### MSG_UPDATE_CARD (7) - 完整实现 ✅ 视角控制
+更新单张卡片信息，现在使用完整的 `CardQuery` 类：
+- controller, location, sequence: 卡片位置
+- card: CardQuery 对象，包含完整的查询数据
+- **opponentView**: 对手视角下，盖放卡片（POS_FACEDOWN）只显示 flags = QUERY_CODE 和 code = 0
+- **teammateView**: TAG 决斗中
+  - 场上卡片（LOCATION_ONFIELD）：队友可以看到己方盖放的卡片
+  - 非场上卡片：和对手视角相同
+
+### MSG_UPDATE_DATA (6) - 完整实现 ✅ 视角控制
+更新某个位置所有卡片的信息，现在使用 `CardQuery[]` 数组：
+- player, location: 位置信息
+- cards: CardQuery 数组，每张卡片的完整查询数据
+- **opponentView**: 对手视角下，盖放卡片（POS_FACEDOWN）清除所有查询数据（flags = 0, empty = true）
+- **teammateView**: TAG 决斗中，根据位置不同处理
+  - MZONE/SZONE：队友可以看到己方盖放的卡片
+  - HAND：队友也看不到非公开的手牌（只有当前操作玩家能看到）
+  - 其他公开区域（GRAVE 等）：队友可以看到
+
+### MSG_RELOAD_FIELD (162)
+重新加载整个场地信息，包含：
+- duelRule: 决斗规则
+- players[2]: 双方玩家状态（LP、各区域卡片数量和位置）
+- chains: 连锁信息数组
+
+## CardQuery 类
+
+新增 `CardQuery` 类，完整实现 OCG 查询数据的序列化和反序列化：
+
+### 支持的查询标志
+- QUERY_CODE (1): 卡片代码
+- QUERY_POSITION (2): 卡片位置
+- QUERY_ALIAS (4): 别名
+- QUERY_TYPE (8): 卡片类型
+- QUERY_LEVEL (16): 等级
+- QUERY_RANK (32): 阶级
+- QUERY_ATTRIBUTE (64): 属性
+- QUERY_RACE (128): 种族
+- QUERY_ATTACK (256): 攻击力
+- QUERY_DEFENSE (512): 守备力
+- QUERY_BASE_ATTACK (1024): 基础攻击力
+- QUERY_BASE_DEFENSE (2048): 基础守备力
+- QUERY_REASON (4096): 原因
+- QUERY_REASON_CARD (8192): 原因卡片（自动跳过）
+- QUERY_EQUIP_CARD (16384): 装备卡位置
+- QUERY_TARGET_CARD (32768): 目标卡片位置数组
+- QUERY_OVERLAY_CARD (65536): 超量素材数组
+- QUERY_COUNTERS (131072): 指示物数组
+- QUERY_OWNER (262144): 拥有者
+- QUERY_STATUS (524288): 状态
+- QUERY_LSCALE (2097152): 左刻度
+- QUERY_RSCALE (4194304): 右刻度
+- QUERY_LINK (8388608): Link 值和 Link 标记
+
+### 小类
+- `CardQuery_CardLocation`: 卡片位置信息
+- `CardQuery_Counter`: 指示物信息
+
+## 视角控制实现
+
+### MSG_UPDATE_CARD
+根据 single_duel.cpp 和 tag_duel.cpp (RefreshSingle) 的实现：
+- **对卡片控制者**：发送完整的查询数据
+- **对对手**：如果卡片是盖放的（POS_FACEDOWN），只保留 flags = QUERY_CODE 和 code = 0
+- **对队友（TAG 决斗）**：
+  - 场上卡片（LOCATION_ONFIELD）：发送完整数据（包括盖放）
+  - 非场上卡片：和对手视角相同
+
+### MSG_UPDATE_DATA
+根据 single_duel.cpp 和 tag_duel.cpp (RefreshMzone/RefreshSzone/RefreshHand) 的实现：
+- **对卡片控制者**：发送完整的查询数据
+- **对对手**：遍历每张卡片，盖放的卡片（POS_FACEDOWN）清除所有查询数据
+- **对队友（TAG 决斗）**：
+  - MZONE/SZONE：发送完整数据（队友可以看到己方盖放的卡片）
+  - HAND：只有当前操作玩家（cur_player[player]）能看到完整手牌，队友也看不到非公开的手牌
+  - 其他公开区域（GRAVE 等）：所有人都能看到
+
+## playerView 实现
+
+### 基类实现
+基类 `YGOProMsgBase` 提供了默认的 `playerView` 实现：
+- 检查 `this['player']` 字段
+- 如果匹配传入的 `playerId`，返回完整数据
+- 否则返回 `opponentView()`
+
+### 特殊实现
+**MSG_UPDATE_CARD** - 字段名是 `controller` 而不是 `player`，需要重写 `playerView`：
+```typescript
+playerView(playerId: number): this {
+  if (this.controller === playerId) {
+    return this.copy();
+  }
+  return this.opponentView();
+}
+```
+
+## 测试结果
+
+✅ 所有 66 个测试通过（新增 20 个查询数据和视角控制测试）
+✅ 构建成功
+
+新增测试：
+- MSG_UPDATE_CARD 的视角控制（对手/队友/playerView）
+- MSG_UPDATE_DATA 的视角控制（对手/队友/playerView）
+- 场上盖放卡片的队友可见性
+- 手牌非公开卡片的队友不可见性
+- playerView 正确使用 controller 和 player 字段

package/CTOS_STOC_IMPLEMENTATION.md

@@ -0,0 +1,279 @@
+# CTOS/STOC 协议实现总结
+
+本文档总结了 CTOS（Client to Server）和 STOC（Server to Client）协议的实现。
+
+## 协议格式
+
+CTOS 和 STOC 协议的二进制格式为：
+```
+[length 2 bytes][identifier 1 byte][body]
+```
+
+- `length`: 2 字节小端序，表示 identifier + body 的总长度
+- `identifier`: 1 字节，协议类型标识符
+- `body`: 正文内容（可变长度）
+
+## 实现架构
+
+### 基础类
+
+#### `YGOProCtosBase` (`src/protos/ctos/base.ts`)
+- 继承自 `PayloadBase`
+- 只处理正文（body）部分
+- 不包含 header 处理逻辑
+
+#### `YGOProStocBase` (`src/protos/stoc/base.ts`)
+- 继承自 `PayloadBase`
+- 只处理正文（body）部分
+- 不包含 header 处理逻辑
+
+### 注册器
+
+#### `YGOProCtos` (`src/protos/ctos/registry.ts`)
+```typescript
+export const YGOProCtos = new RegistryBase(YGOProCtosBase, {
+  identifierOffset: 2,  // identifier 在字节 2
+  dataOffset: 3,        // body 从字节 3 开始
+});
+```
+
+#### `YGOProStoc` (`src/protos/stoc/registry.ts`)
+```typescript
+export const YGOProStoc = new RegistryBase(YGOProStocBase, {
+  identifierOffset: 2,  // identifier 在字节 2
+  dataOffset: 3,        // body 从字节 3 开始
+});
+```
+
+### 公共数据结构
+
+#### `HostInfo` (`src/protos/common/host-info.ts`)
+用于多个协议的房间信息结构（20 字节）：
+- `lflist`: uint32_t
+- `rule`: uint8_t
+- `mode`: uint8_t
+- `duel_rule`: uint8_t
+- `no_check_deck`: uint8_t
+- `no_shuffle_deck`: uint8_t
+- 3 字节 padding
+- `start_lp`: int32_t
+- `start_hand`: uint8_t
+- `draw_count`: uint8_t
+- `time_limit`: uint16_t
+
+## CTOS 协议实现
+
+实现了以下 CTOS 协议（共 19 个）：
+
+| 标识符 | 类名 | 说明 |
+|--------|------|------|
+| 0x01 | `YGOProCtosResponse` | 响应数据（字节数组） |
+| 0x02 | `YGOProCtosUpdateDeck` | 更新卡组（使用 ygopro-deck-encode） |
+| 0x03 | `YGOProCtosHandResult` | 猜拳结果 |
+| 0x04 | `YGOProCtosTpResult` | 先后手选择结果 |
+| 0x10 | `YGOProCtosPlayerInfo` | 玩家信息（名字） |
+| 0x11 | `YGOProCtosCreateGame` | 创建房间 |
+| 0x12 | `YGOProCtosJoinGame` | 加入房间 |
+| 0x13 | `YGOProCtosLeaveGame` | 离开房间（无数据） |
+| 0x14 | `YGOProCtosSurrender` | 认输（无数据） |
+| 0x15 | `YGOProCtosTimeConfirm` | 时间确认（无数据） |
+| 0x16 | `YGOProCtosChat` | 聊天消息 |
+| 0x17 | `YGOProCtosExternalAddress` | 外部地址 |
+| 0x20 | `YGOProCtosHsToDuelist` | 切换到决斗者（无数据） |
+| 0x21 | `YGOProCtosHsToObserver` | 切换到观战者（无数据） |
+| 0x22 | `YGOProCtosHsReady` | 准备（无数据） |
+| 0x23 | `YGOProCtosHsNotReady` | 取消准备（无数据） |
+| 0x24 | `YGOProCtosKick` | 踢人 |
+| 0x25 | `YGOProCtosHsStart` | 开始决斗（无数据） |
+| 0x30 | `YGOProCtosRequestField` | 请求场地信息（无数据） |
+
+### 特殊实现
+
+#### `YGOProCtosUpdateDeck` (0x02)
+- 使用 `ygopro-deck-encode` 库的 `YGOProDeck` 类
+- `fromUpdateDeckPayload()` 和 `toUpdateDeckPayload()` 方法
+- 成员：`deck: YGOProDeck`
+
+#### `YGOProCtosResponse` (0x01)
+- 直接存储原始字节数组
+- 用于游戏响应数据
+
+## STOC 协议实现
+
+实现了以下 STOC 协议（共 24 个）：
+
+| 标识符 | 类名 | 说明 |
+|--------|------|------|
+| 0x01 | `YGOProStocGameMsg` | 游戏消息（使用 YGOProMessages） |
+| 0x02 | `YGOProStocErrorMsg` | 错误消息 |
+| 0x03 | `YGOProStocSelectHand` | 选择猜拳（无数据） |
+| 0x04 | `YGOProStocSelectTp` | 选择先后手（无数据） |
+| 0x05 | `YGOProStocHandResult` | 猜拳结果 |
+| 0x06 | `YGOProStocTpResult` | 先后手结果（保留） |
+| 0x07 | `YGOProStocChangeSide` | 换边（无数据） |
+| 0x08 | `YGOProStocWaitingSide` | 等待换边（无数据） |
+| 0x09 | `YGOProStocDeckCount` | 卡组数量 |
+| 0x11 | `YGOProStocCreateGame` | 创建房间（保留） |
+| 0x12 | `YGOProStocJoinGame` | 加入房间 |
+| 0x13 | `YGOProStocTypeChange` | 类型变更 |
+| 0x14 | `YGOProStocLeaveGame` | 离开房间（保留） |
+| 0x15 | `YGOProStocDuelStart` | 决斗开始（无数据） |
+| 0x16 | `YGOProStocDuelEnd` | 决斗结束（无数据） |
+| 0x17 | `YGOProStocReplay` | 录像（使用 ygopro-yrp-encode） |
+| 0x18 | `YGOProStocTimeLimit` | 时间限制 |
+| 0x19 | `YGOProStocChat` | 聊天消息 |
+| 0x20 | `YGOProStocHsPlayerEnter` | 玩家进入 |
+| 0x21 | `YGOProStocHsPlayerChange` | 玩家状态变更 |
+| 0x22 | `YGOProStocHsWatchChange` | 观战者数量变更 |
+| 0x23 | `YGOProStocTeammateSurrender` | 队友认输（无数据） |
+| 0x30 | `YGOProStocFieldFinish` | 场地同步完成（无数据） |
+| 0x31 | `YGOProStocSrvproRoomlist` | 房间列表（SRVPro 服务器） |
+
+### 特殊实现
+
+#### `YGOProStocSrvproRoomlist` (0x31)
+- SRVPro 服务器特定协议，用于返回房间列表
+- 结构：
+  ```typescript
+  export class SrvproRoomInfo {
+    roomname: string;          // UTF-8, 64 bytes
+    room_status: number;       // uint8_t (0=Waiting, 1=Dueling, 2=Siding)
+    room_duel_count: number;   // int8_t
+    room_turn_count: number;   // int8_t
+    player1: string;           // UTF-8, 128 bytes
+    player1_score: number;     // int8_t
+    player1_lp: number;        // int32_t
+    player2: string;           // UTF-8, 128 bytes
+    player2_score: number;     // int8_t
+    player2_lp: number;        // int32_t
+  }
+  
+  export class YGOProStocSrvproRoomlist {
+    count: number;             // uint16_t
+    rooms: SrvproRoomInfo[];   // 房间数组
+  }
+  ```
+- 每个房间信息大小：333 字节（64 + 1 + 1 + 1 + 128 + 1 + 4 + 128 + 1 + 4）
+
+#### `YGOProStocGameMsg` (0x01)
+- 使用 `YGOProMessages` registry 解析 MSG 协议
+- 成员：`msg: YGOProMsgBase | undefined`
+- 自动解析和序列化 MSG 协议消息
+
+#### `YGOProStocReplay` (0x17)
+- 使用 `ygopro-yrp-encode` 库的 `YGOProYrp` 类
+- `fromYrp()` 和 `toYrp()` 方法
+- 成员：`replay: YGOProYrp`
+
+## 使用示例
+
+### CTOS 协议使用
+
+```typescript
+import { YGOProCtos, YGOProCtosPlayerInfo } from 'ygopro-msg-encode';
+
+// 创建协议对象
+const playerInfo = new YGOProCtosPlayerInfo();
+playerInfo.name = [0x0041, 0x0042, ...]; // UTF-16 字符数组
+
+// 序列化
+const payload = playerInfo.toPayload();
+
+// 解析
+const parsed = YGOProCtos.getInstanceFromPayload(payload);
+```
+
+### STOC 协议使用
+
+```typescript
+import { YGOProStoc, YGOProStocGameMsg, YGOProMsgHint } from 'ygopro-msg-encode';
+
+// 创建游戏消息
+const gameMsg = new YGOProStocGameMsg();
+const hint = new YGOProMsgHint();
+hint.type = 1;
+hint.player = 0;
+hint.desc = 0x1234;
+gameMsg.msg = hint;
+
+// 序列化
+const payload = gameMsg.toPayload();
+
+// 解析
+const parsed = YGOProStoc.getInstanceFromPayload(payload);
+```
+
+### UpdateDeck 使用
+
+```typescript
+import { YGOProCtosUpdateDeck } from 'ygopro-msg-encode';
+import YGOProDeck from 'ygopro-deck-encode';
+
+// 创建
+const updateDeck = new YGOProCtosUpdateDeck();
+updateDeck.deck = new YGOProDeck({
+  main: [12345, 67890],
+  extra: [11111],
+  side: [22222],
+});
+
+// 序列化
+const payload = updateDeck.toPayload();
+
+// 解析
+const parsed = new YGOProCtosUpdateDeck().fromPayload(payload.slice(3)); // 去掉 header
+```
+
+### Replay 使用
+
+```typescript
+import { YGOProStocReplay } from 'ygopro-msg-encode';
+import { YGOProYrp } from 'ygopro-yrp-encode';
+
+// 创建
+const replay = new YGOProStocReplay();
+replay.replay = new YGOProYrp({
+  hostName: 'Player1',
+  clientName: 'Player2',
+  // ... 其他字段
+});
+
+// 序列化
+const payload = replay.toPayload();
+```
+
+## 注意事项
+
+### Struct Padding
+C++ 结构体的 padding 已经在各个类中正确处理：
+- `HostInfo`: 字节 9-11 是 padding
+- `CTOS_JoinGame`: 字节 2-3 是 padding
+- `STOC_ErrorMsg`: 字节 1-3 是 padding
+- `STOC_TimeLimit`: 字节 1 是 padding
+- `STOC_HS_PlayerEnter`: 实际大小 41 字节（有 workaround）
+
+### 数组字段
+- 固定长度数组使用 `@BinaryField('u16', offset, length)`
+- UTF-16 字符串使用 `@BinaryField('utf16', offset, length)`
+- 不使用 `u16[]` 这种写法
+
+### 无数据协议
+多个协议（如 `LEAVE_GAME`, `SURRENDER` 等）没有正文数据，只有 header。
+
+## 依赖库
+
+- `ygopro-deck-encode`: 卡组编解码
+- `ygopro-yrp-encode`: 录像编解码
+
+## 测试
+
+运行测试脚本：
+```bash
+npm run build
+node dist/test-ctos-stoc.cjs
+```
+
+或直接使用 TypeScript：
+```bash
+npx tsx test-ctos-stoc.ts
+```