ARCANUM
C++23 · server and client · guide

Get started with Aether

Build a small world in five files: players walk, chat and earn coins that survive a restart. Every example on these pages compiles.

Shared.hmeadow.aether · step() server::Gameview · inputs · on · spawn · persist client::Sessionview · predict · input · act · send rowsinputs Storefile · Rune Your gamedraws

What Aether is

Aether is the netcode of a game: the tick, who sees what, the held controls, prediction and saving. You write the rules of your game as plain C++ and Aether moves them between a server and its clients.

It stops where your game begins. It never draws and never blends two positions for you; it hands you values (now, before, alpha, correction, serverTime) and you decide what to do with them.

Three ideas carry the whole SDK:

  • Plain structs. A row, a message and a held input are ordinary structs. No macro, no id, no base class.
  • One rule, two sides. The function that moves a player is written once. The server runs it for the truth and the client runs it for the feeling of no delay.
  • The server decides what is sent. You say who can see which rows. Aether finds what changed and sends only that.

These pages build one small game, meadow, from nothing. Each page adds a piece to it. The next page goes deeper into the data model.

What to include

There is one include per side, so the client never links server code.

WhereIncludeGives you
Both sides<aether/shared.h>Plain structs, String<N>, List<T, N>, ecs::Entity. No server code.
Server<aether/server.h>server::Game, Host, App, the stores.
Client<aether/client.h>client::Session, views and prediction. Link aether_client only.
Tests<aether/testing.h>A server and its clients inside one test. The only include a game test needs next to gtest.
Put your game in a namespace. Two structs of the same name in two files of one program are a silent ODR violation. Aether names a row or a message by the struct's name without its namespace, so the namespace costs you nothing on the wire.

1. Describe the data

Start with what travels. In meadow, a player is a Walker that others can see, a Move says which way the controls are held, a Purse holds coins that only its owner sees, and players can talk.

Write those once in a small contract file. A tool turns it into a C++ header, and into JavaScript if you have a web client.

examples/meadow/meadow.aether
namespace meadow;

message Walker { f64 x; f64 y; f64 speed; }          // a row every nearby player sees
message Move   { f32 dx; f32 dy; }                   // the controls as they are held
message Purse  { string<16> owner; u32 gold; }       // a row only its owner sees, and saved
message Chat   { string<80> text; }                  // a message, client to server
message Said   { string<16> who; string<80> text; } // a message, server to clients

Next, the one thing both sides share besides data: the rule of movement. It takes the row, the controls and the time step.

examples/meadow/Shared.h
#pragma once
#include <cmath>

#include <aether/shared.h>
#include <meadow/Messages.h>        // generated from meadow.aether

using meadow::Walker;
using meadow::Move;

// The rule of movement. The server runs it for every Move it receives;
// the client runs it at once (prediction) and again when the server corrects it.
inline void step(Walker& w, const Move& m, float dt) {
    double dx = m.dx, dy = m.dy;
    if (const double len = std::hypot(dx, dy); len > 1) { dx /= len; dy /= len; }
    w.x += dx * w.speed * dt;
    w.y += dy * w.speed * dt;
}

Notice that step knows nothing about networks. It is a plain function over plain structs, which is why the same code can run on both sides.

A contract file is optional. The generated structs are ordinary C++, so you can write them by hand in a shared header instead. The contract file explains what the tool gives you on top: one source for every client, and a check that a client and a server were built from the same version.

2. Write the server

A world is a class that extends server::Game. You say what each struct is, and Aether does the rest: the tick loop, receiving, sending, the client list and the cleanup when someone leaves.

examples/meadow/World.h
#pragma once
#include <aether/server.h>

#include "meadow/Shared.h"

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

class World : public server::Game {
public:
    explicit World(ecs::Store& store) : Game({.store = &store, .contract = meadow::contract}) {}

    void onStart() override {
        persist<Purse>().key(&Purse::owner);                 // saved, filed under its owner
        view<Walker>().spatial("x", "y");                    // seen by players nearby
        view<Purse>().ownerOnly();                           // seen by its owner only
        inputs().apply<Move>(step);                          // what a held Move does
        on<Chat>([this](Player& p, const Chat& c) {          // a message from a client
            broadcast(Said{String<16>(p.query("name", "anon")), c.text});
        });
    }

    void onJoin(Player& p) override {
        const std::string name = p.query("name", "anon");
        p.entity = spawn(Walker{0, 0, 60},
                         load<Purse>(name).value_or(Purse{String<16>(name), 0}));
    }

    void update(float) override {
        for (Player& p : players()) get<Purse>(p.entity).gold += 1;      // a coin a tick
    }
};

Read it from the top:

  • onStart() runs once, before anyone joins. It is where you say what each struct is: a view is a set of rows that clients can see, inputs().apply names the held input and its rule, on<Chat> takes a message.
  • onJoin() runs when a client connects. Setting p.entity gives the player a body. The ?name=Ayla in the URL the client used arrives through p.query.
  • update() runs every tick after the inputs. get<Purse>(e) is a reference to the row, so changing it is all it takes: nothing is sent or saved by hand.

The program around it is short. The store is where saved rows live, and FileStore keeps them in a file.

examples/meadow/server.cpp
#include <cstdio>
#include <cstdlib>

