GDKX로 첫 콘솔 타이틀 빌드 및 실행

이 워크스루는 작은 sample-game 타이틀을 생성하고, XBOX Series X|S 콘솔용으로 빌드하며, 전체 게임을 XBOX 개발 키트에 배포하고, 시작 실패를 진단하며, 설치 가능한 XVC를 생성하는 엔드-투-엔드 프로세스를 다룹니다. 완성된 샘플은 C++, Direct3D 12, XBOX Extensions를 포함한 GDK(GDKX)를 사용합니다. 또한 선택적 렌더링 헬퍼로 DirectXTK12를 사용합니다. 두 패들 모두 컴퓨터가 조작하므로 그래픽, 게임플레이, 효과를 반복 작업하는 동안 게임이 무인으로 실행될 수 있습니다.

GitHub 또는 WinGet을 통해 사용 가능한 공용 GDK는 Windows PC 게임 개발만 지원합니다. XBOX 콘솔 실행 파일을 컴파일하고 배포하려면 XBOX Secure Downloads에서 XBOX Extensions가 포함된 GDK(GDKX)를 설치하세요. 액세스에는 승인된 XBOX 개발자 계정이 필요합니다. ID@XBOX 온보딩 및 GDK 리소스 및 다운로드 액세스를 참조하세요.

무엇을 빌드하나요

이 워크스루가 끝나면 다음을 얻게 됩니다:

네이티브 XBOX GDK 프로젝트 (UWP 프로젝트 아님).
XBOX Series X|S 콘솔 및 XBOX One 제품군 콘솔용 Debug, Profile, Release 구성.
점수, 예측 패들 AI, 파티클 효과, 모션 트레일, 텍스처가 적용된 원형 퍽이 있는 자동 플레이 샘플 게임.
XBOX 개발 키트에서 실행되는 완전한 loose 파일 배포.
개발 키트에서 설치 및 테스트 가능한 선택적 Store 연결 XVC.

시작하기 전에

이 워크스루는 다음 환경에서 검증되었습니다:

Visual Studio 2022 Enterprise 17.14.
2026년 4월 Update 2 GDKX, 에디션 260402.
XBOX Series X|S 콘솔용 Gaming.XBOX.Scarlett.x64.
XBOX One 제품군 콘솔용 Gaming.XBOX.XboxOne.x64.
DirectXTK12 커밋 e656d54637b2830fc6eb5ecd9b329a9c72cb87d4.

다른 릴리스로 워크스루를 따라 하는 경우 260402 대신 개발 PC에 설치된 GDK 에디션을 사용하세요.

1단계: 작업 폴더 생성

PowerShell을 열고 빈 루트 폴더를 만듭니다.

New-Item -ItemType Directory -Path D:\repos\sample-game -Force

이 워크스루에서 사용된 최종 프로젝트 레이아웃은 다음과 같습니다:

D:\repos\sample-game
|-- external
|   `-- DirectXTK12
|-- tools
|   `-- BuildAssets.ps1
|-- sample-game
|   |-- Assets
|   |-- DeviceResources.cpp
|   |-- DeviceResources.h
|   |-- Game.cpp
|   |-- Game.h
|   |-- GameTuning.h
|   |-- GraphicsLogo.png
|   |-- LargeLogo.png
|   |-- Main.cpp
|   |-- MicrosoftGameConfig.mgc
|   |-- ParticleSystem.cpp
|   |-- ParticleSystem.h
|   |-- sample-gameSimulation.cpp
|   |-- sample-gameSimulation.h
|   |-- pch.cpp
|   |-- pch.h
|   |-- SmallLogo.png
|   |-- SplashScreen.png
|   |-- StepTimer.h
|   |-- StoreLogo.png
|   `-- sample-game.vcxproj
`-- sample-game.sln

Visual Studio는 Direct3D 12 XBOX Game 템플릿에서 DeviceResources.*, Main.cpp, pch.*, StepTimer.h, 셸 비주얼 PNG 파일을 생성합니다. 샘플별 소스를 추가할 때 이러한 생성된 파일을 그대로 유지하세요.

2단계: XBOX GDK 설치 확인

