@lzpenguin/server 1.1.10 → 1.1.12

package/README.md

@@ -1,126 +1,128 @@
 # @lzpenguin/server
 
-Riffle 游戏服务器 WebSocket 客户端 SDK
+Riffle game server WebSocket client SDK
 
-## 安装
+## Installation
 
 ```bash
 npm install @lzpenguin/server
 ```
 
-## 快速开始
+## Quick Start
 
 ```javascript
 import { RiffleServer } from '@lzpenguin/server';
 
-// 创建服务器实例
+// Create a server instance
 const server = new RiffleServer({
-  timestamp: 1234567890,         // 必需：游戏时间戳（数字类型），直接使用上下文中给出的值
-  autoReconnect: true,           // 可选：自动重连，默认 true
-  reconnectInterval: 3000        // 可选：重连间隔（毫秒），默认 3000
+  timestamp: 1234567890,         // Required: game timestamp (number). Use the value provided in the context
+  autoReconnect: true,           // Optional: auto reconnect, default true
+  reconnectInterval: 3000        // Optional: reconnect interval (ms), default 3000
 });
 
-// 1. 监听数据推送（init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送）
+// 1. Listen to data push (after init succeeds, auto-pushes every 0.2s; pushes immediately after init/update)
 server.onData((data) => {
-  console.log('World:', data.world);      // 世界数据
-  console.log('Self:', data.self);        // 自己的公开数据（包含 name 字段）
-  console.log('Players:', data.players);  // 其他玩家的公开数据（包含 name 字段）
-  // 注意：self 和 players[i] 结构相同，都只包含公开数据
+  console.log('World:', data.world);      // World data
+  console.log('Self:', data.self);        // Your public data (includes name / avatar / online fields)
+  console.log('Players:', data.players);  // Other players' public data (includes name / avatar / online fields)
+  // Note: self and players[i] have the same structure and contain only public data
 });
 
-// 2. 初始化服务器（必需，连接后必须先调用）
+// 2. Initialize the server (required, must be called after connecting)
 server.init({
   world: { score: 0, level: 1 },
   self: {
     public: { x: 100, y: 100 }
-    // name 字段不需要设置，服务器返回数据会包含
+    // The name field does not need to be set; it is included in the server response
   }
 });
 
-// 3. 更新数据（部分更新，合并到现有数据）
+// 3. Update data (partial update, merged into existing data)
 server.update({
   world: { score: 200 },
   self: { public: { x: 150, y: 150 } }
 });
 ```
 
-## 数据格式
+## Data Format
 
-服务器推送的数据格式（通过 `onData` 接收）：
+Data format pushed by the server (received via `onData`):
 
 ```json
 {
   "world": { "score": 0, "level": 1 },
-  "self": { "name": "Player1", "x": 100, "y": 100 },
+  "self": { "name": "Player1", "avatar": "https://...", "online": true, "x": 100, "y": 100 },
   "players": [
-    { "name": "Player2", "x": 10, "y": 20 },
-    { "name": "Player3", "x": 30, "y": 40 }
+    { "name": "Player2", "avatar": "https://...", "online": true, "x": 10, "y": 20 },
+    { "name": "Player3", "avatar": "https://...", "online": false, "x": 30, "y": 40 }
   ]
 }
 ```
 
-**关于 name 字段：**
-- `self.name` 和 `players[i].name` 字段**一定会存在**，包含用户的昵称或用户名
-- 你不需要在 `init()` 或 `update()` 时设置 name 字段，服务器会直接返回
+**About the name / avatar / online fields:**
+- `self.name` and `players[i].name` **always exist** and contain the user's nickname or username
+- `self.avatar` and `players[i].avatar` are overridden by the server based on the user's avatar
+- `self.online` and `players[i].online` are stored in player data and are set to true when `/api/v1/server/ws` connects, and false when it disconnects
+- You do not need to set name / avatar / online in `init()` or `update()`; the server returns them directly
 
-## API 说明
+## API Reference
 
-### init(data) - 初始化服务器
+### init(data) - Initialize Server
 
-必需，连接后必须先调用。根据 timestamp 判断是否重新初始化。
+Required. Must be called after connecting. Uses timestamp to determine whether to re-initialize.
 
 ```javascript
 server.init({
-  world: { score: 0, level: 1 },   // 可选：世界初始数据
+  world: { score: 0, level: 1 },   // Optional: initial world data
   self: {
-    public: { x: 100, y: 100 }  // 可选：玩家公开数据
-    // 注意：name 字段不需要设置，服务器返回的数据会包含该字段
+    public: { x: 100, y: 100 }  // Optional: player public data
+    // Note: the name field does not need to be set; it is included in the server response
   }
 });
 ```
 
