@quake2ts/server 0.0.1

package/src/index.ts

@@ -0,0 +1,8 @@
+// Export net implementations
+export * from './net/nodeWsDriver.js';
+export * from './dedicated.js';
+export * from './client.js';
+export * from './protocol.js';
+export { ServerOptions, createServer } from './dedicated.js';
+export { NetworkTransport } from './transport.js';
+export * from './server.js';

package/src/net/nodeWsDriver.ts

@@ -0,0 +1,129 @@
+import { NetDriver } from '@quake2ts/shared';
+import WebSocket from 'ws';
+
+export class WebSocketNetDriver implements NetDriver {
+  private socket: WebSocket | null = null;
+  private messageCallback: ((data: Uint8Array) => void) | null = null;
+  private closeCallback: (() => void) | null = null;
+  private errorCallback: ((error: Error) => void) | null = null;
+
+  async connect(url: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.socket = new WebSocket(url);
+        this.socket.binaryType = 'arraybuffer';
+
+        this.socket.onopen = () => {
+          resolve();
+        };
+
+        this.socket.onerror = (event) => {
+          const error = new Error('WebSocket connection error ' + event.message);
+          if (this.errorCallback) {
+            this.errorCallback(error);
+          }
+          reject(error);
+        };
+
+        this.socket.onclose = () => {
+          if (this.closeCallback) {
+            this.closeCallback();
+          }
+          this.socket = null;
+        };
+
+        this.socket.onmessage = (event) => {
+          if (this.messageCallback) {
+            if (event.data instanceof ArrayBuffer) {
+              this.messageCallback(new Uint8Array(event.data));
+            } else if (Buffer.isBuffer(event.data)) {
+               // ws in Node might return Buffer
+               this.messageCallback(new Uint8Array(event.data));
+            } else if (Array.isArray(event.data)) {
+                // Buffer[]
+                 const totalLength = event.data.reduce((acc, buf) => acc + buf.length, 0);
+                 const result = new Uint8Array(totalLength);
+                 let offset = 0;
+                 for (const buf of event.data) {
+                     result.set(buf, offset);
+                     offset += buf.length;
+                 }
+                 this.messageCallback(result);
+            } else {
+              console.warn('Received non-binary message from server', typeof event.data);
+            }
+          }
+        };
+
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+
+  // Method to attach an existing socket (server-side incoming connection)
+  attach(socket: WebSocket) {
+      this.socket = socket;
+      this.socket.binaryType = 'arraybuffer';
+
+      this.socket.onclose = () => {
+          if (this.closeCallback) this.closeCallback();
+          this.socket = null;
+      };
+
+      this.socket.onerror = (event) => {
+          if (this.errorCallback) this.errorCallback(new Error(event.message));
+      };
+
+      this.socket.onmessage = (event) => {
+          if (this.messageCallback) {
+             if (event.data instanceof ArrayBuffer) {
+                  this.messageCallback(new Uint8Array(event.data));
+             } else if (Buffer.isBuffer(event.data)) {
+                 this.messageCallback(new Uint8Array(event.data));
+             } else if (Array.isArray(event.data)) { // ws specific
+                 // handle fragmentation if necessary, usually it's Buffer[]
+                 const totalLength = event.data.reduce((acc: number, buf: Buffer) => acc + buf.length, 0);
+                 const result = new Uint8Array(totalLength);
+                 let offset = 0;
+                 for (const buf of event.data) {
+                     result.set(buf, offset);
+                     offset += buf.length;
+                 }
+                 this.messageCallback(result);
+             }
+          }
+      };
+  }
+
+  disconnect(): void {
+    if (this.socket) {
+      this.socket.close();
+      this.socket = null;
+    }
+  }
+
+  send(data: Uint8Array): void {
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+      this.socket.send(data);
+    } else {
+      console.warn('Attempted to send data on closed or connecting socket');
+    }
+  }
+
+  onMessage(callback: (data: Uint8Array) => void): void {
+    this.messageCallback = callback;
+  }
+
+  onClose(callback: () => void): void {
+    this.closeCallback = callback;
+  }
+
+  onError(callback: (error: Error) => void): void {
+    this.errorCallback = callback;
+  }
+
+  isConnected(): boolean {
+    return this.socket !== null && this.socket.readyState === WebSocket.OPEN;
+  }
+}

package/src/protocol/player.ts

@@ -0,0 +1,2 @@
+export { writePlayerState } from '@quake2ts/shared';
+export type { ProtocolPlayerState } from '@quake2ts/shared';

