@codehz/ecs 0.3.8 → 0.3.9

package/index.mjs

@@ -1,8 +1,4 @@
 //#region src/entity.ts
-/**
-* Constants for ID ranges
-*/
-const INVALID_COMPONENT_ID = 0;
 const COMPONENT_ID_MAX = 1023;
 const ENTITY_ID_START = 1024;
 /**
@@ -10,23 +6,6 @@ const ENTITY_ID_START = 1024;
 */
 const RELATION_SHIFT = 2 ** 42;
 const WILDCARD_TARGET_ID = 0;
-/**
-* Create a component ID
-* @param id Component identifier (1-1023)
-* @see component
-*/
-function createComponentId(id) {
-	if (id < 1 || id > COMPONENT_ID_MAX) throw new Error(`Component ID must be between 1 and ${COMPONENT_ID_MAX}`);
-	return id;
-}
-/**
-* Create an entity ID
-* @param id Entity identifier (starting from 1024)
-*/
-function createEntityId(id) {
-	if (id < ENTITY_ID_START) throw new Error(`Entity ID must be ${ENTITY_ID_START} or greater`);
-	return id;
-}
 function relation(componentId, targetId) {
 	if (!isComponentId(componentId)) throw new Error("First argument must be a valid component ID");
 	let actualTargetId;
@@ -142,24 +121,6 @@ function getDetailedIdType(id) {
 	return { type: "invalid" };
 }
 /**
-* Inspect an EntityId and return a human-readable string representation
-* @param id The EntityId to inspect
-* @returns A friendly string representation of the ID
-*/
-function inspectEntityId(id) {
-	if (id === INVALID_COMPONENT_ID) return "Invalid Component ID (0)";
-	if (isComponentId(id)) return `Component ID (${id})`;
-	if (isEntityId(id)) return `Entity ID (${id})`;
-	if (isRelationId(id)) try {
-		const decoded = decodeRelationId(id);
-		if (!isComponentId(decoded.componentId) || decoded.type !== "wildcard" && !isEntityId(decoded.targetId) && !isComponentId(decoded.targetId)) return `Invalid Relation ID (${id})`;
-		return `Relation ID: ${`Component ID (${decoded.componentId})`} -> ${decoded.type === "entity" ? `Entity ID (${decoded.targetId})` : decoded.type === "component" ? `Component ID (${decoded.targetId})` : "Wildcard (*)"}`;
-	} catch (error) {
-		return `Invalid Relation ID (${id})`;
-	}
-	return `Unknown ID (${id})`;
-}
-/**
 * Entity ID Manager for automatic allocation and freelist recycling
 */
 var EntityIdManager = class {
@@ -254,20 +215,36 @@ var ComponentIdAllocator = class {
 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.
-* Optionally register a name for the component.
-* The name is only for serialization/debugging and does not affect base functionality.
-* @param name Optional name for the component
+* @param nameOrOptions Optional name for the component (for serialization/debugging) or options object
 * @returns The allocated component ID
+* @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(name) {
+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;
 }
 /**
@@ -285,6 +262,30 @@ function getComponentIdByName(name) {
 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
@@ -358,6 +359,12 @@ var Archetype = class {
 	*/
 	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
@@ -366,9 +373,11 @@ var Archetype = class {
 	/**
 	* 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) {
+	constructor(componentTypes, dontFragmentRelations) {
 		this.componentTypes = [...componentTypes].sort((a, b) => a - b);
+		this.dontFragmentRelations = dontFragmentRelations;
 		for (const componentType of this.componentTypes) this.componentData.set(componentType, []);
 	}
 	/**
@@ -389,7 +398,7 @@ var Archetype = class {
 	/**
 	* Add an entity to this archetype with initial component data
 	* @param entityId The entity to add
-	* @param componentData Map of component type to component data
+	* @param componentData Map of component type to component data (includes both regular and dontFragment components)
 	*/
 	addEntity(entityId, componentData) {
 		if (this.entityToIndex.has(entityId)) throw new Error(`Entity ${entityId} is already in this archetype`);
@@ -400,11 +409,18 @@ var Archetype = class {
 			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
+	* @returns Map of component type to component data (includes both regular and dontFragment components)
 	*/
 	getEntity(entityId) {
 		const index = this.entityToIndex.get(entityId);
@@ -414,11 +430,13 @@ var Archetype = class {
 			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
+	* @returns Array of objects with entity and component data (includes both regular and dontFragment components)
 	*/
 	dump() {
 		const result = [];
@@ -429,6 +447,8 @@ var Archetype = class {
 				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
@@ -439,7 +459,7 @@ var Archetype = class {
 	/**
 	* Remove an entity from this archetype
 	* @param entityId The entity to remove
-	* @returns The component data of the removed entity
+	* @returns The component data of the removed entity (includes both regular and dontFragment components)
 	*/
 	removeEntity(entityId) {
 		const index = this.entityToIndex.get(entityId);
@@ -449,6 +469,11 @@ var Archetype = class {
 			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) {
@@ -487,10 +512,20 @@ var Archetype = class {
 					}
 				}
 			}
+			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 {
-			const data = this.getComponentData(componentType)[index];
-			return data === MISSING_COMPONENT ? void 0 : data;
+			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}`);
 		}
 	}
 	/**
@@ -500,11 +535,24 @@ var Archetype = class {
 	* @param data The component data
 	*/
 	set(entityId, componentType, data) {
-		if (!this.componentData.has(componentType)) throw new Error(`Component type ${componentType} is not in this archetype`);
 		const index = this.entityToIndex.get(entityId);
 		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
-		const dataArray = this.getComponentData(componentType);
-		dataArray[index] = data;
+		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
@@ -539,59 +587,82 @@ var Archetype = class {
 	* Helper: compute or return cached data sources for provided componentTypes
 	*/
 	getCachedComponentDataSources(componentTypes) {
-		const cacheKey = componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).join(",");
-		return getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
-			return componentTypes.map((compType) => {
-				let optional = false;
-				if (isOptionalEntityId(compType)) {
-					compType = compType.optional;
-					optional = true;
-				}
-				const detailedType = getDetailedIdType(compType);
-				if (detailedType.type === "wildcard-relation") {
-					const componentId = detailedType.componentId;
-					const matchingRelations = this.componentTypes.filter((ct) => {
-						const detailedCt = getDetailedIdType(ct);
-						if (detailedCt.type !== "entity-relation" && detailedCt.type !== "component-relation") return false;
-						return detailedCt.componentId === componentId;
-					});
-					return optional ? matchingRelations.length > 0 ? matchingRelations : void 0 : matchingRelations;
-				} else return optional ? this.getOptionalComponentData(compType) : this.getComponentData(compType);
-			});
+		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) => {
-			let compType = componentTypes[i];
-			let optional = false;
-			if (isOptionalEntityId(compType)) {
-				compType = compType.optional;
-				optional = true;
-			}
-			if (getIdType(compType) === "wildcard-relation") {
-				if (dataSource === void 0) if (optional) return;
-				else 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;
-			} else {
-				if (dataSource === void 0) if (optional) return;
-				else throw new Error(`No matching relations found for mandatory wildcard relation component type`);
-				const data = dataSource[entityIndex];
-				const result = data === MISSING_COMPONENT ? void 0 : data;
-				return optional ? { value: result } : result;
-			}
+			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
@@ -926,10 +997,16 @@ var Query = class {
 		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() {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+		this.ensureNotDisposed();
 		const result = [];
 		for (const archetype of this.cachedArchetypes) result.push(...archetype.getEntities());
 		return result;
@@ -940,7 +1017,7 @@ var Query = class {
 	* @returns Array of objects with entity and component data
 	*/
 	getEntitiesWithComponents(componentTypes) {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+		this.ensureNotDisposed();
 		const result = [];
 		for (const archetype of this.cachedArchetypes) {
 			const entitiesWithData = archetype.getEntitiesWithComponents(componentTypes);
@@ -954,7 +1031,7 @@ var Query = class {
 	* @param callback Function called for each entity with its components
 	*/
 	forEach(componentTypes, callback) {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+		this.ensureNotDisposed();
 		for (const archetype of this.cachedArchetypes) archetype.forEachWithComponents(componentTypes, callback);
 	}
 	/**
@@ -962,7 +1039,7 @@ var Query = class {
 	* @param componentTypes Array of component types to retrieve
 	*/
 	*iterate(componentTypes) {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+		this.ensureNotDisposed();
 		for (const archetype of this.cachedArchetypes) yield* archetype.iterateWithComponents(componentTypes);
 	}
 	/**
@@ -971,7 +1048,7 @@ var Query = class {
 	* @returns Array of component data for all matching entities
 	*/
 	getComponentData(componentType) {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+		this.ensureNotDisposed();
 		const result = [];
 		for (const archetype of this.cachedArchetypes) result.push(...archetype.getComponentData(componentType));
 		return result;
@@ -1119,6 +1196,8 @@ var World = class {
 	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 */
@@ -1129,10 +1208,6 @@ var World = class {
 	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
 	/** Stores lifecycle hooks for component and relation events */
 	hooks = /* @__PURE__ */ new Map();
-	/** Set of component IDs marked as exclusive relations */
-	exclusiveComponents = /* @__PURE__ */ new Set();
-	/** Set of component IDs that will cascade delete when the relation target is deleted */
-	cascadeDeleteComponents = /* @__PURE__ */ new Set();
 	/**
 	* Create a new World.
 	* If an optional snapshot object is provided (previously produced by `world.serialize()`),
@@ -1214,7 +1289,7 @@ var World = class {
 				const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
 				if (!sourceArchetype) continue;
 				const detailedType = getDetailedIdType(componentType);
-				if (detailedType.type === "entity-relation" && this.cascadeDeleteComponents.has(detailedType.componentId)) {
+				if (detailedType.type === "entity-relation" && isCascadeDeleteComponent(detailedType.componentId)) {
 					if (!visited.has(sourceEntityId)) queue.push(sourceEntityId);
 					continue;
 				}
@@ -1271,13 +1346,20 @@ var World = class {
 	*/
 	has(entityId, componentType) {
 		const archetype = this.entityToArchetype.get(entityId);
-		return archetype ? archetype.componentTypes.includes(componentType) : false;
+		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`);
-		if (getDetailedIdType(componentType).type !== "wildcard-relation") {
-			if (!archetype.componentTypes.includes(componentType)) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+		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);
 	}
@@ -1315,19 +1397,19 @@ var World = class {
 	}
 	/**
 	* Mark a component as exclusive relation
-	* For exclusive relations, an entity can have at most one relation per base component
+	* @deprecated This method has been removed. Use component options instead: component({ exclusive: true })
+	* @throws Always throws an error directing to the new API
 	*/
 	setExclusive(componentId) {
-		this.exclusiveComponents.add(componentId);
+		throw new Error("setExclusive has been removed. Use component options instead: component({ exclusive: true })");
 	}
 	/**
 	* Mark a component as cascade-delete relation
-	* For cascade relations, when the relation target entity is deleted,
-	* the referencing entity will also be deleted (cascade).
-	* Only applicable to entity-relation components
+	* @deprecated This method has been removed. Use component options instead: component({ cascadeDelete: true })
+	* @throws Always throws an error directing to the new API
 	*/
 	setCascadeDelete(componentId) {
-		this.cascadeDeleteComponents.add(componentId);
+		throw new Error("setCascadeDelete has been removed. Use component options instead: component({ cascadeDelete: true })");
 	}
 	/**
 	* Update the world (run all systems in dependency order)
@@ -1462,76 +1544,187 @@ var World = class {
 		}
 		const currentArchetype = this.entityToArchetype.get(entityId);
 		if (!currentArchetype) return changeset;
-		for (const command of commands) switch (command.type) {
-			case "set":
-				if (command.componentType) {
-					const detailedType = getDetailedIdType(command.componentType);
-					if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && this.exclusiveComponents.has(detailedType.componentId)) for (const componentType of currentArchetype.componentTypes) {
-						const componentDetailedType = getDetailedIdType(componentType);
-						if ((componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") && componentDetailedType.componentId === detailedType.componentId) changeset.delete(componentType);
-					}
-					changeset.set(command.componentType, command.component);
-				}
-				break;
-			case "delete":
-				if (command.componentType) {
-					const detailedType = getDetailedIdType(command.componentType);
-					if (detailedType.type === "wildcard-relation") {
-						const baseComponentId = detailedType.componentId;
-						for (const componentType of currentArchetype.componentTypes) {
-							const componentDetailedType = getDetailedIdType(componentType);
-							if (componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") {
-								if (componentDetailedType.componentId === baseComponentId) changeset.delete(componentType);
-							}
-						}
-					} else changeset.delete(command.componentType);
-				}
-				break;
+		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);
 		}
-		const finalComponentTypes = changeset.getFinalComponentTypes(currentArchetype.componentTypes);
-		const removedCompoents = /* @__PURE__ */ new Map();
-		if (finalComponentTypes) {
-			const newArchetype = this.ensureArchetype(finalComponentTypes);
-			const currentComponents = currentArchetype.removeEntity(entityId);
-			for (const componentType of changeset.removes) removedCompoents.set(componentType, currentComponents.get(componentType));
-			newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
-			this.entityToArchetype.set(entityId, newArchetype);
-		} else for (const [componentType, component$1] of changeset.adds) currentArchetype.set(entityId, componentType, component$1);
+	}
+	/**
+	* 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") {
-				const targetEntityId = detailedType.targetId;
-				this.untrackEntityReference(entityId, componentType, targetEntityId);
-			} else if (detailedType.type === "entity") this.untrackEntityReference(entityId, componentType, componentType);
+			if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && isDontFragmentComponent(detailedType.componentId)) return true;
 		}
-		for (const [componentType, component$1] of changeset.adds) {
+		for (const [componentType] of changeset.adds) {
 			const detailedType = getDetailedIdType(componentType);
-			if (detailedType.type === "entity-relation") {
-				const targetEntityId = detailedType.targetId;
-				this.trackEntityReference(entityId, componentType, targetEntityId);
-			} else if (detailedType.type === "entity") this.trackEntityReference(entityId, componentType, 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);
 		}
-		this.triggerLifecycleHooks(entityId, changeset.adds, removedCompoents);
-		return changeset;
 	}
 	/**
 	* Get or create an archetype for the given component types
-	* @returns The archetype for the given component types
+	* Filters out dontFragment relations from the archetype signature
+	* @returns The archetype for the given component types (excluding dontFragment relations)
 	*/
 	ensureArchetype(componentTypes) {
-		const sortedTypes = Array.from(componentTypes).sort((a, b) => a - b);
+		const sortedTypes = this.filterRegularComponentTypes(componentTypes).sort((a, b) => a - b);
 		const hashKey = this.createArchetypeSignature(sortedTypes);
-		return getOrCreateWithSideEffect(this.archetypeBySignature, hashKey, () => {
-			const newArchetype = new Archetype(sortedTypes);
-			this.archetypes.push(newArchetype);
-			for (const componentType of sortedTypes) {
-				const archetypes = this.archetypesByComponent.get(componentType) || [];
-				archetypes.push(newArchetype);
-				this.archetypesByComponent.set(componentType, archetypes);
-			}
-			for (const query of this.queries) query.checkNewArchetype(newArchetype);
-			return newArchetype;
-		});
+		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
@@ -1569,10 +1762,29 @@ var World = class {
 	*/
 	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) {
@@ -1583,6 +1795,11 @@ var World = class {
 				}
 			}
 		}
+	}
+	/**
+	* Remove archetype from all queries
+	*/
+	removeArchetypeFromQueries(archetype) {
 		for (const query of this.queries) query.removeArchetype(archetype);
 	}
 	/**
@@ -1660,5 +1877,5 @@ var World = class {
 };
 
 //#endregion
-export { Archetype, COMPONENT_ID_MAX, ComponentIdAllocator, ENTITY_ID_START, EntityIdManager, INVALID_COMPONENT_ID, MISSING_COMPONENT, Query, RELATION_SHIFT, SystemScheduler, WILDCARD_TARGET_ID, World, component, createComponentId, createEntityId, decodeRelationId, getComponentIdByName, getComponentNameById, getDetailedIdType, getIdType, inspectEntityId, isComponentId, isEntityId, isOptionalEntityId, isRelationId, isWildcardRelationId, relation };
+export { Query, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };
 //# sourceMappingURL=index.mjs.map