ecspresso 0.4.3 → 0.5.0

package/dist/screen-manager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Screen/State management for ECSpresso ECS framework
+ */
+import type EventBus from './event-bus';
+import type AssetManager from './asset-manager';
+import type ECSpresso from './ecspresso';
+import type { ScreenDefinition, ScreenResource, ScreenEvents, ScreenConfigurator } from './screen-types';
+/**
+ * Manages screen/state transitions for ECSpresso
+ */
+export default class ScreenManager<Screens extends Record<string, ScreenDefinition<any, any>> = Record<string, never>> {
+    private readonly screens;
+    private currentScreen;
+    private screenStack;
+    private eventBus;
+    private assetManager;
+    private ecs;
+    /**
+     * Set dependencies for screen transitions
+     * @internal
+     */
+    setDependencies(eventBus: EventBus<ScreenEvents>, assetManager: AssetManager<any> | null, ecs: ECSpresso<any, any, any, any, any>): void;
+    /**
+     * Register a screen definition
+     */
+    register<K extends string, Config extends Record<string, unknown>, State extends Record<string, unknown>>(name: K, definition: ScreenDefinition<Config, State>): void;
+    /**
+     * Transition to a new screen, clearing the stack
+     */
+    setScreen<K extends keyof Screens>(name: K, config: Screens[K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
+    /**
+     * Push a screen onto the stack (overlay)
+     */
+    pushScreen<K extends keyof Screens>(name: K, config: Screens[K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
+    /**
+     * Pop the current screen and return to the previous one
+     */
+    popScreen(): Promise<void>;
+    /**
+     * Exit a screen by name (internal helper)
+     */
+    private exitScreen;
+    /**
+     * Verify required assets are loaded before screen transition
+     */
+    private verifyRequiredAssets;
+    /**
+     * Get the current screen name
+     */
+    getCurrentScreen(): keyof Screens | null;
+    /**
+     * Get the current screen config (immutable)
+     */
+    getConfig<K extends keyof Screens>(): Screens[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    /**
+     * Get the current screen config or null
+     */
+    getConfigOrNull<K extends keyof Screens>(): (Screens[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | null;
+    /**
+     * Get the current screen state (mutable)
+     */
+    getState<K extends keyof Screens>(): Screens[K] extends ScreenDefinition<any, infer S> ? S : never;
+    /**
+     * Get the current screen state or null
+     */
+    getStateOrNull<K extends keyof Screens>(): (Screens[K] extends ScreenDefinition<any, infer S> ? S : never) | null;
+    /**
+     * Update the current screen state
+     */
+    updateState<K extends keyof Screens>(update: Partial<Screens[K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: Screens[K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<Screens[K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
+    /**
+     * Get the screen stack depth
+     */
+    getStackDepth(): number;
+    /**
+     * Check if current screen is an overlay
+     */
+    isOverlay(): boolean;
+    /**
+     * Check if a screen is active (current or in stack)
+     */
+    isActive(screenName: keyof Screens): boolean;
+    /**
+     * Check if a screen is the current screen
+     */
+    isCurrent(screenName: keyof Screens): boolean;
+    /**
+     * Create the $screen resource object
+     */
+    createResource(): ScreenResource<Screens>;
+    /**
+     * Get all registered screen names
+     */
+    getScreenNames(): Array<keyof Screens>;
+    /**
+     * Check if a screen is registered
+     */
+    hasScreen(name: keyof Screens): boolean;
+}
+/**
+ * Implementation of ScreenConfigurator for builder pattern
+ */
+export declare class ScreenConfiguratorImpl<Screens extends Record<string, ScreenDefinition<any, any>>> implements ScreenConfigurator<Screens> {
+    private readonly manager;
+    constructor(manager: ScreenManager<Screens>);
+    add<K extends string, Config extends Record<string, unknown>, State extends Record<string, unknown>>(name: K, definition: ScreenDefinition<Config, State>): ScreenConfigurator<Screens & Record<K, ScreenDefinition<Config, State>>>;
+    /**
+     * Get the underlying manager
+     * @internal
+     */
+    getManager(): ScreenManager<Screens>;
+}
+/**
+ * Create a new ScreenConfigurator for builder pattern usage
+ */
+export declare function createScreenConfigurator<Screens extends Record<string, ScreenDefinition<any, any>> = Record<string, never>>(manager?: ScreenManager<Screens>): ScreenConfiguratorImpl<Screens>;

package/dist/screen-types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Screen/State management types for ECSpresso ECS framework
+ */
+import type ECSpresso from './ecspresso';
+/**
+ * Definition for a screen including its state, lifecycle hooks, and requirements
+ */
+export interface ScreenDefinition<Config extends Record<string, unknown> = Record<string, never>, State extends Record<string, unknown> = Record<string, never>> {
+    /**
+     * Function to create initial state from config
+     */
+    readonly initialState: (config: Config) => State;
+    /**
+     * Lifecycle hook called when entering this screen
+     */
+    readonly onEnter?: (config: Config, ecs: ECSpresso<any, any, any, any, any>) => void | Promise<void>;
+    /**
+     * Lifecycle hook called when exiting this screen
+     */
+    readonly onExit?: (ecs: ECSpresso<any, any, any, any, any>) => void | Promise<void>;
+    /**
+     * Asset keys that must be loaded before entering this screen
+     */
+    readonly requiredAssets?: ReadonlyArray<string>;
+    /**
+     * Asset groups that must be loaded before entering this screen
+     */
+    readonly requiredAssetGroups?: ReadonlyArray<string>;
+}
+/**
+ * Entry in the screen stack for overlay support
+ */
+export interface ScreenStackEntry<Screens extends Record<string, ScreenDefinition<any, any>>, K extends keyof Screens = keyof Screens> {
+    readonly name: K;
+    readonly config: Screens[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    state: Screens[K] extends ScreenDefinition<any, infer S> ? S : never;
+}
+/**
+ * Helper to extract config type from a screen definition
+ */
+export type ScreenConfig<S extends ScreenDefinition<any, any>> = S extends ScreenDefinition<infer C, any> ? C : never;
+/**
+ * Helper to extract state type from a screen definition
+ */
+export type ScreenState<S extends ScreenDefinition<any, any>> = S extends ScreenDefinition<any, infer St> ? St : never;
+/**
+ * Resource interface for accessing screen state in systems
+ * Exposed as $screen resource
+ */
+export interface ScreenResource<Screens extends Record<string, ScreenDefinition<any, any>>> {
+    /**
+     * Current active screen name, or null if no screen
+     */
+    readonly current: keyof Screens | null;
+    /**
+     * Immutable config of the current screen
+     */
+    readonly config: Readonly<ScreenConfig<Screens[keyof Screens]>> | null;
+    /**
+     * Mutable state of the current screen
+     */
+    state: ScreenState<Screens[keyof Screens]> | null;
+    /**
+     * The screen stack (read-only view)
+     */
+    readonly stack: ReadonlyArray<ScreenStackEntry<Screens>>;
+    /**
+     * Whether the current screen is an overlay (has screens beneath it)
+     */
+    readonly isOverlay: boolean;
+    /**
+     * Current depth of the screen stack
+     */
+    readonly stackDepth: number;
+    /**
+     * Check if a specific screen is currently active (either current or in stack)
+     */
+    isActive(screenName: keyof Screens): boolean;
+    /**
+     * Check if a specific screen is the current screen
+     */
+    isCurrent(screenName: keyof Screens): boolean;
+}
+/**
+ * Events emitted by the screen system
+ */
+export interface ScreenEvents {
+    screenEnter: {
+        screen: string;
+        config: unknown;
+    };
+    screenExit: {
+        screen: string;
+    };
+    screenPush: {
+        screen: string;
+        config: unknown;
+    };
+    screenPop: {
+        screen: string;
+    };
+}
+/**
+ * Configuration for screen definitions during builder setup
+ */
+export interface ScreenConfigurator<Screens extends Record<string, ScreenDefinition<any, any>>> {
+    /**
+     * Add a screen definition
+     */
+    add<K extends string, Config extends Record<string, unknown>, State extends Record<string, unknown>>(name: K, definition: ScreenDefinition<Config, State>): ScreenConfigurator<Screens & Record<K, ScreenDefinition<Config, State>>>;
+}
+/**
+ * Type-safe screen state getter result
+ */
+export type CurrentScreenState<Screens extends Record<string, ScreenDefinition<any, any>>, CurrentScreen extends keyof Screens> = Screens[CurrentScreen] extends ScreenDefinition<any, infer S> ? S : never;
+/**
+ * Type-safe screen config getter result
+ */
+export type CurrentScreenConfig<Screens extends Record<string, ScreenDefinition<any, any>>, CurrentScreen extends keyof Screens> = Screens[CurrentScreen] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;

package/dist/system-builder.d.ts

@@ -15,16 +15,19 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
     private eventHandlers?;
     private _priority;
     private _isRegistered;
+    private _inScreens?;
+    private _excludeScreens?;
+    private _requiredAssets?;
     constructor(_label: string, _ecspresso?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes> | null, _bundle?: Bundle<ComponentTypes, EventTypes, ResourceTypes> | null);
     get label(): string;
     /**
      * Returns the associated bundle if one was provided in the constructor
      */
-    get bundle(): Bundle<ComponentTypes, EventTypes, ResourceTypes> | null;
+    get bundle(): Bundle<ComponentTypes, EventTypes, ResourceTypes, {}, {}> | null;
     /**
      * Returns the associated ECSpresso instance if one was provided in the constructor
      */
-    get ecspresso(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes> | null;
+    get ecspresso(): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, {}, {}> | null;
     /**
      * Auto-register this system with its ECSpresso instance if not already registered
      * @private
@@ -48,6 +51,30 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      * @returns This SystemBuilder instance for method chaining
      */
     setPriority(priority: number): this;
+    /**
+     * Restrict this system to only run in specified screens.
+     * System will be skipped during update() when the current screen
+     * is not in this list.
+     * @param screens Array of screen names where this system should run
+     * @returns This SystemBuilder instance for method chaining
+     */
+    inScreens(screens: ReadonlyArray<string>): this;
+    /**
+     * Exclude this system from running in specified screens.
+     * System will be skipped during update() when the current screen
+     * is in this list.
+     * @param screens Array of screen names where this system should NOT run
+     * @returns This SystemBuilder instance for method chaining
+     */
+    excludeScreens(screens: ReadonlyArray<string>): this;
+    /**
+     * Require specific assets to be loaded for this system to run.
+     * System will be skipped during update() if any required asset
+     * is not loaded.
+     * @param assets Array of asset keys that must be loaded
+     * @returns This SystemBuilder instance for method chaining
+     */
+    requiresAssets(assets: ReadonlyArray<string>): this;
     /**
      * Add a query definition to the system
      */

package/dist/types.d.ts

@@ -3,6 +3,26 @@ export interface Entity<ComponentTypes> {
     id: number;
     components: Partial<ComponentTypes>;
 }
+/**
+ * Options for removing an entity
+ */
+export interface RemoveEntityOptions {
+    /**
+     * Whether to also remove all descendants (default: true)
+     */
+    cascade?: boolean;
+}
+/**
+ * Event data emitted when an entity's parent changes
+ */
+export interface HierarchyChangedEvent {
+    /** The entity whose parent changed */
+    entityId: number;
+    /** The previous parent, or null if entity had no parent */
+    oldParent: number | null;
+    /** The new parent, or null if entity was orphaned */
+    newParent: number | null;
+}
 export interface EventHandler<T> {
     callback: (data: T) => void;
     once: boolean;
@@ -80,13 +100,28 @@ export declare function createQueryDefinition<ComponentTypes extends Record<stri
     with: ReadonlyArray<keyof ComponentTypes>;
     without?: ReadonlyArray<keyof ComponentTypes>;
 }>(queryDef: QueryDef): QueryDef;
-export interface System<ComponentTypes extends Record<string, any> = {}, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}> {
+export interface System<ComponentTypes extends Record<string, any> = {}, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, any> = {}> {
     label: string;
     /**
      * System priority - higher values execute first (default: 0)
      * When systems have the same priority, they execute in registration order
      */
     priority?: number;
+    /**
+     * Screens where this system should run. If specified, system only runs
+     * when current screen is in this list.
+     */
+    inScreens?: string[];
+    /**
+     * Screens where this system should NOT run. If specified, system skips
+     * when current screen is in this list.
+     */
+    excludeScreens?: string[];
+    /**
+     * Assets that must be loaded for this system to run.
+     * System will be skipped if any required asset is not loaded.
+     */
+    requiredAssets?: string[];
     entityQueries?: {
         [queryName: string]: QueryConfig<ComponentTypes, WithComponents, WithoutComponents>;
     };
@@ -98,19 +133,19 @@ export interface System<ComponentTypes extends Record<string, any> = {}, WithCom
      */
     process?(queries: {
         [queryName: string]: Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>;
-    } | Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>, deltaTime: number, ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): void;
+    } | Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>, deltaTime: number, ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
     /**
      * Lifecycle hook called when the system is initialized
      * This is called when ECSpresso.initialize() is invoked, after resources are initialized
      * Use this for one-time initialization that depends on resources
      * @param ecs The ECSpresso instance providing access to all ECS functionality
      */
-    onInitialize?(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): void | Promise<void>;
+    onInitialize?(ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void | Promise<void>;
     /**
      * Lifecycle hook called when the system is detached from the ECS
      * @param ecs The ECSpresso instance providing access to all ECS functionality
      */
-    onDetach?(ecs: import("./ecspresso").default<ComponentTypes, EventTypes, ResourceTypes>): void;
+    onDetach?(ecs: import("./ecspresso").default<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
     /**
      * Event handlers for specific event types
      */
@@ -121,7 +156,7 @@ export interface System<ComponentTypes extends Record<string, any> = {}, WithCom
              * @param data The event data specific to this event type
              * @param ecs The ECSpresso instance providing access to all ECS functionality
              */
-            handler(data: EventTypes[EventName], ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): void;
+            handler(data: EventTypes[EventName], ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
         };
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecspresso",
-	"version": "0.4.3",
+	"version": "0.5.0",
 	"main": "dist/index.js",
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",