Froola

Froola is an automated build and test tool for Unreal Engine code plugin projects, supporting multi-platform deployment (Windows, Mac, Linux).

Overview

Froola streamlines the process of building and testing Unreal Engine code plugin projects across multiple platforms (Windows, Mac, Linux). It automates the build, test, and packaging workflow, and outputs a merged package containing all supported platforms.

Features

• Supports Unreal Engine 5.0 and later (tested on 5.3+)
• Easy command-line execution
• Designed for CI/CD and cross-platform development environments
• Developed with .NET 9.0 and C# 12

Supported Platforms

• Unreal Engine: 5.0 or later
• OS: Windows, Mac, Linux (Linux builds are executed via Docker on Windows)
• Package Types: Win64, Mac, Linux, Android, iOS

Setup

Development is primarily based on Windows. Running Froola on Windows is recommended; other platforms are optional.

• Android builds are performed with Unreal Engine on Windows.
• iOS builds are performed with Unreal Engine on Mac.
• Linux builds are performed on Windows using Docker (not Windows UE).

Common Setup

1. Create a UE Plugin project and ensure it can be built, tested, and packaged.
2. Push the project to a GitHub repository.
   • The repository should be structured so that the UE project directory is at the top level, not just the Plugins directory, to allow loading in Unreal Editor.
   • Example repository: ObjectDeliverer

Windows Setup

1. Install Unreal Engine 5.0 or later.
2. Install Visual Studio (C++ build environment required).

• For Android packaging:

3. When installing Unreal Engine, enable Android support.
4. Set up the Android development environment (see Official Documentation).

Mac Setup

1. Install Unreal Engine 5.0 or later.
2. Install Xcode (C++ build environment required).
3. Set up SSH access from Windows to Mac (using SSH/SCP).
   • SSH access can be set up using either password or public key authentication.
4. (Optional) Configure SSH to allow xcode-select execution without sudo password:
   • Normally, xcode-select requires sudo, but for security, you can allow passwordless sudo for only this command.
   • Edit the sudoers file using the following steps:
     1. Open terminal and run:

        sudo visudo

     2. Add the following line at the end of the file (replace youruser with your Mac SSH username):

        youruser ALL=(ALL) NOPASSWD: /usr/bin/xcode-select

     3. Now sudo xcode-select can be executed via SSH without a password.
     4. Froola's build process requires xcode-select without sudo, so this setup is needed.
     5. For security, do not allow passwordless sudo for other commands.
   • If you do not need to switch Xcode versions, xcode-select is not required.
   • For UE and Xcode version compatibility, see Official Documentation.
   • If switching Xcode versions, update Mac.XcodeNames in appsettings.json accordingly.

Linux (Docker) Setup

1. Install Docker (Podman is also supported).
2. Obtain the Unreal Engine Docker image (slim version recommended).
   1. Get access to the Unreal Engine GitHub repository Official Documentation.
   2. Obtain a GitHub access token (with read:package permission) for Docker login.
   3. Run the command to download the image.

Docker Image Acquisition Example (UE5.5 slim image)

// Login (enter your GitHub ID and access token)
docker login ghcr.io
// Download the image
docker pull ghcr.io/epicgames/unreal-engine:dev-slim-5.5.0

Docker Custom Plugins Setup (Optional)

If you have custom Unreal Engine plugins that need to be available in the Docker container during builds, you can configure Froola to mount them:

1. Place your custom plugins in directories on your Windows host machine (e.g., C:\MyUnrealPlugins\UE5.5).

2. Configure the Linux section in appsettings.json:

   Option A: Version-specific plugin paths (recommended for multiple UE versions)

   "Linux": {
     "DockerCommand": "docker",
     "DockerImage": "ghcr.io/epicgames/unreal-engine:dev-slim-%v",
     "CopyPluginsToDocker": true,
     "DockerPluginsSourcePaths": {
       "5.5": "C:\\MyUnrealPlugins\\UE5.5",
       "5.4": "C:\\MyUnrealPlugins\\UE5.4",
       "5.3": "C:\\MyUnrealPlugins\\UE5.3"
     }
   }

   Option B: Single plugin path for all versions

   "Linux": {
     "DockerCommand": "docker",
     "DockerImage": "ghcr.io/epicgames/unreal-engine:dev-slim-%v",
     "CopyPluginsToDocker": true,
     "DockerPluginsSourcePath": "C:\\MyUnrealPlugins"
   }

3. When Froola runs Linux builds, it will mount the appropriate plugins directory to /home/ue4/UnrealEngine/Engine/Plugins in the Docker container.

This feature is useful when your plugin depends on other custom plugins that are not included in the standard Unreal Engine Docker image. The version-specific configuration is especially helpful when plugins need to be compiled differently for different engine versions.

Froola Installation and Setup

1. Download the latest Froola release from GitHub and extract it.
2. Update the appsettings.json file to configure basic settings (e.g., default paths, authentication info, etc.).

Configuration

• Basic settings are specified in appsettings.json.
• Detailed or override settings can be specified with command-line arguments at runtime.

Example appsettings.json

{
  "Git": {
    "GitRepositoryUrl": "",
    "GitBranch": "main",
    "GitSshKeyPath": "C:\\Users\\user\\.ssh\\id_rsa"
  },
  "InitConfig": {
    "OutputPath": ""
  },
  "Mac": {
    "MacUnrealBasePath": "/Users/Shared/Epic Games",
    "SshUser": "",
    "SshPassword": "",
    "SshPrivateKeyPath": "",
    "SshHost": "192.168.1.100",
    "SshPort": 22,
    "XcodeNames": {
      "5.5": "/Applications/Xcode.app",
      "5.4": "/Applications/Xcode_14.1.app",
      "5.3": "/Applications/Xcode_14.1.app"
    }
  },
  "Plugin": {
    "EditorPlatforms": ["Windows","Mac","Linux"],
    "EngineVersions": ["5.5"],
    "ResultPath": "",
    "RunTest": true,
    "RunPackage": true,
    "PackagePlatforms": ["Win64","Mac","Linux","Android","IOS"]
  },
  "Windows": {
    "WindowsUnrealBasePath": "C:\\Program Files\\Epic Games"
  },
  "Linux": {
    "DockerCommand": "docker",
    "DockerImage": "ghcr.io/epicgames/unreal-engine:dev-slim-%v",
    "CopyPluginsToDocker": false,
    "DockerPluginsSourcePath": "",
    "DockerPluginsSourcePaths": {}
  }
}

The latest appsettings.json template can be generated by running the following command from Froola. Edit it after output.

Froola.exe init-config -o "path to save config template(*.json)"

appsettings.json Item Description Template (All Items)

Item Name (Path)	Type	Description	Example
Git.GitRepositoryUrl	string	Git repository URL	"git@github.com:xxx/yyy.git"
Git.GitBranch	string	Branch name to checkout	"main"
Git.GitBranches	Key-Value	UE version-specific Git branches	{"5.5":"UE5.5","5.4":"UE5.4","5.3":"UE5.3"}
Git.GitSshKeyPath	string	GitHub SSH private key file path (※1)	"C:\Users\user\.ssh\id_rsa"
Git.LocalRepositoryPath	string	Local repository path (※2)	"C:\repo\ue_plugin_project"
InitConfig.OutputPath	string	appsettings.json template output path (※3)	"C:\FroolaConfig"
Mac.MacUnrealBasePath	string	Mac Unreal Engine installation base path	"/Users/Shared/Epic Games"
Mac.SshUser	string	Mac SSH username	"macuser"
Mac.SshPassword	string	Mac SSH password (not required for public key authentication)	"password"
Mac.SshPrivateKeyPath	string	Mac SSH private key path (required for public key authentication)	"C:\Users\user\.ssh\id_rsa_mac"
Mac.SshHost	string	Mac IP address or hostname	"192.168.1.100"
Mac.SshPort	int	Mac SSH port number	22
Mac.XcodeNames	Key-Value	UE version-specific Xcode paths (※4)	{"5.5":"/Applications/Xcode.app"}
Plugin.EditorPlatforms	array	Editor platforms to use	["Windows","Mac","Linux"]
Plugin.EngineVersions	array	Unreal Engine versions to use	["5.5"]
Plugin.ResultPath	string	Result output directory (※5)	"C:\UEPluginResults"
Plugin.RunTest	bool	Run tests	true
Plugin.RunPackage	bool	Run packaging	true
Plugin.PackagePlatforms	array	Packaging platforms to use	["Win64","Mac","Linux","Android","IOS"]
Plugin.IsZipped	bool	Whether to zip the plugin output	true
Plugin.KeepBinaryDirectory	bool	Whether to keep the Binary directory after the operation	false
Windows.WindowsUnrealBasePath	string	Windows Unreal Engine installation base path	"C:\Program Files\Epic Games"
Linux.DockerCommand	string	Docker command ("docker" or "podman")	"docker"
Linux.DockerImage	string	Docker image (%v will be replaced with UE version)	"ghcr.io/epicgames/unreal-engine:dev-slim-%v"
Linux.CopyPluginsToDocker	bool	Whether to copy custom plugins to Docker UE installation	false
Linux.DockerPluginsSourcePath	string	Default path to directory containing custom plugins (※6)	"C:\MyPlugins"
Linux.DockerPluginsSourcePaths	Key-Value	UE version-specific plugin paths (※6)	{"5.5":"C:\Plugins\UE5.5","5.4":"C:\Plugins\UE5.4"}

※1 If Git.GitSshKeyPath is not set, HTTPS will be used for cloning. ※2 If Git.LocalRepositoryPath is set, the specified directory will be used base repository path. if so the remote repository will not be cloned. ※3 If InitConfig.OutputPath is not set or empty, the current directory will be used for output. ※4 Set UE version-specific Xcode paths if you need to use different Xcode versions for different UE versions. ※5 If Plugin.ResultPath is not set or empty, the "outputs" directory in the same directory as Froola.exe will be used for output. ※6 DockerPluginsSourcePaths takes precedence over DockerPluginsSourcePath. If a version is not found in DockerPluginsSourcePaths, DockerPluginsSourcePath will be used as fallback.

