archetype-ecs 1.2.0 → 1.3.2

package/dist/Profiler.d.ts

@@ -0,0 +1,12 @@
+export interface ProfilerEntry {
+    avg: number;
+}
+export interface Profiler {
+    readonly enabled: boolean;
+    setEnabled(value: boolean): void;
+    begin(): number;
+    end(name: string, t0: number): void;
+    record(name: string, ms: number): void;
+    getData(): Map<string, ProfilerEntry>;
+}
+export declare const profiler: Profiler;

package/dist/Profiler.js

@@ -0,0 +1,38 @@
+const EMA_ALPHA = 0.1;
+const data = new Map();
+let enabled = false;
+export const profiler = {
+    get enabled() { return enabled; },
+    setEnabled(value) {
+        enabled = value;
+        if (!value)
+            data.clear();
+    },
+    begin() {
+        return enabled ? performance.now() : 0;
+    },
+    end(name, t0) {
+        if (!enabled)
+            return;
+        const ms = performance.now() - t0;
+        const entry = data.get(name);
+        if (entry) {
+            entry.avg += (ms - entry.avg) * EMA_ALPHA;
+        }
+        else {
+            data.set(name, { avg: ms });
+        }
+    },
+    record(name, ms) {
+        if (!enabled)
+            return;
+        const entry = data.get(name);
+        if (entry) {
+            entry.avg += (ms - entry.avg) * EMA_ALPHA;
+        }
+        else {
+            data.set(name, { avg: ms });
+        }
+    },
+    getData() { return data; }
+};

package/dist/System.d.ts

@@ -0,0 +1,41 @@
+import type { ComponentDef } from './ComponentRegistry.js';
+import type { EntityId, EntityManager, ArchetypeView } from './EntityManager.js';
+export declare function OnAdded(...types: ComponentDef[]): (method: (id: EntityId) => void, _context: ClassMethodDecoratorContext) => void;
+export declare function OnRemoved(...types: ComponentDef[]): (method: (id: EntityId) => void, _context: ClassMethodDecoratorContext) => void;
+interface Hook {
+    buffer: Set<EntityId>;
+    handler: (id: EntityId) => void;
+}
+export declare class System {
+    em: EntityManager;
+    _unsubs: (() => void)[];
+    _hooks: Hook[];
+    constructor(em: EntityManager);
+    _registerHook(kind: 'add' | 'remove', types: ComponentDef[], handler: (id: EntityId) => void): void;
+    forEach(types: ComponentDef[], callback: (view: ArchetypeView) => void, exclude?: ComponentDef[]): void;
+    tick?(): void;
+    /** Process hooks and tick without clearing removed-data snapshots. */
+    _runCore(): void;
+    run(): void;
+    dispose(): void;
+}
+type HookCallback = (entityId: EntityId) => void;
+export interface SystemContext {
+    onAdded(...args: [...ComponentDef[], HookCallback]): void;
+    onRemoved(...args: [...ComponentDef[], HookCallback]): void;
+    forEach(types: ComponentDef[], callback: (view: ArchetypeView) => void, exclude?: ComponentDef[]): void;
+}
+export type FunctionalSystemConstructor = (sys: SystemContext) => (() => void) | void;
+export interface FunctionalSystem {
+    (): void;
+    /** @internal Process hooks and tick without clearing removed-data snapshots. */
+    _runCore(): void;
+    dispose(): void;
+}
+export declare function createSystem(em: EntityManager, constructor: FunctionalSystemConstructor): FunctionalSystem;
+export interface Pipeline {
+    (): void;
+    dispose(): void;
+}
+export declare function createSystems(em: EntityManager, entries: (FunctionalSystemConstructor | (new (em: EntityManager) => System))[]): Pipeline;
+export {};

package/dist/System.js

