@aethervtt/shard-core 0.0.1

package/dist/math/vec2.d.ts

@@ -0,0 +1,11 @@
+import type { Readable, Writable } from './types.js';
+export declare const create: (x?: number, y?: number) => Float32Array;
+export declare function set<T extends Writable>(out: T, x: number, y: number): T;
+export declare function copy<T extends Writable>(out: T, a: Readable): T;
+export declare function add<T extends Writable>(out: T, a: Readable, b: Readable): T;
+export declare function sub<T extends Writable>(out: T, a: Readable, b: Readable): T;
+export declare function scale<T extends Writable>(out: T, a: Readable, s: number): T;
+export declare const dot: (a: Readable, b: Readable) => number;
+export declare const length: (a: Readable) => number;
+export declare function normalize<T extends Writable>(out: T, a: Readable): T;
+export declare function lerp<T extends Writable>(out: T, a: Readable, b: Readable, t: number): T;

package/dist/math/vec2.js

@@ -0,0 +1,52 @@
+const create = (x = 0, y = 0) => new Float32Array([x, y]);
+function set(out, x, y) {
+  out[0] = x;
+  out[1] = y;
+  return out;
+}
+function copy(out, a) {
+  out[0] = a[0];
+  out[1] = a[1];
+  return out;
+}
+function add(out, a, b) {
+  out[0] = a[0] + b[0];
+  out[1] = a[1] + b[1];
+  return out;
+}
+function sub(out, a, b) {
+  out[0] = a[0] - b[0];
+  out[1] = a[1] - b[1];
+  return out;
+}
+function scale(out, a, s) {
+  out[0] = a[0] * s;
+  out[1] = a[1] * s;
+  return out;
+}
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1];
+const length = (a) => Math.sqrt(a[0] * a[0] + a[1] * a[1]);
+function normalize(out, a) {
+  const len = Math.sqrt(a[0] * a[0] + a[1] * a[1]);
+  const inv = len > 0 ? 1 / len : 0;
+  out[0] = a[0] * inv;
+  out[1] = a[1] * inv;
+  return out;
+}
+function lerp(out, a, b, t) {
+  out[0] = a[0] + (b[0] - a[0]) * t;
+  out[1] = a[1] + (b[1] - a[1]) * t;
+  return out;
+}
+export {
+  add,
+  copy,
+  create,
+  dot,
+  length,
+  lerp,
+  normalize,
+  scale,
+  set,
+  sub
+};

package/dist/math/vec3.d.ts

@@ -0,0 +1,23 @@
+import { type Readable, type Writable } from './types.js';
+export declare const create: (x?: number, y?: number, z?: number) => Float32Array;
+export declare function set<T extends Writable>(out: T, x: number, y: number, z: number): T;
+export declare function copy<T extends Writable>(out: T, a: Readable): T;
+export declare function add<T extends Writable>(out: T, a: Readable, b: Readable): T;
+export declare function sub<T extends Writable>(out: T, a: Readable, b: Readable): T;
+export declare function mul<T extends Writable>(out: T, a: Readable, b: Readable): T;
+export declare function scale<T extends Writable>(out: T, a: Readable, s: number): T;
+/** out = a + b * s */
+export declare function scaleAndAdd<T extends Writable>(out: T, a: Readable, b: Readable, s: number): T;
+export declare function negate<T extends Writable>(out: T, a: Readable): T;
+export declare const dot: (a: Readable, b: Readable) => number;
+export declare function cross<T extends Writable>(out: T, a: Readable, b: Readable): T;
+export declare const lengthSq: (a: Readable) => number;
+export declare const length: (a: Readable) => number;
+export declare function distance(a: Readable, b: Readable): number;
+export declare function normalize<T extends Writable>(out: T, a: Readable): T;
+export declare function lerp<T extends Writable>(out: T, a: Readable, b: Readable, t: number): T;
+/** Rotates `a` by unit quaternion `q`. */
+export declare function transformQuat<T extends Writable>(out: T, a: Readable, q: Readable): T;
+/** Transforms a point by a column-major mat4, with perspective divide. */
+export declare function transformMat4<T extends Writable>(out: T, a: Readable, m: Readable): T;
+export declare function equals(a: Readable, b: Readable, epsilon?: number): boolean;

