@nice2dev/game-engine 0.1.0

package/dist/types/devtools/DevTools.d.ts

@@ -0,0 +1,217 @@
+import { EventBus } from '../core/EventBus';
+export type ModuleState = 'loaded' | 'updating' | 'error' | 'disposed';
+export interface HMRModule {
+    id: string;
+    path: string;
+    state: ModuleState;
+    version: number;
+    /** The current module exports object. */
+    exports: Record<string, unknown>;
+    /** Timestamp of last update. */
+    lastUpdated: number;
+    /** Dependencies this module depends on. */
+    dependencies: string[];
+    /** Modules that depend on this one. */
+    dependents: string[];
+}
+export interface HMRUpdate {
+    moduleId: string;
+    previousVersion: number;
+    newVersion: number;
+    /** State to preserve across hot reload. */
+    preservedState?: Record<string, unknown>;
+    timestamp: number;
+}
+export type HMRAcceptCallback = (newModule: Record<string, unknown>) => void;
+export type HMRDisposeCallback = (data: Record<string, unknown>) => void;
+export declare class HotModuleReplacer {
+    readonly events: EventBus;
+    private modules;
+    private acceptCallbacks;
+    private disposeCallbacks;
+    private updateHistory;
+    private maxHistory;
+    /** Register a module with the HMR system. */
+    register(id: string, path: string, exports: Record<string, unknown>, dependencies?: string[]): void;
+    /** Register an accept handler — called when the module is hot-replaced. */
+    accept(moduleId: string, callback: HMRAcceptCallback): void;
+    /** Register a dispose handler — called before the module is replaced. */
+    dispose(moduleId: string, callback: HMRDisposeCallback): void;
+    /**
+     * Hot-replace a module with new exports.
+     * Calls dispose callbacks, updates the module, then calls accept callbacks.
+     */
+    update(moduleId: string, newExports: Record<string, unknown>): boolean;
+    /** Get a module by ID. */
+    getModule(id: string): HMRModule | undefined;
+    /** Get all registered modules. */
+    get allModules(): HMRModule[];
+    /** Get update history. */
+    get history(): readonly HMRUpdate[];
+    /** Remove a module from HMR tracking. */
+    unregister(moduleId: string): void;
+}
+export type AssetType = 'image' | 'audio' | 'font' | 'json' | 'tilemap' | 'script' | 'shader' | 'model' | 'unknown';
+export interface AssetMeta {
+    id: string;
+    name: string;
+    type: AssetType;
+    mimeType: string;
+    sizeBytes: number;
+    /** Original filename. */
+    originalName: string;
+    /** Processed / optimized data URL or blob URL. */
+    url: string;
+    /** Dimensions for images. */
+    width?: number;
+    height?: number;
+    /** Duration in seconds for audio. */
+    duration?: number;
+    /** Import timestamp. */
+    importedAt: number;
+    /** Tags for asset management. */
+    tags: string[];
+}
+export interface AssetProcessorOptions {
+    /** Max image dimension (resizes if larger). Default: 2048. */
+    maxImageDimension: number;
+    /** Image quality for JPEG/WebP (0-1). Default: 0.85. */
+    imageQuality: number;
+    /** Preferred output format for images. Default: 'webp'. */
+    preferredImageFormat: 'png' | 'webp' | 'jpeg';
+    /** Whether to generate thumbnail previews. Default: true. */
+    generateThumbnails: boolean;
+    /** Thumbnail size. Default: 128. */
+    thumbnailSize: number;
+}
+export declare class AssetPipeline {
+    readonly events: EventBus;
+    private assets;
+    private options;
+    private nextId;
+    constructor(options?: Partial<AssetProcessorOptions>);
+    /**
+     * Import a file (e.g., from drag & drop or file input).
+     * Processes and optimizes the asset based on its type.
+     */
+    importFile(file: File): Promise<AssetMeta>;
+    /** Import multiple files at once. */
+    importFiles(files: FileList | File[]): Promise<AssetMeta[]>;
+    /** Setup drag & drop on an HTML element. */
+    setupDropZone(element: HTMLElement): () => void;
+    /** Get an asset by ID. */
+    getAsset(id: string): AssetMeta | undefined;
+    /** Get all assets. */
+    getAllAssets(): AssetMeta[];
+    /** Get assets by type. */
+    getAssetsByType(type: AssetType): AssetMeta[];
+    /** Remove an asset. */
+    removeAsset(id: string): void;
+    /** Tag an asset. */
+    tagAsset(id: string, tag: string): void;
+    private detectType;
+    private sanitizeFilename;
+    private readFileAsDataURL;
+    private getImageDimensions;
+    private resizeImage;
+}
+export type DeployTarget = 'web' | 'pwa' | 'electron' | 'capacitor' | 'docker';
+export interface DeployConfig {
+    target: DeployTarget;
+    /** App display name. */
+    appName: string;
+    /** App version (semver). */
+    version: string;
+    /** App description. */
+    description: string;
+    /** App icon path (relative). */
+    iconPath?: string;
+    /** PWA-specific: start URL. */
+    startUrl?: string;
+    /** PWA-specific: theme color. */
+    themeColor?: string;
+    /** PWA-specific: background color. */
+    backgroundColor?: string;
+    /** Electron-specific: window dimensions. */
+    windowWidth?: number;
+    windowHeight?: number;
+    /** Capacitor-specific: bundle ID. */
+    bundleId?: string;
+    /** Whether to minify output. */
+    minify?: boolean;
+    /** Whether to generate source maps. */
+    sourceMaps?: boolean;
+    /** Custom environment variables. */
+    env?: Record<string, string>;
+}
+export interface DeployResult {
+    target: DeployTarget;
+    success: boolean;
+    outputPath?: string;
+    /** Generated files list. */
+    files: string[];
+    /** Total output size in bytes. */
+    totalSizeBytes: number;
+    /** Build duration in ms. */
+    buildDurationMs: number;
+    errors: string[];
+    warnings: string[];
+}
+export declare class DeployManager {
+    readonly events: EventBus;
+    /** Generate PWA manifest JSON. */
+    generatePWAManifest(config: DeployConfig): string;
+    /** Generate service worker registration code. */
+    generateServiceWorkerScript(): string;
+    /** Generate Electron main process entry. */
+    generateElectronMain(config: DeployConfig): string;
+    /** Generate Capacitor config. */
+    generateCapacitorConfig(config: DeployConfig): string;
+    /** Generate Dockerfile for containerized deployment. */
+    generateDockerfile(): string;
+    /** Generate deployment package.json scripts. */
+    generateDeployScripts(config: DeployConfig): Record<string, string>;
+    /** Estimate output size based on input assets. */
+    estimateOutputSize(assets: Array<{
+        sizeBytes: number;
+    }>, minify: boolean): number;
+}
+export interface CollaboratorCursor {
+    peerId: string;
+    displayName: string;
+    color: string;
+    /** Current position in the editor (line, column). */
+    position: {
+        line: number;
+        column: number;
+    };
+    /** Currently editing file/path. */
+    filePath: string;
+    /** Selection range (if any). */
+    selection?: {
+        startLine: number;
+        startCol: number;
+        endLine: number;
+        endCol: number;
+    };
+    /** Time of last update. */
+    lastSeen: number;
+}
+export declare class CollaborationManager {
+    readonly events: EventBus;
+    private cursors;
+    private localPeerId;
+    private colorIndex;
+    private staleTimeoutMs;
+    constructor(localPeerId: string);
+    /** Update a remote cursor position. */
+    updateCursor(peerId: string, data: Omit<CollaboratorCursor, 'color' | 'lastSeen'>): void;
+    /** Remove a collaborator. */
+    removeCursor(peerId: string): void;
+    /** Get all active cursors (excluding stale ones). */
+    getActiveCursors(): CollaboratorCursor[];
+    /** Get cursors in a specific file. */
+    getCursorsInFile(filePath: string): CollaboratorCursor[];
+    /** Number of active collaborators. */
+    get activeCount(): number;
+}

