@vworlds/vecs 1.0.12 → 1.0.14

package/README.md

@@ -15,7 +15,7 @@ yarn add @vworlds/vecs
 | Concept                  | What it is                                                                      |
 | ------------------------ | ------------------------------------------------------------------------------- |
 | **World**                | Central container. Owns every entity, query, system, and pipeline phase.        |
-| **Component**            | A plain data class. Extend `Component` and attach instances to entities.        |
+| **Component**            | A registered plain data class with a no-argument constructor.                   |
 | **Entity**               | A numeric id with a set of components. Created via the world.                   |
 | **Query**                | A reactive, always-up-to-date set of entities matching a predicate.             |
 | **System**               | A `Query` with phase placement and per-tick logic (`update`, `each`, `run`).    |
@@ -30,28 +30,28 @@ yarn add @vworlds/vecs
 registerComponent() × N  →  addPhase() / system() / query() × N  →  start()  →  progress() every frame
 ```
 
-After `start()`, component registration is disabled. Systems and queries can still be created — standalone queries backfill existing matched entities immediately.
+Components must be registered before they are used as component classes. After `start()`, component registration is disabled. Systems and queries can still be created — standalone queries backfill existing matched entities immediately.
 
 ---
 
 ## Example
 
 ```ts
-import { World, Component, IPhase } from "@vworlds/vecs";
+import { World, type IPhase } from "@vworlds/vecs";
 
 // ─── Components ────────────────────────────────────────────────────────────
 