package/dist/math/vec3.js

@@ -0,0 +1,135 @@
+import { EPSILON } from "./types.js";
+const create = (x = 0, y = 0, z = 0) => new Float32Array([x, y, z]);
+function set(out, x, y, z) {
+  out[0] = x;
+  out[1] = y;
+  out[2] = z;
+  return out;
+}
+function copy(out, a) {
+  out[0] = a[0];
+  out[1] = a[1];
+  out[2] = a[2];
+  return out;
+}
+function add(out, a, b) {
+  out[0] = a[0] + b[0];
+  out[1] = a[1] + b[1];
+  out[2] = a[2] + b[2];
+  return out;
+}
+function sub(out, a, b) {
+  out[0] = a[0] - b[0];
+  out[1] = a[1] - b[1];
+  out[2] = a[2] - b[2];
+  return out;
+}
+function mul(out, a, b) {
+  out[0] = a[0] * b[0];
+  out[1] = a[1] * b[1];
+  out[2] = a[2] * b[2];
+  return out;
+}
+function scale(out, a, s) {
+  out[0] = a[0] * s;
+  out[1] = a[1] * s;
+  out[2] = a[2] * s;
+  return out;
+}
+function scaleAndAdd(out, a, b, s) {
+  out[0] = a[0] + b[0] * s;
+  out[1] = a[1] + b[1] * s;
+  out[2] = a[2] + b[2] * s;
+  return out;
+}
+function negate(out, a) {
+  out[0] = -a[0];
+  out[1] = -a[1];
+  out[2] = -a[2];
+  return out;
+}
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+function cross(out, a, b) {
+  const ax = a[0];
+  const ay = a[1];
+  const az = a[2];
+  const bx = b[0];
+  const by = b[1];
+  const bz = b[2];
+  out[0] = ay * bz - az * by;
+  out[1] = az * bx - ax * bz;
+  out[2] = ax * by - ay * bx;
+  return out;
+}
+const lengthSq = (a) => a[0] * a[0] + a[1] * a[1] + a[2] * a[2];
+const length = (a) => Math.sqrt(lengthSq(a));
+function distance(a, b) {
+  const x = a[0] - b[0];
+  const y = a[1] - b[1];
+  const z = a[2] - b[2];
+  return Math.sqrt(x * x + y * y + z * z);
+}
+function normalize(out, a) {
+  const len = length(a);
+  const inv = len > 0 ? 1 / len : 0;
+  out[0] = a[0] * inv;
+  out[1] = a[1] * inv;
+  out[2] = a[2] * inv;
+  return out;
+}
+function lerp(out, a, b, t) {
+  out[0] = a[0] + (b[0] - a[0]) * t;
+  out[1] = a[1] + (b[1] - a[1]) * t;
+  out[2] = a[2] + (b[2] - a[2]) * t;
+  return out;
+}
+function transformQuat(out, a, q) {
+  const qx = q[0];
+  const qy = q[1];
+  const qz = q[2];
+  const qw = q[3];
+  const x = a[0];
+  const y = a[1];
+  const z = a[2];
+  const tx = 2 * (qy * z - qz * y);
+  const ty = 2 * (qz * x - qx * z);
+  const tz = 2 * (qx * y - qy * x);
+  out[0] = x + qw * tx + (qy * tz - qz * ty);
+  out[1] = y + qw * ty + (qz * tx - qx * tz);
+  out[2] = z + qw * tz + (qx * ty - qy * tx);
+  return out;
+}
+function transformMat4(out, a, m) {
+  const x = a[0];
+  const y = a[1];
+  const z = a[2];
+  const w = m[3] * x + m[7] * y + m[11] * z + m[15] || 1;
+  out[0] = (m[0] * x + m[4] * y + m[8] * z + m[12]) / w;
+  out[1] = (m[1] * x + m[5] * y + m[9] * z + m[13]) / w;
+  out[2] = (m[2] * x + m[6] * y + m[10] * z + m[14]) / w;
+  return out;
+}
+function equals(a, b, epsilon = EPSILON) {
+  return Math.abs(a[0] - b[0]) <= epsilon && Math.abs(a[1] - b[1]) <= epsilon && Math.abs(a[2] - b[2]) <= epsilon;
+}
+export {
+  add,
+  copy,
+  create,
+  cross,
+  distance,
+  dot,
+  equals,
+  length,
+  lengthSq,
+  lerp,
+  mul,
+  negate,
+  normalize,
+  scale,
+  scaleAndAdd,
+  set,
+  sub,
+  transformMat4,
+  transformQuat
+};

package/dist/math/vec4.d.ts

@@ -0,0 +1,8 @@
+import type { Readable, Writable } from './types.js';
+export declare const create: (x?: number, y?: number, z?: number, w?: number) => Float32Array;
+export declare function set<T extends Writable>(out: T, x: number, y: number, z: number, w: number): T;
+export declare function copy<T extends Writable>(out: T, a: Readable): T;
+export declare function scale<T extends Writable>(out: T, a: Readable, s: number): T;
+export declare const dot: (a: Readable, b: Readable) => number;
+export declare function lerp<T extends Writable>(out: T, a: Readable, b: Readable, t: number): T;
+export declare function transformMat4<T extends Writable>(out: T, a: Readable, m: Readable): T;

package/dist/math/vec4.js

@@ -0,0 +1,47 @@
+const create = (x = 0, y = 0, z = 0, w = 0) => new Float32Array([x, y, z, w]);
+function set(out, x, y, z, w) {
+  out[0] = x;
+  out[1] = y;
+  out[2] = z;
+  out[3] = w;
+  return out;
+}
+function copy(out, a) {
+  out[0] = a[0];
+  out[1] = a[1];
+  out[2] = a[2];
+  out[3] = a[3];
+  return out;
+}
+function scale(out, a, s) {
+  out[0] = a[0] * s;
+  out[1] = a[1] * s;
+  out[2] = a[2] * s;
+  out[3] = a[3] * s;
+  return out;
+}
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+function lerp(out, a, b, t) {
+  for (let i = 0; i < 4; i++) out[i] = a[i] + (b[i] - a[i]) * t;
+  return out;
+}
+function transformMat4(out, a, m) {
+  const x = a[0];
+  const y = a[1];
+  const z = a[2];
+  const w = a[3];
+  out[0] = m[0] * x + m[4] * y + m[8] * z + m[12] * w;
+  out[1] = m[1] * x + m[5] * y + m[9] * z + m[13] * w;
+  out[2] = m[2] * x + m[6] * y + m[10] * z + m[14] * w;
+  out[3] = m[3] * x + m[7] * y + m[11] * z + m[15] * w;
+  return out;
+}
+export {
+  copy,
+  create,
+  dot,
+  lerp,
+  scale,
+  set,
+  transformMat4
+};

package/dist/scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export { Profiler, ProfilerResource, type SystemTiming } from './profiler.js';
+export { defineSchedule, First, FixedUpdate, Last, PostUpdate, PreUpdate, Schedule, type ScheduleLabel, type ScheduleRunOptions, Startup, type SystemDescription, Update, } from './schedule.js';
+export { type Condition, condition, conditionLabel, defineSystem, defineSystemSet, type Label, not, SystemConfig, type SystemContext, type SystemDef, type SystemSetConfig, type SystemSetDef, type SystemSpec, } from './system.js';

package/dist/scheduler/index.js

@@ -0,0 +1,39 @@
+import { Profiler, ProfilerResource } from "./profiler.js";
+import {
+  defineSchedule,
+  First,
+  FixedUpdate,
+  Last,
+  PostUpdate,
+  PreUpdate,
+  Schedule,
+  Startup,
+  Update
+} from "./schedule.js";
+import {
+  condition,
+  conditionLabel,
+  defineSystem,
+  defineSystemSet,
+  not,
+  SystemConfig
+} from "./system.js";
+export {
+  First,
+  FixedUpdate,
+  Last,
+  PostUpdate,
+  PreUpdate,
+  Profiler,
+  ProfilerResource,
+  Schedule,
+  Startup,
+  SystemConfig,
+  Update,
+  condition,
+  conditionLabel,
+  defineSchedule,
+  defineSystem,
+  defineSystemSet,
+  not
+};

