ecspresso 0.8.0 → 0.10.0

package/dist/reactive-query-manager.d.ts

@@ -3,13 +3,17 @@ import type EntityManager from "./entity-manager";
 /**
  * Definition for a reactive query with enter/exit callbacks
  */
-export interface ReactiveQueryDefinition<ComponentTypes extends Record<string, any>, WithComponents extends keyof ComponentTypes = keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never> {
+export interface ReactiveQueryDefinition<ComponentTypes extends Record<string, any>, WithComponents extends keyof ComponentTypes = keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never> {
     /** Components the entity must have */
     with: ReadonlyArray<WithComponents>;
     /** Components the entity must not have */
     without?: ReadonlyArray<WithoutComponents>;
+    /** Components to include in the entity type but not require for matching */
+    optional?: ReadonlyArray<OptionalComponents>;
+    /** Components the entity's direct parent must have */
+    parentHas?: ReadonlyArray<keyof ComponentTypes>;
     /** Called when an entity starts matching the query */
-    onEnter?: (entity: FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>) => void;
+    onEnter?: (entity: FilteredEntity<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>) => void;
     /** Called when an entity stops matching the query (receives just the ID since entity may be gone) */
     onExit?: (entityId: number) => void;
 }
@@ -19,13 +23,19 @@ export interface ReactiveQueryDefinition<ComponentTypes extends Record<string, a
 export default class ReactiveQueryManager<ComponentTypes extends Record<string, any>> {
     private queries;
     private entityManager;
+    /** Whether any registered query uses parentHas */
+    private _hasParentHasQueries;
     constructor(entityManager: EntityManager<ComponentTypes>);
+    /**
+     * Whether any registered reactive query uses parentHas filters
+     */
+    get hasParentHasQueries(): boolean;
     /**
      * Add a reactive query
      * @param name Unique name for the query
      * @param definition Query definition with callbacks
      */
-    addQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(name: string, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents>): void;
+    addQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never>(name: string, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>): void;
     /**
      * Remove a reactive query
      * @param name Name of the query to remove
@@ -56,4 +66,13 @@ export default class ReactiveQueryManager<ComponentTypes extends Record<string,
      * Fires enter/exit callbacks as appropriate based on current state vs tracked state
      */
     recheckEntity(entity: Entity<ComponentTypes>): void;
+    /**
+     * Recheck all children of a parent entity against parentHas queries.
+     * Called when a component is added/removed from a parent entity.
+     */
+    private _recheckChildren;
+    /**
+     * Recalculate the _hasParentHasQueries flag from all registered queries
+     */
+    private _recalcParentHasFlag;
 }

package/dist/system-builder.d.ts

@@ -1,6 +1,6 @@
 import Bundle from "./bundle";
 import ECSpresso from "./ecspresso";
-import type { FilteredEntity, System } from "./types";
+import type { FilteredEntity, System, SystemPhase } from "./types";
 /**
  * Builder class for creating type-safe ECS Systems with proper query inference
  */
@@ -14,6 +14,7 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
     private initializeFunction?;
     private eventHandlers?;
     private _priority;
+    private _phase;
     private _isRegistered;
     private _groups;
     private _inScreens?;
@@ -52,6 +53,14 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
      * @returns This SystemBuilder instance for method chaining
      */
     setPriority(priority: number): this;
+    /**
+     * Set the execution phase for this system.
+     * Systems are grouped by phase and executed in order:
+     * preUpdate -> fixedUpdate -> update -> postUpdate -> render
+     * @param phase The phase to assign this system to (default: 'update')
+     * @returns This SystemBuilder instance for method chaining
+     */
+    inPhase(phase: SystemPhase): this;
     /**
      * Add this system to a group. Systems can belong to multiple groups.
      * When any group a system belongs to is disabled, the system will be skipped.
@@ -86,9 +95,12 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
     /**
      * Add a query definition to the system
      */
-    addQuery<QueryName extends string, WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, NewQueries extends Queries & Record<QueryName, QueryDefinition<ComponentTypes, WithComponents, WithoutComponents>> = Queries & Record<QueryName, QueryDefinition<ComponentTypes, WithComponents, WithoutComponents>>>(name: QueryName, definition: {
+    addQuery<QueryName extends string, WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never, NewQueries extends Queries & Record<QueryName, QueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>> = Queries & Record<QueryName, QueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>>>(name: QueryName, definition: {
         with: ReadonlyArray<WithComponents>;
         without?: ReadonlyArray<WithoutComponents>;
+        changed?: ReadonlyArray<WithComponents>;
+        optional?: ReadonlyArray<OptionalComponents>;
+        parentHas?: ReadonlyArray<keyof ComponentTypes>;
     }): this extends SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, Queries> ? SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, NewQueries> : this extends SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, Queries> ? SystemBuilderWithBundle<ComponentTypes, EventTypes, ResourceTypes, NewQueries> : SystemBuilder<ComponentTypes, EventTypes, ResourceTypes, NewQueries>;
     /**
      * Set the system's process function that runs each update
@@ -145,12 +157,15 @@ export declare class SystemBuilder<ComponentTypes extends Record<string, any> =
  * @internal Used by SystemBuilder and Bundle
  */
 export declare function registerSystemWithEcspresso<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>>(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes>, ecspresso: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>): void;
-type QueryDefinition<ComponentTypes, WithComponents extends keyof ComponentTypes = any, WithoutComponents extends keyof ComponentTypes = any> = {
+type QueryDefinition<ComponentTypes, WithComponents extends keyof ComponentTypes = any, WithoutComponents extends keyof ComponentTypes = any, OptionalComponents extends keyof ComponentTypes = any> = {
     with: ReadonlyArray<WithComponents>;
     without?: ReadonlyArray<WithoutComponents>;
+    changed?: ReadonlyArray<WithComponents>;
+    optional?: ReadonlyArray<OptionalComponents>;
+    parentHas?: ReadonlyArray<keyof ComponentTypes>;
 };
 type QueryResults<ComponentTypes, Queries extends Record<string, QueryDefinition<ComponentTypes>>> = {
-    [QueryName in keyof Queries]: QueryName extends string ? FilteredEntity<ComponentTypes, Queries[QueryName] extends QueryDefinition<ComponentTypes, infer W, any> ? W : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, infer WO> ? WO : never>[] : never;
+    [QueryName in keyof Queries]: QueryName extends string ? FilteredEntity<ComponentTypes, Queries[QueryName] extends QueryDefinition<ComponentTypes, infer W, any, any> ? W : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, infer WO, any> ? WO : never, Queries[QueryName] extends QueryDefinition<ComponentTypes, any, any, infer O> ? O : never>[] : never;
 };
 /**
  * Function signature for system process methods

package/dist/types.d.ts

@@ -1,4 +1,10 @@
 import ECSpresso from "./ecspresso";
+/**
+ * Execution phase for systems. Systems are grouped by phase and executed
+ * in this fixed order: preUpdate -> fixedUpdate -> update -> postUpdate -> render.
+ * Within each phase, systems are sorted by priority (higher first).
+ */
+export type SystemPhase = 'preUpdate' | 'fixedUpdate' | 'update' | 'postUpdate' | 'render';
 export interface Entity<ComponentTypes> {
     id: number;
     components: Partial<ComponentTypes>;
@@ -45,15 +51,20 @@ export interface EventHandler<T> {
     callback: (data: T) => void;
     once: boolean;
 }
-export interface FilteredEntity<ComponentTypes, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never> {
+export interface FilteredEntity<ComponentTypes, WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never> {
     id: number;
-    components: Omit<Partial<ComponentTypes>, WithoutComponents> & {
+    components: Omit<Partial<ComponentTypes>, WithoutComponents | OptionalComponents> & {
         [K in WithComponents]: ComponentTypes[K];
+    } & {
+        [K in OptionalComponents]: ComponentTypes[K] | undefined;
     };
 }
-export interface QueryConfig<ComponentTypes, WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes> {
+export interface QueryConfig<ComponentTypes, WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes, OptionalComponents extends keyof ComponentTypes = WithComponents> {
     with: ReadonlyArray<WithComponents>;
     without?: ReadonlyArray<WithoutComponents>;
+    changed?: ReadonlyArray<WithComponents>;
+    optional?: ReadonlyArray<OptionalComponents>;
+    parentHas?: ReadonlyArray<keyof ComponentTypes>;
 }
 /**
  * Utility type to derive the entity type that would result from a query definition.
@@ -79,13 +90,19 @@ export interface QueryConfig<ComponentTypes, WithComponents extends keyof Compon
 export type QueryResultEntity<ComponentTypes extends Record<string, any>, QueryDef extends {
     with: ReadonlyArray<keyof ComponentTypes>;
     without?: ReadonlyArray<keyof ComponentTypes>;
-}> = FilteredEntity<ComponentTypes, QueryDef['with'][number], QueryDef['without'] extends ReadonlyArray<any> ? QueryDef['without'][number] : never>;
+    changed?: ReadonlyArray<keyof ComponentTypes>;
+    optional?: ReadonlyArray<keyof ComponentTypes>;
+    parentHas?: ReadonlyArray<keyof ComponentTypes>;
+}> = FilteredEntity<ComponentTypes, QueryDef['with'][number], QueryDef['without'] extends ReadonlyArray<any> ? QueryDef['without'][number] : never, QueryDef['optional'] extends ReadonlyArray<any> ? QueryDef['optional'][number] : never>;
 /**
  * Simplified query definition type for creating reusable queries
  */
-export type QueryDefinition<ComponentTypes extends Record<string, any>, WithComponents extends keyof ComponentTypes = keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = keyof ComponentTypes> = {
+export type QueryDefinition<ComponentTypes extends Record<string, any>, WithComponents extends keyof ComponentTypes = keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = keyof ComponentTypes, OptionalComponents extends keyof ComponentTypes = keyof ComponentTypes> = {
     with: ReadonlyArray<WithComponents>;
     without?: ReadonlyArray<WithoutComponents>;
+    changed?: ReadonlyArray<WithComponents>;
+    optional?: ReadonlyArray<OptionalComponents>;
+    parentHas?: ReadonlyArray<keyof ComponentTypes>;
 };
 /**
  * Helper function to create a query definition with proper type inference.
@@ -117,6 +134,9 @@ export type QueryDefinition<ComponentTypes extends Record<string, any>, WithComp
 export declare function createQueryDefinition<ComponentTypes extends Record<string, any>, const QueryDef extends {
     with: ReadonlyArray<keyof ComponentTypes>;
     without?: ReadonlyArray<keyof ComponentTypes>;
+    changed?: ReadonlyArray<keyof ComponentTypes>;
+    optional?: ReadonlyArray<keyof ComponentTypes>;
+    parentHas?: 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> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, any> = {}> {
     label: string;
@@ -125,6 +145,12 @@ export interface System<ComponentTypes extends Record<string, any> = {}, WithCom
      * When systems have the same priority, they execute in registration order
      */
     priority?: number;
+    /**
+     * Execution phase for this system (default: 'update')
+     * Systems are grouped by phase and executed in order:
+     * preUpdate -> fixedUpdate -> update -> postUpdate -> render
+     */
+    phase?: SystemPhase;
     /**
      * Groups this system belongs to. If any group is disabled, the system will be skipped.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecspresso",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"main": "dist/index.js",
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -18,6 +18,26 @@
 		"./bundles/utils/timers": {
 			"import": "./dist/bundles/utils/timers.js",
 			"types": "./dist/bundles/utils/timers.d.ts"
+		},
+		"./bundles/utils/transform": {
+			"import": "./dist/bundles/utils/transform.js",
+			"types": "./dist/bundles/utils/transform.d.ts"
+		},
+		"./bundles/utils/movement": {
+			"import": "./dist/bundles/utils/movement.js",
+			"types": "./dist/bundles/utils/movement.d.ts"
+		},
+		"./bundles/utils/bounds": {
+			"import": "./dist/bundles/utils/bounds.js",
+			"types": "./dist/bundles/utils/bounds.d.ts"
+		},
+		"./bundles/utils/collision": {
+			"import": "./dist/bundles/utils/collision.js",
+			"types": "./dist/bundles/utils/collision.d.ts"
+		},
+		"./bundles/utils/input": {
+			"import": "./dist/bundles/utils/input.js",
+			"types": "./dist/bundles/utils/input.d.ts"
 		}
 	},
 	"publishConfig": {
@@ -58,7 +78,7 @@
 	"scripts": {
 		"build:clean": "rm -rf dist",
 		"build:ts": "bun tsc -p tsconfig.build.json",
-		"build:js": "bun build --target=browser --sourcemap=linked --minify --external=pixi.js --outdir=dist src/index.ts src/bundles/renderers/renderer2D.ts src/bundles/utils/timers.ts",
+		"build:js": "bun scripts/build.ts",
 		"build": "bun build:clean && bun build:ts && bun build:js",
 		"check:types": "bun tsc --noEmit --skipLibCheck",
 		"check": "bun run check:types && bun test",