Tessera API
Describe the world once. Keep your Aether game as it is. Tessera decides which server runs which zone.
Start
Tessera wraps an Aether game. Your Game class does not change.
tessera_world(mygame) # mygame_zone, mygame_coordinator, mygame_test
| Where | Include | Gives you |
|---|---|---|
| Both programs | <tessera/world.h> | WorldConfig, Area, ZoneId |
| Zone server | <tessera/zone.h> | tessera::Zone<Game>, mirrors, effects |
| Coordinator | <tessera/coordinator.h> | Coordinator, hints, capacity |
| Tests | <tessera/testing.h> | A whole world inside one test |
Describe the world
One struct, shared by every program.
inline const tessera::WorldConfig world{ .name = "ashen-vale", .size = 8192, // world units along one side .minZone = 256, // a zone is never cut smaller than this .overlap = 48, // how far a server sees over its border .position = {"x", "y"}, // the members that place an entity .rune = "rune://rune-0.game.internal:7000", };
Run a zone server
Replace server::App with tessera::Zone. That is the whole change to main.
#include <tessera/zone.h> int main() { tessera::Zone<World> zone(world, {.tickRate = 20}); return zone.listen(9000) ? 0 : 1; // waits for zones to be assigned }
Your game can ask what it owns, and hear about changes:
struct World : server::Game, tessera::Hooks { void onAdopt(const tessera::Area& area) override; // this server now owns it void onRelease(const tessera::Area& area) override; // it has gone to another server }; if (tessera::owns(x, y)) spawn(Wolf{x, y});
Run the coordinator
One coordinator is active for a world. Run a second one and it waits as a standby.
#include <tessera/coordinator.h> int main() { tessera::StaticCapacity servers({"zone-1:9000", "zone-2:9000", "zone-3:9000"}); tessera::Coordinator coordinator(world, servers); return coordinator.run(); }
Crossing a border
Nothing to call. An entity that walks into another server's zone is handed over with every row it has, and its player follows. Two hooks tell you when.
void onDepart(ecs::Entity e, tessera::ZoneId to) override; // last tick here void onArrive(ecs::Entity e, tessera::ZoneId from) override; // first tick here tessera::link(rider, mount); // these two always cross together
| Option | Default | What it sets |
|---|---|---|
.hysteresis | 8 units | How far past the border an entity goes before it is handed over |
.handoffBudget | 64 per tick | How many entities may cross one border in one tick |
Mirrors
A mirror is a read-only copy of an entity that lives just over the border. Say which rows to mirror, then query them like any other.
// in onStart() tessera::mirror<Walker>(); tessera::mirror<Health>().every(2); // anywhere const Walker& w = get<Walker>(target, READONLY); // works for a mirror if (tessera::isMirror(target)) { /* it cannot be changed here */ }
Players see mirrored entities exactly like local ones. The border is invisible on screen.
Effects
To change something another server owns, send an effect. It is a plain struct, delivered once to whichever server owns the target on arrival.
struct Damage { ecs::Entity from; std::uint32_t amount; }; // the server that casts tessera::effect(target, Damage{caster, 120}); // the server that owns the target, in onStart() tessera::onEffect<Damage>([this](ecs::Entity target, const Damage& d) { get<Health>(target).hp -= d.amount; });
Server-only state
Plain rows cross a border by themselves. A server-only component (any C++ type) needs a pair of functions to pack and unpack it.
tessera::pack<AiState>(
[](const AiState& s) { return PackedAi{s.target, s.mood, s.cooldowns()}; },
[](const PackedAi& p) { return AiState::from(p); });
tessera::rebuild<PathCache>(); // or: do not send it, build a fresh one on arrival
Scheduler hints
The scheduler works without help. Hints let you tell it what you know and it cannot.
const tessera::Area capital{3840, 3840, 512, 512}; coordinator.pin(capital, "zone-1:9000"); // always this server coordinator.presplit(bossArena, at("20:55"), 4); // four servers, before the event coordinator.name("harbour", harbourArea); // a label for dashboards and the CLI coordinator.keepTogether(arenaFloor); // never cut this area coordinator.drain("zone-3:9000"); // move everything off it, then release it
Tuning
Every number has a default. Change them in WorldConfig::scheduler.
| Option | Default | What it sets |
|---|---|---|
.splitAbove | 60% | Share of the tick budget above which a server sheds or splits a zone |
.mergeBelow | 25% | Share below which zones are packed onto fewer servers and merged |
.cooldown | 60 s | How long a zone is left alone after it changed |
.movesAtOnce | 2 | Zone moves in flight across the world |
.spareServers | 1 | Idle servers kept ready for a failure or a rush |
The scheduler always works in this order: recover, shed, split, pack, merge.
Capacity
Tessera asks for servers through two calls. Use a provider that ships, or write your own in a dozen lines.
struct Capacity { virtual std::optional<Server> acquire() = 0; // give me a server virtual void release(const Server& server) = 0; // release this server };
| Provider | Where servers come from |
|---|---|
tessera::StaticCapacity | A list of addresses you give it |
tessera::KubernetesCapacity | Pods of a workload, scaled up and down for you |
tessera::KubernetesCapacity servers({ .namespace_ = "game", .workload = "zone-server", .min = 2, .max = 64, });
Client
A client connects to one address and never learns about zones. When its character changes servers, the session follows and prediction carries on.
client::Session session(tessera::gateway("wss://play.example.com")); auto me = session.predict<Walker>(); // the Aether client, unchanged session.onSwitch([](const tessera::Switch& s) { log("now on {} after {} ms", s.server, s.elapsedMs); });
Watching it
coordinator.onChange([](const tessera::Change& c) { log("{} {} -> {} at tick {}", c.kind, c.zone, c.server, c.tick); // split, move, merge, recover }); for (const tessera::ZoneInfo& z : coordinator.topology()) draw(z.area, z.server, z.load, z.players);
The map is a Rune topic. Any service can subscribe to it and see every split, move and merge as it happens.
Command line
$ tessera status ashen-vale ZONE AREA SERVER LOAD PLAYERS z0.1 0,0 4096x4096 zone-1:9000 31% 212 z0.2.3 6144,0 2048x2048 zone-2:9000 44% 390 harbour 4096,2048 256x256 zone-4:9000 58% 801 $ tessera move harbour zone-5:9000 moved at tick 918204 in 140 ms, 801 players switched $ tessera drain zone-3:9000 $ tessera replay ashen-vale --at "yesterday 21:00"
Testing
A coordinator, several zone servers and real clients, inside one unit test.
tessera::test::World<World> w(world, {.servers = 3}); client::Session a(w.url()); a.connect(); w.move(w.zoneAt(100, 100), w.server(2)); // force a move under the player ASSERT_TRUE(test::pump(a, [&] { return w.settled(); })); EXPECT_EQ(w.owners(100, 100), 1); // one owner, always EXPECT_EQ(a.reconnects(), 0);