@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/ecs/query.js

@@ -0,0 +1,110 @@
+import { archetypeMatches, getComponentColumn, isSoAColumn } from "./archetype.js";
+export class Query {
+    descriptor;
+    archetypes = [];
+    cachedArchetypes = new Set();
+    iterComps = [];
+    iterColumns = [];
+    constructor(required, excluded = [], changedFilter) {
+        this.descriptor = {
+            required,
+            excluded,
+            changedFilter,
+            lastReadTick: 0,
+        };
+    }
+    updateArchetypes(allArchetypes) {
+        this.archetypes.length = 0;
+        this.cachedArchetypes.clear();
+        for (let i = 0; i < allArchetypes.length; i++) {
+            const arch = allArchetypes[i];
+            if (archetypeMatches(arch, this.descriptor.required, this.descriptor.excluded)) {
+                this.archetypes.push(arch);
+                this.cachedArchetypes.add(arch.id);
+            }
+        }
+    }
+    matchesArchetype(arch) {
+        return this.cachedArchetypes.has(arch.id);
+    }
+    iterate(currentTick, fn) {
+        const required = this.descriptor.required;
+        const changedFilter = this.descriptor.changedFilter;
+        const ncomps = required.length;
+        const comps = this.iterComps;
+        if (comps.length !== ncomps)
+            comps.length = ncomps;
+        for (let a = 0; a < this.archetypes.length; a++) {
+            const arch = this.archetypes[a];
+            const entities = arch.entities;
+            const count = entities.length;
+            const columns = this.iterColumns;
+            if (columns.length !== ncomps)
+                columns.length = ncomps;
+            for (let r = 0; r < ncomps; r++) {
+                columns[r] = getComponentColumn(arch, required[r]);
+            }
+            if (changedFilter !== undefined) {
+                const changedCol = getComponentColumn(arch, changedFilter);
+                if (!changedCol)
+                    continue;
+                if (isSoAColumn(changedCol)) {
+                    // SoA changed filter: read lastChanged from the TypedArray
+                    const lastChangedArr = changedCol.arrays["lastChanged"];
+                    if (!lastChangedArr)
+                        continue;
+                    for (let row = 0; row < count; row++) {
+                        if (lastChangedArr[row] >= this.descriptor.lastReadTick) {
+                            for (let c = 0; c < ncomps; c++) {
+                                const col = columns[c];
+                                comps[c] = isSoAColumn(col) ? col.arrays : col[row];
+                            }
+                            fn(entities[row], comps, row);
+                        }
+                    }
+                }
+                else {
+                    const changedColArr = changedCol;
+                    for (let row = 0; row < count; row++) {
+                        if (changedColArr[row].lastChanged >= this.descriptor.lastReadTick) {
+                            for (let c = 0; c < ncomps; c++) {
+                                const col = columns[c];
+                                comps[c] = isSoAColumn(col) ? col.arrays : col[row];
+                            }
+                            fn(entities[row], comps, row);
+                        }
+                    }
+                }
+            }
+            else {
+                for (let row = 0; row < count; row++) {
+                    for (let c = 0; c < ncomps; c++) {
+                        const col = columns[c];
+                        comps[c] = isSoAColumn(col) ? col.arrays : col[row];
+                    }
+                    fn(entities[row], comps, row);
+                }
+            }
+        }
+        this.descriptor.lastReadTick = currentTick;
+    }
+    count() {
+        let total = 0;
+        for (let i = 0; i < this.archetypes.length; i++) {
+            total += this.archetypes[i].entities.length;
+        }
+        return total;
+    }
+}
+export function query(...required) {
+    return new Query(required);
+}
+export function queryExcluded(required, excluded) {
+    return new Query(required, excluded);
+}
+export function queryChanged(required, changedComponent) {
+    return new Query(required, [], changedComponent);
+}
+export function queryFromDefs(...defs) {
+    return new Query(defs.map((d) => d.id));
+}

package/dist/core/src/ecs/resource.js

@@ -0,0 +1,3 @@
+export function resourceToken(key) {
+    return { __resourceBrand: undefined, key };
+}

package/dist/core/src/ecs/schedule.js

