A distress signal awakes you from cryosleep. A base on a nearby planet calls for aid, but when you arrive the place is deserted…

Origins

Desan is a reimagening of the very first computer game I made in 2005, also titled Desan. 14 year old me only had basic grasps of the English language and the game was taking place on a desert planet after all. I created the entire game as a point and click website using Cinema4D 6 CE and Adobe Image Ready. One I got from a magazine, the other by using my dad’s work PC. I had no idea what programming even was, just an idea and determination.

Today, only a few images remain from this version. The drive wasn’t backed up and when it failed it took almost everything with it. I remember burning the game to a CD to share, but that too is lost to time.

It seemed fitting to revisit this as my entry project to learn Godot. It took about three weeks, and I’m really happy how it turned out. My plan is to take a break now and revisit it in the future.

Credits & Licenses

No one makes a video game alone. This thanks is dedicated to the countless individuals that make this possible. Software, assets, tutorials, addons, documentation, forums take years of dedication. The tech world constantly tries to hide this fact, but I am truly in awe of the community.

Godot Engine

Freesound.org

ambientCG

Poly Haven

TextureCan

Space Spheremaps

Font Repo

Introduction

If you just want the finished pipeline you’ll find it at the end of this article.

I’ll be honest I just got started with Godot 4.5 a week ago and I can’t seem to put it down. After primarily using Unreal for a decade it’s a real breath of fresh air. Let’s not make this a Godot vs Unreal kinda article though. That will come later.

I wanted to figure out how to use Jenkins to make builds and upload them to itch.io. Godot’s internal documentation is excellent, but I was missing a really bare-bones example on how to just plug and play. Well this is that.

Build

This article focuses on windows, but thankfully all platforms seem to be handled rather similar by the engine. First of all you need a Godot installation. To keep it simple add the installation folder to PATH and rename the engine to Godot.exe.

Next you need to install the export templates. Ideally you have already done that once to make local builds. If not follow this page in the documentation: https://docs.godotengine.org/en/latest/tutorials/export/exporting_projects.html

You’ll end up with the configurations for builds. In this case the Windows one is simply titled windows and exports to .gdignore/Builds/game_windows.zip. These two entries are really all that are needed for the pipeline.

You can now make a build by simply calling

Godot.exe --headless --path "path/to/project/folder" --export-release windows

You can use this for each export configuration.

Deploy

This takes care of building, now onto uploading. You need to install itch’s deployment tool butler and make sure it is authenticated. Save the auth in an environment variable named BUTLER_API_KEY.

With that the build can be uploaded like so:

butler.exe push "path/to/project/folder/.gdignore/Builds/game_windows.zip" username/game-name:windows

Finished Pipeline

All that’s left is package the previous calls into a standard jenkins pipeline. Note that the path/to/project/folder has been replaced with the WORKSPACE variable.

pipeline {
    agent any 
    stages {
        stage('Build') { 
            steps {
                bat "Godot.exe --headless --path \"${WORKSPACE}\" --export-release windows"
            }
        }
        stage('Deploy') { 
            steps {
                bat "butler.exe push \"${WORKSPACE}/.gdignore/Builds/game_windows.zip\" username/game-name:windows"
            }
        }
    }
}

Introduction

If you just want the finished script you’ll find it at the end of this article.

Honestly when I started this task I wasn’t expecting to have to spend so many hours on it. It’s a simple premise after all: Whenever someone submits a change to the perforce depot the contents of the submission message should be posted to Discord. After all, I’ve created similar integrations for a mix and match between Git, Jenkins, Discord and Slack before. Secondly because I expected the use case to be quite common.

Yet I have had a hard time finding out what needed to be done, not least of all because of the “sparse” way the Perforce docs are often written. Also all official samples are still in Python 2?!

Prerequisites

This tutorial is written for Python 3. To run the code you’ll need p4python to communicate with the server and requests to send data to the webhook.

A working Perforce server that you can add triggers to.

The url for a Discord Webhook. If you don’t have one, check out how to make a webhook.

The Script

Most tutorials cover how to connect to P4 like this and then run commands. However, there is a catch, because certain command calls will error out either saying the client workspace is invalid, P4PASSWD isn’t set or the session expired.

from P4 import P4, P4Exception

p4 = P4()

p4.user = "SomeUsername"
p4.password = "SomePassword"
p4.port = "1666"
p4.connect()

To fix all these errors at once you need to call

p4.run_login()

Next get the latest change list info. The order of arguments is important.

changes = p4.run("changes","-l","-m 1", "//depot/...")

changes is a list with one entry. The entry is an object with all the infos from the latest change.

[
  {
    "change": "47", 
    "time": "1752951440", 
    "user": "freetimecoder", 
    "client": "freetimecoder_studio_pc", 
    "status": "submitted", 
    "changeType": "public", 
    "path": "//depot/mainline/Tools/P4/*", 
    "desc": "- Added final report python script\n"
  }
]

So here we store the relevant info for later.

clnr = changes[0]["change"]
user = changes[0]["user"]
desc = changes[0]["desc"]

Now that we got the info it’s time to send it to Discord. Provided the webhook is active this is as simple as doing a json post request to the url.

import requests

...

data = {
    "content" : "",
    "username" : "Perforce",
    "embeds": [
        {
            "title" : f"{user} submitted CL-{clnr}",
            "description" : desc
        }
    ]
}

result = requests.post(discord_webhook_url, json = data)

Running the script yields a message like this in the designated Discord channel.

Trigger Setup

Now that the script is done, all that’s left is to make Perforce actually execute it. Triggers are made for that. Whenever a specific action happens Perforce can execute custom code. To start adding a trigger run this in the terminal:

p4 triggers

This will open a text file in the text editor that is configured for Perforce. Scroll way down to the bottom and add

