Skip to content

Setup Beamable SDK

This guide will walk you through the process of setting up Beamable in your Unreal Engine project

Signing Up Account

To start using Beamable in your project you need to have a valid Account in our Platform. Please do so via our portal.

Please remember your Alias as it'll be used to log into the SDK in your editor or via the Beamable CLI.

Cloning and Installing Dependencies

Start by getting our repo, then installing .NET and Docker Dekstop.

  1. Clone UnrealSDK repo (make sure you have git-lfs installed).
  2. Check out the a tagged release version (in the form X.X.X).
    1. Most git clients will allow you to checkout a specific tagged commit via their UI.
    2. At Beamable, we're partial to Fork.
  3. Ensure Git LFS downloaded the binary assets in the repo.
    1. On Windows, you likely installed it along with git. On Mac, if git-lfs is not installed on your machine, you can run brew install git-lfs.
    2. Run git lfs install from the repository root
    3. Run git lfs checkout from the repository root.
  4. Run the prepare_repo.sh script.
    1. On Windows, use the GitBash that your git install contains.
    2. On Mac, you'll need to run chmod +x ./prepare_repo.sh.
  5. Optional - Generating Project Files (if you want to open the SDK's own project).
    1. On Windows, you can right-click the .uproject file and select Generate Visual Studio project files.
    2. On Mac, run sh "/Users/Shared/Epic Games/UE_5.5/Engine/Build/BatchFiles/Mac/GenerateProjectFiles.sh" "/Users/Path/To/Your/Project/YourProject.uproject" -game.
  6. Optional - Verify things are working by compiling the editor of our SDK project.

Next up, install our dependencies.

Once you have our repo and dependencies set up in your machine, follow along the next section to set up the SDK in your project.

Set up the Beamable SDK - Fast Path - Windows

Setting up the SDK in your project is done by manually copying over a set of files from our Unreal SDK repo to your project.

Unreal Project Requirements

Beamable requires your Unreal project to be a C++ project. That being said, we do provide an entire suite of Blueprint nodes that can be used to achieve most of the same functionality.

Please, follow along these instructions:

  1. Copy the beam_init_game_maker.sh script into the root of your Unreal Project.
  2. From a terminal (on windows, GitBash) running in your project directory, run beam_init_game_maker.sh passing in the path to the UnrealSDK in your machine.
    1. . beam_init_game_maker.sh "E:/Path/To/UnrealSDK"
  3. For each of your Target.cs files, add the following lines to their constructor:
    1. MyProject.Target.cs => Beam.ConfigureGame(this, Beam.OssConfig.Disabled()).
    2. MyProjectEditor.Target.cs => Beam.ConfigureEditor(this, Beam.OssConfig.Disabled()).
    3. MyProjectServer.Target.cs => Beam.ConfigureServer(this, Beam.OssConfig.Disabled()), if you have dedicated server builds.
  4. In each of the Modules you want to use Beamable's SDK, add this to their Build.cs files:
    1. RuntimeModule.Build.cs => Beam.AddRuntimeModuleDependencies(this);
    2. EditorModule.Build.cs => Beam.AddEditorModuleDependencies(this);
    3. UncookedOnlyModule.Build.cs => Beam.AddUncookedOnlyModuleDependencies(this);
    4. Pay attention to the type of module you're adding the SDK to and call the proper function. (You can see the module type in your uproject file)
  5. Regenerate project files.
    1. This should've been done by beam_init_game_maker.sh script. You can also right-click the .uproject file and select Generate Visual Studio project files.
  6. Verify that your project is set up correctly, go to your project's root directory:
    1. Check there is a .beamable folder there.
    2. Check there is a .config/dotnet-tools.json file.
    3. Run dotnet beam --version from inside your project root directory and see that it outputs a valid X.Y.Z string.
  7. Open your IDE and compile your editor.

Set up the Beamable SDK - Fast Path - MacOS

  1. Copy the beam_init_game_maker.sh script into the root of your Unreal Project.
  2. From a terminal, running in your project directory, run beam_init_game_maker.sh passing in the path to the UnrealSDK in your machine.
    1. Run chmod +x ./beam_init_game_maker.sh before running the script.
    2. . beam_init_game_maker.sh "/Users/Me/Path/To/UnrealSDK"
  3. For each of your Target.cs files, add the following lines to their constructor:
    1. MyProject.Target.cs => Beam.ConfigureGame(this, Beam.OssConfig.Disabled()).
    2. MyProjectEditor.Target.cs => Beam.ConfigureEditor(this, Beam.OssConfig.Disabled()).
    3. MyProjectServer.Target.cs => Beam.ConfigureServer(this, Beam.OssConfig.Disabled()), if you have dedicated server builds.
  4. In each of the Modules you want to use Beamable's SDK, add this to their Build.cs files:
    1. RuntimeModule.Build.cs => Beam.AddRuntimeModuleDependencies(this);
    2. EditorModule.Build.cs => Beam.AddEditorModuleDependencies(this);
    3. UncookedOnlyModule.Build.cs => Beam.AddUncookedOnlyModuleDependencies(this);
    4. Pay attention to the type of module you're adding the SDK to and call the proper function. (You can see the module type in your uproject file)
  5. Regenerate project files.
    1. From a terminal, run sh "/Users/Shared/Epic Games/UE_5.5/Engine/Build/BatchFiles/Mac/GenerateProjectFiles.sh" "/Users/Path/To/Your/Project/YourProject.uproject" -game.
  6. Verify that your project is set up correctly, go to your project's root directory:
    1. Check there is a .beamable folder there.
    2. Check there is a .config/dotnet-tools.json file.
    3. Run dotnet beam --version from inside your project root directory and see that it outputs a valid X.Y.Z string.
  7. Open your IDE and compile your editor.

Upgrading the SDK

  1. Check out a tagged release version (in the form X.X.X).
  2. Copy the beam_init_game_maker.sh script into the root of your Unreal Project.
  3. From a terminal (on windows, GitBash) running in your project directory, run beam_init_game_maker.sh passing in the path to the UnrealSDK in your machine.
    1. . beam_init_game_maker.sh "E:/Path/To/UnrealSDK"
    2. . beam_init_game_maker.sh "E:/Path/To/UnrealSDK" true (if you are still using the OnlineSubsystemBeamable plugin)
  4. If you had any custom changes made to the SDK, leverage Git to re-apply them as needed.
    1. When making custom changes to the SDK, don't for get to flag it with a comment so searching for them is easier in this step.
  5. Fix any compilation errors that happened due to breaking changes.
    1. Don't forget to look fix any blueprints as well after you get the editor to compile.
  6. Run dotnet tool restore from your project root.
    1. Verify that the CLI was updated to the proper version by running dotnet beam version and seeing that it matches the version in E:/Path/To/UnrealSDK/.config/dotnet-tools.json.
  7. If you have microservices:
    1. From your microservice project's directory, run dotnet restore.
    2. Verify that the CLI was updated to the proper version by running dotnet beam version from the microservice directory.
    3. Run dotnet beam checks scan --fix all.
      1. Our CLI can fix some breaking changes automatically with this command.