package/dist/types/devtools/DeveloperExperience.d.ts

@@ -0,0 +1,123 @@
+import type { Vec2 } from '../core/types';
+export interface EngineError {
+    code: string;
+    message: string;
+    suggestion: string;
+    docsSection?: string;
+    severity: 'error' | 'warning' | 'info';
+    context?: Record<string, unknown>;
+}
+/** Get a rich engine error by code */
+export declare function getEngineError(code: string, context?: Record<string, unknown>): EngineError;
+/** Format an engine error for console output */
+export declare function formatEngineError(err: EngineError): string;
+/** Throw a rich engine error */
+export declare function throwEngineError(code: string, context?: Record<string, unknown>): never;
+/** Log a rich engine warning */
+export declare function warnEngine(code: string, context?: Record<string, unknown>): void;
+export interface APIHint {
+    method: string;
+    module: string;
+    signature: string;
+    description: string;
+    example: string;
+    params: Array<{
+        name: string;
+        type: string;
+        description: string;
+        optional?: boolean;
+    }>;
+    returns: string;
+    since: string;
+    tags: string[];
+}
+/** Core API hints for auto-complete and intellisense */
+export declare const API_HINTS: APIHint[];
+/** Search API hints */
+export declare function searchAPIHints(query: string): APIHint[];
+export interface PerfSnapshot {
+    timestamp: number;
+    fps: number;
+    frameTimeMs: number;
+    entityCount: number;
+    systemCount: number;
+    drawCalls: number;
+    memoryMB: number;
+    gcPauses: number;
+}
+export interface PerfDashboard {
+    snapshots: PerfSnapshot[];
+    maxSnapshots: number;
+    warnings: string[];
+}
+export declare function createPerfDashboard(maxSnapshots?: number): PerfDashboard;
+export declare function recordPerfSnapshot(dashboard: PerfDashboard, snapshot: PerfSnapshot): void;
+/** Get average FPS from last N snapshots */
+export declare function getAverageFPS(dashboard: PerfDashboard, lastN?: number): number;
+/** Get performance summary */
+export declare function getPerfSummary(dashboard: PerfDashboard): {
+    avgFPS: number;
+    minFPS: number;
+    maxFPS: number;
+    avgFrameTime: number;
+    peakFrameTime: number;
+    totalWarnings: number;
+};
+export interface HealthCheckResult {
+    category: string;
+    status: 'ok' | 'warning' | 'error';
+    message: string;
+    details?: string;
+}
+/** Run a health check on common engine misconfigurations */
+export declare function runHealthCheck(config: {
+    entityCount: number;
+    systemCount: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    targetFps: number;
+    physicsTimestep: number;
+    maxTextureDimension: number;
+}): HealthCheckResult[];
+export interface DebugOverlayConfig {
+    /** Show FPS counter */
+    showFPS: boolean;
+    /** Show entity count */
+    showEntityCount: boolean;
+    /** Show draw calls */
+    showDrawCalls: boolean;
+    /** Show physics debug (colliders) */
+    showPhysicsDebug: boolean;
+    /** Show grid */
+    showGrid: boolean;
+    /** Grid size */
+    gridSize: number;
+    /** Show entity bounding boxes */
+    showBoundingBoxes: boolean;
+    /** Show entity origins (transform position) */
+    showOrigins: boolean;
+    /** Overlay position */
+    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Overlay opacity (0-1) */
+    opacity: number;
+}
+export declare const DEFAULT_DEBUG_OVERLAY: DebugOverlayConfig;
+/** Render a debug text overlay onto a canvas context */
+export declare function renderDebugOverlay(ctx: CanvasRenderingContext2D, config: DebugOverlayConfig, stats: {
+    fps: number;
+    entityCount: number;
+    drawCalls: number;
+    frameTimeMs: number;
+}, canvasSize: Vec2): void;
+export interface QuickStartTemplate {
+    id: string;
+    name: string;
+    description: string;
+    category: 'game' | 'demo' | 'prototype';
+    difficulty: 'beginner' | 'intermediate' | 'advanced';
+    /** Code template as string */
+    code: string;
+    /** Tags */
+    tags: string[];
+}
+export declare const QUICK_START_TEMPLATES: QuickStartTemplate[];

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

