@vworlds/vecs 1.0.10 → 1.0.12

package/README.md

@@ -2,7 +2,7 @@
 
 A TypeScript Entity Component System (ECS) for real-time games and simulations.
 
-`vecs` lets you model game state as **entities** (integer IDs) with **components** (typed data bags) attached to them. **Systems** declare which component combinations they care about and receive automatic callbacks when entities enter or leave their query, when component data changes, and on every tick. A **World** ties it all together and drives the update loop.
+`vecs` lets you model game state as **entities** (numeric ids) with **components** (typed data bags) attached to them. **Systems** declare which component combinations they care about and receive automatic callbacks when entities enter or leave their query, when component data changes, and on every tick. A **World** ties it all together and drives the update loop.
 
 ## Install
 
@@ -14,18 +14,20 @@ yarn add @vworlds/vecs
 
 | Concept                  | What it is                                                                      |
 | ------------------------ | ------------------------------------------------------------------------------- |
-| **World**                | Central container. Owns all entities, runs all systems and queries.             |
+| **World**                | Central container. Owns every entity, query, system, and pipeline phase.        |
 | **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`).        |
+| **Entity**               | A numeric id with a set of components. Created via the world.                   |
+| **Query**                | A reactive, always-up-to-date set of entities matching a predicate.             |
+| **System**               | A `Query` with phase placement and per-tick logic (`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. |
+| **Hook**                 | Lightweight `onAdd` / `onRemove` / `onSet` callbacks per component class.       |
+| **Phase**                | Named ordered bucket of systems within the update pipeline.                     |
+| **Exclusive components** | A group of components where at most one may exist on any entity at a time.      |
 
 ### Lifecycle in brief
 
 ```
-registerComponent() × N  →  system() / query() × N  →  start()  →  progress() every frame
+registerComponent() × N  →  addPhase() / system() / query() × N  →  start()  →  progress() every frame
 ```
 
 After `start()`, component registration is disabled. Systems and queries can still be created — standalone queries backfill existing matched entities immediately.
@@ -34,8 +36,6 @@ After `start()`, component registration is disabled. Systems and queries can sti
 
 ## Example
 
-The example below defines three components, two systems, a phase, and a hook, then runs a simple "move and despawn" loop.
-
 ```ts
 import { World, Component, IPhase } from "@vworlds/vecs";
 
@@ -70,22 +70,15 @@ const cleanup: IPhase = world.addPhase("cleanup");
 
 // ─── Systems ───────────────────────────────────────────────────────────────
 
-// MoveSystem: runs every tick for entities that have both Position and Velocity.
+// MoveSystem: integrates Velocity into Position every tick.
 world
   .system("Move")
   .phase(update)
   .requires(Position, Velocity)
-  .enter([Position, Velocity], (e, [pos, vel]) => {
-    console.log(`entity ${e.eid} entered Move with pos=(${pos.x},${pos.y})`);
-  })
-  .update(Velocity, [Position], (vel, [pos]) => {
-    // Called whenever vel.modified() is queued.
+  .each([Position, Velocity], (e, [pos, vel]) => {
     pos.x += vel.vx;
     pos.y += vel.vy;
-    pos.modified(); // propagate position change to other systems
-  })
-  .exit((e) => {
-    console.log(`entity ${e.eid} left Move`);
+    pos.modified(); // signal that Position changed so other systems react
   });
 
 // HealthSystem: despawns entities whose HP drops to zero.
@@ -101,8 +94,6 @@ world
 
 // ─── Hooks ─────────────────────────────────────────────────────────────────
 
-// Hooks are a lightweight alternative to systems for side effects on a single
-// component type — no per-entity query, just callbacks on add/remove/set.
 world
   .hook(Health)
   .onAdd((h) => console.log(`entity ${h.entity.eid} spawned with hp=${h.hp}`))
@@ -110,16 +101,11 @@ world
 
 // ─── Start ─────────────────────────────────────────────────────────────────
 
-world.start(); // freeze registration, sort systems into phases
-
-// ─── Create entities ───────────────────────────────────────────────────────
-
-const bullet = world.entity();
-bullet.set(Position, { x: 0, y: 0 });
+world.start(); // freeze registration, distribute systems into phases
 
-const vel = bullet.set(Velocity, { vx: 5, vy: 0 }).get(Velocity)!;
+// ─── Spawn entities ────────────────────────────────────────────────────────
 
-const hp = bullet.set(Health, { hp: 3 }).get(Health)!;
+world.entity().set(Position, { x: 0, y: 0 }).set(Velocity, { vx: 5, vy: 0 }).set(Health, { hp: 3 });
 
 // ─── Game loop ─────────────────────────────────────────────────────────────
 
@@ -132,11 +118,25 @@ for (let tick = 0; tick < 5; tick++) {
 
 ---
 
+## Deferred mode
+
+Inside a system body, a `Query.forEach`, or any `world.defer(...)` block, the world is in **deferred mode**: entity mutations (`add` / `set` / `remove` / `destroy` / `setParent` / `modified`) are queued instead of applied inline. The queue drains on the boundary that opened the deferred scope.
+
+Concretely, while deferred:
+
+- `entity.get(C)` returns `undefined` after `entity.add(C)` (no instance has been created yet).
+- `entity.get(C)` returns the **previous** value after `entity.set(C, props)`.
+- `entity.get(C)` still returns the component after `entity.remove(C)`.
+
+Outside any deferred scope (top-level user code) the same calls execute inline and effects are visible immediately. `world.flush()` drains any pending top-level commands; `world.defer(fn)` is sugar for `beginDefer / fn / endDefer`.
+
+---
+
 ## API Reference
 
-### World
+### `World`
 
-The world owns everything. Create one per game session.
+Create one per game session.
 
 ```ts
 const world = new World();
