Wiki

데스크톱 클라이언트

Windows, macOS, Linux용 uVersion 데스크톱 클라이언트: 설치, workspace, 탭, 설정.

설치

데스크톱 클라이언트는 Windows, macOS(Apple Silicon), Linux용 네이티브 애플리케이션입니다. Windows, macOS, Linux 설치 프로그램에는 uversion CLI도 함께 포함되어 사용할 수 있습니다. /downloads에서 다운로드하세요.

Windows

uVersion_x.y.z_x64-setup.exe(서명된 NSIS 설치 프로그램, 약 25 MB)를 다운로드합니다. 실행하면 설치 프로그램은 다음을 수행합니다.

클라이언트를 %LOCALAPPDATA%\uVersion에 설치(사용자별, 관리자 권한 불필요)
설치 폴더를 사용자 PATH에 추가(uversion.exe CLI가 여기에 포함되어 있음)
시작 메뉴에 바로 가기 생성
Tauri updater를 통한 자동 업데이트 활성화

macOS(Apple Silicon)

uVersion_x.y.z_macos-arm64.app.zip(약 32 MB, Developer ID로 서명되고 Apple 공증됨)을 다운로드합니다. 더블 클릭하여 압축을 풀고 uVersion.app을 /Applications로 드래그합니다. 첫 실행 시 Gatekeeper가 공증을 자동으로 검증하며 경고가 표시되지 않습니다.

uversion CLI는 앱에 포함되어 있습니다. 첫 실행 시 클라이언트는 ~/.local/bin/uversion에 대한 심볼릭 링크를 자동으로 생성하고 ~/.zprofile을 통해 ~/.local/bin을 PATH에 추가합니다. 수동 작업이 필요 없습니다. 새 터미널을 열면 uversion을 사용할 수 있습니다.

참고: Apple Silicon(M1/M2/M3/M4)만 지원됩니다. Intel 바이너리는 없습니다.

Linux

x86_64용으로 두 가지 형식이 있습니다.

AppImage(uVersion_x.y.z_amd64.AppImage, 약 76 MB): 포터블이며 모든 종속성(libwebkit2gtk, libgtk, libsoup 등)을 포함합니다. 시스템 설치 없이 모든 Linux 배포판에서 실행됩니다.
```
chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage
```
.deb 패키지(uVersion_x.y.z_amd64.deb, 약 5 MB): Ubuntu / Debian / 파생 배포판용. apt가 시스템 종속성을 해결합니다.
```
sudo apt install ./uVersion_x.y.z_amd64.deb
```
앱은 /usr/bin/uVersion에 설치됩니다.

참고: uversion CLI는 Linux 패키지에 포함되어 있습니다. 첫 실행 시 클라이언트는 바이너리를 ~/.local/bin/uversion에 복사하고 ~/.profile을 통해 ~/.local/bin을 PATH에 추가합니다(수동 작업 불필요).

첫 실행

첫 실행 시 클라이언트는 로그인 페이지를 표시합니다. 다음을 입력하세요.

서버 주소: 스튜디오의 주소(예: https://uversion.mygamestudio.com)
사용자 이름과 비밀번호

연결되면 클라이언트는 세션을 안전하게 기억합니다. uversion CLI와 에디터 플러그인(Unreal, Rider)은 동일한 자격 증명을 자동으로 재사용합니다. 다른 어디에서도 비밀번호를 다시 입력하지 않습니다.

Workspace

workspace는 서버 repository에 연결된 로컬 폴더입니다. 클라이언트는 여러 workspace를 동시에 관리할 수 있으며 상단의 탭 바에 표시됩니다. 각 workspace는 로컬 폴더 루트의 .uversion/에 메타데이터를 저장합니다.

.uversion/config.toml: owner, repo_id, server URL, workspace UUID
.uversion/checkouts_<workspace_id>.json: 이 workspace에서 본인이 보유한 locks
.uversion/changelists_<workspace_id>.json: 로컬 changelists
.uversion/.last_sync: 마지막으로 synced된 리비전(증분 sync용)

Files 탭

상태 필터(Synced, Modified, Local only, Locked…)와 검색 바가 있는 파일 트리.

workspace 파일을 상태와 함께 트리 형태로 표시합니다. 사용 가능한 필터:

Search: path 내 부분 문자열로 검색(대소문자 구분 안 함)
Status filters: Synced, Modified, Local only, Server only, Locked, Deleted

수만 개의 파일이 있는 프로젝트에서도 뷰는 부드럽게 유지됩니다.

다중 선택 + 작업

여러 파일을 선택(클릭 + shift 또는 체크박스 선택)한 후:

Checkout: locks를 획득합니다(idempotent, 이미 locked된 파일의 재 checkout은 no-op)
Sync: 선택한 파일을 다시 다운로드합니다(로컬에서 파일이 손상된 경우 유용)
Revert: lock을 release하고 서버 버전을 복원합니다

Pending 탭

현재 checked-out 상태이며 본인 또는 다른 사용자가 locked한 파일입니다. 두 섹션이 있습니다.

Your locks: 개별적으로 checkin, revert 또는 release할 수 있습니다
Other users' locks: 누가 lock을 보유하고 있는지 표시되며 Production 보드에 request 카드(request 배지)를 생성하는 Request release 버튼이 있습니다

관리자에게는 타인의 locks에 대한 Force unlock 버튼도 표시됩니다. 이는 보유자의 동의 없이 lock을 release합니다. 모든 force unlock은 감사됩니다.

History 탭

펼쳐진 commit과 그 파일 목록, commit의 Get all 버튼.

작성자, 날짜, 메시지, 변경된 파일이 포함된 repository commits의 페이지 매김 목록입니다. commit을 클릭하면 상세 정보가 열립니다. 해당 commit의 전체 파일 목록과 각각의 리비전입니다.

각 commit의 Get all 버튼으로 해당 리비전의 모든 파일에 대한 로컬 복사본을 다운로드할 수 있습니다(안정적인 상태를 복원하는 데 유용).

Production

Production 영역(사이드바의 전용 항목)은 프로젝트 추적을 저장소별로 모읍니다. Workspace의 이전 Activity 탭과 Requests 탭을 대체했습니다: 이제 Workspace는 파일(Files, Pending, History)에 집중합니다.

My tasks

당신에게 할당된 카드 목록이며, 접근 권한이 있는 모든 저장소에 걸쳐 집계됩니다.

Board

kanban: To Do / In Progress / Review / Done 열, 우선순위·라벨·담당자·커버가 있는 카드.

저장소별 kanban 보드이며, 열은 구성 가능합니다(기본값 To Do, In Progress, Review, Done). 각 카드는 우선순위(low / normal / high / urgent), 라벨, 담당자, 마감일, 댓글, asset이나 commit으로의 링크, 커버 이미지를 가집니다.

요청은 보드의 카드입니다 이전의 modification requests(예를 들어 다른 사람이 보유한 lock에 대한 Pending 탭의 'Request release')는 이제 request 배지가 달린 보드의 카드입니다. 별도의 Requests 탭은 더 이상 없습니다.

열린 카드: 설명, 담당자, 마감일, 댓글, asset/commit 링크, 커버.

📷 Screenshot · production-request-cards

Review 열에 있는 request 유형 카드(배지).

Activity

통합 대시보드:

24시간 KPI: commits, 활성 제출자, 활성 locks
활동 캘린더: 여러 달에 걸친 일별 commits(heatmap)
Recent Checkins와 Most Modified Directories
Commit History: 사용자 및 경로별 필터가 있는 페이지 매김 commits

Watchlist

경로(glob 패턴)를 감시하여 그것을 건드리는 check-in의 알림을 받습니다. 각 항목은 감시 대상 경로와 추적되는 이벤트를 표시합니다.

Games

Games 영역은 프로젝트를 위해 게시된 내부 플레이테스트 빌드를 나열합니다. 각 빌드는 버전, 구성(DebugGame / Development / Shipping), 플랫폼(Win64 / Mac / Linux), 크기, 릴리스 노트를 표시하며, 플랫폼에 맞는 다운로드 버튼이 있습니다.

이곳은 playtester의 접근 지점입니다: playtester 역할의 계정은 이 페이지만 볼 수 있고(Workspace도 Production도 없음), 자신에게 열린 프로젝트의 빌드에만 접근합니다.

로컬 Changelists

📷 Screenshot · client-changelists

두 개의 로컬 changelists(예: default와 review)로 분류된 checked-out 파일.

checked-out files를 여러 개의 독립적인 commits로 그룹화합니다. changelists는 본인의 workspace에 대해 로컬입니다(서버로 전송되지 않음). 다음과 같은 경우에 유용합니다.

중요한 수정을 진행 중인 작업과 분리
모든 것을 뒤섞지 않고 여러 제출을 병렬로 준비
WIP용 "default" changelist와 checkin으로 보낼 "review"를 유지

Settings

클라이언트의 전역 설정(%APPDATA%/uversion/uVersion/config/config.toml에 저장):

옵션	설명
Default server URL	로그인 페이지에 미리 입력됨
Username	로그인 페이지에 미리 입력됨
Theme	System / Light / Dark
Show hidden files	Files 탭에서 `.`로 시작하는 파일을 표시
Auto-sync interval	비활성화 / 5분 / 15분 / 30분: 자동 증분 sync를 트리거
Parallel uploads	concurrency 상한(1-32, 기본값 16)
Default repos path	clone 시 기본으로 제안되는 폴더

Unreal 패널

📷 Screenshot · client-unreal-panel

작업 버튼이 있는 Unreal 패널: Open Editor, Compile, Package Game과 그 구성 선택, Publish Build, Stop.

클라이언트가 workspace에서 Unreal 프로젝트(.uproject 파일의 존재)를 감지하면 전용 패널이 나타납니다. IDE를 거치지 않고 클라이언트에서 직접 엔진을 제어합니다. 에디터 열기, 컴파일, 패키징 등입니다. 대부분의 작업은 C++ 프로젝트에만 해당됩니다(순수 Blueprint 프로젝트는 컴파일이 필요 없습니다).

Engine path

Unreal 버전은 .uproject의 EngineAssociation에서 자동으로 감지됩니다(Windows 레지스트리, LauncherInstalled.dat 또는 소스 빌드). 감지에 실패하면 수동으로 재정의할 수 있습니다. 이 경로는 아래의 모든 작업에 필요합니다.

Open Editor

workspace 프로젝트에서 Unreal 에디터(UnrealEditor)를 실행합니다. 이 버튼은 멱등합니다. 에디터가 창을 표시하기까지 수십 초가 걸릴 수 있으므로(특히 macOS / Linux), 그 사이에 두 번째로 클릭해도 두 번째 인스턴스가 열리지 않습니다. 에디터가 시작되는 동안 버튼에는 "Opening…"이 표시됩니다. 로컬에서 한 번도 컴파일하지 않은 C++ 프로젝트의 경우, 에디터를 열면 먼저 프로젝트 파일 생성 후 컴파일이 실행됩니다(자동 작업 참고).

Compile

📷 Screenshot · client-compile-console

Unreal Build Tool의 컴파일 출력을 실시간으로 표시하는 내장 콘솔.

프로젝트를 컴파일합니다(Unreal Build Tool). 출력은 내장 콘솔에 실시간으로 표시됩니다. C++ 프로젝트는 에디터에서 열고 코드 변경을 반영하려면 컴파일해야 합니다.

Generate Project Files

IDE 프로젝트 파일을 재생성합니다(Visual Studio, Rider). 소스 파일을 추가하거나 제거한 후, 또는 clone 후에 유용합니다. 패널의 "…"(추가 작업) 메뉴에 있습니다.

Package Game

RunUAT BuildCookRun으로 게임을 패키징하고 결과를 workspace 루트의 Packages/{config}/에 보관합니다. 세 가지 구성 중에서 선택할 수 있습니다.

Config	용도
`DebugGame`	디버그 빌드(전체 심볼, 최적화 없음).
`Development`	개발 빌드(기본값): 최적화되었지만 개발 도구 포함.
`Shipping`	배포 빌드: 최적화됨, 개발 도구 없음.

Packages/ 폴더는 기본적으로 무시됩니다(.uversionignore). 패키징된 빌드는 버전 관리되지 않으며 Publish Build를 통해 배포됩니다.

Publish Build

패키징된 빌드를 내부 플레이테스트 버전으로 게시합니다. 팀은 클라이언트의 Games 페이지에서 다운로드할 수 있게 됩니다(playtester 역할 또는 빌드 접근 권한 필요). 클라이언트는 Packages/{config}/를 스캔하고 파일을 업로드(서버 측에서 중복 제거)한 다음 매니페스트를 등록합니다.

Open project folder

workspace 폴더를 시스템 파일 탐색기에서 엽니다(Windows 탐색기, Finder 또는 Linux의 xdg-open).

Stop

진행 중인 모든 빌드를 깔끔하게 중단합니다. 컴파일과 패키징 모두입니다. 버튼에는 중단된 빌드 수가 표시됩니다(백그라운드에서 시작된 자동 컴파일이 포함될 수 있습니다).

자동 작업

버튼 외에도, 클라이언트는 C++ 프로젝트가 항상 최신 상태이고 컴파일 가능하도록 일부 Unreal 작업을 스스로 실행합니다.

check-in 전: 코드 파일이 변경된 경우 프로젝트가 먼저 컴파일됩니다. 컴파일에 실패하면 check-in이 차단됩니다(컴파일되지 않는 코드는 제출하지 않습니다).
sync 후: sync가 코드를 다운로드한 경우, 클라이언트는 프로젝트 파일을 재생성한 다음 다시 컴파일합니다.
clone 후 첫 실행 시(C++ 프로젝트): 에디터를 열 수 있기 전에 프로젝트 파일 생성 후 컴파일이 진행됩니다.

이러한 자동 빌드는 엔진 잠금(Unreal Build Tool -WaitMutex)에서 직렬화됩니다. 서로를 거부하지 않고 순차적으로 이어집니다. Stop 버튼으로 이들도 중단됩니다.