@nice2dev/game-engine 0.1.0

package/dist/types/release/MobileExport.d.ts

@@ -0,0 +1,218 @@
+export type ExportPlatform = 'web' | 'pwa' | 'android' | 'ios' | 'electron-win' | 'electron-mac' | 'electron-linux' | 'steam';
+export type ExportStep = 'prepare' | 'bundle' | 'optimize' | 'package' | 'sign' | 'deploy';
+export interface ExportPipelineConfig {
+    platform: ExportPlatform;
+    appName: string;
+    appId: string;
+    version: string;
+    buildNumber: number;
+    icon: string;
+    splashScreen?: string;
+    orientation: 'portrait' | 'landscape' | 'any';
+    minify: boolean;
+    sourceMaps: boolean;
+    treeshake: boolean;
+    compressionLevel: 'none' | 'fast' | 'best';
+    assetOptimization: AssetOptimizationConfig;
+    signing?: SigningConfig;
+}
+export interface AssetOptimizationConfig {
+    compressTextures: boolean;
+    textureFormat: 'png' | 'webp' | 'avif' | 'basis';
+    maxTextureSize: number;
+    compressAudio: boolean;
+    audioFormat: 'mp3' | 'ogg' | 'aac';
+    audioBitrate: number;
+    inlineSmallAssets: boolean;
+    inlineThresholdBytes: number;
+    generateSpriteAtlas: boolean;
+    atlasMaxSize: number;
+}
+export interface SigningConfig {
+    keystore?: string;
+    keystorePassword?: string;
+    keyAlias?: string;
+    teamId?: string;
+    provisioningProfile?: string;
+}
+export declare const DEFAULT_ASSET_OPTIMIZATION: AssetOptimizationConfig;
+export interface ExportResult {
+    platform: ExportPlatform;
+    success: boolean;
+    outputPath: string;
+    fileSize: number;
+    buildDuration: number;
+    errors: string[];
+    warnings: string[];
+}
+export interface PWAConfig {
+    name: string;
+    shortName: string;
+    description: string;
+    themeColor: string;
+    backgroundColor: string;
+    display: 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser';
+    orientation: 'portrait' | 'landscape' | 'any';
+    startUrl: string;
+    scope: string;
+    icons: PWAIcon[];
+    cacheStrategy: 'cache-first' | 'network-first' | 'stale-while-revalidate';
+    offlineSupport: boolean;
+    pushNotifications: boolean;
+    installPrompt: boolean;
+}
+export interface PWAIcon {
+    src: string;
+    sizes: string;
+    type: string;
+    purpose: 'any' | 'maskable' | 'monochrome';
+}
+export declare function generateServiceWorkerConfig(config: PWAConfig): Record<string, unknown>;
+export interface CapacitorConfig {
+    appId: string;
+    appName: string;
+    webDir: string;
+    plugins: CapacitorPluginConfig;
+    ios: CapacitorIOSConfig;
+    android: CapacitorAndroidConfig;
+}
+export interface CapacitorPluginConfig {
+    statusBar?: {
+        style: 'dark' | 'light';
+        backgroundColor: string;
+    };
+    splashScreen?: {
+        launchShowDuration: number;
+        launchAutoHide: boolean;
+        backgroundColor: string;
+    };
+    keyboard?: {
+        resize: 'body' | 'ionic' | 'native' | 'none';
+    };
+    haptics?: boolean;
+    screenOrientation?: string;
+}
+export interface CapacitorIOSConfig {
+    scheme: string;
+    contentInset: 'automatic' | 'always' | 'never';
+    allowsLinkPreview: boolean;
+    deploymentTarget: string;
+    preferredContentMode: 'mobile' | 'desktop';
+}
+export interface CapacitorAndroidConfig {
+    minSdkVersion: number;
+    targetSdkVersion: number;
+    allowMixedContent: boolean;
+    backgroundColor: string;
+    buildToolsVersion: string;
+}
+export declare function createCapacitorConfig(appId: string, appName: string): CapacitorConfig;
+export interface ElectronConfig {
+    width: number;
+    height: number;
+    minWidth: number;
+    minHeight: number;
+    resizable: boolean;
+    fullscreen: boolean;
+    fullscreenable: boolean;
+    frame: boolean;
+    titleBarStyle: 'default' | 'hidden' | 'hiddenInset';
+    autoHideMenuBar: boolean;
+    webPreferences: ElectronWebPrefs;
+    singleInstance: boolean;
+    tray: boolean;
+    autoUpdater: boolean;
+}
+export interface ElectronWebPrefs {
+    nodeIntegration: boolean;
+    contextIsolation: boolean;
+    sandbox: boolean;
+    webSecurity: boolean;
+    devTools: boolean;
+}
+export declare function createElectronConfig(partial?: Partial<ElectronConfig>): ElectronConfig;
+export type VirtualControlType = 'joystick' | 'dpad' | 'button' | 'slider' | 'swipe-zone';
+export interface VirtualControl {
+    id: string;
+    type: VirtualControlType;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: number;
+    anchor: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'center';
+    opacity: number;
+    hapticFeedback: boolean;
+    label?: string;
+    icon?: string;
+}
+export interface VirtualJoystickConfig extends VirtualControl {
+    type: 'joystick';
+    deadzone: number;
+    dynamic: boolean;
+    lockAxis?: 'x' | 'y';
+    returnSpeed: number;
+}
+export interface VirtualButtonConfig extends VirtualControl {
+    type: 'button';
+    mappedAction: string;
+    holdable: boolean;
+    repeatRate?: number;
+    shape: 'circle' | 'square' | 'rounded';
+}
+export interface TouchControlLayout {
+    id: string;
+    name: string;
+    controls: VirtualControl[];
+    autoHide: boolean;
+    autoHideDelay: number;
+    customizable: boolean;
+    previewImage?: string;
+}
+export declare function createDefaultMobileLayout(): TouchControlLayout;
+export type AdProvider = 'admob' | 'unity-ads' | 'ironsource' | 'applovin' | 'custom';
+export type AdType = 'banner' | 'interstitial' | 'rewarded' | 'native';
+export type AdPosition = 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export interface AdConfig {
+    provider: AdProvider;
+    appId: string;
+    testMode: boolean;
+    childDirected: boolean;
+    placements: AdPlacement[];
+    consentRequired: boolean;
+    maxAdsPerSession: number;
+    cooldownBetweenAds: number;
+}
+export interface AdPlacement {
+    id: string;
+    type: AdType;
+    unitId: string;
+    position?: AdPosition;
+    size?: {
+        width: number;
+        height: number;
+    };
+    autoShow?: boolean;
+    trigger?: string;
+    rewardAmount?: number;
+    rewardType?: string;
+}
+export interface AdEvent {
+    placement: string;
+    type: 'loaded' | 'shown' | 'clicked' | 'closed' | 'failed' | 'rewarded';
+    timestamp: number;
+    error?: string;
+    rewardGranted?: boolean;
+}
+export interface MobilePerformanceProfile {
+    tier: 'low' | 'medium' | 'high';
+    maxFPS: number;
+    renderScale: number;
+    maxParticles: number;
+    maxAudioSources: number;
+    shadowQuality: 'off' | 'low' | 'medium' | 'high';
+    postProcessing: boolean;
+    textureQuality: 'low' | 'medium' | 'high';
+    physicsBroadPhaseSize: number;
+}
+export declare const MOBILE_PERF_PROFILES: Record<string, MobilePerformanceProfile>;