@@ -145,24 +145,22 @@ const world = new World();
 #### Component registration
 
 ```ts
-// Auto-assigned type id (starts at 256 for "local" components):
+// Auto-assigned type id (≥ 256 for "local" components):
 world.registerComponent(Position);
 
-// Explicit numeric type id (required when the id comes from a server):
+// Explicit numeric type id (e.g. server-assigned):
 world.registerComponent(Position, 1);
 
-// With a display name different from the class name:
+// Explicit display name (e.g. when the class name differs from the network name):
 world.registerComponent(Position, "pos");
 
 // Pre-register a name → id mapping before the class is available:
 world.registerComponentType("Position", 1);
 ```
 
-After `world.start()` any further call to `registerComponent` throws.
-
-#### Exclusive components
+After `world.start()` (or `world.disableComponentRegistration()`) any further call to `registerComponent` throws.
 
-Declare a group of components that cannot coexist on the same entity. Adding a member of the group automatically removes any other member that was already present.
+#### Exclusive component groups
 
 ```ts
 world.setExclusiveComponents(Walking, Running, Idle);
@@ -170,12 +168,9 @@ world.setExclusiveComponents(Walking, Running, Idle);
 const e = world.entity();
 e.add(Walking);
 e.add(Running); // Walking is automatically removed first
-// e.get(Walking) === undefined, e.get(Running) is defined
 ```
 
-Each call to `setExclusiveComponents` defines one independent group. Components not in the group are unaffected. A component may belong to at most one exclusivity group (calling `setExclusiveComponents` a second time with the same class overwrites its group).
-
-`setExclusiveComponents` may be called before or after `world.start()`.
+Each call defines one independent group. A component may belong to at most one group; calling `setExclusiveComponents` again with the same class overwrites its group. Safe to call before or after `world.start()`.
 
 #### Entity management
 
@@ -184,58 +179,147 @@ Each call to `setExclusiveComponents` defines one independent group. Components
 const e = world.entity();
 
 // Look up by id (returns undefined if not found):
-const e = world.entity(42);
+const found = world.entity(42);
 
 // Server-assigned id; creates the entity if it doesn't exist yet:
-const e = world.getOrCreateEntity(serverId, (newEntity) => {
+const net = world.getOrCreateEntity(serverId, (newEntity) => {
   tracked.add(newEntity);
 });
 
+// Reserve a high id range for locally created entities so they don't collide
+// with server-assigned ids (call before world.start()):
+world.setEntityIdRange(0x10000);
+
 // Destroy everything (e.g. on level reset):
 world.clearAllEntities();
+```
 
-// Reserve a high id range for locally-created entities so they don't
-// collide with server-assigned ids (call before world.start()):
-world.setEntityIdRange(0x10000);
+#### Hooks
+
+```ts
+world
+  .hook(Sprite)
+  .onAdd((sprite) => sprite.initialize(scene))
+  .onRemove((sprite) => sprite.destroy())
+  .onSet((sprite) => sprite.syncToScene());
+```
+
+`onAdd` fires when the component is first attached. `onRemove` fires when it is removed (or the entity is destroyed). `onSet` fires whenever `component.modified()` (or `entity.modified(c)`) is called, and when `entity.set(C, props)` is applied to an entity that already has the component.
+
+#### Phases
+
+```ts
+const preUpdate = world.addPhase("preupdate");
+const update = world.addPhase("update");
+const send = world.addPhase("send");
+
+// Drive every phase in registration order:
+world.progress(now, delta);
+
+// ...or run individual phases manually:
+world.beginFrame(now, delta);
+try {
+  world.runPhase(preUpdate, now, delta);
+  world.runPhase(update, now, delta);
+  world.runPhase(send, now, delta);
+} finally {
+  world.endFrame();
+}
 ```
 
+Systems with no explicit phase are placed in the built-in `"update"` phase.
+
 #### Systems
 
 ```ts
-// Create, configure, and register a system in one chain:
-world.system("MySystem")
+world
+  .system("MySystem")
   .phase("update")
   .requires(A, B)
   .enter(...)
   .update(...)
+  .each(...)
   .exit(...);
+```
+
+#### Timers and rate filters
+
+Systems can opt into a slower cadence instead of running on every phase tick. `interval()` takes seconds; throttled `run()` callbacks receive the accumulated milliseconds since the previous fire as `delta`.
+
+```ts
+import { IntervalTickSource, RateTickSource } from "@vworlds/vecs";
+
+world
+  .system("Move")
+  .interval(1.0)
+  .each([Position], (e, [pos]) => {
+    // 1 Hz
+  });
+
+world
+  .system("Move")
+  .rate(2)
+  .each([Position], (e, [pos]) => {
+    // every 2nd frame
+  });
 
-world.start(); // distributes systems to phases, freezes component registration
+const second = new IntervalTickSource(1.0);
+
+world
+  .system("Move")
+  .tickSource(second)
+  .each([Position], (e, [pos]) => {
+    // driven by a shared timer
+  });
+
+second.stop();
+second.start();
+
+const minute = new RateTickSource(60, second);
+const hour = world
+  .system("Hour")
+  .tickSource(minute)
+  .rate(60)
+  .run((now, delta) => {
+    console.log("hour tick", now, delta);
+  });
+
+// Systems can also be tick sources for each other.
+const eachSecond = world
+  .system("EachSecond")
+  .interval(1)
+  .run(() => {
+    // ...
+  });
+
+const eachMinute = world
+  .system("EachMinute")
+  .tickSource(eachSecond)
+  .rate(60)
+  .run(() => {
+    // ...
+  });
 ```
 
-#### Queries
+Tick source objects and systems can both be used as sources. Disabling a source system suppresses its callbacks, but its clock still drives downstream consumers.
 
-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.
+#### Queries
 
 ```ts
 const enemies = world
   .query("Enemies")
   .requires(Enemy, Health)
-  .enter((e) => console.log("enemy spawned", e.eid))
-  .exit((e) => console.log("enemy died", e.eid));
+  .enter((e) => console.log("enemy spawned", e.eid));
 
 world.start();
-// enemies.entities is kept up-to-date automatically
+// enemies.entities is kept up-to-date automatically.
 
-// Can also be created after start(); existing matched entities are backfilled:
-const lateQuery = world.query("Walls").requires(Wall);
-// lateQuery.entities immediately contains all current Wall entities
+// Standalone queries can also be created after start(); existing matched
+// entities are backfilled immediately.
 ```
 
 #### Filters
 
-A `Filter` is a non-reactive, one-shot scan. It holds no tracked entity set — each `forEach` call walks all world entities at that moment. Use it for ad-hoc lookups that don't need to stay live.
-
 ```ts
 // Entity only:
 world.filter([Position]).forEach((e) => console.log(e.eid));
@@ -249,55 +333,30 @@ world.filter([Position, Velocity]).forEach([Position, Velocity], (e, [pos, vel])
 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
+    pos.x += vel.vx;
   });
 
-// Manual type hint for queries the extractor can't see through:
+// Manual hint for queries the type extractor can't see through:
 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.
+A `Filter` requires no name, no `world.start()`, and no `destroy()` — create it anywhere and discard freely.
 
-#### Phases
+#### Pipeline control
 
 ```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");
-
-// 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);
-```
-
-Systems with no explicit phase go into a built-in `"update"` phase.
-
-#### Hooks
-
-A hook is a shorthand for reacting to a single component's lifecycle without writing a full system:
+world.start();                         // freeze registration, distribute systems
+world.disableComponentRegistration();  // freeze registration without sorting
 
-```ts
-world
-  .hook(Sprite)
-  .onAdd((sprite) => sprite.initialize(scene))
-  .onRemove((sprite) => sprite.destroy())
-  .onSet((sprite) => sprite.syncToScene());
+world.flush();                         // drain queued top-level mutations
+world.defer(() => { ... });            // run a block in deferred mode
+world.beginDefer();                    // pair with endDefer() for finer scoping
+world.endDefer();
 ```
 
-`onSet` fires whenever `component.modified()` is called.  
-`onAdd` fires when the component is first attached to an entity.  
-`onRemove` fires when it is removed or the entity is destroyed.
-
 ---
 
-### Component
-
-Extend `Component` to define your data:
+### `Component`
 
 ```ts
 class Position extends Component {
@@ -312,90 +371,80 @@ const pos = entity.get(Position)!;
 pos.x = 100;
 pos.modified(); // tell the world this component changed
 
-// Alternatively:
+// Equivalent — set assigns props and fires onSet automatically:
 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.        |
+| `meta`            | `ComponentMeta` — type id, display name, and bit-pointer.             |
 | `type`            | Numeric type id (shorthand for `meta.type`).                          |
+| `bitPtr`          | `BitPtr` (shorthand for `meta.bitPtr`).                               |
 | `modified()`      | Queue an `onSet` / `update` notification. Call after mutating fields. |
+| `toString()`      | Returns the registered component name.                                |
 
 ---
 
-### Entity
-
-```ts
-const e = world.entity();
-```
-
-| 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:
+### `Entity`
+
+Created via `world.entity()` (auto-assigned id) or `world.getOrCreateEntity(id, ...)` (caller-supplied id).
+
+| Property / Method     | Description                                                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `eid`                 | Unique numeric entity id.                                                                                                             |
+| `world`               | The `World` that owns this entity.                                                                                                    |
+| `componentBitmask`    | `Bitset` of component type ids attached to this entity. Used by archetype matching.                                                   |
+| `properties`          | `Map<string, any>` free-form bag for module-level bookkeeping.                                                                        |
+| `add(Class)`          | Attach a component (idempotent). Returns the entity for chaining.                                                                     |
+| `set(Class, props)`   | Attach a component and assign `props`; fires `onSet`. Returns the entity for chaining.                                                |
+| `modified(component)` | Queue an `onSet` / `update` notification. Returns the entity for chaining.                                                            |
+| `get(Class)`          | Return the component instance, or `undefined`.                                                                                        |
+| `remove(Class)`       | Detach a component (fires `onRemove` and `exit`).                                                                                     |
+| `destroy()`           | Remove all components, unregister from the world, recurse into children.                                                              |
+| `components`          | `ReadonlyArrayMap<Component>` — read-only view of attached components keyed by type id. Supports `forEach`, `get`, `has`, and `size`. |
+| `empty`               | `true` when no components are attached.                                                                                               |
+| `parent`              | Parent entity, or `undefined` for a root entity.                                                                                      |
+| `children`            | `ReadonlySet<Entity>` of direct children (lazy).                                                                                      |
+| `setParent(p)`        | Reparent the entity. `undefined` makes it a root entity. Throws on cycles.                                                            |
+| `events`              | Typed event emitter. Currently emits `"destroy"` just before teardown.                                                                |
+| `toString()`          | Returns `"EntityN"`.                                                                                                                  |
+
+`entity.modified(c)` is equivalent to `c.modified()` but returns the entity so it can 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)!);
+entity.modified(vel); // chainable
 ```
 
-#### Parent–child hierarchy
+#### Parent / child hierarchy
 
 ```ts
-child.parent = parent;
-parent.children.add(child);
+child.setParent(parent);
+parent.children.has(child); // true
 
 // Destroying a parent recursively destroys all children:
 parent.destroy();
 ```
 
-Archetype queries that use `{ PARENT: ... }` are automatically re-evaluated when a parent's component set changes.
+`setParent` throws if the new parent is a descendant of the entity. Archetype queries that use `{ PARENT: ... }` are re-evaluated automatically when a parent's component set changes.
 
 ---
 
-### System
+### `System`
 
-Systems are created via `world.system(name)` and configured through a fluent builder API. All methods return `this` for chaining.
+Systems are created via `world.system(name)` and configured through a fluent builder. Every method returns `this` for chaining. `System` extends `Query`, so the membership / enter / exit / update / sort APIs are shared.
 
 #### `.requires(...components)` and `.query(q)`
 
-Declare which entities the system should track:
+Declare which entities the system tracks.
 
 ```ts
-// Entities that have both Position and Velocity:
-.requires(Position, Velocity)
-
-// Equivalent explicit query:
-.query({ HAS: [Position, Velocity] })
-
-// Entities that have a parent with Player AND Container:
-.query({ PARENT: { AND: [Player, Container] } })
-
-// Compound queries:
-.query({ AND: [Position, { OR: [Sprite, Container] }] })
+.requires(Position, Velocity)                                    // shorthand for HAS
+.query({ HAS: [Position, Velocity] })                            // explicit
+.query({ PARENT: { AND: [Player, Container] } })                 // parent-aware
+.query({ AND: [Position, { OR: [Sprite, Container] }] })         // compound
 .query({ NOT: Invisible })
 ```
 
@@ -409,130 +458,128 @@ Declare which entities the system should track:
 | `{ 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]`              |
+| An array `[A, B]`      | Shorthand for `{ HAS: [A, B] }`          |
+| A single class / id    | Shorthand for `{ HAS: [C] }`             |
+| A predicate function   | Custom membership logic                  |
 
-**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:
+**Type inference.** `requires()` records the listed classes as a type parameter `R` on the system. Callbacks in `.sort()`, `.each()`, and `.update()` injection treat those components as non-nullable — no `!` needed. For complex `query()` expressions the type system can't introspect, supply a `_guaranteed` second argument:
 
 ```ts
 .query({ AND: [{ HAS: Position }, { HAS: Velocity }] }, [Position, Velocity])
 .each([Position, Velocity], (e, [pos, vel]) => {
   pos.x += vel.vx; // pos and vel are non-null
-})
+});
 ```
 
 #### `.phase(p)`
 
-Assign the system to a named phase or an `IPhase` reference. Systems without a phase run in `"update"`.
+Assign the system to a phase by name or `IPhase` reference. Default phase is `"update"`.
 
 ```ts
-.phase("preupdate")   // by name
-.phase(myPhase)       // by IPhase reference
+.phase("preupdate")
+.phase(myPhase)
 ```
 
 #### `.enter(callback)` / `.enter(inject, callback)`
 
-Called once when an entity first matches the system's query.
+Fires once when an entity first matches the system.
 
 ```ts
-// No injection:
-.enter((e) => { console.log("entity joined", e.eid); })
-
-// With injection — component instances resolved from the entity:
+.enter((e) => { ... })
 .enter([Position, Sprite], (e, [pos, sprite]) => {
   sprite.setPosition(pos.x, pos.y);
 })
 
-// Resolve from parent:
+// Resolve from the entity's parent:
 .enter([{ parent: Container }], (e, [container]) => {
   container.add(e.get(Sprite)!.gameObject);
-})
+});
 ```
 
 #### `.exit(callback)` / `.exit(inject, callback)`
 
-Called when an entity leaves the system (component removed or entity destroyed). Components removed in the same frame are still accessible in exit callbacks.
+Fires when an entity leaves the system (component removed or entity destroyed). Components removed in the same frame are still resolvable in `inject`.
 
 ```ts
-.exit([Sprite], (e, [sprite]) => {
-  sprite.destroy();
-})
+.exit([Sprite], (e, [sprite]) => sprite.destroy());
 ```
 
 #### `.update(ComponentClass, callback)` / `.update(ComponentClass, inject, callback)`
 
-Called when `component.modified()` is queued on a watched component of a tracked entity.
+Fires when `component.modified()` is called for the watched component on a tracked entity.
 
 ```ts
-// Simple — receives the modified component:
-.update(Position, (pos) => {
-  renderer.setPosition(pos.x, pos.y);
-})
+.update(Position, (pos) => renderer.setPosition(pos.x, pos.y));
 
-// With injection — receives the modified component and extra components:
 .update(Position, [Sprite], (pos, [sprite]) => {
   sprite.sprite.setPosition(pos.x, pos.y);
-})
+});
 ```
 
-Injected components listed in `requires()` are non-nullable in the callback; any others are `Type | undefined`.
-
-Calling `update` also adds that component type to the system's implicit `HAS` query (unless you called `query()` first).
+If `query()` has not been called, `update` automatically expands the implicit `HAS` predicate to require the watched component.
 
 #### `.each(components, callback)`
 
-Called every tick for **every tracked entity**, unconditionally. Unlike `update` (which only fires when `component.modified()` is called), `each` fires regardless of whether the component was modified — use it for per-entity logic that must run on every frame.
-
-The callback receives the entity and a tuple of resolved component instances. Components declared via `requires()` are guaranteed non-null; any others are `undefined` if the entity lacks them.
+Fires every tick for **every tracked entity**, regardless of whether anything changed. Use it for per-entity logic that must run every frame. Implies `.track()`. Only one `each` per system.
 
 ```ts
 .requires(Position, Velocity)
 .each([Position, Velocity], (e, [pos, vel]) => {
-  pos.x += vel.vx; // non-null — both are in requires()
-  pos.y += vel.vy;
-})
+  pos.x += vel.vx;
+});
 ```
 
-`each` does not modify the system's query — define membership with `requires(...)` or `query(...)` as usual. Only one `each` may be registered per system; a second call throws.
-
 #### `.sort(components, compare)`
 
-Enable sorted entity tracking. Matched entities are stored in an ordered set whose insertion position is determined by `compare`, which receives a tuple of resolved component instances for each pair being ordered. Implies `.track()`.
-
-Components declared via `requires()` are non-null in the compare callback.
+Store matched entities in a custom order determined by `compare`. Implies `.track()`. Iterating `system.entities`, `forEach`, and `each` walks entities in sorted order.
 
 ```ts
 world
   .system("Render")
   .requires(Position, Sprite)
   .sort([Position], ([posA], [posB]) => posA.z - posB.z)
-  .each([Position, Sprite], (e, [pos, sprite]) => {
-    sprite.draw(pos.x, pos.y);
-  });
+  .each([Position, Sprite], (e, [pos, sprite]) => sprite.draw(pos.x, pos.y));
 ```
 
-Iterating `system.entities` after a phase run yields entities in the sorted order.
-
 #### `.track()`
 
-Enable entity tracking without an `each` callback — matched entities are exposed via `system.entities` (or `query.entities`) as they enter and leave. `each` and `sort` imply `track` automatically; call this directly only when you need the tracked set without a per-tick callback.
-
-When called after `world.start()`, `track()` immediately backfills existing entities that satisfy the query predicate.
+Enable entity tracking without an `each` callback — exposes matched entities via `system.entities`. `each` and `sort` imply `track` automatically. When called after `world.start()`, immediately backfills existing matched entities.
 
 #### `.run(callback)`
 
-Called every tick when the system's phase runs, regardless of entity state. Use this for polling, network I/O, timers, etc.
+Fires every tick when the system's phase runs, regardless of entity state. Use for polling, network I/O, timers, etc.
 
 ```ts
 .run((now, delta) => {
   sendNetworkPacket(now);
-})
+});
 ```
 
+#### `.disable()` / `.enable()`
+
+Pause and resume a system at runtime. While disabled the system is effectively invisible: the inbox is cleared immediately, any new `enter`, `exit`, or `update` events are silently dropped, `run` and `each` callbacks do not fire, and the system skips its `_run` entirely. Entity membership in the underlying query is still maintained, so the tracked set remains correct and the system resumes cleanly when re-enabled. Events that occurred while the system was disabled are **not** replayed.
+
+```ts
+const ai = world.system("AI").requires(Enemy).run(tickAI);
+
+// Pause AI processing during a cutscene:
+ai.disable();
+
+// Resume normal processing:
+ai.enable();
+```
+
+Both methods return `this` for chaining and are idempotent (calling `disable()` on an already-disabled system, or `enable()` on an already-enabled system, is a no-op).
+
+#### `.destroy()`
+
+**Not supported on `System`** — calling it throws. Systems live for the duration of the world. Use a standalone `Query` for temporary reactive sets.
+
 ---
 
-### Query
+### `Query`
 
-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.
+`world.query(name)` returns a standalone reactive entity set, configured through the same builder API as `System`. It has no phase and no per-tick callbacks.
 
 ```ts
 const projectiles = world
@@ -545,46 +592,42 @@ const projectiles = world
 
 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 to `HAS(...components)` and start tracking. |
+| `.query(expr, _guaranteed?)`                            | Set the membership predicate using a `QueryDSL` expression.              |
+| `.enter(callback)` / `.enter(inject, callback)`         | Fires when an entity joins the query.                                    |
+| `.exit(callback)` / `.exit(inject, callback)`           | Fires when an entity leaves the query.                                   |
+| `.update(C, callback)` / `.update(C, inject, callback)` | Fires when `C` is modified on a tracked entity.                          |
+| `.sort(components, compare)`                            | Store matched entities in sorted order.                                  |
+| `.track()`                                              | Enable tracking. Backfills when called after `start()`.                  |
+| `.belongs(e)`                                           | Returns `true` if the entity satisfies the predicate.                    |
+| `.forEach(callback)`                                    | Iterate currently tracked entities.                                      |
+| `.forEach(components, callback)`                        | Iterate with component injection.                                        |
+| `.entities`                                             | `ReadonlySet<Entity>` of currently tracked entities.                     |
+| `.destroy()`                                            | Remove the query from the world and from every entity (no exit fires).   |
 
-#### `.destroy()`
+#### `.destroy()` semantics
 
-Permanently removes a standalone query from the world. All entity references are silently purged (no exit callbacks fire), the tracked entity set is cleared, and the query's `world` reference is set to `undefined`. After this call, any use of the query object is **undefined behavior**.
+`destroy()` permanently removes a standalone query from the world. Entity references are silently purged (no `exit` callbacks fire), the tracked set is cleared, and the `world` reference is set to `undefined`. Any further use of the object is **undefined behavior**.
 
 ```ts
 const q = world.query("Temporary").requires(Position);
 // ... use q.entities ...
-q.destroy(); // unregisters from world and all entities
+q.destroy();
 ```
 
-`System` does **not** support `destroy()` — calling it throws. Systems are owned by the world for the lifetime of the session. Use a standalone `Query` when you need a temporary reactive set.
-
-Both `System` and `Query` share the same query DSL, enter/exit callbacks, sort, and `entities` set — `System` extends `Query` and layers phase execution on top.
+`System` shares the same DSL, callback, sorting, and tracking machinery — `System` extends `Query` and adds phase placement, `run`, `each`, and an inbox replayed on every tick.
 
 ---
 
-### Filter
+### `Filter`
 
-A `Filter` is created via `world.filter(dsl)` and provides a non-reactive `forEach`. It accepts the same [`QueryDSL`](#-requirescomponents-and-queryq) expressions as systems and queries.
+`world.filter(dsl)` returns a `Filter` that performs a non-reactive scan. It accepts the same `QueryDSL` expressions as systems and queries.
 
 ```ts
 const f = world.filter([Position, Velocity]);
@@ -592,30 +635,58 @@ const f = world.filter([Position, Velocity]);
 
 | Method                           | Description                                                                |
 | -------------------------------- | -------------------------------------------------------------------------- |
-| `.forEach(callback)`             | Walk all world entities; invoke callback for each matching one.            |
+| `.forEach(callback)`             | Walk all world entities; invoke callback on each match.                    |
 | `.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:
+`forEach` runs inside a deferred scope, so mutations made by the callback are batched and become visible after iteration finishes.
+
+**Type inference.** Component classes the type system can extract from the DSL (`HAS`, `HAS_ONLY`, plain arrays, `AND` of those) are non-nullable in the callback tuple. For the rest, supply a `_guaranteed` second argument to `world.filter()`:
 
 ```ts
 // Auto-deduced — both non-null:
-world.filter([Position, Velocity])
-  .forEach([Position, Velocity], (e, [pos, vel]) => { ... });
+world.filter([Position, Velocity]).forEach([Position, Velocity], (e, [pos, vel]) => { ... });
 
 // Manual hint for OR / NOT / PARENT / custom function:
-world.filter({ OR: [Position, Velocity] }, [Position])
-  .forEach([Position], (e, [pos]) => pos.x);
+world.filter({ OR: [Position, Velocity] }, [Position]).forEach([Position], (e, [pos]) => pos.x);
 ```
 
 A `Filter` holds no tracked set, makes no registration calls, and needs no `destroy()`.
 
 ---
 
+### `Bitset`
+
+A compact, growable set of non-negative integers backed by 32-bit words. Used internally for entity archetypes and watchlists, and exposed in the public API so component data can use it for bit-flag fields.
+
+| Method             | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| `add(n)`           | Set bit `n`.                                                             |
+| `addBit(bptr)`     | Set the bit at a pre-computed `BitPtr`.                                  |
+| `delete(n)`        | Clear bit `n`. Trims trailing zero words.                                |
+| `has(n)`           | Returns `true` if bit `n` is set.                                        |
+| `hasBit(bptr)`     | Fast check via a pre-computed `BitPtr`.                                  |
+| `equal(other)`     | Returns `true` when both bitsets have the same bits set.                 |
+| `hasBitset(other)` | Returns `true` when every bit set in `other` is also set in this bitset. |
+| `forEach(cb)`      | Visit each set bit index in ascending order.                             |
+| `indices()`        | Return all set bit indices as a `number[]`.                              |
+
+```ts
+class Tags extends Component {
+  tags = new Bitset();
+}
+
+tags.tags.add(TAG_VISIBLE);
+if (tags.tags.has(TAG_VISIBLE)) { ... }
+```
+
+---
+
 ## Build & Test
 
 ```
 yarn build
 yarn test
+yarn lint
 ```
 
 ---