package/src/protocol/write.ts

@@ -0,0 +1,185 @@
+import { BinaryWriter, ServerCommand, TempEntity, Vec3 } from '@quake2ts/shared';
+import { Entity } from '@quake2ts/game';
+
+/**
+ * Writes a server command and its arguments to a BinaryWriter.
+ * This handles the serialization of generic arguments passed to multicast/unicast
+ * into the specific binary format expected by the protocol.
+ */
+export function writeServerCommand(writer: BinaryWriter, event: ServerCommand, ...args: any[]): void {
+    writer.writeByte(event);
+
+    switch (event) {
+        case ServerCommand.print: {
+            // args: [level: number, text: string]
+            const level = args[0] as number;
+            const text = args[1] as string;
+            writer.writeByte(level);
+            writer.writeString(text);
+            break;
+        }
+
+        case ServerCommand.centerprint: {
+            // args: [text: string]
+            const text = args[0] as string;
+            writer.writeString(text);
+            break;
+        }
+
+        case ServerCommand.stufftext: {
+            // args: [text: string]
+            const text = args[0] as string;
+            writer.writeString(text);
+            break;
+        }
+
+        case ServerCommand.sound: {
+            // args: [flags, soundNum, volume?, attenuation?, offset?, ent?, pos?]
+            const flags = args[0] as number;
+            const soundNum = args[1] as number;
+            const volume = args[2] as number | undefined;
+            const attenuation = args[3] as number | undefined;
+            const offset = args[4] as number | undefined;
+            const ent = args[5] as number | undefined;
+            const pos = args[6] as Vec3 | undefined;
+
+            writer.writeByte(flags);
+            writer.writeByte(soundNum);
+
+            if (flags & 1) { // SND_VOLUME
+                writer.writeByte(volume || 0);
+            }
+            if (flags & 2) { // SND_ATTENUATION
+                writer.writeByte(attenuation || 0);
+            }
+            if (flags & 16) { // SND_OFFSET
+                writer.writeByte(offset || 0);
+            }
+            if (flags & 8) { // SND_ENT
+                writer.writeShort(ent || 0);
+            }
+            if (flags & 4) { // SND_POS
+                if (pos) {
+                    writer.writePos(pos);
+                } else {
+                    writer.writePos({x:0, y:0, z:0});
+                }
+            }
+            break;
+        }
+
+        case ServerCommand.muzzleflash: {
+            // args: [entityIndex: number, flashType: number]
+            const entIndex = args[0] as number;
+            const flashType = args[1] as number;
+            writer.writeShort(entIndex);
+            writer.writeByte(flashType);
+            break;
+        }
+
+        case ServerCommand.temp_entity: {
+            // args: [type: TempEntity, ...params]
+            const type = args[0] as TempEntity;
+            writer.writeByte(type);
+            writeTempEntity(writer, type, args.slice(1));
+            break;
+        }
+
+        default:
+            console.warn(`writeServerCommand: Unhandled command ${event}`);
+            break;
+    }
+}
+
+function writeTempEntity(writer: BinaryWriter, type: TempEntity, args: any[]): void {
+    switch (type) {
+        case TempEntity.ROCKET_EXPLOSION:
+        case TempEntity.GRENADE_EXPLOSION:
+        case TempEntity.EXPLOSION1:
+        case TempEntity.EXPLOSION2:
+        case TempEntity.ROCKET_EXPLOSION_WATER:
+        case TempEntity.GRENADE_EXPLOSION_WATER:
+        case TempEntity.BFG_EXPLOSION:
+        case TempEntity.BFG_BIGEXPLOSION:
+        case TempEntity.PLASMA_EXPLOSION:
+        case TempEntity.PLAIN_EXPLOSION:
+        case TempEntity.TRACKER_EXPLOSION:
+        case TempEntity.EXPLOSION1_BIG:
+        case TempEntity.EXPLOSION1_NP:
+        case TempEntity.EXPLOSION1_NL:
+        case TempEntity.EXPLOSION2_NL:
+        case TempEntity.BERSERK_SLAM:
+            // Format: [pos]
+            writer.writePos(args[0] as Vec3);
+            break;
+
+        case TempEntity.BLASTER:
+        case TempEntity.FLECHETTE:
+            // Format: [pos, dir]
+            writer.writePos(args[0] as Vec3);
+            writer.writeDir(args[1] as Vec3);
+            break;
+
+        case TempEntity.RAILTRAIL:
+        case TempEntity.DEBUGTRAIL:
+        case TempEntity.BUBBLETRAIL:
+        case TempEntity.BUBBLETRAIL2:
+        case TempEntity.BFG_LASER:
+        case TempEntity.LIGHTNING_BEAM:
+        case TempEntity.LIGHTNING:
+            // Format: [start, end]
+            writer.writePos(args[0] as Vec3);
+            writer.writePos(args[1] as Vec3);
+            break;
+
+        case TempEntity.LASER_SPARKS:
+        case TempEntity.WELDING_SPARKS:
+        case TempEntity.TUNNEL_SPARKS:
+        case TempEntity.ELECTRIC_SPARKS:
+        case TempEntity.HEATBEAM_SPARKS:
+        case TempEntity.HEATBEAM_STEAM:
+        case TempEntity.STEAM:
+            // Format: [count, pos, dir, color?]
+            // Q2: writeByte(count), writePos(start), writeDir(normal), writeByte(skin/color)
+            writer.writeByte(args[0] as number);
+            writer.writePos(args[1] as Vec3);
+            writer.writeDir(args[2] as Vec3);
+            writer.writeByte(args[3] as number || 0);
+            break;
+
+        case TempEntity.PARASITE_ATTACK:
+        case TempEntity.MEDIC_CABLE_ATTACK:
+            // Format: [entIndex, start, end]
+            // args[0] is Entity usually
+            const ent = args[0] as Entity;
+            writer.writeShort(ent ? ent.index : 0);
+            writer.writePos(args[1] as Vec3);
+            writer.writePos(args[2] as Vec3);
+            break;
+
+        case TempEntity.GUNSHOT:
+        case TempEntity.BLOOD:
+        case TempEntity.SPARKS:
+        case TempEntity.BULLET_SPARKS:
+        case TempEntity.SCREEN_SPARKS:
+        case TempEntity.SHIELD_SPARKS:
+            // Format: [pos, dir]
+            writer.writePos(args[0] as Vec3);
+            writer.writeDir(args[1] as Vec3);
+            break;
+
+        case TempEntity.SPLASH:
+        case TempEntity.POWER_SPLASH:
+        case TempEntity.WIDOWSPLASH:
+            // Format: [count, pos, dir, color]
+            writer.writeByte(args[0] as number);
+            writer.writePos(args[1] as Vec3);
+            writer.writeDir(args[2] as Vec3);
+            writer.writeByte(args[3] as number || 0);
+            break;
+
+        default:
+            console.warn(`writeTempEntity: Unhandled TempEntity ${type}`);
+            break;
+    }
+}

