@ste_tisci/ecs 0.1.0 → 0.1.2

package/src/types/ISparseSet.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Interface used for fast entity lookups, insertion and removal.
+ *
+ * Maintain two parallel arrays:
+ *
+ * - sparse: a direct lookup table that maps an entity ID (eid) to its index in the dense array.
+ * - dense: a compact array that stores all active entity IDs contiguously.
+ */
+export interface ISparseSet {
+  /**
+   * Check if an entity ID exists in the set
+   * @param eid The entity ID to check
+   * @returns True if the entity ID exists, false otherwise
+   */
+  has: (eid: number) => boolean;
+
+  /**
+   * Add the entity ID to the set
+   * @param eid The entity ID to add
+   * @thows Error if the entity ID is already been added
+   */
+  add: (eid: number) => void;
+
+  /**
+   * Remove an Entity ID from the set
+   * @param eid The entity ID to remove
+   * @throws Error if the ID does not exists in the set
+   */
+  remove: (eid: number) => void;
+
+  /**
+   * Retrive the index of the entity ID in the set
+   * @param eid The entity ID
+   * @returns The index corresponding to an entity ID in the set
+   */
+  getIndex: (eid: number) => number;
+
+  /**
+   * Retrive the full dense array that contain all the entity IDs of the set
+   * @returns an Array with all the current entity IDs
+   */
+  getDense: () => number[];
+
+  /**
+   * Retrive the size representing the number of active entities in the set.
+   * @returns The current size of the Dense array
+   */
+  getSize: () => number;
+}

package/src/types/index.d.ts

@@ -0,0 +1,42 @@
+import type { IComponentStore } from './IComponentStore.js';
+
+/**
+ * Represents component data in Structure of Arrays (SoA) format.
+ * Each property of the component is stored in a separate array,
+ * enabling cache-efficient iteration and SIMD operations.
+ * @template T - The component data type
+ * @example
+ * // For Position component: { x: number, y: number }
+ * // ComponentDataArrays would be: { x: number[], y: number[] }
+ */
+export type ComponentDataArrays<T> = {
+  [K in keyof T]: T[K][];
+};
+
+/**
+ * Maps component names to their corresponding ComponentStore instances.
+ * Used internally by CreateWorld to manage all component stores.
+ * @template T - Record type defining all component types
+ */
+export type StoreMap<T> = {
+  [K in keyof T]: IComponentStore<T[K]>;
+};
+
+/**
+ * Maps component names to their data arrays for direct access.
+ * Used to expose component data to the user without store methods.
+ * @template T - Record type defining all component types
+ */
+export type StoreDataMap<T> = {
+  [K in keyof T]: ComponentDataArrays<T[K]>;
+};
+
+/**
+ * Type helper for the query result.
+ * Creates an object with eid and all required components typed correctly.
+ * @template T - Record type with all component types.
+ * @template C - Array of the component names requested in the query.
+ */
+export type QueryResult<T, C extends (keyof T)[]> = {
+  [K in C[number]]: { id: number };
+};

package/src/utils/ComponentRegistry.ts

@@ -0,0 +1,32 @@
+import type { IComponentRegistry } from '../types/IComponentRegistry.js';
+
+export function createComponentRegistry<K extends string>(): IComponentRegistry<K> {
+  const nameToID = new Map<K, number>();
+  const IDtoName = new Map<number, K>();
+  let nextID: number = 0;
+
+  function register(name: K): void {
+    if (!nameToID.has(name)) {
+      const eid = nextID++;
+
+      nameToID.set(name, eid);
+      IDtoName.set(eid, name);
+    }
+  }
+
+  function getID(name: K): number {
+    const eid = nameToID.get(name);
+    if (eid === undefined) throw new Error(`Component ${name} not registered`);
+
+    return eid;
+  }
+
+  function getName(cid: number): K {
+    const name = IDtoName.get(cid);
+    if (!name) throw new Error(`Component ID ${cid} not registered`);
+
+    return name;
+  }
+
+  return { register, getID, getName };
+}

package/src/utils/SparseSet.ts