Triggers:
    discord change-commit //depot/... "py /path/to/script/reporter.py"

Save and close the file and Perforce should say “Triggers saved.”

The config is composed of these parts:

And there you go, pushing a change should now post messages in Discord.

Finished Script

The final script has a few more bells and whistles, but essentially works the same. A thing to note is that if you want to sync the script inside the repository you need to put the credentials into environment variables or an external config file.

#!/usr/bin/env python3
from P4 import P4, P4Exception
import requests

# You'll need to change these to fit your setup 
p4_user = "SomeUsername"
p4_password = "SomePassword"
p4_port = "server:1666"
# This is optional depending on your ssl setup
p4_fingerprint = None 
# What path to watch for changes, in case you have multiple depots
p4_depot_path = "//depot/..."
# Endpoint for the messages
discord_webhook_url = "https://discord.com/..."

p4 = P4()

try:
    p4.user = p4_user
    p4.password = p4_password
    p4.port = p4_port
    p4.connect()
    if p4_fingerprint not None:
        p4.run_trust("-i", p4_fingerprint)
    p4.run_login()
    
    # Fetch the long description of the latest submission
    changes = p4.run("changes","-l","-m 1", p4_depot_path)

    # Get the parts of the changelog that interest us for the message
    clnr = changes[0]["change"]
    user = changes[0]["user"]
    desc = changes[0]["desc"]
        
    # An empty message "from Perforce" with the change list message in an embed
    data = {
        "content" : "",
        "username" : "Perforce",
        "embeds": [
            {
                "title" : f"{user} submitted CL-{clnr}",
                "description" : desc
            }
        ]
    }
    
    # Send message to Discord
    result = requests.post(discord_webhook_url, json = data)
    result.raise_for_status()
    
except P4Exception:
    # Send any P4 errors to Discord and output
    for e in p4.errors: 
        requests.post(config["discord_webhook"], json = { "content" : str(e), "username" : "Perforce"})
        print(e)
except Exception as e:
    # Send any other exceptions to Discord as well 
    requests.post(config["discord_webhook"], json = { "content" : str(e), "username" : "Perforce"})
    print(e)

Errors

Perforce does throw errors, but it’s hard to know what they mean and how to fix them. So I’ve listed all of them down here in hopes a search engine might pick up on it.

The -l parameter must be passed in before the depot path

p4.run_login() must be called before running the command

Most tutorial go right to where p4.connect() is called, however p4.run_login() needs to be called before running some commands.

And despite my best efforts to talk people’s ears off about them whenever I can there are still people unaware of my very specific opinions. So here you go!

Oh, and none of this is sponsored, in fact I bought all the plugins myself.

Blueprint Assist

Get it on FAB

Blueprint Assist auto formats Blueprints. It’s a must-have if you are working with Blueprints. I’ve become allergic to dragging nodes around with my mouse. Just hit F on a node and watch your Blueprint be pretty. I’ve heard complaints that it’s not always making it pretty, but that means you can improve the flow of your code.

Node Graph Assistant

Get it on FAB

I’d say this is the spiritual little brother of Blueprint Assist. Lots of helpful improvements for wrangling Blueprint wires. It also has auto-format capabilities, but I mostly use it for auto-connecting or disconnecting wires.

The plugin has a ton more features, it’s best to check out the documentation.

LE Extended Standard Library

Get it on FAB

This one is a goodie box of helpful nodes. I’ve been using this since forever, there’s too much to look at in here so I’ll encourage you to look at the store page and docs.

Auto Size Comments

Get it on FAB

Does what it says. Instead of dragging comment box borders around to match their contents, this just does it for you.

Blockout Tools

Get it on FAB

Yes I know about the Modeling tools and the Grid Modeler, but for me the Blockout tools are still the quickest and easiest way to jot down some level geometry. This plugin contains a variety of different shape builders and mostly uses simple base shape meshes, so it won’t bloat your project with custom mesh bits and pieces.

~~

Capture Thumbnail

This one is the easiest, but also entirely manual. In Unreal simply right-click on an asset and choose Asset Actions -> Capture Thumbnail. This will take a screenshot of the current level viewport and make it the asset’s thumbnail.

Class Icon / Class Thumbnail

To create a default thumbnail like Unreal does for Bluperints or Data Assets you’ll need an editor slate style. There’s a good article on creating and using slate styles on Minifloppy.it, so I’m only going to cover the important section here. Unreal will also generate a boilerplate style if you create a new editor mode plugin via the plugin window.

The important part is to set Brushes in the format ClassIcon.ClassName and ClassThumbnail.ClassName and assign .png or .svg files. The code below loads MyPlugin/Resources/myclass_icon.png which is 16 by 16 pixels and MyPlugin/Resources/myclass_thumbnail.svg.

Though SVGs are vector graphics Unreal code always passes along a 64 size. Inspecting the code reveals that it goes into the FDeprecateSlateVector2D structure, so maybe it’s no longer needed. I’ve not delved further into the code to find out so I’ll keep it for now.

TSharedRef< FSlateStyleSet > FMyPluginEditorStyle::Create()
{
	// This is how Unreal code does it for sizes, as far as I know there's only 16, 20 and 64
	const FVector2D Icon16x16(16.0f, 16.0f);
	const FVector2D Icon64x64(64.0f, 64.0f);

	TSharedRef< FSlateStyleSet > Style = MakeShareable(new FSlateStyleSet("MyPluginEditorStyle"));
	
	// Set the content root of the style to the plugins resource directory
	Style->SetContentRoot(IPluginManager::Get().FindPlugin("MyPlugin")->GetBaseDir() / TEXT("Resources"));

	// Loads a png image as a class icon for UMyClass or AMyClass
	Style->Set("ClassIcon.MyClass", new IMAGE_BRUSH(TEXT("myclass_icon"), Icon16x16));

	// Loads an svg image as a thumbnail icon for UMyClass or AMyClass
	Style->Set("ClassThumbnail.MyClass", new IMAGE_BRUSH_SVG(TEXT("myclass_thumbnail"), Icon64x64));
	return Style;
}

