FAQ とトラブルシューティング

症状を起点にした回答です。どのインポートエラーにも、コンソールレポート内にそれ自体のどこで/何が/なぜ/どうすればよいかという文が付いています——まずはそこから確認してください。

セットアップと初回実行

「Addressables なしでアセットをインポートした——コンパイルはできる? なぜインポートがロックされているのか?」

このアセットは Addressables なしでもコンパイルできます(Addressables を使用するコードは、SHEETFORGE_ADDRESSABLES バージョン定義の内側に保護されています)。アドレスによる読み込みと AssetRef@Group 型には com.unity.addressables が必要なため、パイプライン全体(インポート・エクスポート・Push・書き戻し)は インストールするまでロックされます——各エントリーポイントにインストール通知が表示され、処理が止まります(部分的な実行はありません)。

Package Manager から com.unity.addressables をインストールしてください。「はじめに」ウィンドウの Addressables 行には Open Package Manager ボタンがあり、Editor がそのパッケージなしでもコンパイルできるため、そのウィンドウは Safe Mode にブロックされることなく正常に実行されます。

インストール後もコンパイルエラーが残る場合、それはプロジェクト内の他のコードに起因します——SheetForge は、パッケージがあってもなくてもコンパイルできます。

「新しいバージョンにアップデートしたら、プロジェクトがコンパイルできなくなった。」

.unitypackage のインポートは、ファイルの追加と更新は行いますが、削除は決して行いません。そのため、この製品が後のバージョンで廃止したファイルが残り続け、もはや存在しない API を参照したままになることがあります。

エディターの読み込み時に、依存関係を持たないブートストラップ SheetForge.Setup が、既知の廃止済みパスを検知し、その削除を提案します——何にも触れる前に、まずすべてのパスを一覧表示します。ダイアログを承認すれば、コンパイルは回復します。これは専用のアセンブリの中で動作しているため、メインのアセンブリが失敗している間も動作し続けます。このプロンプト自体を完全にスキップするには、新しいパッケージをインポートする前に Assets/SheetForge フォルダーを削除してください。

これがカバー しない のは、その後廃止された契約に対して書かれた、あなた自身のコードです。それは、CHANGELOG.md(ソースリポジトリ側 にのみ存在し、リリースパッケージには同梱されません)の Upgrade notes 表を使って、手動で移植してください——スタートガイドに、その内容の要約があります。

「Create Sheet には組み込みのテンプレートしか表示されない——skills デモのテンプレートはどこ? / 独自のものを追加するには?」

組み込みの Create Sheet 一覧には、二つのテンプレート——アイテム例(コア型のみ) と、@enum シートを用意する Enum definitions——に加えて「from scratch(ゼロから)」が同梱されています。

プラグインを必要とするドメインテンプレート(skills デモなど)は、そのプラグイン 自身によって 登録されるため、プラグインが存在するときにのみ表示されます。Plugin Demo パッケージをインポートすると、その Skill demo テンプレートが表示されます。あなた自身のものを提供するには、ISheetForgeTemplatePlugin を実装してください——プラグイン作成 §4.6 を参照してください。

「どこから始めればいいのか? / Editor を開くたびにウィンドウが開き続ける。」

それは 「はじめに」 ウィンドウです。Editor が最初に読み込まれたときに自動的に開き、推奨される入り口となります——Addressables の状態、アクティブな設定アセットの選択、サンプルのインポート、最初のインポートの実行が、すべて一つの場所にまとまっています。

下部の 「エディター起動時にこのウィンドウを表示」 トグルで自動表示をオフにでき、Tools ▸ SheetForge ▸ はじめに からいつでも再度開けます。

「デモパッケージをインポートしたが何も起きない——設定アセットも addressable グループも存在しない。」

各デモパッケージは 事前設定済みの設定アセットを同梱しており、パッケージをインポートすると それが自動的にアクティブ化されます(あなた自身のアクティブな設定を持っていない場合に限ります)。すでに持っている場合は、あなたの設定をサイレントに変更する代わりに、「はじめに」ウィンドウが開いて切り替えを提案します。

そのあと Tools ▸ SheetForge ▸ Data Studio で ↓ Pull from source を一度押せば、addressable グループとタブごとのアドレスが自動的に作成されます。流れ: パッケージをインポート →(設定が自動でアクティブ化される)→ Run Import → Play。

