Wiki
Unreal Engine 플러그인
Unreal Engine용 uVersion 플러그인: 에디터 내 네이티브 버전 관리, Blueprint 차이 비교, Project Health 감사, 그리고 제출을 가장 자주 막는 두 가지 규칙.
사전 요구 사항
.uversion/ 폴더를 찾습니다. 이를 찾지 못하고, 이전에 저장된 인증 토큰도
없으면, 플러그인은 전혀 활성화되지 않으며 Unreal은 버전 관리 없이 그대로 남습니다.
이것은 고장이 아닙니다. uVersion으로 버전 관리되지 않는 프로젝트에 스스로 끼어들지 못하게 하는 장치입니다.
프로젝트는 desktop 클라이언트가 클론한 폴더에서 여세요. 다른 곳에 놓아 둔
사본에서 열지 마세요.
설치
uVersion 플러그인은 미리 컴파일된 바이너리로 배포되며 desktop 클라이언트가 관리합니다. 직접 컴파일할 필요도, 다룰 소스 파일도 없습니다. 절대 버전 관리되지 않습니다. 리포지토리와 함께 오지 않으며, 그 안으로 제출해서도 안 됩니다. 각 머신은 그 Unreal 버전과 그 시스템에 맞는 바이너리를 설치합니다.
지원되는 Unreal 버전: 5.6 이상.
1. desktop 클라이언트에서 워크스페이스 열기
uVersion desktop 클라이언트를 설치하고 로그인한 다음, Unreal 프로젝트가 들어 있는 워크스페이스를 엽니다. 모든 작업은 클라이언트에서 이루어집니다. 다운로드할 아카이브도, 프로젝트에 직접 압축을 풀어 넣을 것도 없습니다.
2. 클라이언트가 프로젝트를 감지하도록 하기
클라이언트는 워크스페이스 루트 아래에서(3단계보다 깊이 묻혀 있지 않다면)
여러분의 .uproject(Unreal 프로젝트를 기술하는 파일)를 찾습니다. 이를 찾는 즉시 워크스페이스 탭 상단에
Unreal 바가 나타나고, 사용 중인 Unreal 버전에 맞는 플러그인을 Plugins/uVersion/에
배치합니다. 왼쪽 배지에는 플러그인의 상태와 버전
번호가 표시됩니다. 업데이트도 바로 그곳에서 확인합니다.
3. Unreal에서 프로젝트 열기
플러그인은 즉시 활성화됩니다. 에디터의 Plugins 창에서 체크할 것도, 재시작할 것도 없습니다. 만약 보이지 않는다면, 그것은 클라이언트가 아직 배치하지 않았기 때문이지, 활성화가 남아 있어서가 아닙니다.
이후: 업데이트
desktop 클라이언트는 프로젝트를 열 때와 그 후 주기적으로 새 버전을 확인합니다. 주의하세요. 자동 확인은 두 경우에 서로 다른 일을 합니다:
- 플러그인이 없는 경우: 아무것도 묻지 않고 설치됩니다. 이것이 첫 시작을 매끄럽게 만듭니다.
-
플러그인이 이미 있지만 오래된 경우(새 버전, 또는 Unreal 버전 변경): 클라이언트는
알려 주기만 합니다. 설치된 플러그인을 스스로 교체하는 일은 절대 없습니다. 그러면 Unreal 패널의
배지가
Update ready로 바뀝니다.
업데이트를 적용하려면: Unreal 에디터를 닫은 다음 배지를 클릭하세요. 로드된 플러그인은
디스크에서 교체할 수 없습니다. 에디터가 아직 열려 있으면 배지에
Restart UE가 표시됩니다.
첫 연결
일반적인 경우에는 연결할 것이 없습니다. 플러그인은 프로젝트 주변에서 uVersion 워크스페이스를 감지하거나 이미 저장된 토큰을 감지하는 즉시, 버전 관리 공급자로 스스로를 선택합니다. 자격 증명은 desktop 클라이언트에서 가져오며, 다시 입력할 필요가 없습니다. 프로젝트를 여는 것만으로 충분합니다.
아래 세 단계는 이 자동 선택이 이루어지지 않은 경우에만 필요합니다.
1. Revision Control 메뉴 열기
그것은 에디터의 상태 표시줄 오른쪽 아래에 있으며, 상단 메뉴에는 없습니다. 위쪽으로
열리며 Submit Content를 포함한 Unreal의 동작들과, Audit Project (Project Health) 항목이 있는
uVersion 섹션을 담고 있습니다.
Connect to Revision Control을 선택하세요.
2. Provider 목록에서 uVersion 선택
Revision Control Login 창이 열립니다. Provider를 펼치고 uVersion을 선택하세요. 워크스페이스가 인식되면 창이 녹색으로 스스로 이를 알리고 (Automatically configured from workspace), Workspace, Server URL, Username 필드는 이미 채워져 있습니다. 입력할 것이 없습니다.
3. Accept Settings로 확정
창 아래쪽의 Accept Settings 버튼이 선택을 적용하고 창을 닫습니다. 그러면 상태 표시줄에 Connected to에 이어 리포지토리 이름과 여러분의 사용자 이름이 표시됩니다. 이 선택은 기억되어, 이후 프로젝트를 열 때 다시 이 과정을 거치지 않습니다.
에셋을 체크아웃한 다음 제출하기
콘텐츠 파일에 대한, 에디터에서의 전체 흐름입니다. 코드는 여기서 절대 나가지 않습니다. 코드는 desktop 클라이언트를 거칩니다를 참고하세요.
1. 시작하기 전에 에셋 상태 확인하기
Content Browser의 각 썸네일에는 에셋의 상태를 알려 주는 배지가 있습니다: 내가 체크아웃함, 다른 사람이 체크아웃함, 또는 서버 대비 오래됨. 툴팁은 전체 문장을 보여 주는데, 예를 들어 File is out of date, sync to get the latest version과 같습니다. 이 경우 먼저 동기화하세요 (우클릭, Revision Control, Sync). 오래된 버전에서 작업을 시작하는 것은 충돌을 준비하는 것입니다.
2. 에셋 체크아웃하기
에셋을 우클릭하고 Revision Control 하위 메뉴, 그다음 Check Out. 모든 것이 있습니다: Sync, Check Out, Check In, History, Diff Against Depot, Revert. 다른 어떤 Unreal 공급자와도 동일합니다. 아티스트가 새로 배울 것은 전혀 없습니다.
실제로는 대개 할 일이 없습니다. 에셋을 수정하는 즉시, 플러그인이 수동 체크아웃 없이 서버 측 잠금을 스스로 설정합니다.
3. 제출 전에 비교하기
Diff Against Depot은 Blueprint에서도 에디터의 표준 시각적 비교 도구를 엽니다. 두 리비전이 나란히 표시되고, 추가·삭제·수정된 노드가 테두리로 표시됩니다. History에서 히스토리의 어떤 커밋에 대해서도 작동합니다.
4. 제출하기
우클릭, Revision Control, 선택 항목에 대해 Check In, 또는 상태 표시줄 메뉴의 Submit Content로 한 번에 모두 보냅니다. 창에는 대상 파일이, 삭제를 포함하여 나열되고 설명이 요구됩니다. 제출 시 플러그인은 이름 변경으로 남은 redirector를 정리하고 활성화된 검증 규칙을 실행합니다. error 규칙이 있으면 제출이 중단되고 원인이 된 파일을 알려 줍니다.
플러그인이 Unreal에서 하는 일
Project Health: 프로젝트 감사하기
상태 표시줄의 Revision Control 메뉴에는
Audit Project (Project Health) 항목이 있습니다. 이것은 프로젝트의 에셋 레지스트리를
단 하나의 에셋도 로드하지 않고 훑으며, 상태 보고서를 생성합니다: 명명, 폴더 구조,
종속성, 고아 콘텐츠, 비용. 오프라인에서 작동하며(보고서는 Saved/uVersionAudit 아래에
기록됩니다), 연결되면 서버로 전송되어 desktop 클라이언트의
Project Health 탭에 반영됩니다.
redirector 정리
에셋의 이름을 바꾸거나 이동하면, Unreal은 그 뒤에 redirector를 남깁니다. 이는 이전 경로를 새 경로로 가리키는 작은 전달 파일로, 이전 이름을 참조하던 에셋이 계속 작동하도록 합니다. 이들은 빠르게 쌓여 결국 트리를 읽기 어렵게 만듭니다. 플러그인은 이들을 감지하고 checkin 시점에 정리하며, 영향을 받는 모든 에셋의 참조를 업데이트합니다.
checkin 전 검증
플러그인은 제출된 파일에 대해 일련의 검사를 실행할 수 있습니다: Blueprint 컴파일, 명명 규칙, 텍스처 크기, 임포트 설정, 누락된 종속성, 순환 종속성, 고아 에셋, 중복, 머티리얼 복잡도. 전부 아홉 가지 규칙입니다. error 규칙은 제출을 차단하고, warning 규칙은 확인 후 허용합니다.
시작 시 조정
프로젝트가 열리면 플러그인은 여러분의 에셋 상태를 서버와 비교합니다. Content/
와 프로젝트 플러그인의 Content/를 훑으며, 디스크에서 쓰기 가능하지만
아직 체크아웃되지 않은 에셋을 모두 자동으로 체크아웃합니다. 의도는 여러분을 보호하는 것입니다. 여러분이 수정하기 시작한
파일을 두 세션 사이에 팀원이 가로챌 수 없도록 합니다.
코드는 Unreal이 아니라 desktop 클라이언트를 거칩니다
플러그인은 코드 파일의 제출을 거부합니다: .cpp, .h,
.hpp, .c, .cs. 시도는 원인이 된 파일을 알려 주는 차단 창에서
멈춥니다. 이것은 결함이 아닙니다. desktop 클라이언트는 보내기 전에 컴파일하고, 팀원이 동기화 시 받아 가는
에디터 바이너리를 게시합니다. 에디터에서 보낸 코드 커밋은 그 둘을 모두
놓치게 되고, 팀 전체에 대한 바이너리 배포를 중단시킵니다.
그러니 코드는 desktop 클라이언트에서 제출하세요. 반면 콘텐츠 파일은 Unreal에서 자유롭게 보낼 수 있습니다.
.uasset 제출이라도 마찬가지입니다. 메시지는 먼저 desktop
클라이언트에서 코드를 제출하라고 알려 줍니다.
이것은 가장 흔한 차단이며, 코드를 쓰지 않는 사람에게도 곧잘 떨어집니다. 소스 파일이 디스크에서 쓰기 가능하게 되기만 하면, 시작 시 조정이 그것을 스스로 체크아웃해 버리기 때문입니다. 이유는 실재합니다. 제출되지 않은 코드에 대해 저장된 에셋은 그것을 동기화하는 모든 사람을 망가뜨립니다. 그들의 바이너리에는 그 에셋이 의존하는 코드가 없기 때문입니다.
해제 방법: desktop 클라이언트의 Pending 탭, My Pending Changes 목록을 열고, 코드 파일을 찾아, 수정했다면 Checkin Selected, 손대지 않았다면 Revert를 하세요. 그러면 콘텐츠 제출이 정상적으로 진행됩니다. 에디터가 잠금 상태를 새로 고칠 때까지 몇 초가 걸릴 수 있습니다.
자주 발생하는 문제
uVersion 메뉴가 없음: 에디터가 버전 관리를 무시함
프로젝트가 uVersion 워크스페이스 안에 있지 않을 가능성이 큽니다. 클론한 폴더의 루트에
.uversion/ 폴더가 있는지, 그리고 다른 곳에 놓아 둔 사본이 아니라 그 폴더에서
프로젝트를 열고 있는지 확인하세요.
« Failed to connect to source control »
desktop 클라이언트가 실행 중이고, 거기에 로그인되어 있는지 확인하세요. 여러분의 자격 증명을 보유하고 자체 서명 서버와 대화할 수 있는 것은 그것입니다. 워크스페이스를 소유한 계정이 클라이언트에 로그인되어 있지 않으면, 플러그인은 다른 identity로 작업하기를 거부합니다. 이것은 의도된 동작입니다.
코드에 전혀 손대지 않았는데 제출이 거부됨
여러분은 코드 파일의 체크아웃을 보유하고 있습니다. 코드는 desktop 클라이언트를 거칩니다를 참고하세요.
다른 사람이 잠근 에셋이 필요함
이것은 Unreal에서 요청하지 않습니다. 플러그인에는 해제 요청 기능이 없습니다. desktop 클라이언트의 Pending 탭, Other Users' Locks 섹션에서 파일 행의 Request Release 버튼을 사용하세요. 보유자는 Production 보드의 카드로 요청을 받습니다.
플러그인이 업데이트되지 않음
이것은 예상된 동작입니다. 자동 확인은 없는 플러그인은 설치하지만,
업데이트에 대해서는 알려 주기만 합니다. Unreal 에디터를 닫고(로드된 플러그인은 교체할 수 없습니다), 그다음
desktop 클라이언트의 Unreal 바에 있는 Update ready 배지를 클릭하여 적용하세요.
검증 규칙이 한 번도 발동하지 않음
아홉 가지 규칙은 비활성화된 상태로 제공됩니다. 관리자가 Admin 패널의 Rules 탭에서 프로젝트별로 활성화해야 합니다.