Thumbnails appear in the content browser (1) and class icons just about everywhere else (2 - 5).

Style wise I’ve observed that Unreal’s thumbnails always have an empty background and border around them. If the image has no borders it almost fills the entire thumbnail, but leaves a few pixels free. Personally I’d recommend to always keep some space.

Class icons should always be in greyscale, but even better in black and white since they get tinted differently all over the place.

Custom Thumbnail Renderer

This approach is arguably the most versatile but also most complicated. Some assets like Textures or Meshes get thumbnails based on their content. In order to do this there is a class called UThumbnailRenderer (or it’s more often used derived class UDefaultSizedThumbnailRenderer) which allows the thumbnail size to be set via config. The main methods to override are CanVisualizeAsset and Draw. In order for the renderer to be used it needs to be registered with the UThumbnailManager.

CanVisualizeAsset gets given the loaded asset before any rendering takes place. Returning true continues the render process, false aborts and the thumbnail stays empty.

Draw is where the actual thumbnail texture is being rendered. In my use case the thumbnail simply draws a background, the icon of a data asset and a tag text to show it’s a recipe.

Here’s the header for a custom thumbnail renderer for Recipe Data Assets in Garden Witch Life:

#pragma once

#include "ThumbnailRendering/DefaultSizedThumbnailRenderer.h"
#include "GWLRecipeAssetThumbnailRenderer.generated.h"

/**
 * Thumbnail renderer for Recipe Assets
 */
UCLASS()
class GARDENWITCHLIFEEDITOR_API UGWLRecipeAssetThumbnailRenderer : public UDefaultSizedThumbnailRenderer
{
	GENERATED_BODY()

public:
	virtual bool CanVisualizeAsset(UObject* Object) override;
	virtual void Draw(UObject* Object, int32 X, int32 Y, uint32 Width, uint32 Height, FRenderTarget* Viewport, FCanvas* Canvas, bool bAdditionalViewFamily) override;
};

And the Implementation:

#include "GWLRecipeAssetThumbnailRenderer.h"
#include "Crafting/GWLRecipeDataAsset.h"
#include "CanvasItem.h"
#include "CanvasTypes.h"
#include "ThumbnailRendering/ThumbnailManager.h"

bool UGWLRecipeAssetThumbnailRenderer::CanVisualizeAsset(UObject* Object)
{
	// Only render thumbnail for recipes that have a valid icon
	if(const auto Recipe = Cast<UGWLRecipeDataAsset>(Object))
	{
		if(Recipe->Icon.LoadSynchronous())
		{
			return true;
		}
	}
	
	return false;
}

void UGWLRecipeAssetThumbnailRenderer::Draw(UObject* Object, int32 X, int32 Y, uint32 Width, uint32 Height,
											FRenderTarget* Viewport, FCanvas* Canvas, bool bAdditionalViewFamily)
{
	const UGWLRecipeDataAsset* Recipe = Cast<UGWLRecipeDataAsset>(Object);
	const UTexture2D* RecipeIcon = Recipe->Icon.LoadSynchronous();
	
	// Draw a checkerboard background
	constexpr int32 CheckerDensity = 8;
	const auto Checker = UThumbnailManager::Get().CheckerboardTexture;
	Canvas->DrawTile(
		0.0f, 0.0f, Width, Height, // Dimensions
		0.0f, 0.0f, CheckerDensity, CheckerDensity, // UVs
		FLinearColor::Gray, Checker->GetResource()); // Tint & Texture

	// Draw the recipe's icon centered and filling out the thumbnail
	FCanvasTileItem CanvasTile(FVector2D(X, Y), RecipeIcon->GetResource(), FVector2D(Width, Height), FLinearColor::White);
	CanvasTile.BlendMode = SE_BLEND_Translucent;
	CanvasTile.Draw(Canvas);

	// Figure out how big the rendered text would be
	auto RecipeChars = TEXT("Recipe");
	int32 RecipeTextWidth = 0;
	int32 RecipeHeight = 0;
	StringSize(GEngine->GetLargeFont(), RecipeTextWidth, RecipeHeight, RecipeChars);
	float PaddingX = Width / 128.0f;
	float PaddingY = Height / 128.0f;
	float ScaleX = Width / 64.0f; //Text is 1/64'th of the size of the thumbnails
	float ScaleY = Height / 64.0f;

	// Draw the "Recipe" overlay text
	FCanvasTextItem TextItem(FVector2D(Width - PaddingX - RecipeTextWidth * ScaleX, Height - PaddingY - RecipeHeight * ScaleY), FText::FromString(RecipeChars), GEngine->GetLargeFont(), FLinearColor::White);
	TextItem.EnableShadow(FLinearColor::Black);
	TextItem.Scale = FVector2D(ScaleX, ScaleY);
	TextItem.Draw(Canvas);
}

In order for the thumbnail renderer to be called by Unreal it needs to be registered, preferrably on module startup.

#include "ThumbnailRendering/ThumbnailManager.h"

void FGardenWitchLifeEditorModule::StartupModule()
{
    UThumbnailManager::Get().RegisterCustomRenderer(UGWLRecipeDataAsset::StaticClass(), UGWLRecipeAssetThumbnailRenderer::StaticClass());
}

And now it’s doing its job:

Custom Thumbnail Renderer (for Blueprints)

Sadly this approach doesn’t work for Blueprints. Registering a thumbnail renderer for AMyActor wouldn’t work, because Unreal wraps all Blueprint assets into UBlueprints and there already is a UBlueprintThumbnailRenderer. In order to solve this, a new renderer can be injected. Thanks to @Schadek on the Unreal Forums for this solution!

