Utiliser des données persistantes vous permet de suivre et d'enregistrer des données par joueur d'une session de jeu à l'autre, donnant ainsi accès à une multitude de modes de jeu progressifs qui laissent les joueurs libres de quitter la partie et d'y revenir afin de poursuivre leurs objectifs ou de constater un état de jeu identique à celui du moment de leur départ.
Les données persistantes reposent sur le stockage des données de chaque joueur, telles que leur profil ou leurs statistiques, dans Verse. Ces données peuvent alors être mises à jour autant de fois qu'elles sont modifiées. Ces données étant persistantes, elles resteront d'une session de jeu à l'autre et seront disponibles chaque fois que le joueur est en ligne dans le jeu.
Les jeux de survie, les tycoons, les jeux de rôle et les roguelites figurent parmi les types de jeux qui utilisent des données persistantes. Dans ces jeux, les joueurs doivent acquérir des objets pour atteindre des objectifs à long terme.
Utilisez des données persistables dans vos scripts Verse pour stocker les informations enregistrées par joueur ou par module. Implémentez des données persistantes dans les modes de jeu où vous souhaitez voir revenir les joueurs afin qu'ils poursuivent leur progression de manière continue.
Pour vous entraîner à implémenter la persistance, consultez le tutoriel sur les statistiques persistantes des joueurs.
Bien que des données persistables puissent être créées et utilisées dans Verse, certains appareils du mode Créatif possèdent des fonctionnalités de base prenant en charge les données persistables. Pour en savoir plus, consultez la rubrique Appareils de persistance.
Signification de la persistance dans Verse
Dans Verse, une variable définie dans un module est globale pour toute instance de jeu en cours d'exécution dont la variable se trouve dans l'étendue. À l'exception des variables à étendue de module associées à la session, une variable à étendue de module requiert une persistance et le stockage des données au-delà de la partie en cours. C'est pourquoi il existe des restrictions sur les types pouvant être utilisés dans l'étendue de module.
Actuellement, vous pouvez utiliser les types suivants en étendue de module :
| Types d'étendue de module autorisés | Définition | Restrictions |
|---|---|---|
| Vous pouvez stocker et consulter les données représentées par | Les données ne sont stockées que pendant la session en cours et ne persistent pas au cours des manches suivantes. |
| Les données de tout type persistable représenté par | L'accès aux données persistantes du joueur n'est autorisé que lorsque le joueur se trouve dans la partie en cours. |
Si un joueur quitte une partie ou ne se trouve pas dans la session en cours, vous ne pouvez plus stocker ses données ni y accéder pendant cette session de jeu. Si le joueur revient au même jeu ou y rejoue, vous pouvez alors accéder à ses données et les mettre à jour.
Créer des données persistables dans Verse
Pour chaque joueur, vous pouvez créer des données persistantes qui peuvent être en permanence mises à jour, stockées et rappelées chaque fois qu'il se reconnecte au jeu. Pendant le matchmaking, le jeu vérifiera si des données persistantes le concernant ont été enregistrées. Si le joueur dispose de données persistantes, elles sont chargées et mises à la disposition des scripts Verse.
Si le joueur dispose de données persistantes pour une île et que le chargement des données échoue, il ne pourra pas rejoindre l'île. Cette mesure de protection évite d'écraser des données persistantes en cas d'échec du chargement.
Pour créer des données persistables dans votre code Verse, définissez une variable weak_map globale qui utilise le type de joueur comme clé et un type persistable comme valeur. Voir Types persistables pour obtenir la liste complète des types qui peuvent être persistables.
Dans l'exemple suivant, la variable globale "weak_map" MySavedPlayerData utilise le type de joueur comme clé et un entier comme valeur. Le stockage d'une valeur entière pour un joueur dans cette variable signifie que les données persisteront d'une session de jeu à l'autre et pourront être consultées et mises à jour à tout moment lorsque le joueur a rejoint le jeu.
var MySavedPlayerData:weak_map(player, int) = map{}
Lorsque vous aurez défini vos données persistantes, vous devrez initialiser les données pour chaque joueur. Pour cela, vérifiez qu'aucune donnée n'est déjà stockée pour ce joueur, puis ajoutez le joueur et une valeur initiale au weak_map.
# Runs when the device is started in a running game
OnBegin<override>()<suspends>:void =
InitialSavedPlayerData:int = 0
Players := GetPlayspace().GetPlayers()
for (Player : Players):
if:
not MySavedPlayerData[Player]
set MySavedPlayerData[Player] = InitialSavedPlayerDataDans l'exemple précédent, une seule valeur entière a été stockée, mais vous pouvez utiliser d'autres types, tels que des classes et des matrices, pour stocker d'autres données pour chaque joueur dans le weak_map. Consultez la rubrique Types persistables pour obtenir la liste complète des types que vous pouvez utiliser.
L'exemple Verse suivant illustre la définition d'un profil de joueur personnalisé dans une classe que vous pouvez stocker, mettre à jour et laisser à la disposition ultérieure d'un joueur. La classe player_profile_data stocke les informations d'un joueur, telles que son EXP acquise, son rang et les quêtes qu'il a accomplies.
player_profile_data := class<final><persistable>:
Version:int = 0
Class:player_class = player_class.Villager
XP:int = 0
Rank:int = 0
CompletedQuestCount:int = 0
QuestHistory:[]string = array{}
var PlayerProfileDataMap:weak_map(player, player_profile_data) = map{}La quantité de données que vous stockez par joueur et par île est concernée par une limite. Chaque fois que vous enregistrez des données, nous vous recommandons de vérifier l'incidence de vos mises à jour sur la taille totale à l'aide de la fonction "FitsInPlayerMap". Pour en savoir plus, consultez la rubrique S'assurer du respect des limites.
Maintenant que vous savez créer vos propres données persistables et les initialiser pour chaque joueur, prenez le temps de consulter les meilleures pratiques pour connaître les méthodes d'utilisation des données persistables recommandées dans Verse.
Modifier des données entre des versions publiées de votre île
Une fois la version actuelle de votre île publiée, lorsque vous effectuez des mises à jour des données persistantes, toutes les données stockées dans une version précédente de l'île doivent être prises en charge dans ses versions ultérieures.
Pour cela, une vérification de rétrocompatibilité est exécutée dans l'UEFN et, si le code Verse n'est plus compatible avec la version actuellement publiée, la compilation échoue. Cette vérification de rétrocompatibilité est exécutée chaque fois que vous :
Cliquez sur Lancer la session dans la barre d'outils de l'UEFN.
Cliquez sur Envoyer les modifications ou Envoyer les modifications Verse dans la barre d'outils de l'UEFN.
Publier votre île pour la première fois.
Activer une nouvelle version publique de votre île.
Cette vérification de rétrocompatibilité consiste principalement à contrôler le type de valeur de la variable à étendue de module weak_map. Les types simples, tels que les entiers, ne peuvent pas être modifiés une fois l'île publiée. Cela concerne également les structs, qui ne vous permettent pas de modifier la définition de structure après la publication de l'île.
Le seul type persistable auquel vous pouvez actuellement ajouter des données après publication de votre île est le type class, à condition que les nouveaux champs comportent des valeurs par défaut. Cela signifie que le chargement de données enregistrées à partir d'une version précédente inclura les nouveaux champs et leurs valeurs par défaut. Pour en savoir plus, consultez les meilleures pratiques d'utilisation des classes comme données persistables.
Réinitialiser les données persistables de votre île
Si vous devez forcer la réinitialisation des données persistantes de votre île, vous pouvez attribuer une valeur par défaut aux données persistables du weak_map dans Verse pour le moment où le joueur rejoint l'île.
Pour déterminer si les données du joueur ont déjà été réinitialisées, vous pouvez inclure une valeur de version pour votre classe et la mettre à jour des nouvelles modifications dans le cadre de vos données persistantes. Il s'agit de l'une des meilleures pratiques répertoriées ci-dessous, mais assurez-vous de consulter aussi les autres !
Types persistables dans Verse
Vous pouvez utiliser les types persistables suivants dans votre variable à étendue de module weak_map :
| Type | Description |
|---|---|
Une matrice est persistable si le type d'éléments qu'elle contient l'est. | |
Les valeurs de caractères sont persistables. | |
Les valeurs de caractères sont persistables. | |
Une classe est persistante dans les cas suivants :
| |
Les valeurs de couleur sont persistables. | |
Une enum est persistable lorsqu'elle est définie avec le spécificateur persistable. | |
Les valeurs à virgule flottante sont persistables. | |
Les valeurs entières sont persistables. | |
Les valeurs de logique sont persistables. | |
Un mappage est persistant si les types clé et valeur sont persistants. | |
Une option est persistable si sa valeur l'est. | |
Une structure est persistante dans les cas suivants :
Une fois que vous avez publié votre île, vous ne pouvez plus modifier une structure persistante. C'est pourquoi nous recommandons d'utiliser des structures capables de persister uniquement lorsqu'il est sûr que le schéma est constant. tuple | |
Un tuple est persistable si chaque type d'élément l'est. | |
Les valeurs Vector2 sont persistables. | |
Les valeurs Vector2i sont persistables. | |
Les valeurs Vector3 sont persistables. |
Tester avec des données persistantes
Pour tester le comportement des données persistantes avant de publier la dernière version de votre île, vous pouvez définir le comportement suivant de votre appareil Paramètres de l'île, à la fois pour le paramètre Comportement de persistance : Session de test et le paramètre Comportement de persistance : Modifier la session :
| Comportement des données persistables | Description |
|---|---|
Importer à partir de données en direct | Importez les données de session à partir de données en direct disponibles, le cas échéant. Pour cela, l'île doit avoir été publiée en direct, et le joueur doit avoir joué sur la version en direct de l'île. Si des données en direct sont disponibles, les données de session de test seront alimentées par une copie des données en direct. Cela peut être très utile pour tester les problèmes liés aux données persistantes dus aux modifications apportées à la logique de votre île. |
Simuler un nouvel utilisateur | Fait démarrer le joueur avec de nouvelles données persistables, comme s'il jouait sur l'île pour la première fois. |
Les comportements Importer à partir de données en direct et Simuler un nouvel utilisateur fonctionnent à la fois pour les appareils de persistance Verse et les appareils de persistance tels que le point de sauvegarde et le traqueur. Simuler un nouvel utilisateur exécutera la session avec des données vides pour la persistance Verse et les appareils de persistance sans modifier les données en direct, et Importer à partir de données en direct chargera les données persistantes des deux si des données en direct sont disponibles.
Les paramètres de comportement des données de persistance s'appliquent lorsque vous effectuez les tests. Il existe deux scénarios différents dans lesquels vous pouvez effectuer des tests avec des données persistantes :
Modifier la session : les paramètres de comportement des données de persistance sont appliqués lorsque vous lancez une session à partir de l'UEFN. Cela signifie que les données persistantes peuvent subsister sur plusieurs jeux au cours d'une même session. Si vous quittez la session et en relancez une nouvelle, les données persistantes seront réinitialisées et les paramètres de comportement des données de persistance seront réappliqués.
Session de test : les paramètres de comportement des données de persistance sont appliqués lorsque vous configurez un test dans le portail de créateur lorsqu'un testeur se connecte via un code de test ou un code de liaison privé. Les paramètres de comportement des données de persistance s'appliquent uniquement la première fois que le joueur se connecte. Lorsque le joueur quitte et rejoint le test, ses données persistent d'une session à l'autre et les paramètres de comportement des données de persistance ne sont pas réappliqués. Pour réinitialiser les données persistantes, vous devrez créer un autre code de liaison de test.
Pour les mises à jour d'îles ayant une incidence sur la gestion et la mise à jour des données persistantes, nous vous recommandons de tester dans les deux scénarios, à la fois en lançant une session à partir de l'UEFN et en effectuant un test qui utilise un code de liaison. Assurez-vous de tester les modifications que vous apportez aux données persistantes avec à la fois des données en direct et de nouvelles données utilisateur simulées. Vous veillez ainsi à ce que vos mises à jour fonctionnent à la fois pour les joueurs actuels de votre île et pour les nouveaux joueurs.
Effets de la publication de nouvelles versions de votre île
Une fois votre île publiée, un enregistrement persistable est créé pour les joueurs lorsque leurs données sont stockées dans le weak_map. Ces données seront ensuite stockées et chargées lors des visites suivantes sur votre île.
Si de nouvelles versions de votre île sont publiées, les données persistantes y seront automatiquement intégrées. Consultez la page Modifier des données entre des versions publiées de votre île pour en savoir plus.
Effets de la restauration d'une version antérieure de votre île publiée
Si vous restaurez une version antérieure de votre île via le portail de créateur, les données persistantes de tous les utilisateurs sont réinitialisées.
Pour le moment, il n'existe aucun moyen d'informer les joueurs que leurs données ont été affectées par une restauration.
Cela entraînera la perte des mises à jour récentes des données des joueurs, voire la réinitialisation complète des données des joueurs. Cela est vrai même si la restauration n'inclut pas en interne de modifications de la logique qui affecteraient les données persistantes.
En raison de son impact sur les données persistantes, nous recommandons d'utiliser la fonctionnalité de restauration uniquement en dernier recours.
Limitations
L'utilisation de données persistantes dans Verse présente les limitations suivantes.
Taille maximale des objets persistants
La quantité de données pouvant être stockées dans un weak_map par joueur est limitée.
Un registre weak_map est la quantité totale de données associées à un même élément weak_map. Un registre weak_map est limité à une taille de données maximale de 256 kilo-octets (Ko) par joueur.
Lorsqu'une valeur `weak_map` est enregistrée, la quantité totale de mémoire requise pour enregistrer les données est calculée.
Par exemple, les données suivantes dépasseraient les limites de 256 Ko :
Environ 24 000 valeurs
floatouint.Environ 200 000 caractères de texte. Cela équivaut à environ 60 pages de texte d'un roman.
Si vous tentez d'enregistrer des données supérieures à 256 Ko pour l'enregistrement d'un joueur, l'enregistrement échouera et vous recevrez une erreur d'exécution Verse.
Pour éviter tout échec d'enregistrement, utilisez la fonction d'aide Verse FitsInPlayerMap. La fonction FitsInPlayerMap effectue une copie du registre à enregistrer et vérifie sa taille. Si l'enregistrement peut être sauvegardé, l'appel de fonction réussira. Sinon, si l'enregistrement est trop volumineux, il échouera.
La fonction FitsInPlayerMap est particulièrement utile lorsque vous travaillez avec une matrice ou un mappage dynamique de données et que vous y ajoutez des éléments. La mise à jour d'une valeur int, float ou logic qui se trouvait déjà dans le registre persistable ne modifiera pas sa taille.
Nombre maximal de mappages faibles de joueur persistants par île
Une île peut avoir jusqu'à quatre variables persistantes, c'est-à-dire quatre variables weak_map dont player est le type de clé. Le compilateur Verse impose cette condition.
Mappage faible requis avec un type de classe
La valeur weak_map d'au moins une variable persistante doit être une classe si la limite max de variables persistantes a été atteinte. Des données peuvent ainsi être ajoutées ultérieurement aux variables tout en respectant la rétrocompatibilité lors des publications ultérieures de l'île.