@nice2dev/game-engine 0.1.0

package/dist/types/core/GameLoop.d.ts

@@ -0,0 +1,32 @@
+export interface GameLoopCallbacks {
+    /** Called every frame with delta in seconds */
+    update(dt: number): void;
+    /** Called at fixed intervals (physics) */
+    fixedUpdate(fixedDt: number): void;
+    /** Called every frame after update */
+    render(interpolation: number): void;
+}
+export declare class GameLoop {
+    private callbacks;
+    private _running;
+    private _rafId;
+    private _lastTime;
+    private _accumulator;
+    private _frameCount;
+    private _fpsTime;
+    private _fps;
+    private _timeScale;
+    fixedTimestep: number;
+    maxDelta: number;
+    constructor(callbacks: GameLoopCallbacks);
+    get running(): boolean;
+    get fps(): number;
+    get frameCount(): number;
+    get timeScale(): number;
+    set timeScale(v: number);
+    start(): void;
+    stop(): void;
+    /** Run a single frame manually (for step-debug) */
+    stepFrame(dt?: number): void;
+    private tick;
+}

package/dist/types/core/ServiceLocator.d.ts

@@ -0,0 +1,36 @@
+export declare class ServiceLocator {
+    private static _instance;
+    private services;
+    static get instance(): ServiceLocator;
+    /** Register a service by key. */
+    register<T>(key: string, service: T): void;
+    /** Retrieve a service by key. Throws if not registered. */
+    get<T>(key: string): T;
+    /** Retrieve a service, or undefined if not registered. */
+    tryGet<T>(key: string): T | undefined;
+    /** Check if a service is registered. */
+    has(key: string): boolean;
+    /** Remove a service. */
+    unregister(key: string): boolean;
+    /** Remove all services. */
+    clear(): void;
+    /** Reset static singleton (for testing). */
+    static reset(): void;
+}
+export declare const SERVICE_KEYS: {
+    readonly CONFIG: "GameConfig";
+    readonly CLOCK: "GameClock";
+    readonly LOOP: "GameLoop";
+    readonly EVENTS: "EventBus";
+    readonly EVENT_BUS: "EventBus";
+    readonly INPUT: "InputManager";
+    readonly AUDIO: "AudioManager";
+    readonly RENDERER: "Renderer2D";
+    readonly CAMERA: "Camera2D";
+    readonly PHYSICS: "PhysicsEngine";
+    readonly SCENES: "SceneManager";
+    readonly SCENE_MANAGER: "SceneManager";
+    readonly PLAYERS: "PlayerManager";
+    readonly PLAYER_MANAGER: "PlayerManager";
+    readonly WORLD: "World";
+};

package/dist/types/core/TypeSafety.d.ts

