@codehz/ecs 0.10.0 → 0.10.1

package/dist/builder.d.mts

@@ -1022,8 +1022,9 @@ interface SingletonHandleOps<T> {
 /**
  * Explicit handle for a singleton component (component-as-entity).
  *
- * This provides an explicit and concise API for singleton components without
- * overloading `world.set()` semantics.
+ * This is the preferred API for singleton components.
+ * `world.set(componentId, value)` remains available only as a deprecated
+ * compatibility shorthand.
  *
  * @example
  * const config = world.singleton(Config);
@@ -1050,6 +1051,7 @@ declare class SingletonHandle<T = void> {
  * Manages entities and components
  */
 declare class World {
+  private static readonly DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING;
   private entityIdManager;
   private entityReferences;
   /** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
@@ -1119,6 +1121,10 @@ declare class World {
    * @overload set(entityId: EntityId, componentType: EntityId<void>): void
    * Marks a void component as present on the entity
    *
+   * @overload set<T>(componentId: ComponentId<T>, component: Exclude<NoInfer<T>, number>): void
+   * @deprecated Use `world.singleton(componentId).set(value)` or `world.set(componentId, componentId, value)` instead.
+   * Compatibility shorthand for singleton component data when the second argument is not a number
+   *
    * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
    * Adds or updates a component with data on the entity
    *
@@ -1129,9 +1135,12 @@ declare class World {
    * world.set(entity, Position, { x: 10, y: 20 });
    * world.set(entity, Marker); // void component
    * world.singleton(GlobalConfig).set({ debug: true }); // singleton component
+   * world.set(GlobalConfig, { debug: true }); // deprecated singleton compatibility shorthand
    * world.sync(); // Apply changes
    */
   set(entityId: EntityId, componentType: EntityId<void>): void;
+  /** @deprecated Use `world.singleton(componentId).set(value)` or `world.set(componentId, componentId, value)` instead. */
+  set<T>(componentId: ComponentId<T>, component: Exclude<NoInfer<T>, number>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
   /**
    * Removes a component from an entity.

package/dist/world.mjs

@@ -626,8 +626,9 @@ var EntityBuilder = class {
 /**
 * Explicit handle for a singleton component (component-as-entity).
 *
-* This provides an explicit and concise API for singleton components without
-* overloading `world.set()` semantics.
+* This is the preferred API for singleton components.
+* `world.set(componentId, value)` remains available only as a deprecated
+* compatibility shorthand.
 *
 * @example
 * const config = world.singleton(Config);
@@ -2746,15 +2747,25 @@ function assertSetComponentTypeValid(componentType) {
 /**
 * Resolve the (entity, componentType, value) for a set() call.
 */
-function resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, exists = () => true) {
+function resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, argCount = 3, exists = () => true) {
 	const targetEntityId = entityId;
+	if (argCount === 2 && isComponentId(targetEntityId) && typeof componentTypeOrComponent !== "number") {
+		assertEntityExists(targetEntityId, "Component entity", exists);
+		return {
+			entityId: targetEntityId,
+			componentType: targetEntityId,
+			component: componentTypeOrComponent,
+			deprecatedSingletonShorthand: true
+		};
+	}
 	const componentType = componentTypeOrComponent;
 	assertEntityExists(targetEntityId, "Entity", exists);
 	assertSetComponentTypeValid(componentType);
 	return {
 		entityId: targetEntityId,
 		componentType,
-		component: maybeComponent
+		component: maybeComponent,
+		deprecatedSingletonShorthand: false
 	};
 }
 /**
@@ -2944,7 +2955,8 @@ function deserializeWorld(ctx, snapshot) {
 * World class for ECS architecture
 * Manages entities and components
 */
-var World = class {
+var World = class World {
+	static DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING = "world.set(componentId, value) for singleton components is deprecated; use world.singleton(componentId).set(value) or world.set(componentId, componentId, value) instead.";
 	entityIdManager = new EntityIdManager();
 	entityReferences = /* @__PURE__ */ new Map();
 	/** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
@@ -3096,7 +3108,8 @@ var World = class {
 		return this.entityToArchetype.has(entityId);
 	}
 	set(entityId, componentTypeOrComponent, maybeComponent) {
-		const { entityId: targetEntityId, componentType, component } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, (id) => this.exists(id));
+		const { entityId: targetEntityId, componentType, component, deprecatedSingletonShorthand } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, arguments.length, (id) => this.exists(id));
+		if (deprecatedSingletonShorthand) console.warn(World.DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING);
 		this.commandBuffer.set(targetEntityId, componentType, component);
 	}
 	remove(entityId, componentType) {