@codehz/ecs 0.3.7 → 0.3.9

package/index.mjs

@@ -0,0 +1,1881 @@
+//#region src/entity.ts
+const COMPONENT_ID_MAX = 1023;
+const ENTITY_ID_START = 1024;
+/**
+* Constants for relation ID encoding
+*/
+const RELATION_SHIFT = 2 ** 42;
+const WILDCARD_TARGET_ID = 0;
+function relation(componentId, targetId) {
+	if (!isComponentId(componentId)) throw new Error("First argument must be a valid component ID");
+	let actualTargetId;
+	if (targetId === "*") actualTargetId = WILDCARD_TARGET_ID;
+	else {
+		if (!isEntityId(targetId) && !isComponentId(targetId)) throw new Error("Second argument must be a valid entity ID, component ID, or '*'");
+		actualTargetId = targetId;
+	}
+	return -(componentId * RELATION_SHIFT + actualTargetId);
+}
+/**
+* Check if an ID is a component ID
+*/
+function isComponentId(id) {
+	return id >= 1 && id <= COMPONENT_ID_MAX;
+}
+/**
+* Check if an ID is an entity ID
+*/
+function isEntityId(id) {
+	return id >= ENTITY_ID_START;
+}
+/**
+* Check if an ID is a relation ID
+*/
+function isRelationId(id) {
+	return id < 0;
+}
+/**
+* Check if an ID is a wildcard relation id
+*/
+function isWildcardRelationId(id) {
+	if (!isRelationId(id)) return false;
+	return -id % RELATION_SHIFT === WILDCARD_TARGET_ID;
+}
+/**
+* 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
+*/
+function decodeRelationId(relationId) {
+	if (!isRelationId(relationId)) throw new Error("ID is not a relation ID");
+	const absId = -relationId;
+	const componentId = Math.floor(absId / RELATION_SHIFT);
+	const targetId = absId % RELATION_SHIFT;
+	if (targetId === WILDCARD_TARGET_ID) return {
+		componentId,
+		targetId,
+		type: "wildcard"
+	};
+	else if (isEntityId(targetId)) return {
+		componentId,
+		targetId,
+		type: "entity"
+	};
+	else if (isComponentId(targetId)) return {
+		componentId,
+		targetId,
+		type: "component"
+	};
+	else throw new Error("Invalid target ID in relation");
+}
+/**
+* Get the string representation of an ID type
+*/
+function getIdType(id) {
+	if (isComponentId(id)) return "component";
+	if (isEntityId(id)) return "entity";
+	if (isRelationId(id)) try {
+		const decoded = decodeRelationId(id);
+		if (!isComponentId(decoded.componentId) || decoded.type !== "wildcard" && !isEntityId(decoded.targetId) && !isComponentId(decoded.targetId)) return "invalid";
+		switch (decoded.type) {
+			case "entity": return "entity-relation";
+			case "component": return "component-relation";
+			case "wildcard": return "wildcard-relation";
+		}
+	} catch (error) {
+		return "invalid";
+	}
+	return "invalid";
+}
+/**
+* Get detailed type information for an EntityId
+* @param id The EntityId to analyze
+* @returns Detailed type information including relation subtypes
+*/
+function getDetailedIdType(id) {
+	if (isComponentId(id)) return { type: "component" };
+	if (isEntityId(id)) return { type: "entity" };
+	if (isRelationId(id)) try {
+		const decoded = decodeRelationId(id);
+		if (!isComponentId(decoded.componentId) || decoded.type !== "wildcard" && !isEntityId(decoded.targetId) && !isComponentId(decoded.targetId)) return { type: "invalid" };
+		let type;
+		switch (decoded.type) {
+			case "entity":
+				type = "entity-relation";
+				break;
+			case "component":
+				type = "component-relation";
+				break;
+			case "wildcard":
+				type = "wildcard-relation";
+				break;
+		}
+		return {
+			type,
+			componentId: decoded.componentId,
+			targetId: decoded.targetId
+		};
+	} catch (error) {
+		return { type: "invalid" };
+	}
+	return { type: "invalid" };
+}
+/**
+* Entity ID Manager for automatic allocation and freelist recycling
+*/
+var EntityIdManager = class {
+	nextId = ENTITY_ID_START;
+	freelist = /* @__PURE__ */ new Set();
+	/**
+	* Allocate a new entity ID
+	* Uses freelist if available, otherwise increments counter
+	*/
+	allocate() {
+		if (this.freelist.size > 0) {
+			const id = this.freelist.values().next().value;
+			this.freelist.delete(id);
+			return id;
+		} else {
+			const id = this.nextId;
+			this.nextId++;
+			if (this.nextId >= Number.MAX_SAFE_INTEGER) throw new Error("Entity ID overflow: reached maximum safe integer");
+			return id;
+		}
+	}
+	/**
+	* Deallocate an entity ID, adding it to the freelist for reuse
+	* @param id The entity ID to deallocate
+	*/
+	deallocate(id) {
+		if (!isEntityId(id)) throw new Error("Can only deallocate valid entity IDs");
+		if (id >= this.nextId) throw new Error("Cannot deallocate an ID that was never allocated");
+		this.freelist.add(id);
+	}
+	/**
+	* Get the current freelist size (for debugging/monitoring)
+	*/
+	getFreelistSize() {
+		return this.freelist.size;
+	}
+	/**
+	* Get the next ID that would be allocated (for debugging)
+	*/
+	getNextId() {
+		return this.nextId;
+	}
+	/**
+	* Serialize internal state for persistence.
+	* Returns a plain object representing allocator state. Values may be non-JSON-serializable.
+	*/
+	serializeState() {
+		return {
+			nextId: this.nextId,
+			freelist: Array.from(this.freelist)
+		};
+	}
+	/**
+	* Restore internal state from a previously-serialized object.
+	* Overwrites the current nextId and freelist.
+	*/
+	deserializeState(state) {
+		if (typeof state.nextId !== "number") throw new Error("Invalid state for EntityIdManager.deserializeState");
+		this.nextId = state.nextId;
+		this.freelist = new Set(state.freelist || []);
+	}
+};
+/**
+* Component ID Manager for automatic allocation
+* Components are typically registered once and not recycled
+*/
+var ComponentIdAllocator = class {
+	nextId = 1;
+	/**
+	* Allocate a new component ID
+	* Increments counter sequentially from 1
+	*/
+	allocate() {
+		if (this.nextId > COMPONENT_ID_MAX) throw new Error(`Component ID overflow: maximum ${COMPONENT_ID_MAX} components allowed`);
+		const id = this.nextId;
+		this.nextId++;
+		return id;
+	}
+	/**
+	* Get the next ID that would be allocated (for debugging)
+	*/
+	getNextId() {
+		return this.nextId;
+	}
+	/**
+	* Check if more component IDs are available
+	*/
+	hasAvailableIds() {
+		return this.nextId <= COMPONENT_ID_MAX;
+	}
+};
+const globalComponentIdAllocator = new ComponentIdAllocator();
+const ComponentNames = /* @__PURE__ */ new Map();
+const ComponentIdForNames = /* @__PURE__ */ new Map();
+const ComponentOptions = /* @__PURE__ */ new Map();
+/**
+* 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 });
+*/
+function component(nameOrOptions) {
+	const id = globalComponentIdAllocator.allocate();
+	let name;
+	let options;
+	if (typeof nameOrOptions === "string") name = nameOrOptions;
+	else if (typeof nameOrOptions === "object" && nameOrOptions !== null) {
+		options = nameOrOptions;
+		name = options.name;
+	}
+	if (name) {
+		if (ComponentIdForNames.has(name)) throw new Error(`Component name "${name}" is already registered`);
+		ComponentNames.set(id, name);
+		ComponentIdForNames.set(name, id);
+	}
+	if (options) ComponentOptions.set(id, options);
+	return id;
+}
+/**
+* Get a component ID by its registered name
+* @param name The component name
+* @returns The component ID if found, undefined otherwise
+*/
+function getComponentIdByName(name) {
+	return ComponentIdForNames.get(name);
+}
+/** Get a component name by its ID
+* @param id The component ID
+* @returns The component name if found, undefined otherwise
+*/
+function getComponentNameById(id) {
+	return ComponentNames.get(id);
+}
+/**
+* Check if a component is marked as exclusive
+* @param id The component ID
+* @returns true if the component is exclusive, false otherwise
+*/
+function isExclusiveComponent(id) {
+	return ComponentOptions.get(id)?.exclusive ?? false;
+}
+/**
+* Check if a component is marked as cascade delete
+* @param id The component ID
+* @returns true if the component is cascade delete, false otherwise
+*/
+function isCascadeDeleteComponent(id) {
+	return ComponentOptions.get(id)?.cascadeDelete ?? false;
+}
+/**
+* Check if a component is marked as dontFragment
+* @param id The component ID
+* @returns true if the component is dontFragment, false otherwise
+*/
+function isDontFragmentComponent(id) {
+	return ComponentOptions.get(id)?.dontFragment ?? false;
+}
+
+//#endregion
+//#region src/types.ts
+function isOptionalEntityId(type) {
+	return typeof type === "object" && type !== null && "optional" in type;
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* 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
+*/
+function getOrComputeCache(cache, key, compute) {
+	let value = cache.get(key);
+	if (value === void 0) {
+		value = compute();
+		cache.set(key, value);
+	}
+	return value;
+}
+/**
+* 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
+*/
+function getOrCreateWithSideEffect(cache, key, create) {
+	let value = cache.get(key);
+	if (value === void 0) {
+		value = create();
+		cache.set(key, value);
+	}
+	return value;
+}
+
+//#endregion
+//#region src/archetype.ts
+/**
+* Special value to represent missing component data
+*/
+const MISSING_COMPONENT = Symbol("missing component");
+/**
+* Archetype class for ECS architecture
+* Represents a group of entities that share the same set of components
+* Optimized for fast iteration and component access
+*/
+var Archetype = class {
+	/**
+	* The component types that define this archetype
+	*/
+	componentTypes;
+	/**
+	* List of entities in this archetype
+	*/
+	entities = [];
+	/**
+	* Component data storage - maps component type to array of component data
+	* Each array index corresponds to the entity index in the entities array
+	*/
+	componentData = /* @__PURE__ */ new Map();
+	/**
+	* Reverse mapping from entity to its index in this archetype
+	*/
+	entityToIndex = /* @__PURE__ */ new Map();
+	/**
+	* 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
+	*/
+	dontFragmentRelations;
+	/**
+	* Cache for pre-computed component data sources to avoid repeated calculations
+	* For regular components: data array
+	* For wildcards: matching relation types array
+	*/
+	componentDataSourcesCache = /* @__PURE__ */ new Map();
+	/**
+	* 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, dontFragmentRelations) {
+		this.componentTypes = [...componentTypes].sort((a, b) => a - b);
+		this.dontFragmentRelations = dontFragmentRelations;
+		for (const componentType of this.componentTypes) this.componentData.set(componentType, []);
+	}
+	/**
+	* Get the number of entities in this archetype
+	*/
+	get size() {
+		return this.entities.length;
+	}
+	/**
+	* Check if this archetype matches the given component types
+	* @param componentTypes The component types to check
+	*/
+	matches(componentTypes) {
+		if (this.componentTypes.length !== componentTypes.length) return false;
+		const sortedTypes = [...componentTypes].sort((a, b) => a - b);
+		return this.componentTypes.every((type, index) => type === sortedTypes[index]);
+	}
+	/**
+	* 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, componentData) {
+		if (this.entityToIndex.has(entityId)) throw new Error(`Entity ${entityId} is already in this archetype`);
+		const index = this.entities.length;
+		this.entities.push(entityId);
+		this.entityToIndex.set(entityId, index);
+		for (const componentType of this.componentTypes) {
+			const data = componentData.get(componentType);
+			this.getComponentData(componentType).push(data === void 0 ? MISSING_COMPONENT : data);
+		}
+		const dontFragmentData = /* @__PURE__ */ new Map();
+		for (const [componentType, data] of componentData) {
+			if (this.componentTypes.includes(componentType)) continue;
+			const detailedType = getDetailedIdType(componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) dontFragmentData.set(componentType, data);
+		}
+		if (dontFragmentData.size > 0) this.dontFragmentRelations.set(entityId, dontFragmentData);
+	}
+	/**
+	* 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) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) return;
+		const entityData = /* @__PURE__ */ new Map();
+		for (const componentType of this.componentTypes) {
+			const data = this.getComponentData(componentType)[index];
+			entityData.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
+		}
+		const dontFragmentData = this.dontFragmentRelations.get(entityId);
+		if (dontFragmentData) for (const [componentType, data] of dontFragmentData) entityData.set(componentType, data);
+		return entityData;
+	}
+	/**
+	* 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() {
+		const result = [];
+		for (let i = 0; i < this.entities.length; i++) {
+			const entity = this.entities[i];
+			const components = /* @__PURE__ */ new Map();
+			for (const componentType of this.componentTypes) {
+				const data = this.getComponentData(componentType)[i];
+				components.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
+			}
+			const dontFragmentData = this.dontFragmentRelations.get(entity);
+			if (dontFragmentData) for (const [componentType, data] of dontFragmentData) components.set(componentType, data);
+			result.push({
+				entity,
+				components
+			});
+		}
+		return result;
+	}
+	/**
+	* 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) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) return;
+		const removedData = /* @__PURE__ */ new Map();
+		for (const componentType of this.componentTypes) {
+			const dataArray = this.getComponentData(componentType);
+			removedData.set(componentType, dataArray[index]);
+		}
+		const dontFragmentData = this.dontFragmentRelations.get(entityId);
+		if (dontFragmentData) {
+			for (const [componentType, data] of dontFragmentData) removedData.set(componentType, data);
+			this.dontFragmentRelations.delete(entityId);
+		}
+		this.entityToIndex.delete(entityId);
+		const lastIndex = this.entities.length - 1;
+		if (index !== lastIndex) {
+			const lastEntity = this.entities[lastIndex];
+			this.entities[index] = lastEntity;
+			this.entityToIndex.set(lastEntity, index);
+			for (const componentType of this.componentTypes) {
+				const dataArray = this.getComponentData(componentType);
+				dataArray[index] = dataArray[lastIndex];
+			}
+		}
+		this.entities.pop();
+		for (const componentType of this.componentTypes) this.getComponentData(componentType).pop();
+		return removedData;
+	}
+	/**
+	* Check if an entity is in this archetype
+	* @param entityId The entity to check
+	*/
+	exists(entityId) {
+		return this.entityToIndex.has(entityId);
+	}
+	get(entityId, componentType) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
+		if (isWildcardRelationId(componentType)) {
+			const componentId = decodeRelationId(componentType).componentId;
+			const relations = [];
+			for (const relType of this.componentTypes) {
+				const relDetailed = getDetailedIdType(relType);
+				if ((relDetailed.type === "entity-relation" || relDetailed.type === "component-relation") && relDetailed.componentId === componentId) {
+					const dataArray = this.getComponentData(relType);
+					if (dataArray && dataArray[index] !== void 0) {
+						const data = dataArray[index];
+						relations.push([relDetailed.targetId, data === MISSING_COMPONENT ? void 0 : data]);
+					}
+				}
+			}
+			const dontFragmentData = this.dontFragmentRelations.get(entityId);
+			if (dontFragmentData) for (const [relType, data] of dontFragmentData) {
+				const relDetailed = getDetailedIdType(relType);
+				if ((relDetailed.type === "entity-relation" || relDetailed.type === "component-relation") && relDetailed.componentId === componentId) relations.push([relDetailed.targetId, data]);
+			}
+			return relations;
+		} else {
+			if (this.componentTypes.includes(componentType)) {
+				const data = this.getComponentData(componentType)[index];
+				return data === MISSING_COMPONENT ? void 0 : data;
+			}
+			const dontFragmentData = this.dontFragmentRelations.get(entityId);
+			if (dontFragmentData && dontFragmentData.has(componentType)) return dontFragmentData.get(componentType);
+			throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
+		}
+	}
+	/**
+	* 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(entityId, componentType, data) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
+		if (this.componentData.has(componentType)) {
+			const dataArray = this.getComponentData(componentType);
+			dataArray[index] = data;
+			return;
+		}
+		const detailedType = getDetailedIdType(componentType);
+		if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) {
+			let dontFragmentData = this.dontFragmentRelations.get(entityId);
+			if (!dontFragmentData) {
+				dontFragmentData = /* @__PURE__ */ new Map();
+				this.dontFragmentRelations.set(entityId, dontFragmentData);
+			}
+			dontFragmentData.set(componentType, data);
+			return;
+		}
+		throw new Error(`Component type ${componentType} is not in this archetype`);
+	}
+	/**
+	* Get all entities in this archetype
+	*/
+	getEntities() {
+		return this.entities;
+	}
+	/**
+	* Get the mapping of entities to their indices in this archetype
+	*/
+	getEntityToIndexMap() {
+		return this.entityToIndex;
+	}
+	/**
+	* Get component data for all entities of a specific component type
+	* @param componentType The component type
+	*/
+	getComponentData(componentType) {
+		const data = this.componentData.get(componentType);
+		if (!data) throw new Error(`Component type ${componentType} is not in this archetype`);
+		return data;
+	}
+	/**
+	* 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(componentType) {
+		return this.componentData.get(componentType);
+	}
+	/**
+	* Helper: compute or return cached data sources for provided componentTypes
+	*/
+	getCachedComponentDataSources(componentTypes) {
+		const cacheKey = this.buildCacheKey(componentTypes);
+		return getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => componentTypes.map((compType) => this.getComponentDataSource(compType)));
+	}
+	/**
+	* Build cache key for component types
+	*/
+	buildCacheKey(componentTypes) {
+		return componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).join(",");
+	}
+	/**
+	* Get data source for a single component type
+	*/
+	getComponentDataSource(compType) {
+		const optional = isOptionalEntityId(compType);
+		const actualType = optional ? compType.optional : compType;
+		const detailedType = getDetailedIdType(actualType);
+		if (detailedType.type === "wildcard-relation") return this.getWildcardRelationDataSource(detailedType.componentId, optional);
+		else return optional ? this.getOptionalComponentData(actualType) : this.getComponentData(actualType);
+	}
+	/**
+	* Get data source for wildcard relations
+	*/
+	getWildcardRelationDataSource(componentId, optional) {
+		const matchingRelations = this.componentTypes.filter((ct) => {
+			const detailedCt = getDetailedIdType(ct);
+			return (detailedCt.type === "entity-relation" || detailedCt.type === "component-relation") && detailedCt.componentId === componentId;
+		});
+		return optional ? matchingRelations.length > 0 ? matchingRelations : void 0 : matchingRelations;
+	}
+	/**
+	* Helper: build component tuples for a specific entity index using precomputed data sources
+	*/
+	buildComponentsForIndex(componentTypes, componentDataSources, entityIndex) {
+		return componentDataSources.map((dataSource, i) => {
+			const compType = componentTypes[i];
+			return this.buildSingleComponent(compType, dataSource, entityIndex);
+		});
+	}
+	/**
+	* Build a single component value from its data source
+	*/
+	buildSingleComponent(compType, dataSource, entityIndex) {
+		const optional = isOptionalEntityId(compType);
+		if (getIdType(optional ? compType.optional : compType) === "wildcard-relation") return this.buildWildcardRelationValue(dataSource, entityIndex, optional);
+		else return this.buildRegularComponentValue(dataSource, entityIndex, optional);
+	}
+	/**
+	* Build wildcard relation value from matching relations
+	*/
+	buildWildcardRelationValue(dataSource, entityIndex, optional) {
+		if (dataSource === void 0) {
+			if (optional) return;
+			throw new Error(`No matching relations found for mandatory wildcard relation component type`);
+		}
+		const matchingRelations = dataSource;
+		const relations = [];
+		for (const relType of matchingRelations) {
+			const data = this.getComponentData(relType)[entityIndex];
+			const decodedRel = decodeRelationId(relType);
+			relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? void 0 : data]);
+		}
+		return optional ? { value: relations } : relations;
+	}
+	/**
+	* Build regular component value from data source
+	*/
+	buildRegularComponentValue(dataSource, entityIndex, optional) {
+		if (dataSource === void 0) {
+			if (optional) return;
+			throw new Error(`Component data not found for mandatory component type`);
+		}
+		const data = dataSource[entityIndex];
+		const result = data === MISSING_COMPONENT ? void 0 : data;
+		return optional ? { value: result } : result;
+	}
+	/**
+	* 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(componentTypes) {
+		const result = [];
+		this.forEachWithComponents(componentTypes, (entity, ...components) => {
+			result.push({
+				entity,
+				components
+			});
+		});
+		return result;
+	}
+	/**
+	* 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(componentTypes) {
+		const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+		for (let entityIndex = 0; entityIndex < this.entities.length; entityIndex++) yield [this.entities[entityIndex], ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex)];
+	}
+	/**
+	* 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(componentTypes, callback) {
+		const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+		for (let entityIndex = 0; entityIndex < this.entities.length; entityIndex++) {
+			const entity = this.entities[entityIndex];
+			callback(entity, ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex));
+		}
+	}
+	/**
+	* Iterate over all entities with their component data
+	* @param callback Function called for each entity with its component data
+	*/
+	forEach(callback) {
+		for (let i = 0; i < this.entities.length; i++) {
+			const components = /* @__PURE__ */ new Map();
+			for (const componentType of this.componentTypes) {
+				const data = this.getComponentData(componentType)[i];
+				components.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
+			}
+			callback(this.entities[i], components);
+		}
+	}
+};
+
+//#endregion
+//#region src/changeset.ts
+/**
+* @internal Represents a set of component changes to be applied to an entity
+*/
+var ComponentChangeset = class {
+	adds = /* @__PURE__ */ new Map();
+	removes = /* @__PURE__ */ new Set();
+	/**
+	* Add a component to the changeset
+	*/
+	set(componentType, component$1) {
+		this.adds.set(componentType, component$1);
+		this.removes.delete(componentType);
+	}
+	/**
+	* Remove a component from the changeset
+	*/
+	delete(componentType) {
+		this.removes.add(componentType);
+		this.adds.delete(componentType);
+	}
+	/**
+	* Check if the changeset has any changes
+	*/
+	hasChanges() {
+		return this.adds.size > 0 || this.removes.size > 0;
+	}
+	/**
+	* Clear all changes
+	*/
+	clear() {
+		this.adds.clear();
+		this.removes.clear();
+	}
+	/**
+	* Merge another changeset into this one
+	*/
+	merge(other) {
+		for (const [componentType, component$1] of other.adds) {
+			this.adds.set(componentType, component$1);
+			this.removes.delete(componentType);
+		}
+		for (const componentType of other.removes) {
+			this.removes.add(componentType);
+			this.adds.delete(componentType);
+		}
+	}
+	/**
+	* Apply the changeset to existing components and return the final state
+	*/
+	applyTo(existingComponents) {
+		for (const componentType of this.removes) existingComponents.delete(componentType);
+		for (const [componentType, component$1] of this.adds) existingComponents.set(componentType, component$1);
+		return existingComponents;
+	}
+	/**
+	* 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) {
+		const finalComponentTypes = new Set(existingComponentTypes);
+		let changed = false;
+		for (const componentType of this.removes) {
+			if (!finalComponentTypes.has(componentType)) {
+				this.removes.delete(componentType);
+				continue;
+			}
+			changed = true;
+			finalComponentTypes.delete(componentType);
+		}
+		for (const componentType of this.adds.keys()) {
+			if (finalComponentTypes.has(componentType)) continue;
+			changed = true;
+			finalComponentTypes.add(componentType);
+		}
+		return changed ? Array.from(finalComponentTypes) : void 0;
+	}
+};
+
+//#endregion
+//#region src/command-buffer.ts
+/**
+* Command buffer for deferred structural changes
+*/
+var CommandBuffer = class {
+	commands = [];
+	executeEntityCommands;
+	/**
+	* Create a command buffer with an executor function
+	*/
+	constructor(executeEntityCommands) {
+		this.executeEntityCommands = executeEntityCommands;
+	}
+	set(entityId, componentType, component$1) {
+		this.commands.push({
+			type: "set",
+			entityId,
+			componentType,
+			component: component$1
+		});
+	}
+	/**
+	* Remove a component from an entity (deferred)
+	*/
+	remove(entityId, componentType) {
+		this.commands.push({
+			type: "delete",
+			entityId,
+			componentType
+		});
+	}
+	/**
+	* Destroy an entity (deferred)
+	*/
+	delete(entityId) {
+		this.commands.push({
+			type: "destroy",
+			entityId
+		});
+	}
+	/**
+	* Execute all commands and clear the buffer
+	*/
+	execute() {
+		const MAX_ITERATIONS = 100;
+		let iterations = 0;
+		while (this.commands.length > 0) {
+			if (iterations >= MAX_ITERATIONS) throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
+			iterations++;
+			const currentCommands = [...this.commands];
+			this.commands = [];
+			const entityCommands = /* @__PURE__ */ new Map();
+			for (const cmd of currentCommands) {
+				if (!entityCommands.has(cmd.entityId)) entityCommands.set(cmd.entityId, []);
+				entityCommands.get(cmd.entityId).push(cmd);
+			}
+			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
+		}
+	}
+	/**
+	* Get current commands (for testing)
+	*/
+	getCommands() {
+		return [...this.commands];
+	}
+	/**
+	* Clear all commands
+	*/
+	clear() {
+		this.commands = [];
+	}
+};
+
+//#endregion
+//#region src/multi-map.ts
+var MultiMap = class {
+	map = /* @__PURE__ */ new Map();
+	_valueCount = 0;
+	get valueCount() {
+		return this._valueCount;
+	}
+	get keyCount() {
+		return this.map.size;
+	}
+	hasKey(key) {
+		return this.map.has(key);
+	}
+	has(key, value) {
+		const set = this.map.get(key);
+		if (!set) return false;
+		if (arguments.length === 1) return true;
+		return set.has(value);
+	}
+	add(key, value) {
+		let set = this.map.get(key);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.map.set(key, set);
+		}
+		if (!set.has(value)) {
+			set.add(value);
+			this._valueCount++;
+		}
+	}
+	remove(key, value) {
+		const set = this.map.get(key);
+		if (!set) return false;
+		if (!set.has(value)) return false;
+		set.delete(value);
+		this._valueCount--;
+		if (set.size === 0) this.map.delete(key);
+		return true;
+	}
+	deleteKey(key) {
+		const set = this.map.get(key);
+		if (!set) return false;
+		this._valueCount -= set.size;
+		this.map.delete(key);
+		return true;
+	}
+	get(key) {
+		const set = this.map.get(key);
+		return set ? new Set(set) : /* @__PURE__ */ new Set();
+	}
+	*keys() {
+		yield* this.map.keys();
+	}
+	*values() {
+		for (const set of this.map.values()) for (const v of set) yield v;
+	}
+	[Symbol.iterator]() {
+		return this.entries();
+	}
+	*entries() {
+		for (const [k, set] of this.map.entries()) for (const v of set) yield [k, v];
+	}
+	clear() {
+		this.map.clear();
+		this._valueCount = 0;
+	}
+};
+
+//#endregion
+//#region src/query-filter.ts
+/**
+* Serialize a QueryFilter into a deterministic string suitable for cache keys.
+* Currently only serializes `negativeComponentTypes`.
+*/
+function serializeQueryFilter(filter = {}) {
+	const negative = (filter.negativeComponentTypes || []).slice().sort((a, b) => a - b);
+	if (negative.length === 0) return "";
+	return `neg:${negative.join(",")}`;
+}
+/**
+* Check if an archetype matches the given component types
+*/
+function matchesComponentTypes(archetype, componentTypes) {
+	return componentTypes.every((type) => {
+		const detailedType = getDetailedIdType(type);
+		if (detailedType.type === "wildcard-relation") return archetype.componentTypes.some((archetypeType) => {
+			if (!isRelationId(archetypeType)) return false;
+			return decodeRelationId(archetypeType).componentId === detailedType.componentId;
+		});
+		else return archetype.componentTypes.includes(type);
+	});
+}
+/**
+* Check if an archetype matches the filter conditions (only filtering logic)
+*/
+function matchesFilter(archetype, filter) {
+	return (filter.negativeComponentTypes || []).every((type) => {
+		const detailedType = getDetailedIdType(type);
+		if (detailedType.type === "wildcard-relation") return !archetype.componentTypes.some((archetypeType) => {
+			if (!isRelationId(archetypeType)) return false;
+			return decodeRelationId(archetypeType).componentId === detailedType.componentId;
+		});
+		else return !archetype.componentTypes.includes(type);
+	});
+}
+
+//#endregion
+//#region src/query.ts
+/**
+* Query class for efficient entity queries with cached archetypes
+*/
+var Query = class {
+	world;
+	componentTypes;
+	filter;
+	cachedArchetypes = [];
+	isDisposed = false;
+	constructor(world, componentTypes, filter = {}) {
+		this.world = world;
+		this.componentTypes = [...componentTypes].sort((a, b) => a - b);
+		this.filter = filter;
+		this.updateCache();
+		world._registerQuery(this);
+	}
+	/**
+	* Check if query is disposed and throw error if so
+	*/
+	ensureNotDisposed() {
+		if (this.isDisposed) throw new Error("Query has been disposed");
+	}
+	/**
+	* Get all entities matching the query
+	*/
+	getEntities() {
+		this.ensureNotDisposed();
+		const result = [];
+		for (const archetype of this.cachedArchetypes) result.push(...archetype.getEntities());
+		return result;
+	}
+	/**
+	* Get entities with their component data
+	* @param componentTypes Array of component types to retrieve
+	* @returns Array of objects with entity and component data
+	*/
+	getEntitiesWithComponents(componentTypes) {
+		this.ensureNotDisposed();
+		const result = [];
+		for (const archetype of this.cachedArchetypes) {
+			const entitiesWithData = archetype.getEntitiesWithComponents(componentTypes);
+			result.push(...entitiesWithData);
+		}
+		return result;
+	}
+	/**
+	* 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(componentTypes, callback) {
+		this.ensureNotDisposed();
+		for (const archetype of this.cachedArchetypes) archetype.forEachWithComponents(componentTypes, callback);
+	}
+	/**
+	* Iterate over entities with their component data (generator)
+	* @param componentTypes Array of component types to retrieve
+	*/
+	*iterate(componentTypes) {
+		this.ensureNotDisposed();
+		for (const archetype of this.cachedArchetypes) yield* archetype.iterateWithComponents(componentTypes);
+	}
+	/**
+	* 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(componentType) {
+		this.ensureNotDisposed();
+		const result = [];
+		for (const archetype of this.cachedArchetypes) result.push(...archetype.getComponentData(componentType));
+		return result;
+	}
+	/**
+	* Update the cached archetypes
+	* Called when new archetypes are created
+	*/
+	updateCache() {
+		if (this.isDisposed) return;
+		this.cachedArchetypes = this.world.getMatchingArchetypes(this.componentTypes).filter((archetype) => matchesFilter(archetype, this.filter));
+	}
+	/**
+	* Check if a new archetype matches this query and add to cache if it does
+	*/
+	checkNewArchetype(archetype) {
+		if (this.isDisposed) return;
+		if (matchesComponentTypes(archetype, this.componentTypes) && matchesFilter(archetype, this.filter) && !this.cachedArchetypes.includes(archetype)) this.cachedArchetypes.push(archetype);
+	}
+	/**
+	* Remove an archetype from the cached archetypes
+	*/
+	removeArchetype(archetype) {
+		if (this.isDisposed) return;
+		const index = this.cachedArchetypes.indexOf(archetype);
+		if (index !== -1) this.cachedArchetypes.splice(index, 1);
+	}
+	/**
+	* 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() {
+		this.world.releaseQuery(this);
+	}
+	/**
+	* Internal full dispose called by World when refCount reaches zero.
+	*/
+	_disposeInternal() {
+		if (!this.isDisposed) {
+			this.world._unregisterQuery(this);
+			this.cachedArchetypes = [];
+			this.isDisposed = true;
+		}
+	}
+	/**
+	* Symbol.dispose implementation for automatic resource management
+	*/
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	/**
+	* Check if the query has been disposed
+	*/
+	get disposed() {
+		return this.isDisposed;
+	}
+};
+
+//#endregion
+//#region src/system-scheduler.ts
+/**
+* System Scheduler for managing system dependencies and execution order
+*/
+var SystemScheduler = class {
+	systems = /* @__PURE__ */ new Set();
+	systemDependencies = /* @__PURE__ */ new Map();
+	cachedExecutionOrder = null;
+	/**
+	* Add a system with optional dependencies
+	* @param system The system to add
+	* @param additionalDeps Additional dependencies for the system
+	*/
+	addSystem(system, additionalDeps = []) {
+		this.systems.add(system);
+		for (const dep of system.dependencies || []) this.systems.add(dep);
+		this.systemDependencies.set(system, new Set([...additionalDeps, ...system.dependencies || []]));
+		this.cachedExecutionOrder = null;
+	}
+	/**
+	* Get the execution order of systems based on dependencies
+	* Uses topological sort
+	*/
+	getExecutionOrder() {
+		if (this.cachedExecutionOrder !== null) return this.cachedExecutionOrder;
+		const result = [];
+		const visited = /* @__PURE__ */ new Set();
+		const visiting = /* @__PURE__ */ new Set();
+		const visit = (system) => {
+			if (visited.has(system)) return;
+			if (visiting.has(system)) throw new Error("Circular dependency detected in system scheduling");
+			visiting.add(system);
+			for (const dep of this.systemDependencies.get(system) || []) visit(dep);
+			visiting.delete(system);
+			visited.add(system);
+			result.push(system);
+		};
+		for (const system of this.systems) if (!visited.has(system)) visit(system);
+		this.cachedExecutionOrder = result;
+		return result;
+	}
+	update(...params) {
+		const executionOrder = this.getExecutionOrder();
+		const systemPromises = /* @__PURE__ */ new Map();
+		for (const system of executionOrder) {
+			const depPromises = Array.from(this.systemDependencies.get(system) || []).map((dep) => systemPromises.get(dep)).filter(Boolean);
+			if (depPromises.length > 0) {
+				const promise = Promise.all(depPromises).then(() => system.update(...params));
+				systemPromises.set(system, promise);
+			} else {
+				const result = system.update(...params);
+				if (result instanceof Promise) systemPromises.set(system, result);
+			}
+		}
+		return Promise.all(systemPromises.values());
+	}
+	/**
+	* Clear all systems and dependencies
+	*/
+	clear() {
+		this.systems.clear();
+		this.cachedExecutionOrder = null;
+	}
+};
+
+//#endregion
+//#region src/world.ts
+/**
+* World class for ECS architecture
+* Manages entities, components, and systems
+*/
+var World = class {
+	/** Manages allocation and deallocation of entity IDs */
+	entityIdManager = new EntityIdManager();
+	/** Array of all archetypes in the world */
+	archetypes = [];
+	/** Maps archetype signatures (component type signatures) to archetype instances */
+	archetypeBySignature = /* @__PURE__ */ new Map();
+	/** Maps entity IDs to their current archetype */
+	entityToArchetype = /* @__PURE__ */ new Map();
+	/** Maps component types to arrays of archetypes that contain them */
+	archetypesByComponent = /* @__PURE__ */ new Map();
+	/** Tracks which entities reference each entity as a component type */
+	entityReferences = /* @__PURE__ */ new Map();
+	/** Storage for dontFragment relations - maps entity ID to a map of relation type to component data */
+	dontFragmentRelations = /* @__PURE__ */ new Map();
+	/** Array of all active queries for archetype change notifications */
+	queries = [];
+	/** Cache for queries keyed by component types and filter signatures */
+	queryCache = /* @__PURE__ */ new Map();
+	/** Schedules and executes systems in dependency order */
+	systemScheduler = new SystemScheduler();
+	/** Buffers structural changes for deferred execution */
+	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
+	/** Stores lifecycle hooks for component and relation events */
+	hooks = /* @__PURE__ */ new Map();
+	/**
+	* 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) {
+		if (snapshot && typeof snapshot === "object") {
+			if (snapshot.entityManager) this.entityIdManager.deserializeState(snapshot.entityManager);
+			if (Array.isArray(snapshot.entities)) for (const entry of snapshot.entities) {
+				const entityId = entry.id;
+				const componentsArray = entry.components || [];
+				const componentMap = /* @__PURE__ */ new Map();
+				const componentTypes = [];
+				for (const componentEntry of componentsArray) {
+					const componentTypeRaw = componentEntry.type;
+					let componentType;
+					if (typeof componentTypeRaw === "number") componentType = componentTypeRaw;
+					else if (typeof componentTypeRaw === "string") {
+						const compId = getComponentIdByName(componentTypeRaw);
+						if (compId === void 0) throw new Error(`Unknown component name in snapshot: ${componentTypeRaw}`);
+						componentType = compId;
+					} else if (typeof componentTypeRaw === "object" && componentTypeRaw !== null && typeof componentTypeRaw.component === "string") {
+						const compId = getComponentIdByName(componentTypeRaw.component);
+						if (compId === void 0) throw new Error(`Unknown component name in snapshot: ${componentTypeRaw.component}`);
+						if (typeof componentTypeRaw.target === "string") {
+							const targetCompId = getComponentIdByName(componentTypeRaw.target);
+							if (targetCompId === void 0) throw new Error(`Unknown target component name in snapshot: ${componentTypeRaw.target}`);
+							componentType = relation(compId, targetCompId);
+						} else componentType = relation(compId, componentTypeRaw.target);
+					} else throw new Error(`Invalid component type in snapshot: ${JSON.stringify(componentTypeRaw)}`);
+					componentMap.set(componentType, componentEntry.value);
+					componentTypes.push(componentType);
+				}
+				const archetype = this.ensureArchetype(componentTypes);
+				archetype.addEntity(entityId, componentMap);
+				this.entityToArchetype.set(entityId, archetype);
+				for (const compType of componentTypes) {
+					const detailedType = getDetailedIdType(compType);
+					if (detailedType.type === "entity-relation") {
+						const targetEntityId = detailedType.targetId;
+						this.trackEntityReference(entityId, compType, targetEntityId);
+					} else if (detailedType.type === "entity") this.trackEntityReference(entityId, compType, compType);
+				}
+			}
+		}
+	}
+	/**
+	* Generate a signature string for component types array
+	* @returns A string signature for the component types
+	*/
+	createArchetypeSignature(componentTypes) {
+		return componentTypes.join(",");
+	}
+	/**
+	* Create a new entity
+	* @returns The ID of the newly created entity
+	*/
+	new() {
+		const entityId = this.entityIdManager.allocate();
+		let emptyArchetype = this.ensureArchetype([]);
+		emptyArchetype.addEntity(entityId, /* @__PURE__ */ new Map());
+		this.entityToArchetype.set(entityId, emptyArchetype);
+		return entityId;
+	}
+	/**
+	* Destroy an entity and remove all its components (immediate execution)
+	*/
+	destroyEntityImmediate(entityId) {
+		const queue = [entityId];
+		const visited = /* @__PURE__ */ new Set();
+		while (queue.length > 0) {
+			const cur = queue.shift();
+			if (visited.has(cur)) continue;
+			visited.add(cur);
+			const archetype = this.entityToArchetype.get(cur);
+			if (!archetype) continue;
+			const componentReferences = Array.from(this.getEntityReferences(cur));
+			for (const [sourceEntityId, componentType] of componentReferences) {
+				const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
+				if (!sourceArchetype) continue;
+				const detailedType = getDetailedIdType(componentType);
+				if (detailedType.type === "entity-relation" && isCascadeDeleteComponent(detailedType.componentId)) {
+					if (!visited.has(sourceEntityId)) queue.push(sourceEntityId);
+					continue;
+				}
+				const currentComponents = /* @__PURE__ */ new Map();
+				let removedComponent = sourceArchetype.get(sourceEntityId, componentType);
+				for (const archetypeComponentType of sourceArchetype.componentTypes) if (archetypeComponentType !== componentType) {
+					const componentData = sourceArchetype.get(sourceEntityId, archetypeComponentType);
+					currentComponents.set(archetypeComponentType, componentData);
+				}
+				const newArchetype = this.ensureArchetype(currentComponents.keys());
+				sourceArchetype.removeEntity(sourceEntityId);
+				if (sourceArchetype.getEntities().length === 0) this.cleanupEmptyArchetype(sourceArchetype);
+				newArchetype.addEntity(sourceEntityId, currentComponents);
+				this.entityToArchetype.set(sourceEntityId, newArchetype);
+				this.untrackEntityReference(sourceEntityId, componentType, cur);
+				this.triggerLifecycleHooks(sourceEntityId, /* @__PURE__ */ new Map(), new Map([[componentType, removedComponent]]));
+			}
+			this.entityReferences.delete(cur);
+			archetype.removeEntity(cur);
+			if (archetype.getEntities().length === 0) this.cleanupEmptyArchetype(archetype);
+			this.entityToArchetype.delete(cur);
+			this.entityIdManager.deallocate(cur);
+		}
+	}
+	/**
+	* Check if an entity exists
+	*/
+	exists(entityId) {
+		return this.entityToArchetype.has(entityId);
+	}
+	set(entityId, componentType, component$1) {
+		if (!this.exists(entityId)) throw new Error(`Entity ${entityId} does not exist`);
+		const detailedType = getDetailedIdType(componentType);
+		if (detailedType.type === "invalid") throw new Error(`Invalid component type: ${componentType}`);
+		if (detailedType.type === "wildcard-relation") throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
+		this.commandBuffer.set(entityId, componentType, component$1);
+	}
+	/**
+	* Remove a component from an entity (deferred)
+	*/
+	remove(entityId, componentType) {
+		if (!this.exists(entityId)) throw new Error(`Entity ${entityId} does not exist`);
+		if (getDetailedIdType(componentType).type === "invalid") throw new Error(`Invalid component type: ${componentType}`);
+		this.commandBuffer.remove(entityId, componentType);
+	}
+	/**
+	* Destroy an entity and remove all its components (deferred)
+	*/
+	delete(entityId) {
+		this.commandBuffer.delete(entityId);
+	}
+	/**
+	* Check if an entity has a specific component
+	*/
+	has(entityId, componentType) {
+		const archetype = this.entityToArchetype.get(entityId);
+		if (!archetype) return false;
+		if (archetype.componentTypes.includes(componentType)) return true;
+		const detailedType = getDetailedIdType(componentType);
+		if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) return this.dontFragmentRelations.get(entityId)?.has(componentType) ?? false;
+		return false;
+	}
+	get(entityId, componentType) {
+		const archetype = this.entityToArchetype.get(entityId);
+		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
+		const detailedType = getDetailedIdType(componentType);
+		if (detailedType.type !== "wildcard-relation") {
+			const inArchetype = archetype.componentTypes.includes(componentType);
+			const isDontFragment = (detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId);
+			if (!(inArchetype || isDontFragment && this.dontFragmentRelations.get(entityId)?.has(componentType))) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+		}
+		return archetype.get(entityId, componentType);
+	}
+	/**
+	* Register a system with optional dependencies
+	*/
+	registerSystem(system, additionalDeps = []) {
+		this.systemScheduler.addSystem(system, additionalDeps);
+	}
+	/**
+	* Register a lifecycle hook for component or wildcard relation events
+	*/
+	hook(componentType, hook) {
+		if (!this.hooks.has(componentType)) this.hooks.set(componentType, /* @__PURE__ */ new Set());
+		this.hooks.get(componentType).add(hook);
+		if (hook.on_init !== void 0) this.archetypesByComponent.get(componentType)?.forEach((archetype) => {
+			const entities = archetype.getEntityToIndexMap();
+			const componentData = archetype.getComponentData(componentType);
+			for (const [entity, index] of entities) {
+				const data = componentData[index];
+				const value = data === MISSING_COMPONENT ? void 0 : data;
+				hook.on_init?.(entity, componentType, value);
+			}
+		});
+	}
+	/**
+	* Unregister a lifecycle hook for component or wildcard relation events
+	*/
+	unhook(componentType, hook) {
+		const hooks = this.hooks.get(componentType);
+		if (hooks) {
+			hooks.delete(hook);
+			if (hooks.size === 0) this.hooks.delete(componentType);
+		}
+	}
+	/**
+	* Mark a component as exclusive relation
+	* @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) {
+		throw new Error("setExclusive has been removed. Use component options instead: component({ exclusive: true })");
+	}
+	/**
+	* Mark a component as cascade-delete relation
+	* @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) {
+		throw new Error("setCascadeDelete has been removed. Use component options instead: component({ cascadeDelete: true })");
+	}
+	/**
+	* 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) {
+		const result = this.systemScheduler.update(...params);
+		if (result instanceof Promise) return result.then(() => this.commandBuffer.execute());
+		else this.commandBuffer.execute();
+	}
+	/**
+	* Execute all deferred commands immediately without running systems
+	*/
+	sync() {
+		this.commandBuffer.execute();
+	}
+	/**
+	* Create a cached query for efficient entity lookups
+	* @returns A Query object for the specified component types and filter
+	*/
+	createQuery(componentTypes, filter = {}) {
+		const sortedTypes = [...componentTypes].sort((a, b) => a - b);
+		const filterKey = serializeQueryFilter(filter);
+		const key = `${this.createArchetypeSignature(sortedTypes)}${filterKey ? `|${filterKey}` : ""}`;
+		const cached = this.queryCache.get(key);
+		if (cached) {
+			cached.refCount++;
+			return cached.query;
+		}
+		const query = new Query(this, sortedTypes, filter);
+		this.queryCache.set(key, {
+			query,
+			refCount: 1
+		});
+		return query;
+	}
+	/**
+	* @internal Register a query for archetype update notifications
+	*/
+	_registerQuery(query) {
+		this.queries.push(query);
+	}
+	/**
+	* @internal Unregister a query
+	*/
+	_unregisterQuery(query) {
+		const index = this.queries.indexOf(query);
+		if (index !== -1) this.queries.splice(index, 1);
+	}
+	/**
+	* Release a query reference obtained from createQuery.
+	* Decrements the refCount and fully disposes the query when it reaches zero.
+	*/
+	releaseQuery(query) {
+		for (const [k, v] of this.queryCache.entries()) if (v.query === query) {
+			v.refCount--;
+			if (v.refCount <= 0) {
+				this.queryCache.delete(k);
+				this._unregisterQuery(query);
+				v.query._disposeInternal();
+			}
+			return;
+		}
+	}
+	/**
+	* @internal Get archetypes that match specific component types (for internal use by queries)
+	*/
+	getMatchingArchetypes(componentTypes) {
+		if (componentTypes.length === 0) return [...this.archetypes];
+		const regularComponents = [];
+		const wildcardRelations = [];
+		for (const componentType of componentTypes) {
+			const detailedType = getDetailedIdType(componentType);
+			if (detailedType.type === "wildcard-relation") wildcardRelations.push({
+				componentId: detailedType.componentId,
+				relationId: componentType
+			});
+			else regularComponents.push(componentType);
+		}
+		let matchingArchetypes = [];
+		if (regularComponents.length > 0) {
+			const sortedRegularTypes = [...regularComponents].sort((a, b) => a - b);
+			if (sortedRegularTypes.length === 1) {
+				const componentType = sortedRegularTypes[0];
+				matchingArchetypes = this.archetypesByComponent.get(componentType) || [];
+			} else {
+				const archetypeLists = sortedRegularTypes.map((type) => this.archetypesByComponent.get(type) || []);
+				const firstList = archetypeLists[0] || [];
+				const intersection = /* @__PURE__ */ new Set();
+				for (const archetype of firstList) {
+					let hasAllComponents = true;
+					for (let listIndex = 1; listIndex < archetypeLists.length; listIndex++) if (!archetypeLists[listIndex].includes(archetype)) {
+						hasAllComponents = false;
+						break;
+					}
+					if (hasAllComponents) intersection.add(archetype);
+				}
+				matchingArchetypes = Array.from(intersection);
+			}
+		} else matchingArchetypes = [...this.archetypes];
+		for (const wildcard of wildcardRelations) matchingArchetypes = matchingArchetypes.filter((archetype) => archetype.componentTypes.some((archetypeType) => {
+			if (!isRelationId(archetypeType)) return false;
+			return decodeRelationId(archetypeType).componentId === wildcard.componentId;
+		}));
+		return matchingArchetypes;
+	}
+	query(componentTypes, includeComponents) {
+		const matchingArchetypes = this.getMatchingArchetypes(componentTypes);
+		if (includeComponents) {
+			const result = [];
+			for (const archetype of matchingArchetypes) {
+				const entitiesWithData = archetype.getEntitiesWithComponents(componentTypes);
+				result.push(...entitiesWithData);
+			}
+			return result;
+		} else {
+			const result = [];
+			for (const archetype of matchingArchetypes) result.push(...archetype.getEntities());
+			return result;
+		}
+	}
+	/**
+	* @internal Execute commands for a single entity (for internal use by CommandBuffer)
+	* @returns ComponentChangeset describing the changes made
+	*/
+	executeEntityCommands(entityId, commands) {
+		const changeset = new ComponentChangeset();
+		if (commands.some((cmd) => cmd.type === "destroy")) {
+			this.destroyEntityImmediate(entityId);
+			return changeset;
+		}
+		const currentArchetype = this.entityToArchetype.get(entityId);
+		if (!currentArchetype) return changeset;
+		this.processCommands(entityId, currentArchetype, commands, changeset);
+		const removedComponents = this.applyChangeset(entityId, currentArchetype, changeset);
+		this.updateEntityReferences(entityId, changeset);
+		this.triggerLifecycleHooks(entityId, changeset.adds, removedComponents);
+		return changeset;
+	}
+	/**
+	* Process commands and populate the changeset
+	*/
+	processCommands(entityId, currentArchetype, commands, changeset) {
+		for (const command of commands) if (command.type === "set" && command.componentType) this.processSetCommand(entityId, currentArchetype, command.componentType, command.component, changeset);
+		else if (command.type === "delete" && command.componentType) this.processDeleteCommand(entityId, currentArchetype, command.componentType, changeset);
+	}
+	/**
+	* Process a set command, handling exclusive relations
+	*/
+	processSetCommand(entityId, currentArchetype, componentType, component$1, changeset) {
+		const detailedType = getDetailedIdType(componentType);
+		if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isExclusiveComponent(detailedType.componentId)) this.removeExclusiveRelations(entityId, currentArchetype, detailedType.componentId, changeset);
+		changeset.set(componentType, component$1);
+	}
+	/**
+	* Remove all relations with the same base component (for exclusive relations)
+	*/
+	removeExclusiveRelations(entityId, currentArchetype, baseComponentId, changeset) {
+		for (const componentType of currentArchetype.componentTypes) if (this.isRelationWithComponent(componentType, baseComponentId)) changeset.delete(componentType);
+		const entityData = currentArchetype.getEntity(entityId);
+		if (entityData) for (const [componentType] of entityData) {
+			if (currentArchetype.componentTypes.includes(componentType)) continue;
+			if (this.isRelationWithComponent(componentType, baseComponentId)) changeset.delete(componentType);
+		}
+	}
+	/**
+	* Check if a component type is a relation with the given base component
+	*/
+	isRelationWithComponent(componentType, baseComponentId) {
+		const detailedType = getDetailedIdType(componentType);
+		return (detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId === baseComponentId;
+	}
+	/**
+	* Process a delete command, handling wildcard relations
+	*/
+	processDeleteCommand(entityId, currentArchetype, componentType, changeset) {
+		const detailedType = getDetailedIdType(componentType);
+		if (detailedType.type === "wildcard-relation") this.removeWildcardRelations(entityId, currentArchetype, detailedType.componentId, changeset);
+		else changeset.delete(componentType);
+	}
+	/**
+	* Remove all relations matching a wildcard component ID
+	*/
+	removeWildcardRelations(entityId, currentArchetype, baseComponentId, changeset) {
+		for (const componentType of currentArchetype.componentTypes) if (this.isRelationWithComponent(componentType, baseComponentId)) changeset.delete(componentType);
+		const entityData = currentArchetype.getEntity(entityId);
+		if (entityData) for (const [componentType] of entityData) {
+			if (currentArchetype.componentTypes.includes(componentType)) continue;
+			if (this.isRelationWithComponent(componentType, baseComponentId)) changeset.delete(componentType);
+		}
+	}
+	/**
+	* Apply changeset to entity, moving to new archetype if needed
+	* @returns Map of removed components with their data
+	*/
+	applyChangeset(entityId, currentArchetype, changeset) {
+		const currentEntityData = currentArchetype.getEntity(entityId);
+		const allCurrentComponentTypes = currentEntityData ? Array.from(currentEntityData.keys()) : currentArchetype.componentTypes;
+		const finalComponentTypes = changeset.getFinalComponentTypes(allCurrentComponentTypes);
+		const removedComponents = /* @__PURE__ */ new Map();
+		if (finalComponentTypes) this.moveEntityToNewArchetype(entityId, currentArchetype, finalComponentTypes, changeset, removedComponents);
+		else this.updateEntityInSameArchetype(entityId, currentArchetype, changeset, removedComponents);
+		return removedComponents;
+	}
+	/**
+	* Move entity to a new archetype with updated components
+	*/
+	moveEntityToNewArchetype(entityId, currentArchetype, finalComponentTypes, changeset, removedComponents) {
+		const newArchetype = this.ensureArchetype(finalComponentTypes);
+		const currentComponents = currentArchetype.removeEntity(entityId);
+		for (const componentType of changeset.removes) removedComponents.set(componentType, currentComponents.get(componentType));
+		newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
+		this.entityToArchetype.set(entityId, newArchetype);
+		if (currentArchetype.getEntities().length === 0) this.cleanupEmptyArchetype(currentArchetype);
+	}
+	/**
+	* Update entity in same archetype (no archetype change needed)
+	*/
+	updateEntityInSameArchetype(entityId, currentArchetype, changeset, removedComponents) {
+		const currentComponents = currentArchetype.getEntity(entityId);
+		const hasDontFragmentChanges = this.hasDontFragmentChanges(changeset);
+		if (hasDontFragmentChanges) for (const componentType of changeset.removes) {
+			const detailedType = getDetailedIdType(componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) removedComponents.set(componentType, currentComponents.get(componentType));
+		}
+		if (hasDontFragmentChanges) this.readdEntityWithUpdatedComponents(entityId, currentArchetype, currentComponents, changeset);
+		else for (const [componentType, component$1] of changeset.adds) currentArchetype.set(entityId, componentType, component$1);
+	}
+	/**
+	* Check if changeset contains dontFragment relation changes
+	*/
+	hasDontFragmentChanges(changeset) {
+		for (const componentType of changeset.removes) {
+			const detailedType = getDetailedIdType(componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) return true;
+		}
+		for (const [componentType] of changeset.adds) {
+			const detailedType = getDetailedIdType(componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) return true;
+		}
+		return false;
+	}
+	/**
+	* Remove and re-add entity with updated components (for dontFragment changes)
+	*/
+	readdEntityWithUpdatedComponents(entityId, archetype, currentComponents, changeset) {
+		const newComponents = /* @__PURE__ */ new Map();
+		for (const [ct, value] of currentComponents) if (!changeset.removes.has(ct)) newComponents.set(ct, value);
+		for (const [ct, value] of changeset.adds) newComponents.set(ct, value);
+		archetype.removeEntity(entityId);
+		archetype.addEntity(entityId, newComponents);
+	}
+	/**
+	* Update entity reference tracking based on changeset
+	*/
+	updateEntityReferences(entityId, changeset) {
+		for (const componentType of changeset.removes) {
+			const detailedType = getDetailedIdType(componentType);
+			if (detailedType.type === "entity-relation") this.untrackEntityReference(entityId, componentType, detailedType.targetId);
+			else if (detailedType.type === "entity") this.untrackEntityReference(entityId, componentType, componentType);
+		}
+		for (const [componentType] of changeset.adds) {
+			const detailedType = getDetailedIdType(componentType);
+			if (detailedType.type === "entity-relation") this.trackEntityReference(entityId, componentType, detailedType.targetId);
+			else if (detailedType.type === "entity") this.trackEntityReference(entityId, componentType, componentType);
+		}
+	}
+	/**
+	* 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)
+	*/
+	ensureArchetype(componentTypes) {
+		const sortedTypes = this.filterRegularComponentTypes(componentTypes).sort((a, b) => a - b);
+		const hashKey = this.createArchetypeSignature(sortedTypes);
+		return getOrCreateWithSideEffect(this.archetypeBySignature, hashKey, () => this.createNewArchetype(sortedTypes));
+	}
+	/**
+	* Filter out dontFragment relations from component types
+	*/
+	filterRegularComponentTypes(componentTypes) {
+		const regularTypes = [];
+		for (const componentType of componentTypes) {
+			const detailedType = getDetailedIdType(componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) continue;
+			regularTypes.push(componentType);
+		}
+		return regularTypes;
+	}
+	/**
+	* Create a new archetype and register it with all tracking structures
+	*/
+	createNewArchetype(componentTypes) {
+		const newArchetype = new Archetype(componentTypes, this.dontFragmentRelations);
+		this.archetypes.push(newArchetype);
+		this.registerArchetypeInComponentIndex(newArchetype, componentTypes);
+		this.notifyQueriesOfNewArchetype(newArchetype);
+		return newArchetype;
+	}
+	/**
+	* Register archetype in the component-to-archetype index
+	*/
+	registerArchetypeInComponentIndex(archetype, componentTypes) {
+		for (const componentType of componentTypes) {
+			const archetypes = this.archetypesByComponent.get(componentType) || [];
+			archetypes.push(archetype);
+			this.archetypesByComponent.set(componentType, archetypes);
+		}
+	}
+	/**
+	* Notify all queries to check the new archetype
+	*/
+	notifyQueriesOfNewArchetype(archetype) {
+		for (const query of this.queries) query.checkNewArchetype(archetype);
+	}
+	/**
+	* 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
+	*/
+	trackEntityReference(sourceEntityId, componentType, targetEntityId) {
+		if (!this.entityReferences.has(targetEntityId)) this.entityReferences.set(targetEntityId, new MultiMap());
+		this.entityReferences.get(targetEntityId).add(sourceEntityId, componentType);
+	}
+	/**
+	* 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
+	*/
+	untrackEntityReference(sourceEntityId, componentType, targetEntityId) {
+		const references = this.entityReferences.get(targetEntityId);
+		if (references) {
+			references.remove(sourceEntityId, componentType);
+			if (references.keyCount === 0) this.entityReferences.delete(targetEntityId);
+		}
+	}
+	/**
+	* 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
+	*/
+	getEntityReferences(targetEntityId) {
+		return this.entityReferences.get(targetEntityId) ?? new MultiMap();
+	}
+	/**
+	* Remove an empty archetype from all internal data structures
+	*/
+	cleanupEmptyArchetype(archetype) {
+		if (archetype.getEntities().length > 0) return;
+		this.removeArchetypeFromList(archetype);
+		this.removeArchetypeFromSignatureMap(archetype);
+		this.removeArchetypeFromComponentIndex(archetype);
+		this.removeArchetypeFromQueries(archetype);
+	}
+	/**
+	* Remove archetype from the main archetypes list
+	*/
+	removeArchetypeFromList(archetype) {
+		const index = this.archetypes.indexOf(archetype);
+		if (index !== -1) this.archetypes.splice(index, 1);
+	}
+	/**
+	* Remove archetype from the signature-to-archetype map
+	*/
+	removeArchetypeFromSignatureMap(archetype) {
+		const hashKey = this.createArchetypeSignature(archetype.componentTypes);
+		this.archetypeBySignature.delete(hashKey);
+	}
+	/**
+	* Remove archetype from the component-to-archetypes index
+	*/
+	removeArchetypeFromComponentIndex(archetype) {
+		for (const componentType of archetype.componentTypes) {
+			const archetypes = this.archetypesByComponent.get(componentType);
+			if (archetypes) {
+				const compIndex = archetypes.indexOf(archetype);
+				if (compIndex !== -1) {
+					archetypes.splice(compIndex, 1);
+					if (archetypes.length === 0) this.archetypesByComponent.delete(componentType);
+				}
+			}
+		}
+	}
+	/**
+	* Remove archetype from all queries
+	*/
+	removeArchetypeFromQueries(archetype) {
+		for (const query of this.queries) query.removeArchetype(archetype);
+	}
+	/**
+	* Execute component lifecycle hooks for added and removed components
+	*/
+	triggerLifecycleHooks(entityId, addedComponents, removedComponents) {
+		for (const [componentType, component$1] of addedComponents) {
+			const directHooks = this.hooks.get(componentType);
+			if (directHooks) for (const lifecycleHook of directHooks) lifecycleHook.on_set?.(entityId, componentType, component$1);
+			const detailedType = getDetailedIdType(componentType);
+			if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
+				const wildcardRelationId = relation(detailedType.componentId, "*");
+				const wildcardHooks = this.hooks.get(wildcardRelationId);
+				if (wildcardHooks) for (const lifecycleHook of wildcardHooks) lifecycleHook.on_set?.(entityId, componentType, component$1);
+			}
+		}
+		for (const [componentType, component$1] of removedComponents) {
+			const directHooks = this.hooks.get(componentType);
+			if (directHooks) for (const lifecycleHook of directHooks) lifecycleHook.on_remove?.(entityId, componentType, component$1);
+			const detailedType = getDetailedIdType(componentType);
+			if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
+				const wildcardRelationId = relation(detailedType.componentId, "*");
+				const wildcardHooks = this.hooks.get(wildcardRelationId);
+				if (wildcardHooks) for (const hook of wildcardHooks) hook.on_remove?.(entityId, componentType, component$1);
+			}
+		}
+	}
+	/**
+	* 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() {
+		const entities = [];
+		for (const archetype of this.archetypes) {
+			const dumpedEntities = archetype.dump();
+			for (const { entity, components } of dumpedEntities) entities.push({
+				id: entity,
+				components: Array.from(components.entries()).map(([rawType, value]) => {
+					const detailedType = getDetailedIdType(rawType);
+					let type = rawType;
+					let componentName;
+					switch (detailedType.type) {
+						case "component":
+							type = getComponentNameById(rawType) || rawType;
+							break;
+						case "entity-relation":
+							componentName = getComponentNameById(detailedType.componentId);
+							if (componentName) type = {
+								component: componentName,
+								target: detailedType.targetId
+							};
+							break;
+						case "component-relation":
+							componentName = getComponentNameById(detailedType.componentId);
+							if (componentName) type = {
+								component: componentName,
+								target: getComponentNameById(detailedType.targetId) || detailedType.targetId
+							};
+							break;
+					}
+					return {
+						type,
+						value: value === MISSING_COMPONENT ? void 0 : value
+					};
+				})
+			});
+		}
+		return {
+			version: 1,
+			entityManager: this.entityIdManager.serializeState(),
+			entities
+		};
+	}
+};
+
+//#endregion
+export { Query, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };
+//# sourceMappingURL=index.mjs.map