@vworlds/vecs 1.0.40 → 1.0.42

package/dist/filter.d.ts

@@ -70,12 +70,12 @@ export declare class Filter<R extends ComponentType[] = []> {
      * @param callback - Receives the entity and a tuple of resolved component
      *   instances.
      */
-    forEach<J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     /**
      * As above, but pass `{ cursor: Entity, inject: [...] }` to make the
      * entity-first signature explicit. Identical behavior to the array form.
      */
-    forEach<J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     /**
      * As above, but pass `{ cursor: Iter, inject: [...] }` to receive a reused
      * {@link Iter} cursor instead of the bare entity. The cursor exposes the
@@ -83,6 +83,6 @@ export declare class Filter<R extends ComponentType[] = []> {
      * resolved component was read from (the visited entity for direct components,
      * the relationship's target entity for ones injected via `target`).
      */
-    forEach<J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     private _forEachMatch;
 }

package/dist/package.json

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

package/dist/query/group.d.ts

@@ -11,8 +11,8 @@ export declare class Group<K = unknown, R extends ComponentType[] = []> {
     get count(): number;
     [Symbol.iterator](): IterableIterator<Entity>;
     forEach(callback: (e: Entity) => void): this;
-    forEach<J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
-    forEach<J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
-    forEach<J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     has(e: Entity): boolean;
 }

package/dist/query/query.d.ts

@@ -48,22 +48,22 @@ export declare class Query<R extends ComponentType[] = []> implements TermConsum
     belongs(e: Entity): boolean;
     has(e: Entity): boolean;
     forEach(callback: (e: Entity) => void): this;
-    forEach<J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
-    forEach<J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
-    forEach<J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    forEach<const J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     toString(): string;
     with<const S extends readonly QuerySpec[]>(...specs: [...S]): Query<[...R, ...ExtractSpecsRequired<S>]>;
     without(dsl: QueryDSL): this;
     track(): this;
-    orderBy<J extends InjectTuple>(components: readonly [...J], compare: (entityA: Entity, a: MaybeResolvedInjectTuple<J, R>, entityB: Entity, b: MaybeResolvedInjectTuple<J, R>) => number): this;
-    orderBy<J extends InjectTuple>(options: EntityCursorOption & OrderByOptions<J>, compare: (entityA: Entity, a: MaybeResolvedInjectTuple<J, R>, entityB: Entity, b: MaybeResolvedInjectTuple<J, R>) => number): this;
-    orderBy<J extends InjectTuple>(options: IterCursorOption & OrderByOptions<J>, compare: (a: Iter, aResolved: MaybeResolvedInjectTuple<J, R>, b: Iter, bResolved: MaybeResolvedInjectTuple<J, R>) => number): this;
+    orderBy<const J extends InjectTuple>(components: readonly [...J], compare: (entityA: Entity, a: MaybeResolvedInjectTuple<J, R>, entityB: Entity, b: MaybeResolvedInjectTuple<J, R>) => number): this;
+    orderBy<const J extends InjectTuple>(options: EntityCursorOption & OrderByOptions<J>, compare: (entityA: Entity, a: MaybeResolvedInjectTuple<J, R>, entityB: Entity, b: MaybeResolvedInjectTuple<J, R>) => number): this;
+    orderBy<const J extends InjectTuple>(options: IterCursorOption & OrderByOptions<J>, compare: (a: Iter, aResolved: MaybeResolvedInjectTuple<J, R>, b: Iter, bResolved: MaybeResolvedInjectTuple<J, R>) => number): this;
     cascade(rel: ComponentRef): this;
     cascade(options: CascadeOptions): this;
     cascade(rel: ComponentRef, compare: (a: Entity, b: Entity) => number): this;
     cascade(options: CascadeOptions, compare: (a: Entity, b: Entity) => number): this;