GDKX와 함께 설치된 XBOX Series X|S VS 2022 Gaming Command Prompt를 엽니다. 바로가기는 일반적으로 시작 메뉴의 Microsoft GDK 아래에 있습니다. 일반 명령 프롬프트에서 환경을 초기화할 수도 있습니다:

call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxScarlettVS2022 260402

XBOX 빌드 및 배포 도구가 사용 가능한지 확인합니다:

echo %GXDKEDITION%
where msbuild
where cl
where xbconnect
where xbapp
where makepkg

다음의 경우 GDK 설치는 콘솔 개발 준비가 되지 않은 것입니다:

GXDKEDITION이 비어 있음.
XBOX 명령 프롬프트 바로가기가 없음.
Visual Studio에 XBOX 프로젝트 템플릿이 표시되지 않음.
Gaming.XBOX.Scarlett.x64 MSBuild 플랫폼을 사용할 수 없음.
xbconnect 또는 xbapp을 찾을 수 없음.

Desktop GDK 명령 프롬프트와 Desktop 템플릿만 사용할 수 있는 경우, GDKX 대신 공용 PC GDK가 설치되었을 가능성이 큽니다.

3단계: 네이티브 XBOX 프로젝트 생성

Visual Studio 2022를 열고 Create a new project 선택

Language를 **C++**로, Platform을 XBOX로, Project type을 Games로 설정합니다.

Direct3D 12 XBOX Game 선택

프로젝트 이름을 sample-game으로, 위치를 D:\repos\sample-game으로 설정합니다.

Place solution and project in the same directory는 선택 해제

솔루션은 루트에, 프로젝트는 D:\repos\sample-game\sample-game에 위치하도록 합니다.

프로젝트 생성

지원되는 워크플로는 Visual Studio를 통해 프로젝트를 생성하는 것입니다. d3d12game_gx 템플릿 파일을 수동으로 복사하는 것은 복구 기법일 뿐, 권장되는 새 프로젝트 워크플로가 아닙니다.

프로젝트가 UWP가 아닌지 확인

게임 코드를 추가하기 전에 프로젝트가 다음 조건을 만족하는지 확인합니다:

MicrosoftGameConfig.mgc를 포함.
Gaming.XBOX.*.x64 프로젝트 플랫폼 사용.
XBOX GDK 플랫폼 라이브러리에 링크됨.
타이틀 구성으로 Package.appxmanifest를 사용하지 않음.
Universal Windows 템플릿이 아닌 Direct3D 12 XBOX Game에서 생성됨.

프로젝트가 UWP인 경우 삭제하고 XBOX GDK 템플릿에서 새 프로젝트를 만드세요. 생성된 UWP 프로젝트를 변환하는 것보다 올바른 템플릿으로 시작하는 것이 오류 가능성이 훨씬 낮습니다.

4단계: GDK 에디션 고정 및 콘솔 대상 구성

GDK 에디션을 고정하면 향후 GDK 설치가 프로젝트에서 사용하는 툴체인을 조용히 변경하는 것을 방지할 수 있습니다. sample-game.vcxproj의 주 속성 그룹에 다음을 설정합니다:

<XdkEditionTarget>260402</XdkEditionTarget>

Visual Studio Configuration Manager를 사용하여 다음 솔루션 구성을 확인합니다:

Configuration	Platform
Debug	`Gaming.XBOX.Scarlett.x64`
Profile	`Gaming.XBOX.Scarlett.x64`
Release	`Gaming.XBOX.Scarlett.x64`
Debug	`Gaming.XBOX.XboxOne.x64`
Profile	`Gaming.XBOX.XboxOne.x64`
Release	`Gaming.XBOX.XboxOne.x64`

타이틀이 XBOX Series X|S 콘솔만 지원하는 경우, XBOX One 제품군 콘솔 구성을 생략할 수 있습니다. 세대 간 동일 타이틀 출시에 관해서는 Cross-gen을 참조하세요.

5단계: 수정되지 않은 템플릿 빌드

종속성이나 게임 코드를 추가하기 전에 생성된 템플릿을 빌드합니다. 이렇게 하면 툴체인 문제와 샘플에서 발생하는 문제를 분리할 수 있습니다. XBOX Series X|S VS 2022 Gaming Command Prompt에서:

