@lzpenguin/server 1.0.4 → 1.0.5

package/README.md

@@ -37,6 +37,80 @@ server.init({
 });
 ```
 
+## 新特性 🎉
+
+### 同步优化（v2.0+）
+
+我们对同步机制进行了全面优化，提供更可靠和高效的数据同步：
+
+#### 1. **时间戳和序列号**
+- ✅ 每条消息都包含服务器时间戳和序列号
+- ✅ 自动检测消息丢失和延迟警告
+- ✅ 确保数据按正确顺序处理
+- ✅ 实时显示网络延迟和序列号状态
+
+```javascript
+server.onData((data) => {
+  console.log('时间戳:', data.timestamp);
+  console.log('序列号:', data.sequence);
+  console.log('数据:', data.world);
+});
+```
+
+#### 2. **操作确认机制**
+- 支持回调确认每个更新操作
+- 自动超时检测（5秒）
+- 返回唯一操作ID用于追踪
+
+```javascript
+server.update({
+  world: { score: 100 }
+}, (error, result) => {
+  if (error) {
+    console.error('更新失败:', error);
+  } else {
+    console.log('更新已确认:', result);
+  }
+});
+```
+
+#### 3. **增量更新**
+- 只发送变化的数据，节省带宽
+- 支持数组追加操作
+- 特别适合笔画等增量数据
+
+```javascript
+server.updateDelta({
+  world: {
+    strokes: {
+      $append: [newStroke]  // 只追加新笔画
+    }
+  }
+}, (error, result) => {
+  console.log('增量更新完成');
+});
+```
+
+#### 4. **自适应推送频率**
+- 服务器根据活动情况动态调整推送频率
+- 高活动：50ms 推送一次
+- 中活动：100ms 推送一次
+- 低活动：200ms 推送一次
+- 无活动：500ms 推送一次
+
+#### 5. **统计信息**
+- 实时查看连接状态和同步统计
+- 监控消息丢失和延迟
+
+```javascript
+const stats = server.getStats();
+console.log('连接状态:', stats.connected);
+console.log('本地序列号:', stats.localSequence);
+console.log('最后接收序列号:', stats.lastReceivedSequence);
+console.log('待确认操作数:', stats.pendingOperations);
+console.log('更新次数:', stats.updateCount);
+```
+
 ## API
 
 ### 构造函数
@@ -94,9 +168,20 @@ server.init({
 部分更新数据（合并到现有数据，不替换）。
 
 ```javascript
-// 更新世界数据
+// 基本更新（不带确认）
 server.update({ world: { score: 200 } });
 
