@ste_tisci/ecs 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+> [!IMPORTANT]  
+> Work in progress.
+
+# ECS in TypeScript
+
+A minimalistic game engine with zero dependencies based on the **Entity Component System (ECS)** architecture implemented in **TypeScript**
+
+## Features
+
+- **ECS architecture** with single responsability principles (SRP)
+
+- **SparSet** for ultra-fast entities lookup
+
+- **Structure of Arrays(SoA)** for optimized memory storage and access
+
+- **Bitmask** for efficient component queries
+
+## Core Components
+
+- **EntityManager**: Manage creation, destruction and entity recycle. Uses a bitmask to track components of every entity.
+
+- **ComponentStore**: Generic store that maintains components data in SoA format to maximise cache locality.
+
+- **ECS**: Central Orchestator that coordinates entity and components, expose an API for queries and CRUD operations
+
+- **SparseSet**: Data structure that grants O(1) for insertion, removal and lookups of entities.
+
+## Technologies
+
+- TypeScript for type safety
+- Data oriented architecture for optimal performance
+- Functional pattern without classes
+
+## ⚖️ License
+
+MIT © 2025 SteTisci

package/dist/index.cjs

@@ -0,0 +1,247 @@
+"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.cts

@@ -0,0 +1,103 @@
+/**
+ * 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 };

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 };

package/dist/index.js

@@ -0,0 +1,220 @@
+// 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 };
+}
+export {
+  ECS
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ste_tisci/ecs",
+  "version": "0.1.0",
+  "description": "A minimalistic game engine with zero dependencies based on the Entity Component System (ECS) architecture implemented in TypeScript",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SteTisci/ecs"
+  },
+  "type": "module",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}