@vworlds/vecs 1.0.5 → 1.0.7

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/README.md

@@ -12,14 +12,14 @@ yarn add @vworlds/vecs
 
 ## Concepts
 
-| Concept | What it is |
-|---|---|
-| **World** | Central container. Owns all entities, runs all systems and queries. |
-| **Component** | A plain data class. Extend `Component` and attach instances to entities. |
-| **Entity** | An integer id with a set of components. Create via the world. |
-| **Query** | A reactive, always-updated set of entities that match a predicate. |
-| **System** | A `Query` with per-tick runtime logic (phases, `update`, `each`, `run`). |
-| **Filter** | A non-reactive, one-shot scan: walks all world entities on each `forEach` call. |
+| Concept                  | What it is                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| **World**                | Central container. Owns all entities, runs all systems and queries.             |
+| **Component**            | A plain data class. Extend `Component` and attach instances to entities.        |
+| **Entity**               | An integer id with a set of components. Create via the world.                   |
+| **Query**                | A reactive, always-updated set of entities that match a predicate.              |
+| **System**               | A `Query` with per-tick runtime logic (phases, `update`, `each`, `run`).        |
+| **Filter**               | A non-reactive, one-shot scan: walks all world entities on each `forEach` call. |
 | **Exclusive components** | A group of components where at most one may be present on any entity at a time. |
 
 ### Lifecycle in brief
@@ -117,11 +117,9 @@ world.start(); // freeze registration, sort systems into phases
 const bullet = world.createEntity();
 bullet.set(Position, { x: 0, y: 0 });
 
-const vel = bullet.set(Velocity, { vx: 5, vy: 0 });
-vel.modified(); // first update: notify Move system
+const vel = bullet.set(Velocity, { vx: 5, vy: 0 }).get(Velocity)!;
 
-const hp = bullet.set(Health, { hp: 3 });
-hp.modified();
+const hp = bullet.set(Health, { hp: 3 }).get(Health)!;
 
 // ─── Game loop ─────────────────────────────────────────────────────────────
 
@@ -220,10 +218,11 @@ world.start(); // distributes systems to phases, freezes component registration
 A standalone `Query` is a reactive entity set without a phase or per-tick callbacks. Use it when you need the matched set kept up-to-date automatically — for example to enumerate scene nodes or find the nearest enemy.
 
 ```ts
-const enemies = world.query("Enemies")
+const enemies = world
+  .query("Enemies")
   .requires(Enemy, Health)
   .enter((e) => console.log("enemy spawned", e.eid))
-  .exit((e)  => console.log("enemy died",    e.eid));
+  .exit((e) => console.log("enemy died", e.eid));
 
 world.start();
 // enemies.entities is kept up-to-date automatically
@@ -242,20 +241,19 @@ A `Filter` is a non-reactive, one-shot scan. It holds no tracked entity set —
 world.filter([Position]).forEach((e) => console.log(e.eid));
 
 // With component injection:
-world.filter([Position, Velocity])
-  .forEach([Position, Velocity], (e, [pos, vel]) => {
-    pos.x += vel.vx;
-  });
+world.filter([Position, Velocity]).forEach([Position, Velocity], (e, [pos, vel]) => {
+  pos.x += vel.vx;
+});
 
 // Full DSL, with auto-deduced required components:
-world.filter({ AND: [{ HAS: Position }, { HAS: Velocity }] })
+world
+  .filter({ AND: [{ HAS: Position }, { HAS: Velocity }] })
   .forEach([Position, Velocity], (e, [pos, vel]) => {
     pos.x += vel.vx; // pos and vel are non-null — deduced from AND of HAS
   });
 
 // Manual type hint for queries the extractor can't see through:
-world.filter({ OR: [Position, Velocity] }, [Position])
-  .forEach([Position], (e, [pos]) => pos.x);
+world.filter({ OR: [Position, Velocity] }, [Position]).forEach([Position], (e, [pos]) => pos.x);
 ```
 
 Unlike `Query`, a `Filter` requires no name, no `world.start()`, and no `destroy()` — create it anywhere and discard it freely.
