@lzpenguin/server 1.0.10 → 1.1.1

package/README.md

@@ -13,10 +13,11 @@ npm install @lzpenguin/server
 ```javascript
 import { RiffleServer } from '@lzpenguin/server';
 
+// post_id 和 token 会自动从浏览器 URL 参数中读取
+// 例如：https://example.com/game.html?post_id=123456&token=your-token-here
 const server = new RiffleServer({
   url: 'wss://api.riffle.app',
-  postId: 123456,
-  token: 'your-token-here'
+  timestamp: 'timestamp given in the context'  // 游戏时间戳，用于判断是否需要重新初始化
 });
 
 // 监听数据更新
@@ -28,7 +29,6 @@ server.onData((data) => {
 
 // 初始化服务器
 server.init({
-  hash: 'game-version-hash-123',
   world: { score: 0, level: 1 },
   self: {
     public: { name: 'Player1', x: 100, y: 100 }
@@ -42,97 +42,23 @@ server.init({
 
 ```javascript
 new RiffleServer({
-  url: 'wss://api.riffle.app',  // 必需：WebSocket 服务器 URL
-  postId: 123456,                // 必需：游戏贴文 ID
-  token: 'your-token-here',      // 必需：认证 token
+  url: 'wss://api.riffle.app',   // 必需：WebSocket 服务器 URL
+  timestamp: 'timestamp given in the context',         // 必需：游戏时间戳（用于判断是否需要重新初始化，新 timestamp 必须大于旧的才会重置）
   autoReconnect: true,           // 可选：是否自动重连，默认 true
   reconnectInterval: 3000        // 可选：重连间隔（毫秒），默认 3000
 })
