@vworlds/vecs 1.0.25 → 1.0.26

package/docs/components.md

@@ -0,0 +1,267 @@
+# Components
+
+Define plain-data components, register them with the world, and configure their lifecycle: hooks,
+exclusivity, cleanup policies, interface aliases, and singletons.
+
+## Components are plain data classes
+
+A component is an ordinary class with field initializers and a no-argument constructor. It does
+not inherit from a vecs base class — vecs instantiates it with `new ComponentClass()`:
+
+```ts
+class Position {
+  x = 0;
+  y = 0;
+}
+```
+
+| Rule                      | Description                                                                                                                   |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Plain class               | Ordinary classes with field initializers; methods are allowed but behavior belongs in systems.                                |
+| No-arg construction       | vecs calls `new ComponentClass()`; omit the constructor or take no parameters.                                                |
+| Explicit registration     | Call `world.component(C)` before using the class as a component anywhere.                                                     |
+| Shared instances possible | `entity.attach(instance)` stores the exact passed object (see [Entities](./entities.md#attach-storing-an-existing-instance)). |
+| Manual dirty marking      | After mutating fields directly, call `entity.modified(C)` so hooks, queries, and systems react.                               |
+
+Keep components small and single-purpose — `Position {x,y}` and `Rotation {angle}`, not a
+`Transform` god-component. Absence of a component encodes "not applicable", and small components
+compose into precise queries. The reasoning is developed in the
+[Design guide](./design-guide.md#3-components).
+
+## Registration: `world.component`
+
+Register every component class before using it in `add`, `set`, `get`, `with`, `filter`, hook
+registration, or `setExclusiveComponents`. Registration can happen at any time:
+
+```ts
+// Auto-assigned component id (drawn from the "component" id pool, 1–899 by default):
+const positionComponent = world.component(Position);
+
+// Explicit numeric id (e.g. a server-assigned stable id):
+world.component(Position, 42);
+
+// Access component metadata (numeric id, cleanup policy, usage count, …):
+const meta = world.component(Position).meta;
+
+// Name the component entity, then resolve it by string later:
+world.component(Position).name = "Position";
+world.component("Position"); // returns the same Component entity
+```
+
+`world.component(Class)` (`lib/vecs/src/world/world.components.ts`) returns the **`Component`
+entity** for that class, creating and registering it on the first call. Subsequent calls with the
+same class return the same entity. The same class can be registered independently in multiple
+worlds — metadata is world-specific. Passing an explicit id for an already-registered class (with
+a different id) throws, as does passing a name with no matching component entity.
+
+### Id pools
+
+Entity ids are drawn from configurable pools. The defaults
+(`DEFAULT_POOLS` in `lib/vecs/src/world/world.pools.ts`):
+
+| Pool        | Range     | Used by           |
+| ----------- | --------- | ----------------- |
+| `component` | 1 – 899   | `world.component` |
+| `module`    | 900 – 999 | `world.module`    |
+| `entity`    | 1000 – ∞  | `world.entity()`  |
+
+Pass `idPools` to the `World` constructor to change ranges (each entry is an `IdPoolConfig` with
+`name`, `min`, optional `max`, and optional `reuseWaitFrames`). Freed ids wait
+`reuseWaitFrames` frames (default `DEFAULT_ID_REUSE_WAIT_FRAMES = 16`) before reuse, so an id
+released this frame is not immediately recycled. `world.peekNextEid(poolName)` returns the next id
+a pool would allocate without reserving it. Id 0 is reserved.
+
+## Hooks: `onAdd`, `onSet`, `onRemove`
+
+The `Component` entity exposes lifecycle hooks fired for every entity carrying the component:
+
+```ts
+world
+  .component(Sprite)
+  .onAdd((entity, sprite) => sprite.initialize(scene, entity))
+  .onSet((entity, sprite) => sprite.syncToScene(entity))
+  .onRemove((entity, sprite) => sprite.destroy(scene, entity));
+```
+
+| Hook       | Fires when…                                                                                                                                    |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onAdd`    | The component is first attached (`add`, or `set` on an entity that lacked it).                                                                 |
+| `onSet`    | `entity.set(C, props)` applies data, `entity.attach(instance)` stores an instance, `entity.modified(C)` is called, or `getMut` marks it dirty. |
+| `onRemove` | The component is detached (`entity.remove(C)`), or the owning entity is destroyed.                                                             |
+
+Handlers receive `(entity, componentInstance)` — component instances do not carry entity
+references, so the entity is passed explicitly. Hooks fire synchronously when the corresponding
+command is applied (see [Execution model](./execution-model.md#reactive-routing)). Use hooks for
+resource management and cross-cutting reactions that aren't worth a system; use systems when the
+reaction belongs to a phase.
+
+## Exclusive component groups
+
+`world.setExclusiveComponents(A, B, C)` declares a mutually exclusive group: setting one
+automatically removes the others first.
+
+```ts
+world.setExclusiveComponents(Walking, Running, Idle);
+
+const e = world.entity();
+e.add(Walking);
+e.add(Running); // Walking is removed first
+```
+
+Each call defines one independent group. A component belongs to at most one group; calling
+`setExclusiveComponents` again with the same class overwrites its group membership. Safe to call
+at any time. Exclusivity is how you model "exactly one of N" (one renderable per entity, one
+physics shape per body) — and it makes type swaps clean, because replacing the component fires the
+old one's `exit`/`onRemove` automatically.
+
+## Cleanup policies: destroying a component entity
+
+Every component key is backed by a component entity. What happens when you destroy that entity
+while other entities still carry the component is controlled by `meta.onDelete`
+(`CleanupPolicy` in `lib/vecs/src/component_meta.ts`):
+
+| Policy                 | Meaning                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `CleanupPolicy.Throw`  | Default. Destroying the component entity while other entities carry it throws and changes nothing. |
+| `CleanupPolicy.Remove` | Remove the component from every carrier, then destroy the component entity.                        |
+| `CleanupPolicy.Delete` | Destroy every carrier entity, then destroy the component entity.                                   |
+
+```ts
+import { CleanupPolicy } from "@vworlds/vecs";
+
+world.component(Temporary).meta.onDelete = CleanupPolicy.Remove;
+world.component(Temporary).destroy(); // strips Temporary from all carriers
+```
+
+The `Throw` default also applies to plain entities used as component keys (`entity.add(keyEntity)`).
+A failed destroy leaves the component entity, its carriers, and the usage count untouched.
+
+Relationship components have a second, independent policy — `meta.onDeleteTarget` — that governs
+what happens to _sources_ when a relationship **target** is destroyed. See
+[Relationships](./relationships.md#cleanup-when-a-target-dies).
+
+## Interface aliases with `Implements`
+
+Use the built-in `Implements` component when one concrete component should be queryable through
+abstract parent or interface component types. The concrete component stays the single source of
+truth; vecs stores the same instance under each alias, so `get(Parent) === get(Concrete)`:
+
+```ts
+import { Implements, World } from "@vworlds/vecs";
+
+abstract class Food {
+  calories = 0;
+}
+
+abstract class Fruit extends Food {
+  color = "";
+}
+
+class Orange extends Fruit {
+  acidity = 8;
+}
+
+const world = new World();
+world.component(Food);
+world.component(Fruit).set(Implements, { interfaces: [Food] });
+world.component(Orange).set(Implements, { interfaces: [Fruit] });
+
+const orange = world.entity().set(Orange, { calories: 7 });
+
+orange.get(Food) === orange.get(Orange); // true
+orange.has(Fruit); // true
+
+world
+  .query("foods")
+  .with(Food)
+  .forEach([Food], (_entity, [food]) => {
+    food.calories; // Orange data, read through the Food alias
+  });
+```
+
+Rules (enforced by `ImplementsModule`, `lib/vecs/src/modules/implements.ts`):
+
+- **Aliases are read/query only.** `get`, `has`, `with`, `filter`, and injection accept an
+  interface type; mutation must go through the concrete component. `add`, `set`, `remove`,
+  `modified`, `getMut`, and `attach` on an interface throw at runtime (and `add`/`set` are
+  rejected by TypeScript for abstract classes).
+- **Declarations are transitive.** `Orange` implements `Fruit`, `Fruit` implements `Food`, so an
+  entity with `Orange` matches `with(Food)`. Cyclic declarations throw.
+- **One implementer per interface per entity.** Setting a second concrete component that
+  implements the same interface evicts the first concrete component and all of its aliases.
+- Relationship components cannot be implementers or interfaces.
+
+## Singletons and world-global data
+
+Tag a component class with `Singleton` to enforce that at most one entity holds it:
+
+```ts
+import { Singleton } from "@vworlds/vecs";
+
+world.component(Gravity).add(Singleton); // adding Gravity to a second entity now throws
+```
+
+For world-global state, store the component **on its own component entity** with the `world.get` /
+`world.set` shorthand:
+
+```ts
+world.set(Gravity, { y: -9.8 }); // world.component(Gravity).set(Gravity, {...})
+world.get(Gravity)?.y; // world.component(Gravity).get(Gravity)
+```
+
+`SingletonModule` enforces the constraint (`lib/vecs/src/modules/singleton.ts`); see
+[Modules](./modules.md#built-in-modules).
+
+## Companion components for non-ECS resources
+
+To attach a non-ECS resource (a renderer object, a WASM handle, a DOM node) to an entity, wrap it
+in a local component instead of keeping a side `Map<eid, resource>`:
+
+```ts
+class VGameObject {
+  obj!: Phaser.GameObjects.GameObject;
+}
+
+world.component(VGameObject).onRemove((_entity, vgo) => vgo.obj.destroy());
+```
+
+The entity's component set then _is_ the resource lifecycle: queries drive create/destroy, and
+`onRemove` releases the resource whether the component is removed explicitly or the entity is
+destroyed. The full pattern — including create/update/teardown phase placement — is in the
+[Design guide](./design-guide.md#7-patterns-reach-for-these).
+
+## Reference
+
+### `World` component methods (`lib/vecs/src/world/world.components.ts`)
+
+| Method                               | Description                                                                                        |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `component(Class, ceid?)`            | Register or look up the `Component` entity for `Class`; optional explicit numeric id.              |
+| `component(name)`                    | Resolve an already-registered component entity by its `name`. Throws if absent or not a component. |
+| `get(Class)`                         | Singleton read: `component(Class).get(Class)`.                                                     |
+| `set(Class, props)`                  | Singleton write: `component(Class).set(Class, props)`.                                             |
+| `setExclusiveComponents(...classes)` | Declare one mutually exclusive group.                                                              |
+
+### `Component` entity (`lib/vecs/src/component.ts`)
+
+A `Component<T>` is an `Entity` subclass, so the full [entity API](./entities.md#reference)
+applies. On top of it:
+
+| Member              | Description                                                      |
+| ------------------- | ---------------------------------------------------------------- |
+| `onAdd(handler)`    | Register an add hook. Returns the component entity for chaining. |
+| `onRemove(handler)` | Register a remove hook.                                          |
+| `onSet(handler)`    | Register a set/modified hook.                                    |
+| `meta`              | The `ComponentMeta` bookkeeping record.                          |
+
+### `ComponentMeta` (`lib/vecs/src/component_meta.ts`)
+
+| Field            | Description                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------- |
+| `Class`          | The component class constructor.                                                              |
+| `eid`            | Component entity id assigned at registration.                                                 |
+| `bitPtr`         | Pre-computed bit pointer into entity archetype bitsets.                                       |
+| `isRelationship` | `true` when the class extends `Relationship`.                                                 |
+| `onDelete`       | `CleanupPolicy` applied to carriers when the component entity is destroyed. Default `Throw`.  |
+| `onDeleteTarget` | `CleanupPolicy` applied to sources when a relationship target is destroyed. Default `Remove`. |
+| `usageCount`     | Number of entities currently carrying this component.                                         |

package/docs/concepts.md

@@ -0,0 +1,86 @@
+# Concepts
+
+The vecs mental model: what the pieces are, how they relate, and the one rule that makes the rest
+fall into place.
+
+## The golden rule
+
+Components are **data**, systems are **behavior**, and **lifecycle is driven by the presence and
+change of components — not by imperative bookkeeping**. You do not call `start()` on things or keep
+side maps of what exists; you attach and remove components, and reactive systems respond. Nearly
+every idiom in the [Design guide](./design-guide.md) is a consequence of taking this seriously.
+
+## The pieces
+
+| Concept                  | What it is                                                                                                  |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| **World**                | Central container. Owns every entity, registered component, query, system, and the flat system pipeline.    |
+| **Entity**               | A numeric id (`eid`) with a set of components attached. Created via the world.                              |
+| **Component**            | A registered plain data class with a no-argument constructor. No behavior.                                  |
+| **System**               | A `Query` plus per-tick logic (`update`, `each`, `run`), assigned to one pipeline phase.                    |
+| **Query**                | A reactive, always-up-to-date set of entities matching a predicate, with `enter`/`exit`/`update` callbacks. |
+| **Filter**               | A non-reactive, one-shot scan: walks all world entities on each `forEach` call.                             |
+| **Hook**                 | Lightweight `onAdd` / `onRemove` / `onSet` callbacks registered per component class.                        |
+| **Phase**                | Marker component for entities used as pipeline ordering anchors.                                            |
+| **Relationship**         | A component whose `target` field points at another entity, with reverse lookup and cleanup cascades.        |
+| **Module**               | A unit of packaging: a class whose `init()` registers components, systems, phases, and policy.              |
+| **Exclusive components** | A group of components where at most one may exist on any entity at a time.                                  |
+| **Implements**           | Declares abstract/interface component aliases for a concrete component, for polymorphic queries.            |
+
+## Data vs. behavior
+
+A component is a bag of fields:
+
+```ts
+class Position {
+  x = 0;
+  y = 0;
+}
+```
+
+It carries no methods that act on the world, no reference to its entity, and no lifecycle of its
+own. All behavior lives in systems (and, for small cross-cutting reactions, in hooks). This split
+is what makes composition work: any system can operate on any entity that happens to carry the
+right components, and adding a capability to an entity is just adding a component.
+
+Prefer many small, single-purpose components over one large one. An entity that never rotates
+simply omits `Rotation`; absence encodes "not applicable". See
+[Components](./components.md).
+
+## How a tick works, in brief
+
+```text
+world.component(C) / world.system(name) / world.query(name)  ×  N
+        ↓
+world.progress(now, delta)   — once per frame
+```
+
+`world.progress` runs every system in phase order. Inside a system body the world is **deferred**:
+entity mutations are queued, then flushed after the system finishes, which routes `enter` /
+`update` / `exit` events into the queries and systems that care. Newly created systems are inserted
+into the pipeline the next time `progress` runs; standalone queries backfill already-matching
+entities when they are built. The full story — phase taxonomy, ordering guarantees, flush
+boundaries — is in [Execution model](./execution-model.md).
+
+## Lifecycle is component presence
+
+Because queries react to component presence and change, the component set _is_ the lifecycle:
+
+- "This entity is renderable" — it has a renderable component; the render system's `enter` fires.
+- "This resource must be released" — remove its component (or destroy the entity); `onRemove`
+  fires.
+- "This value changed" — `set`/`modified` fires `onSet` hooks and `update` callbacks.
+
+So instead of factories, registries, and `Map<eid, resource>` side tables, you write systems gated
+on component combinations. The canonical example is the companion-component pattern in the
+[Design guide](./design-guide.md#7-patterns-reach-for-these).
+
+## Where each topic lives
+
+- Registering, configuring, and hooking components → [Components](./components.md)
+- Creating, mutating, and destroying entities → [Entities](./entities.md)
+- System membership, callbacks, and cadence → [Systems](./systems.md)
+- The query DSL, live queries, filters, grouping → [Queries and filters](./queries-and-filters.md)
+- Entity-to-entity links and hierarchy → [Relationships](./relationships.md)
+- Packaging features → [Modules](./modules.md)
+- Terminology → [Glossary](./glossary.md)