Microsoft 게임 개발 키트를 PC Unity 게임과 통합

참고 항목

GDK Unity 패키지는 2024년 12월 31일부터 더 이상 사용되지 않습니다. Microsoft GDK Packages for Unity로 대체됩니다. 자세한 내용은 이 포럼 게시물 참조하세요.

이 항목에서는 GDK를 Unity PC 게임과 통합하는 방법에 대해 설명합니다.

• 개요
• 필수 구성 요소
• Hello World Unity 샘플을 사용하여 GDK 및 Unity 패키지 설정 테스트
• 파트너 센터에서 제품 만들기
• 게임을 Microsoft Store와 연결
• 테스트 계정 만들기
• 게임에 Xbox 서비스 추가
• 추가 고려 사항
• 파트너 센터에 게시

개요

Microsoft Store 또는 PC Game Pass에 나타나는 Unity 게임을 구축하는 기본 구성 요소는 다음과 같습니다.

• Windows 독립 실행형 x86_x64 Unity 프로젝트
• GDK에 제공되는 런타임 라이브러리
• Microsoft에서 제공하는 Unity 패키지입니다.

이를 통해 Xbox의 도전 과제, 리더보드, 클라우드 세이브, Azure PlayFab Party 채팅, 플랫폼 간 멀티플레이어 등과 같은 Microsoft 게임플레이 서비스에 액세스할 수 있습니다.

필수 소프트웨어

GDK와 함께 Unity를 사용하려면 다음 도구와 SDK를 설치해야 합니다.

• 최신 버전의 Windows 10을 사용하는 개발 PC.
• Visual Studio 2017 이상

GDK

1. 이러한 유용한 리소스에 액세스할 수 있는지 확인하세요. 액세스 권한이 없는 경우 Microsoft 담당자에게 문의하세요.

   • 보안 Xbox 다운로드

   • GDK Unity 비공개 포럼

2. GDK 다운로드.

   참고: PC에 게시하기만 하면 GitHub에서 GDK를 다운로드할 수 있습니다.

   1. Xbox 다운로드 보안으로 이동합니다.

   2. 다음 스크린샷과 같이 게임 코어를 선택하고 확인을 선택하세요.

      

   3. 다음 스크린샷에 표시된 대로 최신 도구 및 복구를 다운로드하세요. PC에서만 배송하는 경우에는 복구가 필요하지 않습니다.

      

   4. 각각을 다운로드하려면 지금 다운로드를 선택합니다.

3. GDK 설치하기.

   1. 파일을 다운로드한 위치로 이동합니다. 각 패키지를 추출합니다.

   2. 추출된 GDK 폴더를 찾고 setup.exe를 두 번 클릭하여 설정를 엽니다.

   3. 설정 페이지의 단계를 완료합니다.

최신 게임 런타임 서비스(GRTS) 및 PC 부트스트래퍼

2202년 5월 GRTS 릴리스부터 PC 부트스트래퍼가 PC 게임 실행 환경에 추가되었습니다. PC 부트스트래퍼는 GRTS(게임 런타임 서비스)에 종속되어 있으며 개발 PC에서 GRTS가 최신 상태가 아니면 로그인하려고 할 때 오류(E_FAIL)를 생성할 수 있습니다. 자세한 내용은 PC 부트스트래퍼 개요를 참조하세요.

Unity 패키지

1. GitHub에서 Unity 패키지를 다운로드합니다.
   패키지는 각 릴리스의 자산 섹션에 있으며 이름은 gdk-pc.[버전 번호].unitypackage입니다.

