ygopro-msg-encode 1.0.1

package/VARIABLE_LENGTH_STRINGS.md

@@ -0,0 +1,224 @@
+# 可变长度字符串协议实现说明
+
+## 概述
+
+以下三个协议使用了自定义的可变长度 UTF-16 字符串实现：
+1. `CTOS_CHAT` (0x16)
+2. `STOC_CHAT` (0x19)
+3. `CTOS_EXTERNAL_ADDRESS` (0x17)
+
+## 实现原则
+
+### 序列化（toPayload）
+- ✅ 只发送实际内容的字节数，不填充到最大长度
+- ✅ 在字符串末尾添加一个 UTF-16 null terminator (`\0\0`, 即 2 字节的 0)
+- ✅ 对于有前缀字段的协议（如 player_type, real_ip），先写入前缀字段
+
+### 反序列化（fromPayload）
+- ✅ 解析所有可用字节
+- ✅ 不要求末尾必须有 `\0\0`
+- ✅ 自动移除末尾的所有 null 字符
+- ✅ 对于有前缀字段的协议，先读取前缀字段，然后解析剩余字节为字符串
+
+## 协议详情
+
+### 1. CTOS_CHAT (0x16)
+
+**格式**: `[UTF-16LE 字符串]`
+
+```typescript
+export class YGOProCtosChat extends YGOProCtosBase {
+  static identifier = 0x16;
+  msg: string;
+}
+```
+
+**序列化示例**:
+- 原始消息: `"Hello"` (5 个字符)
+- 输出: 12 字节 = 5 字符 × 2 + 2 字节 null terminator
+- 字节序列: `[0x48, 0x00, 0x65, 0x00, 0x6C, 0x00, 0x6C, 0x00, 0x6F, 0x00, 0x00, 0x00]`
+
+**反序列化**:
+- 接受任意长度的 UTF-16LE 编码字节
+- 自动移除末尾的 null 字符
+
+### 2. STOC_CHAT (0x19)
+
+**格式**: `[player_type 2 bytes][UTF-16LE 字符串]`
+
+```typescript
+export class YGOProStocChat extends YGOProStocBase {
+  static identifier = 0x19;
+  player_type: number;  // uint16_t
+  msg: string;
+}
+```
+
+**序列化示例**:
+- player_type: `0x0010` (Observer + Player 0)
+- 原始消息: `"GG"` (2 个字符)
+- 输出: 8 字节 = 2 (player_type) + 2 字符 × 2 + 2 字节 null terminator
+- 字节序列: `[0x10, 0x00, 0x47, 0x00, 0x47, 0x00, 0x00, 0x00]`
+
+**反序列化**:
+- 前 2 字节: player_type (little endian)
+- 剩余字节: UTF-16LE 字符串（自动移除末尾 null）
+
+### 3. CTOS_EXTERNAL_ADDRESS (0x17)
+
+**格式**: `[real_ip 4 bytes][UTF-16LE 字符串]`
+
+```typescript
+export class YGOProCtosExternalAddress extends YGOProCtosBase {
+  static identifier = 0x17;
+  real_ip: string;      // IPv4 address as string (e.g., "127.0.0.1")
+  hostname: string;
+}
+```
+
+**序列化示例**:
+- real_ip: `"127.0.0.1"` (自动转换为网络序 0x7F000001)
+- 原始主机名: `"example.com"` (11 个字符)
+- 输出: 28 字节 = 4 (real_ip) + 11 字符 × 2 + 2 字节 null terminator
+- 字节序列: `[0x7F, 0x00, 0x00, 0x01, 0x65, 0x00, 0x78, 0x00, ...]`
+  - 注意：real_ip 使用**大端序（网络序）**
+
+**反序列化**:
+- 前 4 字节: real_ip (big endian / network byte order，自动转换为字符串)
+- 剩余字节: UTF-16LE 字符串（自动移除末尾 null）
+
+**IPv6 映射支持**:
+- 输入: `"::ffff:127.0.0.1"` → 自动提取为 `"127.0.0.1"`
+- 序列化时转换为标准 IPv4 格式
+
+## 优势
+
+### 节省带宽
+- ❌ 固定长度方式: CTOS_CHAT 总是发送 512 字节 (256 × 2)
+- ✅ 可变长度方式: "Hello" 只需 12 字节
+
+### 兼容性
+- ✅ 始终添加 null terminator，确保 C/C++ 字符串兼容
+- ✅ 解析时不要求 null terminator，适应各种数据源
+- ✅ 自动处理末尾 null 字符，避免显示问题
+
+## 对比表
+
+| 特性 | 固定长度实现 | 可变长度实现 |
+|------|--------------|--------------|
+| CTOS_CHAT 大小 | 512 bytes | 实际内容 × 2 + 2 |
+| STOC_CHAT 大小 | 514 bytes | 2 + 实际内容 × 2 + 2 |
+| EXTERNAL_ADDRESS 大小 | 516 bytes | 4 + 实际内容 × 2 + 2 |
+| real_ip 类型 | uint32_t | string (IPv4) |
+| real_ip 示例 | 0x7F000001 | "127.0.0.1" |
+| 带宽效率 | 低 | 高 |
+| Null terminator | 可选 | 始终添加 |
+| 解析灵活性 | 低 | 高 |
+
+## 测试
+
+运行测试脚本验证实现：
+
+```bash
+npx tsx test-chat-protocols.ts
+```
+
+测试内容：
+- ✅ CTOS_CHAT 序列化和反序列化
+- ✅ STOC_CHAT 序列化和反序列化
+- ✅ CTOS_EXTERNAL_ADDRESS 序列化和反序列化
+- ✅ 无 null terminator 的数据解析
+- ✅ 验证 null terminator 的存在
+- ✅ 验证前缀字段正确编码
+
+## 实现细节
+
+### UTF-16LE 编码
+
+使用 JavaScript 的 `TextDecoder` 和手动编码：
+
+```typescript
+// 编码
+const utf16 = new Uint16Array(text.length + 1);
+for (let i = 0; i < text.length; i++) {
+  utf16[i] = text.charCodeAt(i);
+}
+utf16[text.length] = 0; // null terminator
+const bytes = new Uint8Array(utf16.buffer);
+
+// 解码
+const decoder = new TextDecoder('utf-16le');
+const text = decoder.decode(data).replace(/\0+$/, '');
+```
+
+### 字节序（Byte Order）
+
+**Little Endian** - 用于 player_type：
+
+```typescript
+// 写入 uint16_t (little endian)
+result[0] = value & 0xff;
+result[1] = (value >> 8) & 0xff;
+```
+
+**Big Endian (Network Byte Order)** - 用于 real_ip：
+
+```typescript
+// 写入 uint32_t (big endian / network byte order)
+result[0] = (value >> 24) & 0xff;
+result[1] = (value >> 16) & 0xff;
+result[2] = (value >> 8) & 0xff;
+result[3] = value & 0xff;
+```
+
+⚠️ **重要**: `real_ip` 字段使用**网络字节序（大端序）**，这是 IPv4 地址的标准格式。
+
+### IPv4 字符串转换
+
+`CTOS_EXTERNAL_ADDRESS` 的 `real_ip` 字段使用字符串格式，自动处理转换：
+
+```typescript
+// IPv4 string to uint32 (network byte order)
+private ipToUint32(ip: string): number {
+  // Handle IPv6-mapped IPv4: "::ffff:127.0.0.1" -> "127.0.0.1"
+  let ipv4 = ip.startsWith('::ffff:') ? ip.substring(7) : ip;
+  
+  const parts = ipv4.split('.');
+  const bytes = parts.map(p => parseInt(p, 10));
+  
+  // Network byte order (big endian)
+  return (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];
+}
+
+// uint32 to IPv4 string
+private uint32ToIp(value: number): string {
+  const byte1 = (value >>> 24) & 0xff;
+  const byte2 = (value >>> 16) & 0xff;
+  const byte3 = (value >>> 8) & 0xff;
+  const byte4 = value & 0xff;
+  return `${byte1}.${byte2}.${byte3}.${byte4}`;
+}
+```
+
+**使用示例**:
+```typescript
+const ext = new YGOProCtosExternalAddress();
+ext.real_ip = "127.0.0.1";           // 标准 IPv4
+ext.real_ip = "::ffff:192.168.1.1";  // IPv6 映射的 IPv4
+
+const payload = ext.toPayload();
+// real_ip "127.0.0.1" → bytes [0x7F, 0x00, 0x00, 0x01]
+```
+
+## 注意事项
+
+1. **字符编码**: 仅支持 BMP（Basic Multilingual Plane）字符，不支持代理对（Surrogate Pairs）
+2. **最大长度**: 虽然是可变长度，但应该避免发送过长的字符串（建议 < 256 字符）
+3. **Null terminator**: 序列化时始终添加，但反序列化时不依赖它
+4. **空字符串**: 空字符串将被序列化为仅 2 字节的 null terminator
+5. **IPv4 格式**: `real_ip` 仅支持 IPv4 地址，IPv6 映射格式会自动提取 IPv4 部分
+6. **IP 验证**: 无效的 IP 地址（如 "abc.def"）会被转换为 `0.0.0.0`
+
+## 更新日期
+
+2026-02-02

