프로젝트 변수 (Project Variables)

프로젝트 파일의 variables 섹션은 프로젝트에 속하는 명명된 값을 선언합니다. 이 변수들은 워크플로 변수와 동일한 {VAR} 치환 시스템에 참여하며, 노드 파라미터 값과 매크로에서 사용할 수 있습니다.

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

필드 목록

필드	필수 여부	기본값	설명
`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와 동일하게 작동합니다. 아직 비밀 정보를 저장하는 용도로 사용하지 마세요. 읽기 제한은 향후 보안 정보(secrets) 지원 기능의 일부로 계획되어 있습니다. 해당 기능이 적용되면 write_only 값은 읽기, 선택기(picker) 및 {VAR} 치환에 표시되지 않게 됩니다.

프로젝트 변수 해석 방식

변수는 계층 구조로 조회되며, 이름 충돌이 발생하면 더 가까운 계층의 변수가 우선 적용됩니다:

워크플로(플로우) 변수 — 워크플로 편집기에서 생성된 변수
프로젝트 변수 — 이 섹션의 변수, 프로젝트 내장 변수 및 디렉터리 이름
전역 변수

프로젝트 계층 내에서는 동일한 이름의 variables: 항목보다 내장 변수와 디렉터리 이름이 항상 우선합니다. workspace_dir이라는 이름이나 디렉터리 중 하나의 이름으로 변수를 선언하면 로드 경고가 발생하며 해당 변수는 절대 해석되지 않습니다. 다른 이름을 선택하세요.

내장 변수 및 디렉터리 이름은 예약어이기도 합니다. 엔진은 워크플로 변수나 전역 변수를 해당 이름으로 생성하거나 이름을 변경하는 것을 거부합니다.

런타임 쓰기 및 영속성

read_write 프로젝트 변수는 엔진 실행 중에 변수 패널이나 변수를 설정하는 노드를 통해 변경할 수 있습니다. 성공적인 변경 사항은 즉시 프로젝트 파일에 다시 저장되므로 재시작 후에도 유지됩니다.

쓰기 작업은 선언된 타입을 기준으로 검사됩니다. int 변수에 문자열 값을 설정하려고 하면 자동으로 형 변환되지 않고 오류와 함께 거부됩니다.

read_only 변수는 모든 런타임 쓰기를 거부합니다. 값을 변경하려면 프로젝트 파일을 편집하고 프로젝트를 다시 로드하세요.

매크로에서의 프로젝트 변수

프로젝트 변수는 호출자가 제공한 값보다 아래이고 프로젝트 environment: 섹션보다 위의 우선순위로 경로 매크로 해석(예: 디렉터리 path_macro 또는 시츄에이션 매크로)에 참여합니다:

내장 변수
디렉터리 이름
호출자가 제공한 변수
프로젝트 변수 (이 섹션)
프로젝트 환경 변수
셸 환경 변수

전체 우선순위에 대한 자세한 설명은 환경 및 내장 변수를 참조하세요.

상속 (Inheritance)

프로젝트가 부모 프로젝트를 선언하는 경우(parent_project_path / parent_project_id), 변수는 항목별로 병합됩니다:

동일한 이름을 가진 자식 항목은 부모 항목을 완전히 대체합니다.
null로 설정된 자식 항목은 상속된 변수를 제거합니다:

# 자식 project.yml
variables:
  shot_code:
    value: sc099      # 부모의 shot_code를 오버라이드함
  facility: null       # 상속된 facility 변수를 제거함

자식이 언급하지 않은 부모 항목은 변경 없이 그대로 상속됩니다.

런타임에 상속된 변수를 삭제하면 자식 파일에 null 툼스톤(삭제 표시)이 기록되므로 다시 로드한 후에도 제거 상태가 유지됩니다.

`variables`와 `environment`의 선택 기준

둘 다 프로젝트 범위의 키-값 섹션이지만 사용 대상이 다릅니다:

variables 항목은 1급(first-class) 엔진 변수입니다. 변수 패널과 선택기에 표시되고, 타입과 권한을 가지며, 런타임에 변경할 수 있고, 노드 파라미터 내부의 {VAR} 치환에 참여합니다.
environment 항목은 매크로 구성(경로, 코드) 및 OS 환경 변수 내보내기를 위해 존재합니다. 문자열만 지원되고 런타임에 쓸 수 없으며 편집기에서 변수로 표시되지 않습니다.

기본 원칙: 아티스트가 보거나 변경해야 하는 값은 변수로 만들고, 경로 매크로를 위한 내부 구성 요소인 경우 environment에 유지하세요.