msbuild D:\repos\sample-game\sample-game.sln /m /restore /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal

XBOX One 제품군 콘솔의 경우 XBOX One 명령 환경을 초기화하고 XBOX One 플랫폼을 빌드합니다:

call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxVS2022 260402
msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.XboxOne.x64 /nologo /verbosity:minimal

기본 XBOX 템플릿이 성공적으로 빌드될 때까지 계속하지 마세요.

6단계: DirectXTK12를 선택적 헬퍼로 추가

DirectXTK12는 GDK 타이틀 생성에 필수는 아닙니다. XBOX GDK 템플릿은 이미 Direct3D 12를 사용해 게임을 빌드하는 데 필요한 Direct3D 12 디바이스, 커맨드 큐, 스왑 체인, 게임 루프를 제공합니다. 이 샘플은 별도의 Microsoft 오픈 소스 DirectXTK12 라이브러리를 사용하여 스프라이트 렌더링, 디스크립터 관리, 텍스처 로딩, 리소스 업로드, 그래픽 메모리 관리에 필요한 저수준 렌더링 유틸리티 코드의 양을 줄입니다. 타이틀은 이러한 헬퍼를 자체 엔진이나 직접적인 D3D12 구현으로 대체할 수 있습니다. DirectXTK12를 프로젝트에 클론합니다:

Set-Location D:\repos\sample-game
New-Item -ItemType Directory -Path .\external -Force
git clone https://github.com/microsoft/DirectXTK12.git .\external\DirectXTK12
git -C .\external\DirectXTK12 checkout e656d54637b2830fc6eb5ecd9b329a9c72cb87d4

Visual Studio에서:

external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj를 솔루션에 추가합니다.
sample-game에서 DirectXTK12를 프로젝트 참조로 추가합니다.
include 디렉터리에 $(SolutionDir)external\DirectXTK12\Inc를 추가합니다.
두 프로젝트를 동일한 XBOX 플랫폼 및 구성으로 빌드합니다.

sample-game 프로젝트는 다음 속성을 사용합니다:

<DirectXTK12Dir>$(SolutionDir)external\DirectXTK12\</DirectXTK12Dir>

그런 다음 include 경로와 프로젝트 참조를 추가합니다:

<AdditionalIncludeDirectories>$(DirectXTK12Dir)Inc;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>

<ProjectReference Include="$(DirectXTK12Dir)DirectXTK_GDKX_2022.vcxproj">
  <Project>{94F17A4D-611B-4B81-8806-B6735910AB31}</Project>
  <Name>DirectXTK12</Name>
</ProjectReference>

이 프로젝트에서 DirectXTK12 셰이더 빌드 명령은 명시적인 프로젝트 상대 경로를 통해 CompileShaders.cmd를 호출하도록 변경되었습니다:

Command="&quot;$(ProjectDir)Src\Shaders\CompileShaders.cmd&quot; gxdk scarlett"

이는 MSBuild가 셰이더 컴파일러를 호출할 때 현재 명령 디렉터리에 의존하는 것을 방지합니다.

7단계: 게임 코드 추가

이 샘플은 시뮬레이션이 Direct3D 코드를 변경하지 않고 조정될 수 있도록 게임플레이 상태를 렌더링과 분리합니다. DeviceResources.*, Main.cpp, pch.*, StepTimer.h와 5개의 셸 비주얼 PNG 파일을 포함한 템플릿 생성 파일을 그대로 유지합니다. 다음 샘플별 파일을 프로젝트에 추가합니다:

파일	용도
`GameTuning.h`	아레나, 패들, 퍽, AI, 트레일, 파티클 상수.
`sample-gameSimulation.h/.cpp`	퍽 이동, 패들 이동, 충돌, 점수, 서브, AI.
`ParticleSystem.h/.cpp`	고정 크기 파티클 풀 및 임팩트 이미터.
`Game.h/.cpp`	DirectXTK12 리소스, 게임 업데이트, 렌더링.
`tools\BuildAssets.ps1`	흰색 스프라이트 및 퍽에 대한 재현 가능한 DDS 생성.

