@codehz/ecs 0.3.8 → 0.3.9

package/index.d.mts

@@ -23,28 +23,6 @@ type EntityRelationId<T = void> = EntityId<T, "entity-relation">;
 type ComponentRelationId<T = void> = EntityId<T, "component-relation">;
 type WildcardRelationId<T = void> = EntityId<T, "wildcard-relation">;
 type RelationId<T = void> = EntityRelationId<T> | ComponentRelationId<T> | WildcardRelationId<T>;
-/**
- * Constants for ID ranges
- */
-declare const INVALID_COMPONENT_ID = 0;
-declare const COMPONENT_ID_MAX = 1023;
-declare const ENTITY_ID_START = 1024;
-/**
- * Constants for relation ID encoding
- */
-declare const RELATION_SHIFT: number;
-declare const WILDCARD_TARGET_ID = 0;
-/**
- * Create a component ID
- * @param id Component identifier (1-1023)
- * @see component
- */
-declare function createComponentId<T = void>(id: number): ComponentId<T>;
-/**
- * Create an entity ID
- * @param id Entity identifier (starting from 1024)
- */
-declare function createEntityId(id: number): EntityId;
 /**
  * Type for relation ID based on component and target types
  */
@@ -83,102 +61,50 @@ declare function decodeRelationId(relationId: RelationId<any>): {
   type: "entity" | "component" | "wildcard";
 };
 /**
- * Get the string representation of an ID type
- */
-declare function getIdType(id: EntityId<any>): "component" | "entity" | "entity-relation" | "component-relation" | "wildcard-relation" | "invalid";
-/**
- * Get detailed type information for an EntityId
- * @param id The EntityId to analyze
- * @returns Detailed type information including relation subtypes
- */
-declare function getDetailedIdType(id: EntityId<any>): {
-  type: "component" | "entity" | "invalid";
-  componentId?: never;
-  targetId?: never;
-} | {
-  type: "entity-relation" | "wildcard-relation";
-  componentId: ComponentId<any>;
-  targetId: EntityId<any>;
-} | {
-  type: "component-relation";
-  componentId: ComponentId<any>;
-  targetId: ComponentId<any>;
-};
-/**
- * Inspect an EntityId and return a human-readable string representation
- * @param id The EntityId to inspect
- * @returns A friendly string representation of the ID
+ * Component options that define intrinsic properties
  */
