API リファレンス — 公開サーフェス

このページには、製品のアセンブリに含まれる すべての public 型 を掲載しています。ここに載っていないものは、設計上 internal です——公開サーフェスは意図的に狭く保たれています。

• Core(SheetForge.Core + SheetForge.Core.Tooling): 137個の public 型(Core: 131個、Core.Tooling: 6個)。Core.Tooling は、レポート出力や Push プランニングのようなインポート時サービスを持つ、エディター専用の半身です——そのためプレイヤービルドには一切含まれません。
• Editor: トップレベルの public 型53個と、それらの public なネスト型。
• Runtime: 7個の型に加え、生成される出力。

これはまさに、コンシューマーシミュレーションテスト(InternalsVisibleTo なし)がコンパイル対象とするサーフェスそのものです。

検出契約(型ではない): 別のアセットも、Editor アセンブリが自己登録する SHEETFORGE スクリプティング定義シンボルを通じて、コンパイル時に SheetForge がインストールされていることを検出できます。これは define であり public な型ではないため、下記の表には載っていません——プラグイン作成 ▸ 他のアセットから SheetForge を検出する を参照してください。(SHEETFORGE_ADDRESSABLES ——Addressables パッケージが存在するかどうかだけを示す内部的なバージョン定義——とは別のものです。)

表記の規則: シグネチャは省略されています(… = ソースの XML ドキュメントを参照)。「pure(純粋)」は、UnityEngine への依存も IO もないことを意味します。

Core アセンブリ(SheetForge.Core)— 純粋な C#

UnityEngine への依存なし、IO なし、ネットワークなし、ドメイン知識なし。コンパイラによって強制されています: Core は何も参照しません。

プラグイン登録契約(SheetForge.Core.Plugins)

構成と互換性(SheetForge.Core.Plugins)

発見はホストごとです——エディターでは Unity の TypeCache、Web ではブラウザーのアップロード済みアセンブリスキャン。それ以降(インスタンス化、順序付け、隔離、互換性ゲート)はすべて、一つの共有された Core の機能であり、これが二つのホストがスロットごとに乖離しないようにしています。

PluginComposition — 二つのメンバー:

• IReadOnlyList<Type> ContractTypes — 発見のフィルターです。その順序は固定されています。診断情報が現れる順序を決めるためです。
• PluginSet Compose(IReadOnlyList<Type> candidateTypes, string hostVersion, ErrorCollector errors, ICollection<string> failures, Func<string,bool> isProductKey = null) — 組み立て呼び出しそのものです。

二種類の問題は分けて扱われます。登録の衝突と互換性の拒否は errors の中で構造化された診断情報になり、実装のバグ——構築失敗、例外を投げるコールバック——は failures の中で英語の一行になります。そこに null を渡すと、それらは破棄されます。

末尾の isProductKey 述語は、文字列オーバーレイの「プラグインは製品キーを上書きできない」というルールが、Core が言語テーブルを一切見ることなく強制される仕組みです: ルールはここにあり、ホストは素材だけを供給します。この述語を省略すると、そのルールだけがスキップされます。

レジストリ(SheetForge.Core.Model / .Validation / .Edges)

EnumRegistry — 三つのメンバーの詳細:

• EnumRegistry(EnumRegistry parent) — 親を読み取りつつ、登録は自分自身にのみ行う子です。親はドメインリロード全体を通じてプラグインが登録した CLR enum を保持し、子は今回のインポートでシート定義された enum を保持するため、インポートが共有キャッシュを変更することは決してありません。親がすでに所有している名前を登録しようとすると、それを覆い隠すのではなく例外を投げます。
• Contains(name) — 自分自身、次に親、Ordinal で判定します。
• SetClrTypeName(name, fullTypeName) — 文字列のみの登録の後で CLR 名を埋めます。型がまだ存在しないため、アセンブリ名は空のままです。

「シート作成」テンプレート(SheetForge.Core.Model)

カスタムセルタイプ(SheetForge.Core.Model)

シート文法定数(SheetForge.Core.Model)

