@lzpenguin/server 1.1.1 → 1.1.2

package/README.md

@@ -13,195 +13,145 @@ 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
+// 创建服务器实例
+// 注意：post_id 和 token 会自动从 URL 参数中读取
+// URL 格式：https://example.com/game.html?post_id=123456&token=your-token
 const server = new RiffleServer({
-  url: 'wss://api.riffle.app',
-  timestamp: 'timestamp given in the context'  // 游戏时间戳，用于判断是否需要重新初始化
+  url: 'wss://api.riffle.app',   // 必需：WebSocket 服务器地址
+  timestamp: 1234567890,         // 必需：游戏时间戳（数字类型），直接使用上下文中给出的值
+  autoReconnect: true,           // 可选：自动重连，默认 true
+  reconnectInterval: 3000        // 可选：重连间隔（毫秒），默认 3000
 });
 
-// 监听数据更新
+// 1. 监听数据推送（init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送）
 server.onData((data) => {
-  console.log('World:', data.world);
-  console.log('Self:', data.self);      // self 现在直接是公开数据，与 players[i] 结构一致
-  console.log('Players:', data.players);
+  console.log('World:', data.world);      // 世界数据
+  console.log('Self:', data.self);        // 自己的公开数据
+  console.log('Players:', data.players);  // 其他玩家的公开数据
+  // 注意：self 和 players[i] 结构相同，都只包含公开数据
 });
 
-// 初始化服务器
+// 2. 初始化服务器（必需，连接后必须先调用）
 server.init({
   world: { score: 0, level: 1 },
   self: {
     public: { name: 'Player1', x: 100, y: 100 }
   }
 });
-```
-
-## API
 
-### 构造函数
-
-```javascript
-new RiffleServer({
-  url: 'wss://api.riffle.app',   // 必需：WebSocket 服务器 URL
-  timestamp: 'timestamp given in the context',         // 必需：游戏时间戳（用于判断是否需要重新初始化，新 timestamp 必须大于旧的才会重置）
-  autoReconnect: true,           // 可选：是否自动重连，默认 true
-  reconnectInterval: 3000        // 可选：重连间隔（毫秒），默认 3000
-})
-// 注意：post_id 和 token 会自动从浏览器 URL 参数中读取
-// 页面 URL 格式：https://example.com/game.html?post_id=123456&token=your-token-here
+// 3. 更新数据（部分更新，合并到现有数据）
+server.update({
+  world: { score: 200 },
+  self: { public: { x: 150, y: 150 } }
+});
 ```
 
-## 三种消息类型
+## 数据格式
 
-### 1. init() - 初始化服务器
-
-初始化服务器（必需，连接后必须先调用）。timestamp（在构造函数中传入）比现有的大则删除旧服务器并重新创建，否则返回现有数据。
-
-```javascript
-server.init({
-  world: { score: 0, level: 1 },   // 可选：世界初始数据
-  self: {
-    public: { name: 'Player1', x: 100, y: 100 }     // 可选：公开数据
-  }
-});
-```
+服务器推送的数据格式（通过 `onData` 接收）：
 
-**响应数据（通过 onData 接收）：**
 ```json
 {
   "world": { "score": 0, "level": 1 },
   "self": { "name": "Player1", "x": 100, "y": 100 },
   "players": [
-    { "name": "Player2", "x": 10, "y": 20 }
+    { "name": "Player2", "x": 10, "y": 20 },
+    { "name": "Player3", "x": 30, "y": 40 }
   ]
 }
 ```
 
-**注意：** `self` 和 `players[i]` 现在具有相同的结构，都只包含公开数据。
+## API 说明
+
+### init(data) - 初始化服务器
 
-**关于 timestamp：**
-- **timestamp 较小或相等**：传入的值不生效，直接返回现有数据
-- **timestamp 较大**：删除旧服务器并重新创建，使用传入的值初始化数据
-- **何时更新 timestamp**：如果更改了游戏，且改动了角色或世界字段的设计（如新增/删除字段、改变字段类型），就需要使用更大的 timestamp（上下文中会给出当前编辑时的timestamp）让服务器重新初始化，避免数据结构不兼容
+必需，连接后必须先调用。根据 timestamp 判断是否重新初始化。
 
-**注意：** init 成功后服务器每 0.2 秒自动推送最新数据
+```javascript
+server.init({
+  world: { score: 0, level: 1 },   // 可选：世界初始数据
+  self: {
+    public: { name: 'Player1', x: 100, y: 100 }  // 可选：玩家公开数据
+  }
+});
+```
 
-### 2. update() - 更新数据
+### update(data) - 更新数据
 
-部分更新数据（合并到现有数据，不替换）。
+部分更新数据（合并，不替换）。只更新提供的字段，未提供的字段保持不变。
 
 ```javascript
 // 更新世界数据
 server.update({ world: { score: 200 } });
 
 // 更新玩家数据
