プロジェクト変数 (Project Variables)

プロジェクトファイルの variables セクションには、プロジェクトに属する名前付きの値を宣言します。これらはワークフロー変数と同じ {VAR} 置換システムに参加し、ノードのパラメータ値やマクロ内で使用できます。

variables:
  shot_code:
    value: sc042
  frame_start:
    value: 1001
    type: int
  facility:
    value: mtl
    permission: read_only

フィールド (Fields)

フィールド	必須	デフォルト値	意味
`value`	はい	—	変数の値。宣言された `type` と一致する文字列または整数である必要があります。
`type`	いいえ	`str`	`str` または `int`。値はこれと一致している必要があります — `type: int` を宣言しながらクォートされた文字列を指定すると読み込みエラーになります。
`permission`	いいえ	`read_write`	`read_write` 変数は実行時に変更可能です（変更内容は即座にこのファイルに書き戻されます）。`read_only` 変数はプロジェクトファイルを直接編集することでのみ変更できます。`write_only` も受け付けられますが、まだ完全には適用されていません（後述）。

真偽値 (boolean) や浮動小数点数 (float) は変数値としてサポートされていません。文字列および整数の値のみが {VAR} トークンへと置換されます。

write_only はまだ読み取り制限されていません

write_only 変数は read_write と同様に実行時の書き込みを受け付けますが、エンジンはまだ読み取り時にその値を隠蔽していません — 現時点では、値が表示されたり置換されたりするすべての場所で read_write と同様に動作します。まだシークレットの保持には使用しないでください。 読み取り制限は、近日予定されているシークレットサポートの一環として計画されています。それが実装されると、write_only の値は読み取り、ピッカー、および {VAR} 置換に表示されなくなります。

プロジェクト変数の解決順序 (How project variables resolve)

変数はレイヤー構造で検索され、名前が衝突した場合はより手前のレイヤーが優先されます：

ワークフロー（フロー）変数 (Workflow variables) — ワークフローエディタ内で作成された変数
プロジェクト変数 (Project variables) — このセクション、およびプロジェクトの組み込み変数とディレクトリ
グローバル変数 (Global variables)

プロジェクトレイヤー内では、組み込み変数とディレクトリ名が常に 同名の variables: エントリよりも 優先されます。workspace_dir やいずれかのディレクトリ名と同名の変数を宣言すると読み込み警告が出力され、その変数が解決されることは決してありません — 別の名前を選択してください。

組み込み変数およびディレクトリ名は 予約名 (reserved) でもあります：エンジンは、ワークフロー変数やグローバル変数をそれらの名前で新規作成したりリネームしたりすることを拒否します。

実行時の書き込みと永続化 (Runtime writes and persistence)

read_write プロジェクト変数は、エンジンの実行中に変更可能です — 変数パネルから変更するか、変数を設定するノードによって変更されます。変更が成功するたびに、内容は即座にプロジェクトファイルに書き戻されるため、再起動後も維持されます。

書き込み内容は宣言された型に対してチェックされます：int 変数に文字列値を設定しようとすると、暗黙的な型変換は行われずエラーで拒否されます。

read_only 変数は、すべての実行時書き込みを拒否します。変更するにはプロジェクトファイルを編集してプロジェクトを再読み込みしてください。

マクロ内でのプロジェクト変数 (Project variables in macros)

プロジェクト変数は、呼び出し元から供給された変数の下、かつプロジェクトの environment: セクションの上に位置づけられ、パスマクロ解決（例えばディレクトリの path_macro やシチュエーションマクロなど）に参加します：

組み込み変数
ディレクトリ名
呼び出し元指定の変数
プロジェクト変数（本セクション）
プロジェクト環境変数
シェル環境変数

優先順位の詳細については、環境と組み込み変数を参照してください。

継承 (Inheritance)

プロジェクトが親（parent_project_path / parent_project_id）を宣言している場合、変数はエントリごとにマージされます：

同名の子エントリは、親のエントリを完全に 置き換えます。
null に設定された子エントリは、継承された変数を 削除（消去） します：

# child project.yml
variables:
  shot_code:
    value: sc099      # 親の shot_code を上書き
  facility: null       # 継承された facility 変数を削除

子プロジェクトで言及されていない親エントリは、そのまま変更なしに継承されます。

実行時に継承された変数を削除すると、子プロジェクトのファイルに null の削除マーク（tombstone）が書き込まれるため、削除状態も再読み込み後に維持されます。

`variables` と `environment` の選択基準

どちらもプロジェクトスコープのキー・バリューセクションですが、用途が異なります：

variables エントリはファーストクラスのエンジン変数です：変数パネルやピッカーに表示され、型とアクセス権限を持ち、実行時に変更可能で、ノードパラメータ内の {VAR} 置換に参加します。
environment エントリは、マクロの合成（パス、コード）および OS 環境変数へのエクスポートのために存在します。文字列専用であり、実行時に書き込むことはできず、エディタ上で変数として表示されることもありません。

経験則: クリエイターが見たり変更したりすべきものは変数（variables）にし、パスマクロのための配管的な設定であれば environment に維持してください。