Interactivity & Blueprints

This is a Work in Progress Article

Overview

Interactivity is the mechanics that adds to the user experience, animation, events and sequences triggered by some form of user input is considered interactivity. In Unreal Engine, this is achieved through the use of Blueprint visual scripting.

Introduction

Blueprints in Unreal Engine can refer to two different things:

Blueprints

The common usage of Blueprints is as 'containers' for 'components.' Prefabs is the more general concept, this is the idea that complete hierarchies of Components can be created so these may be placed multiple times in or across levels and projects, without needing to build them out again every time.

This idea is the same as an Actor, but where Actors are only created in the Level Editor, Blueprints can be thought of as Actors that have been expressed in the Content Browser, and can be added to the level as Blueprint Actors. For a refresher on Actors:

Actors: Components, Content and Editors

Each time you use a Blueprint, you create an instance of that Blueprint which is separate to any other instances. This means you can edit the Blueprint to edit all instances of it, but editing an instance will not change other instances. Careful planning of setting up Blueprints also allows parameters to be exposed and changed on a per instance basis.

A common example to use is a car object. You have a variety of elements that make up a car, like the frame, engine, wheels, and so on. Instead of needing to assemble these elements every time you want a car in your project, you can assemble one Blueprint of the car with all the elements in the right place just once, and it is ready to use. Parameters you might expose so all your instances of cars are different could be the colour of the frame or seat material.

Blueprint Visual Scripting

The more common invocation of Blueprint is as Unreal Engine's Visual Scripting language, which will be referred to as Blueprint Scripts. Blueprint Script is a coding language expressed visually through node, which can be an accessible way to implement functionality into your experience.

Every Blueprint has access to Blueprint Script, so while the Blueprint is a container for content, the Blueprint Script is what adds functionality to that Blueprint.

Blueprint Scripting is also the system that other Editors and Canvases that Unreal Engine uses to some extent, like Materials and Animation. You can expect the same core with minor differences.

Making Blueprints

The blueprint naming convention is: BP_(Blueprint)_(Script if necessary)

Empty Blueprints

Blueprints are made like any other object, you can right click in the content browser. This is used to create empty Blueprints to configure a new Blueprint Prefab using the Viewport Graph Editor, or a empty Blueprint to use for Blueprint Scripting.

From Actor

Actors can be converted into Blueprints through the [Blueprint/Add Script] button in the Actor's Details Panel. A popup will appear prompting for a save folder and Blueprint name.

Blueprint Classes

When creating a Blueprint from the Content Browser, you may be prompted Classes can be thought of as common libraries of functions that are already established conventions. Selecting a Class will give you access to functions, commonly referred to as inheritance in programming.

The Actor class is the the basic generic class and will be used in most cases.

Blueprint Editor

Blueprints are containers for components, and have a Scripting element that can be used to run in the background, extending the functionality of the experience through gameplay elements, sequencing triggers and events, automated behaviours and interactivity. First let us take a look at the editor.

Blueprint Editor

Section

Tool

Description

Top Menu

The top menu features a variety of necessary functions. Compiling needs to be done for the project to play the latest edition, this is separate to saving. For testing, the experience can be played through the blueprint with its own debugging visuals, and the blueprint to debug can be chosen as well.

Graph Editor

The Graph Editor is where you do most of your work. Refer to [Graph Editor] below.

Components

Displays the hierarchy of the blueprints components, any internal blueprints and references are revealed here. This can be manipulated as you would the Outliner.

My Blueprint

Overview of all the variables and functions in this blueprint.

Details

Details relating to the node or the blueprint depending on what is selected, are revealed and can be edited here.

Graph Editor Tabs

This provides a quick overview on what each tab is used for, for more details refer to the relevant sections down the page

Viewport

When a Blueprint is used as a container that has a visual or physical object component to it, the Viewport is where it can all be set up. This functions identically to the Unreal Level Editor.

Construction Script

The construction script allows parameters in the Blueprint to be exposed and changed in the Level Editor like any other object, giving you control over instances of the Blueprint

Event Graph

The Event Graph is where Blueprint Scripting is done, piecing together components, variables and functions.

Custom Macros/Functions

Parts of scripts can be collapsed into more manageable sections that can also be reused. These will comprise new tabs in the Graph Editor when created.

Blueprint Visual Scripting System

The Blueprint Scripting system is based on the concept of using a node-based interface to create mini-programs that references actors in the level and other blueprints. Many of Unreal Engine's editors or canvases use this Blueprint Scripting system, so these concepts apply across the program, this section will cover the basics.

