@nice2dev/game-engine 0.1.0

package/dist/types/network/Networking.d.ts

@@ -0,0 +1,199 @@
+import { EventBus } from '../core/EventBus';
+import type { Vec2, EntityId } from '../core/types';
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'failed';
+export interface PeerInfo {
+    peerId: string;
+    displayName: string;
+    state: ConnectionState;
+    latencyMs: number;
+    /** DataChannel reference */
+    channel: RTCDataChannel | null;
+    connection: RTCPeerConnection | null;
+}
+export interface SignalingMessage {
+    type: 'offer' | 'answer' | 'ice-candidate' | 'join' | 'leave' | 'room-info';
+    from: string;
+    to?: string;
+    roomId?: string;
+    payload: unknown;
+}
+export type SignalingTransport = {
+    send(msg: SignalingMessage): void;
+    onMessage: ((msg: SignalingMessage) => void) | null;
+    connect(url: string): Promise<void>;
+    disconnect(): void;
+};
+/** Default WebSocket-based signaling transport. */
+export declare function createWebSocketSignaling(): SignalingTransport;
+export interface RTCConfig {
+    iceServers?: RTCIceServer[];
+    dataChannelLabel?: string;
+    ordered?: boolean;
+    maxRetransmits?: number;
+}
+export declare class PeerManager {
+    readonly events: EventBus;
+    private peers;
+    private localId;
+    private rtcConfig;
+    private signaling;
+    constructor(localId: string, signaling: SignalingTransport, config?: Partial<RTCConfig>);
+    get localPeerId(): string;
+    get connectedPeers(): PeerInfo[];
+    getPeer(id: string): PeerInfo | undefined;
+    /** Initiate connection to a remote peer. */
+    connectToPeer(remotePeerId: string): Promise<void>;
+    private handleSignaling;
+    private setupChannel;
+    /** Send to a specific peer. */
+    sendTo(peerId: string, data: ArrayBuffer | string): void;
+    /** Broadcast to all connected peers. */
+    broadcast(data: ArrayBuffer | string): void;
+    /** Measure latency via ping / pong. */
+    ping(peerId: string): void;
+    disconnectPeer(peerId: string): void;
+    disconnectAll(): void;
+}
+export type NetworkMode = 'offline' | 'host' | 'client' | 'dedicated';
+export interface NetworkIdentity {
+    netId: number;
+    ownerId: string;
+    entityId: EntityId;
+}
+export interface RPCDef {
+    name: string;
+    /** 'server' = only host runs it, 'client' = everyone, 'owner' = only the owner */
+    target: 'server' | 'client' | 'owner';
+}
+export interface SyncVarDef {
+    entityId: EntityId;
+    component: string;
+    property: string;
+    /** Interpolate on clients (for transforms). */
+    interpolate: boolean;
+}
+export interface NetworkMessage {
+    type: 'rpc' | 'sync' | 'spawn' | 'destroy' | 'snapshot' | 'input' | 'ping' | 'pong';
+    tick: number;
+    senderId: string;
+    payload: unknown;
+}
+export declare class NetworkManager {
+    readonly events: EventBus;
+    private _mode;
+    private _tick;
+    private _tickRate;
+    private _tickAccumulator;
+    private identities;
+    private rpcHandlers;
+    private syncVars;
+    private _nextNetId;
+    peers: PeerManager | null;
+    get mode(): NetworkMode;
+    get tick(): number;
+    get tickRate(): number;
+    set tickRate(v: number);
+    get isHost(): boolean;
+    get isOnline(): boolean;
+    /** Start as host or client. */
+    start(mode: NetworkMode, peerManager: PeerManager): void;
+    stop(): void;
+    registerEntity(entityId: EntityId, ownerId: string): NetworkIdentity;
+    getIdentity(netId: number): NetworkIdentity | undefined;
+    getEntityIdentity(entityId: EntityId): NetworkIdentity | undefined;
+    registerRPC(name: string, handler: (senderId: string, args: unknown[]) => void): void;
+    callRPC(name: string, args: unknown[], target?: 'server' | 'all' | string): void;
+    registerSyncVar(def: SyncVarDef): void;
+    update(dt: number): void;
+    networkSpawn(entityId: EntityId, prefabName: string, position: Vec2): void;
+    networkDestroy(netId: number): void;
+    private handleMessage;
+}
+export interface Snapshot {
+    tick: number;
+    timestamp: number;
+    states: Map<number, EntityState>;
+}
+export interface EntityState {
+    netId: number;
+    position: Vec2;
+    rotation: number;
+    velocity: Vec2;
+    custom: Record<string, unknown>;
+}
+/** Snapshot buffer for interpolation / reconciliation. */
+export declare class SnapshotBuffer {
+    private buffer;
+    readonly maxSize: number;
+    constructor(maxSize?: number);
+    push(snapshot: Snapshot): void;
+    /** Get two snapshots bracketing the given server time for interpolation. */
+    getInterpolationPair(serverTime: number): [Snapshot, Snapshot] | null;
+    getLatest(): Snapshot | null;
+    getAtTick(tick: number): Snapshot | undefined;
+    clear(): void;
+}
+/** Linear interpolation between two entity states. */
+export declare function interpolateState(a: EntityState, b: EntityState, t: number): EntityState;
+/** Client-side prediction: store inputs for reconciliation. */
+export interface PredictionInput {
+    tick: number;
+    inputActions: Record<string, boolean | number>;
+    resultPosition: Vec2;
+}
+export declare class ClientPrediction {
+    private pendingInputs;
+    addInput(input: PredictionInput): void;
+    /** Clear inputs confirmed by server (tick <= serverTick). */
+    acknowledge(serverTick: number): void;
+    /** Re-apply unconfirmed inputs after server correction. */
+    getPendingInputs(): PredictionInput[];
+    clear(): void;
+}
+export interface LobbyRoom {
+    id: string;
+    name: string;
+    hostId: string;
+    maxPlayers: number;
+    currentPlayers: number;
+    isPublic: boolean;
+    hasPassword: boolean;
+    gameMode: string;
+    metadata: Record<string, unknown>;
+}
+export interface LobbyPlayer {
+    peerId: string;
+    displayName: string;
+    ready: boolean;
+    team: number;
+    slot: number;
+}
+export declare class LobbyManager {
+    readonly events: EventBus;
+    private _room;
+    private _players;
+    private _localPeerId;
+    constructor(localPeerId: string);
+    get room(): LobbyRoom | null;
+    get players(): LobbyPlayer[];
+    get isHost(): boolean;
+    get allReady(): boolean;
+    /** Create a new room (as host). */
+    createRoom(name: string, maxPlayers: number, gameMode: string, isPublic?: boolean): LobbyRoom;
+    joinRoom(room: LobbyRoom, displayName: string): void;
+    leaveRoom(): void;
+    addPlayer(peerId: string, displayName: string): void;
+    removePlayer(peerId: string): void;
+    setReady(peerId: string, ready: boolean): void;
+    setTeam(peerId: string, team: number): void;
+    /** Serialize lobby state for broadcasting. */
+    toJSON(): {
+        room: LobbyRoom;
+        players: LobbyPlayer[];
+    };
+    /** Apply state from host. */
+    fromJSON(data: {
+        room: LobbyRoom;
+        players: LobbyPlayer[];
+    }): void;
+}

