@vworlds/vecs 1.0.43 → 1.0.44

package/docs/relationships.md

@@ -43,6 +43,56 @@ subclasses) explicitly in your `networkComponents` array to replicate parent-chi
 
 `entity.childOf(parent)` is shorthand for `entity.set(ChildOf, { target: parent })`.
 
+## Ensuring a target
+
+Use `ensureTarget` when a registered relationship should always have some target and a new,
+independent entity is the correct default:
+
+```ts
+world.component(FriendOf);
+
+const friend = entity.ensureTarget(FriendOf);
+entity.ensureTarget(FriendOf) === friend; // true
+entity.target(FriendOf) === friend; // true
+```
+
+The method returns the existing target when present. Otherwise it creates an entity, initializes
+the relationship with that target, and attaches the relationship. During deferred execution,
+repeated calls share one pending relationship and return the same target; `target(FriendOf)` still
+returns `undefined` until flush.
+
+The generated target is independent: `ensureTarget` does not add `ChildOf`, and destroying the
+source does not destroy the target. Add ownership explicitly when your model requires it. The
+relationship class must be registered before calling `ensureTarget`.
+
+## Owned targets
+
+Mark a relationship component with `OwnedTarget` during world setup when every target assigned
+through that relationship should become a `ChildOf` child of its source:
+
+```ts
+import { OwnedTarget, Relationship } from "@vworlds/vecs";
+
+class Inventory extends Relationship {}
+
+world.component(Inventory).add(OwnedTarget);
+
+const inventory = player.ensureTarget(Inventory);
+inventory.parent === player; // true
+
+player.destroy();
+inventory.destroyed === true; // ChildOf cascades deletion
+```
+
+`OwnedTarget` installs `onSet`, `onRetarget`, and `onRemove` hooks on `Inventory`. New targets become
+`ChildOf` children, displaced targets are destroyed on retarget, and the current target is destroyed
+when the relationship is removed (including source destruction). During deferred execution, these
+changes apply while the command queue drains.
+
+Configure the trait before creating relationship instances; it does not backfill existing targets.
+Do not share one owned target between several sources: retargeting or removing any owning
+relationship can destroy it. `OwnedTarget` rejects ordinary components and `ChildOf` itself.
+
 ## Retargeting
 
 Point a relationship somewhere else with a plain `set`:
@@ -60,6 +110,20 @@ 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`.
 
+Register `onRetarget` when behavior needs both targets:
+
+```ts
+world.component(InCell).onRetarget((entity, oldCell, newCell) => {
+  // entity.target(InCell) is newCell here.
+  // oldCell.children(InCell) no longer contains entity.
+  // newCell.children(InCell) already contains entity.
+});
+```
+
+It fires only when an existing relationship moves to a different existing target, after reverse
+indexes update and before `onSet`. Initial assignment, same-target writes, and removal do not fire
+`onRetarget`; use `onSet` and `onRemove` for those lifecycle points.
+
 ## Cleanup when a target dies
 
 What happens to sources when their target entity is destroyed is governed by the relationship's
@@ -138,16 +202,19 @@ the box — the world's default pipeline is itself a `cascade: DependsOn` 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).  |
+| 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.ensureTarget(R)`                                 | Return `R`'s target, creating an independent entity when absent.                         |
+| `world.component(R).add(OwnedTarget)`               | Make targets assigned through `R` into `ChildOf` children of their sources.              |
+| `world.component(R).onRetarget(handler)`            | React after `R` moves between existing targets; receives source, old target, new target. |
+| `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).   |

package/package.json

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

package/skills/vecs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: vecs
+description: "Designs, implements, reviews, and debugs games or applications using @vworlds/vecs. Use whenever a task creates or changes vecs components, entities, systems, queries, relationships, modules, phases, lifecycle, networked components, or ECS architecture."
+---
+
+# vecs Application Development
+
+Use the documentation shipped with the consuming project's installed `@vworlds/vecs` package.
+Those docs match the API version the project actually uses and are the source of truth for vecs
+design and behavior.
+
+## Before Working
+
+1. Locate `node_modules/@vworlds/vecs/docs/`. In a workspace or non-npm install, resolve the
+   installed `@vworlds/vecs` package and use its adjacent `docs/` directory.
+2. Read `docs/design-guide.md` sections 1, 2, 8, and 9 before designing or changing ECS behavior.
+3. Read the task-specific sections of that design guide:
+   - Components or replicated state: section 3.
+   - Systems or queries: section 4.
+   - Ordering or timing: section 5.
+   - Feature architecture: section 6.
+   - Lifecycle and synchronization patterns: section 7.
+4. Use `docs/README.md` to select any detailed subsystem guides needed by the task. Read
+   `docs/concepts.md` and `docs/execution-model.md` when the design depends on unfamiliar vecs
+   behavior.
+5. Inspect the consuming project's existing vecs modules and conventions before proposing a new
+   pattern.
+
+Do not rely on memory or a different vecs checkout when installed documentation is available.
+Confirm exact names and signatures against the installed declarations under
+`node_modules/@vworlds/vecs/dist/`.
+
+## Design From ECS Semantics
+
+Start from the vecs golden rule: components are data, systems are behavior, and component presence
+and change drive lifecycle.
+
+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.
+- Which phase owns the work and what earlier or later phase it must order against.
+- Whether an owned target, relationship, trait, grouped query, or attached resource expresses the
+  lifecycle better than imperative bookkeeping.
+- Whether the feature belongs in a `Module` that owns registration, systems, phases, and policy.
+
+Prefer the idioms in the installed design guide over generic ECS patterns. vecs execution details,
+including per-system flushes and reactive inbox routing, are part of the design model.
+
+## Avoid Generic Workarounds
+
+Check the design guide before introducing:
+
+- Side maps keyed by entity id.
+- Components containing behavior or broad god-components with optional sentinel fields.
+- Per-frame scans for changes that vecs can route reactively.
+- Manual lifecycle bookkeeping that duplicates component presence.
+- System registration order as a substitute for explicit cross-feature phase ordering.
+- Parallel object graphs that duplicate relationships already represented in the ECS.
+- Wrapper abstractions that hide normal vecs entities, components, systems, or modules without a
+  concrete need.
+
+If the requested design conflicts with a documented vecs invariant, explain the conflict and use
+the documented pattern unless the user explicitly chooses otherwise.
+
+## Implement And Verify
+
+1. Reuse existing components and modules where their semantics match; do not reuse them merely
+   because their fields look similar.
+2. Keep components small data classes and put behavior in systems or narrowly scoped lifecycle
+   hooks as directed by the guide.
+3. Express cross-feature ordering with phases. Treat same-phase registration order as a local
+   implementation detail unless the installed docs explicitly make it part of the design.
+4. Test lifecycle transitions, not only steady-state values: entry, mutation, removal, retargeting,
+   destruction, and same-tick visibility where relevant.
+5. Run the consuming project's typecheck and focused tests. Resolve API uncertainty from the
+   installed declarations and docs rather than guessing.
+
+For networking, physics, Phaser, client, or server integration, also inspect the README and
+declarations shipped with the corresponding `@vworlds/vecs-*` package.