@phalanx-engine/server 0.1.0

package/dist/utils/DeterministicRandom.d.ts

@@ -0,0 +1,88 @@
+import prand from 'pure-rand';
+/**
+ * Deterministic Random Number Generator
+ *
+ * Wrapper around pure-rand library for deterministic pseudo-random number generation.
+ * All clients initialized with the same seed will produce identical sequences.
+ *
+ * @example
+ * ```typescript
+ * const rng = new DeterministicRandom(12345);
+ * const damage = rng.intRange(10, 20); // Same on all clients with same seed
+ * ```
+ */
+export declare class DeterministicRandom {
+    private rng;
+    /**
+     * Create a new deterministic RNG with the given seed
+     * @param seed - A number seed value
+     */
+    constructor(seed: number);
+    /**
+     * Generate next random 32-bit integer and advance state
+     */
+    private nextInt;
+    /**
+     * Get next random float in range [0, 1)
+     */
+    float(): number;
+    /**
+     * Get next random float in range [min, max)
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (exclusive)
+     */
+    floatRange(min: number, max: number): number;
+    /**
+     * Get next random integer in range [min, max]
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     */
+    intRange(min: number, max: number): number;
+    /**
+     * Get next random integer in range [0, max)
+     * @param max - Maximum value (exclusive)
+     */
+    int(max: number): number;
+    /**
+     * Get next random boolean
+     * @param probability - Probability of true (default 0.5)
+     */
+    boolean(probability?: number): boolean;
+    /**
+     * Get a random element from an array
+     * @param array - Array to pick from
+     */
+    pick<T>(array: readonly T[]): T;
+    /**
+     * Shuffle an array in place using Fisher-Yates algorithm
+     * @param array - Array to shuffle
+     * @returns The same array, shuffled
+     */
+    shuffle<T>(array: T[]): T[];
+    /**
+     * Create a fork of this RNG with independent state
+     * Useful for parallel simulations that need separate random streams
+     */
+    fork(): DeterministicRandom;
+    /**
+     * Get current generator for serialization
+     * Note: pure-rand generators are immutable, so this returns a copy
+     */
+    getGenerator(): prand.RandomGenerator;
+    /**
+     * Set generator from previously saved state
+     * @param generator - Previously saved generator
+     */
+    setGenerator(generator: prand.RandomGenerator): void;
+    /**
+     * Generate a random seed (for server use)
+     * Uses crypto module for secure random seed generation
+     */
+    static generateSeed(): number;
+    /**
+     * Create RNG from a bigint seed (for compatibility with previous API)
+     * @param seed - A bigint to use as seed
+     */
+    static fromBigInt(seed: bigint): DeterministicRandom;
+}
+//# sourceMappingURL=DeterministicRandom.d.ts.map

package/dist/utils/DeterministicRandom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeterministicRandom.d.ts","sourceRoot":"","sources":["../../src/utils/DeterministicRandom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,WAAW,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,GAAG,CAAwB;IAEnC;;;OAGG;gBACS,IAAI,EAAE,MAAM;IAKxB;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;OAEG;IACH,KAAK,IAAI,MAAM;IAMf;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAI5C;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAQ1C;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIxB;;;OAGG;IACH,OAAO,CAAC,WAAW,GAAE,MAAY,GAAG,OAAO;IAI3C;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC;IAO/B;;;;OAIG;IACH,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE;IAU3B;;;OAGG;IACH,IAAI,IAAI,mBAAmB;IAM3B;;;OAGG;IACH,YAAY,IAAI,KAAK,CAAC,eAAe;IAIrC;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,eAAe,GAAG,IAAI;IAIpD;;;OAGG;IACH,MAAM,CAAC,YAAY,IAAI,MAAM;IAO7B;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB;CAIrD"}

package/dist/utils/DeterministicRandom.js

