@ste_tisci/ecs 0.1.7 → 0.1.8

package/README.md

@@ -75,6 +75,39 @@ function gameLoop() {
 gameLoop();
 ```
 
+## Hot systems: `queryIds`
+
+`query` yields one result object plus one `{ id }` object per component per entity, which is
+convenient but allocates on every iteration. For systems that run every frame over many
+entities, `queryIds` returns the matching entity IDs instead, and `indices` translates an
+entity ID into its slot in the SoA arrays:
+
+```typescript
+function movementSystem(World) {
+  const { Position, Velocity } = World.components;
+  const pos = World.indices.Position;
+  const vel = World.indices.Velocity;
+
+  for (const eid of World.queryIds('Position', 'Velocity')) {
+    Position.x[pos[eid]] += Velocity.x[vel[eid]];
+    Position.y[pos[eid]] += Velocity.y[vel[eid]];
+  }
+}
+```
+
+Both APIs return the same entities; `queryIds` is roughly 3x faster on a packed query and 5x
+on a fragmented one, at the cost of resolving indices yourself.
+
+## Iteration and mutation
+
+`query` iterates a snapshot taken when the generator starts, so calling `removeComponent` or
+`destroyEntity` from inside the loop cannot skip an entity. Entities created mid-iteration are
+not visited by the query in flight; the next call picks them up.
+
+`queryIds` builds its whole result before returning, so the same guarantee holds. Note that
+destroying an entity invalidates its entry in `indices`, so if a loop destroys entities it
+must not read their storage index afterwards.
+
 ## Error Handling
 
 Every operation validates its inputs and throws a descriptive `Error` instead of failing silently or corrupting state:

package/dist/index.cjs

@@ -60,13 +60,16 @@ function SparseSet() {
   function getSize() {
     return size;
   }
-  return { has, add, remove, getIndex, getDense, getSize };
+  function getSparse() {
+    return sparse;
+  }
+  return { has, add, remove, getIndex, getDense, getSize, getSparse };
 }
 
 // src/ComponentStore.ts
 var INITIAL_CAPACITY = 8;
 function grow(buffer, requiredIndex) {
-  let capacity = buffer.length;
+  let capacity = buffer.length || INITIAL_CAPACITY;
   while (capacity <= requiredIndex) capacity *= 2;
   const grown = new Float32Array(capacity);
   grown.set(buffer);
@@ -74,8 +77,8 @@ function grow(buffer, requiredIndex) {
 }
 function ComponentStore() {
   const componentSet = SparseSet();
-  const componentData = {};
-  const isNumeric = {};
+  const componentData = /* @__PURE__ */ Object.create(null);
+  const isNumeric = /* @__PURE__ */ Object.create(null);
   function add(eid, data) {
     if (componentSet.has(eid)) throw new Error(`Entity ${eid} already has this component`);
     const ID = componentSet.getSize();
@@ -120,7 +123,10 @@ function ComponentStore() {
   function getSize() {
     return componentSet.getSize();
   }
-  return { add, remove, getIndex, getDense, getData, getSize };
+  function getSparse() {
+    return componentSet.getSparse();
+  }
+  return { add, remove, getIndex, getDense, getData, getSize, getSparse };
 }
 
 // src/EntityManager.ts
@@ -164,7 +170,10 @@ function EntityManager(registry) {
     if (!exists(eid)) throw new Error(`Entity ${eid} does not exist`);
     return bitMasks[eid];
   }
-  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask };
+  function tryGetMask(eid) {
+    return eid >= 0 && eid < nextID ? bitMasks[eid] : void 0;
+  }
+  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask, tryGetMask };
 }
 
 // src/utils/ComponentRegistry.ts
@@ -196,14 +205,17 @@ function createComponentRegistry() {
 function ECS() {
   const ComponentRegistry = createComponentRegistry();
   const Entities = EntityManager(ComponentRegistry);
-  const internalStores = {};
-  const components = {};
+  const internalStores = /* @__PURE__ */ Object.create(null);
+  const components = /* @__PURE__ */ Object.create(null);
+  const indices = /* @__PURE__ */ Object.create(null);
   function defineComponents(...names) {
     for (const name of names) {
-      if (name in internalStores) throw new Error(`Component ${String(name)} is already defined`);
+      if (Object.hasOwn(internalStores, name))
+        throw new Error(`Component ${String(name)} is already defined`);
       ComponentRegistry.register(name);
       internalStores[name] = ComponentStore();
       components[name] = internalStores[name].getData();
+      indices[name] = internalStores[name].getSparse();
     }
   }
   function createEntity() {
@@ -231,33 +243,65 @@ function ECS() {
     Entities.removeComponent(eid, name);
     internalStores[name].remove(eid);
   }
-  function* query(...componentName) {
-    if (componentName.length === 0) return;
+  function planQuery(componentName) {
     let targetMask = 0n;
     for (const name of componentName) {
       targetMask |= 1n << BigInt(ComponentRegistry.getID(name));
     }
-    let smallestStore = internalStores[componentName[0]];
-    let smallestSize = smallestStore.getSize();
+    let pivot = internalStores[componentName[0]];
+    let pivotSize = pivot.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;
+      if (size < pivotSize) {
+        pivot = store;
+        pivotSize = size;
       }
     }
-    for (const eid of smallestStore.getDense()) {
-      if ((Entities.getMask(eid) & targetMask) !== targetMask) continue;
+    return { targetMask, pivot };
+  }
+  function* query(...componentName) {
+    if (componentName.length === 0) return;
+    const { targetMask, pivot } = planQuery(componentName);
+    const count = componentName.length;
+    const sparses = new Array(count);
+    for (let i = 0; i < count; i++) sparses[i] = internalStores[componentName[i]].getSparse();
+    const entities = [...pivot.getDense()];
+    for (let i = 0; i < entities.length; i++) {
+      const eid = entities[i];
+      const mask = Entities.tryGetMask(eid);
+      if (mask === void 0 || (mask & targetMask) !== targetMask) continue;
       const result = {};
-      for (const name of componentName) {
-        const id = internalStores[name].getIndex(eid);
-        result[name] = { id };
+      for (let c = 0; c < count; c++) {
+        result[componentName[c]] = { id: sparses[c][eid] };
       }
       yield result;
     }
   }
-  return { defineComponents, createEntity, destroyEntity, addComponent, removeComponent, query, components };
+  function queryIds(...componentName) {
+    const matches = [];
+    if (componentName.length === 0) return matches;
+    const { targetMask, pivot } = planQuery(componentName);
+    const dense = pivot.getDense();
+    for (let i = 0; i < dense.length; i++) {
+      const eid = dense[i];
+      const mask = Entities.tryGetMask(eid);
+      if (mask === void 0 || (mask & targetMask) !== targetMask) continue;
+      matches.push(eid);
+    }
+    return matches;
+  }
+  return {
+    defineComponents,
+    createEntity,
+    destroyEntity,
+    addComponent,
+    removeComponent,
+    query,
+    queryIds,
+    components,
+    indices
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -22,6 +22,16 @@ type StoreDataMap<T> = {
   [K in keyof T]: ComponentDataArrays<T[K]>;
 };
 
+/**
+ * Maps component names to their raw sparse lookup table.
+ * Each table translates an entity ID into that entity's index in the component's
+ * data arrays, which is what queryIds callers need to read the SoA storage.
+ * @template T - Record type defining all component types
+ */
+type IndexMap<T> = {
+  [K in keyof T]: number[];
+};
+
 /**
  * Type helper for the query result.
  * Creates an object with an entry for each requested component, holding its store index.
@@ -91,7 +101,40 @@ interface IECS<T> {
    */
   query: <C extends (keyof T)[]>(...componentName: C) => Generator<QueryResult<C>>;
 
+  /**
+   * Allocation-free counterpart to query, for hot systems.
+   * Returns the IDs of every entity holding all the specified components, instead of
+   * yielding one result object plus one { id } object per component per entity.
+   * Translate an entity ID into a storage index through `indices`:
+   *
+   * ```ts
+   * const { Position, Velocity } = World.components;
+   * const pos = World.indices.Position;
+   * const vel = World.indices.Velocity;
+   *
+   * for (const eid of World.queryIds('Position', 'Velocity')) {
+   *   Position.x[pos[eid]] += Velocity.x[vel[eid]];
+   * }
+   * ```
+   *
+   * The array is complete before it is returned, so adding or removing components while
+   * looping over it cannot skip an entity. Destroying an entity mid-loop does invalidate
+   * its storage index, so guard that case yourself.
+   *
+   * @template C - Array of component names to query for
+   * @param componentName - List of component names that the entity must include
+   * @returns A fresh array of matching entity IDs
+   */
+  queryIds: <C extends (keyof T)[]>(...componentName: C) => number[];
+
   components: StoreDataMap<T>;
+
+  /**
+   * Maps each component name to its sparse lookup table, translating an entity ID into
+   * that entity's index in the component's data arrays. Needed to read `components`
+   * when iterating the output of queryIds.
+   */
+  indices: IndexMap<T>;
 }
 
 declare function ECS<T extends Record<string, Record<string, any>>>(): IECS<T>;

package/dist/index.d.ts

@@ -22,6 +22,16 @@ type StoreDataMap<T> = {
   [K in keyof T]: ComponentDataArrays<T[K]>;
 };
 
+/**
+ * Maps component names to their raw sparse lookup table.
+ * Each table translates an entity ID into that entity's index in the component's
+ * data arrays, which is what queryIds callers need to read the SoA storage.
+ * @template T - Record type defining all component types
+ */
+type IndexMap<T> = {
+  [K in keyof T]: number[];
+};
+
 /**
  * Type helper for the query result.
  * Creates an object with an entry for each requested component, holding its store index.
@@ -91,7 +101,40 @@ interface IECS<T> {
    */
   query: <C extends (keyof T)[]>(...componentName: C) => Generator<QueryResult<C>>;
 
+  /**
+   * Allocation-free counterpart to query, for hot systems.
+   * Returns the IDs of every entity holding all the specified components, instead of
+   * yielding one result object plus one { id } object per component per entity.
+   * Translate an entity ID into a storage index through `indices`:
+   *
+   * ```ts
+   * const { Position, Velocity } = World.components;
+   * const pos = World.indices.Position;
+   * const vel = World.indices.Velocity;
+   *
+   * for (const eid of World.queryIds('Position', 'Velocity')) {
+   *   Position.x[pos[eid]] += Velocity.x[vel[eid]];
+   * }
+   * ```
+   *
+   * The array is complete before it is returned, so adding or removing components while
+   * looping over it cannot skip an entity. Destroying an entity mid-loop does invalidate
+   * its storage index, so guard that case yourself.
+   *
+   * @template C - Array of component names to query for
+   * @param componentName - List of component names that the entity must include
+   * @returns A fresh array of matching entity IDs
+   */
+  queryIds: <C extends (keyof T)[]>(...componentName: C) => number[];
+
   components: StoreDataMap<T>;
+
+  /**
+   * Maps each component name to its sparse lookup table, translating an entity ID into
+   * that entity's index in the component's data arrays. Needed to read `components`
+   * when iterating the output of queryIds.
+   */
+  indices: IndexMap<T>;
 }
 
 declare function ECS<T extends Record<string, Record<string, any>>>(): IECS<T>;

package/dist/index.js

@@ -34,13 +34,16 @@ function SparseSet() {
   function getSize() {
     return size;
   }
-  return { has, add, remove, getIndex, getDense, getSize };
+  function getSparse() {
+    return sparse;
+  }
+  return { has, add, remove, getIndex, getDense, getSize, getSparse };
 }
 
 // src/ComponentStore.ts
 var INITIAL_CAPACITY = 8;
 function grow(buffer, requiredIndex) {
-  let capacity = buffer.length;
+  let capacity = buffer.length || INITIAL_CAPACITY;
   while (capacity <= requiredIndex) capacity *= 2;
   const grown = new Float32Array(capacity);
   grown.set(buffer);
@@ -48,8 +51,8 @@ function grow(buffer, requiredIndex) {
 }
 function ComponentStore() {
   const componentSet = SparseSet();
-  const componentData = {};
-  const isNumeric = {};
+  const componentData = /* @__PURE__ */ Object.create(null);
+  const isNumeric = /* @__PURE__ */ Object.create(null);
   function add(eid, data) {
     if (componentSet.has(eid)) throw new Error(`Entity ${eid} already has this component`);
     const ID = componentSet.getSize();
@@ -94,7 +97,10 @@ function ComponentStore() {
   function getSize() {
     return componentSet.getSize();
   }
-  return { add, remove, getIndex, getDense, getData, getSize };
+  function getSparse() {
+    return componentSet.getSparse();
+  }
+  return { add, remove, getIndex, getDense, getData, getSize, getSparse };
 }
 
 // src/EntityManager.ts
@@ -138,7 +144,10 @@ function EntityManager(registry) {
     if (!exists(eid)) throw new Error(`Entity ${eid} does not exist`);
     return bitMasks[eid];
   }
-  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask };
+  function tryGetMask(eid) {
+    return eid >= 0 && eid < nextID ? bitMasks[eid] : void 0;
+  }
+  return { exists, hasComponent, create, remove, addComponent, removeComponent, getMask, tryGetMask };
 }
 
 // src/utils/ComponentRegistry.ts
@@ -170,14 +179,17 @@ function createComponentRegistry() {
 function ECS() {
   const ComponentRegistry = createComponentRegistry();
   const Entities = EntityManager(ComponentRegistry);
-  const internalStores = {};
-  const components = {};
+  const internalStores = /* @__PURE__ */ Object.create(null);
+  const components = /* @__PURE__ */ Object.create(null);
+  const indices = /* @__PURE__ */ Object.create(null);
   function defineComponents(...names) {
     for (const name of names) {
-      if (name in internalStores) throw new Error(`Component ${String(name)} is already defined`);
+      if (Object.hasOwn(internalStores, name))
+        throw new Error(`Component ${String(name)} is already defined`);
       ComponentRegistry.register(name);
       internalStores[name] = ComponentStore();
       components[name] = internalStores[name].getData();
+      indices[name] = internalStores[name].getSparse();
     }
   }
   function createEntity() {
@@ -205,33 +217,65 @@ function ECS() {
     Entities.removeComponent(eid, name);
     internalStores[name].remove(eid);
   }
-  function* query(...componentName) {
-    if (componentName.length === 0) return;
+  function planQuery(componentName) {
     let targetMask = 0n;
     for (const name of componentName) {
       targetMask |= 1n << BigInt(ComponentRegistry.getID(name));
     }
-    let smallestStore = internalStores[componentName[0]];
-    let smallestSize = smallestStore.getSize();
+    let pivot = internalStores[componentName[0]];
+    let pivotSize = pivot.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;
+      if (size < pivotSize) {
+        pivot = store;
+        pivotSize = size;
       }
     }
-    for (const eid of smallestStore.getDense()) {
-      if ((Entities.getMask(eid) & targetMask) !== targetMask) continue;
+    return { targetMask, pivot };
+  }
+  function* query(...componentName) {
+    if (componentName.length === 0) return;
+    const { targetMask, pivot } = planQuery(componentName);
+    const count = componentName.length;
+    const sparses = new Array(count);
+    for (let i = 0; i < count; i++) sparses[i] = internalStores[componentName[i]].getSparse();
+    const entities = [...pivot.getDense()];
+    for (let i = 0; i < entities.length; i++) {
+      const eid = entities[i];
+      const mask = Entities.tryGetMask(eid);
+      if (mask === void 0 || (mask & targetMask) !== targetMask) continue;
       const result = {};
-      for (const name of componentName) {
-        const id = internalStores[name].getIndex(eid);
-        result[name] = { id };
+      for (let c = 0; c < count; c++) {
+        result[componentName[c]] = { id: sparses[c][eid] };
       }
       yield result;
     }
   }
-  return { defineComponents, createEntity, destroyEntity, addComponent, removeComponent, query, components };
+  function queryIds(...componentName) {
+    const matches = [];
+    if (componentName.length === 0) return matches;
+    const { targetMask, pivot } = planQuery(componentName);
+    const dense = pivot.getDense();
+    for (let i = 0; i < dense.length; i++) {
+      const eid = dense[i];
+      const mask = Entities.tryGetMask(eid);
+      if (mask === void 0 || (mask & targetMask) !== targetMask) continue;
+      matches.push(eid);
+    }
+    return matches;
+  }
+  return {
+    defineComponents,
+    createEntity,
+    destroyEntity,
+    addComponent,
+    removeComponent,
+    query,
+    queryIds,
+    components,
+    indices
+  };
 }
 export {
   ECS

package/package.json

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