strongly-typed, unopinionated, fast-enough entity-component-system system for hobby use1
zecs is a composition-based approach to organizing data and updates!
tightly integrated with zod for schemas
pnpm add zecsnpm install --save zecsyarn add zecsyou can import individual pieces, or the whole thing:
import {component, query} from 'zecs';
import {zecs} from 'zecs';components are just zod types with names:
// docs/010-component.ts
import { zecs } from 'zecs';
import { z } from 'zod/v4';
export const health = zecs.component('health', z.number());
export const position = zecs.component(
'position',
z.object({ x: z.number(), y: z.number() }),
);
export const velocity = zecs.component(
'velocity',
z.object({ x: z.number(), y: z.number() }),
);entities are plain objects where each property matches a component:
// docs/020-entity.ts
export const player = {
health: 100,
position: { x: 10, y: 20 },
};an ecs stores entities that conform to some set of components:
// docs/030-ecs.ts
import { zecs } from 'zecs';
import { health, position, velocity } from './010-component';
import { player } from './020-entity';
export const ecs = zecs.ecs([health, position, velocity]);
ecs.add(player);Note
every component is optional! this allows behavior to differ between entities, and it's why we need queries.
queries select entities based on what components they have...
// docs/040-query.ts
import { zecs } from 'zecs';
import { position, velocity } from './010-component';
import { ecs } from './030-ecs';
const movable = zecs.query().has(position, velocity);
// queries are reusable and not bound to a specific ECS!
for (const entity of movable.query(ecs)) {
entity.position.x += entity.velocity.x;
entity.position.y += entity.velocity.y;
}or any condition you want:
// docs/041-query-refinement.ts
import { zecs } from 'zecs';
import { position, velocity } from './010-component';
import { ecs } from './030-ecs';
declare const keys: Record<string, boolean>;
const canJump = zecs
.query()
.has(position, velocity)
.where(({ position: { y } }) => y === 0);
for (const entity of canJump.query(ecs)) {
if (keys.space) {
entity.velocity.y = -10;
}
}every zecs ECS is serializable, meaning that it can be converted to and from a plain object:
// docs/050-serialization.ts
import { ecs } from './030-ecs';
declare function mySave(data: string): void;
declare function myLoad(): string;
const data = ecs.toJSON();
// your serializing and saving logic
mySave(JSON.stringify(data));
const loaded = JSON.parse(myLoad());
ecs.loadJSON(loaded);components may contain other entities, and zecs will automatically convert them to and from references when serializing:
// docs/051-serializing-references.ts
import { zecs } from 'zecs';
import { z } from 'zod/v4';
const name = zecs.component('name', z.string());
const friend = zecs.component('friend', zecs.entitySchema([name]));
const friendlyEcs = zecs.ecs([name, friend]);
const kai = friendlyEcs.add({ name: 'kai' });
const jules = friendlyEcs.add({ name: 'jules' });
kai.friend = jules;
jules.friend = kai;
friendlyEcs.loadJSON(friendlyEcs.toJSON());it's just fine to put a query in a function and be done with it.
i'll also offer you the system. the simplest system is just like looping over every entity in a query:
// docs/060-system.ts
import { zecs } from 'zecs';
import { z } from 'zod/v4';
import { position, velocity } from './010-component';
import { ecs } from './030-ecs';
const kinematics = zecs.system({
name: 'kinematics',
query: zecs.query().has(position, velocity),
updateParams: z.object({ dt: z.number() }),
onUpdated({ entity: { position, velocity }, updateParams: { dt } }) {
position.x += velocity.x * dt;
position.y += velocity.y * dt;
},
});
const kinematicsHandle = await zecs.attachSystem(ecs, kinematics, {});
kinematicsHandle.update({ dt: 0.016 });a system, much like a component or a query, is just a description. attaching the system to an ECS returns a stateful "handle", which can be .update() every frame or step.
// docs/061-system-lifecycle.ts
import { zecs } from 'zecs';
import { z } from 'zod/v4';
const pointSchema = z.object({ x: z.number(), y: z.number() });
const line = zecs.component(
'line',
z.object({ a: pointSchema, b: pointSchema }),
);
const drawLines = zecs.system({
name: 'drawLines',
query: zecs.query().has(line),
updateParams: z.object({
ctx: z.custom<CanvasRenderingContext2D>(),
}),
onPreUpdate({ updateParams: { ctx } }) {
ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
ctx.save();
ctx.strokeStyle = 'red';
},
onUpdated({ entity: { line }, updateParams: { ctx } }) {
ctx.beginPath();
ctx.moveTo(line.a.x, line.a.y);
ctx.lineTo(line.b.x, line.b.y);
ctx.stroke();
},
onPostUpdate({ updateParams: { ctx } }) {
ctx.restore();
},
});
const lineEcs = zecs.ecs([line]);
const canvas = document.getElementById('canvas') as HTMLCanvasElement;
const ctx = canvas.getContext('2d');
if (!ctx) {
throw new Error('Failed to get canvas context');
}
const drawLinesHandle = await zecs.attachSystem(lineEcs, drawLines, {
ctx,
});
drawLinesHandle.update({ ctx });a system can also have resources--both shared and for each entity:
// docs/062-system-resources.ts
import { zecs } from 'zecs';
import { z } from 'zod/v4';
import { position } from './010-component';
import { ecs } from './030-ecs';
// pixi.js stubs
declare class Asset {}
declare const Assets: { load(src: string): Promise<Asset> };
declare class Sprite {
position: { x: number; y: number };
constructor(p: { texture: Asset; position: { x: number; y: number } });
destroy(): void;
}
const drawSprites = zecs.system({
name: 'drawSprites',
query: zecs.query().has(position),
initParams: z.object({
texturePath: z.string(),
}),
shared: {
async create({ initParams: { texturePath } }) {
const texture = await Assets.load(texturePath);
return { texture };
},
},
each: {
create({ shared: { texture }, entity }) {
const sprite = new Sprite({
texture,
position: { x: entity.position.x, y: entity.position.y },
});
return { sprite };
},
destroy({ each: { sprite } }) {
sprite.destroy();
},
},
onUpdated({ each: { sprite }, entity }) {
sprite.position.x = entity.position.x;
sprite.position.y = entity.position.y;
},
});
const drawSpritesHandle = await zecs.attachSystem(ecs, drawSprites, {
texturePath: './texture.png',
});
drawSpritesHandle.update({});shared resources get created when the system is attached to an ECS. in most cases, this is just once.
each resources are created for each entity that matches the query. they persist as long as it keeps matching, and then they get destroyed.
you can attach an individual system to an ECS and update it by hand, but what if you have a lot?
sure can be tedious to juggle a bunch of system update()s.
schedules take a list of systems and give you a handle to update all of them at once (in a strongly-typed fashion, of course.)
// docs/070-schedule.ts
import { zecs } from 'zecs';
import { z } from 'zod/v4';
import { position, velocity } from './010-component';
const gravitySystem = zecs.system({
name: 'gravity',
query: zecs.query().has(position, velocity),
updateParams: z.object({ dt: z.number() }),
onUpdated({ entity, updateParams }) {
entity.velocity.y -= 9.81 * updateParams.dt;
},
});
const kinematicsSystem = zecs.system({
name: 'kinematics',
query: zecs.query().has(position, velocity),
updateParams: z.object({ dt: z.number() }),
onUpdated({ entity, updateParams }) {
entity.position.x += entity.velocity.x * updateParams.dt;
entity.position.y += entity.velocity.y * updateParams.dt;
},
});
const scheduleEcs = zecs.ecs([position, velocity]);
const schedule = await zecs.scheduleSystems(
scheduleEcs,
[gravitySystem, kinematicsSystem],
{},
);
schedule.update({ dt: 0.016 });Footnotes
-
that's what i use it for, so ymmv ↩