@vworlds/vecs 1.0.25 → 1.0.27

package/docs/modules.md

@@ -0,0 +1,108 @@
+# Modules
+
+Package components, systems, and policy into reusable units, compose them, and meet the built-in
+modules every world installs.
+
+## What a module is
+
+A `Module` (`lib/vecs/src/module.ts`) is a component entity whose `init()` method runs once when
+the module is registered. It is the unit of packaging for a feature: registering components,
+declaring systems, setting exclusivity and cleanup policy, and (rarely) inserting phases.
+
+```ts
+import { Module, PRE_STORE } from "@vworlds/vecs";
+
+export class PoseSyncModule extends Module {
+  public init(): void {
+    const world = this.world;
+    world.component(PhysicsPosition);
+    world.component(RenderPosition);
+    world
+      .system("sync.position")
+      .with(PhysicsPosition, RenderPosition)
+      .phase(PRE_STORE)
+      .update(PhysicsPosition, (e, p) => e.set(RenderPosition, { x: p.x, y: p.y }));
+  }
+}
+
+world.module(PoseSyncModule);
+```
+
+`world.module(ModuleClass, config?, eid?)` (`lib/vecs/src/world/world.modules.ts`) registers the
+module on first call — drawing its entity id from the `module` pool (900–999 by default, or pass
+an explicit `eid`) — and invokes `init(config)` exactly once. Subsequent calls return the existing
+module instance; passing a config again after the first registration throws.
+
+## Configuration
+
+Type the config through the `Module<Config>` parameter; it flows from `world.module(M, config)`
+into `init(config)`:
+
+```ts
+export class RenderModule extends Module<{ scene: Scene; pixelsPerMeter?: number }> {
+  public init(cfg: { scene: Scene; pixelsPerMeter?: number }): void {
+    const ppm = cfg.pixelsPerMeter ?? 32;
+    // ...
+  }
+}
+
+world.module(RenderModule, { scene });
+```
+
+For `Module<undefined>` (the default), the config argument is omitted. Keep configs minimal;
+prefer zero-config when a sensible default exists.
+
+## Composition and umbrella modules
+
+A module's `init` can register sub-modules with `this.world.module(Sub, subConfig)`. A big feature
+is often one module per item plus a thin umbrella that composes them:
+
+```ts
+export class PhaserRenderModule extends Module<{ scene: Scene }> {
+  public init(cfg: { scene: Scene }): void {
+    this.world.component(VGameObject).onRemove((_e, vgo) => vgo.obj.destroy());
+    this.world.module(ArcModule, { scene: cfg.scene });
+    this.world.module(RectangleModule, { scene: cfg.scene });
+    // … shape modules first …
+    this.world.module(TransformSyncModule, {}); // … then sync, so create precedes sync within a phase
+  }
+}
+```
+
+**Load order sets same-phase order.** Systems in the same phase run in creation order, so the
+order an umbrella loads sub-modules is the order their systems run within a shared phase. Use
+that for intra-feature ordering — but express **cross-module** ordering with phases, never with
+load order (see [Execution model](./execution-model.md#ordering-guarantees)).
+
+Guidelines:
+
+- **Declare systems inline in `init`.** A `registerFooSystem(world)` helper per system is a layer
+  for nothing.
+- **Modules own cross-cutting policy** — `setExclusiveComponents`, cleanup policies, phase
+  placement, component registration. Keep that out of application code.
+- **One module per cohesive thing.** Don't pile unrelated features into one `init`.
+
+## Built-in modules
+
+Every `World` constructor installs these (`lib/vecs/src/world/world.ts`); you interact with their
+_components_, not with the module objects:
+
+| Module                | Provides                                                                                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IdentityModule`      | The `Identity` name component and the name → entity index behind `world.entity("name")` / `entity.name`.                                                  |
+| `ImplementsModule`    | Maintains [`Implements` interface aliases](./components.md#interface-aliases-with-implements) and their transitive closure.                               |
+| `SingletonModule`     | Enforces the [`Singleton`](./components.md#singletons-and-world-global-data) one-carrier constraint.                                                      |
+| `RelationshipsModule` | Registers `ChildOf` (with the `Delete` cascade) and maintains [`Traversable` depth tracking](./relationships.md#traversal-order-traversable-and-cascade). |
+| `PipelineModule`      | Creates the eight [built-in phases](./execution-model.md#phases-the-pipeline-spine) and installs the default pipeline query.                              |
+
+All are exported, so a custom world setup can reuse them.
+
+## Reference
+
+| API                                                                            | Description                                                                                         |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `class M extends Module<Config>`                                               | Declare a module; `Config` defaults to `undefined`.                                                 |
+| `init(config)`                                                                 | One-time setup hook; called by the world on first registration.                                     |
+| `world.module(M)` / `world.module(M, config)` / `world.module(M, config, eid)` | Register (first call) or retrieve (later calls) the module. Config after first registration throws. |
+| `this.world`                                                                   | Inside `init`: the owning world (a module is an entity).                                            |
+| `ModuleConfig<T>`                                                              | Utility type extracting a module's config type.                                                     |

package/docs/queries-and-filters.md

@@ -0,0 +1,187 @@
+# Queries and Filters
+
+Express entity predicates with the query DSL, track them live with `Query`, scan once with
+`Filter`, index with `groupBy`, and reach for the `Bitset` utility that powers matching.
+
+## The query DSL
+
+A `QueryDSL` (`lib/vecs/src/dsl.ts`) is a composable expression describing which entities match.
+It is accepted by `query().with`, `system().with`, and `world.filter`:
+
+| Operator               | Meaning                                                             |
+| ---------------------- | ------------------------------------------------------------------- |
+| a component class/id   | Entity has that component                                           |
+| an array `[A, B]`      | Entity has all of `A` and `B` (empty array matches all)             |
+| `true` / `false`       | Match all / match no entities                                       |
+| `{ all: [q1, q2] }`    | Every sub-expression matches                                        |
+| `{ any: [q1, q2] }`    | At least one sub-expression matches                                 |
+| `{ not: q }`           | Sub-expression must not match                                       |
+| `{ only: [A, B] }`     | Entity has exactly `A` and `B`, nothing else                        |
+| `{ target: [R, q] }`   | Relationship `R`'s target matches `q`                               |
+| `{ source: [R, q] }`   | Filter-only: some entity targeting this one through `R` matches `q` |
+| `{ parent: q }`        | Built-in `ChildOf` target matches `q`                               |
+| `{ children: q }`      | Filter-only: some `ChildOf` child matches `q`                       |
+| `{ test: fn, watch? }` | Custom predicate; rechecked when a `watch`-listed component changes |
+
+Operators nest arbitrarily:
+
+```ts
+world.system("render").with({
+  all: [Position, { any: [Sprite, Container] }],
+});
+```
+
+Class-valued terms are components — register them first; an unregistered class throws. Use
+`{ test: fn }` for arbitrary logic the operators can't express, with `watch` naming the components
+whose changes should re-evaluate it.
+
+`target` and `source` take tuple form only: `{ target: [RelationshipClass, innerDSL] }`. The first
+element must extend `Relationship` (a plain component throws). `target` evaluates the inner DSL
+against the relationship's target; `source` evaluates it against each entity pointing at the
+candidate and matches when at least one does. `parent` / `children` are the same operators
+specialized to `ChildOf`. **`source` and `children` are non-reactive**: exact for each filter
+scan, but rejected by tracked queries and systems. `target` / `parent` are fully reactive — see
+[Relationships](./relationships.md#querying-through-relationships).
+
+### `QuerySpec`: adding `cascade` and `hint`
+
+Anywhere a DSL is accepted, you can pass the object form
+`{ with: dsl, cascade?: Rel, hint?: [C...] }`:
+
+- `cascade` orders the tracked set depth-first along a
+  [`Traversable` relationship](./relationships.md#traversal-order-traversable-and-cascade).
+- `hint` declares components as guaranteed-present for **type inference only** (not validated at
+  runtime). Use it when the DSL shape (`any`, `not`, `test`, numeric ids) hides a guarantee the
+  type extractor can't see:
+
+```ts
+world
+  .filter({ with: { any: [Position, Velocity] }, hint: [Position] })
+  .forEach([Position], (e, [pos]) => pos.x);
+```
+
+Without a hint, only plain classes, arrays, `only`, and `all`-chains of those count as guaranteed,
+and everything else injects as `T | undefined`.
+
+## Live queries: `Query`
+
+`world.query(name)` returns a standalone reactive entity set (`lib/vecs/src/query/query.ts`),
+configured through the same fluent builder as systems but without pipeline integration:
+
+```ts
+const projectiles = world
+  .query("Projectiles")
+  .with(Position, Velocity)
+  .enter((e) => console.log("spawned", e.eid))
+  .exit((e) => console.log("gone", e.eid));
+
+projectiles.count; // kept up to date automatically
+projectiles.has(e);
+for (const e of projectiles) { ... }
+projectiles.forEach([Position], (e, [pos]) => { ... });
+```
+
+The crucial difference from systems: **standalone query callbacks fire synchronously** while the
+world routes a command, not in a phase slot. Mutations made inside one callback are themselves
+observed immediately by other queries. Systems instead queue events into an inbox replayed on
+their tick (see [Execution model](./execution-model.md#reactive-routing)).
+
+### Lifecycle: build, backfill, destroy
+
+A query is **built** — its predicate materialized and registered — at the next `world.flush()` /
+`progress()`, or immediately via `query.build()` outside deferred mode. Tracked queries (and any
+query with callbacks) **backfill**: entities that already match are routed through `enter` at
+build time. Builder methods throw once the query is built; `built` reports the state.
+
+`query.destroy()` permanently removes the query: entity references are purged silently (no `exit`
+fires), the tracked set is cleared, and further use of the object is undefined behavior. Use a
+standalone query when you need a reactive set you can destroy mid-session.
+
+### Reading a query
+
+| Member                      | Description                                                                                              |
+| --------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `count`                     | Number of currently tracked entities (0 unless tracking).                                                |
+| `has(e)`                    | `true` when `e` is currently tracked.                                                                    |
+| `belongs(e)`                | Evaluate the predicate against `e` right now (works regardless of tracking).                             |
+| `[Symbol.iterator]`         | Iterate tracked entities.                                                                                |
+| `forEach(...)`              | Iterate with optional [component injection](./systems.md#component-injection); runs in a deferred scope. |
+| `changed`                   | `true` when membership or watched data changed since the last `forEach` reset it.                        |
+| `name` / `entity` / `world` | Display name; the backing entity; the owning world.                                                      |
+
+`orderBy`, `track`, `enter`, `exit`, `update`, `with`, and `without` behave exactly as on systems
+— see [Systems](./systems.md) — except that `update` callbacks fire synchronously here. A plain
+`Query.update` callback can therefore re-enter during command routing; snapshot reused `Iter` /
+tuple values before triggering further mutations from inside it.
+
+### Silencing feedback: `ignoreSource`
+
+`query.ignoreSource(dsl | query)` makes the query drop `update` notifications whose originating
+system matches the given query — the standard cure for write feedback loops (A updates B, B's
+system writes back, A reacts again). The relationship is stored as the built-in `SilenceSource`
+component on the query's backing entity. Entry-time initialization bypasses the silence filter, so
+newly entered entities still initialize.
+
+## Grouped queries: `groupBy`
+
+`groupBy` partitions a query's members into live buckets you can look up by key — spatial grids,
+interest management, any "find members in bucket K" — without re-scanning:
+
+```ts
+const ballsByCell = world
+  .query("ByCell")
+  .with(Ball, Position)
+  .groupBy([Position], (_e, [p]) => cellIndex(p)); // re-buckets reactively as Position changes
+
+ballsByCell.group(key)?.forEach([Position], (e, [p]) => { ... });
+ballsByCell.group(key)?.count;
+for (const group of ballsByCell.groups()) { ... }
+```
+
+Two forms (`lib/vecs/src/query/grouped_query.ts`):
+
+- `groupBy([components], keyFn)` — bucket by a computed key; injected components are watched, so
+  changing them re-keys the entity.
+- `groupBy(RelationshipClass)` — bucket by the relationship's target entity. Moving between
+  buckets is a retarget, a plain data change (see
+  [Relationships](./relationships.md#retargeting)).
+
+The result is a `GroupedQuery<K, R>` adding `group(key)`, `groups()`, `groupKeys()`, `groupCount`,
+and `onGroupEnter` / `onGroupExit` callbacks for bucket creation and disposal. Each `Group` exposes
+`key`, `count`, `has`, iteration, and injected `forEach`. Grouping implies tracking. Systems do
+not support `groupBy` — keep the grouped query standalone and read it from a system.
+
+## Filters: one-shot scans
+
+`world.filter(spec)` returns a `Filter` (`lib/vecs/src/filter.ts`): a non-reactive predicate that
+walks entities on each `forEach` call. It accepts the same DSL (including the filter-only
+`source` / `children` operators):
+
+```ts
+// Entity only:
+world.filter([Position]).forEach((e) => console.log(e.eid));
+
+// With component injection (auto-deduced non-null types):
+world.filter([Position, Velocity]).forEach([Position, Velocity], (e, [pos, vel]) => {
+  pos.x += vel.vx;
+});
+
+// Manual hint where the extractor can't see through the DSL:
+world
+  .filter({ with: { any: [Position, Velocity] }, hint: [Position] })
+  .forEach([Position], (e, [pos]) => pos.x);
+```
+
+A `Filter` holds no tracked set, registers nothing, and needs no `destroy()` — create it anywhere
+and discard freely. `forEach` runs inside a deferred scope, so mutations made by the callback are
+batched and visible after iteration; nested inside an already-deferred block it inherits the outer
+scope. When the world already maintains a live term for the same predicate, the filter iterates
+that term instead of scanning every entity.
+
+Use a `Filter` for occasional or one-off scans; use a `Query`/`System` when you need continuous
+reactivity.
+
+## `Bitset`
+
+`Bitset` is the compact integer-set type that powers entity archetypes and query watchlists.
+It is documented in full in [Utilities](./utilities.md#bitset).

package/docs/relationships.md

@@ -0,0 +1,149 @@
+# Relationships
+
+Link entities to entities with relationship components: hierarchy, reverse lookup, retargeting,
+cleanup cascades, and depth-ordered traversal.
+
+## What a relationship is
+
+A relationship is a component whose `target` field points at another entity. Define one by
+extending the abstract `Relationship` base (`lib/vecs/src/component_meta.ts`) and registering it
+like any component:
+
+```ts
+import { Relationship } from "@vworlds/vecs";
+
+class EquippedBy extends Relationship {}
+
+world.component(EquippedBy);
+
+item.set(EquippedBy, { target: player });
+item.target(EquippedBy); // player
+player.children(EquippedBy).has(item); // true
+```
+
+The **source** entity stores the relationship component; the **target** can enumerate its sources
+with `children(ref)` through a reverse index the world maintains automatically. An entity holds at
+most one instance of a given relationship class (like any component), so multi-target links are
+modeled with one relationship class per meaning, or child entities.
+
+Because `target` is an `Entity` reference, **relationships are not wire-serializable — don't try
+to network them**. Replicate a plain id or tag instead, or keep the relationship server-local.
+
+## Built-in relationships
+
+| Class           | Purpose                                                                                                                    |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `ChildOf`       | General parent/child hierarchy. `onDeleteTarget = Delete`: destroying a parent destroys its `ChildOf` children.            |
+| `DependsOn`     | Pipeline ordering: phases chain to each other and systems attach to phases through it.                                     |
+| `SilenceSource` | Marks a query's silence domain; configured via [`ignoreSource`](./queries-and-filters.md#silencing-feedback-ignoresource). |
+
+`entity.childOf(parent)` is shorthand for `entity.set(ChildOf, { target: parent })`.
+
+## Retargeting
+
+Point a relationship somewhere else with a plain `set`:
+
+```ts
+unit.set(InCell, { target: newCell }); // reverse index updates automatically
+```
+
+Retargeting is a **data change, not an archetype change** — no component is added or removed, so
+no `enter`/`exit` churn. Prefer retargeting a relationship over swapping marker components to
+express "which bucket this entity is in", and pair it with
+[`groupBy(Relationship)`](./queries-and-filters.md#grouped-queries-groupby) for O(1) bucket
+lookups.
+
+`getMut` throws for relationship components: in-place target mutation would bypass the reverse
+index used by `children()` and the cleanup cascades. Always retarget with `set`.
+
+## Cleanup when a target dies
+
+What happens to sources when their target entity is destroyed is governed by the relationship's
+`meta.onDeleteTarget`:
+
+| Policy                 | Meaning                                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| `CleanupPolicy.Remove` | Default. The relationship component is removed from each source.                          |
+| `CleanupPolicy.Delete` | Each source entity targeting the destroyed entity through this relationship is destroyed. |
+
+```ts
+import { CleanupPolicy } from "@vworlds/vecs";
+
+world.component(MyRel).meta.onDeleteTarget = CleanupPolicy.Delete; // cascade like ChildOf
+```
+
+`ChildOf` ships with `Delete`, so destroying a parent recursively destroys its subtree:
+
+```ts
+child.set(ChildOf, { target: parent });
+parent.destroy(); // child (and its own ChildOf children) are destroyed too
+```
+
+`onDeleteTarget` is independent from `onDelete`: `onDeleteTarget` runs when a relationship
+**target** is destroyed; `onDelete` runs when the relationship **component entity itself** is
+destroyed (see
+[Components — cleanup policies](./components.md#cleanup-policies-destroying-a-component-entity)).
+
+## Querying through relationships
+
+The DSL follows relationships in both directions
+([operator table](./queries-and-filters.md#the-query-dsl)):
+
+```ts
+// Reactive: candidates whose FriendOf target has Position and Velocity.
+world.query("body-friends").with({ all: [Body, { target: [FriendOf, [Position, Velocity]] }] });
+
+// Reactive: candidates whose ChildOf parent has Body.
+world.query("positioned-children").with({ all: [Position, { parent: Body }] });
+
+// Filter-only: parents with at least one ChildOf child that has Position.
+world.filter({ all: [Body, { children: Position }] }).forEach((parent) => { ... });
+```
+
+`target` / `parent` queries are **live on both sides**: adding or removing the relationship on the
+candidate re-routes it normally, and changing the _target's_ components refreshes every candidate
+pointing at it — across multiple nested `target` hops. `source` / `children` look down the reverse
+index and are **non-reactive**: exact for each `Filter` scan but rejected by tracked queries and
+systems.
+
+To pull a target's or children's components into callbacks, use `target` / `down` injection — see
+[Systems — relationship injection](./systems.md#relationship-injection-target-and-down).
+
+## Traversal order: `Traversable` and `cascade`
+
+Tag a relationship component entity with `Traversable` to enable automatic depth tracking: every
+entity carrying the relationship gets a depth (hops to its root), maintained reactively by
+`RelationshipsModule` (`lib/vecs/src/modules/relationships.ts`):
+
+```ts
+import { Traversable } from "@vworlds/vecs";
+
+world.component(InCell).add(Traversable);
+```
+
+A query can then order its members depth-first along the relationship with `cascade`:
+
+```ts
+world.query("tree").with({ with: Node, cascade: ChildOf });
+```
+
+Parents sort before children. Retargeting updates relationship depths, and cascade-ordered queries
+refresh their order before the next iteration. `ChildOf` and `DependsOn` are `Traversable` out of
+the box — the world's default pipeline is itself a `cascade: DependsOn` query (see
+[Execution model](./execution-model.md#the-pipeline-is-a-query)).
+
+## Reference
+
+| API                                                 | Description                                                                             |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `class R extends Relationship {}`                   | Declare a relationship component with a `target: Entity` field.                         |
+| `e.set(R, { target })`                              | Create or retarget the relationship.                                                    |
+| `e.target(R)`                                       | The target entity through relationship `R`, or `undefined`.                             |
+| `e.children(R)`                                     | `ReadonlySet<Entity>` of sources targeting `e` through `R`.                             |
+| `e.childOf(parent)`                                 | Shorthand for `e.set(ChildOf, { target: parent })`.                                     |
+| `e.parent` / `e.parent = p`                         | Getter/setter for the built-in `ChildOf` target; setting `undefined` removes `ChildOf`. |
+| `meta.onDeleteTarget`                               | `Remove` (default) or `Delete` cascade when a target is destroyed.                      |
+| `world.component(R).add(Traversable)`               | Enable depth tracking for `cascade` ordering.                                           |
+| `{ target: [R, q] }` / `{ parent: q }`              | Reactive DSL operators through the relationship.                                        |
+| `{ source: [R, q] }` / `{ children: q }`            | Filter-only DSL operators down the reverse index.                                       |
+| `{ target: [R, [C...]] }` / `{ down: [R, [C...]] }` | Injection markers; see [Systems](./systems.md#relationship-injection-target-and-down).  |