@nice2dev/game-engine 1.1.5 → 1.1.6

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

@@ -0,0 +1,121 @@
+/**
+ * @file LocalizationRuntime.ts
+ * @description In-game language switching and runtime localization
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Runtime language switching
+ * - String interpolation
+ * - Pluralization rules
+ * - Date/time/number formatting
+ * - RTL support
+ * - Fallback chains
+ * - Missing translation detection
+ * - Hot-swap translations
+ */
+export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+export interface LocaleInfo {
+    code: string;
+    name: string;
+    nativeName: string;
+    direction: 'ltr' | 'rtl';
+    dateFormat: string;
+    timeFormat: string;
+    numberFormat: NumberFormatInfo;
+    pluralRules: PluralRule[];
+}
+export interface NumberFormatInfo {
+    decimalSeparator: string;
+    thousandsSeparator: string;
+    currencySymbol: string;
+    currencyPosition: 'prefix' | 'suffix';
+}
+export interface PluralRule {
+    category: PluralCategory;
+    condition: (n: number) => boolean;
+}
+export interface TranslationEntry {
+    key: string;
+    value: string;
+    plural?: {
+        [K in PluralCategory]?: string;
+    };
+    context?: string;
+    description?: string;
+}
+export interface TranslationNamespace {
+    namespace: string;
+    entries: Map<string, TranslationEntry>;
+}
+export interface LocalizationConfig {
+    defaultLocale: string;
+    fallbackLocale: string;
+    availableLocales: string[];
+    interpolationPrefix: string;
+    interpolationSuffix: string;
+    missingKeyHandler?: (key: string, locale: string) => string;
+    loadNamespaceAsync?: (namespace: string, locale: string) => Promise<TranslationEntry[]>;
+}
+export interface InterpolationValues {
+    [key: string]: string | number | boolean | Date;
+}
+export interface FormattedDate {
+    full: string;
+    long: string;
+    medium: string;
+    short: string;
+    relative: string;
+}
+export interface FormattedNumber {
+    standard: string;
+    currency: string;
+    percent: string;
+    compact: string;
+}
+export declare const LOCALES: Record<string, LocaleInfo>;
+export declare const DEFAULT_LOCALIZATION_CONFIG: LocalizationConfig;
+export declare class LocalizationRuntime {
+    private config;
+    private currentLocale;
+    private localeInfo;
+    private namespaces;
+    private loadedNamespaces;
+    private missingKeys;
+    private onLocaleChanged?;
+    private onMissingKey?;
+    private onNamespaceLoaded?;
+    constructor(config?: Partial<LocalizationConfig>);
+    setLocale(locale: string): Promise<boolean>;
+    getLocale(): string;
+    getLocaleInfo(): LocaleInfo;
+    getAvailableLocales(): LocaleInfo[];
+    isRTL(): boolean;
+    addTranslations(namespace: string, locale: string, entries: TranslationEntry[]): void;
+    loadNamespace(namespace: string): Promise<boolean>;
+    hasNamespace(namespace: string): boolean;
+    t(key: string, values?: InterpolationValues, options?: {
+        namespace?: string;
+        count?: number;
+    }): string;
+    private getEntry;
+    private handleMissingKey;
+    private interpolate;
+    private formatValue;
+    private getPluralCategory;
+    formatDate(date: Date): FormattedDate;
+    private getRelativeTime;
+    formatNumber(value: number): FormattedNumber;
+    private formatCompact;
+    getMissingKeys(): string[];
+    clearMissingKeys(): void;
+    hasKey(key: string, namespace?: string): boolean;
+    getAllKeys(namespace?: string): string[];
+    setOnLocaleChanged(callback: (oldLocale: string, newLocale: string) => void): void;
+    setOnMissingKey(callback: (key: string, locale: string) => void): void;
+    setOnNamespaceLoaded(callback: (namespace: string, locale: string) => void): void;
+}
+export declare function createLocalizationRuntime(config?: Partial<LocalizationConfig>): LocalizationRuntime;
+export declare function createTranslationEntry(key: string, value: string, plural?: {
+    [K in PluralCategory]?: string;
+}): TranslationEntry;
+export declare function createLocaleInfo(code: string, name: string, nativeName: string, direction?: 'ltr' | 'rtl'): LocaleInfo;

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