-    groupBy<K, J extends FanInjectTuple>(components: readonly [...J], key: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => K): GroupedQuery<K, R>;
-    groupBy<K, J extends FanInjectTuple>(options: GroupByOptions<J>, key: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => K): GroupedQuery<K, R>;
+    groupBy<K, const J extends FanInjectTuple>(components: readonly [...J], key: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => K): GroupedQuery<K, R>;
+    groupBy<K, const J extends FanInjectTuple>(options: GroupByOptions<J>, key: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => K): GroupedQuery<K, R>;
     groupBy(relationship: ComponentRef): GroupedQuery<Entity, R>;
     groupBy(options: {
         relationship: ComponentRef;
@@ -78,13 +78,13 @@ export declare class Query<R extends ComponentType[] = []> implements TermConsum
     set<C extends ComponentClass>(Class: C, props: Partial<InstanceType<C>>): this;
     set(ceid: EID, props: Partial<ComponentInstance>): this;
     set(entity: Entity, props: Partial<ComponentInstance>): this;
-    enter<J extends InjectTuple>(inject: readonly [...J], callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
-    enter<J extends InjectTuple>(options: EntityCursorOption & InjectCallbackOptions<J>, callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
-    enter<J extends InjectTuple>(options: IterCursorOption & InjectCallbackOptions<J>, callback: (it: Iter, injected: RequiredResolvedInjectTuple<J>) => void): this;
+    enter<const J extends InjectTuple>(inject: readonly [...J], callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
+    enter<const J extends InjectTuple>(options: EntityCursorOption & InjectCallbackOptions<J>, callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
+    enter<const J extends InjectTuple>(options: IterCursorOption & InjectCallbackOptions<J>, callback: (it: Iter, injected: RequiredResolvedInjectTuple<J>) => void): this;
     enter(callback: (e: Entity) => void): this;
-    exit<J extends InjectTuple>(inject: readonly [...J], callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
-    exit<J extends InjectTuple>(options: EntityCursorOption & InjectCallbackOptions<J>, callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
-    exit<J extends InjectTuple>(options: IterCursorOption & InjectCallbackOptions<J>, callback: (it: Iter, injected: RequiredResolvedInjectTuple<J>) => void): this;
+    exit<const J extends InjectTuple>(inject: readonly [...J], callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
+    exit<const J extends InjectTuple>(options: EntityCursorOption & InjectCallbackOptions<J>, callback: (e: Entity, injected: RequiredResolvedInjectTuple<J>) => void): this;
+    exit<const J extends InjectTuple>(options: IterCursorOption & InjectCallbackOptions<J>, callback: (it: Iter, injected: RequiredResolvedInjectTuple<J>) => void): this;
     exit(callback: (e: Entity) => void): this;
     /**
      * Register one update callback for a watched component.
@@ -105,10 +105,10 @@ export declare class Query<R extends ComponentType[] = []> implements TermConsum
      *   already has an update callback on this query.
      */
     update<C extends ComponentType>(ComponentClass: C, callback: (e: Entity, c: InstanceType<C>) => void): this;
-    update<C extends ComponentType, J extends InjectTuple>(options: EntityCursorOption & UpdateCallbackOptions<C, J> & {
+    update<C extends ComponentType, const J extends InjectTuple>(options: EntityCursorOption & UpdateCallbackOptions<C, J> & {
         inject: readonly [...J];
     }, callback: (e: Entity, c: InstanceType<C>, injected: MaybeResolvedInjectTuple<J, R>) => void): this;
-    update<C extends ComponentType, J extends InjectTuple>(options: IterCursorOption & UpdateCallbackOptions<C, J> & {
+    update<C extends ComponentType, const J extends InjectTuple>(options: IterCursorOption & UpdateCallbackOptions<C, J> & {
         inject: readonly [...J];
     }, callback: (it: Iter, c: InstanceType<C>, injected: MaybeResolvedInjectTuple<J, R>) => void): this;
     update<C extends ComponentType>(options: EntityCursorOption & UpdateCallbackOptions<C, []>, callback: (e: Entity, c: InstanceType<C>) => void): this;

package/dist/system.d.ts

@@ -165,12 +165,12 @@ export declare class System<R extends ComponentType[] = []> extends Query<R> imp
      *   });
      * ```
      */
-    each<J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    each<const J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     /**
      * As above, but pass `{ cursor: Entity, inject: [...] }` to make the
      * entity-first signature explicit. Identical behavior to the array form.
      */
-    each<J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    each<const J extends FanInjectTuple>(options: EntityCursorOption & FanInjectCallbackOptions<J>, callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     /**
      * As above, but pass `{ cursor: Iter, inject: [...] }` to receive a reused
      * {@link Iter} cursor instead of the bare entity. The cursor exposes the
@@ -178,7 +178,7 @@ export declare class System<R extends ComponentType[] = []> extends Query<R> imp
      * resolved component was read from (the visited entity for direct components,
      * the relationship target for `target`-injected ones).
      */
-    each<J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    each<const J extends FanInjectTuple>(options: IterCursorOption & FanInjectCallbackOptions<J>, callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     /**
      * Add entity-membership predicates using {@link QuerySpec} expressions.
      *

package/docs/README.md

@@ -46,5 +46,5 @@ Keep the [Glossary](./glossary.md) at hand for terminology.
 | [utilities.md](./utilities.md)                     | Public helper classes: `Events`, `ArrayMap`, `IterableArrayMap`, plus `Bitset` cross-ref.    |
 | [glossary.md](./glossary.md)                       | ECS and vecs terminology.                                                                    |
 
-Networking (wire encoding with `@type`, protocol component ordering, replication) lives in the
+Networking (wire encoding with `@wireType`, protocol component ordering, replication) lives in the
 `@vworlds/vecs-wire` and `@vworlds/vecs-protocol` packages and is only cross-referenced here.

package/docs/design-guide.md

@@ -102,9 +102,8 @@ export class Rotation {
 
 ### Networked components
 
-Mark wire fields with `@type` from `@vworlds/vecs-wire` (conventionally imported as
-`import { type as wireType }`). The
-**order** you pass components in `networkComponents` _is the wire protocol_ (type id = index + 1).
+Mark wire fields with `@wireType` from `@vworlds/vecs-wire` (`import { wireType }`). The
+**order** you pass components in `networkComponents` _is the wire protocol_ (wire type id = index + 1).
 Reordering is a breaking protocol change — snapshot-test the order.
 
 ```ts
@@ -114,7 +113,7 @@ class Arc {
 new ServerWorld({ networkComponents: [Position, Rotation, /* … */ Arc] });
 ```
 
-> **Decorator gotcha.** `@type` must work under both _legacy_ (`experimentalDecorators`, used by
+> **Decorator gotcha.** `@wireType` must work under both _legacy_ (`experimentalDecorators`, used by
 > `tsc`) and _standard_ TC39 decorators (what esbuild — `tsx`/Vite — emits for source files).
 > If you load decorated component classes from **source** through an esbuild-based runtime and
 > their fields silently fail to register, that's the standard-vs-legacy mismatch. vecs-wire
@@ -179,8 +178,15 @@ entity.target(InCell); // the target entity
 world.query("ByCell").with(Networked, Position).groupBy(InCell); // index by target
 ```
 
-- **`Relationship.target` is an `Entity` — not serializable, so relationships are not
-  networkable.** Don't try to replicate them.
+- **`Relationship.target` is an `Entity` — not directly serialisable, but
+  relationships can be networked** when listed in `networkComponents`.
+  `vecs-protocol` registers `Relationship.prototype.target` as an `"entity"`
+  wire field (u32 eid), so subclasses serialise their target as a raw entity
+  id. The client resolves the id to a live entity (creating a ghost
+  placeholder if the parent hasn't arrived yet). Use a dedicated relationship
+  class per concern — e.g. `ChildOf` for server-local ownership/lifecycle,
+  `DrawIn` (in vecs-phaser) for networked display hierarchy — so the two
+  concerns don't overload a single relationship.
 - **Retargeting is a plain data change** (no archetype churn). Prefer retargeting a relationship
   over swapping marker components to express "which bucket this entity is in."
 
@@ -547,18 +553,18 @@ system after whatever produces the entity/companion.
 
 ## 8. Anti-patterns (keep ECS semantics)
 
-| Smell                                                                  | Do instead                                                                                                                                           |
-| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A side `Map<eid, resource>`                                            | Store the resource in a **companion component**; let queries drive its lifecycle; release in `onRemove`.                                             |
-| An imperative runtime object with `start()/stop()/track/enable`        | A **module** + the world's own lifecycle (`clearAllEntities()`, closing the world). Systems live on the world; they don't need a wrapper to turn on. |
-| Builder/factory helpers that _create entities_ (`createArc(world, …)`) | Let callers `world.entity().add(Networked).set(Arc, …).set(FillStyle, …)`. Components are small and optional; the caller adds exactly what it wants. |
-| A god component with many optional fields                              | Split into small single-purpose components; absence encodes "not applicable."                                                                        |
-| Duplicated `enter` + `update` doing the same thing                     | One `update({ watch: C, onEnter: true })` when update owns initialization.                                                                           |
-| One system trying to act in two phases                                 | Split into two systems, one per phase.                                                                                                               |
-| Custom phases for app/render logic                                     | Use the standard taxonomy; only engine modules insert phases.                                                                                        |
-| `.each` scanning every entity to detect change                         | Reactive `.update(C)` — fires only on change.                                                                                                        |
-| Networking a relationship                                              | You can't (target is an `Entity`); replicate a plain id/tag instead, or keep the relationship server-local.                                          |
-| A `registerFooSystem(world)` wrapper per system                        | Declare the system inline in the module's `init`.                                                                                                    |
+| Smell                                                                  | Do instead                                                                                                                                                                                                |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A side `Map<eid, resource>`                                            | Store the resource in a **companion component**; let queries drive its lifecycle; release in `onRemove`.                                                                                                  |
+| An imperative runtime object with `start()/stop()/track/enable`        | A **module** + the world's own lifecycle (`clearAllEntities()`, closing the world). Systems live on the world; they don't need a wrapper to turn on.                                                      |
+| Builder/factory helpers that _create entities_ (`createArc(world, …)`) | Let callers `world.entity().add(Networked).set(Arc, …).set(FillStyle, …)`. Components are small and optional; the caller adds exactly what it wants.                                                      |
+| A god component with many optional fields                              | Split into small single-purpose components; absence encodes "not applicable."                                                                                                                             |
+| Duplicated `enter` + `update` doing the same thing                     | One `update({ watch: C, onEnter: true })` when update owns initialization.                                                                                                                                |
+| One system trying to act in two phases                                 | Split into two systems, one per phase.                                                                                                                                                                    |
+| Custom phases for app/render logic                                     | Use the standard taxonomy; only engine modules insert phases.                                                                                                                                             |
+| `.each` scanning every entity to detect change                         | Reactive `.update(C)` — fires only on change.                                                                                                                                                             |
+| Networking a relationship                                              | Relationships can be networked when listed in `networkComponents`: `Relationship.target` serialises as a u32 entity id. List `ChildOf` (or custom subclasses) explicitly to replicate parent-child links. |
+| A `registerFooSystem(world)` wrapper per system                        | Declare the system inline in the module's `init`.                                                                                                                                                         |
 
 ---
 
@@ -576,9 +582,12 @@ system after whatever produces the entity/companion.
 - **Within a phase, order = registration order;** across phases, the spine guarantees order. Don't
   use registration order for cross-module correctness — use phases.
 - **Networked component order = wire protocol.** Reordering breaks the protocol.
-- **`@type`/`@wireType` must survive esbuild's standard decorators** when components load from
+- **`@wireType` must survive esbuild's standard decorators** when components load from
   source (tsx/Vite). Otherwise fields silently don't register.
-- **`Relationship.target` is an `Entity`** — not wire-encodable.
+- **`Relationship.target` is an `Entity`** — not directly wire-encodable, but
+  `vecs-protocol` registers it as an `"entity"` wire field (u32 eid) at module
+  load, so `Relationship` subclasses listed in `networkComponents` serialise
+  correctly.
 - **`world.module(M)` runs `init` once.** Re-registering with a different config throws.
 
 ---

package/docs/glossary.md

@@ -105,8 +105,7 @@ how often a system fires. [Systems](./systems.md#cadence-interval-rate-and-tick-
 **Watchlist** — the set of component types a query or system reacts to via `update`, stored as a
 bitmask. [Systems](./systems.md#reactive-callbacks-enter-update-exit).
 
-**Wire type** — a field-level encoding declaration (`@type` from `@vworlds/vecs-wire`, commonly
-imported as `wireType`) used by the networking packages to serialize components. Networking is
+**Wire type** — a field-level encoding declaration (`@wireType` from `@vworlds/vecs-wire`) used by the networking packages to serialize components. Networking is
 documented with `@vworlds/vecs-wire` / `@vworlds/vecs-protocol`, not here.
 
 **World** — the central container owning entities, component registrations, queries, systems, and

package/docs/relationships.md

@@ -26,8 +26,12 @@ with `children(ref)` through a reverse index the world maintains automatically.
 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.
+Because `target` is an `Entity` reference, relationships are not wire-serializable by default.
+However, `vecs-protocol` registers `Relationship.prototype.target` as an `"entity"` wire field
+(u32 eid) at module load, so **relationship subclasses listed in `networkComponents` are
+networkable**: the target serialises as a raw entity id, and the client resolves it to a live
+entity (creating a ghost placeholder if the parent hasn't arrived yet). List `ChildOf` (or custom
+subclasses) explicitly in your `networkComponents` array to replicate parent-child links.
 
 ## Built-in relationships
 

package/package.json

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