Azure Storage SDK for Unreal Engine

  • Article

Note

This is a Sandbox project. The content in this article is unsupported, and therefore may be out of date or not in a working state. That said, we still think it was awesome enough to include here. Enjoy!

Important

This is an experimental Azure Storage SDK for Unreal Engine. As such, please note that this SDK is not supported and is not provided by the Azure Storage team. If you run into problems, please let us know using the GitHub Issues page for this SDK.

Get the source Try it now

Requirements

Compatibility

This plugin contains builds of the Azure Storage SDK for Win32 and Win64. Other platforms will not work.

Information

The plugin contains the Azure Storage SDK for C++ compiled as static libs along with required dependencies. These libs will be linked against the game when building the project. There is no specific Unreal API, so you can use the Storage SDK as you would from any other application. For more information, please see the following docs:

Add the Plugin

To add the Azure Storage SDK to your Unreal project, do the following:

  1. Download the Plugin package and unzip.

  2. Copy the extracted AzureStorage directory to the Plugins directory in your project.

  3. Right-click on your game's .uproject file in Explorer and select Generate Visual Studio project files... from the menu.

  4. Open your game's .sln solution file in Visual Studio.

  5. Add the AzureStorage module to your game's PrivateDependencyModuleNames list by editing the .Build.cs file for your game:

    PrivateDependencyModuleNames.AddRange(new string[] { "AzureStorage" });

Note

If you are using a non-default Visual C++ compiler, please modify the AzureStorage.Build.cs build script to update the path to the compiler.

  1. If you are using Unreal 4.18 only, add the following line to your game's Target.cs file:

    bForceEnableExceptions = true;

  2. Rebuild the solution in Visual Studio.

  3. When headers are #include'ed from the SDK, please wrap in the following #pragma statements to allow the compiler to ignore warnings around exception handling:

    #pragma warning(push)
#pragma warning(disable:4577 4530)
// #include Storage SDK Headers here...
#pragma warning(pop)

Note

Unreal Engine disables exception handling by default, however the Storage SDK uses exceptions to report errors. This may cause unexpected behavior in your game if the Storage SDK throws an exception. You can download the Unreal Engine source code and build the engine yourself with exceptions enabled if this is an important scenario for your game.

With the above in place, you should now be able to build the project. To use the API, follow the generic C++ instructions listed above to connect to and use the Azure Storage service.

Try the Sample

We created a sample using the Unreal puzzle game template which updates Table Storage for every box clicked. To try out the sample, do the following:

  1. Clone the GitHub repo.
  2. Download the latest Storage plugin release.
  3. Copy the plugin to the StorageDemo project as described above.
  4. Open the Source\StorageDemo\StorageDemoGameGrid.cpp file and add your Azure Storage connection string to the AddScore method where noted.
  5. Run the game via the Editor or build and package.

How It's Made

If you want to compile this for yourself and create your own plugin, here's how we created this. Note that the storage.bat build script in the _build directory performs these steps:

  1. Clone the Vcpkg project.
  2. When complete, run the bootstrap-vcpkg.bat script located in the root directory.
  3. Edit the triplets\x64-windows.cmake and triplets\x86-windows.cmake files to change the last line from set(VCPKG_LIBRARY_LINKAGE dynamic) to set(VCPKG_LIBRARY_LINKAGE static).
  4. Run vcpkg to build the libraries: vcpkg install azure-storage-cpp:x64-windows and vcpkg install azure-storage-cpp:x86-windows.
  5. Copy the following files to the plugin's Binaries\ThirdParty\Win64 directory:
    • packages\azure-storage-cpp_x64-windows\lib\wastorage.lib
    • packages\cpprestsdk_x64-windows\lib\cpprest_2_10.lib
    • packages\zlib_x64-windows\lib\zlib.lib
    • packages\openssl-windows_x64-windows\lib\libeay32.lib
    • packages\openssl-windows_x64-windows\lib\ssleay32.lib
    • packages\boost-system_x64-windowss\lib\boost_system-vc140-mt.lib
  6. Copy the following files to the plugin's Binaries\ThirdParty\Win32 directory:
    • packages\azure-storage-cpp_x86-windows\lib\wastorage.lib
    • packages\cpprestsdk_x86-windows\lib\cpprest_2_10.lib
    • packages\zlib_x86-windows\lib\zlib.lib
    • packages\openssl-windows_x86-windows\lib\libeay32.lib
    • packages\openssl-windows_x86-windows\lib\ssleay32.lib
    • packages\boost-system_x86-windowss\lib\boost_system-vc140-mt.lib
  7. Copy the following include directories to the plugin's Source\Public directory:
    • packages\azure-storage-cpp_x64-windows\include\was
    • packages\azure-storage-cpp_x64-windows\include\wascore
    • packages\cpprestsdk_x64-windows\include\cpprest
    • packages\cpprestsdk_x64-windows\include\pplx

The project's existing AzureStorage.uplugin and AzureStorage.Build.cs contain the necessary definitions to use the plugin with any project.

Cosmos DB Table API

Cosmos DB is Microsoft's globally distributed, multi-model database. One of the data models available for Cosmos DB is Table API. Applications written for Azure Table storage can migrate to Azure Cosmos DB by using the Table API with no code changes and take advantage of premium capabilities. If you have a Cosmos DB database, you can use the Table Storage client SDK we provide to access it from your Unreal Engine game. Check the instructions here on how to find out your connection string.

Next Steps