Usage

To run Froola with the minimum required arguments, use the following command:

Froola.exe plugin -n <plugin name> -p <project name> -u <git repository url> -b <git branch>

• Example 1: Build and package the ObjectDeliverer plugin for Windows, Mac, and Linux platforms (UE 5.5)

Froola.exe plugin -n ObjectDeliverer -p ObjectDelivererTest -u git@github.com:ayumax/ObjectDeliverer.git -b master -e Windows,Mac -v 5.5 -t -c -g Win64,Mac,Android,IOS

This command will execute the build and packaging process based on the settings in appsettings.json.

plugin Command Main Arguments

Option Name	Type	Description
-n, --plugin-name	string	Plugin name (required)
-p, --project-name	string	Project name (required)
-u, --git-repository-url	string	Git repository URL
-b, --git-branch	string	Branch name
-g, --git-branches	string[]?	UE version-specific Git branches
-l, --local-repository-path	string	Local repository path
-e, --editor-platforms	string[]?	Editor platforms (e.g., Windows, Mac, Linux)
-v, --engine-versions	string[]?	Unreal Engine versions (e.g., 5.3, 5.4, 5.5)
-o, --result-path	string?	Result output directory
-t, --run-test	bool?	Run tests
-c, --run-package	bool?	Run packaging
-g, --package-platforms	string[]?	Packaging platforms (Win64, Mac, Linux, Android, IOS)
-d, --keep-binary-directory	bool?	Whether to keep the Binary directory after the operation
-z, --is-zipped	bool?	Whether to zip the plugin output

※Non-required items can also be set in appsettings.json. Command-line arguments take priority over appsettings.json settings. ※Specify platforms and versions as comma-separated arrays (e.g., Windows,Mac,Linux).

plugin Command Execution Flow

1. Clone the specified Git repository to the Windows platform.(if --local-repository-path is not set)
2. Copy the cloned directory to each platform.
3. Execute the build, test, and packaging process for each platform.
4. Save the results in the results directory.
5. Merge the plugin packages for each platform.
6. Save the merged package in the releases directory.

Output Example

Results are saved in the directory specified by --result-path (or appsettings.json's Plugin.ResultPath) in the following structure:

Plugin name = ObjectDeliverer, v1.6.1, UE 5.5, Windows, Mac, and Linux platforms

20250502_205034_ObjectDeliverer/
├── build
│   ├── Windows_UE5.5
│   │   └── Build.log
│   ├── Mac_UE5.5
│   │   └── Build.log
│   └── Linux_UE5.5
│       └── Build.log
├── tests
│   ├── Windows_UE5.5
│   │   ├── AutomationTest.log
│   │   ├── index.html
│   │   └── index.json
│   ├── Mac_UE5.5
│   │   ├── AutomationTest.log
│   │   ├── index.html
│   │   └── index.json
│   └── Linux_UE5.5
│       ├── AutomationTest.log
│       ├── index.html
│       └── index.json
├── packages
│   ├── Windows_UE5.5
│   │   ├── BuildPlugin.log
│   │   └── Plugin
│   │       ├── ObjectDeliverer.uplugin
│   │       ├── Binaries
│   │       ├── Intermediate
│   │       ├── Resources
│   │       └── Source
│   ├── Mac_UE5.5
│   │   ├── BuildPlugin.log
│   │   └── Plugin
│   │       ├── ObjectDeliverer.uplugin
│   │       ├── Binaries
│   │       ├── Intermediate
│   │       ├── Resources
│   │       └── Source
│   └── Linux_UE5.5
│       ├── BuildPlugin.log
│       └── Plugin
│           ├── ObjectDeliverer.uplugin
│           ├── Binaries
│           ├── Intermediate
│           ├── Resources
│           └── Source
├── releases
│   └── ObjectDeliverer_1_6_1_UE5.5.zip
├── froola.log
└── settings.json

• build directory : Build results for each platform
  • Build.log : UE build log
• tests directory : Test results for each platform
  • AutomationTest.log : UE test log
  • index.html : Test result HTML
  • index.json : Test result JSON
• packages directory : Package results for each platform
  • BuildPlugin.log : UE package log
  • Plugin directory : Package result
• releases directory : Merged package for all platforms
  • .zip : Plugin package for release to Fab
• froola.log : Froola log
• settings.json : Merged settings from appsettings.json and command-line arguments

Notes

• Before running Froola, ensure that the necessary services (Docker, SSH, Xcode, Visual Studio, etc.) are properly set up for each platform.
• Mac packaging is performed via SSH on the Mac platform.
• Linux builds are performed on Windows using Docker.

License

Froola is provided under the MIT License.

Contributing

Contributions to Froola are welcome! Please report any bugs or suggest new features by creating an issue or submitting a pull request.

• Create an issue for bug reports or feature requests.
• Fork the repository and create a branch for your changes.
• Submit a pull request with a detailed description and related issue link (if applicable).
• Add tests for new classes or methods whenever possible.
• Thank you to all contributors!