@vworlds/vecs 1.0.0 → 1.0.1

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -21,5 +21,9 @@
   "dependencies": {
     "eventemitter3": "^4.0.7"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vworlds/vecs"
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -21,5 +21,9 @@
   "dependencies": {
     "eventemitter3": "^4.0.7"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vworlds/vecs"
+  }
 }

package/.claude/settings.json

@@ -1,12 +0,0 @@
-{
-  "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

@@ -1,22 +0,0 @@
-{
-  "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

@@ -1,32 +0,0 @@
-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/src/component.ts

@@ -1,180 +0,0 @@
-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 class ComponentMeta implements Hook<Component> {
-  /** The component class constructor. */
-  public readonly Class: typeof Component;
-  /** Numeric type id assigned at registration time. */
-  public readonly type: number;
-  /** Human-readable name used in logs and serialization lookups. */
-  public readonly componentName: string;
-  /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
-  public readonly bitPtr: BitPtr;
-  private onAddHandler: ((c: Component) => void) | undefined;
-  private onRemoveHandler: ((c: Component) => void) | undefined;
-  private onSetHandler: ((c: Component) => void) | undefined;
-
-  constructor(Class: typeof Component, type: number, componentName: string) {
-    this.Class = Class;
-    this.type = type;
-    this.componentName = componentName;
-    this.bitPtr = new BitPtr(type);
-  }
-
-  /** @inheritdoc */
-  public onAdd(handler: (c: Component) => void): ComponentMeta {
-    this.onAddHandler = handler;
-    return this;
-  }
-
-  /** @inheritdoc */
-  public onRemove(handler: (c: Component) => void): ComponentMeta {
-    this.onRemoveHandler = handler;
-    return this;
-  }
-
-  /** @inheritdoc */
-  public onSet(handler: (c: Component) => void): ComponentMeta {
-    this.onSetHandler = handler;
-    return this;
-  }
-}
-
-/** 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 class Component {
-  private dirty: boolean = false;
-
-  constructor(
-    /** The entity this component belongs to. */
-    public readonly entity: Entity,
-    /** Registration metadata (type id, name, bit-pointer). */
-    public readonly meta: ComponentMeta
-  ) {}
-
-  /** Numeric type id — shorthand for `this.meta.type`. */
-  public get type(): number {
-    return this.meta.type;
-  }
-
-  /** Pre-computed bit-pointer — shorthand for `this.meta.bitPtr`. */
-  public get bitPtr(): BitPtr {
-    return this.meta.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.
-   */
-  public modified() {
-    this.entity.world._queueUpdatedComponent(this);
-  }
-
-  /** Returns the component's registered name, e.g. `"Position"`. */
-  public toString(): string {
-    return this.meta.componentName;
-  }
-}
-
-/**
- * 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 function calculateComponentBitmask(
-  classes: ComponentClassArray,
-  world: World
-) {
-  const bitmask = new Bitset();
-  classes.forEach((C) => {
-    bitmask.add(world.getComponentType(C));
-  });
-  return bitmask;
-}

package/src/entity.ts

@@ -1,276 +0,0 @@
-import { Component } from "./component.js";
-import type { World } from "./world.js";
-import { ArrayMap } from "./util/array_map.js";
-import { type System } from "./system.js";
-import { Events } from "./util/events.js";
-import { Bitset } from "./util/bitset.js";
-
-type EntityEvents = Events<{ destroy(): void }>;
-
-/**
- * A game object — a unique identifier with an arbitrary set of
- * {@link Component | components} attached to it.
- *
- * You never construct an `Entity` directly. Use {@link World.createEntity} for
- * locally-owned entities or {@link World.getOrCreateEntity} when the id is
- * assigned by an external authority (e.g. the server):
- *
- * ```ts
- * const e = world.createEntity();
- * const pos = e.add(Position);
- * pos.x = 100;
- * pos.modified();
- * ```
- *
- * Entities support a parent–child hierarchy. When a parent is destroyed its
- * children are destroyed recursively. The `children` set is created lazily.
- */
-export class Entity {
-  private components = new ArrayMap<Component>(); //maps component types to Components
-  private deletedComponents = new ArrayMap<Component>(); //maps deleted component types to Components
-
-  /**
-   * Bitmask representing the set of component types currently attached to this
-   * entity. Used by the world to efficiently match entities against system
-   * queries.
-   */
-  public readonly componentBitmask = new Bitset();
-  private readonly systems = new Set<System>();
-  private readonly newSystems: System[] = [];
-
-  /**
-   * A free-form property bag that modules can use to associate arbitrary data
-   * with an entity without registering a component.
-   */
-  public properties = new Map<string, any>();
-  public declare _events: EntityEvents;
-
-  /** Parent entity in the scene hierarchy, or `undefined` if root. */
-  public parent: Entity | undefined;
-  private _children: Set<Entity> | undefined;
-  public _archetypeChanged: boolean = false;
-  private destroyed = false;
-
-  constructor(
-    /** The {@link World} that owns this entity. */
-    public readonly world: World,
-    /** Unique numeric entity id assigned at creation time. */
-    public readonly eid: number
-  ) {}
-
-  /**
-   * The set of direct child entities in the scene hierarchy.
-   *
-   * The set is created lazily on first access. Mutate it only through
-   * {@link Entity.destroy} or by setting {@link Entity.parent} on a child —
-   * both will keep the parent–child links consistent.
-   */
-  public get children(): Set<Entity> {
-    if (!this._children) this._children = new Set<Entity>();
-    return this._children;
-  }
-
-  /**
-   * Add a component of type `Class` to this entity and return the instance.
-   *
-   * If the component is already present the existing instance is returned and
-   * no callback is fired. Pass `markAsModified = false` to suppress the
-   * initial `onSet` / `update` notification (useful when bulk-loading
-   * network snapshots before systems are running).
-   *
-   * @param Class - The component class to instantiate.
-   * @param markAsModified - Whether to immediately queue an `update`
-   *   notification. Defaults to `true`.
-   * @returns The new (or existing) component instance, typed as
-   *   `InstanceType<Class>`.
-   */
-  public add<C extends typeof Component>(
-    Class: C,
-    markAsModified?: boolean
-  ): InstanceType<C>;
-  /**
-   * Add a component by its numeric type id.
-   *
-   * @param type - Numeric component type id (as returned by
-   *   {@link World.getComponentType}).
-   * @param markAsModified - Whether to queue an update notification.
-   */
-  public add(type: number, markAsModified?: boolean): Component;
-  public add(
-    typeOrClass: number | typeof Component,
-    markAsModified: boolean = true
-  ) {
-    const type = this.world.getComponentType(typeOrClass);
-
-    let c = this.components.get(type);
-    if (c) {
-      return c;
-    }
-    c = this.world["getComponentInstance"](typeOrClass, this);
-
-    this.components.set(type, c);
-    this.componentBitmask.add(type);
-    this.world._notifyComponentAdded(this, c);
-    if (markAsModified) this.world._queueUpdatedComponent(c);
-
-    return c;
-  }
-
-  /**
-   * Remove the component of the given class from this entity.
-   *
-   * The `onRemove` hook and any `exit` callbacks on matching systems are
-   * called when archetype changes are flushed at the end of the next system
-   * run. Does nothing if the component is not present.
-   *
-   * @param Class - The component class to remove.
-   */
-  public remove<C extends typeof Component>(Class: C): void;
-  /**
-   * Remove a component by its numeric type id.
-   *
-   * @param type - Numeric component type id.
-   */
-  public remove(type: number): void;
-  public remove(typeOrClass: number | typeof Component): void {
-    const type = this.world.getComponentType(typeOrClass);
-    const c = this.components.get(type);
-    if (c) {
-      this.components.delete(type);
-      this.deletedComponents.set(type, c);
-      this.componentBitmask.delete(type);
-      this.world._notifyComponentRemoved(this, c);
-    }
-  }
-
-  /** @internal Called by systems to deliver update notifications. */
-  public _notifyModified(component: Component) {
-    this.systems.forEach((s) => {
-      s.notifyModified(component);
-    });
-  }
-
-  /**
-   * Retrieve the component of type `Class`, or `undefined` if not present.
-   *
-   * @param typeOrClass - Component class or numeric type id.
-   * @param get_deleted - If `true`, also search components that were removed
-   *   in the current frame but not yet garbage-collected. Useful inside
-   *   `exit` callbacks to read final component values.
-   * @returns The component instance or `undefined`.
-   */
-  public get<C extends typeof Component>(
-    typeOrClass: number | C,
-    get_deleted: boolean = false
-  ): InstanceType<C> | undefined {
-    const type = this.world.getComponentType(typeOrClass);
-
-    const c = this.components.get(type);
-    if (!c && get_deleted) {
-      return this.deletedComponents.get(type) as InstanceType<C> | undefined;
-    }
-    return c as InstanceType<C> | undefined;
-  }
-
-  /**
-   * Typed event emitter for entity-level lifecycle events.
-   *
-   * Currently emits one event:
-   * - `"destroy"` — fired just before the entity is fully torn down.
-   *
-   * The emitter is created lazily on first access.
-   */
-  public get events(): EntityEvents {
-    if (!this._events) {
-      this._events = new Events();
-    }
-    return this._events;
-  }
-
-  /** @internal */
-  public _hasSystem(s: System) {
-    return this.systems.has(s);
-  }
-
-  /** @internal */
-  public _addSystem(s: System) {
-    if (!this.systems.has(s)) {
-      this.newSystems.push(s);
-      s._enter(this);
-    }
-  }
-
-  /** @internal */
-  public _removeSystem(s: System) {
-    if (this.systems.delete(s)) {
-      s._exit(this);
-    }
-  }
-
-  /** @internal */
-  public _updateSystems() {
-    this.newSystems.forEach((s) => {
-      this.systems.add(s);
-    });
-    this.newSystems.length = 0;
-  }
-
-  /** `true` when the entity has no components attached. */
-  public get empty() {
-    return this.components.size == 0;
-  }
-
-  private _destroy() {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.systems.forEach((s) => {
-      s._exit(this);
-    });
-    this.systems.clear();
-
-    if (this._events) {
-      this._events.emit("destroy");
-      this._events.removeAllListeners("destroy");
-    }
-  }
-
-  /**
-   * Destroy this entity and recursively destroy all of its children.
-   *
-   * All components are removed (triggering `onRemove` hooks and `exit`
-   * callbacks), the entity is unregistered from the world, and the `"destroy"`
-   * event is emitted. The entity must not be used after calling this method.
-   */
-  public destroy() {
-    this.world._notifyEntityDestroyed(this);
-    this.children.forEach((child) => {
-      child.destroy();
-    });
-    this.children.clear();
-    if (this.parent) {
-      this.parent.children.delete(this);
-      this.world.archetypeChanged(this.parent);
-      this.parent = undefined;
-    }
-  }
-
-  /** @internal */
-  public clearDeletedComponents() {
-    this.deletedComponents.clear();
-  }
-
-  /**
-   * Iterate over every component currently attached to this entity.
-   *
-   * @param callback - Called with each component instance. Iteration order is
-   *   not guaranteed.
-   */
-  public forEachComponent(callback: (c: Component) => void) {
-    this.components.forEach(callback);
-  }
-
-  /** Returns `"EntityN"` where N is the entity id. */
-  public toString(): string {
-    return `Entity${this.eid}`;
-  }
-}

package/src/index.ts

@@ -1,6 +0,0 @@
-export { type System } from "./system.js";
-export { World } from "./world.js";
-export { Component, type ComponentMeta } from "./component.js";
-export { type Entity } from "./entity.js";
-export { type IPhase } from "./phase.js";
-export { Bitset } from "./util/bitset.js";

package/src/phase.ts

@@ -1,49 +0,0 @@
-import { type System } from "./system.js";
-import { type World } from "./world.js";
-
-/**
- * A named, ordered bucket of {@link System | systems} within the world's
- * update pipeline.
- *
- * Created internally by {@link World.addPhase}. The systems in a phase run in
- * the order they were registered. Between each system run the world flushes
- * pending archetype changes, so `enter` / `exit` callbacks are always
- * delivered before the next system executes.
- *
- * @internal The concrete class is not part of the public API. Use
- * {@link IPhase} to refer to phases in user code.
- */
-export class Phase {
-  /** Systems that belong to this phase, in execution order. */
-  public systems: System[] = [];
-
-  constructor(
-    /** Name used to look up the phase in the pipeline. */
-    public readonly name: string,
-    public world: World
-  ) {}
-}
-
-/**
- * Public interface for a pipeline phase returned by {@link World.addPhase}.
- *
- * Pass an `IPhase` to {@link System.phase} to assign a system to that phase,
- * or to {@link World.runPhase} to execute it:
- *
- * ```ts
- * const preUpdate = world.addPhase("preupdate");
- * const send      = world.addPhase("send");
- *
- * world.system("NetworkUpdate").phase(preUpdate).run(tick);
- *
- * // each frame:
- * world.runPhase(preUpdate, now, delta);
- * world.runPhase(send,      now, delta);
- * ```
- */
-export interface IPhase {
-  /** The name this phase was registered under. */
-  get name(): string;
-  /** The world that owns this phase. */
-  get world(): World;
-}