@@ -0,0 +1,164 @@
+/**
+ * @file MemoryManagement.ts
+ * @description Allocation tracking and leak detection
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Allocation tracking
+ * - Leak detection
+ * - Memory snapshots
+ * - Heap profiling
+ * - GC monitoring
+ * - Memory budgets
+ * - Allocation statistics
+ * - Memory warnings
+ */
+export type AllocationCategory = 'texture' | 'mesh' | 'audio' | 'buffer' | 'object' | 'array' | 'string' | 'component' | 'entity' | 'system' | 'asset' | 'other';
+export interface AllocationRecord {
+    id: number;
+    category: AllocationCategory;
+    size: number;
+    tag: string;
+    stack?: string;
+    timestamp: number;
+    freed: boolean;
+    freedAt?: number;
+}
+export interface MemorySnapshot {
+    id: string;
+    timestamp: number;
+    totalAllocated: number;
+    totalFreed: number;
+    activeAllocations: number;
+    byCategory: Map<AllocationCategory, CategoryStats>;
+    byTag: Map<string, number>;
+    largestAllocations: AllocationRecord[];
+}
+export interface CategoryStats {
+    allocated: number;
+    freed: number;
+    active: number;
+    count: number;
+    peak: number;
+}
+export interface MemoryBudget {
+    total: number;
+    categories: Partial<Record<AllocationCategory, number>>;
+    warnThreshold: number;
+    criticalThreshold: number;
+}
+export interface LeakReport {
+    suspectedLeaks: SuspectedLeak[];
+    totalLeakedSize: number;
+    reportedAt: number;
+}
+export interface SuspectedLeak {
+    allocation: AllocationRecord;
+    age: number;
+    reason: string;
+}
+export interface GCStats {
+    collections: number;
+    totalPauseTime: number;
+    lastPauseTime: number;
+    lastCollectionTime: number;
+    avgPauseTime: number;
+}
+export interface MemoryStats {
+    totalAllocated: number;
+    totalFreed: number;
+    currentUsage: number;
+    peakUsage: number;
+    allocationCount: number;
+    freeCount: number;
+    activeAllocations: number;
+    avgAllocationSize: number;
+    gcStats: GCStats;
+}
+export interface MemoryConfig {
+    trackAllocations: boolean;
+    trackStacks: boolean;
+    stackDepth: number;
+    leakDetectionInterval: number;
+    leakAgeThreshold: number;
+    snapshotRetention: number;
+    budgets: MemoryBudget;
+}
+export declare const DEFAULT_MEMORY_CONFIG: MemoryConfig;
+export declare class MemoryTracker {
+    private config;
+    private allocations;
+    private nextAllocationId;
+    private stats;
+    private categoryStats;
+    private tagStats;
+    private snapshots;
+    private leakDetectionTimer;
+    private onMemoryWarning?;
+    private onMemoryCritical?;
+    private onLeakDetected?;
+    private onGC?;
+    constructor(config?: Partial<MemoryConfig>);
+    private initializeCategoryStats;
+    /**
+     * Track a memory allocation
+     */
+    alloc(size: number, category: AllocationCategory, tag?: string): number;
+    /**
+     * Track memory deallocation
+     */
+    free(id: number): boolean;
+    /**
+     * Track a resize operation
+     */
+    realloc(id: number, newSize: number): boolean;
+    private captureStack;
+    private checkBudgets;
+    startLeakDetection(): void;
+    stopLeakDetection(): void;
+    detectLeaks(): LeakReport;
+    takeSnapshot(id?: string): MemorySnapshot;
+    getSnapshots(): MemorySnapshot[];
+    compareSnapshots(snapshotA: string, snapshotB: string): {
+        allocationDiff: number;
+        freedDiff: number;
+        categoryDiffs: Map<AllocationCategory, number>;
+        tagDiffs: Map<string, number>;
+    } | null;
+    recordGC(pauseTime: number): void;
+    getStats(): MemoryStats;
+    getCategoryStats(category: AllocationCategory): CategoryStats | undefined;
+    getAllCategoryStats(): Map<AllocationCategory, CategoryStats>;
+    getTagStats(): Map<string, number>;
+    getLargestAllocations(count?: number): AllocationRecord[];
+    getAllocationsByCategory(category: AllocationCategory): AllocationRecord[];
+    getAllocationsByTag(tag: string): AllocationRecord[];
+    formatSize(bytes: number): string;
+    generateReport(): string;
+    reset(): void;
+    getConfig(): MemoryConfig;
+    setConfig(config: Partial<MemoryConfig>): void;
+    setOnMemoryWarning(callback: (usage: number, budget: number, category?: AllocationCategory) => void): void;
+    setOnMemoryCritical(callback: (usage: number, budget: number) => void): void;
+    setOnLeakDetected(callback: (report: LeakReport) => void): void;
+    setOnGC(callback: (stats: GCStats) => void): void;
+}
+export declare class TrackedAllocator {
+    private tracker;
+    private defaultCategory;
+    private defaultTag;
+    constructor(tracker: MemoryTracker, defaultCategory?: AllocationCategory, defaultTag?: string);
+    allocArrayBuffer(size: number, tag?: string): {
+        buffer: ArrayBuffer;
+        id: number;
+    };
+    allocTypedArray<T extends TypedArray>(ArrayType: new (length: number) => T, length: number, tag?: string): {
+        array: T;
+        id: number;
+    };
+    free(id: number): void;
+}
+type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
+export declare function createMemoryTracker(config?: Partial<MemoryConfig>): MemoryTracker;
+export declare function createTrackedAllocator(tracker: MemoryTracker, category?: AllocationCategory, tag?: string): TrackedAllocator;
+export {};

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

