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

Files & UGC

Les fichiers arrivent par morceaux et sont traités au fil de l’arrivée. Envois, assets et leurs variantes dérivées, et contenu créé par les joueurs, avec un circuit de modération.

Quand l’utiliser

• Des joueurs ou des services envoient des blobs : des sessions d’envoi (upload) par morceaux, reprenables, avec des quotas par joueur consultables.
• Le traitement doit démarrer avant la fin de l’envoi : lisez le fichier comme un flux, morceau par morceau.
• Le contenu créé par les joueurs a besoin d’un circuit de modération : SubmitUgc, une file d’attente, un verdict, des hooks aux deux bouts.
• Une même image maîtresse doit servir de nombreuses plateformes : dérivez des variantes (redimensionnement, transcodage) et gardez l’original comme référence.
• Inutile pour les petites charges utiles structurées. Un champ d’enregistrement de Data & Subscriptions les transporte sans session d’envoi.

Qui fait quoi

En bref

// upload, chunked, resumable
var session = await PlayServ.Files.OpenUpload("skins/tank-07.png", contentType: "image/png");
await session.Write(chunk);
var file = await session.Complete();

// consume a file as a stream — start processing before the upload finishes
await using var read = PlayServ.Files.OpenRead(file);
await foreach (var chunk in read) Ingest(chunk);

// attach to an entity
await tank.Attach("decal", file);

// upload, chunked, resumable
const session = await playserv.files.openUpload('skins/tank-07.png', { contentType: 'image/png' });
await session.write(chunk);
const file = await session.complete();

// consume a file as a stream — start processing before the upload finishes
const read = playserv.files.openRead(file);
for await (const chunk of read) ingest(chunk);

// attach to an entity
await tank.attach('decal', file);

# upload, chunked, resumable
session = await playserv.files.open_upload("skins/tank-07.png", content_type="image/png")
await session.write(chunk)
file = await session.complete()

# consume a file as a stream — start processing before the upload finishes
async with playserv.files.open_read(file) as read:
    async for chunk in read:
        ingest(chunk)

# attach to an entity
await tank.attach("decal", file)

// upload, chunked, resumable
Client->Files->Of<FSkin>()->Uploads->Create(FPSIdempotencyKey(UploadId),
    FPSUploadSpec{ .Path = TEXT("skins/tank-07.png"), .ContentType = TEXT("image/png") },
    TPSOnResult<FPSUpload*>::CreateWeakLambda(this, [this](const TPSResult<FPSUpload*>& Result)
    {
        if (!Result.HasValue()) { return; }
        FPSUpload* Upload = Result.Value();
        Upload->Parts->Create(PartNumber, Chunk);
        Upload->Complete(TPSOnResult<FPSFileHandle*>::CreateWeakLambda(this, [this](const TPSResult<FPSFileHandle*>& Completed)
        {
            if (!Completed.HasValue()) { return; }
            OnSkinUploaded(Completed.Value());
        }));
    }));

// consume a file as a stream — start processing before the upload finishes
TPSSubscription SkinBytes = Client->Files->Of<FSkin>()->Contents->Subscribe(File,
    [this](const TArray<uint8>& Chunk) { Ingest(Chunk); });

// attach to an entity
Tank->Files->Attach(TEXT("decal"), File);
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// upload, chunked, resumable
var session = await PlayServ.Files.OpenUpload("skins/tank-07.png", contentType: "image/png");
await session.Write(chunk);
var file = await session.Complete();

// consume a file as a stream — start processing before the upload finishes
await using var read = PlayServ.Files.OpenRead(file);
await foreach (var chunk in read) Ingest(chunk);

// attach to an entity
await tank.Attach("decal", file);

L’UGC, côté joueur :

var submission = await playserv.Files.SubmitUgc(file, kind: "level");   // cl

const submission = await playserv.files.submitUgc(file, { kind: 'level' });   // cl

submission = await playserv.files.submit_ugc(file, kind="level")   # cl

