@codehz/ecs 0.9.0 → 0.10.1

package/README.md

@@ -222,7 +222,7 @@ bun run examples/inventory-system-relations.ts
 | `spawnMany(count, configure)`         | 批量创建多个实体                                                                    |
 | `exists(entity)`                      | 检查实体是否存在                                                                    |
 | `set(entity, componentId, data?)`     | 添加/更新组件（缓冲，`sync()` 后生效）。对 `void` 组件可不传 data                   |
-| `set(componentId, data)`              | 单例组件简写：`world.set(GlobalConfig, { ... })`                                    |
+| `singleton(componentId)`              | 获取单例组件句柄，推荐用 `world.singleton(Config).set(value)`                       |
 | `get(entity, componentId?)`           | 获取组件数据。**若组件不存在会抛出异常**，请先用 `has()` 检查或使用 `getOptional()` |
 | `getOptional(entity, componentId?)`   | 安全获取组件，返回 `{ value: T } \| undefined`                                      |
 | `has(entity, componentId?)`           | 检查组件是否存在                                                                    |
@@ -236,6 +236,18 @@ bun run examples/inventory-system-relations.ts
 | `serialize()`                         | 序列化世界状态为快照对象                                                            |
 | `sync()`                              | 执行所有延迟命令                                                                    |
 
+单例组件推荐写法：
+
+```ts
+const config = world.singleton(GlobalConfig);
+config.set({ debug: true });
+world.sync();
+
+if (config.has()) {
+  console.log(config.get());
+}
+```
+
 ### Query
 
 查询通过 `world.createQuery()` 创建，应**跨帧复用**以获得最佳性能。

package/dist/builder.d.mts

@@ -1009,39 +1009,66 @@ declare class Query {
   get disposed(): boolean;
 }
 //#endregion
+//#region src/world/singleton.d.ts
+interface SingletonHandleOps<T> {
+  has(): boolean;
+  get(): T;
+  getOptional(): {
+    value: T;
+  } | undefined;
+  remove(): void;
+  set(value: T | undefined): void;
+}
+/**
+ * Explicit handle for a singleton component (component-as-entity).
+ *
+ * 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);
+ * config.set({ debug: true });
+ * world.sync();
+ * console.log(config.get());
+ */
+declare class SingletonHandle<T = void> {
+  readonly componentId: ComponentId<T>;
+  private readonly ops;
+  constructor(componentId: ComponentId<T>, ops: SingletonHandleOps<T>);
+  has(): boolean;
+  get(): T;
+  getOptional(): {
+    value: T;
+  } | undefined;
+  remove(): void;
+  set(...args: T extends void ? [] : [value: NoInfer<T>]): void;
+}
+//#endregion
 //#region src/world/world.d.ts
 /**
  * World class for ECS architecture
  * Manages entities and components
  */
 declare class World {
+  private static readonly DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING;
   private entityIdManager;
-  private archetypes;
-  private archetypeBySignature;
-  private entityToArchetype;
-  private archetypesByComponent;
   private entityReferences;
-  /** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
-  private entityToReferencingArchetypes;
   /** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
   private readonly sparseStore;
   /** Component entity (singleton) storage */
   private readonly componentEntities;
+  private archetypeManager;
+  private get archetypes();
+  private get entityToArchetype();
+  private get archetypesByComponent();
+  private get entityToReferencingArchetypes();
   private readonly queryRegistry;
   private hooks;
-  private readonly _debugCollectors;
-  private _debugMigrations;
-  private _debugArchetypesCreated;
-  private _debugArchetypesRemoved;
+  private readonly debugStats;
   private commandBuffer;
-  private readonly _changeset;
-  private readonly _removeChangeset;
-  /** Cached command processor context to avoid per-entity object allocation */
-  private readonly _commandCtx;
-  /** Cached hooks context to avoid per-entity object allocation */
-  private readonly _hooksCtx;
+  private commandExecutor;
   constructor(snapshot?: SerializedWorld);
-  private createArchetypeSignature;
   /**
    * Creates a new entity.
    * The entity is created with an empty component set and can be configured using `set()`.
@@ -1086,11 +1113,6 @@ declare class World {
    * if (world.has(entity, Position)) { ... }
    */
   exists(entityId: EntityId): boolean;
-  private assertEntityExists;
-  private assertComponentTypeValid;
-  private assertSetComponentTypeValid;
-  private resolveSetOperation;
-  private resolveRemoveOperation;
   /**
    * Adds or updates a component on an entity (or marks void component as present).
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -1099,24 +1121,27 @@ 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
    *
-   * @overload set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void
-   * Adds or updates a singleton component (shorthand for set(componentId, componentId, component))
-   *
    * @throws {Error} If the entity does not exist
    * @throws {Error} If the component type is invalid or is a wildcard relation
    *
    * @example
    * world.set(entity, Position, { x: 10, y: 20 });
    * world.set(entity, Marker); // void component
-   * world.set(GlobalConfig, { debug: true }); // singleton 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;
-  set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void;
   /**
    * Removes a component from an entity.
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -1154,6 +1179,18 @@ declare class World {
    * world.sync(); // Apply changes
    */
   delete(entityId: EntityId): void;
+  /**
+   * Returns an explicit handle for a singleton component (component-as-entity).
+   *
+   * This is the preferred API for singleton components.
+   *
+   * @example
+   * const config = world.singleton(GlobalConfig);
+   * config.set({ debug: true });
+   * world.sync();
+   * console.log(config.get());
+   */
+  singleton<T>(componentId: ComponentId<T>): SingletonHandle<T>;
   /**
    * Checks if a specific **component** is present on an entity.
    *
@@ -1401,8 +1438,6 @@ declare class World {
    * This is intended for development/debugging and leak detection.
    */
   createDebugStatsCollector(callback: (stats: SyncDebugStats) => void): DebugStatsCollector;
-  private _resetDebugActivityCounters;
-  private _deliverDebugStats;
   /**
    * 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.
@@ -1498,7 +1533,6 @@ declare class World {
    * @internal
    */
   getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[];
-  private getArchetypesWithComponents;
   /**
    * Queries entities with specific components.
    * For simpler use cases, prefer using `createQuery()` with `forEach()` which is cached and more efficient.
@@ -1531,21 +1565,9 @@ declare class World {
     entity: EntityId;
     components: ComponentTuple<T>;
   }>;
-  private executeEntityCommands;
-  private applyEntityCommands;
-  private createHooksContext;
-  private removeComponentImmediate;
-  private updateEntityReferences;
   private ensureArchetype;
-  /** Add componentType to the reverse index if it contains an entity ID */
-  private addToReferencingIndex;
-  /** Remove componentType from the reverse index */
-  private removeFromReferencingIndex;
-  private createNewArchetype;
-  private updateArchetypeHookMatches;
-  private archetypeMatchesHook;
   private cleanupArchetypesReferencingEntity;
-  private removeArchetype;
+  private archetypeMatchesHook;
   /**
    * Serializes the entire world state to a plain JavaScript object.
    * This creates a "memory snapshot" that can be stored or transmitted.
@@ -1567,6 +1589,8 @@ declare class World {
    * const savedData = JSON.parse(localStorage.getItem('save'));
    * const newWorld = new World(savedData);
    */
+  private removeComponentImmediate;
+  private createHooksContext;
   serialize(): SerializedWorld;
 }
 //#endregion
