@codehz/ecs 0.7.5 → 0.8.0

package/dist/world.mjs

@@ -5,18 +5,17 @@ const ENTITY_ID_START = 1024;
 * Constants for relation ID encoding
 */
 const RELATION_SHIFT = 2 ** 42;
-const WILDCARD_TARGET_ID = 0;
 /**
 * Check if a component ID is valid (1-1023)
 */
 function isValidComponentId(componentId) {
-	return componentId >= 1 && componentId <= COMPONENT_ID_MAX;
+	return componentId >= 1 && componentId <= 1023;
 }
 /**
 * Check if an ID is a component ID
 */
 function isComponentId(id) {
-	return id >= 1 && id <= COMPONENT_ID_MAX;
+	return id >= 1 && id <= 1023;
 }
 /**
 * Check if an ID is an entity ID
@@ -30,7 +29,6 @@ function isEntityId(id) {
 function isRelationId(id) {
 	return id < 0;
 }
-
 //#endregion
 //#region src/entity/relation.ts
 /**
@@ -49,7 +47,7 @@ function decodeRelationRaw(id) {
 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;
+	if (targetId === "*") actualTargetId = 0;
 	else {
 		if (!isEntityId(targetId) && !isComponentId(targetId)) throw new Error("Second argument must be a valid entity ID, component ID, or '*'");
 		actualTargetId = targetId;
@@ -64,7 +62,7 @@ function relation(componentId, targetId) {
 */
 function isWildcardRelationId(id) {
 	const decoded = decodeRelationRaw(id);
-	return decoded !== null && decoded.targetId === WILDCARD_TARGET_ID;
+	return decoded !== null && decoded.targetId === 0;
 }
 /**
 * Decode a relation ID into component and target IDs
@@ -78,7 +76,7 @@ function decodeRelationId(relationId) {
 	if (!isValidComponentId(rawComponentId)) throw new Error("Invalid component ID in relation");
 	const componentId = rawComponentId;
 	const targetId = rawTargetId;
-	if (targetId === WILDCARD_TARGET_ID) return {
+	if (targetId === 0) return {
 		componentId,
 		targetId,
 		type: "wildcard"
@@ -106,7 +104,7 @@ function getIdType(id) {
 		if (decoded === null) return "invalid";
 		const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
 		if (!isValidComponentId(rawComponentId)) return "invalid";
-		if (rawTargetId === WILDCARD_TARGET_ID) return "wildcard-relation";
+		if (rawTargetId === 0) return "wildcard-relation";
 		else if (isEntityId(rawTargetId)) return "entity-relation";
 		else if (isComponentId(rawTargetId)) return "component-relation";
 		else return "invalid";
@@ -128,7 +126,7 @@ function getDetailedIdType(id) {
 		if (!isValidComponentId(rawComponentId)) return { type: "invalid" };
 		const componentId = rawComponentId;
 		const targetId = rawTargetId;
-		if (targetId === WILDCARD_TARGET_ID) return {
+		if (targetId === 0) return {
 			type: "wildcard-relation",
 			componentId,
 			targetId
@@ -168,9 +166,8 @@ function getTargetIdFromRelationId(id) {
 */
 function isEntityRelation(id) {
 	const decoded = decodeRelationRaw(id);
-	return decoded !== null && decoded.targetId >= ENTITY_ID_START;
+	return decoded !== null && decoded.targetId >= 1024;
 }
-
 //#endregion
 //#region src/entity/manager.ts
 /**
@@ -248,7 +245,7 @@ var ComponentIdAllocator = class {
 	* Increments counter sequentially from 1
 	*/
 	allocate() {
-		if (this.nextId > COMPONENT_ID_MAX) throw new Error(`Component ID overflow: maximum ${COMPONENT_ID_MAX} components allowed`);
+		if (this.nextId > 1023) throw new Error(`Component ID overflow: maximum ${COMPONENT_ID_MAX} components allowed`);
 		const id = this.nextId;
 		this.nextId++;
 		return id;
@@ -266,7 +263,6 @@ var ComponentIdAllocator = class {
 		return this.nextId <= COMPONENT_ID_MAX;
 	}
 };
