Référence de l'API — la surface publique

Cette page liste tous les types publics des assemblies du produit. Tout ce qui n'est pas listé ici est internal par conception ; la surface publique est délibérément étroite.

• Core (SheetForge.Core + SheetForge.Core.Tooling) : 137 types publics (Core : 131, Core.Tooling : 6). Core.Tooling est la moitié réservée à l'Editor qui héberge les services au moment de l'import comme le reporting et la planification du Push — rien de tout cela n'est livré dans les builds joueur.
• Editor : 53 types publics de premier niveau plus leurs types imbriqués publics.
• Runtime : 7 types, plus les sorties générées.

C'est exactement la surface contre laquelle compilent les tests de simulation de consommateur (sans InternalsVisibleTo).

Contrat de détection (pas un type) : un asset séparé peut aussi détecter que SheetForge est installé à la compilation via le symbole de compilation SHEETFORGE que l'assembly Editor s'auto-enregistre. C'est un define, pas un type public, donc il n'est pas listé dans les tableaux ci-dessous — voir Création de plugins ▸ Détecter SheetForge depuis un autre asset. (Distinct de SHEETFORGE_ADDRESSABLES, un define de version interne qui ne fait que marquer la présence du package Addressables.)

Conventions : les signatures sont abrégées (… = voir les docs XML source) ; « pur » signifie aucun UnityEngine / aucune E/S.

Assembly Core (SheetForge.Core) — C# pur

Aucun UnityEngine, aucune E/S, aucun réseau, aucune connaissance du domaine. Imposé par le compilateur : le Core ne référence rien.

Contrats d'enregistrement de plugin (SheetForge.Core.Plugins)

Composition et compatibilité (SheetForge.Core.Plugins)

La découverte est propre à chaque hôte — le TypeCache d'Unity dans l'éditeur, le scan d'assembly téléversé du navigateur sur le web. Tout ce qui suit (instanciation, ordonnancement, isolation et la barrière de compatibilité) est une seule fonction Core partagée, ce qui est ce qui empêche les deux hôtes de dériver emplacement par emplacement.

PluginComposition — les deux membres :

• IReadOnlyList<Type> ContractTypes — le filtre de découverte. Son ordre est fixe, car il décide l'ordre dans lequel les diagnostics apparaissent.
• PluginSet Compose(IReadOnlyList<Type> candidateTypes, string hostVersion, ErrorCollector errors, ICollection<string> failures, Func<string,bool> isProductKey = null) — l'appel d'assemblage lui-même.

Deux sortes de problèmes sont tenues à part. Les conflits d'enregistrement et les refus de compatibilité deviennent des diagnostics structurés dans errors ; les bugs d'implémentation — échec de construction, callback qui lève une exception — deviennent des lignes en anglais dans failures, et passer null là-bas les ignore.

Le prédicat final isProductKey est ce qui impose la règle « un plugin ne peut pas écraser une clé produit » de la surcouche de chaînes sans que le Core ne voie jamais les tables de langue : la règle vit ici, l'hôte ne fournit que la matière. Omettez le prédicat et seule cette règle est ignorée.

Registres (SheetForge.Core.Model / .Validation / .Edges)

EnumRegistry — les trois membres en détail :

• EnumRegistry(EnumRegistry parent) — un enfant qui lit à travers un parent et n'enregistre que sur lui-même. Le parent porte les enums CLR enregistrés par plugin pour tout le rechargement de domaine, l'enfant ceux définis par feuille pour cet import, si bien qu'un import ne modifie jamais le cache partagé. Enregistrer un nom que le parent possède déjà lève une exception plutôt que de le masquer.
• Contains(name) — soi-même puis le parent, Ordinal.
• SetClrTypeName(name, fullTypeName) — renseigne un nom CLR après un enregistrement à base de chaîne seule. Le nom d'assembly reste vide car le type n'existe pas encore.

Modèles « Créer une feuille » (SheetForge.Core.Model)

Types de cellule personnalisés (SheetForge.Core.Model)

Constantes de la grammaire de feuille (SheetForge.Core.Model)

Un pack qui lit ou écrit du texte de cellule fonctionne avec la même grammaire que l'import — découper une cellule de liste, composer une chaîne @type, vérifier si un nom est déjà pris.