package/dist/scheduler/profiler.d.ts

@@ -0,0 +1,19 @@
+export interface SystemTiming {
+    /** Most recent run, in ms. */
+    last: number;
+    /** Mean over the window, in ms. */
+    avg: number;
+    max: number;
+    /** Number of samples in the window. */
+    samples: number;
+}
+/** Per-system CPU time over the last `window` runs, in a ring buffer. */
+export declare class Profiler {
+    readonly window: number;
+    private readonly series;
+    constructor(window?: number);
+    record(name: string, ms: number): void;
+    timing(name: string): SystemTiming | undefined;
+    all(): Record<string, SystemTiming>;
+}
+export declare const ProfilerResource: import("..").ResourceDef<Profiler>;

package/dist/scheduler/profiler.js

@@ -0,0 +1,44 @@
+import { defineResource } from "../schema/resource.js";
+class Profiler {
+  window;
+  series = /* @__PURE__ */ new Map();
+  constructor(window = 120) {
+    this.window = window;
+  }
+  record(name, ms) {
+    let series = this.series.get(name);
+    if (!series) {
+      series = { samples: new Float64Array(this.window), cursor: 0, count: 0 };
+      this.series.set(name, series);
+    }
+    series.samples[series.cursor] = ms;
+    series.cursor = (series.cursor + 1) % this.window;
+    if (series.count < this.window) series.count++;
+  }
+  timing(name) {
+    const series = this.series.get(name);
+    if (!series || series.count === 0) return void 0;
+    let sum = 0;
+    let max = 0;
+    for (let i = 0; i < series.count; i++) {
+      const v = series.samples[i];
+      sum += v;
+      if (v > max) max = v;
+    }
+    const last = series.samples[(series.cursor - 1 + this.window) % this.window];
+    return { last, avg: sum / series.count, max, samples: series.count };
+  }
+  all() {
+    const out = {};
+    for (const name of this.series.keys()) out[name] = this.timing(name);
+    return out;
+  }
+}
+const ProfilerResource = defineResource("core/Profiler", {
+  description: "Per-system CPU timings over recent frames.",
+  init: () => new Profiler()
+});
+export {
+  Profiler,
+  ProfilerResource
+};

package/dist/scheduler/schedule.d.ts

@@ -0,0 +1,52 @@
+import type { World } from '../ecs/world.js';
+import type { Profiler } from './profiler.js';
+import { SystemConfig, type SystemDef, type SystemSetConfig } from './system.js';
+export interface ScheduleLabel {
+    readonly kind: 'schedule';
+    readonly name: string;
+}
+export declare function defineSchedule(name: string): ScheduleLabel;
+/** Runs once, before the first frame. */
+export declare const Startup: ScheduleLabel;
+export declare const First: ScheduleLabel;
+export declare const PreUpdate: ScheduleLabel;
+/** Runs 0..N times per frame at a fixed rate. */
+export declare const FixedUpdate: ScheduleLabel;
+export declare const Update: ScheduleLabel;
+export declare const PostUpdate: ScheduleLabel;
+export declare const Last: ScheduleLabel;
+export interface ScheduleRunOptions {
+    now: () => number;
+    profiler?: Profiler | undefined;
+}
+export interface SystemDescription {
+    name: string;
+    description?: string;
+    after: string[];
+    before: string[];
+    sets: string[];
+    conditions: string[];
+}
+/**
+ * An ordered set of systems. Order comes from `after`/`before` constraints (on systems and
+ * sets); systems with no relation keep registration order, so runs are deterministic.
+ */
+export declare class Schedule {
+    readonly label: ScheduleLabel;
+    private readonly entries;
+    private readonly setConfigs;
+    private order;
+    constructor(label: ScheduleLabel);
+    add(system: SystemDef<unknown> | SystemConfig): void;
+    /** Removes systems by name and set configs by identity (hot reload). Returns how many systems went. */
+    remove(systems: ReadonlySet<string>, sets?: ReadonlySet<SystemSetConfig>): number;
+    configureSet(config: SystemSetConfig): void;
+    get size(): number;
+    /** Systems in the order they run. Throws `app/system-cycle` if constraints form a cycle. */
+    ordered(): readonly SystemConfig[];
+    run(world: World, options: ScheduleRunOptions): void;
+    describe(): SystemDescription[];
+    private setConditionMap;
+    private resolve;
+    private cycleError;
+}

