ARCANUM
C++23 · on top of Aether

Tessera API

Describe the world once. Keep your Aether game as it is. Tessera decides which server runs which zone.

Capacityacquire · release Coordinatorsplit · move · merge Runethe map, as a log zone server · your Game zone server · your Game zone server · your Game handoffs · effects

Start

Tessera wraps an Aether game. Your Game class does not change.

tessera_world(mygame)   # mygame_zone, mygame_coordinator, mygame_test
WhereIncludeGives 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
OptionDefaultWhat it sets
.hysteresis8 unitsHow far past the border an entity goes before it is handed over
.handoffBudget64 per tickHow many entities may cross one border in one tick
Saved rows cross too. Only the server that owns the entity now may write them.

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;
});
The same call works when the target is local. Write the ability once.

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.

OptionDefaultWhat it sets
.splitAbove60%Share of the tick budget above which a server sheds or splits a zone
.mergeBelow25%Share below which zones are packed onto fewer servers and merged
.cooldown60 sHow long a zone is left alone after it changed
.movesAtOnce2Zone moves in flight across the world
.spareServers1Idle 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
};
ProviderWhere servers come from
tessera::StaticCapacityA list of addresses you give it
tessera::KubernetesCapacityPods 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);