Plug-ins & Third-Party SDKs in UE4

Editor's Notes

• #2: *** Prepared and presented by Gerke Max Preussner for MIGS 2016, November 15th
• #4: UE4 provides two methods to implement new features: Blueprint (our visual programming interface) and C++. Most projects use a combination of both, and Blueprint and C++ can interact with each quite easily. It is also possible to implement a game entire in Blueprint, or entirely in C++. This presentation will focus on C++. All C++ code resides in modules. You can think of these as packages or libraries that bundle types and functions together. In earlier versions of Unreal Engine all the code was split into a few DLLs, which lead to a lot of very tightly coupled code that was difficult to maintain and extend. In UE4 we refactored most of this code into hundreds of small modules, each of which has a particular purpose that can be reused more easily. Depending on the platform and type of application, modules can be compiled into static libraries (monolithic builds) or DLLs (non-monolithic builds).
• #5: Because there are so many modules in UE4, we decided to logically organize them depending on how and where they are meant to be used. For example, modules that are to be used exclusively in Unreal Editor and not in any game or project are referred to as ‘Editor’ modules. We also have a number of modules that implement standalone programs and tools. Runtime modules are the most numerous as they form the foundation for all games, programs, and Unreal Editor. Other modules are used exclusively to integrate code and libraries from other third-party vendors. At these we will look in more detail later.
• #6: Modules can be found in various locations of the Engine code base, but they all have more or less the same structure. For most modules there’s a Private and Public folder, as well as a Build.cs file.
• #7: The Private folder contains all the module’s implementation details that should not be accessible by other modules.
• #8: Each module is required to implement special initialization code that is executed each time the module is loaded or unloaded.
• #9: This is easily accomplished by writing a class that implements the IModuleInterface interface.
• #10: The IMPLEMENT_MODULE macro generates the module registration and other boilerplate code. The module initialization file is also a good place to define other things that are used throughout your module, such as log categories.
• #11: All modules in UE4 are also expected to use a pre-compiled header file. This header must be the first include file in any of your module’s .cpp files. UBT will warn during compilation if you fail to do this.
• #12: There are no official guidelines on what should go into the pre-compiled header. Personally I found it most useful to include all external header files from other modules or third-party SDKs that the module uses. We generally use unique file names for all headers in the Engine, but there are a few exceptions. For this reason, I always specify the full include path relative to the Engine’s “Source” directory.
• #13: It is not strictly required to include Core.h as it should always be included by UBT. For consistency, I include it anyway.
• #14: It is also possible to use relative include paths. This is useful when including shared headers from neighboring modules inside of plug-ins.
• #15: The module’s Public folder contains everything that should be accessible by other modules. This typically includes C++ interface declarations…
• #16: … as well as exported types and functions.
• #17: Pure interface declarations can be used by other modules by simply including your module’s public header files. If your module implements functions or class methods, these need to be exported, and other modules have to not include the headers, but also link against your module. Exporting types is easy: we have a macro that is automatically generated for each module ({MODULENAME}_API).
• #18: The most important part of a module is the module build rules file (*.Build.cs) It tells UBT how the module is to be compiled, which modules it depends on for compiling and linking, and many other build options.
• #19: Module build rules are written in C#. UBT automatically locates all build rules, and compiles and executes them in order to generate the command lines for the compiler and linker.
• #20: The build rules are mostly configured via built-in properties. There are many options available for rules compiler, and I quickly want to go over some of the most important ones, because almost everyone gets them wrong (and by that I mean most programmers at Epic, too!).
• #21: For efficiency reasons, UBT does not automatically discover sub-folders in your module’s Private directory. If you have any private sub-folders, you need to add them to PrivateIncludePaths. PublicIncludePaths is currently not needed, because UBT discovers public sub-folders automatically. If your module’s private implementation includes public headers from another module, but does not link against that module (this usually happens when including only interface headers), then you must list that module in PrivateIncludePathModuleNames. If your module’s public interface uses types from another module’s public interface, but does not need to link against it, then you must list that module in PublicIncludePathModuleNames.
• #22: If your module includes public headers from another module and also has to link against that module, then you can list that module in PrivateDependencyModuleNames and PublicDependencyModuleNames respectively. Finally, if your module does not depend on another module at compile or link time, but loads it at run-time, then we must tell UBT to compile that module anyway by adding it to the DynamicallyLoadedModuleNames array. This setting is often used in combination with PrivateIncludePathModuleNames. It is important that you completely understand these options. I often see that module dependencies are over-specified in order to “make things work” without really knowing what that means. I also often see that dependencies are underspecified, and the code compiles, links and runs successfully only by accident, and it may break later if someone changes dependencies in some other, completely unrelated module. You are responsible for ensuring that your module specifies its dependencies correctly.
• #23: One easy way to create a new plug-in in three simple steps is to use the Plug-in Wizard in Unreal Editor. You can reach it via the Plugin Manager from the main menu. However, I generally prefer to just copy the relevant files from an existing plug-in and do a find and replace of the plug-in name in files and file names.
• #24: Plug-ins are really just a collection of one or more modules bundled together with a descriptor file for easy redistribution. Plug-ins can reside in /Engine/Plugins (so called Engine plug-ins), or /MyProject/Plugins (so called project plug-ins). There is no functional difference, except that project plug-ins will only be accessible within a particular project, while Engine plug-ins can be used by all projects. If your plug-in is project specific, put it inside the project. Otherwise put it inside the Engine.
• #25: A plug-in’s C++ modules are located inside its Source sub-directory (just like Engine, project, or program modules). You can see in the picture that one of the three modules in the NdiMedia plug-in is actually the module we looked at a few minutes ago. There are no surprises here.
• #26: The only new addition is the plug-in descriptor, which resides in the plug-in’s root directory.
• #27: The plug-in descriptor is stored as a JSON file with the file extension .uplugin. It must have the same name as the plug-in itself.
• #28: And this is what a plug-in descriptor file looks like. It stores version information, user friendly descriptions, and – most importantly – module loading rules.
• #29: As you can see, most of the information is used to display details about the plug-in in the Editor’s plug-in manager UI.
• #30: However, the “Modules” section is used by the Engine to determine which modules of a plug-in are loaded and when. Let’s take a closer look..
• #31: Each of the plug-in’s modules may have an entry in this section. If it is listed here, the Engine will try to automatically load the module on startup.
• #32: The “Name” field must match the name of the module that should be loaded.
• #33: The “Type” specifies under what circumstances the module is loaded. For example, “Runtime” means that the module should be loaded pretty much anywhere, including in the Engine, the Editor, games, and standalone programs. “RuntimeNoCommandlet” means that the module should be loaded anywhere, except in commandlets. “Editor” means, as you can guess, that the module should be loaded only in the Editor, but not in games or other programs.
• #34: There are also different loading phases that determine when exactly in the startup phase the module should be loaded. This can be used to ensure that certain Engine dependencies are loaded before your plug-in loads, or to control the loading order between a plug-in’s modules.
• #35: Last but not least, you can also blacklist and whitelist specific platforms for each module.
• #36: Projects are the self-contained units that hold all the content (and optional code) that make up your games. Code projects usually include one or more C++ modules. They may also contain plug-ins. The “Source” directory of projects contains target build rules that are unique to projects. A target is an executable to be built by UBT, and the target rules describe which modules are to be included. Similar to plug-ins, projects also have a descriptor file.
• #37: Project descriptors are similar to plug-in descriptors in that they are also JSON files describing the project, as well as loading rules for its modules.
• #38: Whenever you add modules or plug-ins to your UE4 solution, you should run the GenerateProjectFiles.bat batch file, regenerate projects from within the Editor, or hit the re-generate project files button in the UnrealVS Visual Studio plug-in. UBT will then search the entire solution directory for Build.cs files and generate a new Visual Studio solution file. On macOS we generate Xcode project files.
• #39: When compiling your project, UBT will locate all Build.cs files, compile them, create a dependency graph, generate compiler and linker settings, and then compile all C++ modules. Modules are only compiled if they’re referenced somewhere, i.e. if it is listed in a project or plug-in descriptor, or if another module depends on it.
• #40: Before we look at how to include third-party SDKs in plug-ins, I’d like to show you how we treat third-party dependencies in the Engine in general. UE4 already includes a large number of dependencies. If your project requires any of these, we recommend that you use the ones shipping with UE4, because then you can rest assured that they will work on all supported platforms.
• #41: All third-party libraries are located in the /Engine/Source/ThirdParty directory. Just like regular modules, they have their own Build.cs files. These specify public header files to be compiled into dependent modules, as well as public libraries to be linked into dependent modules. Some third-party modules may also declare pre-processor definitions, for example for platform specific switches that can be used in your C++ code.
• #42: We include source code for most third-party modules, but we don’t compile it when building UE4. Instead we provide pre-compiled libraries for all supported platforms, so you don’t have to deal with that. Internally, we use automated and manual ways to compile third-party dependencies. For some dependencies that are particularly complicated, we even have specialized UAT scripts.
• #43: If you’re curious how this works, you can find all UAT scripts in the /Programs/Automation directory of the UE4 solution. The BuildThirdPartyLibs scripts, for example, will locate all UE4_BuildThirdPartyLib.bat batch files and execute them.
• #44: In the Automation folder you can also find the special build script for PhysX that I mentioned.
• #45: When we talked about modules, I showed you various build rules for specifying dependencies to other modules. Some of these are also used to specify additional include directories for third-party SDKs In addition to that, we also have a set of build rules to specify additional SDK library dependencies for linking.
• #46: The PublicLibraryPaths property allows you to specify additional directories to be searched for libraries by the linker. The actual libraries (usually .lib or .a files) to be linked are specified using the PublicAdditionalLibraries property. There are also some platform specific build rule properties, for example for adding Xcode frameworks on macOS and iOS.
• #47: If you use remote compilation, for example when compiling for macOS from Visual Studio on a Windows computer, the remote machine performing the compilation may need additional tools or files that have to be copied from your PC. These can be specified using the PublicAdditionalShadowFiles property. Lastly, after successfully compiling and linking your libraries, you also need to tell UBT which DLLs or other files have to be included in the packaged build. If you don’t do this, then those required files will be missing, and while your game works fine on your own PC, it may not work on anybody else’s device.
• #48: Third-party dependencies for plug-ins are usually placed into a “ThirdParty” folder inside the plug-in’s root directory, but this is not required. Everything I have shown you about Engine third-party dependencies also applies to Plug-in third-party dependencies.
• #49: On some platforms you may have to consider additional things when including third-party dependencies. On Linux, for example, we highly recommend that you link against our bundled libc++ standard library, because that will insure that your plug-in works everywhere UE4 works. All modules that are part of a UE4 solution are already linked against our libc++, so this only applies if you’re compiling other libraries yourself outside of the UE4 solution. Starting with 4.14, we support CentOS 7. We do not target any specific Ubuntu version, but since we bundle the C++ standard library, everything should work on most Linux distributions.
• #50: One thing to keep in mind on Linux is that we currently do not have a convenient to add look-up paths for runtime libraries. The best option is to manually load your libraries via GetDllHandle (= UE4’s dlopen() equivalent) before starting to call functions from your imported library. This is possible, because we use weak symbol resolution on Linux by default, which means that your imported symbols won’t be looked up until you use them for the first time. Another, somewhat hacky solution is to modify the RPATH settings in LinuxToolchain.cs On macOS we are already able to automatically generate RPATH from the RuntimeDependencies property that I have shown you earlier. We are hoping to make this work soon for Linux as well.
• #51: On the Android target platform things can get more complicated, because there are many possible architectures to support. UBT expects that you have library sub-folders for each supported architecture, such as ARM64 or x64. It does not matter where exactly these directories are located, but they have to have the same name as the architecture. In your module’s *.Build.cs file you actually specify the library dependencies for ALL architectures at once. Depending on which architecture you’re compiling for, UBT will later automatically filter out the unnecessary dependencies based on the sub-folder’s name. For example, if you’re compiling only for ARM64, then the dependencies containing “x64” or “ARMv7” will be ignored by UBT.
• #52: Android is presenting additional challenges during compilation and packaging, because it involves extra steps and tools. Because UBT is not aware of these Android specific requirements, and because the build rules can get quite complicated, we actually developed an XML based scripting language to deal with this. UPL was originally called Android Plug-in Language (APL), but it can now also be used for other platforms. Besides Android, it is currently also used for iOS (to modify .plist files). In the UE4 code you may still find references to both APL and UPL – they are the same thing. On Android in particular, UPL is generally used to inject Java code, and to add or remove files to/from Android packages.
• #53: Here is an excerpt of the UPL script for the GearVR plug-in. As you can see, it is all XML code.
• #54: Each UPL script runs in its own context, i.e. <init> in GoogleVR and <init> in GearVR won’t collide.
• #55: You can declare and assign variables. These variables will be visible throughout the rest of the section and any subsequent section.
• #56: There are some XML tags that provide shortcuts to common logic, such as conditional code for specific target architectures.
• #57: You can also declare regular conditional code.
• #58: It’s also possible to read configuration values from INI files.
• #59: <init> is not the only section. There are many others. The platform specific implementation of UPL determines which sections are available. Sections are evaluated sequentially.
• #60: Now, let’s quickly take a look at how you get your plug-in onto the UE4 Marketplace. All the steps required for submission are described on our web site. We have a web form where you can submit all your files, but it’s not that great yet. Until we improved it, a lot of the communication with you will also take place via email.
• #61: After you submitted your project or plug-in, we will audit it. We will make sure that all the information you provided is correct. We will also do some basic code review and functional testing. However, we don’t enforce UE4 coding guidelines.
• #62: When your submission requires third-party libraries, you may only include those that have a permissive license. Non-permissive dependencies have to be kept as a separate download for the user.
• #63: When users download your plug-ins from the UE4 Marketplace, they will be installed as Engine plug-ins. We include pre-compiled binaries for all supported platforms, as well as the source code. However, only the source code to compile and link the plug-in into UE4 is required. You can keep your secret intellectual property inside of static libraries for which you do not have to provide source code. Lastly, we do not automatically check whether your plug-in still works in future versions of UE4. You have to resubmit your work for every version you wish to support.
• #64: Now that you know the basics about integrating third-party dependencies into your projects and plug-ins, let’s take a look at a few examples. For the purpose of this presentation I created a plug-in (called LogLed) that integrates the Logitech LED SDK for driving illuminated keyboards and mice. Zak will show you later how to build a small game around it using UE4 Blueprints. The plug-in can be found on GitHub (https://github.com/ue4plugins/LogiLed). By the way, the https://github.com/ue4plugins/ GitHub depot contains some other interesting plug-ins as well. We use it as a place for experimental plug-ins that we do not want to include with UE4.
• #65: The Logitech SDK is very straightforward, so that the LogiLed plug-in is extremely simple as well. The first half of the module build rules define our Engine module dependencies and private include directories. If we’re building the Editor, then we also include the UnrealEd module, so that we can enable some Editor specific features (i.e. PIE support) in the plug-in.
• #66: The second half the build rules define the third-party library dependencies. Since we only support Windows and simply link against a .lib file to import the DLL functions, there aren’t any big surprise here. First we try to figure out the path to the ThirdParty directory, then we add the path to the include files, and finally the path and names of the libraries to link against.
• #67: VlcMedia is another experimental plug-in on GitHub that implements a Media Framework player using the VideoLAN codec.
• #68: Here, things are a little more complicated. Instead of linking against a static .lib to import the DLL functions, I decided to look up all function imports at runtime. As a result, the build rules only define which DLL files are to be included in the packaged build via the RuntimeDepdencies property. All the rest happens in the C++ code.
• #69: Here’s an excerpt of the C++ code that imports the DLL function pointers. Note that we’re first determining the path to the DLLs and then manually loading them.
• #70: Further down in the code, we can then import the functions exported by the VLC libraries. The VLC_IMPORT is a local macro that makes this a little bit more convenient (implementation not shown here).
• #71: The GearVR plug-in makes extensive use of Unreal Plug-in Language (UPL). Here you can see the UPL file (still called “APL” for historic reasons) being added to the receipt, which will cause it to be executed during the build. On Android, receipt files contain everything about a target being built.
• #72: There are some interesting things happening in the UPL file – injection of Java code, for example.
• #73: How does the Java code get injected into the correct location of the GameActivity.java file? UPL actually parses the java file for special insertion tags that start with //$$ It replaces the text with the one from the XML file and saves it to an output file, which gets built.
• #74: If you’re curious, you can find the replace logic in UEDeployAndroid.cs, which also implements the other Android specific UPL sections.
• #75: Here is another section of the same UPL file that copies additional resource files into the Android package. At the bottom we are removing signature files when making a Shipping build.
• #76: With that I would like to conclude this talk. Make sure to check out our extensive materials on the internet, all of which are available for free. Are there any questions I can answer right now?