package/dist/types/network/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Networking';
+export { LocalTransport, SignalRTransport, type IMultiplayerTransport, type TransportState, type TransportMessage, } from './MultiplayerTransport';

package/dist/types/pathfinding/Pathfinding.d.ts

@@ -0,0 +1,42 @@
+import type { Vec2 } from '../core/types';
+export interface PathGrid {
+    width: number;
+    height: number;
+    /** Return true if (x,y) is walkable. */
+    isWalkable(x: number, y: number): boolean;
+    /** Movement cost to enter (x,y). Default = 1. */
+    cost?(x: number, y: number): number;
+}
+export interface PathfinderOptions {
+    /** Allow diagonal movement (default true). */
+    allowDiagonals?: boolean;
+    /** Maximum iterations before giving up (default 2000). */
+    maxIterations?: number;
+    /** Heuristic weight – higher = faster but less optimal (default 1). */
+    heuristicWeight?: number;
+}
+export declare function findPath(grid: PathGrid, startX: number, startY: number, endX: number, endY: number, options?: PathfinderOptions): Vec2[] | null;
+export declare function smoothPath(path: Vec2[], grid: PathGrid): Vec2[];
+export declare class FlowField {
+    readonly width: number;
+    readonly height: number;
+    /** Direction vectors for each cell. */
+    readonly directions: Vec2[];
+    /** Dijkstra cost for each cell (Infinity = unreachable). */
+    readonly costs: Float32Array;
+    constructor(width: number, height: number);
+    /** Generate flow field towards target (tileX, tileY). */
+    generate(grid: PathGrid, targetX: number, targetY: number): void;
+    getDirection(tileX: number, tileY: number): Vec2;
+    getCost(tileX: number, tileY: number): number;
+}
+export interface NavPolygon {
+    id: number;
+    vertices: Vec2[];
+    neighbors: number[];
+}
+export interface NavMesh {
+    polygons: NavPolygon[];
+}
+/** Find which polygon contains a point (simple point-in-polygon test). */
+export declare function findContainingPolygon(mesh: NavMesh, point: Vec2): NavPolygon | null;