セルのテキストを読み書きするパックは、インポーターと同じ文法で動作します——リストセルを分割する、@type 文字列を組み立てる、名前がすでに使われていないか確認する、といったことです。

これらの定数はその文法の単一の情報源であり、パックが自前の区切り文字を書き直すことは決してありません:文字をコピーして持っておくと、文法が変わった日にずれてしまいます。リストは読み取り専用として渡されるため、パックが何をしても文法そのものを変えることはできません。それらが表す記法は、シート構文 ページに完全に文書化されています——これはその文法へのプログラム的な取っ手です。

マーカー

• CommentPrefix (#) · MarkerPrefix (@)。
• 組み込みマーカー行ごとに定数一つ: NameMarker · TypeMarker · DescMarker · OverlapMarker · StyleMarker · EnumMarker · LocMarker。
• RequiredMarkers — すべてのシートが持たなければならない三つ。
• ReservedMarkers — すべての組み込み名。カスタムマーカーに名前を付ける前にこれを確認してください:衝突は登録時に拒否されます。

区切り文字

• ListSeparator (;) — リストの要素の間。
• EntrySeparator (,)、FieldSeparator (:)、SectionSeparator (|)、KeyTimeSeparator (@) — 一つの値の 内側 にある層であり、だからこそ ; が値自身のテキストの中に現れることは決してありません。
• StyleKeyValueSeparator (=) — @style セルの内部。

@type の記法

• OptionalSuffix (?) · DefaultSeparator (=) · TargetSeparator (@、RecordId@Tab のように)。
• ListTypeName · ListOpen (List<) · ListClose (>)。

型名

• 組み込み名ごとに定数一つ: IntTypeName · FloatTypeName · BoolTypeName · StringTypeName · RecordIdTypeName · IntIdTypeName · AssetRefTypeName · LocRefTypeName · ColorTypeName · AnimationCurveTypeName · GradientTypeName · EnumTypeName。
• BuiltinScalarTypes と IsBuiltinScalarTypeName(name) ——「この名前はすでに組み込みか?」に、パーサーがその名前で登録される前に答えます。
• StyleKeyNames (title、color) · LocReservedColumns (smart、comment)。

値

• TrueCanonical / FalseCanonical — 正規の bool テキスト。
• NumberCellStyles — すべての数値セルの読み取りに使われる NumberStyles。桁区切り文字は除外され、カルチャーは常に不変(invariant)なので、ロケールの小数点カンマは数値を静かに変えてしまう代わりに、はっきりと失敗します。

ドメイン検証(SheetForge.Core.Validation)

エッジの継ぎ目(SheetForge.Core.Validation / .Edges)

ReferenceScanner — 二つの参照用述語:

• GetReferencedTab(TypeToken) — あらゆる利用側が「これは参照か、そしてどこへの参照か」を尋ねるための唯一の述語です。RecordId@Tab、IntId@Tab(整数キー空間)、ラッパーの内側、そして IsCustomReference が付いたカスタム型のいずれに対しても答えます。だからこそ、一つのオプトイン——そして IntId@Tab については、この述語の一つの拡張——だけで、これらすべてが同時に有効になります。
• GetReferenceKind(TypeToken) → RefKeyKind — その参照が 文字列 と 整数 のどちらのキー空間と比較されるかを表します。これにより、名前変更の伝播・ドロップダウン・ピッカーが正しく分岐できます。
• GetReferenceKind(TypeToken, tables) — テーブルを考慮するオーバーロードです。

core の参照は、自身のキー空間(RecordId / IntId)を自ら述べます。参照型のカスタム型には、それを述べるための記法がありません——MyType@Tab が唯一の綴りです——そのため、そのキー空間は 対象タブ自身のアイデンティティ から導出されます: RecordId を自己キーとするタブは文字列空間を、IntId のみのタブは整数空間を意味し、タブが不明な場合や tables が null の場合は文字列空間にフォールバックします(これは、トークンのみを見るオーバーロードが返すのと同じ答えです)。この導出こそが、既存の IReferencingCellType 実装を、一行も変更せずに IntId キーのタブへ向けられるようにしているものです。

参照グラフインデックス(SheetForge.Core.Edges)

core がスキャンした参照とコントリビューターのエッジを一つのモデルに統合し、双方向に索引化した不変のスナップショットです。表示用の材料です——診断情報を生成することは決してありません(問題に関する唯一の信頼できる情報源は、引き続きプロジェクションの Diagnostics です)。

Data Studio のレコードキャンバス(SheetForge.Core.Graphing)

キャンバスは、何を描画するかを自力で決定します: 開いたレコード(terminus)から参照インデックスを外向きにたどり、結果を決定的に配置します。プラグインはその絵を置き換えるのではなく、追加 します。全体を通して純粋なデータです: 列はピクセルではなくグリッドのセルであり、色は、ウィンドウがパレットにマッピングする自由な Category 文字列です。

CanvasAugmentBuilder — 書き込みサーフェス。 できることは四つだけです:

• AddNode(tab, recordId, title = null, category = null) / AddNode(tab, recordId, title, category, CellCoordinate address) — シートのレコードではない識別子(イベントキー、コードアトム)のための 仮想ノード。タブは空でも構いません。
• AddEdge(fromTab, fromRecordId, toTab, toRecordId, label = null, fieldName = null, fieldOnTarget = false, isCyclic = false, cyclicNote = null) — core のスキャナーが見ることのできない 追加のエッジ。fieldName を指定すると、そのリンクがどのセルに書かれているかを示し、fieldOnTarget は、そのセルが出発ではなく到着側にあることを示し、cycle のペアは、ドメインだけが知っている note とともに、そのループを表示用にマークします。
• SetLayer(tab, recordId, layer) — 絶対的なレイヤーヒント(0 = 最も左、負の値はさらに左。それを補うためすべてが右にシフトします)。SetLayerRelative(tab, recordId, offset) — 同じものを terminus からの相対位置 で(−1 = その一つ左の列)、どのヒントによっても動かされる前の terminus の列を基準に解決します。
• SetSubtitle(tab, recordId, subtitle) — 表示のヒント。すでに存在するレコードにも、画面にないレコードにも適用される唯一のもの(connect ピッカーはそれらを読み取ります)。

キーが空の項目は無視され、何が集められたかは internal です。マージのルールは一箇所に集約されているためです。あらゆる拡張は末尾に追加されるため、以前のサーフェスに対して書かれたオーバーライドも引き続きコンパイルできます。

IAuthorableGraphShape — これがない場合の二つのデフォルト:

• この capability が置き換える 作成可能タブの一覧——そもそもキャンバスが開くかどうかや、保留行の探索がどこまで届くかも決める基準——は、フォーカスしているタブからスキーマを 推移的に たどって到達できるすべてのタブを網羅します。
• ユーザーが実際に目にする リンク のカスケードは、現在画面に描画されているポートが指しているタブから始まります。

どちらも、コードレジストリのタブと、キー列を持たないタブを除外します。この関数が返すタブのうち、画面上のどのポートも受け入れないものは、理由を添えたままリンクのカスケードに残り、ウィンドウ自身のゲートもその上に引き続き適用されます。

カラープリセット(SheetForge.Core.Theming)

プリセットは、自身が名指ししたスロットだけを上書きします。それ以外のスロットはすべて製品のデフォルトのままなので、スロットが追加されてもプリセットは有効であり続けます。登録しただけではプリセットは適用されません——ユーザーが Preferences ▸ SheetForge ▸ Theme で選択します。

宣言的オーサリングサーフェス(SheetForge.Core.Studio)

プラグインは、何を表示するかを記述します——外殻はデータとして、述語と効果はデリゲートとして。各ホストは、それを自身のウィジェットで描画します: エディターでは UIToolkit、ブラウザーでは React です。レイアウトの数値は、どこにも登場しません。何を語るかはプラグインのものであり、どう配置するかはレンダラーのものです。

ここにあるすべての enum は 追記専用 です。そのため、語彙が成長しても、登録はその意味を保ちます。

StudioUiNode — ファクトリー、読み取り、URL のルール:

• ファクトリー: Row · Label · Chip · Badge · Button · Rule · Heading · KeyValue · Table(headerRow, rows) · List · Progress · Input · Link、そして WithTooltip(text)(このノードを変更するのではなく、新しい ノードを返します)。
• 読み取り: Kind · Text · Tooltip · ThemeColorSlot? Tone(決してハードコードされた色ではなく、テーマに追従します)· ActionId · Detail · Ratio · Url · Children。
• static bool IsAllowedUrl(url) — http/https のみです。両方のホストが尋ねる一つの述語であり、そのため何を開いて安全かについて意見が食い違うことはありません。

プラグインの UI 文字列(SheetForge.Core.Model)

StringOverlayRegistry — 照合と拒否。 language は IETF コードです("en"、"ko"、"zh-Hans"、"pt-BR"、…)、大文字小文字を区別せずに照合されます。ルックアップは 要求された言語 → 英語 → 見つからない の順にフォールバックし、このフォールバックはここに存在するため、両方のホストが同一に答えます。

四つの登録は拒否され、それぞれサイレントに失敗するのではなく、開発者向けの理由を記録します:

• 製品の組み込みキー——オーバーレイはキーを追加できますが、製品自身の文やメニューパスを上書きすることは決してできません。
• すでに他のパックが登録した キー+言語 の組み合わせ——最初に見つかったものが優先されます。そうしなければ、インストール順が画面を左右してしまいます。
• 空のキーまたは値。
• 製品が知らない言語コード——これは決して英語に畳み込まれません。

パイプラインの観察(SheetForge.Core.Plugins / .Model)

コードレジストリ(SheetForge.Core.Graphing)

コードの中に存在する参照先で、オーサリングサーフェスにはロックされた仮想タブとして公開されます。インポートのバリデーターではなく、Data Studio(サイドバー / グラフ / インスペクター)が消費します。

IR の読み取りモデル(SheetForge.Core.Model)

型付きアセット参照(SheetForge.Core.Model)

AssetRef@Group<Type> の <Type> を解決するのは ホスト です——Core はエンジンもプロジェクトのアセンブリも知らないため——Core はその結果を判定するだけです。ここに登場するものはすべて純粋なデータです。

コード生成は、パイプラインが生成した解決済み辞書を読み取り、解決済みの名前には AssetReferenceT<global::FullName> を出力します。その辞書に見つからない名前が そのまま出力されることは決してありません ——そのフィールドは AssetReference にフォールバックし、AssetTypeUnresolvedFallback 警告が収集されます。解決済みのフルネームは、スキーマフィンガープリントにも組み込まれます。

視覚的な値の型(SheetForge.Core.Model)

三つの組み込み視覚型に対する、エンジンに依存しない値モデルです。それぞれが不変で、IEquatable であり、独自のテキスト形式(TryParse / Render)を持ちます——これはシート構文のページが説明しているのと同じ記法です——そのため、カラー・カーブ・グラデーションの値を保持するプラグインの型は、第二の記法を発明する代わりにこれらを再利用できます。エディターはこれらを UnityEngine.Color / AnimationCurve / Gradient にベイクし、読み戻します。ブラウザーは、計算式を再実装するのではなく、下記の評価器を通じてこれらをサンプリングします。

エラーと結果(SheetForge.Core.Model / .Reporting)

ImportErrorCode — それが網羅する系統:

• マーカー、スキーマ、型、セル、キー/参照、アセットキー。
• ソース/ファイル、csv/xlsx、コード生成の識別子、addressables、baseline/export、Google/認証/Push、テンプレート。
• プラグイン — PluginRegistrationConflict、そしてアセンブリの互換性宣言がこのホストの読み取れる範囲から外れている場合の PluginIncompatible。
• IntId — DuplicateIntId、そして IntId@Tab 参照については UnresolvedIntId · TargetTabHasNoIntId。
• @overlap と DomainRuleViolation。
• enum 定義シート — EnumSheetMarkerConflict · DuplicateEnumName · EnumSheetEmptyColumn · InvalidEnumIdentifier · InvalidEnumUnderlyingType · InvalidEnumMemberValue。
• DropdownNotSupportedByFormat(エラーではなく 警告 です)。
• 型付きアセット参照 — UnknownAssetType · AmbiguousAssetType · AssetTypeNotReferenceable(列ごとに一度、@type の行で)、セルごとの AssetTypeMismatch、そしてコード生成の 警告 AssetTypeUnresolvedFallback。

インデックスとユーティリティ(SheetForge.Core.Validation / .Model / .Parsing / .Unparse)

Push プラン(SheetForge.Core.Unparse)

IPushApprover.Approve(PushPlan) がこれらを公開するため、public になっています。純粋なデータです。

Editor アセンブリ(SheetForge.Editor)

設定・ローカライズ・構成(SheetForge.Editor.Pipeline / .Localization)

PluginRegistry — バンドルとスロットの分離。 ネストされた PluginBundle は、組み立て済みの PluginSet Set——十二スロットの単一の真実であり、これによってバンドルを広げることなく、新しく育ったスロットを読み取れます——に加えて、それへの九つの便宜的な窓を公開します: Enums · Parsers · Validators · EdgeContributors · Markers · Templates · GraphShapes · CodeRegistries · Themes。以前の六引数・八引数のコンストラクターは、後から追加されたレジストリを空にデフォルトするオーバーロードとして残されており、それらの契約が存在する前のバージョンとまったく同じように振る舞います。

分離は、この型ではなく Core のものです: 登録中に例外を投げたプラグインは、名前とともに報告され、スキップされますが、他のすべてのスロットとプラグインは引き続き登録されます。

SheetForgeActions — 完了のセマンティクス。 RunImport/RunPush は投げっぱなし(fire-and-forget)です。 そのボディは async void です。エディターのメインスレッドはネットワーク IO でブロックできないためです。そのため戻り値は完了を意味しません: 完了を知るには ImportEvents.ImportCompleted を購読してください。RunExport/RunHealthCheck/RunLocalizationSync は同期的に完了します——RunLocalizationSync は、インポートの完了が実行するシート → StringTable の経路を実行し、Unity Localization パッケージが無ければインストールの案内を表示するだけで、何も変更しません。

ソースプロバイダーの継ぎ目(SheetForge.Editor.Sources)

Data Studio の拡張ポイント(SheetForge.Editor.Studio)

UIElements / ウィンドウの状態に触れるため、Editor 側にあります——ISheetSourceProvider と同じ、理にかなった非対称性です。四つの契約はすべて TypeCache によって発見され(引数なしのコンストラクター、登録の呼び出しなし)、すべて try/catch の内側で呼び出されます。ウィンドウ自体(DataStudioWindow)は internal です。

データとして表現できるものはすべて、代わりに Core の ISheetForgeStudioPlugin の語彙に属します——そちらはブラウザーでも描画されます。ここにあるのは、記述では語れないもののための、天井のないエスケープハッチです。

最後の四つの項目は契約ではなく、マウントされたウィジェットが利用できるツールです:

• ウィンドウ自身の 読み取り専用 のスキン値。これにより、そこに元からあるかのように見せられます。
• キーのドロップダウン。これにより、セルウィジェットが組み込みのセルと同じ方法でキーを選べます。
• そして発見キャッシュのリセット。これにより、あなた自身のテストが、有効化したばかりのプローブを再発見できます。

StudioInspectorContext — 二つのステージング用デリゲート:

• StageCell はタブ、レコード id、フィールド、正規の生テキストを受け取ります。ウィンドウが Undo ステップを登録し、プロジェクションの世代を進め、論理アドレスをステージングします。
• StageCells は、一緒に変更しなければならない 複数 のセルに対して同様のことを行います: 一つのネイティブ Undo ステップで、オールオアナッシングです。一つでもステージングできなければ、セッションにはまったく触れられません。

失敗は、いずれの場合も画面上ではサイレントですが、ゲート だけは自身の理由を説明します。読み取り専用のソース、すでに実行中のパイプライン、ワークブック由来のタブは、その理由をコンソールに書き込みますが、空のリスト、タブまたはフィールドを欠いた書き込み、どの行にも解決されないレコードキーは、何もせず何も言いません。

StudioPalette — メンバー一覧:

• 33の色スロット: 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。
• 間隔: SectionSpace · RowSpace · RuleHeight · ButtonHeight · PrimaryButtonHeight · GlyphWidth。
• フォントサイズ: HeadingFontSize · SectionFontSize · CaptionFontSize。
• FromRgb(uint) · ToHex(uint)。

Push の承認(SheetForge.Editor.Push)

オーサリングエンジン(SheetForge.Editor.Structure / .Pipeline / .Export)

ステージング用の値の型(SheetForge.Editor.Structure。StagedCellEdit/StagedNewRow は SheetForge.Editor.Windows にあります)

オーサリングヘルパー(SheetForge.Editor.Windows / .Structure)

Runtime アセンブリ(SheetForge.Runtime)

autoReferenced — asmdef の参照なしに、ゲームコードから利用できます。

生成される型(パターン — プロジェクトごとのものであり、出荷される API ではありません)

タブ Foo ごとに、コード生成はあなたの 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
}