package/dist/types/release/Release.d.ts

@@ -0,0 +1,81 @@
+export interface APIDocEntry {
+    name: string;
+    kind: 'class' | 'function' | 'interface' | 'type' | 'enum' | 'const';
+    module: string;
+    description: string;
+    params?: Array<{
+        name: string;
+        type: string;
+        description: string;
+        optional: boolean;
+    }>;
+    returns?: string;
+    example?: string;
+    since: string;
+    deprecated?: string;
+}
+export interface APIDocModule {
+    name: string;
+    path: string;
+    description: string;
+    entries: APIDocEntry[];
+}
+/** Engine module manifest — used for documentation generation. */
+export declare const ENGINE_MODULES: APIDocModule[];
+export declare const ENGINE_VERSION = "1.0.0";
+export declare const ENGINE_NAME = "@nice2dev/game-engine";
+export interface MigrationGuide {
+    from: string;
+    to: string;
+    changes: MigrationChange[];
+}
+export interface MigrationChange {
+    type: 'breaking' | 'deprecation' | 'new' | 'fix';
+    module: string;
+    description: string;
+    before?: string;
+    after?: string;
+}
+export declare const CHANGELOG: MigrationGuide[];
+export interface BenchmarkResult {
+    name: string;
+    iterations: number;
+    totalMs: number;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    opsPerSecond: number;
+}
+export declare function runBenchmark(name: string, fn: () => void, iterations?: number): BenchmarkResult;
+export declare function formatBenchmark(result: BenchmarkResult): string;
+export interface EngineCapabilities {
+    webgl: boolean;
+    webgl2: boolean;
+    webgpu: boolean;
+    webAudio: boolean;
+    gamepad: boolean;
+    touch: boolean;
+    webrtc: boolean;
+    webSocket: boolean;
+    sharedArrayBuffer: boolean;
+    offscreenCanvas: boolean;
+    pointerLock: boolean;
+    fullscreen: boolean;
+    vibration: boolean;
+    performance: boolean;
+}
+export declare function detectCapabilities(): EngineCapabilities;
+export interface ExportConfig {
+    target: 'web' | 'pwa' | 'electron' | 'capacitor';
+    minify: boolean;
+    sourceMaps: boolean;
+    treeshake: boolean;
+    splitChunks: boolean;
+    publicPath: string;
+    outputDir: string;
+    serviceWorker: boolean;
+    manifest: boolean;
+}
+export declare const DEFAULT_EXPORT_CONFIG: ExportConfig;
+/** Generate a minimal PWA manifest. */
+export declare function generatePWAManifest(name: string, shortName: string, description: string, themeColor?: string): Record<string, unknown>;

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

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