package/dist/types/pathfinding/index.d.ts

@@ -0,0 +1 @@
+export * from './Pathfinding';

package/dist/types/performance/AssetCompression.d.ts

@@ -0,0 +1,137 @@
+export type AssetType = 'texture' | 'audio' | 'mesh' | 'animation' | 'font' | 'data';
+export interface CompressionStats {
+    originalSize: number;
+    compressedSize: number;
+    ratio: number;
+    duration: number;
+    format: string;
+}
+export interface TextureCompressionConfig {
+    format: 'webp' | 'avif' | 'basis' | 'ktx2' | 'png';
+    quality: number;
+    maxWidth: number;
+    maxHeight: number;
+    generateMipmaps: boolean;
+    premultiplyAlpha: boolean;
+    powerOfTwo: boolean;
+}
+export interface AudioCompressionConfig {
+    format: 'opus' | 'aac' | 'mp3' | 'ogg';
+    bitrate: number;
+    sampleRate: number;
+    channels: 1 | 2;
+    normalize: boolean;
+}
+export interface MeshCompressionConfig {
+    quantizationBits: number;
+    mergeVertices: boolean;
+    stripNormals: boolean;
+    stripUVs: boolean;
+    draco: boolean;
+}
+export interface AssetManifest {
+    version: number;
+    assets: AssetEntry[];
+    totalOriginalSize: number;
+    totalCompressedSize: number;
+    compressionRatio: number;
+}
+export interface AssetEntry {
+    id: string;
+    type: AssetType;
+    originalPath: string;
+    compressedPath: string;
+    originalSize: number;
+    compressedSize: number;
+    format: string;
+    hash: string;
+    metadata?: Record<string, unknown>;
+}
+export interface StreamingConfig {
+    chunkSize: number;
+    concurrency: number;
+    priorityLevels: number;
+    preloadDistance: number;
+}
+export declare class TextureCompressor {
+    private config;
+    constructor(config?: Partial<TextureCompressionConfig>);
+    compress(imageData: ImageData | HTMLCanvasElement): Promise<{
+        blob: Blob;
+        stats: CompressionStats;
+    }>;
+    generateMipmaps(canvas: HTMLCanvasElement): Promise<HTMLCanvasElement[]>;
+    private resizeCanvas;
+    private ensurePowerOfTwo;
+    private getMimeType;
+}
+export declare class AudioCompressor {
+    private config;
+    constructor(config?: Partial<AudioCompressionConfig>);
+    compress(audioBuffer: AudioBuffer): Promise<{
+        blob: Blob;
+        stats: CompressionStats;
+    }>;
+    private resample;
+    private normalizeAudio;
+    private encodeWAV;
+    private writeString;
+}
+export declare class MeshCompressor {
+    private config;
+    constructor(config?: Partial<MeshCompressionConfig>);
+    compress(vertices: Float32Array, indices: Uint32Array, normals?: Float32Array, uvs?: Float32Array): {
+        vertices: Float32Array | Int16Array;
+        indices: Uint32Array | Uint16Array;
+        normals?: Float32Array | Int8Array;
+        uvs?: Float32Array | Uint16Array;
+        stats: CompressionStats;
+    };
+    private quantizeVertices;
+    private quantizeNormals;
+    private quantizeUVs;
+    private mergeVertices;
+}
+export declare class AssetStreamer {
+    private config;
+    private activeDownloads;
+    private queue;
+    private cache;
+    constructor(config?: Partial<StreamingConfig>);
+    load(url: string, priority?: number): Promise<ArrayBuffer>;
+    private processQueue;
+    preload(urls: string[], priority?: number): Promise<void[]>;
+    evict(url: string): boolean;
+    clearCache(): void;
+    get cacheSize(): number;
+    get pendingDownloads(): number;
+}
+export declare class AssetPipeline {
+    private textureCompressor;
+    private audioCompressor;
+    private meshCompressor;
+    private streamer;
+    private manifest;
+    constructor(config?: {
+        texture?: Partial<TextureCompressionConfig>;
+        audio?: Partial<AudioCompressionConfig>;
+        mesh?: Partial<MeshCompressionConfig>;
+        streaming?: Partial<StreamingConfig>;
+    });
+    getTextureCompressor(): TextureCompressor;
+    getAudioCompressor(): AudioCompressor;
+    getMeshCompressor(): MeshCompressor;
+    getStreamer(): AssetStreamer;
+    getManifest(): Readonly<AssetManifest>;
+    addToManifest(entry: AssetEntry): void;
+    exportManifest(): string;
+    getCompressionSummary(): {
+        totalAssets: number;
+        byType: Record<string, {
+            count: number;
+            savedBytes: number;
+        }>;
+        totalSavedBytes: number;
+        overallRatio: number;
+    };
+}

