@vworlds/vecs 1.0.11 → 1.0.13

package/.husky/pre-commit

@@ -1,2 +1,3 @@
 npx tsc --noEmit
 npx lint-staged
+yarn format:check

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 ─────────────────────────────────────────────────────────────────
 
@@ -144,9 +144,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 +165,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 +208,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, and when `entity.set(C, props)` is applied to an entity that already has the component. Hook callbacks receive the owning entity because component instances do not carry entity references.
 
 #### Phases
 
@@ -217,9 +226,14 @@ const send = world.addPhase("send");
 world.progress(now, delta);
 
 // ...or run individual phases manually:
-world.runPhase(preUpdate, now, delta);
-world.runPhase(update, now, delta);
-world.runPhase(send, now, delta);
+world.beginFrame(delta);
+try {
+  world.runPhase(preUpdate, now, delta);
+  world.runPhase(update, now, delta);
+  world.runPhase(send, now, delta);
+} finally {
+  world.endFrame();
+}
 ```
 
 Systems with no explicit phase are placed in the built-in `"update"` phase.
@@ -237,6 +251,67 @@ world
   .exit(...);
 ```
 
+#### Timers and rate filters
+
+Systems can opt into a slower cadence instead of running on every phase tick. `interval()` takes seconds; throttled `run()` callbacks receive the accumulated milliseconds since the previous fire as `delta`.
+
+```ts
+import { IntervalTickSource, RateTickSource } from "@vworlds/vecs";
+
+world
+  .system("Move")
+  .interval(1.0)
+  .each([Position], (e, [pos]) => {
+    // 1 Hz
+  });
+
+world
+  .system("Move")
+  .rate(2)
+  .each([Position], (e, [pos]) => {
+    // every 2nd frame
+  });
+
+const second = new IntervalTickSource(1.0);
+
+world
+  .system("Move")
+  .tickSource(second)
+  .each([Position], (e, [pos]) => {
+    // driven by a shared timer
+  });
+
+second.stop();
+second.start();
+
+const minute = new RateTickSource(60, second);
+const hour = world
+  .system("Hour")
+  .tickSource(minute)
+  .rate(60)
+  .run((now, delta) => {
+    console.log("hour tick", now, delta);
+  });
+
+// Systems can also be tick sources for each other.
+const eachSecond = world
+  .system("EachSecond")
+  .interval(1)
+  .run(() => {
+    // ...
+  });
+
+const eachMinute = world
+  .system("EachMinute")
+  .tickSource(eachSecond)
+  .rate(60)
+  .run(() => {
+    // ...
+  });
+```
+
+Tick source objects and systems can both be used as sources. Disabling a source system suppresses its callbacks, but its clock still drives downstream consumers.
+
 #### Queries
 
 ```ts
@@ -292,8 +367,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;
 }
@@ -303,20 +380,21 @@ 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 });
 ```
 
-| 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 | A component instance does not know which entity owns it; 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.
 
 ---
 
@@ -324,32 +402,32 @@ 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.                                                                     |
+| `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
 ```
 
 #### Parent / child hierarchy
@@ -396,6 +474,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
@@ -440,12 +520,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);
 });
 ```
@@ -471,7 +551,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));
 ```
 
@@ -489,6 +569,22 @@ Fires every tick when the system's phase runs, regardless of entity state. Use f
 });
 ```
 
+#### `.disable()` / `.enable()`
+
+Pause and resume a system at runtime. While disabled the system is effectively invisible: the inbox is cleared immediately, any new `enter`, `exit`, or `update` events are silently dropped, `run` and `each` callbacks do not fire, and the system skips its `_run` entirely. Entity membership in the underlying query is still maintained, so the tracked set remains correct and the system resumes cleanly when re-enabled. Events that occurred while the system was disabled are **not** replayed.
+
+```ts
+const ai = world.system("AI").requires(Enemy).run(tickAI);
+
+// Pause AI processing during a cutscene:
+ai.disable();
+
+// Resume normal processing:
+ai.enable();
+```
+
+Both methods return `this` for chaining and are idempotent (calling `disable()` on an already-disabled system, or `enable()` on an already-enabled system, is a no-op).
+
 #### `.destroy()`
 
 **Not supported on `System`** — calling it throws. Systems live for the duration of the world. Use a standalone `Query` for temporary reactive sets.
@@ -503,7 +599,7 @@ Fires every tick when the system's phase runs, regardless of entity state. Use f
 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;
   });
@@ -514,20 +610,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
 
@@ -581,6 +677,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.                 |
@@ -589,7 +686,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`.