@vworlds/vecs 1.0.9 → 1.0.11

package/dist/entity.d.ts

@@ -1,209 +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` / `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 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;
-    private deletedComponents;
     /**
-     * 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;
-    private readonly newQueries;
     /**
-     * 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;
-    /** Parent entity in the scene hierarchy, or `undefined` if root. */
-    parent: Entity | undefined;
-    /** @internal */
-    _children: Set<Entity> | undefined;
-    _archetypeChanged: boolean;
-    private destroyed;
     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);
     /**
-     * The set of direct child entities in the scene hierarchy.
-     *
-     * The set is created lazily on first access. Mutate it only through
-     * {@link Entity.destroy} or by setting {@link Entity.parent} on a child —
-     * both will keep the parent–child links consistent.
+     * Re-evaluate every world query for this entity, firing `_enter` / `_exit`
+     * routing whenever membership flipped.
      */
-    get children(): Set<Entity>;
-    private getComponentInstance;
+    private _updateQueries;
     /**
-     * Queue an `onSet` / `update` notification for the given component and
-     * return the entity for chaining.
+     * Construct a fresh component of `type`, apply `props`, store it on this
+     * entity, fire the `onAdd` hook, and route query updates.
      *
-     * Equivalent to `component.modified()`, but usable inside an entity method
-     * chain (e.g. after `add` or `set`).
+     * 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. 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.
      *
-     * @param c - The component instance whose data changed.
-     * @returns This entity, for chaining.
+     * The emitter is created lazily on first access.
      */
-    modified<C extends typeof Component>(c: InstanceType<C>): Entity;
+    get events(): EntityEvents;
+    /** `true` when no components are currently attached to this entity. */
+    get empty(): boolean;
     /**
-     * Add a component of type `Class` to this entity and return the instance.
+     * 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.
      *
-     * If the component is already present the existing instance is returned and
-     * no callback is fired. Pass `markAsModified = false` to suppress the
-     * initial `onSet` / `update` notification (useful when bulk-loading
-     * network snapshots before systems are running).
+     * ```ts
+     * entity.components.forEach((c) => console.log(c.constructor.name));
+     * ```
+     */
+    get components(): ReadonlyArrayMap<Component>;
+    /**
+     * Reparent this entity. In deferred mode the change is queued; outside
+     * deferred mode it executes inline.
      *
-     * @param Class - The component class to instantiate.
-     * @param markAsModified - Whether to immediately queue an `update`
-     *   notification. Defaults to `true`.
-     * @returns The new (or existing) component instance, typed as
-     *   `InstanceType<Class>`.
+     * @param newParent - New parent, or `undefined` to make this a root entity.
      */
-    _add<C extends typeof Component>(Class: C, markAsModified?: boolean): InstanceType<C>;
+    setParent(newParent: Entity | undefined): void;
     /**
-     * Add a component by its numeric type id.
+     * Mark `c` as having changed, queueing the corresponding `onSet` / `update`
+     * notifications.
      *
-     * @param type - Numeric component type id (as returned by
-     *   {@link World.getComponentType}).
-     * @param markAsModified - Whether to queue an update notification.
+     * 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 - Component instance whose data changed.
+     * @returns This entity, for chaining.
      */
-    _add(type: number, markAsModified?: boolean): Component;
+    modified<C extends typeof Component>(c: InstanceType<C>): Entity;
     /**
-     * Add a component of type `Class` to this entity and return the entity.
+     * Attach a component to this entity if it is not already present.
      *
-     * If the component is already present the existing instance is returned and
-     * no callback is fired. Pass `markAsModified = false` to suppress the
-     * initial `onSet` / `update` notification (useful when bulk-loading
-     * network snapshots before systems are running).
+     * 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 markAsModified - Whether to immediately queue an `update`
-     *   notification. Defaults to `true`.
+     * @param Class - Component class to instantiate.
      * @returns This entity, for chaining.
      */
-    add<C extends typeof Component>(Class: C, markAsModified?: boolean): Entity;
+    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 markAsModified - Whether to queue an update notification.
+     * @param type - Numeric component type id.
+     * @returns This entity, for chaining.
      */
-    add(type: number, markAsModified?: boolean): Entity;
+    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.
      *
-     * @param Class - The component class to instantiate.
+     * 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.
      */
     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.
      *
-     * The `onRemove` hook and any `exit` callbacks on matching systems are
-     * called when archetype changes are flushed at the end of the next system
-     * run. Does nothing if the component is not present.
+     * 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 Called by queries to deliver update notifications. */
-    _notifyModified(component: Component): void;
     /**
-     * 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.
-     * @param get_deleted - If `true`, also search components that were removed
-     *   in the current frame but not yet garbage-collected. Useful inside
-     *   `exit` callbacks to read final component values.
-     * @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, get_deleted?: boolean): InstanceType<C> | undefined;
+    get<C extends typeof Component>(typeOrClass: number | C): InstanceType<C> | undefined;
     /**
-     * Typed event emitter for entity-level lifecycle events.
+     * Destroy this entity and recursively destroy its children.
      *
-     * 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;
-    /** @internal */
-    _hasQuery(q: Query): boolean;
-    /** @internal Removes a query from this entity's tracking sets without firing any callbacks. */
-    _purgeQuery(q: Query): void;
-    /** @internal */
-    _addQuery(q: Query): void;
-    /** @internal */
-    _removeQuery(q: Query): void;
-    /** @internal */
-    _updateQueries(): void;
-    /** `true` when the entity has no components attached. */
-    get empty(): boolean;
-    /** @internal */
-    _destroy(): void;
-    /**
-     * Destroy this entity and recursively destroy all of its children.
-     *
-     * All components are removed (triggering `onRemove` hooks and `exit`
-     * callbacks), the entity is unregistered from the world, and the `"destroy"`
-     * event is emitted. The entity must not be used after calling this method.
+     * 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;
-    /** @internal */
-    clearDeletedComponents(): 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;
 }