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.
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.
| Where | Include | Gives 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. |
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.
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.
#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.
#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().applynames the held input and its rule,on<Chat>takes a message.onJoin()runs when a client connects. Settingp.entitygives the player a body. The?name=Aylain the URL the client used arrives throughp.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.
#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.
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.
#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.
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 eachMovegoes through yourstepon that player's row. - Phase
simulate. Yourupdate(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
sendandbroadcastgo 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.