UE Toolbox Installation
There are various ways the UE Toolbox can be installed in your project or Unreal Engine distribution.
In all cases, step 1 is to download the zipped version of the plugin that matches your Engine install version (ie 5.3, 5.4, 5.5, etc). Download links can be found on the main UE Toolbox page. Once you have the plugin downloaded, proceed to one of the steps below.
Binary Plugin, Launcher Engine Build
Installed in Project
In this method, the plugin is installed into your UE Project directory, ie where you would find the .uproject file, project Content directory, and so on. In this case, the plugin will only be available for that project.
Once you have the plugin zip file downloaded, copy it to your UE project, in the /Plugins subfolder. This folder should be in the top level of your project folder, at the same level as the .uproject file, as shown in the first image on the right (click on the thumbnails in the lower row to see the different steps)
Next, you need to extract the contents of this zip file to the path <Project>\Plugins\GradientspaceUEToolbox. The simplest way to do this in Windows is to right-click on the .zip file and select Extract All… from the Explorer context menu. This will pop up a dialog with the destination path. Remove the version numbers at the end of the path, so that the target folder is named GradientspaceUEToolbox (as shown in the third image), and click the Extract button.
You should now have a <Project>\Plugins\GradientspaceUEToolbox folder, containing subfolders with names like Binaries, Content, and Source, as shown in the fourth image. Now you can launch your project and the plugin will be automatically enabled.
Installed in Engine folder
One limitation of installing into your project is that the DebugGame configuration will not be available. If you are using a Blueprints-only project, this is not an issue, but if you are doing C++ project, you might like to be able to debug your game code. Due to limitations of UE’s binary builds, this won’t be possible with a precompiled binary plugin that is located in your project. However it is possible if you put the precompiled binary plugin in your Engine distribution, similar to how UE Marketplace plugins are installed.
Another advantage of this method is that you won’t have to copy the Plugin into each project folder, if you work with multiple projects. However the trade-off is if you work on multiple computers, or on a project with others, they may also need to install the plugin in their Engine folders.
The method to do this installation is very simple - it’s just like installing to your project, except you place the unzipped files in the directory <UnrealEngineInstallLocation>\Engine\Plugins\Marketplace\GradientspaceUEToolbox. So for example, my install location for 5.3 is D:\UnrealEngine\UE_5.3, so my destination path is as shown below
Binary Plugin, Source Engine Build (Advanced)
Although it’s customary to build Plugins from source code when doing a Source engine build, it is possible to use precompiled binary plugins. In particular, if you are doing source builds of an unmodified Github engine release branch, ie a “5.x” branch, just to be able to debug your game code more easily, then you are using the exact same code the launcher binary build that the precompiled plugin was built against, and there should be no issues.
If you are compiling UE5 Main, or working on a game that has a version of the Engine with significant source changes, or have made changes to the C++ compiling/linking build configuration, it’s a bit more questionable. Those changes could result in binary incompatibilities or crashes. The plugin does not rely on many UE features, and in particular the Editor tooling will generally be fine to use (the risk is more in serialized ModelGrid Actors and Assets). Test in a simple project, and if you encounter crashes, we’d be interested to hear about it.
To use this setup, all you need to do is create your Engine build with the same BuildId as the plugin. The BuildId is very slightly documented on Epic’s website. Basically, the BuildId is used to determine if different DLL’s were built with the “same” engine source. When you do a source build, the BuildId is randomly generated and so it will not match the BuildId of DLL’s generated with the binary engine release. To work around this, we need to force the BuildId of the Engine source build to match that of the precompiled Plugin.
The process to follow is:
Unzip the plugin binary installation zip file, and open the text file \GradientspaceUEToolbox\Binaries\Win64\UnrealEditor.modules. The first line of the file will have the BuildId number, formatted like this (the number here will vary): "BuildId": "27405482"
Open the file <EngineSourceDir>\Engine\Build\Build.version. Add the same BuildId to the bottom of the json block, as shown to the right
Regenerate Project Files and fully rebuild the Engine. Open the file <EngineSourceDir>\Engine\Binaries\Win64\UnrealEditor.modules and verify that the BuildId at the top of the file is the same as the BuildId you found in the in the binary plugin UnrealEditor.modules file. If you see a UUID instead, something has gone wrong.
Copy the GradientspaceUEToolbox plugin into your project’s Plugins folder, or into your Engine (ie the same as the locations listed above for a binary launcher build). Regenerate Project Files and then open and run your project. If you see a popup dialog about modules build with a different version, something has gone wrong.
Note that it is possible to go the other way, and modify the UnrealEditor.modules file in the plugin to have a BuildId that matches that of the Engine. However, in an engine source build without a fixed BuildId in the Build.version file, the BuildId is randomly generated each compile, and so the plugin would have to be repeatedly updated. However if you are using a custom BuildId already, the plugin can be updated to match it.
Upgrading UE Toolbox to a new Version
If you are notified about an update to the UE Toolbox in-Editor, or some other way, and you want to upgrade, the process is simply to reinstall it. Shut down the UE Editor, then delete the Plugins/GradientspaceUEToolbox folder and reinstall the newest version, using the instructions above.
Alternately, there is an auto-update script included as part of the plugin distribution. The auto-updater is a windows batch (.bat) file located at the path GradientspaceUEToolbox\update_toolbox.bat. This script will check your local Plugin and Engine version against the current-version file on the Gradientspace file server, and if a new version is available, prompt you to update if desired. This script is experimental and may not work on your machine - if errors occur, please delete the entire GradientspaceUEToolbox folder and re-download the plugin. Note that you may receive security warning messages, and depending on your security access level, may be prevented from running the script entirely.
Note that as of v0.1.3, this update script does not work if there is a space anywhere in the full path to the plugin. Apologies!
Upgrading UE Toolbox to a new Unreal Engine Version
If you upgrade your project to a new UE Version, and then try to load the project, you will see a popup dialog similar to that on the right, notifying you that the UEToolbox plugin that is installed is for a different version.
You will need to upgrade the plugin as per the instructions above. Note that the auto-update script will check for and handle Engine Version differences/updates, in addition to Plugin version updates.
Note that if you are installing UE Toolbox in your Engine/Plugins/Marketplace/ folder, then you would need to download the appropriate 5.x version of the plugin for the new Engine version and install it in the respective Engine subfolder, and then this message will not appear.
DebugGame Configurations
Unfortunately Epic does not support usage of precompiled binary Plugins using the DebugGame or DebugGame Editor project configurations in Visual Studio.
We have made various attempts to include DebugGame configurations in our packaged Plugin build (ie by adding the necessary commands to UBT). However the launcher/binary versions of Unreal Engine are simply unable to load this configuration. DebugGame configurations can only be used with Plugin source builds.
Packaging
ModelGrid Components from the UE Toolbox plugin can be included in a packaged game build. It is not recommended, as currently they are meshed dynamically (ie on game startup) using DynamicMeshComponents, which are relatively expensive. We certainly do not recommend trying to ship a game like this - you should replace the ModelGrids with baked versions, for now.
However, and this is very important - Code Plugins cannot be included when packaging Blueprint-Only Projects. This has always been a limitation of Unreal Engine - see this thread with replies from an Epic Unreal Engine developer going back to 2014.
So, to make a packaged game that depends on the UE Toolbox Plugin, you must use a C++ Project. Note that Blueprint-only projects can be easily converted to a C++ project by simply adding a C++ class via Unreal Editor, this google search will return many websites and videos on the topic.