Prise en main

Prérequis

• Unity 6 (développé et testé sur la version 6000.0.79f1, modèle URP).
• Package Addressables (com.unity.addressables) — requis. Le chargement par adresse est le chemin d'exécution, et le type AssetRef@Group a besoin d'Addressables.
  • Sans le package, l'asset compile quand même, car tout le code utilisant Addressables se trouve derrière un define de version SHEETFORGE_ADDRESSABLES.
  • Mais le pipeline — import · export · push · écriture en retour de création — reste verrouillé. Chaque point d'entrée affiche un avis d'installation, et la fenêtre Prise en main guide l'installation.

Installation d'Addressables

• Voie principale : lorsque vous importez l'asset depuis l'Asset Store, l'invite « Package Manager dependencies » apparaît avant la compilation — choisissez Install et Addressables s'installe en même temps.
• Filet de sécurité : si vous avez cliqué sur Skip (ou importé manuellement), le pipeline reste verrouillé et la fenêtre Prise en main vous guide pour l'installer depuis sa ligne d'état Addressables. Cette fenêtre s'exécute même sans Addressables, puisque l'Editor compile toujours.
  • La fenêtre d'amorçage sans dépendance SheetForge.Setup détecte elle aussi le package manquant au chargement de l'éditeur et affiche un avis une fois par session. Comme elle n'a aucune dépendance, elle continue de fonctionner même quand d'autres erreurs de compilation bloquent les assemblies principales.
• Il n'existe aucune installation programmatique en un clic : les règles de soumission de l'Asset Store limitent l'installation programmatique de packages, la fenêtre se contente donc de vous guider.
• L'avis reflète l'état d'installation réel. Il explique que le produit compile mais que ses fonctionnalités restent verrouillées tant que le package n'est pas installé, et vous oriente ensuite vers la fenêtre Prise en main. Vous pouvez la rouvrir à tout moment depuis Tools ▸ SheetForge ▸ Addressables Setup (ce menu survit même si les assemblies principales échouent à compiler pour une autre raison).

Mise à niveau depuis une version précédente

Un import de .unitypackage ajoute et met à jour des fichiers, mais ne les supprime jamais. Ainsi, un fichier qu'une version plus récente a retiré peut subsister dans Assets/SheetForge, en référençant encore une API qui n'existe plus. La compilation casse, et cela ressemble à une mise à niveau qui aurait cassé votre projet. Deux filets couvrent ce cas :

• Détection automatique. Au chargement de l'éditeur, l'amorçage SheetForge.Setup, sans dépendance, vérifie les chemins que ce produit a retirés. S'il en trouve, il propose de les supprimer — en listant d'abord chaque chemin dans la boîte de dialogue et sans rien toucher tant que vous n'avez pas approuvé. Il vit dans sa propre assembly précisément pour survivre aux erreurs de compilation qu'il existe pour corriger.
• Table rase. Pour une mise à niveau garantie propre, supprimez le dossier Assets/SheetForge existant, importez le nouveau package, puis exécutez Lancer l'import une fois pour reconstruire ce que la suppression a emporté avec elle. Les assets de paramètres et les SO bake (Assets/SheetForgeBaked) vivent en dehors de ce dossier et ne sont pas touchés, tout comme le code généré une fois qu'il se trouve à son emplacement par défaut Assets/SheetForgeGenerated. Si votre projet génère encore vers l'ancien emplacement interne au produit (Assets/SheetForge/Runtime/Generated), supprimer le dossier retire ce code et le réimport l'écrit à la place dans Assets/SheetForgeGenerated. C'est la façon prise en charge de déplacer un projet existant vers le nouvel emplacement. Ce qu'aucun réimport ne peut reconstruire, c'est tout ce que vous avez placé vous-même dans Assets/SheetForge — un asset de paramètres enregistré là, vos propres scripts de plugin, des fichiers de feuille — sortez donc cela d'abord.

Une limite mérite d'être énoncée clairement : le nettoyage automatique supprime les fichiers retirés propres à SheetForge, jamais les vôtres. Si votre propre code de plugin implémente un contrat qui a depuis été retiré, il doit être porté à la main. En bref :

• un générateur de graphe par onglet (IGraphShapeBuilder / GraphSpecBuilder) devient l'augmenteur du canevas d'enregistrements (IRecordCanvasAugmenter / CanvasAugmentBuilder), qui s'ajoute à la fermeture déjà construite par le canevas au lieu de construire toute l'image ;
• GraphMode a disparu, puisque la direction relève désormais du contrôle propre du canevas ;
• StudioGraphContext.ShapeId / ModeId compilent encore mais chacun renvoie une constante, donc toute comparaison AppliesTo par rapport à eux doit simplement être supprimée ;
• IAuthorableGraphShape.CreatableTabs reste inchangé.