The trick is to derive from UBlueprintThumbnailRenderer and replace it with the derived class.

// GWLBlueprintThumbnailRenderer.h

#include "ThumbnailRendering/BlueprintThumbnailRenderer.h"
class UGWLBlueprintThumbnailRenderer : public UBlueprintThumbnailRenderer


// GardenWitchLifeEditorModule.cpp

void FGardenWitchLifeEditorModule::StartupModule()
{
	// Unregister default renderer
 	UThumbnailManager::Get().UnregisterCustomRenderer(UBlueprint::StaticClass());
	
	// Register our custom renderer instead
	UThumbnailManager::Get().RegisterCustomRenderer(UBlueprint::StaticClass(), UGWLBlueprintThumbnailRenderer::StaticClass());
}

and that’s it!

Ok one last thing, the Draw method gets the UBlueprint passed in as the Object to draw, not the native class. To get the actual default object and native class there’s some more work required.

void UMisBlueprintThumbnailRenderer::Draw(UObject* Object, int32 X, int32 Y, uint32 Width, uint32 Height, FRenderTarget* RenderTarget, FCanvas* Canvas, bool bAdditionalViewFamily)
{
	const UBlueprint* Blueprint = Cast<UBlueprint>(Object);
	if (Blueprint)
	{
		const UClass* GeneratedClass = Blueprint->GeneratedClass;
		if (Blueprint->GeneratedClass->IsChildOf(AMyActor::StaticClass()))
		{
			if (const AMyActor* CDO = Class->GetDefaultObject<AMyActor>())
			{
				// Do rendering
				return;
			}
		}
	}

	// Fall back to original renderer
	Super::Draw(Object, X, Y, Width, Height, RenderTarget, Canvas, bAdditionalViewFamily);
}

However, with the number of widgets increasing it also starts to become more and more frustrating to find and launch them via Right Click -> Run Widget. So what better way to offload that than into another editor widget? So I’ve created a button collection widget where each button launches one of the other widgets.

Still I found myself opening and closing that window a lot. Launching one widget instead of many was less fun than I had hoped. So what about putting it in the editor toolbar?

Creating the Toolbar Button

This step is actually quite easy since Unreal’s plugin creation wizard already gives us all the boilerplate code. We simply go to Edit -> Plugins and click the Add button. Then choose Editor Toolbar Button and name it something like MyEditorTools and click Create Plugin.

Tada! After the code is compiled we’ll have a fresh toolbar button.

Running the Editor Widget

When the button is clicked it pops up a little notification that tells us how to change its behavior. The button calls a function named PluginButtonClicked in MyEditorTools.cpp. This is where we’ll open our editor widget.

void FMyEditorToolsModule::PluginButtonClicked()
{
	// Put your "OnButtonClicked" stuff here
	FText DialogText = FText::Format(
					LOCTEXT("PluginButtonDialogText", "Add code to {0} in {1} to override this button's actions"),
					FText::FromString(TEXT("FMyEditorToolsModule::PluginButtonClicked()")),
					FText::FromString(TEXT("MyEditorTools.cpp"))
				   );
	FMessageDialog::Open(EAppMsgType::Ok, DialogText);
}

To be able to open Blueprint Editor Widgets we’ll need to add some dependencies to the plugin.

First in the MyEditorTools.uplugin, we’ll need to add the Editor Scripting Utilities as a dependent plugin:

"Plugins": [
	{
		"Name": "EditorScriptingUtilities",
		"Enabled": true
	}
]

Next we need to add UMGEditor, EditorScriptingUtilities and Blutility to the PrivateDependencyModuleNames list in Plugins/MyEditorTools/Source/MyEditorTools/MyEditorToolsModule.Build.cs. It should look like this:

PrivateDependencyModuleNames.AddRange(
	new string[]
	{
		"Projects",
		"InputCore",
		"EditorFramework",
		"UnrealEd",
		"ToolMenus",
		"CoreUObject",
		"Engine",
		"Slate",
		"SlateCore",
		"UMGEditor",
		"EditorScriptingUtilities",
		"Blutility",
		// ... add private dependencies that you statically link with here ...	
	}
);

Which brings us back to MyEditorTools.cpp. After adding the dependencies we’ll add the following includes:

#include "Editor.h"
#include "EditorAssetLibrary.h"
#include "EditorUtilitySubsystem.h"
#include "EditorUtilityWidgetBlueprint.h"

Next we’ll need the reference path to the Editor Widget that we want to launch. To get that we Right Click on the widget asset and choose Copy Reference. It should put a path into the clipboard looking something like this:

/Script/Blutility.EditorUtilityWidgetBlueprint'/MyEditorTools/MainEditor/EWB_MyEditor.EWB_MyEditor'

We remove the “/Script/Blutility.” part from the path and paste it into the LoadAsset function. This code replaces the stub in the PluginButtonClicked function.

void FMyEditorToolsModule::PluginButtonClicked()
{
	//Load the editor widget asset
	UObject * Blueprint = UEditorAssetLibrary::LoadAsset(FString(TEXT("EditorUtilityWidgetBlueprint'/MyEditorTools/MainEditor/EWB_MyEditor.EWB_MyEditor'")));
	if(IsValid(Blueprint)) 
	{
		//Make sure it's actually an editor widget
		UEditorUtilityWidgetBlueprint* EditorWidget = Cast<UEditorUtilityWidgetBlueprint>(Blueprint);
		if (IsValid(EditorWidget)) 
		{
			//Use the utility subsystem to spawn the widget
			UEditorUtilitySubsystem* EditorUtilitySubsystem = GEditor->GetEditorSubsystem<UEditorUtilitySubsystem>();
			EditorUtilitySubsystem->SpawnAndRegisterTab(EditorWidget);
		}
	}
}