고정 시뮬레이션 스텝 사용

이 프로젝트는 템플릿의 StepTimer를 120Hz 고정 업데이트로 사용합니다. 고정 스텝은 프레임 시간이 변동해도 충돌 반응과 AI 동작을 안정적으로 유지합니다. 시뮬레이션은 다음을 포함합니다:

두 개의 패들 상태.
하나의 원형 퍽 상태.
좌우 점수.
서브 지연 및 교대로 이루어지는 서브 방향.
패들, 벽, 골 충돌에 대한 임팩트 이벤트.

원형 퍽 충돌 구현

각 패들을 축 정렬 사각형으로, 퍽을 원으로 처리합니다:

퍽 중심에 가장 가까운 패들 사각형 위 지점을 찾습니다.
해당 지점에서 퍽 중심까지의 제곱 거리를 측정합니다.
거리가 퍽 반지름의 제곱보다 크지 않으면 충돌이 발생한 것입니다.
반복 겹침을 방지하기 위해 퍽을 패들 밖으로 이동합니다.
히트 오프셋과 패들 속도로부터 나가는 각도를 계산합니다.
퍽의 속도를 최대치까지 조금씩 증가시킵니다.

이렇게 하면 퍽이 정사각형 텍스처로 그려져도 물리는 원형으로 유지됩니다.

예측 자동 플레이 추가

각 패들은:

퍽이 자신의 수평 위치를 가로지를 지점을 예측합니다.
예측 좌표를 위/아래 아레나 벽에서 반사시킵니다.
고정된 반응 간격으로 목표를 업데이트합니다.
스냅 대신 가속과 최대 속도 제한을 사용합니다.
작은 결정론적 조준 오차를 추가합니다.

경기에서 점수가 나도록 각 진영은 가끔 짧은 실수 창에 들어가 예측된 인터셉트에서 의도적으로 멀어집니다. 초기 실수 타이머를 어긋나게 배치하여 두 패들이 동시에 놓치지 않도록 합니다.

DirectXTK12로 장면 렌더링

다음을 생성합니다:

GraphicsMemory.
흰색 텍스처와 퍽 텍스처를 포함하는 디스크립터 힙.
일반 알파 SpriteBatch.
파티클용 가산 SpriteBatch.
ResourceUploadBatch 및 CreateDDSTextureFromFile을 통한 DDS 텍스처.

SpriteBatch로 아레나, 중앙선, 패들, 점수, 퍽 트레일, 퍽을 그립니다. 가산 패스에서 파티클을 그립니다. 완성된 샘플은 1920x1080 가상 좌표계로 렌더링되며 해당 장면을 출력 뷰포트로 스케일링합니다.

효과는 절제된 수준으로 유지

최종 튜닝은 다음과 같습니다:

짧게 지수적으로 감쇠하는 화면 흔들림.
더 작은 줄무늬 모양의 임팩트 파티클.
벽 히트보다 패들 히트에서 더 많은 파티클.
골에서는 더 강한 버스트.
낮은 알파의 퍽 트레일.
짧은 녹색 임팩트 플래시.

이러한 변경은 게임이 만화처럼 보이거나 패들 충돌이 시각적으로 거슬리지 않게 하면서 임팩트 피드백을 유지했습니다.

8단계: 텍스처 자산 생성 및 배포

샘플에는 다음이 필요합니다:

Assets\white.dds: 사각형과 파티클을 그리는 데 사용되는 1x1 흰색 RGBA 텍스처.
Assets\xbox_logo.dds: 퍽에 사용되는 256x256 RGBA 텍스처.

자산 스크립트는:

소스 로고를 로드합니다.
256x256으로 크기를 조정합니다.
원형 알파 마스크(페더링)를 적용합니다.
DX10 헤더가 있는 RGBA8 DDS를 씁니다.
1x1 흰색 DDS를 만듭니다.

PowerShell에서 실행합니다:

Set-Location D:\repos\sample-game
.\tools\BuildAssets.ps1

sample-game.vcxproj에서 두 DDS 파일 모두를 배포 콘텐츠로 등록합니다:

<CopyFileToFolders Include="Assets\white.dds">
  <DeploymentContent>true</DeploymentContent>
  <DestinationFileName>Assets\%(Filename)%(Extension)</DestinationFileName>
</CopyFileToFolders>
<CopyFileToFolders Include="Assets\xbox_logo.dds">
  <DeploymentContent>true</DeploymentContent>
  <DestinationFileName>Assets\%(Filename)%(Extension)</DestinationFileName>
</CopyFileToFolders>

표준 헤더에 DX10 확장을 포함한 DDS 파일은 픽셀 데이터 앞에 148바이트가 있습니다. 원래 세션에서 사용자 지정 DDS 라이터는 152바이트를 방출했고 타이틀은 텍스처 로딩 중 0x8007000D로 실패했습니다. 사용자 지정 DDS 라이터를 사용하는 경우 배포 전에 헤더 레이아웃을 검증하세요.

9단계: 게임 빌드

XBOX Series X|S VS 2022 Gaming Command Prompt에서:

msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal

Loose 빌드 출력 경로는 다음과 같습니다:

D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug

출력에 다음이 포함되어 있는지 확인합니다:

sample-game.exe
MicrosoftGame.config
셸 비주얼 PNG 파일
Assets\white.dds
Assets\xbox_logo.dds
필수 런타임 DLL
빌드가 생성한 Game OS 이미지 또는 기타 배포 메타데이터

프로젝트 소스는 MicrosoftGameConfig.mgc라는 이름입니다. GDK MGCCompile 빌드 항목이 이를 검증하고 빌드 출력에 MicrosoftGame.config를 내보냅니다. 배포와 패키징 모두 생성된 .config 파일을 사용합니다. Game config를 참조하세요.

10단계: XBOX 개발 키트에 연결

콘솔의 Tools IP 주소 또는 호스트 이름을 사용하여 기본 콘솔을 설정합니다:

xbconnect <console-address>

저장된 콘솔을 확인합니다:

xbconnect /B

연결 진단을 실행합니다:

xbconnect /DX

타이틀이 Partner Center 샌드박스를 사용하는 경우 대소문자를 구분하는 샌드박스 ID를 구성하고 콘솔을 다시 시작합니다:

xbconfig sandboxid=<sandbox-id>
xbreboot
xbconnect /WS

현재 샌드박스를 표시합니다:

xbconfig sandboxid

11단계: 전체 게임 배포

전체 빌드 출력 폴더를 배포합니다:

xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug"

sample-game.exe만 복사하지 마세요. 타이틀에는 MicrosoftGame.config, 자산, 런타임 종속성, 셸 이미지, 배포 메타데이터도 필요합니다. 실행 파일만 복사한 것은 유효한 전체 배포가 아닙니다.

자산 또는 구성을 변경한 뒤 깨끗하게 재배포하려면:

xbapp list
xbapp terminate <package-family-name-or-AUMID>
xbapp uninstall <package-full-name>
xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug"

배포 후 xbapp list를 사용하여 등록된 패키지 전체 이름과 애플리케이션 사용자 모델 ID(AUMID)를 찾습니다. AUMID는 !Game으로 끝납니다.

12단계: 게임 실행 및 확인

xbapp list가 보고한 정확한 AUMID를 실행합니다:

xbapp launch <package-family-name>!Game

타이틀 프로세스를 기다립니다:

xbconnect /WTP:60

패키지가 실행 중인지 확인합니다:

xbapp query <package-full-name>

예상 결과는 다음과 같습니다:

Package execution state: 1 (running)

이 시점에서 자동 플레이 매치가 개발 키트에 표시되어야 합니다.

13단계: 즉시 실행 실패 진단

게임이 즉시 종료된다면 실행 파일이 복사되었다는 이유만으로 배포가 성공했다고 가정하지 마세요.

마지막 타이틀 결과 가져오기

xbapp lastgamedetails

디버그 출력 모니터링

한 명령 프롬프트에서 디버그 출력 모니터를 시작합니다:

xbdbgmon /t /v

다른 곳에서 게임을 실행합니다:

xbapp launch <package-family-name>!Game

샘플은 다음 지점에 OutputDebugStringA 메시지를 추가했습니다:

게임 초기화.
DirectXTK12 리소스 생성.
각 텍스처 로드.
스프라이트 파이프라인 생성.
텍스처 업로드 완료.
프레임 예외.

원래 세션의 시작 실패는 white.dds 로딩으로 좁혀졌습니다. 로더는 0x8007000D를 반환했고, 이는 잘못된 형식의 DDS 데이터를 식별했습니다. DDS 헤더를 수정하고 깨끗한 전체 배포를 수행하자 실행이 정상화되었습니다. 더 많은 실행 진단은 실패를 재현하면서 xbWatson을 실행하세요. Error handling도 참조하세요.

14단계: 안전하게 반복 작업

대부분의 코드 전용 변경 사항의 경우:

Debug를 빌드합니다.
실행 중인 패키지를 종료합니다.
전체 출력 폴더를 배포합니다.
등록된 AUMID를 실행합니다.
패키지 상태를 쿼리합니다.

MicrosoftGameConfig.mgc, 자산 또는 배포 메타데이터가 변경된 경우 다시 배포하기 전에 이전 loose 배포를 제거하세요. 이렇게 하면 오래된 파일이나 등록 데이터가 수정 사항을 가리는 것을 방지할 수 있습니다.

선택: XVC 생성 및 테스트

Loose 배포는 가장 빠른 개발 루프입니다. 소매 유사 설치를 테스트하거나 Partner Center에 제출할 패키지를 준비할 때 XVC를 생성하세요. 전체 패키징 레퍼런스는 Packaging을 참조하세요.

MicrosoftGame.config를 Partner Center와 연결

제품의 Game setup > Identity details에서 다음 값을 얻습니다:

Package Identity Name.
Package Identity Publisher.
Publisher Display Name.
Store ID.
XBOX Title ID.
MSA App ID.

소스 제어 예시에는 자리 표시자를 사용하세요. 다른 제품의 신원을 복사하지 마세요. XBOX Series X|S 콘솔의 경우 중요한 구조는 다음과 같습니다:

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
  <Identity Name="REPLACE-WITH-PACKAGE-IDENTITY-NAME"
            Publisher="REPLACE-WITH-PACKAGE-IDENTITY-PUBLISHER"
            Version="1.0.0.0"/>

  <ExecutableList>
    <Executable Name="sample-game.exe"
                TargetDeviceFamily="Scarlett"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="sample-game"
                PublisherDisplayName="REPLACE-WITH-PUBLISHER-DISPLAY-NAME"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="sample-game"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>

  <MSAAppId>REPLACE-WITH-MSA-APP-ID</MSAAppId>
  <TitleId>REPLACE-WITH-XBOX-TITLE-ID</TitleId>
  <StoreId>REPLACE-WITH-STORE-ID</StoreId>
</Game>

XBOX Series X|S 콘솔 패키지에는 TargetDeviceFamily="Scarlett"이 필요합니다. XBOX One 제품군 콘솔 패키지에는 별도의 구성을 사용하세요.

Release 구성 빌드

msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Release /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal

패키지 콘텐츠 준비

Release 출력을 준비 디렉터리에 복사하되, gameos.xvd는 콘텐츠 맵 바깥에 유지하고 PDB 파일은 일반 패키지 콘텐츠로 포함하지 마세요.

$source  = 'D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release'
$root    = 'D:\repos\sample-game\packages\Scarlett\Release'
$staging = Join-Path $root 'staging'
$output  = Join-Path $root 'output'

Remove-Item $staging, $output -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path $staging, $output -Force | Out-Null

Get-ChildItem $source -Force |
    Where-Object { $_.Name -ne 'gameos.xvd' -and $_.Extension -ne '.pdb' } |
    Copy-Item -Destination $staging -Recurse -Force

레이아웃 생성

makepkg genmap /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging"

이 작은 샘플의 경우 결과 레이아웃은 하나의 실행 청크를 포함합니다:

<Package>
  <Chunk Id="1000" Marker="Launch">
    <FileGroup DestinationPath="."        SourcePath="."        Include="*.*" />
    <FileGroup DestinationPath=".\Assets" SourcePath=".\Assets" Include="*.*" />
  </Chunk>
</Package>