@@ -265,16 +263,16 @@ Unlike `Query`, a `Filter` requires no name, no `world.start()`, and no `destroy
 ```ts
 // Declare phases in the order they should run each frame:
 const preUpdate = world.addPhase("preupdate");
-const update    = world.addPhase("update");
-const send      = world.addPhase("send");
+const update = world.addPhase("update");
+const send = world.addPhase("send");
 
 // Each frame, run all phases in registration order:
 world.progress(Date.now(), deltaMs);
 
 // Or drive individual phases manually:
 world.runPhase(preUpdate, Date.now(), deltaMs);
-world.runPhase(update,    Date.now(), deltaMs);
-world.runPhase(send,      Date.now(), deltaMs);
+world.runPhase(update, Date.now(), deltaMs);
+world.runPhase(send, Date.now(), deltaMs);
 ```
 
 Systems with no explicit phase go into a built-in `"update"` phase.
@@ -284,10 +282,11 @@ Systems with no explicit phase go into a built-in `"update"` phase.
 A hook is a shorthand for reacting to a single component's lifecycle without writing a full system:
 
 ```ts
-world.hook(Sprite)
-  .onAdd((sprite)    => sprite.initialize(scene))
+world
+  .hook(Sprite)
+  .onAdd((sprite) => sprite.initialize(scene))
   .onRemove((sprite) => sprite.destroy())
-  .onSet((sprite)    => sprite.syncToScene());
+  .onSet((sprite) => sprite.syncToScene());
 ```
 
 `onSet` fires whenever `component.modified()` is called.  
@@ -308,19 +307,23 @@ class Position extends Component {
 
 world.registerComponent(Position);
 
-const pos = entity.add(Position);
+entity.add(Position);
+const pos = entity.get(Position)!;
 pos.x = 100;
 pos.modified(); // tell the world this component changed
+
+// Alternatively:
+entity.set(Position, { x: 100 });
 ```
 
 Every component instance exposes:
 
-| Property / Method | Description |
-|---|---|
-| `entity` | The `Entity` this component belongs to. |
-| `meta` | `ComponentMeta` — holds the type id, name, and bitset pointer. |
-| `type` | Numeric type id (shorthand for `meta.type`). |
-| `modified()` | Queue an `onSet` / `update` notification. Call after mutating fields. |
+| Property / Method | Description                                                           |
+| ----------------- | --------------------------------------------------------------------- |
+| `entity`          | The `Entity` this component belongs to.                               |
+| `meta`            | `ComponentMeta` — holds the type id, name, and bitset pointer.        |
+| `type`            | Numeric type id (shorthand for `meta.type`).                          |
+| `modified()`      | Queue an `onSet` / `update` notification. Call after mutating fields. |
 
 ---
 