Ces constantes sont la source unique de vérité de cette grammaire, si bien qu'un pack ne redéclare jamais son propre séparateur : un caractère recopié dérive le jour où la grammaire change. Les listes sont fournies en lecture seule, si bien que rien de ce qu'un pack fait ne peut changer la grammaire elle-même. La notation qu'elles expriment est intégralement documentée sur la page Syntaxe des feuilles — ceci en est la prise programmatique.

Marqueurs

• CommentPrefix (#) · MarkerPrefix (@).
• Une constante par ligne de marqueur intégré : NameMarker · TypeMarker · DescMarker · OverlapMarker · StyleMarker · EnumMarker · LocMarker.
• RequiredMarkers — les trois que toute feuille doit porter.
• ReservedMarkers — chaque nom intégré. Consultez-le avant de nommer un marqueur personnalisé : une collision est refusée à l'enregistrement.

Séparateurs

• ListSeparator (;) — entre les éléments d'une liste.
• EntrySeparator (,), FieldSeparator (:), SectionSeparator (|), KeyTimeSeparator (@) — les couches à l'intérieur d'une seule valeur, raison pour laquelle ; n'apparaît jamais dans le texte propre d'une valeur.
• StyleKeyValueSeparator (=) — à l'intérieur d'une cellule @style.

Notation @type

• OptionalSuffix (?) · DefaultSeparator (=) · TargetSeparator (@, comme dans RecordId@Tab).
• ListTypeName · ListOpen (List<) · ListClose (>).

Noms de type

• Une constante par nom intégré : IntTypeName · FloatTypeName · BoolTypeName · StringTypeName · RecordIdTypeName · IntIdTypeName · AssetRefTypeName · LocRefTypeName · ColorTypeName · AnimationCurveTypeName · GradientTypeName · EnumTypeName.
• BuiltinScalarTypes et IsBuiltinScalarTypeName(name) — répondent à « ce nom est-il déjà un type intégré ? » avant qu'un parseur soit enregistré sous ce nom.
• StyleKeyNames (title, color) · LocReservedColumns (smart, comment).

Valeurs

• TrueCanonical / FalseCanonical — le texte canonique de bool.
• NumberCellStyles — le NumberStyles avec lequel chaque cellule numérique est lue. Les séparateurs de milliers sont exclus et la culture est toujours invariante, si bien qu'une virgule décimale locale échoue bruyamment au lieu de changer silencieusement un nombre.

Validation de domaine (SheetForge.Core.Validation)

Couture des arêtes (SheetForge.Core.Validation / .Edges)

ReferenceScanner — les deux prédicats de référence :

• GetReferencedTab(TypeToken) — l'unique prédicat que tout consommateur interroge, « est-ce une référence, et vers où ». Il répond pour RecordId@Tab, pour IntId@Tab (l'espace de clé entier), pour l'intérieur d'un wrapper, et pour un type personnalisé marqué IsCustomReference. C'est pourquoi un seul opt-in — et, pour IntId@Tab, un élargissement de ce prédicat — les active tous à la fois.
• GetReferenceKind(TypeToken) → RefKeyKind — si la référence se compare contre l'espace de clé chaîne ou entier, afin que la propagation de renommage, la liste déroulante et le sélecteur branchent correctement.
• GetReferenceKind(TypeToken, tables) — la surcharge consciente des tables.

Une référence du Core énonce son propre espace (RecordId / IntId). Un type personnalisé référençant n'a aucune notation pour le dire — MyType@Tab est la seule orthographe — si bien que son espace est dérivé de la propre identité de l'onglet cible : une clé propre RecordId signifie l'espace chaîne, IntId seul signifie l'espace entier, et un onglet inconnu ou des tables null retombent sur l'espace chaîne, la même réponse que donne la surcharge à jeton seul. Cette dérivation est ce qui permet à une implémentation existante d'IReferencingCellType de viser un onglet à clé IntId sans qu'une seule ligne ne change.

Index du graphe de référence (SheetForge.Core.Edges)

Un instantané immuable qui fusionne les références scannées par le Core et les arêtes de contributeur en un seul modèle, indexé dans les deux sens. Matériau d'affichage — il ne produit jamais de diagnostics (les Diagnostics de la projection restent l'unique source de vérité pour les problèmes).