@@ -0,0 +1,180 @@
+/**
+ * @file ModSupport.ts
+ * @description Plugin/mod loading system for extensible games
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Mod discovery and loading
+ * - Dependency resolution
+ * - Version compatibility
+ * - Sandboxed execution
+ * - Mod configuration
+ * - Steam Workshop integration ready
+ * - Conflict detection
+ * - Load order management
+ */
+export type ModType = 'content' | 'gameplay' | 'visual' | 'audio' | 'total-conversion' | 'utility';
+export type ModState = 'discovered' | 'loading' | 'loaded' | 'enabled' | 'disabled' | 'error' | 'incompatible';
+export interface ModManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    website?: string;
+    type: ModType;
+    gameVersion: string;
+    gameVersionMin?: string;
+    gameVersionMax?: string;
+    dependencies: ModDependency[];
+    conflicts: string[];
+    loadOrder?: number;
+    entryPoint: string;
+    assets?: string[];
+    config?: ModConfigSchema;
+    tags: string[];
+    thumbnail?: string;
+}
+export interface ModDependency {
+    modId: string;
+    versionMin?: string;
+    versionMax?: string;
+    optional: boolean;
+}
+export interface ModConfigSchema {
+    [key: string]: {
+        type: 'string' | 'number' | 'boolean' | 'select';
+        default: unknown;
+        label: string;
+        description?: string;
+        options?: {
+            value: unknown;
+            label: string;
+        }[];
+        min?: number;
+        max?: number;
+    };
+}
+export interface ModInstance {
+    manifest: ModManifest;
+    state: ModState;
+    config: Record<string, unknown>;
+    loadedAt?: number;
+    error?: string;
+    exports?: ModExports;
+}
+export interface ModExports {
+    init?: () => void | Promise<void>;
+    update?: (deltaTime: number) => void;
+    shutdown?: () => void | Promise<void>;
+    onEnable?: () => void;
+    onDisable?: () => void;
+    onConfigChange?: (key: string, value: unknown) => void;
+    [key: string]: unknown;
+}
+export interface ModConflict {
+    modA: string;
+    modB: string;
+    reason: string;
+    severity: 'warning' | 'error';
+}
+export interface ModLoadResult {
+    success: boolean;
+    modId: string;
+    error?: string;
+    dependencies: string[];
+    loadTime: number;
+}
+export interface ModSupportConfig {
+    modsDirectory: string;
+    enabledModsFile: string;
+    configDirectory: string;
+    gameVersion: string;
+    maxMods: number;
+    sandboxEnabled: boolean;
+    allowNetworkAccess: boolean;
+    allowFileAccess: boolean;
+}
+export declare const DEFAULT_MOD_CONFIG: ModSupportConfig;
+export declare function parseVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export declare function compareVersions(a: string, b: string): number;
+export declare function isVersionCompatible(version: string, min?: string, max?: string): boolean;
+export declare class ModRegistry {
+    private mods;
+    private loadOrder;
+    register(manifest: ModManifest): ModInstance;
+    unregister(modId: string): void;
+    get(modId: string): ModInstance | undefined;
+    getAll(): ModInstance[];
+    getEnabled(): ModInstance[];
+    getByState(state: ModState): ModInstance[];
+    getByType(type: ModType): ModInstance[];
+    setState(modId: string, state: ModState, error?: string): void;
+    setConfig(modId: string, config: Record<string, unknown>): void;
+    setExports(modId: string, exports: ModExports): void;
+    getLoadOrder(): string[];
+    setLoadOrder(order: string[]): void;
+    private getDefaultConfig;
+}
+export declare class DependencyResolver {
+    private registry;
+    constructor(registry: ModRegistry);
+    resolve(modId: string): {
+        order: string[];
+        missing: ModDependency[];
+        circular: boolean;
+    };
+    resolveAll(): {
+        order: string[];
+        missing: ModDependency[];
+        circular: string[];
+    };
+}
+export declare class ConflictDetector {
+    private registry;
+    constructor(registry: ModRegistry);
+    detect(): ModConflict[];
+}
+export declare class ModLoader {
+    private config;
+    private registry;
+    private resolver;
+    private conflictDetector;
+    private onModDiscovered?;
+    private onModLoaded?;
+    private onModEnabled?;
+    private onModDisabled?;
+    private onConflict?;
+    constructor(config?: Partial<ModSupportConfig>);
+    discover(): Promise<ModManifest[]>;
+    registerMod(manifest: ModManifest): void;
+    private validateManifest;
+    load(modId: string): Promise<ModLoadResult>;
+    loadAll(): Promise<ModLoadResult[]>;
+    enable(modId: string): Promise<boolean>;
+    disable(modId: string): Promise<boolean>;
+    unload(modId: string): Promise<boolean>;
+    setModConfig(modId: string, key: string, value: unknown): void;
+    getModConfig(modId: string): Record<string, unknown> | undefined;
+    checkConflicts(): ModConflict[];
+    getLoadOrder(): string[];
+    setLoadOrder(order: string[]): void;
+    moveUp(modId: string): void;
+    moveDown(modId: string): void;
+    getMod(modId: string): ModInstance | undefined;
+    getAllMods(): ModInstance[];
+    getEnabledMods(): ModInstance[];
+    getModsByType(type: ModType): ModInstance[];
+    update(deltaTime: number): void;
+    setOnModDiscovered(callback: (manifest: ModManifest) => void): void;
+    setOnModLoaded(callback: (result: ModLoadResult) => void): void;
+    setOnModEnabled(callback: (modId: string) => void): void;
+    setOnModDisabled(callback: (modId: string) => void): void;
+    setOnConflict(callback: (conflict: ModConflict) => void): void;
+}
+export declare function createModLoader(config?: Partial<ModSupportConfig>): ModLoader;
+export declare function createModManifest(id: string, name: string, version: string, entryPoint: string, options?: Partial<ModManifest>): ModManifest;

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