Le tableau complet de ce que chaque contrat retiré est devenu se trouve dans la section Upgrade notes de CHANGELOG.md dans le dépôt source (le package de version ne l'inclut pas). Les membres retirés qui compilent encore sont marqués [Obsolete] plutôt que supprimés, si bien qu'une mise à niveau les fait apparaître comme des avertissements plutôt que de casser le build.

La fenêtre Prise en main (commencez ici)

Une fois Addressables installé, une fenêtre Prise en main s'ouvre automatiquement une fois par session d'éditeur — à chaque démarrage de l'Editor, mais pas de nouveau après un rechargement de domaine. Elle continue ainsi tant que son interrupteur « Afficher cette fenêtre au démarrage de l'Éditeur » est activé, ce qui est le cas par défaut.

C'est le point d'entrée recommandé. Vous pouvez la rouvrir à tout moment depuis Tools ▸ SheetForge ▸ Prise en main, et désactiver l'ouverture automatique avec cet interrupteur en bas (le choix est stocké par projet et par utilisateur).

Elle rassemble tout le flux de premier lancement en un seul endroit :

1. Tableau de bord d'état — un feu tricolore à trois lignes : Addressables installé, un asset de paramètres d'import actif, et premier import terminé. Chaque ligne affiche ✓ ou ✗, et tout ce qui nécessite encore une action dispose d'un bouton juste à côté (Nouvel asset de paramètres, ou Lancer l'import).
2. Paramètres d'import — liste chaque asset SheetForgeSettings avec un bouton radio pour choisir celui qui est actif, plus un bouton Nouvel asset de paramètres et un bouton Localiser pour retrouver chaque asset.
3. Exemples — un clic importe le package de démo du plugin ou de démo du cœur.
4. Démarrer à partir d'un modèle — choisissez l'un des deux modèles intégrés, choisissez « à partir de zéro » pour définir vous-même les champs, ou utilisez un modèle enregistré par un plugin. « Utiliser » ouvre le panneau de création du Data Studio, pré-rempli avec lui. Ceci nécessite un asset de paramètres actif avec une source modifiable ; si vous n'en avez pas encore, l'exigence est affichée.
   • Les modèles intégrés sont Exemple d'objet, qui utilise uniquement des types de base, et Enum definitions, qui présente une feuille @enum.
   • Les onglets de démo de compétence n'apparaissent ici que si un plugin de modèle tel que le Plugin Demo est présent.
5. Exécuter — Lancer l'import (utilise les paramètres actifs) et Ouvrir Data Studio.
6. Ouvrir le guide complet — un lien vers ce site de documentation.

Les sections ci-dessous détaillent chaque étape ; vous pouvez tout faire depuis la fenêtre, ou depuis les menus et la fenêtre Project comme décrit.

Encore plus rapide — glisser-déposer. Si vous avez déjà un dossier de fichiers de feuille, ouvrez le Data Studio et glissez ce dossier dessus — ou un seul fichier .tsv/.csv/.xlsx. Il propose de créer un asset de paramètres d'import qui lit ce dossier et de l'activer, sans configuration manuelle.

Ouvert sans paramètres actifs, le Studio affiche un panneau « Pour commencer » avec les mêmes boutons de création / import de démo / Prise en main, à la place d'un tableau vide.

Vérification de l'état. À tout moment, ouvrez le Data Studio et choisissez ⋯ ▸ Vérification de l'état dans la barre d'outils pour un diagnostic rapide sans réseau. Il indique ✓/✗ — chacun avec une correction suggérée — pour :

• les paramètres actifs ;
• l'accessibilité de la source (un dossier local qui existe, ou un id Google + un chemin de clé) ;
• l'existence d'une baseline d'import ;
• la fraîcheur du code généré, des SO bake et des addressables.

Langue de l'interface. La première fois que vous ouvrez un projet, SheetForge définit sa langue d'interface à partir de la langue système de votre Editor (neuf langues correspondent ; toute autre langue reste en anglais). Il ne remplace jamais une langue que vous avez déjà choisie ; changez-la à tout moment dans Preferences ▸ SheetForge (voir Localisation).

1. Choisir un asset de paramètres d'import

Créez-en un depuis le bouton Nouvel asset de paramètres de la fenêtre Prise en main, ou faites un clic droit dans la fenêtre Project → Create ▸ SheetForge ▸ Paramètres d'import (les libellés de menu suivent votre paramètre de langue — voir Localisation).

