Not translated yet — showing English.

PlayServ SDK

The game backend that ships with the gameplay. PlayServ is a backend-as-a-service for live games: a studio runs its game's backend — data, players, rooms, matchmaking, commerce — without hosting one. The SDK is how your code, on the server and in the engine, works with that platform.

What follows is the short list of what is different here. Everything on it is decided once for a project and configured rather than written; what you call lives on the module pages, and every section ends by naming the page that owns it.

The simulation is not your code

Rooms, collision, locomotion, prediction and sync all run inside the platform. Your game is declarations (entities, maps, abilities, drop tables, sync policy), hooks (your rules, called at named steps), events (subscribe, don't poll) and operations (what you ask for or command). Every module page is organised around exactly those four.

What you skip is concrete: a game loop, snapshot assembly, a delta encoder, collision resolution, movement integration, reconnect handling, hit validation with lag compensation. A game like Tanks fits in ~300 lines. See Getting Started, which builds exactly that.

Mutating declared state is the network call

There is no send. You declare how a field synchronises — one attribute beside the field — and changing it is the network operation: deltas against the last acknowledged state, the aspect as the unit of policy, priority and send rate, the retained window, before- and after-change hooks. Nothing downstream is written by you.

The same move applies to everything else that is declared: an event, an RPC, a group, a leaderboard axis. A declaration is the input to the typed API, to the admin panel that renders it, and to the codegen for every binding — which is also why the declaration, not the generated code, is the thing you version. See Data & Subscriptions and Schema as Code.

Interfaces follow the actor, not the side

There is no client SDK and no server SDK. One SDK ships, and what a call may do is decided by the actor behind it — a player, a service, a bot brain, an operator.

The case it is built for is a player's machine that creates a room and then runs it: a master-client, holding the room-owner interfaces and nothing more. A room-visitor build has no kick and no close — not disabled, absent.

Rights are composed from atomic permissions, so there are no built-in role tiers, and a role gates data down to the row and the column. See Authority, and Access & Roles for how a grant is spelled.

One design, narrowed twice — over one stack

How it is written

The SDK is one design with two narrowing escapes, and nothing moves down a level until the level above cannot carry it. Common principles are identical in every binding. A language's shape takes only what its paradigm cannot express the common way. An engine's shape takes only what an engine reshapes on top of its language — in Unreal a declaration rides inside the engine's own reflection macro.

How it runs

Your game code addresses modules and nothing else. Modules are assembled from four primitives — events, RPC, data and subscriptions, groups. Under them sits the hub you never call: dependency injection, module mounting, the session, state recovery, message quality of service. Under that, transport adapters, one per protocol, and which one carries a call is not something your code decides or notices.

Both halves in full: How the SDK Is Built, ending at Under the Hood.

Modules compose; nothing subclasses

There is no base module to derive from and no hierarchy to extend — modules form a graph, because real features cross branches: matchmaking reserves seats in rooms, drops place items through the map, a chat lives inside a room.

"Inheritance" covers four different mechanisms here, and they are worth telling apart: an entity's RPCs are part of the entity; a preset is a named bundle of aspects, not a base class; overriding a platform step is an attribute on your replacement; a module borrows another through a decorator that narrows the borrowed interface. See Inheritance & Composition.

Who sees what is declared, not filtered on the client

At forty players a whole-room snapshot is fine; at two hundred it is not, and the fix is not a bigger pipe. Interest rules decide who receives which slice, and per-actor packets and broadcast are two delivery modes of one declared model — moving between them is configuration, not a rewrite. Distant things degrade through declared detail tiers before they disappear.

The part that is a security property rather than a bandwidth one: state that must not leak is never sent. Fog of war and owner-only fields are absent from the packet, not hidden on the client. Spectators, admins and replays get their wider view by holding a wider grant. See Visibility.

What survives losing a host

A host dying does not end the match. Room state is not copied between hosts while play runs — a single owner is what keeps ordering out of consensus — and what makes the match survivable instead is that the state is declared, and declared state is held outside the host. It is snapshotted on a declared interval, and a replacement resumes from the last snapshot.

So the replacement has the state whole — but as of that snapshot. Complete, not current. What it costs is the play since the last snapshot; what is not covered is anything you kept only in engine actors. A deploy uses the same mechanism, minus the loss: draining a host is the failover path run deliberately. See What Survives Losing a Host, and Rooms for the grace window a player re-enters through.

Any platform step can be yours

Every platform scenario is a chain of registered functions, and you replace a link or wrap it. Sign-in, entry validation, purchase, submission, upload — each is a named step, and your replacement is declared with an attribute, with versions chosen by condition and the platform's own step as the fallback.

This is what "customisable platform" means concretely, and it is what stands in place of shipping you our source: you replace the steps rather than fork the thing that runs them. See Extensibility.

One surface, six languages

One contract, six projections: C#, TypeScript, Python and Go on the server; generated Unreal C++ and Unity C# in the engine. Every code sample on this site shows all six, and where a binding has no surface for a step the tab names the reason instead of pretending — the step runs off the engine, or another actor holds the right to make that call.

Two consequences worth knowing before you pick a language: RPC takes SDK objects by reference rather than flattened DTOs, and the async primitives are core rather than bolted on — channels, streams and group addressing, so you can talk to a whole group and collect the answers, or consume a file as chunks while it is still uploading.

There is also a deterministic in-memory host that runs your game code with no backend behind it and time under your control, so a test is a test rather than a race — see Threads, Lifetime and Testing.

What is deliberately not in the SDK — deploys, billing, org and user administration — lives on the operator plane. The sidebar is the map of everything else; Getting Started is the shortest way in.

Not translated yet — showing English.

Getting Started

A playable arena (map, tanks, shooting, drops), declared end to end. Nothing below is a game loop: the simulation runs inside the platform, and this is all the code there is.

Before you start. A project with a dev environment (created on the operator plane, which owns that lifecycle), the playserv CLI signed in to it, and the SDK package for your binding — nothing else is installed into your game.

User flow

Every call you make is one of the examples below; the steps between them are the platform acting on what a declaration said. The ability, the stat and the drop-table in the figure are entity presets — declarations on entities, not modules of their own.

1. Declare the world

Entities are your schema plus their live aspects. One attribute per behaviour, beside the field it describes:

[Entity("tank")]
public class Tank
{
    [Sync] public Vector3 Position;                     // synced every tick
    [Sync(Hz = 10)] public float Fuel;               // ~10 times a second
    [Sync(To = Scope.Owner)] public int Ammo;        // owner's eyes only

    [Stat(Max = 100, AtMin = "death")] public Stat Hp;
    [Body(Shape.Capsule, Radius = 0.6f)] public Body Body;
    [Motion(Model.Tank, MaxSpeed = 8f, TurnRateDeg = 120f)] public Motion Motion;
}

@Entity('tank')
export class Tank {
  @Sync() position!: Vector3;                     // synced every tick
  @Sync({ hz: 10 }) fuel = 0;                  // ~10 times a second
  @Sync({ to: Scope.Owner }) ammo = 0;         // owner's eyes only

  @Stat({ max: 100, atMin: 'death' }) hp: Stat;
  @Body({ shape: 'capsule', radius: 0.6 }) body: Body;
  @Motion({ model: 'tank', maxSpeed: 8, turnRateDeg: 120 }) motion: Motion;
}

@entity("tank")
class Tank:
    position: Vector3 = sync()                      # synced every tick
    fuel: float = sync(hz=10)                    # ~10 times a second
    ammo: int = sync(to=Scope.OWNER)             # owner's eyes only

    hp = stat(max=100, at_min="death")
    body = collision.body(shape="capsule", radius=0.6)
    motion = locomotion.motion(model="tank", max_speed=8.0, turn_rate_deg=120.0)

UCLASS(PSEntity = "tank")
class UTank : public UObject
{
    GENERATED_BODY()

    UPROPERTY(PSSync)                        FVector3f Position;   // synced every tick
    UPROPERTY(PSSync = (Hz = 10))            float     Fuel;       // ~10 times a second
    UPROPERTY(PSSync = (To = "Owner"))       int32     Ammo;       // owner's eyes only

    UPROPERTY(PSStat = (Max = 100, AtMin = "death"))                                FPSStat Hp;
    UPROPERTY(PSBody = (Shape = "Capsule", Radius = "0.6"))                         FPSBody Body;
    UPROPERTY(PSMotion = (Model = "Tank", MaxSpeed = "8.0", TurnRateDeg = 120))     FPSMotion Motion;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

[Entity("tank")]
public class Tank
{
    [Sync] public Vector3 Position;                     // synced every tick
    [Sync(Hz = 10)] public float Fuel;               // ~10 times a second
    [Sync(To = Scope.Owner)] public int Ammo;        // owner's eyes only

    [Stat(Max = 100, AtMin = "death")] public Stat Hp;
    [Body(Shape.Capsule, Radius = 0.6f)] public Body Body;
    [Motion(Model.Tank, MaxSpeed = 8f, TurnRateDeg = 120f)] public Motion Motion;
}

Mutating a [Sync] field is the network operation. There is no snapshot to assemble and no send call to make.

None of those types are yours to define, and each is owned by one page:

The enums are closed. A rule no member covers is written as a predicate rather than a new member: [Aspect("loadout", Visible = "owner == caller.player")] is how per-field visibility is expressed when Scope.Owner is not quite the rule you meant (Data).

2. Declare the room

A room template says what a session is, and names the declarations it draws on. There is no room class to inherit and no tick method to fill, because room internals are the platform's:

[RoomTemplate("battle", Map = "arena")]
public static class Battle
{
    public static int Capacity = 8;
    public static Tick Tick = Tick.Hz30;
}
[Map("arena", Seed = 42, Bounds = "160x160")]
public static class Arena
{
    [Scatter("rock", Count = 40, MinSpacing = 6)] public static ObstacleSet Rocks;
}
[DropTable("crate-loot")]
public static partial class CrateLoot
{
    [Entry("ammo.shell", Weight = 60, Count = "2..4")] public static Drop AmmoShell;
    [Entry("railgun", Weight = 1)]                     public static Drop Railgun;  // the jackpot
}
[Projectile("shell", Cooldown = 1.5f)]
public static class Shell
{
    [Ballistics(Speed = 24, Gravity = 9.8f)] public static Flight Arc;
    [Ammo("ammo.shell", PerShot = 1)]        public static Ammo Load;
    [Effect(Damage = 35)]                    public static Effect OnHit;
}

@RoomTemplate('battle', { map: 'arena' })
export class Battle {
  static capacity = 8;
  static tick = Tick.hz30;
}
@Map('arena', { seed: 42, bounds: '160x160' })
export class Arena {
  @Scatter('rock', { count: 40, minSpacing: 6 }) rocks: ObstacleSet;
}
@DropTable('crate-loot')
export class CrateLoot {
  @Entry('ammo.shell', { weight: 60, count: [2, 4] }) ammoShell: Drop;
  @Entry('railgun', { weight: 1 }) railgun: Drop;              // the jackpot
}
@Projectile('shell', { cooldown: 1.5 })
export class Shell {
  @Ballistics({ speed: 24, gravity: 9.8 }) arc: Flight;
  @Ammo('ammo.shell', { perShot: 1 }) load: Ammo;
  @Effect({ damage: 35 }) onHit: Effect;
}

@room_template("battle", map="arena")
class Battle:
    capacity = 8
    tick = Tick.HZ30

@Map("arena", seed=42, bounds="160x160")
class Arena:
    rocks = scatter("rock", count=40, min_spacing=6)

@drop_table("crate-loot")
class CrateLoot:
    ammo_shell = entry("ammo.shell", weight=60, count=(2, 4))
    railgun = entry("railgun", weight=1)                       # the jackpot

@projectile("shell", cooldown=1.5)
class Shell:
    arc = ballistics(speed=24, gravity=9.8)
    load = ammo("ammo.shell", per_shot=1)
    on_hit = effect(damage=35)

USTRUCT(PSRoomTemplate = (Name = "battle", Map = "arena", Capacity = 8, Tick = 30))
struct FBattle { GENERATED_BODY() };

USTRUCT(PSMap = (Name = "arena", Seed = 42, Bounds = "160x160"))
struct FArena
{
    GENERATED_BODY()

    UPROPERTY(PSScatter = (Obstacle = "rock", Count = 40, MinSpacing = 6)) FPSObstacles Rocks;
};

USTRUCT(PSDropTable = "crate-loot")
struct FCrateLoot
{
    GENERATED_BODY()

    UPROPERTY(PSEntry = (Item = "ammo.shell", Weight = 60, Count = "2..4")) FPSDrop AmmoShell;
    UPROPERTY(PSEntry = (Item = "railgun", Weight = 1))                     FPSDrop Railgun;  // the jackpot
};

USTRUCT(PSProjectile = (Name = "shell", Cooldown = "1.5"))
struct FShell
{
    GENERATED_BODY()

    UPROPERTY(PSBallistics = (Speed = "24.0", Gravity = "9.8")) FPSFlight Arc;
    UPROPERTY(PSAmmo = (Item = "ammo.shell", PerShot = 1))      FPSAmmo Load;
    UPROPERTY(PSEffect = (Damage = 35))                         FPSEffect OnHit;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

[RoomTemplate("battle", Map = "arena")]
public static class Battle
{
    public static int Capacity = 8;
    public static Tick Tick = Tick.Hz30;
}
[Map("arena", Seed = 42, Bounds = "160x160")]
public static class Arena
{
    [Scatter("rock", Count = 40, MinSpacing = 6)] public static ObstacleSet Rocks;
}
[DropTable("crate-loot")]
public static partial class CrateLoot
{
    [Entry("ammo.shell", Weight = 60, Count = "2..4")] public static Drop AmmoShell;
    [Entry("railgun", Weight = 1)]                     public static Drop Railgun;  // the jackpot
}
[Projectile("shell", Cooldown = 1.5f)]
public static class Shell
{
    [Ballistics(Speed = 24, Gravity = 9.8f)] public static Flight Arc;
    [Ammo("ammo.shell", PerShot = 1)]        public static Ammo Load;
    [Effect(Damage = 35)]                    public static Effect OnHit;
}

The quoted ids are content keys, not free text:

playserv push refuses a declaration whose key does not exist in the environment it targets, so a mistyped key fails at deploy time instead of at the first cast. Wherever the template lives, it stays retunable without an engine redeploy: the pushed model is what live-ops edits in the panel.

3. Write your rules as hooks

Hooks are cloud functions the platform calls at named steps. Typed in, typed out — no context bags, no loggers in the signature:

[Before(Rooms.Entry, room: "battle")]
public static Verdict ValidateEntry(EntryRequest entry) =>
    entry.Player.IsBanned
        ? entry.Reject(Problem.Banned, "banned from this project")
        : entry.Accept();

[After(Auth.SignIn, created: true)]
public static async Task GrantStarterPack(Player player)
{
    await player.Inventory.Grant("ammo.shell", count: 20);
}

[After(Stats.Depleted, stat: "hp")]
public static void OnDeath(StatEvent e) => CrateLoot.RollAt(e.Entity.Position);

export const validateEntry = before(Rooms.entry, { room: 'battle' },
  (entry: EntryRequest) =>
    entry.player.isBanned
      ? entry.reject(Problem.banned, 'banned from this project')
      : entry.accept());

export const grantStarterPack = after(Auth.signIn, { created: true },
  async (player: Player) => {
    await player.inventory.grant('ammo.shell', { count: 20 });
  });

export const onDeath = after(Stats.depleted, { stat: 'hp' }, (e: StatEvent) => {
  CrateLoot.rollAt(e.entity.position);
});

@before(rooms.entry, room="battle")
def validate_entry(entry: EntryRequest) -> Verdict:
    if entry.player.is_banned:
        return entry.reject(Problem.BANNED, "banned from this project")
    return entry.accept()

@after(auth.sign_in, created=True)
async def grant_starter_pack(player: Player):
    await player.inventory.grant("ammo.shell", count=20)

@after(stats.depleted, stat="hp")
def on_death(e: StatEvent):
    CrateLoot.roll_at(e.entity.position)

A Before gate can refuse the step; an After observer runs once it has committed and cannot. So a starter pack that did not land costs 20 shells, not the sign-in. Extensibility has the rest.

Almost nothing in that block does the work it appears to do:

Generated types for the engine

playserv schema codegen   # Unreal C++ → Plugins/PlayServ/Generated · Unity C# → Packages/com.playserv.sdk/Generated

Run it (or let CI run it) after every schema push — types are regenerated, never hand-edited, and the generated Tank is the pushed Tank. playserv push reads an engine project exactly as it reads a server project: the UHT specifiers and the C# attributes are the declaration, so pointing the CLI at the UE or Unity project is the whole export step. Which thread a callback lands on, and when a subscription ends, are fixed with the runtime model — Threads, Lifetime and Testing.

4. Connect a client

The client API is symmetrical: the same modules, and what a build may call is decided by the key it runs under. An engine build carries a player key — projectKey here, the credential for one project and one environment, issued in the panel and shipped inside the build. It names no roles: roles resolve server-side on every request, and the player behind them arrives with SignIn. The engine bindings are first-class here; the server bindings drive the same surface headlessly (a bot brain, a load test, an ops tool):

var playserv = await PlayServ.Connect(projectKey);
var session = await playserv.Auth.SignIn(Provider.Device, create: true);

var seat = await playserv.Matchmaking.Find("battle");
var room = await playserv.Rooms.Join(seat);

room.Entities<Tank>().OnChange(tank => Render(tank));

var aim = new Vector3(24f, 0f, 12f);              // the world point under the crosshair
room.My<Tank>().Motion.Drive(throttle: 1f, steer: -0.4f);
await room.My<Tank>().Cast(Abilities.Shell, aim);

const playserv = await PlayServ.connect(projectKey);
const session = await playserv.auth.signIn(Provider.Device, { create: true });

const seat = await playserv.matchmaking.find('battle');
const room = await playserv.rooms.join(seat);

room.entities<Tank>().onChange((tank) => render(tank));

const aim: Vector3 = { x: 24, y: 0, z: 12 };      // the world point under the crosshair
room.my<Tank>().motion.drive({ throttle: 1, steer: -0.4 });
await room.my<Tank>().cast(Shell, aim);

playserv = await PlayServ.connect(project_key)
session = await playserv.auth.sign_in(Provider.DEVICE, create=True)

seat = await playserv.matchmaking.find("battle")
room = await playserv.rooms.join(seat)

room.entities(Tank).on_change(lambda tank: render(tank))

aim = Vector3(24, 0, 12)                          # the world point under the crosshair
room.my(Tank).motion.drive(throttle=1.0, steer=-0.4)
await room.my(Tank).cast(Shell, aim)

FPlayServClient::Connect(ProjectKey,
    TPSOnResult<FPlayServClient*>::CreateWeakLambda(this, [this](const TPSResult<FPlayServClient*>& ConnectResult)
    {
        if (!ConnectResult.HasValue()) { return; }
        FPlayServClient* Client = ConnectResult.Value();
        Client->Auth->SignInAnonymous(FPSIdempotencyKey(DeviceId),
            TPSOnResult<FPSSession>::CreateWeakLambda(this, [this, Client](const TPSResult<FPSSession>& SignedIn)
            {
                if (!SignedIn.HasValue()) { return; }
                FindBattle(Client);
            }));
    }));

// in FindBattle(FPlayServClient* Client): a ticket, the seat it wins, the room it opens
Client->Matchmaking->Of<FBattleQueue>()->Tickets->Create(FPSTicketClaim{ .Mode = TEXT("battle") },
    TPSOnResult<FPSTicket*>::CreateWeakLambda(this, [this, Client](const TPSResult<FPSTicket*>& TicketResult)
    {
        if (!TicketResult.HasValue()) { return; }
        TPSSubscription Placement = TicketResult.Value()->Subscribe([this, Client](const FPSSeat& Seat)
        {
            Client->Rooms->Join(Seat,
                TPSOnResult<FPSRoom*>::CreateWeakLambda(this, [this](const TPSResult<FPSRoom*>& JoinResult)
                {
                    if (!JoinResult.HasValue()) { return; }
                    EnterBattle(JoinResult.Value());
                }));
        });
    }));

// in EnterBattle(FPSRoom* Room): render what you see, drive what is yours
TPSSubscription TankView = Room->Entities->Of<UTank>()->Select()
    .Subscribe([this](const TArray<UTank*>& Tanks) { Render(Tanks); });

const FVector3f Aim(24.f, 0.f, 12.f);            // the world point under the crosshair
Room->Entities->Of<UTank>()->Select().GetMine().Then(
    TPSOnResult<UTank*>::CreateWeakLambda(this, [this, Aim](const TPSResult<UTank*>& MineResult)
    {
        if (!MineResult.HasValue()) { return; }
        UTank* MyTank = MineResult.Value();
        MyTank->Motion->SubmitInput(FPSMoveInput{ .Throttle = 1.f, .Steer = -0.4f }, InputSequence);
        MyTank->Call->Cast(PSKeys::Ability::Shell, Aim);
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

var playserv = await PlayServ.Connect(projectKey);
var session = await playserv.Auth.SignIn(Provider.Device, create: true);

var seat = await playserv.Matchmaking.Find("battle");
var room = await playserv.Rooms.Join(seat);

room.Entities<Tank>().OnChange(tank => Render(tank));

var aim = new Vector3(24f, 0f, 12f);              // the world point under the crosshair
room.My<Tank>().Motion.Drive(throttle: 1f, steer: -0.4f);
await room.My<Tank>().Cast(Abilities.Shell, aim);

Four calls, and each answers something different:

Refusals arrive as the platform's typed Problem — a code plus a reason for a human. C#, TypeScript, Python and Unreal raise it; Go returns it as the error value, which is why every call in that tab is checked. An Unreal dedicated server or a master-client runs the same binary under a host key instead, and its roles carry the mc rows: Rooms → Hosting a room is that surface end to end, Access is where the keys and roles behind it are declared.

5. Push and play

playserv push          # schema + declarations + hooks, one deploy
playserv open battle   # a dev-env room, live in the panel

playserv push scans the project it runs in — attribute hooks and declarations — and deploys to the environment you target (--env dev by default). playserv schema push alone moves just the model, and playserv schema diff is what a push is diffed against (Schema).

A push lands whole or not at all, and it is refused rather than merged if the deployed schema moved since your diff. A change that would break existing data does not ride the push at all: it becomes a migration you read first and then run or cancel (Schema). Moving a model from dev to prod is an operator-plane act rather than an SDK call (the operator plane).

playserv open battle creates one room from the pushed battle template and opens it in the panel, where the room's state and its members are inspectable while you play against it. The panel now shows the template, the map, the drop-table and the hooks: the same model you authored in code, editable there too.

The numbers you did not choose

Capacity = 8, Hz30, Hz = 10 and Cooldown = 1.5f are this game's tuning, not ceilings. The platform's own limits sit above them, and each is declared with what the caller observes at the boundary:

The numbers themselves are per environment and land with the platform's limits; the behaviour at the boundary does not wait for them (Rooms, Access, Auth).

Where to go next

1. Examples, the section straight after this one: a leaderboard in Tanks, health crates in Tanks, or the daily-tournament recipe for the meta loop — one real feature each, every step linking to the module page that owns what you just used.
2. How the SDK works, when the shape of it starts to matter more than the next feature: Core Concepts is the dictionary, and four articles answer who is calling (Authority), how a grant is spelled (Access & Roles), what the SDK is made of (How the SDK Is Built) and how it is executed (Threads, Lifetime and Testing).
3. Then the modules. Every module page has the same anatomy — thesis, actors, when to use it, user flow, examples, model — so the second reads faster than the first and the fifth takes minutes. Entity and Data are the two everything else leans on.

Reading paths by role

Whatever your role, read Authority first — one SDK and a grant per actor is the shared prerequisite — with Core Concepts open beside it.

Not translated yet — showing English.

A leaderboard in Tanks

Tanks, the sample arena from Getting Started, has no leaderboard. This lesson, which you can take any time after Getting Started, adds a weekly kill board in three steps: declare the board, submit from the kill hook, read it in the client. Each step links to the module page that owns what you just used, so the lesson teaches by pointing rather than by repeating.

Step 1 — declare the board

A board is a declaration: which field ranks it, how repeat submits combine, when it resets, and who may submit. Aggregation.Increment adds each submit to the running total, so one kill is one point. Submit.ServerOnly is the default and it closes the board to clients, which is what makes step 2 the only way in.

[Leaderboard("tanks-weekly-kills")]
public static class WeeklyKills
{
    public static Owner Owner = Owner.Player;
    public static Aggregation Agg = Aggregation.Increment;
    public static Reset Reset = Reset.Weekly(DayOfWeek.Monday);
    public static Submit Submit = Submit.ServerOnly;

    [Rank(1, Sort.Descending)] public static int Kills;
}

@Leaderboard('tanks-weekly-kills')
export class WeeklyKills {
  static owner = Owner.Player;
  static agg = Aggregation.Increment;
  static reset = Reset.weekly(DayOfWeek.Monday);
  static submit = Submit.ServerOnly;

  @rank(1, Sort.Descending) static kills: number;
}

@leaderboard("tanks-weekly-kills")
class WeeklyKills:
    owner = Owner.PLAYER
    agg = Aggregation.INCREMENT
    reset = Reset.weekly(DayOfWeek.MONDAY)
    submit = Submit.SERVER_ONLY

    kills: int = rank(1, Sort.DESCENDING)

USTRUCT(PSLeaderboard = (Name = "tanks-weekly-kills", Owner = "Player", Aggregation = "Increment",
                        Reset = "Weekly:Monday", Submit = "ServerOnly"))
struct FWeeklyKills
{
    GENERATED_BODY()

    UPROPERTY(PSRank = (Order = 1, Sort = "Descending")) int32 Kills;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

[Leaderboard("tanks-weekly-kills")]
public static class WeeklyKills
{
    public static Owner Owner = Owner.Player;
    public static Aggregation Agg = Aggregation.Increment;
    public static Reset Reset = Reset.Weekly(DayOfWeek.Monday);
    public static Submit Submit = Submit.ServerOnly;

    [Rank(1, Sort.Descending)] public static int Kills;
}

Push it with playserv push and the board appears in the panel, empty, with its Monday cycle already scheduled — Monday 00:00 UTC, since schedules are UTC. The axes you did not set keep their defaults. See Leaderboards for the full axis list — owner, order key, display fields, tournament rules.

Step 2 — submit from the kill hook

Tanks already ends a life through the HP threshold declared on the tank: at zero HP the death transition fires and the platform calls the hook after it. The hook is a cloud function, typed in and typed out, so submitting a kill is one line inside it.

[After(Stats.Depleted, stat: "hp")]
public static Task SubmitKill(StatEvent e) =>
    PlayServ.Leaderboards.Submit("tanks-weekly-kills", e.By.PlayerId,
        kills: 1, idempotencyKey: e.Id);

export const submitKill = after(Stats.depleted, { stat: 'hp' }, (e: StatEvent) =>
  PlayServ.leaderboards.submit('tanks-weekly-kills', e.by.playerId,
    { kills: 1, idempotencyKey: e.id }));

@after(stats.depleted, stat="hp")
async def submit_kill(e: StatEvent):
    await playserv.leaderboards.submit("tanks-weekly-kills", e.by.player_id,
        kills=1, idempotency_key=e.id)

e.By is the attacker the damage carried, so no bookkeeping tracks who shot whom. e.Id is the event's own id, and passing it as the idempotency key is what an Increment board needs: a re-delivered kill event counts once, not twice. The hook point, the ordering guarantees and the veto contract are Extensibility; the threshold that fires it is a stat preset on the tank, and the score row it writes is ordinary data you can query.

Step 3 — read the board in the client

Two reads cover the whole UI: the top of the board and the window around the local player — five rows above, five below, plus your own. Both come back as ranked entries with kills and display name, ready to bind to a list. A subscription keeps the panel current while the match runs, and it delivers the local player's rank only.

var top    = await playserv.Leaderboards.Top("tanks-weekly-kills", 20);
var around = await playserv.Leaderboards.AroundMe("tanks-weekly-kills", 5);

playserv.Leaderboards.OnRankChanged("tanks-weekly-kills", r => UpdateHud(r));

const top    = await playserv.leaderboards.top('tanks-weekly-kills', 20);
const around = await playserv.leaderboards.aroundMe('tanks-weekly-kills', 5);

playserv.leaderboards.onRankChanged('tanks-weekly-kills', (r) => updateHud(r));

top    = await playserv.leaderboards.top("tanks-weekly-kills", 20)
around = await playserv.leaderboards.around_me("tanks-weekly-kills", 5)

playserv.leaderboards.on_rank_changed("tanks-weekly-kills", lambda r: update_hud(r))

Client->Leaderboards->Of<FWeeklyKills>()->Get(
    TPSOnResult<FPSBoard*>::CreateWeakLambda(this, [this](const TPSResult<FPSBoard*>& Result)
    {
        if (!Result.HasValue()) { return; }
        OnBoard(Result.Value());
    }));

// in OnBoard(FPSBoard* Board):
Board->Entries->Select().Page(20).Then(
    TPSOnResult<TPSPage<FPSLeaderboardEntry>>::CreateWeakLambda(this, [this](const TPSResult<TPSPage<FPSLeaderboardEntry>>& Top)
    {
        if (!Top.HasValue()) { return; }
        Hud->ShowTop(Top.Value().Rows);
    }));

Board->Entries->SelectAround(MyPlayerId, /*Radius*/ 5,
    TPSOnResult<TArray<FPSLeaderboardEntry>>::CreateWeakLambda(this, [this](const TPSResult<TArray<FPSLeaderboardEntry>>& Around)
    {
        if (!Around.HasValue()) { return; }
        Hud->ShowWindow(Around.Value());
    }));

TPSSubscription MyRank = Board->Subscribe->Mine(
    [this](const FPSLeaderboardEntry& Mine) { UpdateHud(Mine); });
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

var top    = await playserv.Leaderboards.Top("tanks-weekly-kills", 20);
var around = await playserv.Leaderboards.AroundMe("tanks-weekly-kills", 5);

playserv.Leaderboards.OnRankChanged("tanks-weekly-kills", r => UpdateHud(r));

Monday's reset closes the cycle instead of deleting it, so last week's table stays readable by its label — the same Top call with a cycle: argument. A reward hook on the cycle close is the natural fourth step, described on Leaderboards.

Where to go next

• Leaderboards — the axes, cycles, tournaments, and the pre-submit hook that caps suspicious scores.
• Extensibility — every hook point, in order, with the veto contract.
• Entity presets — the stat threshold that fired the kill in step 2.
• Health crates in Tanks — the other Tanks example: two declarations and one hook.
• Getting Started — the Tanks arena this lesson extends.
• Core Concepts — the vocabulary every module page assumes.

Not translated yet — showing English.

Health crates in Tanks

This is the second Tanks lesson. It takes three steps and no new module: a declaration for the crate, a declaration for where crates appear, and one hook for what picking one up does. Take it after Getting Started, in either order with the leaderboard lesson.

Step 1 — declare the crate

A crate is an entity with two presets applied and a body that reports contact without stopping anyone. Response.Pass on the pickups layer is what makes it a pickup rather than an obstacle: the contact is reported, the motion passes straight through.

[Entity("health-crate", Persistence = Persistence.Runtime, Presets = new[] { Preset.WorldObjects })]
public class HealthCrate
{
    [Sync] public Vector3 Position;

    [Body(Shape.Sphere, Radius = 0.5f, Layer = "pickups")]
    [CollidesWith("vehicles", Response.Pass)]      // reported, motion passes through
    public Body Body;
}

@Entity('health-crate', { persistence: Persistence.Runtime, presets: [Preset.WorldObjects] })
export class HealthCrate {
  @Sync position: Vector3;

  @Body({ shape: 'sphere', radius: 0.5, layer: 'pickups' })
  @CollidesWith('vehicles', Response.Pass)         // reported, motion passes through
  body: Body;
}

@entity("health-crate", persistence=Persistence.RUNTIME, presets=[Preset.WORLD_OBJECTS])
class HealthCrate:
    position: Vector3 = sync()

    body: Body = body(shape="sphere", radius=0.5, layer="pickups",
                      collides_with=[("vehicles", Response.PASS)])

UCLASS(PSEntity = (Name = "health-crate", Persistence = "Runtime", Presets = "world-objects"))
class UHealthCrate : public UObject
{
    GENERATED_BODY()

    UPROPERTY(PSSync) FVector3f Position;

    UPROPERTY(PSBody = (Shape = "Sphere", Radius = "0.5", Layer = "pickups"),
              PSCollidesWith = "vehicles:Pass")                             // reported, motion passes through
    FPSBody Body;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

Two things you did not have to write: where the crate is drawn (the client already renders declared world objects) and how its position reaches the clients — [Sync] is the network call.

Owned by Entity Presets and Collision.

Step 2 — declare where crates appear

Placement is a declaration too, and this is the step that decides whether the feature feels fair. Spacing keeps crates from clumping, distance from players keeps them from spawning into a duel, and the no-repeat rule keeps the same spot from being the answer every time.

[DropTable("health-crates", Layer = "ground", MinSpacing = 8, AwayFromPlayers = 10, NoRepeat = 3)]
public static partial class HealthCrates
{
    public static readonly Drop Crate = Drop.Of<HealthCrate>(weight: 1);
}

@DropTable('health-crates', { layer: 'ground', minSpacing: 8, awayFromPlayers: 10, noRepeat: 3 })
export class HealthCrates {
  static crate = Drop.of(HealthCrate, { weight: 1 });
}

@drop_table("health-crates", layer="ground", min_spacing=8, away_from_players=10, no_repeat=3)
class HealthCrates:
    crate = drop_of(HealthCrate, weight=1)

USTRUCT(PSDropTable = (Name = "health-crates", Layer = "ground", MinSpacing = 8,
                       AwayFromPlayers = 10, NoRepeat = 3))
struct FHealthCrates
{
    GENERATED_BODY()

    UPROPERTY(PSEntry = (Entity = "health-crate", Weight = 1)) FPSDrop Crate;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

Valid positions come from Map — the table asks for a spot on the ground layer and the map answers with one that is actually reachable, so a crate never lands inside a wall.

Owned by Entity Presets and Map.

Step 3 — heal on pickup

One hook, and it is the only code in the lesson. It runs on the platform as a cloud function, which is why it appears on neither engine tab.

[Before(Drops.Pickup)]
public static Verdict HealOnPickup(PickupIntent p)
{
    if (p.WorldItem.Kind != "health-crate") return Hook.Continue(p);
    if (p.Player.Tank.Hp.IsFull) return Hook.Reject("already at full health");

    p.Player.Tank.Hp.Adjust(+40, by: p.Player);
    return Hook.Continue(p);
}

export const healOnPickup = before(Drops.pickup, (p: PickupIntent) => {
  if (p.worldItem.kind !== 'health-crate') return Hook.continue(p);
  if (p.player.tank.hp.isFull) return Hook.reject('already at full health');

  p.player.tank.hp.adjust(+40, { by: p.player });
  return Hook.continue(p);
});

@before(drops.pickup)
def heal_on_pickup(p: PickupIntent) -> Verdict:
    if p.world_item.kind != "health-crate":
        return Hook.continue_(p)
    if p.player.tank.hp.is_full:
        return Hook.reject("already at full health")

    p.player.tank.hp.adjust(+40, by=p.player)
    return Hook.continue_(p)

Three things this hook gets for free, and each is why the lesson is this short:

• The refusal is typed. A tank at full health gets already at full health with a reason a client can show, and the crate is still there for someone who needs it.
• Adjusting a stat is server-authoritative. It is not something a client can ask for, so there is no anti-cheat exception to write for pickups.
• The HUD updates without being told to. Adjust emits changed; the client is already subscribed to the tank's declared stats. You did not write a network message.

Owned by Extensibility and Entity Presets.

What changed, and what didn't

Where to go next

• Entity Presets — the drop generator, world objects and the stat model this lesson leaned on, all three of them presets of entity rather than modules.
• Collision — layers, responses, and the difference between a reported contact and a blocking one.
• Map — how a valid position is chosen, and what "reachable" means.
• Extensibility — every hook point in order, with the veto contract.
• A leaderboard in Tanks — the other Tanks example.

Not translated yet — showing English.

A daily tournament

What you get: a daily tournament with an entry window, seeded rooms and a prize payout — built entirely from declarations and hooks on modules you already have pages for. Nothing here is a new concept; it is leaderboards, matchmaking, rooms, commerce and messaging composed for one meta loop.

Step 1 — declare the board with an entry window and attempt limits

A tournament is an ordinary leaderboard declaration plus participation constraints: an entry window, a cap on entrants and attempts per cycle. Nothing about scoring changes — the order key, the aggregation and the reset stay exactly as on any board.

[Leaderboard("daily-tournament")]
public static class DailyTournament
{
    public static Owner Owner = Owner.Player;
    public static Aggregation Agg = Aggregation.Best;
    public static Reset Reset = Reset.Daily();                 // 00:00 UTC
    public static Submit Submit = Submit.ServerOnly;
    public static Tournament Rules = Tournament.Define(
        entryWindow: TimeSpan.FromHours(2), maxEntrants: 64,
        attemptsPerCycle: 3, joinRequired: true);

    [Rank(1, Sort.Descending)] public static int Score;
}

@Leaderboard('daily-tournament')
export class DailyTournament {
  static owner = Owner.Player;
  static agg = Aggregation.Best;
  static reset = Reset.daily();                    // 00:00 UTC
  static submit = Submit.ServerOnly;
  static rules = Tournament.define({ entryWindow: hours(2), maxEntrants: 64,
                                     attemptsPerCycle: 3, joinRequired: true });

  @rank(1, Sort.Descending) static score: number;
}

@leaderboard("daily-tournament")
class DailyTournament:
    owner = Owner.PLAYER
    agg = Aggregation.BEST
    reset = Reset.daily()                          # 00:00 UTC
    submit = Submit.SERVER_ONLY
    rules = Tournament.define(entry_window=hours(2), max_entrants=64,
                              attempts_per_cycle=3, join_required=True)

    score: int = rank(1, Sort.DESCENDING)

USTRUCT(PSLeaderboard = (Name = "daily-tournament", Owner = "Player", Aggregation = "Best",
                        Reset = "Daily", Submit = "ServerOnly"),
        PSTournament = (EntryWindow = "2h", MaxEntrants = 64,
                        AttemptsPerCycle = 3, JoinRequired = "true"))
struct FDailyTournament
{
    GENERATED_BODY()

    UPROPERTY(PSRank = (Order = 1, Sort = "Descending")) int32 Score;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

[Leaderboard("daily-tournament")]
public static class DailyTournament
{
    public static Owner Owner = Owner.Player;
    public static Aggregation Agg = Aggregation.Best;
    public static Reset Reset = Reset.Daily();                 // 00:00 UTC
    public static Submit Submit = Submit.ServerOnly;
    public static Tournament Rules = Tournament.Define(
        entryWindow: TimeSpan.FromHours(2), maxEntrants: 64,
        attemptsPerCycle: 3, joinRequired: true);

    [Rank(1, Sort.Descending)] public static int Score;
}

Push it and the panel shows an empty bracket with its window scheduled. joinRequired: true makes the entrants a membership rather than everyone who plays, so a submit from a non-entrant is refused. See Leaderboards for the rest of the axis list and for what each constraint does at its boundary.

Step 2 — the window opens: a party joins, rooms get seeded

Once the entry window opens, players queue exactly as for any match: create or join a party, then one Find call. The matchmaker places the party into a tournament bracket and Rooms seeds the match — the same placement-and-seat path every match uses, just scoped to the tournament's queue.

var party = await playserv.Matchmaking.Party.Create();
await party.Invite(friendId);
var seat = await playserv.Matchmaking.Find("daily-tournament");
var room = await playserv.Rooms.Join(seat);

const party = await playserv.matchmaking.party.create();
await party.invite(friendId);
const seat = await playserv.matchmaking.find('daily-tournament');
const room = await playserv.rooms.join(seat);

party = await playserv.matchmaking.party.create()
await party.invite(friend_id)
seat = await playserv.matchmaking.find("daily-tournament")
room = await playserv.rooms.join(seat)

// a party first; the ticket then carries the party
Client->Matchmaking->Parties->Create(FPSIdempotencyKey(PartyId),
    TPSOnResult<FPSParty*>::CreateWeakLambda(this, [this](const TPSResult<FPSParty*>& PartyResult)
    {
        if (!PartyResult.HasValue()) { return; }
        FPSParty* Party = PartyResult.Value();
        Party->Invitations->Create(FriendId);

        Client->Matchmaking->Of<FDailyTournament>()->Tickets->Create(FPSTicketClaim{ .Party = Party },
            TPSOnResult<FPSTicket*>::CreateWeakLambda(this, [this](const TPSResult<FPSTicket*>& TicketResult)
            {
                if (!TicketResult.HasValue()) { return; }
                TPSSubscription Placement = TicketResult.Value()->Subscribe([this](const FPSSeat& Seat)
                {
                    Client->Rooms->Join(Seat,
                        TPSOnResult<FPSRoom*>::CreateWeakLambda(this, [this](const TPSResult<FPSRoom*>& JoinResult)
                        {
                            if (!JoinResult.HasValue()) { return; }
                            EnterTournament(JoinResult.Value());
                        }));
                });
            }));
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

var party = await playserv.Matchmaking.Party.Create();
await party.Invite(friendId);
var seat = await playserv.Matchmaking.Find("daily-tournament");
var room = await playserv.Rooms.Join(seat);

The caps from step 1 belong to the board, not to the matchmaker: the queue places parties, and it is the board that meets an entrant over its cap or a player past their attempts. Entrant 65 of 64 is refused as a conflict with nothing evicted, and a fourth submit in one cycle answers "attempts exhausted" — also a conflict, cleared by the daily reset rather than by asking for a permission.

Step 3 — scores submit via the on-dispose hook

Rooms don't self-report a winner into a leaderboard; that link is a hook, same Extensibility contract as everywhere else — typed in, typed out, no context bag. The room's on dispose hook (Rooms) is the last thing that runs with the match's final state in hand, and it submits from there.

[After(Rooms.Disposed, room: "daily-tournament")]
public static Task SubmitScore(RoomDisposed e) =>
    PlayServ.Leaderboards.Submit("daily-tournament", e.State.Winner, score: e.State.FinalScore);

export const submitScore = after(Rooms.disposed, { room: 'daily-tournament' }, (e: RoomDisposed) =>
  PlayServ.leaderboards.submit('daily-tournament', e.state.winner, { score: e.state.finalScore }));

@after(rooms.disposed, room="daily-tournament")
async def submit_score(e: RoomDisposed):
    await playserv.leaderboards.submit("daily-tournament", e.state.winner, score=e.state.final_score)

Winner and FinalScore are fields this game's own room template declares in its state — the platform adds nothing to the snapshot (Rooms is where template state is declared). The dispose hook (Rooms.Disposed) hands the final snapshot over, so the match is never recomputed. The pre-submit hook from Leaderboards still runs first — a bracket score is subject to the same correct-cap-or-reject contract as any other submit.

Step 4 — the cycle closes: rewards granted, player notified

The daily reset from step 1 closes the cycle exactly as any leaderboard reset does, and fires CycleClosed carrying the closed cycle's label — that label is what makes the hook read the table that just closed rather than the empty one that just opened.

One hook does the rest: it grants the prize through Commerce's entitlement path and pushes the result through Messaging, so there is no separate payout job to run. A notification is addressed to one actor, so the top 8 is a loop of eight, each carrying its own rank argument into the template.

[After(Leaderboards.CycleClosed, board: "daily-tournament")]
public static async Task RewardAndNotify(CycleClosed closed)
{
    var final = await PlayServ.Leaderboards.Top("daily-tournament", 8, cycle: closed.Cycle);
    foreach (var row in final)
    {
        await PlayServ.Commerce.Grant(row.PlayerId, entitlement: "trophy.daily", origin: Grant.Reward);
        await PlayServ.Messaging.Notify(row.PlayerId, Template.Named("daily-tournament-won"),
                                        args: new { rank = row.Rank });
    }
}

export const rewardAndNotify = after(Leaderboards.cycleClosed, { board: 'daily-tournament' },
  async (closed: CycleClosed) => {
    const final = await PlayServ.leaderboards.top('daily-tournament', 8, { cycle: closed.cycle });
    for (const row of final) {
      await PlayServ.commerce.grant(row.playerId, { entitlement: 'trophy.daily', origin: Grant.Reward });
      await PlayServ.messaging.notify(row.playerId, Template.named('daily-tournament-won'),
        { args: { rank: row.rank } });
    }
  });

@after(leaderboards.cycle_closed, board="daily-tournament")
async def reward_and_notify(closed: CycleClosed):
    final = await playserv.leaderboards.top("daily-tournament", 8, cycle=closed.cycle)
    for row in final:
        await playserv.commerce.grant(row.player_id, entitlement="trophy.daily", origin=Grant.REWARD)
        await playserv.messaging.notify(row.player_id, Template.named("daily-tournament-won"),
                                        args={"rank": row.rank})

The numbers in step 1 are seed values: LiveOps retunes the window, the entrant cap and the attempt count in the panel, and the next deploy does not silently overwrite the change. Making this a weekly tournament is one edit — Reset.Daily() becomes Reset.Weekly(DayOfWeek.Monday), and steps 2 to 4 stay as they are.

Where to go next

• Leaderboards — the tournament axes (entry window, max entrants, attempts).
• Matchmaking → Rooms — parties, placement and seeding.
• Extensibility → Commerce → Messaging — the hook chain that pays out.
• Core Concepts — the vocabulary every module page assumes.

Not translated yet — showing English.

Core Concepts

The words the rest of these pages use without stopping to explain them. A module page assumes you already know what an actor is, or an aspect, or a room — here each one gets a one-line definition and a link to the page where the mechanism behind it actually lives. Read it once before the module reference, or come back when a word turns out to be carrying more weight than you expected.

Three things are too large for an entry and have a page each: Authority — who is calling, and what that alone decides; How the SDK Is Built — what the SDK is made of; Inheritance & Composition — how modules build on each other. In that order they read as one argument.

The four surfaces

Every module exposes exactly four things, and every module page is organised around them. This is the programming model:

Actor

Who is making a call. What a call may do is decided by the actor behind it, never by which build the code was compiled into — the argument is Authority, the mechanism (atomic permissions, composed roles, InterfaceGrant) is Access & Roles.

These docs draw actor names from one catalogue — the presets the platform ships. It is a set of presets, not a closed list (a project names its own actors), but every scheme's actors line, Who-does-what row and flow-diagram chip in these pages uses these exact spellings:

player · backend-service · operator · host · moderator · schema-author · architect · bot-brain · room-owner · room-visitor · entry-validator · spectator · match-organizer · warehouse-keeper · seller — and any when a page means all of them.

A page may additionally introduce a scene role for one diagram — a descriptive participant like member or attacker — as long as its own prose or Who-does-what table introduces it first.

Runtime surface

Where code runs. These four tags are used in every operations table:

This is the axis that is constantly confused with the one above it. Where code runs and which actor interface it holds are two separate questions: the same code holds the same rights wherever it is placed, and only the grant differs.

Project & Environment

A project is one game's backend, with a schema and its data in isolated environments (dev, prod). Every call runs inside a project + environment.

Entity

The central noun. An entity is a schema declaration plus its live aspects: data 0..*, states 0..*, RPC 0..*, events 0..*, hooks, and change history. A tank, a door, a stat bar and a quest are all entities, differing only in which aspects they carry. Common combinations ship as presets (GameObject, Stat, Character, Interactable, Projectile). See Entity.

Expected state

A transition request may name the state it expects, and then it is that state or a refusal. A request that names none is evaluated against the state the machine holds when the platform processes it — never against the state at the moment it was sent.

The reply describes that moment and promises nothing about later: someone else's transition landing while the reply is in flight leaves the reply true and does not cancel it. So name the expected state when the outcome depends on what was there before, and otherwise do not read the reply as a snapshot that outlives the call.

Room

A room is a game session, not a place your code runs. The platform doesn't care what hosts it: a dedicated server, a master-client, or the backend itself. Room internals are ours; you drive a room from outside, from cloud functions and clients, through declarations, hooks, events and operations. See Rooms.

Channel & Stream

The async primitives under everything. A channel is an addressable pub/sub topic: a room, a group, an entity, or your own. A stream is a chunked flow in either direction: files are consumed as chunks arrive, queries can stream, and an RPC can fan out to a group and collect the answers. See Core.

Primitive

One of the four bricks every module is assembled from: events (declare, emit, subscribe), RPC (invoke across the wire), data and subscriptions (sync mechanics) and groups (one list, many listeners). A room, a chat and a matchmaking pool are the same group primitive under different rules. If a feature cannot be expressed through the four, that is a design defect and not an argument for a fifth.

Hook contract

One contract everywhere: a before hook runs ahead of validation, receives the typed payload, may mutate it or reject; an after hook runs once the operation has committed, receives request and result, and can only add side effects — it can never fail the operation. Hooks are ordered; every registered platform step can carry them. See Extensibility.

Delta & Revision

Clients receive state as deltas: only changed fields, encoded against the last state the receiver acknowledged. Every record carries a revision; conditional writes reject on mismatch. One versioning concept serves sync, concurrency and history. See Data. (What Unreal calls replication — which client sees which state, how often — lives here and in Visibility and Prediction. The What Survives Losing a Host page is the other one: which machine owns an entity, and which owns it next.)

Tick

Rooms simulate on a fixed step. Every state change is stamped with its tick; sync, prediction, lag compensation and history all count in ticks rather than wall-clock. Data carries its true event time — that is what makes rewind and reconciliation exact. See Prediction.

Not translated yet — showing English.

Authority

Authority is an abstraction, not two builds of the SDK. There is no client SDK and no server SDK. There is one SDK, and what a given call is allowed to do is decided by the actor making it.

A master-client is neither a client nor a server

A player's machine that creates a room and then runs it — a master-client — holds the room-owner interfaces and nothing more. It is not a server: it cannot do everything a server can. It is not an ordinary client either.

A dedicated server is the same shape from the other side: the same client without the rendering, needing no separate SDK. What separates the two is trust, not construction, and trust is carried by the grant.

Interfaces follow the actor, not the side

A module does not expose "the client API" and "the server API". It exposes what a room-owner can do, what an entry-validator can do, what a seller can do. Client and server are plumbing; actors are the domain. Inside each module page the surface is grouped the same way — this is for these needs, that is for those.

A role is the right and the classification, both

There is exactly one dimension here. A role carries what an actor may do, and it is also how you say who something is addressed to. There is no second axis of tags or labels beside it: one thing to declare, one thing to check, one thing to read in the admin panel.

whoami is how code asks. It reports the actor and the interfaces that actor unlocks right now — not a static list baked into the binary at build time.

Where code runs and which actor it holds are separate questions

Laid out as a grid, the two axes are independent and every cell is reachable:

The emphasised cell is code running on a client and doing a server's work. It is named — room-owner — and it is a grant like any other.

Any combination is legal. A cloud function is not automatically privileged, and a client is not automatically limited: rights come from the grant, and the grant is declared. The code's rights are the same wherever it runs — only what it was granted differs.

Revocation takes effect without reissuing the credential

A credential names an identity. It does not carry a role list. Roles resolve server-side, per request, which means the client never holds the proof of its own permissions and there is nothing stale to keep presenting after a revocation.

Two consequences, both stated where they belong:

• Revoking a role takes effect without reissuing the credential — see Granting a role.
• It becomes observable no later than the declared staleness bound on the rights cache. We do not promise instant.

Where authority is declared, not inferred

• A room type declares its authority mode, and there is no default: either our simulation runs the tick, or an external authority does — the studio's game server, or a player's client as the master-client. That is Who runs the tick.
• How far an external authority is trusted about the outcome is a separate declaration on the room type — accept it, check it with a hook, or do not accept it. Again no default.
• Which credential resolves to which role, and what a host key is, is Access & Roles.

Not translated yet — showing English.

Access & Roles

Roles are composed, never hardcoded. Atomic permissions compose into roles; roles gate data down to row and column, and decide which module interfaces a build even sees. It replaces the client/server key split: a credential names an identity, its roles resolve per request.

When to use it

• You need a credential narrower than "client" or "server" — composed roles resolve behind it per request.
• Data access must stop at rows and columns: region scoping, PII masks, read-only contractors.
• A build should only see the interfaces its role unlocks — kick/close simply isn't there for a visitor.
• Your UI must grey out buttons honestly — CanI evaluates the same policy the server will enforce.
• Skip it when the shipped presets (player, room-owner, seller, …) already match your actors — every module respects them by default; the full catalogue lives on Core Concepts.

Who does what

At a glance

[Role("entry-validator")]
public class EntryValidator
{
    [Allow(Rooms.Membership.Administer)] public Permit GateEntries;
    [Allow(Data.Records.Read, table: "player_profile", rows: "banned == false",
           columns: "id, display_name")] public Permit SeeProfiles;
}

await PlayServ.Access.Grant(staffId, Roles.EntryValidator, Roles.MatchOrganizer);
var key = await PlayServ.Access.IssueKey(staffId);   // the credential names no roles

// any actor, before attempting an operation:
if (await PlayServ.Access.CanI(Commerce.Orders.Administer)) Hud.ShowRefund();

@Role('entry-validator')
export class EntryValidator {
  @Allow(Rooms.membership.administer) gateEntries: Permit;
  @Allow(Data.records.read, { table: 'player_profile', rows: 'banned == false',
                              columns: ['id', 'display_name'] }) seeProfiles: Permit;
}

await playserv.access.grant(staffId, Roles.entryValidator, Roles.matchOrganizer);
const key = await playserv.access.issueKey(staffId);  // the credential names no roles

// any actor, before attempting an operation:
if (await playserv.access.canI(Commerce.orders.administer)) hud.showRefund();

@role("entry-validator")
class EntryValidator:
    gate_entries = allow(rooms.membership.administer)
    see_profiles = allow(data.records.read, table="player_profile",
                         rows="banned == false", columns=["id", "display_name"])

await playserv.access.grant(staff_id, roles.ENTRY_VALIDATOR, roles.MATCH_ORGANIZER)
key = await playserv.access.issue_key(staff_id)   # the credential names no roles

# any actor, before attempting an operation:
if await playserv.access.can_i(commerce.orders.administer):
    hud.show_refund()

// declarations compile into the same pushed model — playserv push from the UE project or CI
USTRUCT(PSRole = "entry-validator")
struct FEntryValidator
{
    GENERATED_BODY()

    UPROPERTY(PSAllow = (Atom = "Rooms.Membership.Administer"))
    FPSPermit GateEntries;

    UPROPERTY(PSAllow = (Atom = "Data.Records.Read", Table = "player_profile",
                         Rows = "banned == false", Columns = "id, display_name"))
    FPSPermit SeeProfiles;
};

// granting is an operator act; a build checks what its identity resolves to
const FPSActor Me = Client->Whoami();   // which interfaces this actor unlocks
Client->Access->CanI(TEXT("Commerce.Orders.Administer"),
    TPSOnResult<bool>::CreateWeakLambda(this, [this](const TPSResult<bool>& Result)
    {
        if (!Result.HasValue()) { return; }
        if (Result.Value()) { Hud->ShowRefund(); }
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// the same `[Role]` / `[Allow]` declaration as the server tab, on the Unity 2021.3 runtime
var me = playserv.Whoami();               // which interfaces this actor unlocks
if (await playserv.Access.CanI(Commerce.Orders.Administer)) hud.ShowRefund();

An atom is a pair — a resource and one of four verbs: read, write, execute, administer. The verb set is fixed, and a case that does not fit splits the resource instead of growing the list. That is why gating somebody else's entry is Rooms.Membership.Administer rather than a ValidateEntry verb of its own: acting on another actor's membership is administration, while joining yourself is Rooms.Membership.Write on the same resource.

The model

The data ACL is role × operation × row predicate × field mask — one model, identical whether it was authored in code, through the API, or in the panel's role grid.

What access is built from.

What a credential resolves to.

The tag legend (fn / cl / mc / adm) is owned by Core Concepts.

What is true of every check.

Who hands out a role. Granting and revoking a role to a player, and the project's declared default role for a new one, are operations on Auth & Players — that module owns identities, and a role is resolved by the identity in the credential. This page owns what a role is; that page owns handing it over.

Errors

• What a predicate hides answers not found, not forbidden — otherwise the refusal itself tells the caller that the thing exists, which is exactly what hiding it was for.
• A right the caller does not hold answers forbidden where the subject's existence is not a secret, and it names what was missing rather than failing blankly.
• A field outside the mask is absent from the answer, not present and empty: an empty value and a masked one would be indistinguishable.
• A role including itself, directly or through a chain, is a configuration error — refused as a declaration rather than resolved at runtime.
• Delegation never widens capability: a call the actor could not make on its own behalf is refused when made on a player's.

Limits

Each ceiling names its behaviour at the edge; the numbers land with the platform limits chapter.

• The size of a selection under a row predicate is bounded, and the ACL model declares that bound rather than discovering it. A read above the ceiling is answered with the ceiling's worth of rows plus the marker saying it was cut, never with a silent short page.
• The staleness bound of a resolved permission is declared, and a revocation does not wait it out — it invalidates at once.

User flow

One tournament-organizer key, from role composition to a live permission change.

Not translated yet — showing English.

How the SDK Is Built

Two questions, and both have short answers. How is the SDK written — why one idea looks slightly different in Python and in Unreal C++. How does the SDK run — what sits between your call and the wire.

Written from the general to the particular

The SDK is one design with two narrowing escapes, and the order is the rule: nothing moves down a level until the level above genuinely cannot carry it.

Read top down, this is why the six tabs on every example are not six different APIs. They are one API, spelled six ways, and the differences you can see are the two lower levels showing through.

How it runs, from your code downwards

Your game code sees modules, and the vocabulary stops there. That is the contract of the top level.

• Modules are what you address. They form a graph, not a tree, and what that buys is Inheritance & Composition.
• The four primitives are what modules are assembled from — events, RPC, data and subscriptions, groups. A room, a chat and a matchmaking pool are the same group primitive under different rules. If a feature cannot be expressed through the four, that is a design defect, not an argument for a fifth.
• The hub is underneath, and you never call it: dependency injection, module mounting, the user session, state recovery, and message quality of service. It is named once on Under the Hood.
• Transport adapters sit at the bottom, one per protocol, and the hub hides them completely. There will be several — WebSocket, our own UDP, HTTP — and which one carries a call is not something your code decides or notices.

What a module tells you about delivery is its quality of service — at-least-once, or at-most-once — and nothing else. How the bytes got there is the part we reserve the right to make faster.

What you get out of this

• One SDK, not a client one and a server one. What a call may do is the actor's grant, not a build flag. That is Authority.
• A declaration is the input to everything. Push it and the typed API appears, the admin panel renders it, and the codegen for each binding follows. See Schema as Code.
• Modules compose rather than inherit. How, and what "inheritance" honestly means here, is Inheritance & Composition.

Not translated yet — showing English.

Threads, Lifetime and Testing

You own the loop. We deliver into exactly one place, and never behind your back. The SDK starts no thread you have to know about, hands you no lock, and calls your code from a single context you chose at startup. Call us from any thread you like; we call you from one.

One delivery context, and you own the loop

An instance declares exactly one delivery context — the single place where all of its handlers run. It is fixed when you initialise and does not change for the life of the instance. An event, a data delta, the outcome of a call: all of them arrive there and nowhere else.

There are two shapes of it, and you pick one at startup:

• You pump it. The runtime does nothing on its own; you drain pending deliveries from your own loop. This is the shape an engine wants — deliveries land on the game thread, in a frame you chose.
• We own it. The runtime holds one dedicated thread of execution. This is the shape a console host or a dedicated server wants.

Neither is a fallback for the other, and there is no third option involving a thread pool: the number of threads the runtime holds is never a question your code has to ask.

The context is never an argument. No handler takes a "which thread am I on" parameter, and there is nothing to query. Where your handler runs is a property of the contract, not data of the call.

Starting and stopping are explicit

Initialisation is a call you make, and it answers with an outcome. Nothing initialises lazily on first use — that is forbidden rather than merely discouraged, because a lazy start moves the one place where a disabled module is visible into whichever arbitrary call happened to be first, where it reads as that call failing.

A disabled module is named at startup, and the outcome says which of two things happened: the whole dependent chain is off, or you are running with less, plus the list of what is unavailable. There is no silent third case.

// the outcome names a disabled module and what it took with it — it is not an exception
options.Delivery = DeliveryContext.Pumped(out IPump pump);   // or DeliveryContext.Owned()
InitializationOutcome outcome = await PlayServRuntime.Initialize(options);
foreach (var gap in outcome.Unavailable) Log(gap);

void OnFrame() => pump.Drain();                          // your loop, your frame

await runtime.DisposeAsync();                            // explicit, idempotent

// the outcome names a disabled module and what it took with it — it is not a thrown error
const outcome = await PlayServ.runtime.initialize({
  delivery: PlayServ.delivery.pumped(),                 // or .owned()
});
outcome.unavailable.forEach(log);

const onFrame = () => outcome.pump.drain();             // your loop, your frame

await runtime.close();                                  // explicit, idempotent

# the outcome names a disabled module and what it took with it — it is not an exception
outcome = await playserv.runtime.initialize(
    delivery=playserv.delivery.pumped(),                # or .owned()
)
for gap in outcome.unavailable:
    log(gap)

def on_frame():
    outcome.pump.drain()                                # your loop, your frame

await runtime.close()                                   # explicit, idempotent

// deliveries land on the game thread; a gap is a named outcome, not an exception
FPlayServClient::Connect(Options,
    TPSOnResult<FPlayServClient*>::CreateLambda([](const TPSResult<FPlayServClient*>& Result)
    {
        if (!Result.HasValue()) { return; }
        FPlayServClient* Client = Result.Value();
        for (const FPSGap& Gap : Client->Unavailable())
        {
            UE_LOG(LogPlayServ, Warning, TEXT("%s"), *Gap.Text);
        }
    }));

// no pump call: the plugin drains on the game thread for you

Client->Shutdown();                          // explicit, idempotent — and not a cancel
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// the outcome names a disabled module and what it took with it — it is not an exception
options.Delivery = DeliveryContext.Pumped(out IPump pump);   // or DeliveryContext.Owned()
InitializationOutcome outcome = await PlayServRuntime.Initialize(options);
foreach (var gap in outcome.Unavailable) Log(gap);

void OnFrame() => pump.Drain();                          // your loop, your frame

await runtime.DisposeAsync();                            // explicit, idempotent

Shutting down does not cancel anything. Shutdown is explicit, complete and idempotent — after it succeeds no handler of that instance is called again — but it says nothing about work already in flight. An operation you started before shutting down stays discoverable by whatever means that operation named. If you need to know whether a purchase went through, shutting down is not how you find out.

Every handle has one declared end — and it is never the garbage collector

A subscription, a deferred-work descriptor, a session: each is a handle, and each has exactly one end that the contract names. Releasing is idempotent, so releasing twice is not an error.

Three consequences that are easy to get wrong:

• The end is never a finaliser, a destructor or a scope. A handle you drop on the floor stays open. That is a bug in your code, not something we quietly reclaim — because a lifetime that depends on the language would be a different lifetime in every binding.
• Using a handle after its end is a declared refusal, with a code. Not an empty result, not undefined behaviour, and not a generic disposed-object error that carries nothing you can act on.
• A dropped connection is not the end of a handle. A subscription survives a disconnect and keeps receiving after reconnection. Handles end for the reasons the contract names, and losing the network is not one of them.

No handle outlives the instance that issued it: once you shut down, every handle it gave you is at its end.

Calling from a handler is fine; waiting inside one is not

Call the surface from any of your threads. Every handle is free-threaded, and that is a promise rather than a property of today's build. You will never take our lock, wait on our barrier, or be told to call something "under a lock" — no synchronisation primitive is part of the surface at all.

Handlers of one instance are serialised: two never run at the same time, and order within one stream is preserved. So a handler needs no locking of its own.

Starting an operation from inside a handler is legal and cannot deadlock. Its outcome, though, never arrives inside that same handler — it comes back as a separate delivery on the same context. Going inwards is allowed; turning round inside is not.

Blocking the delivery context is forbidden, and the ban is not advice. Waiting on the network, waiting on someone else's lock, synchronously waiting on your own call: all forbidden inside a handler. The prohibition has a symptom — a handler that holds the context beyond its declared budget produces either a declared degradation of delivery or a declared refusal. What it never produces is a silent slowdown you get to discover in a player's session.

// legal: start and return. The outcome is a later delivery, not a value here.
sub = await room.Events.Subscribe<CrateOpened>(async e => {
    await player.Inventory.Grant(e.Loot);   // started, not awaited-to-completion inside the context
});                                          // ...the grant's outcome arrives on its own

await sub.DisposeAsync();                    // stop receiving — local, works with the network down

// legal: start and return. The outcome is a later delivery, not a value here.
const sub = await room.events.subscribe(CrateOpened, async (e) => {
  await player.inventory.grant(e.loot);
});

await sub.close();                          // stop receiving — local, works with the network down

# legal: start and return. The outcome is a later delivery, not a value here.
sub = await room.events.subscribe(CrateOpened, lambda e: player.inventory.grant(e.loot))

await sub.close()                           # stop receiving — local, works with the network down

// subscribing is local and immediate; the outcome is a later delivery, on the game thread
TPSSubscription LootWatch = Room->Subscribe->CrateOpened(
    [this](const FCrateOpened& Opened) { GrantLoot(Opened.Loot); });

LootWatch.Unsubscribe();                    // stop receiving — local, works with the network down
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// legal: start and return. The outcome is a later delivery, not a value here.
sub = await room.Events.Subscribe<CrateOpened>(async e => {
    await player.Inventory.Grant(e.Loot);   // started, not awaited-to-completion inside the context
});                                          // ...the grant's outcome arrives on its own

await sub.DisposeAsync();                    // stop receiving — local, works with the network down

"Cancel" is two different things

One word in most languages, two operations here, and the difference is observable:

The second is the one people get wrong. Cancelling accepted work is a request that may not arrive in time — exactly like a timeout, which also does not mean "it did not apply". After either kind of cancellation, the outcome of a started non-idempotent operation remains discoverable by the means that operation named.

And the two failures are distinguishable: cancelling a call that never reached us is a local failure; cancelling work we had accepted gives you a terminal state from a declared set.

What you receive is a copy of the past

A value delivered to your handler does not change afterwards. We never hand out a live reference into our own state, so nothing you are holding mutates between two lines of your code.

Keeping a delivered value beyond the handler is therefore safe — but what you kept is an observation of a moment, not a window onto the present. Deltas may be merged on the way to you, so a list of values you saved is not a history of what happened.

You also never own our buffers. There is no rent-and-return, no assemble-then-send: changing declared state is the network operation.

Testing: an in-memory implementation, not a mock

There is a full in-memory implementation — same surface, same set of declared outcomes, no network. It is a separate thing you depend on, not a flag on the production runtime.

• It is not partial. An operation it does not support is refused with a declared code, never answered with an invented success. A test that passes against it passes for a reason.
• Time is yours. Declared deadlines — a work descriptor's lifetime, a reservation, a retention window — are reached by advancing a step, not by sleeping.
• Determinism is declared and bounded: order within a stream, the declared delivery mode, controllable time. Floating-point determinism is not promised, so a full simulation does not replay here either.

A mock checks that you called what you meant to call; this checks that what you called makes sense.

What you install, and the version floor

The core is one unit; optional modules are separate ones, each with a declared composition and a declared list of mandatory dependencies. Adding a unit never changes another's surface — a module mounts where its declaration says, so nothing appears or disappears elsewhere because of what you installed beside it.

If an optional unit is referenced but cannot load, that is a declared outcome of initialisation — the same place a disabled module is reported. Never a stub that silently does nothing.

Every binding declares the minimum runtime version it is built against. Below it, you get a refusal at initialisation, not partial operation: a runtime that is too old otherwise breaks at the first capability it lacks, which is somewhere arbitrary in your code and usually on a player's machine rather than yours. Raising that minimum is a breaking change and goes through the same process as any other.

Where to go next

• Getting Started — the first room, end to end.
• How the SDK Is Built — why there is one surface and how the pieces fit.
• Under the Hood — the layer beneath this one, if you are curious.

Not translated yet — showing English.

Core

Core is the one object you create, and everything else hangs off it. One key in, and you hold context, identity, typed failures, tracing and batching. Every module call passes through it, and no module ships its own version.

When to use it

• You need to know who and where you are — identity, roles, unlocked modules, project · env · region, all on the one object you hold.
• A cloud function must write as a player — the write is attributed to that player, and the record names both parties, the function and the player.
• Retries must never double-apply — batch operations carry an idempotency key.
• A failure must be branchable and searchable — every throw is a typed Problem with a stable code.
• Skip it when you are after messaging, calls or state — those are the primitives: Events, RPC, Data.

Who does what

At a glance

var me  = PlayServ.Whoami();              // identity, roles, unlocked modules
var env = PlayServ.Context;               // project · env · region

// retries never double-apply: the batch carries an idempotency key
await PlayServ.Batch(key: orderId, b =>
{
    b.Inventory.Grant(playerId, "starter.pack");
    b.Inventory.Grant(playerId, "starter.emote");
});

const me = playserv.whoami();             // identity, roles, unlocked modules
const env = playserv.context;             // project · env · region

// retries never double-apply: the batch carries an idempotency key
await playserv.batch(orderId, (b) => {
  b.inventory.grant(playerId, 'starter.pack');
  b.inventory.grant(playerId, 'starter.emote');
});

me = playserv.whoami()                    # identity, roles, unlocked modules
env = playserv.context                    # project · env · region

# retries never double-apply: the batch carries an idempotency key
async with playserv.batch(key=order_id) as b:
    b.inventory.grant(player_id, "starter.pack")
    b.inventory.grant(player_id, "starter.emote")

const FPSActor Me = Client->Whoami();               // identity, roles, unlocked modules
const FPSPlatformContext Env = Client->Context();   // project · env · region

// retries never double-apply: each keyed operation is safe to repeat
Client->Commerce->Entitlements->Grant(FPSIdempotencyKey(PackGrantId), PlayerId, PSKeys::Item::StarterPack);
Client->Commerce->Entitlements->Grant(FPSIdempotencyKey(EmoteGrantId), PlayerId, PSKeys::Item::StarterEmote);
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

var me  = PlayServ.Whoami();              // identity, roles, unlocked modules
var env = PlayServ.Context;               // project · env · region

// retries never double-apply: the batch carries an idempotency key
await PlayServ.Batch(key: orderId, b =>
{
    b.Inventory.Grant(playerId, "starter.pack");
    b.Inventory.Grant(playerId, "starter.emote");
});

Identity lives inside Core itself. No session or ctx parameter ever appears in a call.

The model

What every error carries.

A consumer branches on the code and the category, never on human text — not by comparison, not by substring, not by parsing. An error from which only the message is reachable is a defect of the binding rather than a shape to work around.

Three origins, and they are not the same thing.

What is true of every refusal.

Core carries the context, not the messages. Emitting and subscribing to facts is the Events primitive; calls — request/response, one-way, group fan-out — are the RPC primitive; state, subscriptions and streaming reads are the Data primitive, addressed through Entity. The audiences all three fan out to are the fourth primitive, Groups. Sized transfers (uploads, downloads) surface in Files & UGC. Mounting semantics — namespacing, collision rejection at mount time — live on Under the Hood.

Errors

try { await PlayServ.Inventory.Grant(playerId, "starter.pack"); }
catch (Problem p) when (p.Code == "rate_limited")
{
    Hud.RetryAt(p.RetryAfter);
}

try { await playserv.inventory.grant(playerId, 'starter.pack'); }
catch (p) {
  if (Problem.code(p) === 'rate_limited') hud.retryAt(p.retryAfter);
  else throw p;
}

try:
    await playserv.inventory.grant(player_id, "starter.pack")
except Problem as p:
    if p.code == "rate_limited":
        hud.retry_at(p.retry_after)
    else:
        raise

// UE builds run without exceptions — the completion carries the result, read explicitly
Client->Commerce->Entitlements->Grant(FPSIdempotencyKey(GrantId), PlayerId, PSKeys::Item::StarterPack,
    TPSOnResult<void>::CreateWeakLambda(this, [this](const TPSResult<void>& Result)
    {
        if (Result.IsRefused() && Result.Refusal().Code == FPSFailureCode::RateLimited)
        {
            Hud->RetryAt(Result.Refusal().RetryNotBefore);   // TOptional<FDateTime> — an instant, not a delay
        }
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

try { await PlayServ.Inventory.Grant(playerId, "starter.pack"); }
catch (Problem p) when (p.Code == "rate_limited")
{
    Hud.RetryAt(p.RetryAfter);
}

What a caller without the role sees. The fn and adm rows are refused, not degraded: a player or client session that calls act as player, emits a trace or reads one gets a Problem with code forbidden — the credential is valid, the roles behind it carry no such right, and repeating the call with the same idempotency key changes nothing. There is no reduced variant that runs with fewer rights and returns less.

Limits

A limit is applied at admission. A call that was accepted has already passed the limit and will be carried out, however long it waits to be processed; a refusal that falls on some later call does nothing to work already admitted. So a queue that filled up is a queue that runs — retrying the accepted call because a neighbour was refused is how you get the work done twice.

You learn a limit by being refused, and there is nothing else to read. The SDK surfaces neither the value in force, nor the headroom left, nor a warning that one is being approached, and nothing about a limit is ever put in front of a player. The refusal carries the whole of it:

• the category, which is what says whether a retry is meaningful at all
• whose limit it was
• when a retry is allowed, and over what window

Branch on those. There is no counter to poll and no budget to display.

User flow

One failing call, from the throw to the trace an operator reads.

Not translated yet — showing English.

Events

An event is the fact that something happened, delivered to everyone who should hear it. Use it for what happens once and cannot be caught up from a current value — a shot, a purchase, a room joined.

When to use it

• Something happened and others must react — a shot fired, a door locked, a match ended.
• The audience varies — the same emit reaches a squad, a room, or one actor, decided by the target the type declares.
• You want typed handlers with autocompletion — a declared event becomes send. and on. on its surface, each with its own contract.
• The fact must still be readable an hour later — declare the type retained and read it back by period.

Who does what

At a glance

[Event("rally_call", Clock = Clock.SimTime, Retention = Retention.Transient)]
public record RallyCall(Vector3 Position);

// emitting: the declaration generated the method — and its contract
squad.Send.RallyCall(position);

// subscribing: typed handler, autocompleted beside every other declared event
squad.On.RallyCall(call => ShowRallyMarker(call.Position));

@Event('rally_call', { clock: Clock.SimTime, retention: Retention.Transient })
export class RallyCall { constructor(public position: Vector3) {} }

// emitting: the declaration generated the method — and its contract
squad.send.rallyCall(position);

// subscribing: typed handler, autocompleted beside every other declared event
squad.on.rallyCall((call) => showRallyMarker(call.position));

@event("rally_call", clock=Clock.SIM_TIME, retention=Retention.TRANSIENT)
class RallyCall:
    position: Vector3

# emitting: the declaration generated the method — and its contract
squad.send.rally_call(position)

# subscribing: typed handler, autocompleted beside every other declared event
squad.on.rally_call(lambda call: show_rally_marker(call.position))

// declarations compile into the same pushed model — playserv push from the UE project or CI
USTRUCT(PSEvent = (Name = "rally_call", Clock = "SimTime", Retention = "Transient"))
struct FRallyCall
{
    GENERATED_BODY()

    UPROPERTY() FVector Position;
};

// emitting and subscribing — generated, typed
Squad->Publish->RallyCall({ Position });
TPSSubscription RallyMarkers = Squad->Subscribe->RallyCall(
    [this](const FRallyCall& Call) { ShowRallyMarker(Call.Position); });
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// the calls are the C# ones; the payload is not — Unity's floor is C# 9 and the generated
// source may carry no records, so a declared payload is a plain serializable type
[Event("rally_call", Clock = Clock.SimTime, Retention = Retention.Transient)]
public sealed class RallyCall
{
    public Vector3 Position;      // converts to and from UnityEngine.Vector3
}

squad.Send.RallyCall(new RallyCall { Position = position });
squad.On.RallyCall(call => ShowRallyMarker(call.Position.ToUnity()));

An event declared inside a module or group surfaces only there: squad.send.rallyCall exists because rally_call is declared for squads, and the emit reaches squad members. An event a module emits outward is part of its declared contract; callers never learn about undeclared ones.

The model

What an event type declares.

What an emission carries.

What a subscription holds.

What is true of every event, whatever the type declares.

Whether a fact is kept after delivery is a slot on its declaration, not a decision taken at the emit — so the same type is always kept the same way and no caller has to remember which call was which.

[Event("objective_taken", Clock = Clock.SimTime, Retention = Retention.Retained, Keep = "7d")]
public record ObjectiveTaken(string Objective, PlayerId By);

// a member who joined late reads what it missed — by type and period, nothing wider
var taken = await squad.Retained.ObjectiveTaken(since: matchStart);

@Event('objective_taken', { clock: Clock.SimTime, retention: Retention.Retained, keep: '7d' })
export class ObjectiveTaken { constructor(public objective: string, public by: PlayerId) {} }

// a member who joined late reads what it missed — by type and period, nothing wider
const taken = await squad.retained.objectiveTaken({ since: matchStart });

@event("objective_taken", clock=Clock.SIM_TIME, retention=Retention.RETAINED, keep="7d")
class ObjectiveTaken:
    objective: str
    by: PlayerId

# a member who joined late reads what it missed — by type and period, nothing wider
taken = await squad.retained.objective_taken(since=match_start)

USTRUCT(PSEvent = (Name = "objective_taken", Clock = "SimTime", Retention = "Retained", Keep = "7d"))
struct FObjectiveTaken
{
    GENERATED_BODY()

    UPROPERTY() FString     Objective;
    UPROPERTY() FPSPlayerId By;
};

// a member who joined late reads what it missed — by type and period, nothing wider
Squad->Retained->ObjectiveTaken->Select(FPSTimeWindow{ .From = MatchStart })
    .Then(TPSOnResult<TArray<FObjectiveTaken>>::CreateWeakLambda(this, [this](const TPSResult<TArray<FObjectiveTaken>>& Result)
    {
        if (!Result.HasValue()) { return; }
        for (const FObjectiveTaken& Taken : Result.Value()) { Timeline->Add(Taken); }
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// same attribute, same read — the payload is a plain serializable type on the C# 9 floor
[Event("objective_taken", Clock = Clock.SimTime, Retention = Retention.Retained, Keep = "7d")]
public sealed class ObjectiveTaken
{
    public string   Objective;
    public PlayerId By;
}

var taken = await squad.Retained.ObjectiveTaken(since: matchStart);

Errors

• Publishing and subscribing are separate rights, and neither implies the other. A subscribe without the right answers forbidden, not not-found — the type is in the module's declared contract, so there is nothing to hide.
• Subscribing to a type the module has not declared is a contract error, surfaced as a typed Problem — never a silent no-op.
• At the emit, three validation refusals: an undeclared type, a payload that fails the schema, and a target the type does not allow.
• A selection past a retained type's term refuses, rather than answering with an empty page.

Limits

Each ceiling names its behaviour at the edge; the numbers behind them land with the platform limits chapter.

• Payload size — over the ceiling the publish fails and the event does not happen, never a truncated payload.
• Publish rate per source — a rate-limit refusal carrying the moment to retry.
• Subscriptions per actor — the new one is refused and the existing ones kept.
• Retention volume per type — eviction by the declared policy, by term, never at random.

User flow

One rally call, from the declaration to the marker each squad member sees on their own screen.

Not translated yet — showing English.

RPC

A typed call whose body lives somewhere else. RPC is the second primitive: declare the procedure where it belongs — on a module, or inside an entity — and every binding gets a generated, awaitable method. The verb is invoke: one-way is a mode the declaration names, not a second verb, and there is no do.

When to use it

• The caller needs an answer — request/response with a typed return.
• The caller reports and moves on — a declared one-way RPC, nothing travels back.
• The work outlasts the call — a declared deferred RPC hands back a work descriptor instead of a timeout.
• One question, many answerers — a group call is N calls, and each answer arrives bound to the member who sent it.
• The verb belongs to a thing — declare it inside the entity; an entity's RPC lives nowhere else (Entity shows the declaration).
• Skip it when nobody is asked to act — a fact others merely react to is an event.

Who does what

At a glance

[Rpc]                                        // answering, immediate, not overridable — the bare defaults
public static ScoreVerdict SubmitScore(ScoreReport report) => Scores.Judge(report);

[Rpc(OneWay = true)]                         // declared one-way: nothing travels back
public static void ReportPing(PingSample sample) => Metrics.Add(sample);

// invoking — generated, typed, awaitable
var verdict = await playserv.Rpc.Invoke.SubmitScore(report);
playserv.Rpc.Invoke.ReportPing(sample);      // one-way by declaration, not by call site

// group fan-out: N calls, one answer bound to each member
await foreach (var answer in squad.Invoke.ReadyCheck())
    Hud.Mark(answer.Member, answer.Ready);

export class MatchRpcs {
  @Rpc()                                     // answering, immediate, not overridable — the bare defaults
  static submitScore(report: ScoreReport): ScoreVerdict { return Scores.judge(report); }

  @Rpc({ oneWay: true })                     // declared one-way: nothing travels back
  static reportPing(sample: PingSample): void { Metrics.add(sample); }
}

// invoking — generated, typed, awaitable
const verdict = await playserv.rpc.invoke.submitScore(report);
playserv.rpc.invoke.reportPing(sample);      // one-way by declaration, not by call site

// group fan-out: N calls, one answer bound to each member
for await (const answer of squad.invoke.readyCheck())
  hud.mark(answer.member, answer.ready);

@rpc()                                       # answering, immediate, not overridable — the bare defaults
def submit_score(report: ScoreReport) -> ScoreVerdict:
    return scores.judge(report)

@rpc(one_way=True)                           # declared one-way: nothing travels back
def report_ping(sample: PingSample):
    metrics.add(sample)

# invoking — generated, typed, awaitable
verdict = await playserv.rpc.invoke.submit_score(report)
playserv.rpc.invoke.report_ping(sample)      # one-way by declaration, not by call site

# group fan-out: N calls, one answer bound to each member
async for answer in squad.invoke.ready_check():
    hud.mark(answer.member, answer.ready)

// invoking — generated, typed (the client surface; bodies live where routing sends them)
Client->Rpc->Call->SubmitScore(Report,
    TPSOnResult<FScoreVerdict>::CreateWeakLambda(this, [this](const TPSResult<FScoreVerdict>& Result)
    {
        if (!Result.HasValue()) { return; }
        Hud->ShowVerdict(Result.Value());
    }));
Client->Rpc->CallOneWay->ReportPing(Sample);   // one-way by declaration, not by call site

// group fan-out: one call, one answer bound to each member
Squad->Call->ReadyCheck(TPSOnResult<FReadyAnswer>::CreateWeakLambda(this,
    [this](const TPSResult<FReadyAnswer>& Answer)
    {
        if (!Answer.HasValue()) { return; }
        Hud->Mark(Answer.Value().Member, Answer.Value().Ready);   // the delegate fires once per member
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// Unity invokes; RPC bodies execute on the platform or a host — engines are not a handler runtime
var verdict = await playserv.Rpc.Invoke.SubmitScore(report);
playserv.Rpc.Invoke.ReportPing(sample);      // one-way by declaration, not by call site

await foreach (var answer in squad.Invoke.ReadyCheck())
    Hud.Mark(answer.Member, answer.Ready);

Where the body executes — cloud function, client, master-client or game server — is routing, declared per method; Extensibility covers overrides and middleware. A failed call throws a typed Problem (Core).

The model

What an RPC declares.

What an invocation carries.

What a deferred call's descriptor holds.

What is true of every RPC.

Every RPC reaches its handler through the router, and which of its directions answers is declared per method rather than being a property of the call site — see Extensibility.

[Rpc(Execution = Execution.Deferred)]        // minutes of work — an answer inside the call would be a timeout
public static MatchReport BuildMatchReport(MatchId match) => Reports.Build(match);

var work = await playserv.Rpc.Invoke.BuildMatchReport(matchId);   // the descriptor, not the report
work.OnOutcome(report => Hud.ShowReport(report));                 // or read it later, by descriptor
await work.Cancel();                                              // a request, not a promise nothing ran

export class ReportRpcs {
  @Rpc({ execution: Execution.Deferred })    // minutes of work — an answer inside the call would be a timeout
  static buildMatchReport(match: MatchId): MatchReport { return Reports.build(match); }
}

const work = await playserv.rpc.invoke.buildMatchReport(matchId);  // the descriptor, not the report
work.onOutcome((report) => hud.showReport(report));                // or read it later, by descriptor
await work.cancel();                                               // a request, not a promise nothing ran

@rpc(execution=Execution.DEFERRED)           # minutes of work — an answer inside the call would be a timeout
def build_match_report(match: MatchId) -> MatchReport:
    return reports.build(match)

work = await playserv.rpc.invoke.build_match_report(match_id)   # the descriptor, not the report
work.on_outcome(lambda report: hud.show_report(report))         # or read it later, by descriptor
await work.cancel()                                             # a request, not a promise nothing ran

// the client side of a deferred call: a descriptor now, the outcome against it later
Client->Rpc->Call->BuildMatchReport(MatchId,
    TPSOnResult<FPSDeferredHandle>::CreateWeakLambda(this, [this](const TPSResult<FPSDeferredHandle>& Result)
    {
        if (!Result.HasValue()) { return; }
        const FPSDeferredHandle Work = Result.Value();
        TPSSubscription ReportWatch = Client->Rpc->Deferred->Subscribe(Work,
            [this](const FMatchReport& Report) { Hud->ShowReport(Report); });
        Client->Rpc->Deferred->Cancel(Work);   // a request, not a promise nothing ran
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// the client side of a deferred call: a descriptor now, the outcome against it later
var work = await playserv.Rpc.Invoke.BuildMatchReport(matchId);
work.OnOutcome(report => Hud.ShowReport(report));
await work.Cancel();                         // a request, not a promise nothing ran

Errors

• The right is on the RPC, never on the primitive. There is no blanket "may invoke": each declaration names the atom its caller must hold, and a caller without it gets a typed forbidden refusal, code and all — not a silent drop.
• A hidden instance reads as "not found". An entity RPC invoked on an instance the caller's row predicate hides answers exactly as reading that instance would, so the refusal tells the caller nothing about what exists.
• No handler is "unavailable", not "not found". The RPC is declared, so it exists; what is missing is a route. That refusal is repeatable — a game server can come back — while "not found" would tell the caller to stop trying.
• A hook refusal carries the hook's own code and reason, so "rejected by a rule of the game" never arrives looking like "the transport broke".
• A timeout is not an outcome. For a deferred call you read the descriptor; for an immediate one the declared idempotency key is what makes the retry safe — including on a one-way call, where the absence of an answer is not an absence of redelivery.

Limits

Each ceiling names its behaviour at the edge; the numbers behind them land with the platform limits chapter.

• Input size — the call is refused before execution.
• Output size — refused rather than truncated, because a trimmed answer is indistinguishable from a full one.
• Call rate per actor — a rate-limit refusal naming when to retry.
• Concurrent deferred calls per actor — the new one is refused and the ones in flight finish.
• Descriptor lifetime — past it the outcome is unavailable, and that is a refusal.
• Call-chain depth — a declared refusal on exceeding it, never exhausted resources or a silent break.

User flow

One score submitted, one ping reported, one squad asked whether it is ready.

Not translated yet — showing English.

Data

You change one field. Everything downstream happens with not one line of code. Data is the third primitive: the mechanics under every synced field — deltas against the last acknowledged state, the aspect as the unit of policy, priority and send rate, resumable subscriptions, the retained window, and before/after change hooks.

You address entities, not tables — see Entity for the read and change surface (find, filter, sort, page, subscribe to a selection); this page is the mechanics underneath. There is no consumer path to a table, and no second way to write: a change is an Entity operation, and the delta is what follows from it.

When to use it

• You need state replicated to clients without snapshot code — changing a field is the whole sync.
• Fields differ in urgency or audience — priority and a send-rate ceiling per aspect, and a visibility predicate for fog-of-war.
• A reconnecting client must not diverge in silence — a gap is detected and named, and a gap past the retained window is answered with full state.
• You need the recent past — the retained window of deltas, indexed by sim_time, is what prediction and lag compensation read.
• A validation rule belongs in one place — a before-change hook clamps or vetoes before the change lands.
• Skip the knobs when all you need is to read or query — Entity's surface rides these mechanics without touching them.

Who does what

At a glance

public class Motion
{
    public Vector3 Position;
    [Sync(Hz = 4)] public float Fuel;                    // one field overrides the aspect
}

public class Loadout { public int Ammo; }

[Entity("tank")]
public class Tank
{
    [Aspect("motion", Priority = 10, Hz = 30)]           // policy lives on the aspect
    public Motion Motion = new();

    [Aspect("loadout", Visible = "owner == caller.player")]
    public Loadout Loadout = new();

    public float InternalHeat;                           // in no aspect — never leaves the server
}

tank.Motion.Position = next;   // ← the change; the delta is its consequence

export class Motion {
  position!: Vector3;
  @Sync({ hz: 4 }) fuel = 0;                             // one field overrides the aspect
}

export class Loadout { ammo = 0; }

@Entity('tank')
export class Tank {
  @Aspect('motion', { priority: 10, hz: 30 })            // policy lives on the aspect
  motion = new Motion();

  @Aspect('loadout', { visible: 'owner == caller.player' })
  loadout = new Loadout();

  internalHeat = 0;                                      // in no aspect — never leaves the server
}

tank.motion.position = next;   // ← the change; the delta is its consequence

class Motion:
    position: Vector3
    fuel: float = sync(hz=4)                             # one field overrides the aspect

class Loadout:
    ammo: int = 0

@entity("tank")
class Tank:
    motion: Motion = aspect("motion", priority=10, hz=30)          # policy lives on the aspect
    loadout: Loadout = aspect("loadout", visible="owner == caller.player")
    internal_heat: float = 0.0                           # in no aspect — never leaves the server

tank.motion.position = next_pos   # ← the change; the delta is its consequence

// declarations compile into the same pushed model — playserv push from the UE project or CI
USTRUCT()
struct FMotion
{
    GENERATED_BODY()

    UPROPERTY() FVector3f Position;
    UPROPERTY(PSSync = (Hz = 4)) float Fuel;             // one field overrides the aspect
};

USTRUCT()
struct FLoadout
{
    GENERATED_BODY()

    UPROPERTY() int32 Ammo;
};

UCLASS(PSEntity = "tank")
class UTank : public UObject
{
    GENERATED_BODY()

    UPROPERTY(PSAspect = (Name = "motion", Priority = 10, Hz = 30))   // policy lives on the aspect
    FMotion Motion;

    UPROPERTY(PSAspect = (Name = "loadout", Visible = "owner == caller.player"))
    FLoadout Loadout;

    float InternalHeat = 0.f;                            // no UPROPERTY, in no aspect — never leaves the server
};

Tank->Motion.Position = Next;   // ← the change; the delta is its consequence

public class Motion
{
    public Vector3 Position;
    [Sync(Hz = 4)] public float Fuel;                    // one field overrides the aspect
}

public class Loadout { public int Ammo; }

[Entity("tank")]
public class Tank
{
    [Aspect("motion", Priority = 10, Hz = 30)]           // policy lives on the aspect
    public Motion Motion = new();

    [Aspect("loadout", Visible = "owner == caller.player")]
    public Loadout Loadout = new();

    public float InternalHeat;                           // in no aspect — never leaves the server
}

tank.Motion.Position = next;   // ← the change; the delta is its consequence

The model

What a delta carries.

What an aspect declares.

All of it by attribute, on the aspect or on a single field, never by a call at runtime. The aspect sets the default and a field may override it; the aspect stays the unit of policy, because otherwise there is nothing to assemble presets from.

What a subscription holds.

What is true of every stream.

What a hook may do, and when.

[Before(Data.Change, aspect: "tank.motion")]
public static Verdict ClampFuel(Change<Motion> change) =>
    change.Next.Fuel < 0 ? Hook.Reject("negative fuel") : Hook.Continue(change);

export const clampFuel = before(Data.change, { aspect: 'tank.motion' }, (change: Change<Motion>) =>
  change.next.fuel < 0 ? Hook.reject('negative fuel') : Hook.continue(change));

@before(data.change, aspect="tank.motion")
def clamp_fuel(change: Change[Motion]) -> Verdict:
    return hook.reject("negative fuel") if change.next.fuel < 0 else hook.proceed(change)

Deleting is hooked on Entity, where the delete lives; this primitive hooks the change.

Errors

• An undeclared subscription target is a validation refusal.
• No permission to subscribe answers forbidden or not found depending on whether the target's existence is itself a secret — the refusal must not become an oracle.
• A resumption position that does not parse is a bad request, never a silent restart from now.
• A subscription closed by the platform's side is a conflict, and it is observable: the machine's closed is terminal and reaching it is not something a client has to infer.
• The subscription count exhausted is a conflict — the permission is held, the room is not.

Limits

Each ceiling names its behaviour at the edge; the numbers behind them land with the platform limits chapter.

• The delta retention window — resuming from older than the window gives the full state rather than a refusal.
• Subscriptions per actor — a new one is refused and the existing ones continue.
• Delta size — the delta is split rather than truncated, and the split is observable.
• The send rate — an upper bound, not a guarantee.
• The cost of a per-actor packet — on exhaustion, declared degradation to the shared packet.

User flow

One position change, from the assignment to corrected motion on every screen.

Not translated yet — showing English.

Groups

One list, one mass listener. A group is the fourth primitive: a named set of actors that receives as one. You address the group and every member hears — a room, a chat, a matchmaking pool and a send-list are the same primitive with different rules: different entry and exit logic, different lifetime, the same list underneath.

When to use it

• You need parties, squads or guilds — named sets of players with a declared capacity and, where the type declares one, a lifetime.
• Membership should follow a declared rule the platform evaluates — new veterans fall in without a cron job, and without a re-evaluate call of your own.
• You want to address many players at once: a declared event fans out with send.*, a declared RPC reaches every member and each answer comes back named.
• You need one membership model reused as an audience — a visibility scope, a messaging conversation, a matchmaking party.
• Skip creating one when the set is one session's members — rooms is this primitive with room rules, and already addresses those.

Who does what

At a glance

// dynamic: the predicate decides membership, and the platform keeps the list current
[Group("veterans", Capacity = 500)]
[GroupRule("player.stats.matches >= 100")]
public static class Veterans { }

// explicit: members are added by an act — capacity, lifetime and lifecycle ride the type
[Group("squad", Capacity = 4, Lifetime = "2h",
       Create = GroupCreate.Ahead, Close = GroupClose.OnLastExit)]
public static class Squad { }

// the event a squad can carry — declared once, surfaced as send.* / on.*
[Event("rally_call")]
public record RallyCall(Vector3 Position);

// an instance of a declared type — a runtime act, so a call
var squad = await PlayServ.Groups.Squad.Create("squad-7");
await squad.Add(friendId);

// the group is an address
squad.Send.RallyCall(position);                   // declared event → generated method
var members = await squad.GetMembers();           // declared data → typed, subscribable

await foreach (var answer in squad.Invoke.ReadyCheck())   // N calls, one per member
    Hud.Mark(answer.Member, answer.Ready);                // each answer names who sent it

var game = PlayServ.Group("game");                // addressing sugar for one group

// dynamic: the predicate decides membership, and the platform keeps the list current
@Group('veterans', { capacity: 500 })
@GroupRule('player.stats.matches >= 100')
export class Veterans {}

// explicit: members are added by an act — capacity, lifetime and lifecycle ride the type
@Group('squad', { capacity: 4, lifetime: '2h',
                  create: GroupCreate.Ahead, close: GroupClose.OnLastExit })
export class Squad {}

// the event a squad can carry — declared once, surfaced as send.* / on.*
@Event('rally_call')
export class RallyCall { constructor(public position: Vector3) {} }

// an instance of a declared type — a runtime act, so a call
const squad = await playserv.groups.squad.create('squad-7');
await squad.add(friendId);

// the group is an address
squad.send.rallyCall(position);                   // declared event → generated method
const members = await squad.getMembers();         // declared data → typed, subscribable

for await (const answer of squad.invoke.readyCheck())   // N calls, one per member
  hud.mark(answer.member, answer.ready);                // each answer names who sent it

const game = playserv.group('game');              // addressing sugar for one group

# dynamic: the predicate decides membership, and the platform keeps the list current
@group("veterans", capacity=500)
@group_rule("player.stats.matches >= 100")
class Veterans: ...

# explicit: members are added by an act — capacity, lifetime and lifecycle ride the type
@group("squad", capacity=4, lifetime="2h",
       create=GroupCreate.AHEAD, close=GroupClose.ON_LAST_EXIT)
class Squad: ...

# the event a squad can carry — declared once, surfaced as send.* / on.*
@event("rally_call")
class RallyCall:
    position: Vector3

# an instance of a declared type — a runtime act, so a call
squad = await playserv.groups.squad.create("squad-7")
await squad.add(friend_id)

# the group is an address
squad.send.rally_call(position)                   # declared event → generated method
members = await squad.get_members()               # declared data → typed, subscribable

async for answer in squad.invoke.ready_check():   # N calls, one per member
    hud.mark(answer.member, answer.ready)         # each answer names who sent it

game = playserv.group("game")                     # addressing sugar for one group

// declarations compile into the same pushed model — playserv push from the UE project or CI
USTRUCT(PSGroup = (Name = "veterans", Capacity = 500, Rule = "player.stats.matches >= 100"))
struct FVeterans { GENERATED_BODY() };

USTRUCT(PSGroup = (Name = "squad", Capacity = 4, Lifetime = "2h",
                  Create = "Ahead", Close = "OnLastExit"))
struct FSquad { GENERATED_BODY() };

USTRUCT(PSEvent = (Name = "rally_call"))
struct FRallyCall { GENERATED_BODY() UPROPERTY() FVector Position; };

// an instance of a declared type — a runtime act, so a call
Client->Groups->Of<FSquad>()->Create(FPSIdempotencyKey(TEXT("squad-7")),
    TPSOnResult<FPSGroup*>::CreateWeakLambda(this, [this](const TPSResult<FPSGroup*>& Result)
    {
        if (!Result.HasValue()) { return; }
        FPSGroup* Squad = Result.Value();
        Squad->Members->Admit(FriendId);

        // the group is an address
        Squad->Publish->RallyCall({ Position });               // declared event → generated member
        Squad->Members->Select().Then(
            TPSOnResult<TArray<FPSMember>>::CreateWeakLambda(this, [this](const TPSResult<TArray<FPSMember>>& Members)
            {
                if (!Members.HasValue()) { return; }
                Roster->Show(Members.Value());
            }));

        Squad->Call->ReadyCheck(TPSOnResult<FReadyAnswer>::CreateWeakLambda(this,
            [this](const TPSResult<FReadyAnswer>& Answer)
            {
                if (!Answer.HasValue()) { return; }
                Hud->Mark(Answer.Value().Member, Answer.Value().Ready);   // fires once per member
            }));
    }));

// addressing sugar for one well-known group
Client->Groups->Get(PSKeys::Groups::Game,
    TPSOnResult<FPSGroup*>::CreateWeakLambda(this, [this](const TPSResult<FPSGroup*>& GameResult)
    {
        if (!GameResult.HasValue()) { return; }
        Announce(GameResult.Value());
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// the same C# declarations push from the Unity project; the client creates, addresses and subscribes
[Group("veterans", Capacity = 500)]
[GroupRule("player.stats.matches >= 100")]
public static class Veterans { }

[Group("squad", Capacity = 4, Lifetime = "2h",
       Create = GroupCreate.Ahead, Close = GroupClose.OnLastExit)]
public static class Squad { }

[Event("rally_call")]
public record RallyCall(Vector3 Position);

var squad = await PlayServ.Groups.Squad.Create("squad-7");
await squad.Add(friendId);

squad.Send.RallyCall(position);                   // declared event → generated method
var members = await squad.GetMembers();           // declared data → typed, subscribable

await foreach (var answer in squad.Invoke.ReadyCheck())   // N calls, one per member
    Hud.Mark(answer.Member, answer.Ready);                // each answer names who sent it

var game = PlayServ.Group("game");                // addressing sugar for one group

A room's chat is this primitive with message semantics on top: the room declares its own group type, mounts it in the room's namespace, and lets the room's own membership decide who is in — so the chat's list and the room's list can never disagree.

[Group("room-chat", In = Rooms.Namespace, Capacity = 64,
       Create = GroupCreate.Ahead, Close = GroupClose.OnLastExit)]
[EntryRule("actor in room.members")]        // the room decides who is in
public static class RoomChat { }

@Group('room-chat', { in: Rooms.namespace, capacity: 64,
                      create: GroupCreate.Ahead, close: GroupClose.OnLastExit })
@EntryRule('actor in room.members')
export class RoomChat {}

@group("room-chat", ns=rooms.namespace, capacity=64,
       create=GroupCreate.AHEAD, close=GroupClose.ON_LAST_EXIT)
@entry_rule("actor in room.members")
class RoomChat: ...

USTRUCT(PSGroup = (Name = "room-chat", In = "rooms", Capacity = 64,
                  Create = "Ahead", Close = "OnLastExit"),
        PSEntryRule = "actor in room.members")
struct FRoomChat { GENERATED_BODY() };

[Group("room-chat", In = Rooms.Namespace, Capacity = 64,
       Create = GroupCreate.Ahead, Close = GroupClose.OnLastExit)]
[EntryRule("actor in room.members")]        // the room decides who is in
public static class RoomChat { }

Nothing about a chat is in the primitive. The audience and the send.* surface come from here; author, thread and history come from Messaging, and who may administer the membership is a right of its own (Access), held by the room.

The model

What a group type declares.

What is true of every group.

Errors

• A rule that says no and a hook that says no are different answers. A false entry rule reads "entry impossible"; a hook rejection carries the hook's own reason and code. An entry hook that cannot be reached refuses the entry — the check fails closed rather than waving the actor through.
• Dynamic membership refuses hand edits. Add or Remove on a rule-declared group is a validation refusal: the predicate is the only thing that moves that list, and the platform recomputes it when the data behind it changes.
• Four rights, none implying another — enter, administer membership, publish to the group, read the composition (Access). An actor missing one gets a refusal, never a silent no-op; a group hidden from it by a visibility predicate answers "not found" instead, and a member always sees its own membership even when the composition is closed to it.

Limits

• Full is a conflict, not a matter of right. At capacity + 1 the entry is rejected as a conflict — the actor was allowed, the seat was not — and the same call succeeds once a seat frees. The capacity itself is on the type (Capacity = 4 above); how many groups a project and a single actor may hold is set with the platform limits chapter.
• An oversized group call is refused whole, before anything is sent — a fan-out is never half-delivered, so no caller has to detect that case. The size ceiling lands with the limits chapter with the platform limits.

User flow

A party forms, one rally call reaches every member, one fan-out RPC brings back an answer per member, and the squad queues as a unit.

Not translated yet — showing English.

Extensibility

Every platform scenario is a chain of registered functions. Replace a link or wrap it. This is what "customisable platform" means concretely, and it is what replaces open source: you replace the platform's own steps with your own, so you don't need our source.

When to use it

• A platform step must run your logic — declare the replacement for a named link with [Override(…)].
• You need checks or side effects around a step — ordered Before/After middleware that can veto or notify.
• Code must run on a schedule, an event, or a webhook — triggers hand you a parsed, typed context.
• You must know what will actually run before deploy — dry-run a chain and read the resolved order.
• Skip it when the rule concerns one entity's writes — a Data hook is the lighter form.

Who does what

At a glance

// gate one named step of the auth scenario — a before hook may refuse, fail-closed
[Before(Auth.SignIn)]
public static Task<Verdict> GateRegion(SignInAttempt a) =>
    a.Region == "sanctioned"
        ? Hook.Reject(Problem.Forbidden, "region not served")
        : Hook.Continue(a);

// wrap a step with ordered middleware
PlayServ.Extend.Scenario("commerce.purchase")
    .Before("grant", LogPurchaseIntent)
    .After("grant", NotifySquad, order: 10);

// customer code on a trigger
[OnSchedule("0 4 * * *")]
public static async Task NightlyCleanup() { ... }

// gate one named step of the auth scenario — a before hook may refuse, fail-closed
export const gateRegion = before(Auth.signIn, (a: SignInAttempt) =>
  a.region === 'sanctioned'
    ? Hook.reject(Problem.forbidden, 'region not served')
    : Hook.continue(a));

// wrap a step with ordered middleware
playserv.extend.scenario('commerce.purchase')
  .before('grant', logPurchaseIntent)
  .after('grant', notifySquad, { order: 10 });

// customer code on a trigger
export const nightlyCleanup = onSchedule('0 4 * * *', async () => { /* ... */ });

# gate one named step of the auth scenario — a before hook may refuse, fail-closed
@before(auth.sign_in)
async def gate_region(a):
    if a.region == "sanctioned":
        return hook.reject(problem.FORBIDDEN, "region not served")
    return hook.cont(a)

# wrap a step with ordered middleware
playserv.extend.scenario("commerce.purchase") \
    .before("grant", log_purchase_intent) \
    .after("grant", notify_squad, order=10)

# customer code on a trigger
@on_schedule("0 4 * * *")
async def nightly_cleanup(): ...

The model

What the platform gives you to attach to.

What a hook declares.

Three ways to attach code.

Where a call goes, and what is true of every route.

What a constraint between hooks is, and when it is checked.

[Rpc("resolve_price", Default = true)]
public static Price ResolvePrice(Sku sku) => Pricing.Base(sku);

[Rpc("resolve_price", When = "env == 'staging'")]
public static Price ResolvePriceStaging(Sku sku) => Pricing.WithDiscount(sku, 0.5f);

// a hook can carry a version too, gated by its own condition
[After("grant", When = "audience == 'beta'")]
public static void NotifySquadBeta(GrantResult r) => Messaging.PingBeta(r.Squad);

export const resolvePrice = rpc('resolve_price', { default: true },
  (sku: Sku) => Pricing.base(sku));

export const resolvePriceStaging = rpc('resolve_price', { when: "env == 'staging'" },
  (sku: Sku) => Pricing.withDiscount(sku, 0.5));

// a hook can carry a version too, gated by its own condition
export const notifySquadBeta = after('grant', { when: "audience == 'beta'" },
  (r: GrantResult) => Messaging.pingBeta(r.squad));

@rpc("resolve_price", default=True)
def resolve_price(sku: Sku) -> Price:
    return pricing.base(sku)

@rpc("resolve_price", when="env == 'staging'")
def resolve_price_staging(sku: Sku) -> Price:
    return pricing.with_discount(sku, 0.5)

# a hook can carry a version too, gated by its own condition
@after("grant", when="audience == 'beta'")
def notify_squad_beta(r: GrantResult):
    messaging.ping_beta(r.squad)

Take it, change it, ship it. "Proprietary open source" is a workflow, not a slogan — the platform's own logic is functions you can pull, edit and redeploy:

playserv functions pull matchmaking.match     # the platform's implementation, as source
# edit: widen the skill window for the weekend event
playserv push                                 # your version registers; the default stays as fallback

Customisation here runs on one axis, and it is logic: the overrides, middleware and versions this page is about.

The other axis does not exist. You cannot add your fields to a platform entity. A player, a room, a leaderboard record and an order are system state with their own machines, not the beginnings of your data model. Your data is your own entity, declared in Schema as Code and tied to the platform's state by a predicate — owner is this player, scope is this room — which is also what keeps it yours when the platform's own model moves.

Errors

• A name that matches no registered handler answers not found — a call is never quietly dropped because nobody was listening.
• A name registered twice, and a set with two implementations claiming the same condition, are refused when the set is declared — at deploy, not resolved by a coin toss at call time.
• A hook's refusal carries the hook's own code and reason, so "a rule of the game said no" never arrives looking like a transport failure.
• A hook that fails behaves by its declared kind — fail-open or fail-closed — and which one it is was declared rather than inferred from what happened.
• A hook may not change what is already claimed: not the owner, not the target, not the board or conversation a call was addressed to. It corrects inputs and returns a verdict.

Limits

Each ceiling names its behaviour at the edge; the numbers behind them land with the platform limits chapter.

• A hook's execution deadline — past it, the failure behaviour its kind declares.
• Hooks at one position, and implementations of one method — registering another is refused.
• The nesting depth of "a hook invokes an operation that has hooks" — a declared refusal, never resource exhaustion.
• The size of the context passed to a hook — truncation is forbidden, so registration is refused instead of a handler receiving half a context.

User flow

One purchase, from the player's click through the customised chain to the squad ping. fraud-check is the studio's own handler on Before("grant"), not a platform module; Commerce draws the same purchase from its own side.

Lessons & recipes: a leaderboard in Tanks uses this module's hooks; a daily tournament runs through this module.

Not translated yet — showing English.

Schema as Code

Declare the model in code, push it, get types back. The developer's way into the schema: the admin panel and code author the same model, and codegen closes the loop for every engine.

When to use it

• Your data model should live in code and review like code — declare, schema diff, schema push.
• Engine types must never drift from the deployed model — schema codegen regenerates the Unreal C++ and Unity C#.
• A breaking change must be readable and cancellable before it runs — propose → plan → apply.
• You reuse one bundle (Stat, Interactable) across projects — declare it once as a preset.
• Skip it when an operator only tweaks values in the admin panel — the model change still diffs back into code.

Who does what

At a glance

[Entity("item")]
public class Item
{
    public string Name = "";
    public Rarity Rarity;              // an enum declared the same way
    public Stats Stats = new();        // a part — embedded, no lifecycle of its own
}

[Part("stats")]
public class Stats { public int Power; public int Weight; }

@Entity('item')
export class Item {
  name = '';
  rarity!: Rarity;                   // an enum declared the same way
  stats = new Stats();               // a part — embedded, no lifecycle of its own
}

@Part('stats')
export class Stats { power = 0; weight = 0; }

@entity("item")
class Item:
    name: str = ""
    rarity: Rarity                     # an enum declared the same way
    stats: Stats = Stats()             # a part — embedded, no lifecycle of its own

@part("stats")
class Stats:
    power: int = 0
    weight: int = 0

USTRUCT(PSPart = "stats")
struct FItemStats
{
    GENERATED_BODY()

    UPROPERTY() int32 Power;
    UPROPERTY() int32 Weight;
};

UCLASS(PSEntity = "item")
class UItem : public UObject
{
    GENERATED_BODY()

    UPROPERTY() FString    Name;
    UPROPERTY() EPSRarity  Rarity;       // an enum declared the same way
    UPROPERTY() FItemStats Stats;        // a part — embedded, no lifecycle of its own
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

[Entity("item")]
public class Item
{
    public string Name = "";
    public Rarity Rarity;              // an enum declared the same way
    public Stats Stats = new();        // a part — embedded, no lifecycle of its own
}

[Part("stats")]
public class Stats { public int Power; public int Weight; }

playserv schema diff       # local declarations vs deployed schema
playserv schema push       # with a revision precondition — no blind overwrites
playserv schema codegen    # regenerate Unreal C++ / Unity C# types

Push is an explicit step. Nothing is uploaded when you save a file: a declaration reaches the deployed model only when playserv push (or schema push) runs, from your machine or from CI, and it carries the revision it was diffed against. A panel edit is visible to you the way any other drift is — schema diff shows it against your declarations. Seeing it is automatic; moving it in either direction is a command you run on purpose.

The model

What a declaration carries.

What a push promises.

What codegen promises.

What a migration promises.

Errors

• A caller without the role gets forbidden and the deployed model is untouched: a refusal is never a partial push. That is a different refusal from a stale revision, which is precondition_failed and means the diff was computed against a schema that has since moved — re-diff and push again.
• A value outside a declared bound is refused on write, never clamped, and a string past its declared length likewise. Clamping produces a value that is valid and wrong, and the cost lands on support rather than on the caller: a refusal costs one round trip.
• An invalid UTF-8 sequence is rejected on write rather than repaired.
• A breaking persistent change with no declared migration cannot be published at all.

Limits

Declaration-shaped ceilings are checked at declaration time — on deploy or on publication — rather than at first use, wherever the runtime symptom would not look like a refusal. That is the rule the platform limits chapter states, and it is why a schema that ships is one that already fits. The numbers themselves land with that chapter.

User flow

One new field, from its declaration in code to regenerated engine types.

Not translated yet — showing English.

Entity

The module everything else leans on. An entity is a schema declaration grown with live aspects: data 0..*, states 0..*, RPC 0..*, events 0..*, hooks, and change history. Maps bind obstacles to entities, collision binds a transform aspect, stats is a preset, world objects are a preset plus a state machine.

Entity mounts at the root, so room.Entity<Door>(id) and playserv.Entities<KeyDef>() sit directly on the root rather than behind a namespace. It builds on three primitives — events, RPC and data — and on nothing else. Collision, locomotion and prediction sit above it: each binds to one aspect, not to the whole entity, which is why a contact can fire a transition without the collision module knowing anything about permissions.

When to use it

• A world object needs behaviour, not just fields — state machines, permissioned RPCs and events on one declaration.
• Doors, traps, pickups: transitions must fire from client events, collision contacts, or stat thresholds without room code.
• You want game objects as one-line creations — apply or derive presets like world-objects.
• A dispute needs the exact world state at the shot — read an instance at a past sim_time, inside the declared window.
• Skip it when the thing has no identity — a value that only ever lives inside something else, like the text on a door's plaque, is a field in an aspect, not an entity of its own. Everything that is addressed is an entity: Data is the mechanics underneath, and no table path bypasses them.

Who does what

At a glance

[Aspect("info", Read = "any")]                            // rarely changes, everyone reads it
public class Info { public string Name; }

[Aspect("motion", Hz = 20, Read = "any", Write = "fn")]   // 20 updates a second while it swings
public class Motion { public float OpenRatio; public bool Jammed; }

[Machine("gate")]
public class Gate
{
    [State(Initial = true), Transition("open_requested", to: "opening")] public State Closed;
    [State, AfterSeconds(1.2f, to: "open")]                              public State Opening;
    [State, Transition("close_requested", to: "closed")]                 public State Open;
    [State("open.blocked"), Transition("cleared", to: "open", Guard = "!motion.jammed")] public State Blocked;
}

[Entity("key-def", Persistence = Persistence.Persistent)]  // authored content: key.bronze, key.gold
public class KeyDef
{
    [Key]    public string Key;
    [Aspect] public Info Info;
}

[Entity("door", Persistence = Persistence.Runtime)]
public class Door
{
    [Aspect]  public Info Info;
    [Aspect]  public Motion Motion;
    [Machine] public Gate Gate;
    [Ref]     public Ref<KeyDef> Needs;                            // holds the id, never the key
    [Event("locked", Clock = Clock.SimTime)] public Event Locked;  // reaches whoever sees the door

    [EntityRpc(Requires = Entity.Permissions.Execute, Rows = "caller in entity.room")]
    public void RequestOpen(Actor caller)
    {
        if (caller.Inventory.Has(Needs)) Gate.Fire("open_requested");
        else Locked.Send();
    }
}

@Aspect('info', { read: 'any' })                            // rarely changes, everyone reads it
export class Info { name = ''; }

@Aspect('motion', { hz: 20, read: 'any', write: 'fn' })     // 20 updates a second while it swings
export class Motion { openRatio = 0; jammed = false; }

@Machine('gate')
export class Gate {
  @State({ initial: true }) @Transition('open_requested', { to: 'opening' }) closed: State;
  @State() @AfterSeconds(1.2, { to: 'open' }) opening: State;
  @State() @Transition('close_requested', { to: 'closed' }) open: State;
  @State('open.blocked') @Transition('cleared', { to: 'open', guard: '!motion.jammed' }) blocked: State;
}

@Entity('key-def', { persistence: Persistence.Persistent })  // authored content: key.bronze, key.gold
export class KeyDef {
  @Key() key = '';
  @Aspect() info: Info;
}

@Entity('door', { persistence: Persistence.Runtime })
export class Door {
  @Aspect() info: Info;
  @Aspect() motion: Motion;
  @Machine() gate: Gate;
  @Ref() needs: Ref<KeyDef>;                                 // holds the id, never the key
  @Event('locked', { clock: Clock.SimTime }) locked: Event;  // reaches whoever sees the door

  @EntityRpc({ requires: Entity.permissions.execute, rows: 'caller in entity.room' })
  requestOpen(caller: Actor) {
    if (caller.inventory.has(this.needs)) this.gate.fire('open_requested');
    else this.locked.send();
  }
}

@aspect("info", read="any")                                  # rarely changes, everyone reads it
class Info:
    name: str = ""

@aspect("motion", hz=20, read="any", write="fn")             # 20 updates a second while it swings
class Motion:
    open_ratio: float = 0.0
    jammed: bool = False

@machine("gate")
class Gate:
    closed  = state(initial=True, on="open_requested", to="opening")
    opening = state(after_seconds=1.2, to="open")
    open    = state(on="close_requested", to="closed")
    blocked = state("open.blocked", on="cleared", to="open", guard="!motion.jammed")

@entity("key-def", persistence=Persistence.PERSISTENT)       # authored content: key.bronze, key.gold
class KeyDef:
    key: str = key()
    info: Info = aspect()

@entity("door", persistence=Persistence.RUNTIME)
class Door:
    info: Info = aspect()
    motion: Motion = aspect()
    gate: Gate = machine()
    needs: Ref[KeyDef] = ref()                               # holds the id, never the key
    locked = event("locked", clock=Clock.SIM_TIME)           # reaches whoever sees the door

    @entity_rpc(requires=entity.permissions.execute, rows="caller in entity.room")
    def request_open(self, caller: Actor):
        if caller.inventory.has(self.needs):
            self.gate.fire("open_requested")
        else:
            self.locked.send()

// declarations compile into the same pushed model — playserv push from the UE project or CI
USTRUCT()
struct FInfo { GENERATED_BODY() UPROPERTY() FString Name; };

USTRUCT()
struct FMotion { GENERATED_BODY() UPROPERTY() float OpenRatio; UPROPERTY() bool bJammed; };

USTRUCT(PSMachine = (Name = "gate"))
struct FGate
{
    GENERATED_BODY()

    UPROPERTY(PSState = (Name = "closed", Initial = "true"),
              PSTransition = (On = "open_requested", To = "opening"))               FPSState Closed;
    UPROPERTY(PSState = "opening", PSAfterSeconds = (Seconds = "1.2", To = "open")) FPSState Opening;
    UPROPERTY(PSState = "open", PSTransition = (On = "close_requested", To = "closed")) FPSState Open;
    UPROPERTY(PSState = (Name = "open.blocked"),
              PSTransition = (On = "cleared", To = "open", Guard = "!motion.jammed")) FPSState Blocked;
};

USTRUCT(PSEvent = (Name = "locked", Clock = "SimTime"))
struct FLocked { GENERATED_BODY() };                       // reaches whoever sees the door

UCLASS(PSEntity = (Name = "key-def", Persistence = "Persistent"))
class UKeyDef : public UObject
{
    GENERATED_BODY()

    UPROPERTY(PSKey)                                    FString Key;
    UPROPERTY(PSAspect = (Name = "info", Read = "any")) FInfo Info;
};

UCLASS(PSEntity = (Name = "door", Persistence = "Runtime"))
class UDoor : public UObject
{
    GENERATED_BODY()

    UPROPERTY(PSAspect = (Name = "info", Read = "any"))                          FInfo Info;
    UPROPERTY(PSAspect = (Name = "motion", Hz = 20, Read = "any", Write = "fn")) FMotion Motion;

    UPROPERTY(PSMachine = "gate")
    FGate Gate;

    UPROPERTY(PSRef = "key-def") TPSRef<UKeyDef> Needs;    // holds the id, never the key

    UFUNCTION(PSRpc = (Requires = "Entity.Execute", Rows = "caller in entity.room"))
    void RequestOpen();
};