FAQ et dépannage

Des réponses organisées par symptôme. Chaque erreur d'import porte aussi sa propre phrase où/quoi/pourquoi/comment dans le rapport de la console — commencez par là.

Configuration et premier lancement

« J'ai importé l'asset sans Addressables — est-ce que ça compile ? Pourquoi l'import est-il verrouillé ? »

L'asset compile sans Addressables (le code utilisant Addressables est protégé derrière un define de version SHEETFORGE_ADDRESSABLES). Le chargement par adresse et le type AssetRef@Group ont bel et bien besoin de com.unity.addressables, si bien que tout le pipeline (import · export · push · écriture en retour) est verrouillé tant que vous ne l'installez pas — chaque point d'entrée affiche un avis d'installation et s'arrête (aucune exécution partielle). Installez com.unity.addressables via Package Manager ; la ligne Addressables de la fenêtre Prise en main a un bouton Open Package Manager, et — parce que l'Editor compile sans le package — cette fenêtre s'exécute normalement au lieu d'être bloquée par le Safe Mode. Si des erreurs de compilation subsistent après l'installation, elles proviennent d'un autre code du projet — SheetForge compile aussi bien avec que sans le package.

« J'ai mis à jour vers une version plus récente et maintenant le projet ne compile plus. »

Un import de .unitypackage ajoute et met à jour des fichiers mais ne les supprime jamais, si bien qu'un fichier que ce produit a retiré dans une version ultérieure peut subsister et référencer une API qui n'existe plus. Au chargement de l'éditeur, l'amorçage SheetForge.Setup, sans dépendance, détecte ces chemins retirés connus et propose de les supprimer, en listant chaque chemin avant de rien toucher — approuvez la boîte de dialogue et la compilation se rétablit. Comme il vit dans sa propre assembly, il continue de fonctionner pendant que les assemblies principales échouent. Pour sauter complètement l'invite, supprimez le dossier Assets/SheetForge avant d'importer le nouveau package. Ce que cela ne couvre pas, c'est votre propre code écrit contre un contrat qui a depuis été retiré — portez-le à la main à l'aide du tableau Upgrade notes dans CHANGELOG.md dans le dépôt source (le package de version ne l'inclut pas) — Prise en main résume ce qu'il indique.

« Créer une feuille n'affiche que les modèles intégrés — où est le modèle de démo de compétences ? / Comment ajouter le mien ? »

La liste intégrée Créer une feuille propose deux modèles — Exemple d'objet (types de base uniquement) et Enum definitions, qui met en page une feuille @enum — plus « à partir de zéro ». Les modèles de domaine qui ont besoin d'un plugin (comme la démo de compétences) sont enregistrés par ce plugin, si bien qu'ils n'apparaissent que lorsque le plugin est présent. Importez le package de démo du plugin et son modèle Skill demo apparaît. Pour fournir le vôtre, implémentez ISheetForgeTemplatePlugin — voir Création de plugins §4.6.

« Par où commencer ? / Une fenêtre s'ouvre sans arrêt quand j'ouvre l'Editor. »

C'est la fenêtre Prise en main. Elle s'ouvre automatiquement au premier chargement de l'Editor et c'est le point d'entrée recommandé — l'état d'Addressables, le choix de l'asset de paramètres actif, l'import d'un exemple, et l'exécution de votre premier import, tout en un seul endroit. Désactivez l'ouverture automatique avec l'interrupteur « Afficher cette fenêtre au démarrage de l'Éditeur » en bas, et rouvrez-la à tout moment depuis Tools ▸ SheetForge ▸ Prise en main.

« J'ai importé un package de démo mais rien ne se passe — il n'y a ni asset de paramètres ni groupe addressable. »

Chaque package de démo intègre un asset de paramètres préconfiguré, et importer le package l'active automatiquement (seulement lorsque vous n'avez pas encore de paramètres actifs à vous — si vous en avez déjà un, la fenêtre Prise en main s'ouvre pour suggérer de changer, au lieu de modifier silencieusement votre configuration). Appuyez ensuite sur ↓ Pull from source dans Tools ▸ SheetForge ▸ Data Studio une fois : cela crée automatiquement le groupe addressable et les adresses par onglet. Flux : importer le package → (paramètres activés automatiquement) → Lancer l'import → Play.

« La scène de démonstration affiche juste un message texte au lieu de la démo. »

La démo charge par adresse Addressables, et ces adresses n'existent qu'après un import sur votre machine (l'asset de groupe est un cache non commité et autoréparateur). Importez le package de démo (ses paramètres s'activent automatiquement) et exécutez Lancer l'import une fois — voir Prise en main §5. (Les types commités des démos utilisent l'espace de noms par défaut SheetForge.Generated, si bien qu'aucun réglage de generatedNamespace n'est nécessaire — le réimport les régénère sur place.)