-
 //#endregion
 //#region src/utils/bit-set.ts
 var BitSet = class {
@@ -363,7 +359,6 @@ var BitSet = class {
 		}
 	}
 };
-
 //#endregion
 //#region src/component/registry.ts
 const globalComponentIdAllocator = new ComponentIdAllocator();
@@ -535,7 +530,7 @@ function checkRelationFlag(id, flagBitSet, targetCondition) {
 * @see {@link ComponentOptions.dontFragment} for the full explanation.
 */
 function isDontFragmentRelation(id) {
-	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
+	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== 0);
 }
 /**
 * Check if an ID is a wildcard relation (`relation(Comp, "*")`) backed by a
@@ -559,7 +554,7 @@ function isDontFragmentRelation(id) {
 * @see {@link ComponentOptions.dontFragment} for the full explanation.
 */
 function isDontFragmentWildcard(id) {
-	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
+	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === 0);
 }
 /**
 * Check if a relation ID is a cascade delete entity-relation.
@@ -578,9 +573,8 @@ function isDontFragmentWildcard(id) {
 * @see {@link ComponentOptions.cascadeDelete}
 */
 function isCascadeDeleteRelation(id) {
-	return checkRelationFlag(id, cascadeDeleteFlags, (targetId) => targetId !== WILDCARD_TARGET_ID && targetId >= ENTITY_ID_START);
+	return checkRelationFlag(id, cascadeDeleteFlags, (targetId) => targetId !== 0 && targetId >= 1024);
 }
-
 //#endregion
 //#region src/world/builder.ts
 /**
@@ -639,7 +633,6 @@ var EntityBuilder = class {
 		return entity;
 	}
 };
-
 //#endregion
 //#region src/component/type-utils.ts
 /**
@@ -649,13 +642,11 @@ var EntityBuilder = class {
 function normalizeComponentTypes(componentTypes) {
 	return [...componentTypes].sort((a, b) => a - b);
 }
-
 //#endregion
 //#region src/types/index.ts
 function isOptionalEntityId(type) {
 	return typeof type === "object" && type !== null && "optional" in type;
 }
-
 //#endregion
 //#region src/utils/utils.ts
 /**
@@ -676,7 +667,6 @@ function getOrCompute(cache, key, compute) {
 	}
 	return value;
 }
-
 //#endregion
 //#region src/archetype/helpers.ts
 /**
@@ -770,7 +760,6 @@ function buildSingleComponent(compType, dataSource, entityIndex, entityId, getCo
 	if (getIdType(actualType) === "wildcard-relation") return buildWildcardRelationValue(actualType, dataSource, (relType) => getComponentData(relType)[entityIndex], dontFragmentRelations.get(entityId), entityId, optional);
 	else return buildRegularComponentValue(dataSource, entityIndex, optional);
 }
-
 //#endregion
 //#region src/archetype/archetype.ts
 /**
@@ -1060,7 +1049,6 @@ var Archetype = class {
 		return false;
 	}
 };
-
 //#endregion
 //#region src/archetype/store.ts
 /**
@@ -1079,7 +1067,6 @@ var DontFragmentStoreImpl = class {
 		this.data.delete(entityId);
 	}
 };
-
 //#endregion
 //#region src/commands/buffer.ts
 /**
@@ -1101,12 +1088,12 @@ var CommandBuffer = class {
 	constructor(executeEntityCommands) {
 		this.executeEntityCommands = executeEntityCommands;
 	}
-	set(entityId, componentType, component$1) {
+	set(entityId, componentType, component) {
 		this.commands.push({
 			type: "set",
 			entityId,
 			componentType,
-			component: component$1
+			component
 		});
 	}
 	/**
@@ -1163,7 +1150,6 @@ var CommandBuffer = class {
 		this.commands = [];
 	}
 };
-
 //#endregion
 //#region src/commands/changeset.ts
 /**
@@ -1175,8 +1161,8 @@ var ComponentChangeset = class {
 	/**
 	* Add a component to the changeset
 	*/
