@vworlds/vecs 1.0.12 → 1.0.14

package/dist/entity.js

@@ -14,18 +14,20 @@ import { Bitset } from "./util/bitset.js";
  * 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)`.
  *
@@ -42,6 +44,8 @@ export class Entity {
         this.eid = eid;
         /** @internal Maps numeric component type id to component instance. */
         this._components = new ArrayMap();
+        /** @internal Component types with pending modified delivery. */
+        this._dirtyComponentBitmask = new Bitset();
         /** @internal Set of queries this entity currently belongs to. */
         this._queries = new Set();
         /**
@@ -57,6 +61,14 @@ export class Entity {
         /** @internal Set to `true` after the world has fully torn down this entity. */
         this._destroyed = false;
     }
+    /** Fire every `onAdd` hook registered for `meta`. */
+    _runOnAddHandlers(meta, component) {
+        meta._onAddHandlers?.forEach((handler) => handler(this, component));
+    }
+    /** Fire every `onSet` hook registered for `meta`. */
+    _runOnSetHandlers(meta, component) {
+        meta._onSetHandlers?.forEach((handler) => handler(this, component));
+    }
     /**
      * Re-evaluate every world query for this entity, firing `_enter` / `_exit`
      * routing whenever membership flipped.
@@ -64,145 +76,70 @@ export class Entity {
     _updateQueries() {
         this.world.queries.forEach((q) => {
             const belongs = q.belongs(this);
-            const isIn = this._isInQuery(q);
+            const isIn = this._queries.has(q);
             if (belongs !== isIn) {
                 belongs ? q._enter(this) : q._exit(this);
             }
         });
     }
-    /**
-     * Construct a fresh component of `type`, apply `props`, store it on this
-     * entity, fire the `onAdd` hook, and route query updates.
-     *
-     * If the component type belongs to an exclusivity group, any conflicting
-     * component already on this entity is removed first.
-     */
-    _new(type, props) {
-        const meta = this.world.getComponentMeta(type);
-        if (meta.exclusive) {
-            for (const exclusiveType of meta.exclusive) {
-                if (this._components.has(exclusiveType)) {
-                    this._remove(exclusiveType);
+    /** Store a component instance and perform the shared add-side bookkeeping. */
+    _storeComponent(meta, component, isAdd) {
+        if (meta._exclusive) {
+            for (const exclusiveMeta of meta._exclusive) {
+                if (this._components.has(exclusiveMeta.type)) {
+                    this._remove(exclusiveMeta);
                 }
             }
         }
-        const c = new meta.Class(this, meta);
-        if (props !== undefined) {
-            Object.assign(c, props);
-        }
-        this._components.set(type, c);
-        this.componentBitmask.add(type);
-        if (meta._onAddHandlers) {
-            meta._onAddHandlers.forEach((handler) => handler(c));
+        this._components.set(meta.type, component);
+        this.componentBitmask.addBit(meta.bitPtr);
+        if (isAdd) {
+            this._runOnAddHandlers(meta, component);
         }
         this._updateQueries();
-        return c;
-    }
-    /**
-     * @internal Return `true` when this entity is currently tracked by `q`.
-     */
-    _isInQuery(q) {
-        return this._queries.has(q);
     }
-    /**
-     * @internal Look up a component instance by numeric type id.
-     *
-     * Faster than {@link get} because no class → type id resolution is needed.
-     */
-    _get(type) {
-        return this._components.get(type);
-    }
-    /**
-     * @internal Reparent this entity in place, maintaining the bidirectional
-     * link. Throws if `newParent` is a descendant of this entity.
-     *
-     * Called by the world either inline (outside deferred mode) or while
-     * routing a queued `SetParent` command.
-     */
-    _setParent(newParent) {
-        if (this._destroyed) {
-            return;
-        }
-        if (newParent !== undefined) {
-            let ancestor = newParent;
-            while (ancestor !== undefined) {
-                if (ancestor === this) {
-                    throw new Error(`Circular parent reference: entity ${this.eid} is already an ancestor of entity ${newParent.eid}`);
-                }
-                ancestor = ancestor._parent;
-            }
-        }
-        if (this._parent) {
-            this._parent._children?.delete(this);
-        }
-        this._parent = newParent;
-        if (newParent) {
-            (newParent._children ?? (newParent._children = new Set())).add(this);
+    /** Perform the shared set-side hook and query update routing. */
+    _notifyComponentSet(meta, component, isUpdate) {
+        this._runOnSetHandlers(meta, component);
+        this._dirtyComponentBitmask.deleteBit(meta.bitPtr);
+        if (isUpdate) {
+            this._queries.forEach((q) => q._notifyModified(this, meta, component));
         }
     }
     /**
-     * @internal Apply a `Set` command: create the component if missing, assign
-     * `props` if provided, fire `onSet`, and route modified events to every
-     * query that watches the component type.
+     * Construct a fresh component of `type`, apply `props`, store it on this
+     * entity, fire the `onAdd` hook, and route query updates.
+     *
+     * If the component type belongs to an exclusivity group, any conflicting
+     * component already on this entity is removed first.
      */
-    _set(type, props) {
-        if (this._destroyed) {
-            return;
-        }
-        const existing = this._components.get(type);
-        const c = existing ?? this._new(type, props);
+    _new(meta, props) {
+        const c = new meta.Class();
         if (props !== undefined) {
-            if (existing) {
-                Object.assign(c, props);
-            }
-            const setHandlers = c.meta._onSetHandlers;
-            if (setHandlers) {
-                setHandlers.forEach((handler) => handler(c));
-            }
-            c._dirty = false;
-            if (existing) {
-                this._queries.forEach((q) => q._notifyModified(c));
-            }
+            Object.assign(c, props);
         }
+        this._storeComponent(meta, c, true);
+        return c;
     }
     /**
-     * @internal Apply a `Modified` command: fire `onSet` and route modified
-     * events to every query that watches the component type.
+     * @internal Record that this entity is now tracked by `q`. Called by
+     * `Query._enter`.
      */
-    _modified(type) {
-        if (this._destroyed) {
-            return;
-        }
-        const c = this._components.get(type);
-        if (!c) {
-            return;
-        }
-        const setHandlers = c.meta._onSetHandlers;
-        if (setHandlers) {
-            setHandlers.forEach((handler) => handler(c));
-        }
-        c._dirty = false;
-        this._queries.forEach((q) => q._notifyModified(c));
+    _addQueryMembership(q) {
+        this._queries.add(q);
     }
     /**
-     * @internal Apply a `Remove` command: clear the type bit, route exits,
-     * detach the component, and fire `onRemove`.
+     * @internal Apply an `Attach` command: store the provided component instance,
+     * replacing any previous instance for this type. Events are fired as if the
+     * caller had performed a `set` operation.
      */
-    _remove(type) {
+    _attach(meta, component) {
         if (this._destroyed) {
             return;
         }
-        const c = this._components.get(type);
-        if (!c) {
-            return;
-        }
-        this.componentBitmask.delete(type);
-        this._updateQueries();
-        this._components.delete(type);
-        const removeHandlers = c.meta._onRemoveHandlers;
-        if (removeHandlers) {
-            removeHandlers.forEach((handler) => handler(c));
-        }
+        const existing = this._components.get(meta.type);
+        this._storeComponent(meta, component, existing === undefined);
+        this._notifyComponentSet(meta, component, existing !== undefined);
     }
     /**
      * @internal Apply a `Destroy` command: fire `_exit` on every query, then
@@ -221,12 +158,14 @@ export class Entity {
             }
         });
         toExit.forEach((q) => q._exit(this));
-        this._components.forEach((c) => {
-            const removeHandlers = c.meta._onRemoveHandlers;
+        this._components.forEach((c, type) => {
+            const meta = this.world.getComponentMeta(type);
+            const removeHandlers = meta._onRemoveHandlers;
             if (removeHandlers) {
-                removeHandlers.forEach((handler) => handler(c));
+                removeHandlers.forEach((handler) => handler(this, c));
             }
         });
+        this._dirtyComponentBitmask.clear();
         if (this._events) {
             this._events.emit("destroy");
             this._events.removeAllListeners("destroy");
@@ -237,6 +176,34 @@ export class Entity {
             this._parent = undefined;
         }
     }
+    /**
+     * @internal Look up a component instance by numeric type id.
+     *
+     * Faster than {@link get} because no class to type id resolution is needed.
+     */
+    _get(type) {
+        return this._components.get(type);
+    }
+    /**
+     * @internal Return `true` when this entity is currently tracked by `q`.
+     */
+    _isInQuery(q) {
+        return this._queries.has(q);
+    }
+    /**
+     * @internal Apply a `Modified` command: fire `onSet` and route modified
+     * events to every query that watches the component type.
+     */
+    _modified(meta) {
+        if (this._destroyed) {
+            return;
+        }
+        const c = this._components.get(meta.type);
+        if (!c) {
+            return;
+        }
+        this._notifyComponentSet(meta, c, true);
+    }
     /**
      * @internal Forget query `q` without firing exit callbacks. Called by
      * {@link World} when a {@link Query.destroy} sweeps every entity.
@@ -245,11 +212,25 @@ export class Entity {
         this._queries.delete(q);
     }
     /**
-     * @internal Record that this entity is now tracked by `q`. Called by
-     * `Query._enter`.
+     * @internal Apply a `Remove` command: clear the type bit, route exits,
+     * detach the component, and fire `onRemove`.
      */
-    _addQueryMembership(q) {
-        this._queries.add(q);
+    _remove(meta) {
+        if (this._destroyed) {
+            return;
+        }
+        const c = this._components.get(meta.type);
+        if (!c) {
+            return;
+        }
+        this._dirtyComponentBitmask.deleteBit(meta.bitPtr);
+        this.componentBitmask.deleteBit(meta.bitPtr);
+        this._updateQueries();
+        this._components.delete(meta.type);
+        const removeHandlers = meta._onRemoveHandlers;
+        if (removeHandlers) {
+            removeHandlers.forEach((handler) => handler(this, c));
+        }
     }
     /**
      * @internal Record that this entity is no longer tracked by `q`. Called by
@@ -258,40 +239,66 @@ export class Entity {
     _removeQueryMembership(q) {
         this._queries.delete(q);
     }
-    /** Parent entity in the scene hierarchy, or `undefined` for a root entity. */
-    get parent() {
-        return this._parent;
-    }
     /**
-     * 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.
+     * @internal Apply a `Set` command: create the component if missing, assign
+     * `props` if provided, fire `onSet`, and route modified events to every
+     * query that watches the component type.
      */
-    get children() {
-        return this._children ?? Entity._emptyChildren;
+    _set(meta, props) {
+        if (this._destroyed) {
+            return;
+        }
+        const existing = this._components.get(meta.type);
+        const c = existing ?? this._new(meta, props);
+        if (props !== undefined) {
+            if (existing) {
+                Object.assign(c, props);
+            }
+            this._notifyComponentSet(meta, c, existing !== undefined);
+        }
     }
     /**
-     * Typed event emitter for entity-level lifecycle events. Currently only the
-     * `"destroy"` event is emitted, just before the entity is fully torn down.
+     * @internal Reparent this entity in place, maintaining the bidirectional
+     * link. Throws if `newParent` is a descendant of this entity.
      *
-     * The emitter is created lazily on first access.
+     * Called by the world either inline (outside deferred mode) or while
+     * routing a queued `SetParent` command.
      */
-    get events() {
-        if (!this._events) {
-            this._events = new Events();
+    _setParent(newParent) {
+        if (this._destroyed) {
+            return;
+        }
+        if (newParent !== undefined) {
+            let ancestor = newParent;
+            while (ancestor !== undefined) {
+                if (ancestor === this) {
+                    throw new Error(`Circular parent reference: entity ${this.eid} is already an ancestor of entity ${newParent.eid}`);
+                }
+                ancestor = ancestor._parent;
+            }
+        }
+        if (this._parent) {
+            this._parent._children?.delete(this);
+        }
+        this._parent = newParent;
+        if (newParent) {
+            (newParent._children ?? (newParent._children = new Set())).add(this);
         }
-        return this._events;
     }
-    /** `true` when no components are currently attached to this entity. */
-    get empty() {
-        return this._components.size == 0;
+    /**
+     * 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() {
+        return this._children ?? Entity._emptyChildren;
     }
     /**
      * 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));
@@ -300,103 +307,145 @@ export class Entity {
     get components() {
         return this._components;
     }
+    /** `true` when no components are currently attached to this entity. */
+    get empty() {
+        return this._components.size == 0;
+    }
     /**
-     * Reparent this entity. In deferred mode the change is queued; outside
-     * deferred mode it executes inline.
+     * Typed event emitter for entity-level lifecycle events. Currently only the
+     * `"destroy"` event is emitted, just before the entity is fully torn down.
      *
-     * @param newParent - New parent, or `undefined` to make this a root entity.
+     * The emitter is created lazily on first access.
      */
-    setParent(newParent) {
+    get events() {
+        if (!this._events) {
+            this._events = new Events();
+        }
+        return this._events;
+    }
+    /** Parent entity in the scene hierarchy, or `undefined` for a root entity. */
+    get parent() {
+        return this._parent;
+    }
+    add(typeOrClass) {
+        const meta = this.world.getComponentMeta(typeOrClass);
         if (this.world.deferred) {
-            this.world._enqueue({ kind: 5 /* CommandKind.SetParent */, entity: this, parent: newParent });
+            this.world._enqueue({ kind: 1 /* CommandKind.Set */, entity: this, meta, props: undefined });
         }
         else {
-            this._setParent(newParent);
+            this._set(meta, undefined);
         }
+        return this;
     }
     /**
-     * Mark `c` as having changed, queueing the corresponding `onSet` / `update`
-     * notifications.
+     * 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.
      *
-     * Equivalent to `c.modified()` but returns the entity for chaining. Repeated
-     * calls before the world routes the modified command are coalesced via the
-     * component's dirty flag.
+     * `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 c - Component instance whose data changed.
+     * @param component - Existing component instance to store on the entity.
      * @returns This entity, for chaining.
      */
