@draug/engine 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+import { ClassType, ComponentType as ComponentType$1 } from '@draug/types/class';
+import { Bitmap } from 'bitmap-index';
+import { AssetsManager } from '@draug/assets/assets';
+
+type ComponentType<T extends object = object> = ClassType<T>;
+interface IStorage<T extends object> {
+    add(id: number, initFn?: (obj: T) => T): T;
+    remove(id: number): void;
+    get(id: number): T | null;
+    tryGet(id: number): T;
+    has(id: number): boolean;
+    size(): number;
+    forEach(cb: (id: number) => void): void;
+    bitmap(): Bitmap;
+}
+
+declare enum ComponentStorageType {
+    COMPONENT_STORAGE = 1,
+    SINGLETON_STORAGE = 2
+}
+type RegisterSingletoneComponentOptions<T extends object> = {
+    storageType: ComponentStorageType.SINGLETON_STORAGE;
+    factory: () => T;
+};
+type RegisterComponentStorageOptions<T extends object> = {
+    storageType: ComponentStorageType.COMPONENT_STORAGE;
+    factory?: () => T;
+};
+type RegisterComponentOptions<T extends object> = RegisterSingletoneComponentOptions<T> | RegisterComponentStorageOptions<T>;
+declare class ComponentAlreadyRegisteredError extends Error {
+    constructor(component: ComponentType);
+}
+declare class ComponentsManager {
+    private maxEntityCount;
+    private readonly storages_;
+    private currId_;
+    private nextId;
+    constructor(maxEntityCount?: number);
+    register<T extends object>(component: ComponentType<T>, opts?: RegisterComponentOptions<T>): IStorage<T>;
+    private createComponentStore;
+    private createSingletonStore;
+    getStorage<T extends object>(component: ComponentType<T>): IStorage<T>;
+    getComponentId(ctor: ComponentType): number;
+}
+
+declare function Component(): ClassDecorator;
+
+declare class ComponentStorage<T extends object> implements IStorage<T> {
+    private bits_;
+    private set_;
+    private pool_;
+    private id_;
+    private cls;
+    constructor(cap: number | undefined, factory: () => T, cls: ClassType<T>);
+    bitmap(): Bitmap;
+    get id(): number;
+    _internalSetId(id: number): number;
+    add(id: number, initFn?: (obj: T) => T): T;
+    remove(id: number): void;
+    get(id: number): T | null;
+    tryGet(id: number): T;
+    writeComponentsToBuf(ids: ReadonlyArray<number>, out: T[]): number;
+    has(id: number): boolean;
+    entityIds(): number[];
+    size(): number;
+    forEach(cb: (id: number) => void): void;
+}
+
+declare class SingletonStorage<T extends object> implements IStorage<T> {
+    private factory;
+    private value;
+    private entityId;
+    constructor(factory: () => T);
+    bitmap(): Bitmap;
+    add(id: number, initFn?: ((obj: T) => T) | undefined): T;
+    remove(id: number): void;
+    get(id: number): T | null;
+    tryGet(id: number): T;
+    has(id: number): boolean;
+    size(): number;
+    forEach(cb: (id: number) => void): void;
+    private validateId;
+}
+
+type EntityID = number;
+declare class UnregisteredComponentStorageError extends Error {
+    constructor(component: ComponentType);
+}
+declare class EntityMaskNotFoundError extends Error {
+    constructor(id: EntityID);
+}
+declare class EntitiesManager {
+    private id_;
+    private nextId;
+    create(): EntityID;
+}
+declare class EntityRef {
+    private world;
+    id: EntityID;
+    constructor(world: World, id: EntityID);
+    with<T extends ComponentType[], Result extends {
+        [K in keyof T]: InstanceType<T[K]>;
+    }>(...components: T): Result;
+}
+
+declare class EventBuffer<T extends unknown> {
+    private readBuf;
+    private writeBuf;
+    write(event: T): void;
+    /**
+     * Advances the buffer to the next frame.
+     *
+     * Performs a double-buffer flip:
+     * - Promotes all events written during the previous frame (`writeBuf`)
+     *   to be readable in the current frame (`readBuf`).
+     * - Reuses the previous `readBuf` as the new `writeBuf` and clears it
+     *   to collect events for the next frame.
+     *
+     * After calling this method:
+     * - `get()` will return a stable snapshot of events produced in the previous frame.
+     * - `add()` will write into an empty buffer for the current frame.
+     *
+     * Guarantees:
+     * - No events written during the current frame are visible until the next `swap()`.
+     * - Readers observe a consistent, immutable snapshot within a frame.
+     *
+     * Expected to be called exactly once per frame, before system execution.
+    */
+    swap(): void;
+    read(): ReadonlyArray<T>;
+    size(): number;
+}
+type EventKey<T> = symbol & {
+    __type?: T;
+};
+declare function createEventKey<T>(description?: string): EventKey<T>;
+declare class EventBus {
+    private storage;
+    swapAll(): void;
+    getBuffer<T>(key: EventKey<T>): EventBuffer<T>;
+}
+
+declare class ResourcesManager {
+    private readonly items_;
+    insert<T extends object>(type: ClassType<T>, value: T): T;
+    get<T extends object>(type: ClassType<T>): T;
+    getOrInsert<T extends object>(type: ClassType<T>, factory: () => T): T;
+    remove<T>(type: ClassType<T>): void;
+}
+
+type WorldCommand = (world: World) => void;
+type ComponentInitFn<C extends ComponentType> = (component: InstanceType<C>) => void;
+type CreateEntityComponentEntry<T extends ComponentType = ComponentType> = T extends unknown ? [T, ComponentInitFn<T>] : never;
+declare function entry<T extends ComponentType>(component: T, init?: ComponentInitFn<T>): CreateEntityComponentEntry;
+declare class Commands {
+    private readonly world;
+    private readonly commandsQueue_;
+    constructor(world: World);
+    add(cmd: WorldCommand): void;
+    flush(world: World): void;
+    createEntity(...entries: CreateEntityComponentEntry[]): number;
+}
+
+type QueryParameters = {
+    include?: ComponentType[];
+    exclude?: ComponentType[];
+    anyOf?: ComponentType[];
+    excludeEntitiesIds?: number[];
+    filter?: (id: number) => boolean;
+};
+declare class QueryManager {
+    private readonly world;
+    private cache;
+    constructor(world: World);
+    get(params: QueryParameters): EntityID[];
+    invalidate(component: ComponentType): void;
+    private getKey;
+    private ids;
+    private collectDeps;
+    private compute;
+    private combineBitmaps;
+    private applyExclusions;
+    private extractIds;
+}
+
+type PluginID = string;
+type PluginDependencies = {
+    components?: ComponentType$1[];
+    resources?: ClassType<any>[];
+    systems?: ClassType<SystemBase>[];
+    plugins?: Array<{
+        id: PluginID;
+        version?: string;
+    }>;
+};
+interface PluginMetadata {
+    id: PluginID;
+    version: string;
+    name: string;
+    dependencies?: PluginDependencies;
+}
+declare function Plugin(metadata: PluginMetadata): ClassDecorator;
+declare function getPluginMetadata(plugin: ClassType<PluginBase>): PluginMetadata;
+declare function isPlugin(ctor: Function): boolean;
+declare abstract class PluginBase {
+    onPluginLoad?: (world: World) => void;
+    onPluginUnload?: (world: World) => void;
+    onAfterWorldInit?: (world: World) => void;
+}
+declare class PluginError extends Error {
+    constructor(pluginId: string);
+}
+declare class ErrNotAPlugin extends Error {
+    constructor(target: Function);
+}
+declare class ErrMissingPluginMetadata extends Error {
+    constructor(plugin: ClassType<PluginBase>);
+}
+declare class ErrUnknownPlugin extends PluginError {
+    constructor(pluginId: string);
+}
+declare class ErrPluginNotInit extends PluginError {
+    constructor(pluginId: string);
+}
+declare class PluginsManager {
+    private plugins_;
+    private isInitiated_;
+    install<T extends ClassType<PluginBase>>(plugin: T, ...constructorProps: ConstructorParameters<T>): void;
+    build(): void;
+    getPluginMetadata(pluginOrId: ClassType<PluginBase> | PluginID): PluginMetadata;
+    getPluginInstance<T extends PluginBase>(pluginOrId: ClassType<T> | PluginID): T;
+    private resolveId;
+}
+
+declare class World {
+    readonly entities: EntitiesManager;
+    readonly components: ComponentsManager;
+    readonly systems: SystemsManager;
+    readonly events: EventBus;
+    readonly resources: ResourcesManager;
+    readonly commands: Commands;
+    readonly queries: QueryManager;
+    readonly plugins: PluginsManager;
+    private entityRefs_;
+    constructor(maxEntityCount?: number);
+    getEntityRef(id: number): EntityRef;
+    query(params: QueryParameters): number[];
+    removeComponent<T extends object>(ref: EntityRef, component: ComponentType$1<T>): void;
+    removeComponent<T extends object>(entity: EntityID, component: ComponentType$1<T>): void;
+    addComponent<T extends object>(id: EntityID, component: ClassType<T>, initFn?: (obj: T) => void): T;
+    addComponent<T extends object>(id: EntityRef, component: ClassType<T>, initFn?: (obj: T) => void): T;
+    update(dt: number): void;
+    build(): void;
+}
+
+declare class SystemError extends Error {
+    constructor(target: Function);
+}
+declare class ErrNotASystem extends Error {
+    constructor(target: Function);
+}
+declare class ErrMissingSystemMetadata extends SystemError {
+    constructor(target: SystemCtor);
+}
+type SystemMetadata = {
+    /**
+     * ECS query definition used to select entities for this system execution.
+     *
+     * Determines the iteration set passed to {@link SystemBase.compute}.
+     * The ECS runtime resolves entities based on this query each update.
+     */
+    query: Readonly<QueryParameters>;
+    /**
+     * Explicit list of component types required by the system but not necessarily
+     * part of the iteration query.
+     *
+     * Used for:
+     * - ensuring component storages are initialized in the world
+     * - safe access via `world.components.getStorage`
+     * - dependencies that should not affect entity selection
+     *
+     * This does NOT influence entity iteration; only runtime validation/setup.
+     */
+    requiredComponents: Set<ComponentType$1>;
+    /**
+     * Systems that must run before this one. Pass constructor arguments
+     * `super(OtherSystemCtor, ...)` to add edges; each listed system is scheduled earlier than
+     * this instance. Used when {@link SystemsManager.build} computes a topological execution order.
+     */
+    computeAfter?: Set<SystemCtor>;
+};
+type SystemDecoratorProps = {
+    query: SystemMetadata['query'];
+    requiredComponents?: ComponentType$1[];
+    computeAfter?: SystemCtor[];
+};
+declare function System(props: SystemDecoratorProps): ClassDecorator;
+declare function getSystemMetadata(system: SystemCtor): SystemMetadata;
+declare function isSystem(ctor: Function): boolean;
+type SystemCtor<T extends SystemBase = SystemBase> = ClassType<T>;
+/**
+ * Arguments passed to {@link SystemBase.compute} on each {@link SystemsManager.update} call.
+ */
+type SystemComputeContext = {
+    /** Entity IDs from the query for this {@link SystemBase.compute} invocation. */
+    entities: number[];
+    /** ECS world instance. */
+    world: World;
+    /** Delta time (seconds or your engine's convention) since the previous update. */
+    dt: number;
+};
+/**
+ * Base class for ECS systems executed by {@link SystemsManager}.
+ *
+ * Subclasses declare which components they iterate over (`queryComponents`), which component
+ * types must exist in the world for registration (`requiredComponents`), and optional ordering
+ * relative to other systems (`computeAfter` / `super(OtherSystem)`).
+ */
+declare abstract class SystemBase {
+    /**
+     * Logic for one systems pass: run for all entities in {@link SystemComputeContext.entities}.
+     */
+    abstract compute(ctx: SystemComputeContext): void;
+    onInit?(world: World): void;
+}
+declare class SystemsManager {
+    private readonly world;
+    private systems_;
+    private executionOrder_;
+    private requiredComponents_;
+    private dirty_;
+    constructor(world: World);
+    getRequiredComponents(): ComponentType$1[];
+    register<T extends SystemBase>(sys: T): void;
+    build(): void;
+    private rebuild;
+    get<T extends SystemBase>(ctor: SystemCtor<T>): T;
+    update(dt: number): void;
+    private buildSystemsArray;
+}
+
+interface TimeSource {
+    now(): number;
+}
+declare class Clock {
+    private readonly timeSource_;
+    private lastTimeMs_;
+    private elapsedTime_;
+    private dt_;
+    constructor(timeSource_: TimeSource);
+    get dt(): number;
+    get ellapsedTime(): number;
+    tick(): void;
+}
+
+type StepFunction = (dt: number) => void;
+declare class GameLoop {
+    private clock;
+    private stepFn;
+    private running;
+    constructor(clock: Clock, stepFn: StepFunction);
+    start(platformLoop: (callback: () => void) => void): void;
+    stop(): void;
+}
+
+declare class Runtime {
+    readonly world: World;
+    readonly assets: AssetsManager;
+    constructor(world: World, assets: AssetsManager);
+    update(dt: number): void;
+}
+
+export { Clock, Commands, Component, ComponentAlreadyRegisteredError, type ComponentInitFn, ComponentStorage, ComponentsManager, type CreateEntityComponentEntry, EntitiesManager, type EntityID, EntityMaskNotFoundError, EntityRef, ErrMissingPluginMetadata, ErrMissingSystemMetadata, ErrNotAPlugin, ErrNotASystem, ErrPluginNotInit, ErrUnknownPlugin, EventBuffer, EventBus, GameLoop, type IStorage, Plugin, PluginBase, type PluginDependencies, PluginError, type PluginID, type PluginMetadata, PluginsManager, ResourcesManager, Runtime, SingletonStorage, type StepFunction, System, SystemBase, type SystemComputeContext, SystemError, SystemsManager, type TimeSource, UnregisteredComponentStorageError, World, type WorldCommand, createEventKey, entry, getPluginMetadata, getSystemMetadata, isPlugin, isSystem };