Pular para o conteúdo principal
Data e Schema

Esta página ainda não foi traduzida: mostrando a versão em inglês.

Leitura de Records

O seu jogo lê os dados como Records C# tipados com PlayServData.Records<T>(). Cada Entity do seu Schema tem uma classe C#; você carrega um Record pelo ID ou consulta vários com filtros, ordenação e páginas. Os exemplos usam o Schema do Sky Arena: Ships, Pilots, MatchResults e o singleton ArenaConfig.

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));

Tipos C# para as suas Entities

Cada Entity precisa de uma classe C# com o mesmo nome e os mesmos campos. Você pode gerá-las a partir do Schema ou escrevê-las à mão.

FormaComo
Gerar a partir do SchemaEm Tools ▸ PlayServ ▸ Settings, na seção Schema Workflows, escolha Import JSON & Generate. As classes são gravadas em Assets/Shared/Generated/Models e substituídas a cada nova geração.
Escrever à mãoClasses C# comuns, sem classe base. Com a ferramenta de Schema local, as mesmas classes também podem definir o Schema, veja Controle de acesso.
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;
}
RegraPor quê
A classe tem exatamente o nome da Entity.Records<Ships>() encontra a Entity pelo nome da classe. Se os nomes forem diferentes, use Records<T>("ent_…") com o ID da Entity.
Os nomes dos campos batem exatamente com o Schema, inclusive maiúsculas e minúsculas.Os campos são enviados com os nomes que têm em C#. [PlayServField("name")] mapeia um nome diferente, e [PlayServIgnore] deixa um membro de fora.
Parts incluídas são classes aninhadas ou listas.Elas ficam guardadas dentro do Record.
Relações são PlayServRecordRef<T> (SDK 0.6.4 ou mais recente) ou o ID do destino como string, como nas classes geradas.O Record guarda só o ID; veja Relações.

Um Record carregado chega como PlayServRecord<T>: os campos ficam em Value, e o Record também traz Id, Owner, CreatedAt e UpdatedAt. Você nunca define o ID: quem o cria é o PlayServ.


Carregar um Record

ChamadaRetorna
LoadAsync(id)O Record com esse ID. Lança PlayServRecordNotFoundException se ele não existir.
LoadByNaturalKeyAsync(PlayServNaturalKey<T>.For(x => x.Name, "Falcon"))O Record cujo campo único tem esse valor. O campo precisa estar marcado como Unique no Schema.
LoadManyAsync(ids)Vários Records por ID, na ordem pedida, com um resultado para cada ID.
var falcon = await ships.LoadByNaturalKeyAsync(PlayServNaturalKey<Ships>.For(s => s.Name, "Falcon"));

Consultar

QueryAsync(query, pagination) retorna uma página de Records que atendem a uma PlayServRecordQuery<T>.

MétodoO que faz
Where(x => …) · And(x => …)Filtra com uma condição C#: ==, !=, >, >=, <, <=, verificações de null, && e list.Contains(x.Field).
Where(x => x.Field, PlayServQueryOperator.…, value)Filtra com um operador: Eq, Neq, Gt, Gte, Lt, Lte, In, Nin, Between, Contains, StartsWith, EndsWith, IsNull, IsNotNull, IsEmpty, IsNotEmpty e Count… para o tamanho de listas.
OrderBy(x => …) · OrderByDescending(x => …)Ordena.
Search("text")Busca de texto completo na Entity.
SelectFields(...) · Hide(...)Carrega só alguns campos, veja abaixo.
PaginaçãoO que faz
new PlayServPagination(limit: 20)Records por página: 50 por padrão, até 200.
page.Records · page.HasMore · page.NextCursorOs Records, se há mais e o cursor da próxima página: passe-o como new PlayServPagination(page.NextCursor, 20).
LoadAllAsync(query)Percorre as páginas por você, até 1000 Records por padrão; IsTruncated informa se havia mais.

Filtre campos Enum pelo nome

Para filtrar um campo Enum, compare-o com o nome do valor: Where("Class", PlayServQueryOperator.Eq, "Fighter"). Uma condição C# sobre o enum, como x.Class == ShipClass.Fighter, pode não encontrar nada.


Relações e Parts

Parts fazem parte do Record: são carregadas junto com ele, e você pode filtrar pelos campos delas com um caminho aninhado, como .Where(s => s.Stats.Speed > 10).

Relações guardam só o ID do destino. Para obter o Record de destino:

ChamadaO que faz
await pilot.Value.Ship.LoadAsync()Carrega a nave relacionada. Retorna null, e não uma exceção, se ela não existir mais.
.Include(p => p.Ship) numa consultaCarrega os Records relacionados junto com a página: os campos da nave ficam então em pilot.Value.Ship.Value, sem chamada extra. Uma consulta inclui só relações diretas; Records ao vivo podem incluir relações aninhadas.

Carregar só alguns campos

SelectFields carrega só os campos que você indicar, e Hide carrega todos menos esses; use um ou outro. Um Record carregado assim é parcial: IsPartial é true, e ele não pode ser salvo até você chamar ReloadAsync().

Um Record parcial não pode ser salvo

O SDK se recusa a salvá-lo e lança InvalidOperationException. Recarregue o Record antes ou carregue-o sem SelectFields.


Singletons

Uma Entity singleton tem exatamente um Record, lido com GetSingletonAsync<T>():

PlayServSingleton<ArenaConfig> config = await PlayServData.GetSingletonAsync<ArenaConfig>();
int maxPlayers = config.Value.MaxPlayers;

Um singleton não tem ID, não pode ser excluído e não aceita assinaturas.


Erros

ExceçãoQuando
PlayServRecordNotFoundExceptionNão existe Record com esse ID ou chave natural.
PlayServDataAccessDeniedExceptionO jogo não tem permissão de ler esta Entity, veja Controle de acesso.
PlayServQueryCapabilityExceptionA consulta usa algo que a chamada não suporta, veja Records ao vivo.
PlayServDataExceptionQualquer outro caso: StatusCode, BackendCode e IsNetworkError dizem o que aconteceu.

Players só veem os próprios Records de uma Entity que pertence a Players

Numa Entity que pertence a Players, com acesso de leitura Owner, uma consulta retorna só os Records do Player logado. Veja Entities que pertencem a Players.


Próximos passos

Atualizado em 21 de out. de 2026