「デモシーンが、デモの代わりにただのテキストメッセージを表示する。」

デモは Addressables アドレスで読み込まれますが、そのアドレスは あなたのマシンで一回インポートを実行した後 にのみ存在します(グループアセットはコミットされない、自己修復型のキャッシュです)。デモパッケージをインポートし(その設定は自動でアクティブ化されます)、Run Import を一度実行してください——スタートガイド §5 を参照してください。

(デモのコミット済みの型は、デフォルトの SheetForge.Generated 名前空間を使うため、generatedNamespace の設定は不要です——再インポートすればそのまま再生成されます。)

「プラグインデモの最初のインポートが `UnknownAssetGroup 'Scripts'` で失敗する。」

プラグインデモには List<AssetRef@Scripts> 型の script 列があり、これには Scripts という名前の Addressables グループが必要です。Addressables グループはマシンごとのもの(コミットされません)であるため、インポートしたばかりのデモにはまだそれが存在しません。

デモは、インポート時にそのグループを 自動的に設定します(PluginDemoAddressableSetup、ドメインリロード時とデモシーンを開いたときに発火します)。そのため、通常のインポートはそのまま機能します。それでもエラーが出る場合は、デモシーンを再度開いて(Tools ▸ SheetForge ▸ Open Plugin Demo Scene)セットアップを発火させ、その後再インポートしてください。

これはプラグインデモにのみ当てはまります——あなた自身の AssetRef@… グループは、あなた自身が登録するものです。

「複数の設定アセットがある場合、どれが使われるのか?」

アクティブ なもの一つです。メニュー・Data Studio・インポートは、いずれもアクティブな設定アセットを使用します。「はじめに」ウィンドウ、または Data Studio のツールバーのドロップダウン(複数存在するときのみ表示されます)で選んでください。

設定アセットが一つだけの場合は、最初のインポートで自動的に選択されます。この選択はプロジェクトごと・ユーザーごとに保存され(EditorPrefs のポインターなので VCS には影響しません)、アクティブなアセットが削除された場合は自己修復します。

「すでにシートの入ったフォルダーがある——SheetForge にそれを最速で指定する方法は?」

Data Studio を開き、そのフォルダー(または単一の .tsv/.csv/.xlsx ファイル)をその上にドラッグしてください。

そのフォルダーから読み込むインポート設定アセットを作成してアクティブにするかどうかを尋ねられます——手動でのフィールド入力は不要です。すでにアクティブな設定がある場合は、ダイアログがその旨を伝え、切り替えを提案します。

「プロジェクトが正しく設定されているか確認したい / なぜインポートが実行できないのか?」

Data Studio ツールバーの ⋯ ▸ ヘルスチェック を選んでください。次について ✓/✗ と修正案を報告します:

アクティブな設定
ソースへの到達可能性 — 存在するローカルフォルダー、または Google の id + サービスアカウントキーパス。ネットワーク呼び出しはありません
インポートの baseline
生成コード/ベイク/addressable の鮮度

結果はコンソールとサマリーダイアログの両方に表示されます。

「メニューや UI が、選んだ覚えのない言語で開いた。」

プロジェクトを初めて開いたとき、SheetForge はあなたの Editor の システム言語 から UI 言語を設定します(九つの言語がマッピング対象で、それ以外は英語になります)。あなた自身が設定した言語を上書きすることは決してありません。変更はいつでも Preferences ▸ SheetForge から行えます——ローカライズを参照してください。

(言語の変更は、メニューラベルが再生成されるため、短い再コンパイルを一回引き起こします。)

「リポジトリをクローンしたら、シーンのベイクされた SO への参照が Missing になっている。」

それは想定どおりです: ベイクされた SO は、マシンごとの GUID を持つ、マシンごとのキャッシュです。シーンから直接参照してはいけません——アドレスで読み込んでください(SheetForgeDatabases.LoadAsync("Tab"))。Run Import を一回実行して、ローカルのキャッシュを再構築してください。

「SheetForge のメッセージとともに、ビルドが中断された。」