@@ -0,0 +1,182 @@
+/**
+ * @file MultiThreadedPhysics.ts
+ * @description Physics simulation with Web Worker threading
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Physics on dedicated worker thread
+ * - Double-buffered state synchronization
+ * - Task parallelization
+ * - Thread pool management
+ * - Message batching
+ * - Shared memory (SharedArrayBuffer) support
+ */
+export interface PhysicsBody {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    angularVelocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    mass: number;
+    isStatic: boolean;
+    shapeType: 'box' | 'sphere' | 'capsule' | 'mesh';
+    shapeData: unknown;
+}
+export interface PhysicsWorld {
+    bodies: Map<string, PhysicsBody>;
+    gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export type WorkerMessageType = 'init' | 'step' | 'add-body' | 'remove-body' | 'update-body' | 'apply-force' | 'apply-impulse' | 'raycast' | 'sync-state' | 'state-update' | 'raycast-result' | 'collision-events';
+export interface WorkerMessage {
+    type: WorkerMessageType;
+    id?: number;
+    data?: unknown;
+}
+export interface PhysicsConfig {
+    workerUrl?: string;
+    useSharedMemory: boolean;
+    maxBodies: number;
+    substeps: number;
+    fixedTimestep: number;
+    gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export interface CollisionEvent {
+    bodyA: string;
+    bodyB: string;
+    point: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    normal: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    impulse: number;
+}
+export interface RaycastResult {
+    hit: boolean;
+    bodyId?: string;
+    point?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    normal?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    distance?: number;
+}
+export declare const DEFAULT_PHYSICS_CONFIG: PhysicsConfig;
+export declare class PhysicsThreadPool {
+    private workers;
+    private taskQueue;
+    private availableWorkers;
+    private workerTasks;
+    private nextTaskId;
+    private pendingTasks;
+    constructor(workerUrl: string, numWorkers: number);
+    execute<T>(task: unknown): Promise<T>;
+    private processQueue;
+    private handleMessage;
+    private handleError;
+    terminate(): void;
+}
+export declare class SharedPhysicsBuffer {
+    private buffer;
+    private bodyData;
+    private flags;
+    private lockArray;
+    private maxBodies;
+    constructor(maxBodies: number);
+    getBuffer(): SharedArrayBuffer;
+    writeBody(index: number, body: PhysicsBody): void;
+    readBody(index: number): Partial<PhysicsBody>;
+    lock(lockIndex: number): void;
+    unlock(lockIndex: number): void;
+}
+export declare class MultiThreadedPhysics {
+    private config;
+    private worker;
+    private sharedBuffer;
+    private bodies;
+    private bodyIndices;
+    private nextBodyIndex;
+    private messageId;
+    private pendingMessages;
+    private accumulator;
+    private isRunning;
+    private onCollision?;
+    private onStateUpdate?;
+    constructor(config?: Partial<PhysicsConfig>);
+    initialize(workerUrl?: string): Promise<void>;
+    private createWorkerBlob;
+    addBody(body: PhysicsBody): Promise<void>;
+    removeBody(id: string): Promise<void>;
+    updateBody(id: string, updates: Partial<PhysicsBody>): Promise<void>;
+    getBody(id: string): PhysicsBody | undefined;
+    step(dt: number): void;
+    applyForce(bodyId: string, force: {
+        x: number;
+        y: number;
+        z: number;
+    }): Promise<void>;
+    applyImpulse(bodyId: string, impulse: {
+        x: number;
+        y: number;
+        z: number;
+    }, point?: {
+        x: number;
+        y: number;
+        z: number;
+    }): Promise<void>;
+    raycast(origin: {
+        x: number;
+        y: number;
+        z: number;
+    }, direction: {
+        x: number;
+        y: number;
+        z: number;
+    }, maxDistance: number): Promise<RaycastResult>;
+    private sendMessage;
+    private handleMessage;
+    private handleStateUpdate;
+    private handleCollisionEvents;
+    private handleError;
+    setOnCollision(callback: (event: CollisionEvent) => void): void;
+    setOnStateUpdate(callback: (bodies: Map<string, PhysicsBody>) => void): void;
+    dispose(): void;
+}
+export declare function createMultiThreadedPhysics(config?: Partial<PhysicsConfig>): MultiThreadedPhysics;
+export declare function createPhysicsBody(id: string, options?: Partial<PhysicsBody>): PhysicsBody;
+export declare function createThreadPool(workerUrl: string, numWorkers?: number): PhysicsThreadPool;
+export declare function createSharedPhysicsBuffer(maxBodies: number): SharedPhysicsBuffer;