@@ -0,0 +1,54 @@
+import type { ISparseSet } from '../types/ISparseSet.js';
+
+export function SparseSet(): ISparseSet {
+  const sparse: number[] = [];
+  const dense: number[] = [];
+  let size = 0;
+
+  function has(eid: number): boolean {
+    const ID = getIndex(eid);
+
+    const exist = ID !== undefined && dense[ID] === eid;
+    const isWhitinBounds = ID >= 0 && ID < size;
+
+    return exist && isWhitinBounds;
+  }
+
+  function add(eid: number): void {
+    if (has(eid)) throw new Error(`ID ${eid} already present in the set`);
+
+    sparse[eid] = size;
+    dense[size] = eid;
+    size++;
+  }
+
+  function remove(eid: number): void {
+    if (!has(eid)) throw new Error(`Cannot remove ID ${eid} because does not exists`);
+
+    const ID = getIndex(eid);
+    const last = dense[size - 1];
+
+    // Swap with the last element inserted
+    dense[ID] = last;
+    sparse[last] = ID;
+
+    // Remove the element
+    dense.pop();
+    size--;
+    delete sparse[eid];
+  }
+
+  function getIndex(eid: number): number {
+    return sparse[eid];
+  }
+
+  function getDense(): number[] {
+    return dense;
+  }
+
+  function getSize(): number {
+    return size;
+  }
+
+  return { has, add, remove, getIndex, getDense, getSize };
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "moduleResolution": "nodenext",
+    "module": "node20"
+  },
+  "exclude": ["node_modules/"],
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  format: ['cjs', 'esm'],
+  entry: ['./src/index.ts'],
+  dts: true,
+  shims: true,
+  skipNodeModulesBundle: true,
+  clean: true,
+});

package/dist/index.cjs