2. Unity 패키지를 가져옵니다.

   1. 새 Unity 프로젝트를 만듭니다. 실제 게임에서 사용하기 전에 먼저 새 프로젝트로 이 프로세스를 진행하는 것이 좋습니다.

   2. 새 Unity 프로젝트에서 기본 메뉴로 이동하여 자산>패키지 가져오기>사용자 지정 패키지를 선택합니다.

   3. 열린 파일 대화 상자에서 다운로드한 GDK .unitypackage 파일을 선택한 다음 열기를 클릭합니다.

   4. 콘솔에 가져오기 오류가 표시되면 삭제를 선택하세요. 오류가 더 이상 발생하지 않으면 무시해도 좋습니다.

   5. 완료되면 자산 패키지가 다음 스크린샷에 표시된 것처럼 자산 폴더 아래의 프로젝트 탭에 나타납니다.

      

   6. 이제 다음 스크린샷에 표시된 것처럼 새 메뉴 옵션 GDK가 Unity 기본 메뉴에 표시됩니다.

      

3. Xbox용으로 개발 중인 경우 Xbox용 Unity 패키지도 설치해야 합니다.

   1. 게임 코어에 대한 Unity 개인 포럼으로 이동합니다. 게임 코어용 Unity 다운로드라는 고정된 게시물로 이동한 다음 해당 링크를 선택합니다.

   2. 패키지 다운로드 링크가 있습니다. GDK 패키지가 이미 이 패키지에 포함되어 있으므로 다운로드할 필요가 없습니다. 다른 패키지를 다운로드할 필요가 없을 수 있습니다. 다운로드해야 하는지 여부를 결정하려면 해당 설명을 읽어 보세요.

이제 GDK를 Unity 게임에 통합하는 데 필요한 모든 작업을 완료해야 합니다.

Hello World Unity 샘플을 사용하여 GDK 및 Unity 패키지 설정 테스트

이 섹션에서는 Hello World Unity 샘플을 실행하는 방법에 대해 설명합니다.

1. 파일>장면 열기를 선택한 다음 [내 프로젝트 디렉터리]\Assets\GDK-Tools\Examples\Sign-in\SignIn.unity에서 샘플 장면을 엽니다.

2. Unity 기본 메뉴에서 파일>빌드 설정을 선택하여 빌드 설정 창을 엽니다.

3. 열린 장면 추가를 선택하여 샘플 장면을 추가합니다.

4. 선택한 다른 장면에 대한 선택을 취소합니다. 이렇게 하면 GDK-Tools/Examples/Sign-in/SignIn 샘플 장면만 선택됩니다.

5. 빌드 설정 대화 상자를 닫습니다.

6. 기본 메뉴에서 GDK>PC>빌드 및 실행을 선택합니다.

7. GDK - PC 빌드 및 실행 대화 상자에는 Assets/GDK-Tools/Examples/Sign-in/Basic.unity와 같은 하나의 샘플 장면만 나열되어야 합니다.

8. 대화 상자에서 MICROSOFT_GAME_CORE 정의를 선택합니다.

9. 대화 상자에서 빌드 및 실행을 선택합니다.

10. 샘플 게임이 시작될 때 Xbox 서비스에 로그인하라는 메시지가 표시되면 GDK 및 Unity 패키지가 올바르게 설정된 것입니다.
    도전 과제 잠금 해제는 도전 과제 샘플 장면에서 아직 작동하지 않습니다.

첫 번째 Unity 게임을 구축하고 실행했습니다. 이제 GDK를 자신의 게임에 통합할 준비가 되었습니다.

파트너 센터에서 제품 만들기

Xbox 서비스 기능을 테스트하거나 게임을 Microsoft Store 게시하기 전에 파트너 센터 Xbox 서비스 지원 제품을 만들어야 합니다. 파트너 센터에 대한 자세한 내용은 관리 파트너를 위해 파트너 센터에서 앱 또는 게임 설정을 참조하세요.

게임을 Microsoft Store와 연결

게임이 Xbox 서비스에 액세스할 수 있도록 하려면 마지막 단계에서 만든 파트너 센터 프로젝트의 값과 일치하도록 게임 구성을 업데이트해야 합니다.