-```
-
-## API 方法
-
-### 细粒度操作 API（推荐）
-
-#### World 数据操作
-
-```javascript
-// 添加/设置单个键值对
-server.world.add('score', 100);
-server.world.update('level', 2);
-
-// 删除键（设置为 null）
-server.world.delete('oldKey');
-
-// 批量设置
-server.world.set({ 
-  score: 100, 
-  level: 2, 
-  players: 10 
-});
-```
-
-#### Self 数据操作
-
-```javascript
-// 添加/设置单个键值对
-server.self.add('x', 150);
-server.self.update('y', 250);
-
-// 删除键（设置为 null）
-server.self.delete('oldProp');
-
-// 批量设置
-server.self.set({ 
-  x: 150, 
-  y: 250, 
-  rotation: 90 
-});
-```
-
-#### 完整示例
-
-```javascript
-import { RiffleServer } from '@lzpenguin/server';
-
-const server = new RiffleServer({
-  url: 'wss://api.riffle.app',
-  postId: 123456,
-  token: 'your-token-here'
-});
-
-// 监听数据更新
-server.onData((data) => {
-  console.log('World:', data.world);
-  console.log('Self:', data.self);
-  console.log('Players:', data.players);
-});
-
-// 初始化
-server.init({
-  hash: 'v1.0.0',
-  world: { score: 0, level: 1 },
-  self: { public: { name: 'Player1', x: 0, y: 0 } }
-});
-
-// 使用细粒度 API 更新数据
-server.world.update('score', 100);       // 更新分数
-server.self.update('x', 150);            // 更新 X 坐标
-server.self.update('y', 250);            // 更新 Y 坐标
-
-// 批量更新
-server.self.set({ x: 200, y: 300, rotation: 45 });
+// 注意：post_id 和 token 会自动从浏览器 URL 参数中读取
+// 页面 URL 格式：https://example.com/game.html?post_id=123456&token=your-token-here
 ```
 
 ## 三种消息类型
 
 ### 1. init() - 初始化服务器
 
-初始化服务器（必需，连接后必须先调用）。hash 相同则返回现有数据，hash 不同则删除旧服务器并重新创建。
+初始化服务器（必需，连接后必须先调用）。timestamp（在构造函数中传入）比现有的大则删除旧服务器并重新创建，否则返回现有数据。
 
 ```javascript
 server.init({
-  hash: 'game-version-hash-123',  // 必需：游戏版本哈希值
   world: { score: 0, level: 1 },   // 可选：世界初始数据
   self: {
     public: { name: 'Player1', x: 100, y: 100 }     // 可选：公开数据
@@ -153,14 +79,47 @@ server.init({
 
 **注意：** `self` 和 `players[i]` 现在具有相同的结构，都只包含公开数据。
 
-**关于 hash：**
-- **hash 相同**：传入的值不生效，直接返回现有数据
-- **hash 不同**：删除旧服务器并重新创建，使用传入的值初始化数据
-- **何时更新 hash**：如果更改了游戏，且改动了角色或世界字段的设计（如新增/删除字段、改变字段类型），就需要更新 hash 让服务器重新初始化，避免数据结构不兼容
+**关于 timestamp：**
+- **timestamp 较小或相等**：传入的值不生效，直接返回现有数据
+- **timestamp 较大**：删除旧服务器并重新创建，使用传入的值初始化数据
+- **何时更新 timestamp**：如果更改了游戏，且改动了角色或世界字段的设计（如新增/删除字段、改变字段类型），就需要使用更大的 timestamp（上下文中会给出当前编辑时的timestamp）让服务器重新初始化，避免数据结构不兼容
 
 **注意：** init 成功后服务器每 0.2 秒自动推送最新数据
 
-### 2. onData() - 监听数据推送
+### 2. update() - 更新数据
+
+部分更新数据（合并到现有数据，不替换）。
+
+```javascript
+// 更新世界数据
+server.update({ world: { score: 200 } });
+
+// 更新玩家数据
+server.update({
+  self: {
+    public: { x: 15, y: 25, rotation: 90 }
+  }
+});
+
+// 同时更新世界和玩家数据
+server.update({
+  world: { score: 200 },
+  self: { public: { x: 15, y: 25 } }
+});
+```
+
+**响应数据（通过 onData 接收）：**
+```json
+{
+  "world": { "score": 200, "level": 1 },
+  "self": { "name": "Player1", "x": 15, "y": 25, "rotation": 90 },
+  "players": [{ "name": "Player2", "x": 10, "y": 20 }]
+}
+```
+
+**注意：** 只更新提供的字段，未提供的字段保持不变，更新后立即推送最新数据
+
+### 3. onData() - 监听数据推送
 
 监听服务器推送的最新数据。init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送。
 
@@ -198,10 +157,10 @@ unsubscribe();
 ```javascript
 import { RiffleServer } from '@lzpenguin/server';
 
+// post_id 和 token 会自动从浏览器 URL 参数中读取
 const server = new RiffleServer({
   url: 'wss://api.riffle.app',
-  postId: 123456,
-  token: 'your-token-here'
+  timestamp: 'timestamp given in the context'
 });
 
 // 监听服务器推送，更新游戏状态
@@ -223,7 +182,6 @@ server.onData((data) => {
 
 // 初始化游戏
 server.init({
-  hash: 'v1.0.0',
   world: { score: 0, level: 1 },
   self: {
     public: { name: 'Player1', x: 0, y: 0 }
@@ -232,12 +190,18 @@ server.init({
 
 // 更新玩家位置
 function movePlayer(x, y) {
-  server.self.set({ x, y });
+  server.update({
+    self: {
+      public: { x, y }
+    }
+  });
 }
 
 // 更新分数
 function updateScore(score) {
-  server.world.update('score', score);
+  server.update({
+    world: { score }
+  });
 }
 ```
 

package/index.d.ts

@@ -8,10 +8,8 @@
 export interface RiffleServerOptions {
   /** WebSocket 服务器 URL */
   url: string;
-  /** 游戏贴文 ID */
-  postId: number;
-  /** 认证 token */
-  token: string;
+  /** 游戏时间戳（用于判断是否需要重新初始化，新 timestamp 必须大于旧的才会重置） */
+  timestamp: number;
   /** 是否自动重连，默认 true */
   autoReconnect?: boolean;
   /** 重连间隔（毫秒），默认 3000 */
@@ -33,8 +31,6 @@ export interface PlayerSelfData {
  * 初始化数据
  */
 export interface InitData {
-  /** 游戏版本哈希值（必需） */
-  hash: string;
   /** 世界初始数据（可选） */
   world?: Record<string, any>;
   /** 玩家初始数据（可选） */
@@ -63,68 +59,6 @@ export interface ServerData {
   players: Array<Record<string, any>>;
 }
 
-/**
- * WorldManager - 管理 world 数据的细粒度操作
- */
-export class WorldManager {
-  /**
-   * 添加或设置 world 中的键值对
-   * @param key 键名
-   * @param value 值
-   */
-  add(key: string, value: any): void;
-
-  /**
-   * 更新 world 中的键值对（与 add 相同，提供语义化接口）
-   * @param key 键名
-   * @param value 值
-   */
-  update(key: string, value: any): void;
-
-  /**
-   * 删除 world 中的键（通过设置为 null）
-   * @param key 键名
-   */
-  delete(key: string): void;
-
-  /**
-   * 批量设置多个键值对
-   * @param data 键值对对象
-   */
-  set(data: Record<string, any>): void;
-}
-
-/**
- * SelfManager - 管理 self 数据的细粒度操作
- */
-export class SelfManager {
-  /**
-   * 添加或设置 self.public 中的键值对
-   * @param key 键名
-   * @param value 值
-   */
-  add(key: string, value: any): void;
-
-  /**
-   * 更新 self.public 中的键值对（与 add 相同，提供语义化接口）
-   * @param key 键名
-   * @param value 值
-   */
-  update(key: string, value: any): void;
-
-  /**
-   * 删除 self.public 中的键（通过设置为 null）
-   * @param key 键名
-   */
-  delete(key: string): void;
-
-  /**
-   * 批量设置多个键值对
-   * @param data 键值对对象
-   */
-  set(data: Record<string, any>): void;
-}
-
 /**
  * RiffleServer - 游戏服务器 WebSocket 客户端
  */
@@ -142,17 +76,18 @@ export class RiffleServer {
   /** 是否已初始化 */
   readonly isInitialized: boolean;
 
-  /** World 数据管理器 */
-  readonly world: WorldManager;
-  /** Self 数据管理器 */
-  readonly self: SelfManager;
-
   /**
    * 初始化服务器（必需，连接后必须先调用）
    * @param initData 初始化数据
    */
   init(initData: InitData): void;
 
+  /**
+   * 更新数据（部分更新，合并到现有数据）
+   * @param updateData 更新数据
+   */
+  update(updateData: UpdateData): void;
+
   /**
    * 监听服务器推送的最新数据
    * @param callback 回调函数，接收服务器推送的数据

package/index.js

@@ -28,160 +28,88 @@ if (typeof window !== 'undefined' && window.WebSocket) {
   }
 }
 
-/**
- * WorldManager - 管理 world 数据的细粒度操作
- */
-class WorldManager {
-  constructor(server) {
-    this._server = server;
-  }
-
-  /**
-   * 添加或设置 world 中的键值对
-   * @param {string} key - 键名
-   * @param {any} value - 值
-   */
-  add(key, value) {
-    this._server.sendUpdate({ world: { [key]: value } });
-  }
-
-  /**
-   * 更新 world 中的键值对（与 add 相同，提供语义化接口）
-   * @param {string} key - 键名
-   * @param {any} value - 值
-   */
-  update(key, value) {
-    this._server.sendUpdate({ world: { [key]: value } });
-  }
-
-  /**
-   * 删除 world 中的键（通过设置为 null）
-   * @param {string} key - 键名
-   */
-  delete(key) {
-    this._server.sendUpdate({ world: { [key]: null } });
-  }
-
-  /**
-   * 批量设置多个键值对
-   * @param {Object} data - 键值对对象
-   */
-  set(data) {
-    this._server.sendUpdate({ world: data });
-  }
-}
-
-/**
- * SelfManager - 管理 self 数据的细粒度操作
- */
-class SelfManager {
-  constructor(server) {
-    this._server = server;
-  }
-
-  /**
-   * 添加或设置 self.public 中的键值对
-   * @param {string} key - 键名
-   * @param {any} value - 值
-   */
-  add(key, value) {
-    this._server.sendUpdate({ self: { public: { [key]: value } } });
-  }
-
-  /**
-   * 更新 self.public 中的键值对（与 add 相同，提供语义化接口）
-   * @param {string} key - 键名
-   * @param {any} value - 值
-   */
-  update(key, value) {
-    this._server.sendUpdate({ self: { public: { [key]: value } } });
-  }
-
-  /**
-   * 删除 self.public 中的键（通过设置为 null）
-   * @param {string} key - 键名
-   */
-  delete(key) {
-    this._server.sendUpdate({ self: { public: { [key]: null } } });
-  }
-
-  /**
-   * 批量设置多个键值对
-   * @param {Object} data - 键值对对象
-   */
-  set(data) {
-    this._server.sendUpdate({ self: { public: data } });
-  }
-}
-
 /**
  * RiffleServer - 游戏服务器 WebSocket 客户端
  * 
  * @example
  * ```js
- * import { RiffleServer } from '@lzpenguin/server';
+ * import { RiffleServer } from '@riffle/server';
  * 
  * const server = new RiffleServer({
  *   url: 'wss://api.riffle.app',
- *   postId: 123456,
- *   token: 'your-token-here'
+ *   timestamp: Date.now()
+ *   // post_id 和 token 会自动从浏览器 URL 参数中读取
+ *   // 例如：https://example.com/game.html?post_id=123456&token=xxx
  * });
  * 
  * // 监听服务器推送的最新数据
  * server.onData((data) => {
  *   console.log('World:', data.world);
- *   console.log('Self:', data.self);
+ *   console.log('Self:', data.self);          // self 现在直接是公开数据，与 players[i] 结构一致
  *   console.log('Players:', data.players);
  * });
  * 
  * // 初始化服务器（必需，连接后必须先调用）
  * server.init({
- *   hash: 'game-version-hash-123',
- *   world: { score: 0, level: 1 },
+ *   hash: 'game-version-hash-123',  // 游戏版本哈希值
+ *   world: { score: 0, level: 1 },   // 世界初始数据（可选）
  *   self: {
- *     public: { name: 'Player1', x: 100, y: 100 }
+ *     public: { name: 'Player1', x: 100, y: 100 }   // 公开数据（可选）
  *   }
  * });
  * 
- * // 新的细粒度操作 API
- * server.world.add('score', 200);           // 添加/更新 world.score
- * server.world.update('level', 2);          // 更新 world.level
- * server.world.delete('oldKey');            // 删除 world.oldKey
- * 
- * server.self.add('x', 150);                // 添加/更新 self.public.x
- * server.self.update('y', 250);             // 更新 self.public.y
- * server.self.delete('oldProp');            // 删除 self.public.oldProp
- * 
- * // 批量操作
- * server.world.set({ score: 200, level: 2 });
- * server.self.set({ x: 150, y: 250, rotation: 90 });
+ * // 更新数据
+ * server.update({ 
+ *   world: { score: 200 },
+ *   self: { 
+ *     public: { x: 15, y: 25, rotation: 90 }
+ *   }
+ * });
  * ```
  */
 export class RiffleServer {
   /**
    * @param {Object} options - 配置选项
-   * @param {string} options.url - WebSocket 服务器 URL（例如：'wss://api.riffle.app' 或 'ws://localhost:8000'）
-   * @param {number} options.postId - 游戏贴文 ID
-   * @param {string} options.token - 认证 token
+   * @param {string} options.url - WebSocket 服务器 URL（例如：'wss://api.riffle.app'）
+   * @param {number} options.timestamp - 游戏时间戳（用于判断是否需要重新初始化，新 timestamp 必须大于旧的才会重置）
    * @param {boolean} [options.autoReconnect=true] - 是否自动重连
    * @param {number} [options.reconnectInterval=3000] - 重连间隔（毫秒）
    */
   constructor(options) {
-    const { url, postId, token, autoReconnect = true, reconnectInterval = 3000 } = options;
+    const { url, timestamp, autoReconnect = true, reconnectInterval = 3000 } = options;
 
     if (!url) {
       throw new Error('URL is required');
     }
+    if (!timestamp) {
+      throw new Error('timestamp is required');
+    }
+
+    // 从浏览器 URL 参数中读取 post_id 和 token
+    let postId;
+    let token;
+
+    if (isBrowser && typeof window !== 'undefined' && window.location) {
+      const urlParams = new URLSearchParams(window.location.search);
+      if (urlParams.has('post_id')) {
+        postId = parseInt(urlParams.get('post_id'), 10);
+      }
+      if (urlParams.has('token')) {
+        token = urlParams.get('token');
+      }
+    }
+
     if (!postId) {
-      throw new Error('postId is required');
+      throw new Error('post_id not found in browser URL parameters. Please ensure URL contains ?post_id=xxx');
     }
     if (!token) {
-      throw new Error('token is required');
+      throw new Error('token not found in browser URL parameters. Please ensure URL contains &token=xxx');
     }
 
     this.url = url;
     this.postId = postId;
     this.token = token;
+    this.timestamp = timestamp;
     this.autoReconnect = autoReconnect;
     this.reconnectInterval = reconnectInterval;
 
@@ -196,10 +124,6 @@ export class RiffleServer {
     // 当前服务器数据缓存
     this.currentData = null;
 
-    // 创建细粒度操作管理器
-    this.world = new WorldManager(this);
-    this.self = new SelfManager(this);
-
     // 连接状态（异步调用，不阻塞构造函数）
     this.connect().catch(err => {
       console.error('[RiffleServer] Initial connection failed:', err);
@@ -359,7 +283,6 @@ export class RiffleServer {
   /**
    * 初始化服务器（必需，连接后必须先调用）
    * @param {Object} initData - 初始化数据
-   * @param {string} initData.hash - 游戏版本哈希值（必需）
    * @param {Object} [initData.world] - 世界初始数据（可选）
    * @param {Object} [initData.self] - 玩家初始数据（可选）
    * @param {Object} [initData.self.public] - 公开数据（可选，旧格式）
@@ -367,7 +290,6 @@ export class RiffleServer {
    * @example
    * // 推荐：直接传递公开数据
    * server.init({
-   *   hash: 'game-version-hash-123',
    *   world: { score: 0, level: 1 },
    *   self: { 
    *     public: { name: 'Player1', x: 100, y: 100 }
@@ -377,19 +299,13 @@ export class RiffleServer {
    * @example
    * // 也支持直接传递对象（服务端会将其作为 public 数据处理）
    * server.init({
-   *   hash: 'game-version-hash-123',
    *   world: { score: 0 },
    *   self: { 
    *     public: { name: 'Player1' }
    *   }
    * });
    */
-  init(initData) {
-    if (!initData || !initData.hash) {
-      console.error('[RiffleServer] hash is required for init');
-      return;
-    }
-
+  init(initData = {}) {
     // 如果还未连接，保存 init 请求，连接建立后自动执行
     if (!this.isConnected || this.ws?.readyState !== WebSocketImpl.OPEN) {
       console.log('[RiffleServer] Not connected yet, will init after connection');
@@ -409,7 +325,7 @@ export class RiffleServer {
   _doInit(initData) {
     try {
       const initMessage = {
-        hash: initData.hash,
+        timestamp: this.timestamp,
         world: initData.world || undefined,
         self: initData.self || undefined
       };
@@ -419,6 +335,25 @@ export class RiffleServer {
     }
   }
 
+  /**
+   * 更新数据（部分更新）
+   * @param {Object} updateData - 更新数据
+   * @param {Object} [updateData.world] - 世界数据（可选）
+   * @param {Object} [updateData.self] - 玩家数据（可选）
+   * @param {Object} [updateData.self.public] - 公开数据（可选）
+   * @param {Object} [updateData.self.private] - 私有数据（已弃用）
+   * @example
+   * server.update({
+   *   world: { score: 200 },
+   *   self: {
+   *     public: { x: 15, y: 25, rotation: 90 }
+   *   }
+   * });
+   */
+  update(updateData) {
+    this.sendUpdate(updateData);
+  }
+
   /**
    * 监听服务器推送的最新数据
    * @param {Function} callback - 回调函数，接收服务器推送的数据

package/package.json

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