After compiling the toolbar button should now launch the editor widget.

Custom Tooltip

When hovering over the button a tooltip is displayed. By default it will say “Execute MyEditorTools action”. We can change what it says by editing the text in the RegisterCommands method in MyEditorToolsCommands.cpp:

void FMyEditorToolsCommands::RegisterCommands()
{
	UI_COMMAND(PluginAction, "MyEditorTools", "Execute MyEditorTools action", EUserInterfaceActionType::Button, FInputChord());
}

Custom Icon

The toolbar button displays as some slanted grey lines. In order to give it a more personal look we edit MyEditorToolsStyle.cpp. FMyEditorToolsStyle::Create creates a new slate style sheet and loads the button icon file as a brush with the id “MyEditorTools.PluginAction”. The folder this image is loaded from is Plugins/MyEditorTools/Resources/.

TSharedRef< FSlateStyleSet > FMyEditorToolsStyle::Create()
{
	TSharedRef< FSlateStyleSet > Style = MakeShareable(new FSlateStyleSet("MyEditorToolsStyle"));
	Style->SetContentRoot(IPluginManager::Get().FindPlugin("MyEditorTools")->GetBaseDir() / TEXT("Resources"));

	Style->Set("MyEditorTools.PluginAction", new IMAGE_BRUSH_SVG(TEXT("PlaceholderButtonIcon"), Icon20x20));
	return Style;
}

To load a different image we put it into the folder.

To load it we create a new IMAGE_BRUSH and use the file name without the extension.

Style->Set("MyEditorTools.PluginAction", new IMAGE_BRUSH(TEXT("ToolbarIcon"), Icon20x20));

In case the icon is an SVG, we use IMAGE_BRUSH_SVG instead.

Style->Set("MyEditorTools.PluginAction", new IMAGE_BRUSH_SVG(TEXT("PlaceholderButtonIcon"), Icon20x20));

And there we have it. One more compile and the custom button is done!✨

Simply pass in any FName for a platform to a static method of UPlatformSettingsManager

static void UPlatformSettingsManager::SetEditorSimulatedPlatform(FName PlatformIniName)

Common UI queries which platform it is running on to determine which icons or traits to use. If the simulated platform value is anything else than None it will get that platform instead of the actual one the editor is running on.

Using it in Blueprints

I have not found a blueprint exposed way to use it, but it’s easy enough to write a small wrapper method in a function library. Be mindful though that the simulated platform only exists with editor context so there’s an #ifdef guard in the implementation.

.h
UFUNCTION(BlueprintCallable, Category="Common UI", CallInEditor)	
static void SetSimulatedUiPlatform(FName PlatformIniName);

.cpp
void UFtsMenuFunctionLibrary::SetSimulatedUiPlatform(FName PlatformIniName)
{
	#if WITH_EDITOR
	UPlatformSettingsManager::SetEditorSimulatedPlatform(PlatformIniName);
	#endif
}

With that I created a small Editor Utility Widget that has a String Combo Box with the different platforms and whenever one is chosen the platform is set.

Going Further

In my project there’s more multi platform code and it essentially centers around UGameplayStatics::GetPlatformName calls. This means even when setting the simulated platform only Common UI code reacts to it. To fix this I added a new method that mirrors what Common UI does internally:

.h
UFUNCTION(BlueprintCallable, BlueprintPure, Category="Common UI")	
static FString GetRealOrSimulatedPlatformName();

.cpp
FString UFtsMenuFunctionLibrary::GetRealOrSimulatedPlatformName()
{
	#if WITH_EDITOR
	const FName SimulatedPlatformName = UPlatformSettingsManager::GetEditorSimulatedPlatform();
	if(!SimulatedPlatformName.IsNone())
	{
		return SimulatedPlatformName.ToString();
	}
	#endif	
	
	return FPlatformProperties::IniPlatformName();
}

Lyra

After posting this Article to the Ben UI Discord I was told that the Lyra Sample Game uses this functionality too and did a quick check. Lyra has an entire class called ULyraPlatformEmulationSettings that does this and a few more things so I’d recommend to check it out.

Thanks

Before getting started I want to give thanks and credit to the following people:

• Blossom Kremer Our publisher’s amazing producer who went above and beyond to support us and the game.
• Ben UI for his blog ben🌱ui / Discord / providing an invaluable amount of resources
• Alexander Bukhonov for answering my questions about how to pass player gender to text
• Denis Maltsev for creating the Translation Editor for UE4

I also want to make it clear that the problems documented in this article stem soely from my inexperience at the time. I don’t want to put blame on anyone else. Everyone involved in the process acted to the best of their knowledge and had nothing but understanding for any technical difficulties.

Other Resources

This article is not meant as a full tutorial on how to localize, there are already plenty of resources out there. I’m trying to fill the blanks I had after reading the other resources.

• Localization, Unreal’s Official Documentation
• Unreal UIs and Localization by ben🌱ui
• Localization in Unreal Engine (UE4) by Chris McCole

Expectations vs. Reality

For the longest time I was aware that Unreal had support for localization and assumed it was mostly automated. As long as I used FText variables (or simply Text in BPs) I could go into the Localization Editor, gather up all the words and translate them or send them to translators.

However, when the time came to prepare translations to send to translators everything fell apart and I had to work long hours to fix it in time to meet deadlines.

Unreal automatically works with .po files, which from my initial research seemed to be a common interchange format for translations. The file is essentially a long list of entries like this one:

#. Key:    C9AD374C498E67CC9B9F9F98E41D87A5
#. SourceLocation:
#. /Game/MagicItemShop/Blueprints/Items/BP_Potion.Default__BP_Potion_C.FriendlyName
#: /Game/MagicItemShop/Blueprints/Items/BP_Potion.Default__BP_Potion_C.FriendlyName
msgctxt ",C9AD374C498E67CC9B9F9F98E41D87A5"
msgid "Potion"
msgstr "Zaubertrank"

