@downdraft/engine 0.0.0 → 0.1.0

package/core/src/ecs/events.ts

@@ -0,0 +1,93 @@
+import { createLogger } from "../util/logger";
+
+const log = createLogger();
+
+export interface EventChannel<T> {
+  send(event: T): void;
+  read(): T[];
+  swap(): void;
+  clear(): void;
+  isDirty(): boolean;
+}
+
+export function createEventChannel<T>(): EventChannel<T> {
+  let current: T[] = [];
+  let pending: T[] = [];
+  let dirty = false;
+  const MAX_QUEUE_SIZE = 10000;
+  let droppedCount = 0;
+
+  return {
+    send(event: T): void {
+      if (pending.length >= MAX_QUEUE_SIZE) {
+        // Drop the oldest event to make room for the newest.
+        pending.shift();
+        droppedCount++;
+        if (droppedCount === 1 || droppedCount % 1000 === 0) {
+          log.warn(
+            "EventChannel",
+            `queue full (${MAX_QUEUE_SIZE}), dropped ${droppedCount} oldest event(s) total`,
+          );
+        }
+      }
+      pending.push(event);
+      dirty = true;
+    },
+    read(): T[] {
+      const result = current;
+      current = [];
+      return result;
+    },
+    swap(): void {
+      const tmp = current;
+      current = pending;
+      pending = tmp;
+      pending.length = 0;
+      dirty = false;
+    },
+    clear(): void {
+      current.length = 0;
+      pending.length = 0;
+      dirty = false;
+    },
+    isDirty(): boolean { return dirty; },
+  };
+}
+
+export class EventBus {
+  private channels: Map<string, EventChannel<unknown>> = new Map();
+
+  get<T>(name: string): EventChannel<T> {
+    let ch = this.channels.get(name);
+    if (!ch) {
+      ch = createEventChannel<T>();
+      this.channels.set(name, ch);
+    }
+    return ch as EventChannel<T>;
+  }
+
+  channel<T>(name: string): EventChannel<T> {
+    return this.get<T>(name);
+  }
+
+  send<T>(name: string, event: T): void {
+    this.get<T>(name).send(event);
+  }
+
+  read<T>(name: string): T[] {
+    return this.get<T>(name).read() as T[];
+  }
+
+  swapAll(): void {
+    // Only swap channels that received events this frame (lazy swap)
+    for (const ch of this.channels.values()) {
+      if (ch.isDirty()) ch.swap();
+    }
+  }
+
+  clearAll(): void {
+    for (const ch of this.channels.values()) {
+      ch.clear();
+    }
+  }
+}

package/core/src/ecs/hierarchy.ts

@@ -0,0 +1,124 @@
+import type { Entity } from "./entity";
+import { ROOT_ENTITY } from "./entity";
+
+interface HierarchyData {
+  parent: Entity | null;
+  children: Entity[];
+  dirty: boolean;
+}
+
+export class Hierarchy {
+  private data: Map<number, HierarchyData> = new Map();
+
+  constructor() {
+    this.setRoot();
+  }
+
+  private setRoot(): void {
+    this.data.set(ROOT_ENTITY.index, {
+      parent: null,
+      children: [],
+      dirty: false,
+    });
+  }
+
+  private getData(entity: Entity): HierarchyData | undefined {
+    return this.data.get(entity.index);
+  }
+
+  private ensureData(entity: Entity | null): HierarchyData {
+    if (!entity) return { parent: null, children: [], dirty: false };
+    let d = this.data.get(entity.index);
+    if (!d) {
+      d = { parent: null, children: [], dirty: false };
+      this.data.set(entity.index, d);
+    }
+    return d;
+  }
+
+  getParent(entity: Entity): Entity | null {
+    const d = this.getData(entity);
+    return d ? d.parent : null;
+  }
+
+  getChildren(entity: Entity): Entity[] {
+    const d = this.getData(entity);
+    return d ? d.children : [];
+  }
+
+  setParent(entity: Entity, newParent: Entity | null): void {
+    const d = this.ensureData(entity);
+    const oldParent = d.parent;
+
+    if (oldParent && newParent && oldParent.index === newParent.index && oldParent.generation === newParent.generation) return;
+    if (!oldParent && !newParent) return;
+
+    if (oldParent) {
+      const oldParentData = this.getData(oldParent);
+      if (oldParentData) {
+        const idx = oldParentData.children.findIndex(
+          (c) => c.index === entity.index && c.generation === entity.generation,
+        );
+        if (idx >= 0) oldParentData.children.splice(idx, 1);
+      }
+    }
+
+    d.parent = newParent;
+    if (newParent) {
+      const newParentData = this.ensureData(newParent);
+      newParentData.children.push(entity);
+    }
+
+    this.markDirty(entity);
+  }
+
+  isDirty(entity: Entity): boolean {
+    const d = this.getData(entity);
+    return d ? d.dirty : false;
+  }
+
+  markDirty(entity: Entity): void {
+    // Iterative (stack-based) to prevent stack overflow on deep hierarchies
+    const stack: Entity[] = [entity];
+    while (stack.length > 0) {
+      const current = stack.pop()!;
+      const d = this.ensureData(current);
+      if (d.dirty) continue;
+      d.dirty = true;
+      for (let i = 0; i < d.children.length; i++) {
+        stack.push(d.children[i]);
+      }
+    }
+  }
+
+  clearDirty(entity: Entity): void {
+    const d = this.getData(entity);
+    if (d) d.dirty = false;
+  }
+
+  isRoot(entity: Entity): boolean {
+    if (entity.index !== ROOT_ENTITY.index || entity.generation !== ROOT_ENTITY.generation) return false;
+    const d = this.getData(entity);
+    return !d || d.parent === null;
+  }
+
+  traverse(root: Entity, fn: (entity: Entity, depth: number) => void): void {
+    // Iterative (stack-based) to prevent stack overflow on deep hierarchies
+    const stack: Array<{ entity: Entity; depth: number }> = [{ entity: root, depth: 0 }];
+    while (stack.length > 0) {
+      const { entity, depth } = stack.pop()!;
+      fn(entity, depth);
+      const children = this.getChildren(entity);
+      // Push in reverse order so children are visited left-to-right
+      for (let i = children.length - 1; i >= 0; i--) {
+        stack.push({ entity: children[i], depth: depth + 1 });
+      }
+    }
+  }
+
+  getDescendants(entity: Entity): Entity[] {
+    const result: Entity[] = [];
+    this.traverse(entity, (e) => result.push(e));
+    return result;
+  }
+}

package/core/src/ecs/hmr-swap-registry.ts

@@ -0,0 +1,22 @@
+import type { System } from "./system";
+
+type SwapCallback = (newMod: Record<string, unknown>) => void;
+
+const swapCallbacks = new Map<string, SwapCallback>();
+
+export function registerHmrSwap(systemName: string, callback: SwapCallback): void {
+  swapCallbacks.set(systemName, callback);
+}
+
+export function hmrSwap(systemName: string, newMod: Record<string, unknown>): void {
+  const cb = swapCallbacks.get(systemName);
+  if (cb) cb(newMod);
+}
+
+export function unregisterHmrSwap(systemName: string): void {
+  swapCallbacks.delete(systemName);
+}
+
+export function clearHmrSwaps(): void {
+  swapCallbacks.clear();
+}

package/core/src/ecs/index.ts

@@ -0,0 +1,25 @@
+// ECS sub-barrel — re-exports all ECS-related items.
+export { archetypeMatches, createArchetype, getArchetypeForComponents, getColumnValue, isSoAColumn, reconstructSoAObject, removeArchetypeFromHashMap, setColumnValue } from "./archetype";
+export type { Archetype, Column, SoAColumn } from "./archetype";
+export { Component, component, getComponentDefinition, getComponentId, getComponentName, isRegisteredComponentId, isRegisteredComponentName, isSoAComponentDef, listComponentDefinitions, listComponentNames, SOA_DEFAULT_VALUE, SOA_TYPED_ARRAY_CTOR, soaComponent } from "./component";
+export type { ComponentDefinition, ComponentId, IComponent, SoAComponentData, SoAComponentDefinition, SoAFieldType, SoASchema, SoATypedArray } from "./component";
+export { entityEqual, entityToString, isAlive, ROOT_ENTITY } from "./entity";
+export type { Entity, EntityMeta } from "./entity";
+export { createEventChannel, EventBus } from "./events";
+export type { EventChannel } from "./events";
+export { Hierarchy } from "./hierarchy";
+export { clearHmrSwaps, hmrSwap, registerHmrSwap, unregisterHmrSwap } from "./hmr-swap-registry";
+export { Query, query, queryChanged, queryExcluded, queryFromDefs } from "./query";
+export type { QueryDescriptor } from "./query";
+export { resourceToken } from "./resource";
+export type { ResourceToken } from "./resource";
+export { Schedule } from "./schedule";
+export { Stage, system } from "./system";
+export type { System, SystemContext, SystemFn } from "./system";
+export { q, res, systemWithParams } from "./system-params";
+export type { ParamSystemFn, QueryParam, Res, ResolvedParam, ResParam, SystemParam } from "./system-params";
+export { World } from "./world";
+
+// Job System (lives under ecs/)
+
+

package/core/src/ecs/query.ts

@@ -0,0 +1,141 @@
+import type { Archetype } from "./archetype";
+import { archetypeMatches, getComponentColumn, isSoAColumn, type Column } from "./archetype";
+import type { ComponentDefinition, ComponentId } from "./component";
+
+export interface QueryDescriptor {
+  required: ComponentId[];
+  excluded: ComponentId[];
+  changedFilter?: ComponentId;
+  lastReadTick: number;
+}
+
+export class Query {
+  readonly descriptor: QueryDescriptor;
+  private archetypes: Archetype[] = [];
+  private cachedArchetypes: Set<number> = new Set();
+
+  private iterComps: unknown[] = [];
+  private iterColumns: Column[] = [];
+
+  constructor(required: ComponentId[], excluded: ComponentId[] = [], changedFilter?: ComponentId) {
+    this.descriptor = {
+      required,
+      excluded,
+      changedFilter,
+      lastReadTick: 0,
+    };
+  }
+
+  updateArchetypes(allArchetypes: Archetype[]): void {
+    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: Archetype): boolean {
+    return this.cachedArchetypes.has(arch.id);
+  }
+
+  iterate<T extends unknown[]>(
+    currentTick: number,
+    fn: (entity: import("./entity").Entity, components: T, row: number) => void,
+  ): void {
+    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"] as Uint32Array | undefined;
+          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 as unknown[])[row];
+              }
+              fn(entities[row], comps as T, row);
+            }
+          }
+        } else {
+          const changedColArr = changedCol as { lastChanged: number }[];
+          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 as unknown[])[row];
+              }
+              fn(entities[row], comps as T, 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 as unknown[])[row];
+          }
+          fn(entities[row], comps as T, row);
+        }
+      }
+    }
+
+    this.descriptor.lastReadTick = currentTick;
+  }
+
+  count(): number {
+    let total = 0;
+    for (let i = 0; i < this.archetypes.length; i++) {
+      total += this.archetypes[i].entities.length;
+    }
+    return total;
+  }
+}
+
+export function query(
+  ...required: ComponentId[]
+): Query {
+  return new Query(required);
+}
+
+export function queryExcluded(
+  required: ComponentId[],
+  excluded: ComponentId[],
+): Query {
+  return new Query(required, excluded);
+}
+
+export function queryChanged(
+  required: ComponentId[],
+  changedComponent: ComponentId,
+): Query {
+  return new Query(required, [], changedComponent);
+}
+
+export function queryFromDefs(
+  ...defs: ComponentDefinition<any>[]
+): Query {
+  return new Query(defs.map((d) => d.id));
+}

package/core/src/ecs/resource.ts

@@ -0,0 +1,8 @@
+export interface ResourceToken<T> {
+  readonly __resourceBrand: T;
+  readonly key: string;
+}
+
+export function resourceToken<T>(key: string): ResourceToken<T> {
+  return { __resourceBrand: undefined as unknown as T, key };
+}

package/core/src/ecs/schedule.ts

