Compétence Roblox hors ligne

Que fait Compétence Roblox hors ligne ?

Objectif

Utilisez cette compétence pour construire et réviser des systèmes fiables de données de joueurs Roblox et de progression calculée pour le temps passé hors jeu. Elle couvre l'architecture, l'implémentation, les tests, les opérations et la récupération. Il s'agit de conseils pour un agent IA, et non d'un framework de persistance déployé.

Conditions de déclenchement

Utilisez cette compétence lorsqu'une tâche implique :

• La sauvegarde, le chargement, la réinitialisation, la migration, la restauration ou l'inspection des données de joueur.
• DataStoreService, les DataStores standard, OrderedDataStores, MemoryStoreService, Open Cloud DataStores ou le Creator Hub Data Stores Manager.
• Les profils de joueurs, monnaies, inventaires, animaux de compagnie, améliorations, terrains, récoltes, machines, générateurs, classements et paramètres persistants.
• La propriété de session, le verrouillage de session, la sauvegarde automatique, les tentatives, les budgets de requête, la limitation, PlayerRemoving ou BindToClose.
• Les gains hors ligne, les revenus passifs, les minuteries agricoles, la production, les temps de recharge ou la progression après reconnexion.
• La perte de données, les écritures périmées, les récompenses dupliquées, les enregistrements corrompus, les reçus d'achat ou les migrations de schéma.

N'utilisez pas cette compétence pour des tâches non liées à l'interface utilisateur, la carte, l'animation, le combat ou le gameplay général, sauf si elles concernent des données persistantes de joueur.

Faits essentiels

1. DataStoreService fournit un stockage cloud persistant Roblox. Il est accessible par le code serveur et nécessite une connectivité aux services Roblox.
2. Le Creator Hub Data Stores Manager est un tableau de bord pour visualiser et gérer les données. Ce n'est pas un service Luau ni une API de base de données d'exécution.
3. MemoryStoreService fournit des données temporaires entre serveurs. Les entrées expirent et ce n'est pas un magasin de profils de joueurs permanent.
4. OrderedDataStore est destiné aux valeurs numériques ordonnées, couramment utilisées pour les scores de classement persistants. Ce n'est pas un profil de joueur complet.
5. La mémoire du serveur est la copie de travail volatile du serveur actif. Elle peut être perdue si le processus se termine avant une sauvegarde réussie.
6. La progression hors ligne signifie normalement un rattrapage limité calculé par le serveur après le retour d'un joueur. Cela ne signifie pas qu'un monde privé continue de simuler sans serveur actif.
7. Un client complètement déconnecté ne peut pas écrire dans les DataStores cloud Roblox. Ne promettez pas qu'une expérience Roblox publiée normale peut continuer à jouer et à sauvegarder dans le cloud sans connectivité.
8. Les appels à DataStoreService appartiennent à des Scripts serveur ou des ModuleScripts requis par des Scripts serveur. Ne sauvegardez jamais de données canoniques à partir d'un LocalScript.
9. UpdateAsync est une opération de lecture-modification-écriture. Elle n'implémente pas, à elle seule, le verrouillage de session.
10. Une requête réussie ne prouve pas que le profil retourné est structurellement valide ou compatible avec le schéma actuel.
11. Un échec de chargement n'est pas équivalent à une clé manquante ou à un nouveau joueur.
12. Ne prétendez jamais que le code a été testé dans Roblox Studio à moins que l'expérience cible n'ait été réellement exécutée dans Studio.

Workflow requis

1. Inspectez avant de modifier

Inspectez l'expérience réelle, les fichiers, les scripts, les ModuleScripts, les remotes, les packages et les intégrations Studio disponibles.

Identifiez :

