@georgeluo/ecs 0.1.0

package/dist/index.cjs

@@ -0,0 +1,813 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Bus: () => Bus,
+  ComponentManager: () => ComponentManager,
+  EjectSystem: () => EjectSystem,
+  EntityManager: () => EntityManager,
+  EvaluationMessageType: () => EvaluationMessageType,
+  EvaluationPlayer: () => EvaluationPlayer,
+  FrameFilter: () => FrameFilter,
+  IOPlayer: () => IOPlayer,
+  InboundHandlerRegistry: () => InboundHandlerRegistry,
+  InjectFrame: () => InjectFrame,
+  InjectSystem: () => InjectSystem,
+  MessageHandler: () => MessageHandler,
+  Pause: () => Pause,
+  Player: () => Player,
+  SimulationMessageType: () => SimulationMessageType,
+  SimulationPlayer: () => SimulationPlayer,
+  Start: () => Start,
+  Stop: () => Stop,
+  System: () => System,
+  SystemManager: () => SystemManager,
+  TimeComponent: () => TimeComponent,
+  TimeSystem: () => TimeSystem,
+  createEntityId: () => createEntityId
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/entity/EntityManager.ts
+var EntityManager = class {
+  constructor() {
+    this.nextId = 0;
+    this.active = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Create and register a new entity identifier.
+   *
+   * @returns Entity id allocated for use in the environment.
+   */
+  create() {
+    const entity = this.nextId;
+    this.nextId += 1;
+    this.active.add(entity);
+    return entity;
+  }
+  /**
+   * Remove an entity and return whether it existed. This should trigger
+   * component cleanup via the ComponentManager (wired externally).
+   *
+   * @param entity Entity identifier to destroy.
+   */
+  remove(entity) {
+    return this.active.delete(entity);
+  }
+  /**
+   * Indicates whether the manager currently tracks the entity.
+   *
+   * @param entity Entity identifier to inspect.
+   */
+  has(entity) {
+    return this.active.has(entity);
+  }
+  /**
+   * Provide a snapshot list of active entities. Higher level systems
+   * may use this to iterate over the environment.
+   */
+  list() {
+    return Array.from(this.active.values());
+  }
+  /**
+   * Iterate over all active entities without allocating an intermediate array.
+   */
+  forEach(callback) {
+    this.active.forEach((entity) => {
+      callback(entity);
+    });
+  }
+};
+
+// src/entity/Entity.ts
+var createEntityId = (value) => value;
+
+// src/components/ComponentManager.ts
+var ComponentManager = class {
+  constructor() {
+    this.componentsByEntity = /* @__PURE__ */ new Map();
+    this.entitiesByType = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Attach a component instance to an entity. Existing component of the same
+   * type should be replaced or rejected per implementation decision.
+   */
+  addComponent(entity, type, payload) {
+    if (!type.validate(payload)) {
+      throw new Error(`Payload failed validation for component type ${type.id}`);
+    }
+    let components = this.componentsByEntity.get(entity);
+    if (!components) {
+      components = /* @__PURE__ */ new Map();
+      this.componentsByEntity.set(entity, components);
+    }
+    const instance = { type, payload };
+    components.set(type.id, instance);
+    let entities = this.entitiesByType.get(type.id);
+    if (!entities) {
+      entities = /* @__PURE__ */ new Set();
+      this.entitiesByType.set(type.id, entities);
+    }
+    entities.add(entity);
+  }
+  /**
+   * Remove all components for an entity, returning how many were removed.
+   */
+  removeAll(entity) {
+    const components = this.componentsByEntity.get(entity);
+    if (!components) {
+      return 0;
+    }
+    const removedCount = components.size;
+    components.forEach((_, typeId) => {
+      const entities = this.entitiesByType.get(typeId);
+      entities?.delete(entity);
+      if (entities && entities.size === 0) {
+        this.entitiesByType.delete(typeId);
+      }
+    });
+    this.componentsByEntity.delete(entity);
+    return removedCount;
+  }
+  /**
+   * Remove a specific component from an entity.
+   */
+  removeComponent(entity, type) {
+    const components = this.componentsByEntity.get(entity);
+    if (!components?.delete(type.id)) {
+      return false;
+    }
+    if (components.size === 0) {
+      this.componentsByEntity.delete(entity);
+    }
+    const entities = this.entitiesByType.get(type.id);
+    entities?.delete(entity);
+    if (entities && entities.size === 0) {
+      this.entitiesByType.delete(type.id);
+    }
+    return true;
+  }
+  /**
+   * Retrieve a component instance for the entity, if present.
+   */
+  getComponent(entity, type) {
+    const components = this.componentsByEntity.get(entity);
+    return components?.get(type.id);
+  }
+  /**
+   * Retrieve all components for the entity.
+   */
+  getComponents(entity) {
+    const components = this.componentsByEntity.get(entity);
+    return components ? Array.from(components.values()) : [];
+  }
+  /**
+   * Populate the provided array with the component instances for the entity,
+   * returning the number of components discovered. The target array is cleared
+   * before population to support buffer reuse.
+   */
+  collectComponents(entity, target) {
+    target.length = 0;
+    const components = this.componentsByEntity.get(entity);
+    if (!components) {
+      return 0;
+    }
+    let index = 0;
+    components.forEach((instance) => {
+      target[index] = instance;
+      index += 1;
+    });
+    target.length = index;
+    return index;
+  }
+  /**
+   * Retrieve entities that possess a component of the provided type.
+   */
+  getEntitiesWithComponent(type) {
+    const entities = this.entitiesByType.get(type.id);
+    return entities ? Array.from(entities.values()) : [];
+  }
+};
+
+// src/components/TimeComponent.ts
+var TimeComponent = {
+  id: "core.time",
+  description: "Tracks the current simulation tick.",
+  validate(payload) {
+    if (payload == null) {
+      return false;
+    }
+    const { tick } = payload;
+    return Number.isInteger(tick) && tick >= 0;
+  }
+};
+
+// src/systems/SystemManager.ts
+var SystemManager = class {
+  constructor(entityManager, componentManager) {
+    this.systems = [];
+    this.context = {
+      entityManager,
+      componentManager
+    };
+  }
+  /** Register a system at the end of the execution order or specified index. */
+  addSystem(system, index) {
+    const insertionIndex = index === void 0 || index < 0 || index > this.systems.length ? this.systems.length : index;
+    this.systems.splice(insertionIndex, 0, system);
+    system.initialize(this.context);
+  }
+  /** Remove a system and trigger destroy lifecycle hook. */
+  removeSystem(system) {
+    const idx = this.systems.indexOf(system);
+    if (idx === -1) {
+      return false;
+    }
+    this.systems.splice(idx, 1);
+    system.destroy(this.context);
+    return true;
+  }
+  /** Execute one update cycle across all systems in order. */
+  runCycle() {
+    for (const system of this.systems) {
+      system.update(this.context);
+    }
+  }
+  /** Retrieve current ordered list of systems. */
+  getSystems() {
+    return [...this.systems];
+  }
+  /** Expose the context passed into systems (entity/component managers). */
+  getContext() {
+    return this.context;
+  }
+};
+
+// src/systems/System.ts
+var System = class {
+  /** Optional hook invoked once when the system is added to the engine. */
+  initialize(_context) {
+  }
+  /** Optional hook invoked when the system is removed from the engine. */
+  destroy(_context) {
+  }
+};
+
+// src/systems/TimeSystem.ts
+var TimeSystem = class extends System {
+  initialize(context) {
+    if (this.timeEntity !== void 0) {
+      return;
+    }
+    const entity = context.entityManager.create();
+    this.timeEntity = entity;
+    context.componentManager.addComponent(entity, TimeComponent, { tick: 0 });
+  }
+  update(context) {
+    if (this.timeEntity === void 0) {
+      this.initialize(context);
+    }
+    const entity = this.timeEntity;
+    const current = context.componentManager.getComponent(entity, TimeComponent);
+    const nextTick = (current?.payload.tick ?? 0) + 1;
+    context.componentManager.addComponent(entity, TimeComponent, { tick: nextTick });
+  }
+};
+
+// src/Player.ts
+var DEFAULT_CYCLE_INTERVAL_MS = 50;
+var Player = class {
+  constructor(systemManager, cycleIntervalMs = DEFAULT_CYCLE_INTERVAL_MS) {
+    this.tick = 0;
+    this.isRunning = false;
+    this.cycleTimer = null;
+    this.nextSystemId = 1;
+    this.systemsById = /* @__PURE__ */ new Map();
+    this.idsBySystem = /* @__PURE__ */ new Map();
+    this.systemManager = systemManager;
+    this.cycleIntervalMs = cycleIntervalMs;
+  }
+  start() {
+    if (this.isRunning) {
+      return;
+    }
+    this.isRunning = true;
+    this.ensureTimer();
+    this.executeCycle();
+  }
+  pause() {
+    this.isRunning = false;
+  }
+  stop() {
+    this.isRunning = false;
+    this.clearTimer();
+    this.resetEnvironment();
+  }
+  injectSystem(payload) {
+    const systemId = this.generateSystemId();
+    this.systemsById.set(systemId, payload.system);
+    this.idsBySystem.set(payload.system, systemId);
+    this.systemManager.addSystem(payload.system);
+    return systemId;
+  }
+  ejectSystem(payload) {
+    const system = payload.system ?? (payload.systemId ? this.systemsById.get(payload.systemId) ?? null : null);
+    if (!system) {
+      return false;
+    }
+    const removed = this.systemManager.removeSystem(system);
+    if (!removed) {
+      return false;
+    }
+    const resolvedId = payload.systemId ?? this.idsBySystem.get(system);
+    if (resolvedId) {
+      this.systemsById.delete(resolvedId);
+    }
+    this.idsBySystem.delete(system);
+    return true;
+  }
+  getContext() {
+    return this.systemManager.getContext();
+  }
+  executeCycle() {
+    const currentTick = this.tick;
+    this.onBeforeCycle(currentTick);
+    this.systemManager.runCycle();
+    this.onAfterCycle(currentTick, this.getContext());
+    this.tick += 1;
+  }
+  // Intended extension hook for subclasses to prepare state prior to a cycle.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onBeforeCycle(_tick) {
+  }
+  // Intended extension hook for subclasses to inspect the environment after a cycle.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onAfterCycle(_tick, _context) {
+  }
+  ensureTimer() {
+    if (this.cycleTimer) {
+      return;
+    }
+    this.cycleTimer = setInterval(() => {
+      if (!this.isRunning) {
+        this.clearTimer();
+        return;
+      }
+      this.executeCycle();
+    }, this.cycleIntervalMs);
+    if (typeof this.cycleTimer.unref === "function") {
+      this.cycleTimer.unref();
+    }
+  }
+  clearTimer() {
+    if (this.cycleTimer) {
+      clearInterval(this.cycleTimer);
+      this.cycleTimer = null;
+    }
+  }
+  resetEnvironment() {
+    const context = this.getContext();
+    const entities = context.entityManager.list();
+    for (const entity of entities) {
+      context.componentManager.removeAll(entity);
+      context.entityManager.remove(entity);
+    }
+    this.tick = 0;
+    this.cleanupSystemRegistry();
+  }
+  generateSystemId() {
+    const id = `system-${this.nextSystemId}`;
+    this.nextSystemId += 1;
+    return id;
+  }
+  cleanupSystemRegistry() {
+    for (const [id, system] of this.systemsById.entries()) {
+      if (!this.idsBySystem.has(system)) {
+        this.systemsById.delete(id);
+      }
+    }
+    for (const [system, id] of this.idsBySystem.entries()) {
+      if (!this.systemsById.has(id)) {
+        this.idsBySystem.delete(system);
+      }
+    }
+  }
+  describe() {
+    const state = this.isRunning ? "running" : this.tick > 0 ? "paused" : "idle";
+    return {
+      state,
+      tick: this.tick,
+      systemCount: this.systemsById.size
+    };
+  }
+};
+
+// src/messaging/inbound/InboundHandlerRegistry.ts
+var InboundHandlerRegistry = class {
+  constructor(handlers = /* @__PURE__ */ new Map()) {
+    this.handlers = new Map(handlers);
+  }
+  register(type, handler) {
+    this.handlers.set(type, handler);
+  }
+  handle(type, context, payload) {
+    const handler = this.handlers.get(type);
+    if (!handler) {
+      return null;
+    }
+    return handler.handle(context, payload);
+  }
+};
+
+// src/IOPlayer.ts
+var IOPlayer = class extends Player {
+  constructor(systemManager, inbound, outbound, frameFilter, handlers, cycleIntervalMs) {
+    super(systemManager, cycleIntervalMs);
+    this.componentBuffer = [];
+    this.inbound = inbound;
+    this.outbound = outbound;
+    this.frameFilter = frameFilter;
+    this.handlers = handlers ?? new InboundHandlerRegistry();
+    this.unsubscribeInbound = this.inbound.subscribe((message) => this.handleInbound(message));
+  }
+  getInboundHandlers() {
+    return this.handlers;
+  }
+  onAfterCycle(tick, context) {
+    const frame = this.createFrameSnapshot(tick, context);
+    this.publishFrame(frame);
+  }
+  handleInbound(message) {
+    const inboundMessage = message;
+    if (!inboundMessage || typeof inboundMessage.type !== "string") {
+      return;
+    }
+    try {
+      const acknowledgement = this.handlers.handle(inboundMessage.type, this, inboundMessage.payload);
+      if (acknowledgement) {
+        this.outbound.publish(acknowledgement);
+      }
+    } catch (error) {
+      const messageId = extractMessageId(inboundMessage.payload);
+      if (!messageId) {
+        return;
+      }
+      this.outbound.publish({
+        messageId,
+        status: "error",
+        detail: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  publishFrame(frame) {
+    const filtered = this.frameFilter.apply(frame);
+    this.outbound.publish(filtered);
+  }
+  createFrameSnapshot(tick, context) {
+    const snapshot = /* @__PURE__ */ Object.create(null);
+    const entityManager = context.entityManager;
+    const componentManager = context.componentManager;
+    entityManager.forEach((entity) => {
+      snapshot[String(entity)] = this.collectComponents(entity, componentManager);
+    });
+    return {
+      tick,
+      entities: snapshot
+    };
+  }
+  collectComponents(entity, componentManager) {
+    const componentCount = componentManager.collectComponents(entity, this.componentBuffer);
+    if (componentCount === 0) {
+      return /* @__PURE__ */ Object.create(null);
+    }
+    const record = /* @__PURE__ */ Object.create(null);
+    for (let index = 0; index < componentCount; index += 1) {
+      const component = this.componentBuffer[index];
+      record[component.type.id] = component.payload;
+    }
+    return record;
+  }
+};
+function extractMessageId(payload) {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+  const candidate = payload.messageId;
+  return typeof candidate === "string" && candidate ? candidate : null;
+}
+
+// src/messaging/inbound/MessageHandler.ts
+var MessageHandler = class {
+  constructor(operations) {
+    this.operations = operations;
+  }
+  handle(context, payload) {
+    let acknowledgement = null;
+    for (const operation of this.operations) {
+      acknowledgement = operation.execute(context, payload);
+    }
+    if (!acknowledgement) {
+      throw new Error("Inbound operations must return an acknowledgement");
+    }
+    return acknowledgement;
+  }
+};
+
+// src/simplayer/operations/Start.ts
+var Start = class {
+  execute(player, payload) {
+    player.start();
+    return { messageId: payload.messageId, status: "success" };
+  }
+};
+
+// src/simplayer/operations/Pause.ts
+var Pause = class {
+  execute(player, payload) {
+    player.pause();
+    return { messageId: payload.messageId, status: "success" };
+  }
+};
+
+// src/simplayer/operations/Stop.ts
+var Stop = class {
+  execute(player, payload) {
+    player.stop();
+    return { messageId: payload.messageId, status: "success" };
+  }
+};
+
+// src/simplayer/operations/InjectSystem.ts
+var InjectSystem = class {
+  execute(player, payload) {
+    if (!payload?.system) {
+      throw new Error("System payload is required for injection");
+    }
+    const systemId = player.injectSystem({ system: payload.system });
+    return { messageId: payload.messageId, status: "success", systemId };
+  }
+};
+
+// src/simplayer/operations/EjectSystem.ts
+var EjectSystem = class {
+  execute(player, payload) {
+    const removed = player.ejectSystem({ system: payload.system, systemId: payload.systemId });
+    if (!removed) {
+      return {
+        messageId: payload.messageId,
+        status: "error",
+        detail: "System not found"
+      };
+    }
+    return { messageId: payload.messageId, status: "success" };
+  }
+};
+
+// src/simplayer/SimulationPlayer.ts
+var SimulationMessageType = {
+  START: "start",
+  PAUSE: "pause",
+  STOP: "stop",
+  INJECT_SYSTEM: "inject-system",
+  EJECT_SYSTEM: "eject-system"
+};
+var SimulationPlayer = class extends IOPlayer {
+  constructor(systemManager, inbound, outbound, frameFilter, handlers, cycleIntervalMs) {
+    super(systemManager, inbound, outbound, frameFilter, handlers, cycleIntervalMs);
+    this.componentTypes = /* @__PURE__ */ new Map();
+    this.registerDefaultHandlers();
+  }
+  registerComponent(component) {
+    this.componentTypes.set(component.id, component);
+  }
+  removeComponent(componentId) {
+    return this.componentTypes.delete(componentId);
+  }
+  getRegisteredComponents() {
+    return Array.from(this.componentTypes.values());
+  }
+  registerDefaultHandlers() {
+    const registry = this.getInboundHandlers();
+    registry.register(
+      SimulationMessageType.START,
+      new MessageHandler([new Start()])
+    );
+    registry.register(
+      SimulationMessageType.PAUSE,
+      new MessageHandler([new Pause()])
+    );
+    registry.register(
+      SimulationMessageType.STOP,
+      new MessageHandler([new Stop()])
+    );
+    registry.register(
+      SimulationMessageType.INJECT_SYSTEM,
+      new MessageHandler([new InjectSystem()])
+    );
+    registry.register(
+      SimulationMessageType.EJECT_SYSTEM,
+      new MessageHandler([new EjectSystem()])
+    );
+  }
+};
+
+// src/evalplayer/operations/InjectFrame.ts
+var InjectFrame = class {
+  execute(player, payload) {
+    if (typeof player.start === "function") {
+      player.start();
+    }
+    player.injectFrame(payload);
+    return { messageId: payload.messageId, status: "success" };
+  }
+};
+
+// src/evalplayer/EvaluationPlayer.ts
+var EvaluationMessageType = {
+  INJECT_FRAME: "inject-frame"
+};
+var FrameComponent = {
+  id: "evaluation.frame",
+  description: "Stores a raw simulation frame for downstream evaluation systems.",
+  validate(payload) {
+    if (!payload || typeof payload !== "object") {
+      return false;
+    }
+    const { tick, entities } = payload;
+    const entitiesIsRecord = typeof entities === "object" && entities !== null;
+    return Number.isFinite(tick) && tick >= 0 && entitiesIsRecord;
+  }
+};
+var EvaluationPlayer = class extends IOPlayer {
+  constructor(systemManager, inbound, outbound, frameFilter, handlers, cycleIntervalMs) {
+    super(
+      systemManager,
+      inbound,
+      outbound,
+      frameFilter,
+      handlers ?? void 0,
+      cycleIntervalMs
+    );
+    this.frames = [];
+    this.componentTypes = /* @__PURE__ */ new Map();
+    this.frameComponentType = FrameComponent;
+    this.lastFrameTick = null;
+    this.registerDefaultHandlers();
+  }
+  injectFrame(payload) {
+    this.resetIfNewRun(payload.frame.tick);
+    const context = this.getContext();
+    const entity = context.entityManager.create();
+    context.componentManager.addComponent(entity, this.frameComponentType, payload.frame);
+    this.frames.push(payload);
+    this.publishFrame(payload.frame);
+    this.lastFrameTick = payload.frame.tick;
+  }
+  getFrames() {
+    return [...this.frames];
+  }
+  registerComponent(component) {
+    this.componentTypes.set(component.id, component);
+  }
+  removeComponent(componentId) {
+    return this.componentTypes.delete(componentId);
+  }
+  getRegisteredComponents() {
+    return Array.from(this.componentTypes.values());
+  }
+  resetIfNewRun(tick) {
+    if (this.lastFrameTick !== null && Number.isFinite(tick) && tick < this.lastFrameTick) {
+      this.frames.length = 0;
+      this.resetEnvironment();
+      this.lastFrameTick = null;
+    }
+  }
+  registerDefaultHandlers() {
+    const registry = this.getInboundHandlers();
+    registry.register(
+      EvaluationMessageType.INJECT_FRAME,
+      new MessageHandler([new InjectFrame()])
+    );
+  }
+};
+
+// src/messaging/Bus.ts
+var Bus = class {
+  constructor() {
+    this.subscribers = [];
+    this.dispatchDepth = 0;
+  }
+  subscribe(callback) {
+    const subscription = { callback, active: true };
+    this.subscribers.push(subscription);
+    return () => {
+      if (!subscription.active) {
+        return;
+      }
+      subscription.active = false;
+      if (this.dispatchDepth === 0) {
+        this.compact();
+      }
+    };
+  }
+  publish(message) {
+    this.dispatchDepth += 1;
+    const snapshotLength = this.subscribers.length;
+    try {
+      for (let index = 0; index < snapshotLength; index += 1) {
+        const subscription = this.subscribers[index];
+        if (subscription?.active) {
+          subscription.callback(message);
+        }
+      }
+    } finally {
+      this.dispatchDepth -= 1;
+      if (this.dispatchDepth === 0) {
+        this.compact();
+      }
+    }
+  }
+  compact() {
+    let writeIndex = 0;
+    for (let readIndex = 0; readIndex < this.subscribers.length; readIndex += 1) {
+      const subscription = this.subscribers[readIndex];
+      if (subscription?.active) {
+        if (writeIndex !== readIndex) {
+          this.subscribers[writeIndex] = subscription;
+        }
+        writeIndex += 1;
+      }
+    }
+    this.subscribers.length = writeIndex;
+  }
+};
+
+// src/messaging/outbound/FrameFilter.ts
+var FrameFilter = class {
+  constructor(componentBlacklist = []) {
+    this.blacklist = new Set(componentBlacklist);
+  }
+  apply(frame) {
+    if (this.blacklist.size === 0) {
+      return frame;
+    }
+    const entities = /* @__PURE__ */ Object.create(null);
+    for (const [entityId, components] of Object.entries(frame.entities)) {
+      const filtered = /* @__PURE__ */ Object.create(null);
+      for (const [componentId, value] of Object.entries(components)) {
+        if (!this.blacklist.has(componentId)) {
+          filtered[componentId] = value;
+        }
+      }
+      entities[entityId] = filtered;
+    }
+    return {
+      tick: frame.tick,
+      entities
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Bus,
+  ComponentManager,
+  EjectSystem,
+  EntityManager,
+  EvaluationMessageType,
+  EvaluationPlayer,
+  FrameFilter,
+  IOPlayer,
+  InboundHandlerRegistry,
+  InjectFrame,
+  InjectSystem,
+  MessageHandler,
+  Pause,
+  Player,
+  SimulationMessageType,
+  SimulationPlayer,
+  Start,
+  Stop,
+  System,
+  SystemManager,
+  TimeComponent,
+  TimeSystem,
+  createEntityId
+});