package/src/protocol.ts

@@ -0,0 +1,91 @@
+import { BinaryStream, ClientCommand, UserCommand } from '@quake2ts/shared';
+
+export interface ClientMessageHandler {
+  onMove(checksum: number, lastFrame: number, userCmd: UserCommand): void;
+  onUserInfo(info: string): void;
+  onStringCmd(cmd: string): void;
+  onNop(): void;
+  onBad(): void;
+}
+
+export class ClientMessageParser {
+  private stream: BinaryStream;
+  private handler: ClientMessageHandler;
+
+  constructor(stream: BinaryStream, handler: ClientMessageHandler) {
+    this.stream = stream;
+    this.handler = handler;
+  }
+
+  public parseMessage(): void {
+    while (this.stream.hasMore()) {
+      const cmdId = this.stream.readByte();
+      if (cmdId === -1) break;
+
+      switch (cmdId) {
+        case ClientCommand.move:
+          this.parseMove();
+          break;
+        case ClientCommand.userinfo:
+          this.parseUserInfo();
+          break;
+        case ClientCommand.stringcmd:
+          this.parseStringCmd();
+          break;
+        case ClientCommand.nop:
+          this.handler.onNop();
+          break;
+        default:
+          console.warn(`Unknown client command: ${cmdId}`);
+          this.handler.onBad();
+          return;
+      }
+    }
+  }
+
+  private parseMove(): void {
+    const checksum = this.stream.readByte();
+    const lastFrame = this.stream.readLong();
+
+    // Read UserCmd
+    // TODO: support delta compression if needed (Q2 uses delta compression for usercmds)
+    // For now, assume full UserCmd or implement basic read
+
+    const msec = this.stream.readByte();
+    const buttons = this.stream.readByte();
+    const angles = {
+      x: this.stream.readShort() * (360.0 / 65536.0),
+      y: this.stream.readShort() * (360.0 / 65536.0),
+      z: this.stream.readShort() * (360.0 / 65536.0),
+    };
+    const forwardmove = this.stream.readShort();
+    const sidemove = this.stream.readShort();
+    const upmove = this.stream.readShort();
+    const impulse = this.stream.readByte();
+    const lightlevel = this.stream.readByte(); // Used for light-based stealth, usually ignored by server logic except for stats
+
+    const userCmd: UserCommand = {
+      msec,
+      buttons,
+      angles,
+      forwardmove,
+      sidemove,
+      upmove,
+      impulse,
+      lightlevel,
+      sequence: 0 // Server doesn't read sequence from packet body in standard protocol, it tracks it
+    };
+
+    this.handler.onMove(checksum, lastFrame, userCmd);
+  }
+
+  private parseUserInfo(): void {
+    const info = this.stream.readString();
+    this.handler.onUserInfo(info);
+  }
+
+  private parseStringCmd(): void {
+    const cmd = this.stream.readString();
+    this.handler.onStringCmd(cmd);
+  }
+}