Vous pouvez conserver plusieurs assets de paramètres (par exemple, un par source de données) et choisir lequel est actif. Les menus, le Data Studio et les imports utilisent tous celui qui est actif. Le choix est stocké par projet et par utilisateur — un pointeur EditorPrefs, donc aucune pollution du contrôle de version et indépendant pour chaque coéquipier — et si l'asset actif est supprimé, le pointeur s'autorépare.

Avec un seul asset de paramètres, votre premier import le sélectionne automatiquement ; aucun choix explicite n'est nécessaire. Lorsque plusieurs existent, choisissez l'actif dans la fenêtre Prise en main ou depuis la liste déroulante qui apparaît dans la barre d'outils du Data Studio.

Configurez l'asset SheetForgeSettings :

L'inspecteur des paramètres n'affiche que les champs pertinents pour le mode source actuel — le mode Local masque les entrées Google ; le gidMap n'apparaît qu'en mode Google ExportUrl.

2. Sécurité de la clé de compte de service (source Google)

Vous utilisez une source LocalFile ? Passez cette section.

L'utilisation de Google Sheets en mode SheetsApi requiert une clé JSON de compte de service. Si vous n'en avez jamais créé, Configuration des feuilles Google explique tout le processus étape par étape. Conservez cette clé en dehors de Assets/ et en dehors de votre dépôt — ne la commitez jamais.

• Recommandé : définissez la variable d'environnement SHEETFORGE_SHEETS_KEY avec le chemin absolu de votre fichier de clé. Elle est prioritaire sur le champ de chemin de clé de l'asset de paramètres, ce qui permet à chaque développeur d'injecter sa propre clé locale sans laisser aucun chemin dans le dépôt.
• Si vous devez absolument renseigner un chemin dans le champ de paramètres, pointez-le en dehors du dépôt (par ex. C:/keys/service-account.json). Un fichier de clé sous Assets/ fuiterait dans les builds et les commits.

3. Lancer votre premier import

Tools ▸ SheetForge ▸ Data Studio, puis appuyez sur ↓ Pull from source dans la barre d'outils.

• Le pipeline récupère → valide → (en cas de succès) génère le code → bake. Les diagnostics s'affichent dans la console sous forme de rapport lisible par un humain, dans votre langue.
• Le premier import se termine automatiquement en deux étapes internes. Lorsqu'un schéma est nouveau ou modifié, l'import écrit le code généré, ce qui déclenche une recompilation/un rechargement de domaine. Il reprend automatiquement le bake après le rechargement. Une seule action utilisateur ; aucun redéclenchement manuel. Si la compilation échoue, la reprise automatique s'interrompt de façon sûre (plafond de 3 tentatives) et laisse une phrase exploitable dans la console.
• La validation recueille tous les diagnostics au moment de l'import (elle ne s'arrête jamais à la première erreur). Si ne serait-ce qu'une seule erreur existe, aucune sortie n'est produite (aucun assemblage partiel).
• L'import enregistre automatiquement la SO Database de chaque onglet dans le groupe Addressables SheetForge, à l'adresse "SheetForge/{tab}" — votre jeu charge les données via cette adresse stable (voir Concepts fondamentaux).

4. Charger des données dans votre jeu

using SheetForge.Runtime;
using UnityEngine.ResourceManagement.AsyncOperations;
 
AsyncOperationHandle<DefinitionDatabase> handle = SheetForgeDatabases.LoadAsync("Items");
await handle.Task;   // or coroutine yield / handle.WaitForCompletion()
if (handle.Status == AsyncOperationStatus.Succeeded)
{
    DefinitionDatabase db = handle.Result;
    // For strong typing: SheetForgeDatabases.LoadAsync<ItemsDatabase>("Items")
}
SheetForgeDatabases.Release(handle);   // Addressables is ref-counted — release what you load

L'assembly SheetForge.Runtime est autoReferenced, si bien que le code de jeu peut l'utiliser sans référence asmdef.

Ne référencez jamais directement une SO issue du bake depuis une scène. Les SO bake sont des caches non commités, propres à chaque machine — leurs GUID diffèrent d'une machine à l'autre et d'un bake à l'autre, si bien qu'une référence de scène directe devient Missing sur la machine d'un coéquipier. Le chargement par adresse absorbe ce problème par conception.

5. Essayer les scènes de démonstration

Deux exemples sont livrés comme des packages d'import sélectif. L'exemple de plugin SheetForge.PluginDemo (types personnalisés, enums, validateurs, arêtes) et un exemple sans plugin SheetForge.CoreDemo (types intégrés du Core uniquement) comprennent chacun une scène de démonstration « ouvrir et Play ».

Les imports de démo vivent à un seul endroit — la section Exemples de la fenêtre Prise en main — il n'existe donc pas de menu dédié pour eux.

