@awesome-ecs/abstract 0.23.0 → 0.24.0

package/dist/components/index.d.cts

@@ -1,2 +1,2 @@
-import { m as IComponent, n as IdentityComponent, p as ComponentTypeUid, t as BasicComponentType } from "../identity-component-5neFUd2Q.cjs";
+import { f as ComponentTypeUid, n as IdentityComponent, p as IComponent, t as BasicComponentType } from "../identity-component-uU0yDR-y.cjs";
 export { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent };

package/dist/components/index.d.mts

@@ -1,2 +1,2 @@
-import { m as IComponent, n as IdentityComponent, p as ComponentTypeUid, t as BasicComponentType } from "../identity-component-BCmEilvk.mjs";
+import { f as ComponentTypeUid, n as IdentityComponent, p as IComponent, t as BasicComponentType } from "../identity-component-CgzvgBVh.mjs";
 export { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent };

package/dist/entities/index.d.cts

@@ -1,3 +1,3 @@
-import { a as IEntity, c as EntityProxy, d as RequiredProxies, f as TypedEntityProxy, i as EntityUid, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid, s as IEntityModelWithRequiredProxies, u as IEntityProxyRepository } from "../identity-component-5neFUd2Q.cjs";
-import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEventsDispatcher, f as IEntityEventsManager, i as IEntityUpdate, l as EntityEventUid, n as IEntityRepository, o as IEntitySnapshot, p as IEventData, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as IEntityEvent } from "../index-6OSsa_UD.cjs";
-export { EntityEventSubscriptionFilter, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+import { a as IEntity, c as IEntityProxy, d as TypedEntityProxy, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy, u as RequiredProxies } from "../identity-component-uU0yDR-y.cjs";
+import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEvent, f as IEntityEventsDispatcher, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, n as IEntityRepository, o as IEntitySnapshot, p as IEntityEventsManager, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as EntityEventUid } from "../index-qSeVF9hf.cjs";
+export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };

package/dist/entities/index.d.mts

@@ -1,3 +1,3 @@
-import { a as IEntity, c as EntityProxy, d as RequiredProxies, f as TypedEntityProxy, i as EntityUid, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid, s as IEntityModelWithRequiredProxies, u as IEntityProxyRepository } from "../identity-component-BCmEilvk.mjs";
-import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEventsDispatcher, f as IEntityEventsManager, i as IEntityUpdate, l as EntityEventUid, n as IEntityRepository, o as IEntitySnapshot, p as IEventData, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as IEntityEvent } from "../index-CQpE-5sx.mjs";
-export { EntityEventSubscriptionFilter, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+import { a as IEntity, c as IEntityProxy, d as TypedEntityProxy, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy, u as RequiredProxies } from "../identity-component-CgzvgBVh.mjs";
+import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEvent, f as IEntityEventsDispatcher, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, n as IEntityRepository, o as IEntitySnapshot, p as IEntityEventsManager, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as EntityEventUid } from "../index-CfEs8NEA.mjs";
+export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };

package/dist/factories/index.d.cts

