Tech Art Bits: Extending Unreal Editor with custom menus using Python: Part 2

Continuing on from my first post on the subject, here we will dive into properly expanding upon the theme of hooking custom python-based menus into the various menus and toolbars that Unreal has to offer. For the sake of example, I will limit myself to containing this to just the Level Editor Toolbar, but I will write another post on how to set your menus up (almost) anywhere in the Unreal Editor Interface.

Now that we've got a menu, we can start expanding it! In this example we're going to be building a custom menu using the ToolMenuEntryScript class, which allows developers to implement overrides for various functions it contains, including the execute() function, which allows one to implement multi-line (much more complex) functionality and tie it to a menu entry. 

This is a surprisingly undocumented feature of Unreal Engine, and it is very difficult to research without diving into C++ yourself, so I will be breaking things down here.

First, let's clean up our code a little bit! I've taken the libery to create a Pycharm project that includes a mapping to my Content folder, and put my Python code directly into my Unreal Content folder.

No need to pay attention to the folder structure yet - we'll get to that later.

The Menu Code

I've taken the liberty to break things up a little so we can actually distinguish between our different bits of code. First, there's a menu setup code, which I've separated out into the parts that set up and create the menu, and the part that registers the custom entry we're making.

Ok, note how we're doing some relative imports here - this is because from this point, we're working with a Python package, which we'll later be using in our init_unreal.py script. This is important, as relative imports (imports like from .constants import tool_menus) will not work in a normal script that you just run from the command line.

The Entry Class

The keen-eyed among you will have noticed as well that this code already includes an import of our custom menu entry script. Let's build that next;

This is a fairly straightforward example, you can override all kinds of methods in this class, with official documentation being accessible here: https://docs.unrealengine.com/4.26/en-US/PythonAPI/class/ToolMenuEntryScript.html#unreal.ToolMenuEntryScript

What's nice about this way of creating menu entries, rather than the more documented way of adding one-liner buttons that import larger functions, is that some of the boilerplate can live on the menu entry itself. This sounds bad, but it actually allows the developer to attach more behaviour to the entry, making it smarter and more dynamic. This is rarely a bad thing in and of itself.

Auto-registering the menu on unreal startup

This is where things get really interesting; if you've followed along so far, you know we have not addressed one part; the init_unreal.py file you might have noticed.

As documented in the official docs on the subject, Unreal automatically runs any init_unreal.py file it detects in a directory it's told about.

You can add this directory to your project settings through the project settings UI:

as for the contents of the file itself, that part is fairly straightforward:

As you can see, now when I start my Unreal Project, I get my custom menu, and when I press it, the console prints out Hello World!

 

That's about it for this tutorial, I hope this will prove useful to you!