コンテンツにスキップ

シチュエーション (Situations)

シチュエーション (Situation) は、名前付きのファイル保存シナリオです。以下を定義します：

  • ファイルの 保存場所（マクロテンプレート経由）
  • 保存先に同名ファイルが既に存在する場合の 処理方法（衝突ポリシー経由）
  • 保存に失敗した場合の 対処法（任意のフォールバックシチュエーション経由）

ノードがファイルを保存する必要がある場合、自身がどのシチュエーションにあるか（例えば save_node_output など）を指定し、プロジェクトシステムはそのシチュエーションのマクロを使用してパスを解決し、ポリシーを適用します。

衝突ポリシー (Collision policies)

ポリシー 挙動
create_new 衝突しない名前が見つかるまでファイル名内のカウンターをインクリメントします。マクロには {_index?:NN}（オプショナル — 初回保存時は省略、衝突時にインデックス付与）または {_index:NN}（必須 — 初回保存時からインデックス付与）を含めることができます。どちらも存在しない場合、システムは衝突時に解決済みファイル名の末尾に _1、_2、… を追加します。
overwrite 確認を行わずに既存のファイルを上書きします。
fail ファイルが既に存在する場合、処理を停止してエラーを報告します。

create_dirs フィールドは、途中の親ディレクトリを自動的に作成するかどうか（mkdir -p のように true）、または親ディレクトリの欠落をエラーとするかどうか（false）を制御します。

フォールバック (Fallbacks)

シチュエーションには、フォールバック（代替）シチュエーションを指定できます。プライマリシチュエーションがマクロを解決できない場合（例えば必須変数が不足している場合など）、システムはフォールバックを試みます。デフォルトの save_file シチュエーションは、他のほとんどのシチュエーションによって使用される最小限のフォールバックです。

デフォルトシチュエーション (Default situations)

save_file

macro:  {file_name_base}{_index?:03}.{file_extension}
policy: create_new, create_dirs: true

プロジェクトルート（または呼び出し元のパスコンテキストが指定する場所）での一般的なファイル保存です。これは他のほとんどのシチュエーションに対するフォールバックです。{_index?:03} 変数はゼロ埋めされたオプショナル形式です — 初回保存時は省略され、衝突時に 001、002、… となります（パディング桁数はシーケンス全体で維持されます）。

copy_external_file