それは、空/古いキャッシュを出荷してしまうことからあなたを守っている、ビルド前の鮮度チェックフックです。その文が言うとおりにしてください——Tools ▸ SheetForge ▸ Data Studio で ↓ Pull from source を押し——もう一度ビルドしてください。

インポートと検証

「インポートは実行され、エラーも見つかったが、何も出力されなかった。」

これは設計どおりです: 一件でもエラーがあれば ⇒ 出力なし(部分的な組み立てはありません)。レポートには、座標と修正案付きで すべての 問題が列挙されています——それらを一度にまとめて直し、再インポートしてください。これによって作業が失われることは決してありません。シートには手が加えられていないからです。

「エラーが指しているセルへ、直接ジャンプできるか?」

できます。人間に読みやすいコンソールレポート内の各エラーには、クリック可能な 「Open in Data Studio」 リンクが付いています。クリックすると Data Studio が開き、そのタブに切り替わり、そのセルがハイライトされます(ファイル/タブレベルのエラーでは、タブにフォーカスするだけです)。マシン可読な座標行は変わらないため、CI/ログのスクレイピングには影響しません。

「インポートがコードを書き出し、再コンパイルされた……これで完了したのか?」

はい、完了しています——スキーマが新規/変更されている場合、インポートは内部的に二段階です(コード生成 → コンパイル/リロード → ベイク)。ベイクは、リロード後に 自動的に再開されます。最終的なレポートについては、コンソールを確認してください。

もしあなたのゲームコードがコンパイルできなくなっていたら(例えば、列の名前変更の後など)、チェーンは実行可能な文とともに安全に中断します。コードを修正し、もう一度インポートしてください。

「空セルのエラーが出たが、そのセルは任意にしたかった。」

無印の型は必須です(サイレントな汚染を防ぐガードです)。セルを任意にするには:

float? と宣言する — 型のデフォルト値
int=1 と宣言する — 明示的なデフォルト値
または List<T> を使う。空セルは空リストになります

シート構文を参照してください。

「`1.5` は問題なくインポートできるのに、`1,5` はエラーになる。」

これは意図的なものです: 数値はロケールに依存しません——小数点は常に . です。カンマ区切りの小数、NaN、Infinity は入口でブロックされます。

「インポートが急にとても遅くなった。」

インポートの所要時間は、データの規模に対して線形です(50k 行 × 20 列でエディター上約 628 ms)。参照が一斉に大量に壊れた場合でも線形のままです——最も近い候補の検索は、フィールドごとに予算が設けられ、長さによる事前フィルタリングも行われます(壊れた参照 4,000 件で約 45 ms、ヘッドレス)。

インポートが急にそれよりずっと時間がかかるようになった場合、見るべきはエラー件数ではなく、シートの規模です。

「未知のマーカー / 未知の型のエラーに、『もしかして』というヒントが付いている。」

@marker 名、型名、enum メンバーのタイプミスは、最も近い候補の提案付きの エラーになります——その提案を適用してください。未登録の型名に付いた未知の @ もエラーです(RecordId@Tab 形式の参照に対するタイプミスの安全性です)。

Googleシート

「Google のインポートが `PERMISSION_DENIED`(403)で失敗する。」

そのスプレッドシートは、サービスアカウントの client_email アドレスと共有されていません——キーだけでは何の権限も得られません。JSON キーを開いて client_email をコピーし、そのアドレスとシートを共有してください(インポートには Viewer、Push には Editor)。全工程は Googleシートの設定にあります。

「Push が SheetsApi を要求していると言われる。」

あなたは、読み取り専用の(認証なしの)ExportUrl モードにいます。何らかの書き戻しには、サービスアカウントキーを使った SheetsApi モードが必要です。ソース・エクスポート・プッシュを参照してください。サービスアカウントとキーの作成方法は、Googleシートの設定で扱っています。

「ExportUrl のインポートが、gid マップを求めて失敗する。」

