@combos-fun/engine 0.0.1

package/dist/engine.d.ts

@@ -0,0 +1,825 @@
+import EventEmitter from 'eventemitter3';
+import { AbstractLoadStrategy, AudioLoadStrategy, ImageLoadStrategy, XhrResponseType, MediaElementLoadStrategy, VideoLoadStrategy, XhrLoadStrategy, Loader, Resource as Resource$1, ResourceType, ResourceState } from 'resource-loader';
+
+/**
+ * Two dimensional vector
+ */
+interface Vector2 {
+    x: number;
+    y: number;
+}
+/**
+ * Two dimensional size
+ */
+interface Size2$1 {
+    width: number;
+    height: number;
+}
+/**
+ * Radiation transformation martix
+ *
+ * {@link https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform-function/matrix() }
+ */
+interface TransformMatrix {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+    array?: number[];
+}
+/**
+ * Transform propterty
+ */
+interface TransformParams extends ComponentParams {
+    position?: Vector2;
+    size?: Size2$1;
+    origin?: Vector2;
+    anchor?: Vector2;
+    scale?: Vector2;
+    skew?: Vector2;
+    rotation?: number;
+}
+/** Basic component for gameObject, See {@link TransformParams}  */
+declare class Transform extends Component<TransformParams> {
+    /**
+     * component's name
+     * @readonly
+     */
+    static componentName: string;
+    readonly name: string;
+    private _parent;
+    /** Whether this transform in a scene object */
+    inScene: boolean;
+    /** World coordinate system transformation matrix */
+    worldTransform: TransformMatrix;
+    /** Child transform components */
+    children: Transform[];
+    /**
+     * Init component
+     * @param params - Transform init data
+     */
+    init(params?: TransformParams): void;
+    position: Vector2;
+    size: Size2$1;
+    origin: Vector2;
+    anchor: Vector2;
+    scale: Vector2;
+    skew: Vector2;
+    rotation: number;
+    set parent(val: Transform);
+    /**
+     * Get parent of this component
+     */
+    get parent(): Transform;
+    /**
+     * Add Child Transform
+     * @remarks
+     * If `child` is already a child of this component, `child` will removed to the last of children list
+     * If `child` is already a child of other component, `child` will removed from its parent first
+     * @param child - child gameObject's transform component
+     */
+    addChild(child: Transform): void;
+    /**
+     * Remove child transform
+     * @param child - child gameObject's transform component
+     */
+    removeChild(child: Transform): void;
+    /** Clear all child transform */
+    clearChildren(): void;
+}
+
+/**
+ * Scene is a gameObject container
+ */
+declare class Scene extends GameObject {
+    gameObjects: GameObject[];
+    canvas: HTMLCanvasElement;
+    constructor(name: any, obj?: TransformParams);
+    /**
+     * Add gameObject
+     * @param gameObject - game object
+     */
+    addGameObject(gameObject: GameObject): void;
+    /**
+     * Remove gameObject
+     * @param gameObject - game object
+     */
+    removeGameObject(gameObject: GameObject): void;
+    /**
+     * Destroy scene
+     */
+    destroy(): void;
+}
+
+/**
+ * GameObject is a general purpose object. It consists of a unique id and components.
+ * @public
+ */
+declare class GameObject {
+    /** Name of this gameObject */
+    private _name;
+    /** Scene is an abstraction, represent a canvas layer */
+    private _scene;
+    /** A key-value map for components on this gameObject */
+    private _componentCache;
+    /** Identifier of this gameObject */
+    id: number;
+    /** Components apply to this gameObject */
+    components: Component<ComponentParams>[];
+    /** GameObject has been destroyed */
+    destroyed: boolean;
+    /**
+     * Consruct a new gameObject
+     * @param name - the name of this gameObject
+     * @param obj - optional transform parameters for default Transform component
+     */
+    constructor(name: string, obj?: TransformParams);
+    /**
+     * Get default transform component
+     * @returns transform component on this gameObject
+     * @readonly
+     */
+    get transform(): Transform;
+    /**
+     * Get parent gameObject
+     * @returns parent gameObject
+     * @readonly
+     */
+    get parent(): GameObject;
+    /**
+     * Get the name of this gameObject
+     * @readonly
+     */
+    get name(): string;
+    set scene(val: Scene);
+    /**
+     * Get the scene which this gameObject added on
+     * @returns scene
+     * @readonly
+     */
+    get scene(): Scene;
+    /**
+     * Add child gameObject
+     * @param gameObject - child gameobject
+     */
+    addChild(gameObject: GameObject): void;
+    /**
+     * Remove child gameObject
+     * @param gameObject - child gameobject
+     */
+    removeChild(gameObject: GameObject): GameObject;
+    /**
+     * Add component to this gameObject
+     * @remarks
+     * If component has already been added on a gameObject, it will throw an error
+     * @param C - component instance or Component class
+     */
+    addComponent<T extends Component<ComponentParams>>(C: T): T;
+    addComponent<T extends Component<ComponentParams>>(C: ComponentConstructor<T>, obj?: ComponentParams): T;
+    /**
+     * Remove component on this gameObject
+     * @remarks
+     * default Transform component can not be removed, if the paramter represent a transform component, an error will be thrown.
+     * @param c - one of the compnoentName, component instance, component Class
+     * @returns
+     */
+    removeComponent<T extends Component<ComponentParams>>(c: string): T;
+    removeComponent<T extends Component<ComponentParams>>(c: T): T;
+    removeComponent<T extends Component<ComponentParams>>(c: ComponentConstructor<T>): T;
+    private _removeComponent;
+    /**
+     * Get component on this gameObject
+     * @param c - one of the compnoentName, component instance, component Class
+     * @returns
+     */
+    getComponent<T extends Component<ComponentParams>>(c: ComponentConstructor<T>): T;
+    getComponent<T extends Component>(c: string): T;
+    /**
+     * Remove this gameObject on its parent
+     * @returns return this gameObject
+     */
+    remove(): GameObject;
+    /** Destory this gameObject */
+    destroy(): void;
+}
+
+/** frame info pass to `Component.update` method */
+interface UpdateParams {
+    /** delta time from last frame */
+    deltaTime: number;
+    /** frame count since game begining */
+    frameCount: number;
+    /** current timestamp */
+    time: number;
+    /** current timestamp */
+    currentTime: number;
+    /** fps at current frame */
+    fps: number;
+}
+interface ComponentParams {
+}
+interface ComponentConstructor<T extends Component<ComponentParams>> {
+    componentName: string;
+    new (params?: ComponentParams): T;
+}
+/**
+ * Component contain raw data apply to gameObject and how it interacts with the world
+ * @public
+ */
+declare class Component<T extends ComponentParams = {}> extends EventEmitter {
+    /** Name of this component */
+    static componentName: string;
+    /** Name of this component */
+    readonly name: string;
+    /**
+     * Represents the status of the component, If component has started, the value is true
+     * @defaultValue false
+     */
+    started: boolean;
+    /**
+     * gameObject which this component had added on
+     * @remarks
+     * Component can only be added on one gameObject, otherwise an error will be thrown,
+     * Component can only be attached to one game object at a time.
+     */
+    gameObject: GameObject;
+    /** Default paramaters for this component */
+    __componentDefaultParams: T;
+    constructor(params?: T);
+    /**
+     * Called during component construction
+     * @param params - optional initial parameters
+     * @override
+     */
+    init?(params?: T): void;
+    /**
+     * Called when component is added to a gameObject
+     * @override
+     */
+    awake?(): void;
+    /**
+     * Called after all component's `awake` method has been called
+     * @override
+     */
+    start?(): void;
+    /**
+     * Called in every tick, change self property or other component property
+     * @param frame - frame info about this tick
+     * @override
+     */
+    update?(frame: UpdateParams): void;
+    /**
+     * Called after all gameObject's `update` method has been called
+     * @param frame - frame info about this tick
+     * @override
+     */
+    lateUpdate?(frame: UpdateParams): void;
+    /**
+     * Called before game runing or every time game paused
+     * @virtual
+     * @override
+     */
+    onResume?(): void;
+    /**
+     * Called while the game paused.
+     * @override
+     */
+    onPause?(): void;
+    /**
+     * Called while component be destroyed.
+     * @override
+     */
+    onDestroy?(): void;
+}
+
+interface ObserverEventParams {
+    type: ObserverType;
+    component: Component;
+    componentName: string;
+    prop?: PureObserverProp;
+}
+interface ObserverEvent extends ObserverEventParams {
+    gameObject?: GameObject;
+    systemName?: string;
+}
+/**
+ * Management observe events
+ * @remarks
+ * See {@link System} for more details
+ * @public
+ */
+declare class ComponentObserver {
+    /**
+     * Component property change events
+     * @defaultValue []
+     */
+    private events;
+    /**
+     * Add event
+     * @remarks
+     * The same event will be placed last
+     * @param component - changed component
+     * @param prop - changed property on `component`
+     * @param type - change event type
+     * @param componentName - `component.name` this parameter will deprecated
+     */
+    add({ component, prop, type, componentName }: ObserverEventParams): void;
+    /** Return change events */
+    getChanged(): ObserverEvent[];
+    /**
+     * Return change events
+     * @readonly
+     */
+    get changed(): ObserverEvent[];
+    /** Clear events */
+    clear(): ObserverEvent[];
+}
+
+interface TickerOptions {
+    autoStart?: boolean;
+    frameRate?: number;
+}
+/**
+ * Timeline tool
+ */
+declare class Ticker {
+    /** Whether or not ticker should auto start */
+    autoStart: boolean;
+    /** FPS, The number of times that raf method is called per second */
+    frameRate: number;
+    /** Global Timeline **/
+    private timeline;
+    /** Time between two frame */
+    private _frameDuration;
+    /** Ticker is a function will called in each raf */
+    private _tickers;
+    /** raf handle id */
+    _requestId: number;
+    /** Last frame render time */
+    private _lastFrameTime;
+    /** Frame count since from ticker beigning */
+    private _frameCount;
+    /** Main ticker method handle */
+    private _ticker;
+    /** Represents the status of the Ticker, If ticker has started, the value is true */
+    private _started;
+    /**
+     * @param autoStart - auto start game
+     * @param frameRate - game frame rate
+     */
+    constructor(options?: TickerOptions);
+    /** Main loop, all _tickers will called in this method */
+    update(): void;
+    /** Add ticker function */
+    add(fn: (params: UpdateParams) => void): void;
+    /** Remove ticker function */
+    remove(fn: (params: UpdateParams) => void): void;
+    /** Start main loop */
+    start(): void;
+    /** Pause main loop */
+    pause(): void;
+    setPlaybackRate(rate: number): void;
+}
+
+/** Plugin registration shape */
+interface PluginStruct {
+    Components?: typeof Component[];
+    Systems?: typeof System[];
+}
+interface GameParams {
+    /** isn't game will auto start */
+    autoStart?: boolean;
+    /** fps for this game */
+    frameRate?: number;
+    /** systems in this game */
+    systems?: System[];
+    /** whether or not need to create scene */
+    needScene?: boolean;
+    /**
+     * Called after async system bootstrap finishes (constructor path with non-empty `systems`),
+     * i.e. after all `addSystem`/`init` work and optional `loadScene` / `start`.
+     * Second argument is set if bootstrap threw (e.g. async `init` rejection).
+     */
+    onSystemsBootstrapComplete?: (game: Game, error?: unknown) => void;
+}
+declare enum LOAD_SCENE_MODE {
+    SINGLE = "SINGLE",
+    MULTI_CANVAS = "MULTI_CANVAS"
+}
+interface LoadSceneParams {
+    scene: Scene;
+    mode?: LOAD_SCENE_MODE;
+    params?: {
+        width?: number;
+        height?: number;
+        canvas?: HTMLCanvasElement;
+        renderType?: number;
+        autoStart?: boolean;
+        sharedTicker?: boolean;
+        sharedLoader?: boolean;
+        transparent?: boolean;
+        antialias?: boolean;
+        preserveDrawingBuffer?: boolean;
+        resolution?: number;
+        backgroundColor?: number;
+        clearBeforeRender?: boolean;
+        roundPixels?: boolean;
+        forceFXAA?: boolean;
+        legacy?: boolean;
+        autoResize?: boolean;
+        powerPreference?: "high-performance";
+    };
+}
+declare class Game extends EventEmitter {
+    _scene: Scene;
+    canvas: HTMLCanvasElement;
+    /**
+     * State of game
+     * @defaultValue false
+     */
+    playing: boolean;
+    started: boolean;
+    multiScenes: Scene[];
+    /**
+     * Ticker
+     */
+    ticker: Ticker;
+    /** Systems alled to this game */
+    systems: System[];
+    constructor({ systems, frameRate, autoStart, needScene, onSystemsBootstrapComplete, }?: GameParams);
+    /** When `systems` is passed in the constructor, run async `init` for each before `loadScene` / `start`. */
+    private bootstrapSystemsAndMaybeStart;
+    /**
+     * Get scene on this game
+     */
+    get scene(): Scene;
+    set scene(scene: Scene);
+    get gameObjects(): any[];
+    addSystem<T extends System>(S: T): Promise<T | undefined>;
+    addSystem<T extends System>(S: SystemConstructor<T>, obj?: ConstructorParameters<SystemConstructor<T>>): Promise<T | undefined>;
+    /**
+     * Remove system from this game
+     * @param system - one of system instance / system Class or system name
+     */
+    removeSystem<S extends System>(system: S | SystemConstructor<S> | string): void;
+    /**
+     * Get system
+     * @param S - system class or system name
+     * @returns system instance
+     */
+    getSystem<T extends System>(S: SystemConstructor<T> | string): T;
+    /** Pause game */
+    pause(): void;
+    /** Start game */
+    start(): void;
+    /** Resume game */
+    resume(): void;
+    /**
+     * add main render method to ticker
+     * @remarks
+     * the method added to ticker will called in each requestAnimationFrame,
+     * 1. call update method on all gameObject
+     * 2. call lastUpdate method on all gameObject
+     * 3. call update method on all system
+     * 4. call lastUpdate method on all system
+     */
+    initTicker(): void;
+    /** Call onResume method on all gameObject's, and then call onResume method on all system */
+    triggerResume(): void;
+    /** Call onPause method on all gameObject */
+    triggerPause(): void;
+    /** remove all system on this game */
+    destroySystems(): void;
+    /** Destroy game instance */
+    destroy(): void;
+    loadScene({ scene, mode, params }: LoadSceneParams): void;
+}
+
+interface SystemConstructor<T extends System = System> {
+    systemName: string;
+    observerInfo: PureObserverInfo;
+    new (params?: any): T;
+}
+/**
+ * Each System runs continuously and performs global actions on every Entity that possesses a Component of the same aspect as that System.
+ * @public
+ */
+declare class System<T extends {} = {}> {
+    /** System name */
+    static systemName: string;
+    name: string;
+    /**
+     * The collection of component properties observed by the System. System will respond to these changes
+     * @example
+     * ```typescript
+     * // TestSystem will respond to changes of `size` and `position` property of the Transform component
+     * class TestSystem extends System {
+     *   static observerInfo = {
+     *     Transform: [{ prop: 'size', deep: true }, { prop: 'position', deep: true }]
+     *   }
+     * }
+     * ```
+     */
+    static observerInfo: PureObserverInfo;
+    /** Component Observer */
+    componentObserver: ComponentObserver;
+    /** Game instance */
+    game: Game;
+    /** Represents the status of the component, if component has started, the value is true */
+    started: boolean;
+    /** Default paramaters for this system */
+    __systemDefaultParams: T;
+    constructor(params?: T);
+    /**
+     * Called when system is added to a gameObject
+     * @remarks
+     * The difference between init and awake is that `init` method recieves params.
+     * Both of those methods are called early than `start` method.
+     * Use this method to prepare data, ect.
+     * @param param - optional params
+     * @override
+     */
+    init?(param?: T): void | Promise<void>;
+    /**
+     * Calleen system installed
+     * @override
+     */
+    awake?(): void;
+    /**
+     * Called after all system `awake` method has been called
+     * @override
+     */
+    start?(): void;
+    /**
+     * Called in each tick
+     * @example
+     * ```typescript
+     * // run TWEEN `update` method in main requestAnimationFrame loop
+     * class TransitionSystem extends System {
+     *   update() {
+     *     TWEEN.update()
+     *   }
+     * }
+     * ```
+     * @param e - info about this tick
+     * @override
+     */
+    update?(e: UpdateParams): void;
+    /**
+     * Called after all system have called the `update` method
+     * @param e - info about this tick
+     * @override
+     */
+    lateUpdate?(e: UpdateParams): void;
+    /**
+     * Called before game runing or every time game paused
+     * @override
+     */
+    onResume?(): void;
+    /**
+     * Called while the game paused
+     * @override
+     */
+    onPause?(): void;
+    /**
+     * Called while the system be destroyed.
+     * @override
+     */
+    onDestroy?(): void;
+    /** Default destory method */
+    destroy(): void;
+}
+
+/** Observer event type */
+declare enum ObserverType {
+    ADD = "ADD",
+    REMOVE = "REMOVE",
+    CHANGE = "CHANGE"
+}
+/**
+ * Observer property
+ * @remarks
+ * If `deep` is true then all descendants of `prop` will be observed
+ * @example
+ * ```typescript
+ * @observerComponent({
+ *   Transform: [{ prop: 'size', deep: true }]
+ * })
+ * class TestSystem extends System {}
+ * ```
+ */
+interface PureObserverProp {
+    deep: boolean;
+    prop: string[];
+}
+/**
+ * Observer Info
+ * @remarks
+ * The key of this map always be component's name, the value of this map is an array of `PureObserverProp`
+ */
+type PureObserverInfo = Record<string, PureObserverProp[]>;
+
+/**
+ * Collect property which react in Editor tooling
+ * @param target - component instance
+ * @param propertyKey - property name
+ */
+declare function IDEProp(target: any, propertyKey: any): void;
+
+type observableKeys = string | string[];
+interface ObserverProp {
+    deep: boolean;
+    prop: observableKeys;
+}
+type ObserverValue = observableKeys | ObserverProp;
+type ComponentName = string;
+/**
+ * Normailized observer info
+ * @example
+ * ```typescript
+ * {
+ *   Transform: [{ prop: ['size'], deep: false }],
+ *   OtherComponent: [{ prop: ['style', 'transform'], deep: true }]
+ * }
+ * ```
+ */
+type ObserverInfo = Record<ComponentName, ObserverValue[]>;
+/**
+ * Normailize system observer info
+ * @param obj - system observer info
+ */
+declare function componentObserver(observerInfo?: ObserverInfo): (constructor: any) => void;
+
+interface EventParam {
+    name: string;
+    resource: ResourceStruct;
+    success: boolean;
+    errMsg?: string;
+}
+declare class Progress extends EventEmitter {
+    progress: number;
+    resourceTotal: number;
+    resourceLoadedCount: number;
+    resource: Resource;
+    constructor({ resource, resourceTotal }: {
+        resource: any;
+        resourceTotal: any;
+    });
+    onStart(): void;
+    onProgress(param: EventParam): void;
+}
+
+declare const resourceLoader: {
+    AbstractLoadStrategy: typeof AbstractLoadStrategy;
+    AudioLoadStrategy: typeof AudioLoadStrategy;
+    ImageLoadStrategy: typeof ImageLoadStrategy;
+    XhrResponseType: typeof XhrResponseType;
+    MediaElementLoadStrategy: typeof MediaElementLoadStrategy;
+    VideoLoadStrategy: typeof VideoLoadStrategy;
+    XhrLoadStrategy: typeof XhrLoadStrategy;
+    Loader: typeof Loader;
+    Resource: typeof Resource$1;
+    ResourceType: typeof ResourceType;
+    ResourceState: typeof ResourceState;
+};
+
+/** Load lifecycle events (decoupled from Resource/Progress to avoid barrel import cycles). */
+declare enum LOAD_EVENT {
+    'START' = "start",
+    'PROGRESS' = "progress",
+    'LOADED' = "loaded",
+    'COMPLETE' = "complete",
+    'ERROR' = "error"
+}
+
+/** Resource type */
+declare enum RESOURCE_TYPE {
+    'IMAGE' = "IMAGE",
+    'SPRITE' = "SPRITE",
+    'SPRITE_ANIMATION' = "SPRITE_ANIMATION",
+    'AUDIO' = "AUDIO",
+    'VIDEO' = "VIDEO"
+}
+/** Resource item */
+interface SrcBase {
+    type: string;
+    url?: string;
+    data?: any;
+    size?: Size2;
+    texture?: TextureBase[] | TextureBase;
+}
+interface Size2 {
+    width: number;
+    height: number;
+}
+interface TextureBase {
+    type: string;
+    url: string;
+    size?: Size2;
+}
+/** Resource base */
+interface ResourceBase {
+    name: string;
+    type: RESOURCE_TYPE;
+    src: {
+        json?: SrcBase;
+        image?: SrcBase;
+        tex?: SrcBase;
+        ske?: SrcBase;
+        video?: SrcBase;
+        audio?: SrcBase;
+        [propName: string]: SrcBase;
+    };
+    complete?: boolean;
+    preload?: boolean;
+}
+/** Resource with entity */
+interface ResourceStruct extends ResourceBase {
+    data?: {
+        json?: any;
+        image?: HTMLImageElement;
+        tex?: any;
+        ske?: any;
+        video?: HTMLVideoElement;
+        audio?: ArrayBuffer;
+        [propName: string]: any;
+    };
+    instance?: any;
+}
+declare const RESOURCE_TYPE_STRATEGY: {
+    [type: string]: new (...args: any[]) => AbstractLoadStrategy;
+};
+type ResourceName = string;
+type ResourceProcessFn = (resource: ResourceStruct) => any;
+type PreProcessResourceHandler = (res: ResourceBase) => void;
+/**
+ * Resource manager
+ * @public
+ */
+declare class Resource extends EventEmitter {
+    /** load resource timeout */
+    timeout: number;
+    private preProcessResourceHandlers;
+    /** Resource cache  */
+    resourcesMap: Record<ResourceName, ResourceStruct>;
+    /** Collection of make resource instance function */
+    private makeInstanceFunctions;
+    /** Collection of destroy resource instance function */
+    private destroyInstanceFunctions;
+    /** Resource load promise */
+    private promiseMap;
+    private loaders;
+    progress: Progress;
+    constructor(options?: {
+        timeout: number;
+    });
+    /** Add resource configs and then preload */
+    loadConfig(resources: ResourceBase[]): void;
+    /** Add single resource config and then preload */
+    loadSingle(resource: ResourceBase): Promise<ResourceStruct>;
+    /** Add resource configs */
+    addResource(resources: ResourceBase[]): void;
+    /** dd resource preprocesser*/
+    addPreProcessResourceHandler(handler: PreProcessResourceHandler): void;
+    removePreProcessResourceHandler(handler: PreProcessResourceHandler): void;
+    /** Start preload */
+    preload(): void;
+    /** Get resource by name */
+    getResource(name: string): Promise<ResourceStruct>;
+    /** Make resource instance by resource type */
+    private instance;
+    /** destory this resource manager */
+    destroy(name: string): Promise<void>;
+    private _destroy;
+    /**
+     * Register a custom resource type string on {@link RESOURCE_TYPE}.
+     * For TypeScript, extend `RESOURCE_TYPE` via `declare module "@combos-fun/engine"` in your app’s ambient `.d.ts`.
+     * Call this before {@link registerInstance} / {@link registerDestroy} for that type.
+     */
+    registerResourceType(type: string, value?: string): void;
+    /** Add resource instance function */
+    registerInstance(type: RESOURCE_TYPE | string, callback: ResourceProcessFn): void;
+    /** Add resource destroy function */
+    registerDestroy(type: RESOURCE_TYPE | string, callback: ResourceProcessFn): void;
+    private loadResource;
+    doComplete(name: any, resolve: any, preload?: boolean): Promise<void>;
+    checkAllLoaded(name: any): boolean;
+    getLoader(preload?: boolean): Loader;
+    private onLoad;
+    private onError;
+}
+/** Resource manager single instance */
+declare const resource: Resource;
+
+/** Decorators util */
+declare const decorators: {
+    IDEProp: typeof IDEProp;
+    componentObserver: typeof componentObserver;
+};
+
+declare const version = "__VERSION__";
+
+export { Component, Game, GameObject, IDEProp, LOAD_EVENT, LOAD_SCENE_MODE, ObserverType as OBSERVER_TYPE, RESOURCE_TYPE, RESOURCE_TYPE_STRATEGY, Scene, System, Transform, componentObserver, decorators, resource, resourceLoader, version };
+export type { ObserverEvent as ComponentChanged, ComponentParams, GameParams, ObserverInfo, PluginStruct, PureObserverInfo, ResourceBase, SystemConstructor, TransformParams, UpdateParams };