Canevas d'enregistrements du Data Studio (SheetForge.Core.Graphing)

Le canevas décide seul de ce qu'il dessine : il parcourt l'index de référence vers l'extérieur depuis l'enregistrement que vous avez ouvert (le terminus) et dispose le résultat de façon déterministe. Un plugin ne remplace pas cette image — il l'enrichit. Des données pures de bout en bout : les colonnes sont des cellules de grille, pas des pixels, et les couleurs sont une chaîne Category libre que la fenêtre associe à une palette.

CanvasAugmentBuilder — la surface d'écriture. Seulement quatre choses :

• AddNode(tab, recordId, title = null, category = null) / AddNode(tab, recordId, title, category, CellCoordinate address) — un nœud virtuel pour une identité qui n'est pas un enregistrement de feuille (une clé d'événement, un atome de code) ; l'onglet peut être vide.
• AddEdge(fromTab, fromRecordId, toTab, toRecordId, label = null, fieldName = null, fieldOnTarget = false, isCyclic = false, cyclicNote = null) — une arête supplémentaire que le scanner du Core ne peut pas voir. Nommer fieldName indique dans quelle cellule le lien est écrit, fieldOnTarget indique que cette cellule se trouve sur l'arrivée plutôt que le départ, et la paire de cycle marque une boucle pour l'affichage avec la note que seul le domaine connaît.
• SetLayer(tab, recordId, layer) — un indice de calque absolu (0 = le plus à gauche, négatif = plus à gauche encore, tout se décale à droite pour compenser). SetLayerRelative(tab, recordId, offset) — le même compté depuis le terminus (−1 = une colonne à sa gauche), résolu par rapport à la colonne du terminus avant qu'un indice ne l'ait déplacée.
• SetSubtitle(tab, recordId, subtitle) — un indice d'affichage, la seule chose qui s'applique aux enregistrements qui existent déjà et aux enregistrements absents de l'écran (le sélecteur de connexion les lit).

Les éléments avec une clé vide sont ignorés, et ce qui a été collecté est interne, car les règles de fusion vivent en un seul endroit. Chaque élargissement est en fin de liste, si bien qu'une surcharge écrite pour une surface antérieure compile toujours.

IAuthorableGraphShape — les deux comportements par défaut sans elle :

• La liste des onglets créables que cette capacité remplace — l'axe qui décide aussi si un canevas s'ouvre du tout et jusqu'où va le balayage des lignes en attente — couvre chaque onglet atteignable depuis l'onglet ciblé en suivant le schéma transitivement.
• La cascade de liaison que l'utilisateur voit réellement part des onglets que ciblent les ports actuellement dessinés.

Les deux abandonnent les onglets de registre de code et les onglets sans colonne clé. Un onglet renvoyé ici qu'aucun port dessiné n'accepte reste listé dans la cascade de liaison avec sa raison attachée, et les propres barrières de la fenêtre s'appliquent quand même par-dessus.

Préréglages de couleur (SheetForge.Core.Theming)

Un préréglage ne surcharge que les slots qu'il nomme ; chaque autre slot garde la valeur par défaut du produit, si bien qu'un préréglage reste valide à mesure que des slots sont ajoutés. Enregistrer n'applique jamais un préréglage — l'utilisateur en choisit un dans Preferences ▸ SheetForge ▸ Theme.

Surfaces de création déclaratives (SheetForge.Core.Studio)

Un plugin décrit ce qu'il faut montrer — la coquille comme données, le prédicat et l'effet comme délégués — et chaque hôte le dessine avec ses propres widgets : UIToolkit dans l'éditeur, React dans le navigateur. Aucun chiffre de mise en page n'apparaît nulle part. Quoi dire appartient au plugin, comment le placer appartient au moteur de rendu.

Chaque enum ici est ajout seul, si bien qu'un enregistrement garde son sens à mesure que le vocabulaire grandit.

StudioUiNode — fabriques, lectures et la règle d'URL :

