スタートガイド

必要環境

• Unity 6(6000.0.79f1、URP テンプレートで開発・検証済み)。
• Addressables パッケージ(com.unity.addressables)— 必須です。 アドレスによる読み込みがランタイムの経路であり、AssetRef@Group 型は Addressables を必要とします。
  • パッケージがなくてもこのアセットはコンパイルできます。Addressables を使用するコードはすべて SHEETFORGE_ADDRESSABLES バージョン定義の内側に置かれているためです。
  • ただし、パイプライン——インポート・エクスポート・Push・オーサリングの書き戻し——は ロックされたまま になります。各エントリーポイントにインストール通知が表示され、「はじめに」ウィンドウがインストールを案内します。

Addressables のインストール

• 基本の経路: Asset Store からこのアセットをインポートすると、コンパイルの前に「Package Manager dependencies」のプロンプトが表示されます——Install を選択すれば、Addressables も一緒にインストールされます。
• セーフティネット: Skip を押した場合(または手動でインポートした場合)、パイプラインはロックされたままになりますが、「はじめに」ウィンドウ がその Addressables ステータス行からインストールを案内します。Editor は Addressables がなくてもコンパイルされるため、このウィンドウも実行されます。
  • 依存関係を持たないブートストラップウィンドウ SheetForge.Setup も、エディター読み込み時にパッケージの欠落を検知し、セッションごとに一度通知を表示します。これに依存関係がないため、他のコンパイルエラーがメインのアセンブリをブロックしている場合でも、動作し続けます。
• ワンクリックでのプログラム的インストールはありません——Asset Store の申請ルールがパッケージのプログラム的インストールを制限しているため、代わりにウィンドウが案内する形を取っています。
• この通知は実際のインストール状態を反映しています。製品自体は問題なくコンパイルされるものの、パッケージがインストールされるまで各機能はロックされたままであることを説明したうえで、そのあと「はじめに」ウィンドウへ案内します。これは Tools ▸ SheetForge ▸ Addressables Setup からいつでも再度開けます(このメニューは、他の理由でメインのアセンブリがコンパイルに失敗した場合でも生き残ります)。

以前のバージョンからのアップグレード

.unitypackage のインポートは、ファイルの追加と更新のみを行い、削除は決して行いません。そのため、新しいバージョンで廃止されたファイルが Assets/SheetForge に残り続け、もはや存在しない API を参照したままになることがあります。コンパイルが壊れ、あたかもアップグレードによってプロジェクトが壊れたかのように見えます。これに対しては、二重の安全策が用意されています:

• 自動検出。 エディターの読み込み時に、依存関係を持たないブートストラップ SheetForge.Setup が、この製品が廃止したパスをチェックします。見つかった場合は削除を提案します——ダイアログにまずすべてのパスを一覧表示し、あなたが承認するまで何にも触れません。これは、それが直そうとしているまさにそのコンパイルエラーを乗り越えて生き残れるように、専用のアセンブリの中で動作しています。
• クリーンスレート。 確実にクリーンな状態でアップグレードするには、既存の Assets/SheetForge フォルダーを削除し、新しいパッケージをインポートしたうえで、Run Import を一度実行して、削除によって失われたものを作り直してください。設定アセットとベイクされた SO(Assets/SheetForgeBaked)はそのフォルダーの外にあり影響を受けません。生成コードも、既定の場所である Assets/SheetForgeGenerated に置かれている限り同様です。プロジェクトがまだ古い製品内の場所(Assets/SheetForge/Runtime/Generated)に生成している場合、フォルダーを削除するとそのコードも一緒になくなり、再インポートが代わりに Assets/SheetForgeGenerated へ書き出します。これが既存プロジェクトを新しい場所へ移す、サポートされた方法です。どんな再インポートをもってしても作り直せないのは、あなた自身が Assets/SheetForge の中に置いたもの(そこに保存した設定アセット、自作のプラグインスクリプト、シートファイルなど)だけなので、それだけはあらかじめ外へ移動しておいてください。

はっきり述べておくべき境界が一つあります: この自動クリーンアップが削除するのは SheetForge 自身の 廃止済みファイルのみであり、あなたのファイルが削除されることはありません。あなた自身のプラグインコードが、その後廃止された契約を実装している場合は、手動で移植する必要があります。要点をまとめると:

• タブ単位のグラフビルダー(IGraphShapeBuilder / GraphSpecBuilder)は、レコードキャンバスのオーグメンター(IRecordCanvasAugmenter / CanvasAugmentBuilder)になりました。これは、全体像を一から構築する代わりに、キャンバスがすでに構築したクロージャに 追加する ものです。
• GraphMode は廃止されました。方向はいまやキャンバス自身が制御するためです。
• StudioGraphContext.ShapeId / ModeId は引き続きコンパイルは通りますが、いずれも定数を返すだけになったため、これらに対する AppliesTo の比較はすべて削除して構いません。
• IAuthorableGraphShape.CreatableTabs は変更されていません。

廃止された各契約がそれぞれ何になったかの完全な表は、CHANGELOG.md の Upgrade notes セクション(ソースリポジトリ側にのみ存在し、リリースパッケージには同梱されません)にあります。廃止されたメンバーのうち、まだコンパイルが通るものは、削除ではなく [Obsolete] としてマークされているため、アップグレード時にはビルドを壊す代わりに警告として表面化します。

「はじめに」ウィンドウ(まずはここから)

Addressables をインストールすると、「はじめに」ウィンドウ が エディターセッションごとに一度——Editor を起動するたびに開きますが、ドメインリロードのあとには再表示されません——自動的に開きます。「エディター起動時にこのウィンドウを表示」 トグルがオンになっている間は、この動作が続きます(デフォルトでオンです)。

これが推奨される入り口です。Tools ▸ SheetForge ▸ はじめに からいつでも再度開け、下部にあるこのトグルで自動表示をオフにできます(この選択はプロジェクトごと・ユーザーごとに保存されます)。

初回実行時の一連の流れを、このウィンドウひとつに集約しています:

1. ステータスダッシュボード — 三行の信号表示: Addressables のインストール状況、アクティブなインポート設定 アセットの有無、初回インポートの完了 状況。各行は ✓ または ✗ を示し、対応が必要な項目にはすぐ隣にアクションボタン(New settings asset や Run Import)が表示されます。
2. Import settings — すべての SheetForgeSettings アセットを一覧表示し、ラジオボタンで アクティブ なものを選べます。New settings asset ボタンと、各アセットの場所を特定する Reveal ボタンも備えています。
3. Examples — ワンクリックで Plugin Demo または Core Demo パッケージをインポートできます。
4. Start from a template — 組み込みの二つのテンプレートのいずれかを選ぶか、「from scratch」を選んでフィールドを自分で定義するか、あるいはプラグインが登録したテンプレートを使います。「Use」を押すと、Data Studio の作成パネルがそれで事前入力された状態で開きます。これには書き込み可能なソースを持つアクティブな設定アセットが必要です。まだ持っていない場合、その要件は表示されます。
   • 組み込みのテンプレートは、コア型のみを使う アイテム例 と、@enum シートを用意する Enum definitions です。
   • スキルデモのタブは、Plugin Demo のようなテンプレートプラグインが存在する場合にのみここに表示されます。
5. Run — Run Import(アクティブな設定を使用)と Data Studio を開く。
6. Open Full Guide — このドキュメントサイトへのリンク。

以下の各節では、それぞれのステップを詳しく説明します。すべての操作はこのウィンドウから行うことも、この後説明するメニューや Project ウィンドウから行うこともできます。

さらに手早く — ドラッグ&ドロップ。 すでにシートファイルの入ったフォルダーがあるなら、Data Studio を開いて、そのフォルダーをその上にドラッグしてください——または単一の .tsv/.csv/.xlsx ファイルでも構いません。そのフォルダーから読み込むインポート設定アセットを作成してアクティブにするかどうかを尋ねられます——手動での設定は不要です。

アクティブな設定がない状態で開くと、Studio は空のテーブルの代わりに、同じ作成 / デモインポート / 「はじめに」ボタンを備えた 「Get started」 パネルを表示します。

ヘルスチェック。 いつでも Data Studio を開き、ツールバーの ⋯ ▸ ヘルスチェック を選べば、ネットワーク不要の簡易診断が受けられます。✓/✗ で報告され、それぞれに修正案が添えられる項目は次のとおりです:

• アクティブな設定
• ソースに到達可能か(存在するローカルフォルダー、または Google の id + キーパス)
• インポートの baseline が存在するか
• 生成コード・ベイクされた SO・addressables が最新かどうか

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

1. インポート設定アセットを選ぶ

「はじめに」ウィンドウの New settings asset ボタンから作成するか、Project ウィンドウで右クリック → Create ▸ SheetForge ▸ Import Settings で作成します(メニューのラベルは言語設定に従います——ローカライズ を参照)。

