@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/vecsA 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 frameDocumentation
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:
- Getting started — install to first ticking world.
- Concepts — the mental model.
- Execution model — phases, deferred mutation, event routing.
- Subsystem guides: Components and traits · Entities
(including changed-only
assign) · Systems · Queries and filters · Relationships, edges, targets, and ownership · Modules · Subtree snapshots · Component reflection - 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 lintLicense
UNLICENSED