@@ -0,0 +1,190 @@
+import type { Vec2, Vec3, Rect, Color, EntityId, Component, ComponentType } from './types';
+/**
+ * Discriminated union of all built-in component types.
+ * Use `component.type` to narrow the type safely.
+ */
+export type BuiltInComponentType = 'Transform' | 'Sprite' | 'Shape' | 'Collider2D' | 'RigidBody2D' | 'Text' | 'Animator' | 'Script' | 'AudioSource' | 'ParticleEmitter' | 'CameraTarget';
+/**
+ * Discriminated union mapping.
+ * Given a component `type` literal, resolves to the concrete component interface.
+ */
+export interface ComponentTypeMap {
+    Transform: {
+        type: 'Transform';
+        position: Vec2;
+        rotation: number;
+        scale: Vec2;
+        prevPosition: Vec2;
+        prevRotation: number;
+    };
+    Sprite: {
+        type: 'Sprite';
+        assetId: string | null;
+        width: number;
+        height: number;
+        opacity: number;
+        layer: number;
+        visible: boolean;
+    };
+    Shape: {
+        type: 'Shape';
+        shape: 'rect' | 'circle' | 'polygon' | 'line';
+        fillColor: Color;
+        strokeColor: Color;
+        layer: number;
+        visible: boolean;
+    };
+    Collider2D: {
+        type: 'Collider2D';
+        shape: 'aabb' | 'circle' | 'polygon';
+        width: number;
+        height: number;
+        radius: number;
+        isTrigger: boolean;
+    };
+    RigidBody2D: {
+        type: 'RigidBody2D';
+        bodyType: 'dynamic' | 'static' | 'kinematic';
+        velocity: Vec2;
+        mass: number;
+    };
+    Text: {
+        type: 'Text';
+        text: string;
+        fontSize: number;
+        fontFamily: string;
+    };
+    Animator: {
+        type: 'Animator';
+    };
+    Script: {
+        type: 'Script';
+        scriptId: string;
+    };
+    AudioSource: {
+        type: 'AudioSource';
+        soundId: string;
+        playing: boolean;
+    };
+    ParticleEmitter: {
+        type: 'ParticleEmitter';
+        rate: number;
+        maxParticles: number;
+    };
+    CameraTarget: {
+        type: 'CameraTarget';
+        priority: number;
+    };
+}
+/** Any concrete built-in component (discriminated union). */
+export type AnyBuiltInComponent = ComponentTypeMap[BuiltInComponentType] & Component;
+export declare function isVec2(value: unknown): value is Vec2;
+export declare function isVec3(value: unknown): value is Vec3;
+export declare function isRect(value: unknown): value is Rect;
+export declare function isColor(value: unknown): value is Color;
+export declare function isComponent(value: unknown): value is Component;
+export declare function isEntityId(value: unknown): value is EntityId;
+/** Narrow component to a specific built-in type. */
+export declare function isComponentOfType<T extends BuiltInComponentType>(component: Component, type: T): component is ComponentTypeMap[T] & Component;
+/**
+ * Get a component with type-safe narrowing instead of `as` cast.
+ * Returns undefined if entity doesn't have that component.
+ */
+export declare function getTypedComponent<T extends BuiltInComponentType>(components: Component[], type: T): (ComponentTypeMap[T] & Component) | undefined;
+/**
+ * Require a component — throws if not found (use only when guaranteed).
+ */
+export declare function requireComponent<T extends BuiltInComponentType>(components: Component[], type: T, entityId: EntityId): ComponentTypeMap[T] & Component;
+/**
+ * Standard event name pattern: `namespace:action`
+ * This type restricts event names to the correct format.
+ */
+export type EngineEventName = `engine:${string}` | `ecs:${string}` | `physics:${string}` | `input:${string}` | `audio:${string}` | `scene:${string}` | `render:${string}` | `network:${string}` | `editor:${string}` | `tutorial:${string}` | `plugin:${string}` | `collision:${string}` | `entity:${string}` | `sound:${string}` | `music:${string}` | `ui:${string}` | `game:${string}`;
+/** Known engine events with typed payloads. */
+export interface EngineEventMap {
+    'engine:start': void;
+    'engine:stop': void;
+    'engine:pause': void;
+    'engine:resume': void;
+    'ecs:entity-created': {
+        entityId: EntityId;
+    };
+    'ecs:entity-destroyed': {
+        entityId: EntityId;
+    };
+    'ecs:component-added': {
+        entityId: EntityId;
+        type: ComponentType;
+    };
+    'ecs:component-removed': {
+        entityId: EntityId;
+        type: ComponentType;
+    };
+    'physics:collision-enter': {
+        entityA: EntityId;
+        entityB: EntityId;
+    };
+    'physics:collision-exit': {
+        entityA: EntityId;
+        entityB: EntityId;
+    };
+    'input:gamepad-connected': {
+        index: number;
+    };
+    'input:gamepad-disconnected': {
+        index: number;
+    };
+    'audio:sound-play': {
+        id: string;
+        soundId: number;
+    };
+    'audio:music-play': {
+        id: string;
+    };
+    'scene:load': {
+        sceneId: string;
+    };
+    'scene:unload': {
+        sceneId: string;
+    };
+}
+/**
+ * Standard time parameter type.
+ * Use `dt` everywhere for delta time (seconds).
+ */
+export interface TimeDelta {
+    /** Delta time in seconds since last frame. */
+    readonly dt: number;
+    /** Fixed delta time in seconds (for physics). */
+    readonly fixedDt: number;
+    /** Total elapsed time in seconds. */
+    readonly elapsed: number;
+    /** Frame count since start. */
+    readonly frame: number;
+}
+/** Generic record type (replaces `Record<string, any>`). */
+export type StrictRecord<V = unknown> = Record<string, V>;
+/** JSON-serializable value (replaces `any` in serialization). */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Callback with optional data (replaces `(...args: any[]) => void`). */
+export type EventCallback<T = unknown> = (data: T) => void;
+/**
+ * Mark properties as strictly typed — no implicit `any` allowed.
+ * Use instead of `Partial<T>` where undefined is meaningful.
+ */
+export type StrictPartial<T> = {
+    [K in keyof T]?: T[K] | undefined;
+};
+/**
+ * Ensure at least one property is defined (replaces loose optionals).
+ */
+export type AtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+/**
+ * Use in `default` of switch to ensure all cases are handled.
+ * Compile-time error if a new case is added but not handled.
+ */
+export declare function assertNever(value: never, message?: string): never;

