Copyright 2021 bitHeads, Inc. All Rights Reserved.
Thanks for downloading the brainCloud Unreal plugin! Here are a few notes to get you started. Further information about the brainCloud API, including example Tutorials can be found here:
http://getbraincloud.com/apidocs/
If you haven't signed up or you want to log into the brainCloud portal, you can do that here:
https://portal.braincloudservers.com/
And join our community here:
https://forums.getbraincloud.com/
| Package | Description |
|---|---|
| latest stable release | C++, Blueprint, and OnlineSubSystem library latest release for Unreal 4 and 5 (download zip) |
| braincloud-unreal-plugin-src | brainCloud Unreal on GitHub (source) |
| examples-unreal | Examples |
| Unreal - Older Versions | Instructions for building brainCloud for older versions of Unreal (for Blueprint only projects) |
- Open your Unreal Project's root folder (where the *.uproject file is)
- Open the Plugins folder, or create it if it does not exist
- Copy the BCClient folder into the Plugins folder
- If your project is NOT Blueprint only, be sure to regenerate your code project files
- Navigate to Edit -> Plugins
- Search for braincloud and enable plugin
- Restart Unreal Editor
- A dialog will pop up saying you're missing 3 modules, click yes to rebuild.
- Or, rebuild manually by deleting Intermediate folder, Binaries folder and .sln file then right click on your .uproject and generate visual studio files.
- Restart Unreal Editor one more time. This ensures you will then be able to access the brainCloud Utility Widget which allows you to manage your projects brainCloud app settings (such as the app ID, secret, etc.)
- Installation complete!
BCClient plugin can be installed as a submodule of your git project. Open a terminal at your project's root folder and enter the command:
$ git submodule add https://github.com/getbraincloud/braincloud-unreal-plugin-src.git Plugins/BCClient
Follow steps 4-10 above.
The plugin will easily work with any version of UE4 and UE5. If switching, ensure that Intermediate files are cleaned up from previous build.
The plugin will work with all platforms. Make sure the required SDK, environment paths and licenses set up. To build for a specific platform only, edit the BCClient.uplugin file. Eg:
"SupportedTargetPlatforms": [
"Win64",
"Android",
"Mac",
"IOS",
"Linux",
"LinuxArm64"
],
Examples of using brainCloud in your Unreal Projects can be found here.
To manipulate JSON in Blueprint another plugin is required. We recommend VaRest, which you can find in Epic Games Marketplace or here: https://github.com/ufna/VaRest
When methods are deprecated and removed Unreal will throw exceptions when opening Blueprints that contain these functions.
Ensure you have removed these functions from your blueprints before updating to the new version of the plugin. If you experience issues, roll back to the previous version and ensure you have not missed removal of these deprecated calls.
Let us know any issues or suggestions in our forums.
Note there is a defect that UTCTimeZoneOffset will be off for one hour in case of daylight savings due to limitations of UE Core API regarding DateTime.
There is a known Clang compiler issue when using Xcode 14 with UE 4. There will be errors of redifintions of HTTP_STATUS codes in thirdparty libraries used by Unreal and brainCloud. This issue is resolved in UE 5. In order to continue development in previous versions of Unreal, the file Engine/Source/ThirdParty/libWebSockets/libwebsockets/include/Mac/libwebsockets.h can be overwritten by the updated one downloaded from Epic Games' developer github.
Here are a few common errors that you may see on your first attempt to connect to brainCloud.
- App id not set: Verify you've set up the app id and app secret correctly in the
initialize()method. Check the server URL is correct including its case. - Platform not enabled: Verify you've enabled your platform on the portal.
If you're still having issues, log into the portal and give us a shout through the help system (bottom right icon with the question mark and chat bubble).
brainCloud is a ready-made back-end platform for the development of feature-rich games, apps and things. brainCloud provides the features you need – along with comprehensive tools to support your team during development, testing and user support.
brainCloud consists of:
- Cloud Service – an advanced, Software-as-a-Service (SaaS) back-end
- Client Libraries – local client libraries (SDKs)
- Design Portal – a portal that allows you to design and debug your apps
- brainCloud Architecture
The wrapper contains quality of life improvement around the brainCloud Client. It may contain device specific code, such as serializing the user's login id on an Android or iOS device. It is recommended to use the wrapper by default.
Using the brainCloud Utility Widget
If you restarted the Unreal Editor a second time once the brainCloud plugins modules have been built and initialized, you will have the brainCloud Utility Widget at your disposal to edit the projects brainCloud app settings.
For Unreal Engine 4, this is located at the end of your main toolbar:
And for Unreal Engine 5, it is located in the Tools submenu under the brainCloud section:
When you click this button a new Editor widget window will open that looks like this. (You can also drag and dock it as a tab in any layout frame)
When you click update to save these settings, it is important to restart your Unreal Editor after for these changes to take effect.
Manually
If you do not want to use the brainCloud Utility Widget, you can simply edit the BrainCloudSettings.ini that is located in your projects Config folder, if it doesn't exist then you can create it.
Then you can fill in the values for your app settings:
[Credentials]
AppId=
AppSecret=
Version=
ServerUrl=
S2SKey=
S2SUrl=
You can then use these values in your project with the GetBCAppData blueprint function. Remember to restart your editor if you make any changes to this file.
-
Create a BrainCloudWrapper - This will store an instance of brainCloud and give you a way of accessing the services we provide.
-
Store and set the wrapper - You will want a variable of type BrainCloudWrapper.
-
Set the Default brainCloud instance to your wrapper - this allows Singleton functionality, and you won't need to pass the wrapper into each function call, unless needed.
-
Get the brainCloud app credentials using GetBCAppData
-
Initialize brainCloud with your app credentials
Your Secret Key, and App Id, is set on the brainCloud dashboard. Under Design | Core App Info > Application IDs
Wrapper Name prefixes save operations that the wrapper will make. Use a Wrapper Name if you plan on having multiple instances of brainCloud running.
If your app is already live, you should NOT specify the Wrapper Name - otherwise the library will look in the wrong location for your user's stored anonymousID and profileID information. Only add a name if you intend to alter the save data.
Make sure to modify or add the ThreadTargetFrameTimeInSeconds to increase the send rate of packets in your projects DefaultEngine.ini config file.
It would go under the [WebSockets.LibWebSockets] category, a lower value is a faster send rate, something like 0.001 or 0.0001 would be adequate for real-time.
Keep in mind that this could impact performance on the socket and CPU, for best results with real-time networking please use UDP protocol.
This is what it would look like in your DefaultEngine.ini file:
[WebSockets.LibWebSockets]
ThreadTargetFrameTimeInSeconds=0.001
Version is the current version of our app. Having an Version less than your minimum app version on brainCloud will prevent the user from accessing the service until they update their app to the lastest version you have provided them.
In your project's update loop, you're going to want to update brainCloud client so it can check for responses.
To do this, you need to call Run Callbacks
Alternatively, if you are using a GameInstance class in your project and wish to manage brainCloud in there, you can run callbacks on a timer.
The simplest form of authenticating with brainCloud is Anonymous Authentication.
After having the user create an anonymous with brainCloud, they are probably going to want to attach an email or username, so their account can be accessed via another platform, or when their local data is discarded. Attaching email authenticate would look like this.
Attaching email authenticate would look like this.
There are many authentication types. You can also merge profiles and detach idenities. See the brainCloud documentation for more information: http://getbraincloud.com/apidocs/apiref/?cpp#capi-auth
Refer to our latest release notes for new brainCloud features and API changes.