npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@vworlds/vecs

v1.0.65

Published

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

Readme

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

The core package also exports the structural Vec2 type for two-dimensional points and vectors.

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({ watch: 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

Select holders of dynamically contributed component types with anyOf.

Use the type returned by groupBy, GroupedQuery, for typed live bucket access; it is not a runtime class.

Use the optional @vworlds/vecs/testing equality tester for cheap reference comparisons in Vitest; entities and worlds also provide safe diagnostic JSON summaries.

For synchronous world teardown and its allowed call sites, see Disposing a world.

For local schema reflection, query ComponentDef to enumerate registered component and module entities, and combine it with Trait to enumerate explicitly declared policy components, or with ModuleDef to enumerate installed modules. To reflect on a component's members, declare their types with @type or component.member(...) and read VecsStruct through a world or VecsStruct.of(C) without one; world.validate and world.normalize check and fix instances on demand.

System entity callbacks can inject Now and Delta alongside components to read the processing tick's timestamp and the system's accumulated tick delta.

Inspect system execution order and cadence with world.pipeline, registered callbacks and watched components with system.callbacks and system.watched, and scoped module provenance through entity parents. Modules carry themselves as singleton values (world.get/has) and release resources through their own remove hooks during world disposal. For opt-in timings and cadence run counts, see Measuring systems. For world-owned clocks and the recommended default-cadence check, see Cadence introspection.

For Node clients that need replicated Phaser poses, see Headless clients. For server keepalive gates and the idle replicated-state clock, see Replication. For independent schemas in one process and the world.cid packing API, see Per-world component ids.

For physics-driven change processing without extra pose watchers, see the post-step pose-change view.

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 (including changed-only assign) · Systems · Queries and filters · Relationships, edges, targets, and ownership · Modules · Subtree snapshots · Component reflection
  5. Design guide — patterns and anti-patterns from real designs.

Use ECS design diagrams for Mermaid schema, instance, and systems views in docs, issues, and PR discussions.

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.

Networking is documented alongside the packages that own it: World-route prefixes · MCP hubs and linked worlds · Named remote procedure calls and deadlines · Sessions and caller context · Client world and read-only diff snapshots. For MCP inspection through an opted-in browser connection, see Browser client targets.

Build & Test

npm run build
npm run test
npm run lint

License

UNLICENSED