• Fabriques : Row · Label · Chip · Badge · Button · Rule · Heading · KeyValue · Table(headerRow, rows) · List · Progress · Input · Link, plus WithTooltip(text), qui renvoie un nouveau nœud plutôt que de modifier celui-ci.
• Lectures : Kind · Text · Tooltip · ThemeColorSlot? Tone (jamais une couleur codée en dur, si bien qu'il suit le thème) · ActionId · Detail · Ratio · Url · Children.
• bool IsAllowedUrl(url) statique — http/https seulement. Un seul prédicat que les deux hôtes interrogent, si bien qu'ils ne peuvent pas être en désaccord sur ce qui est sûr à ouvrir.

Chaînes d'UI de plugin (SheetForge.Core.Model)

StringOverlayRegistry — correspondance et refus. language est un code IETF ("en", "ko", "zh-Hans", "pt-BR", …), comparé sans tenir compte de la casse. La recherche retombe langue demandée → anglais → échec, et le repli vit ici afin que les deux hôtes répondent de façon identique.

Quatre enregistrements sont refusés, chacun consignant une raison destinée au développeur plutôt que d'échouer silencieusement :

• une clé intégrée du produit — une surcouche peut ajouter des clés, jamais écraser les propres phrases ou chemins de menu du produit ;
• une clé+langue qu'un autre pack a déjà enregistrée — le premier trouvé l'emporte, sinon l'ordre d'installation déciderait de l'écran ;
• une clé ou une valeur vide ;
• un code de langue que le produit ne connaît pas, jamais replié sur l'anglais.

Observation du pipeline (SheetForge.Core.Plugins / .Model)

Registres de code (SheetForge.Core.Graphing)

Des cibles de référence qui vivent dans le code, exposées à la surface de création comme des onglets virtuels verrouillés. Consommées par le Data Studio (barre latérale / graphe / inspecteur), pas par le validateur d'import.

Le modèle de lecture de l'IR (SheetForge.Core.Model)

Références d'asset typées (SheetForge.Core.Model)

Le <Type> de AssetRef@Group<Type> est résolu par l'hôte — le Core ne connaît ni le moteur ni les assemblies du projet — et le Core ne fait que juger le résultat. Tout ici est de la donnée pure.

Le codegen lit le dictionnaire résolu que produit le pipeline et émet AssetReferenceT<global::FullName> pour un nom résolu ; un nom qu'il ne trouve pas dans ce dictionnaire n'est jamais émis tel quel — le champ se replie sur AssetReference et un avertissement AssetTypeUnresolvedFallback est collecté. Le nom complet résolu est aussi mélangé dans l'empreinte de schéma.

Types de valeur visuelle (SheetForge.Core.Model)

Modèles de valeur indépendants du moteur pour les trois types visuels intégrés. Chacun est immuable, IEquatable, et possède sa propre forme de texte (TryParse / Render) — la même notation que documente la page Syntaxe des feuilles — si bien qu'un type de plugin qui stocke une couleur, une courbe ou un dégradé peut les réutiliser au lieu d'inventer une seconde notation. L'Editor les bake dans UnityEngine.Color / AnimationCurve / Gradient et les relit ; le navigateur les échantillonne via les évaluateurs ci-dessous plutôt que de réimplémenter les mathématiques.

Erreurs et résultats (SheetForge.Core.Model / .Reporting)

ImportErrorCode — les familles qu'il couvre :

• marqueurs, schéma, types, cellules, clés/références et clés d'asset ;
• sources/fichiers, csv/xlsx, identifiants de codegen, addressables, baseline/export, Google/authentification/Push et modèles ;
• plugins — PluginRegistrationConflict, plus PluginIncompatible quand la déclaration de compatibilité d'un assembly tombe hors de ce que cet hôte lit ;
• IntId — DuplicateIntId, et pour les références IntId@Tab UnresolvedIntId · TargetTabHasNoIntId ;
• @overlap et DomainRuleViolation ;
• feuilles de définition d'enum — EnumSheetMarkerConflict · DuplicateEnumName · EnumSheetEmptyColumn · InvalidEnumIdentifier · InvalidEnumUnderlyingType · InvalidEnumMemberValue ;
• DropdownNotSupportedByFormat, qui est un avertissement plutôt qu'une erreur ;
• références d'asset typées — UnknownAssetType · AmbiguousAssetType · AssetTypeNotReferenceable (une fois par colonne, sur la ligne @type), AssetTypeMismatch par cellule, et l'avertissement de codegen AssetTypeUnresolvedFallback.

Index et utilitaires (SheetForge.Core.Validation / .Model / .Parsing / .Unparse)

Plan de Push (SheetForge.Core.Unparse)

Public car IPushApprover.Approve(PushPlan) les expose ; données pures.

Assembly Editor (SheetForge.Editor)

Paramètres, localisation, composition (SheetForge.Editor.Pipeline / .Localization)

PluginRegistry — le bundle et l'isolation des emplacements. Le PluginBundle imbriqué expose le PluginSet Set composé — la vérité unique à douze emplacements, ce qui permet de lire un emplacement nouvellement ajouté sans élargir le bundle — plus neuf fenêtres de commodité dessus : Enums · Parsers · Validators · EdgeContributors · Markers · Templates · GraphShapes · CodeRegistries · Themes. Les constructeurs antérieurs à six et huit arguments sont conservés comme surcharges qui mettent par défaut les registres ultérieurs à vide, ce qui se comporte de façon identique aux versions d'avant l'existence de ces contrats.

L'isolation appartient au Core, pas à ce type : un plugin qui lève une exception pendant l'enregistrement est signalé par son nom et ignoré, et tous les autres emplacements — ainsi que tout autre plugin — s'enregistrent quand même.

SheetForgeActions — sémantique de complétion. RunImport/RunPush sont fire-and-forget. Leur corps est async void car le thread principal de l'éditeur ne peut pas bloquer sur des E/S réseau, donc le retour n'est pas la complétion — abonnez-vous à ImportEvents.ImportCompleted pour cela. RunExport/RunHealthCheck/RunLocalizationSync se terminent de façon synchrone — RunLocalizationSync parcourt le chemin feuille → StringTable que parcourt une complétion d'import, et sans le package Unity Localization il affiche l'avis d'installation et ne change rien.

Couture des fournisseurs de source (SheetForge.Editor.Sources)

Points d'extension du Data Studio (SheetForge.Editor.Studio)

Côté Editor car ils touchent aux UIElements / à l'état de fenêtre — la même asymétrie justifiée que pour ISheetSourceProvider. Les quatre contrats sont découverts par TypeCache (constructeur sans paramètre ; aucun appel d'enregistrement), et tous sont appelés à l'intérieur d'un try/catch. La fenêtre elle-même (DataStudioWindow) est internal.

