Blueprint Class¶

To Do.

Creating a Blueprint Class¶

In your Content Browser , press the Add button and select . You will then be prompted to pick a parent, a C++ Class (extending UObject) or another Blueprint Class that your new class will inherit from.

Pick Parent Class

You can either choose one of the options listed above or open up All Classes to search for a specific class. For more information on prominent base classes, see the API Reference.

Blueprint Class Editor¶

Once you've created a new Blueprint Class, you'll be taken to the Blueprint Class Editor to begin editing. The editor has several key panels:

Event Graph: The main workspace for event-driven programming in Blueprints, with support for async functionality.
Functions: Your standard instance methods, complete with support for inputs, outputs, and local variables.
Macros: Think C++ macros, but more sophisticated—parameterized node groups to encapsulate repetitive logic.
Variables: Where you declare and manage instance properties, which can be organized into nested categories.
Event Dispatchers: A powerful tool in event-driven programming, enabling Blueprints to reroute and broadcast events.
Class Settings: Adjust global attributes of the class, such as documentation, inheritance, interface, etc.

Note

The Blueprint Class Editor can look widely different depending on the parent class you've chosen. There may be different panels, nodes, and settings. This manual will cover the common elements of Blueprint classes. Special features of prominent base classes are covered in the API Reference.

Event Graph¶

The Event Graph is where the magic happens! Here, you can script the behavior of your class in response to events—special instance methods often triggered by the outside world. The Event Graph of a new Blueprint will contain an entry node for each event declared in the parent class. For example, if you had chosen Actor as the parent class, the Event Graph would look something like this:

Actor Event Graph

By drawing out an outward execution pin ( Output Execution Pin ) from a node, the Actions Menu will show up, which allows you to add new nodes to the graph. These nodes represent calls to functions that are defined in C++ or other Blueprints. To find a specific node, you can either navigate the categories or use the search bar at the top. To learn more about the available nodes, see the API Reference.

You can also use the Right Button anywhere on the graph to access the Actions Menu and pick a node. You can then wire up the nodes by dragging from and onto the execution pins. You also need to wire up the data pins, which represent the flow of data between nodes. With the right level of abstraction, the results can be quite intuitive:

Not all available events are shown on the Event Graph by default. Inherited events that aren't already on the Event Graph can be found under the Override menu.

Flow Control¶

Blueprints support a variety of flow control nodes, found under Utility › Flow Control in the menu.

Branch

Branch Node

Text goes here.

Latent Actions¶

Blueprints support latent actions, asynchronous procedures that can be executed over multiple frames. Following are some of the most frequently used latent actions:

Delay

Delay Node

Text goes here.

Custom Events¶

To define a custom event, you need to select Add Custom Event... from the Actions Menu. This will create a new entry node for the event on the Event Graph. You can set a name for the event and press Enter to confirm. You can always rename the event by selecting it and pressing F2.

My Custom Event

The event can then be triggered by calling it from another event or function. To do this, you need to look up the event in the Actions Menu:

Calling "MyCustomEvent"

Subclasses can override custom events, just like they can override inherited events.

Organization¶

The term "spaghetti code" could not be more fitting for a messy Blueprint graph. To keep things organized, ...

Comments¶

Functions¶

The Functions panel lists all the functions declared in the current class, along with any functions you've overridden from the parent class. By pressing the button, you can define a new method. This will immediately take you to a dedicated graph with an entry node for the function.

Entry Node

You can then drag the function onto any graph to call it. It will also be available in the Actions Menu:

Calling "MyMethod"

Scripting a function is just like scripting an event graph, but with a few key differences:

Functions have their own scope. This means that they can declare local variables.
Functions are expected to execute and return immediately. They cannot use latent actions.

The graph will not contain an exit node by default, but you can add it by selecting Add Return Node from the Actions Menu. You can add multiple return nodes to exit the function at different points.

Exit Node

If you select either node, or select the function itself from the Functions panel, the Details panel will list out the function's settings, along with its inputs, and outputs.

Note

Unlike C++ functions, Blueprint functions do not support overloading.

Inputs & Outputs¶

Blueprint functions can have any number of input and output arguments. You can press the button to add a new argument and to remove it. Inputs and outputs can be of any type, such as primitives, and object references. Fore more info, see Variable Types.

In addition to type and name, inputs arguments support a couple more settings:

Input Settings

