저번에 Jenkins에서 빌드하기 위해서 BuildScript.cs 를 작성했는데, 이에 대해 좀 더 공부하기로 했다.
| BuildScript.cs |
|---|
 |
BuildPlayerOptions
BuildPlayerOptions : Unity 엔진에서 빌드 프로세스를 프로그래밍 방식으로 제어하기 위해 사용되는 핵심 구조체
역할
-
무엇을 빌드할 것인가 (Scenes 목록)
-
어떻게 빌드할 것인가? (Build Target, Build Options)
-
결과를 어디에 저장할 것인가? (Location Path)
주요 속성
| 속성 | 데이터 타입 | 설명 |
|---|---|---|
| scenes | string[] | 빌드에 포함할 Scene 파일들의 경로 배열입니다. (예: "Assets/00. Scenes/MainMenu.unity") |
| locationPathName | string | 빌드 결과 파일(플레이어)의 저장 경로와 이름을 지정합니다. 확장자(.exe, .apk 등)를 포함해야 합니다. (예: "Builds/MyGame/MyGame.exe") |
| target | BuildTarget | 빌드할 대상 플랫폼을 지정합니다. (예: StandaloneWindows64, Android, iOS 등) |
| options | BuildOptions | 추가적인 빌드 동작 플래그를 지정합니다. (예: Development, AutoRunPlayer, CompressWithLz4HC 등) |
| targetGroup | BuildTargetGroup | 빌드 대상이 속한 플랫폼 그룹을 지정합니다. (target과 연관됨) |
고급/자동화 관련 속성
| 속성 | 데이터 타입 | 설명 |
|---|---|---|
| extraScriptingDefines | string[] | 빌드 시 추가적인 스크립트 전처리 정의(#define)를 주입합니다. 특정 환경(예: Jenkins 빌드 서버)에서만 활성화되는 코드를 정의하는 데 사용됩니다. |
| assetBundleManifestPath | string | 빌드된 Asset Bundle Manifest 파일의 경로를 지정합니다. Asset Bundle을 사용하는 프로젝트에서 필수적입니다. |
| subtarget | int | 일부 플랫폼에서 빌드 대상의 세부 버전이나 형식을 지정하는 데 사용됩니다. |
BuildTarget
BuildTarget:
- Unity의 UnityEditor 네임스페이스에 정의된 **열거형(Enum)**
- Unity가 빌드된 게임 또는 애플리케이션을 실행할 대상 하드웨어 플랫폼을 지정하는 데 사용주요 역할
-
컴파일러 설정: 각 플랫폼에 맞는 코드를 컴파일하고 최적화합니다.
-
파일 형식: 최종 출력 파일의 형식(예: Windows는 .exe, Android는 .apk 또는 .aab, iOS는 Xcode 프로젝트 폴더)을 결정합니다.
-
플랫폼 종속 에셋: 해당 플랫폼에 특화된 에셋(예: 텍스처 압축 형식, 셰이더 변형)을 빌드에 포함시킵니다.
주요 맴버 목록
| 그룹 | BuildTarget 멤버 | 설명 |
|---|---|---|
| 데스크톱 | StandaloneWindows64 | 64비트 Windows 운영체제용 독립형 실행 파일 (.exe). |
| 데스크톱 | StandaloneOSX | macOS 운영체제용 독립형 실행 파일 (.app 번들). |
| 데스크톱 | StandaloneLinux64 | 64비트 Linux 운영체제용 독립형 실행 파일. |
| 모바일 | Android | Google Android 운영체제용 빌드 (.apk 또는 .aab). |
| 모바일 | iOS | Apple iOS/iPadOS 운영체제용 빌드 (Xcode 프로젝트). |
| 웹 | WebGL | 웹 브라우저에서 실행 가능한 WebAssembly 기반 빌드. |
| 콘솔 | PS5 | PlayStation 5 콘솔용 빌드. |
| 콘솔 | XboxOne | Xbox One 콘솔용 빌드. |
BuildOptions
BuildOptions:
- Unity의 UnityEditor 네임스페이스에 정의된 **열거형(Enum)**
- BuildPlayerOptions 구조체의 options 속성에 할당되어 기본 빌드 동작에 추가적인 세부 지침을 제공
- 여러 옵션을 동시에 적용하기 위해 비트 플래그(Bit Flag) 방식으로 조합하여 사용되는 것이 특징역할
- 이 플래그들은 빌드 결과물의 특성(디버그 가능 여부, 파일 압축 등)과 빌드 과정의 동작 방식을 제어
| 종류 | 역할 | 주요 멤버 |
|---|---|---|
| 품질/디버깅 | 최종 빌드 결과물에 디버깅 정보(프로파일러 연결 등)를 포함할지 결정합니다. | Development, AllowDebugging |
| 배포/파일 | 빌드 파일의 압축 방식이나 처리 방식을 지정합니다. | CompressWithLz4HC, StripAssets |
| 기타 동작 | 빌드 성공 후 플레이어를 자동 실행하는 등의 부가 동작을 제어합니다. | AutoRunPlayer, ForceRebuildAssetBundle |
주요 멤버 목록
| BuildOptions | 멤버 설명 | 일반적인 용도 |
|---|---|---|
| None | 추가 옵션을 사용하지 않는 가장 기본적인 빌드입니다. (Release 빌드의 기본값) | 최종 배포용 빌드 (Production Build) |
| Development | 개발 빌드를 만듭니다. 빌드된 플레이어에 디버깅 및 프로파일링 정보를 포함시켜, Unity Profiler 연결이나 스크립트 디버깅이 가능해집니다. | QA/테스트 및 디버깅용 빌드 |
| AllowDebugging | 빌드된 플레이어가 스크립트 디버깅을 허용하도록 설정합니다. Development 옵션과 함께 사용되는 경우가 많습니다. | 원격 디버깅이 필요한 경우 |
| AutoRunPlayer | 빌드가 성공적으로 완료된 후, 빌드된 플레이어(실행 파일)를 즉시 자동 실행합니다. | 개발자가 로컬에서 빠른 테스트를 할 때 |
| CompressWithLz4HC | 빌드된 Asset Bundle과 빌드 데이터를 LZ4HC(고압축) 알고리즘으로 압축합니다. 빌드 시간이 늘어나지만, 결과물의 파일 크기를 줄일 수 있습니다. | 최종 배포용 빌드에서 크기 최적화 |
| ForceRebuildAssetBundle | Asset Bundle을 빌드할 때 캐시를 무시하고 강제로 전체를 다시 빌드하도록 지시합니다. | Asset Bundle 캐시 문제를 해결하거나 변경 사항을 확실히 반영할 때 |
- 실제로는 더 많음.
| BuildOptions |
|---|
 |
BuildTargetGroup
BuildTargetGroup:
- Unity 빌드 시스템에서 BuildTarget보다 더 상위 개념
- 유사한 특성을 가진 플랫폼들을 그룹화하는 데 사용되는 열거형(Enum)
- Unity 에디터 내에서 **플랫폼별 설정(Player Settings)**을 관리
- 스크립트 전처리 지시자(\#if)를 사용하여 특정 플랫폼 그룹에만 적용되는 코드를 작성할 때 매우 중요주요 역할
-
설정 관리: Unity 에디터에서 Player Settings를 열면, 각 그룹별로 다른 설정을 지정할 수 있습니다. 예를 들어, Standalone 그룹과 Android 그룹의 아이콘, 번들 식별자, 스크립팅 백엔드 등을 다르게 관리할 수 있습니다.
-
전처리 지시자: 스크립트에서 특정 그룹에 대해서만 코드를 컴파일하도록 지시할 때 사용됩니다. (예: #if UNITY_STANDALONE)
-
BuildPlayerOptions: BuildPlayerOptions 구조체 내의 targetGroup 속성에 할당되어, 빌드 설정이 해당 그룹에 맞게 적용되도록 보장합니다.
주요 멤버 목록
| BuildTargetGroup 멤버 | 포함되는 BuildTarget | 예시 설명 |
|---|---|---|
| Standalone | StandaloneWindows64, StandaloneOSX, StandaloneLinux64 | PC/Mac/Linux 독립형(Standalone) 애플리케이션을 위한 그룹입니다. |
| Android | Android | Google Android 기기용 빌드를 위한 그룹입니다. |
| iOS | iOS | Apple iOS 및 iPadOS 기기용 빌드를 위한 그룹입니다. |
| WebGL | WebGL | 웹 브라우저에서 실행되는 콘텐츠를 위한 그룹입니다. |
| WSA | WSA (Windows Store Apps) | Windows 스토어 앱 빌드를 위한 그룹입니다. |
| Unknown | 해당 없음 | 알 수 없거나 특정되지 않은 대상 그룹입니다. |
BuildTargetGroup과 BuildTarget의 관계
-
BuildTarget이 최종 출력 플랫폼(예: Windows 64-bit)을 정확히 지정한다면, BuildTargetGroup은 그 플랫폼의 상위 범주(예: Standalone)를 지정
-
빌드 스크립트에서 options.targetGroup을 명시적으로 설정하지 않으면, 보통 options.target에 설정된 BuildTarget에 따라 Unity가 자동으로 적절한 그룹을 유추합니다.
-
하지만 자동화된 환경에서는 플랫폼 전환을 명확히 하기 위해 두 속성을 모두 지정하는 것이 좋습니다.
소감
내일은 조사한 자료 토대로 ColorPuzzle 게임의 빌드 옵션을 조금 바꿔서 빌드해볼 생각