package/dist/types/performance/BenchmarkSuite.d.ts

@@ -0,0 +1,99 @@
+export interface BenchmarkScenario {
+    /** Unique scenario ID. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Category for grouping. */
+    category: 'ecs' | 'rendering' | 'physics' | 'scene' | 'general';
+    /** Setup — called once before the benchmark runs. Returns cleanup fn if needed. */
+    setup?: () => void | (() => void);
+    /** The function to benchmark. Called repeatedly. */
+    run: () => void;
+    /** Teardown — called after the benchmark finishes. */
+    teardown?: () => void;
+    /** How many warm-up iterations before measuring. Default: 10 */
+    warmup?: number;
+    /** How many measured iterations. Default: 100 */
+    iterations?: number;
+    /** Expected max ms per iteration (for regression checks). */
+    budgetMs?: number;
+}
+export interface BenchmarkTimings {
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+    p95: number;
+    p99: number;
+    stdDev: number;
+    totalMs: number;
+    iterations: number;
+}
+export interface BenchmarkMemory {
+    heapUsedBefore: number;
+    heapUsedAfter: number;
+    heapDelta: number;
+}
+export interface BenchmarkResult {
+    scenarioId: string;
+    scenarioName: string;
+    category: string;
+    timings: BenchmarkTimings;
+    memory: BenchmarkMemory | null;
+    budgetMs: number | null;
+    withinBudget: boolean | null;
+    timestamp: number;
+}
+export interface BenchmarkReport {
+    /** Engine version or label. */
+    label: string;
+    /** ISO timestamp. */
+    date: string;
+    /** Platform info. */
+    platform: string;
+    /** All results. */
+    results: BenchmarkResult[];
+    /** Summary. */
+    summary: {
+        totalScenarios: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        totalTimeMs: number;
+    };
+}
+export interface RegressionResult {
+    scenarioId: string;
+    scenarioName: string;
+    /** Positive = slower (regression), negative = faster (improvement). */
+    meanDeltaPercent: number;
+    p95DeltaPercent: number;
+    /** Whether it exceeds the threshold. */
+    regressed: boolean;
+    improved: boolean;
+}
+export declare class BenchmarkRunner {
+    private scenarios;
+    private results;
+    /** Register a benchmark scenario. */
+    register(scenario: BenchmarkScenario): void;
+    /** Register multiple scenarios. */
+    registerAll(scenarios: BenchmarkScenario[]): void;
+    /** Run a single scenario. */
+    runScenario(id: string): BenchmarkResult | null;
+    /** Run all registered scenarios. */
+    runAll(): BenchmarkReport;
+    /** Run scenarios in a specific category. */
+    runCategory(category: BenchmarkScenario['category']): BenchmarkReport;
+    /** Generate a full report from collected results. */
+    generateReport(label?: string): BenchmarkReport;
+    /** Compare two reports for regressions. */
+    static compareReports(baseline: BenchmarkReport, current: BenchmarkReport, regressionThresholdPercent?: number): RegressionResult[];
+    /** Get last results. */
+    getResults(): BenchmarkResult[];
+    /** Clear all scenarios and results. */
+    clear(): void;
+    private calculateTimings;
+    private getHeapUsed;
+}
+export declare const BUILTIN_BENCHMARKS: BenchmarkScenario[];