Tout ce qui est exprimable comme données appartient plutôt au vocabulaire Core ISheetForgeStudioPlugin, qui se rend aussi dans le navigateur. Ce sont ici les échappatoires sans plafond pour ce que la description ne peut pas dire.

Les quatre dernières entrées ne sont pas des contrats mais des outils qu'un widget monté peut utiliser :

• les propres valeurs de skin en lecture seule de la fenêtre, pour qu'il ressemble à ce qu'il lui appartient ;
• la liste déroulante de clé, pour qu'un widget de cellule choisisse des clés de la même façon que la cellule intégrée ;
• et la réinitialisation du cache de découverte, pour que vos propres tests puissent redécouvrir une sonde.

StudioInspectorContext — les deux délégués de préparation :

• StageCell prend l'onglet, l'id d'enregistrement, le champ et le texte brut canonique. La fenêtre enregistre l'étape d'annulation, incrémente la génération de projection et prépare l'adresse logique.
• StageCells fait la même chose pour plusieurs cellules qui doivent changer ensemble : une seule étape d'annulation native, tout ou rien. Si l'une ne peut pas être préparée, la session n'est pas touchée du tout.

Un échec est silencieux à l'écran dans les deux cas, et seule la barrière s'explique elle-même. Une source en lecture seule, un pipeline déjà en cours, ou un onglet d'origine classeur écrit sa raison dans la console. Une liste vide, une écriture sans onglet ni champ, et une clé d'enregistrement qui ne résout aucune ligne ne font rien et ne disent rien.

StudioPalette — les membres :

