Utilisation détaillée

1. Configurer le système

La configuration du système se fait dans un Data Asset.

RAPPEL

Comme indiqué dans la section Installation, le Data Asset de configuration doit être ajouté à la liste des assets à cooker.

Ouvrir DA_ADS_SaveSystemConfig pour paramétrer le système. Le plugin charge cet asset dans cet emplacement, il ne faut donc ni le déplacer ni le renommer ni le supprimer. Voici le détails des paramètres :

Paramètre	Description
Project Save Behavior	Classe Blueprint dérivée de ADS Project Save Behavior. Elle est facultative, mais permet de gérer les événements et les conversions propres au projet.
Profile Save Game Class	Classe dérivée de ADS Save Game Object utilisée pour `profile.sav`.
Slot Save Game Class	Classe dérivée de ADS Save Game Object utilisée pour les slots manuels et automatiques.
Current Save Version	Version du format de sauvegarde, au minimum `1`. Augmentez-la lorsqu’une évolution rend les anciennes données incompatibles.
Auto Convert Without Confirmation	Active la conversion directe des anciennes sauvegardes. Désactivé, le projet reçoit d’abord une demande de confirmation.
Manual Save Slot Base Name	Préfixe des sauvegardes manuelles. Par exemple, `save` produit `save01` ; ajoutez vous-même un séparateur si nécessaire.
Manual Save Max Slot Index	Dernier index autorisé pour une sauvegarde manuelle, de `0` à `999`.
Automatic Save Slot Base Name	Préfixe des sauvegardes automatiques. Aucun séparateur n’est ajouté automatiquement.
Automatic Save Slot Count	Nombre de slots utilisés en rotation pour les sauvegardes automatiques, de `1` à `5`.
Save Operation Timeout	Temps d’attente des réponses des participants, entre `2` et `20` secondes.
Default Slot Thumbnail	Image de repli utilisée lorsqu’une miniature enregistrée est indisponible.
Thumbnail Width	Largeur de la miniature capturée, de `64` à `2048` pixels.
Thumbnail Height	Hauteur de la miniature capturée, de `64` à `2048` pixels.
Thumbnail JPEG Quality	Qualité de compression JPEG de la miniature, de `1` à `100`.
Custom Save Directory	Réservé aux usages personnalisés. Les opérations de slots utilisent actuellement le répertoire de sauvegarde Unreal Engine standard.

2. Le subsystem

Accéder au subsystem

ADS Save System est un Game Instance Subsystem. Récupérez une référence au subsystem dans le Blueprint qui doit l’utiliser.

Les fonctions

Les fonctions ci-dessous sont accessibles depuis une référence au subsystem.

Fonction	Description
`Get Project Save Behavior`	Retourne le comportement de sauvegarde du projet.
`Get Project Save Behavior As`	Retourne le comportement de projet avec la classe demandée.
`Check Config`	Vérifie la configuration runtime et retourne les avertissements et erreurs.
`Get Current Save Version`	Retourne la version courante du format de sauvegarde.
`Check Save Version`	Compare une version de sauvegarde à la version courante.
`Get Save Version From Slot`	Lit la version de sauvegarde contenue dans un slot.
`Scan Saves Needing Conversion`	Recherche les sauvegardes qui nécessitent une conversion.
`Is Convert Pending`	Indique si une conversion est en attente.
`Continue Convert`	Poursuit une conversion en attente.
`Cancel Convert`	Annule une conversion en attente.
`Add Participant`	Inscrit un participant et définit les types de sauvegarde auxquels il participe.
`Remove Participant`	Retire un participant inscrit.
`Clear Participants`	Retire tous les participants inscrits.
`Cleanup Participants`	Retire les références de participants qui ne sont plus valides.
`Get Registered Participants`	Retourne les participants inscrits.
`Get Registered Participant Count`	Retourne le nombre de participants inscrits.
`Save Slot`	Démarre une sauvegarde de slot.
`Load Slot`	Démarre le chargement d’un slot.
`Get Slot Cache`	Retourne l’objet de sauvegarde mis en cache pour un slot.
`Get Last Save`	Retourne la dernière sauvegarde connue par le profil.
`Get Slot List`	Retourne la liste des slots demandés, existants ou vides.
`Delete Slot`	Supprime un slot manuel ou automatique.
`Copy Slot`	Copie un slot vers le premier slot disponible du même type.
`Format Time`	Formate une date UTC pour son affichage.
`Get Thumbnail`	Retourne la miniature d’un slot ou son image de repli.
`Save Slot Cache`	Enregistre le cache d’un slot sur disque.
`Does Slot Exist`	Indique si un slot existe.
`Get Slot Name`	Construit le nom correspondant à un type et un index de slot.
`Get Digits`	Retourne le nombre de chiffres nécessaire pour les indices de slots.
`Is Slot Index Valid`	Vérifie la validité d’un index de slot.
`Set Part Saved`	Signale que le participant a terminé sa sauvegarde.
`Set Part Loaded`	Signale que le participant a terminé son chargement.
`Is Saved Cache Complete`	Indique si tous les participants ont terminé leur sauvegarde.
`Is Loaded Cache Complete`	Indique si tous les participants ont terminé leur chargement.
`Is Operation In Progress`	Indique si une opération est active.
`Has Pending Load`	Indique si un chargement doit encore être appliqué.
`Apply Pending Load`	Applique un chargement mis en attente.
`Get Active Operation ID`	Retourne l’identifiant de l’opération active.
`Get Pending Participant Count`	Retourne le nombre de participants dont la réponse est attendue.
`Cancel Active Operation`	Annule l’opération active.
`Get Last Automatic Index`	Retourne le dernier index utilisé pour la sauvegarde automatique.
`Get Next Automatic Index`	Retourne le prochain index de sauvegarde automatique.
`Set Automatic Index State`	Définit l’état de rotation des sauvegardes automatiques.