-    modified(c) {
-        if (c._dirty) {
-            return this;
-        }
-        c._dirty = true;
+    attach(component) {
+        const meta = this.world.getComponentMeta(component.constructor);
         if (this.world.deferred) {
-            this.world._enqueue({ kind: 2 /* CommandKind.Modified */, entity: this, type: c.type });
+            this.world._enqueue({ kind: 6 /* CommandKind.Attach */, entity: this, meta, component });
         }
         else {
-            this._modified(c.type);
+            this._attach(meta, component);
         }
         return this;
     }
-    add(typeOrClass) {
-        const type = this.world.getComponentType(typeOrClass);
+    /**
+     * Destroy this entity and recursively destroy its children.
+     *
+     * 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() {
         if (this.world.deferred) {
-            this.world._enqueue({ kind: 1 /* CommandKind.Set */, entity: this, type, props: undefined });
+            this.world._enqueue({ kind: 4 /* CommandKind.Destroy */, entity: this });
         }
         else {
-            this._set(type, undefined);
+            this._destroy();
+        }
+        if (this._children) {
+            this._children.forEach((child) => {
+                child.destroy();
+            });
+            this._children.clear();
         }
-        return this;
     }
-    set(typeOrClass, props) {
+    /**
+     * 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(typeOrClass) {
         const type = this.world.getComponentType(typeOrClass);
+        return this._get(type);
+    }
+    /**
+     * 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.
+     */
+    modified(typeOrClass) {
+        const meta = this.world.getComponentMeta(typeOrClass);
+        if (this._dirtyComponentBitmask.hasBit(meta.bitPtr)) {
+            return this;
+        }
+        this._dirtyComponentBitmask.addBit(meta.bitPtr);
         if (this.world.deferred) {
-            this.world._enqueue({ kind: 1 /* CommandKind.Set */, entity: this, type, props });
+            this.world._enqueue({ kind: 2 /* CommandKind.Modified */, entity: this, meta });
         }
         else {
-            this._set(type, props);
+            this._modified(meta);
         }
         return this;
     }
     remove(typeOrClass) {
-        const type = this.world.getComponentType(typeOrClass);
+        const meta = this.world.getComponentMeta(typeOrClass);
         if (this.world.deferred) {
-            this.world._enqueue({ kind: 3 /* CommandKind.Remove */, entity: this, type });
+            this.world._enqueue({ kind: 3 /* CommandKind.Remove */, entity: this, meta });
         }
         else {
-            this._remove(type);
+            this._remove(meta);
         }
     }
     /**
-     * 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(typeOrClass) {
-        const type = this.world.getComponentType(typeOrClass);
-        return this._get(type);
-    }
-    /**
-     * Destroy this entity and recursively destroy its children.
+     * Reparent this entity. In deferred mode the change is queued; outside
+     * deferred mode it executes inline.
      *
-     * 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.
+     * @param newParent - New parent, or `undefined` to make this a root entity.
      */
-    destroy() {
+    setParent(newParent) {
         if (this.world.deferred) {
-            this.world._enqueue({ kind: 4 /* CommandKind.Destroy */, entity: this });
+            this.world._enqueue({ kind: 5 /* CommandKind.SetParent */, entity: this, parent: newParent });
         }
         else {
-            this._destroy();
+            this._setParent(newParent);
         }
-        if (this._children) {
-            this._children.forEach((child) => {
-                child.destroy();
-            });
-            this._children.clear();
+    }
+    set(typeOrClass, props) {
+        const meta = this.world.getComponentMeta(typeOrClass);
+        if (this.world.deferred) {
+            this.world._enqueue({ kind: 1 /* CommandKind.Set */, entity: this, meta, props });
+        }
+        else {
+            this._set(meta, props);
         }
+        return this;
     }
     /** Returns `"EntityN"` where N is the entity id. */
     toString() {