Blueprint Scripting for Blueprints will be covered in a the Blueprint Scripting and Programming section further below. By connecting Nodes, Events, Functions, and Variables with Wires, it is possible to create complex gameplay elements. Data flows from left to right, a series of these nodes forms a logic.

Anatomy of a Node

[Replace with an image that has both input and output pins and wires]

Reference

Aspect

Description

Node

Nodes are the parts that describe snippets of functionality that are pieced together in blueprints

Exec

These pins tells the node to carry out its function. As data flows through the blueprint, these exec pins will fire and determines the flow of logic.

Input Pins

Pins are what you plug things into for incoming data. Input pins are always on the left. These pins are colour-coded for the type of data that they can receive. These colours are discussed further down the page.

Output Pins

Outgoing data that has been transformed by the nodes functionality is accessed through the output pin. These are always on the right.

Wire

Represents the flow of data, connecting pins. These wires are also colour coded like the pins.

Options

Some input pins will have options built into them to save needing to expose another node just to input data, this is common for the basic data types for numbers, booleans and vectors. Otherwise the pins would be receiving data from other nodes.

Using Nodes

Now with an understanding of what a node is, the basic usage is:

RMB in an empty space to Search for nodes.
Drag pins to other other pins to create a connection, allowing the data to flow

The Blueprint Scripting interface is by default, context sensitive, this setting can be found here when you right click on an empty part of the canvas [image]

No selection: RMB in an empty space to Search for nodes.

Selection: RMB in an empty space and all relevant nodes to the selected element will be expressed. For example, if you have a mesh selected, you will automatically get node suggestions for referencing the mesh.

From Previous Node: When dragging off a pin from another node, it will only show nodes that are compatible with the data coming out of the pin

Anatomy of a Script

The script flows from left to right, where the exec pins dictates the flow of logic. Therefore, all exec pins of nodes you want to use will need to be connected. Where usual traditional text coding goes through code line after line, Blueprint Scripts run node by node where the exec pins dictates the order of your code. When an exec pin is triggered, this is known as the pin firing.

Using the Viewport Tab

This section is a Work in Progress section.

The Viewport Editor in Blueprint is used to add all sorts of components, either as stand-alone Blueprints for instancing or they can be referenced in the Blueprint Scripts.

For example, a prefab of a lamp and switch may use the Viewport to set up the lamp geometry and light. The switch may take the form of the a Trigger volume to detect when the user is inside it to turn the light on. This light and trigger will be the components referenced in the Blueprint Script to make it interactive

[Image of editor]

Ref.

Aspect

Description

Viewport

Functions like the level editor

Component Hierarchy

Add Components and organise the hierarchy

Details

Detail panel

Components

Actors: Components, Content and Editors

Hierarchies

This sub-panel's contents can be manipulated as you would the World Outliner, [drag and drop]Components to that you which you want it to fall under.

Replacing the Root

The Component Root can be replaced by dragging the desired new Root Component over the existing Root.

Using Construction Script Tab

This section is a Work in Progress section.

Construction Scripts are scripts that automatically exec (fire off) when the object is created or edited. Normally variables in the Blueprint cannot be accessed externally. The Construction Script allows you to externalise these parameters:

Nodes and Programming

This section is a Work in Progress section.

As each node is essentially a snippet of code, this section will cover the types of nodes that makes up the backbone of any script.

Reference

Reference nodes are always blue.

Reference nodes are a category of functions that reference an actor in the level. This is usually used only in the Level Blueprint.

Adding References

To add a reference, with the object selected in the Level Editor, [RMB] in the graph editor with context-sensitive enabled to grab a reference using [Create a reference to... ]

Variables

Variables are parameters that make up various data types that are common in scripting languages, these also colour code the wires.

Node Type

Colour

Comment

Integer

Teal

Represents whole negative and positive numbers.

e.g: -100, -23, -8, 0, 1, 23, 30, 10230

Float

Light Green

Represents decimal negative and positive numbers.

e.g: -132.34, -5.0, 0.003, 1.23, 7.0, 12.234

Boolean

Red

Holds a value of True or False

String

Pink

Holds a string of alphanumeric characters, exactly like this sentence, it is used to store text.

While String is a common data type, in Unreal Engine, Text can hold twice the amount of data, while Name can hold half the amount.

Vector

Yellow

Holds an array of three float values.

e.g: [0.23, -102.3, 55]

Rotator

Light Blue

Holds Unreal Engine rotation data, which consists of a Vector array.

Transform

Orange