• Chaque nom de DataStore, portée, constructeur de clé, préfixe de clé et adaptateur de stockage.
• Tous les appels GetAsync, SetAsync, UpdateAsync, IncrementAsync, RemoveAsync, version et listing.
• PlayerAdded, PlayerRemoving, BindToClose, les tâches de sauvegarde automatique, les gestionnaires de reçus d'achat et chaque scripteur pour chaque clé de profil.
• Le schéma actuel, le modèle par défaut, la version de migration et le point exact où un profil devient inscriptible.
• Si le projet utilise DataStoreService natif, une bibliothèque de profils tierce ou un wrapper personnalisé.
• Comment la propriété du profil, les tentatives, l'ordre des mêmes clés et l'arrêt sont actuellement gérés.
• Ce que l'utilisateur entend par hors ligne : rattrapage de temps d'absence, panne de service temporaire, test simulé ou jeu complètement déconnecté.

N'inférez pas l'architecture à partir d'une capture d'écran, d'un nom de dépôt ou de quelques fragments de code isolés. Préservez un système fonctionnel à moins que des preuves ne montrent une raison concrète de le modifier.

2. Vérifiez le comportement de Roblox

Utilisez references/official-roblox-sources.md comme index source. Revérifiez la documentation actuelle du Roblox Creator Hub pour les signatures d'API, les quotas, le comportement des services, la configuration et les dépréciations avant de coder.

Utilisez la documentation Roblox pour les garanties du moteur. Pour les packages tiers, inspectez la version exacte installée dans le projet cible et vérifiez l'API de ce package. N'inventez pas de méthodes de bibliothèque de mémoire ou d'exemples obsolètes.

3. Choisissez le stockage en fonction des besoins

Besoin	Point de départ correct
Progression durable du joueur	DataStore standard via DataStoreService ou une couche de profil maintenue
Classement numérique persistant	OrderedDataStore
État temporaire partagé entre serveurs	MemoryStoreService
Profil en direct du serveur actuel	Mémoire du serveur
Inspecter ou récupérer des entrées stockées	Creator Hub Data Stores Manager et API de version
Administration externe	Open Cloud via un backend de confiance
Progression pour le temps passé hors jeu	Profil persistant plus calcul de rattrapage côté serveur
Jeu déconnecté autonome complet	Non fourni par les DataStores cloud Roblox normaux

Préférez une clé de profil stable basée sur UserId lorsque le profil correspond et que ses champs nécessitent des mises à jour cohérentes. Ne divisez que pour une raison réelle de taille, de débit ou de modèle d'accès. Ne créez pas de DataStore par joueur.

4. Chargez et possédez les profils en toute sécurité

Un profil devient inscriptible uniquement après un chargement réussi et une propriété exclusive sous l'architecture choisie.

1. Commencez le chargement lorsque le serveur reçoit PlayerAdded.
2. Acquérez le verrou de profil/session en utilisant la couche de persistance existante.
3. Distinguez un résultat de clé manquante valide d'un échec réseau, d'une limitation, d'un conflit de session, de données malformées et d'un schéma non pris en charge.
4. Validez la charge utile et appliquez des migrations ordonnées et déterministes.
5. Publiez le profil comme prêt uniquement après la réussite de toutes les étapes requises.
6. Laissez le gameplay du serveur modifier la copie de travail appartenant au serveur via des méthodes contrôlées.
7. Arrêtez immédiatement les mutations si la bibliothèque de profils signale que la propriété a pris fin.

Ne créez jamais un profil par défaut inscriptible après un échec de chargement transitoire. Cela pourrait écraser les vraies données d'un joueur de retour.

5. Sauvegardez avec ordre et tentatives limitées