• 33 slots de couleur : Canvas · Panel · Band · Chrome · Surface · Chip · Selection · PendingCell · Line · LineSoft · GridLine · LineHover · Text · TextMuted · TextFaint · RefText · OnAccent · Accent · AccentDim · Warning · Danger · Ok · SheetTone · CodeTone · EditedCell · NewRowCell · NewRowLine · DangerChip · DangerPanel · Scrim · Wire · WireDot · GridDot.
• IsDark.
• Espacement : SectionSpace · RowSpace · RuleHeight · ButtonHeight · PrimaryButtonHeight · GlyphWidth.
• Tailles de type : HeadingFontSize · SectionFontSize · CaptionFontSize.
• FromRgb(uint) · ToHex(uint).

Approbation du Push (SheetForge.Editor.Push)

Moteur de création (SheetForge.Editor.Structure / .Pipeline / .Export)

Types de valeur de préparation (SheetForge.Editor.Structure; StagedCellEdit/StagedNewRow sont dans SheetForge.Editor.Windows)

Assistants de création (SheetForge.Editor.Windows / .Structure)

Assembly Runtime (SheetForge.Runtime)

autoReferenced — utilisable depuis le code de jeu sans référence asmdef.

Types générés (schéma — par projet, pas une API livrée)

Pour chaque onglet Foo, le codegen émet dans votre generatedNamespace :

public sealed partial class FooDefinition    // one strongly-typed field per column; @desc → doc/tooltip
public sealed partial class FooDatabase : DefinitionDatabase
{
    // TabName, Count, SchemaFingerprint, Records, RecordsUntyped override,
    // lazy _byId/_byIntId lookups, InvalidateIndex override
}

Chargez avec SheetForgeDatabases.LoadAsync<FooDatabase>("Foo").

Les deux classes sont émises en partial, si bien que vous pouvez ajouter des membres dérivés — une propriété calculée, une implémentation d'interface, un opérateur — dans votre propre fichier à côté du fichier généré, et un réimport ne l'écrasera pas.

Une limite : n'ajoutez aucun champ sérialisé dans votre partie. Le ScriptableObject bake est reconstruit à partir de la feuille à chaque import, donc tout ce que seule votre partie sérialise revient à sa valeur par défaut. Si une valeur appartient aux données, elle appartient à une colonne.

(Le mot-clé partial ne touche pas SchemaFingerprint, qui est calculé à partir du seul schéma, donc rendre les classes partial n'a invalidé aucun bake existant.)

Autres assemblies

• SheetForge.Setup — l'amorçage sans dépendance pour l'absence d'Addressables. Aucune API publique (tout est internal ; il existe pour afficher une fenêtre de guidage).

• SheetForge.PluginDemo (un asmdef fusionné + un asmdef Demo.Editor ; l'espace de noms du contenu reste SheetForge.Skills) — le package d'exemple de référence, pas une API produit. Il contient :

  • SkillsPlugin (sept interfaces de plugin — base, validateur, arête, modèle, graphe, registre de code, thème) ;
  • Modifier + ModifierCellParser (type de cellule personnalisé), ModifierStatEdgeContributor (contributeur d'arêtes) ;
  • ExamplePipelineAugmenter / ExampleReactiveAugmenter (surcharges de canevas), ExampleCodeAtoms (le registre de code _Refs) ;
  • ExampleStudioUi (actions déclaratives, panneau, badge de colonne et indice d'éditeur de cellule), ExampleImportObserver (observateur de pipeline) ;
  • ExampleStageStripWidget / ExampleInspectorAction / ExampleStudioPanel (points d'extension Editor du Data Studio, peints à partir de la palette publique), ExampleLocStrings (enregistre ces libellés en deux langues — dans l'assembly principal, si bien que le navigateur les montre aussi) ;
  • une déclaration SheetForgePluginCompat au niveau de l'assembly ;
  • SkillRunner (consommation à l'exécution), types Example* générés dans l'espace de noms par défaut SheetForge.Generated (l'isolation se fait par le préfixe Example*, pas par un espace de noms séparé).

  L'exemple sans plugin SheetForge.CoreDemo est livré avec zéro asmdef (compile dans Assembly-CSharp).

Pages associées

• Création de plugins — les contrats utilisés, avec des exemples complets
• Noyau de création — les types du moteur en contexte
• Capacités et limites — les limites comportementales de ces API