@utsp/runtime-server 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Piquet
+
+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,36 @@
+# @utsp/runtime-server
+
+> ⚠️ **PROTOTYPE - NOT READY FOR PRODUCTION**
+>
+> This package is currently in early development and should **NOT** be used in production.
+> The API is unstable and subject to breaking changes without notice.
+
+Server-side runtime for UTSP (Universal Text Stream Protocol) multi-user applications.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ⚠️ Development Status
+
+**This is a prototype package under active development.**
+
+- ❌ No stable API
+- ❌ No documentation available yet
+- ❌ Breaking changes expected
+- ❌ Not recommended for production use
+
+**Please check back later for updates or watch the repository for release announcements.**
+
+## Installation
+
+```bash
+npm install @utsp/runtime-server
+```
+
+## Repository
+
+- [GitHub](https://github.com/thp-software/utsp)
+- [Issues](https://github.com/thp-software/utsp/issues)
+
+## License
+
+MIT © 2025 Thomas Piquet

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var h=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var f=(n,t,e)=>t in n?h(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e;var l=(n,t)=>h(n,"name",{value:t,configurable:!0});var w=(n,t)=>{for(var e in t)h(n,e,{get:t[e],enumerable:!0})},T=(n,t,e,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of d(t))!k.call(n,s)&&s!==e&&h(n,s,{get:()=>t[s],enumerable:!(i=v(t,s))||i.enumerable});return n};var S=n=>T(h({},"__esModule",{value:!0}),n);var r=(n,t,e)=>(f(n,typeof t!="symbol"?t+"":t,e),e);var y={};w(y,{ServerRuntime:()=>p});module.exports=S(y);var u=require("@utsp/core"),g=require("@utsp/network-server");var c=class c{constructor(t){r(this,"core");r(this,"network");r(this,"options");r(this,"running",!1);r(this,"startTime",0);r(this,"lastTimestamp",0);r(this,"tickCount",0);r(this,"tps",0);r(this,"tpsUpdateTime",0);r(this,"tickInterval",null);this.options={application:t.application,port:t.port,host:t.host??"0.0.0.0",tickRate:t.tickRate??20,maxConnections:t.maxConnections??100,debug:t.debug??!1,width:t.width??80,height:t.height??25,cors:t.cors??{origin:"*"}},this.log("Initializing ServerRuntime..."),this.core=new u.Core({mode:"server",maxUsers:this.options.maxConnections}),this.network=new g.SocketIOServer({port:this.options.port,host:this.options.host,cors:this.options.cors,maxConnections:this.options.maxConnections,debug:this.options.debug}),this.log("ServerRuntime initialized")}getMode(){return"server"}isRunning(){return this.running}setTickRate(t){if(t<=0||t>1e3)throw new Error(`Invalid tick rate: ${t}. Must be between 1 and 1000.`);if(this.options.tickRate=t,this.log(`Tick rate changed to ${t} TPS`),this.running&&this.tickInterval){clearInterval(this.tickInterval);let e=1e3/t;this.log(`Restarting tick loop at ${t} TPS (${e}ms)...`),this.tickInterval=setInterval(()=>{this.tick()},e)}}getTickRate(){return this.options.tickRate}async start(){if(this.running){this.log("Already running");return}this.log("Starting ServerRuntime..."),await this.network.start(),this.log(`Server listening on ${this.options.host}:${this.options.port}`),this.setupNetworkHandlers(),this.log("Calling application.init()..."),this.options.application.init(this.core,this),this.running=!0,this.startTime=Date.now(),this.lastTimestamp=this.startTime,this.tpsUpdateTime=this.startTime;let t=1e3/this.options.tickRate;this.log(`Starting tick loop at ${this.options.tickRate} TPS (${t}ms)...`),this.tickInterval=setInterval(()=>{this.tick()},t)}async stop(){if(!this.running)return;this.log("Stopping ServerRuntime..."),this.running=!1,this.tickInterval&&(clearInterval(this.tickInterval),this.tickInterval=null),this.network.getClients().forEach(e=>{this.network.disconnectClient(e,"Server stopped")}),await this.network.stop(),this.log("ServerRuntime stopped")}getStats(){return{mode:"server",running:this.running,userCount:this.core.getUsers().length,tps:this.tps,uptime:this.running?Date.now()-this.startTime:0,totalTicks:this.tickCount}}async destroy(){await this.stop(),this.log("Destroying ServerRuntime..."),this.options.application.destroy&&this.options.application.destroy(),await this.network.destroy(),this.log("ServerRuntime destroyed")}setupNetworkHandlers(){this.network.onConnect(t=>{this.log(`Client connected: ${t}`)}),this.network.onDisconnect((t,e)=>{this.log(`Client disconnected: ${t} (${e})`);let i=this.core.getUser(t);i&&(this.options.application.destroyUser&&this.options.application.destroyUser(this.core,i,e),this.core.removeUser(t))}),this.network.on("join",(t,e)=>{this.log(`Join request from ${t}: ${e.username}`);try{let i=e.username||`Player${t.substring(0,4)}`,s=this.core.createUser(t,i);this.options.application.initUser(this.core,s,{username:i,token:e.token}),this.network.sendToClient(t,"join_response",{success:!0,userId:t,roomId:"main"});let o=this.core.generateAllLoadPackets();this.log(`Sending ${o.length} load packets to ${t}...`),o.forEach(m=>{this.network.sendToClient(t,"load",m)});let a=s.getInputBindingsLoadPacket();a&&(this.network.sendToClient(t,"input-bindings",a),this.log(`Sent input bindings to ${t}`)),this.log(`User ${i} (${t}) joined`)}catch(i){this.log(`Failed to join: ${i}`),this.network.sendToClient(t,"join_response",{success:!1,error:"Failed to join game"})}}),this.network.on("leave",t=>{this.log(`Leave request from ${t}`),this.network.disconnectClient(t,"User left")}),this.network.on("input",(t,e)=>{let i=this.core.getUser(t);if(!i){this.log(`Input from unknown user: ${t}`);return}if(e.axes&&Object.entries(e.axes).forEach(([s,o])=>{i.setAxis(s,o)}),e.buttons&&Object.entries(e.buttons).forEach(([s,o])=>{i.setButton(s,o)}),e.mousePosition){let{x:s,y:o}=e.mousePosition;i.setMousePosition(s,o,!0)}e.textInputs&&Array.isArray(e.textInputs)&&i.setTextInputs(e.textInputs)})}tick(){if(!this.running)return;let t=Date.now(),e=(t-this.lastTimestamp)/1e3;this.lastTimestamp=t,this.tickCount++,t-this.tpsUpdateTime>=1e3&&(this.tps=Math.round(this.tickCount*1e3/(t-this.tpsUpdateTime)),this.tickCount=0,this.tpsUpdateTime=t),this.options.application.update&&this.options.application.update(this.core,e),this.core.getUsers().forEach(s=>{this.options.application.updateUser(this.core,s,e),s.clearTextInputs()}),this.core.endTick(),this.broadcastUpdates()}broadcastUpdates(){let t=this.core.endTickSplit(),e=this.core.getCurrentTick();t.forEach(({static:i,dynamic:s},o)=>{if(i&&(this.network.sendToClient(o,"update-static",i),console.warn(`[SERVER] update-static: ${i.length}B (tick ${e})`)),s){let a=this.network;a.sendToClientVolatile?a.sendToClientVolatile(o,"update-dynamic",s):this.network.sendToClient(o,"update-dynamic",s),console.warn(`[SERVER] update-dynamic: ${s.length}B (tick ${e})`)}})}log(t){this.options.debug&&console.warn(`[ServerRuntime] ${t}`)}};l(c,"ServerRuntime");var p=c;0&&(module.exports={ServerRuntime});

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+export { IApplication } from '@utsp/types';
+
+/**
+ * Server Runtime Options
+ */
+interface ServerRuntimeOptions {
+    /**
+     * The application implementation
+     */
+    application: any;
+    /**
+     * Server port
+     */
+    port: number;
+    /**
+     * Server host
+     * @default '0.0.0.0'
+     */
+    host?: string;
+    /**
+     * Server tick rate (updates per second)
+     * @default 60
+     */
+    tickRate?: number;
+    /**
+     * Maximum concurrent connections
+     * @default 100
+     */
+    maxConnections?: number;
+    /**
+     * Terminal width (columns)
+     * @default 80
+     */
+    width?: number;
+    /**
+     * Terminal height (rows)
+     * @default 25
+     */
+    height?: number;
+    /**
+     * CORS configuration
+     * @default { origin: '*' }
+     */
+    cors?: {
+        origin: string | string[];
+        credentials?: boolean;
+    };
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Server Runtime Statistics
+ */
+interface ServerRuntimeStats {
+    /** Runtime mode */
+    mode: 'server';
+    /** Whether the runtime is running */
+    running: boolean;
+    /** Number of connected users */
+    userCount: number;
+    /** Current tick rate (TPS) */
+    tps: number;
+    /** Uptime in milliseconds */
+    uptime: number;
+    /** Total ticks processed */
+    totalTicks: number;
+}
+
+/**
+ * Server Runtime
+ *
+ * Headless mode - runs server without rendering.
+ * Uses: Core + Network (SocketIOServer)
+ * No Render, no Input (receives input from clients)
+ *
+ * Perfect for:
+ * - Multiplayer game servers
+ * - Authoritative game logic
+ * - Scalable backend
+ */
+
+declare class ServerRuntime {
+    private core;
+    private network;
+    private options;
+    private running;
+    private startTime;
+    private lastTimestamp;
+    private tickCount;
+    private tps;
+    private tpsUpdateTime;
+    private tickInterval;
+    constructor(options: ServerRuntimeOptions);
+    getMode(): 'server';
+    isRunning(): boolean;
+    /**
+     * Change le tick rate du serveur (peut être appelé à tout moment)
+     * Redémarre l'interval avec la nouvelle fréquence
+     *
+     * @param tickRate - Nouveau tick rate en TPS (ticks per second)
+     * @example
+     * ```typescript
+     * // Dans init() de votre application :
+     * init(core: UTSPCore, runtime: ServerRuntime): void {
+     *   runtime.setTickRate(60); // Passer à 60 TPS
+     * }
+     * ```
+     */
+    setTickRate(tickRate: number): void;
+    /**
+     * Récupère le tick rate actuel
+     */
+    getTickRate(): number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStats(): ServerRuntimeStats;
+    destroy(): Promise<void>;
+    /**
+     * Setup network event handlers
+     */
+    private setupNetworkHandlers;
+    /**
+     * Main tick loop
+     */
+    private tick;
+    /**
+     * Broadcast updates to all connected clients
+     * Uses split packets:
+     * - Static layers → Reliable channel (guaranteed delivery)
+     * - Dynamic layers → Volatile channel (can drop packets for performance)
+     */
+    private broadcastUpdates;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+export { ServerRuntime };
+export type { ServerRuntimeOptions, ServerRuntimeStats };

package/dist/index.mjs

@@ -0,0 +1 @@
+var c=Object.defineProperty;var g=(r,t,e)=>t in r?c(r,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):r[t]=e;var l=(r,t)=>c(r,"name",{value:t,configurable:!0});var o=(r,t,e)=>(g(r,typeof t!="symbol"?t+"":t,e),e);import{Core as m}from"@utsp/core";import{SocketIOServer as v}from"@utsp/network-server";var p=class p{constructor(t){o(this,"core");o(this,"network");o(this,"options");o(this,"running",!1);o(this,"startTime",0);o(this,"lastTimestamp",0);o(this,"tickCount",0);o(this,"tps",0);o(this,"tpsUpdateTime",0);o(this,"tickInterval",null);this.options={application:t.application,port:t.port,host:t.host??"0.0.0.0",tickRate:t.tickRate??20,maxConnections:t.maxConnections??100,debug:t.debug??!1,width:t.width??80,height:t.height??25,cors:t.cors??{origin:"*"}},this.log("Initializing ServerRuntime..."),this.core=new m({mode:"server",maxUsers:this.options.maxConnections}),this.network=new v({port:this.options.port,host:this.options.host,cors:this.options.cors,maxConnections:this.options.maxConnections,debug:this.options.debug}),this.log("ServerRuntime initialized")}getMode(){return"server"}isRunning(){return this.running}setTickRate(t){if(t<=0||t>1e3)throw new Error(`Invalid tick rate: ${t}. Must be between 1 and 1000.`);if(this.options.tickRate=t,this.log(`Tick rate changed to ${t} TPS`),this.running&&this.tickInterval){clearInterval(this.tickInterval);let e=1e3/t;this.log(`Restarting tick loop at ${t} TPS (${e}ms)...`),this.tickInterval=setInterval(()=>{this.tick()},e)}}getTickRate(){return this.options.tickRate}async start(){if(this.running){this.log("Already running");return}this.log("Starting ServerRuntime..."),await this.network.start(),this.log(`Server listening on ${this.options.host}:${this.options.port}`),this.setupNetworkHandlers(),this.log("Calling application.init()..."),this.options.application.init(this.core,this),this.running=!0,this.startTime=Date.now(),this.lastTimestamp=this.startTime,this.tpsUpdateTime=this.startTime;let t=1e3/this.options.tickRate;this.log(`Starting tick loop at ${this.options.tickRate} TPS (${t}ms)...`),this.tickInterval=setInterval(()=>{this.tick()},t)}async stop(){if(!this.running)return;this.log("Stopping ServerRuntime..."),this.running=!1,this.tickInterval&&(clearInterval(this.tickInterval),this.tickInterval=null),this.network.getClients().forEach(e=>{this.network.disconnectClient(e,"Server stopped")}),await this.network.stop(),this.log("ServerRuntime stopped")}getStats(){return{mode:"server",running:this.running,userCount:this.core.getUsers().length,tps:this.tps,uptime:this.running?Date.now()-this.startTime:0,totalTicks:this.tickCount}}async destroy(){await this.stop(),this.log("Destroying ServerRuntime..."),this.options.application.destroy&&this.options.application.destroy(),await this.network.destroy(),this.log("ServerRuntime destroyed")}setupNetworkHandlers(){this.network.onConnect(t=>{this.log(`Client connected: ${t}`)}),this.network.onDisconnect((t,e)=>{this.log(`Client disconnected: ${t} (${e})`);let i=this.core.getUser(t);i&&(this.options.application.destroyUser&&this.options.application.destroyUser(this.core,i,e),this.core.removeUser(t))}),this.network.on("join",(t,e)=>{this.log(`Join request from ${t}: ${e.username}`);try{let i=e.username||`Player${t.substring(0,4)}`,s=this.core.createUser(t,i);this.options.application.initUser(this.core,s,{username:i,token:e.token}),this.network.sendToClient(t,"join_response",{success:!0,userId:t,roomId:"main"});let n=this.core.generateAllLoadPackets();this.log(`Sending ${n.length} load packets to ${t}...`),n.forEach(u=>{this.network.sendToClient(t,"load",u)});let a=s.getInputBindingsLoadPacket();a&&(this.network.sendToClient(t,"input-bindings",a),this.log(`Sent input bindings to ${t}`)),this.log(`User ${i} (${t}) joined`)}catch(i){this.log(`Failed to join: ${i}`),this.network.sendToClient(t,"join_response",{success:!1,error:"Failed to join game"})}}),this.network.on("leave",t=>{this.log(`Leave request from ${t}`),this.network.disconnectClient(t,"User left")}),this.network.on("input",(t,e)=>{let i=this.core.getUser(t);if(!i){this.log(`Input from unknown user: ${t}`);return}if(e.axes&&Object.entries(e.axes).forEach(([s,n])=>{i.setAxis(s,n)}),e.buttons&&Object.entries(e.buttons).forEach(([s,n])=>{i.setButton(s,n)}),e.mousePosition){let{x:s,y:n}=e.mousePosition;i.setMousePosition(s,n,!0)}e.textInputs&&Array.isArray(e.textInputs)&&i.setTextInputs(e.textInputs)})}tick(){if(!this.running)return;let t=Date.now(),e=(t-this.lastTimestamp)/1e3;this.lastTimestamp=t,this.tickCount++,t-this.tpsUpdateTime>=1e3&&(this.tps=Math.round(this.tickCount*1e3/(t-this.tpsUpdateTime)),this.tickCount=0,this.tpsUpdateTime=t),this.options.application.update&&this.options.application.update(this.core,e),this.core.getUsers().forEach(s=>{this.options.application.updateUser(this.core,s,e),s.clearTextInputs()}),this.core.endTick(),this.broadcastUpdates()}broadcastUpdates(){let t=this.core.endTickSplit(),e=this.core.getCurrentTick();t.forEach(({static:i,dynamic:s},n)=>{if(i&&(this.network.sendToClient(n,"update-static",i),console.warn(`[SERVER] update-static: ${i.length}B (tick ${e})`)),s){let a=this.network;a.sendToClientVolatile?a.sendToClientVolatile(n,"update-dynamic",s):this.network.sendToClient(n,"update-dynamic",s),console.warn(`[SERVER] update-dynamic: ${s.length}B (tick ${e})`)}})}log(t){this.options.debug&&console.warn(`[ServerRuntime] ${t}`)}};l(p,"ServerRuntime");var h=p;export{h as ServerRuntime};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@utsp/runtime-server",
+  "version": "0.1.1",
+  "description": "Server-side runtime for UTSP applications (Node.js, headless)",
+  "author": "Thomas Piquet",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thp-software/utsp.git",
+    "directory": "packages/runtime-server"
+  },
+  "bugs": {
+    "url": "https://github.com/thp-software/utsp/issues"
+  },
+  "homepage": "https://github.com/thp-software/utsp/tree/master/packages/runtime-server#readme",
+  "keywords": [
+    "utsp",
+    "runtime",
+    "server",
+    "multi-user",
+    "terminal",
+    "nodejs",
+    "headless"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@utsp/core": "0.1.1",
+    "@utsp/network-server": "0.1.1",
+    "@utsp/types": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs packages/runtime-server",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "typecheck": "tsc --noEmit"
+  }
+}