@ste_tisci/ecs 0.1.4 → 0.1.6

package/src/EntityManager.ts

@@ -1,58 +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 {
-    return bitMasks[eid];
-  }
-
-  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask };
-}
+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

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

package/src/types/IComponentRegistry.d.ts

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

@@ -1,53 +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;
-}
+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/src/types/IEcs.d.ts

@@ -1,63 +1,64 @@
-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
- */
-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;
-
-  /**
-   * 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>;
-}
+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
+ */
+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
+   * @throws Error if a component name is already defined
+   */
+  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;
+
+  /**
+   * 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<C>>;
+
+  components: StoreDataMap<T>;
+}

package/src/types/IEntityManager.d.ts

@@ -1,64 +1,65 @@
-/**
- * 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;
-}
+/**
+ * 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
+   * @throws Error if the entity doesn't exist
+   */
+  getMask: (eid: number) => bigint;
+}

package/src/types/ISparseSet.d.ts

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