package/dist/types/performance/Performance.d.ts

@@ -0,0 +1,87 @@
+export interface Poolable {
+    /** Reset the object state for reuse. */
+    reset(): void;
+}
+export declare class ObjectPool<T extends Poolable> {
+    private pool;
+    private active;
+    private factory;
+    private maxSize;
+    constructor(factory: () => T, prewarm?: number, maxSize?: number);
+    acquire(): T;
+    release(obj: T): void;
+    releaseAll(): void;
+    activeCount(): number;
+    pooledCount(): number;
+    totalCount(): number;
+}
+export type AssetPriority = 'critical' | 'high' | 'normal' | 'low';
+export interface StreamRequest {
+    id: string;
+    url: string;
+    priority: AssetPriority;
+    loaded: boolean;
+    progress: number;
+    data: unknown;
+    error: string | null;
+}
+export declare class AssetStreamer {
+    private queue;
+    private loading;
+    private loaded;
+    private maxConcurrent;
+    constructor(maxConcurrent?: number);
+    enqueue(id: string, url: string, priority?: AssetPriority): StreamRequest;
+    isLoaded(id: string): boolean;
+    get(id: string): unknown;
+    private processQueue;
+    private loadAsset;
+    getPendingCount(): number;
+    getLoadedCount(): number;
+    clear(): void;
+}
+export interface LODLevel {
+    /** Max distance for this LOD. */
+    distance: number;
+    /** Asset or mesh ID. */
+    assetId: string;
+    /** Vertex reduction factor (1 = full, 0.5 = half polys). */
+    quality: number;
+}
+export interface LODGroup {
+    entityId: number;
+    levels: LODLevel[];
+    currentLevel: number;
+}
+export declare function selectLODLevel(group: LODGroup, distance: number): number;
+export declare function updateLODGroups(groups: LODGroup[], cameraPos: {
+    x: number;
+    y: number;
+    z: number;
+}, positions: Map<number, {
+    x: number;
+    y: number;
+    z: number;
+}>): void;
+export interface AABB {
+    minX: number;
+    minY: number;
+    minZ: number;
+    maxX: number;
+    maxY: number;
+    maxZ: number;
+}
+export interface FrustumPlane {
+    nx: number;
+    ny: number;
+    nz: number;
+    d: number;
+}
+export declare function aabbInFrustum(aabb: AABB, planes: FrustumPlane[]): boolean;
+/** Simple 2D frustum check for 2D camera views. */
+export declare function rectInView(rx: number, ry: number, rw: number, rh: number, viewX: number, viewY: number, viewW: number, viewH: number): boolean;
+export declare function measureMemory(): {
+    heapUsed: number;
+    heapTotal: number;
+} | null;
+export declare function formatBytes(bytes: number): string;