Holds Unreal Engine transformation data, which consists of 3 Vector arrays consisting of Location, Rotation and Scale.

Objects

Blue

For Unreal Engine Objects like Lights and Characters

Promotion

Nodes that have variable data pins can be promoted to variable nodes with:[RMB > Promote to Variable]This offers a faster and convenient way to create variable as the script is being created.

Get, Set

Variables and Objects

Variables and Objects' Get or Set nodes will follow the colour of its data type.

Over the course of a script, the data that a variable holds may be called upon. This is achieved through the Get node. If this data goes through some transformation or change throughout the script and needs the associated variable needs to be updated, a Set node is used to update the data.

These nodes are accessed through the My Blueprint or Component panels. Dragging and dropping a variable or object will prompt whether a Get or Set node is desired and will be automatically setup.

Get Functions

Get Function nodes are usually green.

These are special functions that are used to get specific set of data that exists within an Object, hence they will usually always reference an Object.

Flow Control

Flow Control nodes are usually grey.

Flow control is a key concept to scripting, which helps to further dictate the execution of the script. Pictured above are the most common types of flow control, also known as conditionals, in scripting.

Branch

Branches, also known as if-statements. These nodes take a Boolean input which branches scripts into True or False; if True, do this, otherwise if False, do that.

For Loop

This node will fire of the exec pin for n amount of times as dictated by the node inputs.

While Loop

This node will continuously fire the exec pin while the input Boolean pin is True, but will stop when it turns False. This is done within the span of one frame, and each iteration the node will check the Boolean to see if it needs to continue or stop.

As with other programming languages, While Loops need to have their break condition implemented correctly to prevent infinite loops. Infinite loops will crash the program.

For a comprehensive list of all flow control nodes available in Blueprint Scripting, refer to:

Flow Control

Macros

Macro nodes are usually grey. Macros are scripts that have been collapsed into a smaller package, usually completed pieces of reusable scripts for saving space that can be used elsewhere.

Functions

Function nodes are usually blue.

Functions are micro pieces of program that transforms input data in some way. These will usually always come off an Object node, and will take Input data from Variable Nodes. In the example above, the SetLightColor node will change the input Target's colour into the input New Light Colour when executed.

Execution Events

Execution Event nodes are usually red.

Execution Events are nodes that are waiting to be triggered, these are what usually begins a sequence a code. When these nodes are triggered, they will fire off their exec pin, triggering the start of the script. In the example above, a OnComponentBeginOverlap node fires off when another Actor to collide with its trigger. The OnComponentEndOverlap node fires off when the trigger is no longer in collision with another Actor.

Casting

Casting nodes are usually cyan.

Casting is a way to check if the data is or is not something. All data types, including user-created blueprint objects can be checked against. Casting can be used to filter data, for example in the image above, it will only allow for the script to continue if the Actor that has triggered the Event is a the Player and not some other object. Casting can also be used to execute a different line of logic if the check has failed (Cast Failed).

Scripting for Blueprints

Basic Scripting

Work in Progress

Debugging

As the script is getting built, here are some methods to check along the way to ensure that the expected outcomes are being reached. These methods are also useful for when things are not working to try and identify the issue.

[RMB] over a variable and select to [watch] to reveal this in the event graph during [Play]
Use print string nodes to print data to the console to check if the data.
[RMB] a node and [Add Breakpoint], during [Play], this breakpoint will interrupt the node when it is about to be executed.
Use the Blueprint Debugger found in the top menu:[Window > Developer Tools > Blueprint Debugger]

Level Blueprint vs Blueprints

The Level Blueprint is a special case of Blueprints, it allows for level specific functionality to be added but is constrained only to that level. removing the modularity that usually comes with Blueprints. What does this mean in practice? Let's go through an example case study:

You have two lights in your Level that you want to turn on if a Player gets close.

Using the Level Blueprint: You will have to create two separate references to the light, and duplicate your code. This may be easier to setup, and if there's no need to use this case many times or it is something only really specific to one Level, the Level Blueprint is fine.

Using Blueprints: You can create a Blueprint prefab of a light that turns on when the player gets close, and then add two instances of that Blueprint to your scene. This blueprint can also be used elsewhere. if an object is to be repeated many times, then consider using Blueprints.

Starting Scripts

The past two sections have given a brief rundown on programming basics and the types of nodes you may find, as with any programming language, it is not recommended nor is it necessary to learn all the types of functionality available. Instead, it is the logic of how a script flows that should be learnt and it is recommended to start with a goal in mind. Design the script as a series of steps that will inform an outcome. Usually it helps to work backwards from the outcome: