@codehz/ecs 0.3.15 → 0.4.1

package/world.mjs

@@ -0,0 +1,2081 @@
+//#region src/bit-set.ts
+var BitSet = class {
+	data;
+	_length;
+	constructor(length) {
+		this._length = length;
+		const numWords = Math.ceil(length / 32);
+		this.data = new Uint32Array(numWords);
+	}
+	get length() {
+		return this._length;
+	}
+	has(index) {
+		if (index < 0 || index >= this._length) return false;
+		const word = index >>> 5;
+		const bit = index & 31;
+		return (this.data[word] >>> bit & 1) !== 0;
+	}
+	set(index) {
+		if (index < 0 || index >= this._length) return;
+		const word = index >>> 5;
+		const bit = index & 31;
+		this.data[word] |= 1 << bit;
+	}
+	clear(index) {
+		if (index < 0 || index >= this._length) return;
+		const word = index >>> 5;
+		const bit = index & 31;
+		this.data[word] &= ~(1 << bit);
+	}
+	setRange(lo, hi) {
+		if (lo > hi) return;
+		if (lo < 0) lo = 0;
+		if (hi >= this._length) hi = this._length - 1;
+		const firstWord = lo >>> 5;
+		const lastWord = hi >>> 5;
+		const loBit = lo & 31;
+		const hiBit = hi & 31;
+		const maskFor = (a, b) => {
+			const width = b - a + 1;
+			if (width <= 0) return 0;
+			if (width >= 32) return 4294967295;
+			return (1 << width) - 1 << a >>> 0;
+		};
+		if (firstWord === lastWord) {
+			const mask = maskFor(loBit, hiBit);
+			this.data[firstWord] = (this.data[firstWord] | mask) >>> 0;
+			return;
+		}
+		const firstMask = maskFor(loBit, 31);
+		this.data[firstWord] = (this.data[firstWord] | firstMask) >>> 0;
+		for (let w = firstWord + 1; w <= lastWord - 1; w++) this.data[w] = 4294967295;
+		const lastMask = maskFor(0, hiBit);
+		this.data[lastWord] = (this.data[lastWord] | lastMask) >>> 0;
+	}
+	anyClearInRange(lo, hi) {
+		if (lo > hi) return false;
+		if (lo < 0) lo = 0;
+		if (hi >= this._length) hi = this._length - 1;
+		const firstWord = lo >>> 5;
+		const lastWord = hi >>> 5;
+		const loBit = lo & 31;
+		const hiBit = hi & 31;
+		const maskFor = (a, b) => {
+			const width = b - a + 1;
+			if (width <= 0) return 0;
+			if (width >= 32) return 4294967295;
+			return (1 << width) - 1 << a >>> 0;
+		};
+		if (firstWord === lastWord) {
+			const mask = maskFor(loBit, hiBit);
+			return (this.data[firstWord] & mask) >>> 0 !== mask >>> 0;
+		}
+		const firstMask = maskFor(loBit, 31);
+		if ((this.data[firstWord] & firstMask) >>> 0 !== firstMask >>> 0) return true;
+		for (let w = firstWord + 1; w <= lastWord - 1; w++) if (this.data[w] !== 4294967295) return true;
+		const lastMask = maskFor(0, hiBit);
+		if ((this.data[lastWord] & lastMask) >>> 0 !== lastMask >>> 0) return true;
+		return false;
+	}
+	reset() {
+		this.data.fill(0);
+	}
+	*[Symbol.iterator]() {
+		for (let wordIndex = 0; wordIndex < this.data.length; wordIndex++) {
+			let word = this.data[wordIndex];
+			if (word === 0) continue;
+			const baseIndex = wordIndex * 32;
+			for (let bit = 0; bit < 32 && baseIndex + bit < this._length; bit++) {
+				if (word & 1) yield baseIndex + bit;
+				word >>>= 1;
+			}
+		}
+	}
+};
+
+//#endregion
+//#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;
+/**
+* Internal function to decode a relation ID into raw component and target IDs
+* @param id The EntityId to decode
+* @returns Object with componentId and targetId, or null if not a relation
+*/
+function decodeRelationRaw(id) {
+	if (id >= 0) return null;
+	const absId = -id;
+	return {
+		componentId: Math.floor(absId / RELATION_SHIFT),
+		targetId: absId % RELATION_SHIFT
+	};
+}
+/**
+* Check if a component ID is valid (1-1023)
+*/
+function isValidComponentId(componentId) {
+	return componentId >= 1 && componentId <= COMPONENT_ID_MAX;
+}
+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) {
+	const decoded = decodeRelationRaw(id);
+	return decoded !== null && decoded.targetId === 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) {
+	const decoded = decodeRelationRaw(relationId);
+	if (decoded === null) throw new Error("ID is not a relation ID");
+	const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+	if (!isValidComponentId(rawComponentId)) throw new Error("Invalid component ID in relation");
+	const componentId = rawComponentId;
+	const targetId = rawTargetId;
+	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 (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 (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 ComponentIdForNames = /* @__PURE__ */ new Map();
+const componentNames = new Array(COMPONENT_ID_MAX + 1);
+const exclusiveFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const cascadeDeleteFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
+/**
+* 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[id] = name;
+		ComponentIdForNames.set(name, id);
+	}
+	if (options) {
+		if (options.exclusive) exclusiveFlags.set(id);
+		if (options.cascadeDelete) cascadeDeleteFlags.set(id);
+		if (options.dontFragment) dontFragmentFlags.set(id);
+	}
+	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[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 exclusiveFlags.has(id);
+}
+/**
+* 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 dontFragmentFlags.has(id);
+}
+/**
+* Generic function to check relation flags with specific target conditions
+* @param id The entity/relation ID to check
+* @param flagBitSet The bitset for the flag
+* @param targetCondition Function to check target ID condition
+* @returns true if the condition is met, false otherwise
+*/
+function checkRelationFlag(id, flagBitSet, targetCondition) {
+	const decoded = decodeRelationRaw(id);
+	if (decoded === null) return false;
+	const { componentId, targetId } = decoded;
+	return isValidComponentId(componentId) && targetCondition(targetId) && flagBitSet.has(componentId);
+}
+/**
+* Check if a relation ID is a dontFragment relation (entity-relation or component-relation with dontFragment component)
+* This is an optimized function that avoids the overhead of getDetailedIdType
+* @param id The entity/relation ID to check
+* @returns true if this is a dontFragment relation, false otherwise
+*/
+function isDontFragmentRelation(id) {
+	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
+}
+/**
+* Check if an ID is a wildcard relation with dontFragment component
+* This is an optimized function for filtering archetype component types
+* @param id The entity/relation ID to check
+* @returns true if this is a wildcard relation with dontFragment component, false otherwise
+*/
+function isDontFragmentWildcard(id) {
+	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
+}
+/**
+* Check if a relation ID is a cascade delete entity-relation
+* This is an optimized function that avoids the overhead of getDetailedIdType
+* Note: Cascade delete only applies to entity-relations (not component-relations or wildcards)
+* @param id The entity/relation ID to check
+* @returns true if this is an entity-relation with cascade delete, false otherwise
+*/
+function isCascadeDeleteRelation(id) {
+	return checkRelationFlag(id, cascadeDeleteFlags, (targetId) => targetId !== WILDCARD_TARGET_ID && targetId >= ENTITY_ID_START);
+}
+/**
+* Get the componentId from a relation ID without fully decoding the relation.
+* Returns undefined for non-relation IDs or invalid component IDs.
+*/
+function getComponentIdFromRelationId(id) {
+	const decoded = decodeRelationRaw(id);
+	if (decoded === null || !isValidComponentId(decoded.componentId)) return void 0;
+	return decoded.componentId;
+}
+/**
+* Get the targetId from a relation ID without fully decoding the relation.
+* Returns undefined for non-relation IDs.
+*/
+function getTargetIdFromRelationId(id) {
+	return decodeRelationRaw(id)?.targetId;
+}
+/**
+* Check if an ID is an entity-relation (relation targeting an entity, not a component or wildcard)
+*/
+function isEntityRelation(id) {
+	const decoded = decodeRelationRaw(id);
+	return decoded !== null && decoded.targetId >= ENTITY_ID_START;
+}
+
+//#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 = getComponentIdFromRelationId(componentType);
+			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, entityId) {
+		return componentDataSources.map((dataSource, i) => {
+			const compType = componentTypes[i];
+			return this.buildSingleComponent(compType, dataSource, entityIndex, entityId);
+		});
+	}
+	/**
+	* Build a single component value from its data source
+	*/
+	buildSingleComponent(compType, dataSource, entityIndex, entityId) {
+		const optional = isOptionalEntityId(compType);
+		const actualType = optional ? compType.optional : compType;
+		if (getIdType(actualType) === "wildcard-relation") return this.buildWildcardRelationValue(actualType, dataSource, entityIndex, entityId, optional);
+		else return this.buildRegularComponentValue(dataSource, entityIndex, optional);
+	}
+	/**
+	* Build wildcard relation value from matching relations
+	*/
+	buildWildcardRelationValue(wildcardRelationType, dataSource, entityIndex, entityId, optional) {
+		const matchingRelations = dataSource || [];
+		const relations = [];
+		for (const relType of matchingRelations) {
+			const data = this.getComponentData(relType)[entityIndex];
+			const targetId = getTargetIdFromRelationId(relType);
+			relations.push([targetId, data === MISSING_COMPONENT ? void 0 : data]);
+		}
+		const targetComponentId = getComponentIdFromRelationId(wildcardRelationType);
+		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 === targetComponentId) relations.push([relDetailed.targetId, data]);
+		}
+		if (relations.length === 0) {
+			if (!optional) {
+				const componentId = getComponentIdFromRelationId(wildcardRelationType);
+				throw new Error(`No matching relations found for mandatory wildcard relation component ${componentId} on entity ${entityId}`);
+			}
+			return;
+		}
+		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++) {
+			const entity = this.entities[entityIndex];
+			yield [entity, ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entity)];
+		}
+	}
+	/**
+	* 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, entity));
+		}
+	}
+	/**
+	* 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);
+		}
+	}
+	/**
+	* 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) {
+		for (const componentType of this.componentTypes) {
+			const detailedType = getDetailedIdType(componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId === componentId) return true;
+		}
+		for (const entityId of this.entities) {
+			const entityDontFragmentRelations = this.dontFragmentRelations.get(entityId);
+			if (entityDontFragmentRelations) for (const relationType of entityDontFragmentRelations.keys()) {
+				const detailedType = getDetailedIdType(relationType);
+				if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId === componentId) return true;
+			}
+		}
+		return false;
+	}
+};
+
+//#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 getComponentIdFromRelationId(archetypeType) === 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 getComponentIdFromRelationId(archetypeType) === 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 = [];
+		if (this.componentTypes.some((ct) => {
+			return getDetailedIdType(ct).type === "wildcard-relation";
+		})) for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) {
+			let hasAllRelations = true;
+			for (const componentType of this.componentTypes) if (getDetailedIdType(componentType).type === "wildcard-relation") {
+				const relations = archetype.get(entity, componentType);
+				if (!relations || relations.length === 0) {
+					hasAllRelations = false;
+					break;
+				}
+			}
+			if (hasAllRelations) result.push(entity);
+		}
+		else 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/world.ts
+/**
+* World class for ECS architecture
+* Manages entities and components
+*/
+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();
+	/** 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) {
+				if (!this.entityToArchetype.get(sourceEntityId)) continue;
+				if (isCascadeDeleteRelation(componentType)) {
+					if (!visited.has(sourceEntityId)) queue.push(sourceEntityId);
+					continue;
+				}
+				this.removeComponentImmediate(sourceEntityId, componentType, cur);
+			}
+			this.entityReferences.delete(cur);
+			archetype.removeEntity(cur);
+			this.entityToArchetype.delete(cur);
+			this.cleanupArchetypesReferencingEntity(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;
+		if (isDontFragmentRelation(componentType)) 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`);
+		if (componentType >= 0 || componentType % 2 ** 42 !== 0) {
+			const inArchetype = archetype.componentTypes.includes(componentType);
+			const hasDontFragment = isDontFragmentRelation(componentType);
+			if (!(inArchetype || hasDontFragment && 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 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);
+		}
+	}
+	/**
+	* Execute all deferred commands immediately
+	*/
+	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) if (isWildcardRelationId(componentType)) {
+			const componentId = getComponentIdFromRelationId(componentType);
+			if (componentId !== void 0) wildcardRelations.push({
+				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) if (isDontFragmentComponent(wildcard.componentId)) {
+			const archetypesWithMarker = this.archetypesByComponent.get(wildcard.relationId) || [];
+			if (matchingArchetypes.length === 0) matchingArchetypes = archetypesWithMarker;
+			else matchingArchetypes = matchingArchetypes.filter((archetype) => archetypesWithMarker.includes(archetype));
+		} else matchingArchetypes = matchingArchetypes.filter((archetype) => archetype.hasRelationWithComponentId(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 componentId = getComponentIdFromRelationId(componentType);
+		if (componentId !== void 0) {
+			if (componentId !== void 0 && isExclusiveComponent(componentId)) this.removeExclusiveRelations(entityId, currentArchetype, componentId, changeset);
+			if (componentId !== void 0 && isDontFragmentComponent(componentId)) {
+				const wildcardMarker = relation(componentId, "*");
+				if (!currentArchetype.componentTypes.includes(wildcardMarker)) changeset.set(wildcardMarker, void 0);
+			}
+		}
+		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);
+		}
+	}
+	isRelationWithComponent(componentType, baseComponentId) {
+		return getComponentIdFromRelationId(componentType) === baseComponentId;
+	}
+	/**
+	* Process a delete command, handling wildcard relations
+	*/
+	processDeleteCommand(entityId, currentArchetype, componentType, changeset) {
+		const componentId = getComponentIdFromRelationId(componentType);
+		if (isWildcardRelationId(componentType) && componentId !== void 0) this.removeWildcardRelations(entityId, currentArchetype, componentId, changeset);
+		else {
+			changeset.delete(componentType);
+			if (componentId !== void 0 && isDontFragmentComponent(componentId)) {
+				const wildcardMarker = relation(componentId, "*");
+				const entityData = currentArchetype.getEntity(entityId);
+				let hasOtherRelations = false;
+				if (entityData) for (const [otherComponentType] of entityData) {
+					if (otherComponentType === componentType) continue;
+					if (otherComponentType === wildcardMarker) continue;
+					if (changeset.removes.has(otherComponentType)) continue;
+					if (getComponentIdFromRelationId(otherComponentType) === componentId) {
+						hasOtherRelations = true;
+						break;
+					}
+				}
+				if (!hasOtherRelations) changeset.delete(wildcardMarker);
+			}
+		}
+	}
+	/**
+	* 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);
+		}
+		if (isDontFragmentComponent(baseComponentId)) {
+			const wildcardMarker = relation(baseComponentId, "*");
+			changeset.delete(wildcardMarker);
+		}
+	}
+	/**
+	* Remove a single component from an entity immediately, handling dontFragment relations correctly.
+	* Used by destroyEntityImmediate for non-cascade relation cleanup.
+	*/
+	removeComponentImmediate(entityId, componentType, targetEntityId) {
+		const sourceArchetype = this.entityToArchetype.get(entityId);
+		if (!sourceArchetype) return;
+		const changeset = new ComponentChangeset();
+		const componentId = getComponentIdFromRelationId(componentType);
+		changeset.delete(componentType);
+		if (componentId !== void 0 && isDontFragmentComponent(componentId)) {
+			const wildcardMarker = relation(componentId, "*");
+			const entityData = sourceArchetype.getEntity(entityId);
+			let hasOtherRelations = false;
+			if (entityData) for (const [otherComponentType] of entityData) {
+				if (otherComponentType === componentType) continue;
+				if (otherComponentType === wildcardMarker) continue;
+				if (getComponentIdFromRelationId(otherComponentType) === componentId) {
+					hasOtherRelations = true;
+					break;
+				}
+			}
+			if (!hasOtherRelations) changeset.delete(wildcardMarker);
+		}
+		const removedComponent = sourceArchetype.get(entityId, componentType);
+		this.applyChangeset(entityId, sourceArchetype, changeset);
+		this.untrackEntityReference(entityId, componentType, targetEntityId);
+		this.triggerLifecycleHooks(entityId, /* @__PURE__ */ new Map(), new Map([[componentType, removedComponent]]));
+	}
+	/**
+	* 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) {
+			const currentRegularTypes = this.filterRegularComponentTypes(allCurrentComponentTypes);
+			const finalRegularTypes = this.filterRegularComponentTypes(finalComponentTypes);
+			if (!this.areComponentTypesEqual(currentRegularTypes, finalRegularTypes)) this.moveEntityToNewArchetype(entityId, currentArchetype, finalComponentTypes, changeset, removedComponents);
+			else this.updateEntityInSameArchetype(entityId, currentArchetype, 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);
+	}
+	/**
+	* Update entity in same archetype (no archetype change needed)
+	*/
+	updateEntityInSameArchetype(entityId, currentArchetype, changeset, removedComponents) {
+		this.applyDontFragmentChanges(entityId, changeset, removedComponents);
+		for (const [componentType, component$1] of changeset.adds) {
+			if (isDontFragmentRelation(componentType)) continue;
+			currentArchetype.set(entityId, componentType, component$1);
+		}
+	}
+	/**
+	* Apply dontFragment relation changes directly to World's storage
+	* This is much more efficient than the removeEntity + addEntity approach
+	*/
+	applyDontFragmentChanges(entityId, changeset, removedComponents) {
+		let entityRelations = this.dontFragmentRelations.get(entityId);
+		for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) {
+			if (entityRelations) {
+				const removedValue = entityRelations.get(componentType);
+				if (removedValue !== void 0 || entityRelations.has(componentType)) {
+					removedComponents.set(componentType, removedValue);
+					entityRelations.delete(componentType);
+				}
+			}
+		}
+		for (const [componentType, component$1] of changeset.adds) if (isDontFragmentRelation(componentType)) {
+			if (!entityRelations) {
+				entityRelations = /* @__PURE__ */ new Map();
+				this.dontFragmentRelations.set(entityId, entityRelations);
+			}
+			entityRelations.set(componentType, component$1);
+		}
+		if (entityRelations && entityRelations.size === 0) this.dontFragmentRelations.delete(entityId);
+	}
+	/**
+	* Update entity reference tracking based on changeset
+	*/
+	updateEntityReferences(entityId, changeset) {
+		for (const componentType of changeset.removes) if (isEntityRelation(componentType)) {
+			const targetId = getTargetIdFromRelationId(componentType);
+			this.untrackEntityReference(entityId, componentType, targetId);
+		} else if (componentType >= 1024) this.untrackEntityReference(entityId, componentType, componentType);
+		for (const [componentType] of changeset.adds) if (isEntityRelation(componentType)) {
+			const targetId = getTargetIdFromRelationId(componentType);
+			this.trackEntityReference(entityId, componentType, targetId);
+		} else if (componentType >= 1024) 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));
+	}
+	/**
+	* Compare two arrays of component types for equality (order-independent)
+	*/
+	areComponentTypesEqual(types1, types2) {
+		if (types1.length !== types2.length) return false;
+		const sorted1 = [...types1].sort((a, b) => a - b);
+		const sorted2 = [...types2].sort((a, b) => a - b);
+		return sorted1.every((v, i) => v === sorted2[i]);
+	}
+	/**
+	* Filter out dontFragment relations from component types, but keep wildcard markers
+	*/
+	filterRegularComponentTypes(componentTypes) {
+		const regularTypes = [];
+		for (const componentType of componentTypes) {
+			if (isDontFragmentWildcard(componentType)) {
+				regularTypes.push(componentType);
+				continue;
+			}
+			if (isDontFragmentRelation(componentType)) 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();
+	}
+	/**
+	* Check if an archetype's signature references a specific entity
+	* (via entity-relation targeting the entity, or using entity as component type)
+	*/
+	archetypeReferencesEntity(archetype, entityId) {
+		for (const componentType of archetype.componentTypes) {
+			if (componentType === entityId) return true;
+			if (isEntityRelation(componentType)) {
+				if (getTargetIdFromRelationId(componentType) === entityId) return true;
+			}
+		}
+		return false;
+	}
+	/**
+	* Cleanup empty archetypes that reference a specific deleted entity
+	* Only removes archetypes whose component types reference the entity
+	*/
+	cleanupArchetypesReferencingEntity(entityId) {
+		for (let i = this.archetypes.length - 1; i >= 0; i--) {
+			const archetype = this.archetypes[i];
+			if (archetype.getEntities().length === 0 && this.archetypeReferencesEntity(archetype, entityId)) {
+				this.removeArchetypeFromList(archetype);
+				this.removeArchetypeFromSignatureMap(archetype);
+				this.removeArchetypeFromComponentIndex(archetype);
+				this.removeArchetypeFromQueries(archetype);
+			}
+		}
+	}
+	/**
+	* 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 componentId = getComponentIdFromRelationId(componentType);
+			if (componentId !== void 0) {
+				const wildcardRelationId = relation(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 componentId = getComponentIdFromRelationId(componentType);
+			if (componentId !== void 0) {
+				const wildcardRelationId = relation(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 { getComponentIdByName as a, isEntityId as c, relation as d, decodeRelationId as i, isRelationId as l, Query as n, getComponentNameById as o, component as r, isComponentId as s, World as t, isWildcardRelationId as u };
+//# sourceMappingURL=world.mjs.map