Cette page n’est pas encore traduite : la version anglaise est affichée.

Data

Modifiez un champ, la synchronisation suit. Data, c’est la mécanique sous chaque champ synchronisé : des deltas calculés par rapport au dernier état acquitté, l’aspect comme unité de politique, la priorité et la fréquence d’envoi, des abonnements qui reprennent là où ils s’étaient arrêtés, la fenêtre de rétention, et des hooks avant et après changement.

Vous vous adressez à des entités, pas à des tables — la page Entity décrit l’interface de lecture et de modification (rechercher, filtrer, trier, paginer, s’abonner à une sélection) ; cette page-ci décrit la mécanique en dessous. Aucun chemin ne mène un consommateur jusqu’à une table, et il n’existe pas de seconde façon d’écrire : un changement est une opération d’Entity, et le delta en est la conséquence.

Quand l’utiliser

• Vous voulez répliquer l’état vers les clients sans écrire de code de snapshot : modifier un champ suffit à le synchroniser.
• Les champs n’ont pas la même urgence ni la même audience : une priorité et un plafond de fréquence d’envoi par aspect, et un prédicat de visibilité pour le brouillard de guerre.
• Un client qui se reconnecte ne doit pas diverger en silence : un trou est détecté et signalé, et un trou qui dépasse la fenêtre de rétention reçoit l’état complet.
• Vous avez besoin du passé récent : la fenêtre de rétention des deltas, indexée par sim_time, est ce que lisent la prédiction et la compensation de latence (lag compensation).
• Une règle de validation doit vivre à un seul endroit : un hook avant changement borne ou bloque la valeur avant que le changement ne soit appliqué.
• Laissez les réglages de côté si vous voulez seulement lire ou interroger. L’interface d’Entity s’appuie sur cette mécanique sans y toucher.

Qui fait quoi

En bref

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

Le modèle

Ce que transporte un delta.

Ce que déclare un aspect.

Tout se déclare par attribut, sur l’aspect ou sur un champ isolé, jamais par un appel à l’exécution. L’aspect fixe la valeur par défaut et un champ peut la surcharger ; l’aspect reste l’unité de politique, sans quoi il n’y aurait rien à partir de quoi assembler des presets.

Ce que contient un abonnement.

Ce qui vaut pour tout flux.

Ce qu’un hook peut faire, et quand.

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

La suppression se branche sur Entity, où elle est définie ; cette primitive se branche sur le changement.

Erreurs

• Une cible d’abonnement non déclarée est un refus de validation.
• L’absence de permission pour s’abonner répond forbidden ou not found, selon que l’existence de la cible est elle-même un secret ou non — le refus ne doit pas devenir un oracle.
• Une position de reprise illisible est une requête invalide, jamais un redémarrage silencieux à partir de maintenant.
• Un abonnement fermé côté plateforme est un conflit, et il est observable : l’état closed de la machine est terminal, et le client n’a pas à le deviner.
• Un nombre d’abonnements épuisé est un conflit : la permission est bien détenue, mais il ne reste plus de capacité.

Limites

Les valeurs chiffrées arriveront avec le chapitre sur les limites de la plateforme ; ce qui se passe à chaque plafond est déjà fixé.

• La fenêtre de rétention des deltas : reprendre depuis un point plus ancien que la fenêtre donne l’état complet plutôt qu’un refus.
• Abonnements par acteur : un nouvel abonnement est refusé et les existants continuent.
• Taille d’un delta : le delta est découpé plutôt que tronqué, et le découpage est observable.
• La fréquence d’envoi : une borne supérieure, pas une garantie.
• Le coût d’un paquet par acteur : en cas d’épuisement, dégradation déclarée vers le paquet partagé.