1. Unity로 이동하여 Microsoft 게임 구성 편집기를 엽니다. 다음 스크린샷과 같이 최상위 메뉴에서 GDK>Microsoft Store와 연결을 선택합니다.

   

2. 열린 창에서 다음 스크린샷과 같이 Associate with Store를 선택합니다.

   

3. 열린 창에서 마법사에 나열된 단계를 따릅니다.

4. 파트너 센터 프로젝트의 값과 함께 나머지 필수 정보를 입력합니다.

   • 게시자 필드가 필요합니다. 패키지/ID/게시자 행 아래의 파트너 센터에서 값을 찾을 수 있습니다.
   • 타일 이미지 필드는 기본 이미지와 함께 남을 수 있습니다.
   • PC 탭을 선택하면 멀티 플레이어 프로토콜, 사용자 지정 설치 관리자 또는 프레임워크 종속성과 같은 추가 기능을 지정할 수 있습니다.

5. 저장을 클릭합니다.

테스트 계정 만들기

Xbox 서비스 기능을 테스트하려면 개발 샌드박스에 액세스할 수 있는 테스트 계정을 만들어야 합니다. 테스트 계정 만들기에 대한 자세한 내용은 테스트 계정 만들기를 참조하세요.

Xbox 앱 다운로드

Xbox 앱은 테스트 계정이 로그인되어 있는지 확인하는 데 유용합니다. 여기에서 다운로드할 수 있습니다. Xbox 앱

개발 샌드박스로 전환

테스트 계정을 만든 후 계정을 사용하여 다음 단계에 따라 개발 샌드박스에 액세스할 수 있습니다.

1. 샌드박스 ID를 찾으려면 파트너 센터로 이동합니다.

2. 게임으로 이동합니다.

3. 왼쪽 탐색 창에서 Xbox 서비스>게임 플레이 설정을 선택합니다.

   참고 항목

   샌드박스 ID는 게임 플레이 설정 페이지의 왼쪽 위 모서리에 있는 첫 번째 탭에 있습니다. 이름은 "ABCDEF.0"와 같은 형식입니다.

4. Unity에서 GDK>PC>Sandbox 전환으로 이동하여 Sandbox 전환기를 엽니다.

5. 샌드박스는 다음 스크린샷과 같이 샌드박스 드롭다운 목록에 자동으로 채워집니다.

   

6. Sandbox 전환 버튼을 선택합니다.

7. 샌드박스를 성공적으로 전환했는지 확인하려면 앱 시작을 선택하여 Microsoft Store 앱, Xbox 앱 및 Xbox 콘솔 컴패니언을 다시 엽니다.

8. 앞에서 생성한 Xbox 테스트 계정의 사용자 이름과 암호를 사용하여 Xbox 앱에 로그인합니다. 로그인할 수 있는지 확인합니다.

개발 샌드박스에서 RETAIL 모드로 다시 전환하려면

1. Unity에서 GDK>PC>샌드박스 전환으로 이동합니다.

2. 샌드박스 드롭다운 목록에서 소매를 선택하세요.

3. Sandbox 전환 버튼을 선택합니다.

4. 앱 시작을 선택하세요.

5. 앱 중 하나를 엽니다. 테스트 계정이 아닌 계정으로 로그인한 다음 로그인할 수 있는지 확인합니다.

게임에 Xbox 서비스 추가

이 섹션에서는 Xbox 서비스 로그인, 클라우드 저장, 도전 과제 및 상거래를 게임에 추가하는 방법을 설명합니다.

Xbox 서비스를 사용하도록 설정된 상태로 게임 빌드 및 실행

2207 GDK Unity 패키지 이전

2207 GDK Unity 패키지 이전에는 Xbox 서비스를 사용하도록 설정한 상태로 게임을 실행하려면 GDK 빌드 및 실행 명령(GDK>PC>빌드 및 실행)을 사용하여 게임을 실행해야 했습니다.

