@ste_tisci/ecs 0.1.1 → 0.1.3

package/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "singleQuote": true,
+  "printWidth": 150,
+  "proseWrap": "always",
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "singleAttributePerLine": false,
+  "semi": true
+}

package/README.md

@@ -1,36 +1,84 @@
-> [!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
+> [!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
+
+```typescript
+import { ECS } from '@ste_tisci/ecs';
+
+// Define the type of the components
+const World = ECS<{
+  Position: { x: number; y: number };
+  Velocity: { x: number; y: number };
+  Size: { width: number; height: number };
+  Sprite: { src: HTMLImageElement };
+}>();
+
+// Define the structure of components that will be converted in SoA Arrays with the types previously defined
+// Position = { x: number[], y: number[] }
+// Size = { src: HTMLImageElement[] }
+// etc.
+World.defineComponents({
+  Position: {},
+  Size: {},
+  Velocity: {},
+  Sprite: {},
+});
+
+const ent = World.createEntity();
+
+World.addComponent(ent, 'Position', { x: 100, y: 20 });
+World.addComponent(ent, 'Velocity', { x: 2, y: 1 });
+World.addComponent(ent, 'Size', { width: 20, height: 20 });
+
+function movementSystem(World) {
+  const { Position, Velocity } = World.components;
+
+  for (const entity of World.query('Position', 'Velocity')) {
+    const posID = entity.Position.id;
+    const velID = entity.Velocity.id;
+
+    Position.x[posID] += Velocity.x[velID];
+    Position.y[posID] += Velocity.y[velID];
+  }
+}
+
+function gameLoop() {
+  movementSystem(World);
+  requestAnimationFrame(gameLoop);
+}
+
+gameLoop();
+```
+
+## ⚖️ License
+
+MIT © 2025 SteTisci

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ste_tisci/ecs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",

package/src/ComponentStore.ts

@@ -0,0 +1,64 @@
+import type { IComponentStore } from './types/IComponentStore.js';
+import type { ComponentDataArrays } from './types/index.js';
+import { SparseSet } from './utils/SparseSet.js';
+
+export function ComponentStore<T extends Record<string, any>>(): IComponentStore<T> {
+  const componentSet = SparseSet();
+  const componentData = {} as ComponentDataArrays<T>;
+
+  function add(eid: number, data: T): void {
+    if (componentSet.has(eid)) throw new Error(`Entity ${eid} already has this component`);
+
+    // Use the current size (next index) to maintain data coherence with the dense array
+    const ID = componentSet.getSize();
+
+    componentSet.add(eid);
+
+    // Store each property of the component into its corresponding array
+    for (const key in data) {
+      if (!componentData[key]) {
+        componentData[key] = [] as T[typeof key][];
+      }
+      componentData[key][ID] = data[key];
+    }
+  }
+
+  function remove(eid: number): void {
+    if (!componentSet.has(eid)) throw new Error(`Entity ${eid} does not have this component`);
+
+    const ID = componentSet.getIndex(eid);
+    const lastID = componentSet.getSize() - 1;
+
+    // Swap the component data only if is not the last one inserted
+    if (ID !== lastID) {
+      for (const key of Object.keys(componentData)) {
+        componentData[key][ID] = componentData[key][lastID];
+      }
+    }
+
+    componentSet.remove(eid);
+
+    // Keep component arrays dense and in sync with the SparseSet's dense array
+    for (const key in componentData) {
+      componentData[key].pop();
+    }
+  }
+
+  function getDense(): number[] {
+    return componentSet.getDense();
+  }
+
+  function getData(): ComponentDataArrays<T> {
+    return componentData;
+  }
+
+  function getIndex(eid: number): number {
+    return componentSet.getIndex(eid);
+  }
+
+  function getSize(): number {
+    return componentSet.getSize();
+  }
+
+  return { add, remove, getIndex, getDense, getData, getSize };
+}

package/src/Ecs.ts

@@ -0,0 +1,94 @@
+import type { QueryResult, StoreDataMap, StoreMap } from './types/index.js';
+import type { IECS } from './types/IEcs.js';
+import { ComponentStore } from './ComponentStore.js';
+import { EntityManager } from './EntityManager.js';
+import { createComponentRegistry } from './utils/ComponentRegistry.js';
+
+export function ECS<T extends Record<string, Record<string, any>>>(): IECS<T> {
+  const ComponentRegistry = createComponentRegistry<keyof T & string>();
+  const Entities = EntityManager(ComponentRegistry);
+  const internalStores = {} as StoreMap<T>;
+  const components = {} as StoreDataMap<T>;
+
+  // Initialize the structure of the components used
+  function defineComponents<K extends readonly (keyof T)[]>(...names: K): void {
+    for (const name of names) {
+      ComponentRegistry.register(name as string);
+      internalStores[name] = ComponentStore<T[typeof name]>();
+      components[name] = internalStores[name].getData();
+    }
+  }
+
+  function createEntity(): number {
+    return Entities.create();
+  }
+
+  function destroyEntity(eid: number): void {
+    const entityMask = Entities.getMask(eid);
+
+    let cid = 0;
+    let tempMask = entityMask;
+
+    // Bit operation on the entity mask to track the corresponding components and remove them
+    while (tempMask !== 0n) {
+      if ((tempMask & 1n) !== 0n) {
+        const name = ComponentRegistry.getName(cid);
+        internalStores[name].remove(eid);
+      }
+
+      tempMask >>= 1n;
+      cid++;
+    }
+
+    Entities.remove(eid);
+  }
+
+  function addComponent<K extends keyof T>(eid: number, name: K, data: T[K]): void {
+    Entities.addComponent(eid, name as keyof T & string);
+    internalStores[name].add(eid, data);
+  }
+
+  function removeComponent<K extends keyof T>(eid: number, name: K): void {
+    Entities.removeComponent(eid, name as keyof T & string);
+    internalStores[name].remove(eid);
+  }
+
+  // Generator function to retrive the indexes of the entity components searched
+  function* query<C extends (keyof T)[]>(...componentName: C): Generator<QueryResult<T, C>> {
+    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 as keyof T & string));
+    }
+
+    for (const eid of smallestStore.getDense()) {
+      if ((Entities.getMask(eid) & targetMask) !== targetMask) continue;
+
+      const result = {} as any;
+
+      for (const name of componentName) {
+        const id = internalStores[name].getIndex(eid);
+
+        result[name] = { id };
+      }
+
+      yield result as QueryResult<T, C>;
+    }
+  }
+
+  return { defineComponents, createEntity, destroyEntity, addComponent, removeComponent, query, components };
+}