package/dist/scheduler/schedule.js

@@ -0,0 +1,235 @@
+import { Commands } from "../ecs/commands.js";
+import { ShardError } from "../error.js";
+import {
+  conditionLabel,
+  SystemConfig
+} from "./system.js";
+function defineSchedule(name) {
+  return { kind: "schedule", name };
+}
+const Startup = defineSchedule("Startup");
+const First = defineSchedule("First");
+const PreUpdate = defineSchedule("PreUpdate");
+const FixedUpdate = defineSchedule("FixedUpdate");
+const Update = defineSchedule("Update");
+const PostUpdate = defineSchedule("PostUpdate");
+const Last = defineSchedule("Last");
+class Context {
+  lastRunTick = 0;
+  thisRunTick = 0;
+  commands;
+  world;
+  readers = /* @__PURE__ */ new Map();
+  constructor(world) {
+    this.world = world;
+    this.commands = new Commands(world);
+  }
+  reader(event) {
+    let reader = this.readers.get(event.id);
+    if (!reader) {
+      reader = this.world.reader(event);
+      this.readers.set(event.id, reader);
+    }
+    return reader;
+  }
+}
+class Schedule {
+  label;
+  entries = [];
+  setConfigs = [];
+  order;
+  constructor(label) {
+    this.label = label;
+  }
+  add(system) {
+    const config = system instanceof SystemConfig ? system : new SystemConfig(system);
+    this.entries.push({
+      config,
+      index: this.entries.length,
+      state: void 0,
+      ctx: void 0,
+      conditions: []
+    });
+    this.order = void 0;
+  }
+  /** Removes systems by name and set configs by identity (hot reload). Returns how many systems went. */
+  remove(systems, sets = /* @__PURE__ */ new Set()) {
+    const before = this.entries.length;
+    const kept = this.entries.filter((e) => !systems.has(e.config.system.name));
+    this.entries.length = 0;
+    for (let index = 0; index < kept.length; index++) this.entries.push({ ...kept[index], index });
+    const keptSets = this.setConfigs.filter((c) => !sets.has(c));
+    this.setConfigs.length = 0;
+    this.setConfigs.push(...keptSets);
+    this.order = void 0;
+    return before - this.entries.length;
+  }
+  configureSet(config) {
+    this.setConfigs.push(config);
+    this.order = void 0;
+  }
+  get size() {
+    return this.entries.length;
+  }
+  /** Systems in the order they run. Throws `app/system-cycle` if constraints form a cycle. */
+  ordered() {
+    return this.resolve().map((e) => e.config);
+  }
+  run(world, options) {
+    const order = this.resolve();
+    for (let i = 0; i < order.length; i++) {
+      const entry = order[i];
+      const conditions = entry.conditions;
+      let skip = false;
+      for (let c = 0; c < conditions.length; c++) {
+        if (!conditions[c](world)) {
+          skip = true;
+          break;
+        }
+      }
+      if (skip) continue;
+      const system = entry.config.system;
+      if (!entry.ctx) {
+        entry.ctx = new Context(world);
+        entry.state = system.setup ? system.setup(world) : void 0;
+      }
+      const ctx = entry.ctx;
+      ctx.thisRunTick = world.incrementTick();
+      const start = options.now();
+      try {
+        system.run(entry.state, world, ctx);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const code = err instanceof ShardError ? ` [${err.code}]` : "";
+        throw new ShardError(
+          "app/system-failed",
+          `System "${system.name}" failed${code}: ${message}`,
+          {
+            cause: err,
+            hint: err instanceof ShardError ? err.hint : void 0
+          }
+        );
+      }
+      options.profiler?.record(system.name, options.now() - start);
+      ctx.lastRunTick = ctx.thisRunTick;
+      world.incrementTick();
+      if (ctx.commands.length > 0) ctx.commands.apply();
+    }
+  }
+  describe() {
+    const setConditions = this.setConditionMap();
+    return this.ordered().map((config) => {
+      const out = {
+        name: config.system.name,
+        after: config.afterLabels.map((l) => l.name),
+        before: config.beforeLabels.map((l) => l.name),
+        sets: config.sets.map((s) => s.name),
+        conditions: [
+          ...config.sets.flatMap((s) => setConditions.get(s.name) ?? []),
+          ...config.conditions
+        ].map(conditionLabel)
+      };
+      if (config.system.description) out.description = config.system.description;
+      return out;
+    });
+  }
+  setConditionMap() {
+    const map = /* @__PURE__ */ new Map();
+    for (const sc of this.setConfigs) {
+      map.set(sc.set.name, [...map.get(sc.set.name) ?? [], ...sc.conditions]);
+    }
+    return map;
+  }
+  resolve() {
+    if (this.order) return this.order;
+    const entries = this.entries;
+    const n = entries.length;
+    const edges = entries.map(() => /* @__PURE__ */ new Set());
+    const indegree = new Array(n).fill(0);
+    const link = (from, to) => {
+      if (from === to || edges[from].has(to)) return;
+      edges[from].add(to);
+      indegree[to]++;
+    };
+    const targets = (label) => entries.filter(
+      (e) => label.kind === "system" ? e.config.system === label : e.config.sets.includes(label)
+    ).map((e) => e.index);
+    for (const entry of entries) {
+      for (const label of entry.config.afterLabels) {
+        for (const t of targets(label)) link(t, entry.index);
+      }
+      for (const label of entry.config.beforeLabels) {
+        for (const t of targets(label)) link(entry.index, t);
+      }
+    }
+    for (const sc of this.setConfigs) {
+      const members = targets(sc.set);
+      for (const label of sc.afterLabels) {
+        for (const t of targets(label)) for (const m of members) link(t, m);
+      }
+      for (const label of sc.beforeLabels) {
+        for (const t of targets(label)) for (const m of members) link(m, t);
+      }
+    }
+    const order = [];
+    const done = new Array(n).fill(false);
+    for (let step = 0; step < n; step++) {
+      let next = -1;
+      for (let i = 0; i < n; i++) {
+        if (!done[i] && indegree[i] === 0) {
+          next = i;
+          break;
+        }
+      }
+      if (next === -1) throw this.cycleError(edges, done);
+      done[next] = true;
+      order.push(entries[next]);
+      for (const to of edges[next]) indegree[to]--;
+    }
+    const setConditions = this.setConditionMap();
+    for (const entry of entries) {
+      entry.conditions = [
+        ...entry.config.sets.flatMap((s) => setConditions.get(s.name) ?? []),
+        ...entry.config.conditions
+      ];
+    }
+    this.order = order;
+    return order;
+  }
+  cycleError(edges, done) {
+    const preds = edges.map(() => []);
+    edges.forEach((targets, from) => {
+      for (const to of targets) preds[to].push(from);
+    });
+    const start = done.indexOf(false);
+    const path = [start];
+    const seen = /* @__PURE__ */ new Map([[start, 0]]);
+    let current = start;
+    for (; ; ) {
+      const prev = preds[current].find((p) => !done[p]);
+      if (seen.has(prev)) {
+        const cycle = path.slice(seen.get(prev)).reverse();
+        const names = [...cycle, cycle[0]].map((i) => this.entries[i].config.system.name);
+        return new ShardError(
+          "app/system-cycle",
+          `Systems in ${this.label.name} form an ordering cycle: ${names.join(" \u2192 ")}`,
+          { hint: "Remove one of the after/before constraints in this cycle." }
+        );
+      }
+      seen.set(prev, path.length);
+      path.push(prev);
+      current = prev;
+    }
+  }
+}
+export {
+  First,
+  FixedUpdate,
+  Last,
+  PostUpdate,
+  PreUpdate,
+  Schedule,
+  Startup,
+  Update,
+  defineSchedule
+};