@vworlds/vecs 1.0.53 → 1.0.55

package/docs/modules.md

@@ -34,6 +34,10 @@ world.module(PoseSyncModule);
 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.
+Install new modules outside `progress()` and `defer`; installation also throws during a command
+drain, before registering anything. Looking up an already installed module works in any of those
+contexts. Lazy loading from a system or hook is the application's job: schedule it after
+`progress()` returns.
 
 ## Configuration
 
@@ -84,6 +88,63 @@ Guidelines:
   placement, component registration. Keep that out of application code.
 - **One module per cohesive thing.** Don't pile unrelated features into one `init`.
 
+## Scopes and module provenance
+
+`world.scope(parent, fn)` assigns `ChildOf parent` to entities created **synchronously in its body**:
+plain entities, components, modules, query/system backing entities, and phases.
+Nested scopes restore the caller's parent in `finally`, even when the callback throws. Enter scopes
+outside deferred mode: `world.scope()` throws inside `progress()`, a `defer` block, or a command
+drain, without running the callback. Scoped creations use `.childOf(parent)` before their creation
+notification. Existing name/id/class lookups do not reparent anything. An explicit
+`.childOf(other)` afterwards replaces the scope parent, just as any other exclusive `ChildOf` edge.
+The parent must be live and belong to the same world. Async continuations are outside the scope.
+
+Entities created by callbacks that vecs runs deferred inside the body are **not parented**. This
+includes `query.forEach(cb)`, a query's `enter` backfill when built, and an explicit `world.defer`
+inside a module's `init`. Callback-created entities are run-time data: the same callback outside the
+scope would not parent them either. For example, a module's `enter` or `forEach` callback may create
+one health-bar entity per existing ship. Those health bars remain roots; an entity created directly
+in `init` is a child of the module.
+
+```ts
+import { Entity, Module, World } from "@vworlds/vecs";
+
+class Position {}
+class Feature extends Module {
+  public init(): void {
+    this.world.component(Position);
+    this.world.entity("camera");
+  }
+}
+const world = new World();
+const feature = world.module(Feature);
+world.component(Position).parent === feature; // true
+world.entity("camera").parent === feature; // true
+
+function owningModule(entity: Entity): Module | undefined {
+  const visited = new Set<Entity>();
+  for (let parent = entity.parent; parent && !visited.has(parent); parent = parent.parent) {
+    if (parent instanceof Module) return parent;
+    visited.add(parent);
+  }
+  return undefined;
+}
+owningModule(world.component(Position)); // feature
+world.scope(feature, () => world.entity("another child"));
+```
+
+`world.module()` runs a new module's `init` inside `world.scope(moduleEntity, ...)`. Nested modules
+are children of the enclosing scope; their own creations belong to the nested module. Provenance is
+the **nearest module ancestor**, not necessarily the direct parent: a `OneOf` value may be parented
+to its relationship entity, which is parented to the module. This is a real ownership hierarchy:
+ordinary parent destruction cascades through its children, and subtree traversal follows it.
+
+Vecs' own built-in modules installed by the `World` constructor are **not scoped**; their entities
+remain roots. Provenance covers modules installed after the world is constructed, including physics,
+network, Phaser and application modules. Registration outside a scope leaves a root. Idempotent
+re-registration keeps the existing parent: there is no list of duplicate registrars and no record of
+which module added a trait edge. Explicit reparenting changes ownership, not a historical audit.
+
 ## Built-in modules
 
 Every `World` constructor installs these (`lib/vecs/src/world/world.ts`); you interact with their
@@ -107,4 +168,5 @@ All are exported, so a custom world setup can reuse them.
 | `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).                                            |
+| `world.scope(parent, fn)`                                                      | Parent all synchronous creations in `fn`; existing lookups are unchanged.                           |
 | `ModuleConfig<T>`                                                              | Utility type extracting a module's config type.                                                     |

package/docs/systems.md

@@ -26,7 +26,48 @@ world
 
 Newly created systems enter the pipeline the next time `world.progress` runs. Configuration must
 happen before the system is built (the first `progress`/`flush` after creation); builder calls
-after that throw.
+after that throw. Reading `world.pipeline` between frames also builds pending queries.
+
+## Measuring systems
+
+Enable opt-in synchronous timing for benchmarks, cadence guards, or live diagnostics:
+
+```ts
+world.stats.enableSystems();
+world.progress(1000, 16);
+for (const { system, runs, totalMs, maxMs } of world.stats.systems()) {
+  console.log(system.name, runs, totalMs, maxMs);
+}
+world.stats.resetSystems(); // clear system and extension-operation totals
+world.stats.disableSystems(); // stop measuring; retain results until reset
+```
+
+Timing is off by default. `progress()` chooses the plain or instrumented loop once per tick;
+the plain loop has no per-system timing branch, counter, or clock read. The instrumented loop
+uses one `performance.now()` pair per pipeline entry and reuses first-seen slots.
+
+`systems()` returns independent snapshots in current pipeline order, including systems with zero
+runs. Each row holds the original `System`, not copied identity or cadence metadata. Newly
+registered systems appear after the next pipeline refresh in `progress()`. Removed systems are
+absent. Reading does not reset the totals.
+
+A run means execution admitted by the system's enabled and tick-source gates, not a callback or
+entity count: an idle reactive system or an empty `each` query still counts when due. Disabled
+and cadence-skipped entries contribute neither runs nor time. For an admitted execution, timing
+includes inbox processing, callbacks, and **the flush after that system**, including command
+routing and hooks. Initial frame preparation and final frame closure are not attributed. An
+execution that throws before completing its flush does not contribute a completed run.
+
+Extensions expose breakdown rows through `world.stats.operations()`, under the same switch and
+reset. See [ServerWorld replication timing](../../vecs-server/docs/replication-timing.md).
+Reading either table allocates snapshots; normal measured ticks reuse slots. Reset keeps slots
+and clears totals, including systems temporarily absent from the pipeline.
+
+When implementing a world extension, choose the measured path once per frame with
+`stats.systemsEnabled`, then call `stats.recordOperation(name, elapsedMs)` once per completed
+operation. It aggregates a finite, non-negative duration into a reusable named slot. This method
+does not read a clock or recheck the switch; it lets an already-measured frame complete even if
+a callback disables future timing. Invalid durations throw `RangeError`.
 
 ## Membership: `with` / `without`
 
@@ -389,7 +430,10 @@ world.system("Log").tickSource(clock).run(log); // driven by a shared ITickSourc
 ```
 
 - `.interval(seconds)` replaces the cadence with an `IntervalTickSource`. Note the unit: seconds,
