Wiki

검증 규칙

Unreal 에디터에서의 체크인 시 실행되는 에셋 검증 검사 : 9개의 내장 규칙, error / warning / info 심각도, JSON 설정, 내보내기 / 가져오기 / 초기화, 그리고 알아두어야 할 한계.

소개

검증 규칙은 Unreal 에디터에서의 체크인 시점에 실행되는 Unreal 에셋 검사입니다 : 명명, 텍스처 크기, 누락된 종속성 등. 콘텐츠가 저장소(서버에서 버전 관리되는 프로젝트)에 들어가기 전에 스튜디오 규약을 자동으로 강제하는 데 사용됩니다. 설정은 저장소별로 이루어집니다.

규칙이 실제로 적용되는 곳

검증은 서버가 아니라 Unreal 에디터가 수행합니다 여기서 설정한 규칙은 에디터에서 제출하는 시점에 Unreal Engine용 uVersion 플러그인에 의해 다운로드되어 실행됩니다. 서버 자체는 커밋을 기록할 때 규칙을 전혀 참조하지 않습니다. 이에 의존하기 전에 알아두어야 할 결과 : 데스크톱 클라이언트, 명령줄 (uversion checkin), 또는 Rider 플러그인에서 수행한 제출은 오류 없이 흔적도 남기지 않고 검증 정책을 완전히 우회합니다.

이것은 당신의 설정 오류가 아닙니다 : 현재의 동작 방식입니다. 규칙은 Unreal 에셋(.uasset, .umap)을 대상으로 하며, 이를 검사하려면 프로젝트가 로드된 상태로 에디터가 열려 있어야 합니다. 따라서 이것들을 에디터에서 작업하는 아티스트를 위한 안전장치로 다루고, 누구도 넘을 수 없는 장벽으로 여기지 마세요.

실질적인 두 가지 결과 :

어떤 규약이 단지 권장되는 것이 아니라 보장되어야 한다면, 추가적인 통제(리뷰, 빌드 측 검증)를 마련하세요 : 규칙만으로는 그것을 보장하지 않습니다.
누군가에게서 규칙이 '전혀 발동하지 않는다'면, 먼저 그 사람이 어디에서 제출하는지를 확인하세요. 데스크톱 클라이언트에서 제출하는 아티스트는 설정이 어떻든 아무 검증도 보지 못합니다.

접근 권한과 역할

규칙 탭은 슈퍼 관리자와, 자신이 관리하는 저장소에서의 project_admin 이 사용할 수 있습니다.

자동 시딩, 그러나 모두 비활성화 9개의 기본 규칙은 저장소 생성 시 자동으로 생성됩니다(생성되지 않은 경우, 규칙이 하나도 없는 저장소의 Rules 탭을 처음 열 때). 이 규칙들은 비활성화된 상태로 시딩됩니다 : 새 저장소에서는 관리자가 원하는 규칙을 활성화할 때까지 어떤 검증도 실행되지 않습니다. 완전한 세트에서 시작하여 활성화하고 조정하게 됩니다.

심각도

심각도는 활성화된 규칙이 실패했을 때 Unreal 에디터에서 무슨 일이 일어나는지를 결정합니다.

심각도	Unreal 에디터에서의 체크인 시 효과
`error`	체크인을 차단합니다 : 검증 창이 열리고 Proceed 버튼이 회색으로 비활성화되며 OK 만 클릭 가능한 상태로 남습니다. 에셋을 수정해야 합니다.
`warning`	제출을 막지는 않지만 조용히 통과하지 않습니다 : 검증 창이 그래도 열려 경고를 나열하며, 사용자는 계속하려면 Proceed 를 클릭해야 합니다.
`info`	순전히 정보 제공용 : 그것만으로는 창을 열지 않고 아무것도 중단하지 않습니다.

Unreal 에디터의 Pre-Checkin Validation 창. 발견된 항목 목록과 Proceed 버튼이 표시되어 있습니다.

9개의 내장 규칙

규칙	기본값	검사 내용
`blueprint_compilation`	error	체크인 전에 Blueprint가 오류 없이 컴파일됩니다.
`naming_convention`	warning	명명 접두사(Allar UE5 스타일) : `T_` 텍스처, `M_` 머티리얼, `BP_` 블루프린트, `SM_` 스태틱 메시, `WBP_` 위젯 등.
`max_texture_size`	warning	텍스처 최대 크기 : 기본값 4096 × 4096, 2의 거듭제곱 필수.
`material_complexity`	warning	머티리얼 복잡도 : 기본값으로 최대 256 명령, 16 텍스처 샘플.
`import_settings`	warning	규정에 맞는 임포트 설정(텍스처, 메시).
`missing_dependency`	error	누락된 종속성 없음(기본적으로 엔진 콘텐츠 무시).
`circular_dependency`	error	순환 종속성 없음(기본 탐색 깊이 20).
`unreferenced_asset`	info	참조되지 않은 에셋을 알립니다(기본적으로 맵과 위젯 제외).
`duplicate_asset`	warning	중복 에셋을 감지합니다(기본적으로 `.umap` 무시).

