環境と組み込み変数 (Environment & Builtin Variables)

環境 (Environment)

プロジェクトファイルの environment セクションには、カスタムのキーと値のペアを定義します。これらの値は、マクロやディレクトリの path_macro フィールド内で使用できます。

environment:
  RENDER_STYLE: "realistic"
  CLIENT_CODE: "ACME"

オーバーレイの動作

プロジェクトファイル内の環境エントリは、システムデフォルトの上にマージされます。デフォルトにすでに存在するキーの場合は指定した値で上書きされ、新しいキーの場合は追加されます。

環境値からの他変数の参照

環境値自体もマクロとして機能します。値の中では、{NAME} 構文を使用して組み込み変数、ディレクトリ、他のプロジェクト環境変数、またはシェルの環境変数を参照できます：

Griptape Nodes を起動したシェルで SHARED_DRIVE=/mnt/renders がエクスポートされているとします。この場合：

directories:
  outputs:
    # シェル環境変数を直接参照 — `environment:` 配下での再宣言は不要
    path_macro: "{SHARED_DRIVE}/outputs"

environment:
  CLIENT_CODE: "ACME"
  # 組み込み変数を参照
  PROJECT_RENDERS: "{project_dir}/renders"
  # シェル環境変数、プロジェクト環境変数、リテラル文字列を合成
  CLIENT_RENDERS: "{SHARED_DRIVE}/{CLIENT_CODE}/renders"

参照は変数の優先順位に従って再帰的に解決されます。循環参照（例: A: "{B}" かつ B: "{A}"）は自動検知され、マクロ解決エラーとして報告されます。

レガシーな `$VAR` 構文について

後方互換性のため、値が厳密に $NAME のみである場合（前後のテキストやサフィックス、他のマクロを含まない場合）、その値がマクロによって消費される際にオペレーティングシステムの環境変数を使用して展開されます：

environment:
  OUTPUT_ROOT: "$RENDER_FARM_SHARE"  # マクロ内で動作: {OUTPUT_ROOT} -> /mnt/renders

重要な制限事項 — $VAR 形式は用途が限定されており、いくつかの既知の制約があります：

値全体の一致のみ。 文字列が追加されている場合（例: "$SHARED_DRIVE/outputs"）や前後にテキストがある場合は展開されず、プレーンなリテラル文字列として扱われます。マクロ解決時には、末尾を含む文字列全体をシークレット名として検索しようとして失敗します。
マクロ専用でありプロセス環境変数ではない。 $VAR はマクロ解決時にのみ展開されます。os.environ に書き込まれる際には展開されません — サブプロセスや os.environ.get("OUTPUT_ROOT") を呼び出すノードには、展開後の値ではなく文字列リテラル "$RENDER_FARM_SHARE" がそのまま渡されます。
合成ができない。 $ で始まる値は、他のプロジェクト環境変数、組み込み変数、ディレクトリを参照できません。

すべての新しいプロジェクトでは {NAME} 形式を使用することを強く推奨します。綺麗に合成でき、マクロと os.environ の両方で一貫して展開され、environment の値とディレクトリの path_macro の両方で確実に機能します。

組み込み変数 (Builtin variables)

組み込み変数は、すべてのマクロで自動的に利用可能です。これらはユーザーが定義するものではなく、システムが実行時に自動的に値を供給します。上書きすることはできません。

変数名	型	説明
`project_dir`	directory	プロジェクトベースディレクトリの絶対パス（`griptape-nodes-project.yml` を含むフォルダ、またはプロジェクトファイルが存在しない場合はワークスペースディレクトリ）。
`workspace_dir`	directory	ワークスペースディレクトリの絶対パス（明示的なワークスペースが設定されていない場合はプロジェクトディレクトリがデフォルトとなります。ワークスペースを参照）。
`workflow_name`	string	現在実行中のワークフローの名前。
`workflow_dir`	directory	現在のワークフローファイルを含むディレクトリの絶対パス（まだ保存されていないワークフローの場合は、エディタから指定された作成先フォルダ）。
`static_files_dir`	string	静的ファイルサブディレクトリの名前（設定から取得、デフォルトは `staticfiles`）。

組み込み変数の解決タイミング

