@lzpenguin/server 1.0.7 → 1.0.9

package/README.md

@@ -22,7 +22,7 @@ const server = new RiffleServer({
 // 监听数据更新
 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);
 });
 
@@ -31,8 +31,7 @@ server.init({
   hash: 'game-version-hash-123',
   world: { score: 0, level: 1 },
   self: {
-    public: { name: 'Player1' },
-    private: { health: 100 }
+    public: { name: 'Player1', x: 100, y: 100 }
   }
 });
 ```
@@ -51,6 +50,82 @@ new RiffleServer({
 })
 ```
 
+## API 方法
+
+### 细粒度操作 API（推荐）
+
+从 v1.1.0 起，提供了更细粒度的操作 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 });
+```
+
 ## 三种消息类型
 
 ### 1. init() - 初始化服务器
@@ -62,8 +137,7 @@ server.init({
   hash: 'game-version-hash-123',  // 必需：游戏版本哈希值
   world: { score: 0, level: 1 },   // 可选：世界初始数据
   self: {
-    public: { name: 'Player1' },     // 可选：公开数据
-    private: { health: 100 }         // 可选：私有数据
+    public: { name: 'Player1', x: 100, y: 100 }     // 可选：公开数据
   }
 });
 ```
@@ -72,16 +146,15 @@ server.init({
 ```json
 {
   "world": { "score": 0, "level": 1 },
-  "self": {
-    "public": { "name": "Player1" },
-    "private": { "health": 100 }
-  },
+  "self": { "name": "Player1", "x": 100, "y": 100 },
   "players": [
-    { "name": "Player2", "position": { "x": 10, "y": 20 } }
+    { "name": "Player2", "x": 10, "y": 20 }
   ]
 }
 ```
 
+**注意：** `self` 和 `players[i]` 现在具有相同的结构，都只包含公开数据。
+
 **关于 hash：**
 - **hash 相同**：传入的值不生效，直接返回现有数据
 - **hash 不同**：删除旧服务器并重新创建，使用传入的值初始化数据
@@ -89,44 +162,7 @@ server.init({
 
 **注意：** init 成功后服务器每 0.2 秒自动推送最新数据
 
-### 2. update() - 更新数据
-
-部分更新数据（合并到现有数据，不替换）。
-
-```javascript
-// 更新世界数据
-server.update({ world: { score: 200 } });
-
-// 更新玩家数据
-server.update({
-  self: {
-    public: { position: { x: 15, y: 25 } },
-    private: { health: 90 }
-  }
-});
-
-// 同时更新世界和玩家数据
-server.update({
-  world: { score: 200 },
-  self: { public: { position: { x: 15, y: 25 } } }
-});
-```
-
-**响应数据（通过 onData 接收）：**
-```json
-{
-  "world": { "score": 200, "level": 1 },
-  "self": {
-    "public": { "name": "Player1", "position": { "x": 15, "y": 25 } },
-    "private": { "health": 90, "mana": 50 }
-  },
-  "players": [{ "name": "Player2", "position": { "x": 10, "y": 20 } }]
-}
-```
-
-**注意：** 只更新提供的字段，未提供的字段保持不变，更新后立即推送最新数据
-
-### 3. onData() - 监听数据推送
+### 2. onData() - 监听数据推送
 
 监听服务器推送的最新数据。init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送。
 
@@ -145,17 +181,16 @@ unsubscribe();
 ```json
 {
   "world": { "score": 200, "level": 1 },
-  "self": {
-    "public": { "name": "Player1", "position": { "x": 15, "y": 25 } },
-    "private": { "health": 90, "mana": 50 }
-  },
+  "self": { "name": "Player1", "x": 15, "y": 25 },
   "players": [
-    { "name": "Player2", "position": { "x": 10, "y": 20 } },
-    { "name": "Player3", "position": { "x": 30, "y": 40 } }
+    { "name": "Player2", "x": 10, "y": 20 },
+    { "name": "Player3", "x": 30, "y": 40 }
   ]
 }
 ```
 
+**注意：** `self` 和 `players[i]` 具有相同的数据结构，都只包含公开数据。
+
 **推送时机：** init 响应、定时推送（每 0.2 秒）、init/update 后立即推送
 
 ## 联机游戏示例
@@ -173,8 +208,8 @@ const server = new RiffleServer({
 
 // 监听服务器推送，更新游戏状态
 server.onData((data) => {
-  // 更新自己的位置
-  const myPosition = data.self?.public?.position;
+  // 更新自己的位置（self 现在直接是公开数据对象）
+  const myPosition = { x: data.self.x, y: data.self.y };
   
   // 更新其他玩家列表
   const otherPlayers = data.players || [];
@@ -193,25 +228,18 @@ server.init({
   hash: 'v1.0.0',
   world: { score: 0, level: 1 },
   self: {
-    public: { name: 'Player1', position: { x: 0, y: 0 } },
-    private: { health: 100 }
+    public: { name: 'Player1', x: 0, y: 0 }
   }
 });
 
 // 更新玩家位置
 function movePlayer(x, y) {
-  server.update({
-    self: {
-      public: { position: { x, y } }
-    }
-  });
+  server.self.set({ x, y });
 }
 
 // 更新分数
 function updateScore(score) {
-  server.update({
-    world: { score }
-  });
+  server.world.update('score', score);
 }
 ```
 

package/index.d.ts

@@ -19,12 +19,13 @@ export interface RiffleServerOptions {
 }
 
 /**
- * 玩家数据
+ * 玩家数据（用于发送 init/update 请求）
+ * 注意：此格式仅用于客户端发送数据，服务端返回的 self 已不再使用此结构
  */
 export interface PlayerSelfData {
   /** 公开数据 */
   public?: Record<string, any>;
-  /** 私有数据 */
+  /** 私有数据（已弃用，服务端不再使用） */
   private?: Record<string, any>;
 }
 
@@ -56,12 +57,74 @@ export interface UpdateData {
 export interface ServerData {
   /** 世界数据 */
   world: Record<string, any>;
-  /** 当前玩家数据 */
-  self: PlayerSelfData;
+  /** 当前玩家数据（仅公开数据，与 players[i] 结构一致） */
+  self: Record<string, any>;
   /** 其他玩家列表（仅公开数据） */
   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 客户端
  */
@@ -79,18 +142,17 @@ 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,12 +28,98 @@ 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 '@riffle/server';
+ * import { RiffleServer } from '@lzpenguin/server';
  * 
  * const server = new RiffleServer({
  *   url: 'wss://api.riffle.app',
@@ -50,22 +136,25 @@ if (typeof window !== 'undefined' && window.WebSocket) {
  * 
  * // 初始化服务器（必需，连接后必须先调用）
  * 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' },   // 公开数据（可选）
- *     private: { health: 100 }      // 私有数据（可选）
+ *     public: { name: 'Player1', x: 100, y: 100 }
  *   }
  * });
  * 
- * // 更新数据
- * server.update({ 
- *   world: { score: 200 },
- *   self: { 
- *     public: { position: { x: 15, y: 25 } },
- *     private: { health: 90 }
- *   }
- * });
+ * // 新的细粒度操作 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 });
  * ```
  */
 export class RiffleServer {
@@ -107,6 +196,10 @@ 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);
@@ -269,15 +362,25 @@ export class RiffleServer {
    * @param {string} initData.hash - 游戏版本哈希值（必需）
    * @param {Object} [initData.world] - 世界初始数据（可选）
    * @param {Object} [initData.self] - 玩家初始数据（可选）
-   * @param {Object} [initData.self.public] - 公开数据（可选）
-   * @param {Object} [initData.self.private] - 私有数据（可选）
+   * @param {Object} [initData.self.public] - 公开数据（可选，旧格式）
+   * @param {Object} [initData.self.private] - 私有数据（已弃用）
    * @example
+   * // 推荐：直接传递公开数据
    * server.init({
    *   hash: 'game-version-hash-123',
    *   world: { score: 0, level: 1 },
-   *   self: {
-   *     public: { name: 'Player1' },
-   *     private: { health: 100 }
+   *   self: { 
+   *     public: { name: 'Player1', x: 100, y: 100 }
+   *   }
+   * });
+   * 
+   * @example
+   * // 也支持直接传递对象（服务端会将其作为 public 数据处理）
+   * server.init({
+   *   hash: 'game-version-hash-123',
+   *   world: { score: 0 },
+   *   self: { 
+   *     public: { name: 'Player1' }
    *   }
    * });
    */
@@ -316,26 +419,6 @@ 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: { position: { x: 15, y: 25 } },
-   *     private: { health: 90 }
-   *   }
-   * });
-   */
-  update(updateData) {
-    this.sendUpdate(updateData);
-  }
-
   /**
    * 监听服务器推送的最新数据
    * @param {Function} callback - 回调函数，接收服务器推送的数据
@@ -343,8 +426,11 @@ export class RiffleServer {
    * @example
    * const unsubscribe = 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);
+   *   
+   *   // 例如：data.self = { id: 'abc123', name: 'Player1', x: 100, y: 200 }
+   *   // 而 data.players[0] 也是相同结构：{ id: 'def456', name: 'Player2', x: 150, y: 250 }
    * });
    * 
    * // 取消监听

package/package.json

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