@@ -1643,5 +1667,5 @@ declare class EntityBuilder {
   build(): EntityId;
 }
 //#endregion
-export { WildcardRelationId as A, isWildcardRelationId as C, EntityId as D, ComponentRelationId as E, isEntityId as M, isRelationId as N, EntityRelationId as O, decodeRelationId as S, ComponentId as T, getComponentIdByName as _, ComponentTuple as a, isSparseRelation as b, LifecycleCallback as c, SerializedComponent as d, SerializedEntity as f, component as g, ComponentOptions as h, Query as i, isComponentId as j, RelationId as k, LifecycleHook as l, SerializedWorld as m, EntityBuilder as n, ComponentType as o, SerializedEntityId as p, World as r, DebugStatsCollector as s, ComponentDef as t, SyncDebugStats as u, getComponentNameById as v, relation as w, isSparseWildcard as x, isSparseComponent as y };
+export { EntityRelationId as A, isSparseWildcard as C, ComponentId as D, relation as E, isRelationId as F, WildcardRelationId as M, isComponentId as N, ComponentRelationId as O, isEntityId as P, isSparseRelation as S, isWildcardRelationId as T, ComponentOptions as _, SingletonHandleOps as a, getComponentNameById as b, ComponentType as c, LifecycleHook as d, SyncDebugStats as f, SerializedWorld as g, SerializedEntityId as h, SingletonHandle as i, RelationId as j, EntityId as k, DebugStatsCollector as l, SerializedEntity as m, EntityBuilder as n, Query as o, SerializedComponent as p, World as r, ComponentTuple as s, ComponentDef as t, LifecycleCallback as u, component as v, decodeRelationId as w, isSparseComponent as x, getComponentIdByName as y };
 //# sourceMappingURL=builder.d.mts.map

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as WildcardRelationId, C as isWildcardRelationId, D as EntityId, E as ComponentRelationId, M as isEntityId, N as isRelationId, O as EntityRelationId, S as decodeRelationId, T as ComponentId, _ as getComponentIdByName, a as ComponentTuple, b as isSparseRelation, c as LifecycleCallback, d as SerializedComponent, f as SerializedEntity, g as component, h as ComponentOptions, i as Query, j as isComponentId, k as RelationId, l as LifecycleHook, m as SerializedWorld, n as EntityBuilder, o as ComponentType, p as SerializedEntityId, r as World, s as DebugStatsCollector, t as ComponentDef, u as SyncDebugStats, v as getComponentNameById, w as relation, x as isSparseWildcard, y as isSparseComponent } from "./builder.mjs";
-export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, type DebugStatsCollector, EntityBuilder, type EntityId, type EntityRelationId, type LifecycleCallback, type LifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, type SyncDebugStats, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isSparseComponent as isDontFragmentComponent, isSparseComponent, isSparseRelation as isDontFragmentRelation, isSparseRelation, isSparseWildcard as isDontFragmentWildcard, isSparseWildcard, isEntityId, isRelationId, isWildcardRelationId, relation };
+import { A as EntityRelationId, C as isSparseWildcard, D as ComponentId, E as relation, F as isRelationId, M as WildcardRelationId, N as isComponentId, O as ComponentRelationId, P as isEntityId, S as isSparseRelation, T as isWildcardRelationId, _ as ComponentOptions, a as SingletonHandleOps, b as getComponentNameById, c as ComponentType, d as LifecycleHook, f as SyncDebugStats, g as SerializedWorld, h as SerializedEntityId, i as SingletonHandle, j as RelationId, k as EntityId, l as DebugStatsCollector, m as SerializedEntity, n as EntityBuilder, o as Query, p as SerializedComponent, r as World, s as ComponentTuple, t as ComponentDef, u as LifecycleCallback, v as component, w as decodeRelationId, x as isSparseComponent, y as getComponentIdByName } from "./builder.mjs";
+export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, type DebugStatsCollector, EntityBuilder, type EntityId, type EntityRelationId, type LifecycleCallback, type LifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, SingletonHandle, type SingletonHandleOps, type SyncDebugStats, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isSparseComponent as isDontFragmentComponent, isSparseComponent, isSparseRelation as isDontFragmentRelation, isSparseRelation, isSparseWildcard as isDontFragmentWildcard, isSparseWildcard, isEntityId, isRelationId, isWildcardRelationId, relation };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as getComponentIdByName, c as isSparseRelation, d as isWildcardRelationId, f as relation, h as isRelationId, i as component, l as isSparseWildcard, m as isEntityId, n as Query, o as getComponentNameById, p as isComponentId, r as EntityBuilder, s as isSparseComponent, t as World, u as decodeRelationId } from "./world.mjs";
-export { EntityBuilder, Query, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isSparseComponent as isDontFragmentComponent, isSparseComponent, isSparseRelation as isDontFragmentRelation, isSparseRelation, isSparseWildcard as isDontFragmentWildcard, isSparseWildcard, isEntityId, isRelationId, isWildcardRelationId, relation };
+import { a as component, c as isSparseComponent, d as decodeRelationId, f as isWildcardRelationId, g as isRelationId, h as isEntityId, i as EntityBuilder, l as isSparseRelation, m as isComponentId, n as Query, o as getComponentIdByName, p as relation, r as SingletonHandle, s as getComponentNameById, t as World, u as isSparseWildcard } from "./world.mjs";
+export { EntityBuilder, Query, SingletonHandle, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isSparseComponent as isDontFragmentComponent, isSparseComponent, isSparseRelation as isDontFragmentRelation, isSparseRelation, isSparseWildcard as isDontFragmentWildcard, isSparseWildcard, isEntityId, isRelationId, isWildcardRelationId, relation };

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { A as WildcardRelationId, D as EntityId, T as ComponentId, c as LifecycleCallback, g as component, i as Query, k as RelationId, l as LifecycleHook, n as EntityBuilder, r as World, t as ComponentDef, w as relation } from "./builder.mjs";
+import { D as ComponentId, E as relation, M as WildcardRelationId, d as LifecycleHook, j as RelationId, k as EntityId, n as EntityBuilder, o as Query, r as World, t as ComponentDef, u as LifecycleCallback, v as component } from "./builder.mjs";
 
 //#region src/testing/index.d.ts
 /**

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { d as isWildcardRelationId, f as relation, i as component, r as EntityBuilder, t as World } from "./world.mjs";
+import { a as component, f as isWildcardRelationId, i as EntityBuilder, p as relation, t as World } from "./world.mjs";
 //#region src/testing/index.ts
 /**
 * A test fixture that manages a World instance and provides convenient