@@ -1,247 +0,0 @@
-"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, {
-  ECS: () => ECS
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/utils/SparseSet.ts
-function SparseSet() {
-  const sparse = [];
-  const dense = [];
-  let size = 0;
-  function has(eid) {
-    const ID = getIndex(eid);
-    const exist = ID !== void 0 && dense[ID] === eid;
-    const isWhitinBounds = ID >= 0 && ID < size;
-    return exist && isWhitinBounds;
-  }
-  function add(eid) {
-    if (has(eid)) throw new Error(`ID ${eid} already present in the set`);
-    sparse[eid] = size;
-    dense[size] = eid;
-    size++;
-  }
-  function remove(eid) {
-    if (!has(eid)) throw new Error(`Cannot remove ID ${eid} because does not exists`);
-    const ID = getIndex(eid);
-    const last = dense[size - 1];
-    dense[ID] = last;
-    sparse[last] = ID;
-    dense.pop();
-    size--;
-    delete sparse[eid];
-  }
-  function getIndex(eid) {
-    return sparse[eid];
-  }
-  function getDense() {
-    return dense;
-  }
-  function getSize() {
-    return size;
-  }
-  return { has, add, remove, getIndex, getDense, getSize };
-}
-
-// src/ComponentStore.ts
-function ComponentStore() {
-  const componentSet = SparseSet();
-  const componentData = {};
-  function add(eid, data) {
-    if (componentSet.has(eid)) throw new Error(`Entity ${eid} already has this component`);
-    const ID = componentSet.getSize();
-    componentSet.add(eid);
-    for (const key in data) {
-      if (!componentData[key]) {
-        componentData[key] = [];
-      }
-      componentData[key][ID] = data[key];
-    }
-  }
-  function remove(eid) {
-    if (!componentSet.has(eid)) throw new Error(`Entity ${eid} does not have this component`);
-    const ID = componentSet.getIndex(eid);
-    const lastID = componentSet.getSize() - 1;
-    if (ID !== lastID) {
-      for (const key of Object.keys(componentData)) {
-        componentData[key][ID] = componentData[key][lastID];
-      }
-    }
-    componentSet.remove(eid);
-    for (const key in componentData) {
-      componentData[key].pop();
-    }
-  }
-  function getDense() {
-    return componentSet.getDense();
-  }
-  function getData() {
-    return componentData;
-  }
-  function getIndex(eid) {
-    return componentSet.getIndex(eid);
-  }
-  function getSize() {
-    return componentSet.getSize();
-  }
-  return { add, remove, getIndex, getDense, getData, getSize };
-}
-
-// src/EntityManager.ts
-function EntityManager(registry) {
-  let nextID = 0;
-  const recycledIDs = [];
-  const bitMasks = [];
-  function exists(eid) {
-    const isWithinBounds = eid >= 0 && eid < nextID;
-    const hasMask = bitMasks[eid] !== void 0;
-    return isWithinBounds && hasMask;
-  }
-  function hasComponent(eid, name) {
-    if (!exists(eid)) throw new Error(`Entity ${eid} does not exist`);
-    const cid = registry.getID(name);
-    return (bitMasks[eid] & 1n << BigInt(cid)) !== 0n;
-  }
-  function create() {
-    const ID = recycledIDs.length > 0 ? recycledIDs.pop() : nextID++;
-    bitMasks[ID] = 0n;
-    return ID;
-  }
-  function remove(eid) {
-    if (!exists(eid)) throw new Error(`Entity ${eid} does not exist`);
-    bitMasks[eid] = void 0;
-    recycledIDs.push(eid);
-  }
-  function addComponent(eid, name) {
-    if (!exists(eid)) throw new Error(`Entity ${eid} does not exists`);
-    if (hasComponent(eid, name)) throw new Error(`Entity ${eid} already has component ${name}`);
-    const cid = registry.getID(name);
-    bitMasks[eid] |= 1n << BigInt(cid);
-  }
-  function removeComponent(eid, name) {
-    if (!exists(eid)) throw new Error(`Entity ${eid} does not exists`);
-    if (!hasComponent(eid, name)) throw new Error(`Entity ${eid} does not have component ${name}`);
-    const cid = registry.getID(name);
-    bitMasks[eid] &= ~(1n << BigInt(cid));
-  }
-  function getMask(eid) {
-    return bitMasks[eid];
-  }
-  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask };
-}
-
-// src/utils/ComponentRegistry.ts
-function createComponentRegistry() {
-  const nameToID = /* @__PURE__ */ new Map();
-  const IDtoName = /* @__PURE__ */ new Map();
-  let nextID = 0;
-  function register(name) {
-    if (!nameToID.has(name)) {
-      const eid = nextID++;
-      nameToID.set(name, eid);
-      IDtoName.set(eid, name);
-    }
-  }
-  function getID(name) {
-    const eid = nameToID.get(name);
-    if (eid === void 0) throw new Error(`Component ${name} not registered`);
-    return eid;
-  }
-  function getName(cid) {
-    const name = IDtoName.get(cid);
-    if (!name) throw new Error(`Component ID ${cid} not registered`);
-    return name;
-  }
-  return { register, getID, getName };
-}
-
-// src/Ecs.ts
-function ECS() {
-  const ComponentRegistry = createComponentRegistry();
-  const Entities = EntityManager(ComponentRegistry);
-  const internalStores = {};
-  const components = {};
-  function defineComponents(data) {
-    for (const key in data) {
-      ComponentRegistry.register(key);
-      internalStores[key] = ComponentStore();
-      components[key] = internalStores[key].getData();
-    }
-  }
-  function createEntity() {
-    return Entities.create();
-  }
-  function destroyEntity(eid) {
-    const entityMask = Entities.getMask(eid);
-    let cid = 0;
-    let tempMask = entityMask;
-    while (tempMask !== 0n) {
-      if ((tempMask & 1n) !== 0n) {
-        const name = ComponentRegistry.getName(cid);
-        internalStores[name].remove(eid);
-      }
-      tempMask >>= 1n;
-      cid++;
-    }
-    Entities.remove(eid);
-  }
-  function addComponent(eid, name, data) {
-    Entities.addComponent(eid, name);
-    internalStores[name].add(eid, data);
-  }
-  function removeComponent(eid, name) {
-    Entities.removeComponent(eid, name);
-    internalStores[name].remove(eid);
-  }
-  function* query(...componentName) {
-    if (componentName.length === 0) return;
-    let smallestStore = internalStores[componentName[0]];
-    let smallestSize = smallestStore.getSize();
-    for (let i = 1; i < componentName.length; i++) {
-      const store = internalStores[componentName[i]];
-      const size = store.getSize();
-      if (size < smallestSize) {
-        smallestStore = store;
-        smallestSize = size;
-      }
-    }
-    let targetMask = 0n;
-    for (const name of componentName) {
-      targetMask |= 1n << BigInt(ComponentRegistry.getID(name));
-    }
-    for (const eid of smallestStore.getDense()) {
-      if ((Entities.getMask(eid) & targetMask) !== targetMask) continue;
-      const result = {};
-      for (const name of componentName) {
-        const id = internalStores[name].getIndex(eid);
-        result[name] = { id };
-      }
-      yield result;
-    }
-  }
-  return { defineComponents, createEntity, destroyEntity, addComponent, removeComponent, query, components };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ECS
-});

