@vworlds/vecs 1.0.9 → 1.0.10

package/.husky/pre-commit

@@ -1 +1,2 @@
+npx tsc --noEmit
 npx lint-staged

package/dist/command.d.ts

@@ -0,0 +1,46 @@
+import type { Component } from "./component.js";
+import type { Entity } from "./entity.js";
+export declare const enum CommandKind {
+    CreateEntity = 0,
+    Set = 1,
+    Modified = 2,
+    Remove = 3,
+    Destroy = 4,
+    SetParent = 5
+}
+/**
+ * Command kinds emitted by {@link Entity} and routed by {@link World}.
+ *
+ * Commands are produced by `entity.add` / `entity.set` / `entity.remove` /
+ * `entity.destroy` (and `Component.modified`). In deferred mode they are
+ * pushed onto the world's command queue and processed at well-defined
+ * boundaries (after each system run, on `flush()`, on the next `runPhase`,
+ * etc.). Outside deferred mode they execute inline.
+ *
+ * @internal
+ */
+export type Command = {
+    kind: CommandKind.CreateEntity;
+    entity: Entity;
+} | {
+    kind: CommandKind.Set;
+    entity: Entity;
+    type: number;
+    /** Properties to assign. `undefined` for `entity.add(C)` (ensure-exists, no data). */
+    props: Partial<Component> | undefined;
+} | {
+    kind: CommandKind.Modified;
+    entity: Entity;
+    type: number;
+} | {
+    kind: CommandKind.Remove;
+    entity: Entity;
+    type: number;
+} | {
+    kind: CommandKind.Destroy;
+    entity: Entity;
+} | {
+    kind: CommandKind.SetParent;
+    entity: Entity;
+    parent: Entity | undefined;
+};

package/dist/command.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":""}

package/dist/entity.d.ts

@@ -21,6 +21,20 @@ type EntityEvents = Events<{
  *
  * Entities support a parent–child hierarchy. When a parent is destroyed its
  * children are destroyed recursively. The `children` set is created lazily.
+ *
+ * ## 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:
+ *
+ * - `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.
  */
 export declare class Entity {
     /** The {@link World} that owns this entity. */
@@ -28,7 +42,6 @@ export declare class Entity {
     /** Unique numeric entity id assigned at creation time. */
     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
@@ -36,33 +49,37 @@ export declare class Entity {
      */
     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.
      */
     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;
+    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: World, 
     /** Unique numeric entity id assigned at creation time. */
     eid: number);
+    /** Parent entity in the scene hierarchy, or `undefined` if this is a root entity. */
+    get parent(): Entity | undefined;
+    /** Read-only view of direct child entities. */
+    get children(): ReadonlySet<Entity>;
     /**
-     * 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.
+     * 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.
      */
-    get children(): Set<Entity>;
-    private getComponentInstance;
+    _setParent(newParent: Entity | undefined): void;
+    /**
+     * Reparent this entity. In deferred mode the change is queued; outside
+     * deferred mode it executes immediately.
+     */
+    setParent(newParent: Entity | undefined): void;
     /**
      * Queue an `onSet` / `update` notification for the given component and
      * return the entity for chaining.
@@ -75,54 +92,30 @@ export declare class Entity {
      */
     modified<C extends typeof Component>(c: InstanceType<C>): Entity;
     /**
-     * Add a component of type `Class` to this entity and return the instance.
+     * Add a component of type `Class` to this entity if it isn't already
+     * present, and return the entity for chaining.
      *
-     * 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).
+     * Does nothing if the component is already attached. `add` does not fire
+     * `onSet` — use {@link set} when you want to apply data and notify.
      *
      * @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>`.
-     */
-    _add<C extends typeof Component>(Class: C, markAsModified?: boolean): InstanceType<C>;
-    /**
-     * Add a component by its numeric type id.
-     *
-     * @param type - Numeric component type id (as returned by
-     *   {@link World.getComponentType}).
-     * @param markAsModified - Whether to queue an update notification.
-     */
-    _add(type: number, markAsModified?: boolean): Component;
-    /**
-     * Add a component of type `Class` to this entity and return the entity.
-     *
-     * 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).
-     *
-     * @param Class - The component class to instantiate.
-     * @param markAsModified - Whether to immediately queue an `update`
-     *   notification. Defaults to `true`.
      * @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.
      *
      * @param type - Numeric component type id (as returned by
      *   {@link World.getComponentType}).
-     * @param markAsModified - Whether to queue an update notification.
      */
-    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.
      *
+     * In deferred mode the props are not applied until the world processes the
+     * resulting `Set` command.
+     *
      * @param Class - The component class to instantiate.
      * @param props - Properties to assign onto the component instance.
      * @returns This entity, for chaining.
@@ -139,9 +132,9 @@ export declare class Entity {
     /**
      * Remove the component of the given class 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(Class)` continues to return
+     * the component until the queue is processed. Once processed, queries fire
+     * exit callbacks first, then the `onRemove` hook fires.
      *
      * @param Class - The component class to remove.
      */
@@ -152,18 +145,15 @@ export declare class Entity {
      * @param type - Numeric component type id.
      */
     remove(type: number): void;
-    /** @internal Called by queries to deliver update notifications. */
-    _notifyModified(component: Component): 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.
      *
      * @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`.
      */
-    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.
      *
@@ -173,30 +163,33 @@ export declare class Entity {
      * The emitter is created lazily on first access.
      */
     get events(): EntityEvents;
-    /** @internal */
-    _hasQuery(q: Query): boolean;
+    isInQuery(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;
+    /** @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;
-    /** @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.
+     * 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.
      */
     destroy(): void;
-    /** @internal */
-    clearDeletedComponents(): void;
     /**
      * Iterate over every component currently attached to this entity.
      *