활성화 및 설정

1. Rules 탭 열기

관리 패널에서 먼저 PROJECT 행의 선택기에서 저장소를 선택한 다음, 같은 행의 Rules 탭을 여세요 : 규칙은 한 번에 하나의 저장소를 대상으로 합니다. 9개의 규칙이 한 줄에 하나씩, 펼치기용 쉐브론, 스위치, 규칙 이름, 심각도, 설명과 함께 표시됩니다.

9개 검증 규칙의 목록 : 각 줄에 쉐브론, 활성화 스위치, 규칙 이름, 심각도, 그리고 오른쪽의 Error / Warning / Info 드롭다운 메뉴.

2. 규칙 활성화

이름 왼쪽의 스위치를 클릭하세요. 저장은 즉시 이루어집니다 : 이 작업에는 저장 버튼이 없습니다. 이것이 잊기 쉬운 단계입니다 : 새 저장소에서는 모든 스위치가 꺼져 있으며, 꺼진 규칙은 심각도가 무엇이든 누구에게도 아무것도 말하지 않습니다.

3. 심각도 선택

줄 오른쪽의 드롭다운 메뉴는 Error, Warning, Info 를 제공하며 여기서도 즉시 저장됩니다. 실제로 체크인을 차단하는 것은 error 뿐입니다 : 심각도 참조.

4. 매개변수 조정(JSON)

줄 시작 부분의 쉐브론을 클릭하여 규칙을 펼치세요. Configuration (JSON) 필드에 그 매개변수가 들어 있습니다. 그것들을 편집한 다음 Save Config 를 클릭하세요. 잘못된 JSON은 저장을 차단하고 필드 아래에 오류 세부 정보(Invalid JSON: ...)를 표시하며, 그 경우 규칙은 이전 상태로 유지됩니다.

Configuration (JSON) 편집기가 펼쳐진 규칙 : 입력 영역의 매개변수 텍스트와 오른쪽 하단의 Save Config 버튼.

예 : 모바일 프로젝트를 위해 max_texture_size 를 2048로 낮추거나, 엄격하게 강제하기 위해 naming_convention 을 error 로 전환합니다.

내보내기, 가져오기, 초기화

Rules 탭의 오른쪽 상단 도구 모음에는 세 개의 버튼이 있습니다 :

Export : 모든 규칙의 상태(활성화, 심각도, 설정)를 포함하는 rules.json 파일을 다운로드합니다.
Import : rules.json 을 다시 불러와 각 항목을 해당 규칙에 적용합니다 (알 수 없는 키는 무시됩니다).
Reset to Defaults : 모든 규칙을 기본값으로 되돌립니다. 사용자 지정 설정은 손실됩니다 (확인이 필요합니다).

내보내기 / 가져오기는 한 저장소에서 다른 저장소로 검증 정책을 복제하거나, 오프라인으로 버전 관리하는 데 사용됩니다.

저장소의 rules.json

커밋된 rules.json은 아무나 적용할 수 있는 것이 아닙니다 커밋된 .uversion/rules.json 파일은 커밋 작성자가 manage_rules 라는 이름의 권한('기능', 즉 역할에 연결되어 서버 전체에서 유효한 권한)을 보유한 경우에만 저장소 정책에 적용됩니다. 그렇지 않으면 파일은 저장되지만 규칙은 변경되지 않습니다. 이것은 보호 장치입니다 : 해당 경로에 쓰기 권한이 있는 기여자가 파일을 커밋하여 검증을 비활성화할 수는 없습니다.

흔한 함정

Unreal 에디터에서 체크인이 차단됨

error 로 설정된 규칙이 실패했습니다 : 검증 창이 발견된 항목을 나열하고 Proceed 버튼이 회색으로 비활성화된 채로 남습니다. 에셋을 수정하거나, (규칙이 자신의 상황에 너무 엄격하다면) 심각도를 warning 으로 낮추거나 비활성화하세요.

초기화가 내 설정을 지웁니다

Reset to Defaults 는 사용자 지정 설정에 대해 파괴적입니다. 되돌릴 수 있기를 원한다면 먼저 Export 를 하세요.

규칙이 아무것도 하지 않는 것 같음

이 순서로 세 가지를 확인하세요 :

그 사람은 어디에서 제출합니까? 데스크톱 클라이언트, 명령줄 또는 Rider 플러그인에서는 어떤 규칙도 평가되지 않습니다(규칙이 실제로 적용되는 곳 참조).
규칙이 활성화되어 있습니까? 새 저장소에서는 처음에 모두 비활성화되어 있습니다.
심각도가 올바릅니까? 체크인을 차단하는 것은 error 뿐입니다. info 는 아무것도 중단하지 않습니다.