@codehz/ecs 0.3.6 → 0.3.8

package/index.d.mts

@@ -0,0 +1,775 @@
+//#region src/entity.d.ts
+/**
+ * Unique symbol brand for associating component type information with EntityId
+ */
+declare const __componentTypeMarker: unique symbol;
+/**
+ * Unique symbol brand for tagging the kind of EntityId (e.g., 'component', 'entity-relation')
+ */
+declare const __entityIdTypeTag: unique symbol;
+/**
+ * Entity ID type for ECS architecture
+ * Based on 52-bit integers within safe integer range
+ * - Component IDs: 1-1023
+ * - Entity IDs: 1024+
+ * - Relation IDs: negative numbers encoding component and entity associations
+ */
+type EntityId<T = void, U$1 = unknown> = number & {
+  readonly [__componentTypeMarker]: T;
+  readonly [__entityIdTypeTag]: U$1;
+};
+type ComponentId<T = void> = EntityId<T, "component">;
+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
+ */
+type RelationIdType<T, R> = R extends ComponentId<infer U> ? U extends void ? ComponentRelationId<T> : ComponentRelationId<T extends void ? U : T> : R extends EntityId<any> ? EntityRelationId<T> : never;
+/**
+ * Create a relation ID by associating a component with another ID (entity or component)
+ * @param componentId The component ID (0-1023)
+ * @param targetId The target ID (entity, component, or '*' for wildcard)
+ */
+declare function relation<T>(componentId: ComponentId<T>, targetId: "*"): WildcardRelationId<T>;
+declare function relation<T, R extends EntityId<any>>(componentId: ComponentId<T>, targetId: R): RelationIdType<T, R>;
+/**
+ * Check if an ID is a component ID
+ */
+declare function isComponentId<T>(id: EntityId<T>): id is ComponentId<T>;
+/**
+ * Check if an ID is an entity ID
+ */
+declare function isEntityId<T>(id: EntityId<T>): id is EntityId<T>;
+/**
+ * Check if an ID is a relation ID
+ */
+declare function isRelationId<T>(id: EntityId<T>): id is RelationId<T>;
+/**
+ * Check if an ID is a wildcard relation id
+ */
+declare function isWildcardRelationId<T>(id: EntityId<T>): id is WildcardRelationId<T>;
+/**
+ * Decode a relation ID into component and target IDs
+ * @param relationId The relation ID (must be negative)
+ * @returns Object with componentId, targetId, and relation type
+ */
+declare function decodeRelationId(relationId: RelationId<any>): {
+  componentId: ComponentId<any>;
+  targetId: EntityId<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
+ */
+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;
+  /**
+   * Serialize internal state for persistence.
+   * Returns a plain object representing allocator state. Values may be non-JSON-serializable.
+   */
+  serializeState(): {
+    nextId: number;
+    freelist: number[];
+  };
+  /**
+   * Restore internal state from a previously-serialized object.
+   * Overwrites the current nextId and freelist.
+   */
+  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;
+  /**
+   * Allocate a new component ID
+   * Increments counter sequentially from 1
+   */
+  allocate<T = void>(): ComponentId<T>;
+  /**
+   * Get the next ID that would be allocated (for debugging)
+   */
+  getNextId(): number;
+  /**
+   * Check if more component IDs are available
+   */
+  hasAvailableIds(): 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
+ * @returns The allocated component ID
+ */
+declare function component<T = void>(name?: string): ComponentId<T>;
+/**
+ * Get a component ID by its registered name
+ * @param name The component name
+ * @returns The component ID if found, undefined otherwise
+ */
+declare function getComponentIdByName(name: string): ComponentId<any> | undefined;
+/** Get a component name by its ID
+ * @param id The component ID
+ * @returns The component name if found, undefined otherwise
+ */
+declare function getComponentNameById(id: ComponentId<any>): string | undefined;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Hook types for component lifecycle events
+ */
+interface LifecycleHook<T = unknown> {
+  /**
+   * Called when a component is added to an entity
+   */
+  on_init?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+  /**
+   * Called when a component is added to an entity
+   */
+  on_set?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+  /**
+   * Called when a component is deleted from an entity
+   */
+  on_remove?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+}
+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;
+} ? {
+  value: ComponentTypeToData<U>;
+} | undefined : T extends WildcardRelationId<infer U> ? [EntityId<unknown>, U][] : T extends EntityId<infer U> ? U : never;
+/**
+ * Type helper for component tuples extracted from EntityId array
+ */
+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
+ * Optimized for fast iteration and component access
+ */
+declare class Archetype {
+  /**
+   * The component types that define this archetype
+   */
+  readonly componentTypes: EntityId<any>[];
+  /**
+   * List of entities in this archetype
+   */
+  private entities;
+  /**
+   * Component data storage - maps component type to array of component data
+   * Each array index corresponds to the entity index in the entities array
+   */
+  private componentData;
+  /**
+   * Reverse mapping from entity to its index in this archetype
+   */
+  private entityToIndex;
+  /**
+   * Cache for pre-computed component data sources to avoid repeated calculations
+   * For regular components: data array
+   * For wildcards: matching relation types array
+   */
+  private componentDataSourcesCache;
+  /**
+   * Create a new archetype with the specified component types
+   * @param componentTypes The component types that define this archetype
+   */
+  constructor(componentTypes: EntityId<any>[]);
+  /**
+   * Get the number of entities in this archetype
+   */
+  get size(): number;
+  /**
+   * Check if this archetype matches the given component types
+   * @param componentTypes The component types to check
+   */
+  matches(componentTypes: EntityId<any>[]): boolean;
+  /**
+   * 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
+   */
+  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
+   */
+  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
+   */
+  dump(): Array<{
+    entity: EntityId;
+    components: Map<EntityId<any>, any>;
+  }>;
+  /**
+   * Remove an entity from this archetype
+   * @param entityId The entity to remove
+   * @returns The component data of the removed entity
+   */
+  removeEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
+  /**
+   * Check if an entity is in this archetype
+   * @param entityId The entity to check
+   */
+  exists(entityId: EntityId): boolean;
+  /**
+   * Get component data for a specific entity and wildcard relation type
+   * Returns an array of all matching relation instances
+   * @param entityId The entity
+   * @param componentType The wildcard relation type
+   */
+  get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][];
+  /**
+   * Get component data for a specific entity and component type
+   * @param entityId The entity
+   * @param componentType The component type
+   */
+  get<T>(entityId: EntityId, componentType: EntityId<T>): T;
+  /**
+   * Set component data for a specific entity and component type
+   * @param entityId The entity
+   * @param componentType The component type
+   * @param data The component data
+   */
+  set<T>(entityId: EntityId, componentType: EntityId<T>, data: T): void;
+  /**
+   * Get all entities in this archetype
+   */
+  getEntities(): EntityId[];
+  /**
+   * Get the mapping of entities to their indices in this archetype
+   */
+  getEntityToIndexMap(): Map<EntityId, number>;
+  /**
+   * Get component data for all entities of a specific component type
+   * @param componentType The component type
+   */
+  getComponentData<T>(componentType: EntityId<T>): T[];
+  /**
+   * Get optional component data for all entities of a specific component type
+   * @param componentType The component type
+   * @returns An array of component data or undefined if not present
+   */
+  getOptionalComponentData<T>(componentType: EntityId<T>): T[] | undefined;
+  /**
+   * Helper: compute or return cached data sources for provided componentTypes
+   */
+  private getCachedComponentDataSources;
+  /**
+   * Helper: build component tuples for a specific entity index using precomputed data sources
+   */
+  private buildComponentsForIndex;
+  /**
+   * Get entities with their component data for specified component types
+   * Optimized for bulk component access with pre-computed indices
+   * @param componentTypes Array of component types to retrieve
+   * @returns Array of objects with entity and component data
+   */
+  getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): Array<{
+    entity: EntityId;
+    components: ComponentTuple<T>;
+  }>;
+  /**
+   * Iterate over entities with their component data for specified component types
+   * implemented as a generator returning each entity/components pair lazily
+   * @param componentTypes Array of component types to retrieve
+   */
+  iterateWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<[EntityId, ...ComponentTuple<T>]>;
+  /**
+   * Iterate over entities with their component data for specified component types
+   * Optimized for bulk component access
+   * @param componentTypes Array of component types to retrieve
+   * @param callback Function called for each entity with its components
+   */
+  forEachWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+  /**
+   * Iterate over all entities with their component data
+   * @param callback Function called for each entity with its component data
+   */
+  forEach(callback: (entityId: EntityId, components: Map<EntityId<any>, any>) => void): void;
+}
+//#endregion
+//#region src/changeset.d.ts
+/**
+ * @internal Represents a set of component changes to be applied to an entity
+ */
+declare class ComponentChangeset {
+  readonly adds: Map<EntityId<any>, any>;
+  readonly removes: Set<EntityId<any>>;
+  /**
+   * Add a component to the changeset
+   */
+  set<T>(componentType: EntityId<T>, component: T): void;
+  /**
+   * Remove a component from the changeset
+   */
+  delete<T>(componentType: EntityId<T>): void;
+  /**
+   * Check if the changeset has any changes
+   */
+  hasChanges(): boolean;
+  /**
+   * Clear all changes
+   */
+  clear(): void;
+  /**
+   * Merge another changeset into this one
+   */
+  merge(other: ComponentChangeset): void;
+  /**
+   * Apply the changeset to existing components and return the final state
+   */
+  applyTo(existingComponents: Map<EntityId<any>, any>): Map<EntityId<any>, any>;
+  /**
+   * Get the final component types after applying the changeset
+   * @param existingComponentTypes - The current component types on the entity
+   * @returns The final component types or undefined if no changes
+   */
+  getFinalComponentTypes(existingComponentTypes: EntityId<any>[]): EntityId<any>[] | undefined;
+}
+//#endregion
+//#region src/command-buffer.d.ts
+/**
+ * Command for deferred execution
+ */
+interface Command {
+  type: "set" | "delete" | "destroy";
+  entityId: EntityId;
+  componentType?: EntityId<any>;
+  component?: any;
+}
+//#endregion
+//#region src/query-filter.d.ts
+/**
+ * Filter options for queries
+ */
+interface QueryFilter {
+  negativeComponentTypes?: EntityId<any>[];
+}
+//#endregion
+//#region src/query.d.ts
+/**
+ * Query class for efficient entity queries with cached archetypes
+ */
+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 ComponentType<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 ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+  /**
+   * Iterate over entities with their component data (generator)
+   * @param componentTypes Array of component types to retrieve
+   */
+  iterate<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<[EntityId, ...ComponentTuple<T>]>;
+  /**
+   * 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;
+  /**
+   * Remove an archetype from the cached archetypes
+   */
+  removeArchetype(archetype: Archetype): void;
+  /**
+   * Dispose the query and disconnect from world
+   */
+  /**
+   * Request disposal of this query.
+   * This will decrement the world's reference count for the query.
+   * The query will only be fully disposed when the ref count reaches zero.
+   */
+  dispose(): void;
+  /**
+   * Internal full dispose called by World when refCount reaches zero.
+   */
+  _disposeInternal(): void;
+  /**
+   * Symbol.dispose implementation for automatic resource management
+   */
+  [Symbol.dispose](): void;
+  /**
+   * Check if the query has been disposed
+   */
+  get disposed(): boolean;
+}
+//#endregion
+//#region src/system.d.ts
+/**
+ * Base System interface
+ */
+interface System<UpdateParams extends any[] = []> {
+  /**
+   * Update the system
+   */
+  update(...params: UpdateParams): void | Promise<void>;
+  /**
+   * Dependencies of this system (systems that must run before this one)
+   */
+  readonly dependencies?: readonly System<UpdateParams>[];
+}
+//#endregion
+//#region src/world.d.ts
+/**
+ * World class for ECS architecture
+ * Manages entities, components, and systems
+ */
+declare class World<UpdateParams extends any[] = []> {
+  /** Manages allocation and deallocation of entity IDs */
+  private entityIdManager;
+  /** Array of all archetypes in the world */
+  private archetypes;
+  /** Maps archetype signatures (component type signatures) to archetype instances */
+  private archetypeBySignature;
+  /** Maps entity IDs to their current archetype */
+  private entityToArchetype;
+  /** Maps component types to arrays of archetypes that contain them */
+  private archetypesByComponent;
+  /** Tracks which entities reference each entity as a component type */
+  private entityReferences;
+  /** Array of all active queries for archetype change notifications */
+  private queries;
+  /** Cache for queries keyed by component types and filter signatures */
+  private queryCache;
+  /** Schedules and executes systems in dependency order */
+  private systemScheduler;
+  /** Buffers structural changes for deferred execution */
+  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()`),
+   * the world will be restored from that snapshot. The snapshot may contain non-JSON values.
+   */
+  constructor(snapshot?: SerializedWorld);
+  /**
+   * Generate a signature string for component types array
+   * @returns A string signature for the component types
+   */
+  private createArchetypeSignature;
+  /**
+   * Create a new entity
+   * @returns The ID of the newly created entity
+   */
+  new(): EntityId;
+  /**
+   * Destroy an entity and remove all its components (immediate execution)
+   */
+  private destroyEntityImmediate;
+  /**
+   * Check if an entity exists
+   */
+  exists(entityId: EntityId): boolean;
+  /**
+   * Add a component to an entity (deferred)
+   */
+  set(entityId: EntityId, componentType: EntityId<void>): void;
+  set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
+  /**
+   * Remove a component from an entity (deferred)
+   */
+  remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
+  /**
+   * Destroy an entity and remove all its components (deferred)
+   */
+  delete(entityId: EntityId): void;
+  /**
+   * Check if an entity has a specific component
+   */
+  has<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
+  /**
+   * Get component data for a specific entity and wildcard relation type
+   * Returns an array of all matching relation instances
+   * @param entityId The entity
+   * @param componentType The wildcard relation type
+   * @returns Array of [targetEntityId, componentData] pairs for all matching relations
+   */
+  get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][];
+  /**
+   * Get component data for a specific entity and component type
+   * @param entityId The entity
+   * @param componentType The component type
+   * @returns The component data
+   */
+  get<T>(entityId: EntityId, componentType: EntityId<T>): T;
+  /**
+   * Register a system with optional dependencies
+   */
+  registerSystem(system: System<UpdateParams>, additionalDeps?: System<UpdateParams>[]): void;
+  /**
+   * Register a lifecycle hook for component or wildcard relation events
+   */
+  hook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
+  /**
+   * Unregister a lifecycle hook for component or wildcard relation events
+   */
+  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
+   */
+  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
+   */
+  setCascadeDelete(componentId: EntityId): void;
+  /**
+   * Update the world (run all systems in dependency order)
+   * This function is synchronous when all systems are synchronous,
+   * and asynchronous (returns a Promise) when any system is asynchronous.
+   */
+  update(...params: UpdateParams): Promise<void> | void;
+  /**
+   * Execute all deferred commands immediately without running systems
+   */
+  sync(): void;
+  /**
+   * Create a cached query for efficient entity lookups
+   * @returns A Query object for the specified component types and filter
+   */
+  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;
+  /**
+   * Release a query reference obtained from createQuery.
+   * Decrements the refCount and fully disposes the query when it reaches zero.
+   */
+  releaseQuery(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
+   * @returns Array of entity IDs that have all the specified components
+   */
+  query(componentTypes: EntityId<any>[]): EntityId[];
+  query<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)
+   * @returns ComponentChangeset describing the changes made
+   */
+  executeEntityCommands(entityId: EntityId, commands: Command[]): ComponentChangeset;
+  /**
+   * Get or create an archetype for the given component types
+   * @returns The archetype for the given component types
+   */
+  private ensureArchetype;
+  /**
+   * 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
+   * @param componentType The component type (which may be an entity ID used as component type)
+   * @param targetEntityId The entity being used as component type
+   */
+  private trackEntityReference;
+  /**
+   * Remove a component reference from the reverse index
+   * @param sourceEntityId The entity that has the component
+   * @param componentType The component type
+   * @param targetEntityId The entity being used as component type
+   */
+  private untrackEntityReference;
+  /**
+   * Get all component references where a target entity is used as a component type
+   * @param targetEntityId The target entity
+   * @returns A MultiMap of sourceEntityId to componentTypes that reference the target entity
+   */
+  private getEntityReferences;
+  /**
+   * Remove an empty archetype from all internal data structures
+   */
+  private cleanupEmptyArchetype;
+  /**
+   * Execute component lifecycle hooks for added and removed components
+   */
+  private triggerLifecycleHooks;
+  /**
+   * Convert the world into a plain snapshot object.
+   * This returns an in-memory structure and does not perform JSON stringification.
+   * Component values are stored as-is (they may be non-JSON-serializable).
+   */
+  serialize(): SerializedWorld;
+}
+type SerializedWorld = {
+  version: number;
+  entityManager: any;
+  entities: SerializedEntity[];
+};
+type SerializedEntity = {
+  id: number;
+  components: SerializedComponent[];
+};
+type SerializedComponent = {
+  type: number | string | {
+    component: string;
+    target: number | string;
+  };
+  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 };
+//# sourceMappingURL=index.d.mts.map