@@ -0,0 +1,159 @@
+// ── Decorators (TC39 Stage 3) ────────────────────────────
+export function OnAdded(...types) {
+    return function (method, _context) {
+        _context.addInitializer(function () {
+            const self = this;
+            self._registerHook('add', types, method.bind(self));
+        });
+    };
+}
+export function OnRemoved(...types) {
+    return function (method, _context) {
+        _context.addInitializer(function () {
+            const self = this;
+            self._registerHook('remove', types, method.bind(self));
+        });
+    };
+}
+export class System {
+    em;
+    _unsubs = [];
+    _hooks = [];
+    constructor(em) {
+        this.em = em;
+    }
+    _registerHook(kind, types, handler) {
+        const buffer = new Set();
+        if (kind === 'add') {
+            for (const comp of types) {
+                const unsub = this.em.onAdd(comp, (id) => {
+                    for (let i = 0; i < types.length; i++) {
+                        if (!this.em.hasComponent(id, types[i]))
+                            return;
+                    }
+                    buffer.add(id);
+                });
+                this._unsubs.push(unsub);
+            }
+        }
+        else {
+            for (const comp of types) {
+                const unsub = this.em.onRemove(comp, (id) => buffer.add(id));
+                this._unsubs.push(unsub);
+            }
+        }
+        this._hooks.push({ buffer, handler });
+    }
+    forEach(types, callback, exclude) {
+        this.em.forEach(types, callback, exclude);
+    }
+    /** Process hooks and tick without clearing removed-data snapshots. */
+    _runCore() {
+        for (const hook of this._hooks) {
+            for (const id of hook.buffer)
+                hook.handler(id);
+            hook.buffer.clear();
+        }
+        if (this.tick)
+            this.tick();
+    }
+    run() {
+        this._runCore();
+        this.em.commitRemovals();
+    }
+    dispose() {
+        for (const unsub of this._unsubs)
+            unsub();
+        this._unsubs.length = 0;
+        this._hooks.length = 0;
+    }
+}
+export function createSystem(em, constructor) {
+    const hooks = [];
+    const sys = {
+        onAdded(...args) {
+            const callback = args[args.length - 1];
+            const types = args.slice(0, -1);
+            const buffer = new Set();
+            const unsubs = [];
+            for (const comp of types) {
+                const unsub = em.onAdd(comp, (id) => {
+                    for (let i = 0; i < types.length; i++) {
+                        if (!em.hasComponent(id, types[i]))
+                            return;
+                    }
+                    buffer.add(id);
+                });
+                unsubs.push(unsub);
+            }
+            hooks.push({ unsubs, buffer, callback });
+        },
+        onRemoved(...args) {
+            const callback = args[args.length - 1];
+            const types = args.slice(0, -1);
+            const buffer = new Set();
+            const unsubs = [];
+            for (const comp of types) {
+                const unsub = em.onRemove(comp, (id) => {
+                    buffer.add(id);
+                });
+                unsubs.push(unsub);
+            }
+            hooks.push({ unsubs, buffer, callback });
+        },
+        forEach(types, callback, exclude) {
+            em.forEach(types, callback, exclude);
+        },
+    };
+    const tick = constructor(sys);
+    function runCore() {
+        for (const hook of hooks) {
+            for (const id of hook.buffer)
+                hook.callback(id);
+            hook.buffer.clear();
+        }
+        if (tick)
+            tick();
+    }
+    function system() {
+        runCore();
+        em.commitRemovals();
+    }
+    system._runCore = runCore;
+    system.dispose = function () {
+        for (const hook of hooks) {
+            for (const unsub of hook.unsubs)
+                unsub();
+        }
+        hooks.length = 0;
+    };
+    return system;
+}
+function isSystemClass(entry) {
+    let proto = entry.prototype;
+    while (proto) {
+        proto = Object.getPrototypeOf(proto);
+        if (proto === System.prototype)
+            return true;
+    }
+    return false;
+}
+export function createSystems(em, entries) {
+    const systems = entries.map(Entry => {
+        if (isSystemClass(Entry)) {
+            return new Entry(em);
+        }
+        const sys = createSystem(em, Entry);
+        return { _runCore: sys._runCore, dispose: sys.dispose };
+    });
+    function pipeline() {
+        for (let i = 0; i < systems.length; i++)
+            systems[i]._runCore();
+        em.commitRemovals();
+    }
+    pipeline.dispose = function () {
+        for (let i = 0; i < systems.length; i++)
+            systems[i].dispose();
+    };
+    return pipeline;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { createEntityManager } from './EntityManager.js';
+export type { EntityId, ArchetypeView, EntityManager, SerializedData } from './EntityManager.js';
+export { createSystem, createSystems, System, OnAdded, OnRemoved } from './System.js';
+export type { SystemContext, FunctionalSystemConstructor, FunctionalSystem, Pipeline } from './System.js';
+export { profiler } from './Profiler.js';
+export type { Profiler, ProfilerEntry } from './Profiler.js';
+export { TYPED, componentSchemas, parseTypeSpec } from './ComponentRegistry.js';
+export type { ComponentDef, FieldRef, TypeSpec } from './ComponentRegistry.js';
+import { type ComponentDef } from './ComponentRegistry.js';
+export declare function component(name: string): ComponentDef;
+export declare function component<const F extends readonly string[]>(name: string, type: string, fields: F): ComponentDef<F[number]>;
+export declare function component<S extends Record<string, string>>(name: string, schema: S): ComponentDef<Extract<keyof S, string>>;

package/dist/index.js

@@ -0,0 +1,29 @@
+export { createEntityManager } from './EntityManager.js';
+export { createSystem, createSystems, System, OnAdded, OnRemoved } from './System.js';
+export { profiler } from './Profiler.js';
+export { TYPED, componentSchemas, parseTypeSpec } from './ComponentRegistry.js';
+import { parseTypeSpec, componentSchemas } from './ComponentRegistry.js';
+export function component(name, typeOrSchema, fields) {
+    const sym = Symbol(name);
+    const comp = { _sym: sym, _name: name };
+    let schema;
+    if (typeof typeOrSchema === 'string' && Array.isArray(fields)) {
+        const spec = parseTypeSpec(typeOrSchema);
+        schema = {};
+        for (const f of fields) {
+            schema[f] = spec;
+            comp[f] = { _sym: sym, _field: f };
+        }
+    }
+    else if (typeOrSchema && typeof typeOrSchema === 'object') {
+        schema = {};
+        for (const [field, type] of Object.entries(typeOrSchema)) {
+            schema[field] = parseTypeSpec(type);
+            comp[field] = { _sym: sym, _field: field };
+        }
+    }
+    if (schema) {
+        componentSchemas.set(sym, schema);
+    }
+    return comp;
+}

package/dist/src/ComponentRegistry.d.ts

@@ -0,0 +1,18 @@
+export declare const TYPED: unique symbol;
+type TypedArrayConstructor = typeof Float32Array | typeof Float64Array | typeof Int8Array | typeof Int16Array | typeof Int32Array | typeof Uint8Array | typeof Uint16Array | typeof Uint32Array | typeof Array;
+export declare const TYPE_MAP: Record<string, TypedArrayConstructor>;
+export type TypeSpec = TypedArrayConstructor | [TypedArrayConstructor, number];
+export declare function parseTypeSpec(typeStr: string): TypeSpec;
+export declare const componentSchemas: Map<symbol, Record<string, TypeSpec>>;
+export interface FieldRef {
+    readonly _sym: symbol;
+    readonly _field: string;
+}
+export type ComponentDef<S extends Record<string, string> = {}> = {
+    readonly _sym: symbol;
+    readonly _name: string;
+} & {
+    readonly [K in keyof S]: FieldRef;
+};
+export declare function toSym(type: ComponentDef | symbol): symbol;
+export {};

package/dist/src/ComponentRegistry.js

@@ -0,0 +1,29 @@
+export const TYPED = Symbol('typed');
+export const TYPE_MAP = {
+    'f32': Float32Array,
+    'f64': Float64Array,
+    'i8': Int8Array,
+    'i16': Int16Array,
+    'i32': Int32Array,
+    'u8': Uint8Array,
+    'u16': Uint16Array,
+    'u32': Uint32Array,
+    'string': Array,
+};
+export function parseTypeSpec(typeStr) {
+    const match = typeStr.match(/^(\w+)\[(\d+)\]$/);
+    if (match) {
+        const Ctor = TYPE_MAP[match[1]];
+        if (!Ctor)
+            throw new Error(`Unknown base type "${match[1]}"`);
+        return [Ctor, parseInt(match[2])];
+    }
+    const Ctor = TYPE_MAP[typeStr];
+    if (!Ctor)
+        throw new Error(`Unknown type "${typeStr}"`);
+    return Ctor;
+}
+export const componentSchemas = new Map();
+export function toSym(type) {
+    return type._sym || type;
+}

package/dist/src/EntityManager.d.ts

@@ -0,0 +1,49 @@
+import { type ComponentDef, type FieldRef } from './ComponentRegistry.js';
+export type { FieldRef } from './ComponentRegistry.js';
+export type EntityId = number;
+export interface ArchetypeView {
+    readonly id: number;
+    readonly entityIds: EntityId[];
+    readonly count: number;
+    readonly snapshotEntityIds: EntityId[] | null;
+    readonly snapshotCount: number;
+    field(ref: FieldRef): any;
+    fieldStride(ref: FieldRef): number;
+    snapshot(ref: FieldRef): any;
+}
+export interface SerializedData {
+    nextId: number;
+    entities: EntityId[];
+    components: Record<string, Record<string, unknown>>;
+}
+export interface EntityManager {
+    createEntity(): EntityId;
+    destroyEntity(id: EntityId): void;
+    addComponent(entityId: EntityId, type: ComponentDef, data?: any): void;
+    removeComponent(entityId: EntityId, type: ComponentDef): void;
+    getComponent(entityId: EntityId, type: ComponentDef): any;
+    get(entityId: EntityId, fieldRef: FieldRef): any;
+    set(entityId: EntityId, fieldRef: FieldRef, value: any): void;
+    hasComponent(entityId: EntityId, type: ComponentDef): boolean;
+    query(include: ComponentDef[], exclude?: ComponentDef[]): EntityId[];
+    getAllEntities(): EntityId[];
+    createEntityWith(...args: unknown[]): EntityId;
+    count(include: ComponentDef[], exclude?: ComponentDef[]): number;
+    forEach(include: ComponentDef[], callback: (view: ArchetypeView) => void, exclude?: ComponentDef[]): void;
+    onAdd(type: ComponentDef, callback: (entityId: EntityId) => void): () => void;
+    onRemove(type: ComponentDef, callback: (entityId: EntityId) => void): () => void;
+    flushHooks(): void;
+    enableTracking(filterComponent: ComponentDef): void;
+    flushChanges(): {
+        created: Set<EntityId>;
+        destroyed: Set<EntityId>;
+    };
+    flushSnapshots(): void;
+    serialize(symbolToName: Map<symbol, string>, stripComponents?: ComponentDef[], skipEntitiesWith?: ComponentDef[], options?: {
+        serializers?: Map<string, (data: unknown) => unknown>;
+    }): SerializedData;
+    deserialize(data: SerializedData, nameToSymbol: Record<string, ComponentDef>, options?: {
+        deserializers?: Map<string, (data: unknown) => unknown>;
+    }): void;
+}
+export declare function createEntityManager(): EntityManager;