package/dist/types/core/Validation.d.ts

@@ -0,0 +1,24 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function clampPositive(value: number): number;
+export declare function assertFinite(value: number, name: string): void;
+export declare function assertPositive(value: number, name: string): void;
+export declare function assertNonNegative(value: number, name: string): void;
+export declare function assertInRange(value: number, min: number, max: number, name: string): void;
+export declare function assertNonEmpty(value: string, name: string): void;
+export declare function assertCanvasElement(el: unknown, name?: string): asserts el is HTMLCanvasElement;
+export interface ValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+export declare function validateGameSettings(settings: {
+    width?: number;
+    height?: number;
+    targetFps?: number;
+    maxPlayers?: number;
+}): ValidationResult;
+export declare function validatePhysicsSettings(settings: {
+    fixedTimestep?: number;
+    velocityIterations?: number;
+    positionIterations?: number;
+}): ValidationResult;

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

@@ -0,0 +1,7 @@
+export * from './types';
+export { GameLoop, type GameLoopCallbacks } from './GameLoop';
+export { GameClock } from './GameClock';
+export { GameConfig, DEFAULT_SETTINGS, DEFAULT_PHYSICS, DEFAULT_AUDIO, DEFAULT_RENDERING } from './GameConfig';
+export { EventBus, type EventHandler } from './EventBus';
+export { ServiceLocator, SERVICE_KEYS } from './ServiceLocator';
+export { v2 } from './math';

package/dist/types/core/math.d.ts

@@ -0,0 +1,32 @@
+import type { Vec2 } from './types';
+export declare const v2: {
+    create(x?: number, y?: number): Vec2;
+    zero(): Vec2;
+    one(): Vec2;
+    clone(a: Vec2): Vec2;
+    add(a: Vec2, b: Vec2): Vec2;
+    sub(a: Vec2, b: Vec2): Vec2;
+    mul(a: Vec2, s: number): Vec2;
+    div(a: Vec2, s: number): Vec2;
+    dot(a: Vec2, b: Vec2): number;
+    cross(a: Vec2, b: Vec2): number;
+    len(a: Vec2): number;
+    lenSq(a: Vec2): number;
+    normalize(a: Vec2): Vec2;
+    dist(a: Vec2, b: Vec2): number;
+    distSq(a: Vec2, b: Vec2): number;
+    lerp(a: Vec2, b: Vec2, t: number): Vec2;
+    rotate(a: Vec2, angle: number): Vec2;
+    angle(a: Vec2): number;
+    angleBetween(a: Vec2, b: Vec2): number;
+    negate(a: Vec2): Vec2;
+    perpCW(a: Vec2): Vec2;
+    perpCCW(a: Vec2): Vec2;
+    reflect(a: Vec2, normal: Vec2): Vec2;
+    equals(a: Vec2, b: Vec2, epsilon?: number): boolean;
+    min(a: Vec2, b: Vec2): Vec2;
+    max(a: Vec2, b: Vec2): Vec2;
+    clamp(v: Vec2, min: Vec2, max: Vec2): Vec2;
+    fromAngle(angle: number, length?: number): Vec2;
+    random(minLen?: number, maxLen?: number): Vec2;
+};