2207 GDK Unity 패키지

2207 GDK Unity 패키지부터 2022년 3월 GDK 업데이트 1 또는 2022년 6월 GDK 이상을 사용하는 경우 표준 Unity 빌드 및 실행 명령(파일>빌드 및 실행)과GDK 빌드 및 실행 명령(GDK>PC>빌드 및 실행)을 통해 게임을 실행할 수 있습니다.
또한 편집기 내에서 실행할 때 Xbox 서비스를 사용하도록 설정할 수 있습니다.

편집기 내에서 재생을 사용하도록 설정하려면 프로젝트를 Microsoft Store 앱과 연결한 후(또는 MicrosoftGame.Config를 변경할 때마다) GDK>PC>편집기 게임 구성 업데이트를 사용합니다. 사용 권한 프롬프트를 제공하고 MicrosofGame.Config를 편집기의 실행 파일 위치에 복사합니다. GDK>PC>빌드 및 실행 메뉴에서 MICROSOFT_GAME_CORE 정의를 사용하도록 설정합니다. 그런 다음 편집기 내에서 테스트할 수 있습니다.

로그인

Unity에서 로그인을 구현하려면 장면에 GdkHelper 프리팹을 추가해야 합니다.
Unity의 프로젝트 창에서 \Assets\GDK-Tools\Prefabs\GdkHelper.prefab으로 이동한 다음 GdkHelper 프리팹을 장면으로 드래그합니다.

새 기능을 테스트하려면 위의 개발 샌드박스 섹션으로 전환 섹션의 단계를 사용하여 개발 샌드박스 로 전환한 다음 GDK>PC>빌드 및 실행을 선택하여 게임을 빌드하고 실행합니다.
로그인하는 데 문제가 있는 경우 로그인 및 샌드박스 문제 해결을 참조하여 도움을 받으세요.

클라우드 저장

게임에 클라우드 저장 기능을 추가하려면 GDK.Helpers.Save 및 GDK.Helpers.LoadSaveData 함수를 사용해야 합니다.
클라우드 저장 통합의 예는 프로젝트 창의 Assets\GDK-Tools\Examples\Cloud Saves\GameSaveSampleLogic.cs에서 샘플 코드를 검토하세요.

새 기능을 테스트하려면 위의 개발 샌드박스 섹션으로 전환 섹션의 단계를 사용하여 개발 샌드박스 로 전환한 다음 GDK>PC>빌드 및 실행을 선택하여 게임을 빌드하고 실행합니다.

도전 과제

게임에 도전 과제 지원을 추가하려면 GDK.Helpers.UnlockAchievement 함수를 사용해야 합니다.
도전 과제 잠금 해제 통합의 예는 프로젝트 창의 Assets\GDK-Tools\Examples\Achievements\UnlockAchievementSampleLogic.cs에서 샘플 코드를 검토하세요.

게임에서 도전 과제에 대한 지원을 추가하는 것 외에도 다음 섹션에 설명된 대로 파트너 센터에서 도전 과제 게시를 활성화하고 도전 과제을 만들어야 합니다.

파트너 센터에서 도전 과제 게시를 활성화하려면

1. 도전 과제를 구현하기 전에 로그인이 작동하는지 확인하세요.

2. 파트너 센터로 이동합니다.

3. 왼쪽 창에서 다음 스크린샷과 같이 Xbox 설정을 선택합니다.

   

4. 소매에 도전 과제를 게시하시겠습니까?에서, 다음 스크린샷과 같이 네, 도전 과제를 게시하겠습니다를 선택합니다.

   

파트너 센터에서 새 도전 과제 만들기

1. 다음 스크린샷과 같이 왼쪽 창의 Xbox 서비스 섹션에서 게임 실행 설정을 선택합니다.

   

2. 도전 과제 페이지로 이동하려면 도전 과제 링크를 선택합니다.