#include "meadow/World.h"

int main(int argc, char** argv) {
    ecs::FileStore store("meadow.db");
    World world(store);
    server::App app(world, {.tickRate = 20});
    const std::uint16_t port = argc > 1 ? std::atoi(argv[1]) : 9000;
    return app.listen(port, [](std::uint16_t p) { std::printf("meadow on %u\n", p); }) ? 0 : 1;
}

listen blocks until the server stops, and returns false if the port cannot be bound.

Write override. With a wrong signature the compiler says only "marked override, but does not override", and without override your function silently never runs. update takes a float: a double dt does not override.

3. Write the client

A client opens a client::Session on a URL, asks it for the views it wants, and polls it from its own frame loop. There is no thread: poll receives, reconciles and sends.

examples/meadow/client.cpp
#include <chrono>
#include <cstdio>

#include <aether/client.h>

#include "meadow/Shared.h"

using namespace aether;

static double lerp(double a, double b, double t) { return a + (b - a) * t; }

int main(int argc, char** argv) {
    client::Session session(argc > 1 ? argv[1] : "ws://localhost:9000/?name=Ayla",
                            {.contract = meadow::contract});
    session.onClose([](std::uint16_t code, std::string_view why) {
        std::printf("closed %u: %.*s\n", code, int(why.size()), why.data());
    });
    session.onError([](std::string_view what) { std::printf("error: %.*s\n", int(what.size()), what.data()); });

    auto players = session.view<Walker>();               // the rows of every walker near me
    auto purses  = session.view<meadow::Purse>();        // my own purse
    auto me      = session.predict<Walker>();            // my own row, predicted
    me.apply<Move>(step);                                // the same rule the server runs
    session.on<meadow::Said>([](const meadow::Said& s) {
        std::printf("%s: %s\n", s.who.str().c_str(), s.text.str().c_str());
    });
    session.connect();

    using Clock = std::chrono::steady_clock;
    const auto start = Clock::now();
    auto lastPrint = start;
    bool said = false;
    while (Clock::now() - start < std::chrono::seconds(4)) {
        session.poll(5);                                  // receive, reconcile, send
        me.input(Move{1, 0});                             // every frame: the controls as they are now
        if (session.ready() && !said) { session.send(meadow::Chat{String<80>("hello")}); said = true; }
        if (Clock::now() - lastPrint > std::chrono::milliseconds(500)) {
            lastPrint = Clock::now();
            const double a = me.alpha();
            const auto purse = purses.find(session.me());
            std::printf("x=%.1f gold=%u\n", lerp(me.before().x, me.now().x, a), purse ? purse->gold : 0);
        }
    }
}

Notice what the client never does: it never waits for the server. me.input(Move{1, 0}) is applied at once through step, so the player moves on the next frame. The server runs the same rule on the same input a moment later, and if it disagrees, me is corrected.

The two view calls ask for rows. The server decides whether a given row is sent at all, so a client only ever has what it is allowed to see.

4. Build and run

A game lives in examples/meadow/. Add one line to the AETHER_BUILD_EXAMPLES block of CMakeLists.txt:

aether_game(meadow)      # builds meadow_server, meadow_client and, if tests/MeadowTest.cpp exists, meadow_test

That line finds meadow.aether, generates <meadow/Messages.h> from it, rebuilds when the file changes, and links it into the server, the client and the test. There is no second line to write.

cmake --build build --target meadow_server meadow_client -j4
build/meadow_server &
build/meadow_client

The client prints the chat message the server broadcast, then its position and its coins twice a second:

Ayla: hello
x=23.5 gold=10
x=53.7 gold=19
x=83.7 gold=29
x=113.7 gold=39

Stop the server, start it again and run the client with the same ?name=Ayla. The coins carry on from where they were, because the Purse was saved to meadow.db.

One build at a time on a small machine. cmake --build build --target meadow_test -j2 builds only your game and its test; the libraries are built once, before.

What happens in a tick

You never write this loop, but its order explains most behaviour. A tick of a server::Game runs these steps, in this order:

  • Receive. Each player's pending messages are read.
  • Phase input. Held inputs run, so each Move goes through your step on that player's row.
  • Phase simulate. Your update(dt) runs, then any systems you added to the schedule.
  • Commit. Every view is rebuilt from the rows as they are now. A row nobody changed is not sent.
  • Phase send. Each client is sent the changes in the views it can see.
  • After send. The messages you queued with send and broadcast go out, so "match over" never arrives before the last hit.

The tick rate is a setting of the server ({.tickRate = 20} above). The client does not count ticks: it asks the session for alpha and serverTime.

Where to go from here

You now have the whole shape: data, a server world, a client. Each of the other pages takes one part and covers it completely, starting with a guided tour and ending with a reference of every call.

  • Data: entities, the three kinds of component, every type a row may hold, the contract file.
  • Views: what clients are sent, and every option that decides who sees what.
  • Server: the game class, players, inputs, messages, options.
  • Client: sessions, views, prediction, corrections and clocks.
  • Saving: stores, persist, loading, Rune.
  • Network: transports, links, budgets, limits, several games.
  • ECS: the registry underneath: queries, hooks, groups, the schedule.
  • Testing: test helpers, building, diagnostics.