SheetForgeDatabases.LoadAsync<FooDatabase>("Foo") で読み込みます。

どちらのクラスも partial として出力されます。そのため、派生メンバー——計算プロパティ、インターフェースの実装、演算子など——を、生成されたファイルの隣にあるあなた自身のファイルに追加でき、再インポートしてもそれは上書きされません。一つだけ境界があります: あなたの部分に シリアライズされるフィールドを追加しないでください。ベイクされた ScriptableObject は、インポートのたびにシートから再構築されるため、あなたの部分だけがシリアライズするものは、デフォルト値に戻ってしまいます——ある値がデータに属するのであれば、それは列に属するべきです。(partial キーワードは、スキーマだけから計算される SchemaFingerprint には影響しないため、クラスを partial にしたことで、既存のベイクが無効になることはありません。)

その他のアセンブリ

• SheetForge.Setup — 依存関係を持たない、Addressables 欠落時のブートストラップです。公開 API はありません(すべて internal です。これはガイダンスウィンドウを表示するために存在します)。

• SheetForge.PluginDemo(一つに統合された asmdef + Demo.Editor asmdef。コンテンツの名前空間は SheetForge.Skills のまま)— 参照用のサンプルパッケージであり、製品の API ではありません。次を含みます:

  • SkillsPlugin(七つのプラグインインターフェース——base、validator、edge、template、graph、code registry、theme)。
  • Modifier + ModifierCellParser(カスタムセルタイプ)、ModifierStatEdgeContributor(エッジコントリビューター)。
  • ExamplePipelineAugmenter / ExampleReactiveAugmenter(キャンバスオーバーライド)、ExampleCodeAtoms(_Refs コードレジストリ)。
  • ExampleStudioUi(宣言的なアクション・パネル・列バッジ・セルエディターの hint)、ExampleImportObserver(パイプラインオブザーバー)。
  • ExampleStageStripWidget / ExampleInspectorAction / ExampleStudioPanel(Data Studio の Editor 拡張ポイントで、公開パレットから描画されます)、ExampleLocStrings(それらのラベルを二つの言語で登録します——メインの アセンブリにあるため、ブラウザーにも表示されます)。
  • アセンブリレベルの SheetForgePluginCompat 宣言。
  • SkillRunner(ランタイムを利用する側)、デフォルトの SheetForge.Generated 名前空間にある生成された Example* 型(分離を担っているのは、別の名前空間ではなく Example* という接頭辞です)。

  プラグインを使わない SheetForge.CoreDemo サンプルは、asmdef を 一切持たず(Assembly-CSharp にコンパイルされます)出荷されます。

関連ページ

• プラグイン作成 — 使用されている契約と、その完全な例
• オーサリングカーネル — 文脈の中でのエンジンの型
• 機能と制限 — これらの API の振る舞いの境界