package/dist/types/rendering/Camera2D.d.ts

@@ -0,0 +1,39 @@
+import type { Vec2, Rect } from '../core/types';
+export interface CameraShake {
+    intensity: number;
+    duration: number;
+    elapsed: number;
+    decay: boolean;
+}
+export declare class Camera2D {
+    position: Vec2;
+    zoom: number;
+    rotation: number;
+    private _viewportWidth;
+    private _viewportHeight;
+    private _target;
+    private _smoothing;
+    private _deadzone;
+    private _bounds;
+    private _shake;
+    private _shakeOffset;
+    constructor(viewportWidth: number, viewportHeight: number);
+    get viewportWidth(): number;
+    get viewportHeight(): number;
+    get worldBounds(): Rect;
+    follow(target: Vec2, smoothing?: number, deadzone?: Vec2): void;
+    unfollow(): void;
+    /** Set world boundaries the camera cannot exceed. */
+    setBounds(bounds: Rect | null): void;
+    shake(intensity: number, duration: number, decay?: boolean): void;
+    /** World position → screen position */
+    worldToScreen(world: Vec2): Vec2;
+    /** Screen position → world position */
+    screenToWorld(screen: Vec2): Vec2;
+    /** Check if a world-space rect is visible. */
+    isVisible(rect: Rect): boolean;
+    resize(width: number, height: number): void;
+    update(dt: number): void;
+    /** Apply camera transform to a Canvas2D context. */
+    applyTransform(ctx: CanvasRenderingContext2D): void;
+}

package/dist/types/rendering/Renderer2D.d.ts