• Gérez les appels réseau avec pcall ou la couche d'erreur établie du projet.
• Ne réessayez que les erreurs transitoires, en utilisant un backoff exponentiel limité et une gigue aléatoire.
• Ne réessayez pas les arguments invalides ou les échecs permanents indéfiniment.
• Sérialisez les écritures par clé. Une ancienne tentative retardée ne doit pas écraser une sauvegarde réussie plus récente.
• Concevez les opérations réessayables pour être idempotentes car une réponse échouée peut laisser le résultat de l'écriture incertain.
• Utilisez UpdateAsync lorsque la nouvelle valeur dépend de l'état stocké actuel ou que des écritures simultanées sont possibles.
• SetAsync est valide pour un remplacement intentionnel de la valeur entière lorsque la propriété exclusive et la sémantique de remplacement sont établies. Ne l'appelez pas universellement interdit.
• Gardez les fonctions de transformation UpdateAsync déterministes, non bloquantes et exemptes d'effets secondaires externes. N'effectuez jamais d'attentes, d'appels HTTP, d'appels distants, d'octroi de reçus, d'analyses ou de création d'Instances à l'intérieur du callback.
• Un retour nil d'une transformation UpdateAsync annule l'écriture.
• Observez les budgets de requête actuels et le comportement de limitation. UpdateAsync consomme à la fois le budget de lecture et d'écriture.
• Échelonnez les sauvegardes automatiques. Ne sauvegardez pas à chaque image ou pour chaque événement de jeu minuscule.

6. Implémentez correctement la progression hors ligne

Lisez references/offline-progression.md et examples/offline-progress.luau avant de construire un système de récompense hors ligne.

Le serveur doit :

1. Charger et valider le profil.
2. Confirmer la propriété exclusive de la session.
3. Lire les horodatages enregistrés et les entrées de production appartenant au serveur.
4. Obtenir l'heure d'époque actuelle côté serveur.
5. Calculer le temps écoulé non négatif et le limiter à un maximum configuré.
6. Dériver les taux de production à partir de la propriété validée et des définitions côté serveur.
7. Appliquer l'efficacité, l'éligibilité et les plafonds de récompense hors ligne configurés.
8. Mettre à jour la récompense et son horodatage de simulation correspondant ensemble dans la copie de travail du profil.
9. Persister via la couche de profil active.
10. Répliquer les données de présentation au client.

Utilisez os.time() ou un autre horodatage d'époque côté serveur documenté pour les calculs entre sessions. N'utilisez jamais os.clock() comme horodatage d'époque. Ne faites jamais confiance à une horloge client, à une durée écoulée, à un taux de production, à un stade de récolte, à une liste d'actifs ou à un horodatage de dernière réclamation.

N'attribuez pas le même intervalle deux fois. Ne comptez pas deux fois la production en ligne. N'exécutez pas une boucle illimitée une fois par seconde hors ligne. Gérez délibérément les horodatages manquants, malformés, nuls, négatifs et futurs.

7. Protégez les données de développement et de production

• Utilisez une expérience de développement ou de staging publiée séparée pour les tests d'intégration DataStore en direct.
• Activez l'accès Studio aux services API uniquement sur cette expérience de test isolée.
• Roblox avertit que Studio peut accéder aux mêmes DataStores que l'application en direct. N'activez jamais ce paramètre sur la production pour des tests de routine.
• Utilisez des simulations (mocks) ou un adaptateur en mémoire pour les tests logiques déterministes. Une simulation n'est pas une sauvegarde de joueur réelle et n'est pas un stockage durable.
• Utilisez des comptes jetables et des clés de test.
• Ne supprimez, ne restaurez, ne renommez ni n'écrasez les données de production sans autorisation explicite de l'opérateur, identification précise de la cible et plan de récupération.
• Gardez les informations d'identification Open Cloud sur un backend de confiance. Ne les exposez jamais dans un LocalScript, un client, un dépôt public ou un contexte d'invite.

8. Vérifiez et rapportez honnêtement

Utilisez references/test-matrix.md. Couvrez les profils pour la première fois et de retour, les échecs de chargement, les conflits, les propriétaires obsolètes, l'ordre d'écriture, les tentatives, la sauvegarde automatique, l'arrêt, la récupération après crash, les charges utiles malformées, les migrations, les plafonds hors ligne, les réclamations répétées et les reçus en double.

Rapportez le niveau de validation avec précision :