3. 새 도전 과제를 선택하세요. 필요한 정보를 입력합니다.

4. 새 도전 과제가 생성되면 ID 필드에 도전 과제 ID를 기록합니다. 자동 생성되며 "1"과 같은 문자열이 됩니다.

5. 게임 실행 설정 게시 대화 상자를 열려면 게시를 선택하세요.

6. 대상: 필드를 이전에 생성한 개발자 샌드박스로 변경합니다. 확인을 선택합니다.

7. 게시 프로세스가 완료될 때까지 기다립니다.

새 기능을 테스트하려면 위의 개발 샌드박스로 전환 섹션의 단계를 사용하여 개발 샌드박스로 전환한 다음 GDK>빌드 및 실행을 선택하여 게임을 빌드하고 실행합니다.

게임에 상거래 추가

게임에서 구매하려면 GDK.Helpers.ShowPurchaseUIAsync 및 Gdk.Helpers.GetAssociatedProductsAsync 함수를 사용합니다. 게임 내 스토어 구현의 예는 프로젝트 창의 Assets\GDK-Tools\Examples\In Game Store 아래에 있는 In Game Store 예를 참조하세요.

게임에 상거래 지원을 추가한 후에는 게임에 대한 추가 기능 만들기 및 상거래 테스트 준비의 단계에 따라 구매에 대한 추가 기능을 만들고 게임을 상거래 테스트를 위해 준비해야 합니다.

게임에 대한 추가 기능 만들기

이 섹션에서는 파트너 센터 게임 내 아이템에 대한 목록을 만드는 방법을 설명합니다.

1. 파트너 센터로 이동합니다.

2. 게임으로 이동합니다.

3. 왼쪽의 탐색 창에서 추가 기능을 선택합니다.

4. 맨 위에서 [새로 만들기...] 버튼을 클릭합니다. 적절한 범주 선택

5. 필요한 정보를 입력한 다음 원하는 추가 게임 내 아이템을 만드세요.

6. 테이블에서 추가 기능을 클릭하여 세부 정보를 확인합니다.

7. 왼쪽 탐색 창에서 지속성 설정 페이지(또는 소모성 항목을 만든 경우 소모성 설정)을 선택합니다.

8. ID 세부 정보 섹션에서 세부 정보 표시 버튼을 클릭합니다.

9. Store ID 필드의 값을 복사합니다. 이 값은 이 섹션의 뒷부분에서 ShowPurchaseUIAsync API로 전달됩니다.

10. 필수 필드의 나머지 부분을 채웁니다. 쉽게 테스트할 수 있도록 가격을 무료로 설정합니다.

11. 완료되면 개발자 샌드박스에 게시합니다.

상거래 기능 테스트

이 섹션에서는 상점 API를 테스트하기 위해 환경을 준비하는 방법을 보여줍니다. 자세한 내용은 XStore 개발 및 테스트 활성화를 참조하세요.
상거래 기능을 테스트하려면 먼저 파트너 센터에 게시 섹션에 설명된 대로 게임 패키지를 파트너 센터에 업로드해야 합니다(업로드 대신에 업로드할 개발 샌드박스를 선택해야 함).

1. 위의 개발 샌드박스로 전환 섹션의 단계를 사용하여 개발 샌드박스로 전환합니다.

2. Xbox 앱에서 게임을 검색합니다.

3. 게임 다운로드 및 설치 테스트 계정에 게임 라이선스를 제공하는 방법에 대한 설명이므로 이는 중요한 단계입니다. 라이선스가 없으면 E_IAP_UNEXPECTED 오류가 발생합니다.

4. 콘솔의 경우 게임 명령 프롬프트에서 xbapp list /d을(를) 실행하여 콘텐츠 ID 및 EKB ID 값을 가져올 수 있습니다.

5. PC의 경우 명령 프롬프트를 열고 다음을 입력하여 콘텐츠 ID 값을 가져올 수 있습니다: reg query HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Store\ContentId