The really important parts are:

• msgctxt: This is an identifier in the form “Namespace,Key” for a given piece of text
• msgid: The original text
• msgstr: The translated text

The other lines are comments that you can see in the Localization Editor in Unreal (and supposedly in other software that uses this format). From my understanding translators would be able to work with this info to sort through the text. This was right at the start of development in 2019.

When it came time to initially discuss translations with our publisher in 2021 I learned that the way data would be passed around was going to be via an Excel Sheet. So I went back to Google and found Denis Maltsev’s Translation Editor for UE4. I did a few tests with it and it worked very well. It provides a way to handle Excel files and the import / export process worked like a charm.

Development continued until 2023 when the milestone for translations was next. At this point I was given a pre-formatted Excel sheet by our publisher. And it was not compatible with the Translation Editor. So I took the Excel export from the editor and tried to manually copy over the lines into their respecitve columns. It was at this point I realized that only the text keys remain to identify and sort the text.

All of them look something like this: “C9AD374C498E67CC9B9F9F98E41D87A5”.

My mistake was assuming that the auto generated keys would have some sort of grouping or order to them. In hindsight this is something I could have caught early, but there were too many other things requiring my attention before translations became the top priority.

Now I had to go through all of the text variables in our game and assign proper keys to over 6000 entries strewn all over the project. Overall this process took weeks.

Generating Text Keys

A lot of assets in the game are id based. Items, Mails, Quests utilize Primary Asset Ids. That means these objects already have a unique (Type, Name) pair that they are addressed by. I wrote a small piece of C++ code that updates a Text namespace and key to match given values and I made these values dependent on the asset id.

This is the snippet inside a Blueprint Function Library that changes the keys. Technically only FText::ChangeKey is required. However I update these values whenever an asset is saved and this can happen while cooking content. To avoid warnings I made sure to only update the data if needed.

MisUtilityFunctionLibrary.h
/**
 * @brief Changes the namespace and key of a given Text property, but only if they are different from the given ones.
 * @param InOutText Text property to update namespace and key for
 * @param NewKey Key to set for text property
 * @param Namespace Namespace to set for text property
 */
UFUNCTION(BlueprintCallable, Category="FreetimeStudio|Editor")
static void UpdateTextKeyIfDifferent(UPARAM(Ref) FText& InOutText, const FString& NewKey, const FString& Namespace);


MisUtilityFunctionLibrary.cpp

void UMisUtilityFunctionLibrary::UpdateTextKeyIfDifferent(FText& InOutText, const FString& NewKey,
								const FString& Namespace)
{
#if WITH_EDITORONLY_DATA
	const TOptional<FString> ExistingKey = FTextInspector::GetKey(InOutText);
	const TOptional<FString> ExistingNamespace = FTextInspector::GetNamespace(InOutText);
	if(!ExistingKey.IsSet() || ExistingKey.GetValue() != NewKey || ExistingNamespace != Namespace)
	{
		InOutText = FText::ChangeKey(Namespace, NewKey, InOutText);
	}
#endif
}

Updating the text happens when an asset is saved. I’m not guaranteeing that this is the best place to do this, but from my tests this is where it works:

• Actors: PreSave
• Data Assets: PreSaveRoot

Alternatively the function can also be called during Construction Scripts or other initializers.

void UMisMailMessageDataAsset::PreSaveRoot(FObjectPreSaveRootContext ObjectSaveContext)
{
	Super::PreSaveRoot(ObjectSaveContext);

#if WITH_EDITORONLY_DATA
	//Get Asset Id
	const FPrimaryAssetId AssetId = GetPrimaryAssetId();
	
	//Convert Asset Id Type,Name to "Type_Name" prefix for key
	const FString TextKeyPrefix = AssetId.PrimaryAssetType.ToString() + FString("_") 
							+ AssetId.PrimaryAssetName.ToString();

	//Change Text data to (Mail, Type_Name_Title)
	const FString TitleKey = TextKeyPrefix + FString("_Title");
	UMisUtilityFunctionLibrary::UpdateTextKeyIfDifferent(Title, TitleKey, "Mail");

	//Change Text data to (Mail, Type_Name_Message)
	const FString MessageKey = TextKeyPrefix + FString("_Message");
	UMisUtilityFunctionLibrary::UpdateTextKeyIfDifferent(Message, MessageKey, "Mail");
#endif
	
}

With this in place key data gets updated automatically and requires a simple “Resave All” for existing assets.

String Tables

Purely from a data organization viewpoint String Tables are the way to go for every text. However in practice there were multiple people involved in the creation of items, mails, quests and dialogue and I decided against trying to consolidate everything into one or more tables. Instead I went with the automatically generated key approach for those assets.

Another area that needed a lot of text was UI though. Here I was the only one adding text and a lot of elements share the same texts. The setup was a bit more involved because each text value needs to be assigned manually, but the benefit is that translators don’t have to translate the exact same text multiple times.

Automating Import

After realizing that I would not be able to use the Translation Editor to import translations I wrote a python script to take care of this step. It was quite a bit of trial and error, but thanks to OpenPyXL for reading xlsx and Babel being able to handle po files, I managed to automate the process.

The exact Excel sheet is under wraps, but the format was roughly like this: A text id per row with languages in columns. The file also had multiple work sheets for different categories.

The goal was to make the corresponding entries in the po files look like this:

#. Key:    CommunityBox_Report
#. SourceLocation:
#. /Game/MagicItemShop/Localization/StringTables/ST_UserInterface.ST_UserInterface
#: /Game/MagicItemShop/Localization/StringTables/ST_UserInterface.ST_UserInterface
msgctxt "UI,CommunityBox_Report"
msgid "Earnings"
msgstr "Ertrag"

#. Key:    CommunityBox_Sell
#. SourceLocation:
#. /Game/MagicItemShop/Localization/StringTables/ST_UserInterface.ST_UserInterface
#: /Game/MagicItemShop/Localization/StringTables/ST_UserInterface.ST_UserInterface
msgctxt "UI,CommunityBox_Sell"
msgid "Sell"
msgstr "Verkaufen"

#. Key:    Container_Chest
#. SourceLocation:
#. /Game/MagicItemShop/Localization/StringTables/ST_UserInterface.ST_UserInterface
#: /Game/MagicItemShop/Localization/StringTables/ST_UserInterface.ST_UserInterface
msgctxt "UI,Container_Chest"
msgid "Chest"
msgstr "Kiste"

The idea of the import script is straight forward. Read a row in the sheet, find the corresponding key in the different langauge files and assign the value in found in that language’s cell.

#!/usr/bin/env python3
# Extra modules required for this script
# pip install openpyxl
# pip install babel

import json
from babel.messages import pofile
from openpyxl import Workbook, load_workbook
from io import BytesIO

# Set localization sheet path:
localization_sheet_path = "some/where/in/the/cloud/Localization/"
localization_sheets = [
    "Garden Witch Life - Main Localization.xlsx", 
    "Garden Witch Life - Achievements Localization.xlsx",
    "Garden Witch Life - Additional Localization 1.xlsx", 
    "Garden Witch Life - Additional Localization 2.xlsx"
]

#Path to folder where the .uproject file is in
unreal_loc_path = "some/where/local/UnrealProject/Content/Localization/Game"

# Map all Unreal cultures to columns in the translation sheet
culture_map = [
    ["en", "F"], # E before proofreading, F after
    ["de", "G"], 
    ["..", ".."] # Additional language mappings
]

# Sheet includes header info that is not part of the translation data
first_value_row = 4

# Worksheet Ids, name of each sheet
worksheet_id_UI = "Menu"
worksheet_id_Characters = "Characters"
worksheet_id_Quests = "Quests"
worksheet_id_Dialogue = "Dialogue"
worksheet_id_Items = "Objects"

# Put them all in a list for iteration
worksheet_ids = [
    worksheet_id_UI, 
    worksheet_id_Characters, 
    worksheet_id_Quests, 
    worksheet_id_Dialogue, 
    worksheet_id_Items
]

# All texts in unreal are identified by a combination of Namepsace:Key
# Map all Unreal namespaces to sheet ids, e.g. all text with the namespace UI 
# will be found in the work sheet worksheet_id_UI
namespace_map = {
    "UI" : worksheet_id_UI,
    "Character" : worksheet_id_Characters,
    "Creature" : worksheet_id_Characters,
    "Quest" : worksheet_id_Quests,
    "Mail" : worksheet_id_Quests,
    "Dialogue" : worksheet_id_Dialogue,
    "Item" : worksheet_id_Items,
}


# This is where all the localization data from the sheets will be stored
# in the form database[ "en" : { "id1" => "text", "id2" => "text2" } ]
loc_database = {}

# Populate the table with all the cultures
for culture in culture_map:
    loc_database[culture[0]] = {}

# First step is to iterate over all localization excel files 
# and gather all the localization data
for localization_sheet in localization_sheets:
    workbook_path = localization_sheet_path+localization_sheet
    
    print("Loading "+workbook_path)
    
    workbook = load_workbook(filename=workbook_path)

    # Iterate through all work books
    for worksheet_id in worksheet_ids:
	
        # Some of the sheets only contain partial data, 
        # so skip reading if one is missing
        if worksheet_id not in workbook:
            print("Skipping missing sheet Id "+worksheet_id)
            continue
        
        # Get the sheet and read all rows
        sheet = workbook[worksheet_id]
        
        # Start reading data after header row
        row = first_value_row
        more_data = True
        
        while more_data:
            # Check if the id cell has a value, after a certain point 
            # there are no more values in the table
            row_str = str(row)
            key = sheet["A"+row_str].value
            if key == None:
                more_data = False
                break

            # Iterate through all cultures in map and read the cell values into the database
            for culture in culture_map:
                translation = sheet[culture[1]+row_str].value
                if translation != None:
                    loc_database[culture[0]][key] = translation
                else:
                    # Empty cell
                    loc_database[culture[0]][key] = ""
            
            row += 1

# Next step is to write the read data into the po files
for culture in culture_map:
    culture_id = str(culture[0])
    po_path = unreal_loc_path+"/"+culture_id+"/Game.po"

    # Open the file, make sure to use UTF-8 encoding, 
    # otherwise some language will error out
    with open(po_path, 'r', encoding='utf-8') as fh:
        catalog = pofile.read_po(fh)
        
        # Each entry in the po file is a message, and the key is called 'context'
        for message in catalog:
            if message.context in loc_database[culture_id]:
                translation = loc_database[culture_id][message.context]
                if translation:
                    message.string = str(translation)
                else:
                    message.string = ""
            
        
        # Write po file into bytes first to avoid any encoding problems
        buf = BytesIO()
        pofile.write_po(buf, catalog)

        # Write buffer into file, overwriting po with new data
        print("Writing file "+ culture_id)
        with open(unreal_loc_path+"/"+culture_id+"/Game.po", 'wb') as out:
            out.write(buf.getbuffer())
            

Fallback Fonts

When defining a font for text Unreal has the option to define fallbacks for characters that are not included in the primary font. Honestly I don’t have much to say about this, it mostly worked as intended.

I stumbled over one curious case though: From what I understand Japanese and Chinese share some charsets. However when configuring the character ranges I either had the case where Chinese was missing symbols because the font would switch to the Japanese fallback or Japanese was missing symbols because it was using the Chinese fallback.

