2. Modify and build your project

Before you open your project in the Editor you need to:

  • Add the SpatialGDK module to your project
  • Set up and build your project
  • Modify Unreal classes for GDK compatibility
  • Configure your project to work with SpatialOS
  • Modify your project to support SpatialOS cloud deployments

Step 1: Add the SpatialGDK module to your project

To use the GDK and SpatialOS networking, you must add the SpatialGDK module to your project.

  1. In File Explorer (Windows) or Finder (macOS), navigate to /<ProjectRoot>/<GameRoot>/Source/<YourProject>/.
  2. Open the <YourProject>.Build.cs file in a code editor and add "SpatialGDK" to PublicDependencyModuleNames.

For example:

   PublicDependencyModuleNames.AddRange( 
            new string[] {
                "Core",
                "CoreUObject",
                "Engine",
                "OnlineSubsystem",
                "OnlineSubsystemUtils",   
                "AssetRegistry",
                "AIModule",
                "GameplayTasks",
                "SpatialGDK",
            }
        );

Step 2: Set up and build your project


To set up your Unreal project to work with the GDK Unreal Engine fork, which you cloned and installed in the Before you start section:

  1. In File Explorer, navigate to <ProjectRoot>/<GameRoot>.
  2. Right-click your <YourProject>.uproject file and select Switch Unreal Engine version.
  3. Select the path to the Unreal Engine fork you cloned earlier. This associates your project with the Unreal Engine fork and automatically generates a Visual Studio solution file for your project called <YourProject>.sln
  4. In the same directory, double-click <YourProject>.sln to open it with Visual Studio.
  5. On the Visual Studio toolbar, set your Solution configuration to Development Editor.

Image: The Visual Studio toolbar, with the Development Editor Solution configuration highlighted in red.

  1. In the Solution Explorer window, right-click on <YourProject> and select Build.
  2. After the build finishes, open the project in Unreal Editor:
    Press F5 on your keyboard or select Local Windows Debugger in the Visual Studio toolbar.

To set up your Unreal project to work with the GDK Unreal Engine fork, which you cloned and installed in the Before you start section:

  1. In Finder, navigate to UnrealEngine/Engine/Binaries/Mac/.
  2. Double click UE4Editor to open the Unreal Editor.
  3. In the Project Browser window select More, then Browse, and find your .uproject file <ProjectRoot>/<GameRoot>/<YourProject>.uproject.
  4. If you are asked to rebuild the project, do so. (This process also generates your <YourProject>.xcworkspace.)
  5. Unreal automatically opens the project in the Unreal Editor after the rebuild is finished.

Step 3: Modify Unreal classes for GDK compatibility

You must modify your GameInstance class to work with the GDK, by making it inherit from SpatialGameInstance. (See the examples below to find out how to do this.) You must also configure your project settings.

  1. Make a Game Instance

If you have not made a GameInstance for your game and are still using the default GameInstance, you can either:

  • Use the SpatialGameInstance directly by selecting it in Settings > Project Settings > Maps and Modes > Game Instance.
  • Create your own Blueprint, and ensure its parent class is set to SpatialGameInstance.
  • Create a native GameInstance class, which inherits from SpatialGameInstance. To do that:
    1. In the Content Browser, select Add New, then New C++ Class.
    2. Select Show All Classes.
    3. In the search field, type SpatialGameInstance.
    4. Select it and then select Next.
  1. Configure project settings
    Remember to configure your project settings to use the new GameInstance by default, under Settings > Project Settings > Maps and Modes > Game Instance > Game Instance Class.

How to set up inheritance from SpatialGameInstance

C++ class

If your game's GameInstance is a C++ class:

a. Locate its header file and add #include "SpatialGameInstance.h".

For example:

 #include "CoreMinimal.h" 
 #include "SpatialGameInstance.h" 
 #include "YourProjectGameInstance.generated.h"

b. Then, under UCLASS(), change the parent class from UGameInstance to USpatialGameInstance:

For example:

  UCLASS()
  class YOURPROJECT_API UYourProjectGameInstance : public USpatialGameInstance
  {
      GENERATED_BODY()
  };

c. If you override StartGameInstance but do not call Super::StartGameInstance, you need to add a call to TryConnectToSpatial to initialize the connection to SpatialOS. For example:

void UMyProjectGameInstance::StartGameInstance()
{
	TryConnectToSpatial(); // add this line

	// custom game initialization logic, which does not include Super::StartGameInstance
}

Blueprint class

If your GameInstance is a Blueprint class, you need to open and edit it in the Blueprint Editor:

a. From the Blueprint Editor toolbar, navigate to the Class Settings.
b. In Class Options set the Parent Class to SpatialGameInstance.

Image: The Blueprint class settings screen

Step 4: Configure your project to work with SpatialOS

  1. SpatialOS expects the server target to be named [GameName]Server, so you need to rename the target where it is specified within the [server].Target.cs file within the project's Source folder. You need to change the name of the file as well as the name of the class inside the file.

For example, if you have a project called MyGame and a server target called MyServer, you need to rename MyServer.Target.cs to MyGameServer.Target.cs.

Inside the file, your change will look as follows:

// Change from class MyServerTarget to MyGameServerTarget

public class MyGameServerTarget : TargetRules
{
	public MyGameServerTarget(TargetInfo Target) : base(Target)
    ...

If you do not have a ServerTarget already created for your project, you should create one as follows:

a. Copy the <YourProject>Editor.Target.cs file in the Source directory and rename it to <YourProject>Server.Target.cs.
b. Next, replace every mention of Editor in the file with Server.
c. For example, in C# change the following:

using UnrealBuildTool;
using System.Collections.Generic;
public class MyGameEditorTarget : TargetRules
{
	public MyGameEditorTarget(TargetInfo Target) : base(Target)
	{
		Type = TargetType.Editor;
		DefaultBuildSettings = BuildSettingsVersion.V2;
		ExtraModuleNames.Add("MyGame");
	}
}

To:

using UnrealBuildTool;
using System.Collections.Generic;
public class MyGameServerTarget : TargetRules
{
	public MyGameServerTarget(TargetInfo Target) : base(Target)
	{
		Type = TargetType.Server;
		DefaultBuildSettings = BuildSettingsVersion.V2;
		ExtraModuleNames.Add("MyGame");
	}
}
  1. If your game uses ReplicationGraph, you need to extend your replication graph classes from USpatialReplicationGraph instead of the default UReplicationGraph.

Step 5: Modify your project to support SpatialOS cloud deployments

Before you launch a cloud deployment, you need to make sure that the Spatial directory gets cooked when you build your workers. There are two ways to do this:

  1. Go to Settings > Project Settings > Packaging. In the Packaging section, expand the advanced section. You will see a field called Additional Asset Directories to Cook. Add the Spatial directory in there.
  2. Open the DefaultGame.ini (located in <ProjectRoot>/<GameRoot>/Config/DefaultGame.ini) configuration file in a text editor, and make sure the following two lines are present at the end:
[/Script/UnrealEd.ProjectPackagingSettings] 
 +DirectoriesToAlwaysCook=(Path"Spatial")

You need to ensure you have a Server Default Map set if you have not done so already for your project. To do this:

  1. Navigate to the Maps and Modes tab in your Project Settings.
  2. Under Default Maps expand the section and set the Server Default Map to the map you would like your servers to start on when running in the cloud.

Step 6: Enable the SpatialOS multiserver features

You must enable the SpatialOS multiserver features in your project. To do this:

  1. Go to Edit > Project Settings > Engine > General Settings > Default Classes.
  2. From the World Settings Class drop-down menu, select SpatialWorldSettings.

> Next: 3. Launch a local deployment


2020-06-25 Page updated with editorial review: added step 6: Enable the SpatialOS multiserver features.
2020-06-25 Page updated with editorial review: added macOS, mobile, UI and deployment workflow changes.
2019-07-16 Page updated with editorial review.

Updated about a year ago


2. Modify and build your project


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.