@codehz/ecs 0.6.5 → 0.6.7

package/world.mjs

@@ -1766,6 +1766,8 @@ var World = class {
 	archetypesByComponent = /* @__PURE__ */ new Map();
 	entityReferences = /* @__PURE__ */ new Map();
 	dontFragmentRelations = /* @__PURE__ */ new Map();
+	componentEntityComponents = /* @__PURE__ */ new Map();
+	relationEntityIdsByTarget = /* @__PURE__ */ new Map();
 	queries = [];
 	queryCache = /* @__PURE__ */ new Map();
 	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
@@ -1776,6 +1778,18 @@ var World = class {
 	}
 	deserializeSnapshot(snapshot) {
 		if (snapshot.entityManager) this.entityIdManager.deserializeState(snapshot.entityManager);
+		if (Array.isArray(snapshot.componentEntities)) for (const entry of snapshot.componentEntities) {
+			const entityId = decodeSerializedId(entry.id);
+			if (!this.isComponentEntityId(entityId)) continue;
+			const componentsArray = entry.components || [];
+			const componentMap = /* @__PURE__ */ new Map();
+			for (const componentEntry of componentsArray) {
+				const componentType = decodeSerializedId(componentEntry.type);
+				componentMap.set(componentType, componentEntry.value);
+			}
+			this.componentEntityComponents.set(entityId, componentMap);
+			this.registerRelationEntityId(entityId);
+		}
 		if (Array.isArray(snapshot.entities)) for (const entry of snapshot.entities) {
 			const entityId = decodeSerializedId(entry.id);
 			const componentsArray = entry.components || [];
@@ -1799,6 +1813,18 @@ var World = class {
 	createArchetypeSignature(componentTypes) {
 		return componentTypes.join(",");
 	}
+	/**
+	* Creates a new entity.
+	* The entity is created with an empty component set and can be configured using `set()`.
+	*
+	* @template T - The initial component type (defaults to void if not specified)
+	* @returns A unique identifier for the new entity
+	*
+	* @example
+	* const entity = world.new<MyComponent>();
+	* world.set(entity, MyComponent, { value: 42 });
+	* world.sync();
+	*/
 	new() {
 		const entityId = this.entityIdManager.allocate();
 		let emptyArchetype = this.ensureArchetype([]);
@@ -1806,6 +1832,50 @@ var World = class {
 		this.entityToArchetype.set(entityId, emptyArchetype);
 		return entityId;
 	}
+	isComponentEntityId(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		return detailed.type !== "entity" && detailed.type !== "invalid";
+	}
+	registerRelationEntityId(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		if (detailed.type !== "entity-relation") return;
+		const targetId = detailed.targetId;
+		if (targetId === void 0) return;
+		const existing = this.relationEntityIdsByTarget.get(targetId);
+		if (existing) {
+			existing.add(entityId);
+			return;
+		}
+		this.relationEntityIdsByTarget.set(targetId, new Set([entityId]));
+	}
+	unregisterRelationEntityId(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		if (detailed.type !== "entity-relation") return;
+		const targetId = detailed.targetId;
+		if (targetId === void 0) return;
+		const existing = this.relationEntityIdsByTarget.get(targetId);
+		if (!existing) return;
+		existing.delete(entityId);
+		if (existing.size === 0) this.relationEntityIdsByTarget.delete(targetId);
+	}
+	getComponentEntityComponents(entityId, create) {
+		let data = this.componentEntityComponents.get(entityId);
+		if (!data && create) {
+			data = /* @__PURE__ */ new Map();
+			this.componentEntityComponents.set(entityId, data);
+			this.registerRelationEntityId(entityId);
+		}
+		return data;
+	}
+	clearComponentEntityComponents(entityId) {
+		if (this.componentEntityComponents.delete(entityId)) this.unregisterRelationEntityId(entityId);
+	}
+	cleanupComponentEntitiesReferencingEntity(targetId) {
+		const relationEntities = this.relationEntityIdsByTarget.get(targetId);
+		if (!relationEntities) return;
+		for (const relationEntityId of relationEntities) this.componentEntityComponents.delete(relationEntityId);
+		this.relationEntityIdsByTarget.delete(targetId);
+	}
 	destroyEntityImmediate(entityId) {
 		const queue = [entityId];
 		const visited = /* @__PURE__ */ new Set();
@@ -1827,9 +1897,22 @@ var World = class {
 			triggerRemoveHooksForEntityDeletion(this.createHooksContext(), cur, removedComponents, archetype);
 			this.cleanupArchetypesReferencingEntity(cur);
 			this.entityIdManager.deallocate(cur);
+			this.cleanupComponentEntitiesReferencingEntity(cur);
 		}
 	}
+	/**
+	* Checks if an entity exists in the world.
+	*
+	* @param entityId - The entity identifier to check
+	* @returns `true` if the entity exists, `false` otherwise
+	*
+	* @example
+	* if (world.exists(entityId)) {
+	*   console.log("Entity exists");
+	* }
+	*/
 	exists(entityId) {
+		if (this.isComponentEntityId(entityId)) return true;
 		return this.entityToArchetype.has(entityId);
 	}
 	set(entityId, componentType, component$1) {
@@ -1839,22 +1922,91 @@ var World = class {
 		if (detailedType.type === "wildcard-relation") throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
 		this.commandBuffer.set(entityId, componentType, component$1);
 	}
+	/**
+	* Removes a component from an entity.
+	* The change is buffered and takes effect after calling `world.sync()`.
+	* If the entity does not exist, throws an error.
+	*
+	* @template T - The component data type
+	* @param entityId - The entity identifier
+	* @param componentType - The component type to remove
+	*
+	* @throws {Error} If the entity does not exist
+	* @throws {Error} If the component type is invalid
+	*
+	* @example
+	* world.remove(entity, Position);
+	* world.sync(); // Apply changes
+	*/
 	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);
 	}
+	/**
+	* Deletes an entity and all its components from the world.
+	* The change is buffered and takes effect after calling `world.sync()`.
+	* Related entities may trigger cascade delete hooks if configured.
+	*
+	* @param entityId - The entity identifier to delete
+	*
+	* @example
+	* world.delete(entity);
+	* world.sync(); // Apply changes
+	*/
 	delete(entityId) {
 		this.commandBuffer.delete(entityId);
 	}
+	/**
+	* Checks if an entity has a specific component.
+	* Immediately reflects the current state without waiting for `sync()`.
+	*
+	* @template T - The component data type
+	* @param entityId - The entity identifier
+	* @param componentType - The component type to check
+	* @returns `true` if the entity has the component, `false` otherwise
+	*
+	* @example
+	* if (world.has(entity, Position)) {
+	*   const pos = world.get(entity, Position);
+	* }
+	*/
 	has(entityId, componentType) {
+		if (this.isComponentEntityId(entityId)) {
+			if (isWildcardRelationId(componentType)) {
+				const componentId = getComponentIdFromRelationId(componentType);
+				if (componentId === void 0) return false;
+				const data = this.componentEntityComponents.get(entityId);
+				if (!data) return false;
+				for (const key of data.keys()) if (getComponentIdFromRelationId(key) === componentId) return true;
+				return false;
+			}
+			return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
+		}
 		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) {
+	get(entityId, componentType = entityId) {
+		if (this.isComponentEntityId(entityId)) {
+			if (isWildcardRelationId(componentType)) {
+				const componentId = getComponentIdFromRelationId(componentType);
+				const data$1 = this.componentEntityComponents.get(entityId);
+				const relations = [];
+				if (componentId !== void 0 && data$1) {
+					for (const [key, value] of data$1.entries()) if (getComponentIdFromRelationId(key) === componentId) {
+						const detailed = getDetailedIdType(key);
+						if (detailed.type === "entity-relation" || detailed.type === "component-relation") relations.push([detailed.targetId, value]);
+					}
+				}
+				return relations;
+			}
+			const data = this.componentEntityComponents.get(entityId);
+			if (!data || !data.has(componentType)) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+			return data.get(componentType);
+		}
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
 		if (componentType >= 0 || componentType % 2 ** 42 !== 0) {
@@ -1864,7 +2016,25 @@ var World = class {
 		}
 		return archetype.get(entityId, componentType);
 	}
-	getOptional(entityId, componentType) {
+	getOptional(entityId, componentType = entityId) {
+		if (this.isComponentEntityId(entityId)) {
+			if (isWildcardRelationId(componentType)) {
+				const componentId = getComponentIdFromRelationId(componentType);
+				if (componentId === void 0) return void 0;
+				const data$1 = this.componentEntityComponents.get(entityId);
+				if (!data$1) return void 0;
+				const relations = [];
+				for (const [key, value] of data$1.entries()) if (getComponentIdFromRelationId(key) === componentId) {
+					const detailed = getDetailedIdType(key);
+					if (detailed.type === "entity-relation" || detailed.type === "component-relation") relations.push([detailed.targetId, value]);
+				}
+				if (relations.length === 0) return void 0;
+				return { value: relations };
+			}
+			const data = this.componentEntityComponents.get(entityId);
+			if (!data || !data.has(componentType)) return void 0;
+			return { value: data.get(componentType) };
+		}
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
 		if (isWildcardRelationId(componentType)) {
@@ -1957,9 +2127,47 @@ var World = class {
 			}
 		}
 	}
+	/**
+	* Synchronizes all buffered commands (set/remove/delete) to the world.
+	* This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
+	* Typically called once per frame at the end of your game loop.
+	*
+	* @example
+	* world.set(entity, Position, { x: 10, y: 20 });
+	* world.remove(entity, OldComponent);
+	* world.sync(); // Apply all buffered changes
+	*/
 	sync() {
 		this.commandBuffer.execute();
 	}
+	/**
+	* Creates a cached query for efficiently iterating entities with specific components.
+	* The query is cached internally and reused across calls with the same component types and filter.
+	*
+	* **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)
+	* @returns A Query instance that can be used to iterate matching entities
+	*
+	* @example
+	* // Create once, reuse many times
+	* 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;
+	* });
+	*
+	* // With filter
+	* const activeQuery = world.createQuery([Position], {
+	*   without: [Disabled]
+	* });
+	*/
 	createQuery(componentTypes, filter = {}) {
 		const sortedTypes = [...componentTypes].sort((a, b) => a - b);
 		const filterKey = serializeQueryFilter(filter);
@@ -1976,9 +2184,38 @@ var World = class {
 		});
 		return query;
 	}
+	/**
+	* Creates a new entity builder for fluent entity configuration.
+	* Useful for building entities with multiple components in a single expression.
+	*
+	* @returns An EntityBuilder instance
+	*
+	* @example
+	* const entity = world.spawn()
+	*   .with(Position, { x: 0, y: 0 })
+	*   .with(Velocity, { x: 1, y: 1 })
+	*   .build();
+	* world.sync(); // Apply changes
+	*/
 	spawn() {
 		return new EntityBuilder(this);
 	}
+	/**
+	* Spawns multiple entities with a configuration callback.
+	* More efficient than calling `spawn()` multiple times when creating many entities.
+	*
+	* @param count - Number of entities to spawn
+	* @param configure - Callback that receives an EntityBuilder and index; must return the configured builder
+	* @returns Array of created entity IDs
+	*
+	* @example
+	* const entities = world.spawnMany(100, (builder, index) => {
+	*   return builder
+	*     .with(Position, { x: index * 10, y: 0 })
+	*     .with(Velocity, { x: 0, y: 1 });
+	* });
+	* world.sync();
+	*/
 	spawnMany(count, configure) {
 		const entities = [];
 		for (let i = 0; i < count; i++) {
@@ -1994,6 +2231,17 @@ var World = class {
 		const index = this.queries.indexOf(query);
 		if (index !== -1) this.queries.splice(index, 1);
 	}
+	/**
+	* Releases a cached query and frees its resources if no longer needed.
+	* Call this when you're done using a query to allow the world to clean up its cache entry.
+	*
+	* @param query - The query to release
+	*
+	* @example
+	* const query = world.createQuery([Position]);
+	* // ... use query ...
+	* world.releaseQuery(query); // Optional cleanup
+	*/
 	releaseQuery(query) {
 		for (const [k, v] of this.queryCache.entries()) if (v.query === query) {
 			v.refCount--;
@@ -2005,6 +2253,14 @@ var World = class {
 			return;
 		}
 	}
+	/**
+	* Returns all archetypes that contain entities with the specified components.
+	* Used internally for query optimization but can be useful for debugging.
+	*
+	* @param componentTypes - Array of component types to match
+	* @returns Array of Archetype objects containing matching components
+	* @internal
+	*/
 	getMatchingArchetypes(componentTypes) {
 		if (componentTypes.length === 0) return [...this.archetypes];
 		const regularComponents = [];
@@ -2043,6 +2299,10 @@ var World = class {
 	}
 	executeEntityCommands(entityId, commands) {
 		const changeset = new ComponentChangeset();
+		if (this.isComponentEntityId(entityId)) {
+			this.executeComponentEntityCommands(entityId, commands);
+			return changeset;
+		}
 		if (commands.some((cmd) => cmd.type === "destroy")) {
 			this.destroyEntityImmediate(entityId);
 			return changeset;
@@ -2060,6 +2320,24 @@ var World = class {
 		triggerLifecycleHooks(this.createHooksContext(), entityId, changeset.adds, removedComponents, currentArchetype, newArchetype);
 		return changeset;
 	}
+	executeComponentEntityCommands(entityId, commands) {
+		if (commands.some((cmd) => cmd.type === "destroy")) {
+			this.clearComponentEntityComponents(entityId);
+			return;
+		}
+		for (const command of commands) if (command.type === "set" && command.componentType) this.getComponentEntityComponents(entityId, true).set(command.componentType, command.component);
+		else if (command.type === "delete" && command.componentType) {
+			const data = this.componentEntityComponents.get(entityId);
+			if (!data) continue;
+			if (isWildcardRelationId(command.componentType)) {
+				const componentId = getComponentIdFromRelationId(command.componentType);
+				if (componentId !== void 0) {
+					for (const key of Array.from(data.keys())) if (getComponentIdFromRelationId(key) === componentId) data.delete(key);
+				}
+			} else data.delete(command.componentType);
+			if (data.size === 0) this.clearComponentEntityComponents(entityId);
+		}
+	}
 	createHooksContext() {
 		return {
 			hooks: this.legacyHooks,
@@ -2148,6 +2426,27 @@ var World = class {
 		}
 		for (const query of this.queries) query.removeArchetype(archetype);
 	}
+	/**
+	* Serializes the entire world state to a plain JavaScript object.
+	* This creates a "memory snapshot" that can be stored or transmitted.
+	* The snapshot can be restored using `new World(snapshot)`.
+	*
+	* **Note:** This is NOT automatically persistent storage. To persist data,
+	* you must serialize the returned object to JSON or another format yourself.
+	*
+	* @returns A serializable object representing the world state
+	*
+	* @example
+	* // Create snapshot
+	* const snapshot = world.serialize();
+	*
+	* // Save to storage (example)
+	* localStorage.setItem('save', JSON.stringify(snapshot));
+	*
+	* // Later, restore from snapshot
+	* const savedData = JSON.parse(localStorage.getItem('save'));
+	* const newWorld = new World(savedData);
+	*/
 	serialize() {
 		const entities = [];
 		for (const archetype of this.archetypes) {
@@ -2160,10 +2459,19 @@ var World = class {
 				}))
 			});
 		}
+		const componentEntities = [];
+		for (const [entityId, components] of this.componentEntityComponents.entries()) componentEntities.push({
+			id: encodeEntityId(entityId),
+			components: Array.from(components.entries()).map(([rawType, value]) => ({
+				type: encodeEntityId(rawType),
+				value: value === MISSING_COMPONENT ? void 0 : value
+			}))
+		});
 		return {
 			version: 1,
 			entityManager: this.entityIdManager.serializeState(),
-			entities
+			entities,
+			componentEntities
 		};
 	}
 };