package/src/server.ts

@@ -0,0 +1,76 @@
+import { CollisionModel } from "@quake2ts/shared";
+import { EntityState, MAX_CONFIGSTRINGS, MAX_EDICTS, MAX_CHALLENGES } from "@quake2ts/shared";
+import { Client } from "./client.js";
+
+/**
+ * ServerState corresponds to server_state_t in the original source.
+ */
+export enum ServerState {
+    Dead,           // no map loaded
+    Loading,        // spawning level edicts
+    Game,           // actively running
+    Cinematic,
+    Demo,
+    Pic
+}
+
+export interface Challenge {
+    adr: string; // IP address
+    challenge: number;
+    time: number;
+}
+
+/**
+ * ServerStatic holds the state that is constant across server restarts.
+ * Corresponds to server_static_t in the original source.
+ */
+export interface ServerStatic {
+    initialized: boolean;
+    realTime: number; // always increasing
+
+    mapCmd: string;   // ie: *intro.cin+base
+
+    spawnCount: number; // incremented each server start
+
+    clients: (Client | null)[];
+
+    // In original this is: entity_state_t *client_entities;
+    // We might need a different approach in TS, but keeping the concept:
+    // This buffer holds entity states for all clients history.
+    // For now we might store it on the client directly or here.
+    // Original: client_entities[maxclients*UPDATE_BACKUP*MAX_PACKET_ENTITIES]
+
+    lastHeartbeat: number;
+
+    challenges: Challenge[];
+
+    // Demo recording stuff
+    demoFile?: any; // File handle
+}
+
+/**
+ * Server holds the state for the current running server instance.
+ * Corresponds to server_t in the original source.
+ */
+export interface Server {
+    state: ServerState;
+
+    attractLoop: boolean;
+    loadGame: boolean;
+
+    startTime: number; // Added back as it was used in dedicated.ts and is useful
+    time: number;       // sv.framenum * 100 msec
+    frame: number;
+
+    name: string;       // map name
+
+    // Models are handled by AssetManager in engine usually,
+    // but server needs collision models.
+    collisionModel: CollisionModel | null;
+
+    configStrings: string[]; // [MAX_CONFIGSTRINGS]
+    baselines: (EntityState | null)[]; // [MAX_EDICTS]
+
+    // Multicast buffer
+    multicastBuf: Uint8Array;
+}

package/src/transport.ts

@@ -0,0 +1,8 @@
+import { NetDriver } from '@quake2ts/shared';
+
+export interface NetworkTransport {
+    listen(port: number): Promise<void>;
+    close(): void;
+    onConnection(callback: (driver: NetDriver, info?: any) => void): void;
+    onError(callback: (error: Error) => void): void;
+}

package/src/transports/websocket.ts

@@ -0,0 +1,42 @@
+import { WebSocketServer } from 'ws';
+import { WebSocketNetDriver } from '../net/nodeWsDriver.js';
+import { NetworkTransport } from '../transport.js';
+import { NetDriver } from '@quake2ts/shared';
+
+export class WebSocketTransport implements NetworkTransport {
+    private wss: WebSocketServer | null = null;
+    private connectionCallback: ((driver: NetDriver, info?: any) => void) | null = null;
+    private errorCallback: ((error: Error) => void) | null = null;
+
+    async listen(port: number): Promise<void> {
+        return new Promise((resolve) => {
+            this.wss = new WebSocketServer({ port });
+            this.wss.on('listening', () => resolve());
+            this.wss.on('connection', (ws, req) => {
+                const driver = new WebSocketNetDriver();
+                driver.attach(ws);
+                if (this.connectionCallback) {
+                    this.connectionCallback(driver, req);
+                }
+            });
+            this.wss.on('error', (err) => {
+                if (this.errorCallback) this.errorCallback(err);
+            });
+        });
+    }
+
+    close() {
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+        }
+    }
+
+    onConnection(callback: (driver: NetDriver, info?: any) => void) {
+        this.connectionCallback = callback;
+    }
+
+    onError(callback: (error: Error) => void) {
+        this.errorCallback = callback;
+    }
+}