組み込み変数は、プロジェクトファイルの読み込み時ではなく、マクロが評価される瞬間に解決されます。つまり：

workflow_name および workflow_dir は、現在実際に実行されているワークフローの内容を反映します。
project_dir は、読み込まれたプロジェクトファイルの実パスを反映します。
workspace_dir は、明示的なワークスペースが設定されていない場合はプロジェクトディレクトリを、設定されている場合はプロジェクト隣接設定または環境変数からの値を反映します。

組み込み変数が必須であるにもかかわらず解決できない場合（例えば、ワークフローが実行されていない状態での workflow_name など）、マクロ解決はエラーで失敗します。変数がオプショナル（? 付き）としてマークされている場合は、エラーにならずにそのブロック全体が静かに省略されます。

シチュエーションマクロでの組み込み変数

save_static_file シチュエーションは workflow_dir と static_files_dir を使用します：

{workflow_dir?:/}{static_files_dir}/{file_name_base}.{file_extension}

workflow_dir が利用可能な場合、静的ファイルはワークフローフォルダのサブディレクトリに保存されます。利用できない場合は {workflow_dir?:/} ブロックが省略され、パスはワークスペース相対になります。

未保存のワークフローの挙動

一度も保存されたことがないワークフローには実体ファイルが存在しないため、workflow_dir を導出するためのディレクトリが存在しません。フォルダをブラウズしている最中にワークフローを新規作成した場合、エディタはどのフォルダであったかをエンジンに伝え、ワークフローが保存されるまで workflow_dir はそのフォルダを返します。初回保存前に生成されたファイルは、ワークスペースルートではなくそのフォルダに保存されます。

ワークフローが一度保存されると、workflow_dir は保存先ファイルのディレクトリに切り替わります（別のフォルダに保存した場合は場所が変わります）。生成されたファイル自体は最初に書き込まれた場所に残りますが、{workflow_dir} に基づいて構築された保存参照は新しいフォルダを指すようになるため、保存前に生成された出力はディスク上に存在していてもノード上では見つからないように見える場合があります。

エディタからフォルダ情報が渡されなかった場合、workflow_dir は初回保存まで利用不可のままとなり、上述の通り {workflow_dir?:/} は省略されます。

変数の優先順位 (Variable priority)

マクロが解決される際、以下の優先順位に従って変数が供給されます：

組み込み変数 (Builtin variables) — 常に最優先。他のいかなるソースによっても上書きできません。
ディレクトリ名 (Directory names) — プロジェクトのディレクトリ定義から解決されます。呼び出し元から渡された変数で上書きすることはできません。
呼び出し元指定の変数 (Caller-supplied variables) — パス解決を要求するノードや処理から渡された値。
派生変数 (Derived variables) — 上記の変数とプロジェクト状態から計算され、シチュエーションマクロが解決される直前に注入されます。呼び出し元がすでにその値を指定している場合は派生変数は介入しないため、呼び出し元指定の値が優先されます。
プロジェクト変数 (Project variables) — プロジェクトの variables: ブロックで定義された値（プロジェクト変数を参照）。文字列および整数の値のみが参加します。
プロジェクト環境変数 (Project environment variables) — プロジェクトの environment: ブロックで定義された値。再帰的に解決されるため、組み込み変数、ディレクトリ名、他のプロジェクト環境変数、シェル環境変数を参照できます。
シェル環境変数 (Shell environment variables) — 最終的なフォールバック。Griptape Nodes を起動したシェルで設定されている任意の環境変数（HOME、USER、またはユーザーがエクスポートした任意の値）をマクロ内で {NAME} として参照できます。同名のプロジェクト環境変数が常に優先されます。予約名（組み込み変数、ディレクトリ）は、シェルに存在する偶然の変数によってプロジェクト状態が隠蔽されないよう、シェル環境変数よりも優先されます。

呼び出し元が組み込み変数やディレクトリ名に対してシステム値と異なる値を指定しようとした場合、マクロ解決は RESERVED_NAME_COLLISION エラーで失敗します。

派生変数一覧

変数名	派生元	真実のソース (Source of truth)
`file_extension_directory`	`file_extension` + プロジェクトの `file_extension_directories` マッピング	拡張子別ディレクトリを参照