Default Value: The value that will be used if the input is not connected. This setting is only available for primitives and enumerations.
Pass-by-Reference: Whether the input should be passed by reference or by copy (default behavior). This setting is only useful when you need to mutate the input variable inside your function. Moreover, you can check Const to prevent the input argument from being modified. Passed-by-reference inputs are distinguished by a diamond icon ().

Note

When naming your output arguments, you may want to use the term ReturnValue for the primary output. Some features in the engine expect this name to be used for at least one output argument.

Local Variables¶

You'll notice that a panel named Local Variables shows up when you open a function's graph. This panel is similar to the Variables panel, but the scope is limited to the function.

Local Variables Panel

Overriding Functions¶

By hovering over the Functions panel, a dropdown menu can be accessed that lists (public and protected) functions (or events) declared in the parent. You can override any of these functions by selecting them from the list.

Override

When overriding a function (or event), you can call the parent's implementation at any point by right-clicking on the entry node and selecting Add Call to Parent Function.

Add Call to Parent Function

Function Settings¶

The following settings are accessible in the Details panel when a function is selected:

Description

Used to provide a description of the function that will be displayed in the editor when the function is hovered over.

Static Functions¶

Blueprints do not support static methods, i.e., methods without a Target (=this in C++). Instead, you can create a Blueprint Function Library to group related static functions together. See the API Reference for more info.

Macros¶

Macros can be used to group a set of nodes for reusable procedures. By pressing the button in the Macros panel, you can add a new macro to your class in a similar fashion to functions.

Similar to functions, macros also have their own graph, but they are not executed in a dedicated scope. Instead, they are expanded in place wherever they are used, just like C++ macros are. Moreover, macros can similarly have any number of input and output pins, and they support some of the same settings functions do.

Macro Settings

Unlike functions, macros are not inherited like methods, and they can't be called from other objects. More importantly, macros can have any number of in/out execution pins, which are enabled via a pseudo-type called Exec.

Macro with Multiple In/Out Exec Pins

Variables¶

The Variables panel lists all the variables declared in the current class, along with their type, and an indicator of whether they are instance editable or not.

Example Variable

By pressing the button in the Variables panel, you can add a new variable to your Blueprint Class. The Details panel will then show the variable's settings, along with its default value.

By dragging in a variable from the panel onto the graph, you'll be prompted to add a Getter node or a Setter node for that variable.

A Getter node simply allows you to read the value of a variable:

Example Variable Getter

while a Setter node allows you to write a new value to the variable:

Example Variable Setter

Alternatively, you can hold down Ctrl or Alt when releasing the mouse button to choose a Getter and a Setter node, respectively.

Note

Inherited variables won't show up in the Variables panel, but you can still interact with them. Simply open up the Actions Menu by right-clicking on the graph and look for "Get Variable Name" / "Set Variable Name".

Variable Type

Variable Types¶

A variable can be of one of the following types:

Primitives like booleans, integers, etc.
Structures declared in Blueprint or C++.
Enumerations declared in Blueprint or C++.
References to instances of Object Types,
i.e. Blueprint Classes or UObject subclasses.
References to instances of Interface types,
declared in Blueprint or C++.

In the Details panel, you can also choose to make the variable a container. The variable can be either an Array (contiguous dynamic list), a Set (hash set), or a Map (hash map). If you pick Map, the selected type will be used for the keys, and you'll be prompted to choose a type for the values.

Variable Type

Object Types¶

When you pick an object type—referencing an instance of another Blueprint or a UObject subclasses class—you'll be presented with a menu that allows you to choose the type of reference you want to create:

Object Types

An Object Reference is a simple pointer to an existing object, e.g., another actor in the level. Naturally, you can access the object's properties and methods via the reference:

Object references may be invalid at times—set to null or simply dangling. Accessing an invalid object reference will result in a crash. You might want to use a Validated Get to redirect the flow of execution:

Note that whenever this Blueprint is loaded, any object it references will be immediately loaded into memory. In rare cases, this cascading behavior may lead to hangups and stutters, especially if the referenced object is heavy. In such cases, you might want to use a Soft Object Reference instead. With a soft reference, you'll have to first call one of the following methods to resolve the actual object:

Soft Object Reference Loading

If the object is already loaded into memory, both methods will return immediately. Otherwise, Load Asset Blocking will pause the execution until the object is loaded, while Async Load Asset will load the object in background and resolve later. The latter is ideal for most cases, since Blueprints generally run on the Game Thread and blocking it will lead to a noticeable stutter.

