다음을 통해 공유

PC용 C# 사용자 지정 엔진 통합: 시작하기

  • 아티클

PC의 Microsoft Store에 게시하기 위해 게임을 준비 중이고 게임에서 GDK에 대한 지원이 기본 제공되지 않은 C# 기반 엔진을 사용하는 경우 이 항목을 사용하세요.

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

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

GDK를 C# 게임에 통합

GDK를 C# 게임에 통합하려면 게임에 3가지가 필요합니다.

  1. 기본 구현을 위해 C# 친화적인 기능을 제공하는 "API 계층"입니다.
  2. 관리 계층(Unity와 같은 C# 엔진)과 비관리 계층(GRTS/XSAPI 런타임 dll) 간의 상호 운용성을 처리하는 "Interop 계층"입니다.
  3. 함수의 런타임 구현을 실제로 포함하는 동적 링크 라이브러리.

게임 런타임 서비스 및 Xbox 서비스 API에 대한 요구 사항을 프로젝트에 추가

다음 단계에서는 게임 런타임 서비스(GRTS) 및 Xbox 서비스 API(XSAPI)를 사용하기 위한 모든 요구 사항이 있는지 확인하기 위해 프로젝트에 적용해야 하는 변경 내용을 간략하게 설명합니다.

  1. https://github.com/microsoft/gdk-unity-package에서 Unity GDK 플러그 인 git 리포지토리의 .zip을 복제하거나 다운로드합니다.

  2. gdk-unity-package/Tools/XGamingRuntimeSDK/에 있는 XGamingRuntimeSDK.sln을 엽니다.

    솔루션 파일은 Visual Studio 2017용이며 필요한 C# 버전은 6 이상입니다.

  3. XGamingRuntime 프로젝트에서 XBL\Social\XblSocialRelationshipFilter.cs를 열고 파일 상단의 using UnityEngine; 줄을 메모 처리하고 저장합니다.

  4. XGamingRuntimeThunks 프로젝트와 XGamingRuntime 프로젝트를 빌드합니다.

  5. C# 게임 프로젝트를 엽니다.

  6. 프로젝트를 대상 x64로 설정합니다.

  7. XGamingRuntime 프로젝트로 빌드한 XGamingRuntime.dll에 대한 참조를 추가합니다.
    DLL은 gdk-unity-package-main\Tools\XGamingRuntimeSDK\Gaming.Desktop.x64\Debug|Release에서 찾을 수 있습니다.

  8. XGamingRuntime.dll, XGamingRuntimeThunks.dll, XCurl.dll이 .exe가 빌드된 동일한 디렉터리에 복사되었는지 확인합니다.
    DLL은 gdk-unity-package-main\Tools\XGamingRuntimeSDK\Gaming.Desktop.x64\Debug|Release에서 찾을 수 있습니다.

    참고: 엔진에서 실행할 때 다른 .exe를 사용하는 편집기의 실행 기능을 지원하는 경우 .exe가 이러한 .dls도 참조하는지 확인해야 합니다. .dlls가 .exe에서 참조되지 않으면 실행 편집기 기능을 사용할 때 Xbox 서비스가 작동하지 않습니다.

  9. Microsoft.Xbox.Services.GDK.C.Thunks.dll이 .exe가 빌드된 동일한 디렉터리에 복사되었는지 확인합니다.
    아래의 GDK 설치 경로에서 DLL을 찾을 수 있습니다.

    • (2024년 10월 이상) C:\Program Files (x86)\Microsoft GDK\241000\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Debug|석방

    • (2024년 6월 또는 그 이전) C:\Program Files (x86)\Microsoft GDK\220300\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Debug|릴리스합니다.
      DLL 이름은 GDK에서 밑줄 대신 마침표를 사용하며 마침표 대신 밑줄을 사용하도록 이름을 바꿔야 합니다.

    참고: 엔진에서 실행할 때 다른 .exe를 사용하는 편집기의 실행 기능을 지원하는 경우 .exe가 이러한 .dll도 참조하는지 확인해야 합니다. .dll이 .exe에서 참조되지 않으면 실행 편집기 기능을 사용할 때 Xbox 서비스가 작동하지 않습니다.

  10. MicrosoftGame.config 파일을 만들고 빌드하는 동안 .exe와 동일한 대상에 복사되었는지 확인합니다.

    참고: 엔진에서 실행할 때 다른 .exe를 사용하는 모든 종류의 실행 편집기 기능을 지원하는 경우 MicrosoftGame.config를 해당 .exe와 동일한 디렉터리에 복사해야 합니다. Microsoft Game.config가 .exe와 동일한 디렉터리에 없으면 실행 편집기 기능을 사용할 때 Xbox 서비스가 작동하지 않습니다.

    개발을 시작하기 위해 다음 예제와 같이 기본값이 있는 구성을 사용할 수 있습니다. ID->이름, 실행 파일->이름 및 실행 파일->별칭에 대한 값은 모두 실행 파일의 이름으로 바뀝니다.

    <?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>

<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>

<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

MicrosoftGame.config 업데이트

이전 단계에서 만든 MicrosoftGame.config 파일에는 Gaming Runtime, Microsoft Store 및 타이틀 ID의 기능을 사용하기 시작할 때까지 추가 구성 없이 PC 및 Xbox에서 초기 개발을 허용하는 기본값이 있습니다. Xbox 서비스 기능을 사용하려면 파트너 센터 프로젝트 ID 세부정보로 프로젝트의 MicrosoftGame.config를 업데이트해야 합니다.
또한 VC14를 Microsoft.Xbox.Services.GDK.C.Thunks.dll에 필요한 알려진 종속성으로 나열해야 합니다.

  1. 파트너 센터 대시보드로 이동합니다.
  2. 제품 목록에서 게임을 선택합니다.
  3. 게임 설정 탭을 선택하고 ID 세부 정보를 선택합니다.
  4. 세부 정보 표시를 선택하요 ID 세부 정보 섹션을 확장합니다.
  5. Identity details 섹션의 표에서 다음 값을 사용한 다음 파트너 센터에서 해당 값을 MicrosoftGame.config의 해당 요소 및 필드에 복사합니다.
  6. DesktopRegistration->DependencyList에서 VC14에 대한 KnownDependency에 대한 요소를 추가합니다.
파트너 센터의 이름 MicrosoftGame.config
Xbox 타이틀 ID TitleId
Package/Identity/Name ID->이름
Package/Identity/Publisher ID->게시자
Xbox 서비스 -> Xbox 설정 -> MSAAppId MSAAppId

예를 들어 파트너 센터에서 다음 ID 세부 정보를 사용하면 MicrosoftGame.config가 아래 샘플과 같이 표시됩니다.

파트너 센터의 이름 예제 값
Xbox 타이틀 ID 64353034
Package/Identity/Name 41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
Xbox 서비스 -> Xbox 설정 -> MSAAppId 0000000000000000 
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>

  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>
  
  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>

  <DesktopRegistration>
    <DependencyList>
      <KnownDependency Name="VC14"/>
    </DependencyList>
  </DesktopRegistration>

</Game>

MicrosoftGame.config의 값에 대한 추가 정보는 MicrosoftGame.config 개요를 참조하세요.

게임 런타임 및 XSAPI 초기화

다음 단계는 게임에서 Gaming Runtime Services 및 XSAPI를 초기화하는 방법을 보여줍니다.

  1. 프로젝트의 .cs 파일에 using XGamingRuntime;을(를) 추가합니다.
  2. 프로젝트의 .cs 파일에 using XGamingRuntime.Interop;을(를) 추가합니다.
  3. 게임 런타임 초기화를 위한 호출 추가:
    Int32 hr = SDK.XGameRuntimeInitialize();
  4. Xbox 서비스를 초기화하기 위한 호출 추가:
    Int32 hresult = SDK.XBL.XblInitialize(SCID);
    SCID를 파트너 센터 프로젝트의 SCID가 포함된 문자열로 바꿉니다.

게임 런타임 초기화 취소

게임이 종료되기 전에 게임 런타임 서비스 초기화를 취소해야 합니다. XSAPI는 종료하기 전에 명시적으로 정리할 필요가 없습니다.

SDK.XGameRuntimeUnititialize를 호출하여 GDK 런타임을 초기화 취소합니다.

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 SDK.XGameRuntimeUnititialize();

게임에서 XSAPI를 사용하는 방법에 대한 자세한 개요는 Xbox 서비스 API 시작하기를 참조하세요.
GDK 기능 구현에 대한 개요는 개요 및 방법을 참조하세요.

게임에서 Xbox 서비스 테스트

게임에서 도전 과제와 같은 Xbox 서비스 기능을 테스트하려면 샌드박스를 사용하고 해당 샌드박스에 액세스할 수 있는 계정을 테스트해야 합니다.

테스트 계정 만들기

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

샌드박스 전환

테스트 계정을 만들었으면 다음 단계에 따라 계정을 사용하여 샌드박스에 액세스합니다.

  1. 샌드박스 ID를 찾으려면 파트너 센터로 이동합니다.
  2. Xbox 서비스를 선택하고 Gameplay Settings(게임플레이 설정)를 선택합니다.

    참고 항목

    샌드박스 ID는 첫 번째 탭에 있으며 “ABCDEF.0”과 같이 이름이 지정됩니다.

  3. 시작 메뉴를 엽니다.
  4. Microsoft GDK Command Prompts를 입력하고 키보드의 Enter 키를 누릅니다.
  5. 첫 번째 명령 프롬프트를 엽니다.
  6. 명령 프롬프트에 XblPCSandbox.exe [샌드박스 ID]를 입력합니다.
  7. 명령 프롬프트에서 여러 개 앱이 시작되면 테스트 계정을 사용하여 Xbox 앱에 로그인합니다.

성공적으로 로그인할 수 있으면 테스트 계정을 만들고 테스트를 시작하기 위해 샌드박스로 변경한 것입니다.

샌드박스에 대한 자세한 내용은 Xbox 서비스 샌드박스 개요를 참조하세요.

게시

게임을 게시할 준비를 하려면 다음을 수행해야 합니다.

이 두 가지 요구 사항을 완료하면 게시할 준비가 된 것입니다. 게임을 제출하려면 파트너 센터로 이동하고 UI의 지침에 따릅니다.