Les Event Dispatchers

Les Event Dispatchers du subsystem permettent aux participants, aux menus et à la logique de projet de réagir aux opérations. Les participants doivent s’abonner dans leur BeginPlay à On Save Requested et On Load Requested pour traiter leur propre partie des données.

Event Dispatcher	Description
`On Save Requested`	Déclenché au début d’une sauvegarde. Chaque participant inscrit écrit ses données puis appelle `Set Part Saved` avec le contexte reçu.
`On Load Requested`	Déclenché lorsque les données chargées doivent être appliquées. Chaque participant les lit, les applique puis appelle `Set Part Loaded` avec le contexte reçu.
`On Save Completed`	Déclenché lorsqu’une sauvegarde réussit, échoue ou expire. L’écriture disque a lieu seulement après la réponse réussie de tous les participants attendus.
`On Load Completed`	Déclenché lorsqu’un chargement réussit, échoue ou expire, après l’application des données par tous les participants attendus.
`On Convert Completed`	Déclenché lorsqu’une conversion de sauvegarde réussit, échoue ou est annulée. Il est indépendant de la fin du chargement.
`On Slot Deleted`	Déclenché après la suppression réussie d’un slot manuel ou automatique. Les sauvegardes de profil ne peuvent pas être supprimées avec `Delete Slot`.
`On Slot Copied`	Déclenché après la copie réussie d’un slot manuel ou automatique vers le premier slot disponible du même type.

3. Save Game Object

Créez un Blueprint enfant de ADS Save Game Object et ajoutez-y les variables de projet à conserver (avec l’option SaveGame). Le système y renseigne automatiquement la version, la date UTC, le niveau, le type, l’index, le nom du slot et, si demandé, la miniature.

Pour des données génériques par participant, vous pouvez utiliser Set Part Data, Get Part Data, Remove Part Data, Clear Part Data et Has Part Data. Une partie possède un nom, une version, un contenu texte et un contenu binaire. Pour des données usuelles, préférez néanmoins des variables explicites dans votre Blueprint enfant : elles restent plus faciles à lire et maintenir.

4. Inscrire les participants

Un participant est l’objet qui possède des données à écrire dans une sauvegarde ou à réappliquer au chargement. Chaque participant est responsable de son propre enregistrement : ne centralisez pas cet appel dans un autre Blueprint.

Dans l’événement BeginPlay de chaque participant, récupérez une référence au subsystem. Depuis une référence au subsystem, appelez Add Participant en indiquant l’objet participant et sa participation aux sauvegardes de profil, manuelles et/ou automatiques.

Lorsqu’un participant n’est plus nécessaire, depuis une référence au subsystem, appelez Remove Participant. Utilisez Clear Participants ou Cleanup Participants depuis l’objet qui gère volontairement l’ensemble des participants. Ne créez jamais un nouveau contexte : réutilisez toujours celui reçu par l’événement. Les fonctions Is Saved Cache Complete, Is Loaded Cache Complete, Get Pending Participant Count et Is Operation In Progress permettent de diagnostiquer le flux.

5. Sauvegarder

Déclencher une sauvegarde

