@codehz/ecs 0.4.0 → 0.4.2

package/world.mjs

@@ -1340,6 +1340,81 @@ var Query = class {
 //#endregion
 //#region src/world.ts
 /**
+* Encode an internal EntityId into a SerializedEntityId for snapshots
+*/
+function encodeEntityId(id) {
+	const detailed = getDetailedIdType(id);
+	switch (detailed.type) {
+		case "component": {
+			const name = getComponentNameById(id);
+			if (!name) console.warn(`Component ID ${id} has no registered name, serializing as number`);
+			return name || id;
+		}
+		case "entity-relation": {
+			const componentName = getComponentNameById(detailed.componentId);
+			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+			return {
+				component: componentName || detailed.componentId.toString(),
+				target: detailed.targetId
+			};
+		}
+		case "component-relation": {
+			const componentName = getComponentNameById(detailed.componentId);
+			const targetName = getComponentNameById(detailed.targetId);
+			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+			if (!targetName) console.warn(`Target component ID ${detailed.targetId} in relation has no registered name`);
+			return {
+				component: componentName || detailed.componentId.toString(),
+				target: targetName || detailed.targetId
+			};
+		}
+		case "wildcard-relation": {
+			const componentName = getComponentNameById(detailed.componentId);
+			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+			return {
+				component: componentName || detailed.componentId.toString(),
+				target: "*"
+			};
+		}
+		default: return id;
+	}
+}
+/**
+* Decode a SerializedEntityId back into an internal EntityId
+*/
+function decodeSerializedId(sid) {
+	if (typeof sid === "number") return sid;
+	if (typeof sid === "string") {
+		const id = getComponentIdByName(sid);
+		if (id === void 0) {
+			const num = parseInt(sid, 10);
+			if (!isNaN(num)) return num;
+			throw new Error(`Unknown component name in snapshot: ${sid}`);
+		}
+		return id;
+	}
+	if (typeof sid === "object" && sid !== null && typeof sid.component === "string") {
+		let compId = getComponentIdByName(sid.component);
+		if (compId === void 0) {
+			const num = parseInt(sid.component, 10);
+			if (!isNaN(num)) compId = num;
+		}
+		if (compId === void 0) throw new Error(`Unknown component name in snapshot: ${sid.component}`);
+		if (sid.target === "*") return relation(compId, "*");
+		let targetId;
+		if (typeof sid.target === "string") {
+			const tid = getComponentIdByName(sid.target);
+			if (tid === void 0) {
+				const num = parseInt(sid.target, 10);
+				if (!isNaN(num)) targetId = num;
+				else throw new Error(`Unknown target component name in snapshot: ${sid.target}`);
+			} else targetId = tid;
+		} else targetId = sid.target;
+		return relation(compId, targetId);
+	}
+	throw new Error(`Invalid ID in snapshot: ${JSON.stringify(sid)}`);
+}
+/**
 * World class for ECS architecture
 * Manages entities and components
 */
@@ -1375,27 +1450,12 @@ var World = class {
 		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 entityId = decodeSerializedId(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)}`);
+					const componentType = decodeSerializedId(componentEntry.type);
 					componentMap.set(componentType, componentEntry.value);
 					componentTypes.push(componentType);
 				}
@@ -1558,6 +1618,27 @@ var World = class {
 		return query;
 	}
 	/**
+	* Create an EntityBuilder for convenient entity creation.
+	* @returns EntityBuilder
+	*/
+	spawn() {
+		return new EntityBuilder(this);
+	}
+	/**
+	* Spawn multiple entities using an EntityBuilder configuration callback
+	* @param count number of entities
+	* @param configure builder configuration callback
+	* @returns Created entity IDs
+	*/
+	spawnMany(count, configure) {
+		const entities = [];
+		for (let i = 0; i < count; i++) {
+			const builder = new EntityBuilder(this);
+			entities.push(configure(builder, i).build());
+		}
+		return entities;
+	}
+	/**
 	* @internal Register a query for archetype update notifications
 	*/
 	_registerQuery(query) {
@@ -1958,16 +2039,6 @@ var World = class {
 		}
 	}
 	/**
-	* 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) {
@@ -2037,35 +2108,11 @@ var World = class {
 		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
-					};
-				})
+				id: encodeEntityId(entity),
+				components: Array.from(components.entries()).map(([rawType, value]) => ({
+					type: encodeEntityId(rawType),
+					value: value === MISSING_COMPONENT ? void 0 : value
+				}))
 			});
 		}
 		return {
@@ -2075,7 +2122,63 @@ var World = class {
 		};
 	}
 };
+var EntityBuilder = class {
+	world;
+	components = [];
+	constructor(world) {
+		this.world = world;
+	}
+	with(componentId, value) {
+		this.components.push({
+			type: "component",
+			id: componentId,
+			value
+		});
+		return this;
+	}
+	withTag(componentId) {
+		this.components.push({
+			type: "component",
+			id: componentId,
+			value: void 0
+		});
+		return this;
+	}
+	withRelation(componentId, targetEntity, value) {
+		this.components.push({
+			type: "relation",
+			componentId,
+			targetId: targetEntity,
+			value
+		});
+		return this;
+	}
+	withRelationTag(componentId, targetEntity) {
+		this.components.push({
+			type: "relation",
+			componentId,
+			targetId: targetEntity,
+			value: void 0
+		});
+		return this;
+	}
+	/**
+	* Create an entity and enqueue components to be applied. This method
+	* does NOT call `world.sync()` automatically; callers must invoke
+	* `world.sync()` to apply deferred commands.
+	* (Previously auto-synced; now a breaking change — buildDeferred() removed.)
+	*/
+	build() {
+		const entity = this.world.new();
+		for (const def of this.components) if (def.type === "component") this.world.set(entity, def.id, def.value);
+		else {
+			const relationId = relation(def.componentId, def.targetId);
+			this.world.set(entity, relationId, def.value);
+		}
+		return entity;
+	}
+};
 
 //#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 };
+export { decodeRelationId as a, isComponentId as c, isWildcardRelationId as d, relation as f, component as i, isEntityId as l, World as n, getComponentIdByName as o, Query as r, getComponentNameById as s, EntityBuilder as t, isRelationId as u };
 //# sourceMappingURL=world.mjs.map