ARCANUM
Guide ยท ecs

The registry and the schedule

Everything a server::Game keeps its world in is an ecs::Registry, run by an ecs::Schedule. Here they are on their own: use them from inside a Game, or build a server with no Game at all.

Where the registry sits

A server::Game owns one ecs::Registry (registry()), one ecs::Schedule (schedule()) and one ecs::Interest (interest()). Everything the other pages call a row, a view or a player ends up as entities and components in that registry. spawn(...), get<Row>(e) and view<Row>() on the Game are short forms of calls on it.

You reach for the registry itself when you want to walk many entities in one loop, react to a component being added or removed, destroy entities while looping, keep server-only state in a singleton, or run your own systems at their own rate. You can also use it with no Game at all; the last sections of this page show how a world is assembled from the pieces.

The examples use meadow: the rows Walker {x, y, speed} and Purse {owner, gold} from meadow.aether. To read them in a standalone program, include the generated header and <aether/ecs.h>:

a standalone program
#include <aether/ecs.h>
#include <meadow/Messages.h>     // generated from meadow.aether

using namespace aether;
using meadow::Walker;
using meadow::Purse;

ecs::Registry registry;
One thread. A Registry and everything made from it (queries, rows, handles, the Interest, the Schedule) belong to one thread, the world thread. Nothing here is thread safe. From another thread, hand the work to the world with Game::post(fn).

A Registry is neither copyable nor movable, and it must outlive everything made from it: an Interest must not outlive its Registry and every client must be detached before it is destroyed; a Persistence is destroyed before the Registry.

Entities

An entity is only an id. You get one from create(), put components on it, and give it up with destroy().

const ecs::Entity ayla = registry.create();
registry.alive(ayla);          // true
registry.entityCount();        // 1

registry.destroy(ayla);        // removes all its components and view rows
registry.alive(ayla);          // false
registry.destroy(ayla);        // fine: destroying a dead entity does nothing

An ecs::Entity is a 64-bit id: the low 32 bits are a slot, the high 32 bits the slot's generation. When a slot is reused for a new entity its generation is larger, so a stale id of the old entity never matches the new one. Generation 0 is never alive.

It prints as slot:generation (std::format("{}", e), or ecs::toString(e)): the first entity created is 0:1, and a new entity in the same slot after a destroy is 0:2. Two helpers are for entity members of rows: ecs::kNoEntity is the "none" value, and ecs::isSet(e) is false for it and for Entity{}, which is what an Entity member of a row holds until someone sets it. isSet says nothing about whether the entity still exists: that is registry.alive(e).

To make many at once, create(n, out) appends n new entities to a vector in one reservation instead of n calls:

std::vector<ecs::Entity> herd;
registry.create(100, herd);     // appends 100 ids to herd
Trap. Entity ids do not survive a restart, and an Entity member of a row is not saved by a persisted component. Save the other entity's key, not its id (see saving).

Registering components

A component is a kind of row an entity may have, at most one of each kind. Before you can add one you register it with the registry, which gives you a small handle (copy it freely). There are three kinds, and the data page says what each is for. Here is how each is registered:

KindRegister withThe handleUse it for
Flat structregistry.component<S>()ecs::Typed<S>rows that are sent, saved or both: a plain struct of fixed-size members. The row is stored as the struct itself.
Hand-built typeregistry.component(Type)ecs::Componenta layout known only at run time, and tags (a type with no fields). Rows are read and written through Field handles.
Localregistry.local<T>()ecs::Local<T>any movable C++ type that stays on the server (a map, a pointer, a navigation mesh). Never sent, never saved.

Both Typed<S> and Local<T> convert to ecs::Component, so every call that takes a Component takes them too (add, remove, has, destroy, none, any, group, the hooks).

const auto walker = registry.component<Walker>();    // a flat struct; named "Walker"
const auto purse  = registry.component<Purse>();

// a type with no fields is a tag
const auto sleeping = registry.component(ecs::Type::define("sleeping").build());

// anything movable, kept on the server
struct Notes { std::string text; };
const auto notes = registry.local<Notes>();

Names are unique: a component (or view) named like an existing one throws std::invalid_argument: ecs::Registry: a component or view named 'character' exists. A struct component is named after its struct without the namespace, so two structs both called Hero in different namespaces clash (the error names both).

reserveRows (default 1024) is how many rows to allocate up front; the buffer doubles when full. It is an optimisation, not a limit:

const auto cargo = registry.component(ecs::Type::define("cargo").uint32("kg").build(), 4096);   // room for 4096 rows before the first growth

Look a component up by name with registry.findComponent("Walker"), which returns std::optional<ecs::Component> (empty if there is none). A component has id() (dense, from 0, in registration order) and type() (its ecs::Type).

Local components have three rules the compiler checks: the type must be movable, its move constructor and destructor must be noexcept (the registry moves objects when its storage grows), and alignof at most 64. std::map, std::vector, std::string, std::shared_ptr and std::unique_ptr all qualify. registry.local<T>() a second time returns the same handle. A local component never survives a restart and cannot be persisted or selected into a view; show part of it with a function view (data, views).

Adding, reading and removing components

Give an entity a component with add, which for a flat struct takes the value:

registry.add(ayla, walker, Walker{0, 0, 60});        // returns a Walker&
registry.has(ayla, walker);                            // true
Walker& w = registry.get(ayla, walker);              // the struct itself, in the buffer
w.x += 5;                                              // change it in place: nothing to write back

add(e, handle) with no value adds a zeroed row. get gives a reference to the row in the component's buffer; tryGet gives a pointer, or nullptr if the entity does not have it; has is a bool; remove takes the component away and does nothing if there was none.

if (Walker* w = registry.tryGet(ayla, walker)) w->speed = 30;
registry.remove(ayla, walker);
registry.remove(ayla, walker);                         // no-op

What goes wrong is reported by exception, with a message that says what to do:

CallWhen it throwsMessage
addthe entity already has the componentecs::Registry::add: the entity already has 'Walker' (std::logic_error)
addthe entity is deadecs::Registry::add: entity 0:1 is dead (it was destroyed, or it is from another registry): use an entity from create() that has not been destroyed
getthe entity is dead or has noneecs::Registry::get: entity 2:1 has no 'Purse': add it first, or use has(e, handle) / tryGet(e, handle) (for a dead one: ... is dead and has no 'Walker': ...)

Local components have the same calls with the same names, and the reference is to the object itself:

registry.add(ayla, notes, Notes{"likes the pond"});       // Notes&
registry.get(ayla, notes).text += "!";
const Notes* n = registry.tryGet(ayla, notes);            // nullptr if it has none
References move. The Walker& from get (and every Row, ConstRow, S&, T& and pointer from a query) is valid only until an entity gains or loses that component, or, if the component is in a group, another component of the group. Rows of other entities move when one is added or removed. Do not keep a reference across such a call or across ticks; ask again.

Row and ConstRow: a row without the struct

A hand-built type has no struct, and you sometimes want to touch a flat component through its fields without copying the whole struct. For that there are ecs::Row (read and write) and ecs::ConstRow (read only). Get one from registry.get(e, component) with a plain ecs::Component (a typed handle picks the struct overload, so convert it: ecs::Component(walker)). The result is false (operator bool) if the entity is dead or has no such component.

ecs::Row row = registry.get(ayla, ecs::Component(walker));
if (row) {
    row.set(&Walker::x, 5.0);                  // a member pointer names the member
    double x = row.get(&Walker::x);
    Walker whole = row.get<Walker>();          // or the whole struct
    row.set(Walker{1, 2, 60});
}

A member pointer path reaches into nested structs, and an index goes into a std::array or aether::List: row.get(&Hero::position, &Vec2::x), row.set(&Hero::hp, 5), row.get(&Hero::hotbar, 2). set returns the row, so sets chain. For a hand-built type you use a Field<T> handle looked up once from the type (runtime types): row.set(posX, 1.0).

Reading never marks anything dirty: a row that is read is not saved or sent. A row is sent or saved when its bytes differ from what was last sent or saved; a write that leaves it byte-identical is not a change.

Which form of every call you get per kind, at a glance:

CallFlat struct (Typed<S>)Hand-built (Component)Local (Local<T>)
add(e, c, value)S&(bytes: add(e, c) returns a Row)T&
add(e, c)zeroed S&zeroed Rowdefault-constructed T&
get(e, c)S&Row (false if none)T&
tryGet(e, c)S*(use get and test the row)T*
has, removeall kinds

A persisted component is added with its key, add(e, c, key), and loaded from a store record with load; both are covered on the saving page and listed in the reference below.

Next: walking many entities at once.

Queries

A query names the components an entity must have and a callback receives the rows of each entity that has them all. It is the one loop you will write most.

registry.query(walker, purse).each([](ecs::Entity e, Walker& w, Purse& p) {
    if (w.x > 100) p.gold += 1;      // an entity with both a Walker and a Purse
});

Notice that the callback takes the entity first, then one parameter per required component in the order you listed them. What each parameter is depends on the component's kind and on how you wrote the argument:

ArgumentFlat structHand-built typeLocalSelects entities?
cS&ecs::RowT&must have it
ecs::read(c)const S&ecs::ConstRowconst T&must have it
ecs::optional(c)S* (null if none)ecs::Row (false if none)T* (null if none)no
ecs::optional(ecs::read(c))const S*ecs::ConstRow (false if none)const T*no
ecs::none(c, ...)no parameterhas none of these
ecs::any(c, ...)no parameterhas at least one of these; each any() is required on its own

Here is a query that uses every clause. It visits the walkers that are not sleeping, reads their purse if they have one, and skips ones that carry notes:

registry.query(walker,
               ecs::optional(ecs::read(purse)),     // const Purse* (null if none)
               ecs::none(sleeping))                 // no parameter
    .each([](ecs::Entity e, Walker& w, const Purse* p) {
        w.speed = p && p->gold > 100 ? 80 : 60;
    });

registry.query(ecs::read(walker), ecs::any(sleeping, ecs::Component(purse)))   // at least one of the two
    .each([](ecs::Entity, const Walker&) {});

Some rules, each enforced:

  • A query needs at least one required component (a plain one or read): the walk goes over the required components, and optional, none and any only test or look up per entity. With none it does not compile: ecs::Query needs at least one required component ....
  • A component may appear in a query once, in one place. Twice throws std::invalid_argument: ecs::Registry::query: 'Walker' is in the query twice. A null component, or one from another registry, throws the same type.
  • The callback must be callable as fn(ecs::Entity, rows...), one parameter per required and optional component in the order listed (none and any add none). Otherwise a static_assert says so at compile time.
  • The order of the entities visited is the storage order of the walked component, not stable across removals. Do not rely on it.

query(...) is cheap to make and may be kept in a variable and reused. Two more calls on it:

auto walkers = registry.query(walker);
walkers.count();       // how many entities each() would visit now
walkers.sizeHint();    // the smallest required component's size: an upper bound on what each() visits

count() is O(1) for a query of one component, or of exactly the members of a group, with no none or any; otherwise it walks without calling anything.

How a query walks

Only the required components decide the cost. With one required component the walk goes forward over its rows. With several (a join) it walks the smallest one and looks the entity up in the others. If the query holds every component of a group, it walks the group's first rows, where all members agree on the entity, with no lookup, when that is the shorter walk. none and any cost a few bit tests on the entity's has-bits (no pool is looked up) and an optional component one lookup when the entity has it.

Tip. For a tight loop over rows, take field handles into local variables first: a lambda that reads them through this or a reference must load them again after every store into a row. Query::each inlines your callback into its loops.

Next: what you may and may not do to the registry while a query is walking.

Changing things while a query walks

Adding or removing a component moves rows in the pool you are walking. So inside each, a structural change to a required or optional component of the running query (or to a component in the same group as one) throws std::logic_error:

registry.query(walker).each([&](ecs::Entity e, Walker&) {
    registry.remove(e, walker);     // throws: ecs::Registry::remove: 'Walker' is in a running query
});
registry.query(walker).each([&](ecs::Entity e, Walker&) {
    registry.destroy(e);            // throws: ecs::Registry::destroy: the entity has a row in a component of the running query
});

Put such changes in the defer family. They run when the outermost each returns, in the order you made them. Called outside any each, they run at once.

registry.query(walker, purse).each([&](ecs::Entity e, Walker& w, Purse& p) {
    if (p.gold > 1000) registry.deferAdd(e, sleeping);           // add a component
    if (w.x < -500)    registry.deferRemove(e, purse);           // remove one
    if (w.y > 9000)    registry.deferDestroy(e);                 // destroy the entity
    if (w.speed < 0)   registry.defer([&] { registry.add(e, notes, Notes{"stuck"}); });   // anything else
});
CallWhat it does when applied
defer(std::function<void()>)runs the function
deferAdd(e, c, row = {})the effect and the exceptions of add at that moment. row, if not empty, must have the component's blockLength bytes and initialises the new row; it is copied when deferred. Local components take no bytes: deferAdd(e, handle) makes a default object, deferAdd(e, handle, value) a given one.
deferRemove(e, c)as remove
deferDestroy(e)as destroy

The simple forms are recorded as plain data in a buffer that keeps its capacity, so once it is warm they allocate nothing; defer(fn) stores a std::function. A deferred change is applied with the exceptions of the real call at that time, and it fires hooks then. If the each is left by an exception, the deferred changes are dropped (verified: a deferDestroy followed by a throw destroyed nothing).

What a query does not lock

A component the query only names in none() or any() is not locked. A callback may add or remove it directly, and an entity the walk has not reached yet is judged by the new state; the entity of the current call and those already visited are not revisited.

registry.query(walker, ecs::none(sleeping)).each([&](ecs::Entity e, Walker& w) {
    if (w.speed == 0) registry.add(e, sleeping);       // fine: sleeping is only in none()
});

Adding a component that is not in the query at all is also fine. Adding purse in an each over walker is allowed unless the two are in one group (the error then says 'Purse' is in a running query).

Trap. registry.commit(...) inside each throws ecs::Registry::commit: called inside Query::each. Event emit is the one registry call here that is always allowed inside each (events).

Hooks: reacting to a component coming and going

Sometimes a rule belongs to the component and not to the code that adds it: a walker that falls asleep drops its speed to 0 wherever it was put to sleep; a purse that is taken away is logged. A hook is a function the registry runs for you.

registry.onAdd(sleeping, [&](ecs::Entity e, ecs::Row) {
    if (registry.has(e, walker)) registry.get(e, walker).speed = 0;
});
registry.onRemove(purse, [](ecs::Entity e, ecs::ConstRow row) {
    std::println("{} loses a purse of {}", e, row.get(&Purse::gold));
});
registry.onDestroy([](ecs::Entity e) { std::println("{} is gone", e); });

Notice that the hook for a flat struct component receives an ecs::Row (or ConstRow for removal), not the struct: use row.get(&Purse::gold) or row.get<Purse>(). For a local component the hooks give the object, fn(Entity, T&), for both onAdd and onRemove.

The contract