@@ -0,0 +1,157 @@
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export class Schedule {
+    systems = new Map();
+    ordered = new Map();
+    allQueries = [];
+    dirty = true;
+    add(sys) {
+        return this.addSystem(sys);
+    }
+    addSystem(sys) {
+        const stage = sys.stage;
+        let bucket = this.systems.get(stage);
+        if (!bucket) {
+            bucket = [];
+            this.systems.set(stage, bucket);
+        }
+        bucket.push({ system: sys, order: bucket.length });
+        this.dirty = true;
+        return this;
+    }
+    remove(name) {
+        return this.removeSystem(name);
+    }
+    removeSystem(name) {
+        for (const [stage, bucket] of this.systems.entries()) {
+            const idx = bucket.findIndex((s) => s.system.name === name);
+            if (idx >= 0) {
+                bucket.splice(idx, 1);
+                this.dirty = true;
+            }
+        }
+        return this;
+    }
+    getSystems(stage) {
+        if (this.dirty) {
+            this.resolveOrder();
+        }
+        return this.ordered.get(stage) ?? [];
+    }
+    getAllSystems() {
+        if (this.dirty) {
+            this.resolveOrder();
+        }
+        const all = [];
+        for (let s = 0; s <= 4; s++) {
+            const stage = s;
+            all.push(...(this.ordered.get(stage) ?? []));
+        }
+        return all;
+    }
+    getAllQueries() {
+        if (this.dirty) {
+            this.resolveOrder();
+        }
+        return this.allQueries;
+    }
+    updateQueryArchetypes(archetypes) {
+        const queries = this.getAllQueries();
+        for (let i = 0; i < queries.length; i++) {
+            queries[i].updateArchetypes(archetypes);
+        }
+    }
+    run(world, dt, tick) {
+        const ctx = { world, dt, tick };
+        for (let s = 0; s <= 4; s++) {
+            this.runStage(s, ctx);
+        }
+    }
+    runStage(stage, ctx) {
+        if (this.dirty) {
+            this.resolveOrder();
+        }
+        const systems = this.ordered.get(stage);
+        if (!systems)
+            return;
+        for (let i = 0; i < systems.length; i++) {
+            systems[i].fn(ctx);
+        }
+    }
+    resolveOrder() {
+        for (const [stage, bucket] of this.systems.entries()) {
+            const sorted = this.topologicalSort(bucket);
+            this.ordered.set(stage, sorted);
+        }
+        this.allQueries.length = 0;
+        for (const systems of this.ordered.values()) {
+            for (let i = 0; i < systems.length; i++) {
+                const queries = systems[i].queries;
+                for (let q = 0; q < queries.length; q++) {
+                    this.allQueries.push(queries[q]);
+                }
+            }
+        }
+        this.dirty = false;
+    }
+    topologicalSort(bucket) {
+        const nameToSys = new Map();
+        for (let i = 0; i < bucket.length; i++) {
+            nameToSys.set(bucket[i].system.name, bucket[i]);
+        }
+        // Build reverse edges from `before` declarations:
+        // if A declares `before: [B]`, then B must run after A.
+        // We collect these as additional implicit `after` deps on B.
+        const implicitAfter = new Map();
+        for (let i = 0; i < bucket.length; i++) {
+            const sys = bucket[i].system;
+            if (!sys.before)
+                continue;
+            for (let j = 0; j < sys.before.length; j++) {
+                const target = sys.before[j];
+                if (!nameToSys.has(target))
+                    continue; // skip unknown systems
+                let list = implicitAfter.get(target);
+                if (!list) {
+                    list = [];
+                    implicitAfter.set(target, list);
+                }
+                list.push(sys.name);
+            }
+        }
+        const visited = new Set();
+        const result = [];
+        const visit = (name, path) => {
+            if (visited.has(name))
+                return;
+            if (path.has(name)) {
+                log.warn("schedule", `System dependency cycle detected involving "${name}" — skipping`);
+                return;
+            }
+            const entry = nameToSys.get(name);
+            if (!entry)
+                return;
+            path.add(name);
+            // Process explicit `after` deps
+            if (entry.system.after) {
+                for (let i = 0; i < entry.system.after.length; i++) {
+                    visit(entry.system.after[i], path);
+                }
+            }
+            // Process implicit `after` deps (from other systems' `before` declarations)
+            const implicit = implicitAfter.get(name);
+            if (implicit) {
+                for (let i = 0; i < implicit.length; i++) {
+                    visit(implicit[i], path);
+                }
+            }
+            path.delete(name);
+            visited.add(name);
+            result.push(entry.system);
+        };
+        for (let i = 0; i < bucket.length; i++) {
+            visit(bucket[i].system.name, new Set());
+        }
+        return result;
+    }
+}