-### update(data) - 更新数据
+### update(data) - Update Data
 
-部分更新数据（合并，不替换）。只更新提供的字段，未提供的字段保持不变。
+Partially updates data (merged, not replaced). Only provided fields are updated; missing fields remain unchanged.
 
 ```javascript
-// 更新世界数据
+// Update world data
 server.update({ world: { score: 200 } });
 
-// 更新玩家数据
+// Update player data
 server.update({ self: { public: { x: 15, y: 25 } } });
 
-// 同时更新
+// Update both
 server.update({
   world: { score: 200 },
   self: { public: { x: 15, y: 25 } }
 });
 ```
 
-### onData(callback) - 监听数据推送
+### onData(callback) - Listen to Data Pushes
 
-监听服务器推送的数据。返回取消监听函数。
+Listens to data pushed by the server. Returns an unsubscribe function.
 
 ```javascript
 const unsubscribe = server.onData((data) => {
-  // 处理数据
+  // Handle data
 });
 
-// 取消监听
+// Unsubscribe
 unsubscribe();
 ```
 
-**推送时机：** init 成功后每 0.2 秒自动推送，调用 init/update 后立即推送
+**Push timing:** after init succeeds, auto-pushes every 0.2s; pushes immediately after init/update
 
-## 关于 timestamp
+## About timestamp
 
-- **类型要求**：必须是数字类型（number/int），不能是字符串
-- **如何获取**：直接使用上下文中给出的 timestamp 值
-- **较小或相等**：不生效，返回现有数据
-- **较大**：删除旧服务器并重新创建
-- **何时更新**：改动角色或世界字段设计（新增/删除/改变类型）时，需使用更大的 timestamp 重新初始化
+- **Type requirement**: must be a number (number/int), not a string
+- **How to get it**: use the timestamp value provided in the context directly
+- **Smaller or equal**: no effect; returns existing data
+- **Larger**: deletes the old server and recreates it
+- **When to update**: when changing character or world field design (add/remove/change type), use a larger timestamp to re-initialize
 
-## 完整示例
+## Complete Example
 
 ```javascript
 import { RiffleServer } from '@lzpenguin/server';
@@ -129,33 +131,33 @@ const server = new RiffleServer({
   timestamp: 1234567890
 });
 
-// 监听推送
+// Listen to pushes
 server.onData((data) => {
-  // data.self.name 和 data.players[i].name 一定会存在
-  console.log('我的名字:', data.self.name);
+  // data.self.name and data.players[i].name always exist
+  console.log('My name:', data.self.name);
   
   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);
+    console.log('Game over! Score:', data.world.score);
   }
 });
 
-// 初始化
+// Initialize
 server.init({
   world: { score: 0, level: 1 },
   self: { public: { x: 0, y: 0 } }
-  // name 字段不需要设置，返回的数据会包含
+  // The name field does not need to be set; it is included in the response
 });
 
-// 更新玩家位置
+// Update player position
 function movePlayer(x, y) {
   server.update({ self: { public: { x, y } } });
 }
 
-// 更新分数
+// Update score
 function updateScore(score) {
   server.update({ world: { score } });
 }

package/index.js

@@ -204,6 +204,28 @@ export class RiffleServer {
 
           // 检查是否是数据消息（包含 world、self、players 字段）
           if (message.world !== undefined && message.self !== undefined && message.players !== undefined) {
+            if (message.self && typeof message.self === 'object') {
+              if (message.self.online === undefined) {
+                message.self.online = false;
+              }
+              if (message.self.avatar === undefined) {
+                message.self.avatar = '';
+              }
+            }
+            if (Array.isArray(message.players)) {
+              message.players = message.players.map((player) => {
+                if (player && typeof player === 'object') {
+                  if (player.online === undefined) {
+                    player.online = false;
+                  }
+                  if (player.avatar === undefined) {
+                    player.avatar = '';
+                  }
+                }
+                return player;
+              });
+            }
+
             // 如果还未初始化，这可能是 init 响应
             if (!this.isInitialized && message.self) {
               this.isInitialized = true;

package/package.json

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