@inglorious/server 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Inglorious Coderz Srl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# Inglorious Server
+
+A real-time, lightweight server designed to enable multiplayer experiences for games built with the Inglorious Engine. This server is built on Node.js and uses WebSockets to handle real-time communication, ensuring low-latency updates for all connected clients.
+
+## Features
+
+- **Real-Time Communication**: Uses WebSockets to provide bidirectional, low-latency communication between the server and clients.
+- **Server-Authoritative Game State**: Manages a central game state using the `@inglorious/store` and acts as the single source of truth for all clients.
+- **Scalable Architecture**: The server's logic is modular and split into dedicated files for handling game loading, the main game loop, and WebSocket events.
+- **Dynamic Game Loading**: Supports loading game data from a specified JavaScript module, allowing you to easily run different game worlds without changing the server code.
+- **Production-Ready Logging**: Uses `pino` for fast, structured logging, making it easy to monitor and debug in a production environment.
+
+## Getting Started
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (version 22 or higher)
+- [pnpm](https://pnpm.io/) (used for package management)
+
+### Installation
+
+1. Clone the Inglorious Engine repository:
+
+```sh
+git clone https://github.com/IngloriousCoderz/inglorious-engine.git
+```
+
+2. Navigate to the `@inglorious/server` directory:
+
+```sh
+cd packages/server
+```
+
+3. Install the dependencies:
+
+```sh
+pnpm install
+```
+
+## Usage
+
+The server can be started using the `start` or `dev` scripts. You can optionally provide a path to a game module to load a specific game state.
+
+### Running in Development Mode
+
+To run the server with automatic restarts on file changes, use the `dev` script.
+
+```sh
+pnpm dev
+```
+
+### Running in Production Mode
+
+To run the server in a production environment, use the `start` script.
+
+```sh
+pnpm start
+```
+
+### Loading a Specific Game
+
+By default, the server will attempt to load a `./default-game.js` file. To load a different game, provide the file path as a command-line argument.
+
+```sh
+pnpm start ./path/to/your-game.js
+```
+
+## Project Structure
+
+The server's code is split into several files to maintain a clear separation of concerns.
+
+- `src/index.js`: The main entry point for the server. It orchestrates the setup of the HTTP and WebSocket servers and initializes the game store and its core handlers.
+- `src/game-loader.js`: Handles the dynamic loading of the initial game state from a JavaScript module. It also includes a fallback state if the game file is not found.
+- `src/game-loop.js`: Contains the core setInterval loop that drives the game logic by calling the store.update() function at a fixed tick rate (60 updates per second).
+- `src/websocket-handler.js`: Manages all WebSocket events, including new connections, incoming messages, and disconnections. It dispatches client events to the store and broadcasts changes to all clients.
+
+## Dependencies
+
+- `@inglorious/store`: The state management solution for the game engine.
+- `ws`: A simple and fast WebSocket library.
+- `pino`: A highly performant logger for Node.js.
+
+## License
+
+This project is licensed under the MIT License.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@inglorious/server",
+  "version": "0.1.0",
+  "description": "A real-time, lightweight server designed to enable multiplayer experiences for games built with the Inglorious Engine.",
+  "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IngloriousCoderz/inglorious-engine.git"
+  },
+  "homepage": "https://inglorious-engine.vercel.app/",
+  "bugs": {
+    "url": "https://github.com/IngloriousCoderz/inglorious-engine/issues"
+  },
+  "keywords": [
+    "functional-programming",
+    "gamedev",
+    "game-engine",
+    "inglorious-engine",
+    "server",
+    "real-time",
+    "multiplayer",
+    "websocket"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "inglorious-server": "./src/index.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "pino": "^9.9.4",
+    "ws": "^8.18.3",
+    "@inglorious/store": "1.0.0"
+  },
+  "devDependencies": {
+    "globals": "^16.3.0",
+    "nodemon": "^3.1.10",
+    "prettier": "^3.6.2"
+  },
+  "engines": {
+    "node": ">= 22"
+  },
+  "scripts": {
+    "format": "prettier --write '**/*.{js,jsx}'",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "start": "node src/index.js",
+    "dev": "nodemon src/index.js"
+  }
+}

package/src/default-game.js

@@ -0,0 +1 @@
+export default {}

package/src/game-loader.js

@@ -0,0 +1,49 @@
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+/**
+ * Dynamically loads the initial game state from a module and provides a fallback.
+ * @param {string} gameFilePath The path to the game module.
+ * @param {object} logger A Pino logger instance.
+ * @returns {Promise<{initialTypes: object, initialEntities: object}>} The initial game state.
+ */
+export async function loadGame(gameFilePath, logger) {
+  let gameConfig = {}
+
+  try {
+    // Dynamically import the game module.
+    const __filename = fileURLToPath(import.meta.url)
+    const __dirname = path.dirname(__filename)
+    const modulePath = path.resolve(__dirname, gameFilePath)
+    const { default: config } = await import(`file://${modulePath}`)
+    gameConfig = config
+    gameConfig.types ??= {}
+    gameConfig.entities ??= {}
+
+    logger.info(`Loaded game data from ${gameFilePath}`)
+  } catch (error) {
+    logger.error(`Failed to load game module: ${gameFilePath}`)
+    logger.error(error)
+    // Fallback to a basic initial state if loading fails.
+    gameConfig = {
+      types: {
+        player: {
+          move: (entity, payload) => {
+            logger.info(
+              `Player ${entity.id} moved to ${payload.x}, ${payload.y}`,
+            )
+          },
+        },
+        box: {},
+      },
+
+      entities: {
+        player1: { id: "player1", type: "player", x: 0, y: 0 },
+        box1: { id: "box1", type: "box", x: 10, y: 10 },
+      },
+    }
+    logger.warn("Using default game state as a fallback.")
+  }
+
+  return gameConfig
+}

