Writing code within the framework of a modern game engine can seem like a daunting prospect. Fortunately, Unreal Engine’s visual scripting language Blueprint has lowered the barrier of entry and made it easier than ever to create your own game logic. However, this doesn’t mean it can’t get messy, complicated, or confusing at times. Maintaining your code is important no matter what development environment you’re using.
Keeping your Blueprint graphs neat and tidy is not difficult, but it does require a solid understanding of best practices within the editor, knowledge of the toolset the engine provides, and consistent effort to maintain your code so things don’t get out of hand. Here are the best tips I’ve found for keeping your Blueprints organized:
- Have a style guide (and stick to it!)
- Use a modular design pattern
- Make liberal use of comments
- Take advantage of Unicode symbols
- Assign variable categories
- Master the Alignment tools
- Keep your wires tidy with reroute nodes
- Use fewer nodes to achieve the same goal
- Collapse your graphs into manageable groups
- Use functions for repeated sections of code
- Consider third-party plugins (list included)
By adopting a combination of these techniques your Blueprint graphs will be far more legible (absolutely critical if you’re working with other people) and easily extended as you continue to add functionality to your game.
Before we dive in I thought I might first offer a short preemptive self defense as to why all of this is such a big deal.
Why is so much organization necessary?
We’ve all seen Blueprints from Hell. It’s that special kind of node ‘spaghetti’ that can take hours to unravel. I like to think we’ve all been responsible for this kind of mess at one time or another. I know I have!
A Blueprint graph I made in 2015. It’s functional but…yikes.
The reason we should all be organizing and maintaining our Blueprints so diligently is for both clarity and collaboration.
Messy graphs with no structure and inconsistent style are difficult to read and even more difficult to work with. At the top of some dedicated time to work on your project, if you have to take an additional few minutes to untangle the wires and figure out what you were doing the last time you opened your project, you’re going to end up with hours of lost production time over the course of the game’s lifecycle.
This is especially true if you’re working with other people. No one is going to thank you for wasting their time figuring out your mess.
The following tips are the lessons I have learned and the rules I follow personally when working within Blueprint. It is still something I am figuring out for myself, so where appropriate I will try to explain some of the rules I have abandoned along the way and why I decided they were no longer helpful.
I encourage you to find a system that works for you. Take from this what you find useful, but most importantly talk to your team. Discuss amongst yourselves and decide how you’re going to organize your Blueprints as a group. Otherwise you will likely struggle to enforce it for very long.
When should I organize my graphs?
This might be a contentious question, and my answer may ruffle some feathers. I believe the appropriate time to organize (and sometimes refactor) your graphs is when you’ve finished prototyping a feature or hit a similar minor milestone.
Making your nodes neat as you go is a perfectly acceptable way to work, but if you’re experimenting with functionality, moving chunks of nodes around and trying different configurations, then making all of that presentable on the fly will really slow you down. In the immediate short-term, a graph you’re actively working on will always be a bit messy, that’s just part of the process.
On the other hand it’s very important that once you’ve finished working on a section of code you do your due diligence and make sure it’s legible. You never know when you might be back. Maybe someone else will get there first.
If you’re using source control (and you absolutely should be, even for a solo project), try to avoid committing disorganized or broken Blueprints to your repository. Turn cleaning up and reviewing your work just before you push to source control into a habit. Your teammates will absolutely appreciate the consideration.
#1) Have a style guide (and stick to it!)
A style guide is a document containing detailed instructions on how your Blueprints (amongst other things) should be presented. Depending on its granularity it will dictate how your graphs are structured, how comments work, where nodes are placed, and more.
In many ways this article itself forms part of my own style guide to working within Blueprint Actors, and if you’ve not got a style guide already feel free to start here. If you already have one then have a think about how it compares and take only what you find useful.
Here are some common questions to ask yourself when considering your Blueprint development style. with my personal opinion on each.
Further reading
If you’re looking for a more all-encompassing style guide for working within Unreal, I highly recommend checking out Michael Allar’s comprehensive ue5-style-guide on Github.
For my own projects I use Unreal Directive’s searchable database of naming conventions for common Unreal assets.
Should dependent nodes go alongside or underneath their parent?
This is an easy one, and it really just comes down to personal preference. When arranging your graphs do you put dependent nodes (like variables being plugged into a function) alongside their parent or stacked underneath it?
One option takes up more horizontal space, but (at least to me) is much easier to read. The other is more compact and neat, but all of those S-shaped wires make me a little uncomfortable.
How important is it that my execution line goes strictly from left to right?
Your execution line is the thick white wire which dictates the order in which Blueprint nodes are executed. This one isn’t just about keeping it straight, but rather about the general flow of your logic.
Blueprint is designed to go from left to right, top to bottom, but how much verticality your graphs have is up to you. In general I want to assume that the further to the right I move in the graph, the further along the execution chain I am going. As such, in general I try to avoid Sequence nodes as this usually means doubling back.
The only exception to this rule I allow in my own projects is when I need to split up large chunks of code that need to run sequentially, like updating a character’s state before calculating their movement.
What is my attitude towards long wires?
The Blueprint editor can struggle with accurately representing really long wires and it’ll often draw them incorrectly. Even with reroute nodes (which we’ll get to) long wires are among the main offenders creating the spaghetti we’re trying to avoid.
An alternative to longer wires is to use more nodes. If you’re plugging the same variable into multiple disparate functions in your graph, use multiple ‘gets’ instead. At the end of the day it’s all the same performance-wise. The Blueprint will fetch that value multiple times either way, as it may have changed in the intervening logic.
In the end it comes down to which you’d prefer. Shorter, easier to maintain wires, or fewer nodes.
How far apart do I want my nodes to sit?
Node spacing is an interesting one, and like most of these questions it’s a tradeoff; this time between how much space your code takes up on the graph, and how easy it is to follow.
Cramming nodes together makes for a more difficult to read graph, but because it’s so compact you can work in a smaller space and see more of your code at once.
Spacing your nodes further apart makes it much easier to see the flow of logic when zoomed out, but you’ll be panning the graph a lot more as you work.
#2) Use a modular design pattern
I have found that monolithic architecture within Blueprint (where most of your functionality is stored in one actor) isn’t the greatest idea. This is especially true if your game is in any way more complicated than a project like Tappy Chicken.
Luckily, Unreal provides a lot of tools to help you structure your Blueprints in a modular way so you can reuse functionality and make sure that each graph is only as complex as it needs to be.
Using Blueprint Components is a great way to attach additional logic to your actors. You can create them from within the Content Browser just like any other object, and you can add them to your Blueprint Actors to augment their functionality.
Actor and Scene Components are in the Common Classes menu when you create a new Blueprint.
As a practical example, let’s say you’re making a shooter game. You’ve created an Enemy Blueprint which contains logic for movement, pathfinding, and target selection. Now you’re looking to add variety by giving these characters different weapons.
Instead of making subclasses of your character for each weapon variation, you can instead create a component for each weapon type (or extensions of a more generic ‘weapon’ class) and mix and match them, even at runtime. This lets your characters share as much functionality as possible and retains a single source of truth for the behavior of their weapons.
If you decide to add more weapons or swap them around you can just reassign components. It’s an intuitive and effective way to structure your code.
This kind of modular design does take a deal of forethought, and if you’re caught mid-development and are considering refactoring your code I don’t envy your position. That said, its definitely worth considering adding modularity to your architecture wherever you can. It will save you a lot of time in the long run.
One Blueprint to Rule Them All isn’t helping anyone if it takes over 30 seconds to save and only one person can have it open at a time.
#3) Make liberal use of comments
I can’t overstate the importance of commenting your code, and it’s not just something you do for other people. Good documentation will help you in 3 months time when you come back to make tweaks to your graph and you’ve forgotten what in the world you were thinking.
Leaving useful comments in your graphs will save you a lot of time, money, and emotional energy.
Node comments
There are two types of comment you can make in Blueprint. The first is adding notes to individual nodes, which you can do by right clicking them. These tags can scale with the node or be pinned so they’re always legible.
I tend to use this type of comment as a way to flag nodes that need particular attention. I use them to mark ‘magic numbers’ that need to be addressed and to make note of specific nodes that I think might be causing issues.
Comment boxes
You can create a comment box by selecting ‘Add Comment to Selection’ from the Actions menu, or by pressing the shortcut C. Comment boxes can be moved around just like any other node and they have a few options for customization.
You can change their size by dragging out from their borders, and by selecting them you can alter their tint, opacity, and whether or not nodes within their bounds are carried with them or left behind when the box is moved.
Comment boxes are perfect for marking down the purpose of a group of nodes. I use them in any graph where functionality can be easily broken up into discrete actions. I tend not to use comment boxes in smaller graphs that only execute a single task.
Heads up
If you have nodes selected when you create a Comment box it will automatically be sized to encompass them. Unfortunately when done this way the box rarely ends up sitting on grid. What’s worse, if you move that box at all it will snap back to the grid, and in the process offset all of the nodes within.
What a nightmare!
These days I prefer to keep all of my comment boxes the same color and rely on their description to define the purpose of the nodes within. I just think my graphs are easier to work with that way. That’s just me though, and I change my mind all the time. I encourage you to explore your options and find a color system that works for you.
Just remember to keep it consistent.
At one point I was using yellow to indicate pure calculation to find a value, orange to indicate when a value was being set, and red for more complicated functionality. Sometimes I just made it rainbow colored for fun.
I don’t have time for these kinds of shenanigans anymore!
A devil’s advocate opinion on comments
A colleague once told me that if a Blueprint graph was made properly it’s purpose should be self-evident and comments wouldn’t be necessary. His contention was that you only need to comment your code if it’s not well made, because good graphs don’t need explaining.
It made for a lively discussion, to say the least.
Edit, June 2023: It’s been some time since I wrote this article, and these days I tend to agree. Good code is most often self-explanatory, but comments don’t hurt.
Edit, April 2024: I have swung back around on this. Comments are incredibly useful. Use them!
#4) Take advantage of Unicode symbols
On Windows you can insert Unicode symbols into your Unreal Engine comments by pressing period (.) while holding the Windows key. I use these liberally to mark special statuses within my Blueprint comments.
They’re a great way quickly convey information, as long as your team can agree on their meanings!
In my Shooter Sandbox project I use them to indicate the network status of my code. The 🖥️ symbol means the code within that comment will run on the server, whereas the 👥 or 👤 symbols indicate code running on all client machines, or just the owning client respectively.
I might be the only one who uses symbols in this way, but I have found the technique invaluable. It’s the only way I was able to get my head around the flow of my multiplayer graphs. I don’t know what I’d do without them!
#5) Assign variable categories
As your Blueprints get bigger and more complex you’re going to be wrangling a lot of variables. It’s important to have a standardized manner of sorting them into categories or working with them will become increasingly difficult.
The category setting can be found in your variables details panel, but what you might not know is that you can also use this symbol | (sometimes called a pipe) to create subcategories. For example, the setting Character|Locomotion will create a Locomotion subcategory under the Character heading.
Have a think about how you want to organize your variables. I tend to keep exposed parameters in a separate category called ‘Config’. It just makes them easier to find when I set up instances in my levels.
#6) Master the Alignment tools
The Alignment section of the menu can be found by right clicking any node in your Blueprint editor, and it has several options for automating node placement. These are mostly self explanatory and will affect any nodes you have currently selected.
Learning the shortcuts to these tools can seriously speed up your workflow, and it’s very much worth taking the time to practice them. Just remember that the align tools can move your nodes off-grid. This can make some people (myself included) very sad.
#7) Keep your wires tidy with reroute nodes
You can double-click anywhere on a wire to create a reroute node. These act as both an additional handle that you can use to reposition the wire, and a way to branch its single output into multiple where possible.
The reroute node is your friend. Use them liberally to increase the legibility of your code, prevent wires overlapping with nodes, and to overall reduce the amount of nodes required in your graph.
Reroutes are also particularly useful for loops, and anywhere else where your code needs to double back on itself.
#8) Use fewer nodes to achieve the same goal
In general, the fewer nodes you need to use, the better. It keeps your graphs simple and makes them easier to maintain. Here are a few quick tips to help you keep the number of nodes to a workable minimum.
Split your structs
A struct is a collection of values stored as a single variable for ease of use. Vectors and rotators are the most common structs you’re likely to work with, but Unreal comes packaged with a lot of them and you can make your own via the Content Browser under Add > Blueprint > Structure.
Any struct can be broken into its component variables using a Break node, but you can also right click on any struct’s input or output pin and select ‘Split’ to get the same result without the need for that extra node.
If you need to merge them back in again just right click and select ‘Recombine’.
For math-heavy graphs this can significantly cut down on the number of nodes needed to get the job done.
Select nodes
The Select node is incredibly versatile and can used to elegantly reduce the amount of nodes in your graph. The way it works is simple: It will select a value from a list of user-defined variables based on a condition. This condition can take the form of an enumeration, boolean, byte, or integer.
Keep in mind that this isn’t the same as a Switch node, which will execute just one path based on your input. The Select node is a pure function, loading all of its inputs to determine the outcome. This has the potential to have a much higher performance cost, particularly if your select node is at the end of a long chain of logic. A single Select node might require that chain to be run multiple times unnecessarily.
Using a switch node.
Same functionality, fewer nodes.
Click any of the images for a higher resolution version.
That said, the select node doesn’t take up much space in your graph and won’t split your execution chain. Use it wisely!
Validated Get nodes
If you needed to check a variable before fetching its value there was a time where your only choice was to pass it through a ‘Is Valid’ function.
These days you can right click on your variable reference and select ‘Convert to Validated Get’ to do the same thing but all in the one node. Much cleaner!
#9) Collapse your graphs into manageable groups
Useful for compartmentalizing chunks of logic for different purposes within the same Blueprint, you can right click and ‘Collapse’ a selection of nodes into its own sub-graph. These Collapsed Graph nodes can have their own input, output, and execution pins.
Although you can collapse any collection of nodes (including those within Functions) my personal preference is to stay only one layer deep. I find it’s easier to make my way around. Don’t let that stop you from creating graphs within graphs within graphs, though. Whatever works for you.
#10) Use functions for repeated actions
As a general rule you shouldn’t copy/paste your code. In Blueprint terms this means if you’ve got sections of your graph made up of the same sequence of nodes repeated over and over, it’s time to turn them into a function.
Functions can be thought of as repeatable sections of logic with one execution input and output. They have their own graph and are entirely self contained with their own local environment. If you find yourself using the same sequence of nodes more than once, consider making them a Function.
Some examples of different types of functions being used together to reset and then save an actor’s position.
For more information on working with Functions have a look at this page in the documentation.
Blueprint Function Libraries
This is just a quick side note as best practices for working with Functions is a bit of a rabbit hole, but if you’re finding yourself using a lot of similar functions across many Blueprints in your project you should consider using a Blueprint Function Library.
You can make as many as you like, and they provide a way to store generic functions that any of the Blueprints in your project can call. It’s a good way of reducing clutter within your individual actors.
#11) Consider third-party plugins
The Unreal Engine Marketplace has an abundance of productivity-centered plugins which can fundamentally change your workflow. The following are some of these that I have worked with personally and found either useful or interesting. Check them out if they seem helpful, but remember that by installing a plugin you become increasingly reliant on a third-party for regular updates and support. Make sure the reward is worth the risk.
Electronic Nodes
Electronic Nodes will change the shape of the wiring in both your Blueprint and Material editors to resemble a circuit board, keeping lines as straight as possible and only using 90 and 45 degree angles.
This is probably one of the most ‘love it or hate it’ plugins I have ever worked with. It can make some graphs look amazingly clean and easy to read, but not mine. I found that to get the most out of it you need to have a lot wider node spacing than you would normally with the default wire implementation.
I worked with Electronic Nodes for about 6 months before switching back to default. It’s not for me, but others I’ve spoken to swear by it so maybe it’s something I’m missing. Try it out for yourself!
Linter
A free plugin by Michael Allar, Linter acts as a watchdog for style guide compliance. Very configurable, you can tell Linter what you want it to look out for: from irregular naming and missing files, to variable naming conventions and function etiquette, and when you run the program it will scan your entire project and compile a report on the things it’s found that don’t match style.
Linter won’t change your files for you (which in my opinion is great news as I don’t like to trust third-party automation), but it will let you know where you can improve, based on what you’ve told the system is important to your project.
I’ve used Linter since its first iteration and I’ve found it incredibly helpful. One of the best plugins on the marketplace.
Final thoughts
That’s it! Thanks a lot for reading what is essentially some guy on the internet’s opinion of how you should organize your game project. I appreciate your time and consideration, and I hope to come back to update this post as my own understanding of best Blueprint practices changes over time.
How you choose to organize your projects can be a really personal decision. I hope you’ve found these tips useful.
