Blueprint Functions: What you need to know

From the basics to best practices, this is what you need to know about Blueprint Functions

Blueprint Functions: What you need to know

Functions are essential when it comes to both Unreal Engine development and programming in general. They allow the reuse of code, improve overall maintainability and allow scalability by being callable from other entities – such as blueprints.

In this article, I will be teaching you everything you need to know about Unreal Engine blueprint functions.

This is one article of many that go over the fundamental anatomy of an Unreal Engine blueprint. Make sure you subscribe to be informed when a new article becomes available.
Join the community

The basics

Understanding the basics of what functions are goes a long way in being better prepared to create and utilize functions properly and efficiently. Without this fundamental knowledge, it's very easy to miss out on opportunities to simplify Unreal Engine development.

What is a function?

A function is an isolated block of code that is executed when called. This block of code can take parameters as an input, process those parameters, and return a result.

As an important note – you can have as many, or as few, inputs and return parameters as needed. That said, they are not required.

Why should I use functions?

There are many reasons why a function should be used –

Organization

Functions are a great way to compartmentalize code into smaller chunks of logic that are easier to handle. These smaller chunks can reduce the overall complexity of the blueprint.

Reusability

Once a function has been established, it can be reused as many times as needed. This heavily cuts down on the need to copy and paste the same exact code in multiple locations.

Be forward-thinking and lazy. Write once – reuse.

Extensibility

Adjustments to functions will automatically propagate everywhere the function is used. Copy and pasted code do not.

How do I create a function?

Functions can be created in any type of blueprint and in Blueprint Function Libraries.

To create a function inside of a blueprint, you can utilize the following methods –

Primary Method

This is the primary and most common method to create functions for blueprints.

  1. Locate the My Blueprint Panel located to the left of the blueprint window
  2. Under the Functions section, click the plus button

Conversion Method

You can convert a selection of nodes into a blueprint.

  1. Select the desired nodes
  2. Right-click to open the action menu
  3. Click on Convert to Function in the action menu

Override Method

Functions that have been established in the blueprints parent class can be overridden.

  1. Locate the My Blueprint Panel located to the left of the blueprint window
  2. Hover over the Functions section
  3. Click on the Override combo box
  4. Select the desired function to override

Convert Event to Function Method

Events can be converted to functions and vice-versa.

  1. Right-click on the desired event
  2. Click on Convert Event to Function in the action menu

How do I call a function?

Functions can be called via a multitude of methods –

For Impure Functions – make sure to hook up the function's execution input pin otherwise the function will not execute.

Drag and drop from Functions section

Under the My Blueprint Functions section, simply hold left-click on any of the functions available and drag into the graph.

Call from Action Menu

From within a blueprint, simply right-click to open the Action Menu. Utilize its search field to find the desired function.

Call from Node Context

By holding left-click on a node property and dragging it anywhere in the graph, the Action Menu will open. The options available will be based on the context of the property.

Bonus: Call from Timers

Functions can be called via the Set Timer by Function Name node. Each time the timer reaches the end of the given time, the function will be executed.

Do note that this method only allows for functions without input and output parameters.

The anatomy of a function

In this section, I will be going over every aspect of the function in detail.

The Details Panel

The details panel for a function is where the function's properties are set. This is often one of the first areas of configuration when creating a function.

This panel hosts multiple different elements –  

Name

This is where the name of the function will be declared.

It's critically important that the name of the function clearly states the functions intent – thus having a verb as a prefix.

Examples

Here are some good and bad examples to provide a better understanding on how to properly name functions –

Good Example ✔ Bad Example ✘
IsVisible Visible
GetStamina Stamina
SetMaxHealth MaxHealth
GetInventory Inventory
ReceiveMessage GotMessage
Attack Atk
GetColor Color
GetCachedVehicleManager Function_0

Description

The description will explain what the function does.

