@vworlds/vecs 1.0.13 → 1.0.15

package/README.md

@@ -120,11 +120,12 @@ for (let tick = 0; tick < 5; tick++) {
 
 ## Deferred mode
 
-Inside a system body, a `Query.forEach`, or any `world.defer(...)` block, the world is in **deferred mode**: entity mutations (`add` / `set` / `remove` / `destroy` / `setParent` / `modified`) are queued instead of applied inline. The queue drains on the boundary that opened the deferred scope.
+Inside a system body, a `Query.forEach`, or any `world.defer(...)` block, the world is in **deferred mode**: entity mutations (`add` / `attach` / `set` / `remove` / `destroy` / `setParent` / `modified`) are queued instead of applied inline. The queue drains on the boundary that opened the deferred scope.
 
 Concretely, while deferred:
 
 - `entity.get(C)` returns `undefined` after `entity.add(C)` (no instance has been created yet).
+- `entity.get(C)` returns `undefined` after `entity.attach(instance)` if C was absent.
 - `entity.get(C)` returns the **previous** value after `entity.set(C, props)`.
 - `entity.get(C)` still returns the component after `entity.remove(C)`.
 
@@ -213,7 +214,7 @@ world
   .onSet((entity, sprite) => sprite.syncToScene(entity));
 ```
 
-`onAdd` fires when the component is first attached. `onRemove` fires when it is removed (or the entity is destroyed). `onSet` fires whenever `entity.modified(C)` is called, and when `entity.set(C, props)` is applied to an entity that already has the component. Hook callbacks receive the owning entity because component instances do not carry entity references.
+`onAdd` fires when the component is first attached. `onRemove` fires when it is removed (or the entity is destroyed). `onSet` fires whenever `entity.modified(C)` is called, when `entity.set(C, props)` applies data, and when `entity.attach(instance)` stores an existing instance. Hook callbacks receive the owning entity because component instances do not carry entity references.
 
 #### Phases
 
@@ -384,15 +385,20 @@ entity.modified(Position); // tell the world this component changed
 
 // Equivalent — set assigns props and fires onSet automatically:
 entity.set(Position, { x: 100 });
+
+// Store an existing instance directly:
+const shared = new Position();
+entity.attach(shared);
+entity.get(Position) === shared; // true
 ```
 
-| Rule                      | Description                                                                                                   |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Plain class               | Components should be ordinary classes with field initializers and methods as needed.                          |
-| No-arg construction       | vecs calls `new ComponentClass()`, so constructors should be omitted or take no parameters.                   |
-| Explicit registration     | Call `world.registerComponent(C)` before using the class as a component.                                      |
-| Shared instances possible | A component instance does not know which entity owns it; code should use the entity passed by vecs callbacks. |
-| Manual dirty marking      | After mutating fields directly, call `entity.modified(C)` to notify hooks, queries, and systems.              |
+| Rule                      | Description                                                                                                    |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Plain class               | Components should be ordinary classes with field initializers and methods as needed.                           |
+| No-arg construction       | vecs calls `new ComponentClass()`, so constructors should be omitted or take no parameters.                    |
+| Explicit registration     | Call `world.registerComponent(C)` before using the class as a component.                                       |
+| Shared instances possible | `entity.attach(instance)` stores the exact passed object; code should use the entity passed by vecs callbacks. |
+| Manual dirty marking      | After mutating fields directly, call `entity.modified(C)` to notify hooks, queries, and systems.               |
 
 Use `world.getComponentMeta(C)` or `world.getComponentType(C)` when you need metadata such as the numeric type id or component name. Metadata is world-specific.
 
@@ -409,6 +415,7 @@ Created via `world.entity()` (auto-assigned id) or `world.getOrCreateEntity(id,
 | `componentBitmask`  | `Bitset` of component type ids attached to this entity. Used by archetype matching.                                                   |
 | `properties`        | `Map<string, any>` free-form bag for module-level bookkeeping.                                                                        |
 | `add(Class)`        | Attach a component (idempotent). Returns the entity for chaining.                                                                     |
+| `attach(instance)`  | Attach an existing registered component instance directly; replaces any previous instance for that component class and fires `onSet`. |
 | `set(Class, props)` | Attach a component and assign `props`; fires `onSet`. Returns the entity for chaining.                                                |
 | `modified(Class)`   | Queue an `onSet` / `update` notification for a component class or numeric type id. Returns the entity for chaining.                   |
 | `get(Class)`        | Return the component instance, or `undefined`.                                                                                        |
@@ -430,6 +437,8 @@ vel.vx += accel;
 entity.modified(Velocity); // chainable
 ```
 
+Use `entity.attach(instance)` when component ownership is intentionally shared with caller code or another object graph. The instance constructor must be registered in the entity's world; unregistered instances throw. If the component belongs to an exclusive component group, conflicting components are removed before the instance is stored.
+
 #### Parent / child hierarchy
 
 ```ts

package/dist/dsl.js.map

@@ -1 +1 @@
-{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"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"}

package/dist/entity.d.ts

@@ -19,18 +19,20 @@ type EntityEvents = Events<{
  * e.set(Position, { x: 100 });
  * ```
  *
- * Entities support a parent–child hierarchy. `parent` and `children` form a
+ * Entities support a parent-child hierarchy. `parent` and `children` form a
  * bidirectional link maintained by {@link setParent}; the children set is
  * created lazily. Destroying a parent recursively destroys its children.
  *
  * ## Deferred semantics
  *
  * Inside a system body or `forEach` iteration the world is in **deferred
- * mode**: `add` / `set` / `modified` / `remove` / `destroy` / `setParent` only
- * enqueue commands. The data layer (the components map and `componentBitmask`)
- * is mutated when the world drains its queue. Concretely, while deferred:
+ * mode**: `add` / `attach` / `set` / `modified` / `remove` / `destroy` /
+ * `setParent` only enqueue commands. The data layer (the components map and
+ * `componentBitmask`) is mutated when the world drains its queue. Concretely,
+ * while deferred:
  *
  * - `entity.get(C)` returns `undefined` after `entity.add(C)` (no instance yet).
+ * - `entity.get(C)` returns `undefined` after `entity.attach(instance)` if C was absent.
  * - `entity.get(C)` returns the previous value after `entity.set(C, props)`.
  * - `entity.get(C)` still returns the component after `entity.remove(C)`.
  *
@@ -57,11 +59,19 @@ export declare class Entity {
     world: World, 
     /** Unique numeric entity id assigned at creation. */
     eid: number);
+    /** Fire every `onAdd` hook registered for `meta`. */
+    private _runOnAddHandlers;
+    /** Fire every `onSet` hook registered for `meta`. */
+    private _runOnSetHandlers;
     /**
      * Re-evaluate every world query for this entity, firing `_enter` / `_exit`
      * routing whenever membership flipped.
      */
     private _updateQueries;
+    /** Store a component instance and perform the shared add-side bookkeeping. */
+    private _storeComponent;
+    /** Perform the shared set-side hook and query update routing. */
+    private _notifyComponentSet;
     /**
      * Construct a fresh component of `type`, apply `props`, store it on this
      * entity, fire the `onAdd` hook, and route query updates.
@@ -70,57 +80,39 @@ export declare class Entity {
      * component already on this entity is removed first.
      */
     private _new;
-    /** Parent entity in the scene hierarchy, or `undefined` for a root entity. */
-    get parent(): Entity | undefined;
     /**
      * Read-only view of direct child entities. The backing set is created lazily
      * on the first child link; before that this getter returns a shared empty set.
      */
     get children(): ReadonlySet<Entity>;
-    /**
-     * Typed event emitter for entity-level lifecycle events. Currently only the
-     * `"destroy"` event is emitted, just before the entity is fully torn down.
-     *
-     * The emitter is created lazily on first access.
-     */
-    get events(): EntityEvents;
-    /** `true` when no components are currently attached to this entity. */
-    get empty(): boolean;
     /**
      * Read-only view of all components currently attached to this entity, keyed
      * by numeric component type id.
      *
      * The mutating methods (`set`, `delete`, `clear`) are not exposed. Use
-     * `entity.add`, `entity.set`, and `entity.remove` to change the component
-     * set.
+     * `entity.add`, `entity.attach`, `entity.set`, and `entity.remove` to change
+     * the component set.
      *
      * ```ts
      * entity.components.forEach((c) => console.log(c.constructor.name));
      * ```
      */
     get components(): ReadonlyArrayMap<Component>;
+    /** `true` when no components are currently attached to this entity. */
+    get empty(): boolean;
     /**
-     * Reparent this entity. In deferred mode the change is queued; outside
-     * deferred mode it executes inline.
-     *
-     * @param newParent - New parent, or `undefined` to make this a root entity.
-     */
-    setParent(newParent: Entity | undefined): void;
-    /**
-     * Mark a component type as having changed, queueing the corresponding `onSet` / `update`
-     * notifications.
-     *
-     * Repeated calls before the world routes the modified command are coalesced via
-     * the entity's dirty component bitset.
+     * Typed event emitter for entity-level lifecycle events. Currently only the
+     * `"destroy"` event is emitted, just before the entity is fully torn down.
      *
-     * @param typeOrClass - Component class or numeric type id whose data changed.
-     * @returns This entity, for chaining.
+     * The emitter is created lazily on first access.
      */
-    modified(typeOrClass: ComponentClassOrType): Entity;
+    get events(): EntityEvents;
+    /** Parent entity in the scene hierarchy, or `undefined` for a root entity. */
+    get parent(): Entity | undefined;
     /**
      * Attach a component to this entity if it is not already present.
      *
-     * Idempotent. Does not fire `onSet` — use {@link set} when you want to apply
+     * Idempotent. Does not fire `onSet` -- use {@link set} when you want to apply
      * data and notify watchers.
      *
      * @param Class - Component class to instantiate.
@@ -135,26 +127,44 @@ export declare class Entity {
      */
     add(type: number): Entity;
     /**
-     * Attach a component (creating it if necessary), copy `props` onto the
-     * instance, and fire the `onSet` hook plus any `update` callbacks for the
-     * component type.
+     * Attach an existing component instance to this entity and store that exact
+     * object. If a component of the same registered class already exists, it is
+     * replaced rather than assigned into.
      *
-     * In deferred mode `props` are not applied until the queued `Set` command is
-     * routed.
+     * `attach` uses the instance constructor to resolve component metadata, so
+     * the constructor must already be registered in this world. The operation
+     * fires hooks and query updates like a `set` operation.
      *
-     * @param Class - Component class to instantiate.
-     * @param props - Properties to assign onto the component instance.
+     * @param component - Existing component instance to store on the entity.
      * @returns This entity, for chaining.
      */
-    set<C extends ComponentClass>(Class: C, props: Partial<InstanceType<C>>): Entity;
+    attach(component: Component): Entity;
     /**
-     * Attach a component by numeric type id and copy `props` onto it.
+     * Destroy this entity and recursively destroy its children.
      *
-     * @param type - Numeric component type id.
-     * @param props - Properties to assign onto the component instance.
+     * Each component fires its `onRemove` hook, the `"destroy"` event is emitted
+     * just before teardown, and the entity is unregistered from the world.
+     * After destruction the entity must not be used.
+     */
+    destroy(): void;
+    /**
+     * Look up a component on this entity.
+     *
+     * @param typeOrClass - Component class or numeric type id.
+     * @returns The component instance, or `undefined` when it is not attached.
+     */
+    get<C extends ComponentClass>(typeOrClass: number | C): InstanceType<C> | undefined;
+    /**
+     * Mark a component type as having changed, queueing the corresponding `onSet` / `update`
+     * notifications.
+     *
+     * Repeated calls before the world routes the modified command are coalesced via
+     * the entity's dirty component bitset.
+     *
+     * @param typeOrClass - Component class or numeric type id whose data changed.
      * @returns This entity, for chaining.
      */
-    set(type: number, props: Partial<Component>): Entity;
+    modified(typeOrClass: ComponentClassOrType): Entity;
     /**
      * Detach a component from this entity.
      *
@@ -172,20 +182,33 @@ export declare class Entity {
      */
     remove(type: number): void;
     /**
-     * Look up a component on this entity.
+     * Reparent this entity. In deferred mode the change is queued; outside
+     * deferred mode it executes inline.
      *
-     * @param typeOrClass - Component class or numeric type id.
-     * @returns The component instance, or `undefined` when it is not attached.
+     * @param newParent - New parent, or `undefined` to make this a root entity.
      */
-    get<C extends ComponentClass>(typeOrClass: number | C): InstanceType<C> | undefined;
+    setParent(newParent: Entity | undefined): void;
     /**
-     * Destroy this entity and recursively destroy its children.
+     * Attach a component (creating it if necessary), copy `props` onto the
+     * instance, and fire the `onSet` hook plus any `update` callbacks for the
+     * component type.
      *
-     * Each component fires its `onRemove` hook, the `"destroy"` event is emitted
-     * just before teardown, and the entity is unregistered from the world.
-     * After destruction the entity must not be used.
+     * In deferred mode `props` are not applied until the queued `Set` command is
+     * routed.
+     *
+     * @param Class - Component class to instantiate.
+     * @param props - Properties to assign onto the component instance.
+     * @returns This entity, for chaining.
      */
-    destroy(): void;
+    set<C extends ComponentClass>(Class: C, props: Partial<InstanceType<C>>): Entity;
+    /**
+     * Attach a component by numeric type id and copy `props` onto it.
+     *
+     * @param type - Numeric component type id.
+     * @param props - Properties to assign onto the component instance.
+     * @returns This entity, for chaining.
+     */
+    set(type: number, props: Partial<Component>): Entity;
     /** Returns `"EntityN"` where N is the entity id. */
     toString(): string;
 }