複数の設定アセットを保持しておくこともできます(たとえばデータソースごとに一つずつ)。その中からどれを アクティブ にするかを選べます。メニュー・Data Studio・インポートは、いずれもそのアクティブな設定を使用します。この選択は プロジェクトごと・ユーザーごと に保存され(EditorPrefs のポインターなので VCS には影響せず、チームメイトごとに独立しています)、アクティブなアセットが削除された場合、このポインターは自己修復します。

設定アセットが 一つだけ の場合、最初のインポートでそれが自動的に選択されます——明示的な選択は不要です。複数 存在する場合は、「はじめに」ウィンドウで、または Data Studio のツールバーに表示されるドロップダウンからアクティブなものを選んでください。

SheetForgeSettings アセットを設定します:

設定のインスペクターは、現在のソースモードに関係するフィールドだけ を表示します——Local モードでは Google 用の入力欄が隠され、gidMap は Google ExportUrl モードのときにのみ表示されます。

2. サービスアカウントキーのセキュリティ(Google ソース)

LocalFile ソースを使っていますか? この節は読み飛ばして構いません。

SheetsApi モードで Googleシートを使うには、サービスアカウントの JSON キーが必要です。まだ作成したことがない場合は、Googleシートの設定 が全工程を順を追って説明します。このキーは Assets/ の外、かつリポジトリの外に置いてください——絶対にコミットしないでください。

• 推奨: 環境変数 SHEETFORGE_SHEETS_KEY に、キーファイルの絶対パスを設定してください。これは設定アセットのキーパスフィールドよりも 優先 されるため、各開発者はリポジトリにパスを残すことなく、自分のローカルキーを注入できます。
• 設定フィールドにパスを書かざるを得ない場合は、リポジトリの外 を指すようにしてください(例: C:/keys/service-account.json)。Assets/ 配下のキーファイルは、ビルドやコミットに漏れ出してしまいます。

3. 最初のインポートを実行する

Tools ▸ SheetForge ▸ Data Studio を開き、ツールバーの ↓ Pull from source を押します。

• パイプラインは 取得 → 検証 →(成功したら)コード生成 → ベイク、の順に進みます。診断情報は、あなたの言語で人間に読みやすいレポートとしてコンソールに出力されます。
• 最初のインポートは、内部的に二つの段階を自動的に経て完了します。 スキーマが新規または変更されている場合、インポートは生成コードを書き出し、それがコンパイル/ドメインリロードを引き起こします——そしてリロード後、ベイクが自動的に再開されます。ユーザーの操作は一回だけで、手動での再実行は不要です。コンパイルが失敗した場合、自動再開は安全に中断し(試行上限3回)、コンソールに実行可能な文を残します。
• 検証はインポート時に すべて の診断情報を収集します(最初のエラーで止まることはありません)。一つでもエラーがあれば、出力は生成されません(部分的な組み立てはありません)。
• インポートは各タブの Database SO を、Addressables グループ SheetForge のアドレス "SheetForge/{tab}" に自動登録します——ゲームはその安定したアドレスで読み込みます(コアコンセプト を参照)。

4. ゲーム内でデータを読み込む

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

SheetForge.Runtime アセンブリは autoReferenced なので、ゲームコードは asmdef の参照なしにこれを利用できます。

ベイクされた SO をシーンから直接参照してはいけません。 ベイクされた SO はコミットされない、マシンごとのキャッシュです——GUID はマシンや再ベイクのたびに変わるため、シーンから直接参照すると、チームメイトのマシンでは Missing になってしまいます。アドレスによる読み込みは、この問題を設計上吸収します。

5. デモシーンを試す

二つのサンプルが 選択的にインポートするパッケージ として同梱されています。プラグインのサンプル SheetForge.PluginDemo(カスタム型、enum、バリデーター、エッジ)と、プラグインを使わない SheetForge.CoreDemo(コアの組み込み型のみ)は、それぞれ「開いて Play するだけ」のデモシーンを含んでいます。

デモのインポートは 一箇所——「はじめに」ウィンドウの Examples セクション——に集約されており、そのためのメニュー項目はありません。

