Not translated yet — showing English.
Reading Records
Your game reads its data as typed C# records with PlayServData.Records<T>(). Each entity of your schema has a C# class; you load a record by its ID or query many with filters, sorting and pages. The examples use the Sky Arena schema: Ships, Pilots, MatchResults and the ArenaConfig singleton.
using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;
var ships = PlayServData.Records<Ships>();
// One record by ID
PlayServRecord<Ships> ship = await ships.LoadAsync(shipId);
Debug.Log(ship.Value.Name);
// Ships up to 500, cheapest first, 20 per page
var page = await ships.QueryAsync(
new PlayServRecordQuery<Ships>()
.Where(s => s.Price <= 500)
.OrderBy(s => s.Price),
new PlayServPagination(limit: 20));
C# types for your entities
Each entity needs a C# class with the same name and fields. You can generate them from the schema, or write them yourself.
| Way | How |
|---|---|
| Generate from the schema | In Tools ▸ PlayServ ▸ Settings, under Schema Workflows, choose Import JSON & Generate. The classes are written to Assets/Shared/Generated/Models and replaced each time you generate. |
| Write them yourself | Plain C# classes, no base class needed. With the local schema tool, the same classes can also define the schema, see Access Control. |
public class Ships
{
public string Name;
public ShipClass Class;
public Stats Stats; // an included part
public int Price;
}
public class Stats { public double Speed; public int Armor; public int Damage; }
public class Pilots
{
public string Callsign;
public int Level;
public PlayServRecordRef<Ships> Ship; // a relation
public Loadout Loadout;
}
| Rule | Why |
|---|---|
| The class is named exactly like the entity. | Records<Ships>() finds the entity by the class name. Use Records<T>("ent_…") with the entity's ID if they differ. |
| Field names match the schema exactly, case included. | Fields are sent under their C# names. [PlayServField("name")] maps a different name, [PlayServIgnore] leaves a member out. |
| Included parts are nested classes or lists. | They are stored inside the record. |
Relations are PlayServRecordRef<T> (SDK 0.6.4 and later), or the target's ID as a string, as in generated classes. | The record stores only the ID; see Relations. |
A loaded record comes as PlayServRecord<T>: its fields are in Value, and the record also carries its Id, Owner, CreatedAt and UpdatedAt. You never set the ID yourself: PlayServ creates it.
Load one record
| Call | Returns |
|---|---|
LoadAsync(id) | The record with that ID. Throws PlayServRecordNotFoundException if there isn't one. |
LoadByNaturalKeyAsync(PlayServNaturalKey<T>.For(x => x.Name, "Falcon")) | The record whose unique field has that value. The field must be marked Unique in the schema. |
LoadManyAsync(ids) | Several records by ID, in the order you asked, with a result per ID. |
var falcon = await ships.LoadByNaturalKeyAsync(PlayServNaturalKey<Ships>.For(s => s.Name, "Falcon"));
Query
QueryAsync(query, pagination) returns a page of records that match a PlayServRecordQuery<T>.
| Method | What it does |
|---|---|
Where(x => …) · And(x => …) | Filters with a C# condition: ==, !=, >, >=, <, <=, null checks, &&, and list.Contains(x.Field). |
Where(x => x.Field, PlayServQueryOperator.…, value) | Filters with an operator: Eq, Neq, Gt, Gte, Lt, Lte, In, Nin, Between, Contains, StartsWith, EndsWith, IsNull, IsNotNull, IsEmpty, IsNotEmpty, and Count… for list sizes. |
OrderBy(x => …) · OrderByDescending(x => …) | Sorts. |
Search("text") | Full-text search over the entity. |
SelectFields(...) · Hide(...) | Loads only some fields, see below. |
| Paging | What it does |
|---|---|
new PlayServPagination(limit: 20) | Records per page: 50 by default, up to 200. |
page.Records · page.HasMore · page.NextCursor | The records, whether there are more, and the cursor of the next page: pass it as new PlayServPagination(page.NextCursor, 20). |
LoadAllAsync(query) | Pages through for you, up to 1000 records by default; IsTruncated says whether there were more. |
Filter enum fields by name
To filter on an enum field, compare it with the value's name: Where("Class", PlayServQueryOperator.Eq, "Fighter"). A C# condition on the enum, such as x.Class == ShipClass.Fighter, may not match.
Relations and parts
Parts are part of the record: they load with it, and you can filter on their fields with a nested path, such as .Where(s => s.Stats.Speed > 10).
Relations store only the target's ID. To get the target record:
| Call | What it does |
|---|---|
await pilot.Value.Ship.LoadAsync() | Loads the related ship. Returns null, not an exception, if it no longer exists. |
.Include(p => p.Ship) on a query | Loads the related records together with the page: the ship's fields are then in pilot.Value.Ship.Value, with no extra call. A query includes direct relations only; live records can include nested ones. |
Load only some fields
SelectFields loads only the fields you name, and Hide loads all but those; you can use one or the other. A record loaded this way is partial: IsPartial is true, and it can't be saved until you call ReloadAsync().
A partial record can't be saved
The SDK refuses to save it and throws InvalidOperationException. Reload the record first, or load it without SelectFields.
Singletons
A singleton entity has exactly one record, read with GetSingletonAsync<T>():
PlayServSingleton<ArenaConfig> config = await PlayServData.GetSingletonAsync<ArenaConfig>();
int maxPlayers = config.Value.MaxPlayers;
A singleton has no ID and can't be deleted or subscribed to.
Errors
| Exception | When |
|---|---|
PlayServRecordNotFoundException | No record with that ID or natural key. |
PlayServDataAccessDeniedException | The game may not read this entity, see Access Control. |
PlayServQueryCapabilityException | The query uses something the call doesn't support, see Live Records. |
PlayServDataException | Anything else: StatusCode, BackendCode and IsNetworkError say what happened. |
Players see only their own records of a player-owned entity
On an entity owned by players, with read access Owner, a query returns only the signed-in player's records. See Player-owned entities.
Next steps
- Writing Records — create, save and delete records
- Live Records — get changes as they happen
- Access Control — who may read each entity
Last updated on 21 Oct 2026