@ste_tisci/ecs 0.1.4 → 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.4",
-  "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

@@ -1,64 +1,96 @@
-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 };
-}
+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

@@ -1,94 +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) {
-      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 };
-}
+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 };
+}