-class Position extends Component {
+class Position {
   x = 0;
   y = 0;
 }
 
-class Velocity extends Component {
+class Velocity {
   vx = 0;
   vy = 0;
 }
 
-class Health extends Component {
+class Health {
   hp = 100;
 }
 
@@ -78,7 +78,7 @@ world
   .each([Position, Velocity], (e, [pos, vel]) => {
     pos.x += vel.vx;
     pos.y += vel.vy;
-    pos.modified(); // signal that Position changed so other systems react
+    e.modified(Position); // signal that Position changed so other systems react
   });
 
 // HealthSystem: despawns entities whose HP drops to zero.
@@ -86,9 +86,9 @@ world
   .system("Health")
   .phase(cleanup)
   .requires(Health)
-  .update(Health, (health) => {
+  .update(Health, (entity, health) => {
     if (health.hp <= 0) {
-      health.entity.destroy();
+      entity.destroy();
     }
   });
 
@@ -96,8 +96,8 @@ world
 
 world
   .hook(Health)
-  .onAdd((h) => console.log(`entity ${h.entity.eid} spawned with hp=${h.hp}`))
-  .onRemove((h) => console.log(`entity ${h.entity.eid} died`));
+  .onAdd((entity, h) => console.log(`entity ${entity.eid} spawned with hp=${h.hp}`))
+  .onRemove((entity) => console.log(`entity ${entity.eid} died`));
 
 // ─── Start ─────────────────────────────────────────────────────────────────
 
@@ -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)`.
 
@@ -144,9 +145,16 @@ const world = new World();
 
 #### Component registration
 
+Components are ordinary classes. They do not inherit from a vecs base class, and vecs constructs them with `new ComponentClass()`, so constructors should take no parameters. Register every component class before using it in `add`, `set`, `get`, `requires`, `query`, `filter`, `hook`, or `setExclusiveComponents`.
+
 ```ts
+class Position {
+  x = 0;
+  y = 0;
+}
+
 // Auto-assigned type id (≥ 256 for "local" components):
-world.registerComponent(Position);
+const positionMeta = world.registerComponent(Position);
 
 // Explicit numeric type id (e.g. server-assigned):
 world.registerComponent(Position, 1);
@@ -158,7 +166,9 @@ world.registerComponent(Position, "pos");
 world.registerComponentType("Position", 1);
 ```
 
-After `world.start()` (or `world.disableComponentRegistration()`) any further call to `registerComponent` throws.
+`registerComponent` returns the `ComponentMeta` for the class. Internally, vecs stores that metadata on the component class under a hidden world-specific key, so the same class can be registered independently in multiple worlds. Numeric type lookup still goes through the world's type table.
+
+After `world.start()` (or `world.disableComponentRegistration()`) any further call to `registerComponent` throws. There is no automatic component registration; using an unregistered component class as a component is an error.
 
 #### Exclusive component groups
 
@@ -199,12 +209,12 @@ world.clearAllEntities();
 ```ts
 world
   .hook(Sprite)
-  .onAdd((sprite) => sprite.initialize(scene))
-  .onRemove((sprite) => sprite.destroy())
-  .onSet((sprite) => sprite.syncToScene());
+  .onAdd((entity, sprite) => sprite.initialize(scene, entity))
+  .onRemove((entity, sprite) => sprite.destroy(scene, entity))
+  .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 `component.modified()` (or `entity.modified(c)`) is called, and when `entity.set(C, props)` is applied to an entity that already has the component.
+`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
 
@@ -217,7 +227,7 @@ const send = world.addPhase("send");
 world.progress(now, delta);
 
 // ...or run individual phases manually:
-world.beginFrame(now, delta);
+world.beginFrame(delta);
 try {
   world.runPhase(preUpdate, now, delta);
   world.runPhase(update, now, delta);
@@ -358,8 +368,10 @@ world.endDefer();
 
 ### `Component`
 
+Components are plain classes. vecs does not provide a runtime base class and does not attach `entity`, `meta`, `type`, `bitPtr`, or `modified()` to component instances.
+
 ```ts
-class Position extends Component {
+class Position {
   x = 0;
   y = 0;
 }
@@ -369,20 +381,26 @@ world.registerComponent(Position);
 entity.add(Position);
 const pos = entity.get(Position)!;
 pos.x = 100;
-pos.modified(); // tell the world this component changed
+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
 ```
 
-| Property / Method | Description                                                           |
-| ----------------- | --------------------------------------------------------------------- |
-| `entity`          | The `Entity` this component belongs to.                               |
-| `meta`            | `ComponentMeta` — type id, display name, and bit-pointer.             |
-| `type`            | Numeric type id (shorthand for `meta.type`).                          |
-| `bitPtr`          | `BitPtr` (shorthand for `meta.bitPtr`).                               |
-| `modified()`      | Queue an `onSet` / `update` notification. Call after mutating fields. |
-| `toString()`      | Returns the registered component name.                                |
+| 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.
 
 ---
 
@@ -390,34 +408,37 @@ entity.set(Position, { x: 100 });
 
 Created via `world.entity()` (auto-assigned id) or `world.getOrCreateEntity(id, ...)` (caller-supplied id).
 
-| Property / Method     | Description                                                                                                                           |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `eid`                 | Unique numeric entity id.                                                                                                             |
-| `world`               | The `World` that owns this entity.                                                                                                    |
-| `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.                                                                     |
-| `set(Class, props)`   | Attach a component and assign `props`; fires `onSet`. Returns the entity for chaining.                                                |
-| `modified(component)` | Queue an `onSet` / `update` notification. Returns the entity for chaining.                                                            |
-| `get(Class)`          | Return the component instance, or `undefined`.                                                                                        |
-| `remove(Class)`       | Detach a component (fires `onRemove` and `exit`).                                                                                     |
-| `destroy()`           | Remove all components, unregister from the world, recurse into children.                                                              |
-| `components`          | `ReadonlyArrayMap<Component>` — read-only view of attached components keyed by type id. Supports `forEach`, `get`, `has`, and `size`. |
-| `empty`               | `true` when no components are attached.                                                                                               |
-| `parent`              | Parent entity, or `undefined` for a root entity.                                                                                      |
-| `children`            | `ReadonlySet<Entity>` of direct children (lazy).                                                                                      |
-| `setParent(p)`        | Reparent the entity. `undefined` makes it a root entity. Throws on cycles.                                                            |
-| `events`              | Typed event emitter. Currently emits `"destroy"` just before teardown.                                                                |
-| `toString()`          | Returns `"EntityN"`.                                                                                                                  |
-
-`entity.modified(c)` is equivalent to `c.modified()` but returns the entity so it can chain:
+| Property / Method   | Description                                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `eid`               | Unique numeric entity id.                                                                                                             |
+| `world`             | The `World` that owns this entity.                                                                                                    |
+| `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`.                                                                                        |
+| `remove(Class)`     | Detach a component (fires `onRemove` and `exit`).                                                                                     |
+| `destroy()`         | Remove all components, unregister from the world, recurse into children.                                                              |
+| `components`        | `ReadonlyArrayMap<Component>` — read-only view of attached components keyed by type id. Supports `forEach`, `get`, `has`, and `size`. |
+| `empty`             | `true` when no components are attached.                                                                                               |
+| `parent`            | Parent entity, or `undefined` for a root entity.                                                                                      |
+| `children`          | `ReadonlySet<Entity>` of direct children (lazy).                                                                                      |
+| `setParent(p)`      | Reparent the entity. `undefined` makes it a root entity. Throws on cycles.                                                            |
+| `events`            | Typed event emitter. Currently emits `"destroy"` just before teardown.                                                                |
+| `toString()`        | Returns `"EntityN"`.                                                                                                                  |
+
+Call `entity.modified(C)` after mutating a component directly. Repeated calls for the same component type are coalesced while the world is deferred:
 
 ```ts
 const vel = entity.get(Velocity)!;
 vel.vx += accel;
-entity.modified(vel); // chainable
+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
@@ -462,6 +483,8 @@ Declare which entities the system tracks.
 | A single class / id    | Shorthand for `{ HAS: [C] }`             |
 | A predicate function   | Custom membership logic                  |
 
+Class-valued query terms are recognized as components by looking up registered metadata for the current world. Register component classes before using them in a `QueryDSL`; an unregistered class is treated like a predicate function and will fail if it cannot be called that way.
+
 **Type inference.** `requires()` records the listed classes as a type parameter `R` on the system. Callbacks in `.sort()`, `.each()`, and `.update()` injection treat those components as non-nullable — no `!` needed. For complex `query()` expressions the type system can't introspect, supply a `_guaranteed` second argument:
 
 ```ts
@@ -506,12 +529,12 @@ Fires when an entity leaves the system (component removed or entity destroyed).
 
 #### `.update(ComponentClass, callback)` / `.update(ComponentClass, inject, callback)`
 
-Fires when `component.modified()` is called for the watched component on a tracked entity.
+Fires when `entity.modified(ComponentClass)` is called for the watched component on a tracked entity. It also fires for `entity.set(C, props)` on an already-attached component and for initial watched components when an entity enters the query. The callback receives the entity first because component instances do not carry owner references.
 
 ```ts
-.update(Position, (pos) => renderer.setPosition(pos.x, pos.y));
+.update(Position, (entity, pos) => renderer.setPosition(entity.eid, pos.x, pos.y));
 
-.update(Position, [Sprite], (pos, [sprite]) => {
+.update(Position, [Sprite], (entity, pos, [sprite]) => {
   sprite.sprite.setPosition(pos.x, pos.y);
 });
 ```
@@ -537,7 +560,7 @@ Store matched entities in a custom order determined by `compare`. Implies `.trac
 world
   .system("Render")
   .requires(Position, Sprite)
-  .sort([Position], ([posA], [posB]) => posA.z - posB.z)
+  .sort([Position], (_entityA, [posA], _entityB, [posB]) => posA.z - posB.z)
   .each([Position, Sprite], (e, [pos, sprite]) => sprite.draw(pos.x, pos.y));
 ```
 
@@ -585,7 +608,7 @@ Both methods return `this` for chaining and are idempotent (calling `disable()`
 const projectiles = world
   .query("Projectiles")
   .requires(Position, Velocity)
-  .sort([Position], ([a], [b]) => a.z - b.z)
+  .sort([Position], (_entityA, [a], _entityB, [b]) => a.z - b.z)
   .enter([Position], (e, [pos]) => {
     pos.x = spawnX;
   });
@@ -596,20 +619,20 @@ projectiles.forEach((e) => { ... });
 console.log(projectiles.entities.size, "active projectiles");
 ```
 
-| Method                                                  | Description                                                              |
-| ------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `.requires(...components)`                              | Set the membership predicate to `HAS(...components)` and start tracking. |
-| `.query(expr, _guaranteed?)`                            | Set the membership predicate using a `QueryDSL` expression.              |
-| `.enter(callback)` / `.enter(inject, callback)`         | Fires when an entity joins the query.                                    |
-| `.exit(callback)` / `.exit(inject, callback)`           | Fires when an entity leaves the query.                                   |
-| `.update(C, callback)` / `.update(C, inject, callback)` | Fires when `C` is modified on a tracked entity.                          |
-| `.sort(components, compare)`                            | Store matched entities in sorted order.                                  |
-| `.track()`                                              | Enable tracking. Backfills when called after `start()`.                  |
-| `.belongs(e)`                                           | Returns `true` if the entity satisfies the predicate.                    |
-| `.forEach(callback)`                                    | Iterate currently tracked entities.                                      |
-| `.forEach(components, callback)`                        | Iterate with component injection.                                        |
-| `.entities`                                             | `ReadonlySet<Entity>` of currently tracked entities.                     |
-| `.destroy()`                                            | Remove the query from the world and from every entity (no exit fires).   |
+| Method                                                  | Description                                                                                         |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `.requires(...components)`                              | Set the membership predicate to `HAS(...components)` and start tracking.                            |
+| `.query(expr, _guaranteed?)`                            | Set the membership predicate using a `QueryDSL` expression.                                         |
+| `.enter(callback)` / `.enter(inject, callback)`         | Fires when an entity joins the query.                                                               |
+| `.exit(callback)` / `.exit(inject, callback)`           | Fires when an entity leaves the query.                                                              |
+| `.update(C, callback)` / `.update(C, inject, callback)` | Fires when `C` is modified on a tracked entity. Callback receives `(entity, component, injected?)`. |
+| `.sort(components, compare)`                            | Store matched entities in sorted order. Comparator receives `(entityA, tupleA, entityB, tupleB)`.   |
+| `.track()`                                              | Enable tracking. Backfills when called after `start()`.                                             |
+| `.belongs(e)`                                           | Returns `true` if the entity satisfies the predicate.                                               |
+| `.forEach(callback)`                                    | Iterate currently tracked entities.                                                                 |
+| `.forEach(components, callback)`                        | Iterate with component injection.                                                                   |
+| `.entities`                                             | `ReadonlySet<Entity>` of currently tracked entities.                                                |
+| `.destroy()`                                            | Remove the query from the world and from every entity (no exit fires).                              |
 
 #### `.destroy()` semantics
 
@@ -663,6 +686,7 @@ A compact, growable set of non-negative integers backed by 32-bit words. Used in
 | `add(n)`           | Set bit `n`.                                                             |
 | `addBit(bptr)`     | Set the bit at a pre-computed `BitPtr`.                                  |
 | `delete(n)`        | Clear bit `n`. Trims trailing zero words.                                |
+| `clear()`          | Remove every set bit.                                                    |
 | `has(n)`           | Returns `true` if bit `n` is set.                                        |
 | `hasBit(bptr)`     | Fast check via a pre-computed `BitPtr`.                                  |
 | `equal(other)`     | Returns `true` when both bitsets have the same bits set.                 |
@@ -671,7 +695,7 @@ A compact, growable set of non-negative integers backed by 32-bit words. Used in
 | `indices()`        | Return all set bit indices as a `number[]`.                              |
 
 ```ts
-class Tags extends Component {
+class Tags {
   tags = new Bitset();
 }
 

package/dist/component.d.ts

@@ -1,5 +1,11 @@
 import { BitPtr } from "./util/bitset.js";
 import type { Entity } from "./entity.js";
+/** A component instance. Components are plain objects created with a no-arg constructor. */
+export type Component = object;
+/** A component class constructor. */
+export type ComponentClass<T extends Component = Component> = new () => T;
+/** A component class constructor or its numeric type id. */
+export type ComponentClassOrType = number | ComponentClass;
 /**
  * Lifecycle hook for a registered component class. Obtained via
  * {@link World.hook}.
@@ -11,16 +17,16 @@ import type { Entity } from "./entity.js";
  *
  * ```ts
  * world.hook(Sprite)
- *   .onAdd(c => initSprite(c))
- *   .onRemove(c => destroySprite(c))
- *   .onSet(c => syncSprite(c));
+ *   .onAdd((e, c) => initSprite(e, c))
+ *   .onRemove((e, c) => destroySprite(e, c))
+ *   .onSet((e, c) => syncSprite(e, c));
  * ```
  *
  * Callbacks fire synchronously when the corresponding entity command is
  * applied: inline outside deferred mode, or while the world drains its command
  * queue inside a system / `forEach` / `defer` block.
  *
- * @typeParam C - Component subclass this hook is bound to.
+ * @typeParam C - Component class this hook is bound to.
  */
 export interface Hook<C extends Component = Component> {
     /**
@@ -28,29 +34,29 @@ export interface Hook<C extends Component = Component> {
      * to an entity (`entity.add(C)` or `entity.set(C, ...)` on an entity that
      * does not yet have the component).
      *
-     * @param handler - Receives the freshly created component instance.
+     * @param handler - Receives the entity and freshly created component instance.
      * @returns This hook, for chaining.
      */
-    onAdd(handler: (c: C) => void): Hook<C>;
+    onAdd(handler: (entity: Entity, c: C) => void): Hook<C>;
     /**
      * Register a handler invoked when a component of this type is removed from
      * an entity (explicit `entity.remove(C)` or implicit removal during
      * `entity.destroy()`).
      *
-     * @param handler - Receives the component instance that was removed.
+     * @param handler - Receives the entity and component instance that was removed.
      * @returns This hook, for chaining.
      */
-    onRemove(handler: (c: C) => void): Hook<C>;
+    onRemove(handler: (entity: Entity, c: C) => void): Hook<C>;
     /**
      * Register a handler invoked when a component's data has been marked as
-     * changed (`component.modified()` or `entity.modified(c)`), and when
+     * changed (`entity.modified(C)`), and when
      * `entity.set(C, props)` is called on an entity that already has the
      * component.
      *
-     * @param handler - Receives the component instance whose data changed.
+     * @param handler - Receives the entity and component instance whose data changed.
      * @returns This hook, for chaining.
      */
-    onSet(handler: (c: C) => void): Hook<C>;
+    onSet(handler: (entity: Entity, c: C) => void): Hook<C>;
 }
 /**
  * Bookkeeping record produced for each component class registered via
@@ -63,72 +69,18 @@ export interface Hook<C extends Component = Component> {
  */
 export declare class ComponentMeta implements Hook<Component> {
     /** The component class constructor this meta represents. */
-    readonly Class: typeof Component;
+    readonly Class: ComponentClass;
     /** Numeric type id assigned at registration time. */
     readonly type: number;
     /** Human-readable name used in logs and serialization lookups. */
     readonly componentName: string;
     /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
     readonly bitPtr: BitPtr;
-    /**
-     * Type ids of components that cannot coexist with this one on the same
-     * entity. Set via {@link World.setExclusiveComponents}; `undefined` means
-     * no restriction.
-     */
-    exclusive: number[] | undefined;
-    constructor(Class: typeof Component, type: number, componentName: string);
+    constructor(Class: ComponentClass, type: number, componentName: string);
     /** @inheritdoc */
-    onAdd(handler: (c: Component) => void): ComponentMeta;
+    onAdd(handler: (entity: Entity, c: Component) => void): ComponentMeta;
     /** @inheritdoc */
-    onRemove(handler: (c: Component) => void): ComponentMeta;
+    onRemove(handler: (entity: Entity, c: Component) => void): ComponentMeta;
     /** @inheritdoc */
-    onSet(handler: (c: Component) => void): ComponentMeta;
-}
-/** A component class constructor or its numeric type id. */
-export type ComponentClassOrType = number | typeof Component;
-/**
- * Base class for all ECS components.
- *
- * Subclass `Component` to declare data that can be attached to an
- * {@link Entity}. Instances are constructed by the world when
- * {@link Entity.add} or {@link Entity.set} runs — never instantiate manually.
- *
- * ```ts
- * class Position extends Component {
- *   x = 0;
- *   y = 0;
- * }
- *
- * world.registerComponent(Position);
- * entity.set(Position, { x: 100 });
- * ```
- *
- * Each instance is bound to a single entity via {@link entity}; that link is
- * permanent for the component's lifetime.
- */
-export declare class Component {
-    /** The entity this component belongs to. */
-    readonly entity: Entity;
-    /** Registration metadata (type id, display name, bit-pointer). */
-    readonly meta: ComponentMeta;
-    constructor(
-    /** The entity this component belongs to. */
-    entity: Entity, 
-    /** Registration metadata (type id, display name, bit-pointer). */
-    meta: ComponentMeta);
-    /** Numeric type id — shorthand for `this.meta.type`. */
-    get type(): number;
-    /** Pre-computed bit-pointer — shorthand for `this.meta.bitPtr`. */
-    get bitPtr(): BitPtr;
-    /**
-     * Notify the world that this component's data has changed.
-     *
-     * Queues a modified event that fires `update` callbacks on every system /
-     * query that watches this component type, plus the component's `onSet`
-     * hook. Repeated calls before the world drains its queue are coalesced
-     * into one delivery.
-     */
-    modified(): void;
-    /** Returns the component's registered display name (e.g. `"Position"`). */
-    toString(): string;
+    onSet(handler: (entity: Entity, c: Component) => void): ComponentMeta;
 }

package/dist/component.js

@@ -11,11 +11,11 @@ import { BitPtr, Bitset } from "./util/bitset.js";
 export class ComponentMeta {
     constructor(Class, type, componentName) {
         /**
-         * Type ids of components that cannot coexist with this one on the same
-         * entity. Set via {@link World.setExclusiveComponents}; `undefined` means
-         * no restriction.
+         * @internal Peer metas of components that cannot coexist with this one on
+         * the same entity. Set via {@link World.setExclusiveComponents}; `undefined`
+         * means no restriction.
          */
-        this.exclusive = undefined;
+        this._exclusive = undefined;
         this.Class = Class;
         this.type = type;
         this.componentName = componentName;
@@ -37,61 +37,6 @@ export class ComponentMeta {
         return this;
     }
 }
-/**
- * Base class for all ECS components.
- *
- * Subclass `Component` to declare data that can be attached to an
- * {@link Entity}. Instances are constructed by the world when
- * {@link Entity.add} or {@link Entity.set} runs — never instantiate manually.
- *
- * ```ts
- * class Position extends Component {
- *   x = 0;
- *   y = 0;
- * }
- *
- * world.registerComponent(Position);
- * entity.set(Position, { x: 100 });
- * ```
- *
- * Each instance is bound to a single entity via {@link entity}; that link is
- * permanent for the component's lifetime.
- */
-export class Component {
-    constructor(
-    /** The entity this component belongs to. */
-    entity, 
-    /** Registration metadata (type id, display name, bit-pointer). */
-    meta) {
-        this.entity = entity;
-        this.meta = meta;
-        /** @internal Set by {@link Entity.modified} to coalesce repeated calls until the world routes the modified command. */
-        this._dirty = false;
-    }
-    /** Numeric type id — shorthand for `this.meta.type`. */
-    get type() {
-        return this.meta.type;
-    }
-    /** Pre-computed bit-pointer — shorthand for `this.meta.bitPtr`. */
-    get bitPtr() {
-        return this.meta.bitPtr;
-    }
-    /**
-     * Notify the world that this component's data has changed.
-     *
-     * Queues a modified event that fires `update` callbacks on every system /
-     * query that watches this component type, plus the component's `onSet`
-     * hook. Repeated calls before the world drains its queue are coalesced
-     * into one delivery.
-     */
-    modified() {
-        this.entity.modified(this);
-    }
-    /** Returns the component's registered display name (e.g. `"Position"`). */
-    toString() {
-        return this.meta.componentName;
-    }
-}
 /**
  * Compute a {@link Bitset} with one bit set for every component class or
  * numeric type id in `classes`.

package/dist/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AA2DlD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAwBxB,YAAY,KAAuB,EAAE,IAAY,EAAE,aAAqB;QAdxE;;;;WAIG;QACI,cAAS,GAAyB,SAAS,CAAC;QAUjD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+B;QAC7C,CAAC,IAAI,CAAC,iBAAiB,KAAtB,IAAI,CAAC,iBAAiB,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,SAAS;IAIpB;IACE,4CAA4C;IAC5B,MAAc;IAC9B,kEAAkE;IAClD,IAAmB;QAFnB,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAe;QAPrC,uHAAuH;QAChH,WAAM,GAAY,KAAK,CAAC;IAO5B,CAAC;IAEJ,wDAAwD;IACxD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,mEAAmE;IACnE,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACI,QAAQ;QACb,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,2EAA2E;IACpE,QAAQ;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAA4B,EAAE,KAAY;IACnF,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAoElD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAwBxB,YAAY,KAAqB,EAAE,IAAY,EAAE,aAAqB;QAdtE;;;;WAIG;QACI,eAAU,GAAgC,SAAS,CAAC;QAUzD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+C;QAC1D,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+C;QAC7D,CAAC,IAAI,CAAC,iBAAiB,KAAtB,IAAI,CAAC,iBAAiB,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+C;QAC1D,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAA4B,EAAE,KAAY;IACnF,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/dsl.d.ts

@@ -1,4 +1,4 @@
-import { Component, ComponentClassArray, ComponentClassOrType } from "./component.js";
+import { type ComponentClass, ComponentClassArray, ComponentClassOrType } from "./component.js";
 import type { Entity } from "./entity.js";
 /**
  * A predicate that decides whether a given entity belongs to a query.
@@ -26,9 +26,13 @@ export type EntityTestFunc = (e: Entity) => boolean;
  * ```
  *
  * Short forms recognized by `query` / `filter`:
- * - A single class or numeric type id is shorthand for `{ HAS: [C] }`.
+ * - A registered component class or numeric type id is shorthand for `{ HAS: [C] }`.
  * - An array `[A, B]` is shorthand for `{ HAS: [A, B] }`.
  * - An {@link EntityTestFunc} is invoked directly for fully custom logic.
+ *
+ * Function values are treated as component classes only when the world already
+ * has registered metadata for that class. Register component classes before
+ * using them in query DSL expressions.
  */
 export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFunc | {
     HAS: ComponentClassArray | ComponentClassOrType;
@@ -53,13 +57,13 @@ export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFu
  * @typeParam C - Component class being injected.
  * @typeParam R - Tuple of component classes guaranteed present.
  */
-export type MaybeRequired<C, R extends (typeof Component)[]> = C extends typeof Component ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
+export type MaybeRequired<C, R extends ComponentClass[]> = C extends ComponentClass ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
 /**
  * Statically extract the component classes that are **guaranteed present** on
  * every entity matched by a {@link QueryDSL} expression.
  *
  * Rules:
- * - Plain class `C` → `[C]`
+ * - Plain component class `C` → `[C]`
  * - Plain array `[A, B]` → `[A, B]`
  * - `{ HAS: ... }` / `{ HAS_ONLY: ... }` → recurse into the payload
  * - `{ AND: [q1, q2, ...] }` → concatenate each branch's extraction
@@ -68,7 +72,7 @@ export type MaybeRequired<C, R extends (typeof Component)[]> = C extends typeof
  *
  * @typeParam Q - Query expression to analyse.
  */
-export type ExtractRequired<Q> = Q extends typeof Component ? [Q] : Q extends readonly (typeof Component)[] ? Q : Q extends {
+export type ExtractRequired<Q> = Q extends ComponentClass ? [Q] : Q extends readonly ComponentClass[] ? Q : Q extends {
     HAS: infer H;
 } ? ExtractRequired<H> : Q extends {
     HAS_ONLY: infer H;