-  unlike the millisecond deltas of `progress`.
+  unlike the millisecond deltas of `progress`. Interval boundaries tolerate floating-point
+  residue so whole-frame intervals do not fire one frame late (see `IntervalTickSource`'s
+  TSDoc for the tolerance). Each source fires at most once per frame, even with a large delta;
+  positive residual time is preserved, and a tolerated negative remainder is clamped to zero.
 - `.rate(n)` divides the current cadence source by `n` (for an unconfigured system: every `n`
   frames). `.rate(n, source)` divides an explicit upstream source.
 - `.tickSource(source)` mirrors another source directly — an `IntervalTickSource`,
@@ -420,6 +464,66 @@ ai.destroy(); // permanent: disables, then unregisters the backing entity
 While disabled, query membership is still maintained, so the tracked set is correct on resume.
 `destroy` fires no `exit` callbacks. Both `disable` and `enable` are idempotent and chainable.
 
+## Introspection
+
+Read `world.pipeline` after finishing system configuration to inspect the **existing flat execution
+pipeline**, not a separately maintained inventory. It returns `readonly System[]`, including disabled
+systems, in the order selected by the pipeline query (including a custom `setPipeline`). Between
+frames it builds pending queries and refreshes only when the pipeline query changed. It does not
+execute systems or drain deferred commands. During a frame it returns that frame's pipeline; queued
+changes become visible after their normal flush. Re-read the getter after changes: an old array is
+not a live subscription. Read-only means the TypeScript array API; do not cast away the type to mutate it.
+
+```ts
+import {
+  ALWAYS_TICK_SOURCE,
+  DependsOn,
+  IntervalTickSource,
+  RateTickSource,
+  System,
+  World,
+  type ITickSource,
+} from "@vworlds/vecs";
+
+function describeCadence(source: ITickSource): string {
+  if (source === ALWAYS_TICK_SOURCE) return "every tick";
+  if (source instanceof IntervalTickSource) return `every ${source.seconds}s`;
+  if (source instanceof RateTickSource) {
+    return `every ${source.rate} ticks of ${
+      source.source ? describeCadence(source.source) : "world frames"
+    }`;
+  }
+  if (source instanceof System) return `system ${source.name}`;
+  return "custom clock";
+}
+
+const world = new World();
+world
+  .system("AI")
+  .interval(0.5)
+  .run(() => {});
+for (const [order, system] of world.pipeline.entries()) {
+  console.log({
+    order,
+    name: system.name,
+    phase: system.entity.target(DependsOn)?.name,
+    cadence: describeCadence(system.cadence),
+    enabled: system.enabled,
+  });
+}
+```
+
+`system.cadence` exposes the current source; the existing `.tickSource(source)` method configures
+it. Compare cadence by identity with the exported `ALWAYS_TICK_SOURCE` for the default every-tick
+case. `IntervalTickSource.seconds`, `RateTickSource.rate`, and `RateTickSource.source` are getters;
+an unconfigured standalone rate source has no upstream source and counts world frames. Replacing
+cadence changes the getter immediately. A source's existing `start`/`stop` controls still work.
+
+Name and phase need no new API: `system.name` and `system.entity.target(DependsOn)` already expose
+them. Systems are entities carrying `System`, so a query with `System` can inventory them independently
+of pipeline membership; retrieve the instance with `entity.get(System)`. The existing `toString()`
+display is unchanged; introspection does not add structured query terms or `world.systems()`.
+
 ## Reference
 
 | Method                                                           | Description                                                                                                                      |
@@ -438,6 +542,8 @@ While disabled, query membership is still maintained, so the tracked set is corr
 | `disable()` / `enable()`                                         | Pause / resume processing. Idempotent.                                                                                           |
 | `destroy()`                                                      | Permanently remove the system (no `exit` callbacks).                                                                             |
 | `didTick` / `lastFireDelta`                                      | This frame's cadence result; ms accumulated into the last fire.                                                                  |
+| `cadence` / `enabled`                                            | Read current cadence source and enabled state; see [Introspection](#introspection).                                              |
+| `world.pipeline`                                                 | Read systems in pipeline execution order; see [Introspection](#introspection).                                                   |
 | `count` / `has(e)` / `belongs(e)` / iteration / `forEach`        | Shared query surface; see [Queries](./queries-and-filters.md#reading-a-query).                                                   |
 
 `groupBy` is not available on systems — use `world.query(...).groupBy(...)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.53",
+  "version": "1.0.55",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/tsconfig.types.json

@@ -1,4 +1,9 @@
 {
   "extends": "./tsconfig.json",
-  "include": ["src", "tests/clock-inject.test.ts"]
+  "include": [
+    "src",
+    "tests/clock-inject.test.ts",
+    "tests/world-scope.test.ts",
+    "tests/system-introspection.test.ts"
+  ]
 }