package/dist/index.d.ts

@@ -1,103 +0,0 @@
-/**
- * Represents component data in Structure of Arrays (SoA) format.
- * Each property of the component is stored in a separate array,
- * enabling cache-efficient iteration and SIMD operations.
- * @template T - The component data type
- * @example
- * // For Position component: { x: number, y: number }
- * // ComponentDataArrays would be: { x: number[], y: number[] }
- */
-type ComponentDataArrays<T> = {
-  [K in keyof T]: T[K][];
-};
-
-/**
- * Maps component names to their data arrays for direct access.
- * Used to expose component data to the user without store methods.
- * @template T - Record type defining all component types
- */
-type StoreDataMap<T> = {
-  [K in keyof T]: ComponentDataArrays<T[K]>;
-};
-
-/**
- * Type helper for the query result.
- * Creates an object with eid and all required components typed correctly.
- * @template T - Record type with all component types.
- * @template C - Array of the component names requested in the query.
- */
-type QueryResult<T, C extends (keyof T)[]> = {
-  [K in C[number]]: { id: number };
-};
-
-type StoreInit<T> = {
-  [K in keyof T]: {
-    [P in keyof T[K]]: T[K][P][];
-  };
-};
-
-/**
- * Interface for the main ECS registry.
- * Provides high-level API for entity-component management,
- * coordinating between EntityManager and ComponentStores.
- * @template T - Record type defining all component types in the ECS
- */
-interface IECS<T> {
-  /**
-   * Initializes the ECS with component definitions.
-   * Registers all components and creates their corresponding stores.
-   * Must be called before any other operations.
-   * @param components - Object mapping component names to their structure
-   */
-  defineComponents: (data: StoreInit<T>) => void;
-
-  /**
-   * Creates a new entity in the ECS.
-   * @returns The ID of the newly created entity
-   */
-  createEntity: () => number;
-
-  /**
-   * Completely removes an entity and all its components from the ECS.
-   * Cleans up all component data and entity records.
-   * @param eid - The entity ID to destroy
-   */
-  destroyEntity: (eid: number) => void;
-
-  /**
-   * Adds a component to an entity with the provided data.
-   * Updates both the entity's bitmask and the component store.
-   * @template K - The component name type (key of T)
-   * @param eid - The entity ID
-   * @param name - The component name
-   * @param data - The component data to store
-   */
-  addComponent: <K extends keyof T>(eid: number, name: K, data: T[K]) => void;
-
-  /**
-   * Removes a component from an entity.
-   * Updates both the entity's bitmask and the component store.
-   * @template K - The component name type (key of T)
-   * @param eid - The entity ID
-   * @param name - The component name
-   */
-  removeComponent: <K extends keyof T>(eid: number, name: K) => void;
-
-  /**
-   * Retrieves all entities that contain the specified set of components.
-   * Performs a filtered search across component stores and yields each matching entity.
-   * The returned generator allows efficient iteration without allocating large arrays.
-   *
-   * @template C - Array of component names to query for
-   * @param components - List of component names that the entity must include
-   * @returns A generator that yields an object for each matching entity,
-   *          containing the entity ID and the related component data
-   */
-  query: <C extends (keyof T)[]>(...componentName: C) => Generator<QueryResult<T, C>>;
-
-  components: StoreDataMap<T>;
-}
-
-declare function ECS<T extends Record<string, Record<string, any>>>(): IECS<T>;
-
-export { ECS };