It's critically important that this field gets filled out and that it clearly states what the function does along with detailing each input and output variable.

Adding a description to a variable can be done via – by going to the next line (SHIFT + ENTER) and by typing in the following – @param VariableName The description of the variable

Where will the description of the function be viewable from?

  • Hovering the mouse over the functions node in the blueprints graph
  • Hovering the mouse over the function in the blueprints action menu
  • Hovering the mouse over the function in the functions section in the blueprints My Blueprint details panel
  • Any automatic documentation generators

Category

When set, this will change where the function will be located in both the Actions Menu and in the Functions category in the blueprints My Blueprint Panel.

It's ideal to set a category rather than leave it to the default as it will allow developers to more easily find the function.

Nested categories can be accomplished by placing a vertical bar ( | ) in between the two category names.

Keywords

Setting keyboards help to quickly find a function when searching for it with the Action Menu.

Each entry should be separated by a comma.

Compact Node Title

The function node will change to a compact form when text is added to this field.

Access Specifiers

Access specifiers define what can access the function.

By default, this setting is set to public, allowing for any object to access it.

The access specifier option can be found in the Details Panel when the function is selected in the My Blueprint Panel.

Public

The public access specifier allows the function to be called from any other object. This is the default specifier.

Use this specifier if you want the function to be freely accessible.

Protected

The protected access specifier locks the function to only be accessible from within the declared blueprint or any child blueprints.

Use this specifier if you want the function to only be usable from within the declared blueprint and any derived children blueprints.

Private

The private access specifier locks the function to be only accessible from within the declared blueprint.

Use this specifier if you only want the function to be usable from within the declared blueprint and NOT by anything else.

Pure

When enabled, the function will become a pure function. Pure functions cannot alter data and the execution pins are removed.

Pure functions should never modify data, or call any function that can modify data. They are purely for getting or calculating data.

Pure Vs. Impure

Pure Functions are –

  • used as getter/helper functions to return data via the data pins
  • executed when data is requested
  • called one time for each node it's connected to

Impure Functions are –

  • used as setter/modifier functions to mutate data
  • executed when the blueprint's execution flow reaches the impure function's execution pin

Call In Editor

When enabled, a button with the functions name will be added to the blueprint's details panel. When this button is pressed, the function is called.

Notes

  • The button will not appear if the function has any input or output variables
  • Will be placed under the designated category in the blueprints details pa
  • Will ignore category nesting

Const

When enabled, the function cannot modify any member variables of the blueprint.

Deprecated

Marks the function as obsolete and produces a compiler warning indicating that the function should be either removed or replaced.

Make sure to fill out the deprecation message.

Deprecation Message

The message that will be included with the compiler warning.

It is ideal to state what function is replacing the deprecated function. This helps other developers, and future you.

X is no longer being used. Please replace with Y.

Inputs

The parameters to bring into the function.

Default Value

The default value to use for that variable when the pin isn't used or hasn't been changed.

Note that this option is only available for select variables.

To reset a value back to its default, right-click on the variable on the function node and click on Reset to Default Value

Pass-by-Reference

Pass the variable itself rather than a copy, allowing for any modifications to it to reflect back on the origin variable.

Pass-by-Reference variables are easily identified by their diamond-shaped data pins.

Outputs

The resulting parameters.

Graph

This is where the functionality of the function is set up.

Return Node

The Return Node marks the end of the function. This will be where the output variables will be passed into.

Important Notes
- The function ends when the return node is executed
- Functions without output variables will not have the Return node
- The Return Node can be manually added via searching Return Node from within the Action Menu

Local Variables

These are essentially variables that are only relevant during the function's execution. Once the function has finished executing, the variable is thrown away.

Local variables are only found from within the graph of the function.

Function Overrides

Functions declared in parent blueprints that have their access specifiers set to either Public or Protected can be overridden.

Overriding functions are a great way to either expand upon the parent's function itself or to completely override it.

