koota 0.1.8 → 0.1.10

package/README.md

@@ -20,7 +20,7 @@ const Velocity = trait({ x: 0, y: 0 });
 
 // Trait with a callback for initial value
 // ⚠️ Must be an object
-const Mesh = trait(() => THREE.Mesh());
+const Mesh = trait(() => new THREE.Mesh());
 
 // Tag trait (no data)
 const IsActive = trait();
@@ -309,6 +309,20 @@ entity.set(Position, { x: 10, y: 20 });
 entity.remove(Position);
 ```
 
+### Change detection with `udpateEach`
+
+By default, `updateEach` will automatically turn on change detection for traits that are being tracked via `onChange` or the `Changed` modifier. If you want to silence change detection for a loop or force it to always run, you can do so with an options config.
+
+```js
+// Setting changeDetection to 'never' will silence it, triggering no change events
+world.query(Position, Velocity).updateEach(([position, velocity]) => {
+}, { changeDetection: 'never' });
+
+// Setting changeDetection to 'always' will ignore selective tracking and always emit change events for all traits that are mutated
+world.query(Position, Velocity).updateEach(([position, velocity]) => {
+}, { changeDetection: 'never' });
+```
+
 ### World traits
 
 For global data like time, these can be traits added to the world. **World traits do not appear in queries.**
@@ -338,7 +352,7 @@ world.query(Position, Velocity, Mass)
 
 ### Modifying trait stores direclty
 
-For performance-critical operations, you can modify trait stores directly using the useStore hook. This approach bypasses some of the safety checks and event triggers, so use it with caution. All stores are structure of arrays for performance purposes.
+For performance-critical operations, you can modify trait stores directly using the `useStore` hook. This approach bypasses some of the safety checks and event triggers, so use it with caution. All stores are structure of arrays for performance purposes.
 
 ```js
 // Returns the SoA stores
@@ -400,6 +414,11 @@ const time = world.get(Time)
 
 // Sets the trait and triggers a change event
 world.set(Time, { current: performance.now() })
+// Can take a callback with the previous state passed in
+world.set(Time, (prev) => ({
+  current: performance.now(),
+  delta: performance.now() - prev.current
+}))
 
 // Subscribe to add, remove or change events for a set of query parameters
 // Anything you can put in a query is legal
@@ -445,6 +464,11 @@ const position = entity.get(Position)
 
 // Sets the trait and triggers a change event
 entity.set(Position, { x: 10, y: 10 })
+// Can take a callback with the previous state passed in
+entity.set(Position, (prev) => ({
+  x: prev + 1,
+  y: prev + 1
+}))
 
 // Get the targets for a relationship
 // Return Entity[]
@@ -464,14 +488,37 @@ entity.destroy()
 
 ### Trait
 
-A trait defines a kind of data. If you are familiar with ECS, it is our version of a component. We call it a trait instead to not get confused with React or web components. From a high level, you just create traits either with a schema or with a callback returning an object.
+A trait is a specific block of data. They are added to entities to build up its overall data signature. If you are familiar with ECS, it is our version of a component. It is called a trait instead to not get confused with React or web components. 
+
+A trait can be created with a schema that describes the kind of data it will hold. 
 
 ```js
-// A schema
 const Position = trait({ x: 0, y: 0, z: 0 })
+```
+
+In cases where the data needs to be initialized for each instance of the trait created, a callback can be passed in to be used a as a lazy initializer.
+
+```js
+// ❌ The items array will be shared between every instance of this trait
+const Inventory = trait({ 
+  items: [], 
+  max: 10, 
+})
+
+// ✅ With a lazy initializer, each instance will now get its own array
+const Inventory = trait({ 
+  items: () => [], 
+  max: 10, 
+})
+```
+
+Sometimes a trait only has one field that points to an object instance. In cases like this, it is useful to skip the schema and use a callback directly in the trait.
+
+```js
+const Velocity = trait(() => new THREE.Vector3())
 
-// A callback
-const Velocity = trait(() => THREE.Vector3())
+// The returned state is simply the instance
+const velocity = entity.get(Velocity)
 ```
 
 Both schema-based and callback-based traits are used similarly, but they have different performance implications due to how their data is stored internally:
@@ -512,7 +559,7 @@ const store = [
 ];
 
 // Similarly, this will create a new instance of Mesh in each index