package/tests/client.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createClient, ClientState } from '../src/client.js';
+import { NetChan } from '@quake2ts/shared';
+import { createMockNetDriver } from '@quake2ts/test-utils';
+
+describe('Server Client', () => {
+    it('should initialize with NetChan', () => {
+        const mockNetDriver = createMockNetDriver();
+
+        const client = createClient(0, mockNetDriver);
+
+        expect(client).toBeDefined();
+        expect(client.netchan).toBeDefined();
+        expect(client.netchan).toBeInstanceOf(NetChan);
+        expect(client.state).toBe(ClientState.Connected);
+
+        // Verify qport is set (it's random, but should be a number)
+        expect(typeof client.netchan.qport).toBe('number');
+    });
+});

package/tests/connection_flow.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { DedicatedServer } from '../src/dedicated.js';
+import { createGame, GameExports } from '@quake2ts/game';
+import { ClientState } from '../src/client.js';
+import { createMockTransport, MockTransport, createMockServerClient, createMockNetDriver, createMockGameExports, createMockConnection } from '@quake2ts/test-utils';
+
+// Mock dependencies
+// ws mock removed
+vi.mock('node:fs/promises', () => ({
+  default: {
+    readFile: vi.fn().mockResolvedValue(Buffer.from([0])),
+  },
+}));
+vi.mock('@quake2ts/engine', () => ({
+  parseBsp: vi.fn().mockReturnValue({}),
+}));
+vi.mock('@quake2ts/game', () => ({
+  createGame: vi.fn(),
+  createPlayerInventory: vi.fn(),
+  createPlayerWeaponStates: vi.fn(),
+}));
+
+describe('DedicatedServer Connection Flow', () => {
+  let server: DedicatedServer;
+  let mockGame: GameExports;
+  let sentMessages: Uint8Array[] = [];
+  let consoleLogSpy: any;
+  let consoleWarnSpy: any;
+  let transport: MockTransport;
+
+  beforeEach(async () => {
+    sentMessages = [];
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    mockGame = createMockGameExports({
+      clientConnect: vi.fn().mockReturnValue(true),
+      clientBegin: vi.fn(() => ({ id: 1, classname: 'player' } as any)),
+    });
+
+    (createGame as vi.Mock).mockReturnValue(mockGame);
+
+    transport = createMockTransport();
+    server = new DedicatedServer({ transport });
+    await server.startServer('test.bsp');
+  });
+
+  afterEach(() => {
+    server.stopServer();
+    vi.clearAllMocks();
+    consoleLogSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should handle "connect" command', () => {
+    // 1. Setup a client using proper factory
+    const mockNet = createMockNetDriver({
+        send: vi.fn((data) => {
+            sentMessages.push(data);
+        })
+    });
+
+    // Use createMockConnection for more semantic setup, overriding with our mockNet
+    const client = createMockConnection(ClientState.Connected, {
+        net: mockNet,
+        edict: null, // Explicitly null edict as player hasn't entered game yet
+        index: 0
+    });
+
+    // Make sure transmit returns something so client.net.send is called with it
+    (client.netchan.transmit as any).mockReturnValue(new Uint8Array([1, 2, 3]));
+
+
+    // Inject client
+    // @ts-ignore
+    server.svs.clients[0] = client;
+
+    // 2. Simulate "connect" string command
+    // Use private access for unit testing
+    // @ts-ignore
+    server.handleStringCmd(client, 'connect \\name\\Player\\skin\\male/grunt');
+
+    // 3. Verify clientConnect was called
+    expect(mockGame.clientConnect).toHaveBeenCalledWith(null, '\\name\\Player\\skin\\male/grunt');
+
+    // 4. Verify response (ServerData)
+    // Check if any messages were sent
+    expect(sentMessages.length).toBeGreaterThan(0);
+
+    // Just verify that client.net.send was called.
+    expect(mockNet.send).toHaveBeenCalled();
+  });
+});