これは必須です: gid のないエクスポート URL は、サイレントに最初のタブだけを返してしまうため、マップ(タブ名 → #gid=)が強制されます。あるいは、マップが不要な SheetsApi モードに切り替えてください。

「Push が、スキップされたセルを報告してきた。」

送信前のライブ再取得が、競合を発見しました(チームメイトがセルを編集した、行が移動/消失した、キーが重複していた、など)。スキップされたセルは失敗ではなく保護です——レポートには適用/スキップの件数が表示されます。再インポートして整合性を取り、もう一度 Push してください。

「ローカルで行を削除したのに、Push 後も Googleシートにはまだ残っている。」

行の削除は決して Push されません(本番シートに対する位置ベースの削除は安全ではないためです)——代わりに通知が届きます。シート側で行を削除し、その後再インポートしてください。

オーサリング

「Ctrl+Z で、保留中の変更が元に戻らない。」

境界は二つあります:

フォーカスされたテキストフィールドが Ctrl+Z を先に消費します——他の場所をクリックしてから undo してください。
「シートに反映」が成功した後は、ステージングの履歴がクリアされます——undo は反映前のセッション内でのみ機能します。

反映後は、シートを編集してください(シートが正規です)。

「保留中の編集の一部に『isolated』バッジが付いていて、反映されなかった。」

ステージングと反映の間に、シートが外部で変更され、それらの編集の論理アドレスが破綻しました(行のキーが外部で名前変更された / 行が削除された / キーが競合した)。それらは除外されます——サイレントに失われるのでも、残りをブロックするのでもありません。個別に破棄し、新しい baseline に対して再度ステージングしてください。

「列/タブの名前を変更したら、ゲームコードがコンパイルできなくなった。」

これは想定どおりで、確認ダイアログでも開示されています: 名前変更は、生成されるフィールド/クラス名を変更します。あなたのゲームコードを更新してください。インポートチェーンは、次の実行で完了します。列のデータの値は完全に保持されていました。

「二つのタブ名を入れ替えたり(A↔B)、循環的にタブの名前を変更したりを、一つのバッチでできるか?」

できます——相互の入れ替えや循環(A→B→C→A)は、一つのバッチでステージングして反映できます(UI が却下するのは、二つの名前変更が同じ名前を対象にしているという 本物の 競合の場合だけです)。参照はデータに追従し、アトミックに書き換えられます。

Google に関しては、一つだけ限界が残っています: 互いを 参照している、入れ替えられた 二つのタブは、向き先を変更されません(ローカルは完全に正しく処理します)。相互参照を第三のタブ経由にするか、中間の名前を介して反映してください。Data Studio と機能と制限を参照してください。

「キーの名前を変更したのに、同じバッチ内で入力した参照が更新されなかった。」

伝播が書き換えるのは baseline のセルだけです——たった今入力したテキストが書き換えられることは決してありません(入力したばかりの内容がサイレントに書き換えられることはありません)。事前検証が、宙に浮いた参照にフラグを立てます。自分で修正してください。

「xlsx のタブが原因で、反映が拒否された。」

既知のケースが二つあります:

xlsx 由来のタブはタブの名前変更ができません(ワークブックの保護のため)。
xlsx タブに触れることになるキー名変更の伝播は、バッチ全体をブロックします(部分的な反映はありません)。

ワークブックを直接編集し、その後再インポートしてください。

「インスペクターでベイクされた SO を編集したら、再インポートでそれが消された。」

これは設計どおりです——シートが唯一の信頼できる情報源であり、SO はキャッシュです。インスペクターの「テスト編集」トグルは、明示的に一時的なものです。本当の変更は、シートまたは Data Studio を通じて行ってください。

エクスポートとその他

「Export がスキーマの不一致で失敗する。」

あなたのベイクは、スキーマ変更に対して古くなっています(ExportSchemaMismatch — フィンガープリントのチェックです)。インポートを実行してコード生成 + ベイクを完了させ、その後 Export/Push してください。

「エクスポートした float が `1` になっているが、シートには `1.0` と書いてあった。」

意味的なラウンドトリップです: 値は正確に保持され、表記は最短のラウンドトリップ形式に正規化されます。構造(マーカー、列の順序、コメント、あなたのテキスト)は 100% 保持されます。

「xlsx のインポートが、一部のセルを却下した。」

組み込みの OOXML リーダーは、意図的に最小限に留められています。サポートされていないものが三つあります:

キャッシュされた値を持たない数式セル
エラーセル
セル内のタブ文字/改行

数式は値として実体化し、リストには ; を使ってください。