-server.update({
-  self: {
-    public: { x: 15, y: 25, rotation: 90 }
-  }
-});
+server.update({ self: { public: { x: 15, y: 25 } } });
 
-// 同时更新世界和玩家数据
+// 同时更新
 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() - 监听数据推送
+### onData(callback) - 监听数据推送
 
-监听服务器推送的最新数据。init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送。
+监听服务器推送的数据。返回取消监听函数。
 
 ```javascript
 const unsubscribe = server.onData((data) => {
-  console.log('World:', data.world);
-  console.log('Self:', data.self);
-  console.log('Players:', data.players);
+  // 处理数据
 });
 
 // 取消监听
 unsubscribe();
 ```
 
-**数据格式：**
-```json
-{
-  "world": { "score": 200, "level": 1 },
-  "self": { "name": "Player1", "x": 15, "y": 25 },
-  "players": [
-    { "name": "Player2", "x": 10, "y": 20 },
-    { "name": "Player3", "x": 30, "y": 40 }
-  ]
-}
-```
-
-**注意：** `self` 和 `players[i]` 具有相同的数据结构，都只包含公开数据。
+**推送时机：** init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送
 
-**推送时机：** init 响应、定时推送（每 0.2 秒）、init/update 后立即推送
+## 关于 timestamp
 
-## 联机游戏示例
+- **类型要求**：必须是数字类型（number/int），不能是字符串
+- **如何获取**：直接使用上下文中给出的 timestamp 值
+- **较小或相等**：不生效，返回现有数据
+- **较大**：删除旧服务器并重新创建
+- **何时更新**：改动角色或世界字段设计（新增/删除/改变类型）时，需使用更大的 timestamp 重新初始化
 
-以下示例展示如何使用本库实现多人在线游戏：
+## 完整示例
 
 ```javascript
 import { RiffleServer } from '@lzpenguin/server';
 
-// post_id 和 token 会自动从浏览器 URL 参数中读取
 const server = new RiffleServer({
   url: 'wss://api.riffle.app',
-  timestamp: 'timestamp given in the context'
+  timestamp: 1234567890
 });
 
-// 监听服务器推送，更新游戏状态
+// 监听推送
 server.onData((data) => {
-  // 更新自己的位置（self 现在直接是公开数据对象）
   const myPosition = { x: data.self.x, y: data.self.y };
-  
-  // 更新其他玩家列表
   const otherPlayers = data.players || [];
-  
-  // 渲染游戏画面
   renderPlayers(myPosition, otherPlayers);
   
-  // 检查游戏状态
   if (data.world?.gameOver) {
     console.log('游戏结束！分数:', data.world.score);
   }
 });
 
-// 初始化游戏
+// 初始化
 server.init({
   world: { score: 0, level: 1 },
-  self: {
-    public: { name: 'Player1', x: 0, y: 0 }
-  }
+  self: { public: { name: 'Player1', x: 0, y: 0 } }
 });
 
 // 更新玩家位置
 function movePlayer(x, y) {
-  server.update({
-    self: {
-      public: { x, y }
-    }
-  });
+  server.update({ self: { public: { x, y } } });
 }
 
 // 更新分数
 function updateScore(score) {
-  server.update({
-    world: { score }
-  });
+  server.update({ world: { score } });
 }
 ```
 

package/package.json

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