Skip to main content
Data & Schema

Not translated yet — showing English.

Live Records

Subscribe to a query or a record, and the game gets its full current state, then a fresh copy every time it changes. There is no polling to write: when another player, a function or an operator in the Backoffice changes the data, your Changed handler runs with the new state. The examples use the Sky Arena schema; the C# types are set up in Reading Records.

using System.Collections.Generic;
using System.Linq;
using Playserv.Data;
using Playserv.DataSubscription;
using Playserv.Wrapper;

ISharedCollection<MatchResults> top = await PlayServData.Records<MatchResults>().SubscribeAsync(
    new PlayServRecordQuery<MatchResults>()
        .Where(m => m.Score >= 1000)
        .WithLimit(50));

void Show(IReadOnlyList<MatchResults> results) =>
    leaderboard.Show(results.OrderByDescending(m => m.Score).Take(10));   // sort on the client

Show(top.Items);          // the current state, already there when SubscribeAsync returns
top.Changed += Show;      // every change after that

Subscribe to a set of records

Records<T>().SubscribeAsync(query) returns an ISharedCollection<T>. Items holds the matching records' values: the current state is already in it when SubscribeAsync returns. After that, Changed fires with the whole set after every change. Changed doesn't fire for the starting state, so show Items first. Each time, the set is replaced as a whole; it isn't a list of what changed.

A live query supports less than a query that reads once:

FeatureRead onceLive
Where, And, IncludeYesYes
OrNoYes, up to 8 groups
Include of a relation of a relationNoYes
OrderBy, Search, Hide, cursorsYesNo: sort the records on the client.

A query with something the call doesn't support throws PlayServQueryCapabilityException, which names what to remove.


Subscribe to one record

record.SubscribeAsync() keeps one loaded record up to date, and returns an IPlayServRecordSubscription<T>:

var pilot = await PlayServData.Records<Pilots>().LoadAsync(pilotId);
var live = await pilot.SubscribeAsync();
hud.SetLevel(pilot.Value.Level);                                   // the state you loaded
live.Changed += change => hud.SetLevel(change.Record.Value.Level); // every change after that
MemberWhat it tells you
ChangedThe record changed. change.Record is the updated record; ChangedFields lists the fields that changed.
ConflictThe record changed on the platform while you had unsaved edits in it. You get both versions: LocalValue and RemoteValue.

A record with unsaved changes can't start a subscription: save or reload it first. A partial record is reloaded in full before it starts.


What arrives

WhenWhat you get
The subscription startsThe current state, in Items (or the record you subscribed). Changed doesn't fire.
A matching record is created, changed or deletedThe new full state of the set, in Changed.
A record linked through Include changesThe new full state too, with the linked record updated.

Events of a single-record subscription arrive on the Unity main thread, so you can update the UI from the handler.


Limits

WhatLimit
Records in a live set200
Fields64
Filters16, and 16 in each Or group
Or groups8
Levels of Include6

Keep a live set under 200 records

A live query without WithLimit that matches more than 200 records ends, at the start or later when the set grows past 200. Set WithLimit to 200 or less, or narrow the filter.


When a subscription ends

A subscription ends for good when:

  • the record it follows is deleted: record.IsDeleted is then true;
  • the set grows past 200 records without a limit.

Failure fires with the reason, then Terminated. State becomes Terminated and TerminalError holds the reason. The last state you received stays in Items or Record. To follow the data again, subscribe again.


Stop a subscription

Call CloseAsync() when you no longer need it, or Dispose() if you can't wait, for example in OnDestroy. State becomes Closed; no Failure or Terminated fires.

void OnDestroy() => top?.Dispose();

Identical subscriptions are shared

Several subscriptions with the same query share one on the platform. The shared one stops only when the last of them is closed, so close each one you open.


Reconnects

If the connection drops, State becomes Reconnecting, and the SDK opens every open subscription again once the game is back online, with no code on your side. The subscription then gets the current state, including anything that changed in the meantime. See Connection & Session.


Next steps

Last updated on 21 Oct 2026