Unreal Engine 모듈 · 플러그인 개발LESSON 33

엔진 버전 호환성, 버전 관리, 배포 전 점검

난이도심화

예상 시간145분

선수지식32강의 Plugin 패키징과 이식 검증

33강. 엔진 버전 호환성, 버전 관리, 배포 전 점검

1. 이번 강의에서 해결할 문제

“UE5 지원”이라고만 적으면 어느 마이너 버전, 플랫폼, Source·Binary 조합을 실제로 확인했는지 알 수 없습니다. 공개 UFUNCTION 이름 변경이나 Config 키 삭제는 수신 프로젝트의 Blueprint와 설정을 조용히 깨뜨릴 수 있습니다. 배포는 압축 파일보다 호환성 계약과 검증 기록이 핵심입니다.

2. 학습 목표

3. 핵심 개념

Plugin 자체 버전과 Unreal Engine 호환 버전은 다른 축입니다.

Plugin Version: 정수 기반 내부 버전
Plugin VersionName: 사람이 읽는 릴리스 이름
Engine 호환: 실제로 빌드·실행한 UE 버전과 플랫폼의 명시적 목록

Descriptor의 Engine 관련 필드와 허용 형식은 UE5 버전마다 달라질 수 있습니다. 값을 추측해 넓게 선언하지 말고 사용하는 엔진의 Plugin Descriptor 문서와 Parser를 확인합니다.

4. 단계별 실습

Descriptor에는 확인한 범위만 기록합니다.

ReusableInteraction.uplugin의 릴리스 메타데이터 예시
{
  "FileVersion": 3,
  "Version": 10000,
  "VersionName": "1.0.0",
  "FriendlyName": "Reusable Interaction",
  "Description": "Project-independent interaction runtime component.",
  "Category": "Gameplay",
  "CreatedBy": "Your Team",
  "CanContainContent": true,
  "IsBetaVersion": false,
  "Modules": [
    {
      "Name": "ReusableInteraction",
      "Type": "Runtime",
      "LoadingPhase": "Default"
    }
  ]
}

지원 표는 README에 별도로 둡니다.

Plugin	Engine	Platform	형태	검증
ReusableInteraction 1.0.0	실제 사용 UE5.x	Win64	Source	Editor·Game·Package
DataGuard 1.0.0	실제 사용 UE5.x	Win64 Editor	Source	Tab·Validation·Commandlet

Semantic Versioning을 실무 판단에 맞게 적용합니다.

Patch: 내부 구현·문서·호환 버그 수정, 공개 계약 유지
Minor: 기존 사용을 유지하는 새 API·규칙 추가
Major: 함수 제거, Reflection 이름 변경, Config Migration이 필요한 변경

공개 UPROPERTY·UFUNCTION을 바꿀 때는 Blueprint 노드, 저장된 Asset, Config Section, C++ Include 경로까지 영향 범위를 검사합니다. 제거 대신 Deprecated Metadata와 Migration 기간을 제공할 수 있습니다.

배포 전 체크리스트를 저장소에 남깁니다.

[ ] Public Header에 프로젝트 Module Include 없음
[ ] Runtime Build.cs에 UnrealEd·ToolMenus·Slate 없음
[ ] Descriptor Module 이름과 Source 폴더 일치
[ ] Source 배포에서 Intermediate·Saved 제외
[ ] Binary 배포라면 Engine·Platform·Configuration 명시
[ ] Config 기본값과 선택 Content의 라이선스 확인
[ ] Editor·Game·Shipping·Commandlet 조합 검증
[ ] 빈 C++ 프로젝트 이식 결과 기록
[ ] Changelog와 알려진 제한 작성

Marketplace 등록은 배포 채널 중 하나일 뿐 이 과정의 필수 결과가 아닙니다. 외부 서비스 등록이나 유료 판매 없이도 Git 저장소·압축 산출물과 명확한 라이선스로 재사용 배포를 연습할 수 있습니다.

5. 코드가 동작하는 이유

지원 범위를 실제 검증 결과와 연결하면 사용자 환경에서 재현 가능한 기대치를 제공합니다. 공개 Reflection 계약을 버전으로 관리하면 Blueprint와 Asset 직렬화의 파괴적 변경을 계획적으로 처리할 수 있습니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