✨ core: tracking modifiers with logical OR (#225)

* ✨ core: implement tracking modifiers in Or

* ⚡️ core: use tracking groups; optimize queries

Author: krispya

README.md

@@ -423,6 +423,8 @@ const movingOrVisible = world.query(Or(Velocity, Renderable))
 
 The `Added` modifier tracks all entities that have added the specified traits or relations since the last time the query was run. A new instance of the modifier must be created for tracking to be unique.
 
+When multiple traits are passed to `Added` it uses logical `AND`. Only entities where **all** specified traits have been added will be returned.
+
 ```js
 import { createAdded } from 'koota'
 
@@ -434,13 +436,21 @@ const newPositions = world.query(Added(Position))
 // Track entities that added a ChildOf relation
 const newChildren = world.query(Added(ChildOf))
 
+// Track entities where BOTH Position AND Velocity were added
+const fullyAdded = world.query(Added(Position, Velocity))
+
+// Track entities where EITHER Position OR Velocity was added
+const eitherAdded = world.query(Or(Added(Position), Added(Velocity)))
+
 // After running the query, the Added modifier is reset
 ```
 
 #### Removed
 
 The `Removed` modifier tracks all entities that have removed the specified traits or relations since the last time the query was run. This includes entities that have been destroyed. A new instance of the modifier must be created for tracking to be unique.
 
+When multiple traits are passed to `Removed` it uses logical `AND`. Only entities where **all** specified traits have been removed will be returned.
+
 ```js
 import { createRemoved } from 'koota'
 
@@ -452,6 +462,12 @@ const stoppedEntities = world.query(Removed(Velocity))
 // Track entities that removed a ChildOf relation
 const orphaned = world.query(Removed(ChildOf))
 
+// Track entities where BOTH Position AND Velocity were removed
+const fullyRemoved = world.query(Removed(Position, Velocity))
+
+// Track entities where EITHER Position OR Velocity was removed
+const eitherRemoved = world.query(Or(Removed(Position), Removed(Velocity)))
+
 // After running the query, the Removed modifier is reset
 ```
 
@@ -475,6 +491,9 @@ const updatedChildren = world.query(Changed(ChildOf))
 // Track entities where BOTH Position AND Velocity have changed
 const fullyUpdated = world.query(Changed(Position, Velocity))
 
+// Track entities where EITHER Position OR Velocity has changed
+const eitherChanged = world.query(Or(Changed(Position), Changed(Velocity)))
+
 // After running the query, the Changed modifier is reset
 ```
 

packages/core/src/query/modifier.ts

@@ -1,6 +1,6 @@
 import { Brand } from '../common';
 import { Trait } from '../trait/types';
-import { Modifier, QueryParameter } from './types';
+import { EventType, Modifier, OrModifier, QueryParameter } from './types';
 
 export const $modifier = Symbol('modifier');
 
@@ -21,3 +21,23 @@ export function createModifier<TTrait extends Trait[] = Trait[], TType extends s
 export /* @inline @pure */ function isModifier(param: QueryParameter): param is Modifier {
     return (param as Brand<typeof $modifier> | null | undefined)?.[$modifier] as unknown as boolean;
 }
+
+/** Check if a modifier is a tracking modifier (added, removed, or changed) */
+export function isTrackingModifier(modifier: Modifier): boolean {
+    const { type } = modifier;
+    return type.includes('added') || type.includes('removed') || type.includes('changed');
+}
+
+/** Get the tracking type from a modifier */
+export function getTrackingType(modifier: Modifier): EventType | null {
+    const { type } = modifier;
+    if (type.includes('added')) return 'add';
+    if (type.includes('removed')) return 'remove';
+    if (type.includes('changed')) return 'change';
+    return null;
+}
+
+/** Check if an Or modifier has nested modifiers */
+export function isOrWithModifiers(modifier: Modifier): modifier is OrModifier {
+    return modifier.type === 'or' && Array.isArray((modifier as OrModifier).modifiers);
+}

packages/core/src/query/modifiers/or.ts

@@ -1,7 +1,22 @@
 import type { Trait } from '../../trait/types';
-import type { Modifier } from '../types';
-import { createModifier } from '../modifier';
+import type { Modifier, OrModifier, OrParameter } from '../types';
+import { $modifier, createModifier } from '../modifier';
 
-export const Or = <T extends Trait[] = Trait[]>(...traits: T): Modifier<T, 'or'> => {
-    return createModifier('or', 2, traits);
+export const Or = <T extends OrParameter[]>(...params: T): OrModifier<T> => {
+    // Separate traits from nested modifiers
+    const traits: Trait[] = [];
+    const modifiers: Modifier[] = [];
+
+    for (const param of params) {
+        if ((param as Modifier)[$modifier]) {
+            modifiers.push(param as Modifier);
+        } else {
+            traits.push(param as Trait);
+        }
+    }
+
+    const modifier = createModifier('or', 2, traits) as OrModifier<T>;
+    modifier.modifiers = modifiers;
+
+    return modifier;
 };