-const Mesh = trait(() => THREE.Mesh())
+const Mesh = trait(() => new THREE.Mesh())
 ```
 
 #### Typing traits
@@ -521,17 +568,17 @@ Traits can have a schema type passed into its generic. This can be useful if the
 
 ```js
 type AttackerSchema = {
-	continueCombo: boolean | null,
-	currentStageIndex: number | null,
-	stages: Array<AttackStage> | null,
-	startedAt: number | null,
+  continueCombo: boolean | null,
+  currentStageIndex: number | null,
+  stages: Array<AttackStage> | null,
+  startedAt: number | null,
 }
 
 const Attacker = trait<AttackerSchema>({
-	continueCombo: null,
-	currentStageIndex: null,
-	stages: null,
-	startedAt: null,
+  continueCombo: null,
+  currentStageIndex: null,
+  stages: null,
+  startedAt: null,
 })
 ```
 
@@ -540,18 +587,18 @@ Interfaces can be used with `Pick` to convert the key signatures into something
 
 ```js
 interface AttackerSchema {
-	continueCombo: boolean | null,
-	currentStageIndex: number | null,
-	stages: Array<AttackStage> | null,
-	startedAt: number | null,
+  continueCombo: boolean | null,
+  currentStageIndex: number | null,
+  stages: Array<AttackStage> | null,
+  startedAt: number | null,
 }
 
 // Pick is required to not get type errors
 const Attacker = trait<Pick<AttackerSchema, keyof AttackerSchema>>({
-	continueCombo: null,
-	currentStageIndex: null,
-	stages: null,
-	startedAt: null,
+  continueCombo: null,
+  currentStageIndex: null,
+  stages: null,
+  startedAt: null,
 })
 ```
 

package/dist/{chunk-XQK5JJDD.js → chunk-L2TCLFSQ.js}

@@ -553,11 +553,17 @@ Number.prototype.changed = function(trait2) {
   return setChanged(world, this, trait2);
 };
 Number.prototype.get = function(trait2) {
-  const ctx = trait2[$internal];
-  const index = this & ENTITY_ID_MASK;
   const worldId = this >>> WORLD_ID_SHIFT;
-  const store = ctx.stores[worldId];
-  return ctx.get(index, store);
+  const world = universe.worlds[worldId];
+  const worldCtx = world[$internal];
+  const data = worldCtx.traitData.get(trait2);
+  if (!data) return void 0;
+  const mask = worldCtx.entityMasks[data.generationId][this];
+  if ((mask & data.bitflag) !== data.bitflag) return void 0;
+  const traitCtx = trait2[$internal];
+  const index = this & ENTITY_ID_MASK;
+  const store = traitCtx.stores[worldId];
+  return traitCtx.get(index, store);
 };
 Number.prototype.set = function(trait2, value, triggerChanged = true) {
   const ctx = trait2[$internal];
@@ -794,6 +800,7 @@ var Query = class {
     __publicField(this, "entities", new SparseSet());
     __publicField(this, "isTracking", false);
     __publicField(this, "hasChangedModifiers", false);
+    __publicField(this, "changedTraits", /* @__PURE__ */ new Set());
     __publicField(this, "toRemove", new SparseSet());
     __publicField(this, "addSubscriptions", /* @__PURE__ */ new Set());
     __publicField(this, "removeSubscriptions", /* @__PURE__ */ new Set());
@@ -847,6 +854,7 @@ var Query = class {
         }
         if (parameter.type.includes("changed")) {
           for (const trait2 of traits) {
+            this.changedTraits.add(trait2);
             const data = ctx.traitData.get(trait2);
             this.traitData.changed.push(data);
             this.traits.push(trait2);
@@ -1084,27 +1092,60 @@ function createQueryResult(query, world, params) {
   const traits = [];
   getQueryStores(params, traits, stores, world);
   const results = Object.assign(entities, {
-    updateEach(callback, options) {
-      const changeDetection = options?.changeDetection ?? false;
+    updateEach(callback, options = { changeDetection: "auto" }) {
       const state = new Array(traits.length);
-      if (!changeDetection) {
+      if (options.changeDetection === "auto") {
+        const changedPairs = [];
+        const atomicSnapshots = [];
+        const trackedTraits = [];
+        const untrackedTraits = [];
+        for (const trait2 of traits) {
+          if (world[$internal].trackedTraits.has(trait2)) {
+            trackedTraits.push(trait2);
+          } else if (query.hasChangedModifiers && query.changedTraits.has(trait2)) {
+            trackedTraits.push(trait2);
+          } else {
+            untrackedTraits.push(trait2);
+          }
+        }
         for (let i = 0; i < entities.length; i++) {
           const entity = entities[i];
           const eid = getEntityId(entity);
           for (let j = 0; j < traits.length; j++) {
             const trait2 = traits[j];
             const ctx = trait2[$internal];
-            state[j] = ctx.get(eid, stores[j]);
+            const value = ctx.get(eid, stores[j]);
+            state[j] = value;
+            atomicSnapshots[j] = ctx.type === "aos" ? { ...value } : null;
           }
           callback(state, entity, i);
           if (!world.has(entity)) continue;
-          for (let j = 0; j < traits.length; j++) {
-            const trait2 = traits[j];
+          for (let j = 0; j < trackedTraits.length; j++) {
+            const trait2 = trackedTraits[j];
+            const ctx = trait2[$internal];
+            const newValue = state[j];
+            let changed = false;
+            if (ctx.type === "aos") {
+              changed = ctx.fastSetWithChangeDetection(eid, stores[j], newValue);
+              if (!changed) {
+                changed = !shallowEqual(newValue, atomicSnapshots[j]);
+              }
+            } else {
+              changed = ctx.fastSetWithChangeDetection(eid, stores[j], newValue);
+            }
+            if (changed) changedPairs.push([entity, trait2]);
+          }
+          for (let j = 0; j < untrackedTraits.length; j++) {
+            const trait2 = untrackedTraits[j];
             const ctx = trait2[$internal];
             ctx.fastSet(eid, stores[j], state[j]);
           }
         }
-      } else {
+        for (let i = 0; i < changedPairs.length; i++) {
+          const [entity, trait2] = changedPairs[i];
+          entity.changed(trait2);
+        }
+      } else if (options.changeDetection === "always") {
         const changedPairs = [];
         const atomicSnapshots = [];
         for (let i = 0; i < entities.length; i++) {
@@ -1139,6 +1180,23 @@ function createQueryResult(query, world, params) {
           const [entity, trait2] = changedPairs[i];
           entity.changed(trait2);
         }
+      } else if (options.changeDetection === "never") {
+        for (let i = 0; i < entities.length; i++) {
+          const entity = entities[i];
+          const eid = getEntityId(entity);
+          for (let j = 0; j < traits.length; j++) {
+            const trait2 = traits[j];
+            const ctx = trait2[$internal];
+            state[j] = ctx.get(eid, stores[j]);
+          }
+          callback(state, entity, i);
+          if (!world.has(entity)) continue;
+          for (let j = 0; j < traits.length; j++) {
+            const trait2 = traits[j];
+            const ctx = trait2[$internal];
+            ctx.fastSet(eid, stores[j], state[j]);
+          }
+        }
       }
       return results;
     },
@@ -1194,7 +1252,8 @@ var World = class {
       dirtyMasks: /* @__PURE__ */ new Map(),
       trackingSnapshots: /* @__PURE__ */ new Map(),
       changedMasks: /* @__PURE__ */ new Map(),
-      worldEntity: null
+      worldEntity: null,
+      trackedTraits: /* @__PURE__ */ new Set()
     });
     __privateAdd(this, _isInitialized, false);
     __publicField(this, "traits", /* @__PURE__ */ new Set());
@@ -1268,6 +1327,7 @@ var World = class {
     ctx.trackingSnapshots.clear();
     ctx.dirtyMasks.clear();
     ctx.changedMasks.clear();
+    ctx.trackedTraits.clear();
     ctx.worldEntity = createEntity(this, IsExcluded);
   }
   query(...args) {
@@ -1317,7 +1377,11 @@ var World = class {
     if (!ctx.traitData.has(trait2)) registerTrait(this, trait2);
     const data = ctx.traitData.get(trait2);
     data.changedSubscriptions.add(callback);
-    return () => data.changedSubscriptions.delete(callback);
+    ctx.trackedTraits.add(trait2);
+    return () => {
+      data.changedSubscriptions.delete(callback);
+      ctx.trackedTraits.delete(trait2);
+    };
   }
 };
 _id = new WeakMap();

package/dist/index.cjs

@@ -590,11 +590,17 @@ Number.prototype.changed = function(trait2) {
   return setChanged(world, this, trait2);
 };
 Number.prototype.get = function(trait2) {
-  const ctx = trait2[$internal];
-  const index = this & ENTITY_ID_MASK;
   const worldId = this >>> WORLD_ID_SHIFT;
-  const store = ctx.stores[worldId];
-  return ctx.get(index, store);
+  const world = universe.worlds[worldId];
+  const worldCtx = world[$internal];
+  const data = worldCtx.traitData.get(trait2);
+  if (!data) return void 0;
+  const mask = worldCtx.entityMasks[data.generationId][this];
+  if ((mask & data.bitflag) !== data.bitflag) return void 0;
+  const traitCtx = trait2[$internal];
+  const index = this & ENTITY_ID_MASK;
+  const store = traitCtx.stores[worldId];
+  return traitCtx.get(index, store);
 };
 Number.prototype.set = function(trait2, value, triggerChanged = true) {
   const ctx = trait2[$internal];
@@ -772,6 +778,7 @@ var Query = class {
     __publicField(this, "entities", new SparseSet());
     __publicField(this, "isTracking", false);
     __publicField(this, "hasChangedModifiers", false);
+    __publicField(this, "changedTraits", /* @__PURE__ */ new Set());
     __publicField(this, "toRemove", new SparseSet());
     __publicField(this, "addSubscriptions", /* @__PURE__ */ new Set());
     __publicField(this, "removeSubscriptions", /* @__PURE__ */ new Set());
@@ -825,6 +832,7 @@ var Query = class {
         }
         if (parameter.type.includes("changed")) {
           for (const trait2 of traits) {
+            this.changedTraits.add(trait2);
             const data = ctx.traitData.get(trait2);
             this.traitData.changed.push(data);
             this.traits.push(trait2);
@@ -1062,27 +1070,60 @@ function createQueryResult(query, world, params) {
   const traits = [];
   getQueryStores(params, traits, stores, world);
   const results = Object.assign(entities, {
-    updateEach(callback, options) {
-      const changeDetection = options?.changeDetection ?? false;
+    updateEach(callback, options = { changeDetection: "auto" }) {
       const state = new Array(traits.length);
-      if (!changeDetection) {
+      if (options.changeDetection === "auto") {
+        const changedPairs = [];
+        const atomicSnapshots = [];
+        const trackedTraits = [];
+        const untrackedTraits = [];
+        for (const trait2 of traits) {
+          if (world[$internal].trackedTraits.has(trait2)) {
+            trackedTraits.push(trait2);
+          } else if (query.hasChangedModifiers && query.changedTraits.has(trait2)) {
+            trackedTraits.push(trait2);
+          } else {
+            untrackedTraits.push(trait2);
+          }
+        }
         for (let i = 0; i < entities.length; i++) {
           const entity = entities[i];
           const eid = getEntityId(entity);
           for (let j = 0; j < traits.length; j++) {
             const trait2 = traits[j];
             const ctx = trait2[$internal];
-            state[j] = ctx.get(eid, stores[j]);
+            const value = ctx.get(eid, stores[j]);
+            state[j] = value;
+            atomicSnapshots[j] = ctx.type === "aos" ? { ...value } : null;
           }
           callback(state, entity, i);
           if (!world.has(entity)) continue;
-          for (let j = 0; j < traits.length; j++) {
-            const trait2 = traits[j];
+          for (let j = 0; j < trackedTraits.length; j++) {
+            const trait2 = trackedTraits[j];
+            const ctx = trait2[$internal];
+            const newValue = state[j];
+            let changed = false;
+            if (ctx.type === "aos") {
+              changed = ctx.fastSetWithChangeDetection(eid, stores[j], newValue);
+              if (!changed) {
+                changed = !shallowEqual(newValue, atomicSnapshots[j]);
+              }
+            } else {
+              changed = ctx.fastSetWithChangeDetection(eid, stores[j], newValue);
+            }
+            if (changed) changedPairs.push([entity, trait2]);
+          }
+          for (let j = 0; j < untrackedTraits.length; j++) {
+            const trait2 = untrackedTraits[j];
             const ctx = trait2[$internal];
             ctx.fastSet(eid, stores[j], state[j]);
           }
         }
-      } else {
+        for (let i = 0; i < changedPairs.length; i++) {
+          const [entity, trait2] = changedPairs[i];
+          entity.changed(trait2);
+        }
+      } else if (options.changeDetection === "always") {
         const changedPairs = [];
         const atomicSnapshots = [];
         for (let i = 0; i < entities.length; i++) {
@@ -1117,6 +1158,23 @@ function createQueryResult(query, world, params) {
           const [entity, trait2] = changedPairs[i];
           entity.changed(trait2);
         }
+      } else if (options.changeDetection === "never") {
+        for (let i = 0; i < entities.length; i++) {
+          const entity = entities[i];
+          const eid = getEntityId(entity);
+          for (let j = 0; j < traits.length; j++) {
+            const trait2 = traits[j];
+            const ctx = trait2[$internal];
+            state[j] = ctx.get(eid, stores[j]);
+          }
+          callback(state, entity, i);
+          if (!world.has(entity)) continue;
+          for (let j = 0; j < traits.length; j++) {
+            const trait2 = traits[j];
+            const ctx = trait2[$internal];
+            ctx.fastSet(eid, stores[j], state[j]);
+          }
+        }
       }
       return results;
     },
@@ -1172,7 +1230,8 @@ var World = class {
       dirtyMasks: /* @__PURE__ */ new Map(),
       trackingSnapshots: /* @__PURE__ */ new Map(),
       changedMasks: /* @__PURE__ */ new Map(),
-      worldEntity: null
+      worldEntity: null,
+      trackedTraits: /* @__PURE__ */ new Set()
     });
     __privateAdd(this, _isInitialized, false);
     __publicField(this, "traits", /* @__PURE__ */ new Set());
@@ -1246,6 +1305,7 @@ var World = class {
     ctx.trackingSnapshots.clear();
     ctx.dirtyMasks.clear();
     ctx.changedMasks.clear();
+    ctx.trackedTraits.clear();
     ctx.worldEntity = createEntity(this, IsExcluded);
   }
   query(...args) {
@@ -1295,7 +1355,11 @@ var World = class {
     if (!ctx.traitData.has(trait2)) registerTrait(this, trait2);
     const data = ctx.traitData.get(trait2);
     data.changedSubscriptions.add(callback);
-    return () => data.changedSubscriptions.delete(callback);
+    ctx.trackedTraits.add(trait2);
+    return () => {
+      data.changedSubscriptions.delete(callback);
+      ctx.trackedTraits.delete(trait2);
+    };
   }
 };
 _id = new WeakMap();

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as Schema, T as Trait, N as Norm, M as ModifierData, W as World, Q as QueryParameter, R as Relation, a as RelationTarget, b as WildcardRelation } from './world-liWg9VB-.cjs';
-export { $ as $internal, A as AoSFactory, C as ConfigurableTrait, l as Entity, j as ExtractIsTag, E as ExtractSchema, i as ExtractStore, k as ExtractStores, r as InstancesFromParameters, s as IsNotModifier, I as IsTag, m as QueryModifier, p as QueryResult, o as QueryResultOptions, n as QuerySubscriber, h as Store, q as StoresFromParameters, g as TraitInstance, f as TraitTuple, d as TraitType, e as TraitValue, c as createWorld } from './world-liWg9VB-.cjs';
+import { S as Schema, T as Trait, N as Norm, M as ModifierData, W as World, Q as QueryParameter, R as Relation, a as RelationTarget, b as WildcardRelation } from './world-CIrtrsKj.cjs';
+export { $ as $internal, A as AoSFactory, C as ConfigurableTrait, l as Entity, j as ExtractIsTag, E as ExtractSchema, i as ExtractStore, k as ExtractStores, r as InstancesFromParameters, s as IsNotModifier, I as IsTag, m as QueryModifier, p as QueryResult, o as QueryResultOptions, n as QuerySubscriber, h as Store, q as StoresFromParameters, g as TraitInstance, f as TraitTuple, d as TraitType, e as TraitValue, c as createWorld } from './world-CIrtrsKj.cjs';
 
 declare function defineTrait<S extends Schema = {}>(schema?: S): Trait<Norm<S>>;
 declare const trait: typeof defineTrait;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Schema, T as Trait, N as Norm, M as ModifierData, W as World, Q as QueryParameter, R as Relation, a as RelationTarget, b as WildcardRelation } from './world-liWg9VB-.js';
-export { $ as $internal, A as AoSFactory, C as ConfigurableTrait, l as Entity, j as ExtractIsTag, E as ExtractSchema, i as ExtractStore, k as ExtractStores, r as InstancesFromParameters, s as IsNotModifier, I as IsTag, m as QueryModifier, p as QueryResult, o as QueryResultOptions, n as QuerySubscriber, h as Store, q as StoresFromParameters, g as TraitInstance, f as TraitTuple, d as TraitType, e as TraitValue, c as createWorld } from './world-liWg9VB-.js';
+import { S as Schema, T as Trait, N as Norm, M as ModifierData, W as World, Q as QueryParameter, R as Relation, a as RelationTarget, b as WildcardRelation } from './world-CIrtrsKj.js';
+export { $ as $internal, A as AoSFactory, C as ConfigurableTrait, l as Entity, j as ExtractIsTag, E as ExtractSchema, i as ExtractStore, k as ExtractStores, r as InstancesFromParameters, s as IsNotModifier, I as IsTag, m as QueryModifier, p as QueryResult, o as QueryResultOptions, n as QuerySubscriber, h as Store, q as StoresFromParameters, g as TraitInstance, f as TraitTuple, d as TraitType, e as TraitValue, c as createWorld } from './world-CIrtrsKj.js';
 
 declare function defineTrait<S extends Schema = {}>(schema?: S): Trait<Norm<S>>;
 declare const trait: typeof defineTrait;

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   relation,
   trait,
   universe
-} from "./chunk-XQK5JJDD.js";
+} from "./chunk-L2TCLFSQ.js";
 export {
   $internal,
   Not,

package/dist/react.cjs

@@ -582,11 +582,17 @@ Number.prototype.changed = function(trait2) {
   return setChanged(world, this, trait2);
 };
 Number.prototype.get = function(trait2) {
-  const ctx = trait2[$internal];
-  const index = this & ENTITY_ID_MASK;
   const worldId = this >>> WORLD_ID_SHIFT;
-  const store = ctx.stores[worldId];
-  return ctx.get(index, store);
+  const world = universe.worlds[worldId];
+  const worldCtx = world[$internal];
+  const data = worldCtx.traitData.get(trait2);
+  if (!data) return void 0;
+  const mask = worldCtx.entityMasks[data.generationId][this];
+  if ((mask & data.bitflag) !== data.bitflag) return void 0;
+  const traitCtx = trait2[$internal];
+  const index = this & ENTITY_ID_MASK;
+  const store = traitCtx.stores[worldId];
+  return traitCtx.get(index, store);
 };
 Number.prototype.set = function(trait2, value, triggerChanged = true) {
   const ctx = trait2[$internal];
@@ -764,6 +770,7 @@ var Query = class {
     __publicField(this, "entities", new SparseSet());
     __publicField(this, "isTracking", false);
     __publicField(this, "hasChangedModifiers", false);
+    __publicField(this, "changedTraits", /* @__PURE__ */ new Set());
     __publicField(this, "toRemove", new SparseSet());
     __publicField(this, "addSubscriptions", /* @__PURE__ */ new Set());
     __publicField(this, "removeSubscriptions", /* @__PURE__ */ new Set());
@@ -817,6 +824,7 @@ var Query = class {
         }
         if (parameter.type.includes("changed")) {
           for (const trait2 of traits) {
+            this.changedTraits.add(trait2);
             const data = ctx.traitData.get(trait2);
             this.traitData.changed.push(data);
             this.traits.push(trait2);
@@ -1054,27 +1062,60 @@ function createQueryResult(query, world, params) {
   const traits = [];
   getQueryStores(params, traits, stores, world);
   const results = Object.assign(entities, {
-    updateEach(callback, options) {
-      const changeDetection = options?.changeDetection ?? false;
+    updateEach(callback, options = { changeDetection: "auto" }) {
       const state = new Array(traits.length);
-      if (!changeDetection) {
+      if (options.changeDetection === "auto") {
+        const changedPairs = [];
+        const atomicSnapshots = [];
+        const trackedTraits = [];
+        const untrackedTraits = [];
+        for (const trait2 of traits) {
+          if (world[$internal].trackedTraits.has(trait2)) {
+            trackedTraits.push(trait2);
+          } else if (query.hasChangedModifiers && query.changedTraits.has(trait2)) {
+            trackedTraits.push(trait2);
+          } else {
+            untrackedTraits.push(trait2);
+          }
+        }
         for (let i = 0; i < entities.length; i++) {
           const entity = entities[i];
           const eid = getEntityId(entity);
           for (let j = 0; j < traits.length; j++) {
             const trait2 = traits[j];
             const ctx = trait2[$internal];
-            state[j] = ctx.get(eid, stores[j]);
+            const value = ctx.get(eid, stores[j]);
+            state[j] = value;
+            atomicSnapshots[j] = ctx.type === "aos" ? { ...value } : null;
           }
           callback(state, entity, i);
           if (!world.has(entity)) continue;
-          for (let j = 0; j < traits.length; j++) {
-            const trait2 = traits[j];
+          for (let j = 0; j < trackedTraits.length; j++) {
+            const trait2 = trackedTraits[j];
+            const ctx = trait2[$internal];
+            const newValue = state[j];
+            let changed = false;
+            if (ctx.type === "aos") {
+              changed = ctx.fastSetWithChangeDetection(eid, stores[j], newValue);
+              if (!changed) {
+                changed = !shallowEqual(newValue, atomicSnapshots[j]);
+              }
+            } else {
+              changed = ctx.fastSetWithChangeDetection(eid, stores[j], newValue);
+            }
+            if (changed) changedPairs.push([entity, trait2]);
+          }
+          for (let j = 0; j < untrackedTraits.length; j++) {
+            const trait2 = untrackedTraits[j];
             const ctx = trait2[$internal];
             ctx.fastSet(eid, stores[j], state[j]);
           }
         }
-      } else {
+        for (let i = 0; i < changedPairs.length; i++) {
+          const [entity, trait2] = changedPairs[i];
+          entity.changed(trait2);
+        }
+      } else if (options.changeDetection === "always") {
         const changedPairs = [];
         const atomicSnapshots = [];
         for (let i = 0; i < entities.length; i++) {
@@ -1109,6 +1150,23 @@ function createQueryResult(query, world, params) {
           const [entity, trait2] = changedPairs[i];
           entity.changed(trait2);
         }
+      } else if (options.changeDetection === "never") {
+        for (let i = 0; i < entities.length; i++) {
+          const entity = entities[i];
+          const eid = getEntityId(entity);
+          for (let j = 0; j < traits.length; j++) {
+            const trait2 = traits[j];
+            const ctx = trait2[$internal];
+            state[j] = ctx.get(eid, stores[j]);
+          }
+          callback(state, entity, i);
+          if (!world.has(entity)) continue;
+          for (let j = 0; j < traits.length; j++) {
+            const trait2 = traits[j];
+            const ctx = trait2[$internal];
+            ctx.fastSet(eid, stores[j], state[j]);
+          }
+        }
       }
       return results;
     },
@@ -1164,7 +1222,8 @@ var World = class {
       dirtyMasks: /* @__PURE__ */ new Map(),
       trackingSnapshots: /* @__PURE__ */ new Map(),
       changedMasks: /* @__PURE__ */ new Map(),
-      worldEntity: null
+      worldEntity: null,
+      trackedTraits: /* @__PURE__ */ new Set()
     });
     __privateAdd(this, _isInitialized, false);
     __publicField(this, "traits", /* @__PURE__ */ new Set());
@@ -1238,6 +1297,7 @@ var World = class {
     ctx.trackingSnapshots.clear();
     ctx.dirtyMasks.clear();
     ctx.changedMasks.clear();
+    ctx.trackedTraits.clear();
     ctx.worldEntity = createEntity(this, IsExcluded);
   }
   query(...args) {
@@ -1287,7 +1347,11 @@ var World = class {
     if (!ctx.traitData.has(trait2)) registerTrait(this, trait2);
     const data = ctx.traitData.get(trait2);
     data.changedSubscriptions.add(callback);
-    return () => data.changedSubscriptions.delete(callback);
+    ctx.trackedTraits.add(trait2);
+    return () => {
+      data.changedSubscriptions.delete(callback);
+      ctx.trackedTraits.delete(trait2);
+    };
   }
 };
 _id = new WeakMap();

package/dist/react.d.cts

@@ -1,4 +1,4 @@
-import { Q as QueryParameter, p as QueryResult, W as World, T as Trait, l as Entity, g as TraitInstance } from './world-liWg9VB-.cjs';
+import { Q as QueryParameter, p as QueryResult, W as World, T as Trait, l as Entity, g as TraitInstance } from './world-CIrtrsKj.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare function useQuery<T extends QueryParameter[]>(...parameters: T): QueryResult<T>;