« Le premier import de la démo du plugin échoue avec `UnknownAssetGroup 'Scripts'`. »

La démo du plugin a une colonne script typée List<AssetRef@Scripts>, qui a besoin d'un groupe Addressables nommé Scripts. Les groupes Addressables sont propres à chaque machine (non commités), si bien qu'une démo fraîchement importée ne l'a pas encore. La démo configure automatiquement ce groupe à l'import (PluginDemoAddressableSetup, déclenché au rechargement de domaine et quand vous ouvrez la scène de démo), si bien qu'un import normal fonctionne simplement. Si vous voyez encore l'erreur, rouvrez la scène de démo (Tools ▸ SheetForge ▸ Open Plugin Demo Scene) pour déclencher la configuration, puis réimportez. Cela ne s'applique qu'à la démo du plugin — vos propres groupes AssetRef@… sont ceux que vous enregistrez vous-même.

« Quel asset de paramètres est utilisé quand j'en ai plusieurs ? »

Celui qui est actif. Les menus, le Data Studio et les imports utilisent tous l'asset de paramètres actif. Choisissez-le dans la fenêtre Prise en main ou dans la liste déroulante de la barre d'outils du Data Studio (affichée seulement lorsque plusieurs existent). Avec un seul asset de paramètres, le premier import le sélectionne automatiquement. Le choix est stocké par projet et par utilisateur (un pointeur EditorPrefs — aucune pollution du contrôle de version), et s'autorépare si l'asset actif est supprimé.

« J'ai déjà un dossier de feuilles — quel est le moyen le plus rapide d'y pointer SheetForge ? »

Ouvrez le Data Studio et glissez le 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 saisie manuelle de champ. Si vous avez déjà des paramètres actifs, la boîte de dialogue le signale et propose de basculer.

« Comment vérifier que mon projet est correctement configuré / pourquoi l'import ne se lance pas ? »

Choisissez ⋯ ▸ Vérification de l'état dans la barre d'outils du Data Studio. Il indique ✓/✗ 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é de compte de service, sans aucun appel réseau ;
la baseline d'import ;
la fraîcheur du code généré/du bake/des addressables.

Les résultats vont dans la Console plus une boîte de dialogue récapitulative.

« Les menus et l'interface se sont ouverts dans une langue que je n'ai pas choisie. »

À la première ouverture d'un projet, SheetForge définit sa langue d'interface à partir de la langue système de votre Editor (neuf langues correspondent, sinon anglais). Il ne remplace jamais une langue que vous avez définie vous-même. Changez-la à tout moment dans Preferences ▸ SheetForge — voir Localisation. (Changer la langue déclenche une courte recompilation unique car les libellés de menu sont régénérés.)

« J'ai cloné le dépôt et mes références de scène vers des SO bake sont Missing. »

Attendu : les SO bake sont des caches propres à chaque machine, avec des GUID propres à chaque machine. Ne les référencez jamais directement depuis des scènes — chargez par adresse (SheetForgeDatabases.LoadAsync("Tab")). Lancez un import une fois pour reconstruire votre cache local.

« Mon build a été interrompu avec un message de SheetForge. »

C'est le hook de fraîcheur pré-build qui vous protège de la livraison d'un cache vide/périmé. Faites ce que dit la phrase — appuyez sur ↓ Pull from source dans Tools ▸ SheetForge ▸ Data Studio — et relancez le build.

Import et validation

« L'import s'est exécuté, a trouvé des erreurs, et n'a rien produit du tout. »

C'est voulu : une erreur ⇒ aucune sortie (aucun assemblage partiel). Le rapport liste tous les problèmes avec leurs coordonnées et des corrections suggérées — corrigez-les en une seule passe et réimportez. Vous ne perdez jamais de travail à cause de cela ; la feuille reste intacte.

« Puis-je aller directement à la cellule concernée par une erreur ? »

Oui. Chaque erreur dans le rapport Console lisible par un humain a un lien cliquable « Open in Data Studio » ; cliquer dessus ouvre le Data Studio, bascule sur cet onglet et met en surbrillance cette cellule (seulement l'onglet pour les erreurs de niveau fichier/onglet). La ligne de coordonnées lisible par une machine est inchangée, donc le scraping CI/logs n'est pas affecté.

« L'import a écrit du code, a recompilé… est-ce que c'est terminé ? »

Oui — lorsqu'un schéma est nouveau/modifié, l'import se déroule en interne en deux étapes (codegen → compilation/rechargement → bake), et le bake reprend automatiquement après le rechargement. Surveillez la console pour le rapport final. Si votre code de jeu ne compile plus (par ex. après un renommage de colonne), la chaîne s'interrompt de façon sûre avec une phrase exploitable ; corrigez votre code et importez à nouveau.

« Erreur de cellule vide, mais je voulais que la cellule soit optionnelle. »

Les types non marqués sont obligatoires (garde-fou anti-contamination silencieuse). Pour rendre une cellule optionnelle :

déclarez float? — valeur par défaut du type ;
déclarez int=1 — valeur par défaut explicite ;
ou utilisez List<T>, où une cellule vide est une liste vide.

Voir Syntaxe des feuilles.

« `1.5` s'importe bien, mais `1,5` provoque une erreur. »

C'est voulu : les nombres sont indépendants de la locale — toujours un . décimal. Les décimales à virgule, NaN, et Infinity sont bloqués à l'entrée.

« L'import est soudainement devenu très lent. »

Le temps d'import est linéaire par rapport à la taille de vos données (50k lignes × 20 colonnes ≈ 628 ms dans l'éditeur), et il reste linéaire même quand de nombreuses références se cassent d'un coup — la recherche de correspondance la plus proche est budgétée par champ et préfiltrée par longueur (≈ 45 ms pour 4,000 références cassées, en headless). Si un import prend soudain beaucoup plus de temps que ça, c'est la taille de la feuille qu'il faut regarder, pas le nombre d'erreurs.

« Erreur de marqueur inconnu / type inconnu, avec une suggestion "vouliez-vous dire". »

Les fautes de frappe dans les noms @marker, les noms de type, ou les membres d'enum sont des erreurs assorties de suggestions de correspondance la plus proche — appliquez la suggestion. Un @ inconnu sur un nom de type non enregistré est aussi une erreur (sécurité contre les fautes de frappe pour les références de style RecordId@Tab).

Google Sheets

« L'import Google échoue avec `PERMISSION_DENIED` (403). »

La feuille de calcul n'est pas partagée avec l'adresse client_email du compte de service — la clé seule n'accorde rien. Ouvrez la clé JSON, copiez client_email, et partagez la feuille avec cette adresse (Viewer pour l'import, Editor pour le Push). Le guide complet se trouve dans Configuration des feuilles Google.

« Push dit qu'il nécessite SheetsApi. »

Vous êtes en mode ExportUrl, qui est en lecture seule (sans authentification). Toute écriture en retour nécessite le mode SheetsApi avec une clé de compte de service. Voir Sources, export et push. Créer le compte de service et la clé est expliqué dans Configuration des feuilles Google.

« L'import ExportUrl échoue en demandant une gid map. »

Requis : une URL d'export sans gid renvoie silencieusement seulement le premier onglet, la map (nom d'onglet → #gid=) est donc imposée. Ou basculez vers le mode SheetsApi, qui ne nécessite aucune map.

« Push a signalé des cellules ignorées. »

La nouvelle récupération en direct avant envoi a trouvé des conflits (un coéquipier a modifié une cellule, une ligne a bougé/disparu, une clé en double). Les cellules ignorées sont une protection, pas un échec — le rapport affiche les compteurs appliqué/ignoré. Réimportez pour réconcilier, puis relancez un Push.

« J'ai supprimé des lignes localement, mais elles sont toujours dans la feuille Google après le Push. »

