@codehz/ecs 0.3.14 → 0.4.0

package/world.d.mts

@@ -0,0 +1,766 @@
+//#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>;
+/**
+ * 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";
+};
+/**
+ * Component options that define intrinsic properties
+ */
+interface ComponentOptions {
+  /**
+   * Optional name for the component (for serialization/debugging)
+   */
+  name?: string;
+  /**
+   * 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.
+   */
+  exclusive?: boolean;
+  /**
+   * 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.
+   */
+  cascadeDelete?: boolean;
+  /**
+   * 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.
+   */
+  dontFragment?: boolean;
+}
+/**
+ * Allocate a new component ID from the global allocator.
+ * @param nameOrOptions Optional name for the component (for serialization/debugging) or options object
+ * @returns The allocated component ID
+ * @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
+ * @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>;
+};
+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
+/**
+ * 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;
+  /**
+   * 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
+   * 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
+   * @param dontFragmentRelations Reference to the World's dontFragmentRelations storage
+   */
+  constructor(componentTypes: EntityId<any>[], dontFragmentRelations: Map<EntityId, Map<EntityId<any>, 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 (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 (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 (includes both regular and dontFragment components)
+   */
+  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 (includes both regular and dontFragment components)
+   */
+  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;
+  /**
+   * 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
+   * @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;
+  /**
+   * Check if any entity in this archetype has a relation matching the given component ID
+   * This includes both regular relations in componentTypes and dontFragment relations
+   * @param componentId The component ID to match
+   * @returns true if any entity has a matching relation
+   */
+  hasRelationWithComponentId(componentId: EntityId<any>): boolean;
+}
+//#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, componentTypes: EntityId<any>[], filter?: QueryFilter);
+  /**
+   * Check if query is disposed and throw error if so
+   */
+  private ensureNotDisposed;
+  /**
+   * 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/world.d.ts
+/**
+ * World class for ECS architecture
+ * Manages entities and components
+ */
+declare class World {
+  /** 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;
+  /** 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 */
+  private queryCache;
+  /** Buffers structural changes for deferred execution */
+  private commandBuffer;
+  /** Stores lifecycle hooks for component and relation events */
+  private hooks;
+  /**
+   * 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 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;
+  /**
+   * Execute all deferred commands immediately
+   */
+  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;
+  /**
+   * 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;
+  private isRelationWithComponent;
+  /**
+   * Process a delete command, handling wildcard relations
+   */
+  private processDeleteCommand;
+  /**
+   * Remove all relations matching a wildcard component ID
+   */
+  private removeWildcardRelations;
+  /**
+   * Remove a single component from an entity immediately, handling dontFragment relations correctly.
+   * Used by destroyEntityImmediate for non-cascade relation cleanup.
+   */
+  private removeComponentImmediate;
+  /**
+   * 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;
+  /**
+   * Apply dontFragment relation changes directly to World's storage
+   * This is much more efficient than the removeEntity + addEntity approach
+   */
+  private applyDontFragmentChanges;
+  /**
+   * Update entity reference tracking based on changeset
+   */
+  private updateEntityReferences;
+  /**
+   * Get or create an 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;
+  /**
+   * Compare two arrays of component types for equality (order-independent)
+   */
+  private areComponentTypesEqual;
+  /**
+   * Filter out dontFragment relations from component types, but keep wildcard markers
+   */
+  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
+   * @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;
+  /**
+   * Check if an archetype's signature references a specific entity
+   * (via entity-relation targeting the entity, or using entity as component type)
+   */
+  private archetypeReferencesEntity;
+  /**
+   * Cleanup empty archetypes that reference a specific deleted entity
+   * Only removes archetypes whose component types reference the entity
+   */
+  private cleanupArchetypesReferencingEntity;
+  /**
+   * 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
+   */
+  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
+export { relation as S, getComponentNameById as _, ComponentType as a, isRelationId as b, ComponentOptions as c, EntityRelationId as d, RelationId as f, getComponentIdByName as g, decodeRelationId as h, ComponentTuple as i, ComponentRelationId as l, component as m, World as n, LifecycleHook as o, WildcardRelationId as p, Query as r, ComponentId as s, SerializedWorld as t, EntityId as u, isComponentId as v, isWildcardRelationId as x, isEntityId as y };
+//# sourceMappingURL=world.d.mts.map