// client — a submission is keyed; a retried submit returns the same submission
Client->Files->Ugc->Create(FPSIdempotencyKey(SubmitId), File,
    TPSOnResult<FPSSubmission*>::CreateWeakLambda(this, [this](const TPSResult<FPSSubmission*>& Result)
    {
        if (!Result.HasValue()) { return; }
        Hud->ShowPending(Result.Value());
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

var submission = await playserv.Files.SubmitUgc(file, kind: "level");   // cl

Les contrôles autour sont des hooks, avec le même contrat que partout ailleurs :

[Before(Files.Upload)]
public static Verdict CheckUpload(UploadIntent u) =>
    u.Size > 20.Mb() ? Hook.Reject("too large") : Hook.Continue(u);

[After(Files.SubmitUgc)]
public static Task Screen(UgcSubmission s) => PlayServ.Files.Moderation.Enqueue(s);

export const checkUpload = before(Files.upload, (u: UploadIntent) =>
  u.size > mb(20) ? Hook.reject('too large') : Hook.continue(u));

export const screen = after(Files.submitUgc,
  (s: UgcSubmission) => playserv.files.moderation.enqueue(s));

@before(files.upload)
def check_upload(u: UploadIntent) -> Verdict:
    return hook.reject("too large") if u.size > mb(20) else hook.continue_(u)

@after(files.submit_ugc)
async def screen(s: UgcSubmission):
    await playserv.files.moderation.enqueue(s)

Les deux hooks encadrent une étape d’opération, jamais un événement : Before(Files.Upload) décide si l’envoi démarre, After(Files.SubmitUgc) s’exécute une fois la soumission créée et la place dans la file de modération via le Moderation.Enqueue du module. Les événements (envoi terminé, variante prête, UGC soumis, verdict de modération) vont aux abonnés, et un abonné n’oppose de veto à rien.

Le modèle

Un fichier, ce sont des octets opaques plus des métadonnées déclarées (origine, type de contenu, taille), et ce n’est pas un stockage d’état sur lequel on prend des décisions. Son lien avec le modèle du jeu va dans l’autre sens : c’est un champ de votre type qui porte la référence ; le fichier ne sait rien du jeu.

Ce que déclare un type de fichier.

Ce qui vaut pour tout fichier.

Chaque point d’extension nomme le type qu’il transmet au hook (l’intention d’envoi avant l’envoi, la soumission après) : un hook ne reçoit donc jamais un sac de valeurs non typé.

Erreurs

• L’absence de droit d’usage répond not found, pas forbidden : la liste des refus ne révèle pas quels contenus additionnels existent. Un fichier retiré répond de la même façon.
• Une session expirée est un conflit : ouvrez-en une nouvelle.
• Une partie hors de l’ordre ou de la taille déclarés, un type de contenu non déclaré et une taille au-delà de la limite sont des refus de validation ; celui sur la taille tombe à l’ouverture de la session, pas après le transfert des octets.
• Une somme de contrôle qui ne concorde pas est un refus de validation qui vaut la peine d’être retenté : renvoyez la partie.
• Le quota épuisé est un conflit, à retenter après avoir libéré de l’espace.
• Un droit de lecture expiré répond not authenticated : demandez-en un nouveau au lieu de le traiter comme un problème de permission.
• Un rejet à la modération est un verdict, pas un refus : la soumission a été examinée et la réponse est négative, avec un motif déclaré ; la suite dépend donc du motif.
• La fréquence d’envoi dépassée répond dans la catégorie rate limit, avec un délai.

Limites

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

• La taille d’un fichier selon son origine : l’envoi est refusé avant qu’aucune partie ne soit acceptée, pas sur la dernière.
• La taille d’une partie : la partie est refusée pour échec de validation.
• La durée de vie de la session : expired avec un événement, et les parties sont libérées.
• Le quota de stockage par projet et par joueur : une nouvelle session est refusée comme conflit, et ce qui est déjà publié n’est jamais supprimé en silence pour faire de la place.
• Les versions de contenu créé par l’équipe conservées : la plus ancienne est retirée, mais une version référencée par un environnement en vigueur ne l’est jamais.
• La fréquence d’envoi par acteur : une limite de débit, avec un délai.
• La rétention du contenu généré par le jeu : passé ce délai, un retrait avec un événement.