REST Explorer API

The REST addon is intended for editor and explorer tooling. Enable it when creating the world:

C

ecs_with_features({ .rest = true });

C++

ecs_world_feat_desc_t features{ .rest = true };
ecs::init(features);

The server listens on port 4040 and is polled by ecs_progress() when the feature is enabled.

Routes

Route	Purpose
GET /health	Returns OK when the server is reachable.
GET /schema	Lists reflected component schemas and editor field types.
GET /entities	Lists root entities and entities without a parent.
POST /entities	Creates a new entity and returns its list item payload.
GET /entities/:index	Returns one entity detail by entity index.
GET /entities/:index/children	Returns direct children for an entity index.
PUT /entities/:index/components/:component	Replaces one reflected component value on an entity.

Entity Explorer

The entity routes expose tree-friendly data for an editor:

Entity list items are intentionally small:

type EntityListItem = {
  name: string;
  index: number;
  generation: number;
  hasChildren?: boolean;
};

Entity detail adds parent, inherited base, children, and reflected component values when they exist:

type EntityDetail = EntityListItem & {
  parent?: EntityListItem;
  isA?: EntityDetail;
  children: EntityListItem[];
  components: EntityComponent[];
};

Component Schema

The schema routes are for editor forms. They describe reflected components and fields using compact type information rather than dumping reflection internals:

type Schema = {
  components: Component[];
  types: EditorType[];
};

type ComponentField = {
  name: string;
  type: number;
};

type Component = {
  id: number;
  name: string;
  isRelation: boolean;
  type: number;
  fields: ComponentField[];
};

type EditorType = {
  id: number;
  name: string;
  editor: "boolean" | "number" | "object" | "string" | "entity" | "unsupported";
};

Unreflected components are not editable from the explorer because the server does not know their field layout.

Entity detail serializes reflected component values with the component id and component name:

type EntityComponent = {
  id: number;
  name: string;
  value: unknown;
};

Mutating Component Values

Component mutation is component-level: the client submits the full component value for one entity and one component. This keeps the server simple and avoids partial-update ambiguity for structs.

The update route accepts the full JSON value for the reflected component:

PUT /entities/12/components/4
Content-Type: application/json

{ "x": 10, "y": 20 }

Editor clients should fetch /schema, fetch /entities/:index, render form controls from reflected field types, then submit the full component value after editing.

Production Notes

The REST addon is a development/editor feature. Do not expose it on an untrusted network without authentication, routing restrictions, or a separate proxy layer.