-	set(componentType, component$1) {
-		this.adds.set(componentType, component$1);
+	set(componentType, component) {
+		this.adds.set(componentType, component);
 		this.removes.delete(componentType);
 	}
 	/**
@@ -1203,8 +1189,8 @@ var ComponentChangeset = class {
 	* Merge another changeset into this one
 	*/
 	merge(other) {
-		for (const [componentType, component$1] of other.adds) {
-			this.adds.set(componentType, component$1);
+		for (const [componentType, component] of other.adds) {
+			this.adds.set(componentType, component);
 			this.removes.delete(componentType);
 		}
 		for (const componentType of other.removes) {
@@ -1217,7 +1203,7 @@ var ComponentChangeset = class {
 	*/
 	applyTo(existingComponents) {
 		for (const componentType of this.removes) existingComponents.delete(componentType);
-		for (const [componentType, component$1] of this.adds) existingComponents.set(componentType, component$1);
+		for (const [componentType, component] of this.adds) existingComponents.set(componentType, component);
 		return existingComponents;
 	}
 	/**
@@ -1244,7 +1230,6 @@ var ComponentChangeset = class {
 		return changed ? Array.from(finalComponentTypes) : void 0;
 	}
 };
-
 //#endregion
 //#region src/component/entity-store.ts
 /**
@@ -1411,7 +1396,6 @@ var ComponentEntityStore = class {
 		if (existing.size === 0) this.relationEntityIdsByTarget.delete(targetId);
 	}
 };
-
 //#endregion
 //#region src/query/filter.ts
 /**
@@ -1452,7 +1436,6 @@ function matchesFilter(archetype, filter) {
 		else return !archetype.componentTypeSet.has(type);
 	});
 }
-
 //#endregion
 //#region src/query/query.ts
 /**
@@ -1518,9 +1501,9 @@ var Query = class {
 	getEntities() {
 		this.ensureNotDisposed();
 		if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
-			const result$1 = [];
-			for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) result$1.push(entity);
-			return result$1;
+			const result = [];
+			for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) result.push(entity);
+			return result;
 		}
 		const result = [];
 		for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) if (this.entityMatchesQuery(archetype, entity)) result.push(entity);
@@ -1659,7 +1642,6 @@ var Query = class {
 		return this.isDisposed;
 	}
 };
-
 //#endregion
 //#region src/query/registry.ts
 /**
@@ -1747,14 +1729,13 @@ var QueryRegistry = class {
 		for (const query of this.queries) query.removeArchetype(archetype);
 	}
 };
-
 //#endregion
 //#region src/world/commands.ts
 function processCommands(entityId, currentArchetype, commands, changeset, handleExclusiveRelation) {
 	for (const command of commands) if (command.type === "set") processSetCommand(entityId, currentArchetype, command.componentType, command.component, changeset, handleExclusiveRelation);
 	else if (command.type === "delete") processDeleteCommand(entityId, currentArchetype, command.componentType, changeset);
 }
-function processSetCommand(entityId, currentArchetype, componentType, component$1, changeset, handleExclusiveRelation) {
+function processSetCommand(entityId, currentArchetype, componentType, component, changeset, handleExclusiveRelation) {
 	const componentId = getComponentIdFromRelationId(componentType);
 	if (componentId !== void 0) {
 		handleExclusiveRelation(entityId, currentArchetype, componentId);
@@ -1766,10 +1747,10 @@ function processSetCommand(entityId, currentArchetype, componentType, component$
 	const merge = getComponentMerge(componentType);
 	if (merge !== void 0 && changeset.adds.has(componentType)) {
 		const prev = changeset.adds.get(componentType);
-		changeset.set(componentType, merge(prev, component$1));
+		changeset.set(componentType, merge(prev, component));
 		return;
 	}
-	changeset.set(componentType, component$1);
+	changeset.set(componentType, component);
 }
 function processDeleteCommand(entityId, currentArchetype, componentType, changeset) {
 	const componentId = getComponentIdFromRelationId(componentType);
@@ -1846,9 +1827,9 @@ function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArch
 	}
 	if (removedComponents !== null) applyDontFragmentChanges(ctx.dontFragmentStore, entityId, changeset, removedComponents);
 	else applyDontFragmentChangesNoHooks(ctx.dontFragmentStore, entityId, changeset);
-	for (const [componentType, component$1] of changeset.adds) {
+	for (const [componentType, component] of changeset.adds) {
 		if (isDontFragmentRelation(componentType)) continue;
-		currentArchetype.set(entityId, componentType, component$1);
+		currentArchetype.set(entityId, componentType, component);
 	}
 	return currentArchetype;
 }
@@ -1866,12 +1847,12 @@ function applyDontFragmentChanges(dontFragmentRelations, entityId, changeset, re
 			}
 		}
 	}
-	for (const [componentType, component$1] of changeset.adds) if (isDontFragmentRelation(componentType)) {
+	for (const [componentType, component] of changeset.adds) if (isDontFragmentRelation(componentType)) {
 		if (!entityRelations) {
 			entityRelations = /* @__PURE__ */ new Map();
 			dontFragmentRelations.set(entityId, entityRelations);
 		}
-		entityRelations.set(componentType, component$1);
+		entityRelations.set(componentType, component);
 	}
 	if (entityRelations && entityRelations.size === 0) dontFragmentRelations.delete(entityId);
 }
@@ -1880,12 +1861,12 @@ function applyDontFragmentChangesNoHooks(dontFragmentRelations, entityId, change
 	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) {
 		if (entityRelations) entityRelations.delete(componentType);
 	}
-	for (const [componentType, component$1] of changeset.adds) if (isDontFragmentRelation(componentType)) {
+	for (const [componentType, component] of changeset.adds) if (isDontFragmentRelation(componentType)) {
 		if (!entityRelations) {
 			entityRelations = /* @__PURE__ */ new Map();
 			dontFragmentRelations.set(entityId, entityRelations);
 		}
-		entityRelations.set(componentType, component$1);
+		entityRelations.set(componentType, component);
 	}
 	if (entityRelations && entityRelations.size === 0) dontFragmentRelations.delete(entityId);
 }
@@ -1901,7 +1882,6 @@ function filterRegularComponentTypes(componentTypes) {
 	}
 	return regularTypes;
 }
-
 //#endregion
 //#region src/world/hooks.ts
 /**
@@ -2019,9 +1999,12 @@ function reconstructWildcardWithRemoved(ctx, entityId, wildcardId, removedCompon
 	const currentData = ctx.get(entityId, wildcardId);
 	if (!Array.isArray(currentData)) throw new Error(`Expected wildcard relation data to be an array, but got ${typeof currentData} for entity ${entityId} and wildcard ${wildcardId}. This indicates a HooksContext implementation that does not conform to the expected contract.`);
 	const result = [...currentData];
-	for (const [removedCompId, removedValue] of removedComponents.entries()) if (componentMatchesHookType(removedCompId, wildcardId)) {
-		const targetId = getTargetIdFromRelationId(removedCompId);
-		if (targetId !== void 0) result.push([targetId, removedValue]);
+	for (const [removedCompId, removedValue] of removedComponents.entries()) {
+		if (isWildcardRelationId(removedCompId)) continue;
+		if (componentMatchesHookType(removedCompId, wildcardId)) {
+			const targetId = getTargetIdFromRelationId(removedCompId);
+			if (targetId !== void 0) result.push([targetId, removedValue]);
+		}
 	}
 	return result;
 }
@@ -2033,8 +2016,8 @@ function collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, re
 				const result = reconstructWildcardWithRemoved(ctx, entityId, optionalId, removedComponents);
 				return result.length > 0 ? { value: result } : void 0;
 			}
-			const match$1 = findMatchingComponent(removedComponents, optionalId);
-			return match$1 ? { value: match$1[1] } : ctx.getOptional(entityId, optionalId);
+			const match = findMatchingComponent(removedComponents, optionalId);
+			return match ? { value: match[1] } : ctx.getOptional(entityId, optionalId);
 		}
 		const compId = ct;
 		if (isWildcardRelationId(compId)) return reconstructWildcardWithRemoved(ctx, entityId, compId, removedComponents);
@@ -2054,8 +2037,8 @@ function collectComponentsFromRemoved(componentTypes, removedComponents) {
 				const result = collectWildcardFromRemoved(optionalId, removedComponents);
 				return result.length > 0 ? { value: result } : void 0;
 			}
-			const match$1 = findMatchingComponent(removedComponents, optionalId);
-			return match$1 ? { value: match$1[1] } : void 0;
+			const match = findMatchingComponent(removedComponents, optionalId);
+			return match ? { value: match[1] } : void 0;
 		}
 		const compId = ct;
 		if (isWildcardRelationId(compId)) return collectWildcardFromRemoved(compId, removedComponents);
@@ -2068,13 +2051,15 @@ function collectComponentsFromRemoved(componentTypes, removedComponents) {
 */
 function collectWildcardFromRemoved(wildcardId, removedComponents) {
 	const result = [];
-	for (const [removedCompId, removedValue] of removedComponents.entries()) if (componentMatchesHookType(removedCompId, wildcardId)) {
-		const targetId = getTargetIdFromRelationId(removedCompId);
-		if (targetId !== void 0) result.push([targetId, removedValue]);
+	for (const [removedCompId, removedValue] of removedComponents.entries()) {
+		if (isWildcardRelationId(removedCompId)) continue;
+		if (componentMatchesHookType(removedCompId, wildcardId)) {
+			const targetId = getTargetIdFromRelationId(removedCompId);
+			if (targetId !== void 0) result.push([targetId, removedValue]);
+		}
 	}
 	return result;
 }
-
 //#endregion
 //#region src/utils/multi-map.ts
 const _MISSING = Symbol("missing");
@@ -2144,7 +2129,6 @@ var MultiMap = class {
 		this._valueCount = 0;
 	}
 };
-
 //#endregion
 //#region src/world/references.ts
 function trackEntityReference(entityReferences, sourceEntityId, componentType, targetEntityId) {
@@ -2161,7 +2145,6 @@ function untrackEntityReference(entityReferences, sourceEntityId, componentType,
 function getEntityReferences(entityReferences, targetEntityId) {
 	return entityReferences.get(targetEntityId) ?? new MultiMap();
 }
-
 //#endregion
 //#region src/storage/serialization.ts
 /**
@@ -2239,7 +2222,6 @@ function decodeSerializedId(sid) {
 	}
 	throw new Error(`Invalid ID in snapshot: ${JSON.stringify(sid)}`);
 }
-
 //#endregion
 //#region src/world/serialization.ts
 /**
@@ -2309,7 +2291,6 @@ function deserializeWorld(ctx, snapshot) {
 		}
 	}
 }
-
 //#endregion
 //#region src/world/world.ts
 /**
@@ -2505,8 +2486,8 @@ var World = class {
 		};
 	}
 	set(entityId, componentTypeOrComponent, maybeComponent) {
-		const { entityId: targetEntityId, componentType, component: component$1 } = this.resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent);
-		this.commandBuffer.set(targetEntityId, componentType, component$1);
+		const { entityId: targetEntityId, componentType, component } = this.resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent);
+		this.commandBuffer.set(targetEntityId, componentType, component);
 	}
 	remove(entityId, componentType) {
 		const { entityId: targetEntityId, componentType: targetComponentType } = this.resolveRemoveOperation(entityId, componentType);
@@ -2631,25 +2612,28 @@ var World = class {
 	* **Important:** Store the query reference and reuse it across frames for optimal performance.
 	* Creating a new query each frame defeats the caching mechanism.
 	*
-	* @param componentTypes - Array of component types to match
-	* @param filter - Optional filter for additional constraints (e.g., without specific components)
+	* **Note on optional components:** Only **required** (non-optional) component types should be
+	* passed to `createQuery`. Optional components (wrapped with `{ optional: ... }`) must be
+	* specified at **iteration time** via {@link Query.forEach}, {@link Query.getEntitiesWithComponents},
+	* or {@link Query.iterate} — NOT here. Including optional wrappers in `createQuery` will cause
+	* undefined behavior because the internal normalization relies on numeric sorting of component IDs.
+	*
+	* @param componentTypes - Array of **required** component types to match (do not include optional wrappers)
+	* @param filter - Optional filter for additional constraints (e.g., exclude entities with certain components)
 	* @returns A Query instance that can be used to iterate matching entities
 	*
 	* @example
-	* // Create once, reuse many times
+	* // Create once, reuse many times (required components only)
 	* const movementQuery = world.createQuery([Position, Velocity]);
 	*
-	* // In game loop
-	* movementQuery.forEach((entity) => {
-	*   const pos = world.get(entity, Position);
-	*   const vel = world.get(entity, Velocity);
-	*   pos.x += vel.x;
-	*   pos.y += vel.y;
+	* // Optional components are passed at iteration time, not creation time:
+	* movementQuery.forEach([Position, { optional: Velocity }], (entity, pos, vel) => {
+	*   pos.x += vel?.value?.x ?? 0;
 	* });
 	*
 	* // With filter
 	* const activeQuery = world.createQuery([Position], {
-	*   without: [Disabled]
+	*   negativeComponentTypes: [Disabled]
 	* });
 	*/
 	createQuery(componentTypes, filter = {}) {
@@ -2821,11 +2805,11 @@ var World = class {
 		for (const componentType of changeset.removes) if (isEntityRelation(componentType)) {
 			const targetId = getTargetIdFromRelationId(componentType);
 			untrackEntityReference(this.entityReferences, entityId, componentType, targetId);
-		} else if (componentType >= ENTITY_ID_START) untrackEntityReference(this.entityReferences, entityId, componentType, componentType);
+		} else if (componentType >= 1024) untrackEntityReference(this.entityReferences, entityId, componentType, componentType);
 		for (const [componentType] of changeset.adds) if (isEntityRelation(componentType)) {
 			const targetId = getTargetIdFromRelationId(componentType);
 			trackEntityReference(this.entityReferences, entityId, componentType, targetId);
-		} else if (componentType >= ENTITY_ID_START) trackEntityReference(this.entityReferences, entityId, componentType, componentType);
+		} else if (componentType >= 1024) trackEntityReference(this.entityReferences, entityId, componentType, componentType);
 	}
 	ensureArchetype(componentTypes) {
 		const sortedTypes = normalizeComponentTypes(filterRegularComponentTypes(componentTypes));
@@ -2942,7 +2926,7 @@ var World = class {
 		return serializeWorld(this.archetypes, this.componentEntities, this.entityIdManager);
 	}
 };
-
 //#endregion
 export { getComponentIdByName as a, isWildcardRelationId as c, isEntityId as d, isRelationId as f, component as i, relation as l, Query as n, getComponentNameById as o, EntityBuilder as r, decodeRelationId as s, World as t, isComponentId as u };
+
 //# sourceMappingURL=world.mjs.map