Parent Node

When a function is overridden, a Parent Node will be present. This Parent Node is what executes the parent functions logic.

If the desire is to fully override the function without the parent function executing, simply remove the Parent Node.


Join the community

Best Practices

Getter & Setter Functions

It's ideal to create getter and setter functions for variables that need to be accessed outside of the blueprint. This allows for a greater degree of flexibility and simplifies the debugging process when things go wrong.

Use proper naming conventions

Function names, inputs, outputs, and local variables should clearly express their intent.

For example, setter functions should start with Set and getter functions should start with Get. Or if the getter function is asking for a boolean state, it should start with Is.

Good Example ✔ Bad Example ✘
IsVisible Visible
GetStamina Stamina
SetMaxHealth MaxHealth
GetInventory Inventory
ReceiveMessage GotMessage
Attack Atk
GetColor Color
GetCachedVehicleManager Function_0

Provide function descriptions

While this goes for everything – always add a description to the functions you create and manage. These are immensely helpful when you're utilizing them and debugging them many weeks down the line.

Make sure the description clearly explains what the function does.

Input/output descriptions

When filling out the description of the function, make sure to add descriptions for the input and output variables.

This can be done by going to the next line (SHIFT + ENTER) and by typing in the following – @param VariableName The description of the variable

Optional – Append [in] or [out] to @param to clarify the parameter as an input or an output.

Set categories

It's ideal to organize functions by categories. This cleans up the function hierarchy along with helping you and anyone else easily find the function.

Practices to avoid

One-off functions

Do not create functions that are only ever used once inside of the owning blueprint. More prudent here would be to use a collapsed node instead.

Convert and forget

Do not convert a selection of nodes into a function and not clean it up. Most of the time, there are going to be extra input/output variables that need to be culled, and nodes that need to be re-arranged post-conversion.

Spaghetti

Do not leave spaghetti code – clean up those functions. Functions should be easily navigatable when you come back to them in a year's time.

Tips & Tricks

Input variables nodes

While inside of the function graph, input variables can be accessed directly as variable nodes.

Utilize these to remove those long wires and clean up your function graphs.

Split struct parameters

Parameters that have multiple internal values – suck as a vector or structure – can be split in place. Simply right-click on the property and click Split Struct Pin.

Parameters can be re-combined by right-clicking on one of the split parameters and clicking on Recombine Struct Pin.

Frequently asked questions

These are some of the questions I get frequently asked.

What are the differences between Functions, Macros, and Custom Events?

While they share similar characteristics, there are stark differences between a function, a macro, and a custom event.

Here are the primary differences –

Feature Function Macro Custom Event
Input Parameters Yes Yes Yes
Output Parameters Yes Yes No
Execution Paths One Many One
Callable by other blueprints Yes No Yes
Latent Nodes (I.E: Delay) No Yes Yes
Replicatable No No Yes
Forcibly End Execution Yes (Return Node) No No

Additional Resources

Looking for more information about this subject? Check out these additional resources!

Functions
Node graphs that can be executed, or called, from another graph.
Creating Functions
Create a Function which displays text when a key is pressed.
Introduction to Blueprints
If you are just getting started with Blueprints, this provides a high-level overview of what they are and what they can do.
Blueprint Visual Scripting
Overview of using the Blueprint visual scripting system for gameplay.
WTF Is? Blueprint Function in Unreal Engine 4 ( UE4 )
What is a Function in a Blueprint in Unreal Engine 4Source Files: https://github.com/MWadstein/wtf-hdi-files
Did I miss anything?

If you have found that there are missing details or incorrect information – please let me know via – Twitter or the Feedback channel in the Unreal Directive Discord server.

Please provide a detailed description of the issue along with providing resources and/or examples.

Change Log

03 January 2022

  • Added clarification on what type of functions Timers allow

01 January 2022

  • Expanded information regarding Function Overrides
Become a Patreon!