@@ -0,0 +1,41 @@
+import type { Color } from '../core/types';
+import { World, System } from '../ecs/World';
+import { Camera2D } from './Camera2D';
+export interface RenderStats {
+    drawCalls: number;
+    entities: number;
+    particles: number;
+    fps: number;
+}
+export declare class Renderer2D {
+    readonly canvas: HTMLCanvasElement;
+    readonly ctx: CanvasRenderingContext2D;
+    readonly camera: Camera2D;
+    private _bgColor;
+    private _textures;
+    private _stats;
+    private _debugDraw;
+    private _particles;
+    constructor(canvas: HTMLCanvasElement);
+    set backgroundColor(c: Color);
+    get backgroundColor(): Color;
+    set debugDraw(v: boolean);
+    get debugDraw(): boolean;
+    get stats(): RenderStats;
+    loadTexture(id: string, src: string): Promise<void>;
+    setTexture(id: string, source: HTMLImageElement | HTMLCanvasElement): void;
+    getTexture(id: string): HTMLImageElement | HTMLCanvasElement | undefined;
+    resize(width: number, height: number): void;
+    render(world: World, interpolation: number): void;
+    private drawSprite;
+    private drawShape;
+    private drawText;
+    updateParticles(world: World, dt: number): void;
+    private renderParticles;
+    private renderDebug;
+}
+export declare class RenderSystem extends System {
+    private renderer;
+    constructor(renderer: Renderer2D, priority?: number);
+    update(world: World, dt: number): void;
+}

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

@@ -0,0 +1,2 @@
+export { Camera2D, type CameraShake } from './Camera2D';
+export { Renderer2D, RenderSystem, type RenderStats } from './Renderer2D';

package/dist/types/runtime3d/Runtime3D.d.ts