@@ -330,21 +333,34 @@ Every component instance exposes:
 const e = world.createEntity();
 ```
 
-| Property / Method | Description |
-|---|---|
-| `eid` | Unique numeric entity id. |
-| `world` | The `World` that owns this entity. |
-| `add(Class)` | Attach a component; returns the typed instance. Idempotent. |
-| `set(Class, props)` | Like `add`, but also assigns the given partial properties onto the instance. Returns the typed instance. |
-| `get(Class)` | Return the component instance, or `undefined` if not present. |
-| `remove(Class)` | Detach a component (triggers `onRemove` hooks and `exit` callbacks). |
-| `destroy()` | Remove all components and unregister the entity. Recurses to children. |
-| `empty` | `true` when no components are attached. |
-| `forEachComponent(cb)` | Iterate over all attached components. |
-| `parent` | Parent entity in the scene hierarchy, or `undefined`. |
-| `children` | `Set<Entity>` of direct children (lazy, created on first access). |
-| `events` | Typed event emitter. Currently emits `"destroy"` before teardown. |
-| `properties` | `Map<string, any>` free-form bag for module-level bookkeeping. |
+| Property / Method      | Description                                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `eid`                  | Unique numeric entity id.                                                                                     |
+| `world`                | The `World` that owns this entity.                                                                            |
+| `add(Class)`           | Attach a component and return the entity for chaining. Idempotent.                                            |
+| `set(Class, props)`    | Like `add`, but also assigns the given partial properties onto the instance. Returns the entity for chaining. |
+| `modified(component)`  | Queue an `onSet` / `update` notification for the component. Returns the entity for chaining.                  |
+| `get(Class)`           | Return the component instance, or `undefined` if not present.                                                 |
+| `remove(Class)`        | Detach a component (triggers `onRemove` hooks and `exit` callbacks).                                          |
+| `destroy()`            | Remove all components and unregister the entity. Recurses to children.                                        |
+| `empty`                | `true` when no components are attached.                                                                       |
+| `forEachComponent(cb)` | Iterate over all attached components.                                                                         |
+| `parent`               | Parent entity in the scene hierarchy, or `undefined`.                                                         |
+| `children`             | `Set<Entity>` of direct children (lazy, created on first access).                                             |
+| `events`               | Typed event emitter. Currently emits `"destroy"` before teardown.                                             |
+| `properties`           | `Map<string, any>` free-form bag for module-level bookkeeping.                                                |
+
+`entity.modified(c)` is equivalent to `c.modified()` but returns the entity, making it usable in a method chain:
+
+```ts
+// Mutate fields then signal the change inline:
+const vel = entity.get(Velocity)!;
+vel.vx += accel;
+entity.modified(vel); // same effect as vel.modified(), returns entity
+
+// Or in a chain — add without initial notification, then notify later:
+entity.add(Position, false).modified(entity.get(Position)!);
+```
 
 #### Parent–child hierarchy
 
@@ -385,15 +401,15 @@ Declare which entities the system should track:
 
 **Query operators:**
 
-| Operator | Meaning |
-|---|---|
-| `{ HAS: [A, B] }` | Entity has all of A and B |
+| Operator               | Meaning                                  |
+| ---------------------- | ---------------------------------------- |
+| `{ HAS: [A, B] }`      | Entity has all of A and B                |
 | `{ HAS_ONLY: [A, B] }` | Entity has exactly A and B, nothing else |
-| `{ AND: [q1, q2] }` | Both sub-queries must match |
-| `{ OR: [q1, q2] }` | Either sub-query matches |
-| `{ NOT: q }` | Sub-query must not match |
-| `{ PARENT: q }` | Entity's parent matches q |
-| An array `[A, B]` | Shorthand for `HAS: [A, B]` |
+| `{ AND: [q1, q2] }`    | Both sub-queries must match              |
+| `{ OR: [q1, q2] }`     | Either sub-query matches                 |
+| `{ NOT: q }`           | Sub-query must not match                 |
+| `{ PARENT: q }`        | Entity's parent matches q                |
+| An array `[A, B]`      | Shorthand for `HAS: [A, B]`              |
 
 **Type inference:** `requires()` records the listed classes as a type parameter on the system. Callbacks in `.sort()`, `.each()`, and `.update()` inject then treat those components as non-nullable — no `!` needed. For complex `query()` expressions the type system cannot introspect, pass a second argument as an explicit hint:
 
@@ -485,7 +501,8 @@ Enable sorted entity tracking. Matched entities are stored in an ordered set who
 Components declared via `requires()` are non-null in the compare callback.
 
 ```ts
