@driftengine/entities 4.7.0 → 4.7.1

package/dist/system.d.ts

@@ -45,6 +45,18 @@ export interface SystemView {
     read(entity: Entity, type: ComponentType, field: string): unknown;
     write(entity: Entity, type: ComponentType, field: string, value: unknown): void;
     has(entity: Entity, type: ComponentType): boolean;
+    /**
+     * How many entities carry a component, and the one at an index among them; both reads, so both
+     * checked. A script's `ecs.count` and `ecs.at` reach these, and a view without them made each
+     * throw the moment a system called it.
+     */
+    count(type: ComponentType): number;
+    at(type: ComponentType, index: number): Entity;
+    /**
+     * Whether a handle names a live entity. It asks nothing of any component, so nothing is checked;
+     * an entity this system destroyed is still alive until the system returns.
+     */
+    alive(entity: Entity): boolean;
     create(): Entity;
     add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void;
     /** Deferred to after this system runs. See the header. */
@@ -105,6 +117,9 @@ export declare class BoundSystem implements SystemView {
     read(entity: Entity, type: ComponentType, field: string): unknown;
     write(entity: Entity, type: ComponentType, field: string, value: unknown): void;
     has(entity: Entity, type: ComponentType): boolean;
+    count(type: ComponentType): number;
+    at(type: ComponentType, index: number): Entity;
+    alive(entity: Entity): boolean;
     create(): Entity;
     add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void;
     destroy(entity: Entity): void;

package/dist/system.js

@@ -72,6 +72,17 @@ export class BoundSystem {
         this.requireReadable(type);
         return this.world.has(entity, type);
     }
+    count(type) {
+        this.requireReadable(type);
+        return this.world.count(type);
+    }
+    at(type, index) {
+        this.requireReadable(type);
+        return this.world.at(type, index);
+    }
+    alive(entity) {
+        return this.world.alive(entity);
+    }
     create() {
         return this.world.create();
     }

package/dist/world.d.ts

@@ -73,6 +73,15 @@ export declare class World implements CursorHost {
      * number of component *types* rather than of entities.
      */
     destroy(entity: Entity): boolean;
+    /** How many entities carry a component. */
+    count(type: ComponentType): number;
+    /**
+     * The entity at `index` among those carrying a component, or `-1` past the end.
+     *
+     * The order is the store's: insertion, modified by swap-removal, so it is a walk and not an
+     * identity, and an index held across a removal names a different entity.
+     */
+    at(type: ComponentType, index: number): Entity;
     /** The store for a component type, made on first ask. */
     store(type: ComponentType): ComponentStore;
     /**

package/dist/world.js

@@ -60,6 +60,20 @@ export class World {
             store.remove(entity);
         return this.entities.destroy(entity);
     }
+    /** How many entities carry a component. */
+    count(type) {
+        return this.store(type).size;
+    }
+    /**
+     * The entity at `index` among those carrying a component, or `-1` past the end.
+     *
+     * The order is the store's: insertion, modified by swap-removal, so it is a walk and not an
+     * identity, and an index held across a removal names a different entity.
+     */
+    at(type, index) {
+        const store = this.store(type);
+        return index >= 0 && index < store.size ? store.dense[index] : -1;
+    }
     /** The store for a component type, made on first ask. */
     store(type) {
         const existing = this.stores.get(type.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/entities",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "description": "Entities with generational identity, component storage, systems and scenes",
   "license": "Apache-2.0",
   "type": "module",

package/src/system.ts

@@ -46,6 +46,18 @@ export interface SystemView {
   read(entity: Entity, type: ComponentType, field: string): unknown;
   write(entity: Entity, type: ComponentType, field: string, value: unknown): void;
   has(entity: Entity, type: ComponentType): boolean;
+  /**
+   * How many entities carry a component, and the one at an index among them; both reads, so both
+   * checked. A script's `ecs.count` and `ecs.at` reach these, and a view without them made each
+   * throw the moment a system called it.
+   */
+  count(type: ComponentType): number;
+  at(type: ComponentType, index: number): Entity;
+  /**
+   * Whether a handle names a live entity. It asks nothing of any component, so nothing is checked;
+   * an entity this system destroyed is still alive until the system returns.
+   */
+  alive(entity: Entity): boolean;
   create(): Entity;
   add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void;
   /** Deferred to after this system runs. See the header. */
@@ -147,6 +159,20 @@ export class BoundSystem implements SystemView {
     return this.world.has(entity, type);
   }
 
+  count(type: ComponentType): number {
+    this.requireReadable(type);
+    return this.world.count(type);
+  }
+
+  at(type: ComponentType, index: number): Entity {
+    this.requireReadable(type);
+    return this.world.at(type, index);
+  }
+
+  alive(entity: Entity): boolean {
+    return this.world.alive(entity);
+  }
+
   create(): Entity {
     return this.world.create();
   }

package/src/world.ts

@@ -110,6 +110,22 @@ export class World implements CursorHost {
     return this.entities.destroy(entity);
   }
 
+  /** How many entities carry a component. */
+  count(type: ComponentType): number {
+    return this.store(type).size;
+  }
+
+  /**
+   * The entity at `index` among those carrying a component, or `-1` past the end.
+   *
+   * The order is the store's: insertion, modified by swap-removal, so it is a walk and not an
+   * identity, and an index held across a removal names a different entity.
+   */
+  at(type: ComponentType, index: number): Entity {
+    const store = this.store(type);
+    return index >= 0 && index < store.size ? (store.dense[index] as number) : -1;
+  }
+
   /** The store for a component type, made on first ask. */
   store(type: ComponentType): ComponentStore {
     const existing = this.stores.get(type.id);