Les suppressions de ligne ne sont jamais poussées (les suppressions positionnelles sur une feuille en direct sont dangereuses) — vous obtenez un avis à la place. Supprimez les lignes dans la feuille, puis réimportez.

Création

« Ctrl+Z n'annule pas ma modification préparée. »

Deux limites :

un champ de texte ayant le focus consomme Ctrl+Z en premier — cliquez ailleurs, puis annulez ;
une fois que « Répercuter vers la feuille » réussit, l'historique de préparation est effacé, si bien que l'annulation ne fonctionne qu'à l'intérieur de la session pré-répercussion.

Après la répercussion, modifiez la feuille (elle est canonique).

« Certaines de mes modifications préparées affichent un badge "isolée" et n'ont pas été répercutées. »

La feuille a changé de l'extérieur entre la préparation et la répercussion, d'une façon qui a cassé l'adresse logique de ces modifications (clé de la ligne renommée à l'extérieur / ligne supprimée / conflit de clé). Elles sont exclues — ni perdues silencieusement, ni bloquantes pour le reste. Abandonnez-les individuellement et repréparez-les contre la nouvelle baseline.

« J'ai renommé une colonne/un onglet et maintenant mon code de jeu ne compile plus. »

Attendu et divulgué dans la boîte de dialogue de confirmation : les renommages changent le nom du champ/de la classe généré(e). Mettez à jour votre code de jeu ; la chaîne d'import se termine ensuite à la prochaine exécution. Les valeurs de données de la colonne ont été entièrement préservées.

« Puis-je permuter deux noms d'onglet (A↔B), ou renommer des onglets en cycle, en un seul lot ? »

Oui — les permutations mutuelles et les cycles (A→B→C→A) se préparent et se répercutent en un seul lot (l'interface ne rejette qu'un véritable conflit : deux renommages ciblant le même nom). Les références suivent les données et sont réécrites atomiquement. Un cas particulier subsiste sur Google : deux onglets permutés qui se référencent l'un l'autre ne sont pas repointés (le mode local est entièrement correct) — faites transiter la référence mutuelle par un troisième onglet, ou répercutez via un nom intermédiaire. Voir Data Studio et Capacités et limites.

« Mon renommage de clé n'a pas mis à jour une référence que j'ai saisie dans le même lot. »

La propagation ne réécrit que les cellules de la baseline — jamais le texte que vous venez de saisir (aucune réécriture silencieuse de saisie fraîche). La validation préalable signale la référence pendante ; corrigez-la vous-même.

« La répercussion a été refusée à cause d'un onglet xlsx. »

Deux cas connus :

les onglets d'origine xlsx ne peuvent pas être renommés (protection de classeur) ;
la propagation de renommage de clé qui toucherait un onglet xlsx bloque le lot entier (aucune répercussion partielle).

Modifiez le classeur directement, puis réimportez.

« J'ai modifié une SO bake dans l'inspecteur et le réimport l'a effacée. »

C'est voulu — la feuille est la source unique de vérité et la SO est un cache. L'interrupteur « Modification test » de l'inspecteur est explicitement temporaire. Faites de véritables changements via la feuille ou le Data Studio.

Export et divers

« L'export échoue avec une discordance de schéma. »

Votre bake est périmé par rapport à un changement de schéma (ExportSchemaMismatch — vérification d'empreinte). Lancez un import pour terminer codegen + bake, puis Export/Push.

« Mon flottant exporté indique `1` alors que la feuille avait `1.0`. »

Aller-retour sémantique : les valeurs sont préservées exactement ; la notation se normalise vers la forme d'aller-retour la plus courte. La structure (marqueurs, ordre des colonnes, commentaires, votre texte) est préservée à 100 %.

« L'import xlsx a rejeté certaines cellules. »

Le lecteur OOXML intégré est volontairement minimal. Trois choses ne sont pas prises en charge :

les cellules de formule sans valeur mise en cache ;
les cellules d'erreur ;
les tabulations/sauts de ligne à l'intérieur d'une cellule.

Matérialisez les formules en valeurs ; utilisez ; pour les listes.

Capacités et limites — la version systématique de ces réponses
Prise en main — les étapes de configuration référencées ci-dessus
Syntaxe des feuilles — les règles de notation référencées ci-dessus