• プラグインデモ: 「はじめに」で プラグインデモをインポート を押すか、Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage をダブルクリックします。どちらも Assets/SheetForge.PluginDemo/… の下に復元されます。シーン: Demo/PluginDemo.unity(メニュー Tools ▸ SheetForge ▸ Open Plugin Demo Scene、サンプル自身が追加します)。サンプルのデータベースを アドレスで 読み込み、シートのデータから組み立てられたスキルを表示します(fireball の合計ダメージ = Damage 10 + DamageOverTime 3×3 = 19)。
• コアのみのデモ: 「はじめに」で コアデモをインポート を押すか、Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage をダブルクリックします。Assets/SheetForge.CoreDemo/… の下に復元されます。シーン: Demo/CoreDemo.unity(メニュー Tools ▸ SheetForge ▸ Open Core Demo Scene)。コアの組み込み型のみを使い、アイテム参照から組み立てられたロードアウトを表示します。 このデモにはローカライズシート(ExampleStrings)も含まれており、アイテムが LocRef セルでそのキーを参照します — ローカライズシート を参照。

(これらのサンプルメニューの末端ラベルは、コアのローカライズ済みメニューパイプラインの外にあるため、英語のままです。)

各デモパッケージは、事前設定済みの設定アセットを同梱しています。 デモパッケージをインポートすると、あなた自身のアクティブな設定を持っていない場合に限り、SheetForge はその同梱の設定アセットを自動的にアクティブ化します。すでに持っている場合は、あなたの選択をサイレントに上書きする代わりに、「はじめに」ウィンドウが開いて切り替えを提案します。つまりデモの流れは単純です: パッケージをインポート →(設定が自動でアクティブ化される)→ Run Import → Play——手動での設定作成は不要です。

デモは、あなたのマシンで一度インポートを実行した後にのみ動作します。 デモが読み込む Addressables アドレスは、インポートが一度実行された後にのみ存在します(Addressables グループアセットはコミットされない、自己修復型のキャッシュです)。それまでの間、デモシーンは失敗する代わりにガイダンスメッセージを表示します。

デモを完成させるには(上記のサンプルパッケージをインポートした後で):

1. デモに同梱されている設定アセットがアクティブになっていることを確認してください(「はじめに」ウィンドウに表示されるか、インポートが自動でアクティブ化しています)。これは source = LocalFile、local folder = サンプルの DemoSheets フォルダー、そしてデフォルトの SheetForge.Generated 名前空間を使うため、再インポートするとコミット済みの型がそのまま再生成されます。
2. プラグインデモのスクリプト参照については、何も操作する必要はありません。 ExampleEffects タブには AssetRef@Scripts の例が含まれています。サンプル自身が DemoScripts/special_effect.lua.txt を Scripts Addressables グループのアドレス special_effect として、べき等に自動登録します——そのため最初のインポートは参照検証を通過します。登録できなかった旨の警告(たとえばアセットが見つからない場合など)が出たときにだけ、その項目を手動で追加してください——あるいは、この Addressables の例が不要であれば、その行を削除してください。
3. Tools ▸ SheetForge ▸ Data Studio で ↓ Pull from source を一度押し(または「はじめに」ウィンドウの Run Import ボタン)、デモシーンを開いて Play を押してください。

6. チームのワークフローまとめ

• ベイクされた SO(Assets/SheetForgeBaked)は マシンごとのキャッシュ です。gitignore の対象にしてください。クローン後、各チームメイトが一度 Run Import を実行します。
• 生成コード(Assets/SheetForgeGenerated)はプロジェクト自身のソースであり、コミットすることを推奨します。そうすれば、誰かがインポートを実行する前から新規クローンがコンパイルでき、スキーマの変更もレビューにそのまま現れます。これは決定的な(deterministic)出力なので、チームメイトのインポートも同じバイト列を生成し、差分によるノイズを生みません。代わりに gitignore する方法も引き続き有効です——その場合は、クローン後の Run Import がコンパイルを回復させる役目を果たします。
• ビルド前の鮮度チェックフック が、コミットされている生成 Database 型ごとに (i) ベイクされた SO が存在するか、(ii) スキーマフィンガープリントが baseline と一致するか、(iii) Addressables への登録が存在するか、を確認します。何か一つでも失敗すれば、実行可能な文とともにビルドは中断されます。これにより、クローンした環境や CI マシンが、空のキャッシュを気づかぬまま出荷してしまうことは決してありません。

関連ページ

• コアコンセプト — シートが正規である理由と、パイプラインの各段階
• シート構文 — 最初のシートの書き方
• ソース・エクスポート・プッシュ — Google の設定詳細
• FAQ とトラブルシューティング — 初回実行時の問題