package/src/EntityManager.ts

@@ -0,0 +1,58 @@
+import type { IComponentRegistry } from './types/IComponentRegistry.js';
+import type { IEntityManager } from './types/IEntityManager.js';
+
+export function EntityManager<K extends string>(registry: IComponentRegistry<K>): IEntityManager<K> {
+  let nextID: number = 0;
+  const recycledIDs: number[] = [];
+  const bitMasks: bigint[] = [];
+
+  function exists(eid: number): boolean {
+    const isWithinBounds = eid >= 0 && eid < nextID;
+    const hasMask = bitMasks[eid] !== undefined;
+
+    return isWithinBounds && hasMask;
+  }
+
+  function hasComponent(eid: number, name: K): boolean {
+    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(): number {
+    const ID = recycledIDs.length > 0 ? recycledIDs.pop()! : nextID++;
+    bitMasks[ID] = 0n;
+
+    return ID;
+  }
+
+  function remove(eid: number): void {
+    if (!exists(eid)) throw new Error(`Entity ${eid} does not exist`);
+
+    bitMasks[eid] = undefined as any;
+    recycledIDs.push(eid);
+  }
+
+  function addComponent(eid: number, name: K): void {
+    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: number, name: K): void {
+    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: number): bigint {
+    return bitMasks[eid];
+  }
+
+  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask };
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { ECS } from './Ecs.js';

package/src/types/IComponentRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Interface for managing component registration and ID mapping.
+ * Provides a centralized registry that maps component names to unique IDs
+ * and vice versa, used for efficient bitmask operations in the ECS.
+ */
+export interface IComponentRegistry<K extends string> {
+  /**
+   * Registers a new component by name.
+   * Assigns a unique incremental ID to the component if not already registered.
+   * @param name - The name of the component to register
+   */
+  register: (name: K) => void;
+
+  /**
+   * Retrieves the unique ID associated with a component name.
+   * @param name - The name of the component
+   * @returns The unique ID assigned to the component
+   * @throws Error if the component is not registered
+   */
+  getID: (name: K) => number;
+
+  /**
+   * Retrieves the component name associated with a given ID.
+   * @param cid - The unique ID of the component
+   * @returns The name of the component
+   * @throws Error if the ID is not registered
+   */
+  getName: (cid: number) => K;
+}

package/src/types/IComponentStore.d.ts

@@ -0,0 +1,53 @@
+import type { ComponentDataArrays } from './index.js';
+
+/**
+ * Interface for storing and managing component data using Structure of Arrays (SoA) pattern.
+ * Each component type has its own store that maintains entity-component associations
+ * and stores component data in separate arrays per property for cache efficiency.
+ * @template T - The component data type (object with properties)
+ */
+export interface IComponentStore<T> {
+  /**
+   * Adds a component to an entity with the provided data.
+   * Stores each property of the component in separate arrays for efficient iteration.
+   * @param eid - The entity ID to add the component to
+   * @param data - The component data to store
+   * @throws Error if the entity already has this component
+   */
+  add: (eid: number, data: T) => void;
+
+  /**
+   * Removes a component from an entity.
+   * Uses swap-and-pop technique to maintain dense arrays.
+   * @param eid - The entity ID to remove the component from
+   * @throws Error if the entity doesn't have this component
+   */
+  remove: (eid: number) => void;
+
+  /**
+   * Gets the index of an entity's component data in the dense arrays.
+   * @param eid - The entity ID
+   * @returns The index in the data arrays where this entity's component data is stored
+   */
+  getIndex: (eid: number) => number;
+
+  /**
+   * Returns the dense array of entity IDs that have this component.
+   * Useful for efficient iteration over all entities with this component.
+   * @returns Array of entity IDs
+   */
+  getDense: () => number[];
+
+  /**
+   * Returns the component data arrays organized by property.
+   * Each property of the component type has its own array.
+   * @returns Object mapping property names to their value arrays
+   */
+  getData: () => ComponentDataArrays<T>;
+
+  /**
+   * Returns the number of entities that have this component.
+   * @returns The count of entities with this component
+   */
+  getSize: () => number;
+}

package/{dist/index.d.cts → src/types/IEcs.d.ts}

@@ -1,97 +1,63 @@
-/**
- * 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 };
-};
+import type { QueryResult, StoreDataMap } from './index.js';
 
-/**
- * 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: Partial<Record<keyof T, any>>) => 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>;
-}
+/**
+ * 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
+ */
+export 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 names -component names
+   */
+  defineComponents<K extends readonly (keyof T)[]>(...names: K): 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;
 
-declare function ECS<T extends Record<string, Record<string, any>>>(): IECS<T>;
+  /**
+   * 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;
 
-export { ECS };
+  /**
+   * 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>;
+}

package/src/types/IEntityManager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Interface for managing entities and their component associations.
+ * Uses bitmasks to efficiently track which components each entity has,
+ * enabling fast component checks and queries.
+ */
+export interface IEntityManager<K extends string> {
+  /**
+   * Checks if an entity exists in the system.
+   * @param eid - The entity ID to check
+   * @returns True if the entity exists, false otherwise
+   */
+  exists: (eid: number) => boolean;
+
+  /**
+   * Checks if an entity has a specific component.
+   * Uses bitwise operations on the entity's bitmask for fast lookups.
+   * @param eid - The entity ID
+   * @param name - The component name
+   * @returns True if the entity has the component, false otherwise
+   */
+  hasComponent: (eid: number, name: K) => boolean;
+
+  /**
+   * Creates a new entity.
+   * Recycles entity IDs when possible, otherwise assigns a new incremental ID.
+   * @returns The ID of the newly created entity
+   */
+  create: () => number;
+
+  /**
+   * Removes an entity from the system.
+   * Marks the entity ID for recycling.
+   * @param eid - The entity ID to remove
+   * @throws Error if the entity doesn't exist
+   */
+  remove: (eid: number) => void;
+
+  /**
+   * Adds a component flag to an entity's bitmask.
+   * Updates the entity's bitmask to indicate it has the specified component.
+   * @param eid - The entity ID
+   * @param name - The component name
+   * @throws Error if the entity doesn't exist or already has the component
+   */
+  addComponent: (eid: number, name: K) => void;
+
+  /**
+   * Removes a component flag from an entity's bitmask.
+   * Updates the entity's bitmask to indicate it no longer has the specified component.
+   * @param eid - The entity ID
+   * @param name - The component name
+   * @throws Error if the entity doesn't exist
+   */
+  removeComponent: (eid: number, name: K) => void;
+
+  /**
+   * Retrieves the complete bitmask for an entity.
+   * The bitmask represents all components the entity has,
+   * with each bit corresponding to a component ID.
+   * @param eid - The entity ID
+   * @returns The entity's component bitmask
+   */
+  getMask: (eid: number) => bigint;
+}