@ste_tisci/ecs 0.1.5 → 0.1.6

package/.prettierrc

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

package/README.md

@@ -1,84 +1,89 @@
-> [!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
+> [!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 — numeric fields are backed by `Float32Array`, non-numeric fields by plain arrays
+
+- **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 component data in SoA format to maximise cache locality — numeric fields in a growable `Float32Array`, non-numeric fields (e.g. `HTMLImageElement`) in a plain array.
+
+- **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 to SoA storage.
+// Numeric fields become Float32Array, everything else stays a plain array.
+// Position = { x: Float32Array, y: Float32Array }
+// Sprite   = { src: HTMLImageElement[] }
+// etc.
+World.defineComponents('Position', 'Velocity', 'Size', '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();
+```
+
+## Error Handling
+
+Every operation validates its inputs and throws a descriptive `Error` instead of failing silently or corrupting state:
+
+- `addComponent` / `removeComponent` / `destroyEntity` throw if the entity does not exist
+- `addComponent` throws if the entity already has the component; `removeComponent` throws if it doesn't
+- `query`, `addComponent` and `removeComponent` throw if the component name was never registered via `defineComponents`
+- `defineComponents` throws if a component name is already defined
+
+## ⚖️ License
+
+MIT © 2025 SteTisci

package/package.json

@@ -1,23 +1,23 @@
-{
-  "name": "@ste_tisci/ecs",
-  "version": "0.1.5",
-  "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"
-  }
-}
+{
+  "name": "@ste_tisci/ecs",
+  "version": "0.1.6",
+  "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"
+  }
+}

package/src/ComponentStore.ts

@@ -0,0 +1,96 @@
+import type { IComponentStore } from './types/IComponentStore.js';
+import type { ComponentDataArrays } from './types/index.js';
+import { SparseSet } from './utils/SparseSet.js';
+
+const INITIAL_CAPACITY = 8;
+
+// Float32Array has a fixed length, so numeric fields grow by doubling capacity
+// (like a dynamic array reallocation) instead of relying on push/pop.
+function grow(buffer: Float32Array, requiredIndex: number): Float32Array {
+  let capacity = buffer.length;
+  while (capacity <= requiredIndex) capacity *= 2;
+
+  const grown = new Float32Array(capacity);
+  grown.set(buffer);
+  return grown;
+}
+
+// Internally every field is either a Float32Array (numeric) or a plain array (anything else).
+// The precise, per-field ComponentDataArrays<T> type is only applied at the public getData() boundary.
+type FieldStore = Float32Array | unknown[];
+
+export function ComponentStore<T extends Record<string, any>>(): IComponentStore<T> {
+  const componentSet = SparseSet();
+  const componentData: Record<string, FieldStore> = {};
+
+  // Tracks which fields are numeric (Float32Array-backed) vs plain arrays, keyed by field name
+  const isNumeric: Record<string, boolean> = {};
+
+  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) {
+      const value = data[key];
+
+      if (!(key in componentData)) {
+        isNumeric[key] = typeof value === 'number';
+        componentData[key] = isNumeric[key] ? new Float32Array(INITIAL_CAPACITY) : [];
+      }
+
+      if (isNumeric[key] && ID >= componentData[key].length) {
+        componentData[key] = grow(componentData[key] as Float32Array, ID);
+      }
+
+      (componentData[key] as unknown[])[ID] = value;
+    }
+  }
+
+  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] as unknown[])[ID] = componentData[key][lastID];
+      }
+    }
+
+    componentSet.remove(eid);
+
+    // Plain arrays are trimmed to release references and stay in sync with the dense array.
+    // Float32Array slots beyond the current size are simply unused (unreachable via query/getIndex),
+    // so there's nothing to release and the capacity is kept as-is.
+    for (const key in componentData) {
+      if (!isNumeric[key]) {
+        (componentData[key] as unknown[]).pop();
+      }
+    }
+  }
+
+  function getDense(): number[] {
+    return componentSet.getDense();
+  }
+
+  function getData(): ComponentDataArrays<T> {
+    return componentData as ComponentDataArrays<T>;
+  }
+
+  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,98 @@
+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) {
+      if (name in internalStores) throw new Error(`Component ${String(name)} is already defined`);
+
+      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<C>> {
+    if (componentName.length === 0) return;
+
+    // Validate that every requested component is registered before touching internalStores,
+    // so an unknown name throws a clear error instead of a raw "undefined" access below.
+    let targetMask = 0n;
+    for (const name of componentName) {
+      targetMask |= 1n << BigInt(ComponentRegistry.getID(name as keyof T & string));
+    }
+
+    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;
+      }
+    }
+
+    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<C>;
+    }
+  }
+
+  return { defineComponents, createEntity, destroyEntity, addComponent, removeComponent, query, components };
+}

package/src/EntityManager.ts

@@ -0,0 +1,60 @@
+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 {
+    if (!exists(eid)) throw new Error(`Entity ${eid} does not exist`);
+
+    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;
+}