@draug/engine 1.0.0

package/ecs/system.ts

@@ -0,0 +1,214 @@
+import { DAGNode, topologicalSort } from '@draug/core/graph/dag';
+import type { ClassType, ComponentType } from '@draug/types/class'
+import type { World } from "./world";
+import type { QueryParameters } from './query';
+
+
+export class SystemError extends Error {
+    constructor(target: Function) {
+        super(`[System Error] (System "${target.name}".`)
+    }
+}
+export class ErrNotASystem extends Error {
+    constructor(target: Function) {
+        super(`Provided class "${target.name}" is not a System! Extend your class from SystemBase.`)
+    }
+}
+export class ErrMissingSystemMetadata extends SystemError {
+    constructor(target: SystemCtor) {
+        super(target);
+        this.message = `${this.message}: Missing system metadata! Define system class with @System decorator.`
+    }
+};
+
+export 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>;
+    /**
+     * 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>;
+};
+export type SystemDecoratorProps = {
+    query: SystemMetadata['query'];
+    requiredComponents?: ComponentType[];
+    computeAfter?: SystemCtor[];
+};
+const SystemMetadataSymbol = Symbol("system");
+type FunctionWithMetadata = Function & { [SystemMetadataSymbol]?: SystemMetadata };
+
+export function System(props: SystemDecoratorProps): ClassDecorator {
+    return (target: Function) => {
+        const systemTarget = target as FunctionWithMetadata;
+
+        if ('__proto__' in systemTarget && systemTarget.__proto__ !== SystemBase) {
+            throw new ErrNotASystem(target);
+        }
+
+        const query = { ...props.query };
+        const requiredComponents = new Set(props.requiredComponents);
+        const computeAfter = new Set(props.computeAfter);
+        const metadata: SystemMetadata = { query, requiredComponents, computeAfter };
+
+        // Теперь TS позволяет записать значение
+        systemTarget[SystemMetadataSymbol] = metadata;
+    };
+}
+
+export function getSystemMetadata(system: SystemCtor): SystemMetadata {
+    if (hasMetadata(system)) {
+        return system[SystemMetadataSymbol] as SystemMetadata;
+    }
+    throw new ErrMissingSystemMetadata(system);
+}
+
+
+export function hasMetadata(ctor: Function): ctor is Required<FunctionWithMetadata> {
+    return SystemMetadataSymbol in ctor;
+}
+
+export function isSystem(ctor: Function): boolean {
+    return hasMetadata(ctor);
+}
+
+
+export type SystemCtor<T extends SystemBase = SystemBase> = ClassType<T>;
+
+/**
+ * Arguments passed to {@link SystemBase.compute} on each {@link SystemsManager.update} call.
+ */
+export 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)`).
+ */
+export abstract class SystemBase {
+    /**
+     * Logic for one systems pass: run for all entities in {@link SystemComputeContext.entities}.
+     */
+    public abstract compute(ctx: SystemComputeContext): void;
+
+    public onInit?(world: World): void;
+};
+
+
+export class SystemsManager {
+    private systems_ = new Map<SystemCtor, SystemBase>();
+    private executionOrder_: SystemBase[] = [];
+    private requiredComponents_: Set<ComponentType> = new Set();
+
+    private dirty_ = true;
+
+    constructor(
+        private readonly world: World,
+    ) { }
+
+    public getRequiredComponents(): ComponentType[] {
+        return Array.from(this.requiredComponents_);
+    }
+
+    public register<T extends SystemBase>(sys: T): void {
+        const ctor = sys.constructor as SystemCtor<T>;
+        if (this.systems_.has(ctor)) throw new Error("Duplicate system");
+        const { query, requiredComponents } = getSystemMetadata(ctor);
+
+        this.systems_.set(ctor, sys);
+
+        const q = query;
+
+        for (const c of q.include ?? [])
+            this.requiredComponents_.add(c);
+
+        for (const c of q.exclude ?? [])
+            this.requiredComponents_.add(c);
+
+        for (const c of q.anyOf ?? [])
+            this.requiredComponents_.add(c);
+        for (const c of requiredComponents)
+            this.requiredComponents_.add(c);
+    }
+
+    public build(): void {
+        this.buildSystemsArray();
+        for (const sys of this.systems_.values())
+            sys.onInit?.(this.world);
+    }
+
+    private rebuild(): void {
+        this.build();
+    };
+
+    public get<T extends SystemBase>(ctor: SystemCtor<T>): T {
+        const s = this.systems_.get(ctor);
+
+        if (!s)
+            throw new Error("System not registered");
+        return s as T;
+    }
+
+    public update(dt: number): void {
+        if (this.dirty_)
+            this.rebuild();
+
+        this.world.events.swapAll();
+
+        for (const s of this.executionOrder_) {
+            const { query } = getSystemMetadata(s.constructor as SystemCtor)
+            const entities = this.world.query(query);
+            s.compute({ entities, world: this.world, dt });
+        }
+    }
+
+    private buildSystemsArray(): void {
+        const map = new Map<SystemCtor, DAGNode<SystemBase>>();
+
+        for (const [ctor, system] of this.systems_.entries()) {
+            map.set(ctor, new DAGNode(system));
+        }
+
+        for (const ctor of this.systems_.keys()) {
+            const currentNode = map.get(ctor)!;
+            const { computeAfter } = getSystemMetadata(ctor);
+            for (const depCtor of computeAfter ?? []) {
+                const depNode = map.get(depCtor);
+                if (!depNode) {
+                    throw new Error(`Dependency ${depCtor.name} not registered`);
+                }
+
+                depNode.vertices.push(currentNode);
+            }
+        }
+
+        this.executionOrder_ = topologicalSort(map.values()).map(x => x.data);
+    }
+}

package/ecs/world.ts

@@ -0,0 +1,99 @@
+/*
+ECS World implementation
+⢀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+⢻⣿⡗⢶⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣠⣄
+⠀⢻⣇⠀⠈⠙⠳⣦⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⠶⠛⠋⣹⣿⡿
+⠀⠀⠹⣆⠀⠀⠀⠀⠙⢷⣄⣀⣀⣀⣤⣤⣤⣄⣀⣴⠞⠋⠉⠀⠀⠀⢀⣿⡟⠁
+⠀⠀⠀⠙⢷⡀⠀⠀⠀⠀⠉⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⡾⠋⠀⠀
+⠀⠀⠀⠀⠈⠻⡶⠂⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣠⡾⠋⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⣼⠃⠀⢠⠒⣆⠀⠀⠀⠀⠀⠀⢠⢲⣄⠀⠀⠀⢻⣆⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⢰⡏⠀⠀⠈⠛⠋⠀⢀⣀⡀⠀⠀⠘⠛⠃⠀⠀⠀⠈⣿⡀⠀⠀⠀⠀
+⠀⠀⠀⠀⣾⡟⠛⢳⠀⠀⠀⠀⠀⣉⣀⠀⠀⠀⠀⣰⢛⠙⣶⠀⢹⣇⠀⠀⠀⠀
+⠀⠀⠀⠀⢿⡗⠛⠋⠀⠀⠀⠀⣾⠋⠀⢱⠀⠀⠀⠘⠲⠗⠋⠀⠈⣿⠀⠀⠀⠀
+⠀⠀⠀⠀⠘⢷⡀⠀⠀⠀⠀⠀⠈⠓⠒⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⡇⠀⠀⠀
+⠀⠀⠀⠀⠀⠈⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣧⠀⠀⠀
+⠀⠀⠀⠀⠀⠈⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠁⠀⠀⠀
+*/
+
+import { type ClassType, type ComponentType } from "@draug/types/class";
+import { EntitiesManager, type EntityID, EntityRef } from "./entity";
+import { SystemsManager } from "./system";
+import { ECS_DEFAULTS } from "./constant";
+import { EventBus } from "./events-buffer";
+import { ComponentsManager } from "./components";
+import { ResourcesManager } from "./resources/resources";
+import { Commands } from "./command";
+import { QueryManager, type QueryParameters } from "./query";
+import { PluginsManager } from "../plugin";
+
+export class World {
+    public readonly entities = new EntitiesManager();
+    public readonly components = new ComponentsManager();
+    public readonly systems = new SystemsManager(this);
+    public readonly events = new EventBus();
+    public readonly resources = new ResourcesManager();
+    public readonly commands = new Commands(this);
+    public readonly queries = new QueryManager(this);
+    public readonly plugins = new PluginsManager();
+
+    private entityRefs_ = new Map<number, EntityRef>();
+
+    constructor(maxEntityCount: number = ECS_DEFAULTS.MAX_ENTITY_COUNT) {
+        this.components = new ComponentsManager(maxEntityCount);
+    }
+
+    public getEntityRef(id: number): EntityRef {
+        let ref = this.entityRefs_.get(id);
+        if (!ref) {
+            ref = new EntityRef(this, id);
+            this.entityRefs_.set(id, ref);
+        }
+        return ref;
+    }
+    public query(params: QueryParameters): number[] {
+        return this.queries.get(params);
+    }
+
+    public removeComponent<T extends object>(ref: EntityRef, component: ComponentType<T>): void;
+    public removeComponent<T extends object>(entity: EntityID, component: ComponentType<T>): void;
+    public removeComponent<T extends object>(
+        entity: EntityID | EntityRef,
+        component: ComponentType<T>
+    ): void {
+        const id = typeof entity === 'number' ? entity : entity.id;
+
+        const storage = this.components.getStorage(component);
+        storage.remove(id);
+
+        this.queries.invalidate(component);
+    }
+
+    public addComponent<T extends object>(id: EntityID, component: ClassType<T>, initFn?: (obj: T) => void): T;
+    public addComponent<T extends object>(id: EntityRef, component: ClassType<T>, initFn?: (obj: T) => void): T
+    public addComponent<T extends object>(entity: EntityID | EntityRef, component: ClassType<T>, initFn?: (obj: T) => void): T {
+        const storage = this.components.getStorage(component);
+        let id: number;
+        if (typeof entity === 'number') {
+            id = entity;
+        } else {
+            id = entity.id;
+        }
+        const c = storage.add(id, (o) => {
+            if (initFn) {
+                initFn(o);
+            }
+            return o;
+        });
+        this.queries.invalidate(component);
+        return c;
+    };
+
+    public update(dt: number): void {
+        this.systems.update(dt);
+        this.commands.flush(this);
+    }
+
+    public build(): void {
+        this.plugins.build();
+    }
+};

package/index.ts

@@ -0,0 +1,74 @@
+export {
+    System,
+    SystemBase,
+    SystemError,
+    ErrMissingSystemMetadata,
+    ErrNotASystem,
+    isSystem,
+    getSystemMetadata,
+    SystemsManager,
+    type SystemComputeContext
+} from './ecs/system';
+
+export {
+    World
+} from './ecs/world';
+
+export {
+    Component,
+    ComponentAlreadyRegisteredError,
+    ComponentStorage,
+    ComponentsManager,
+    type IStorage,
+    SingletonStorage,
+} from './ecs/components';
+
+export { ResourcesManager } from './ecs/resources';
+
+export {
+    entry,
+    Commands,
+    type CreateEntityComponentEntry,
+    type ComponentInitFn,
+    type WorldCommand,
+} from './ecs/command';
+
+export {
+    EntityMaskNotFoundError,
+    EntityRef,
+    EntitiesManager,
+    UnregisteredComponentStorageError,
+    type EntityID,
+} from './ecs/entity';
+
+export {
+    Plugin,
+    isPlugin,
+    getPluginMetadata,
+    PluginBase,
+    PluginsManager,
+    PluginError,
+    ErrMissingPluginMetadata,
+    ErrNotAPlugin,
+    ErrPluginNotInit,
+    ErrUnknownPlugin,
+    type PluginID,
+    type PluginMetadata,
+    type PluginDependencies,
+} from './plugin';
+
+export {
+    EventBuffer,
+    EventBus,
+    createEventKey,
+} from './ecs/events-buffer';
+
+export {
+    Clock,
+    type TimeSource,
+} from './runtime/clock';
+
+export { GameLoop, type StepFunction } from './runtime/game-loop';
+export {
+    Runtime
+} from './runtime/runtime';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@draug/engine",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "author": {
+    "name": "future_undefined",
+    "email": "evgenijantonenkov456@gmail.com",
+    "url": "https://github.com/yazmeyaa"
+  },
+  "description": "Amber game engine. Based on ECS architecture.",
+  "license": "GPL-3.0-only",
+  "readme": "README.md",
+  "dependencies": {
+    "@draug/core": "workspace:^",
+    "bitmap-index": "^1.0.9",
+    "ts-sparse-set": "^1.0.5"
+  },
+  "scripts": {
+    "test": "echo Hello from engine!"
+  },
+  "devDependencies": {
+    "@draug/types": "workspace:^",
+    "typescript": "^6.0.3"
+  }
+}

package/plugin/index.ts

@@ -0,0 +1,15 @@
+export {
+    Plugin,
+    isPlugin,
+    getPluginMetadata,
+    PluginBase,
+    PluginsManager,
+    PluginError,
+    ErrMissingPluginMetadata,
+    ErrNotAPlugin,
+    ErrPluginNotInit,
+    ErrUnknownPlugin,
+    type PluginID,
+    type PluginMetadata,
+    type PluginDependencies,
+} from './plugin'

package/plugin/plugin.ts

@@ -0,0 +1,200 @@
+import type { ClassType, ComponentType } from "@draug/types/class";
+import { SystemBase } from "../ecs/system";
+import type { World } from "../ecs/world";
+import { DAGNode, topologicalSort, ErrDAGCycleDetected } from '@draug/core/graph/dag';
+
+export type PluginID = string;
+
+export type PluginDependencies = {
+    components?: ComponentType[];
+    resources?: ClassType<any>[];
+    systems?: ClassType<SystemBase>[];
+    plugins?: Array<{ id: PluginID; version?: string }>;
+}
+
+export interface PluginMetadata {
+    id: PluginID;
+    version: string;
+    name: string;
+    dependencies?: PluginDependencies;
+}
+
+const PluginMetadataSymbol = Symbol("plugin");
+
+export function Plugin(metadata: PluginMetadata): ClassDecorator {
+    return (target: Function) => {
+        if ('__proto__' in target && target.__proto__ !== PluginBase)
+            throw new ErrNotAPlugin(target);
+
+        (target as FunctionWithMetadata)[PluginMetadataSymbol] = metadata;
+    };
+}
+
+export function getPluginMetadata(plugin: ClassType<PluginBase>): PluginMetadata {
+    if (hasMetadata(plugin)) {
+        return plugin[PluginMetadataSymbol] as PluginMetadata;
+    }
+    throw new ErrMissingPluginMetadata(plugin);
+}
+
+type FunctionWithMetadata = Function & { [PluginMetadataSymbol]: PluginMetadata };
+
+export function hasMetadata(ctor: Function): ctor is FunctionWithMetadata {
+    return PluginMetadataSymbol in ctor;
+}
+
+export function isPlugin(ctor: Function): boolean {
+    return hasMetadata(ctor);
+}
+
+export abstract class PluginBase {
+    public onPluginLoad?: (world: World) => void;
+    public onPluginUnload?: (world: World) => void;
+    public onAfterWorldInit?: (world: World) => void;
+}
+
+type PluginManagerInternalPluginStorageItem<T extends ClassType<PluginBase>> = {
+    ctor: T;
+    ctorParams: ConstructorParameters<T>;
+    instance?: InstanceType<T>;
+    metadata: PluginMetadata;
+};
+
+export class PluginError extends Error {
+    constructor(pluginId: string) {
+        super(`Plugin error! Plugin [${pluginId}]`);
+    }
+}
+
+export class ErrNotAPlugin extends Error {
+    constructor(target: Function) {
+        super(`Provided class ${target.name} is not a Plugin! Every plugin must extends of PluginBase class.`);
+    }
+}
+
+export class ErrMissingPluginMetadata extends Error {
+    constructor(plugin: ClassType<PluginBase>) {
+        super(`Provided class ${plugin.name}: Missing plugin metadata! Define plugin class with @Plugin decorator.`);
+    }
+}
+
+export class ErrUnknownPlugin extends PluginError {
+    constructor(pluginId: string) {
+        super(pluginId);
+        this.message = `${super.message}: Plugin not found in manager.`;
+    }
+}
+
+export class ErrPluginNotInit extends PluginError {
+    constructor(pluginId: string) {
+        super(pluginId);
+        this.message = `${super.message}: Plugin not initiated yet. You must use PluginsManager.build() before getting instance.`;
+    }
+}
+
+export class ErrMissingPluginDependency extends PluginError {
+    constructor(pluginId: string, missingDepId: string) {
+        super(pluginId);
+        this.message = `${super.message}: Missing required dependency [${missingDepId}]. Install it first.`;
+    }
+}
+
+export class ErrDAGCycleDetectedPlugin extends Error {
+    constructor() {
+        super(`Cycle detected in plugin dependencies!`);
+    }
+}
+
+export class PluginsManager {
+    private plugins_: Map<PluginID, PluginManagerInternalPluginStorageItem<any>> = new Map();
+    private isInitiated_ = false;
+
+    public install<T extends ClassType<PluginBase>>(plugin: T, ...constructorProps: ConstructorParameters<T>): void {
+        if (!isPlugin(plugin))
+            throw new ErrMissingPluginMetadata(plugin);
+
+        const metadata = getPluginMetadata(plugin);
+
+        if (this.plugins_.has(metadata.id))
+            return;
+
+        const entry: PluginManagerInternalPluginStorageItem<T> = {
+            ctor: plugin,
+            ctorParams: constructorProps,
+            metadata,
+        };
+
+        this.plugins_.set(metadata.id, entry);
+    }
+
+    public build(): void {
+        const nodes = new Map<PluginID, DAGNode<PluginID>>();
+        for (const id of this.plugins_.keys()) {
+            nodes.set(id, new DAGNode(id));
+        }
+
+        for (const [id, entry] of this.plugins_) {
+            const node = nodes.get(id)!;
+            const depPlugins = entry.metadata.dependencies?.plugins ?? [];
+
+            for (const dep of depPlugins) {
+                const depNode = nodes.get(dep.id);
+                if (!depNode) {
+                    throw new ErrMissingPluginDependency(id, dep.id);
+                }
+                node.vertices.push(depNode);
+            }
+        }
+
+        let sortedNodes: DAGNode<PluginID>[];
+        try {
+            sortedNodes = topologicalSort(nodes.values());
+        } catch (e) {
+            if (e instanceof ErrDAGCycleDetected) {
+                throw new ErrDAGCycleDetectedPlugin();
+            }
+            throw e;
+        }
+
+        for (const node of sortedNodes) {
+            const entry = this.plugins_.get(node.data)!;
+            const { ctor, ctorParams } = entry;
+            entry.instance = new ctor(...ctorParams);
+        }
+
+        this.isInitiated_ = true;
+    }
+
+    public getPluginMetadata(pluginOrId: ClassType<PluginBase> | PluginID): PluginMetadata {
+        const id = this.resolveId(pluginOrId);
+        const entry = this.plugins_.get(id);
+        if (!entry) throw new ErrUnknownPlugin(id);
+        return entry.metadata;
+    }
+
+    public getPluginInstance<T extends PluginBase>(pluginOrId: ClassType<T> | PluginID): T {
+        if (!this.isInitiated_) {
+            throw new Error("Plugin instance is not initiated yet. Use PluginManager.build() before use plugins.");
+        }
+
+        const id = this.resolveId(pluginOrId);
+
+        const entry = this.plugins_.get(id);
+        if (!entry) throw new ErrUnknownPlugin(id);
+        if (!entry.instance) throw new ErrPluginNotInit(id);
+
+        return entry.instance as T;
+    }
+
+    private resolveId(pluginOrId: ClassType<PluginBase> | PluginID): PluginID {
+        if (typeof pluginOrId === 'string') {
+            return pluginOrId;
+        }
+
+        if (!isPlugin(pluginOrId)) {
+            throw new ErrMissingPluginMetadata(pluginOrId);
+        }
+
+        return getPluginMetadata(pluginOrId).id;
+    }
+};

package/runtime/clock.ts

@@ -0,0 +1,31 @@
+export interface TimeSource {
+    now(): number;
+}
+
+export class Clock {
+    private lastTimeMs_: number;
+    private elapsedTime_: number = 0;
+    private dt_: number = 0;
+
+    public constructor(
+        private readonly timeSource_: TimeSource,
+    ) {
+        this.lastTimeMs_ = timeSource_.now();
+    }
+
+
+    public get dt(): number {
+        return this.dt_;
+    }
+    public get ellapsedTime(): number {
+        return this.elapsedTime_;
+    }
+
+    public tick(): void {
+        const now = this.timeSource_.now();
+        const dt = now - this.lastTimeMs_;
+        this.dt_ = dt;
+        this.elapsedTime_ += dt;
+        this.lastTimeMs_ = now;
+    }
+};

package/runtime/game-loop.ts

@@ -0,0 +1,32 @@
+import { Clock } from "./clock";
+
+export type StepFunction = (dt: number) => void;
+
+export class GameLoop {
+    private running = false;
+
+    constructor(
+        private clock: Clock,
+        private stepFn: StepFunction,
+    ) { };
+
+
+    public start(platformLoop: (callback: () => void) => void) {
+        this.running = true;
+
+        const loop = () => {
+            if (!this.running) return;
+
+            this.clock.tick();
+            this.stepFn(this.clock.dt);
+
+            platformLoop(loop);
+        };
+
+        platformLoop(loop);
+    }
+
+        public stop() {
+        this.running = false;
+    }
+};