package/dist/types/core/types.d.ts

@@ -0,0 +1,130 @@
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Color {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export type GameState = 'idle' | 'loading' | 'running' | 'paused' | 'menu' | 'gameover';
+/** Unique entity identifier */
+export type EntityId = number;
+/** Component type tag */
+export type ComponentType = string;
+/**
+ * Base component — all components extend this.
+ * Every component records its entity owner and type.
+ */
+export interface Component {
+    readonly type: ComponentType;
+    entityId: EntityId;
+    enabled: boolean;
+}
+/** Callback for system update */
+export type UpdateFn = (dt: number) => void;
+export type InputDevice = 'keyboard' | 'mouse' | 'gamepad' | 'touch';
+export interface InputAction {
+    name: string;
+    pressed: boolean;
+    justPressed: boolean;
+    justReleased: boolean;
+    value: number;
+}
+export type AudioChannel = 'master' | 'music' | 'sfx' | 'voice' | 'ui';
+export interface SceneData {
+    id: string;
+    name: string;
+    entities: SerializedEntity[];
+    settings: Record<string, unknown>;
+}
+export interface SerializedEntity {
+    id: EntityId;
+    name: string;
+    tags: string[];
+    components: SerializedComponent[];
+    children: EntityId[];
+}
+export interface SerializedComponent {
+    type: ComponentType;
+    data: Record<string, unknown>;
+}
+export interface GameProject {
+    /** .ndg format version */
+    formatVersion: number;
+    name: string;
+    version: string;
+    author: string;
+    description: string;
+    settings: GameSettings;
+    scenes: SceneData[];
+    startSceneId: string;
+    assets: AssetManifest;
+}
+export interface GameSettings {
+    width: number;
+    height: number;
+    targetFps: number;
+    maxPlayers: number;
+    physics: PhysicsSettings;
+    audio: AudioSettings;
+    rendering: RenderingSettings;
+}
+export interface PhysicsSettings {
+    gravity: Vec2;
+    fixedTimestep: number;
+    velocityIterations: number;
+    positionIterations: number;
+}
+export interface AudioSettings {
+    masterVolume: number;
+    musicVolume: number;
+    sfxVolume: number;
+    voiceVolume: number;
+}
+export interface RenderingSettings {
+    pixelPerfect: boolean;
+    antiAlias: boolean;
+    backgroundColor: Color;
+}
+export type AssetType = 'sprite' | 'spritesheet' | 'audio' | 'tilemap' | 'scene' | 'prefab' | 'script' | 'font';
+export interface AssetEntry {
+    id: string;
+    name: string;
+    type: AssetType;
+    path: string;
+    meta?: Record<string, unknown>;
+}
+export interface AssetManifest {
+    assets: AssetEntry[];
+}
+export type GameEventType = string;
+export interface GameEvent<T = unknown> {
+    type: GameEventType;
+    data: T;
+    timestamp: number;
+}
+export type ScreenMode = 'shared' | 'split-horizontal' | 'split-vertical' | 'split-quad' | 'split-6' | 'split-9' | 'split-12';
+export interface PlayerConfig {
+    index: number;
+    name: string;
+    color: Color;
+    inputDevice: InputDevice;
+    gamepadIndex?: number;
+}
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+export type Constructor<T = unknown> = new (...args: unknown[]) => T;

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

@@ -0,0 +1,133 @@
+export type AssetCategory = 'sprite' | 'audio' | 'tileset' | 'template' | 'font' | 'shader' | 'model3d' | 'particle' | 'animation';
+export type AssetLicense = 'free' | 'cc0' | 'cc-by' | 'premium' | 'subscription';
+export interface StoreAsset {
+    id: string;
+    name: string;
+    description: string;
+    category: AssetCategory;
+    tags: string[];
+    author: string;
+    license: AssetLicense;
+    price: number;
+    currency: string;
+    thumbnailUrl: string;
+    downloadUrl: string;
+    fileSize: number;
+    downloads: number;
+    rating: number;
+    ratingCount: number;
+    createdAt: string;
+    updatedAt: string;
+    version: string;
+    compatibility: string[];
+    preview?: string[];
+}
+export interface StoreSearchParams {
+    query?: string;
+    category?: AssetCategory;
+    license?: AssetLicense;
+    minRating?: number;
+    maxPrice?: number;
+    sortBy?: 'popular' | 'newest' | 'rating' | 'name' | 'price';
+    page?: number;
+    pageSize?: number;
+    tags?: string[];
+}
+export interface StoreSearchResult {
+    assets: StoreAsset[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface InstalledAsset {
+    asset: StoreAsset;
+    installedAt: string;
+    localPath: string;
+    version: string;
+}
+export declare const BUILTIN_FREE_ASSETS: StoreAsset[];
+export declare class AssetStore {
+    private installed;
+    private allAssets;
+    /** Search available assets. */
+    search(params?: StoreSearchParams): StoreSearchResult;
+    /** Get featured assets. */
+    getFeatured(): StoreAsset[];
+    /** Get assets by category. */
+    getByCategory(category: AssetCategory): StoreAsset[];
+    /** Install an asset (downloads and registers locally). */
+    install(assetId: string, localPath: string): InstalledAsset | null;
+    /** Uninstall an asset. */
+    uninstall(assetId: string): boolean;
+    /** Get installed assets. */
+    getInstalled(): InstalledAsset[];
+    /** Check if an asset is installed. */
+    isInstalled(assetId: string): boolean;
+    /** Register external assets (from remote catalog). */
+    registerAssets(assets: StoreAsset[]): void;
+}
+export type DiffType = 'added' | 'removed' | 'modified' | 'unchanged';
+export interface DiffEntry {
+    path: string;
+    type: DiffType;
+    oldValue?: unknown;
+    newValue?: unknown;
+    children?: DiffEntry[];
+}
+export interface ProjectDiff {
+    timestamp: string;
+    versionA: string;
+    versionB: string;
+    entities: DiffEntry[];
+    scenes: DiffEntry[];
+    assets: DiffEntry[];
+    settings: DiffEntry[];
+    summary: {
+        added: number;
+        removed: number;
+        modified: number;
+        unchanged: number;
+    };
+}
+/**
+ * Compare two serialized game projects and produce a diff.
+ */
+export declare function compareProjects(projectA: Record<string, unknown>, projectB: Record<string, unknown>, versionA?: string, versionB?: string): ProjectDiff;
+/** Format diff as human-readable text. */
+export declare function formatDiff(diff: ProjectDiff): string;
+export interface MarketplaceConfig {
+    /** Remote catalog endpoint URL */
+    catalogUrl?: string;
+    /** Max concurrent downloads */
+    maxConcurrent: number;
+    /** Auto-update installed plugins */
+    autoUpdate: boolean;
+    /** Allowed categories */
+    categories: string[];
+}
+export declare const DEFAULT_MARKETPLACE_CONFIG: MarketplaceConfig;
+export interface PluginInstallResult {
+    pluginId: string;
+    success: boolean;
+    version: string;
+    message: string;
+}
+/**
+ * Plugin Marketplace UI controller.
+ * Extends the PluginSDK's PluginMarketplace with one-click install flow.
+ */
+export declare class PluginMarketplaceUI {
+    private config;
+    private installing;
+    private installHistory;
+    constructor(config?: Partial<MarketplaceConfig>);
+    /** Check if a plugin is currently being installed. */
+    isInstalling(pluginId: string): boolean;
+    /** One-click install: validate, download, activate. */
+    installPlugin(pluginId: string, version?: string): Promise<PluginInstallResult>;
+    /** Uninstall a plugin. */
+    uninstallPlugin(pluginId: string): PluginInstallResult;
+    /** Get install history. */
+    getHistory(): PluginInstallResult[];
+}