-world.system("Render")
+world
+  .system("Render")
   .requires(Position, Sprite)
   .sort([Position], ([posA], [posB]) => posA.z - posB.z)
   .each([Position, Sprite], (e, [pos, sprite]) => {
@@ -518,31 +535,36 @@ Called every tick when the system's phase runs, regardless of entity state. Use
 A standalone query is created via `world.query(name)` and configured through the same fluent builder API as `System` (`requires`, `query`, `enter`, `exit`, `sort`, `track`, `forEach`, `entities`). It has no phase and no per-tick callbacks.
 
 ```ts
-const projectiles = world.query("Projectiles")
+const projectiles = world
+  .query("Projectiles")
   .requires(Position, Velocity)
   .sort([Position], ([a], [b]) => a.z - b.z)
-  .enter([Position], (e, [pos]) => { pos.x = spawnX; });
+  .enter([Position], (e, [pos]) => {
+    pos.x = spawnX;
+  });
 
 world.start();
 
 // Anywhere in game code:
-projectiles.forEach((e) => { /* ... */ });
+projectiles.forEach((e) => {
+  /* ... */
+});
 console.log(projectiles.entities.size, "active projectiles");
 ```
 
-| Method | Description |
-|---|---|
-| `.requires(...components)` | Set the membership predicate and start tracking. |
-| `.query(expr)` | Set the membership predicate using the {@link SystemQuery} DSL. |
-| `.enter(callback)` / `.enter(inject, callback)` | Fires when an entity joins the query. |
-| `.exit(callback)` / `.exit(inject, callback)` | Fires when an entity leaves the query. |
-| `.sort(components, compare)` | Store matched entities in sorted order. |
-| `.track()` | Enable tracking (implied by `sort`; backfills when called after `start`). |
-| `.belongs(e)` | Returns `true` if the entity satisfies the predicate. |
-| `.forEach(callback)` | Iterate all currently tracked entities (entity only). |
-| `.forEach(components, callback)` | Iterate with component injection — same signature as `Filter.forEach`. |
-| `.entities` | `ReadonlySet<Entity>` of all currently tracked entities. |
-| `.destroy()` | Remove the query from the world and all entities. See below. |
+| Method                                          | Description                                                               |
+| ----------------------------------------------- | ------------------------------------------------------------------------- |
+| `.requires(...components)`                      | Set the membership predicate and start tracking.                          |
+| `.query(expr)`                                  | Set the membership predicate using the {@link SystemQuery} DSL.           |
+| `.enter(callback)` / `.enter(inject, callback)` | Fires when an entity joins the query.                                     |
+| `.exit(callback)` / `.exit(inject, callback)`   | Fires when an entity leaves the query.                                    |
+| `.sort(components, compare)`                    | Store matched entities in sorted order.                                   |
+| `.track()`                                      | Enable tracking (implied by `sort`; backfills when called after `start`). |
+| `.belongs(e)`                                   | Returns `true` if the entity satisfies the predicate.                     |
+| `.forEach(callback)`                            | Iterate all currently tracked entities (entity only).                     |
+| `.forEach(components, callback)`                | Iterate with component injection — same signature as `Filter.forEach`.    |
+| `.entities`                                     | `ReadonlySet<Entity>` of all currently tracked entities.                  |
+| `.destroy()`                                    | Remove the query from the world and all entities. See below.              |
 
 #### `.destroy()`
 
@@ -568,9 +590,9 @@ A `Filter` is created via `world.filter(dsl)` and provides a non-reactive `forEa
 const f = world.filter([Position, Velocity]);
 ```
 
-| Method | Description |
-|---|---|
-| `.forEach(callback)` | Walk all world entities; invoke callback for each matching one. |
+| Method                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `.forEach(callback)`             | Walk all world entities; invoke callback for each matching one.            |
 | `.forEach(components, callback)` | Same, with component injection and non-null types for required components. |
 
 **Type inference** works the same way as for `requires()` on systems/queries: component classes extractable from the DSL (`HAS`, `HAS_ONLY`, plain arrays, and `AND` of those) are non-nullable in the callback tuple. Pass a `_guaranteed` second argument to `world.filter()` as a manual override when inference can't reach:

package/dist/component.d.ts

@@ -65,9 +65,12 @@ export declare class ComponentMeta implements Hook<Component> {
     readonly componentName: string;
     /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
     readonly bitPtr: BitPtr;
-    private onAddHandler;
-    private onRemoveHandler;
-    private onSetHandler;
+    /** @internal */
+    _onAddHandler: ((c: Component) => void) | undefined;
+    /** @internal */
+    _onRemoveHandler: ((c: Component) => void) | undefined;
+    /** @internal */
+    _onSetHandler: ((c: Component) => void) | undefined;
     /**
      * Type ids of components that cannot coexist with this one on the same entity.
      * Set via {@link World.setExclusiveComponents}. `undefined` means no restrictions.
@@ -97,9 +100,7 @@ export type ComponentClassArray = ComponentClassOrType[];
  * }
  *
  * world.registerComponent(Position);
- * const pos = entity.add(Position);
- * pos.x = 100;
- * pos.modified(); // notify watching systems
+ * entity.set(Position, { x: 100 });
  * ```
  *
  * A component instance is always bound to a single entity and is created by
@@ -110,7 +111,8 @@ export declare class Component {
     readonly entity: Entity;
     /** Registration metadata (type id, name, bit-pointer). */
     readonly meta: ComponentMeta;
-    private dirty;
+    /** @internal */
+    _dirty: boolean;
     constructor(
     /** The entity this component belongs to. */
     entity: Entity, 

package/dist/component.js

@@ -23,17 +23,17 @@ export class ComponentMeta {
     }
     /** @inheritdoc */
     onAdd(handler) {
-        this.onAddHandler = handler;
+        this._onAddHandler = handler;
         return this;
     }
     /** @inheritdoc */
     onRemove(handler) {
-        this.onRemoveHandler = handler;
+        this._onRemoveHandler = handler;
         return this;
     }
     /** @inheritdoc */
     onSet(handler) {
-        this.onSetHandler = handler;
+        this._onSetHandler = handler;
         return this;
     }
 }
@@ -49,9 +49,7 @@ export class ComponentMeta {
  * }
  *
  * world.registerComponent(Position);
- * const pos = entity.add(Position);
- * pos.x = 100;
- * pos.modified(); // notify watching systems
+ * entity.set(Position, { x: 100 });
  * ```
  *
  * A component instance is always bound to a single entity and is created by
@@ -65,7 +63,8 @@ export class Component {
     meta) {
         this.entity = entity;
         this.meta = meta;
-        this.dirty = false;
+        /** @internal */
+        this._dirty = false;
     }
     /** Numeric type id — shorthand for `this.meta.type`. */
     get type() {
@@ -83,7 +82,7 @@ export class Component {
      * fields to ensure systems react to the new values.
      */
     modified() {
-        this.entity.world._queueUpdatedComponent(this);
+        this.entity.modified(this);
     }
     /** Returns the component's registered name, e.g. `"Position"`. */
     toString() {

package/dist/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAoDlD;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IAkBxB,YAAY,KAAuB,EAAE,IAAY,EAAE,aAAqB;QANxE;;;WAGG;QACI,cAAS,GAAyB,SAAS,CAAC;QAGjD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+B;QAC7C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,SAAS;IAGpB;IACE,4CAA4C;IAC5B,MAAc;IAC9B,0DAA0D;IAC1C,IAAmB;QAFnB,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAe;QAN7B,UAAK,GAAY,KAAK,CAAC;IAO5B,CAAC;IAEJ,wDAAwD;IACxD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,mEAAmE;IACnE,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,QAAQ;QACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,kEAAkE;IAC3D,QAAQ;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAA4B,EAC5B,KAAY;IAEZ,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAoDlD;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IAqBxB,YAAY,KAAuB,EAAE,IAAY,EAAE,aAAqB;QANxE;;;WAGG;QACI,cAAS,GAAyB,SAAS,CAAC;QAGjD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+B;QAC7C,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,SAAS;IAIpB;IACE,4CAA4C;IAC5B,MAAc;IAC9B,0DAA0D;IAC1C,IAAmB;QAFnB,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAe;QAPrC,gBAAgB;QACT,WAAM,GAAY,KAAK,CAAC;IAO5B,CAAC;IAEJ,wDAAwD;IACxD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,mEAAmE;IACnE,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,QAAQ;QACb,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,kEAAkE;IAC3D,QAAQ;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAA4B,EAAE,KAAY;IAClF,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/dsl.d.ts

@@ -65,7 +65,10 @@ export type ExtractRequired<Q> = Q extends typeof Component ? [Q] : Q extends re
 } ? ExtractRequired<H> : Q extends {
     AND: infer A extends readonly QueryDSL[];
 } ? ExtractAndChain<A> : [];
-type ExtractAndChain<A extends readonly QueryDSL[]> = A extends readonly [infer First, ...infer Rest extends readonly QueryDSL[]] ? [...ExtractRequired<First>, ...ExtractAndChain<Rest>] : [];
+type ExtractAndChain<A extends readonly QueryDSL[]> = A extends readonly [
+    infer First,
+    ...infer Rest extends readonly QueryDSL[]
+] ? [...ExtractRequired<First>, ...ExtractAndChain<Rest>] : [];
 /** Convert a {@link QueryDSL} expression into a runtime entity-test predicate. */
 export declare function buildEntityTest(world: World, q: QueryDSL): EntityTestFunc;
 export {};

package/dist/dsl.js

@@ -21,8 +21,7 @@ function PARENT(func) {
 }
 /** Convert a {@link QueryDSL} expression into a runtime entity-test predicate. */
 export function buildEntityTest(world, q) {
-    if (typeof q === "number" ||
-        (typeof q === "function" && q.prototype instanceof Component)) {
+    if (typeof q === "number" || (typeof q === "function" && q.prototype instanceof Component)) {
         return HAS(world, q);
     }
     else if (typeof q === "function") {

package/dist/dsl.js.map

@@ -1 +1 @@
-{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAGT,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAyCxB,MAAM,UAAU,GAAG,CAAC,KAAY,EAAE,GAAG,UAA+B;IAClE,MAAM,WAAW,GAAG,yBAAyB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAY,EAAE,GAAG,UAA+B;IAChE,MAAM,WAAW,GAAG,yBAAyB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,GAAG,CAAC,IAAoB;IAC/B,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,GAAG,CAAC,GAAG,KAAuB;IACrC,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,EAAE,CAAC,GAAG,KAAuB;IACpC,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,MAAM,CAAC,IAAoB;IAClC,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC;AAC9D,CAAC;AA4CD,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,KAAY,EAAE,CAAW;IACvD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,EAAE;QAC1F,OAAO,GAAG,CAAC,KAAK,EAAE,CAAqB,CAAC,CAAC;KAC1C;SAAM,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE;QAClC,OAAO,CAAmB,CAAC;KAC5B;IAED,IAAI,CAAC,YAAY,KAAK,EAAE;QACtB,OAAO,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;KACzB;IAED,IAAI,KAAK,IAAI,CAAC,EAAE;QACd,OAAO,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;KACtC;IAED,IAAI,UAAU,IAAI,CAAC,EAAE;QACnB,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QACrB,IAAI,CAAC,YAAY,KAAK,EAAE;YACtB,OAAO,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;SAC9B;QACD,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;KAC3B;IAED,IAAI,KAAK,IAAI,CAAC,EAAE;QACd,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;KAC9D;IAED,IAAI,IAAI,IAAI,CAAC,EAAE;QACb,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;KAC5D;IAED,IAAI,KAAK,IAAI,CAAC,EAAE;QACd,OAAO,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;KAC3C;IAED,IAAI,QAAQ,IAAI,CAAC,EAAE;QACjB,OAAO,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;KACjD;IAED,MAAM,yBAAyB,CAAC;AAClC,CAAC"}

package/dist/entity.d.ts

@@ -16,9 +16,7 @@ type EntityEvents = Events<{
  *
  * ```ts
  * const e = world.createEntity();
- * const pos = e.add(Position);
- * pos.x = 100;
- * pos.modified();
+ * e.set(Position, { x: 100 });
  * ```
  *
  * Entities support a parent–child hierarchy. When a parent is destroyed its
@@ -47,7 +45,8 @@ export declare class Entity {
     _events: EntityEvents;
     /** Parent entity in the scene hierarchy, or `undefined` if root. */
     parent: Entity | undefined;
-    private _children;
+    /** @internal */
+    _children: Set<Entity> | undefined;
     _archetypeChanged: boolean;
     private destroyed;
     constructor(
@@ -64,6 +63,17 @@ export declare class Entity {
      */
     get children(): Set<Entity>;
     private getComponentInstance;
+    /**
+     * Queue an `onSet` / `update` notification for the given component and
+     * return the entity for chaining.
+     *
+     * Equivalent to `component.modified()`, but usable inside an entity method
+     * chain (e.g. after `add` or `set`).
+     *
+     * @param c - The component instance whose data changed.
+     * @returns This entity, for chaining.
+     */
+    modified<C extends typeof Component>(c: InstanceType<C>): Entity;
     /**
      * Add a component of type `Class` to this entity and return the instance.
      *
@@ -78,7 +88,29 @@ export declare class Entity {
      * @returns The new (or existing) component instance, typed as
      *   `InstanceType<Class>`.
      */
-    add<C extends typeof Component>(Class: C, markAsModified?: boolean): InstanceType<C>;
+    _add<C extends typeof Component>(Class: C, markAsModified?: boolean): InstanceType<C>;
+    /**
+     * Add a component by its numeric type id.
+     *
+     * @param type - Numeric component type id (as returned by
+     *   {@link World.getComponentType}).
+     * @param markAsModified - Whether to queue an update notification.
+     */
+    _add(type: number, markAsModified?: boolean): Component;
+    /**
+     * Add a component of type `Class` to this entity and return the entity.
+     *
+     * If the component is already present the existing instance is returned and
+     * no callback is fired. Pass `markAsModified = false` to suppress the
+     * initial `onSet` / `update` notification (useful when bulk-loading
+     * network snapshots before systems are running).
+     *
+     * @param Class - The component class to instantiate.
+     * @param markAsModified - Whether to immediately queue an `update`
+     *   notification. Defaults to `true`.
+     * @returns This entity, for chaining.
+     */
+    add<C extends typeof Component>(Class: C, markAsModified?: boolean): Entity;
     /**
      * Add a component by its numeric type id.
      *
@@ -86,23 +118,24 @@ export declare class Entity {
      *   {@link World.getComponentType}).
      * @param markAsModified - Whether to queue an update notification.
      */
-    add(type: number, markAsModified?: boolean): Component;
+    add(type: number, markAsModified?: boolean): Entity;
     /**
-     * Add a component of type `Class` (if not already present) and assign the
-     * provided properties onto the instance, then return it.
+     * Add a component of type `Class` (if not already present), assign the
+     * provided properties onto the instance, and return the entity for chaining.
      *
      * @param Class - The component class to instantiate.
-     * @param props - Optional properties to assign onto the component instance.
-     * @returns The new (or existing) component instance with the given properties applied.
+     * @param props - Properties to assign onto the component instance.
+     * @returns This entity, for chaining.
      */
-    set<C extends typeof Component>(Class: C, props: Partial<InstanceType<C>>): InstanceType<C>;
+    set<C extends typeof Component>(Class: C, props: Partial<InstanceType<C>>): Entity;
     /**
-     * Add a component by its numeric type id and assign the provided properties.
+     * Add a component by its numeric type id, assign the provided properties,
+     * and return the entity for chaining.
      *
      * @param type - Numeric component type id.
-     * @param props - Optional properties to assign onto the component instance.
+     * @param props - Properties to assign onto the component instance.
      */
-    set(type: number, props: Partial<Component>): Component;
+    set(type: number, props: Partial<Component>): Entity;
     /**
      * Remove the component of the given class from this entity.
      *
@@ -152,7 +185,8 @@ export declare class Entity {
     _updateQueries(): void;
     /** `true` when the entity has no components attached. */
     get empty(): boolean;
-    private _destroy;
+    /** @internal */
+    _destroy(): void;
     /**
      * Destroy this entity and recursively destroy all of its children.
      *