package/src/game-loop.js

@@ -0,0 +1,24 @@
+import { performance } from "node:perf_hooks"
+
+const ONE_SECOND = 1000
+const TICK_RATE = 60 // 60 updates per second
+const TICK_INTERVAL = ONE_SECOND / TICK_RATE // ~16.67ms
+let lastTime = performance.now()
+
+/**
+ * Starts the main server-side game loop.
+ * @param {object} store The game store instance.
+ * @param {object} api The game API with broadcast functionality.
+ */
+export function start(store, api) {
+  // The main server-side game loop.
+  setInterval(() => {
+    const currentTime = performance.now()
+    const dt = (currentTime - lastTime) / ONE_SECOND // Convert to seconds
+    lastTime = currentTime
+
+    // The store's update function is the heart of the game loop.
+    // It processes events and advances the game state.
+    store.update(dt, api)
+  }, TICK_INTERVAL)
+}

package/src/index.js

@@ -0,0 +1,70 @@
+import http from "node:http"
+
+import { createStore } from "@inglorious/store"
+import pino from "pino"
+import { WebSocketServer } from "ws"
+
+import { loadGame } from "./game-loader.js"
+import { start as startGameLoop } from "./game-loop.js"
+import { setup as setupWebSocketHandler } from "./ws-handler.js"
+
+// The server's port. You can change this or use an environment variable.
+const PORT = 3000
+const HTTP_STATUS_OK = 200
+
+const logger = pino({ name: "Inglorious Server", level: "info" })
+
+// =========================================================================
+// Initial Game State
+// =========================================================================
+
+// Get the game file path from command-line arguments.
+let [, , gameFilePath] = process.argv
+gameFilePath ??= "./default-game.js"
+
+const gameConfig = await loadGame(gameFilePath, logger)
+
+// =========================================================================
+// Server Setup
+// =========================================================================
+
+// Create a minimal HTTP server. The WebSocket server will be "attached" to this.
+const httpServer = http.createServer((req, res) => {
+  res.writeHead(HTTP_STATUS_OK, { "Content-Type": "text/plain" })
+  res.end("Inglorious Server is running.")
+})
+
+// Create the WebSocket server.
+const wss = new WebSocketServer({ server: httpServer })
+const clients = new Set() // A Set to keep track of all connected clients.
+
+// Initialize the game store. This is the central source of truth.
+const store = createStore(gameConfig)
+
+// A small-scale API for your systems and events to interact with the world.
+// This can be expanded as needed.
+const api = {
+  // A simple broadcast function.
+  broadcast: (event) => {
+    // Stringify the event for transmission.
+    const message = JSON.stringify(event)
+    for (const client of clients) {
+      client.send(message)
+    }
+  },
+}
+
+// =========================================================================
+// Start Game Loop and WebSocket Handling
+// =========================================================================
+
+// Start the core game loop.
+startGameLoop(store, api)
+
+// Set up the WebSocket event handlers.
+setupWebSocketHandler(wss, store, clients, logger)
+
+// Start the server and listen on the specified port.
+httpServer.listen(PORT, () => {
+  logger.info(`Listening on http://localhost:${PORT}`)
+})

package/src/ws-handler.js

@@ -0,0 +1,49 @@
+/**
+ * Sets up WebSocket event handling for a given server and store.
+ * @param {object} wss The WebSocket server instance.
+ * @param {object} store The game store instance.
+ * @param {Set<object>} clients A Set to keep track of all connected clients.
+ * @param {object} logger A Pino logger instance.
+ */
+export function setup(wss, store, clients, logger) {
+  // Listen for new client connections.
+  wss.on("connection", (ws) => {
+    logger.info("A new client has connected.")
+    clients.add(ws)
+
+    // Send the initial state to the new client.
+    ws.send(JSON.stringify({ type: "initialState", payload: store.getState() }))
+
+    // Listen for messages from the client.
+    ws.on("message", (message) => {
+      try {
+        // Parse the incoming event.
+        const event = JSON.parse(message)
+
+        // Dispatch the event to the central store.
+        store.dispatch(event)
+
+        // Broadcast the event to all other clients.
+        const eventMessage = JSON.stringify(event)
+        for (const client of clients) {
+          if (client !== ws) {
+            // Exclude the sender from the broadcast.
+            client.send(eventMessage)
+          }
+        }
+      } catch (error) {
+        logger.error("Failed to parse message:", error)
+      }
+    })
+
+    // Listen for the client disconnecting.
+    ws.on("close", () => {
+      logger.info("A client has disconnected.")
+      clients.delete(ws)
+    })
+
+    ws.on("error", (error) => {
+      logger.error("WebSocket error:", error)
+    })
+  })
+}