REST Explorer API

The REST addon is an independent Bake package intended for editor and explorer tooling. Add siecs_rest to the application and import it explicitly:

C

#include <siecs.h>
#include <siecs_rest.h>

int main(void) {
    ecs_init();
    ECS_MODULE_IMPORT(SiecsRest, { .port = 4040 });
    ecs_progress();
    ecs_fini();
}

C++

#include <siecs/cpp.hpp>
#include <siecs_rest.h>

ecs::init();
ECS_MODULE_IMPORT(SiecsRest, { .port = 4040 });

The default port is 4040; the server listens on the configured port and is polled by ecs_progress() while the imported module is enabled. The package owns the server lifetime and stops it when the world is finalized.

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 under the value property:

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

{ "value": { "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 tooling feature for inspectors and editors. Do not expose it on an untrusted network without authentication, routing restrictions, or a separate proxy layer.