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

Data

Mude um campo, e a sincronização vem junto. Data é a mecânica por trás de todo campo sincronizado — deltas contra o último estado confirmado, o aspecto como unidade de política, prioridade e taxa de envio, assinaturas que podem ser retomadas, a janela de retenção e hooks antes e depois da mudança.

Você endereça entidades, não tabelas — a interface de leitura e mudança (buscar, filtrar, ordenar, paginar, assinar uma seleção) está em Entity; esta página é a mecânica por baixo. Não existe um caminho do consumidor até uma tabela nem uma segunda forma de escrever: uma mudança é uma operação do Entity, e o delta é o que decorre dela.

Quando usar

• Você precisa de estado replicado para os clientes sem código de snapshot: mudar um campo já é toda a sincronização.
• Os campos diferem em urgência ou público: prioridade e um teto de taxa de envio por aspecto, e um predicado de visibilidade para a névoa de guerra.
• Um cliente que reconecta não pode divergir em silêncio: uma lacuna é detectada e identificada, e uma lacuna maior que a janela de retenção é respondida com o estado completo.
• Você precisa do passado recente: a janela de retenção de deltas, indexada por sim_time, é o que a predição e a compensação de lag leem.
• Uma regra de validação deve ficar num lugar só: um hook antes da mudança limita ou veta o valor antes que a mudança seja aplicada.
• Não é preciso mexer nesses ajustes quando você só precisa ler ou consultar. A interface do Entity usa essa mecânica sem alterar nada nela.

Quem faz o quê

Resumo

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

O modelo

O que um delta carrega.

O que um aspecto declara.

Tudo por atributo, no aspecto ou num único campo, nunca por uma chamada em runtime. O aspecto define o padrão, e um campo pode sobrescrevê-lo; o aspecto continua sendo a unidade de política, porque senão não haveria de onde montar presets.

O que uma assinatura guarda.

O que vale para todo fluxo.

O que um hook pode fazer, e quando.

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

A exclusão tem hook no Entity, onde ela fica; esta primitiva põe o hook na mudança.

Erros

• Um alvo de assinatura não declarado é uma recusa de validação.
• Sem permissão para assinar, a resposta é forbidden ou not found, conforme a própria existência do alvo seja ou não um segredo — a recusa não pode virar um oráculo.
• Uma posição de retomada que não pode ser interpretada é uma requisição inválida, nunca um recomeço silencioso a partir de agora.
• Uma assinatura encerrada pelo lado da plataforma é um conflito, e é observável: o closed da máquina é terminal, e chegar a ele não é algo que o cliente precise deduzir.
• O número de assinaturas esgotado é um conflito: a permissão existe, mas não há mais capacidade.

Limites

Os números chegam com o capítulo de limites da plataforma; o que acontece em cada teto já está definido.

• A janela de retenção de deltas: retomar de um ponto mais antigo que a janela dá o estado completo, e não uma recusa.
• Assinaturas por ator: uma nova é recusada, e as existentes continuam.
• Tamanho do delta: o delta é dividido em vez de truncado, e a divisão é observável.
• A taxa de envio: um limite superior, não uma garantia.
• O custo de um pacote por ator: quando se esgota, degradação declarada para o pacote compartilhado.