개발 키트 테스트 패키지 생성

기본 테스트 암호화는 로컬 개발 키트 설치에 유용합니다:

makepkg pack /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" /pd "D:\repos\sample-game\packages\Scarlett\Release\output" /gameos "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release\gameos.xvd" /symbolpaths "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release" /validationcritical /loggable

StoreId가 MicrosoftGame.config에 있는 경우, 일반 Store 제출에는 /productid가 필요하지 않습니다. 문서화된 오프라인 또는 디스크 시나리오에서 특별히 요구되지 않는 한 생략하세요.

Partner Center 패키지에는 제출 암호화 사용

sample-game 패키지는 처음에 설치와 실행을 확인할 수 있도록 개발 키트 테스트 암호화로 생성되었습니다. 제출될 패키지의 경우 현재 패키징 정책을 따르고 /lk 또는 /l을 사용하세요. 권장되는 반복 가능한 /lk 워크플로:

makepkg genkey /ekb D:\secure\sample-game.lekb
makepkg pack /lk D:\secure\sample-game.lekb /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" /pd "D:\repos\sample-game\packages\Scarlett\Release\output" /gameos "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release\gameos.xvd" /symbolpaths "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release" /validationcritical /loggable

LEKB를 안전하게 보관하세요. 소스 제어에 커밋하지 마세요.

XVC 설치 및 실행

xbapp install "<path-to-package>.xvc"
xbapp list
xbapp launch <store-associated-package-family-name>!Game
xbapp query <store-associated-package-full-name>

테스트가 완료되면 패키지를 종료합니다:

xbapp terminate <store-associated-package-family-name>!Game

일반적인 문제와 해결책

증상	원인	해결 방법
Desktop 템플릿만 사용 가능	XBOX Extensions 없이 공용 PC GDK만 설치됨	XBOX Secure Downloads에서 GDKX와 Visual Studio 통합을 설치합니다.
프로젝트에 `Package.appxmanifest`가 있고 UWP를 대상으로 함	잘못된 Visual Studio 템플릿이 선택됨	Direct3D 12 XBOX Game으로 프로젝트를 다시 생성합니다.
`Gaming.XBOX.Scarlett.x64`를 사용할 수 없음	XBOX GDK 플랫폼 또는 Visual Studio 확장이 누락됨	일치하는 GDKX 릴리스와 Visual Studio 통합을 복구하거나 다시 설치합니다.
타이틀이 실행되었다가 즉시 종료됨	배포 파일 누락 또는 런타임 초기화 실패	전체 빌드 출력을 배포하고 `xbapp lastgamedetails` 및 `xbdbgmon`을 검사합니다.
DDS 로딩이 `0x8007000D` 반환	잘못된 형식의 DDS 헤더 또는 지원되지 않는 데이터	DDS를 다시 생성하고 148바이트 DDS와 DX10 헤더를 확인합니다.
자산 변경이 나타나지 않음	오래된 loose 배포	종료, 제거, 전체 재배포.
`makepkg`가 구성을 거부함	`TargetDeviceFamily`가 누락되었거나 잘못됨	XBOX Series X\|S 콘솔에는 `Scarlett`, XBOX One 제품군 콘솔에는 `XboxOne`을 설정합니다.
제품 신원이 여러 곳에서 제공되고 있음	Store 신원이 이미 게임 config에 있음에도 `/productid`가 추가됨	게임 config에 `StoreId`를 유지하고 일반 Store 제출에는 `/productid`를 생략합니다.
PDB 파일이 패키지 맵 또는 검증 문제를 유발	심볼이 게임 콘텐츠로 포함됨	PDB를 스테이징에서 제외하고 빌드 디렉터리를 `/symbolpaths`로 전달합니다.
Store 연결 실행이 핸드셰이크 중 실패로 보임	타이틀이 아직 시작 중이거나 진단이 불완전할 수 있음	`/WaitToExit`, `/show:all`, `/LogModuleLoads`로 실행한 다음 패키지 상태를 쿼리합니다.

참고 자료

마지막 수정일 2026년 8월 24일

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

무엇을 빌드하나요

시작하기 전에

1단계: 작업 폴더 생성

