@vworlds/vecs 1.0.10 → 1.0.11

package/dist/entity.d.ts

@@ -1,202 +1,192 @@
 import { Component } from "./component.js";
 import type { World } from "./world.js";
-import { type Query } from "./query.js";
+import { ReadonlyArrayMap } from "./util/array_map.js";
 import { Events } from "./util/events.js";
 import { Bitset } from "./util/bitset.js";
 type EntityEvents = Events<{
     destroy(): void;
 }>;
 /**
- * A game object — a unique identifier with an arbitrary set of
- * {@link Component | components} attached to it.
+ * A game object: a unique numeric id with an arbitrary set of
+ * {@link Component | components} attached.
  *
- * You never construct an `Entity` directly. Use {@link World.entity} to create
- * one, or {@link World.getOrCreateEntity} when the id is assigned by an
- * external authority (e.g. the server):
+ * Never instantiate `Entity` directly. Use {@link World.entity} for an
+ * auto-assigned id, or {@link World.getOrCreateEntity} when the id comes from
+ * an external authority such as a game server:
  *
  * ```ts
  * const e = world.entity();
  * e.set(Position, { x: 100 });
  * ```
  *
- * Entities support a parent–child hierarchy. When a parent is destroyed its
- * children are destroyed recursively. The `children` set is created lazily.
+ * 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` / `remove` / `destroy` only enqueue commands; the
- * data layer (`components` map, `componentBitmask`) is not mutated until the
- * world processes the queue. Concretely, inside deferred mode:
+ * 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:
  *
  * - `entity.get(C)` returns `undefined` after `entity.add(C)` (no instance yet).
  * - `entity.get(C)` returns the previous value after `entity.set(C, props)`.
  * - `entity.get(C)` still returns the component after `entity.remove(C)`.
  *
- * Outside deferred mode (top-level user code) the same calls execute inline —
- * mutations are visible immediately.
+ * Outside deferred mode the same calls execute inline and mutations are
+ * visible immediately.
  */
 export declare class Entity {
-    /** The {@link World} that owns this entity. */
+    /** World that owns this entity. */
     readonly world: World;
-    /** Unique numeric entity id assigned at creation time. */
+    /** Unique numeric entity id assigned at creation. */
     readonly eid: number;
-    private components;
     /**
-     * Bitmask representing the set of component types currently attached to this
-     * entity. Used by the world to efficiently match entities against query
-     * predicates.
+     * Bitmask of component type ids currently attached to this entity. Used by
+     * the world for fast archetype matching against query predicates.
      */
     readonly componentBitmask: Bitset;
-    private readonly queries;
     /**
-     * A free-form property bag that modules can use to associate arbitrary data
-     * with an entity without registering a component.
+     * Free-form property bag. Modules can use it to associate arbitrary data with
+     * an entity without registering a dedicated component.
      */
     properties: Map<string, any>;
-    _events: EntityEvents;
-    private _parent;
-    private _children;
-    /** @internal True once the world has fully processed this entity's destruction. */
-    _destroyed: boolean;
-    private static readonly _emptyChildren;
     constructor(
-    /** The {@link World} that owns this entity. */
+    /** World that owns this entity. */
     world: World, 
-    /** Unique numeric entity id assigned at creation time. */
+    /** Unique numeric entity id assigned at creation. */
     eid: number);
-    /** Parent entity in the scene hierarchy, or `undefined` if this is a root entity. */
+    /**
+     * Re-evaluate every world query for this entity, firing `_enter` / `_exit`
+     * routing whenever membership flipped.
+     */
+    private _updateQueries;
+    /**
+     * 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.
+     */
+    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. */
+    /**
+     * 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>;
     /**
-     * Immediately reparent this entity. Maintains the bidirectional link,
-     * removes it from the old parent's children, and adds it to the new
-     * parent's children. Throws if the operation would create a cycle.
+     * 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.
+     *
+     * ```ts
+     * entity.components.forEach((c) => console.log(c.constructor.name));
+     * ```
      */
-    _setParent(newParent: Entity | undefined): void;
+    get components(): ReadonlyArrayMap<Component>;
     /**
      * Reparent this entity. In deferred mode the change is queued; outside
-     * deferred mode it executes immediately.
+     * deferred mode it executes inline.
+     *
+     * @param newParent - New parent, or `undefined` to make this a root entity.
      */
     setParent(newParent: Entity | undefined): void;
     /**
-     * Queue an `onSet` / `update` notification for the given component and
-     * return the entity for chaining.
+     * Mark `c` as having changed, queueing the corresponding `onSet` / `update`
+     * notifications.
      *
-     * Equivalent to `component.modified()`, but usable inside an entity method
-     * chain (e.g. after `add` or `set`).
+     * 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.
      *
-     * @param c - The component instance whose data changed.
+     * @param c - Component instance whose data changed.
      * @returns This entity, for chaining.
      */
     modified<C extends typeof Component>(c: InstanceType<C>): Entity;
     /**
-     * Add a component of type `Class` to this entity if it isn't already
-     * present, and return the entity for chaining.
+     * Attach a component to this entity if it is not already present.
      *
-     * Does nothing if the component is already attached. `add` does not fire
-     * `onSet` — use {@link set} when you want to apply data and notify.
+     * Idempotent. Does not fire `onSet` — use {@link set} when you want to apply
+     * data and notify watchers.
      *
-     * @param Class - The component class to instantiate.
+     * @param Class - Component class to instantiate.
      * @returns This entity, for chaining.
      */
     add<C extends typeof Component>(Class: C): Entity;
     /**
-     * Add a component by its numeric type id.
+     * Attach a component by numeric type id.
      *
-     * @param type - Numeric component type id (as returned by
-     *   {@link World.getComponentType}).
+     * @param type - Numeric component type id.
+     * @returns This entity, for chaining.
      */
     add(type: number): Entity;
     /**
-     * Add a component of type `Class` (if not already present), assign the
-     * provided properties onto the instance, and return the entity for chaining.
+     * 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.
      *
-     * In deferred mode the props are not applied until the world processes the
-     * resulting `Set` command.
+     * In deferred mode `props` are not applied until the queued `Set` command is
+     * routed.
      *
-     * @param Class - The component class to instantiate.
+     * @param Class - Component class to instantiate.
      * @param props - Properties to assign onto the component instance.
      * @returns This entity, for chaining.
      */
     set<C extends typeof Component>(Class: C, props: Partial<InstanceType<C>>): Entity;
     /**
-     * Add a component by its numeric type id, assign the provided properties,
-     * and return the entity for chaining.
+     * 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;
     /**
-     * Remove the component of the given class from this entity.
+     * Detach a component from this entity.
      *
-     * In deferred mode the removal is queued — `get(Class)` continues to return
-     * the component until the queue is processed. Once processed, queries fire
-     * exit callbacks first, then the `onRemove` hook fires.
+     * In deferred mode the removal is queued; `get(C)` continues to return the
+     * component until the queue drains. When applied, queries fire `exit`
+     * callbacks first and the `onRemove` hook fires last.
      *
-     * @param Class - The component class to remove.
+     * @param Class - Component class to detach.
      */
     remove<C extends typeof Component>(Class: C): void;
     /**
-     * Remove a component by its numeric type id.
+     * Detach a component by numeric type id.
      *
      * @param type - Numeric component type id.
      */
     remove(type: number): void;
-    /** @internal Look up a component instance by type id. */
-    _get(type: number): Component | undefined;
     /**
-     * Retrieve the component of type `Class`, or `undefined` if not present.
+     * Look up a component on this entity.
      *
      * @param typeOrClass - Component class or numeric type id.
-     * @returns The component instance or `undefined`.
+     * @returns The component instance, or `undefined` when it is not attached.
      */
     get<C extends typeof Component>(typeOrClass: number | C): InstanceType<C> | undefined;
     /**
-     * Typed event emitter for entity-level lifecycle events.
-     *
-     * Currently emits one event:
-     * - `"destroy"` — fired just before the entity is fully torn down.
-     *
-     * The emitter is created lazily on first access.
-     */
-    get events(): EntityEvents;
-    isInQuery(q: Query): boolean;
-    /** @internal Removes a query from this entity's tracking sets without firing any callbacks. */
-    _purgeQuery(q: Query): void;
-    /** @internal Add a query to the entity's tracked-query set. Called by Query._enter. */
-    _addQueryMembership(q: Query): void;
-    /** @internal Remove a query from the entity's tracked-query set. Called by Query._exit. */
-    _removeQueryMembership(q: Query): void;
-    private _updateQueries;
-    private _new;
-    /** @internal Execute a Set command — create if absent, apply props, fire hooks, route events. */
-    _set(type: number, props: Partial<Component> | undefined): void;
-    /** @internal Execute a Modified command — fire onSet and route update events. */
-    _modified(type: number): void;
-    /** @internal Execute a Remove command — clear bitmask, route exits, remove component, fire onRemove. */
-    _remove(type: number): void;
-    /** @internal Execute a Destroy command — exit queries, fire onRemove, emit event, unregister. */
-    _destroy(): void;
-    /** `true` when the entity has no components attached. */
-    get empty(): boolean;
-    /**
-     * Destroy this entity and recursively destroy all of its children.
+     * Destroy this entity and recursively destroy its children.
      *
-     * All components have their `onRemove` hooks fired, the entity is
-     * unregistered from the world, and the `"destroy"` event is emitted. The
-     * entity must not be used after the destroy completes.
+     * 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;
-    /**
-     * Iterate over every component currently attached to this entity.
-     *
-     * @param callback - Called with each component instance. Iteration order is
-     *   not guaranteed.
-     */
-    forEachComponent(callback: (c: Component) => void): void;
     /** Returns `"EntityN"` where N is the entity id. */
     toString(): string;
 }