@lzpenguin/server 1.0.0

package/README.md

@@ -0,0 +1,220 @@
+# @lzpenguin/server
+
+Riffle 游戏服务器 WebSocket 客户端 SDK
+
+## 安装
+
+```bash
+npm install @lzpenguin/server
+```
+
+## 快速开始
+
+```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: 'game-version-hash-123',
+  world: { score: 0, level: 1 },
+  self: {
+    public: { name: 'Player1' },
+    private: { health: 100 }
+  }
+});
+```
+
+## API
+
+### 构造函数
+
+```javascript
+new RiffleServer({
+  url: 'wss://api.riffle.app',  // 必需：WebSocket 服务器 URL
+  postId: 123456,                // 必需：游戏贴文 ID
+  token: 'your-token-here',      // 必需：认证 token
+  autoReconnect: true,           // 可选：是否自动重连，默认 true
+  reconnectInterval: 3000        // 可选：重连间隔（毫秒），默认 3000
+})
+```
+
+## 三种消息类型
+
+### 1. init() - 初始化服务器
+
+初始化服务器（必需，连接后必须先调用）。hash 相同则返回现有数据，hash 不同则删除旧服务器并重新创建。
+
+```javascript
+server.init({
+  hash: 'game-version-hash-123',  // 必需：游戏版本哈希值
+  world: { score: 0, level: 1 },   // 可选：世界初始数据
+  self: {
+    public: { name: 'Player1' },     // 可选：公开数据
+    private: { health: 100 }         // 可选：私有数据
+  }
+});
+```
+
+**响应数据（通过 onData 接收）：**
+```json
+{
+  "world": { "score": 0, "level": 1 },
+  "self": {
+    "public": { "name": "Player1" },
+    "private": { "health": 100 }
+  },
+  "players": [
+    { "name": "Player2", "position": { "x": 10, "y": 20 } }
+  ]
+}
+```
+
+**关于 hash：**
+- **hash 相同**：传入的值不生效，直接返回现有数据
+- **hash 不同**：删除旧服务器并重新创建，使用传入的值初始化数据
+- **何时更新 hash**：如果更改了游戏，且改动了角色或世界字段的设计（如新增/删除字段、改变字段类型），就需要更新 hash 让服务器重新初始化，避免数据结构不兼容
+
+**注意：** 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() - 监听数据推送
+
+监听服务器推送的最新数据。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": {
+    "public": { "name": "Player1", "position": { "x": 15, "y": 25 } },
+    "private": { "health": 90, "mana": 50 }
+  },
+  "players": [
+    { "name": "Player2", "position": { "x": 10, "y": 20 } },
+    { "name": "Player3", "position": { "x": 30, "y": 40 } }
+  ]
+}
+```
+
+**推送时机：** init 响应、定时推送（每 0.2 秒）、init/update 后立即推送
+
+## 联机游戏示例
+
+以下示例展示如何使用本库实现多人在线游戏：
+
+```javascript
+import { RiffleServer } from '@lzpenguin/server';
+
+const server = new RiffleServer({
+  url: 'wss://api.riffle.app',
+  postId: 123456,
+  token: 'your-token-here'
+});
+
+// 监听服务器推送，更新游戏状态
+server.onData((data) => {
+  // 更新自己的位置
+  const myPosition = data.self?.public?.position;
+  
+  // 更新其他玩家列表
+  const otherPlayers = data.players || [];
+  
+  // 渲染游戏画面
+  renderPlayers(myPosition, otherPlayers);
+  
+  // 检查游戏状态
+  if (data.world?.gameOver) {
+    console.log('游戏结束！分数:', data.world.score);
+  }
+});
+
+// 初始化游戏
+server.init({
+  hash: 'v1.0.0',
+  world: { score: 0, level: 1 },
+  self: {
+    public: { name: 'Player1', position: { x: 0, y: 0 } },
+    private: { health: 100 }
+  }
+});
+
+// 更新玩家位置
+function movePlayer(x, y) {
+  server.update({
+    self: {
+      public: { position: { x, y } }
+    }
+  });
+}
+
+// 更新分数
+function updateScore(score) {
+  server.update({
+    world: { score }
+  });
+}
+```
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,315 @@
+import WebSocket from 'ws';
+
+/**
+ * RiffleServer - 游戏服务器 WebSocket 客户端
+ * 
+ * @example
+ * ```js
+ * import { RiffleServer } from '@riffle/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: 'game-version-hash-123',  // 游戏版本哈希值
+ *   world: { score: 0, level: 1 },   // 世界初始数据（可选）
+ *   self: {
+ *     public: { name: 'Player1' },   // 公开数据（可选）
+ *     private: { health: 100 }      // 私有数据（可选）
+ *   }
+ * });
+ * 
+ * // 更新数据
+ * server.update({ 
+ *   world: { score: 200 },
+ *   self: { 
+ *     public: { position: { x: 15, y: 25 } },
+ *     private: { health: 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 {boolean} [options.autoReconnect=true] - 是否自动重连
+   * @param {number} [options.reconnectInterval=3000] - 重连间隔（毫秒）
+   */
+  constructor(options) {
+    const { url, postId, token, autoReconnect = true, reconnectInterval = 3000 } = options;
+
+    if (!url) {
+      throw new Error('URL is required');
+    }
+    if (!postId) {
+      throw new Error('postId is required');
+    }
+    if (!token) {
+      throw new Error('token is required');
+    }
+
+    this.url = url;
+    this.postId = postId;
+    this.token = token;
+    this.autoReconnect = autoReconnect;
+    this.reconnectInterval = reconnectInterval;
+
+    this.ws = null;
+    this.isConnected = false;
+    this.isConnecting = false;
+    this.isInitialized = false;
+    this.reconnectTimer = null;
+    this.dataCallbacks = [];
+    this.pendingInit = null;  // 待执行的 init 请求
+
+    // 当前服务器数据缓存
+    this.currentData = null;
+
+    // 连接状态
+    this.connect();
+  }
+
+  /**
+   * 连接到 WebSocket 服务器
+   * @private
+   */
+  connect() {
+    if (this.isConnecting || (this.isConnected && this.ws?.readyState === WebSocket.OPEN)) {
+      return;
+    }
+
+    this.isConnecting = true;
+
+    // 构建 WebSocket URL（包含 post_id 和 token）
+    let wsUrl = `${this.url}?post_id=${this.postId}&token=${this.token}`;
+
+
+    try {
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.on('open', () => {
+        this.isConnected = true;
+        this.isConnecting = false;
+        this.isInitialized = false;  // 连接后重置初始化状态
+        console.log('[RiffleServer] Connected');
+        
+        // 如果有待执行的 init 请求，自动执行
+        if (this.pendingInit) {
+          const initData = this.pendingInit;
+          this.pendingInit = null;
+          this._doInit(initData);
+        }
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const message = JSON.parse(data.toString());
+          
+          // 检查是否是错误消息
+          if (message.error) {
+            console.error('[RiffleServer] Server error:', message.error);
+            return;
+          }
+
+          // 检查是否是数据消息（包含 world、self、players 字段）
+          if (message.world !== undefined && message.self !== undefined && message.players !== undefined) {
+            // 如果还未初始化，这可能是 init 响应
+            if (!this.isInitialized && message.self) {
+              this.isInitialized = true;
+              console.log('[RiffleServer] Initialized');
+            }
+            
+            // 更新缓存并触发数据回调
+            this.currentData = message;
+            this.dataCallbacks.forEach(cb => cb(message));
+          }
+        } catch (error) {
+          console.error('[RiffleServer] Failed to parse message:', error);
+        }
+      });
+
+      this.ws.on('error', (error) => {
+        console.error('[RiffleServer] WebSocket error:', error);
+      });
+
+      this.ws.on('close', () => {
+        this.isConnected = false;
+        this.isConnecting = false;
+        this.isInitialized = false;  // 断开连接后重置初始化状态
+        console.log('[RiffleServer] Disconnected');
+
+        // 自动重连
+        if (this.autoReconnect && !this.reconnectTimer) {
+          this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+          }, this.reconnectInterval);
+        }
+      });
+    } catch (error) {
+      this.isConnecting = false;
+      console.error('[RiffleServer] Connection error:', error);
+    }
+  }
+
+  /**
+   * 断开连接
+   * @private
+   */
+  disconnect() {
+    this.autoReconnect = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.isConnected = false;
+  }
+
+  /**
+   * 发送更新请求
+   * @private
+   * @param {Object} updateData - 更新数据
+   */
+  sendUpdate(updateData) {
+    if (!this.isConnected || this.ws?.readyState !== WebSocket.OPEN) {
+      console.warn('[RiffleServer] Not connected, cannot send update');
+      return;
+    }
+
+    if (!this.isInitialized) {
+      console.warn('[RiffleServer] Not initialized, please call init() first');
+      return;
+    }
+
+    try {
+      this.ws.send(JSON.stringify(updateData));
+    } catch (error) {
+      console.error('[RiffleServer] Failed to send update:', error);
+    }
+  }
+
+  /**
+   * 初始化服务器（必需，连接后必须先调用）
+   * @param {Object} initData - 初始化数据
+   * @param {string} initData.hash - 游戏版本哈希值（必需）
+   * @param {Object} [initData.world] - 世界初始数据（可选）
+   * @param {Object} [initData.self] - 玩家初始数据（可选）
+   * @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 }
+   *   }
+   * });
+   */
+  init(initData) {
+    if (!initData || !initData.hash) {
+      console.error('[RiffleServer] hash is required for init');
+      return;
+    }
+
+    // 如果还未连接，保存 init 请求，连接建立后自动执行
+    if (!this.isConnected || this.ws?.readyState !== WebSocket.OPEN) {
+      console.log('[RiffleServer] Not connected yet, will init after connection');
+      this.pendingInit = initData;
+      return;
+    }
+
+    // 已连接，直接执行
+    this._doInit(initData);
+  }
+
+  /**
+   * 执行初始化请求
+   * @private
+   * @param {Object} initData - 初始化数据
+   */
+  _doInit(initData) {
+    try {
+      const initMessage = {
+        hash: initData.hash,
+        world: initData.world || undefined,
+        self: initData.self || undefined
+      };
+      this.ws.send(JSON.stringify(initMessage));
+    } catch (error) {
+      console.error('[RiffleServer] Failed to send init:', error);
+    }
+  }
+
+  /**
+   * 更新数据（部分更新）
+   * @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 - 回调函数，接收服务器推送的数据
+   * @returns {Function} 取消监听的函数
+   * @example
+   * const unsubscribe = server.onData((data) => {
+   *   console.log('World:', data.world);
+   *   console.log('Self:', data.self);
+   *   console.log('Players:', data.players);
+   * });
+   * 
+   * // 取消监听
+   * unsubscribe();
+   */
+  onData(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('Callback must be a function');
+    }
+    this.dataCallbacks.push(callback);
+
+    // 如果已有缓存数据，立即调用一次
+    if (this.currentData) {
+      callback(this.currentData);
+    }
+
+    // 返回取消监听的函数
+    return () => {
+      const index = this.dataCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.dataCallbacks.splice(index, 1);
+      }
+    };
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lzpenguin/server",
+  "version": "1.0.0",
+  "description": "Riffle 游戏服务器 WebSocket 客户端 SDK",
+  "license": "ISC",
+  "author": "lzpenguin",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "keywords": [
+    "riffle",
+    "websocket",
+    "game-server"
+  ],
+  "dependencies": {
+    "ws": "^8.14.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/ws": "^8.5.10"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}
+