Recently I made some python scripts that work in the Unreal Engine editor. I’ve been using them in my own projects to help find potential problems and possible optimisations. I thought I’d put them out for free so everyone can use them. If you want to see when I release updates or new tools give me a follow on Twitter.
I’ll split this blog post into three sections that follow the above video:
- How to set up
- Quick functionality run-through
These scripts don't actually edit anything; they simply log things that could be worth you looking into. The idea is that we can catch smaller issues that aren't obvious and bring up the overall sturdy-ness and quality of our games. I tied all of my scripts together into a UI (Editor Utility Widget) to make them easier to use. Below you can see me running the script: Log Static Meshes With No Collision. When complete it kicks out a notepad file summarising its findings.
In this case, we can see that there are 18 static meshes in the project which have no collision primitives setup. The first entry in the list is an asset called Floor_400x400. Generally, floors should have collision, so straight away we have found a potential problem, and that's the gist of how these scripts work. It shows you potential things, then it's down to you to decide how to act on them.
HOW TO SET UP
At the time of writing, my scripts will probably only work in 4.26 but I’ll be updating to other engine versions in the near future. It’s really easy to set up. In my example, I’m adding it to a new project but you could add it directly to your own project as well. First off we need to turn on some project plugins so head up to Edit and Plugins
Then head down to the Scripting category on the left-hand side. We need to turn on two separate plugins. The first is the Python Editor Script Plugin. This is what allows the editor to run python. The second is called Editor Scripting Utilities, which has some helper functions that the scripts need.
When you turn each of these scripts on they will kick up a warning. This is basically telling you that it's an Early Access beta version. Click Yes for both.
Once you enable the plugins you will need to Restart your editor. Use the button in the bottom right of the project plugin window that you have currently open. It should look like the image below.
Next up we need to get the actual scripts. So head on over to https://github.com/ and in the top right search for cbgamedev
This brings up just the one repository atm, which is called: CB-Game-Developer/UnrealEngine-LogOptimisationsHelperScripts. Click into that.
Then we need to click on the Code button with the little drop down on it and then click on Download ZIP.
Once the file has been downloaded open up the zip and navigate down into the folders till you see the Python folder. Right-click on the folder and hit copy.
Then go back to your project. Right-click on any asset in your project and click on Show In Explorer.
This will open up your project folder. We need to navigate up to your project's content folder. Then Right-Click, Paste the recently copied Python folder into here (This needs to be in this specific location for it to work).
Now if we go back to our project and look we will see the python folder is now visible in the editor. Navigate to it and look for the EUW_Optimise_Scripts_4_26 asset.
EUW_Optimise_Scripts_4_26 is an Engine Utility Widget. Put simply, it's a UI that can be run in editor. Right-click on it and then select the top option from the menu called Run Editor Utility Widget.
And that's it, everything is set up and the scripts are good to run by pressing the different buttons.
QUICK FUNCTIONALITY RUN-THROUGH
So I’ll quickly run through the different scripts to give you an idea of what they do and how they might be useful to you.
Log Static Meshes with No Collision: This is going to log any static meshes that have no collision primitives setup (You might get some false positives with assets using custom collision or complex collision, but those are probably worth looking at for optimisations anyway). I find this useful for quickly finding assets that should have collision for example floors, walls and other key assets.
Log Static Meshes With No LODs: This will return a list of static meshes which have no LODs set up at all. Generally, everything in your game should have at least a couple of LODs, so this can be a good way to see some optimisation opportunities.
Log Static Meshes With X or More Materials: This can help you find static meshes which are greedy because they have a large number of material IDs. It returns a list of static meshes with material IDs that number more than the value you set on the button. For example, all static meshes that have 3 or more materials. You can change the amount to check against by moving the slider in the lower half of the button. Having lots of separate materials IDs is sometimes necessary on an asset but if you can reduce the number and keep the quality you are after then it will be more optimised.
Log Static Meshes With X or More UV Channels: This script can help you find static meshes which have a larger number of UV channels and are worth looking at. Generally, the fewer UV channels you use the more optimised your asset will be. In most cases, you will have 1 or 2. The first is your assets texture UVs and the second is lightmap UVs if you are using baked lighting. So if we search for 3 or more UV channels we can identify some potential optimisation opportunities. Just remember some assets may be using those extra channels in their materials. So always double-check before you consider removing them. You can change the amount to check against by moving the slider in the lower half of the button.
Log Unused Project Assets: This script goes through your project and logs any assets which have zero references e.g. aren't being used in any levels or by any other assets. This script is a good example of why these scripts only log and do not edit. You might find that you have a lot of assets that aren't currently being used but that doesn't mean you want to automatically delete them. That’s why I chose to log and let you decide what to do with the information.
Log Redirects: If you’re using source control and moving assets around you can create a bunch of redirectors. It’s good practice to fix-up these. This is a nice quick way of identifying any around your entire project and worth running every so often.
Log Skeletal Meshes With No LODs: This script is used to find any skeletal meshes that have no LODs at all. Similar to the static meshes, really everything should have a couple of LODs to keep your project optimised and this is a great way to find those problem assets. Also worth noting that this script will only work in 4.26 onward as it requires some Unreal side fixes/added functionality.
Log Skeletal Meshes Missing Physics Assets: This probably isn’t something you will encounter a lot but we can use this script to find skeletal meshes that do not have any physics assets plugged in. Not having a physics asset can cause a range of problems including; ragdoll issues, shadow problems as well as some potential visibility issues.
Log Skeletal Meshes With X Or More Materials: This script allows us to list skeletal meshes which have X or more material IDs. Similar to the static mesh version of this script, large amounts of material IDs can add extra performance costs. So where possible we want to keep the amount down to stay optimised. You can change the amount to check against by moving the slider in the lower half of the button.
Log Sound Cues Missing Attenuation: This script returns a list of all sound cues which have no attenuation asset plugged in or have no attenuation override turned on. I’ve found this is an important one for finding potential bugs, especially if you are making a multiplayer game. If you use the standard play sound function in Unreal and the sound you selected has no attenuation setup, that sound will play for everyone in the entire game. I’ve made that mistake before, not great!
Log Sound Cues Missing Sound Class: This script is going to return a list of all sound cues that have no concurrency asset plugged in or have no concurrency override set. This is more of an optimisation check as it’s good to have concurrency limits in place in your sounds. You can set concurrency as local (per actor) or global and is definitely something to look into if you haven’t heard about it before.
Log Sound Cues Missing Concurrency: This script will return a list of all the sound cues that have no sound class asset plugged in or sound cues that are using the default sound class from the engine. Firstly, not having a sounds class plugged in means that your sound cant be considered when affecting specific audio types e.g. turning down only the UI volume or only the music. Then secondly, it’s good practice where possible to use your own assets rather than pulling from engine content (You can just duplicate the engine asset into your project). A good reason to do this is because when you cook your project you can set it to not include engine content, which makes for a smaller quicker cook, but you can’t do this if you are using engine content as it will cause errors in-game.
Log Non-Power Of Two Textures: This script generates a list of any textures that aren't using a size which is a power of 2 e.g. 32, 64, 128 etc. If a texture isn't a power of 2 then it causes issues with compression and you can’t use mipmaps etc. So it's worth looking into any textures in this list to see if you can get some easy win optimisations.
Log Textures With X Size: This script will create a list of all textures that are of a certain size. You can use the slider at the bottom of the button to increase/decrease the size you are looking for. I have been mainly using this searching for larger texture sizes e.g. 512 upwards. Then looking through the list to see if there are textures that do not need to be as high. For example, a smaller asset that is never seen up close probably doesn’t need to have a 2048 texture size. You can use this to help fine-tune and optimise your project. A good general rule of thumb is that you want to keep your texture sizes as low as possible without sacrificing visual fidelity.
Log Materials Using Translucency: This will generate a list of materials using Blend Mode::Translucent. Translucency tends to be expensive and so the idea behind this was to be able to help quickly identify materials that we could optimise. Looking through the list to see if there is anything that doesn't need to be translucent or could potentially be adjusted to instead use Blend Mode::Masked.
Log Materials Using Two Sided: This will log materials that are set as two-sided. This is again an optimising check, as two side materials are more expensive. This is an interesting one to look through, as you might find for example that the bushes in your game recently got changed to be camera facing so now they do not need two-sided checked anymore. Potential for a few easy optimisation wins here.
Log Materials Missing Phys Mats: This script will look through your project’s materials and check if they do not have any physical materials plugged in. I’ve found this one super useful, as it’s really easy to miss or forget to do when you’re making a new material/material instance. This is useful to get fixed because if for example, you’re doing footsteps or bullet impact sounds based on physical materials, without a phys mat plugged in you would get no sound or the default material sound, rather than getting the full experience you want to give the player.
I made these scripts for my own projects to help find problems I didn't know existed as well as potential opportunities for optimisations. The idea is that we can catch smaller issues that aren't obvious and bring up the overall sturdy-ness and quality of our games. If you want to see when I release updates or new tools give me a follow on Twitter.
Remember these scripts are free so give them a go and I hope you find them useful. If you have any ideas for extra functionality which might be useful, give me a shout, and maybe I can add it to the tool!
Also if you are into Unreal Engine, you might find my Quick Dev Tips useful. It's a series of quick bite-sized game development tips and tricks videos, focused around UE4 / UE5.