• Révision statique
• Tests unitaires purs
• Tests d'intégration simulés/en mémoire
• Tests DataStore de staging publiés
• Tests d'exécution Roblox Studio
• Tests multi-serveurs/conflits de session

Ce sont des contrôles différents. Si Studio ou le staging n'était pas disponible, indiquez que la validation d'exécution reste en attente.

Interdictions non négociables

• Ne sauvegardez jamais de données canoniques de joueur à partir d'un LocalScript.
• Ne faites jamais confiance aux UserIds, soldes, prix, inventaires, propriétés, taux de récompense, horodatages, temps écoulé ou résultats d'achat fournis par le client.
• Ne traitez jamais une erreur de chargement transitoire comme un nouveau joueur.
• N'utilisez jamais MemoryStoreService ou la RAM du serveur comme stockage de profil permanent.
• N'utilisez jamais DataStore2 pour une nouvelle expérience. Roblox l'identifie actuellement comme une bibliothèque héritée.
• Ne bloquez jamais et n'effectuez jamais d'effets secondaires dans les callbacks UpdateAsync.
• Ne laissez jamais les écritures et les tentatives de même clé entrer en concurrence.
• Ne volez jamais de force une session active comme une tentative de réessai normale.
• N'écrivez jamais de valeurs brutes sur une clé gérée par une bibliothèque de profil.
• Ne prétendez jamais que UpdateAsync seul implémente un verrouillage de session.
• N'exécutez jamais de boucles de simulation hors ligne illimitées.
• N'exposez jamais les secrets Open Cloud.
• Ne modifiez jamais de manière destructive les données de production sans autorisation explicite et plan de récupération.
• Ne prétendez jamais avoir effectué des tests Studio qui n'ont pas eu lieu.

Carte de référence

Chargez uniquement les documents nécessaires à la tâche actuelle :

• references/architecture-and-services.md : rôles des services, DataStore Manager, Open Cloud et sélection de stockage.
• references/player-data-lifecycle.md : cycle de vie du profil, copies de travail en mémoire, état de préparation, départ et arrêt.
• references/session-locking-and-failures.md : propriété de session, UpdateAsync, ordre d'écriture, tentatives, limitation et résultats inconnus.
• references/offline-progression.md : récompenses d'inactivité, minuteries de récolte, générateurs, calcul des horodatages, plafonds et limitations de la déconnexion.
• references/studio-testing.md : accès API, staging, simulations et isolation de test sécurisée.
• references/schema-migrations-and-recovery.md : sérialisation, versions de schéma, migrations, historique des versions et récupération.
• references/security-and-purchases.md : remotes, autorité serveur, reçus, secrets Open Cloud et confidentialité des données.
• references/performance-and-limits.md : limites documentées, budgets, débit et réglage opérationnel.
• references/library-selection.md : DataStoreService natif, code de référence officiel et évaluation de packages tiers.
• references/game-patterns.md : profils, classements, terrains, systèmes inactifs, échanges et achats.
• references/test-matrix.md : scénarios de vérification.
• references/official-roblox-sources.md : liens vers les sources officielles du Roblox Creator Hub uniquement.
• examples/profile-template.luau : forme de profil illustrative.
• examples/offline-progress.luau : calcul pur et limité de récompense hors ligne.

Réponse d'implémentation requise

Pour les tâches d'implémentation et de débogage :

1. Résumez l'architecture existante trouvée dans le projet réel.
2. Expliquez le flux de données prévu et le plus petit changement sûr.
3. Listez les fichiers exacts à créer ou à modifier.
4. Fournissez un code complet et contextuel, pas des fragments déconnectés.
5. Expliquez les étapes de configuration, de staging et de migration de schéma.
6. Rapportez les tests réels et les contrôles d'exécution restants.
7. Énoncez les limites et les risques matériels sans inventer de garanties.

Respectez la langue et le style demandés par l'utilisateur. Préservez les systèmes fonctionnels. N'ajoutez pas de fonctionnalités non liées et ne remplacez pas une bibliothèque de persistance existante pour des raisons stylistiques.