A Class Reference, on the other hand, can be used to refer to a class, rather than in instance. This variable can accept a reference to the object type you selected in the first place, or to any of its subclasses.

Class Reference Example

Similar to Object References, Class References have a Soft variant, which similarly needs to be resolved before use:

Soft Class Reference Loading

Casts??? To Do.

Variable Settings¶

By selecting a variable in the panel, you can access the following settings in the Details panel:

Variable Name

The name of the variable.

Internally, the name is represented as a FName object. This means that the name may contain spaces, but the editor will generally show it in its display format, which can cause confusion at times. It's best to avoid them.

Variable Type

The type of the variable. See Variable Types for more info.

Description

Used to provide a description of the function that will be displayed in the editor when the variable is hovered over.

Instance Editable

Allows you to edit the variable's value in the Details panel of any instances of the Blueprint. Otherwise, you can only set the default value in Class Defaults .

Blueprint Read Only

Whether this variable can be modified in Blueprints or not.

Expose On Spawn

Whether this variable be exposed when spawning an instance of this Blueprint. The variable must be Instance Editable for this to work.

Private

When set, deriving classes won't be able to access this variable.

Expose to Cinematics

Exposes the property to the Sequencer for keyframe interpolation.

Event Dispatchers¶

The Event Dispatchers panel lists all the event dispatchers, also known as dynamic multicast delegates, declared in the current class. They can be used to reroute and broadcast events to one or more listeners. You can add a new dispatcher to your class by pressing the button.

Example Event Dispatcher

To trigger the dispatcher, you can drag in the dispatcher onto the graph and pick a Call node:

The dispatcher will then trigger any bound events, executing the custom logic you've defined. You can bind any number of listener events to a dispatcher using the Bind Event node:

Binding a custom event to an event dispatcher

Note that you can dynamically bind and unbind events to a dispatcher at runtime. This is useful when you want to listen to an event only under certain conditions.

Unbind All and Bind Again

In addition to the usual settings of a variable, a dispatcher can also declare input parameters in the Details panel:

Event Dispatcher Inputs

These parameters are passed to the bound events when the dispatcher is triggered.

Inherited event dispatchers won't show up in the Event Dispatchers panel, but they are still accessible. You can find these dispatchers under the Events panel in Class Defaults, and bind a custom event to them by clicking the button.

Class Settings¶

By clicking on the button, the Class Settings will show up in the Details panel. These settings are categorized as follows:

Class Options¶

Parent Class

The base class for the Blueprint.

Changing the parent class may break the Blueprint, if the new parent does not have the same properties or methods as the old one. The compilation will fail until you fix the issues.

Advanced › Deprecate

Marks the class as deprecated.

This flag has no effect on the class's behavior, but it will be displayed in the editor as a warning to the user.

Advanced › Generate Const Class

When set, all variables and functions in the class will be marked as constant.

Advanced › Generate Abstract Class

When set, the class will be marked as abstract, meaning it cannot be instantiated directly. It must be subclassed.

Advanced › Should Cook Property Guids?

Incomplete

This section is incomplete and needs to be expanded.

Blueprint Options¶

Run Construction Script on Drag

When set, the construction script will be continuously executed while dragging the actor in the editor. Otherwise, it will only run when the drag operation is completed.

Run Construction Script in Sequencer

When set, the construction script will be continuously executed while scrubbing the timeline in the sequencer.

Blueprint Display Name

An alternative name for the Blueprint, displayed in the editor.

Blueprint Description

A description of the Blueprint, displayed in the editor when the Blueprint is hovered over.

Blueprint Namespace

Incomplete

This section is incomplete and needs to be expanded.

Blueprint Category

Incomplete

This section is incomplete and needs to be expanded.

Hide Categories

Incomplete

This section is incomplete and needs to be expanded.

Imports¶

Incomplete

This section is incomplete and needs to be expanded.

Interfaces¶

See Blueprint Interfaces to learn more.

Class Defaults¶

To Do.

Blueprint Class¶

Creating a Blueprint Class¶

Blueprint Class Editor¶

Event Graph¶

Flow Control¶

Latent Actions¶

Custom Events¶

Organization¶

Comments¶

Functions¶

Inputs & Outputs¶

Local Variables¶

Overriding Functions¶

Function Settings¶

Static Functions¶

Macros¶

Variables¶

Variable Types¶

Object Types¶

Variable Settings¶

Event Dispatchers¶

Class Settings¶

Class Options¶

Blueprint Options¶

Imports¶

Interfaces¶

Class Defaults¶

Optimization¶