@lzpenguin/server

Riffle game server WebSocket client SDK

Installation

npm install @lzpenguin/server

Quick Start

import { RiffleServer } from '@lzpenguin/server';

// Create a server instance
const server = new RiffleServer({
  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. 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);      // 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. Initialize the server (required, must be called after connecting)
server.init({
  world: { score: 0, level: 1 },
  self: {
    public: { x: 100, y: 100 }
    // The name field does not need to be set; it is included in the server response
  }
});

// 3. Update data (partial update, merged into existing data)
server.update({
  world: { score: 200 },
  self: { public: { x: 150, y: 150 } }
});

Data Format

Data format pushed by the server (received via onData):

{
  "world": { "score": 0, "level": 1 },
  "self": { "name": "Player1", "avatar": "https://...", "online": true, "x": 100, "y": 100 },
  "players": [
    { "name": "Player2", "avatar": "https://...", "online": true, "x": 10, "y": 20 },
    { "name": "Player3", "avatar": "https://...", "online": false, "x": 30, "y": 40 }
  ]
}

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 Reference

init(data) - Initialize Server

Required. Must be called after connecting. Uses timestamp to determine whether to re-initialize.

server.init({
  world: { score: 0, level: 1 },   // Optional: initial world data
  self: {
    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

Partially updates data (merged, not replaced). Only provided fields are updated; missing fields remain unchanged.

// 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) - Listen to Data Pushes

Listens to data pushed by the server. Returns an unsubscribe function.

const unsubscribe = server.onData((data) => {
  // Handle data
});

// Unsubscribe
unsubscribe();

Push timing: after init succeeds, auto-pushes every 0.2s; pushes immediately after init/update

About 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

import { RiffleServer } from '@lzpenguin/server';

const server = new RiffleServer({
  timestamp: 1234567890
});

// Listen to pushes
server.onData((data) => {
  // 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('Game over! Score:', data.world.score);
  }
});

// Initialize
server.init({
  world: { score: 0, level: 1 },
  self: { public: { x: 0, y: 0 } }
  // 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 } });
}

License

ISC