macro:    {inputs}/{node_name?:_}{parameter_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

ユーザーが外部ファイルをプロジェクト内にコピーまたはドラッグ＆ドロップした際に使用されます。ファイルは inputs ディレクトリに配置されます。ファイルの出所を識別しやすくするために、ノード名とパラメータ名がオプショナルなプレフィックスとして先頭に付加されます。

例:

node_name="LoadImage", parameter_name="source", file_name_base="photo", file_extension="jpg"
→ inputs/LoadImage_source_photo.jpg

node_name 未指定, file_name_base="photo", file_extension="jpg"
→ inputs/photo.jpg

download_url

macro:    {inputs}/{sanitized_url}
policy:   overwrite, create_dirs: true
fallback: save_file

ノードが URL からファイルをダウンロードする際に使用されます。URL は安全なファイル名へとサニタイズされます。同じ URL からダウンロードされたファイルは、重複作成されずに上書きされます。

save_node_output

macro:    {outputs}/{sub_dirs?:/}{node_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

ノードが出力を生成して保存する際に使用されます。ファイルは outputs ディレクトリに保存されます。オプショナルなサブディレクトリ（{sub_dirs?:/}）により、出力配下での階層化が可能です。ノード名は任意のプレフィックスとなります。

例:

outputs="outputs", node_name="ImageGen", file_name_base="render", _index=1, file_extension="png"
→ outputs/ImageGen_render001.png

sub_dirs="lighting/pass_a", node_name="ImageGen", file_name_base="render", file_extension="exr"
→ outputs/lighting/pass_a/ImageGen_render.exr

save_output_directory

macro:  {outputs}/{sub_dirs?:/}{dir_name}_v{###}
policy: create_new, create_dirs: true

ノードが単一のファイルではなくフォルダに出力を書き込む場合に使用されます。実行ごとに新しい連番フォルダが作成されるため、過去の結果が上書きされることはありません。番号はディスク上に既に存在する最大バージョンからカウントアップされ、欠番を埋めます。

例:

dir_name="renders"
→ outputs/renders_v001      (初回実行)
→ outputs/renders_v002      (2回目実行)

save_file_sequence

macro:  {outputs}/{file_extension_directory?:/}{sub_dirs?:/}{file_name_base}_v{###}/{file_name_base}.####.{file_extension}
policy: create_new, create_dirs: true

動画から抽出したフレームなど、ノードが番号付きの一連のファイル群を書き込む場合に使用されます。実行ごとに独自のバージョンフォルダが割り当てられ、その中のフレームは個別に番号付けされます。

2 種類の # 記号は異なる役割を果たします。中括弧内の {###} はフォルダのバージョン番号です。中括弧の外側にある単独の #### は各フレームの番号が入る場所です。マクロ内で使用できる {###} は 1 つのみであるため、フレーム番号には中括弧なしの形式を使用します。フレーム番号付けの詳細については シーケンス を参照してください。

例:

file_name_base="frames", file_extension="png"
→ outputs/images/frames_v001/frames.0001.png
→ outputs/images/frames_v001/frames.0002.png
→ outputs/images/frames_v002/frames.0001.png   (2回目実行)

これら 2 つのシチュエーションは最新のプロジェクトテンプレートに同梱されています。レガシーテンプレートから作成されたプロジェクトには含まれていないため、ノードは同じレイアウトを生成する組み込みマクロを使用します。

save_preview

macro:    {previews}/{drive_volume_mount?:/}{source_relative_path?:/}{source_file_name}.{preview_format}
policy:   overwrite, create_dirs: true
fallback: save_file

プレビューサムネイルを生成するために使用されます。各ソースファイルに対してプレビューが正確に 1 つだけ存在するように、プレビューは元のファイルのディレクトリ階層を反映します。プレビューはバージョン管理されずに上書きされます。previews ディレクトリのデフォルトは .griptape-nodes-previews（隠しフォルダ）です。

save_static_file

macro:    {workflow_dir?:/}{static_files_dir}/{file_name_base}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

静的ファイルマネージャーが静的アセットを保存する際に使用されます。ファイルは現在のワークフローのディレクトリ配下の static_files_dir サブディレクトリに保存されます。これらのファイルは再生成時に上書きされます。

save_temp_file

macro:    {temp}/{node_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

処理中にノードが中間ファイルやスクラッチファイル（例えば、色空間変換ステップ間で書き出される一時的な EXR など）を書き出す必要がある場合に使用されます。ファイルは temp ディレクトリに保存され、使用後にノードによって削除される必要があります。

save_workflow

macro:    {workspace_dir}/{sub_dirs?:/}{file_name_base}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

ワークフローファイルが書き込まれるたびに使用されます：ユーザーが明示的に保存する場合のほか、エディタがワークフローファイルを自動生成する場合（ワークフローのブランチ作成やテンプレートからの複製作成など）も含まれます。これらもこのシチュエーションを経由するため、save_workflow の指定先を変更すると、明示的な保存だけでなくそれらすべてが移動します。

ワークフローファイルはワークスペースルートに保存され、オプショナルな {sub_dirs?:/} プレフィックスを介してサブディレクトリ階層が維持されます。ワークフローの保存はバージョン管理ではなく既存ファイルの上書きとなります；代わりに番号付きの連番保存を生成したい場合は、後述の create_versioned_workflow を参照してください。

例:

workspace_dir="/projects/demo", file_name_base="my_workflow", file_extension="py"
→ /projects/demo/my_workflow.py

sub_dirs="archived", file_name_base="my_workflow", file_extension="py"
→ /projects/demo/archived/my_workflow.py

create_versioned_workflow

macro:    {workspace_dir}/{sub_dirs?:/}{file_name_base}_v{_index:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

バージョン付き保存の意図をもってワークフローを保存する際に使用されます。保存ごとにシーケンス内の次のパディングインデックスを持つ新しいファイル（my_workflow_v001.py、my_workflow_v002.py、…）が生成されるため、ユーザーは過去の作業を上書きすることなくスナップショットを保持できます。

バージョンの繰り上げは マクロ駆動 (macro-driven) です：バージョン付き保存が実行されると、エンジンは前回の保存パスをこのシチュエーションのマクロと逆マッチングし、バインドされたパディングスロットを含め、マクロが定義するすべての変数を抽出します。次回の保存ではそれらの変数がそのまま再利用され、衝突回避処理によって既存ファイルを越えてパディングインデックスが進められます。バージョンサフィックスに関してハードコードされた要素は何もないため、マクロのカスタマイズ（例: _v{_index:03} を .{_index:04} に変更するなど）もそのまま機能します — 新しいパターンが順方向の保存と逆マッチングの双方における規約となります。

ヒント: カスタムプロジェクトでは、自動インデックススロットをより明示的な _v{###} 構文に変更できます（シーケンススロット ({###}) を参照）。これはデフォルトの 3 桁の場合に {_index:03} と全く同様に動作し、999 を超えてもゼロ埋め桁数に縛られず自然にオーバーフローします。

このシチュエーションは、API レイヤーにおいて SaveWorkflowRequest に create_versioned=True を渡すことで選択されます；UI では別個のメニュー項目（例: 「Save As New Version」）として公開されます。自動インデックスの仕様については マクロ — 数値パディング を参照してください。

注意: save_workflow を直接カスタマイズして create_new を指定した場合（create_versioned_workflow とフラグを使用する代わり）、保存時に警告が出力されます。その設定でも動作自体は可能ですが（初回保存は _v001 となる）、それ以降のすべての保存がその場での上書きブランチに入り、_v002 に進むのではなく _v001 に上書き保存されてしまいます。真のバージョン管理を行うには create_versioned_workflow を使用してください。

例:

workspace_dir="/projects/demo", file_name_base="my_workflow", file_extension="py"
  初回保存  → /projects/demo/my_workflow_v001.py
  2回目保存 → /projects/demo/my_workflow_v002.py
  3回目保存 → /projects/demo/my_workflow_v003.py

ノードによるシチュエーションの使用方法

ノードが使用するシチュエーションは、ユーザーではなくノードの作者によって選択されます。ファイルを保存するノードは ProjectFileParameter を使用し、そのパラメータが構築される際にシチュエーション名が組み込まれます。ノードの表面にシチュエーションフィールドは存在しません。ノードにはファイル名パラメータ（多くは Output File と表示）があり、その背後にシチュエーションが控えています。

ファイル名パラメータ そのもの が ProjectFileParameter です。そこに入力した内容が file_name_base および file_extension 変数となり、シチュエーションのマクロがファイルの実際の保存場所を決定します。したがって、save_node_output を使用しているノードに render.png と入力すると、プロジェクトルートの render.png ではなく outputs/MyNode_render.png が生成されます。ノードはファイル名の構成要素を提供し、プロジェクトシステムがそれ以外のすべて（ディレクトリパス、組み込み変数）を供給します。

ほぼすべての生成ノードおよび保存ノードは save_node_output を使用しています。他のシチュエーションは、それらが名指しするシステムの一部によって使用されます：ファイルのドラッグ＆ドロップでは copy_external_file、URL ダウンロードでは download_url、サムネイルでは save_preview、ワークフローの保存では save_workflow が使用されます。

特定ノードの出力を全く別の場所へ送信する

render.png のようなプレーンな名前を入力すると、シチュエーションに保存先を任せることができ、これはほとんどの場合において望ましい挙動です。入力欄に他の 2 種類の形式を入力することで、そのノード単体の保存先を上書きできます：

  • 相対フォルダパス — lighting/pass_a/render.png と入力すると、ファイルはシチュエーションのディレクトリ内にネストされるため、save_node_output はそれを outputs/lighting/pass_a/ に配置します。起点となるフォルダは依然としてシチュエーションが決定します。
  • 絶対パス — /mnt/studio/renders/render.png、C:\renders\render.png、またはそれらの file:///mnt/studio/renders/render.png 表記。この場合、ディスク上の厳密な場所を指定することになるため、シチュエーションはパスを構築せず、指定した場所に直接保存されます：outputs ディレクトリは付かず、ノード名のプレフィックスも付かず、バージョン番号も付加されません。ただし、その場所に既にファイルが存在する場合の処理（save_node_output のもとでは過去のレンダリングを失うことなく render_1.png となる）や、存在しないフォルダの自動作成などは、依然としてシチュエーションが制御します。

Web アドレスは保存先として指定できません。ノードは https://example.com/render.png に保存することはできず、入力すると意図しない場所にファイルができるのではなくエラーとなります。

絶対パスはプロジェクトシステムをバイパスするため、プロジェクトシステムが提供する利点も失われます：パスが自身のマシン固有になるため、そのワークフローを他の人のコンピュータで開いてもその場所は見つかりません。マシンに存在しないドライブ名（macOS や Linux 上で開かれた C: パスなど）を指定すると、予期せぬ場所に C: というフォルダが作成されるのではなくエラーとなります。すべての ノードの書き込み先を変更したい場合は、代わりにプロジェクトファイル内のシチュエーションを編集してください。

ノードが使用しているシチュエーションの確認

ノードのファイル名パラメータにマウスカーソルを合わせます（ホバー）。ツールチップにシチュエーション名が表示されます。例：

Output filename (uses 'save_node_output' situation template)

すべてのノードとシチュエーションを一覧表示するパネルは存在しないため、特定のノードを確認するにはツールチップを参照するのが確実です。カスタムノードのソースコード内では、ProjectFileParameter に渡される situation= 引数にあたります。

1 つのノードでのシチュエーションの上書き

プロジェクトファイルを編集することなく単一のノードの書き込み先を変更するには、ノードのファイル名パラメータにある 歯車 ボタンをクリックします。これにより、そのパラメータに接続された File Output Settings ノードが作成され、そのノードのシチュエーションと現在のファイル名が事前に設定されます。

File Output Settings ノードは、シチュエーションが裏に隠していた設定を表に出し、各フィールドを変更できるようにします：

  • Situation: プロジェクトファイルのカスタムシチュエーションを含め、任意のシチュエーションを選択できます。変更すると、下部のマクロと衝突ポリシーが再読み込みされます。
  • Macro: この接続単体で編集可能なパステンプレート。
  • If File Exists: 衝突ポリシー（Increment Version、Overwrite Existing、または Abort / Error）。
  • Auto Create Path: 存在しない親ディレクトリを作成するかどうか。

ここで設定した内容は、それが接続されているノードにのみ適用されます。すべての ノードの保存先を変更したい場合は、代わりにプロジェクトファイル内のシチュエーションを編集してください。

カスタムシチュエーションの追加

具体例については カスタマイズガイド を参照してください。

プロジェクトファイル内で save_node_output などのデフォルトシチュエーションを再定義すると、ノード側の編集を一切行うことなく、それを使用するすべてのノードの保存先が変更されます。新しい シチュエーションを追加した場合、それが反映されるのは何かが明示的にそれを選択している場所のみです：situation= を渡すカスタムノードか、またはそれを指定した File Output Settings ノードです。