Unreal development for PC: get started

  • Article


Use this topic to prepare your Unreal game for publishing to the Microsoft Store.

Using Unreal 4.27 or later

The easiest way to integrate your Unreal game with the Microsoft Game Development Kit is to upgrade to the latest version of Unreal. GDK support for both Windows PC and Xbox consoles is built into Unreal for versions 4.27 or later.

Note

By default Direct3D 11 is not supported in UE versions prior to 4.27. Direct3D 11 support can be enabled in UE 4.26 by integrating two change lists as described in this tech note: DX11 support in WinGDK before 4.27. If these changes are not integrated, Direct3D 12 will be used in 4.25Plus/4.26 regardless of any settings specifying Direct3D 11.

If you don't want to upgrade to Unreal version 4.27 or later, follow the instructions in the Earlier versions of Unreal section later in this topic.

Note

Unreal 4.26 has GDK support built in as well, but is not recommended because it had several issues including lack of Direct3D 11 support and a PSO shader cache issue that lead to stuttering during the first playthrough of a game.

Up to date Gaming Runtime Services (GRTS) and PC Bootstrapper

Starting with the May 2202 GRTS release, a PC Bootstrapper has been added to the PC game launch experience. The PC Bootstrapper has a dependency on the Gaming RunTime Service (GRTS) and If GRTS is out of date on your development PC, it can generate an error (E_FAIL) when attempting to sign in. See the PC Bootstrapper overview for more information.

Enrolling in ID@Xbox

Before you can get access to the Unreal source with GDK support, you need to enroll in the ID@Xbox at program. The ID@Xbox program enables developers to publish games on Xbox and Windows with Xbox services. You can start the enrollment process by going to Independent Developers Program for Xbox One | Xbox and clicking APPLY NOW.

Getting access to Unreal source with GDK support

IMPORTANT: You need to get access to console development even if you are building for PC.

To begin Unreal GDK development, request access by using the Console Development Request form. If your access request doesn't go through, contact your developer account manager (DAM).

Standard Unreal does not contain support for the GDK. This is why you need to request access to Unreal's GDK support.

Implementing platform features

GDK platform integration is part of Unreal's Online Subsystem. To tell Unreal to use the GDK online subsystem, edit your WinGDKEngine.ini file (in Platforms\WinGDK\Config) to include the following:

[OnlineSubsystem]
DefaultPlatformService=GDK

Sign in

Sign in is part of the online subsystem for the GDK.

Achievements

To use achievements in you Unreal game you need to make the following changes to your game and your Partner Center project.

Setting Unreal to use the GDK online subsystem with title-managed achievements and event-based stats

Achievements are included as part of the online subsystem for the GDK. To tell Unreal to use title-managed achievements and event-based stats, edit your WinGDKEngine.ini file (in Platforms\WinGDK\Config) to include the following:

[OnlineSubsystemGDK]   
AchievementMode=2017   
StatsMode=2013

Configuring stats and achievement systems for your game in Partner Center

To configure achievements:

  1. Go to the Partner Center dashboard.
  2. Navigate to your game.
  3. Expand the Xbox services section in the navigation pane.
  4. Click on Xbox Settings.
  5. Make sure Stats configuration system is set to Event-Based Stats.
  6. Make sure Achievements configuration system is set to Title-Managed Achievements.

Note: If you are migrating from the XDK, the OnlineSubsystemLive has been replaced by the OnlineSubsystemGDK. You need to set this as the default OnlineSubsystem in the Windows GDK .ini file.

Mapping achievement names in Unreal

Achievement names used in Unreal need to be mapped to the achievement IDs used in Partner Center.

To map achievement names used in Unreal create a file named Achievements.json in the platforms\GDK\Config\OSS\ directory of your project (note that the path may not exist and you may need to create it yourself). Achievements.json contains a mapping for achievement names to their Partner center IDs. For example, if your project has 10 achievements named achievement 1 through achievement 10, Achievements.json would look like this:

{
    "AchievementEventName" : "NotUsedInAchievement2017",
    "AchievementMap" :
    {
      "achievement 1" : 1,
      "achievement 2" : 2,
      "achievement 3" : 3,
      "achievement 4" : 4,
      "achievement 5" : 5,
      "achievement 6" : 6,
      "achievement 7" : 7,
      "achievement 8" : 8,
      "achievement 9" : 9,
      "achievement 10" : 10
    }
}

Cloud saves

Cloud saves are part of the Game Save interface in Unreal and don't require additional configuration to enable.

See Saving and Loading Your Game in the Unreal Engine documentation for information on using the game save interface in Unreal.

Note: If you are having trouble figuring out why cross-saves are not working, it is important to remember that the save location for GDK is different than the generic save game location. If you are having trouble, check where the save games are saved to are and where you are querying them from in case the locations are different.

Store APIs

Store integration like in-app purchases and downloadable content (DLC) are also part of the online subsystem in Unreal.

Creating a product in Partner Center

Before you can test Xbox services functionality or publish a game to the Microsoft Store, you need to create your Xbox services-enabled product in Partner Center. For more information about Partner Center, see Setting up an app or game in Partner Center, for Managed Partners.

Configuring your game for the Microsoft Store

Before you can create a package for testing or upload to the Microsoft Store, you need to configure your project with values from the product definition you created in Partner Center.