package/VARIABLE_LENGTH_UPDATE.md

@@ -0,0 +1,229 @@
+# 可变长度字符串协议更新
+
+## 更新日期
+2026-02-02
+
+## 更新内容
+
+### 修改的协议
+
+将以下三个协议从固定长度实现改为可变长度实现：
+
+1. **CTOS_CHAT** (0x16)
+   - 文件: `src/protos/ctos/proto/chat.ts`
+   - 从: `@BinaryField('utf16', 0, 256)` 
+   - 到: 自定义 `fromPayload` / `toPayload` 实现
+
+2. **STOC_CHAT** (0x19)
+   - 文件: `src/protos/stoc/proto/chat.ts`
+   - 从: `@BinaryField('utf16', 2, 256)`
+   - 到: 自定义实现，先处理 `player_type`，再处理可变长度字符串
+
+3. **CTOS_EXTERNAL_ADDRESS** (0x17)
+   - 文件: `src/protos/ctos/proto/external-address.ts`
+   - 从: `@BinaryField('utf16', 4, 256)`
+   - 到: 自定义实现，先处理 `real_ip`，再处理可变长度字符串
+
+## 实现特性
+
+### 序列化（toPayload）
+```typescript
+// 1. 将字符串转换为 UTF-16LE
+// 2. 在末尾添加 null terminator (\0\0)
+// 3. 只发送实际内容长度，不填充到最大长度
+
+// 示例："Hello" → 12 bytes (不是 512 bytes)
+```
+
+### 反序列化（fromPayload）
+```typescript
+// 1. 读取所有可用字节
+// 2. 使用 TextDecoder('utf-16le') 解码
+// 3. 移除末尾的所有 null 字符
+// 4. 不要求末尾必须有 \0\0
+```
+
+## 带宽优化
+
+| 协议 | 固定长度 | 可变长度 (示例) | 节省 |
+|------|----------|-----------------|------|
+| CTOS_CHAT | 512 bytes | ~10-30 bytes | ~95% |
+| STOC_CHAT | 514 bytes | ~10-30 bytes | ~95% |
+| CTOS_EXTERNAL_ADDRESS | 516 bytes | ~20-50 bytes | ~90% |
+
+**实际示例**:
+- "Hello": 12 bytes vs 512 bytes (节省 97.7%)
+- "GG": 8 bytes vs 512 bytes (节省 98.4%)
+- "example.com": 28 bytes vs 516 bytes (节省 94.6%)
+
+## 代码对比
+
+### 之前 (固定长度)
+```typescript
+export class YGOProCtosChat extends YGOProCtosBase {
+  static identifier = 0x16;
+  
+  @BinaryField('utf16', 0, 256)
+  msg: string;
+}
+```
+- 总是序列化 512 字节
+- 浪费带宽
+- 简单但低效
+
+### 之后 (可变长度)
+```typescript
+export class YGOProCtosChat extends YGOProCtosBase {
+  static identifier = 0x16;
+  msg: string;
+  
+  fromPayload(data: Uint8Array): this {
+    const decoder = new TextDecoder('utf-16le');
+    this.msg = decoder.decode(data).replace(/\0+$/, '');
+    return this;
+  }
+  
+  toPayload(): Uint8Array {
+    // 编码为 UTF-16LE + null terminator
+    const utf16 = new Uint16Array(text.length + 1);
+    for (let i = 0; i < text.length; i++) {
+      utf16[i] = text.charCodeAt(i);
+    }
+    utf16[text.length] = 0; // null terminator
+    return new Uint8Array(utf16.buffer);
+  }
+}
+```
+- 只序列化实际内容
+- 高效利用带宽
+- 自定义但灵活
+
+## 兼容性
+
+### ✅ 向前兼容
+- 始终添加 null terminator，确保 C/C++ 代码可以正确读取
+- UTF-16LE 编码与原有实现一致
+
+### ✅ 向后兼容
+- 解析时不要求 null terminator，可以处理各种格式
+- 自动移除末尾 null 字符，避免显示问题
+
+### ✅ 多语言支持
+- UTF-16LE 编码支持所有 Unicode BMP 字符
+- 中文、日文、韩文等多语言无问题
+
+## 测试
+
+### 测试脚本
+`test-chat-protocols.ts` 包含以下测试：
+
+1. **CTOS_CHAT 测试**
+   - 序列化 "Hello World!"
+   - 验证 null terminator 存在
+   - 反序列化并验证内容
+
+2. **STOC_CHAT 测试**
+   - 序列化 player_type + "GG!"
+   - 验证 player_type 正确编码
+   - 验证 null terminator 存在
+   - 反序列化并验证内容
+
+3. **CTOS_EXTERNAL_ADDRESS 测试**
+   - 序列化 real_ip + "example.com"
+   - 验证 real_ip 正确编码
+   - 验证 null terminator 存在
+   - 反序列化并验证内容
+
+4. **无 null terminator 测试**
+   - 验证可以解析不带 null terminator 的数据
+   - 确保向后兼容
+
+### 运行测试
+```bash
+npx tsx test-chat-protocols.ts
+```
+
+## 构建结果
+
+```
+✅ 编译成功
+✅ 无 linter 错误
+✅ 无 TypeScript 错误
+
+文件大小:
+- dist/index.cjs: 154.6kb
+- dist/index.mjs: 144.4kb
+```
+
+## 影响范围
+
+### 修改的文件
+- `src/protos/ctos/proto/chat.ts` ✏️
+- `src/protos/stoc/proto/chat.ts` ✏️
+- `src/protos/ctos/proto/external-address.ts` ✏️
+
+### 新增的文件
+- `test-chat-protocols.ts` ✨
+- `VARIABLE_LENGTH_STRINGS.md` 📄
+- `VARIABLE_LENGTH_UPDATE.md` 📄 (本文件)
+
+### 更新的文件
+- `FINAL_SUMMARY.md` 📝
+
+## 技术细节
+
+### UTF-16LE 编码
+```typescript
+// 手动编码（避免依赖 TextEncoder 的 UTF-16 支持）
+const utf16 = new Uint16Array(text.length + 1);
+for (let i = 0; i < text.length; i++) {
+  utf16[i] = text.charCodeAt(i);
+}
+utf16[text.length] = 0; // null terminator
+const bytes = new Uint8Array(utf16.buffer);
+```
+
+### 多字节字段编码
+```typescript
+// Little Endian
+result[0] = value & 0xff;
+result[1] = (value >> 8) & 0xff;
+result[2] = (value >> 16) & 0xff;
+result[3] = (value >> 24) & 0xff;
+```
+
+### 解码
+```typescript
+// 使用浏览器/Node.js 内置 API
+const decoder = new TextDecoder('utf-16le');
+const text = decoder.decode(data).replace(/\0+$/, '');
+```
+
+## 性能影响
+
+### ✅ 优化
+- 减少网络传输字节数（节省 90-98%）
+- 减少内存占用
+- 更快的序列化/反序列化（处理的字节更少）
+
+### ⚠️ 注意
+- 自定义实现稍微增加了代码复杂度
+- 需要手动处理字符串编码（不使用装饰器）
+
+## 未来改进
+
+可能的未来改进方向：
+
+1. 支持 UTF-8 编码（更节省带宽）
+2. 支持代理对（Surrogate Pairs）处理 Unicode 扩展字符
+3. 添加最大长度限制检查
+4. 性能优化（缓存编码器）
+
+## 总结
+
+✅ **成功将三个协议改为可变长度实现**  
+✅ **大幅减少网络带宽使用（节省 90-98%）**  
+✅ **保持完全兼容性（向前和向后）**  
+✅ **所有测试通过，构建成功**  
+
+这次更新显著提升了这三个协议的效率，特别是在频繁发送聊天消息的场景下。