@@ -0,0 +1,140 @@
+import prand from 'pure-rand';
+/**
+ * Deterministic Random Number Generator
+ *
+ * Wrapper around pure-rand library for deterministic pseudo-random number generation.
+ * All clients initialized with the same seed will produce identical sequences.
+ *
+ * @example
+ * ```typescript
+ * const rng = new DeterministicRandom(12345);
+ * const damage = rng.intRange(10, 20); // Same on all clients with same seed
+ * ```
+ */
+export class DeterministicRandom {
+    rng;
+    /**
+     * Create a new deterministic RNG with the given seed
+     * @param seed - A number seed value
+     */
+    constructor(seed) {
+        // Use xoroshiro128+ algorithm - fast and high quality
+        this.rng = prand.xoroshiro128plus(seed);
+    }
+    /**
+     * Generate next random 32-bit integer and advance state
+     */
+    nextInt() {
+        const [value, next] = this.rng.next();
+        this.rng = next;
+        return value;
+    }
+    /**
+     * Get next random float in range [0, 1)
+     */
+    float() {
+        // Use unsigned 32-bit integer for conversion
+        const value = this.nextInt() >>> 0;
+        return value / 0x100000000;
+    }
+    /**
+     * Get next random float in range [min, max)
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (exclusive)
+     */
+    floatRange(min, max) {
+        return min + this.float() * (max - min);
+    }
+    /**
+     * Get next random integer in range [min, max]
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     */
+    intRange(min, max) {
+        min = Math.floor(min);
+        max = Math.floor(max);
+        const [value, next] = prand.uniformIntDistribution(min, max)(this.rng);
+        this.rng = next;
+        return value;
+    }
+    /**
+     * Get next random integer in range [0, max)
+     * @param max - Maximum value (exclusive)
+     */
+    int(max) {
+        return this.intRange(0, max - 1);
+    }
+    /**
+     * Get next random boolean
+     * @param probability - Probability of true (default 0.5)
+     */
+    boolean(probability = 0.5) {
+        return this.float() < probability;
+    }
+    /**
+     * Get a random element from an array
+     * @param array - Array to pick from
+     */
+    pick(array) {
+        if (array.length === 0) {
+            throw new Error('Cannot pick from empty array');
+        }
+        return array[this.intRange(0, array.length - 1)];
+    }
+    /**
+     * Shuffle an array in place using Fisher-Yates algorithm
+     * @param array - Array to shuffle
+     * @returns The same array, shuffled
+     */
+    shuffle(array) {
+        for (let i = array.length - 1; i > 0; i--) {
+            const j = this.intRange(0, i);
+            const temp = array[i];
+            array[i] = array[j];
+            array[j] = temp;
+        }
+        return array;
+    }
+    /**
+     * Create a fork of this RNG with independent state
+     * Useful for parallel simulations that need separate random streams
+     */
+    fork() {
+        // Generate a new seed from current state
+        const newSeed = this.nextInt();
+        return new DeterministicRandom(newSeed >>> 0);
+    }
+    /**
+     * Get current generator for serialization
+     * Note: pure-rand generators are immutable, so this returns a copy
+     */
+    getGenerator() {
+        return this.rng;
+    }
+    /**
+     * Set generator from previously saved state
+     * @param generator - Previously saved generator
+     */
+    setGenerator(generator) {
+        this.rng = generator;
+    }
+    /**
+     * Generate a random seed (for server use)
+     * Uses crypto module for secure random seed generation
+     */
+    static generateSeed() {
+        // Use dynamic import to avoid issues in environments without crypto
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const crypto = require('crypto');
+        return crypto.randomBytes(4).readUInt32BE();
+    }
+    /**
+     * Create RNG from a bigint seed (for compatibility with previous API)
+     * @param seed - A bigint to use as seed
+     */
+    static fromBigInt(seed) {
+        // Use lower 32 bits of the bigint
+        return new DeterministicRandom(Number(BigInt.asUintN(32, seed)));
+    }
+}
+//# sourceMappingURL=DeterministicRandom.js.map

package/dist/utils/DeterministicRandom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeterministicRandom.js","sourceRoot":"","sources":["../../src/utils/DeterministicRandom.ts"],"names":[],"mappings":"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"}