• Démo du plugin : appuyez sur Importer le Plugin Demo dans Prise en main, ou double-cliquez sur Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage. L'un ou l'autre le restaure sous Assets/SheetForge.PluginDemo/…. Scène : Demo/PluginDemo.unity (menu Tools ▸ SheetForge ▸ Open Plugin Demo Scene, ajouté par l'exemple lui-même). Elle charge les bases de données d'exemple par adresse et affiche une compétence assemblée à partir de données de la feuille (dégâts totaux de la boule de feu = Damage 10 + DamageOverTime 3×3 = 19).
• Démo du cœur seul : appuyez sur Importer le Core Demo dans Prise en main, ou double-cliquez sur Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage. Cela le restaure sous Assets/SheetForge.CoreDemo/…. Scène : Demo/CoreDemo.unity (menu Tools ▸ SheetForge ▸ Open Core Demo Scene). Elle affiche des équipements assemblés à partir de références d'item en utilisant uniquement les types intégrés du Core. La démo contient aussi une feuille de localisation (ExampleStrings) dont les clés sont référencées par les items via des cellules LocRef — voir Feuilles de localisation.

(Les libellés terminaux de ces menus d'exemple restent en anglais, car ils se situent en dehors du pipeline de menus localisés du Core.)

Chaque package de démo intègre un asset de paramètres préconfiguré. Lorsque vous importez un package de démo, SheetForge active automatiquement cet asset de paramètres intégré si vous n'avez pas encore de paramètres actifs à vous. Si vous en avez déjà un, il ouvre la fenêtre Prise en main pour suggérer de changer, au lieu d'écraser silencieusement votre choix. Le flux de démo se résume donc à : importer le package → (paramètres activés automatiquement) → Lancer l'import → Play — aucune création manuelle de paramètres.

Une démo ne fonctionne qu'après avoir exécuté un import sur votre machine — les adresses Addressables qu'elle charge n'existent qu'après que l'import a été exécuté une fois (l'asset de groupe Addressables est un cache non commité et autoréparateur). Avant cela, la scène de démo affiche un message de guidage au lieu d'échouer.

Pour terminer une démo (après avoir importé le package d'exemple ci-dessus) :

1. Assurez-vous que l'asset de paramètres intégré à la démo est actif (la fenêtre Prise en main l'indique, ou l'import l'a activé automatiquement). Il utilise source = LocalFile, dossier local = le dossier DemoSheets de l'exemple, et l'espace de noms par défaut SheetForge.Generated, si bien que le réimport régénère les types commités sur place.
2. Aucune action nécessaire pour la référence de script de la démo du plugin. L'onglet ExampleEffects comprend un exemple AssetRef@Scripts. L'exemple enregistre lui-même DemoScripts/special_effect.lua.txt sous l'adresse special_effect dans un groupe Addressables Scripts, de façon idempotente, si bien que le premier import passe la validation de référence. Seulement s'il journalise un avertissement indiquant qu'il n'a pas pu le faire (un asset manquant, par exemple), vous devez ajouter cette entrée à la main — ou supprimer la ligne si vous ne voulez pas de l'exemple Addressables.
3. Appuyez sur ↓ Pull from source dans Tools ▸ SheetForge ▸ Data Studio une fois (ou le bouton Lancer l'import dans Prise en main), puis ouvrez la scène de démo et appuyez sur Play.

6. Résumé du flux de travail en équipe

• Les SO bake (Assets/SheetForgeBaked) sont un cache propre à chaque machine. Ajoutez-les au gitignore ; après un clone, chaque coéquipier exécute Lancer l'import une fois.
• Le code généré (Assets/SheetForgeGenerated) est le code source propre de votre projet, et la recommandation est de le committer. Un clone tout neuf compile alors avant que quiconque ait lancé un import, et les changements de schéma apparaissent dans la revue de code. C'est une sortie déterministe, si bien que l'import d'un coéquipier produit les mêmes octets et ne crée aucun bruit. Le mettre au gitignore fonctionne aussi comme alternative ; Lancer l'import après le clone est alors ce qui restaure la compilation.
• Un hook de fraîcheur pré-build vérifie, pour chaque type Database généré et commité, que (i) la SO bake existe, (ii) l'empreinte de schéma correspond à la baseline, et (iii) l'enregistrement Addressables existe. Si quoi que ce soit échoue, le build est interrompu avec une phrase exploitable, de sorte qu'une machine clonée ou de CI ne puisse jamais livrer silencieusement un cache vide.

Pages associées

• Concepts fondamentaux — pourquoi la feuille est canonique et quelles sont les étapes du pipeline
• Syntaxe des feuilles — comment écrire votre première feuille
• Sources, export et push — détails de configuration de Google
• FAQ et dépannage — problèmes de premier lancement