package/dist/core/src/ecs/system-params.js

@@ -0,0 +1,45 @@
+import { queryFromDefs } from "./query.js";
+export function res(token) {
+    return { kind: "res", token };
+}
+export function q(...defs) {
+    return { kind: "query", query: queryFromDefs(...defs) };
+}
+export function resolveParams(world, params) {
+    const resolved = [];
+    params.forEach((param) => {
+        if (param.kind === "res") {
+            // Live view: the getter reads from the world on every .value access,
+            // so resource updates (including hot-reload) are reflected immediately.
+            resolved.push({
+                get value() {
+                    return world.getResourceTyped(param.token);
+                },
+            });
+        }
+        else {
+            resolved.push(param.query);
+        }
+    });
+    return resolved;
+}
+export function systemWithParams(name, stage, params, fn, opts = {}) {
+    let resolvedCache = null;
+    const wrappedFn = (ctx) => {
+        if (!resolvedCache) {
+            resolvedCache = resolveParams(ctx.world, [...params]);
+        }
+        fn(ctx, ...resolvedCache);
+    };
+    const queries = params
+        .filter((p) => p.kind === "query")
+        .map((p) => p.query);
+    return {
+        name,
+        stage,
+        fn: wrappedFn,
+        queries,
+        after: opts.after,
+        before: opts.before,
+    };
+}

package/dist/core/src/ecs/system.js

@@ -0,0 +1,18 @@
+export var Stage;
+(function (Stage) {
+    Stage[Stage["Input"] = 0] = "Input";
+    Stage[Stage["Update"] = 1] = "Update";
+    Stage[Stage["Physics"] = 2] = "Physics";
+    Stage[Stage["PostUpdate"] = 3] = "PostUpdate";
+    Stage[Stage["Render"] = 4] = "Render";
+})(Stage || (Stage = {}));
+export function system(name, stage, fn, opts = {}) {
+    return {
+        name,
+        stage,
+        fn,
+        queries: opts.queries ?? [],
+        after: opts.after,
+        before: opts.before,
+    };
+}

package/dist/core/src/ecs/world.js