2단계: XBOX GDK 설치 확인

3단계: 네이티브 XBOX 프로젝트 생성

프로젝트가 UWP가 아닌지 확인

4단계: GDK 에디션 고정 및 콘솔 대상 구성

5단계: 수정되지 않은 템플릿 빌드

6단계: DirectXTK12를 선택적 헬퍼로 추가

7단계: 게임 코드 추가

고정 시뮬레이션 스텝 사용

원형 퍽 충돌 구현

예측 자동 플레이 추가

DirectXTK12로 장면 렌더링

효과는 절제된 수준으로 유지

8단계: 텍스처 자산 생성 및 배포

9단계: 게임 빌드

10단계: XBOX 개발 키트에 연결

11단계: 전체 게임 배포

12단계: 게임 실행 및 확인

13단계: 즉시 실행 실패 진단

마지막 타이틀 결과 가져오기

디버그 출력 모니터링

14단계: 안전하게 반복 작업

선택: XVC 생성 및 테스트

MicrosoftGame.config를 Partner Center와 연결

Release 구성 빌드

패키지 콘텐츠 준비

레이아웃 생성

개발 키트 테스트 패키지 생성

Partner Center 패키지에는 제출 암호화 사용

XVC 설치 및 실행

일반적인 문제와 해결책

참고 자료

​무엇을 빌드하나요

​시작하기 전에

​1단계: 작업 폴더 생성

​2단계: XBOX GDK 설치 확인

​3단계: 네이티브 XBOX 프로젝트 생성

​프로젝트가 UWP가 아닌지 확인

​4단계: GDK 에디션 고정 및 콘솔 대상 구성

​5단계: 수정되지 않은 템플릿 빌드

​6단계: DirectXTK12를 선택적 헬퍼로 추가

​7단계: 게임 코드 추가

​고정 시뮬레이션 스텝 사용

​원형 퍽 충돌 구현

​예측 자동 플레이 추가

​DirectXTK12로 장면 렌더링

​효과는 절제된 수준으로 유지

​8단계: 텍스처 자산 생성 및 배포

​9단계: 게임 빌드

​10단계: XBOX 개발 키트에 연결

​11단계: 전체 게임 배포

​12단계: 게임 실행 및 확인

​13단계: 즉시 실행 실패 진단

​마지막 타이틀 결과 가져오기

​디버그 출력 모니터링

​14단계: 안전하게 반복 작업

​선택: XVC 생성 및 테스트

​MicrosoftGame.config를 Partner Center와 연결

​Release 구성 빌드

​패키지 콘텐츠 준비

​레이아웃 생성

​개발 키트 테스트 패키지 생성

​Partner Center 패키지에는 제출 암호화 사용

​XVC 설치 및 실행

​일반적인 문제와 해결책

​참고 자료

무엇을 빌드하나요

시작하기 전에

1단계: 작업 폴더 생성

2단계: XBOX GDK 설치 확인

3단계: 네이티브 XBOX 프로젝트 생성

프로젝트가 UWP가 아닌지 확인

4단계: GDK 에디션 고정 및 콘솔 대상 구성

5단계: 수정되지 않은 템플릿 빌드

6단계: DirectXTK12를 선택적 헬퍼로 추가

7단계: 게임 코드 추가

고정 시뮬레이션 스텝 사용

원형 퍽 충돌 구현

예측 자동 플레이 추가

DirectXTK12로 장면 렌더링

효과는 절제된 수준으로 유지

8단계: 텍스처 자산 생성 및 배포

9단계: 게임 빌드

10단계: XBOX 개발 키트에 연결

11단계: 전체 게임 배포

12단계: 게임 실행 및 확인

13단계: 즉시 실행 실패 진단

마지막 타이틀 결과 가져오기

디버그 출력 모니터링

14단계: 안전하게 반복 작업

선택: XVC 생성 및 테스트

MicrosoftGame.config를 Partner Center와 연결

Release 구성 빌드

패키지 콘텐츠 준비

레이아웃 생성

개발 키트 테스트 패키지 생성

Partner Center 패키지에는 제출 암호화 사용

XVC 설치 및 실행

일반적인 문제와 해결책

참고 자료