6. 게임 패키지의 콘텐츠 ID 값을 찾습니다.

7. \GDK-Tools\ProjectMetadata로 이동하여 MicrosoftGame.config 파일을 엽니다. 참고: Unity에서는 열 수 없습니다. 파일 탐색기에서 폴더를 찾아 다른 프로그램에서 열어야 합니다.

8. ContentIdOverride 값을 위에서 가져온 값으로 바꿉니다. 콘솔의 경우 EKBIDOverride도 설정해야 합니다. 그러나 콘솔의 MicrosoftGame.config 값은 PC와 다른 위치에 설정되어 있습니다. Xbox의 경우 Xbox 빌드 플랫폼에 대한 플레이어 설정...>게시 설정에서 찾을 수 있습니다.

참고 항목

XStore 개발 및 테스트 활성화저장소 통합 문제 해결로그인 및 샌드박스 문제 해결

배송 전 추가 고려 사항

필수 업데이트 확인 중

필수 업데이트 확인은 코드를 작성할 필요 없이 콘솔 및 PC의 PC 부트스트래퍼를 통해 자동으로 수행됩니다.

인증 테스트 사례

배송하기 전에 정책 및 Xbox 요구 사항을 살펴보는 것이 좋습니다.

TCUI 대화를 통한 Unity 고려

TCUI(타이틀 호출 가능 UI) 대화를 표시할 것으로 예상하는 모든 게임은 "Application.runInBackground"를 참으로 설정하는 것이 좋습니다. TCUI 대화 상자를 성공적으로 표시하는 방법에 대한 자세한 내용은 Window 디스플레이 모드 및 타이틀 호출 가능 UI 대화를 참조하세요.

파트너 센터에 게시

이 섹션에서는 파트너 센터에서 게임을 패키징, 업로드 및 게시하는 방법에 대해 설명합니다.

1. Unity에서 GDK>PC>빌드 및 실행으로 이동합니다.

2. 다음 스크린샷과 같이 저장소에 업로드할 패키지 생성 확인란을 선택합니다.

   

3. 빌드를 선택합니다.

4. 메시지가 나타나면 빌드 패키지 파일의 폴더를 선택합니다.

5. 빌드가 완료되면 Microsoft Store에 업로드해야 하는 파일이 들어 있는 폴더가 열립니다.

6. 파트너 센터로 이동합니다.

7. 다음 스크린샷과 같이 창에서 패키지를 선택하세요.

   

8. 다음 스크린샷과 같이 드래그 영역으로 파일을 끌어 이 섹션의 5단계에서 .msixvc, .ekb 및 .xml 파일을 업로드합니다. .m6vc 파일을 업로드할 수 없는 경우 Microsoft 담당자에게 도움을 요청하세요.

   

9. 다음 스크린샷과 같이 속성, 연령 등급, Store 목록 및 가격 및 가용성 섹션에 필요한 정보를 입력합니다.

   

10. Store 목록 페이지에서 트레일러를 업로드해야 합니다. 트레일러는 UI에서 필수로 나열되지 않지만 게임에 필요합니다.

11. 게시하려면 다음 스크린샷에 표시된 것처럼 검토 및 게시를 선택하세요.

    

12. 소매를 선택하세요. 이 작업을 수행하면 게임이 인증을 위해 제출됩니다.

    참고 항목

    수익 SKU에 대한 오류가 표시되면 패키지가 인증 프로세스의 일부로 생성됩니다. 패키지를 소매에 게시하려면 인증을 거쳐야 합니다.

13. 게임이 인증을 통과하면 소매점에 릴리스될 수 있습니다. 게임이 언제 게임 개요 페이지의 게시 상태 섹션에서 인증을 통과했는지 확인할 수 있습니다.

참고 항목

로그인 및 샌드박스 문제 해결