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.
| Forma | Como |
|---|---|
| Gerar a partir do Schema | Em 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ão | Classes 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;
}
| Regra | Por 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
| Chamada | Retorna |
|---|---|
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étodo | O 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ção | O que faz |
|---|---|
new PlayServPagination(limit: 20) | Records por página: 50 por padrão, até 200. |
page.Records · page.HasMore · page.NextCursor | Os 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:
| Chamada | O 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 consulta | Carrega 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ção | Quando |
|---|---|
PlayServRecordNotFoundException | Não existe Record com esse ID ou chave natural. |
PlayServDataAccessDeniedException | O jogo não tem permissão de ler esta Entity, veja Controle de acesso. |
PlayServQueryCapabilityException | A consulta usa algo que a chamada não suporta, veja Records ao vivo. |
PlayServDataException | Qualquer 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
- Escrita de Records — criar, salvar e excluir Records
- Records ao vivo — receber as alterações assim que acontecem
- Controle de acesso — quem pode ler cada Entity
Atualizado em 21 de out. de 2026