package/dist/utils/FixedMath.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Fixed-Point Math Module
+ *
+ * Re-exports from phalanx-math for convenience.
+ * The canonical implementation is in phalanx-math.
+ *
+ * @example
+ * ```typescript
+ * import { FP, FPVector3 } from '@phalanx-engine/server';
+ *
+ * const position = FPVector3.FromFloat(10.5, 0, 20.3);
+ * const target = FPVector3.FromFloat(5.0, 0, 10.0);
+ *
+ * const distance = FPVector3.Distance(position, target);
+ *
+ * // Convert back to number for display
+ * console.log(FP.ToFloat(distance));
+ * ```
+ */
+export { FixedPoint, FP, FPVector2, FPVector3, } from '@phalanx-engine/math';
+export type { FPVector2 as FPVector2Interface, FPVector3 as FPVector3Interface } from '@phalanx-engine/math';
+//# sourceMappingURL=FixedMath.d.ts.map

package/dist/utils/FixedMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FixedMath.d.ts","sourceRoot":"","sources":["../../src/utils/FixedMath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAEL,UAAU,EAEV,EAAE,EACF,SAAS,EACT,SAAS,GACV,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,SAAS,IAAI,kBAAkB,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/utils/FixedMath.js

@@ -0,0 +1,26 @@
+/**
+ * Fixed-Point Math Module
+ *
+ * Re-exports from phalanx-math for convenience.
+ * The canonical implementation is in phalanx-math.
+ *
+ * @example
+ * ```typescript
+ * import { FP, FPVector3 } from '@phalanx-engine/server';
+ *
+ * const position = FPVector3.FromFloat(10.5, 0, 20.3);
+ * const target = FPVector3.FromFloat(5.0, 0, 10.0);
+ *
+ * const distance = FPVector3.Distance(position, target);
+ *
+ * // Convert back to number for display
+ * console.log(FP.ToFloat(distance));
+ * ```
+ */
+// Re-export everything from phalanx-math
+export { 
+// Core type
+FixedPoint, 
+// Unified API (Unity/Quantum style)
+FP, FPVector2, FPVector3, } from '@phalanx-engine/math';
+//# sourceMappingURL=FixedMath.js.map

package/dist/utils/FixedMath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FixedMath.js","sourceRoot":"","sources":["../../src/utils/FixedMath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yCAAyC;AACzC,OAAO;AACL,YAAY;AACZ,UAAU;AACV,oCAAoC;AACpC,EAAE,EACF,SAAS,EACT,SAAS,GACV,MAAM,sBAAsB,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Phalanx Engine Utilities
+ */
+export { DeterministicRandom } from './DeterministicRandom.js';
+export { FP, FPVector2, FPVector3, FixedPoint } from './FixedMath.js';
+export type { FPVector2Interface, FPVector3Interface } from './FixedMath.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+/**
+ * Phalanx Engine Utilities
+ */
+export { DeterministicRandom } from './DeterministicRandom.js';
+export { FP, FPVector2, FPVector3, FixedPoint } from './FixedMath.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@phalanx-engine/server",
+  "version": "0.1.0",
+  "description": "Phalanx Engine Server - A game-agnostic deterministic lockstep multiplayer server with authentication, matchmaking, and command synchronization",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "multiplayer",
+    "game-server",
+    "lockstep",
+    "deterministic",
+    "netcode",
+    "socket.io",
+    "matchmaking",
+    "phalanx"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phaeton-forge/phalanx-engine.git",
+    "directory": "phalanx-server"
+  },
+  "bugs": "https://github.com/phaeton-forge/phalanx-engine/issues",
+  "homepage": "https://github.com/phaeton-forge/phalanx-engine/tree/main/phalanx-server#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0.0 <25.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "pure-rand": "^7.0.1",
+    "socket.io": "^4.7.0",
+    "@phalanx-engine/math": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0",
+    "socket.io-client": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}