@vworlds/vecs 1.0.0

package/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//home/jm/src/procura/.devcontainer/**)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(npx tsc *)",
+      "Bash(npx vitest *)",
+      "Bash(git push *)"
+    ]
+  }
+}

package/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "name": "vecs",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20",
+  "remoteUser": "node",
+  "postCreateCommand": "yarn install",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "anthropic.claude-code"
+      ],
+      "settings": {
+        "claudeCode.allowDangerouslySkipPermissions": true
+      }
+    }
+  },
+  "mounts": [
+    // Claude Code auth — mounts ~/.claude from the host so login carries over seamlessly
+    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
+  ]
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run tests
+        run: yarn test
+
+      - name: Build
+        run: yarn build
+
+      - name: Publish
+        run: yarn publish --access public

package/README.md

@@ -0,0 +1,464 @@
+# vecs
+
+A TypeScript Entity Component System (ECS) for real-time games and simulations.
+
+`vecs` lets you model game state as **entities** (integer IDs) with **components** (typed data bags) attached to them. **Systems** declare which component combinations they care about and receive automatic callbacks when entities enter or leave their query, when component data changes, and on every tick. A **World** ties it all together and drives the update loop.
+
+## Install
+
+```
+yarn add @vworlds/vecs
+```
+
+## Concepts
+
+| Concept | What it is |
+|---|---|
+| **World** | Central container. Owns all entities, runs all systems. |
+| **Component** | A plain data class. Extend `Component` and attach instances to entities. |
+| **Entity** | An integer id with a set of components. Create via the world. |
+| **System** | Reactive logic. Declare which components you need; get called when things change. |
+
+### Lifecycle in brief
+
+```
+registerComponent() × N  →  system() × N  →  start()  →  progress() every frame
+```
+
+After `start()`, no new components or systems can be registered.
+
+---
+
+## Example
+
+The example below defines three components, two systems, a phase, and a hook, then runs a simple "move and despawn" loop.
+
+```ts
+import { World, Component, IPhase } from "@vworlds/vecs";
+
+// ─── Components ────────────────────────────────────────────────────────────
+
+class Position extends Component {
+  x = 0;
+  y = 0;
+}
+
+class Velocity extends Component {
+  vx = 0;
+  vy = 0;
+}
+
+class Health extends Component {
+  hp = 100;
+}
+
+// ─── World setup ───────────────────────────────────────────────────────────
+
+const world = new World();
+
+world.registerComponent(Position);
+world.registerComponent(Velocity);
+world.registerComponent(Health);
+
+// ─── Phases ────────────────────────────────────────────────────────────────
+
+const update: IPhase = world.addPhase("update");
+const cleanup: IPhase = world.addPhase("cleanup");
+
+// ─── Systems ───────────────────────────────────────────────────────────────
+
+// MoveSystem: runs every tick for entities that have both Position and Velocity.
+world
+  .system("Move")
+  .phase(update)
+  .requires(Position, Velocity)
+  .enter([Position, Velocity], (e, [pos, vel]) => {
+    console.log(`entity ${e.eid} entered Move with pos=(${pos.x},${pos.y})`);
+  })
+  .update(Velocity, [Position], (vel, [pos]) => {
+    // Called whenever vel.modified() is queued.
+    pos.x += vel.vx;
+    pos.y += vel.vy;
+    pos.modified(); // propagate position change to other systems
+  })
+  .exit((e) => {
+    console.log(`entity ${e.eid} left Move`);
+  });
+
+// HealthSystem: despawns entities whose HP drops to zero.
+world
+  .system("Health")
+  .phase(cleanup)
+  .requires(Health)
+  .update(Health, (health) => {
+    if (health.hp <= 0) {
+      health.entity.destroy();
+    }
+  });
+
+// ─── Hooks ─────────────────────────────────────────────────────────────────
+
+// Hooks are a lightweight alternative to systems for side effects on a single
+// component type — no per-entity query, just callbacks on add/remove/set.
+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`));
+
+// ─── Start ─────────────────────────────────────────────────────────────────
+
+world.start(); // freeze registration, sort systems into phases
+
+// ─── Create entities ───────────────────────────────────────────────────────
+
+const bullet = world.createEntity();
+const pos = bullet.add(Position);
+pos.x = 0;
+pos.y = 0;
+
+const vel = bullet.add(Velocity);
+vel.vx = 5;
+vel.vy = 0;
+vel.modified(); // first update: notify Move system
+
+const hp = bullet.add(Health);
+hp.hp = 3;
+hp.modified();
+
+// ─── Game loop ─────────────────────────────────────────────────────────────
+
+let now = 0;
+for (let tick = 0; tick < 5; tick++) {
+  now += 16;
+  world.progress(now, 16);
+}
+```
+
+---
+
+## API Reference
+
+### World
+
+The world owns everything. Create one per game session.
+
+```ts
+const world = new World();
+```
+
+#### Component registration
+
+```ts
+// Auto-assigned type id (starts at 256 for "local" components):
+world.registerComponent(Position);
+
+// Explicit numeric type id (required when the id comes from a server):
+world.registerComponent(Position, 1);
+
+// With a display name different from the class name:
+world.registerComponent(Position, "pos");
+
+// Pre-register a name → id mapping before the class is available:
+world.registerComponentType("Position", 1);
+```
+
+After `world.start()` any further call to `registerComponent` throws.
+
+#### Entity management
+
+```ts
+// Locally-owned entity with an auto-incrementing id:
+const e = world.createEntity();
+
+// Server-assigned id; creates the entity if it doesn't exist yet:
+const e = world.getOrCreateEntity(serverId, (newEntity) => {
+  tracked.add(newEntity);
+});
+
+// Look up by id (returns undefined if not found):
+const e = world.entity(42);
+
+// Destroy everything (e.g. on level reset):
+world.clearAllEntities();
+
+// Reserve a high id range for locally-created entities so they don't
+// collide with server-assigned ids (call before world.start()):
+world.setEntityIdRange(0x10000);
+```
+
+#### Systems
+
+```ts
+// Create, configure, and register a system in one chain:
+world.system("MySystem")
+  .phase("update")
+  .requires(A, B)
+  .enter(...)
+  .update(...)
+  .exit(...);
+
+world.start(); // must be called once, after all systems are set up
+```
+
+#### Phases
+
+```ts
+// Declare phases in the order they should run each frame:
+const preUpdate = world.addPhase("preupdate");
+const update    = world.addPhase("update");
+const send      = world.addPhase("send");
+
+// Each frame, run all phases in registration order:
+world.progress(Date.now(), deltaMs);
+
+// Or drive individual phases manually:
+world.runPhase(preUpdate, Date.now(), deltaMs);
+world.runPhase(update,    Date.now(), deltaMs);
+world.runPhase(send,      Date.now(), deltaMs);
+```
+
+Systems with no explicit phase go into a built-in `"update"` phase.
+
+#### Hooks
+
+A hook is a shorthand for reacting to a single component's lifecycle without writing a full system:
+
+```ts
+world.hook(Sprite)
+  .onAdd((sprite)    => sprite.initialize(scene))
+  .onRemove((sprite) => sprite.destroy())
+  .onSet((sprite)    => sprite.syncToScene());
+```
+
+`onSet` fires whenever `component.modified()` is called.  
+`onAdd` fires when the component is first attached to an entity.  
+`onRemove` fires when it is removed or the entity is destroyed.
+
+---
+
+### Component
+
+Extend `Component` to define your data:
+
+```ts
+class Position extends Component {
+  x = 0;
+  y = 0;
+}
+
+world.registerComponent(Position);
+
+const pos = entity.add(Position);
+pos.x = 100;
+pos.modified(); // tell the world this component changed
+```
+
+Every component instance exposes:
+
+| Property / Method | Description |
+|---|---|
+| `entity` | The `Entity` this component belongs to. |
+| `meta` | `ComponentMeta` — holds the type id, name, and bitset pointer. |
+| `type` | Numeric type id (shorthand for `meta.type`). |
+| `modified()` | Queue an `onSet` / `update` notification. Call after mutating fields. |
+
+---
+
+### Entity
+
+```ts
+const e = world.createEntity();
+```
+
+| Property / Method | Description |
+|---|---|
+| `eid` | Unique numeric entity id. |
+| `world` | The `World` that owns this entity. |
+| `add(Class)` | Attach a component; returns the typed instance. Idempotent. |
+| `get(Class)` | Return the component instance, or `undefined` if not present. |
+| `remove(Class)` | Detach a component (triggers `onRemove` hooks and `exit` callbacks). |
+| `destroy()` | Remove all components and unregister the entity. Recurses to children. |
+| `empty` | `true` when no components are attached. |
+| `forEachComponent(cb)` | Iterate over all attached components. |
+| `parent` | Parent entity in the scene hierarchy, or `undefined`. |
+| `children` | `Set<Entity>` of direct children (lazy, created on first access). |
+| `events` | Typed event emitter. Currently emits `"destroy"` before teardown. |
+| `properties` | `Map<string, any>` free-form bag for module-level bookkeeping. |
+
+#### Parent–child hierarchy
+
+```ts
+child.parent = parent;
+parent.children.add(child);
+
+// Destroying a parent recursively destroys all children:
+parent.destroy();
+```
+
+Archetype queries that use `{ PARENT: ... }` are automatically re-evaluated when a parent's component set changes.
+
+---
+
+### System
+
+Systems are created via `world.system(name)` and configured through a fluent builder API. All methods return `this` for chaining.
+
+#### `.requires(...components)` and `.query(q)`
+
+Declare which entities the system should track:
+
+```ts
+// Entities that have both Position and Velocity:
+.requires(Position, Velocity)
+
+// Equivalent explicit query:
+.query({ HAS: [Position, Velocity] })
+
+// Entities that have a parent with Player AND Container:
+.query({ PARENT: { AND: [Player, Container] } })
+
+// Compound queries:
+.query({ AND: [Position, { OR: [Sprite, Container] }] })
+.query({ NOT: Invisible })
+```
+
+**Query operators:**
+
+| Operator | Meaning |
+|---|---|
+| `{ HAS: [A, B] }` | Entity has all of A and B |
+| `{ HAS_ONLY: [A, B] }` | Entity has exactly A and B, nothing else |
+| `{ AND: [q1, q2] }` | Both sub-queries must match |
+| `{ OR: [q1, q2] }` | Either sub-query matches |
+| `{ NOT: q }` | Sub-query must not match |
+| `{ PARENT: q }` | Entity's parent matches q |
+| An array `[A, B]` | Shorthand for `HAS: [A, B]` |
+
+**Type inference:** `requires()` records the listed classes as a type parameter on the system. Callbacks in `.sort()`, `.each()`, and `.update()` inject then treat those components as non-nullable — no `!` needed. For complex `query()` expressions the type system cannot introspect, pass a second argument as an explicit hint:
+
+```ts
+.query({ AND: [{ HAS: Position }, { HAS: Velocity }] }, [Position, Velocity])
+.each([Position, Velocity], (e, [pos, vel]) => {
+  pos.x += vel.vx; // pos and vel are non-null
+})
+```
+
+#### `.phase(p)`
+
+Assign the system to a named phase or an `IPhase` reference. Systems without a phase run in `"update"`.
+
+```ts
+.phase("preupdate")   // by name
+.phase(myPhase)       // by IPhase reference
+```
+
+#### `.enter(callback)` / `.enter(inject, callback)`
+
+Called once when an entity first matches the system's query.
+
+```ts
+// No injection:
+.enter((e) => { console.log("entity joined", e.eid); })
+
+// With injection — component instances resolved from the entity:
+.enter([Position, Sprite], (e, [pos, sprite]) => {
+  sprite.setPosition(pos.x, pos.y);
+})
+
+// Resolve from parent:
+.enter([{ parent: Container }], (e, [container]) => {
+  container.add(e.get(Sprite)!.gameObject);
+})
+```
+
+#### `.exit(callback)` / `.exit(inject, callback)`
+
+Called when an entity leaves the system (component removed or entity destroyed). Components removed in the same frame are still accessible in exit callbacks.
+
+```ts
+.exit([Sprite], (e, [sprite]) => {
+  sprite.destroy();
+})
+```
+
+#### `.update(ComponentClass, callback)` / `.update(ComponentClass, inject, callback)`
+
+Called when `component.modified()` is queued on a watched component of a tracked entity.
+
+```ts
+// Simple — receives the modified component:
+.update(Position, (pos) => {
+  renderer.setPosition(pos.x, pos.y);
+})
+
+// With injection — receives the modified component and extra components:
+.update(Position, [Sprite], (pos, [sprite]) => {
+  sprite.sprite.setPosition(pos.x, pos.y);
+})
+```
+
+Injected components listed in `requires()` are non-nullable in the callback; any others are `Type | undefined`.
+
+Calling `update` also adds that component type to the system's implicit `HAS` query (unless you called `query()` first).
+
+#### `.each(components, callback)`
+
+Called every tick for **every tracked entity**, unconditionally. Unlike `update` (which only fires when `component.modified()` is called), `each` fires regardless of whether the component was modified — use it for per-entity logic that must run on every frame.
+
+The callback receives the entity and a tuple of resolved component instances. Components declared via `requires()` are guaranteed non-null; any others are `undefined` if the entity lacks them.
+
+```ts
+.requires(Position, Velocity)
+.each([Position, Velocity], (e, [pos, vel]) => {
+  pos.x += vel.vx; // non-null — both are in requires()
+  pos.y += vel.vy;
+})
+```
+
+`each` does not modify the system's query — define membership with `requires(...)` or `query(...)` as usual. Only one `each` may be registered per system; a second call throws.
+
+#### `.sort(components, compare)`
+
+Enable sorted entity tracking. Matched entities are stored in an ordered set whose insertion position is determined by `compare`, which receives a tuple of resolved component instances for each pair being ordered. Implies `.track()`.
+
+Components declared via `requires()` are non-null in the compare callback.
+
+```ts
+world.system("Render")
+  .requires(Position, Sprite)
+  .sort([Position], ([posA], [posB]) => posA.z - posB.z)
+  .each([Position, Sprite], (e, [pos, sprite]) => {
+    sprite.draw(pos.x, pos.y);
+  });
+```
+
+Iterating `system.entities` after a phase run yields entities in the sorted order.
+
+#### `.track()`
+
+Enable entity tracking without an `each` callback — matched entities are exposed via `system.entities` as they enter and leave. `each` and `sort` imply `track` automatically; call this directly only when you need the set without a per-tick callback.
+
+#### `.run(callback)`
+
+Called every tick when the system's phase runs, regardless of entity state. Use this for polling, network I/O, timers, etc.
+
+```ts
+.run((now, delta) => {
+  sendNetworkPacket(now);
+})
+```
+
+---
+
+## Build & Test
+
+```
+yarn build
+yarn test
+```
+
+---
+
+## License
+
+UNLICENSED

package/dist/component.d.ts

@@ -0,0 +1,135 @@
+import { BitPtr, Bitset } from "./util/bitset.js";
+import type { Entity } from "./entity.js";
+import { type World } from "./world.js";
+/**
+ * Lifecycle hook for a component type. Obtained via {@link World.hook}.
+ *
+ * Hooks let you react to component lifecycle events without building a full
+ * {@link System}. Each call returns the same `Hook` so the methods can be
+ * chained:
+ *
+ * ```ts
+ * world.hook(Sprite)
+ *   .onAdd(c  => initSprite(c))
+ *   .onRemove(c => destroySprite(c))
+ *   .onSet(c  => syncSprite(c));
+ * ```
+ *
+ * Callbacks are invoked synchronously during {@link World.runPhase} when
+ * archetype changes are flushed.
+ *
+ * @typeParam C - The `Component` subclass this hook is bound to.
+ */
+export interface Hook<C extends Component = Component> {
+    /**
+     * Register a callback that fires when a component of this type is added to
+     * an entity.
+     *
+     * @param handler - Receives the newly created component instance.
+     * @returns `this` for chaining.
+     */
+    onAdd(handler: (c: C) => void): Hook<C>;
+    /**
+     * Register a callback that fires when a component of this type is removed
+     * from an entity (including when the entity is destroyed).
+     *
+     * @param handler - Receives the component instance being removed.
+     * @returns `this` for chaining.
+     */
+    onRemove(handler: (c: C) => void): Hook<C>;
+    /**
+     * Register a callback that fires when {@link Component.modified} is called
+     * on a component of this type.
+     *
+     * @param handler - Receives the component instance that changed.
+     * @returns `this` for chaining.
+     */
+    onSet(handler: (c: C) => void): Hook<C>;
+}
+/**
+ * Internal bookkeeping record for a registered component class.
+ *
+ * Every component class that is passed to {@link World.registerComponent} gets
+ * a `ComponentMeta` that maps it to a numeric type id, a string name, and a
+ * pre-computed {@link BitPtr} used for fast archetype checks.
+ *
+ * `ComponentMeta` also implements {@link Hook}, so you can attach lifecycle
+ * callbacks directly on the meta object (as `World.hook()` returns it).
+ */
+export declare class ComponentMeta implements Hook<Component> {
+    /** The component class constructor. */
+    readonly Class: typeof Component;
+    /** 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;
+    private onAddHandler;
+    private onRemoveHandler;
+    private onSetHandler;
+    constructor(Class: typeof Component, type: number, componentName: string);
+    /** @inheritdoc */
+    onAdd(handler: (c: Component) => void): ComponentMeta;
+    /** @inheritdoc */
+    onRemove(handler: (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;
+/** An array of component class constructors or type ids. */
+export type ComponentClassArray = ComponentClassOrType[];
+/**
+ * Base class for all ECS components.
+ *
+ * Extend this class to define data that can be attached to an {@link Entity}:
+ *
+ * ```ts
+ * class Position extends Component {
+ *   x = 0;
+ *   y = 0;
+ * }
+ *
+ * world.registerComponent(Position);
+ * const pos = entity.add(Position);
+ * pos.x = 100;
+ * pos.modified(); // notify watching systems
+ * ```
+ *
+ * A component instance is always bound to a single entity and is created by
+ * the world when {@link Entity.add} is called.
+ */
+export declare class Component {
+    /** The entity this component belongs to. */
+    readonly entity: Entity;
+    /** Registration metadata (type id, name, bit-pointer). */
+    readonly meta: ComponentMeta;
+    private dirty;
+    constructor(
+    /** The entity this component belongs to. */
+    entity: Entity, 
+    /** Registration metadata (type id, 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 the component for delivery to all {@link System.update} callbacks
+     * that watch this component type. Call this after mutating the component's
+     * fields to ensure systems react to the new values.
+     */
+    modified(): void;
+    /** Returns the component's registered name, e.g. `"Position"`. */
+    toString(): string;
+}
+/**
+ * Compute a {@link Bitset} that has a bit set for every component class or
+ * type id in `classes`.
+ *
+ * @internal Used internally to build archetype masks for system queries.
+ */
+export declare function calculateComponentBitmask(classes: ComponentClassArray, world: World): Bitset;