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>:
#include <aether/ecs.h> #include <meadow/Messages.h> // generated from meadow.aether using namespace aether; using meadow::Walker; using meadow::Purse; ecs::Registry registry;
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
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:
| Kind | Register with | The handle | Use it for |
|---|---|---|---|
| Flat struct | registry.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 type | registry.component(Type) | ecs::Component | a layout known only at run time, and tags (a type with no fields). Rows are read and written through Field handles. |
| Local | registry.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:
| Call | When it throws | Message |
|---|---|---|
add | the entity already has the component | ecs::Registry::add: the entity already has 'Walker' (std::logic_error) |
add | the entity is dead | ecs::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 |
get | the entity is dead or has none | ecs::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
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:
| Call | Flat 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 Row | default-constructed T& |
get(e, c) | S& | Row (false if none) | T& |
tryGet(e, c) | S* | (use get and test the row) | T* |
has, remove | all 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:
| Argument | Flat struct | Hand-built type | Local | Selects entities? |
|---|---|---|---|---|
c | S& | ecs::Row | T& | must have it |
ecs::read(c) | const S& | ecs::ConstRow | const 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 parameter | has none of these | ||
ecs::any(c, ...) | no parameter | has 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 astatic_assertsays 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.
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 });
| Call | What 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).
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
| Hook | Runs | The 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 entity | has 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 anything | still 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
onAddhooks in the order they were registered; likewiseonRemoveandonDestroy). - A hook has no effect on rows that exist when it is registered.
create()has no hook (a new entity has no component). Hooks ofaddrun for each component added to the entities of a bulkcreate(n, out).- A change made inside
eachis 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
Rowit was given after changing a component of the same group. - A registry with no hooks and no persisted component pays nothing for them:
add,removeanddestroytest 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_errorat that call: ecs::Registry::remove: a hook of 'Walker' changes the component it is hooked on. - Registering a hook throws
std::invalid_argumentfor an empty function (ecs::Registry::onAdd: the function is empty) or a component of another registry, andstd::logic_errorinside a hook. - An exception thrown by a hook propagates out of the call that ran it. For
onAddthe row has been added already (verified: after the exception above,haswas still true). ForonRemoveandonDestroynothing 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; whenethereby 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, ordestroy(e), whenehas 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.
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)throwsstd::invalid_argumentif 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
Rowof 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 throwsstd::invalid_argument.emit(event)appends a zeroed row and returns it as aRowto fill in. That Row is valid until the nextemitof 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 ofConstRowin emission order. Its iterators stay valid when more is emitted (they index the buffer), but a Row they gave out does not.emitis allowed insideQuery::each: events are not components, so emitting moves no row.- An event or singleton handle of another registry throws
std::invalid_argumentwhen 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.
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
| Parameter | Meaning |
|---|---|
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_errorifstampis 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_errorif called insideQuery::each:ecs::Registry::commit: called inside Query::each.std::logic_errorif a persisted component exists and noPersistenceis 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
- The phases in the order declared, in each the systems in the order added; a system that is not due is skipped.
registry.commit(stamp, now).- The systems of the built-in phase
"send"(so they see the views of this commit), in the order added. persistence.collect(now), ifschedule.persist(persistence)was called.- The
afterSendhooks, 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-thrun()after the run it last ran in (n >= 1;every(1)is every tick). Arun()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 firstrun()whosenowhas 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 isnowplus 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
| Exception | When |
|---|---|
std::invalid_argument | a 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_error | system(), 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.
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:
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
stringandbytes) are not allowed: a row has one size. - Each field has a durable
tagand asinceVersion;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()hasblockLength0. As a component it stores the entity list only (addreturns 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):
Prim | Value | Builder method | C++ type of Field<T> | Width |
|---|---|---|---|---|
Int32 | 0 | int32(name) | std::int32_t | 4 |
Int64 | 1 | int64(name) | std::int64_t | 8 |
UInt16 | 2 | uint16(name) | std::uint16_t | 2 |
UInt32 | 3 | uint32(name) | std::uint32_t | 4 |
UInt64 | 4 | uint64(name) | std::uint64_t | 8 |
Float64 | 5 | float64(name) | double | 8 |
Bool | 6 | boolean(name) | bool | 1 |
Enum | 7 | enumeration(name, allowed = {}) | std::int32_t | 4 |
FixedStr | 10 | string(name, bytes) | std::string_view | N bytes, zero padded |
Int8 | 11 | int8(name) | std::int8_t | 1 |
UInt8 | 12 | uint8(name) | std::uint8_t | 1 |
Int16 | 13 | int16(name) | std::int16_t | 2 |
Float32 | 14 | float32(name) | float | 4 |
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'.
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 givesnull.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):
- Game:
examples/walker/World.h, four lines. - CustomWorld: still a Game, with options and a system of your own.
- ManualWorld: no Game: Registry, Schedule, Interest, Inputs, Players and
receive()by hand. - A bare WorldProcessor: no ECS at all: raw clients and bytes (
examples/echo). - No App: the pieces under App assembled yourself (
examples/assemble).
Rung 1 and 2: Game, and Game with two customisations
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}); } };
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.
#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 callsinterest_.send()after the schedule's commit. BecauseSchedule::run(stamp, now)commits, you never callregistry.commityourself here. - Interest decides who is sent which rows.
attach(client, entity)makes the client a viewer standing where its entity is;detachmust 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 anInputsturns 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 inflush(), which you call afterinterest.send()(here inafterSend): a client gets the tick message with the state a message is about before the message.players_.attached(p)afterinterest_.attachmakes the player see its own entity in every view and applies the shows and focuses requested before it was attached. server::receivereads 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.
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:
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.
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:
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.
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>
| Item | Meaning |
|---|---|
Entity | low 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. |
kNoEntity | the "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;
| Parameter | Meaning |
|---|---|
type | the hand-built ecs::Type of the component. |
S | a 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. |
persist | makes 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. |
reserveRows | rows 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();
| Parameter | Meaning |
|---|---|
T | a 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);
| Parameter | Meaning |
|---|---|
components | two 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;
| Call | Meaning |
|---|---|
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);
| Parameter | Meaning |
|---|---|
e | a live entity of this registry. |
c | the 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. |
value | the 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_errorif the entity is dead or already has the component (also inside a running query of that component). FiresonAdd. 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_errorif the entity is dead or has none, saying what to do. get with aComponentreturns aRow/ConstRowthat is false (operator bool) if the entity is dead or has none; it does not throw. - tryGet returns
nullptrinstead of throwing. - has is false for a dead entity.
- remove does nothing if the entity has none. Fires
onRemovefirst. Inside a running query of that component it throws'Walker' is in a running query; usedeferRemove. A persisted row's removal follows itsonRemovepolicy (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);
| Item | Meaning |
|---|---|
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; };
| Call | Meaning |
|---|---|
operator bool | false 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):nameis the rune topic name if the type is ever persisted;versionis the type's version.field<T>(name)throwsstd::invalid_argumentif there is no such field (ecs::Type 'character': there is no field 'zzz') or ifTis not the C++ type of its Prim (... field 'name' is string(16), not double: use field<string_view>("name")). AnInt32orEnumfield is read asstd::int32_t.fingerprint(): rune's fingerprint of the equivalent descriptor.FieldInfo::offsetis the field's place in a packed row (the wire, view rows, records, fingerprints);slotits place in a row as the pool stores it (equal tooffsetexcept for a component stored as its struct);tagits durable identity across versions;sinceVersionthe 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(); };
| Method | Meaning |
|---|---|
| field methods | add 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; };
| Item | Parameters, 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. |
Tick | stamp, 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);
| Call | Parameters, 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):
| Call | Returns |
|---|---|
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.
| Field | Type, default | Meaning |
|---|---|---|
cellSize | float = 32 | grid cell size in world units; finite and > 0. |
radius | server::Rule<float, const server::Client&>, unset = 64 | how 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(). |
stopOnBadRadius | bool = true in debug, false with NDEBUG | see radius. |
cap | std::uint32_t = 2000 | subscriptions per viewer over all views. |
unsubscribeDelay | std::uint32_t = 3 | sends an entity (or a held cell, at most 255) may be out of sight before Unsubscribed. 0: on the first send. |
maxIgnoreMs | std::uint32_t = 600000 | a longer ignore is cut to this. |
maxIgnored | std::uint32_t = 4096 | ignore entries per viewer. |
budget | std::function<std::size_t(const server::Client&)>, unset = no limit | bytes per send for Delta and Full entries; 0: only headers and Unsubscribed. |
weight, weightFor | functions, 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. |
focus | float = 0.5 | share of a budget the entries sent entity by entity take first. |
cellWeight, nearReserve, crowdEvery, cut | see network | the crowd path under a budget. nearReserve defaults to {after = 30, within = 1.5, share = 0.25}. |
workers | std::uint32_t = 1 | threads 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, layoutType | std::uint8_t = 2, 3, 4, 5, 6 | wire message types; each > 1 and all different. |
sendLayouts | bool = true | send each viewer the layout of every view it can be sent, once. Off: the game sends them. |
sendWelcome | bool = false | attach writes a welcome [player entity u64][tick rate u16][input rate u16] (type welcomeType = 7). Inputs turns it on. |
ownerRowEveryTick | bool = false | the viewer's own row is sent in every send, also in a view's sends that every(k) sits out. Inputs turns it on. |
idleHeaderTicks | std::uint32_t = 1 | sends 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).
| Item | Meaning |
|---|---|
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. |
onStart | once, 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);
| Call | Meaning |
|---|---|
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; };
| Item | Meaning |
|---|---|
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 field | Default | Meaning |
|---|---|---|
rate | 0 | input steps per second; 0 = the tick rate. |
maxPerTick | 0 | held inputs applied per client per run(); 0 = ceil(rate / tickRate) + 1. |
excess | Excess::Wait | held 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. |
queue | 0 | held inputs kept per client; 0 = 2 * maxPerTick. |
starved | Starved::Skip | a 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. |
repeatTicks | 6 | how many runs Repeat repeats. |
maxActions | 16 | acts applied per client per run; at least 1. |
type | kInputType | the 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); };
| Item | Meaning |
|---|---|
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::entity | the 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; };
| Item | Meaning |
|---|---|
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.