@@ -0,0 +1,181 @@
+import { createLogger } from "../util/logger";
+import type { Archetype } from "./archetype";
+import type { Query } from "./query";
+import { Stage, type System, type SystemContext } from "./system";
+export type { SystemContext };
+
+const log = createLogger();
+
+interface ScheduledSystem {
+  system: System;
+  order: number;
+}
+
+export class Schedule {
+  private systems: Map<Stage, ScheduledSystem[]> = new Map();
+  private ordered: Map<Stage, System[]> = new Map();
+  private allQueries: Query[] = [];
+  private dirty: boolean = true;
+
+  add(sys: System): this {
+    return this.addSystem(sys);
+  }
+
+  addSystem(sys: System): this {
+    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: string): this {
+    return this.removeSystem(name);
+  }
+
+  removeSystem(name: string): this {
+    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: Stage): System[] {
+    if (this.dirty) {
+      this.resolveOrder();
+    }
+    return this.ordered.get(stage) ?? [];
+  }
+
+  getAllSystems(): System[] {
+    if (this.dirty) {
+      this.resolveOrder();
+    }
+    const all: System[] = [];
+    for (let s = 0; s <= 4; s++) {
+      const stage = s as Stage;
+      all.push(...(this.ordered.get(stage) ?? []));
+    }
+    return all;
+  }
+
+  getAllQueries(): Query[] {
+    if (this.dirty) {
+      this.resolveOrder();
+    }
+    return this.allQueries;
+  }
+
+  updateQueryArchetypes(archetypes: Archetype[]): void {
+    const queries = this.getAllQueries();
+    for (let i = 0; i < queries.length; i++) {
+      queries[i].updateArchetypes(archetypes);
+    }
+  }
+
+  run(world: import("./world").World, dt: number, tick: number): void {
+    const ctx: SystemContext = { world, dt, tick };
+    for (let s = 0; s <= 4; s++) {
+      this.runStage(s as Stage, ctx);
+    }
+  }
+
+  runStage(stage: Stage, ctx: SystemContext): void {
+    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);
+    }
+  }
+
+  private resolveOrder(): void {
+    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;
+  }
+
+  private topologicalSort(bucket: ScheduledSystem[]): System[] {
+    const nameToSys = new Map<string, ScheduledSystem>();
+    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<string, string[]>();
+    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<string>();
+    const result: System[] = [];
+
+    const visit = (name: string, path: Set<string>) => {
+      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/core/src/ecs/system-params.ts

@@ -0,0 +1,99 @@
+import type { ComponentDefinition } from "./component";
+import type { Query } from "./query";
+import { queryFromDefs } from "./query";
+import type { ResourceToken } from "./resource";
+import { Stage, type System, type SystemContext, type SystemFn } from "./system";
+import type { World } from "./world";
+
+export interface Res<T> {
+  /** Live view of the resource — re-reads from the world on every access. */
+  readonly value: T | undefined;
+}
+
+export interface ResParam<T> {
+  readonly kind: "res";
+  readonly token: ResourceToken<T>;
+}
+
+export interface QueryParam {
+  readonly kind: "query";
+  readonly query: Query;
+}
+
+export type SystemParam = ResParam<unknown> | QueryParam;
+
+export function res<T>(token: ResourceToken<T>): ResParam<T> {
+  return { kind: "res", token };
+}
+
+export function q(
+  ...defs: ComponentDefinition<any>[]
+): QueryParam {
+  return { kind: "query", query: queryFromDefs(...defs) };
+}
+
+export type ResolvedParam = Res<unknown> | Query;
+
+export function resolveParams(
+  world: World,
+  params: SystemParam[],
+): ResolvedParam[] {
+  const resolved: ResolvedParam[] = [];
+  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 type ParamSystemFn = (ctx: SystemContext, ...args: ResolvedParam[]) => void;
+
+/** Maps a declared SystemParam to the value injected into the system fn. */
+export type ResolvedParamFor<P> =
+  P extends ResParam<infer T> ? Res<T>
+  : P extends QueryParam ? Query
+  : ResolvedParam;
+
+/** Tuple-map: `q(...) → Query`, `res(Tok<T>) → Res<T>`, in declared order. */
+export type ResolvedParamsFor<P extends readonly SystemParam[]> = {
+  [K in keyof P]: ResolvedParamFor<P[K]>;
+};
+
+export function systemWithParams<P extends readonly SystemParam[]>(
+  name: string,
+  stage: Stage,
+  params: P,
+  fn: (ctx: SystemContext, ...args: ResolvedParamsFor<P>) => void,
+  opts: { after?: string[]; before?: string[] } = {},
+): System {
+  let resolvedCache: ResolvedParam[] | null = null;
+
+  const wrappedFn: SystemFn = (ctx: SystemContext) => {
+    if (!resolvedCache) {
+      resolvedCache = resolveParams(ctx.world, [...params]);
+    }
+    fn(ctx, ...(resolvedCache as unknown as ResolvedParamsFor<P>));
+  };
+
+  const queries = params
+    .filter((p): p is QueryParam => p.kind === "query")
+    .map((p) => p.query);
+
+  return {
+    name,
+    stage,
+    fn: wrappedFn,
+    queries,
+    after: opts.after,
+    before: opts.before,
+  };
+}