@codehz/ecs 0.6.8 → 0.6.10

package/builder.d.mts

@@ -64,10 +64,11 @@ declare function decodeRelationId(relationId: RelationId<any>): {
 };
 //#endregion
 //#region src/core/component-registry.d.ts
+type ComponentMerge<T = any> = (prev: T, next: T) => T;
 /**
  * Component options that define intrinsic properties
  */
-interface ComponentOptions {
+interface ComponentOptions<T = any> {
   /**
    * Optional name for the component (for serialization/debugging)
    */
@@ -93,6 +94,10 @@ interface ComponentOptions {
    * Inspired by Flecs' DontFragment trait.
    */
   dontFragment?: boolean;
+  /**
+   * Custom merge behavior for repeated set() of the same componentType in a single sync batch.
+   */
+  merge?: ComponentMerge<T>;
 }
 /**
  * Allocate a new component ID from the global allocator.
@@ -108,7 +113,7 @@ interface ComponentOptions {
  * // With name and options
  * const ChildOf = component({ name: "ChildOf", exclusive: true });
  */
-declare function component<T = void>(nameOrOptions?: string | ComponentOptions): ComponentId<T>;
+declare function component<T = void>(nameOrOptions?: string | ComponentOptions<T>): ComponentId<T>;
 /**
  * Get a component ID by its registered name
  * @param name The component name
@@ -163,13 +168,21 @@ declare class ComponentChangeset {
 //#region src/commands/command-buffer.d.ts
 /**
  * Command for deferred execution
+ * Uses discriminated union for type safety
  */
-interface Command {
-  type: "set" | "delete" | "destroy";
+type Command = {
+  type: "set";
   entityId: EntityId;
-  componentType?: EntityId<any>;
-  component?: any;
-}
+  componentType: EntityId<any>;
+  component: any;
+} | {
+  type: "delete";
+  entityId: EntityId;
+  componentType: EntityId<any>;
+} | {
+  type: "destroy";
+  entityId: EntityId;
+};
 //#endregion
 //#region src/core/types.d.ts
 /**
@@ -181,7 +194,7 @@ interface LegacyLifecycleHook<T = unknown> {
    */
   on_init?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
   /**
-   * Called when a component is added to an entity
+   * Called when a component is updated on an entity
    */
   on_set?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
   /**
@@ -235,6 +248,10 @@ declare class Archetype {
    * The component types that define this archetype
    */
   readonly componentTypes: EntityId<any>[];
+  /**
+   * Set version of componentTypes for O(1) lookups in hot paths
+   */
+  readonly componentTypeSet: ReadonlySet<EntityId<any>>;
   /**
    * List of entities in this archetype
    */
@@ -254,9 +271,6 @@ declare class Archetype {
    * Stored in World to avoid migration overhead when entities change archetypes
    */
   private dontFragmentRelations;
-  /**
-   * Cache for pre-computed component data sources to avoid repeated calculations
-   */
   /**
    * Multi-hooks that match this archetype
    */
@@ -267,10 +281,17 @@ declare class Archetype {
   private componentDataSourcesCache;
   constructor(componentTypes: EntityId<any>[], dontFragmentRelations: Map<EntityId, Map<EntityId<any>, any>>);
   get size(): number;
+  /**
+   * Check if the given component types match this archetype
+   * @param componentTypes - Component types to check (can be in any order)
+   * @returns true if the types match this archetype's component set
+   * @note This method handles unsorted input by internally sorting for comparison
+   */
   matches(componentTypes: EntityId<any>[]): boolean;
   addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
   private addDontFragmentRelations;
   getEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
+  getEntityDontFragmentRelations(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   dump(): Array<{
     entity: EntityId;
     components: Map<EntityId<any>, any>;
@@ -320,6 +341,8 @@ declare class Query {
   private filter;
   private cachedArchetypes;
   private isDisposed;
+  /** Cache key assigned by World for O(1) releaseQuery lookup */
+  _cacheKey: string | undefined;
   /** Cached wildcard component types for faster entity filtering */
   private wildcardTypes;
   /** Cached specific dontFragment relation types that need entity-level filtering */
@@ -401,9 +424,16 @@ type SerializedEntityId = number | string | {
   component: string;
   target: number | string | "*";
 };
+/**
+ * Serialized state of EntityIdManager
+ */
+interface SerializedEntityIdManager {
+  nextId: number;
+  freelist?: number[];
+}
 type SerializedWorld = {
   version: number;
-  entityManager: any;
+  entityManager: SerializedEntityIdManager;
   entities: SerializedEntity[];
   componentEntities?: SerializedEntity[];
 };
@@ -433,9 +463,14 @@ declare class World {
   private relationEntityIdsByTarget;
   private queries;
   private queryCache;
-  private commandBuffer;
   private legacyHooks;
   private hooks;
+  private commandBuffer;
+  private readonly _changeset;
+  /** 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;
   constructor(snapshot?: SerializedWorld);
   private deserializeSnapshot;
   private createArchetypeSignature;
@@ -471,6 +506,12 @@ declare class World {
    * }
    */
   exists(entityId: EntityId): boolean;
+  private assertEntityExists;
+  private assertComponentTypeValid;
+  private assertSetComponentTypeValid;
+  private resolveSetOperation;
+  private resolveRemoveOperation;
+  private getComponentEntityWildcardRelations;
   /**
    * 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()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "repository": {
     "url": "https://github.com/codehz/ecs"
   },