@@ -0,0 +1,3 @@
+export * from './AssetStore';
+export * from './DeveloperExperience';
+export * from './DevTools';

package/dist/types/docs/APIPlayground.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+export interface PlaygroundExample {
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    code: string;
+    setup?: string;
+    expectedOutput?: string;
+}
+export interface PlaygroundState {
+    code: string;
+    output: string[];
+    error: string | null;
+    running: boolean;
+}
+export declare const PLAYGROUND_EXAMPLES: PlaygroundExample[];
+export declare function createPlaygroundRunner(engineModule: Record<string, unknown>): {
+    run(code: string): {
+        output: string[];
+        error: string | null;
+    };
+};
+export declare const NiceAPIPlayground: React.FC<{
+    engineModule?: Record<string, unknown>;
+}>;

package/dist/types/docs/Cookbook.d.ts

@@ -0,0 +1,18 @@
+export interface Recipe {
+    id: string;
+    title: string;
+    description: string;
+    category: RecipeCategory;
+    tags: string[];
+    difficulty: 'easy' | 'medium' | 'hard';
+    code: string;
+    explanation: string;
+}
+export type RecipeCategory = 'movement' | 'physics' | 'animation' | 'input' | 'audio' | 'ai' | 'ui' | 'procedural' | 'rendering' | 'multiplayer' | 'optimization' | 'patterns';
+export declare const COOKBOOK_RECIPES: Recipe[];
+export declare function searchRecipes(query: string): Recipe[];
+export declare function getRecipesByCategory(category: RecipeCategory): Recipe[];
+export declare function getRecipeCategories(): {
+    category: RecipeCategory;
+    count: number;
+}[];