+// 带确认回调的更新（推荐）
+server.update({
+  world: { score: 200 }
+}, (error, result) => {
+  if (error) {
+    console.error('更新失败:', error);
+  } else {
+    console.log('更新已确认');
+  }
+});
+
 // 更新玩家数据
 server.update({
   self: {
@@ -112,6 +197,12 @@ server.update({
 });
 ```
 
+**参数：**
+- `updateData`: 要更新的数据对象
+- `callback` (可选): 确认回调函数 `(error, result) => {}`
+
+**返回值：** 操作ID（字符串），可用于追踪操作
+
 **响应数据（通过 onData 接收）：**
 ```json
 {
@@ -144,9 +235,11 @@ unsubscribe();
 **数据格式：**
 ```json
 {
+  "timestamp": 1705123456789,
+  "sequence": 42,
   "world": { "score": 200, "level": 1 },
   "self": {
-    "public": { "name": "Player1", "position": { "x": 15, "y": 25 } },
+    "public": { "name": "Player1", "position": { "x": 15, y: 25 } },
     "private": { "health": 90, "mana": 50 }
   },
   "players": [
@@ -156,6 +249,74 @@ unsubscribe();
 }
 ```
 
+**字段说明：**
+- `timestamp`: 服务器时间戳（毫秒）
+- `sequence`: 消息序列号（用于检测消息丢失）
+- `world`: 世界数据
+- `self`: 当前玩家数据
+- `players`: 其他玩家数据
+
+### 4. updateDelta() - 增量更新 ✨
+
+只发送变化的数据，适合频繁更新的场景（如画板笔画）。
+
+```javascript
+// 追加新笔画（不发送整个数组）
+const newStroke = {
+  id: 'stroke_123',
+  points: [{ x: 0, y: 0 }, { x: 10, y: 10 }],
+  color: '#FF0000',
+  width: 2
+};
+
+server.updateDelta({
+  world: {
+    strokes: {
+      $append: [newStroke]  // 使用 $append 标记表示追加
+    }
+  }
+}, (error, result) => {
+  if (!error) {
+    console.log('笔画已添加');
+  }
+});
+```
+
+**参数：**
+- `delta`: 增量数据对象（支持 `$append` 等特殊操作）
+- `callback` (可选): 确认回调函数
+
+**返回值：** 操作ID
+
+### 5. getStats() - 获取统计信息 ✨
+
+获取实时同步统计信息，用于监控和调试。
+
+```javascript
+const stats = server.getStats();
+console.log(stats);
+// {
+//   connected: true,
+//   initialized: true,
+//   localSequence: 10,
+//   lastReceivedSequence: 8,
+//   lastReceivedTimestamp: 1705123456789,
+//   pendingOperations: 2,
+//   updateCount: 10,
+//   lastUpdateTime: 1705123456789
+// }
+```
+
+**返回值：**
+- `connected`: 是否已连接
+- `initialized`: 是否已初始化
+- `localSequence`: 本地发送的序列号
+- `lastReceivedSequence`: 最后接收的序列号
+- `lastReceivedTimestamp`: 最后接收的时间戳
+- `pendingOperations`: 待确认的操作数量
+- `updateCount`: 总更新次数
+- `lastUpdateTime`: 最后更新时间
+
 **推送时机：** init 响应、定时推送（每 0.2 秒）、init/update 后立即推送
 
 ## 联机游戏示例

package/index.d.ts

@@ -54,6 +54,10 @@ export interface UpdateData {
  * 服务器推送的数据
  */
 export interface ServerData {
+  /** 服务器时间戳（毫秒） */
+  timestamp?: number;
+  /** 消息序列号 */
+  sequence?: number;
   /** 世界数据 */
   world: Record<string, any>;
   /** 当前玩家数据 */
@@ -62,6 +66,43 @@ export interface ServerData {
   players: Array<Record<string, any>>;
 }
 
+/**
+ * 增量更新数据
+ */
+export interface DeltaData {
+  /** 世界数据（支持 $append 等特殊操作） */
+  world?: Record<string, any>;
+  /** 玩家数据 */
+  self?: PlayerSelfData;
+}
+
+/**
+ * 统计信息
+ */
+export interface Stats {
+  /** 是否已连接 */
+  connected: boolean;
+  /** 是否已初始化 */
+  initialized: boolean;
+  /** 本地发送的序列号 */
+  localSequence: number;
+  /** 最后接收的序列号 */
+  lastReceivedSequence: number;
+  /** 最后接收的时间戳 */
+  lastReceivedTimestamp: number;
+  /** 待确认的操作数量 */
+  pendingOperations: number;
+  /** 总更新次数 */
+  updateCount: number;
+  /** 最后更新时间 */
+  lastUpdateTime: number;
+}
+
+/**
+ * 确认回调函数
+ */
+export type ConfirmCallback = (error: Error | null, result: { confirmed: boolean } | null) => void;
+
 /**
  * RiffleServer - 游戏服务器 WebSocket 客户端
  */
@@ -82,14 +123,43 @@ export class RiffleServer {
   /**
    * 初始化服务器（必需，连接后必须先调用）
    * @param initData 初始化数据
+   * @param callback 确认回调函数（可选）
+   * @returns 操作ID（如果已连接）
    */
-  init(initData: InitData): void;
+  init(initData: InitData, callback?: ConfirmCallback): string | undefined;
 
   /**
    * 更新数据（部分更新，合并到现有数据）
    * @param updateData 更新数据
+   * @param callback 确认回调函数（可选）
+   * @returns 操作ID
+   */
+  update(updateData: UpdateData, callback?: ConfirmCallback): string | null;
+
+  /**
+   * 增量更新（只发送变化的数据）
+   * @param delta 增量数据
+   * @param callback 确认回调函数（可选）
+   * @returns 操作ID
+   * @example
+   * ```typescript
+   * // 只追加新笔画，而不是发送整个数组
+   * server.updateDelta({
+   *   world: {
+   *     strokes: {
+   *       $append: [newStroke]
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  updateDelta(delta: DeltaData, callback?: ConfirmCallback): string | null;
+
+  /**
+   * 获取同步统计信息
+   * @returns 统计信息对象
    */
-  update(updateData: UpdateData): void;
+  getStats(): Stats;
 
   /**
    * 监听服务器推送的最新数据

package/index.js

@@ -177,39 +177,9 @@ export class RiffleServer {
               console.log('[RiffleServer] Initialized');
             }
             
-            // 合并服务器数据与当前缓存，避免丢失乐观更新的数据
-            // 策略：对于 world 数据，优先保留乐观更新（当前缓存），然后合并服务器数据
-            // 这样可以确保刚画的笔画不会因为服务器推送旧数据而丢失
-            if (this.currentData) {
-              const mergedData = {
-                // world 数据：先使用当前缓存（包含乐观更新），再合并服务器数据
-                // _deepMerge 会先保留 target（当前缓存）的所有数据，然后添加 source（服务器数据）中不存在的项
-                // 对于数组（如 strokes），会合并去重，确保不会丢失任何笔画
-                world: this._deepMerge(this.currentData.world || {}, message.world || {}),
-                // self 数据：服务器数据优先（因为服务器会合并所有玩家的更新）
-                // 但也要合并当前缓存，确保不丢失字段
-                self: {
-                  public: this._deepMerge(
-                    message.self?.public || {},
-                    this.currentData.self?.public || {}
-                  ),
-                  private: this._deepMerge(
-                    message.self?.private || {},
-                    this.currentData.self?.private || {}
-                  )
-                },
-                // players 列表使用服务器数据（其他玩家的数据）
-                players: message.players
-              };
-              
-              // 使用合并后的数据
-              this.currentData = mergedData;
-              this.dataCallbacks.forEach(cb => cb(mergedData));
-            } else {
-              // 如果没有缓存数据，直接使用服务器数据
-              this.currentData = message;
-              this.dataCallbacks.forEach(cb => cb(message));
-            }
+            // 更新缓存并触发数据回调
+            this.currentData = message;
+            this.dataCallbacks.forEach(cb => cb(message));
           }
         } catch (error) {
           console.error('[RiffleServer] Failed to parse message:', error);
@@ -270,58 +240,6 @@ export class RiffleServer {
     this.isConnected = false;
   }
 
-  /**
-   * 深度合并对象
-   * @private
-   * @param {Object} target - 目标对象（基础数据）
-   * @param {Object} source - 源对象（新数据，优先使用）
-   * @returns {Object} 合并后的对象
-   */
-  _deepMerge(target, source) {
-    if (!target) return source ? (Array.isArray(source) ? [...source] : { ...source }) : {};
-    if (!source) return target;
-    
-    // 处理数组：如果都是数组，合并去重（基于 JSON 字符串比较）
-    // 先保留 target 的所有项，然后添加 source 中不存在的项
-    // 这样可以确保不会丢失任何数据
-    if (Array.isArray(target) && Array.isArray(source)) {
-      const merged = [...target];
-      const targetStrings = new Set(target.map(item => JSON.stringify(item)));
-      for (const item of source) {
-        const itemStr = JSON.stringify(item);
-        if (!targetStrings.has(itemStr)) {
-          merged.push(item);
-          targetStrings.add(itemStr);
-        }
-      }
-      return merged;
-    }
-    
-    // 如果类型不匹配，使用源数据
-    if (Array.isArray(target) || Array.isArray(source)) {
-      return Array.isArray(source) ? [...source] : source;
-    }
-    
-    // 处理对象：递归合并
-    // 先复制 target，然后用 source 的值覆盖（但递归合并子对象）
-    const result = { ...target };
-    for (const key in source) {
-      if (source.hasOwnProperty(key)) {
-        const sourceValue = source[key];
-        const targetValue = target[key];
-        
-        // 如果源值是对象且不是数组，递归合并
-        if (sourceValue && typeof sourceValue === 'object' && !Array.isArray(sourceValue)) {
-          result[key] = this._deepMerge(targetValue, sourceValue);
-        } else {
-          // 否则使用源值（优先使用新数据）
-          result[key] = sourceValue;
-        }
-      }
-    }
-    return result;
-  }
-
   /**
    * 发送更新请求
    * @private
@@ -338,38 +256,6 @@ export class RiffleServer {
       return;
     }
 
-    // 乐观更新：立即更新本地缓存并触发回调
-    if (this.currentData) {
-      const optimisticData = { ...this.currentData };
-      
-      // 合并 world 数据
-      if (updateData.world) {
-        optimisticData.world = this._deepMerge(this.currentData.world || {}, updateData.world);
-      }
-      
-      // 合并 self 数据
-      if (updateData.self) {
-        optimisticData.self = { ...this.currentData.self };
-        if (updateData.self.public) {
-          optimisticData.self.public = this._deepMerge(
-            this.currentData.self?.public || {},
-            updateData.self.public
-          );
-        }
-        if (updateData.self.private) {
-          optimisticData.self.private = this._deepMerge(
-            this.currentData.self?.private || {},
-            updateData.self.private
-          );
-        }
-      }
-      
-      // 更新缓存并立即触发回调（乐观更新）
-      this.currentData = optimisticData;
-      this.dataCallbacks.forEach(cb => cb(optimisticData));
-    }
-
-    // 发送更新请求到服务器
     try {
       this.ws.send(JSON.stringify(updateData));
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzpenguin/server",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Riffle 游戏服务器 WebSocket 客户端 SDK",
   "license": "ISC",
   "author": "lzpenguin",