About

@nanoforge-dev/ecs is NanoForge's built-in entity-component-system library, backed by a WebAssembly registry (compiled from C++). It ships two subpath entry points — @nanoforge-dev/ecs/client and @nanoforge-dev/ecs/server — each loading its own WASM build (browser-targeted vs Node-targeted) behind the same EcsLibrary API, so a client bundle never pulls in the server build or vice versa. The root entry point, @nanoforge-dev/ecs, only exposes the shared types (Registry, Component, System, Entity, SparseArray, Context, EcsContextApi) and pulls in no WASM binary, so it's safe to import from code that targets both client and server.

Installation

Node.js 26 or newer is required.

npm install @nanoforge-dev/ecs
yarn add @nanoforge-dev/ecs
pnpm add @nanoforge-dev/ecs
bun add @nanoforge-dev/ecs

Example usage

Register EcsLibrary from the entry point matching your app:

// Client app
import { EcsLibrary } from "@nanoforge-dev/ecs/client";

app.use(new EcsLibrary());

// Server app
import { EcsLibrary } from "@nanoforge-dev/ecs/server";

app.use(new EcsLibrary());

Shared types like Registry, Component, and System are available from the root entry point, regardless of which platform you're targeting:

import type { Component, Context, Registry, System } from "@nanoforge-dev/ecs";

const Position: Component = { name: "Position" };

const gravity: System = (registry: Registry, ctx: Context) => {
  // ...
};

Once registered, Context.ecs.registry gives every other library access to the entity/component registry:

public override async __run(ctx: Context): Promise<void> {
  const entity = ctx.ecs.registry.spawnEntity();
  ctx.ecs.registry.addComponent(entity, new Position(0, 0));
}

Register systems to run on every tick:

ctx.ecs.registry.addSystem((registry) => {
  for (const { __RESERVED_entityId, Position } of registry.getZipper([
    { name: "__RESERVED_entityId" },
    { name: "Position" },
  ])) {
    // Move things around.
  }
});

When registered alongside @nanoforge-dev/editor's EditorLibrary, EcsLibrary also listens for a "hot-reload" command from the editor and applies incoming components via registry.addComponent — useful for live-editing entity state from an external editor host.

Links

• GitHub
• npm

Contributing

Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the documentation.
See the contribution guide if you'd like to submit a PR.

Help

If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle nudge in the right direction, please don't hesitate to ask questions in discussions.