GUI でのプロジェクト管理 (Managing Projects in the GUI)
プロジェクト (Project) は、ファイルの保存先や使用するノードライブラリ、エンジンバージョンを Griptape Nodes に指示する保存済み設定環境です。プロジェクトを切り替えると、レンダリング画像やダウンロードの保存先、表示されるワークフロー一覧、利用可能なノードライブラリなど、作業に関わるコンテキスト全体がそのプロジェクト向けに切り替わります。
このページでは、GUI から実行可能なすべてのプロジェクト管理タスク（プロジェクトの切り替え、新規作成、表示と編集、削除、エクスポート/インポート）について解説します。プロジェクトの概念（ファイル形式、マクロ、バージョン固定など）については、プロジェクトシステムの概要 を参照してください。
このページで解説するすべての操作は、Project Management ウィンドウ内で行います。上部メニューバーから開きます：Manage → Project Management。
Project Management ウィンドウ
Project Management ウィンドウを開くと、まず プロジェクトリスト が表示されます。プロジェクトはツリー構造で表示され、子プロジェクトは親プロジェクトの下にインデント（ネスト）されて配置されます。現在アクティブなプロジェクトには Active バッジが付きます。
右上隅にある 2 つのボタンから、プロジェクトをリストに追加できます：
- Register Template…: ディスク上にすでに存在するプロジェクトファイルを指定してリストに追加します。
- Create New Template…: 完全に新しいプロジェクトをゼロから作成します。
リスト内の任意のプロジェクトをクリックすると、その詳細ビューが開き、設定内容の確認や編集が行えます。
プロジェクトの切り替え (Switching projects)
プロジェクトの切り替えは最も頻繁に行う操作です。Project Management ウィンドウから切り替えることも可能ですが（プロジェクトをクリックして Activate を押す）、最も素早い方法はワークフロー選択画面にある プロジェクトピッカー を使用することです。
ピッカーには、現在アクティブなプロジェクト名が表示されています。クリックして展開するとリストから別のプロジェクトを検索・選択でき、チェックマークで現在のアクティブプロジェクトが示されます。
別のプロジェクトを選択すると、確認ダイアログが表示されます。どのプロジェクトからどのプロジェクトへ移動するかが明示されます。
プロジェクトの切り替えによってエンジンが再読み込みされます。 現在開いているアクティブなワークフローはまず閉じられ（未保存の変更がある場合は保存を促すプロンプトが表示されます）、ワークフローリストが再読み込みされて新しいプロジェクトのワークフローが表示されます。切り替え完了後、新しいプロジェクトからワークフローを開いて作業を継続してください。
切り替え先のプロジェクトが特定のライブラリバージョンを固定している場合は、まず プロビジョニングプレビュー (provisioning preview) が表示され、切り替えが実行される前に、どのライブラリがインストールまたは変更されるかを確認（および承認）できます。
Switching to
プロジェクトの新規作成
Create New Template… をクリックして New Project Template ダイアログを開きます。ほとんどのプロジェクトでは名前を入力するだけで十分であり、その他の項目には適切なデフォルト値が設定されています。
上部のサブタイトルには「Creating a new project template inside Default Project」のように表示されます。この強調表示されている名前が 保存場所 (Location) です：新しいプロジェクトがどのプロジェクトのフォルダ内に保存されるかを選択するピッカーです。デフォルトでは現在アクティブなプロジェクト（または Default Project）になります。クリックして別の場所を選択できます。
基本項目を入力します：
- Project Name: GUI の至る所で表示される人間可読の名前。このフィールドのみが必須です。
- Description: プロジェクトの目的を記述する任意のメモ。
- Location: プロジェクトファイル（
griptape-nodes-project.yml）が書き込まれる場所。デフォルトでは選択した場所にリンクされ、your-project-name/griptape-nodes-project.ymlで終わる読み取り専用パスとして表示され、名前を入力するにつれて自動更新されます。パスを手動で指定したい場合はパスをクリックします（またはフォルダボタンで参照）。Reset をクリックするとデフォルトの連動状態に戻ります。
高度な設定 (Advanced Settings)
ほとんどのクリエイターはここを変更する必要はありません。Advanced Settings を展開すると以下の項目が表示されます：
- Project ID: プロジェクトの一意で恒久的な識別子。プロジェクト名に短いランダムなサフィックスを付与して自動生成され、基本的にはそのままにしておきます。クリックして自身で入力することも可能です（小文字、数字、ダッシュのみ使用可能で、一意である必要があります）。作成後に ID を変更することはできません。
- Inherits settings from: 親プロジェクト。子プロジェクトは親プロジェクトの設定をベースとして開始され、変更した部分のみを保持します。これはデフォルトで保存場所と連動しているため、場所を選ぶと自動的に親も設定されます。継承を行いたくない場合はここで Default Project を選択してください。継承の仕組みについては プロジェクト を参照してください。
- Workspace directory: 新しいプロジェクトがワークフローや生成ファイルを保持する場所。新しいプロジェクトでは自己完結性を保つためにデフォルトで
./（自身のフォルダ）になります。別の場所を指定するか、親プロジェクトからワークスペースを継承する場合は空欄にします（最新スキーマのプロジェクトでのみ表示されます。スキーマバージョン を参照）。
Create をクリックします。進捗パネルが表示され、プロジェクトの保存、エンジンへの登録、アクティベーション、仕上げ処理のステップが順次実行されます。プロジェクトを作成するとそれが直ちにアクティブプロジェクトになるため、エンジンが再読み込みされます（切り替え時と同じ再読み込みです）。未保存のワークフローを開いている場合は、先に保存を促されます。
保存場所または親プロジェクトが特定のライブラリバージョンを固定している場合、切り替え時と同様の プロビジョニングプレビュー が表示され、新しいプロジェクトがアクティブになる前にライブラリを確認・承認できます。
準備が整うと Project created 確認メッセージが表示されます。
プロジェクトの表示と編集
リスト内のプロジェクトをクリックして詳細ビューを開きます。ヘッダーには、プロジェクト名、ファイルパス（コピー用ボタン付き）、および Active や Unsaved changes（未保存の変更）のバッジが表示されます。
名前の隣にある鉛筆アイコンをクリックして、名前 (name) と 説明文 (description) をインラインで編集できます。
Inherits from ドロップダウンで親プロジェクトを設定（または解除）できます。詳細ビューには、以下の編集可能なセクションも表示されます：
ワークスペースディレクトリ (Workspace directory)
Workspace dir フィールドは、このプロジェクトの作業ルートとなるフォルダを設定します：相対パス、出力、ダウンロードが解決される基準となるフォルダです。これはワークスペースを選択するための最も優先度の高い方法であり、ユーザー別設定やグローバル設定を上書きします。
空欄のままにしておくと、エンジンが設定から算出したワークスペースが使用されます。空欄の場合、フィールドには算出された (calculated) パスが薄いグレーのプレースホルダーテキストとして表示されるため、設定を変更しなくても作業ファイルがどこに保存されるかを確認できます。明示的にパスを入力して固定することも、フォルダボタンをクリックして参照することも可能です。ディレクトリと同様に、Linux、macOS、Windows で異なるパスを指定するためのプラットフォーム別トグルも備えています。
完全なリファレンスについては、ワークスペースディレクトリ および ワークスペース を参照してください。
ライブラリディレクトリ (Libraries directory)
Libraries dir フィールドは、ワークスペースとは別に、このプロジェクトがライブラリをインストールおよび解決する場所を設定します。関連する複数のプロジェクト間で、各自が個別に再ダウンロードする代わりに 1 つのライブラリインストール場所を共有したい場合に使用します。
空欄にしておくと、親プロジェクトのライブラリディレクトリを継承し、上位で何も指定されていない場合はワークスペース内の libraries フォルダへとフォールバックします。新しいトップレベルプロジェクトには、子プロジェクトがデフォルトでその共有場所を継承できるように ./libraries が事前入力されます（子プロジェクトは空欄で作成されます）。特定の場所を指定するか、フォルダボタンで参照できます。ワークスペースフィールドと同様に、OS ごとのパスを指定するプラットフォーム別トグルが用意されています。
完全なリファレンスについては、ライブラリディレクトリ を参照してください。
ディレクトリ (Directories)
Directories は、短い論理名（outputs など）を実際のフォルダパスに対応付けます。ワークフローやノードはその論理名を参照し、プロジェクトが実際の配置場所を決定します。Add Directory で新しいディレクトリを作成でき、行のプラットフォーム別トグルを使用して OS ごとに異なるパスを指定できます。
完全なリファレンスについては、ディレクトリ を参照してください。
拡張子別ディレクトリ (File Extension Directories)
File Extension Directories は、拡張子に基づいてファイルをフォルダに自動分類します（例: png → images、mp4 → videos）。セクションを展開してマッピングを追加または編集します。
完全なリファレンスについては、拡張子別ディレクトリ を参照してください。
環境 (Environment)
Environment は、このプロジェクトが提供するカスタムのキー・バリュー変数セットです。プロジェクト内の他の場所から参照できます。Add Variable を使用して追加します。
完全なリファレンスについては、環境と組み込み変数 を参照してください。
シチュエーション (Situations)
Situations は、名前付きのファイル保存シナリオです（ノードの出力保存、URL からのダウンロードなど）。各シチュエーションはパステンプレート（マクロ）と同名ファイルがすでに存在する場合の処理ポリシーを持ちます。Add Situation で新しいシチュエーションを定義します。
完全なリファレンスについては、シチュエーション を参照してください。
保存、検証、再読み込み
詳細ビュー上部のツールバーには、編集中のプロジェクトに対する各種アクションが配置されています：
- Validate: 保存せずにプロジェクトに問題がないか検査します。問題点があればフィールドと説明が一覧表示され、問題がなければ Template is valid と表示されます。
- Reload from Disk: 画面上での編集を破棄し、ディスク上に保存されている状態に再読み込みします。
- Save Changes: 編集内容をプロジェクトファイルに書き込みます（未保存の変更がある場合のみ有効）。
- Upgrade schema: プロジェクトがエンジンの現在バージョンより古いスキーマバージョンである場合にのみ表示されます。後述の プロジェクトスキーマのアップグレード を参照してください。
- Back to Projects: プロジェクト一覧に戻ります。未保存の変更がある場合は、破棄する前に確認ダイアログが表示されます。
プロジェクトが特定のライブラリバージョンを固定している場合、Library Pins パネルにそれらの固定情報が表示されます。
プロジェクトスキーマのアップグレード
プロジェクトが、エンジンに同梱されているものより古いメジャースキーマバージョンで作成されている場合（例えば、現在のエンジンが 1.x スキーマであるのに対して 0.x プロジェクトである場合）、ツールバーに Upgrade schema ボタンが表示されます。アップグレードすると、プロジェクトが最新のデフォルトをベースにリベースされます：明示的にカスタマイズした設定は維持され、古いデフォルトのままにしていた設定はすべて新しいデフォルトに更新されます。
これは破壊的変更 (breaking change) です — プロジェクトがワークスペース、ライブラリ、および保存ファイルを解決する場所が変化する可能性があるため、自動的に実行されることは絶対にありません。書き込みを行う前に確認ダイアログで影響が明示され、キャンセルすることも可能です（古いバージョンのまま使用し続けることも完全にサポートされています。新しい動作を希望する場合にのみアップグレードしてください）。
未保存の変更がある間はボタンが無効化されます — アップグレードはディスクからプロジェクトを再読み込みするため、先に保存するか再読み込みを実行してください。
既存プロジェクトの登録
チームで共有されたプロジェクトファイルなどがディスク上にすでに存在する場合は、プロジェクトリストで Register Template… を使用し、該当する griptape-nodes-project.yml を指定すればリストに追加されます。追加後は他のプロジェクトと同様にアクティベート、表示、編集が可能です。
プロジェクトの削除
リストからプロジェクトを削除するには、プロジェクトを開いてゴミ箱アイコンをクリックするか、リスト上の行にあるゴミ箱アイコンをクリックします。Remove Template ダイアログで確認します。
削除操作はプロジェクトの登録を解除するだけです。 ディスク上のプロジェクトファイル自体が削除されることはありません。後から Register Template… で再度登録できます。
プロジェクトのエクスポートとインポート
プロジェクトを単一の .zip ファイルにパッケージングして、別のマシンへ移動したり、チームメンバーに渡したり、バックアップとして保管したりできます。パッケージにはプロジェクトファイルとともに依存するライブラリもバンドルされるため、受け取り先で手動セットアップを行うことなくすぐに動作します。
シークレットの値がパッケージに含まれることは絶対にありません。 API キーなどは名前のみが参照されます。インポート後、自身で Settings からそれらのシークレットを設定します。インポートダイアログに設定が必要なキーが正確にリストアップされます。
プロジェクトのエクスポート
プロジェクトリストの各プロジェクト行に、小さなパッケージアイコンが表示されています。クリックして保存先フォルダを選択すると、Griptape Nodes はそこに <project-name>.zip を書き出します。パスを示す確認画面が表示され、プロジェクトがシークレットに依存している場合は、パッケージをインポートするユーザーが提供すべきシークレットキー名も一覧表示されます。
プロジェクトのインポート
プロジェクトリストの右上にある Import Project… をクリックし、.zip パッケージを選択します。解凍が開始される前に、Import project ダイアログに中身が表示されます：
- Package: プロジェクトの元の名前。
- New project name（任意）: インポートしたコピーの名前を変更します。空欄のままにすると元の名前が維持されます。プロジェクトの分岐や複製作成に便利です。
- Libraries: バンドルされている各ライブラリ。bundled（完全なコピーがパッケージ内に同梱）または referenced（インポート時に再ダウンロード）としてタグ付けされます。
- Secrets to set: お使いの環境でまだ設定されていない、このプロジェクトが必要とするシークレットキー。プロジェクトを実行する前に Settings で設定してください。
Choose location & import をクリックし、展開先フォルダを選択すると、プロジェクトがリストに登録されます。保存先を示す確認画面が表示されます（設定すべきシークレットの通知も含まれます）。インポートされたプロジェクトはリストに追加されますが、自動的にアクティベートされることはありません。準備ができたら手動で切り替えてください。
Default Project（デフォルトプロジェクト）
Griptape Nodes には、常に組み込みの Default Project が用意されています。これは読み取り専用です：閲覧は可能ですが、編集や保存はできません。開くとバナーが表示され、独自のディレクトリ、シチュエーション、変数を定義できるように Create a custom project へのショートカットが提示されます。
他のプロジェクトがアクティブになっていない場合、この Default Project がアクティブな環境となります。
プロジェクトのワークフローの確認
ワークフロー選択画面には、現在アクティブなプロジェクトに属するワークフローのみが表示されます。そのため、プロジェクトを切り替えると、表示されるワークフローの一覧も一緒に切り替わります。
