vecs

A TypeScript Entity Component System (ECS) for real-time games and simulations.

vecs lets you model game state as entities (numeric ids) with components (typed data classes) 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 a phased update pipeline.

Install

npm install @vworlds/vecs

A taste

import { ON_VALIDATE, World } from "@vworlds/vecs";

class Position {
  x = 0;
  y = 0;
}
class Velocity {
  vx = 0;
  vy = 0;
}
class Health {
  hp = 100;
}

const world = new World();
world.component(Position);
world.component(Velocity);
world.component(Health);

world
  .system("Move")
  .with(Position, Velocity)
  .each([Position, Velocity], (e, [pos, vel]) => {
    pos.x += vel.vx;
    pos.y += vel.vy;
    e.modified(Position);
  });

world
  .system("Reap")
  .phase(ON_VALIDATE)
  .with(Health)
  .update(Health, (entity, health) => {
    if (health.hp <= 0) entity.destroy();
  });

world.entity().set(Position, { x: 0, y: 0 }).set(Velocity, { vx: 5, vy: 0 }).set(Health, { hp: 3 });

world.progress(performance.now(), 16); // call once per frame

Documentation

The full documentation lives in docs/. Recommended reading order:

1. Getting started — install to first ticking world.
2. Concepts — the mental model.
3. Execution model — phases, deferred mutation, event routing.
4. Subsystem guides: Components and traits · Entities · Systems · Queries and filters · Relationships, targets, and ownership · Modules
5. Design guide — patterns and anti-patterns from real designs.

Plus the Utilities guide for helper classes and the Glossary for terminology. The exhaustive per-symbol reference is the JSDoc on the source under src/ — read it in your IDE.

Build & Test

npm run build
npm run test
npm run lint

License

UNLICENSED