@@ -0,0 +1,292 @@
+import { isDebug } from "../sab/errors.js";
+import { createLogger } from "../util/logger.js";
+import { addEntityToArchetype, createArchetype, findEntityRow, getArchetypeForComponents, getColumnValue, removeArchetypeFromHashMap, removeEntityFromArchetype, setColumnValue } from "./archetype.js";
+import { ROOT_ENTITY } from "./entity.js";
+import { EventBus } from "./events.js";
+import { Schedule } from "./schedule.js";
+const log = createLogger();
+export class World {
+    entities = [];
+    // Unbounded on purpose: the free list can only ever hold ≤ peak-entity-count
+    // entries, while capping it meant discarded indices were never recycled and
+    // entities[] grew unboundedly under high spawn/despawn churn.
+    entityFreeList = [];
+    archetypes = new Map();
+    allArchetypes = [];
+    archetypeById = new Map();
+    schedule = new Schedule();
+    events = new EventBus();
+    resources = new Map();
+    tick = 0;
+    archetypesDirty = false;
+    commands = [];
+    emptyArchetype;
+    constructor() {
+        this.emptyArchetype = createArchetype([]);
+        this.allArchetypes.push(this.emptyArchetype);
+        this.archetypeById.set(this.emptyArchetype.id, this.emptyArchetype);
+        this.entities[0] = { generation: 0, alive: true, archetypeId: this.emptyArchetype.id };
+    }
+    registerArchetype(arch) {
+        if (!this.archetypeById.has(arch.id)) {
+            this.allArchetypes.push(arch);
+        }
+        this.archetypeById.set(arch.id, arch);
+    }
+    spawn(components) {
+        const componentIds = [...components.keys()];
+        const arch = componentIds.length === 0
+            ? this.emptyArchetype
+            : getArchetypeForComponents(this.archetypes, componentIds);
+        this.registerArchetype(arch);
+        let index;
+        let generation;
+        if (this.entityFreeList.length > 0) {
+            index = this.entityFreeList.pop();
+            generation = this.entities[index].generation;
+            this.entities[index] = { generation, alive: true, archetypeId: arch.id };
+        }
+        else {
+            index = this.entities.length;
+            generation = 0;
+            this.entities.push({ generation, alive: true, archetypeId: arch.id });
+        }
+        const entity = { index, generation };
+        addEntityToArchetype(arch, entity, components);
+        this.archetypesDirty = true;
+        return entity;
+    }
+    despawn(entity) {
+        this.commands.push((w) => w._despawnImmediate(entity));
+    }
+    _despawnImmediate(entity) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return;
+        const arch = this.findArchetypeById(meta.archetypeId);
+        if (!arch)
+            return;
+        removeEntityFromArchetype(arch, entity);
+        meta.alive = false;
+        meta.generation++;
+        this.entityFreeList.push(entity.index);
+        this.archetypesDirty = true;
+    }
+    addComponent(entity, componentId, data) {
+        this.commands.push((w) => w._addComponentImmediate(entity, componentId, data));
+    }
+    _addComponentImmediate(entity, componentId, data) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return;
+        const oldArch = this.findArchetypeById(meta.archetypeId);
+        if (!oldArch || oldArch.componentSet.has(componentId))
+            return;
+        const oldRow = findEntityRow(oldArch, entity);
+        if (oldRow < 0)
+            return;
+        const existingComponents = new Map();
+        oldArch.componentIds.forEach((cid) => {
+            existingComponents.set(cid, getColumnValue(oldArch.columns.get(cid), oldRow));
+        });
+        existingComponents.set(componentId, data);
+        removeEntityFromArchetype(oldArch, entity);
+        const newArch = getArchetypeForComponents(this.archetypes, [...existingComponents.keys()]);
+        this.registerArchetype(newArch);
+        addEntityToArchetype(newArch, entity, existingComponents);
+        meta.archetypeId = newArch.id;
+        this.archetypesDirty = true;
+    }
+    removeComponent(entity, componentId) {
+        this.commands.push((w) => w._removeComponentImmediate(entity, componentId));
+    }
+    _removeComponentImmediate(entity, componentId) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return;
+        const oldArch = this.findArchetypeById(meta.archetypeId);
+        if (!oldArch || !oldArch.componentSet.has(componentId))
+            return;
+        const oldRow = findEntityRow(oldArch, entity);
+        if (oldRow < 0)
+            return;
+        const existingComponents = new Map();
+        oldArch.componentIds.forEach((cid) => {
+            if (cid !== componentId) {
+                existingComponents.set(cid, getColumnValue(oldArch.columns.get(cid), oldRow));
+            }
+        });
+        removeEntityFromArchetype(oldArch, entity);
+        const newArch = existingComponents.size === 0
+            ? this.emptyArchetype
+            : getArchetypeForComponents(this.archetypes, [...existingComponents.keys()]);
+        this.registerArchetype(newArch);
+        addEntityToArchetype(newArch, entity, existingComponents);
+        meta.archetypeId = newArch.id;
+        this.archetypesDirty = true;
+    }
+    /**
+     * In-place data update for a component the entity already has.
+     * Unlike addComponent (which no-ops when the component is present), this
+     * replaces the stored value without an archetype move.
+     */
+    setComponent(entity, componentId, data) {
+        this.commands.push((w) => w._setComponentImmediate(entity, componentId, data));
+    }
+    _setComponentImmediate(entity, componentId, data) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return;
+        const arch = this.findArchetypeById(meta.archetypeId);
+        if (!arch || !arch.componentSet.has(componentId))
+            return;
+        const row = findEntityRow(arch, entity);
+        if (row < 0)
+            return;
+        setColumnValue(arch.columns.get(componentId), row, data);
+        this.archetypesDirty = true;
+    }
+    getArchetypeAndRow(entity) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return null;
+        const arch = this.findArchetypeById(meta.archetypeId);
+        if (!arch)
+            return null;
+        const row = findEntityRow(arch, entity);
+        if (row < 0)
+            return null;
+        return { arch, row };
+    }
+    getComponent(entity, componentId) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return null;
+        const arch = this.findArchetypeById(meta.archetypeId);
+        if (!arch || !arch.componentSet.has(componentId))
+            return null;
+        const row = findEntityRow(arch, entity);
+        if (row < 0)
+            return null;
+        return (getColumnValue(arch.columns.get(componentId), row) ?? null);
+    }
+    hasComponent(entity, componentId) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return false;
+        const arch = this.findArchetypeById(meta.archetypeId);
+        return arch ? arch.componentSet.has(componentId) : false;
+    }
+    flushCommands() {
+        for (let i = 0; i < this.commands.length; i++) {
+            try {
+                this.commands[i](this);
+            }
+            catch (err) {
+                log.error("world", `Command at index ${i} threw: ${err}`);
+                // In debug mode, re-throw to surface command errors immediately.
+                // In production, log and continue for game-loop resilience.
+                if (isDebug())
+                    throw err;
+            }
+        }
+        this.commands.length = 0;
+        if (this.archetypesDirty) {
+            this.pruneEmptyArchetypes();
+            this.schedule.updateQueryArchetypes(this.allArchetypes);
+            this.archetypesDirty = false;
+        }
+    }
+    /**
+     * Reclaim archetypes with no live entities. `allArchetypes` only ever grew —
+     * a game that churns through many component combinations (spawn/despawn
+     * variety) accumulated dead archetypes that `updateQueryArchetypes` rescanned
+     * on every structural flush. Hysteresis: only prune when the list is large
+     * AND mostly dead, so spawn/despawn oscillation between two archetypes
+     * doesn't thrash destroy→recreate.
+     */
+    pruneEmptyArchetypes() {
+        const all = this.allArchetypes;
+        if (all.length < 256)
+            return;
+        let dead = 0;
+        all.forEach((a) => {
+            if (a.entities.length === 0 && a !== this.emptyArchetype)
+                dead++;
+        });
+        if (dead * 4 < all.length)
+            return;
+        const survivors = [];
+        all.forEach((a) => {
+            if (a.entities.length === 0 && a !== this.emptyArchetype) {
+                this.archetypeById.delete(a.id);
+                removeArchetypeFromHashMap(this.archetypes, a);
+            }
+            else {
+                survivors.push(a);
+            }
+        });
+        this.allArchetypes = survivors;
+    }
+    step(dt) {
+        this.tick++;
+        this.events.swapAll();
+        // Update query archetypes before running systems so that entities
+        // spawned/modified before this step are visible to queries during it.
+        // flushCommands() at the end of step() will handle any structural
+        // changes made by systems during this step.
+        if (this.archetypesDirty) {
+            this.schedule.updateQueryArchetypes(this.allArchetypes);
+            this.archetypesDirty = false;
+        }
+        const ctx = { world: this, dt, tick: this.tick };
+        this.schedule.runStage(0, ctx); // Input
+        this.schedule.runStage(1, ctx); // Update
+        this.schedule.runStage(2, ctx); // Physics
+        this.schedule.runStage(3, ctx); // PostUpdate
+        this.schedule.runStage(4, ctx); // Render (render-prep systems)
+        this.flushCommands();
+    }
+    setResourceTyped(token, value) {
+        this.resources.set(token.key, value);
+    }
+    getResourceTyped(token) {
+        return this.resources.get(token.key);
+    }
+    addComponentDef(entity, def, data) {
+        this.addComponent(entity, def.id, data);
+    }
+    getComponentDef(entity, def) {
+        return this.getComponent(entity, def.id);
+    }
+    hasComponentDef(entity, def) {
+        return this.hasComponent(entity, def.id);
+    }
+    clearAllEntities() {
+        for (let i = 1; i < this.entities.length; i++) {
+            const meta = this.entities[i];
+            if (meta && meta.alive) {
+                this.despawn({ index: i, generation: meta.generation });
+            }
+        }
+        this.flushCommands();
+    }
+    entityCount() {
+        let count = 0;
+        for (let i = 0; i < this.entities.length; i++) {
+            if (this.entities[i].alive)
+                count++;
+        }
+        return count;
+    }
+    findArchetypeById(id) {
+        return this.archetypeById.get(id);
+    }
+    getArchetypeForEntity(entity) {
+        const meta = this.entities[entity.index];
+        if (!meta || meta.generation !== entity.generation || !meta.alive)
+            return null;
+        return this.archetypeById.get(meta.archetypeId) ?? null;
+    }
+}
+export { ROOT_ENTITY };