Constraining the Japanese font to the ‘ja’ culture fixed it. This is the feature working as intended, I was just not aware of its existence until I hovered over the text box.

Pitfalls

In this section I’ll list any other smaller issues that came up during production.

Other platforms, other terminology

If you plan to release your game on consoles you might need to adhere to much stricter guidelines than if you release just on PC. Simple things like “Press Any Key” can get flagged as improper terminology on a console, because it should be “Button” instead. Sadly specific examples are under NDA, so make sure you read up on the available documentation.

In such cases I added a TMap<FString,FText> PlatformOverrides property. It allowed me to add a different text for a specific platform that can be queried with GetPlatformName.

The Localization System picks up on Niagara assets

Make sure to not include folders with Niagara Particle System assets. Otherwise there will be some system text in the gathered localization.

Languages other than English care about gender a lot more

English is very relaxed when it comes to gendering, almost everything is neutral or can be expressed in a neutral way. However it is very important to let translators know which gender characters have in text referencing them. A lot of things can change based on that and translators need to be able to know who is talking, who they are talking to and what about. If your player can pick their character’s gender make sure to pass along a variable translators can use.

Let them know how to use variables by showing them the documentation or by providing your own notes tailored to the specific use cases. There is a great article on how to pass player gender to text.

For Garden Witch Life’s dialogue I provided the following list of variables. Leaving the player gender as simply g was done to make the translators life easier, since a lot of dialogue required its use.

Be prepared to answer questions

The translators will most likely not know what text is referencing and they will ask about it. Probably 90% of questions we got was about what something looked like. I ended up writing an editor utility script to export all the items into a long table that contained their icon, id and display name.

Be wary of missing text

At the start I wanted to do everything very cleanly. Added all the folders with Blueprints and Data Assets in them so the Text Gather would pick them up. Later I realized that this makes it much easier to miss something. An asset could be moved, a new folder created without the path being added.

Having a clean folder structure is a good goal, however in reality it’s better to be on the save side. I added the entire Content folder to the Include Path Wildcards and only selectively removed folders using Exclude Path Wildcards when something turned up in the text export that was not supposed to be there.

If you add plugin folders through the localization folder it will do so without complaint, but the text gather will silently fail and not include assets in plugins.

In my case however there was so much text that only shows up in very specific states of the game I would never get to test it all in a reasonable time frame.

Same keys = Same text

Not so much a problem, but it’s good to be aware that Unreal will consider two pieces of text the same if they have the same namespace and key. This can be useful when copy pasting text to different places in the game. However in such a case it is probably better to use a String table entry instead.

You may need to update localization over and over

The ideal path for translation was

1. Export English texts
2. Get proof reading done
3. Get translations done
4. Import to Unreal

The actual path was more like:

1. Export English Texts
2. Send to be proof read
   • 2.1 Answer Questions for proof readers
   • 2.2 Get proof read results
3. Send to translators
   • 3.1 Answer questions from translators
4. Notice there was a miscommunication whether or not it should be American or British English
   • 4.1 Send back to proof reading
   • 4.2 Receive updated results
5. Get first part of translations
   • 5.1 Send update to translators
   • 5.2 Answer questions from translators
6. Import first batch of translations
7. Realize some pieces of text are missing
8. Export new pieces in separate sheet
9. Get new sheet proofread
10. Send new sheet to translators
    • 10.1 Answer questions from translators
11. Get feedback from LQA testers that some things are worded strange
12. - ???. End up sending lots of documents back and forth, have multiple corrections and now there are four sheets.

Conclusion

So there you have it. Writing it down after the fact makes it all feel very straight forward. In reality I thought I was prepared and quickly realized I wasn’t and it got very chaotic. But that’s game dev so what else is new? :D

I hope that my experiences and solutions can help someone else to avoid these issues.

Add these lines to BuildConfiguration.xml:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <ParallelExecutor>
        <ProcessorCountMultiplier>2</ProcessorCountMultiplier>
        <MemoryPerActionBytes>0</MemoryPerActionBytes>
    </ParallelExecutor>
</Configuration>

The file can be found here:

• Launcher Builds: %AppData%/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml
• Source Builds: UE_5.X/Engine/Saved/UnrealBuildTool/BuildConfiguration.xml

Why is it needed at all?

When compiling each compilation process reserves a specific amount of memory to work with. By default that is 1.5 GB. Depending on how much RAM you have or how many other process are running the build log might show something like this:

Determining max actions to execute in parallel (8 physical cores, 16 logical cores)
  Executing up to 8 processes, one per physical core
  Requested 1.5 GB free memory per action, 4.61 GB available: limiting max parallel actions to 3
Building 267 actions with 3 processes...

In my opinion the allocated amount of memory is very pessimistic. In my use cases the amount used per process stays between 100 and 400 mb. The MemoryPerActionBytes setting can be changed to a different default amount. Setting it to 0 will disable it completely. I’ve never had problems disabling it, but if you run into memory problems consider setting a non-zero value.

This change improves the utilization a lot already:

Determining max actions to execute in parallel (8 physical cores, 16 logical cores)
  Executing up to 8 processes, one per physical core
Building 267 actions with 8 processes...

However note it says 8 physical cores and 16 logical ones. This means some form of hyperthreading is available. The build tool does not take that into account by itself, but you can force it to multiply the number of compilation threads based on processors with the ProcessorCountMultiplier setting. Setting it to 2 in this case gives:

Determining max actions to execute in parallel (8 physical cores, 16 logical cores)
  Requested 2 process count multiplier: limiting max parallel actions to 16
Building 267 actions with 16 processes...

Drawbacks?

Having all cores and all memory go to compilation can make the computer pretty unusable and unresponsive for anything else while it is compiling. I prefer the compilation to take less time though.