@codehz/ecs 0.0.0

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@codehz/ecs",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "peerDependencies": {
+    "typescript": "~5.9.2"
+  }
+}

package/query-filter.d.ts

@@ -0,0 +1,16 @@
+import { Archetype } from "./archetype";
+import type { EntityId } from "./entity";
+/**
+ * Filter options for queries
+ */
+export interface QueryFilter {
+    negativeComponentTypes?: EntityId<any>[];
+}
+/**
+ * Check if an archetype matches the given component types
+ */
+export declare function matchesComponentTypes(archetype: Archetype, componentTypes: EntityId<any>[]): boolean;
+/**
+ * Check if an archetype matches the filter conditions (only filtering logic)
+ */
+export declare function matchesFilter(archetype: Archetype, filter: QueryFilter): boolean;

package/query.d.ts

@@ -0,0 +1,62 @@
+import { Archetype } from "./archetype";
+import type { EntityId } from "./entity";
+import type { ComponentTuple } from "./types";
+import { type QueryFilter } from "./query-filter";
+import type { World } from "./world";
+/**
+ * Query class for efficient entity queries with cached archetypes
+ */
+export declare class Query {
+    private world;
+    private componentTypes;
+    private filter;
+    private cachedArchetypes;
+    private isDisposed;
+    constructor(world: World<any[]>, componentTypes: EntityId<any>[], filter?: QueryFilter);
+    /**
+     * Get all entities matching the query
+     */
+    getEntities(): EntityId[];
+    /**
+     * Get entities with their component data
+     * @param componentTypes Array of component types to retrieve
+     * @returns Array of objects with entity and component data
+     */
+    getEntitiesWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T): Array<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
+    /**
+     * Iterate over entities with their component data
+     * @param componentTypes Array of component types to retrieve
+     * @param callback Function called for each entity with its components
+     */
+    forEach<const T extends readonly EntityId<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    /**
+     * Get component data arrays for all matching entities
+     * @param componentType The component type to retrieve
+     * @returns Array of component data for all matching entities
+     */
+    getComponentData<T>(componentType: EntityId<T>): T[];
+    /**
+     * Update the cached archetypes
+     * Called when new archetypes are created
+     */
+    updateCache(): void;
+    /**
+     * Check if a new archetype matches this query and add to cache if it does
+     */
+    checkNewArchetype(archetype: Archetype): void;
+    /**
+     * Dispose the query and disconnect from world
+     */
+    dispose(): void;
+    /**
+     * Symbol.dispose implementation for automatic resource management
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Check if the query has been disposed
+     */
+    get disposed(): boolean;
+}

package/system.d.ts

@@ -0,0 +1,10 @@
+import type { World } from "./world";
+/**
+ * Base System interface
+ */
+export interface System<ExtraParams extends any[] = [deltaTime: number]> {
+    /**
+     * Update the system
+     */
+    update(world: World<ExtraParams>, ...params: ExtraParams): void;
+}

package/types.d.ts

@@ -0,0 +1,7 @@
+import type { EntityId, WildcardRelationId } from "./entity";
+/**
+ * Type helper for component tuples extracted from EntityId array
+ */
+export type ComponentTuple<T extends readonly EntityId<any>[]> = {
+    readonly [K in keyof T]: T[K] extends WildcardRelationId<infer U> ? [EntityId<unknown>, U][] : T[K] extends EntityId<infer U> ? U : never;
+};

package/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility functions for ECS library
+ */
+/**
+ * Get a value from cache or compute and cache it if not present
+ * @param cache The cache map
+ * @param key The cache key
+ * @param compute Function to compute the value if not cached
+ * @returns The cached or computed value
+ */
+export declare function getOrComputeCache<K, V>(cache: Map<K, V>, key: K, compute: () => V): V;
+/**
+ * Get a value from cache or create and cache it if not present, allowing side effects during creation
+ * @param cache The cache map
+ * @param key The cache key
+ * @param create Function to create the value if not cached (can have side effects)
+ * @returns The cached or created value
+ */
+export declare function getOrCreateWithSideEffect<K, V>(cache: Map<K, V>, key: K, create: () => V): V;

package/world.d.ts

@@ -0,0 +1,106 @@
+import { Archetype } from "./archetype";
+import { type Command } from "./command-buffer";
+import type { EntityId } from "./entity";
+import { Query } from "./query";
+import type { QueryFilter } from "./query-filter";
+import type { ComponentTuple } from "./types";
+import type { System } from "./system";
+/**
+ * World class for ECS architecture
+ * Manages entities, components, and systems
+ */
+export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
+    private entityIdManager;
+    private archetypes;
+    private archetypeMap;
+    private entityToArchetype;
+    private systems;
+    private queries;
+    private commandBuffer;
+    private componentToArchetypes;
+    constructor();
+    /**
+     * Generate a hash key for component types array
+     */
+    private getComponentTypesHash;
+    /**
+     * Create a new entity
+     */
+    createEntity(): EntityId;
+    /**
+     * Destroy an entity and remove all its components (immediate execution)
+     */
+    private _destroyEntity;
+    /**
+     * Check if an entity exists
+     */
+    hasEntity(entityId: EntityId): boolean;
+    /**
+     * Add a component to an entity (deferred)
+     */
+    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: T): void;
+    /**
+     * Remove a component from an entity (deferred)
+     */
+    removeComponent<T>(entityId: EntityId, componentType: EntityId<T>): void;
+    /**
+     * Destroy an entity and remove all its components (deferred)
+     */
+    destroyEntity(entityId: EntityId): void;
+    /**
+     * Check if an entity has a specific component
+     */
+    hasComponent<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
+    /**
+     * Get a component from an entity
+     */
+    getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
+    /**
+     * Register a system
+     */
+    registerSystem(system: System<ExtraParams>): void;
+    /**
+     * Unregister a system
+     */
+    unregisterSystem(system: System<ExtraParams>): void;
+    /**
+     * Update the world (run all systems)
+     */
+    update(...params: ExtraParams): void;
+    /**
+     * Execute all deferred commands immediately without running systems
+     */
+    flushCommands(): void;
+    /**
+     * Create a cached query for efficient entity lookups
+     */
+    createQuery(componentTypes: EntityId<any>[], filter?: QueryFilter): Query;
+    /**
+     * @internal Register a query for archetype update notifications
+     */
+    registerQuery(query: Query): void;
+    /**
+     * @internal Unregister a query
+     */
+    unregisterQuery(query: Query): void;
+    /**
+     * @internal Get archetypes that match specific component types (for internal use by queries)
+     */
+    getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[];
+    /**
+     * Query entities with specific components
+     */
+    queryEntities(componentTypes: EntityId<any>[]): EntityId[];
+    queryEntities<const T extends readonly EntityId<any>[]>(componentTypes: T, includeComponents: true): Array<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
+    /**
+     * @internal Execute commands for a single entity (for internal use by CommandBuffer)
+     */
+    executeEntityCommands(entityId: EntityId, commands: Command[]): void;
+    /**
+     * Get or create an archetype for the given component types
+     */
+    private getOrCreateArchetype;
+}