@vworlds/vecs 1.0.50 → 1.0.51

package/README.md

@@ -59,6 +59,8 @@ world.progress(performance.now(), 16); // call once per frame
 
 ## Documentation
 
+For Node clients that need replicated Phaser poses, see [Headless clients](../vecs-phaser-client/README.md#headless-clients).
+
 The full documentation lives in [`docs/`](./docs/README.md). Recommended reading order:
 
 1. [Getting started](./docs/getting-started.md) — install to first ticking world.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.50",
+  "version": "1.0.51",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -27,12 +27,5 @@
     "type": "git",
     "url": "https://github.com/vworlds/vecs",
     "directory": "lib/vecs"
-  },
-  "lint-staged": {
-    "*.ts": [
-      "prettier --write",
-      "eslint --fix"
-    ],
-    "*.md": "prettier --write"
   }
 }

package/docs/README.md

@@ -36,6 +36,8 @@ Keep the [Glossary](./glossary.md) at hand for terminology.
 
 ## Map
 
+For Node clients that need replicated Phaser poses, see [Headless clients](../../vecs-phaser-client/README.md#headless-clients).
+
 | Guide                                              | Covers                                                                                       |
 | -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | [getting-started.md](./getting-started.md)         | A runnable tutorial from `npm install` to a ticking world.                                   |
@@ -57,6 +59,8 @@ sessions, and the client world) lives in the `@vworlds/vecs-wire`, `@vworlds/vec
 `@vworlds/vecs-server`, and `@vworlds/vecs-client` packages:
 
 - [Remote procedure calls](../../vecs-protocol/docs/rpc.md) — the call channel and typed errors.
+- [State diffs](../../vecs-protocol/docs/state-diffs.md) — what a diff carries, the order a client
+  applies it in, and how a reused entity id stays unambiguous.
 - [Sessions and caller context](../../vecs-server/docs/sessions.md) — per-connection RPC context,
   `closeSession`, and exactly-once teardown.
 - [Client world](../../vecs-client/docs/client-world.md) — replication, render time,

package/docs/components.md

@@ -73,7 +73,15 @@ released this frame is not immediately recycled. A frame is one `beginFrame()`,
 `progress()`; a wait of `0` frees the id at once. Once the wait is over, allocation hands out free
 ids before never-used ones, lowest first, so a released id is recycled by one of the next entities
 created. A `ClientWorld` sets the wait to `0` for the ids of replicated entities and keeps the
-default for its local ones. A recycled id is why a stored id is not a safe link between entities
+default for its local ones. A `ServerWorld` allocates its replicated entities from the `entity` pool,
+and holds a freed id for at least `historyFrames + 1` frames (65 by default) whatever the wait
+asks for, so the frame that removed an entity has left every session's history before its id comes
+back (see [Reusing entity ids](../../vecs-server/docs/sessions.md#reusing-entity-ids)). The
+`networkEntityReuseWaitFrames` option of the networked worlds sets the wait of the pool that holds
+the replicated entities: `entity` for a server, `network_entity` for a client. A diff that removes
+an entity and snapshots a new one under the same id is read in a fixed order, which is how a client
+tells the two apart (see [State diffs](../../vecs-protocol/docs/state-diffs.md)). A recycled id is
+why a stored id is not a safe link between entities
 (see [Link with edges, not stored ids](./relationships.md#link-with-edges-not-stored-ids)).
 `world.peekNextEid(poolName)` returns the next id a pool would allocate without reserving it. Id 0
 is reserved.
@@ -155,6 +163,7 @@ world.component(Orange).set(Implements, { interfaces: [Fruit] });
 | `Traversable`     | Exclusive relationships                      | Maintains hierarchy depth for cascade ordering                               |
 | `OwnedTarget`     | Exclusive relationships other than `ChildOf` | Owns each explicit target through `ChildOf` and destructive edge replacement |
 | `OneOf`           | Relationships                                | Constrains each target to be a direct `ChildOf` child of a declared parent   |
+| `With`            | A component and a target of the same kind    | Adding the component also adds the target (the same targets, for edges)      |
 
 Traits declare policy; their built-in modules install the hooks and maintain the metadata that
 enforce it. Configure traits in feature-module setup rather than opportunistically inside systems.
@@ -168,6 +177,11 @@ Do not assume all traits have the same lifecycle:
   `ChildOf` child of the declared parent.
 - `Traversable` backfills existing relationship instances.
 - Setting or removing `Implements` recomputes interface aliases.
+- Add `With` before the component is in use, as `world.component(X).add(With, world.component(Y))`.
+  It is irrevocable, both must be plain components or both relationships, and it only brings `Y`
+  along: an existing `Y` is left as it is, and removing `X` does not remove `Y`. On a `ClientWorld`,
+  a network removal of `Y` is skipped while `X` is on the entity (see
+  [Applying a frame](../../vecs-client/docs/client-world.md#applying-a-frame)).
 
 Treat traits as setup policy unless their documentation explicitly supports runtime changes. Before
 writing custom component-type bookkeeping, check whether an existing trait already expresses the

package/docs/design-guide.md

@@ -177,6 +177,7 @@ world.component(Orange).set(Implements, { interfaces: [Fruit] });
 | `Traversable`     | An exclusive relationship hierarchy needs depth or cascade ordering                |
 | `OwnedTarget`     | An exclusive relationship owns its explicitly added target                         |
 | `OneOf`           | A relationship's targets must be direct children of a declared parent (enum-style) |
+| `With`            | Adding one component should bring another along, as a companion it does not own    |
 
 Traits declare policy; modules implement it through hooks and metadata. Configure them in module
 setup, not inside systems. Lifecycle differs by trait: `OwnedTarget` and `Singleton` are setup-time
@@ -184,6 +185,18 @@ policy, `Traversable` backfills, and `Implements` recomputes declarations. Do no
 dynamically removable. See the [Components guide](./components.md#component-traits-policy-on-component-entities)
 for the full model and custom-trait guidance.
 
+`With` is a pair-form trait: `world.component(Motion).add(With, world.component(Position))` adds a
+`Position` whenever a `Motion` is added. It only brings the companion along: removing `Motion` does
+not remove `Position`, and a `Position` the entity already holds is left as it is. A networked
+client has one more rule, because the server decides what a client replicates but the client decides
+what it derives. **`ClientWorld.apply` skips a network removal of a component that another
+component present on the entity brings through `With`**, so a server can swap the source of a
+client-local component in one diff, say a streamed `Position` for a dead-reckoned `Motion`, and the
+entity never goes without it: no `remove` hook fires, and the queries and `DrawBy` children that
+match on it never see it leave. A bringer that the same diff sets counts as present. The entity-destroy
+path is unaffected, and a relationship is removed as sent (see
+[Applying a frame](../../vecs-client/docs/client-world.md#applying-a-frame)).
+
 ### Exclusive component groups
 
 `world.setExclusiveComponents(A, B, C)` declares a mutually exclusive set: setting one
@@ -269,6 +282,23 @@ classes or DSL objects (`{ all: [...] }`, `{ any: [...] }`, `{ parent: X }`, `{
 > `.with(...)`, `.without(...)`, and `.update(C)` own membership. `.update(C)` watches change events
 > and also requires `C`, so `.with(A).update(C)` matches entities carrying both `A` and `C`.
 
+**`.without` is not free.** `.without(X)` is `.with({ not: X })`: a `not` term holds every live
+entity that lacks `X`, a world-sized set, and the query intersects it with its positive terms. The
+exclusion does not run over the positive terms' candidates. Vecs seeds that set with one scan of
+the world when the term is first built, then adds each new entity to it, removes each destroyed
+entity from it, and flips an entity in or out when `X` is added to it or removed from it. Changes
+to `X`'s data cost nothing. The term is shared by every query that excludes the same `X`, so the
+upkeep is paid once per distinct exclusion, plus one membership check per query that uses it.
+
+- Add `.without(X)` only when the exclusion is needed, and put positive terms next to it: they keep
+  the query's members and callbacks small. A query made only of `.without` terms tracks every
+  entity in the world.
+- The creation pattern `.with(NewShape).without(Phaser.GameObjects.NewKind).enter(...)` relies on
+  that narrowing. The positive term limits the members to the few entities that just got
+  `NewShape`, while the exclusion keeps those that already have a display object from entering.
+
+Details: [Queries and filters](./queries-and-filters.md#the-cost-of-not-and-without).
+
 ### Reactive callbacks: `enter` / `update` / `exit`
 
 - **`enter`** — fires once when an entity _becomes_ a member. Use it for one-time setup
@@ -282,6 +312,14 @@ classes or DSL objects (`{ all: [...] }`, `{ any: [...] }`, `{ parent: X }`, `{
   Its injected components are read from a **snapshot captured at exit time**, so they're still
   resolvable even though they're being removed.
 
+**Repeated writes in one tick.** Vecs never merges `update` events, so a callback fires once per
+routed write. `entity.modified(C)` and `entity.getMut(C)` coalesce through the entity's dirty bit:
+repeated calls before the queued command drains give one `update`. Each `entity.set(C, …)` queues
+its own command and routes its own `update`, so three `set` calls give three callbacks. Write in
+place plus `modified` (or `getMut`) to get one callback per tick, or compare before `set`. When
+producers already use `modified`/`getMut`, do not add a defensive per-tick dedupe or batching layer
+on the consumer side. See [Systems](./systems.md#repeated-writes-in-one-tick).
+
 Choose `onEnter: true` by asking who owns the initial value:
 
 - Use **`onEnter: true`** for projection / sync callbacks: copying ECS data into a runtime object,
@@ -339,7 +377,8 @@ Components listed in the inject tuple but **not** guaranteed by `.with(...)` res
 ### `each` vs reactive — don't scan when you can react
 
 - **`.each([...], cb)`** iterates **every matching entity every tick**. Use it only when you
-  genuinely need a per-frame sweep over all members.
+  genuinely need a per-frame sweep over all members. An `.each` must justify running every tick: a
+  body that returns early for most members is a reactive system or a narrower query in disguise.
 - **Reactive `enter`/`update`/`exit`** fire only on change. For "copy A→B when A changes,"
   reactive `.update(A)` touches _nothing_ on idle entities, where `.each` would scan them all.
 
@@ -351,6 +390,28 @@ Components listed in the inject tuple but **not** guaranteed by `.with(...)` res
 .with(PhysicsPosition, RenderPosition).update(PhysicsPosition, (e, p) => e.set(RenderPosition, { x: p.x, y: p.y }));
 ```
 
+When the work really is per-tick (a held input, a cooldown, a charge), narrow the query with a tag
+or component that exists **only while the work is live**, instead of sweeping every candidate and
+returning early. A reactive `update` on the intent adds and removes the marker:
+
+```ts
+// ❌ visits every shooter every tick; most return at once
+.with(Weapon).each([Weapon], (e, [w]) => { if (!e.has(TriggerHeld)) return; /* fire */ });
+
+// ✅ the cadence system matches only entities that are firing right now
+world.system("TriggerIntent").with(Weapon).update(FireIntent, (e, intent) =>
+  intent.held ? e.add(Firing) : e.remove(Firing));
+world.system("Fire").with(Weapon, Firing).interval(0.1).each([Weapon], (e, [w]) => { /* fire */ });
+```
+
+For a countdown, do not write a bespoke "tick every timer" system over all entities. Vecs has no
+per-entity timer component: `interval`, `rate` and `tickSource` (see below) throttle _systems_.
+Model the window as an owned helper entity, an `Exclusive` + `OwnedTarget` relationship target that
+carries the deadline (see [Owned target entities](#owned-target-entities-entity-valued-properties)).
+Its presence is the window: an `.each` over the helper entities visits only open windows, and
+destroying a helper ends its window and removes the edge through the relationship's cleanup policy,
+so no remove hook or flag is needed.
+
 ### `run` and `interval`
 
 - **`.run(cb)`** — a system with no per-entity query; the body runs once per tick. For
@@ -853,10 +914,19 @@ system after whatever produces the entity/companion.
   [Pose Updates Fire Only When The Pose Changes](../../vecs-physics/docs/systems-and-phases.md#pose-updates-fire-only-when-the-pose-changes)).
 - **vecs-phaser-server: game code owns the physics pose; the render pose is protocol-private.** On
   the server, read and write the physics `Position` and `Rotation` of every entity, including one
-  without a `Body`. The render `Position` and `Rotation` and the dead-reckoning `Motion` are wire
-  encodings of that pose that only the sync systems write: a `DeadReckoned` body has no render pose
-  at all, and adding one throws (see
+  without a `Body`. The render `Position` and `Rotation` and the dead-reckoning `Motion` and
+  `MotionParams` are wire encodings of that pose that only the sync systems write: a `DeadReckoned`
+  body has no render pose at all, and adding one throws (see
   [Dead reckoning](../../vecs-phaser-server/README.md#dead-reckoning)).
+- **vecs-phaser-server: switch `DeadReckoned` on a change of state, and keep a constantly driven body
+  streamed.** The tag may be added or removed at any time, so a body can be dead reckoned while it
+  drifts and streamed while joints, thrust or a tow drive it (a driven body diverges from its
+  prediction every step and would cost a baseline of about 27 bytes per step against about 22 for a
+  streamed pose update). Toggle it when the state changes, not every frame: each switch costs a
+  baseline one way and a pose update the other, and clients blend the hand-off over `blendMs`. A
+  render pose or `Motion` created or switched late in a frame, in `PRE_STORE`, `ON_STORE` or an RPC
+  handler, is still synced from the physics pose before the frame is recorded (see
+  [Switching at runtime](../../vecs-phaser-server/README.md#switching-at-runtime)).
 - **vecs-client: attach a `ClientWorld` socket only after `socket.connect()` resolves,** so no ack
   precedes the data channel (`connectDgram` does this). Pending `invoke` calls reject with
   `RPC_CLOSED_CODE` on disconnect or `dispose` (see

package/docs/queries-and-filters.md

@@ -44,6 +44,31 @@ evaluates it against each entity pointing at the candidate and also matches when
 queries and systems. `target` / `parent` are fully reactive to edge changes and target-side changes
 — see [Relationships](./relationships.md#querying-through-relationships).
 
+### The cost of `not` and `.without`
+
+`.without(X)` is `.with({ not: X })` (`lib/vecs/src/query/query.ts`, `without`), and `.with` merges
+into `{ all: [...] }`. A `not` term is built from the world term plus `X`'s term and holds every live
+entity that lacks `X` (`lib/vecs/src/terms/not_term.ts`). It is a world-sized set, independent of
+the query's positive terms, and the `all` term intersects it with them.
+
+| Event                               | Effect on a `not X` term                                                      |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| Term built (first use)              | One scan of the whole world seeds the set (`term.ts`, `_initializeFromWorld`) |
+| Entity created or destroyed         | Added to or removed from the set (`world_term.ts`, `entityCreated`)           |
+| `X` added to or removed from entity | The entity leaves or re-enters the set                                        |
+| `X` data modified                   | Nothing (`not_term.ts`, `onTermRefresh` is a no-op)                           |
+
+Terms are cached by canonical key, so the upkeep is paid once per distinct exclusion, not once per
+query. Each query that uses it adds one membership check per change of the set, and the positive
+term comes first, so most checks stop there.
+
+- Use `.without` only when the exclusion is needed, and pair it with positive terms that keep the
+  query's members small. A query with only `.without` terms tracks every entity in the world, so
+  its `enter` fires for each created entity.
+- The creation pattern `.with(NewShape).without(Phaser.GameObjects.NewKind).enter(...)` depends on
+  this: the positive term limits the members, and the exclusion drops the few that already hold the
+  object.
+
 ### `QuerySpec`: adding `cascade` and `hint`
 
 Anywhere a DSL is accepted, you can pass the object form

package/docs/relationships.md

@@ -40,8 +40,9 @@ component field (`ownerEid = 0`, `target: Entity | undefined`). The world mainta
 cannot maintain a field:
 
 - **A stored eid can come to name another entity.** A destroyed entity's id is reused once its
-  pool's `reuseWaitFrames` have passed: 16 frames by default, and `0` for replicated entities on a
-  `ClientWorld` (see [Id pools](./components.md#id-pools)). Allocation hands out free ids before
+  pool's `reuseWaitFrames` have passed: 16 frames by default, `0` for replicated entities on a
+  `ClientWorld`, and at least `historyFrames + 1` on a `ServerWorld` (see
+  [Id pools](./components.md#id-pools)). Allocation hands out free ids before
   never-used ones, so one of the next entities created takes it. Until an entity does,
   `world.getEntity(id)` returns `undefined`; from then on it returns that live, unrelated entity and
   the stale id looks valid.

package/docs/systems.md

@@ -44,6 +44,7 @@ the full query DSL (operator semantics in
 .with({ parent: Body })                                   // ChildOf target has Body
 ```
 
+`.without` is not free: see [its cost](./queries-and-filters.md#the-cost-of-not-and-without).
 Multiple `with` calls merge with `all`. The `source` / `children` operators are non-reactive and
 rejected by systems — they are filter-only (see
 [Queries and filters](./queries-and-filters.md#filters-one-shot-scans)).
@@ -131,6 +132,25 @@ Use `.update(C, ...)` by itself when `C` is the membership shape and watched val
 A query or system can register only one `update(C, ...)` callback for each component. A duplicate
 registration throws instead of replacing the existing callback.
 
+#### Repeated writes in one tick
+
+Each routed write is one `update` event, and a system's inbox replays its events in arrival order
+without merging any (`lib/vecs/src/system.ts`, `_pushUpdate` and the drain loop in
+`_runDeferred`). What differs is how many events a write routes:
+
+| Write                      | Events routed for `C` in one drain window                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `entity.set(C, …)` × n     | n: every call queues its own command and fires its own `onSet` and `update`                      |
+| `entity.modified(C)` × n   | 1: the first call sets the dirty bit, the command clears it when it runs, later calls are no-ops |
+| `entity.getMut(C, cb)` × n | 1: it marks modified through the same dirty bit                                                  |
+
+Coalescing needs a queued command, so it applies to calls made while commands are deferred (inside
+system callbacks); outside them `modified` applies immediately. To get one callback per tick, write
+in place and call `modified` (or use `getMut`), or compare before `set` and skip equal values. Do
+not add a per-tick dedupe or batching step in the consumer when producers already use
+`modified`/`getMut`. Source: `lib/vecs/src/entity/entity.components.ts` (`_markModified`, `set`,
+`_notifyRaw`).
+
 ### `.exit(callback)` / `.exit(inject, callback)` / `.exit(options, callback)`
 
 Fires when an entity stops matching (component removed, or entity destroyed). Directly injected
@@ -149,7 +169,9 @@ object remain visible:
 ### `.each(components, callback)` / `.each(options, callback)`
 
 Fires every tick the system runs, once per tracked entity, regardless of change. Use it only for
-genuinely per-frame sweeps — when reacting to change suffices, prefer `update` (see
+genuinely per-frame sweeps — when reacting to change suffices, prefer `update`. An `.each` must
+justify running every tick, and when it does, narrow `.with(...)` to a tag that exists only while
+the work is live (see
 [Design guide](./design-guide.md#each-vs-reactive--dont-scan-when-you-can-react)):
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.50",
+  "version": "1.0.51",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -27,12 +27,5 @@
     "type": "git",
     "url": "https://github.com/vworlds/vecs",
     "directory": "lib/vecs"
-  },
-  "lint-staged": {
-    "*.ts": [
-      "prettier --write",
-      "eslint --fix"
-    ],
-    "*.md": "prettier --write"
   }
 }

package/skills/vecs/SKILL.md

@@ -40,6 +40,10 @@ Before implementing, identify:
 - The state represented by each component and whether absence has meaning.
 - Which component transition creates, updates, or removes related state or resources.
 - Whether the work should react through `enter`, `update`, or `exit` rather than scan every frame.
+  An `.each` must justify running every tick; when it does, narrow its query with a tag that exists
+  only while the work is live (for example a `Firing` tag that a reactive `update` on the intent
+  adds and removes) instead of looping over every candidate and returning early.
+  ([`each` vs reactive](../../docs/design-guide.md#each-vs-reactive--dont-scan-when-you-can-react))
 - Which phase owns the work and what earlier or later phase it must order against.
 - Whether a multi-target relationship, an `Exclusive` relationship, an explicitly created owned
   target, a grouped query, or an attached resource expresses the lifecycle better than imperative
@@ -73,6 +77,15 @@ other anti-patterns and pitfalls; each rule below links to the detail.
 - Do not call `getMut` per tick unless a change is intended. It marks the component modified even
   without a callback and even if nothing is written, which fires `update` watchers and replication.
   Read with `get`. ([`getMut`](../../docs/entities.md#getmut-and-ensure-mutating-in-place))
+- `.without(X)` does not filter the positive terms' candidates: it keeps a world-sized "not X" set,
+  updated on every entity create and destroy and every `X` add or remove, and intersects it with
+  them. Use it only when needed, after positive terms that keep the members small; a query with only
+  `.without` terms tracks the whole world.
+  ([Cost of `.without`](../../docs/queries-and-filters.md#the-cost-of-not-and-without))
+- `entity.modified(C)` and `getMut(C)` coalesce into one `update` per drain; every `entity.set(C, …)`
+  routes its own, and the system inbox never merges events. Write in place plus `modified`, or
+  compare before `set`, and do not add per-tick dedupe batches when producers use `modified`/`getMut`.
+  ([Repeated writes](../../docs/systems.md#repeated-writes-in-one-tick))
 - A system's `enter` reaches only entities still in its query when the system drains. An entity
   that left the query or died first gets neither `enter` nor the paired `exit`, and a re-entry
   within one drain gives `enter`, `exit`, `enter`, so keep setup and teardown symmetric.