@@ -0,0 +1,259 @@
+import { EventBus } from '../core/EventBus';
+import type { EntityId, Color } from '../core/types';
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Quaternion {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export declare const v3: {
+    create: (x?: number, y?: number, z?: number) => Vec3;
+    zero: () => Vec3;
+    one: () => Vec3;
+    clone: (a: Vec3) => Vec3;
+    add: (a: Vec3, b: Vec3) => Vec3;
+    sub: (a: Vec3, b: Vec3) => Vec3;
+    scale: (a: Vec3, s: number) => Vec3;
+    dot: (a: Vec3, b: Vec3) => number;
+    cross: (a: Vec3, b: Vec3) => Vec3;
+    length: (a: Vec3) => number;
+    normalize: (a: Vec3) => Vec3;
+    dist: (a: Vec3, b: Vec3) => number;
+    lerp: (a: Vec3, b: Vec3, t: number) => Vec3;
+    negate: (a: Vec3) => Vec3;
+    min: (a: Vec3, b: Vec3) => Vec3;
+    max: (a: Vec3, b: Vec3) => Vec3;
+};
+export declare const quat: {
+    identity: () => Quaternion;
+    fromEuler: (x: number, y: number, z: number) => Quaternion;
+    multiply: (a: Quaternion, b: Quaternion) => Quaternion;
+    normalize: (q: Quaternion) => Quaternion;
+    slerp: (a: Quaternion, b: Quaternion, t: number) => Quaternion;
+    /** Rotate a Vec3 by quaternion. */
+    rotateVec3: (q: Quaternion, v: Vec3) => Vec3;
+};
+export interface Transform3D {
+    entityId: EntityId;
+    position: Vec3;
+    rotation: Quaternion;
+    scale: Vec3;
+}
+export type MeshPrimitive = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'plane' | 'custom';
+export interface MeshComponent {
+    entityId: EntityId;
+    primitive: MeshPrimitive;
+    /** Custom mesh asset ID (when primitive = 'custom'). */
+    assetId: string | null;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    visible: boolean;
+}
+export type LightType = 'directional' | 'point' | 'spot' | 'ambient';
+export interface LightComponent {
+    entityId: EntityId;
+    lightType: LightType;
+    color: Color;
+    intensity: number;
+    range: number;
+    spotAngle: number;
+    castShadow: boolean;
+}
+export type CameraMode3D = 'perspective' | 'orthographic';
+export interface Camera3DComponent {
+    entityId: EntityId;
+    mode: CameraMode3D;
+    fov: number;
+    near: number;
+    far: number;
+    orthoSize: number;
+}
+export interface Material3D {
+    id: string;
+    name: string;
+    albedoColor: Color;
+    metallic: number;
+    roughness: number;
+    emissiveColor: Color;
+    emissiveIntensity: number;
+    albedoTextureId: string | null;
+    normalTextureId: string | null;
+    metallicRoughnessTextureId: string | null;
+    transparent: boolean;
+    opacity: number;
+}
+export declare class World3D {
+    readonly events: EventBus;
+    private transforms;
+    private meshes;
+    private lights;
+    private cameras;
+    private materials;
+    private _nextId;
+    createTransform(overrides?: Partial<Transform3D>): Transform3D;
+    addMesh(entityId: EntityId, primitive?: MeshPrimitive, assetId?: string | null): MeshComponent;
+    addLight(entityId: EntityId, lightType?: LightType, color?: Color): LightComponent;
+    addCamera(entityId: EntityId, mode?: CameraMode3D): Camera3DComponent;
+    getTransform(id: EntityId): Transform3D | undefined;
+    getMesh(id: EntityId): MeshComponent | undefined;
+    getLight(id: EntityId): LightComponent | undefined;
+    getCamera(id: EntityId): Camera3DComponent | undefined;
+    allTransforms(): Transform3D[];
+    allMeshes(): MeshComponent[];
+    allLights(): LightComponent[];
+    allCameras(): Camera3DComponent[];
+    registerMaterial(mat: Material3D): void;
+    getMaterial(id: string): Material3D | undefined;
+    allMaterials(): Material3D[];
+    static createDefaultMaterial(name?: string): Material3D;
+    removeEntity(id: EntityId): void;
+    clear(): void;
+}
+export type CameraController = 'fps' | 'third-person' | 'orbit' | 'fly';
+export interface Camera3DSettings {
+    controller: CameraController;
+    position: Vec3;
+    target: Vec3;
+    up: Vec3;
+    fov: number;
+    near: number;
+    far: number;
+    /** Only for orbit / third-person */
+    distance: number;
+    /** Orbit angle in radians (yaw, pitch). */
+    yaw: number;
+    pitch: number;
+    minPitch: number;
+    maxPitch: number;
+    sensitivity: number;
+    smoothing: number;
+}
+export declare function createDefaultCamera3DSettings(controller?: CameraController): Camera3DSettings;
+export declare function updateOrbitCamera(settings: Camera3DSettings, dt: number): void;
+export type ColliderShape3D = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'trimesh' | 'convex';
+export type RigidBodyType3D = 'dynamic' | 'static' | 'kinematic';
+export interface Collider3DDef {
+    shape: ColliderShape3D;
+    halfExtents?: Vec3;
+    radius?: number;
+    halfHeight?: number;
+    isTrigger: boolean;
+    friction: number;
+    restitution: number;
+}
+export interface RigidBody3DDef {
+    bodyType: RigidBodyType3D;
+    mass: number;
+    linearDamping: number;
+    angularDamping: number;
+    gravityScale: number;
+    lockRotationX: boolean;
+    lockRotationY: boolean;
+    lockRotationZ: boolean;
+}
+export interface PhysicsWorld3DConfig {
+    gravity: Vec3;
+    timestep: number;
+}
+/** Abstract 3D physics backend. Implement with Rapier.js, Cannon.js, etc. */
+export interface PhysicsBackend3D {
+    init(config: PhysicsWorld3DConfig): void;
+    step(dt: number): void;
+    addRigidBody(entityId: EntityId, def: RigidBody3DDef, position: Vec3, rotation: Quaternion): void;
+    removeRigidBody(entityId: EntityId): void;
+    addCollider(entityId: EntityId, def: Collider3DDef): void;
+    removeCollider(entityId: EntityId): void;
+    getPosition(entityId: EntityId): Vec3 | null;
+    getRotation(entityId: EntityId): Quaternion | null;
+    setPosition(entityId: EntityId, pos: Vec3): void;
+    setRotation(entityId: EntityId, rot: Quaternion): void;
+    applyForce(entityId: EntityId, force: Vec3): void;
+    applyImpulse(entityId: EntityId, impulse: Vec3): void;
+    setLinearVelocity(entityId: EntityId, vel: Vec3): void;
+    getLinearVelocity(entityId: EntityId): Vec3 | null;
+    /** Raycast and return first hit. */
+    raycast(origin: Vec3, direction: Vec3, maxDist: number): RaycastHit3D | null;
+    destroy(): void;
+}
+export interface RaycastHit3D {
+    entityId: EntityId;
+    point: Vec3;
+    normal: Vec3;
+    distance: number;
+}
+/** Simple physics world that delegates to a backend. */
+export declare class PhysicsWorld3D {
+    readonly events: EventBus;
+    private backend;
+    readonly config: PhysicsWorld3DConfig;
+    constructor(config?: Partial<PhysicsWorld3DConfig>);
+    setBackend(backend: PhysicsBackend3D): void;
+    step(dt: number): void;
+    addBody(entityId: EntityId, body: RigidBody3DDef, position: Vec3, rotation: Quaternion): void;
+    addCollider(entityId: EntityId, def: Collider3DDef): void;
+    removeBody(entityId: EntityId): void;
+    getTransform(entityId: EntityId): {
+        position: Vec3;
+        rotation: Quaternion;
+    } | null;
+    applyForce(entityId: EntityId, force: Vec3): void;
+    applyImpulse(entityId: EntityId, impulse: Vec3): void;
+    raycast(origin: Vec3, direction: Vec3, maxDist?: number): RaycastHit3D | null;
+    destroy(): void;
+}
+/** Abstract 3D renderer backend. Implement with Three.js, Babylon.js, etc. */
+export interface RendererBackend3D {
+    init(canvas: HTMLCanvasElement): void;
+    resize(width: number, height: number): void;
+    render(world: World3D, cameraSettings: Camera3DSettings): void;
+    /** Sync mesh entity from World3D into the render scene. */
+    syncEntity(entityId: EntityId, transform: Transform3D, mesh?: MeshComponent): void;
+    /** Sync light into the render scene. */
+    syncLight(entityId: EntityId, transform: Transform3D, light: LightComponent): void;
+    setMaterial(entityId: EntityId, material: Material3D): void;
+    removeEntity(entityId: EntityId): void;
+    setSkybox(textureIds: string[]): void;
+    setAmbientLight(color: Color, intensity: number): void;
+    /** Enable/disable shadows globally. */
+    setShadows(enabled: boolean): void;
+    dispose(): void;
+}
+/** 3D Renderer that delegates to a swappable backend (Three.js, etc). */
+export declare class Renderer3D {
+    private backend;
+    private canvas;
+    setBackend(backend: RendererBackend3D): void;
+    init(canvas: HTMLCanvasElement): void;
+    resize(width: number, height: number): void;
+    render(world: World3D, camera: Camera3DSettings): void;
+    setMaterial(entityId: EntityId, material: Material3D): void;
+    removeEntity(entityId: EntityId): void;
+    dispose(): void;
+}
+export interface CharacterControllerConfig {
+    height: number;
+    radius: number;
+    stepHeight: number;
+    slopeLimit: number;
+    moveSpeed: number;
+    jumpForce: number;
+    gravity: number;
+    groundCheckDistance: number;
+}
+export declare const DEFAULT_CHARACTER_CONFIG: CharacterControllerConfig;
+export interface CharacterState {
+    velocity: Vec3;
+    grounded: boolean;
+    jumping: boolean;
+}
+/** Simple character controller for FPS / third-person games. */
+export declare function updateCharacterController(state: CharacterState, input: {
+    moveX: number;
+    moveZ: number;
+    jump: boolean;
+}, config: CharacterControllerConfig, dt: number): Vec3;