Depuis une référence au subsystem, appelez Save Slot en indiquant le type de slot et l’index lorsque le type est manuel. Pour une sauvegarde automatique, l’index est résolu par la rotation. L’option Capture Thumbnail enregistre une miniature JPEG de la vue courante avant l’écriture.

Save Slot déclenche l’opération générale : le subsystem prépare l’objet de sauvegarde puis délègue la sauvegarde des données à chaque participant inscrit pour ce type de slot. Une fois l’opération terminée, le subsystem appelle le dispatcher On Save Completed, avec le contexte, la réussite et une raison d’échec. Appelez Cancel Active Operation pour arrêter une opération en cours ; aucune sauvegarde annulée n’est écrite sur disque.

La sauvegarde des participants

Dans son BeginPlay, chaque participant concerné s’abonne au dispatcher On Save Requested. Lorsque ce dispatcher est déclenché, le participant reçoit le contexte et traite sa sauvegarde. Il écrit sa propre partie des données dans Save Game Object, puis appelle Set Part Saved depuis une référence au subsystem, avec le même contexte et Success à vrai. Le subsystem attend la réponse de tous les participants avant d’écrire le slot.

6. Charger

Déclencher un chargement

Depuis une référence au subsystem, appelez Load Slot avec la classe de sauvegarde configurée. Le subsystem retrouve le slot, peut ouvrir automatiquement le niveau mémorisé, puis délègue l’application des données aux participants après le chargement de la carte. Apply Pending Load est destiné à un flux personnalisé ou au débogage ; normalement il est appelé automatiquement.

Une fois l’opération terminée, le subsystem appelle le dispatcher On Load Completed, avec le contexte, la réussite et une raison d’échec.

Le chargement des participants

Dans son BeginPlay, chaque participant concerné s’abonne au dispatcher On Load Requested. Lorsque ce dispatcher est déclenché, le participant reçoit le contexte et traite son chargement. Il lit sa propre partie des données dans Save Game Object, les applique, puis appelle Set Part Loaded depuis une référence au subsystem avec le même contexte. Le chargement général ne se termine que lorsque tous les participants attendus ont répondu.

7. La logique projet

Introduction

ADS Project Save Behavior est un objet facultatif de logique propre au projet. Le subsystem le crée à partir de la classe configurée dans l’asset runtime, puis l’utilise pour notifier le cycle de vie, les opérations et les conversions de sauvegarde.

Créer la logique

Créez un Blueprint enfant de ADS Project Save Behavior, puis assignez cette classe dans le paramètre Project Save Behavior de DA_ADS_SaveSystemConfig. Implémentez seulement les événements nécessaires à votre projet. Les fonctions présentées ci-dessous sont des événements à override dans ce Blueprint enfant. Overridez seulement celles dont votre projet a besoin.

Les fonctions

Fonction	Description
`Initialize Behavior`	Appelée après la création de la logique projet. Elle reçoit le subsystem principal.
`Deinitialize Behavior`	Appelée avant la libération de la logique projet.
`Handle Save Operation Completed`	Appelée à la fin d’une sauvegarde, réussie ou non, avant le dispatcher public `On Save Completed`.
`Handle Load Operation Completed`	Appelée à la fin d’un chargement, réussi ou non, avant le dispatcher public `On Load Completed`.
`Handle Save Operation Failed`	Appelée lorsqu’une sauvegarde échoue ; la raison précise la cause de l’échec.
`Handle Load Operation Failed`	Appelée lorsqu’un chargement échoue ; la raison précise la cause de l’échec.
`Handle Need Convert`	Appelée lorsqu’une ancienne sauvegarde requiert la confirmation du projet avant conversion.
`Convert Save`	Convertit l’objet de sauvegarde entre deux versions. Cette fonction doit être synchrone et retourner vrai seulement si les données sont compatibles.
`Handle Convert Completed`	Appelée après une conversion réussie, échouée ou annulée, avant le dispatcher public `On Convert Completed`.
`Get ADS Save System`	Retourne le subsystem qui possède cette logique projet.

Gérer les versions des sauvegardes

Depuis une référence au subsystem, utilisez Check Save Version, Get Save Version From Slot ou Scan Saves Needing Conversion pour identifier les sauvegardes anciennes. Si une conversion est requise et que Auto Convert Without Confirmation est désactivé, la logique projet reçoit Handle Need Convert. Après confirmation par votre interface, appelez Continue Convert ; sinon appelez Cancel Convert.

Dans Convert Save, adaptez les données de l’objet de sauvegarde à la nouvelle version. Une sauvegarde créée avec une version plus récente que celle du projet ne peut pas être chargée.