-declare function inspectEntityId(id: EntityId<any>): string;
-/**
- * Entity ID Manager for automatic allocation and freelist recycling
- */
-declare class EntityIdManager {
-  private nextId;
-  private freelist;
-  /**
-   * Allocate a new entity ID
-   * Uses freelist if available, otherwise increments counter
-   */
-  allocate(): EntityId;
-  /**
-   * Deallocate an entity ID, adding it to the freelist for reuse
-   * @param id The entity ID to deallocate
-   */
-  deallocate(id: EntityId<any>): void;
-  /**
-   * Get the current freelist size (for debugging/monitoring)
-   */
-  getFreelistSize(): number;
-  /**
-   * Get the next ID that would be allocated (for debugging)
-   */
-  getNextId(): number;
+interface ComponentOptions {
   /**
-   * Serialize internal state for persistence.
-   * Returns a plain object representing allocator state. Values may be non-JSON-serializable.
+   * Optional name for the component (for serialization/debugging)
    */
-  serializeState(): {
-    nextId: number;
-    freelist: number[];
-  };
+  name?: string;
   /**
-   * Restore internal state from a previously-serialized object.
-   * Overwrites the current nextId and freelist.
+   * If true, an entity can have at most one relation per base component.
+   * When adding a new relation with the same base component, any existing relations
+   * with that base component are automatically removed.
+   * Only applicable to relation components.
    */
-  deserializeState(state: {
-    nextId: number;
-    freelist?: number[];
-  }): void;
-}
-/**
- * Component ID Manager for automatic allocation
- * Components are typically registered once and not recycled
- */
-declare class ComponentIdAllocator {
-  private nextId;
+  exclusive?: boolean;
   /**
-   * Allocate a new component ID
-   * Increments counter sequentially from 1
+   * If true, when a relation target entity is deleted, all entities that reference
+   * it through this component will also be deleted (cascade delete).
+   * Only applicable to entity-relation components.
    */
-  allocate<T = void>(): ComponentId<T>;
+  cascadeDelete?: boolean;
   /**
-   * Get the next ID that would be allocated (for debugging)
+   * If true, relations with this component will not cause archetype fragmentation.
+   * Entities with different target entities for this relation component will be stored
+   * in the same archetype, preventing fragmentation when there are many different targets.
+   * Only applicable to relation components.
+   * Inspired by Flecs' DontFragment trait.
    */
-  getNextId(): number;
-  /**
-   * Check if more component IDs are available
-   */
-  hasAvailableIds(): boolean;
+  dontFragment?: boolean;
 }
 /**
  * Allocate a new component ID from the global allocator.
- * Optionally register a name for the component.
- * The name is only for serialization/debugging and does not affect base functionality.
- * @param name Optional name for the component
+ * @param nameOrOptions Optional name for the component (for serialization/debugging) or options object
  * @returns The allocated component ID
- */
-declare function component<T = void>(name?: string): ComponentId<T>;
+ * @example
+ * // Just a name
+ * const Position = component<Position>("Position");
+ *
+ * // With options
+ * const ChildOf = component({ exclusive: true, cascadeDelete: true });
+ *
+ * // With name and options
+ * const ChildOf = component({ name: "ChildOf", exclusive: true });
+ */
+declare function component<T = void>(nameOrOptions?: string | ComponentOptions): ComponentId<T>;
 /**
  * Get a component ID by its registered name
  * @param name The component name
@@ -213,7 +139,6 @@ type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
 type OptionalEntityId<T> = {
   optional: EntityId<T>;
 };
-declare function isOptionalEntityId<T>(type: ComponentType<T>): type is OptionalEntityId<T>;
 type ComponentTypeToData<T> = T extends {
   optional: infer U;
 } ? {
@@ -225,10 +150,6 @@ type ComponentTypeToData<T> = T extends {
 type ComponentTuple<T extends readonly ComponentType<any>[]> = { readonly [K in keyof T]: ComponentTypeToData<T[K]> };
 //#endregion
 //#region src/archetype.d.ts
-/**
- * Special value to represent missing component data
- */
-declare const MISSING_COMPONENT: unique symbol;
 /**
  * Archetype class for ECS architecture
  * Represents a group of entities that share the same set of components
@@ -252,6 +173,12 @@ declare class Archetype {
    * Reverse mapping from entity to its index in this archetype
    */
   private entityToIndex;
+  /**
+   * Reference to dontFragment relations storage from World
+   * This allows entities with different relation targets to share the same archetype
+   * Stored in World to avoid migration overhead when entities change archetypes
+   */
+  private dontFragmentRelations;
   /**
    * Cache for pre-computed component data sources to avoid repeated calculations
    * For regular components: data array
@@ -261,8 +188,9 @@ declare class Archetype {
   /**
    * Create a new archetype with the specified component types
    * @param componentTypes The component types that define this archetype
+   * @param dontFragmentRelations Reference to the World's dontFragmentRelations storage
    */
-  constructor(componentTypes: EntityId<any>[]);
+  constructor(componentTypes: EntityId<any>[], dontFragmentRelations: Map<EntityId, Map<EntityId<any>, any>>);
   /**
    * Get the number of entities in this archetype
    */
@@ -275,18 +203,18 @@ declare class Archetype {
   /**
    * Add an entity to this archetype with initial component data
    * @param entityId The entity to add
-   * @param componentData Map of component type to component data
+   * @param componentData Map of component type to component data (includes both regular and dontFragment components)
    */
   addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
   /**
    * Get all component data for a specific entity
    * @param entityId The entity to get data for
-   * @returns Map of component type to component data
+   * @returns Map of component type to component data (includes both regular and dontFragment components)
    */
   getEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   /**
    * Dump all entities and their component data in this archetype
-   * @returns Array of objects with entity and component data
+   * @returns Array of objects with entity and component data (includes both regular and dontFragment components)
    */
   dump(): Array<{
     entity: EntityId;
@@ -295,7 +223,7 @@ declare class Archetype {
   /**
    * Remove an entity from this archetype
    * @param entityId The entity to remove
-   * @returns The component data of the removed entity
+   * @returns The component data of the removed entity (includes both regular and dontFragment components)
    */
   removeEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   /**
@@ -346,10 +274,34 @@ declare class Archetype {
    * Helper: compute or return cached data sources for provided componentTypes
    */
   private getCachedComponentDataSources;
+  /**
+   * Build cache key for component types
+   */
+  private buildCacheKey;
+  /**
+   * Get data source for a single component type
+   */
+  private getComponentDataSource;
+  /**
+   * Get data source for wildcard relations
+   */
+  private getWildcardRelationDataSource;
   /**
    * Helper: build component tuples for a specific entity index using precomputed data sources
    */
   private buildComponentsForIndex;
+  /**
+   * Build a single component value from its data source
+   */
+  private buildSingleComponent;
+  /**
+   * Build wildcard relation value from matching relations
+   */
+  private buildWildcardRelationValue;
+  /**
+   * Build regular component value from data source
+   */
+  private buildRegularComponentValue;
   /**
    * Get entities with their component data for specified component types
    * Optimized for bulk component access with pre-computed indices
@@ -449,6 +401,10 @@ declare class Query {
   private cachedArchetypes;
   private isDisposed;
   constructor(world: World<any[]>, componentTypes: EntityId<any>[], filter?: QueryFilter);
+  /**
+   * Check if query is disposed and throw error if so
+   */
+  private ensureNotDisposed;
   /**
    * Get all entities matching the query
    */
@@ -548,6 +504,8 @@ declare class World<UpdateParams extends any[] = []> {
   private archetypesByComponent;
   /** Tracks which entities reference each entity as a component type */
   private entityReferences;
+  /** Storage for dontFragment relations - maps entity ID to a map of relation type to component data */
+  private dontFragmentRelations;
   /** Array of all active queries for archetype change notifications */
   private queries;
   /** Cache for queries keyed by component types and filter signatures */
@@ -558,10 +516,6 @@ declare class World<UpdateParams extends any[] = []> {
   private commandBuffer;
   /** Stores lifecycle hooks for component and relation events */
   private hooks;
-  /** Set of component IDs marked as exclusive relations */
-  private exclusiveComponents;
-  /** Set of component IDs that will cascade delete when the relation target is deleted */
-  private cascadeDeleteComponents;
   /**
    * Create a new World.
    * If an optional snapshot object is provided (previously produced by `world.serialize()`),
@@ -632,14 +586,14 @@ declare class World<UpdateParams extends any[] = []> {
   unhook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
   /**
    * Mark a component as exclusive relation
-   * For exclusive relations, an entity can have at most one relation per base component
+   * @deprecated This method has been removed. Use component options instead: component({ exclusive: true })
+   * @throws Always throws an error directing to the new API
    */
   setExclusive(componentId: EntityId): void;
   /**
    * Mark a component as cascade-delete relation
-   * For cascade relations, when the relation target entity is deleted,
-   * the referencing entity will also be deleted (cascade).
-   * Only applicable to entity-relation components
+   * @deprecated This method has been removed. Use component options instead: component({ cascadeDelete: true })
+   * @throws Always throws an error directing to the new API
    */
   setCascadeDelete(componentId: EntityId): void;
   /**
@@ -688,11 +642,77 @@ declare class World<UpdateParams extends any[] = []> {
    * @returns ComponentChangeset describing the changes made
    */
   executeEntityCommands(entityId: EntityId, commands: Command[]): ComponentChangeset;
+  /**
+   * Process commands and populate the changeset
+   */
+  private processCommands;
+  /**
+   * Process a set command, handling exclusive relations
+   */
+  private processSetCommand;
+  /**
+   * Remove all relations with the same base component (for exclusive relations)
+   */
+  private removeExclusiveRelations;
+  /**
+   * Check if a component type is a relation with the given base component
+   */
+  private isRelationWithComponent;
+  /**
+   * Process a delete command, handling wildcard relations
+   */
+  private processDeleteCommand;
+  /**
+   * Remove all relations matching a wildcard component ID
+   */
+  private removeWildcardRelations;
+  /**
+   * Apply changeset to entity, moving to new archetype if needed
+   * @returns Map of removed components with their data
+   */
+  private applyChangeset;
+  /**
+   * Move entity to a new archetype with updated components
+   */
+  private moveEntityToNewArchetype;
+  /**
+   * Update entity in same archetype (no archetype change needed)
+   */
+  private updateEntityInSameArchetype;
+  /**
+   * Check if changeset contains dontFragment relation changes
+   */
+  private hasDontFragmentChanges;
+  /**
+   * Remove and re-add entity with updated components (for dontFragment changes)
+   */
+  private readdEntityWithUpdatedComponents;
+  /**
+   * Update entity reference tracking based on changeset
+   */
+  private updateEntityReferences;
   /**
    * Get or create an archetype for the given component types
-   * @returns The archetype for the given component types
+   * Filters out dontFragment relations from the archetype signature
+   * @returns The archetype for the given component types (excluding dontFragment relations)
    */
   private ensureArchetype;
+  /**
+   * Filter out dontFragment relations from component types
+   */
+  private filterRegularComponentTypes;
+  /**
+   * Create a new archetype and register it with all tracking structures
+   */
+  private createNewArchetype;
+  /**
+   * Register archetype in the component-to-archetype index
+   */
+  private registerArchetypeInComponentIndex;
+  /**
+   * Notify all queries to check the new archetype
+   */
+  private notifyQueriesOfNewArchetype;
   /**
    * Add a component reference to the reverse index when an entity is used as a component type
    * @param sourceEntityId The entity that has the component
@@ -717,6 +737,22 @@ declare class World<UpdateParams extends any[] = []> {
    * Remove an empty archetype from all internal data structures
    */
   private cleanupEmptyArchetype;
+  /**
+   * Remove archetype from the main archetypes list
+   */
+  private removeArchetypeFromList;
+  /**
+   * Remove archetype from the signature-to-archetype map
+   */
+  private removeArchetypeFromSignatureMap;
+  /**
+   * Remove archetype from the component-to-archetypes index
+   */
+  private removeArchetypeFromComponentIndex;
+  /**
+   * Remove archetype from all queries
+   */
+  private removeArchetypeFromQueries;
   /**
    * Execute component lifecycle hooks for added and removed components
    */
@@ -745,31 +781,5 @@ type SerializedComponent = {
   value: any;
 };
 //#endregion
-//#region src/system-scheduler.d.ts
-/**
- * System Scheduler for managing system dependencies and execution order
- */
-declare class SystemScheduler<UpdateParams extends any[] = []> {
-  private systems;
-  private systemDependencies;
-  private cachedExecutionOrder;
-  /**
-   * Add a system with optional dependencies
-   * @param system The system to add
-   * @param additionalDeps Additional dependencies for the system
-   */
-  addSystem(system: System<UpdateParams>, additionalDeps?: System<UpdateParams>[]): void;
-  /**
-   * Get the execution order of systems based on dependencies
-   * Uses topological sort
-   */
-  getExecutionOrder(): System<UpdateParams>[];
-  update(...params: UpdateParams): Promise<void[]> | void;
-  /**
-   * Clear all systems and dependencies
-   */
-  clear(): void;
-}
-//#endregion
-export { Archetype, COMPONENT_ID_MAX, ComponentId, ComponentIdAllocator, ComponentRelationId, ComponentTuple, ComponentType, ComponentTypeToData, ENTITY_ID_START, EntityId, EntityIdManager, EntityRelationId, INVALID_COMPONENT_ID, LifecycleHook, MISSING_COMPONENT, OptionalEntityId, Query, RELATION_SHIFT, RelationId, SerializedComponent, SerializedEntity, SerializedWorld, System, SystemScheduler, WILDCARD_TARGET_ID, WildcardRelationId, World, component, createComponentId, createEntityId, decodeRelationId, getComponentIdByName, getComponentNameById, getDetailedIdType, getIdType, inspectEntityId, isComponentId, isEntityId, isOptionalEntityId, isRelationId, isWildcardRelationId, relation };
+export { type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, type EntityId, type EntityRelationId, type LifecycleHook, Query, type RelationId, type SerializedWorld, type System, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };
 //# sourceMappingURL=index.d.mts.map