package/dist/types/docs/DocGenerator.d.ts

@@ -0,0 +1,83 @@
+import { EventBus } from '../core/EventBus';
+export type DocCategory = 'core' | 'ecs' | 'rendering' | 'physics' | 'audio' | 'input' | 'ui' | 'scene' | 'multiplayer' | 'editor' | 'legendary' | 'other';
+export type DocMemberKind = 'class' | 'interface' | 'type' | 'function' | 'constant' | 'enum';
+export interface DocParam {
+    name: string;
+    type: string;
+    description: string;
+    optional?: boolean;
+    defaultValue?: string;
+}
+export interface DocMember {
+    name: string;
+    kind: DocMemberKind;
+    description: string;
+    category?: DocCategory;
+    /** Signature or type representation. */
+    signature?: string;
+    /** Parameters (for functions/methods). */
+    params?: DocParam[];
+    /** Return type description. */
+    returns?: string;
+    /** Code example. */
+    example?: string;
+    /** Since which version. */
+    since?: string;
+    /** Deprecated message (if deprecated). */
+    deprecated?: string;
+    /** Related API names. */
+    seeAlso?: string[];
+    /** Tags for search. */
+    tags?: string[];
+}
+export interface DocModule {
+    name: string;
+    category: DocCategory;
+    description: string;
+    members: DocMember[];
+}
+export interface DocSearchResult {
+    member: DocMember;
+    module: string;
+    score: number;
+}
+export declare class DocRegistry {
+    readonly events: EventBus;
+    private modules;
+    /** Register a module's documentation. */
+    registerModule(mod: DocModule): void;
+    /** Unregister a module. */
+    unregisterModule(name: string): void;
+    /** Get a module by name. */
+    getModule(name: string): DocModule | undefined;
+    /** Get all registered modules. */
+    getAllModules(): DocModule[];
+    /** Get all modules in a category. */
+    getModulesByCategory(category: DocCategory): DocModule[];
+    /** Search across all docs. */
+    search(query: string, maxResults?: number): DocSearchResult[];
+    private scoreMember;
+    /** Get a specific member by name. */
+    findMember(memberName: string): {
+        member: DocMember;
+        module: string;
+    } | null;
+    /** Generate Markdown docs for a single module. */
+    generateModuleMarkdown(moduleName: string): string;
+    /** Generate full Markdown documentation for all modules. */
+    generateFullMarkdown(): string;
+    /** Generate a JSON index for interactive docs browser. */
+    generateSearchIndex(): Array<{
+        name: string;
+        module: string;
+        kind: DocMemberKind;
+        description: string;
+        tags: string[];
+    }>;
+    /** Total number of documented members. */
+    get totalMembers(): number;
+    /** Reset. */
+    clear(): void;
+}
+export declare const DOCS_ECS: DocModule;
+export declare const DOCS_RENDERING: DocModule;

package/dist/types/docs/Guides.d.ts

@@ -0,0 +1,18 @@
+export interface Guide {
+    id: string;
+    title: string;
+    category: 'architecture' | 'migration' | 'performance' | 'troubleshooting';
+    sections: GuideSection[];
+}
+export interface GuideSection {
+    heading: string;
+    content: string;
+    code?: string;
+}
+export declare const GUIDE_ARCHITECTURE: Guide;
+export declare const GUIDE_MIGRATION: Guide;
+export declare const GUIDE_PERFORMANCE: Guide;
+export declare const GUIDE_TROUBLESHOOTING: Guide;
+export declare const ALL_GUIDES: Guide[];
+export declare function getGuide(id: string): Guide | undefined;
+export declare function searchGuides(query: string): GuideSection[];

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

@@ -0,0 +1,4 @@
+export * from './APIPlayground';
+export * from './Cookbook';
+export * from './DocGenerator';
+export * from './Guides';