@@ -1,6 +1,6 @@
-import { a as IEntity } from "../identity-component-5neFUd2Q.cjs";
-import { l as IPipelineContext, o as IPipeline } from "../index-BUadwkVZ.cjs";
-import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-BtPTY71-.cjs";
+import { a as IEntity } from "../identity-component-uU0yDR-y.cjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-DZvjMjYZ.cjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-J5AU4JAU.cjs";
 
 //#region src/factories/context-factory.d.ts
 interface IContextFactory {

package/dist/factories/index.d.mts

@@ -1,6 +1,6 @@
-import { a as IEntity } from "../identity-component-BCmEilvk.mjs";
-import { l as IPipelineContext, o as IPipeline } from "../index-DcirKLCP.mjs";
-import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-CW6-OhB4.mjs";
+import { a as IEntity } from "../identity-component-CgzvgBVh.mjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-D4jK3qG1.mjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-DULE7rVz.mjs";
 
 //#region src/factories/context-factory.d.ts
 interface IContextFactory {

package/dist/{identity-component-BCmEilvk.d.mts → identity-component-CgzvgBVh.d.mts}

@@ -132,6 +132,27 @@ interface IEntityProxyRepository {
    * @returns A readonly map of entity type UIDs to an array of their proxies.
    */
   getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+  /**
+   * Registers an entity as a scoped proxy, making it resolvable by any entity in the same scope.
+   * Only entity types marked as scopeRoot or scopedProxy should be registered.
+   * @param entity - The entity to register as a scoped proxy.
+   * @param scopeId - The scope in which to register.
+   */
+  setScopedProxy(entity: IEntityProxy, scopeId: string): void;
+  /**
+   * Retrieves a scoped proxy by scope ID and entity type.
+   * @param scopeId - The scope to look up.
+   * @param entityType - The entity type to resolve.
+   * @returns The scoped proxy, or null if none exists.
+   */
+  getScopedProxy(scopeId: string, entityType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Removes an entity from the scoped proxy index.
+   * Called during entity cleanup to unregister from scope resolution.
+   * @param entity - The entity to remove.
+   * @param scopeId - The scope to remove from.
+   */
+  removeScopedProxy(entity: IEntityProxy, scopeId: string): void;
 }
 //#endregion
 //#region src/entities/entity.d.ts
@@ -147,32 +168,24 @@ type EntityTypeUid = string | number;
 type EntityUid = string | number;
 /**
  * Represents the core identification and initialization data for an entity.
- * Every entity must have a model containing the minimal information needed for instantiation.
- * Models are immutable and define the entity's initial structure.
+ * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies when creating an entity.
  */
-interface IEntityModel {
+interface IEntityModel<TProxyTypes extends readonly EntityTypeUid[] = undefined> {
   /**
    * The unique identifier for this entity instance.
    */
   readonly uid: EntityUid;
   /**
-   * Optional array of proxies (references) to other entities.
-   * Used to establish relationships at entity creation time.
+   * The scope this entity belongs to.
+   * Automatically set by the framework — scopeRoot entities generate a UUID,
+   * child entities inherit from their parent via addEntity().
    */
-  readonly proxies?: readonly IEntityProxy[];
-}
-/**
- * Entity model with enforced required proxy relationships.
- * Used when an entity requires specific relationships to be present from creation.
- *
- * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies.
- */
-interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends IEntityModel {
+  readonly scopeId?: string;
   /**
-   * Required proxies for this entity.
-   * The array structure matches the TProxyTypes template to ensure type-safe proxy definitions.
+   * Optional array of proxies (references) to other entities.
+   * Used to establish relationships at entity creation time.
    */
-  readonly proxies: RequiredProxies<TProxyTypes>;
+  readonly proxies?: RequiredProxies<TProxyTypes>;
 }
 /**
  * The core entity interface representing a composition of components and relationships.
@@ -237,5 +250,5 @@ interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
   readonly lastUpdated?: Date;
 }
 //#endregion
-export { IEntity as a, EntityProxy as c, RequiredProxies as d, TypedEntityProxy as f, EntityUid as i, IEntityProxy as l, IComponent as m, IdentityComponent as n, IEntityModel as o, ComponentTypeUid as p, EntityTypeUid as r, IEntityModelWithRequiredProxies as s, BasicComponentType as t, IEntityProxyRepository as u };
-//# sourceMappingURL=identity-component-BCmEilvk.d.mts.map
+export { IEntity as a, IEntityProxy as c, TypedEntityProxy as d, ComponentTypeUid as f, EntityUid as i, IEntityProxyRepository as l, IdentityComponent as n, IEntityModel as o, IComponent as p, EntityTypeUid as r, EntityProxy as s, BasicComponentType as t, RequiredProxies as u };
+//# sourceMappingURL=identity-component-CgzvgBVh.d.mts.map

package/dist/{identity-component-5neFUd2Q.d.cts → identity-component-uU0yDR-y.d.cts}

@@ -132,6 +132,27 @@ interface IEntityProxyRepository {
    * @returns A readonly map of entity type UIDs to an array of their proxies.
    */
   getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+  /**
+   * Registers an entity as a scoped proxy, making it resolvable by any entity in the same scope.
+   * Only entity types marked as scopeRoot or scopedProxy should be registered.
+   * @param entity - The entity to register as a scoped proxy.
+   * @param scopeId - The scope in which to register.
+   */
+  setScopedProxy(entity: IEntityProxy, scopeId: string): void;
+  /**
+   * Retrieves a scoped proxy by scope ID and entity type.
+   * @param scopeId - The scope to look up.
+   * @param entityType - The entity type to resolve.
+   * @returns The scoped proxy, or null if none exists.
+   */
+  getScopedProxy(scopeId: string, entityType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Removes an entity from the scoped proxy index.
+   * Called during entity cleanup to unregister from scope resolution.
+   * @param entity - The entity to remove.
+   * @param scopeId - The scope to remove from.
+   */
+  removeScopedProxy(entity: IEntityProxy, scopeId: string): void;
 }
 //#endregion
 //#region src/entities/entity.d.ts
@@ -147,32 +168,24 @@ type EntityTypeUid = string | number;
 type EntityUid = string | number;
 /**
  * Represents the core identification and initialization data for an entity.
- * Every entity must have a model containing the minimal information needed for instantiation.
- * Models are immutable and define the entity's initial structure.
+ * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies when creating an entity.
  */
-interface IEntityModel {
+interface IEntityModel<TProxyTypes extends readonly EntityTypeUid[] = undefined> {
   /**
    * The unique identifier for this entity instance.
    */
   readonly uid: EntityUid;
   /**
-   * Optional array of proxies (references) to other entities.
-   * Used to establish relationships at entity creation time.
+   * The scope this entity belongs to.
+   * Automatically set by the framework — scopeRoot entities generate a UUID,
+   * child entities inherit from their parent via addEntity().
    */
-  readonly proxies?: readonly IEntityProxy[];
-}
-/**
- * Entity model with enforced required proxy relationships.
- * Used when an entity requires specific relationships to be present from creation.
- *
- * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies.
- */
-interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends IEntityModel {
+  readonly scopeId?: string;
   /**
-   * Required proxies for this entity.
-   * The array structure matches the TProxyTypes template to ensure type-safe proxy definitions.
+   * Optional array of proxies (references) to other entities.
+   * Used to establish relationships at entity creation time.
    */
-  readonly proxies: RequiredProxies<TProxyTypes>;
+  readonly proxies?: RequiredProxies<TProxyTypes>;
 }
 /**
  * The core entity interface representing a composition of components and relationships.
@@ -237,5 +250,5 @@ interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
   readonly lastUpdated?: Date;
 }
 //#endregion
-export { IEntity as a, EntityProxy as c, RequiredProxies as d, TypedEntityProxy as f, EntityUid as i, IEntityProxy as l, IComponent as m, IdentityComponent as n, IEntityModel as o, ComponentTypeUid as p, EntityTypeUid as r, IEntityModelWithRequiredProxies as s, BasicComponentType as t, IEntityProxyRepository as u };
-//# sourceMappingURL=identity-component-5neFUd2Q.d.cts.map
+export { IEntity as a, IEntityProxy as c, TypedEntityProxy as d, ComponentTypeUid as f, EntityUid as i, IEntityProxyRepository as l, IdentityComponent as n, IEntityModel as o, IComponent as p, EntityTypeUid as r, EntityProxy as s, BasicComponentType as t, RequiredProxies as u };
+//# sourceMappingURL=identity-component-uU0yDR-y.d.cts.map

package/dist/{index-CQpE-5sx.d.mts → index-CfEs8NEA.d.mts}

@@ -1,4 +1,4 @@
-import { a as IEntity, l as IEntityProxy, m as IComponent, n as IdentityComponent, o as IEntityModel, r as EntityTypeUid } from "./identity-component-BCmEilvk.mjs";
+import { a as IEntity, c as IEntityProxy, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./identity-component-CgzvgBVh.mjs";
 
 //#region src/entities/entity-events.d.ts
 /**
@@ -39,6 +39,25 @@ interface IEntityEvent<TEventData extends IEventData> {
    * The event payload containing type-specific data.
    */
   data: TEventData;
+  /**
+   * The scope of the dispatching entity.
+   * When set, the event is only delivered to subscribers in the same scope.
+   */
+  scopeId?: string;
+}
+/**
+ * Options for subscribing to an entity event.
+ */
+interface EntityEventSubscriptionOptions {
+  /**
+   * Optional function to determine which specific events are processed.
+   */
+  filter?: EntityEventSubscriptionFilter;
+  /**
+   * The scope of the subscribing entity.
+   * When set, the subscriber only receives events from the same scope.
+   */
+  scopeId?: string;
 }
 /**
  * Manages subscriptions and dispatching for entity events.
@@ -51,9 +70,9 @@ interface IEntityEventsManager {
    * The entity will be notified when events of that type are dispatched.
    * @param uid - The event type to subscribe to.
    * @param entity - The entity registering for this event type.
-   * @param filter - Optional function to determine which specific events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribe(uid: EntityEventUid, entity: IEntityProxy, filter?: EntityEventSubscriptionFilter): void;
+  subscribe(uid: EntityEventUid, entity: IEntityProxy, options?: EntityEventSubscriptionOptions): void;
   /**
    * Unsubscribes an entity from a specific event type.
    * The entity will no longer receive notifications for this event type.
@@ -305,5 +324,5 @@ interface IEntityScheduler {
   has(entityProxy: IEntityProxy): boolean;
 }
 //#endregion
-export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEventsDispatcher as d, IEntityEventsManager as f, IEntityUpdate as i, EntityEventUid as l, IEntityRepository as n, IEntitySnapshot as o, IEventData as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, IEntityEvent as u };
-//# sourceMappingURL=index-CQpE-5sx.d.mts.map
+export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEvent as d, IEntityEventsDispatcher as f, IEntityUpdate as i, EntityEventSubscriptionOptions as l, IEventData as m, IEntityRepository as n, IEntitySnapshot as o, IEntityEventsManager as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, EntityEventUid as u };
+//# sourceMappingURL=index-CfEs8NEA.d.mts.map

package/dist/{index-DcirKLCP.d.mts → index-D4jK3qG1.d.mts}

@@ -60,14 +60,14 @@ interface IMiddleware<TContext extends IPipelineContext> {
    * Can read and modify the context to influence downstream middleware and results.
    * @param context The pipeline context containing all relevant state.
    */
-  action(context: TContext): void;
+  action(context: TContext): void | Promise<void>;
   /**
    * Optional cleanup function executed during pipeline teardown.
    * Middlewares execute in reverse registration order during cleanup phase.
    * Used to release resources, clear temporary state, and perform final operations.
    * @param context The pipeline context (may be in modified state from action phases).
    */
-  cleanup?(context: TContext): void;
+  cleanup?(context: TContext): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/middleware-runner.d.ts
@@ -85,14 +85,14 @@ interface IMiddlewareRunner<TContext extends IPipelineContext> {
    * @param context The current pipeline context.
    * @param middleware The middleware whose action should be executed.
    */
-  dispatch(context: TContext, middleware: IMiddleware<TContext>): void;
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
   /**
    * Decides how to execute a middleware's cleanup.
    * Can add pre/post processing or error handling around cleanup operations.
    * @param context The current pipeline context.
    * @param middleware The middleware whose cleanup should be executed.
    */
-  cleanup(context: TContext, middleware: IMiddleware<TContext>): void;
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline.d.ts
@@ -130,7 +130,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    * Execution continues until all middleware complete or a middleware requests early termination.
    * @param context - The context object passed to all middleware.
    */
-  dispatch(context: Partial<TContext>): void;
+  dispatch(context: Partial<TContext>): void | Promise<void>;
   /**
    * Executes the cleanup phase with all registered middleware in reverse order.
    * Allows middleware to perform resource cleanup and final operations.
@@ -138,7 +138,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    *
    * @param context - The context object that will be passed to each middleware function.
    */
-  cleanup(context: Partial<TContext>): void;
+  cleanup(context: Partial<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline-nested.d.ts
@@ -209,7 +209,7 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param middleware - The ordered middleware array to execute.
    * @param startIndex - Optional starting position in the middleware array (default: 0).
    */
-  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void;
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void | Promise<void>;
   /**
    * Executes the cleanup phase of all middleware in reverse order.
    * All middleware cleanup functions are called (if defined), regardless of errors.
@@ -217,8 +217,8 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param context - The context passed to each middleware cleanup.
    * @param middleware - The ordered middleware array for cleanup (reversed during execution).
    */
-  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void;
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void | Promise<void>;
 }
 //#endregion
 export { IParentMiddleware as a, IMiddleware as c, IParentContext as i, IPipelineContext as l, INestedContext as n, IPipeline as o, INestedMiddleware as r, IMiddlewareRunner as s, IPipelineRunner as t, PipelineRuntime as u };
-//# sourceMappingURL=index-DcirKLCP.d.mts.map
+//# sourceMappingURL=index-D4jK3qG1.d.mts.map

package/dist/{index-CW6-OhB4.d.mts → index-DULE7rVz.d.mts}

@@ -1,8 +1,8 @@
-import { a as IEntity, c as EntityProxy, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid } from "./identity-component-BCmEilvk.mjs";
+import { a as IEntity, c as IEntityProxy, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy } from "./identity-component-CgzvgBVh.mjs";
 import { n as Immutable } from "./types-CnDtpKsY.mjs";
-import { i as IEntityUpdate, l as EntityEventUid, o as IEntitySnapshot, p as IEventData, u as IEntityEvent } from "./index-CQpE-5sx.mjs";
+import { d as IEntityEvent, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, o as IEntitySnapshot, u as EntityEventUid } from "./index-CfEs8NEA.mjs";
 import { i as ILogger, n as PerformanceTimeEntry, s as IJsonSerializer } from "./index-BWmhFdFg.mjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-DcirKLCP.mjs";
+import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-D4jK3qG1.mjs";
 
 //#region src/systems/pipeline/system-context-events.d.ts
 /**
@@ -50,9 +50,9 @@ interface ISystemContextEvents {
    * Subscribes to events of a specific type.
    * The entity will be notified of matching events through the update system.
    * @param uid - The event type to listen for.
-   * @param filter - Optional predicate to further filter which events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribeTo<TEventData extends IEventData>(uid: EntityEventUid, filter?: (event: IEntityEvent<TEventData>) => boolean): void;
+  subscribeTo(uid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
   /**
    * Stops listening for events of a specific type.
    * @param uid - The event type to stop listening for.
@@ -152,7 +152,7 @@ interface ISystemContextRepository {
    * @param proxy - Reference to the entity.
    * @returns The immutable entity instance.
    */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity>): Immutable<TEntity>;
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
   /**
    * Queues an entity for update.
    * Triggers the update pipeline for the entity.
@@ -322,6 +322,19 @@ interface ISystemsModule<TEntity extends IEntity> {
    * @returns The initialized entity.
    */
   readonly initEntity?: (model: IEntityModel) => TEntity;
+  /**
+   * If true, this entity type creates a new scope boundary when initialized.
+   * A new scope ID is auto-generated. All child entities inherit this scope.
+   * Typically used for root entities like Engine.
+   */
+  readonly scopeRoot?: boolean;
+  /**
+   * If true, this entity type registers itself as a scoped proxy when initialized.
+   * It joins the inherited scope and becomes resolvable via `context.proxies.get()`
+   * by any entity in the same scope. Throws if no scope exists.
+   * Typically used for scope-wide entities like Scene, Input, AssetsManager.
+   */
+  readonly scopedProxy?: boolean;
 }
 //#endregion
 //#region src/systems/pipeline/system-middleware.d.ts
@@ -365,6 +378,19 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> {
    * @returns This builder for method chaining.
    */
   addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
+  /**
+   * Marks this entity type as a scope root.
+   * When initialized, a new scope is auto-generated and all child entities inherit it.
+   * @returns This builder for method chaining.
+   */
+  setScopeRoot(): this;
+  /**
+   * Marks this entity type as a scoped proxy.
+   * When initialized, the entity registers itself in the inherited scope,
+   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * @returns This builder for method chaining.
+   */
+  setScopedProxy(): this;
 }
 //#endregion
 //#region src/systems/module/systems-module-repository.d.ts
@@ -469,6 +495,10 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
    * The system context for the current entity execution.
    */
   readonly systemContext: ISystemContext<TEntity>;
+  /**
+   * The proxy repository for managing entity proxy relationships and scopes.
+   */
+  readonly proxyRepository: IEntityProxyRepository;
 }
 //#endregion
 //#region src/systems/runtime/systems-runtime-middleware.d.ts
@@ -482,4 +512,4 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
 type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
 //#endregion
 export { ISystemsModuleRepository as a, ISystemsModule as c, ISystemContextSnapshot as d, ISystemContextScheduler as f, ISystemContextEvents as h, ISystemContextEntity as i, SystemType as l, ISystemContextProxies as m, ISystemsRuntimeContext as n, ISystemsModuleBuilder as o, ISystemContextRepository as p, ISystemsRuntime as r, ISystemMiddleware as s, ISystemsRuntimeMiddleware as t, ISystemContext as u };
-//# sourceMappingURL=index-CW6-OhB4.d.mts.map
+//# sourceMappingURL=index-DULE7rVz.d.mts.map

package/dist/{index-BUadwkVZ.d.cts → index-DZvjMjYZ.d.cts}

@@ -60,14 +60,14 @@ interface IMiddleware<TContext extends IPipelineContext> {
    * Can read and modify the context to influence downstream middleware and results.
    * @param context The pipeline context containing all relevant state.
    */
-  action(context: TContext): void;
+  action(context: TContext): void | Promise<void>;
   /**
    * Optional cleanup function executed during pipeline teardown.
    * Middlewares execute in reverse registration order during cleanup phase.
    * Used to release resources, clear temporary state, and perform final operations.
    * @param context The pipeline context (may be in modified state from action phases).
    */
-  cleanup?(context: TContext): void;
+  cleanup?(context: TContext): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/middleware-runner.d.ts
@@ -85,14 +85,14 @@ interface IMiddlewareRunner<TContext extends IPipelineContext> {
    * @param context The current pipeline context.
    * @param middleware The middleware whose action should be executed.
    */
-  dispatch(context: TContext, middleware: IMiddleware<TContext>): void;
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
   /**
    * Decides how to execute a middleware's cleanup.
    * Can add pre/post processing or error handling around cleanup operations.
    * @param context The current pipeline context.
    * @param middleware The middleware whose cleanup should be executed.
    */
-  cleanup(context: TContext, middleware: IMiddleware<TContext>): void;
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline.d.ts
@@ -130,7 +130,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    * Execution continues until all middleware complete or a middleware requests early termination.
    * @param context - The context object passed to all middleware.
    */
-  dispatch(context: Partial<TContext>): void;
+  dispatch(context: Partial<TContext>): void | Promise<void>;
   /**
    * Executes the cleanup phase with all registered middleware in reverse order.
    * Allows middleware to perform resource cleanup and final operations.
@@ -138,7 +138,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    *
    * @param context - The context object that will be passed to each middleware function.
    */
-  cleanup(context: Partial<TContext>): void;
+  cleanup(context: Partial<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline-nested.d.ts
@@ -209,7 +209,7 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param middleware - The ordered middleware array to execute.
    * @param startIndex - Optional starting position in the middleware array (default: 0).
    */
-  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void;
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void | Promise<void>;
   /**
    * Executes the cleanup phase of all middleware in reverse order.
    * All middleware cleanup functions are called (if defined), regardless of errors.
@@ -217,8 +217,8 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param context - The context passed to each middleware cleanup.
    * @param middleware - The ordered middleware array for cleanup (reversed during execution).
    */
-  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void;
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void | Promise<void>;
 }
 //#endregion
 export { IParentMiddleware as a, IMiddleware as c, IParentContext as i, IPipelineContext as l, INestedContext as n, IPipeline as o, INestedMiddleware as r, IMiddlewareRunner as s, IPipelineRunner as t, PipelineRuntime as u };
-//# sourceMappingURL=index-BUadwkVZ.d.cts.map
+//# sourceMappingURL=index-DZvjMjYZ.d.cts.map

package/dist/{index-BtPTY71-.d.cts → index-J5AU4JAU.d.cts}

@@ -1,8 +1,8 @@
-import { a as IEntity, c as EntityProxy, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid } from "./identity-component-5neFUd2Q.cjs";
+import { a as IEntity, c as IEntityProxy, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy } from "./identity-component-uU0yDR-y.cjs";
 import { n as Immutable } from "./types-DLOd2zXO.cjs";
-import { i as IEntityUpdate, l as EntityEventUid, o as IEntitySnapshot, p as IEventData, u as IEntityEvent } from "./index-6OSsa_UD.cjs";
+import { d as IEntityEvent, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, o as IEntitySnapshot, u as EntityEventUid } from "./index-qSeVF9hf.cjs";
 import { i as ILogger, n as PerformanceTimeEntry, s as IJsonSerializer } from "./index-eECJUE_O.cjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-BUadwkVZ.cjs";
+import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-DZvjMjYZ.cjs";
 
 //#region src/systems/pipeline/system-context-events.d.ts
 /**
@@ -50,9 +50,9 @@ interface ISystemContextEvents {
    * Subscribes to events of a specific type.
    * The entity will be notified of matching events through the update system.
    * @param uid - The event type to listen for.
-   * @param filter - Optional predicate to further filter which events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribeTo<TEventData extends IEventData>(uid: EntityEventUid, filter?: (event: IEntityEvent<TEventData>) => boolean): void;
+  subscribeTo(uid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
   /**
    * Stops listening for events of a specific type.
    * @param uid - The event type to stop listening for.
@@ -152,7 +152,7 @@ interface ISystemContextRepository {
    * @param proxy - Reference to the entity.
    * @returns The immutable entity instance.
    */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity>): Immutable<TEntity>;
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
   /**
    * Queues an entity for update.
    * Triggers the update pipeline for the entity.
@@ -322,6 +322,19 @@ interface ISystemsModule<TEntity extends IEntity> {
    * @returns The initialized entity.
    */
   readonly initEntity?: (model: IEntityModel) => TEntity;
+  /**
+   * If true, this entity type creates a new scope boundary when initialized.
+   * A new scope ID is auto-generated. All child entities inherit this scope.
+   * Typically used for root entities like Engine.
+   */
+  readonly scopeRoot?: boolean;
+  /**
+   * If true, this entity type registers itself as a scoped proxy when initialized.
+   * It joins the inherited scope and becomes resolvable via `context.proxies.get()`
+   * by any entity in the same scope. Throws if no scope exists.
+   * Typically used for scope-wide entities like Scene, Input, AssetsManager.
+   */
+  readonly scopedProxy?: boolean;
 }
 //#endregion
 //#region src/systems/pipeline/system-middleware.d.ts
@@ -365,6 +378,19 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> {
    * @returns This builder for method chaining.
    */
   addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
+  /**
+   * Marks this entity type as a scope root.
+   * When initialized, a new scope is auto-generated and all child entities inherit it.
+   * @returns This builder for method chaining.
+   */
+  setScopeRoot(): this;
+  /**
+   * Marks this entity type as a scoped proxy.
+   * When initialized, the entity registers itself in the inherited scope,
+   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * @returns This builder for method chaining.
+   */
+  setScopedProxy(): this;
 }
 //#endregion
 //#region src/systems/module/systems-module-repository.d.ts
@@ -469,6 +495,10 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
    * The system context for the current entity execution.
    */
   readonly systemContext: ISystemContext<TEntity>;
+  /**
+   * The proxy repository for managing entity proxy relationships and scopes.
+   */
+  readonly proxyRepository: IEntityProxyRepository;
 }
 //#endregion
 //#region src/systems/runtime/systems-runtime-middleware.d.ts
@@ -482,4 +512,4 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
 type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
 //#endregion
 export { ISystemsModuleRepository as a, ISystemsModule as c, ISystemContextSnapshot as d, ISystemContextScheduler as f, ISystemContextEvents as h, ISystemContextEntity as i, SystemType as l, ISystemContextProxies as m, ISystemsRuntimeContext as n, ISystemsModuleBuilder as o, ISystemContextRepository as p, ISystemsRuntime as r, ISystemMiddleware as s, ISystemsRuntimeMiddleware as t, ISystemContext as u };
-//# sourceMappingURL=index-BtPTY71-.d.cts.map
+//# sourceMappingURL=index-J5AU4JAU.d.cts.map

package/dist/{index-6OSsa_UD.d.cts → index-qSeVF9hf.d.cts}

@@ -1,4 +1,4 @@
-import { a as IEntity, l as IEntityProxy, m as IComponent, n as IdentityComponent, o as IEntityModel, r as EntityTypeUid } from "./identity-component-5neFUd2Q.cjs";
+import { a as IEntity, c as IEntityProxy, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./identity-component-uU0yDR-y.cjs";
 
 //#region src/entities/entity-events.d.ts
 /**
@@ -39,6 +39,25 @@ interface IEntityEvent<TEventData extends IEventData> {
    * The event payload containing type-specific data.
    */
   data: TEventData;
+  /**
+   * The scope of the dispatching entity.
+   * When set, the event is only delivered to subscribers in the same scope.
+   */
+  scopeId?: string;
+}
+/**
+ * Options for subscribing to an entity event.
+ */
+interface EntityEventSubscriptionOptions {
+  /**
+   * Optional function to determine which specific events are processed.
+   */
+  filter?: EntityEventSubscriptionFilter;
+  /**
+   * The scope of the subscribing entity.
+   * When set, the subscriber only receives events from the same scope.
+   */
+  scopeId?: string;
 }
 /**
  * Manages subscriptions and dispatching for entity events.
@@ -51,9 +70,9 @@ interface IEntityEventsManager {
    * The entity will be notified when events of that type are dispatched.
    * @param uid - The event type to subscribe to.
    * @param entity - The entity registering for this event type.
-   * @param filter - Optional function to determine which specific events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribe(uid: EntityEventUid, entity: IEntityProxy, filter?: EntityEventSubscriptionFilter): void;
+  subscribe(uid: EntityEventUid, entity: IEntityProxy, options?: EntityEventSubscriptionOptions): void;
   /**
    * Unsubscribes an entity from a specific event type.
    * The entity will no longer receive notifications for this event type.
@@ -305,5 +324,5 @@ interface IEntityScheduler {
   has(entityProxy: IEntityProxy): boolean;
 }
 //#endregion
-export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEventsDispatcher as d, IEntityEventsManager as f, IEntityUpdate as i, EntityEventUid as l, IEntityRepository as n, IEntitySnapshot as o, IEventData as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, IEntityEvent as u };
-//# sourceMappingURL=index-6OSsa_UD.d.cts.map
+export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEvent as d, IEntityEventsDispatcher as f, IEntityUpdate as i, EntityEventSubscriptionOptions as l, IEventData as m, IEntityRepository as n, IEntitySnapshot as o, IEntityEventsManager as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, EntityEventUid as u };
+//# sourceMappingURL=index-qSeVF9hf.d.cts.map

package/dist/pipelines/index.d.cts

@@ -1,2 +1,2 @@
-import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-BUadwkVZ.cjs";
+import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-DZvjMjYZ.cjs";
 export { IMiddleware, IMiddlewareRunner, INestedContext, INestedMiddleware, IParentContext, IParentMiddleware, IPipeline, IPipelineContext, IPipelineRunner, PipelineRuntime };

package/dist/pipelines/index.d.mts

@@ -1,2 +1,2 @@
-import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-DcirKLCP.mjs";
+import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-D4jK3qG1.mjs";
 export { IMiddleware, IMiddlewareRunner, INestedContext, INestedMiddleware, IParentContext, IParentMiddleware, IPipeline, IPipelineContext, IPipelineRunner, PipelineRuntime };

package/dist/systems/index.d.cts

@@ -1,2 +1,2 @@
-import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-BtPTY71-.cjs";
+import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-J5AU4JAU.cjs";
 export { ISystemContext, ISystemContextEntity, ISystemContextEvents, ISystemContextProxies, ISystemContextRepository, ISystemContextScheduler, ISystemContextSnapshot, ISystemMiddleware, ISystemsModule, ISystemsModuleBuilder, ISystemsModuleRepository, ISystemsRuntime, ISystemsRuntimeContext, ISystemsRuntimeMiddleware, SystemType };

package/dist/systems/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-CW6-OhB4.mjs";
+import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-DULE7rVz.mjs";
 export { ISystemContext, ISystemContextEntity, ISystemContextEvents, ISystemContextProxies, ISystemContextRepository, ISystemContextScheduler, ISystemContextSnapshot, ISystemMiddleware, ISystemsModule, ISystemsModuleBuilder, ISystemsModuleRepository, ISystemsRuntime, ISystemsRuntimeContext, ISystemsRuntimeMiddleware, SystemType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesome-ecs/abstract",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "A comprehensive Entity-Component-System (ECS) Architecture implementation. Abstract components.",
   "type": "module",
   "scripts": {
@@ -97,5 +97,5 @@
     "url": "https://github.com/privatebytes/awesome-ecs/issues"
   },
   "homepage": "https://github.com/privatebytes/awesome-ecs#readme",
-  "gitHead": "8409c84b5ac82181b01ad384d5732e84f6f5e13a"
+  "gitHead": "1146c6993998eaf82e765a7822d6cde176857a89"
 }