HookRunsThe row
onAdd(c, fn(Entity, Row))after add, after deferAdd when it is applied, and after load put a new row of c on the entityhas its initial bytes (zero, the deferAdd bytes, the persisted key, or the loaded record). load over an existing row is not an add.
onRemove(c, fn(Entity, ConstRow))before remove (or deferRemove, when applied) takes the row, and, for every component the entity has, before destroy takes anythingstill there
onDestroy(fn(Entity))once, at the start of destroy, with every component still in place(none)
  • Hooks run on the world thread, at once, in registration order (a component's onAdd hooks in the order they were registered; likewise onRemove and onDestroy).
  • A hook has no effect on rows that exist when it is registered.
  • create() has no hook (a new entity has no component). Hooks of add run for each component added to the entities of a bulk create(n, out).
  • A change made inside each is deferred, so its hooks run when it is applied.
  • A hook may change other components and entities, and destroy other entities. It must not rely on a Row it was given after changing a component of the same group.
  • A registry with no hooks and no persisted component pays nothing for them: add, remove and destroy test the one flag that persistence already had.

Errors

  • A hook that adds or removes the component it is hooked on (on any entity, also by destroying an entity that has it) throws std::logic_error at that call: ecs::Registry::remove: a hook of 'Walker' changes the component it is hooked on.
  • Registering a hook throws std::invalid_argument for an empty function (ecs::Registry::onAdd: the function is empty) or a component of another registry, and std::logic_error inside a hook.
  • An exception thrown by a hook propagates out of the call that ran it. For onAdd the row has been added already (verified: after the exception above, has was still true). For onRemove and onDestroy nothing has been taken away yet, so the throw cancels the remove or destroy (for destroy: the hooks that ran before the throwing one have run).

Next: speeding up a hot join.

Groups: components walked together

A join walks the smallest component and looks the entity up in the others. If two components are almost always walked together (every walker with a purse, say), a group keeps their rows in the same order, so a query over both walks them forward with no lookup, like an EnTT owning group.

ecs::Registry zone;
const auto w = zone.component<Walker>();
const auto p = zone.component<Purse>();
zone.group(w, p);                    // right after registering, before any entity has a row

The invariant: the first n rows of every member are the same n entities in the same order, and those are exactly the entities that have every member; behind them each member holds the entities that lack another member. Nothing else about the order of rows is promised.

What it costs

  • add(e, c) of a member costs, besides the normal add, one lookup in each other member; when e thereby has every member, its rows are swapped into position n in all of them (members times 2 row swaps).
  • remove(e, c) of a member, or destroy(e), when e has every member, costs the same swaps, moving its rows out of the first n before they are erased. An entity that lacks a member pays the normal cost.
  • A query over a subset of the members is a plain join (no gain). A query over members plus other components walks the group's first rows and looks the others up. Both are correct; the order of entities visited differs from a registry without the group.
  • A group is for components walked far more often than they are added and removed.
Row validity. A Row of a member is valid until an entity gains or loses that member or another member of its group. Structural changes to any member of a group inside a Query::each over any member throw std::logic_error, like those of the walked component: with w and p grouped, add(e, p) in an each over w throws ecs::Registry::add: 'Purse' is in a running query.

Errors

group throws std::invalid_argument for fewer than two components (this does not compile for the variadic form: it needs at least two), a component twice (ecs::Registry::group: 'Walker' is given twice), a null component or one of another registry. It throws std::logic_error if a component is already in a group (... 'Walker' is in a group already; a component is in at most one group), already has rows (... 'Walker' has rows already), or the call is inside Query::each.

A second form takes a span: group(std::span<const ecs::Component>), for a list built at run time.

Singletons

Some state is not about any entity: the weather, the round clock. A singleton is one zeroed row that belongs to the registry. It has no add, no entity and no query; you get its row from its handle.

const ecs::Type weatherType = ecs::Type::define("weather").uint32("rain").build();
const ecs::Singleton weather = registry.singleton(weatherType);
const auto rain = weather.field<std::uint32_t>("rain");

weather.row().set(rain, 3);
const std::uint32_t now = weather.constRow().get(rain);
  • registry.singleton(type) throws std::invalid_argument if a singleton of that type name exists (ecs::Registry::singleton: a singleton named 'clock' exists). Singletons, events and components are separate name spaces.
  • The row is zeroed once and lives as long as the registry: a Row of it never moves, and nothing outside the owner changes it. Handles are copies of one pointer.
  • It is not a component: no query, view or persistence reaches it, and it is not persisted. The type may be a tag (no fields); the row is then empty.

Events between systems

An event is a row that one system emits for the systems after it, and the next commit throws away. Use it when a rule should say "this happened" without the other rules having to find out by walking.

const ecs::Type coinType = ecs::Type::define("coin").uint64("who").uint32("amount").build();
const ecs::EventType coin = registry.event(coinType);
const auto who = coin.field<std::uint64_t>("who");
const auto amount = coin.field<std::uint32_t>("amount");

// one system emits (allowed inside Query::each) ...
registry.emit(coin).set(who, static_cast<std::uint64_t>(ayla)).set(amount, 5);

// ... the systems after it read, in emission order
for (ecs::ConstRow c : registry.events(coin)) std::println("{} gets {}", c.get(who), c.get(amount));
registry.events(coin).size();     // how many so far this tick
registry.events(coin).empty();
  • registry.event(type) registers an event type; a duplicate name throws std::invalid_argument.
  • emit(event) appends a zeroed row and returns it as a Row to fill in. That Row is valid until the next emit of the same event (the buffer may grow: it doubles, and keeps its capacity, so a warm registry allocates nothing per emit). A tag type is a count only.
  • events(event) is a range of ConstRow in emission order. Its iterators stay valid when more is emitted (they index the buffer), but a Row they gave out does not.
  • emit is allowed inside Query::each: events are not components, so emitting moves no row.
  • An event or singleton handle of another registry throws std::invalid_argument when used.

When are they thrown away? At commit: registry.commit(...) empties every event buffer, once it has succeeded (a commit that throws leaves them). So a system sees the events of the systems that ran before it in the same tick, and none from the systems after it in this tick. Order the systems in the schedule accordingly (schedule). Verified: after one emit, events(e).size() is 1; after the next commit it is 0.

Trap. Events here stay inside the server. They are not messages to players: to tell a player something, send(player, Msg{...}) on the Game (server).

The commit: one clock for everything

Once per tick, after your systems, you say "the world is now like this": registry.commit(stamp, nowMs). It builds every view row from the components as they are now and stores it in the view's history under stamp, clears the event buffers, and tells the registry what time it is.

registry.commit(stamp, nowMs);           // once per tick, after the systems
interest.send();                         // no time argument: it reads the one the commit was given
ParameterMeaning
stamp (ecs::Stamp, int64)the number of this commit: a tick counter or a time, as you choose. Each commit must pass a larger one than the last.
nowMs (int64)a time in milliseconds on your clock; it must not go backwards. It is "the one clock": Interest::send() and handle(), Persistence::collect() and RuneStore::poll() with no time argument read it from the last commit.

What it throws

  • std::logic_error if stamp is not larger than the last: ecs::Registry::commit: the stamp must increase: commit(5) after the last commit(5). Pass a larger one each time (a tick counter you increment).
  • std::logic_error if called inside Query::each: ecs::Registry::commit: called inside Query::each.
  • std::logic_error if a persisted component exists and no Persistence is attached: ecs::Registry::commit: persisted components have no Persistence attached: 'Purse' (saving).

With no time, and what you can read back

commit(stamp) is the explicit form with no time. The calls that normally read the registry's time then need it as an argument (interest.send(nowMs)), and the no-argument forms throw std::logic_error: ecs::Registry::lastCommitMs: the last commit had no time. Say the time once at the commit, registry.commit(tick, nowMs), or pass it to the call that asked for it (for example interest.send(nowMs)). lastCommit() is the last stamp (0 before the first). lastCommitMs() is the time given to the last commit(stamp, nowMs); it throws if there was none yet or the last commit had no time.

Change stamps

For each subscribable view row, the commit also keeps a change stamp per entity slot: the commit at which the row appeared or one of its delta fields differed from the previous commit (one compare per row in the build pass). Interest uses it to skip entities that did not change. A write that leaves the row byte-identical is not a change. How views are declared is on the views page.

In a Game you never call commit: the tick does it (WorldProcessor::tickNumber() is the stamp, always larger than the last, and nowMs() the time).

Errors that cannot be thrown

A problem the registry cannot throw (today: a function view that threw, ecs::View 'name': the function threw for entity 3:1 (what); its row is left out of the view until it stops throwing) goes to the function you give registry.onError(fn(const std::string&)). The default is one line on stderr prefixed aether: . Each problem is reported once, not at every commit.

registry.onError([](const std::string& message) { std::println(stderr, "ecs: {}", message); });

The schedule: systems in order, at their own rate

A tick runs many rules: read the inputs, move the walkers, grow the grass, then publish. A Schedule names these steps, runs them in a fixed order and keeps the tail of the tick (commit, send, persistence) in the right place.

ecs::Schedule schedule(registry);
schedule.phase("input").phase("simulate").phase("late");
schedule.system("movement", "simulate", [&](const ecs::Tick& t) { /* uses t.sinceLastRun */ });
schedule.system("grass", "simulate", [&](const ecs::Tick&) { /* ... */ }).every(4);          // every 4th tick
schedule.system("regen", "simulate", [&](const ecs::Tick&) { /* ... */ }).every(std::chrono::seconds(1));

schedule.run(stamp, nowMs);          // once per tick

What one run does

  1. The phases in the order declared, in each the systems in the order added; a system that is not due is skipped.
  2. registry.commit(stamp, now).
  3. The systems of the built-in phase "send" (so they see the views of this commit), in the order added.
  4. persistence.collect(now), if schedule.persist(persistence) was called.
  5. The afterSend hooks, in the order added.

The tail is fixed: a system added to "send" runs after the commit, the others before it. "send" always exists, comes after every phase and cannot be declared again. Here is what a run printed in a test with systems in input, simulate (one with every(2), one every(100ms)) and send: runs 1, 3 and 5 ran the every(2) system, and the send system saw registry.lastCommit() equal to the stamp of the run.

Rates

The last every call on a system wins; with no rate a system runs every tick.

  • every(n): runs on its first tick, then on every n-th run() after the run it last ran in (n >= 1; every(1) is every tick). A run() counts once it is past the stamp check, even if a system of it throws.
  • every(duration): runs on its first tick, then at the first run() whose now has reached its due time; the due time then advances by the interval, so the average rate holds whatever the tick length. It does not run twice to catch up after a stall: if the due time is still in the past after advancing, the next one is now plus the interval. The duration is rounded down to milliseconds and must be at least 1 ms.

The system receives an ecs::Tick: stamp and now as given to run(), sinceLastRun (the now of its previous run subtracted from this one, in ms; 0 on its first run) and runCount (runs of this system including this one; 1 on the first). A system with a rate wants t.sinceLastRun as its time step, not a fixed one.

The schedule never reads a clock for scheduling: now is the caller's (it must not go backwards). It reads std::chrono::steady_clock only to time each system for stats().

Persistence and the end of the tick

schedule.persist(persistence) adds persistence.collect(now) after the send systems (the Persistence must outlive the schedule's runs). schedule.afterSend(fn(Stamp, std::int64_t)) runs at the end of the tick, after the collect: where RuneStore::poll() goes.

Errors

ExceptionWhen
std::invalid_argumenta system added to an unknown phase (ecs::Schedule::system: 'z': unknown phase 'nope'), a duplicate system name (... a system named 'a' exists), a duplicate phase name, also "send" (... a phase named 'send' exists), an empty name (... the name is empty) or function (... 'y' has no function), every(0) (ecs::Schedule::every: zero ticks) or a duration below 1 ms (... the interval is below 1 ms)
std::logic_errorsystem(), phase(), persist() or afterSend() while run() is running (a system must not change the schedule); run() called from a system; a stamp not larger than registry.lastCommit() (ecs::Schedule::run: the stamp must increase: run(5, ...) after the last commit(5). ...), checked before any system runs, so a bad stamp runs nothing

A system that throws: the exception propagates out of run() at once. The rest of the tick is not run: the later systems, registry.commit(stamp), the send systems, persistence.collect and the afterSend hooks are all skipped. The throwing system's run is counted in the stats; the schedule is usable for the next run() (the caller decides whether to retry the same stamp: nothing was committed). In a Game or a WorldProcessor server the exception reaches Options::onError and the world carries on.

Trap. A throw before the commit means this tick's views were not built and nothing was sent. A bug in one system therefore silences the whole tick, not just that system.

Timing your systems

for (const ecs::SystemStats& s : schedule.stats())
    std::println("{} ({}): last {} ns, longest {} ns, {} runs", s.name, s.phase, s.lastNs, s.maxNs, s.runs);
schedule.resetStats();         // zero them; the rates are untouched

stats() lists the systems in the order they were added; a system skipped by its rate does not count. The span is valid until a system is added. No allocation happens in run() once the schedule is built.

In a Game

A server::Game has built the schedule already: phases "input" (runs inputs().run()) and "simulate" (runs your update(dt)), then the commit, the "send" phase (interest.send()), and an afterSend that flushes queued messages and saves changes. Add your own phase after "simulate" and your own systems:

examples/walker/Variants.h
schedule().phase("world");                                      // after "simulate"
schedule().system("bounds", "world", [this](const aether::ecs::Tick&) {
    registry().query(componentOf<Walker>()).each([](aether::ecs::Entity, aether::ecs::Row row) {
        Walker w = row.get<Walker>();
        w.x = std::clamp(w.x, -1000.0, 1000.0);
        row.set(w);
    });
});

Notice componentOf<Walker>(): it is the Game's way to the ecs::Component of a row struct, so the query hands you an ecs::Row.

Runtime types

A struct is the usual way to say what a row holds. When the layout is only known at run time (a tool, a bridge, a generic container), or you want a tag, you build an ecs::Type. The three component kinds are described on the data page, and its runtime Type section teaches this builder step by step; here it is in short, with the full reference at the end of this page.

const ecs::Type character = ecs::Type::define("character")
    .uint64("characterId").key()
    .uint64("userId")
    .string("name", 16)
    .uint16("hairSheet")
    .build();

const auto name = character.field<std::string_view>("name");     // look a field up once
const auto hair = character.field<std::uint16_t>("hairSheet");

const auto chars = registry.component(character);
const ecs::Entity e = registry.create();
registry.add(e, chars).set(name, "Ayla").set(hair, 3);
  • Fields are packed little-endian in declaration order with no padding: a row is the fixed block of a rune record. blockLength() is the size of a row in bytes.
  • The field types are rune's fixed-size ones. Variable-length fields (rune's string and bytes) are not allowed: a row has one size.
  • Each field has a durable tag and a sinceVersion; fingerprint() is rune's fingerprint of the equivalent descriptor (FNV-1a-64 over the name and, per field in tag order: tag, type, sinceVersion, key flag, name, enum values and, for a string, its width).
  • A type with no fields is a tag: Type::define("sleeping").build() has blockLength 0. As a component it stores the entity list only (add returns a Row that must not be read or written); it has no key, so it cannot be persisted, and it cannot be a source of a view. Use it in queries (required, none, any).

The field types of the Prim enum, with the C++ type a Field<T> reads and writes (the builder method is in the reference):

PrimValueBuilder methodC++ type of Field<T>Width
Int320int32(name)std::int32_t4
Int641int64(name)std::int64_t8
UInt162uint16(name)std::uint16_t2
UInt323uint32(name)std::uint32_t4
UInt644uint64(name)std::uint64_t8
Float645float64(name)double8
Bool6boolean(name)bool1
Enum7enumeration(name, allowed = {})std::int32_t4
FixedStr10string(name, bytes)std::string_viewN bytes, zero padded
Int811int8(name)std::int8_t1
UInt812uint8(name)std::uint8_t1
Int1613int16(name)std::int16_t2
Float3214float32(name)float4

Values 8 and 9 are rune's variable-length types and are not used. A string longer than its field throws std::invalid_argument (ecs::Row::set: the string is longer than its field) and leaves the row unchanged; it is never truncated.

Builder mistakes are reported by build() as std::invalid_argument naming the type and field: ecs::Type 'e': field 'a': duplicate name, ... field 'b': a second key (the first is 'a'), ... key() before any field, ... string field 'a' needs at least 1 byte, ... field 'a': a key must be an integer or a string of at most 16 bytes, ... field 'b': duplicate tag 3. A Field of the wrong C++ type throws too: ecs::Type 'character': field 'name' is string(16), not double: use field<string_view>("name"), and a missing one ... there is no field 'zzz'.

Debug builds check your handles. A Field remembers the type it came from. Using it on a row of another component aborts with aether: ecs::Row::set: the field belongs to component 'b' but the row is a 'a' row. Look the field up on the type of the row you use it on: type.field<T>("name"). and a read or write on a false row aborts with ... on a false Row: the entity is dead or does not have the component. Test the row first (if (row) ...) or add the component before writing to it. A release build (NDEBUG) has neither check, so a mistake there reads or writes the wrong bytes.

Dumping state for logs and tests

ecs::dump turns a row, an entity or a view row into JSON, for logs, game-master tools and test failures. It allocates: it is for debugging, not for the tick. Include <aether/ecs/Dump.h>.

std::println("{}", ecs::dump(registry, ayla));
// for an entity with a Walker {5, 0, 60} and a Purse {"x", 5}:
// {"entity":"0:2","Walker":{"x":5,"y":0,"speed":60},"Purse":{"owner":"x","gold":5}}
  • dump(const Type&, ConstRow) is one row, fields in declaration order; a false row gives null.
  • dump(const Registry&, Entity) lists the components the entity has, in registration order, a tag as {}; a dead entity is {"entity":"7:2","alive":false}.
  • dump(const View&, Entity) has the entity's row at the last commit, and no view member if it has none.

Values: integers are JSON numbers, exact (64-bit ones are not cut to 53 bits); a double is the shortest decimal that reads back to the same double; a float is its exact double value (0.1f is 0.10000000149011612); NaN and infinities are the strings "NaN", "Infinity", "-Infinity"; a bool is true or false; an enum is its number; a string is its content up to the first NUL, quoted and escaped (other bytes pass through; UTF-8 is not checked). An entity is "slot:generation".

It takes a registry or a type, not a game struct directly: for a struct S in a Game, ecs::dump(registry(), p.entity).

Going below Game

A server::Game is a thin composition of public pieces: it does nothing a world written by hand with them cannot do, and the hand-written way stays first-class. That matters when a world outgrows Game: you take over one piece at a time, and the handlers, the shared step(), the view and the client do not change.

The ladder, as examples/walker climbs it for one game, the walker (meadow's walker without chat or gold):

  1. Game: examples/walker/World.h, four lines.
  2. CustomWorld: still a Game, with options and a system of your own.
  3. ManualWorld: no Game: Registry, Schedule, Interest, Inputs, Players and receive() by hand.
  4. A bare WorldProcessor: no ECS at all: raw clients and bytes (examples/echo).
  5. No App: the pieces under App assembled yourself (examples/assemble).

Rung 1 and 2: Game, and Game with two customisations

examples/walker/World.h
struct World : aether::server::Game {
    explicit World(aether::server::GameOptions options = {}) : Game(options) {}
    void onStart() override { view<Walker>().spatial("x", "y"); inputs().apply<Move>(step); }
    void onJoin(Player& p) override { p.entity = spawn(Walker{0, 0, 60}); }
};
examples/walker/Variants.h
struct CustomWorld : aether::server::Game {
    CustomWorld() : Game({.inputs = {.rate = 60, .maxPerTick = 4}, .radius = 200}) {}   // 1. options
    void onStart() override {
        view<Walker>().spatial("x", "y").every(2).history(2);                          // the full view builder
        inputs().apply<Move>(step);
        schedule().phase("world");                                                      // 2. a phase and a system of its own, after "simulate"
        schedule().system("bounds", "world", [this](const aether::ecs::Tick&) {
            registry().query(componentOf<Walker>()).each([](aether::ecs::Entity, aether::ecs::Row row) {
                Walker w = row.get<Walker>();
                w.x = std::clamp(w.x, -1000.0, 1000.0);
                row.set(w);
            });
        });
    }
    void onJoin(Player& p) override { p.entity = spawn(Walker{0, 0, 60}); }
};

Game options are listed on the server page.

Rung 3: the pieces by hand

A world with no Game is a class derived from server::WorldProcessor. It is called when a client connects (onConnect), when it leaves (onDisconnect) and once per tick (doWork). Everything else is yours. Here is meadow's walker world that way, with chat added, so you can see where each Game feature went. It is served by an App like any world, and a client cannot tell it from the Game version.

meadow without server::Game
#include <aether/server.h>
#include "meadow/Shared.h"

using namespace aether;
using meadow::Chat;
using meadow::Said;

class MeadowManual : public server::WorldProcessor {
    ecs::Registry registry_;
    ecs::Schedule schedule_{registry_};
    ecs::Interest interest_{registry_};
    server::Inputs inputs_{interest_};
    server::Messages messages_{interest_};
    server::Players players_{&interest_};
    ecs::Typed<Walker> walker_;

    void onStart(server::WorldManager&) override {
        walker_ = registry_.component<Walker>();
        ecs::View::define<Walker>().spatial("x", "y").build(registry_);
        interest_.setTickRate(tickRate());
        inputs_.apply<Move>(walker_, step);
        messages_.on<Chat>([this](server::Client& c, const Chat& chat) {
            const server::Player* p = players_.find(c);
            players_.broadcast(Said{String<16>(p->query("name", "anon")), chat.text});
        });
        schedule_.phase("input").phase("simulate");
        schedule_.system("inputs", "input", [this](const ecs::Tick&) { inputs_.run(); });
        schedule_.system("interest", "send", [this](const ecs::Tick&) { interest_.send(); });
        schedule_.afterSend([this](ecs::Stamp, std::int64_t) { players_.flush(); });
    }
    void onConnect(server::Client& c) override {
        server::Player& p = players_.add(c);
        p.entity = registry_.create();
        registry_.add(p.entity, walker_, Walker{0, 0, 60});
        interest_.attach(c, p.entity);
        players_.attached(p);
    }
    void onDisconnect(server::Client& c) override {
        interest_.detach(c);
        registry_.destroy(players_.find(c)->entity);
        players_.remove(c);
    }
    int doWork() override {
        for (server::Player& p : players_) server::receive(p.client, nowMs(), interest_, inputs_, messages_);
        schedule_.run(tickNumber(), nowMs());
        return 1;
    }
};

Notice what each piece does and where Game's behaviour went:

  • Registry and Schedule are as in the sections above. The "interest" system in the "send" phase calls interest_.send() after the schedule's commit. Because Schedule::run(stamp, now) commits, you never call registry.commit yourself here.
  • Interest decides who is sent which rows. attach(client, entity) makes the client a viewer standing where its entity is; detach must come before the Client goes away. setTickRate(tickRate()) tells it the server's rate for the welcome message and for time-based figures; the Game does this for you.
  • Inputs turns the client's held-input messages into calls of your step function, one per tick (or more). inputs_.apply<Move>(walker_, step) says "a Move steps the client's Walker row". inputs_.run() belongs in a phase before the simulation. Constructing an Inputs turns on the welcome message the client needs (its entity, the tick and input rates).
  • Messages are the handlers for plain structs the client sends with session.send(Chat{...}).
  • Players keeps who is connected, which entity is theirs and queued messages to them. Queued messages (players_.broadcast, send) go out in flush(), which you call after interest.send() (here in afterSend): a client gets the tick message with the state a message is about before the message. players_.attached(p) after interest_.attach makes the player see its own entity in every view and applies the shows and focuses requested before it was attached.
  • server::receive reads everything a client sent and hands each message to whoever owns it: first the Interest (subscribe, ignore, don't know), then each handler you listed, in order.

What the Game does on top of this, which you take over: it runs the posted functions (post) at the start of the input phase, calls players_.sync() before every send (a player given a new entity in the tick is moved to it), refuses a client whose onJoin throws (close code 4000) and removes what onJoin spawned, handles saving, the contract check and load timeouts, and limits to Options::rate.perTick messages read per client per tick. In a hand-written world, server::receive(p.client, nowMs(), limit, interest, handlers...) takes the limit yourself.

Trap. Close a world before you destroy the object you derived from WorldProcessor: the base destructor closes it too, but by then your part is gone and onClose() can no longer reach it. App does this for you; in your own loop, call world.close().

Rung 4: a world with no ECS

The smallest Aether server echoes every message back to the client that sent it, with the same type. It uses only WorldProcessor and Client:

examples/echo/main.cpp
class EchoWorld final : public WorldProcessor {
protected:
    void onStart(WorldManager&) override {}

    void onConnect(Client& c) override {
        std::printf("client %llu connected from %.*s\n", static_cast<unsigned long long>(c.id()),
                    static_cast<int>(c.address().size()), c.address().data());
        clients_.push_back(&c);
    }

    void onDisconnect(Client& c) override {
        std::printf("client %llu disconnected\n", static_cast<unsigned long long>(c.id()));
        clients_.erase(std::remove(clients_.begin(), clients_.end(), &c), clients_.end());
    }

    int doWork() override {
        int work = 0;
        for (Client* client : clients_) {
            work += client->receive([&](std::uint8_t type, std::span<const std::uint8_t> body) {
                if (client->send(type, body) == SendResult::Full) client->disconnect();  // too slow to keep
            });
        }
        return work;
    }

private:
    std::vector<Client*> clients_;
};

int main(int argc, char** argv) {
    const auto port = static_cast<std::uint16_t>(argc > 1 ? std::atoi(argv[1]) : 9000);

    EchoWorld world;
    App app(world);
    const bool ok = app.listen(port, [](std::uint16_t p) { std::printf("listening on %u\n", p); });
    if (!ok) std::fprintf(stderr, "cannot listen on port %u\n", port);
    return ok ? 0 : 1;
}

Notice three things. The client gives you its messages as a type byte and a body (receive calls you for each, oldest first); messages you send back are written into its output buffer and put on the wire by the server's next flush, not by you. send returns a SendResult, which you must look at ([[nodiscard]]): Full means the client's output buffer had no room. And message types 0 and 1 are reserved (1 is the ping), so a message the client sent with type 1 never reaches you.

Wire types. The first byte of every message is its type, 1 to 255. Type 1 is the ping. If you use ecs::Interest, types 2 to 6 are its defaults (tick 2, subscribe 3, ignore 4, don't know 5, layout 6), and the welcome is 7 by default: start your own at aether::kFirstGameType (16).

Rung 5: without App

App is a WebSocketServer, the session pipeline, a NetworkProcessor and your world, started and stopped for you (three threads: the server layer, the network processor and the world). examples/assemble builds the echo server again from those pieces, so you can choose the threads, the transport and the pipeline yourself:

examples/assemble/main.cpp
const Options options;

WorldManager manager(options);                       // owns the world buffer: all the two sides share
EchoWorld world;
world.start(manager, options);                       // the world, on its thread
Sessions sessions = makeSessions(manager, options);  // the pipeline
WebSocketServer server(port, sessions, options);     // the transport
NetworkProcessor network(server, sessions, options);
network.start();                                     // flushes the sessions through the server, 30 times a second

std::thread io;
if (!server.loopOn(io)) {
    std::fprintf(stderr, "cannot listen on port %u\n", port);
    network.close();
    world.close();
    io.join();
    return 1;
}
std::printf("listening on %u\n", server.port());

std::signal(SIGINT, [](int) { g_stop.store(true); });
while (!g_stop.load()) std::this_thread::sleep_for(std::chrono::milliseconds(50));

server.stop();    // closes every connection; returns once the disconnects are in the world buffer
io.join();
network.close();
world.close();    // delivers them, then onClose

A transport other than WebSocket implements server::Connection and calls a ConnectionHandler (the session pipeline implements it; so can you), both in aether/server/Connection.h and listed in the reference. The GameNetworkingSockets flavour is one such transport (network).

Interest by hand, and a client with no Session helpers

examples/client is two programs. view_server is a world with no Inputs and no Players: it defines a view, makes an ecs::Interest, attaches each client to an entity of its own, commits once per tick and sends. view_client links only aether_client (no server code) and prints the rows it is sent, through the replica of the client page.

examples/client/server.cpp
void onStart(server::WorldManager&) override {
    position_ = registry_.component<Position>();
    view_ = ecs::View::define("entities")
                .from(position_)
                .select(position_, "x").delta()
                .select(position_, "y").delta()
                .subscribable()
                .spatial(position_, "x", "y")
                .build(registry_);
    interest_ = std::make_unique<ecs::Interest>(registry_);
    for (int i = 0; i < 20; ++i) walkers_.push_back(spawn(i * 3.0, 0));
}
void onConnect(server::Client& c) override {
    interest_->attach(c, spawn(0, 0));  // the layout of "entities" goes out with the first send
    clients_.push_back(&c);
}
void onDisconnect(server::Client& c) override {
    interest_->detach(c);
    clients_.erase(std::remove(clients_.begin(), clients_.end(), &c), clients_.end());
}
int doWork() override {
    // ... move the walkers ...
    registry_.commit(tickNumber(), nowMs());  // the time is said once, here
    for (server::Client* c : clients_) c->receive([&](std::uint8_t type, std::span<const std::uint8_t> body) {
        interest_->handle(*c, type, body);
    });
    interest_->send();
    return 1;
}

Notice the order in doWork: change the world, commit (which builds the view rows), read what the clients sent (the Interest's own messages), then send. Nothing is sent before the first commit: Interest::send() before it does nothing and returns 0.

Reference

Every public item of the registry layer, in the order of this page. Throw types are as in the headers; messages are quoted where a run printed them. Everything is in namespace aether::ecs (or aether::server where stated), included by <aether/ecs.h> and <aether/server.h>.

Entity

enum class Entity : std::uint64_t {};
inline constexpr Entity kNoEntity{~std::uint64_t{0}};
constexpr bool isSet(Entity e) noexcept;
std::string toString(Entity e);
std::ostream& operator<<(std::ostream&, Entity);   // and std::formatter<Entity>
ItemMeaning
Entitylow 32 bits: slot; high 32 bits: generation. An enum class: no arithmetic by accident; static_cast<std::uint64_t>(e) gives the raw id. Generation 0 is never alive.
kNoEntitythe "none" id (all bits set).
isSet(e)false for kNoEntity and for Entity{}; says nothing about whether it exists.
toString(e)"slot:generation", e.g. "7:2"; "none" if not set.

Registry

Registry();   ~Registry();
Registry(const Registry&) = delete;   Registry& operator=(const Registry&) = delete;

No parameters. Not copyable, not movable. One thread.

component, findComponent

Component component(Type type, std::size_t reserveRows = 1024);
Component component(Type type, const PersistOptions& persist, std::size_t reserveRows = 1024);
template <class S> Typed<S> component(std::size_t reserveRows = 1024);
template <class S> Typed<S> component(const PersistOptions& persist, std::size_t reserveRows = 1024);
template <class S, class Saved> Typed<S> component(const PersistWith<Saved>& persist, std::size_t reserveRows = 1024);
std::optional<Component> findComponent(std::string_view name) const;
ParameterMeaning
typethe hand-built ecs::Type of the component.
Sa flat struct: trivially copyable, every member a fixed size (integers, float, double, bool, aether::String<N>, ecs::Entity, a plain struct, std::array and aether::List of those). Registered under its name without the namespace. A struct that is not flat does not compile: ecs::Registry::component<S>(): S is not a flat struct, so it cannot be a component. ... use a local component: registry.local<S>(). Calling it again for a registered struct returns the existing component.
persistmakes the component persisted (saving): ecs::persist("topic", &S::key). A type with no key field throws std::invalid_argument.
Saved(the third form) the flat struct the component is stored as: ecs::persist("hero", &Hero::id).convert<SavedHero>(toSaved, fromSaved); S may then have a List or an Entity.
reserveRowsrows allocated up front, default 1024; the buffer doubles when full.
name(findComponent) the component's name.

Returns: a handle (Component or Typed<S>); findComponent returns an empty optional if there is none. Throws: std::invalid_argument if a component or view of that name exists (ecs::Registry: a component or view named 'character' exists) or if two structs share an unqualified name (the message names both). See also: Registering components, data.

const auto walker = registry.component<Walker>();
if (const auto c = registry.findComponent("Walker")) { /* c->id(), c->type() */ }
std::optional<Component> structComponent(std::type_index type) const;
void noteStruct(std::type_index type, std::string_view qualifiedName, Component c);
std::string_view structName(Component c) const;

The struct layer's bookkeeping, used by component<S>() so that two structs sharing an unqualified name are told apart. structComponent: the component made for that struct, if any. noteStruct: records it (qualifiedName is for messages). structName: the qualified name of the struct a component was made from; empty for a component built by hand from a Type.

local

template <class T> Local<T> local();
ParameterMeaning
Ta class type: not a reference, a const type or a C array; movable; noexcept move constructor and destructor; alignof(T) <= 64. Named as the compiler writes it ("Notes", "game::Notes"). Each rule is a static_assert with a message that says what to do.

Returns: the handle (the same one if called again). A persist argument is a compile error: a local component stays on the server and is never persisted; persist a flat plain struct ... with the part of it that must last. The object lives in the entity's row; it is destroyed when the component is removed, the entity is destroyed or the registry is.

group

template <class... Cs> requires(sizeof...(Cs) >= 2 && (std::convertible_to<Cs, Component> && ...))
void group(Cs... components);
void group(std::span<const Component> components);
ParameterMeaning
componentstwo or more components to keep in the same dense order. Call right after registering them, before any entity has a row in one of them.

Throws: std::invalid_argument for fewer than two, a component twice, a null one, or one of another registry; std::logic_error if one already is in a group, already has rows, or inside Query::each. See also: Groups.

create, destroy, alive, entityCount

Entity create();
void create(std::size_t n, std::vector<Entity>& out);
void destroy(Entity e);
bool alive(Entity e) const;
std::size_t entityCount() const;
CallMeaning
create()a new entity with no components.
create(n, out)appends n new entities to out: one reservation and one pass.
destroy(e)removes all its components and view rows; viewers are sent Unsubscribed on their next send. No-op if dead. Runs onDestroy and the onRemove hooks first. Inside each: throws if the entity has a row in a component of the running query (ecs::Registry::destroy: the entity has a row in a component of the running query); use deferDestroy.
alive(e)one load: the slot's word holds the generation and a live bit. False for a stale id and for an id made up with generation 0.
entityCount()the number of live entities.

add, get, tryGet, has, remove

Row  add(Entity e, Component c);                                    // a zeroed row
template <std::integral K> requires(!std::is_same_v<K, bool>)
Row  add(Entity e, Component c, K key);                             // a persisted component
Row  add(Entity e, Component c, std::string_view key);              // a persisted component, string key
template <class S> S& add(Entity e, const Typed<S>& c, const S& value);
template <class S> S& add(Entity e, const Typed<S>& c);                // a zeroed S
template <class T> T& add(Entity e, const Local<T>& c, T value);
template <class T> T& add(Entity e, const Local<T>& c);                // default constructed T

Row      get(Entity e, Component c);
ConstRow get(Entity e, Component c) const;
template <class S> S& get(Entity e, const Typed<S>& c);     // and const S& (const overload)
template <class T> T& get(Entity e, const Local<T>& c);     // and const T& (const overload)
template <class S> S* tryGet(Entity e, const Typed<S>& c);   // and const S*
template <class T> T* tryGet(Entity e, const Local<T>& c);   // and const T*
bool has(Entity e, Component c) const;
void remove(Entity e, Component c);
ParameterMeaning
ea live entity of this registry.
cthe component handle (a Typed or Local converts to Component).
key(persisted components only) the row's key field, never zero or empty; the only way to add a persisted component.
valuethe initial value; for a flat struct every member is set from it (a keyed component takes its key from the member named in persist).
  • add throws std::logic_error if the entity is dead or already has the component (also inside a running query of that component). Fires onAdd. Returns the row, or the struct / object in the buffer, valid until the next structural change of that component.
  • get of a struct or local component throws std::logic_error if the entity is dead or has none, saying what to do. get with a Component returns a Row/ConstRow that is false (operator bool) if the entity is dead or has none; it does not throw.
  • tryGet returns nullptr instead of throwing.
  • has is false for a dead entity.
  • remove does nothing if the entity has none. Fires onRemove first. Inside a running query of that component it throws 'Walker' is in a running query; use deferRemove. A persisted row's removal follows its onRemove policy (saving).
registry.add(ayla, walker, Walker{0, 0, 60});
Walker& w = registry.get(ayla, walker);
if (Purse* p = registry.tryGet(ayla, purse)) p->gold += 1;

load, decode

Row load(Entity e, Component c, std::span<const std::uint8_t> record);
std::vector<std::uint8_t> decode(Component c, std::span<const std::uint8_t> record);

load adds (or overwrites) the persisted component from a rune record [blockLength u16][version u16][row]; the row is clean (not marked changed). A record carries no layout: it is refused, with std::invalid_argument saying so, when its length differs from the row's at the same version. A change that keeps the size is not seen here: keep the layout's fingerprint with the topic (ecs::Store::expect, which Game::persist calls; RuneStore compares it at start). onAdd runs for a new row, not for an overwrite. decode returns the row bytes a record holds (the component's own layout; a record stored through convert<Saved> goes through fromSaved) without adding anything, and throws like load for a bad record. See also: saving.

query

template <class... Cs> Query<detail::Plain<Cs>...> query(Cs... components);

components: Component (or a typed handle), ecs::read(c), ecs::optional(c), ecs::optional(ecs::read(c)), ecs::none(c...), ecs::any(c...); at least one required one. Throws: std::invalid_argument if a component is null or of another registry, or is in the query twice. The returned Query may be kept and reused; a component registered after the query was made does not break it. See Queries.

Query: each, count, sizeHint; read, optional, none, any

template <class Fn> void each(Fn&& fn) const;
std::size_t count() const;
std::size_t sizeHint() const;

Read read(Component c);                                  // ConstRow
template <class T> ReadLocal<T> read(const Local<T>& l);      // const T&
template <class S> ReadTyped<S> read(const Typed<S>& t);      // const S&
Optional<Component> optional(Component c);              // Row, false if none
Optional<Read> optional(Read r);                        // ConstRow, false if none
template <class T> Optional<Local<T>> optional(const Local<T>&);      // T*   (and Optional<ReadLocal<T>> for const T*)
template <class S> Optional<Typed<S>> optional(const Typed<S>&);      // S*   (and Optional<ReadTyped<S>> for const S*)
template <class... Cs> None<sizeof...(Cs)> none(Cs... components);
template <class... Cs> Any<sizeof...(Cs)> any(Cs... components);
ItemMeaning
each(fn)calls fn(Entity, rows...) once per matching entity. Rows are given in the order the query lists the required and optional components (none and any add none). The callback is inlined into the walks. Locks the structure of the required and optional components (and their groups) while it runs; the deferred changes made inside run when the outermost each returns. A callback that does not match is a compile error (see Queries).
count()how many entities each would visit now; O(1) for one component, or exactly a group's members, with no none or any.
sizeHint()the size of the smallest required component: an upper bound.
none(c...), any(c...)at least one argument each (requires); several none are one list; each any is required on its own: with any(a, b) and any(c, d) the entity needs a or b, and c or d.

defer, deferAdd, deferRemove, deferDestroy

void defer(std::function<void()> change);
void deferAdd(Entity e, Component c, std::span<const std::uint8_t> row = {});
template <class T> void deferAdd(Entity e, const Local<T>& c, T value);
void deferRemove(Entity e, Component c);
void deferDestroy(Entity e);

Run when no Query::each is running: at once if none is, else when the outermost one returns, in the order deferred. row, if not empty, must have the component's blockLength bytes and is copied when deferred; passing bytes for a local component throws, saying to pass the value with its handle. deferAdd of a local value outside a query adds at once. A deferred change has the effect and the exceptions of add, remove or destroy at the time it runs. If each is left by an exception the deferred changes are dropped.

commit, lastCommit, lastCommitMs, findView

void commit(Stamp stamp, std::int64_t nowMs);
void commit(Stamp stamp);
Stamp lastCommit() const;
std::int64_t lastCommitMs() const;
std::optional<View> findView(std::string_view name) const;

Stamp is std::int64_t. See The commit for the parameters, the exceptions (stamp not larger than the last; inside each; persisted component with no Persistence) and the clock. lastCommit() is 0 before the first. lastCommitMs() throws std::logic_error if there was no commit yet or the last had no time. findView(name) returns the view of that name, or an empty optional (views).

onAdd, onRemove, onDestroy

void onAdd(Component c, std::function<void(Entity, Row)> fn);
void onRemove(Component c, std::function<void(Entity, ConstRow)> fn);
void onDestroy(std::function<void(Entity)> fn);
template <class T> void onAdd(const Local<T>& c, std::function<void(Entity, T&)> fn);
template <class T> void onRemove(const Local<T>& c, std::function<void(Entity, T&)> fn);

c: the component (a typed handle converts). fn: the hook; an empty function throws std::invalid_argument (ecs::Registry::onAdd: the function is empty), as does a component of another registry; registering inside a hook throws std::logic_error. When they run, what they may do and what an exception does: Hooks.

onError

void onError(std::function<void(const std::string&)> fn);

Where the errors the registry cannot throw go (today: a function view that threw). fn(message). Default: one line on stderr, aether: <message>. Each problem is reported once, not at every commit.

singleton, event, emit, events

Singleton  singleton(Type type);
EventType  event(Type type);
Row        emit(EventType e);
EventRange events(EventType e) const;

class Singleton {                       // a small handle
    const Type& type() const;
    Row row() const;   ConstRow constRow() const;
    template <class T> Field<T> field(std::string_view name) const;
};
class EventType {
    const Type& type() const;
    template <class T> Field<T> field(std::string_view name) const;
};
class EventRange {
    iterator begin() const;  iterator end() const;      // input iterator yielding ConstRow
    std::size_t size() const;   bool empty() const;
};

singleton(type): throws std::invalid_argument if a singleton of that type name exists. event(type): throws std::invalid_argument for a duplicate name. emit(e): appends a zeroed row and returns it; valid until the next emit of the same event; allowed inside each. events(e): what was emitted since the last commit, in emission order. A handle of another registry throws std::invalid_argument when used. See Singletons and Events.

Component, Typed, Local

class Component {
    Component() = default;
    const Type& type() const;
    std::uint32_t id() const;                               // dense, from 0, in registration order
    template <class T> Field<T> field(std::string_view name) const;
    template <class... Ts> std::tuple<Field<Ts>...> fields(detail::NameOf<Ts>... names) const;
    friend bool operator==(const Component&, const Component&);   // the same component
};
template <class S> class Typed : public /* one Field per member, for macro-listed structs */ {
    operator Component() const;
};
template <class T> class Local {
    operator Component() const;
    Component component() const;
};

Small handles; copy freely. field<T>(name) and fields forward to the type (Type); for example std::tie(x, y) = position.fields<double, double>("x", "y"). A default-constructed Component is null: passing it to query or group throws.

Row and ConstRow

class ConstRow {
    ConstRow() = default;   explicit ConstRow(const std::uint8_t* p);
    explicit operator bool() const;
    const std::uint8_t* data() const;
    template <class T> T get(Field<T> f) const;
    template <class S> S get() const;
    template <class First, class... Rest> requires(std::is_member_object_pointer_v<First>)
    auto get(First first, Rest... rest) const;
};
class Row : public ConstRow {
    Row() = default;   explicit Row(std::uint8_t* p);
    std::uint8_t* data() const;
    template <class T> Row set(Field<T> f, std::type_identity_t<T> v) const;
    template <class S> Row set(const S& value) const;
    template <class First, class... Rest> requires(std::is_member_object_pointer_v<First>)
    Row set(First first, Rest... rest) const;
};
CallMeaning
operator boolfalse for a row from get of a dead entity or a missing component, and for an optional row the entity lacks.
get(Field<T>)the field's value: a plain load. A std::string_view field gives the content up to the first NUL (or all width bytes). Not for a false row.
get<S>()the whole row as the struct S that describes it.
get(&S::m, ...)one member by a path of member pointers; an index goes into a std::array or List (row.get(&Hero::hotbar, 2)).
set(Field<T>, v)writes the field; returns the row so sets chain. A string longer than the field throws std::invalid_argument (ecs::Row::set: the string is longer than its field) and leaves the row unchanged; a shorter one is zero padded.
set(S)writes every member of the struct.
set(&S::m, ..., value)one member by a path, the value last.

In a debug build, get and set abort on a false row or on a field that belongs to another component (see Runtime types, and diagnostics). Row::data() is the raw pointer to the bytes; valid until the storage changes.

Type, TypeBuilder, Field, FieldInfo, Prim

class Type {
    static TypeBuilder define(std::string name, std::uint16_t version = 1);
    std::string_view name() const;
    std::uint16_t version() const;
    std::uint32_t blockLength() const;                   // size of a packed row in bytes
    const std::vector<FieldInfo>& fields() const;        // declaration order
    const FieldInfo* find(std::string_view name) const;  // nullptr if there is none
    const FieldInfo* key() const;                        // the key field, or nullptr
    template <class T> Field<T> field(std::string_view name) const;
    template <class... Ts> std::tuple<Field<Ts>...> fields(detail::NameOf<Ts>... names) const;
    std::uint64_t fingerprint() const;
    std::uint32_t rowSize() const;                       // size of a row as a pool holds it
    friend bool operator==(const Type&, const Type&);  // same definition, or equal names, versions and fields
};
struct FieldInfo { std::string name; std::uint16_t tag; Prim prim; std::uint32_t offset; std::uint32_t slot;
                   std::uint16_t width; std::uint16_t sinceVersion; bool isKey; std::vector<std::int32_t> enumValues; };
template <class T> struct Field { std::uint32_t offset; std::uint16_t width; /* debug builds: the type it came from */ };
  • define(name, version = 1): name is the rune topic name if the type is ever persisted; version is the type's version.
  • field<T>(name) throws std::invalid_argument if there is no such field (ecs::Type 'character': there is no field 'zzz') or if T is not the C++ type of its Prim (... field 'name' is string(16), not double: use field<string_view>("name")). An Int32 or Enum field is read as std::int32_t.
  • fingerprint(): rune's fingerprint of the equivalent descriptor.
  • FieldInfo::offset is the field's place in a packed row (the wire, view rows, records, fingerprints); slot its place in a row as the pool stores it (equal to offset except for a component stored as its struct); tag its durable identity across versions; sinceVersion the version that added it.
class TypeBuilder {
    TypeBuilder& int32(std::string name);    TypeBuilder& uint32(std::string name);
    TypeBuilder& int64(std::string name);    TypeBuilder& uint64(std::string name);
    TypeBuilder& uint16(std::string name);   TypeBuilder& float64(std::string name);
    TypeBuilder& int8(std::string name);     TypeBuilder& uint8(std::string name);
    TypeBuilder& int16(std::string name);    TypeBuilder& float32(std::string name);
    TypeBuilder& boolean(std::string name);
    TypeBuilder& enumeration(std::string name, std::vector<std::int32_t> allowed = {});
    TypeBuilder& string(std::string name, std::uint16_t bytes);   // throws std::invalid_argument if 0
    TypeBuilder& key();                             // the last field is the key
    TypeBuilder& tag(std::uint16_t tag);            // durable tag of the last field
    TypeBuilder& since(std::uint16_t version);      // version that added the last field
    Type build();
};
MethodMeaning
field methodsadd one field of that Prim. enumeration: an int32, optionally limited to the listed values (empty: any value). string(name, bytes): a fixed string of bytes bytes, zero padded.
key()marks the last field as the key (the rune topic key). At most one field; an integer, or a string of at most 16 bytes.
tag(t)the durable tag of the last field. Default: its position in the declaration, as rune numbers it.
since(v)the version that added the last field. Default 1.
build()throws std::invalid_argument naming the field for: a duplicate name or tag, a second key, a key of a type that cannot be one, key(), tag() or since() before any field, a zero-byte string. A type with no fields builds: it is a tag (the comment in Type.h says build() throws for "no fields"; the code does not).

The Prim table is in Runtime types.

Schedule

explicit Schedule(Registry& registry);   ~Schedule();
Schedule& phase(std::string name);
SystemRef system(std::string name, std::string_view phase, std::function<void(const Tick&)> fn);
Schedule& persist(Persistence& persistence);
Schedule& afterSend(std::function<void(Stamp, std::int64_t)> fn);
void run(Stamp stamp, std::int64_t nowMs);
std::span<const SystemStats> stats() const;
void resetStats();

SystemRef& SystemRef::every(std::uint32_t ticks);
SystemRef& SystemRef::every(std::chrono::milliseconds interval);
template <class Rep, class Period> SystemRef& SystemRef::every(std::chrono::duration<Rep, Period> interval);

struct Tick { Stamp stamp = 0; std::int64_t now = 0; std::int64_t sinceLastRun = 0; std::uint64_t runCount = 0; };
struct SystemStats { std::string name; std::string phase; std::int64_t lastNs; std::int64_t maxNs; std::uint64_t runs; };
ItemParameters, returns, errors
Schedule(registry)the registry the commit is made on. Neither copyable nor movable.
phase(name)declares a phase after the ones declared so far; returns the schedule (chain). Throws std::invalid_argument for a duplicate (also "send") or empty name; std::logic_error while run() runs.
system(name, phase, fn)adds fn to the end of phase ("send" is built in and runs after the commit). Returns a SystemRef valid until the next system(). Throws std::invalid_argument for an unknown phase, a duplicate or empty name, an empty function.
every(ticks)every n-th run, n >= 1; 0 throws std::invalid_argument. every(duration): rounded down to ms, at least 1 ms, else std::invalid_argument; a non-millisecond std::chrono::duration is converted with duration_cast. The last call wins.
persist(p)p.collect(now) after the send systems; p must outlive the schedule's runs.
afterSend(fn)fn(stamp, now) at the end of the tick after the collect, in the order added.
run(stamp, nowMs)one tick; see the schedule. Throws std::logic_error for a stamp not larger than registry.lastCommit() (nothing runs) and when called from a system; whatever a system throws propagates and the tail is skipped.
stats(), resetStats()per system in the order added: name, phase, lastNs and maxNs (nanoseconds, of the last run and the longest), runs. resetStats() zeroes them, not the rates.
Tickstamp, now: as given to run; sinceLastRun: ms since this system last ran, 0 the first time; runCount: runs including this one.
schedule.system("regen", "simulate", [&](const ecs::Tick& t) { /* t.sinceLastRun ms since the last run */ })
        .every(std::chrono::seconds(1));

See also: The schedule.

dump

std::string dump(const Type& type, ConstRow row);
std::string dump(const Registry& registry, Entity entity);
std::string dump(const View& view, Entity entity);

JSON for logs, tools and tests (Dumping state). type + row: the row; a false row gives null. registry + entity: the components the entity has, in registration order, or {"entity":"7:2","alive":false}. view + entity: the entity's row at the last commit. Allocates. Include <aether/ecs/Dump.h>.

Interest (the low-level API)

One ecs::Interest per registry. It decides, per attached client, which rows are sent and writes one tick message per send into the client's output ring. Views and what clients see are on views; budgets, weights and the crowd path are on network. These are the calls a hand-written world makes.

explicit Interest(Registry& registry, InterestPolicy policy = {});   ~Interest();
const InterestPolicy& policy() const;      Registry& registry() const;
void setTickRate(int hz);    void setInputRate(int hz);    void setIdleHeaderTicks(std::uint32_t sends);
int tickRate() const;        int inputRate() const;
void snap(Entity e);
wire::IdTable& ids();
void enableWelcome();
void observe(const void* owner, std::function<void(server::Client&, Entity)> onAttach,
             std::function<void(server::Client&)> onDetach, std::function<void(server::Client&, Entity)> onPlayer = {});
void unobserve(const void* owner);
void attach(server::Client& client, Entity player);
void setPlayer(server::Client& client, Entity player);
void detach(server::Client& client);
bool attached(const server::Client& client) const;
void show(server::Client& client, View view, Entity e);   void hide(server::Client& client, View view, Entity e);
void show(server::Client& client, Entity e);              void hide(server::Client& client, Entity e);
void focus(server::Client& client, Entity e);             void unfocus(server::Client& client, Entity e);
bool handle(server::Client& client, std::uint8_t type, std::span<const std::uint8_t> body);
bool handle(server::Client& client, std::uint8_t type, std::span<const std::uint8_t> body, std::int64_t nowMs);
void setInputSequence(server::Client& client, std::uint32_t sequence);
std::size_t send();    std::size_t send(std::int64_t nowMs);
CallParameters, returns, errors
Interest(registry, policy)policy: InterestPolicy. Throws std::invalid_argument for a policy that breaks a rule (cellSize, cap 0, message types) and std::logic_error if the registry already has an Interest (ecs::Interest: the registry already has one). It must not outlive the registry, and every Client must be detached before it is destroyed.
setTickRate(hz)the server's ticks a second, for the welcome; default 20 (the default of Options::tickRate). Call it with WorldProcessor::tickRate() in onStart, before the first attach.
setInputRate(hz)input steps a second (server::Inputs sets it); 0 = the tick rate. inputRate() is never 0.
setIdleHeaderTicks(n)the policy field, changed after construction.
snap(e)this commit's change of e is a snap (a discontinuity clients must not blend across), in every view; a viewer that has e is sent a Snap entry instead of a Delta in the first send that includes it. Call it in the tick that changes the row, before the commit. A viewer that lacks e is sent a plain Full.
ids()the table of wire ids of this server: Messages, Inputs and Client::send(msg) make ids for plain structs in it; attach sends the whole table, and ids made later go to attached clients.
enableWelcome()sendWelcome and ownerRowEveryTick on from now on (Inputs calls it).
observe(owner, onAttach, onDetach, onPlayer)calls onAttach(client, player) at the end of attach and onDetach(client) at the start of detach; onPlayer(client, player), if given, at setPlayer. owner is the key for unobserve.
attach(client, player)the client is a viewer from now on, standing where player is (its position is that of the player's row in the spatial view with the lowest id that has one; with none it has no grid neighbours). player may be kNoEntity (only shown entities are sent). Throws std::logic_error if the client is attached, or if the registry has no subscribable view. The first send() then also sends the layouts. Call it in onConnect, once the entity exists.
setPlayer(client, player)the client's player is player from now on (a respawn): the viewer stands where it is, owner-only rows come from it, the welcome is sent again so the client's me() changes. Nothing else is reset. Throws std::logic_error if not attached.
detach(client)forgets the client and sends nothing; no-op if not attached. Call it in onDisconnect, before the Client goes.
show / hide (client, view, e)e is a neighbour of the viewer in view wherever it is, until hide: for views without a radius, or entities out of it. The view must be subscribable (std::logic_error). hide of an entity that was not shown is a no-op.
show / hide (client, e)in every subscribable view at once, except owner-only views.
focus / unfocus (client, e)the viewer cares about e: it is sent to this viewer entity by entity, wherever it is, and under a budget before the crowd. No-ops for an entity already focused / not focused; std::logic_error if not attached.
handle(client, type, body[, nowMs])gives Interest a message read from the client. True if type is the subscribe, ignore or don't-know type (handled or dropped); false otherwise or when the client is not attached. The time for an ignore's end is the last commit's; throws std::logic_error if that commit had none; the explicit form takes it.
setInputSequence(client, n)the last input sequence the game applied for this client; travels in the header of its tick messages (Inputs::run calls it).
send(), send(nowMs)sends every viewer its tick message for the last commit. Call once per tick after registry.commit. Returns the bytes written to all output rings (message bodies, without the type byte), layouts included. Before the first commit it does nothing and returns 0. The time is the last commit's (std::logic_error if none); send(nowMs) is the explicit form.

Reading what happened, per viewer (each throws std::logic_error if the client is not attached unless stated):

CallReturns
radius(client) (float)the radius used in the last send.
subscribed(client), subscribed(client, view), subscribed(client, view, e)subscriptions over all views, in one view (size_t), or whether e is subscribed (bool).
ignored(client), ignored(client, view, e)ignore entries (size_t) or whether e is ignored.
dropped(client)client messages dropped since attach.
deferred(client)Deltas and Fulls of the last send that the budget or the ring left out or cut: what to shrink the radius by.
budget(client)the budget of the last send; SIZE_MAX: no limit.
crowdDelay(client), focusDelay(client) (std::chrono::milliseconds)how long the longest-waiting cell, or focused entity, had waited in the last send; 0 before the first send or when there is none.
layoutsPending(client)views whose layout has not gone out to this client yet (always 0 with sendLayouts off).
entriesLast(client)Deltas plus Fulls written to this viewer by the last send.
attached(client)whether it is attached (does not throw).
viewers()the number of attached viewers.
badRadius()radius answers that were NaN or negative (used as 0), since the Interest was made.
unplaced()rows of spatial views that are not in a grid as of the last send because a position is not finite as a float.
lastSendStats()benchmark instrumentation: where the last send spent its time and what it wrote (SendStats).

Messages from the client that handle understands (little-endian, the type byte is not part of the body): subscribe [view u16][entity u64] (Explicit views), ignore [view u16][entity u64][ms u32], don't know [view u16][entity u64]. The client's Session sends them for you; a hand-written client sends them itself (client).

InterestPolicy

A struct with these fields in this order (use designated initialisers in this order). Defaults as written.

FieldType, defaultMeaning
cellSizefloat = 32grid cell size in world units; finite and > 0.
radiusserver::Rule<float, const server::Client&>, unset = 64how far a viewer sees, a number or a function of the client asked once per viewer per send. Not clamped. NaN or negative: a debug build stops with a message naming the client; a release build uses 0 and counts it in badRadius().
stopOnBadRadiusbool = true in debug, false with NDEBUGsee radius.
capstd::uint32_t = 2000subscriptions per viewer over all views.
unsubscribeDelaystd::uint32_t = 3sends an entity (or a held cell, at most 255) may be out of sight before Unsubscribed. 0: on the first send.
maxIgnoreMsstd::uint32_t = 600000a longer ignore is cut to this.
maxIgnoredstd::uint32_t = 4096ignore entries per viewer.
budgetstd::function<std::size_t(const server::Client&)>, unset = no limitbytes per send for Delta and Full entries; 0: only headers and Unsubscribed.
weight, weightForfunctions, unset = 1 / (1 + distance)how much other matters to a viewer; weightFor takes the client and wins if set. With workers above 1 they are called from several threads.
focusfloat = 0.5share of a budget the entries sent entity by entity take first.
cellWeight, nearReserve, crowdEvery, cutsee networkthe crowd path under a budget. nearReserve defaults to {after = 30, within = 1.5, share = 0.25}.
workersstd::uint32_t = 1threads that send viewers in parallel; 1: the world thread alone; 0: one per hardware thread (at most 16). Fewer than 32 viewers are always sent by the world thread.
tickType, subscribeType, ignoreType, dontKnowType, layoutTypestd::uint8_t = 2, 3, 4, 5, 6wire message types; each > 1 and all different.
sendLayoutsbool = truesend each viewer the layout of every view it can be sent, once. Off: the game sends them.
sendWelcomebool = falseattach writes a welcome [player entity u64][tick rate u16][input rate u16] (type welcomeType = 7). Inputs turns it on.
ownerRowEveryTickbool = falsethe viewer's own row is sent in every send, also in a view's sends that every(k) sits out. Inputs turns it on.
idleHeaderTicksstd::uint32_t = 1sends in a row that may write no header for a viewer with nothing to say. server::Game sets it to the tick rate.

WorldProcessor

class WorldProcessor {
public:
    WorldProcessor();   virtual ~WorldProcessor();               // closes it
    void start(WorldManager& manager, const Options& options = {}, std::function<void()> onStartFailed = {});
    void attach(WorldManager& manager, const Options& options = {});
    int  tick();
    void close();
protected:
    std::int64_t tickNumber() const;   int tickRate() const;   const RateLimit& rate() const;   std::int64_t nowMs() const;
    virtual void onStart(WorldManager& manager) = 0;
    virtual void onConnect(Client& client) = 0;
    virtual void onDisconnect(Client& client) = 0;
    virtual void onMessage(std::int32_t typeId, std::span<const std::uint8_t> message) {}
    virtual int  doWork() = 0;
    virtual void onClose() {}
};
inline constexpr std::int32_t kFirstReservedWorldType = 1 << 30;

One tick is: (1) read the world buffer: onConnect / onDisconnect for the session pipeline's messages, onMessage for the rest; (2) doWork(); (3) send a ping to every client that is due one (every Options::pingIntervalMs). Every protected method is called on the world thread. The world shares nothing with the server thread: all it has of a client is its id and its two ring buffers; what it writes to a client's output buffer is put on the wire by the NetworkProcessor's next flush (the world does not flush).

ItemMeaning
start(manager, options, onStartFailed)runs the world on a thread of its own (Options::worldThreadName) at Options::tickRate: onStart(manager) there, then tick() per frame. Returns once onStart has finished (or thrown). manager must outlive the world. If onStart throws, the world never ticks: the cause goes to Options::onError (stderr by default), onClose is not called, and onStartFailed is called once on the world thread (App uses it to stop listen()). Throws std::logic_error if already started or attached.
attach(manager, options)or drive it yourself: calls onStart(manager) on the calling thread; then call tick() from your own loop.
tick()one tick; returns doWork()'s result.
close()stops and joins the thread if start() was used, reads the world buffer one last time (delivers the remaining disconnects), calls onClose() exactly once, frees the clients. Harmless if never started, attached or already closed. Do not call it from the world thread.
tickNumber()1 during the first tick, then 2, 3 ... (0 before the first): always larger than the last, so it is what registry.commit takes.
tickRate()Options::tickRate as given to start/attach (20 before).
rate()Options::rate; the world reads at most rate().perTick messages of a client per tick (0 = all).
nowMs()the time of this tick in ms (a steady clock), read once when the tick starts; never goes backwards; before the first tick it reads the clock.
onStartonce, before the first tick; manager is valid until onClose returns.
onConnect(client)keep the reference: read its input and write its output from doWork.
onDisconnect(client)its input buffer can still be read during the call; after it returns the client and its buffers are destroyed.
onMessage(typeId, message)a message another thread wrote to the world buffer; the span is valid only during the call. Type ids from kFirstReservedWorldType up are the server pieces' own; use 1 to kFirstReservedWorldType - 1 for yours.
doWork()one tick; returns the amount of work done (0 for none).
onClose()once, after the last tick (not if onStart threw); every client has already been disconnected.

It reads these Options: tickRate (start), worldIdle (start), pingIntervalMs, rttCapMs, rttMaxSampleMs, rttSmoothing, worldThreadName (start), onError (start: called on the world thread when a tick throws; the world carries on). All of Options is on network.

server::Client

using ClientId = std::uint64_t;                       // never reused within a process
inline constexpr std::uint8_t kPingType = 1;

ClientId id() const;
std::string_view query() const;                       // "token=abc&map=3"
std::string_view address() const;
void disconnect();
void disconnect(std::uint16_t code, std::string_view reason);
enum class ClosedBy : std::uint8_t { None = 0, TooManyMessages = 1, OutputStalled = 2 };
ClosedBy closedBy() const;
const Link& link() const;
Dropped dropped() const;
std::size_t outputBytes() const;   std::uint32_t socketBytes() const;   float outputFill() const;
concurrent::OneToOneRingBuffer& input();   concurrent::OneToOneRingBuffer& output();
[[nodiscard]] SendResult send(std::uint8_t type, std::span<const std::uint8_t> body);
template <class M> [[nodiscard]] SendResult send(const M& message);
template <class Write> [[nodiscard]] SendResult send(std::uint8_t type, std::size_t size, Write&& write);
template <class OnMessage> int receive(OnMessage&& onMessage, int limit = INT_MAX);
bool handleSystem(std::int32_t typeId, concurrent::AtomicBuffer& buffer, std::int32_t index, std::int32_t length);
wire::IdTable& ids();   void bindIds(wire::IdTable* table);
CallMeaning
id(), query(), address()the connection's id, the query string of the connect URL and the remote address as text.
disconnect()asks the server thread to close the connection after the messages already in its output buffer have been written; onDisconnect still follows. Harmless to call again.
disconnect(code, reason)the same, and the client's session.onClose(fn(code, reason)) gets them. 3000..4999 is for the game (4000 is "rejected"); reason at most 123 bytes (cut if longer). Only the first call's reason counts.
closedBy()why the server (not the game) ended the connection, if it did: TooManyMessages or OutputStalled; None for the game's own disconnect.
link()the measured Link, updated while the client's input is read (receive).
dropped()messages dropped instead of handled, since it connected: rate, ringFull, perType, total().
outputBytes(), outputFill()the bytes (and the fraction, 0 to 1) of the output buffer that the world wrote and the server thread has not taken yet.
socketBytes()what the connection holds that is not on the wire, as of the last flush pass of the server thread.
input(), output()the raw rings. An output record is the whole wire message, type byte first, with the type as its ring type id. If you read the input ring yourself, pass every record to handleSystem first.
send(type, body)copies a message of type (2 to 255; with Interest, yours start at 16) into the output buffer. Returns SendResult::Ok, Full (no room in the buffer) or TooLarge. Throws std::invalid_argument("message types 0 and 1 are reserved") for a type of 0 or 1.
send(const M&)sends a game message struct; its type is on the server's id table. Throws std::logic_error if the client is not attached to an Interest: server::Client::send(message): the client is not attached to an ecs::Interest, so the ids of the messages are not known to it yet (attach it first).
send(type, size, write)zero copy: write(std::span<std::uint8_t> out) is called with size bytes of the output buffer to encode the body into; not called unless the result is Ok; if it throws, nothing is sent.
receive(onMessage, limit)calls onMessage(std::uint8_t type, std::span<const std::uint8_t> body) for each message the client sent, oldest first, at most limit of them (default: all). Returns how many. The span is valid only during the call. Ping echoes and link reports are consumed here: they update link() and are not passed on.
ids(), bindIds(table)the id table of the server it is attached to (set by Interest::attach); ids() throws std::logic_error if not attached.

Each ring has exactly one writing thread and one reading thread. Client::send, Players::broadcast and posted work run in a tick, on the world thread (or, during Interest::send with workers > 1, on its workers).

Link (rttMs, jitterMs, loss, capacity, sending, receiving, backlog, queueMs, left, interpMs, limit and the helpers congested() and headroom()) is described on network.

Connection and ConnectionHandler

class Connection {                                                   // one remote peer, owned by the server layer
public:
    virtual std::string_view query() const = 0;
    virtual std::string_view address() const = 0;
    virtual bool send(std::span<const std::uint8_t> message) = 0;    // false if closed
    virtual void cork(const std::function<void()>& writes);
    virtual std::size_t buffered() const = 0;
    virtual bool full(std::size_t backpressureBytes) const;
    virtual std::size_t queued() const;
    virtual PathInfo path();
    virtual void end() = 0;                                          // close after what was sent has gone out
    virtual void end(std::uint16_t code, std::string_view reason);
    virtual void close() = 0;                                        // close now
    std::uint64_t bytesIn = 0, bytesOut = 0;
    pipeline::Session session;
};
class ConnectionHandler {                                            // what a transport calls; the session pipeline implements it
public:
    virtual void onConnect(Connection&) = 0;
    virtual void onMessage(Connection&, std::span<const std::uint8_t> message) = 0;
    virtual void onWritable(Connection&) = 0;
    virtual void onDisconnect(Connection&) = 0;
    virtual int  flush() = 0;
    virtual bool pending() const = 0;
};
struct PathInfo { std::uint32_t capacity = 0; float loss = 0; std::uint32_t queueMs = kUnknown; bool appLimited = false; bool measured = false; std::uint64_t bytesAcked = 0; };

The contract between a transport (WebSocket, GameNetworkingSockets, your own) and the session pipeline; everything is called on the server layer's thread. send queues one whole message; cork(writes) runs writes now (a transport that can batch puts the messages sent inside it on the wire together); buffered() is bytes accepted by send that the transport has not sent; full(n) is true when the write pass should stop; queued() is the transport's own reading of its queue, default buffered(); end(code, reason) closes with a close code and reason if the transport has them (the default ignores them). PathInfo is what a transport can say about the path, read about every Options::linkReportIntervalMs; a field it cannot give is 0 (capacity, loss) or kUnknown (queueMs); measured: the transport's own measurement, used as it is; appLimited: the capacity sample was taken while the connection was not filling the path (at best a lower bound); bytesAcked: cumulative bytes the peer has acknowledged, 0 if the transport does not say. ConnectionHandler::flush writes what the world queued and does the handler's other periodic work; pending() is true while only flush() can finish some work (the server layer waits for it before it stops).

server::Inputs

explicit Inputs(ecs::Interest& interest, InputPolicy policy = {});   ~Inputs();
template <class Input, class Fn> Inputs& apply(Fn&& fn);
template <class Input, class Row, class Step> Inputs& apply(const ecs::Typed<Row>& component, Step step);
template <class Input, class Fn> Inputs& action(Fn&& fn);
template <class Input> Inputs& valid(std::function<bool(const Input&)> fn);
void checkValidators() const;
bool handle(Client& client, std::uint8_t type, std::span<const std::uint8_t> body);
void run();
void onError(std::function<void(Client&, std::string_view what)> fn);   std::size_t failed() const;
void entityOf(std::function<ecs::Entity(Client&, ecs::Entity)> fn);
std::uint32_t applied(const Client& c) const;   int queued(const Client& c) const;   std::uint64_t dropped(const Client& c) const;
float stepSeconds() const;   int rate() const;   int maxPerTick() const;   int queueLimit() const;

enum class Excess : std::uint8_t { Wait, Drop };
enum class Starved : std::uint8_t { Skip, Repeat, Neutral };
struct InputPolicy { int rate = 0; int maxPerTick = 0; Excess excess = Excess::Wait; int queue = 0;
                     Starved starved = Starved::Skip; int repeatTicks = 6; int maxActions = 16; std::uint8_t type = kInputType; };
ItemMeaning
Inputs(interest, policy)reads the clients' input messages (wire type 8), keeps a short queue per client, applies them one at a time with the game's functions, and reports the last one applied as the ack in every tick message. Sets the Interest's input rate and enables the welcome; observes attach and detach. Throws std::invalid_argument if rate, maxPerTick, queue or repeatTicks is below 0 or maxActions is below 1: server::Inputs: rate, maxPerTick, queue, repeatTicks must be >= 0 and maxActions >= 1.
apply<Input>(fn)registers the held input (kind 0; a game has one). fn returns nothing and is one of ([Client&,] ecs::Entity, const Input&[, float dt]), or (Row&, const Input&[, float]) / (Hero&, Mine&, const Input&[, float]) where each Row is a flat struct component of the client's entity, read, passed by reference and written back. A handler that returns a value does not compile (a handler returns nothing: send the result as a message: send(player, Result{...}) ...). Registering the same type again replaces its handler; another type as the held input throws std::logic_error naming both.
apply<Input>(component, step)the common case: step(Row&, const Input&, float dt) steps the row of the client's entity in component; skipped if the entity is not alive or has no such row.
action<Act>(fn)registers an act (kind 1 to 255, from the struct's name: its id is the next free one on the server's table, sent to the clients). Never dropped by the budget; at most maxActions per client per run(), the rest wait. Two acts with the same struct name throw std::logic_error. An act is at most 255 bytes packed (a static_assert says THIS ACTION IS TOO BIG). A server::Game writes on<Jump>(fn) instead, which is this plus the message.
valid<Input>(fn)a check: an input for which fn says false is dropped (counted in dropped()). Before or after the input is registered. One that is never registered is an error when the game starts: checkValidators() throws std::logic_error (server::Inputs::valid<X>(): X is not registered as the held input or an act ...); Game::open calls it.
handle(client, type, body)true if type is the input message (handled or dropped). Copies into a fixed queue: no allocation, no game code. A sequence not newer than the last received (serial arithmetic) is ignored; a cut-short or unknown-kind message loses the rest of its batch and is counted.
run()once per tick, in a phase before the simulation. For each client, in sequence order, calls the registered function of each entry, then interest.setInputSequence. Held inputs: at most maxPerTick per client per run, each with dt = 1 / rate.
onError(fn)a handler that throws loses that one input; the error goes to fn (default: stderr aether: an input handler (client N) threw: ...), the tick carries on. failed() counts them.
entityOf(fn)asks who a client's entity is at the moment an input is applied: fn(client, the entity the slot knows). Game uses it so that an input after a respawn in the same tick goes to the new entity.
applied(c), queued(c), dropped(c)the ack (last sequence consumed; 0 for a client not attached), the queue length, and the inputs dropped (stale, invalid, over the queue, or over the budget with Excess::Drop).
rate(), maxPerTick(), queueLimit(), stepSeconds()the effective values: rate = the policy's, or the tick rate if 0; maxPerTick = the policy's, or ceil(rate / tickRate) + 1; queueLimit = the policy's or 2 * maxPerTick; stepSeconds = 1 / rate.
InputPolicy fieldDefaultMeaning
rate0input steps per second; 0 = the tick rate.
maxPerTick0held inputs applied per client per run(); 0 = ceil(rate / tickRate) + 1.
excessExcess::Waitheld inputs over the budget: Wait: stay queued for the next runs (the queue keeps the newest queue; when it is full the oldest is dropped and counted); Drop: consumed and acknowledged, not applied.
queue0held inputs kept per client; 0 = 2 * maxPerTick.
starvedStarved::Skipa run with no held input to apply (after the client has sent one): Skip: nothing; Repeat: the last held input again for repeatTicks runs, then a neutral (all-zero) one; Neutral: a neutral one at once. The ack does not move in any case; applies max(1, round(rate / tickRate)) steps per starved run.
repeatTicks6how many runs Repeat repeats.
maxActions16acts applied per client per run; at least 1.
typekInputTypethe wire type of the input message.

server::Players and Player

explicit Players(ecs::Interest* interest = nullptr);
Player& add(Client& client, ecs::Entity entity = ecs::kNoEntity);
void attached(Player& p);
void sync();
void remove(Client& client);
Player* find(const Client& client) const;       Player* find(ecs::Entity e);
std::size_t size() const;   bool empty() const;   /* begin(), end(): range over Player& */
template <class M> void send(Player& p, const M& message);
template <class M> void broadcast(const M& message);
int flush();
std::size_t dropped() const;

class Player {
    Client& client;
    ecs::Entity entity = ecs::kNoEntity;
    std::string query(std::string_view key, std::string fallback = {}) const;
    template <class T> T& user();
    Link link() const;
    std::chrono::milliseconds crowdDelay() const;   std::chrono::milliseconds focusDelay() const;
    void kick(std::string_view reason);
    Dropped dropped() const;
    template <class M> void send(const M& message);
    void show(ecs::Entity e);    void hide(ecs::Entity e);
    void focus(ecs::Entity e);   void unfocus(ecs::Entity e);
};
ItemMeaning
Players(interest)interest is needed for Player::show(); without it show and focus throw std::logic_error (server::Player::show(): this Players has no Interest (server::Players players{&interest})).
add(client, entity)registers a client and returns its Player; does not attach it to the Interest (the world does that, once the player has an entity). Call it in onConnect.
attached(p)call after interest.attach(client, ...): the player sees its own entity in every view, then what it asked to show or focus before it was attached.
sync()a player whose entity was assigned since it was attached (a respawn) is moved to the new one: the interest, the inputs and the client's session.me() follow. Call before every send.
remove(client)forgets the client; queued messages to it are dropped. Call it in onDisconnect.
find(client), find(entity)the Player of a client (one load), or the first whose entity it is; nullptr if none.
send(p, msg), broadcast(msg)queued, and go out in flush(), after interest.send(): a client gets the tick message with the state a message is about before the message. A message too big is dropped (counted in dropped()). One that finds the client's output buffer full waits for the next flush, in order, up to one buffer's worth of bytes per client; beyond that it is dropped (counted). A queued message to a client that has left is dropped. p.client.send(msg) is immediate.
flush()writes the queued messages to the clients' buffers; returns how many went out. Call it in afterSend.
Player::entitythe player's own entity: what the client's me() is. Assign again for a respawn; kNoEntity for a player with no character for a while.
query(key, fallback)the value of ?key=value in the URL the client connected with, or fallback.
user<T>()the game's own struct for this player, default-constructed on first use. One type per game: another type throws std::logic_error.
link()the Link with left and the live backlog and queueMs filled in.
kick(reason)ends the connection after what was queued, telling the client: its session.onClose gets code 4001 and reason (at most 123 bytes).
show / hide / focus / unfocus (e)per-player visibility of one entity in every view, until hidden; before the client is attached they are applied when it is.
crowdDelay(), focusDelay()the Interest's measurements, 0 if the client is not attached.
dropped()this player's Dropped counts.

server::receive and server::Messages

template <class... Handlers>
int receive(Client& client, std::int64_t nowMs, int limit, ecs::Interest& interest, Handlers&... handlers);
template <class... Handlers>
int receive(Client& client, std::int64_t nowMs, ecs::Interest& interest, Handlers&... handlers);

class Messages {
    Messages();   explicit Messages(ecs::Interest& interest);
    template <class M> Messages& on(std::function<void(Client&, const M&)> fn);
    template <class M> Messages& limit(int count, std::chrono::milliseconds per);
    bool handle(Client& client, std::uint8_t type, std::span<const std::uint8_t> body);
    void onError(std::function<void(Client&, std::string_view what)> fn);
    std::size_t failed() const;   std::size_t dropped() const;
};
ItemMeaning
receive(client, nowMs, limit, interest, handlers...)reads what the client sent and gives each message to interest.handle(client, type, body, nowMs) first, then to each handler's bool handle(Client&, std::uint8_t, std::span<const std::uint8_t>) until one returns true. At most limit messages are read; the rest wait in the client's ring for the next tick (Game passes Options::rate.perTick, 16); limit <= 0 reads all. Returns the number of messages read. The overload without limit reads all.
Messages(interest)the ids of message structs go to the clients of this Interest. The default constructor is for a test of the handlers: ids are made but no client is told them.
on<M>(fn)fn(Client&, const M&) for a plain struct M, returning nothing. Its type is the next free one on the table. Throws std::logic_error for a type below 16 (message types below 16 are aether's) and, via the id table, for two structs with the same unqualified name (the message names both).
limit<M>(count, per)at most count messages of M per per from one client (a bucket of count); set after on<M>(). Throws std::invalid_argument("server::Messages::limit<M>(count, per): both must be positive"). What is over is dropped and counted in Client::dropped().perType; the first of a run also warns the client (session.onWarning), the second is dropped silently, the third closes the connection with code 4290.
handle(...)true if type is a registered message (handled or dropped). A body of the wrong size is dropped and counted in dropped(). A handler that throws loses that message; the error goes to onError or stderr (aether: the handler of message type N (client C) threw: ...); failed() counts them.

The Game's own surface (on<M>(fn).limit(...), send, broadcast) is on the server page.