Use the following steps to configure your project in the Unreal Editor:

  1. Open the Unreal Editor, select Edit, and then select Project Settings.
  2. On the left pane, select Platforms, and then select Windows (GDK) as shown in the following screenshot.

    Screenshot of the platform Project Settings in Unreal

  3. Complete the form that appears. The following fields are required for PC development.
  • Product Name (the display name for your game)
  • Culture Image Resources
    • Store Logo
    • Application Logo
    • Application Small Logo
    • Application Splash Screen

The rest of the required fields are in Partner Center. Use the following steps to go to Partner Center and complete your product configuration:

  1. Go to the Partner Center dashboard.
  2. Select your game from the list of products.
  3. Select the Game setup tab, and then select Identity details.
  4. Select Show Details to expand the Identity details section.
  5. Use the following values from the table, and then copy the values from Partner Center into the project settings for Windows (GDK).
Name in Partner Center Name in the Unreal Editor
Package/Properties/PublisherDisplayName Package/Properties/PublisherDisplayName
Xbox Title ID Title Id
Package/Identity/Name Package/Identity/Name
Package/Identity/Publisher Package/Identity/Publisher
Xbox services -> Xbox Settings -> Identity MSAAppId

Testing platform features

Platform features don't work in the editor. They only work in a packaged build. This means that you can write code for the platform features, but you can't test the build without creating a package.

To test platform features such as sign in, cloud saves, and achievements, create a test account and switch your sandbox. Learn how to create a package, test accounts, and switch your sandbox in the following sections.

Creating a package

Package your game the same way that you would when you're using other Unreal platforms. Use the following steps to create an MSIXVC package to upload to the Microsoft Store.

  1. Access the packaging dialog box by selecting File > Package Project > Windows on GDK.
  2. Choose a folder for the build output from the File Explorer dialog box, and then select Select Folder.

If you encounter errors, you can build manually. For more information about manual builds, see Title packaging, content updates, and streaming-installation testing.

Installing and running a package

For more information about installing and running packages, see Utilizing Microsoft Game Development Kit tools to install and launch your PC title.

Creating a test account

You'll need to create a test account with access to your development sandbox to be able to test Xbox services functionality. For more information about creating test accounts, see Creating test accounts.

Downloading the Xbox App

The Xbox app is helpful for verifying that your test account is signed in. You can download it here: Xbox App

Switching your development sandbox

After you've created a test account, use the account to access your development sandbox by using the following steps.

  1. To find your sandbox ID, go to Partner Center.

  2. Navigate to your game.

  3. Select Xbox services > Gameplay settings in the left navigation pane.

    Note

    Your sandbox ID is on the first tab in the upper-left corner of the Gameplay Setting page. It's named something like "ABCDEF.0".

  4. Open the Start menu.

  5. Enter Microsoft GDK Command Prompts, and then select Enter on your keyboard.

  6. Open the first command prompt.

  7. In the command prompt, enter XblPCSandbox.exe [your sandbox ID].

  8. After the command prompt launches several apps, sign in with your test account to the Xbox App.

If you're able to sign in successfully, you've created a test account and changed to your sandbox to begin testing. If you have trouble signing in, refer to the Troubleshooting sign-in and sandboxes for help.

Publishing

After you've finished integrating your game with the GDK, you're ready to publish. To submit your game, go to Partner Center and follow the instructions in the UI.

Troubleshooting your GDK configuration for Unreal

Verify your game matches the values in Partner Center

If your game is unable to sign in or your calls to Xbox services are failing, verify the values you set in the Configuring your game for the Microsoft Store section match the values for your project in Partner Center.

Verify the contents of WinGDKEngine.ini and Achievements.json

Verify WinGDKEngine.ini and Achievements.json are set up as described in the Setting Unreal to use the GDK online subsystem with title-managed achievements and event-based stats section.

Use fiddler to examine network traffic

If neither of the previous steps resolve the issue, consider installing Fiddler and examining the network traffic generated by your game. See Troubleshooting Xbox services traffic for PC games for more information.

Samples

Unreal and GDK samples can be used as references to compare your project to and to see expected network traffic for calls to xboxlive.com.

Unreal samples

The Unreal sample ShooterGame is set up to use the GDK and Xbox services and can be used as a reference to compare with your project configuration. You can use this sample with the values for the Partner Center project for your game using the process described in the Configuring your game for the Microsoft Store section. The ShooterGame sample can be found in the UE source repo under Samples\Games\ShooterGame.

GDK samples

The Achievements2017_desktop GDK sample can be used as a reference in combination with Fiddler to see network traffic for sign-in and querying and setting achievements. Achievements2017_desktop is already setup to work with its own Partner Center project and can be used with its existing configuration.

The GameSave_desktop GDK sample can be used as a reference in combination with Fiddler to see network traffic for Cloud Save. GameSave_desktop is already setup to work with its own Partner Center project and can be used with its existing configuration.

Additional troubleshooting tips

For additional troubleshooting tips see Troubleshooting sign-in and sandboxes.

Appendix

Earlier versions of Unreal

If you're using a version of Unreal that's earlier than 4.26, you can still target the GDK by following some of the previous instructions. However, you need to integrate platform features and create the package yourself. See Unreal development for PC: get started (earlier versions) for more information.

See also

Unreal development forums
Troubleshooting sign-in and sandboxes