1.3 - Variables

Choose your OS:

BPVariablesExample.png

In this example, we have a Blueprint Actor that has two spot lights set up. The color of each spot light is controlled by a variable. In programming, a variable is defined as a location in the computer's memory that stores some amount of data. In Blueprint scripts, variables are used in precisely the same way as virtual containers into which we can place, and out of which we can query, some kind of information. In this case, each light in our example uses a Linear Color variable, which stores an RGB value for a specific color. We can put in default values for this color, query it to use it in various locations, and set new colors to it, all as parts of our Blueprint script.

Although in this example we are using primarily Linear Color variables, there are many different types of variables available for use within your Blueprint scripts. Each type of variable holds a different type of data, and it will be important for you to have at least a basic understanding of what the primary data types are. For a list of these types and more information about variable usage, please see the Blueprint variables documentation.

On the left spot light, this variable has been made public, meaning that it will be editable within the Details panel while the Blueprint Actor is selected. On the right is a similar setup, but with the Linear Color variable remaining private. This means that in order to change the color value, one would need to open up the Blueprint script for the Actor and change the default setting for the private variable, or change it some other way as a part of the script's functionality.

Making a variable public simply requires that you check its Editable property, or click the eye icon next to a variable's name in the My Blueprint window. Once a variable is editable, the eye-shaped button next to it will highlight yellow. This indicates that although the variable is publicly editable, it has no tooltip, which may confuse some users. To remedy this, enter a description in the variable's Tooltip property. Once this is done, the eye-shaped button will appear green.

It is important for beginners to note that you will not always want your variables to be public. Sometimes, giving a user the ability to easily change a critical variable can end up breaking or potentially altering important functionality. Always make sure that your public variables are things that an artist or level designer will need access to, and leave anything they are not supposed to touch as private.

You should always make sure your public variables have tooltips to explain what they are used for.

Components

The Components for this Blueprint Actor are fairly extensive, because this example has two completely independent and working lights. Most of the Components are Static Mesh Components, with a few Text Render Components used for labeling. Of course, we must also have some Spot Light Components to complete the effect.

LightComponentList.png LightComponentPreview.png

There are two separate setups, though both are essentially the same. The Component setup for each light is as follows:

Note that the words Public and Private will be appended to these names as a prefix for each of the respective light setups. Also, be aware that indentation indicates parenting relationships from one Component to another, just as it does within the Components list.

  • Wall Mount - This is the Static Mesh Component that appears to be fastened to the wall.

    • Bracket - This is a Static Mesh Component which would attach to the wall mount and appear to hold the Light Fixture.

      • Light Fixture - This is the Static Mesh Component for the fixture itself. To a player, this would appear to be the spot light. The second Material Element (Element 1) has a special Material applied that is created such that its color will update to match the light color.

        • Spot Light - This is a Spot Light Component, which provides the illumination for the effect.

    • Text - A Text Render Component used as a label for Public or Private.

      • Description - Some descriptive text to help further explain the effect.

Variable Setup

When adding Components to a Blueprint Actor, you will notice that the My Blueprint panel (as seen in Graph mode) automatically populates with variables for each Component. This allows you to access each one of the Components should you need to get data from or set data on them. Beyond this, however, we have a few special variables that have been set up specifically for this example.

LightVariables.png

The custom variables that were created specifically for this effect are as follows:

  • PublicColor - This is a Linear Color variable that stores the color applied to the Public light, which is on the left. We set a default value of green on the property.

  • PrivateColor - This is also a Linear Color variable, storing the color applied the Private light, which is on the right. We set a default value of red on the property.

There are also two other variables created to hold the Dynamic Material Instances applied to the lenses of the light fixtures. These are set up so that we can send the color values from the above variables into them, which in turn changes the lens color for the lights to match the color of the Spot Light Components.

  • PublicLightLensMaterial - This holds the Dynamic Material Instance for the Public Light Fixture's lens.

  • PrivateLightLensMaterial - This holds the Dynamic Material Instance for the Private Light Fixture's lens.

Variable Creation

Not all variables need to be created manually within the My Blueprint panel. If you see a value on a node's input or output that you know you need to be stored in a variable, you can right-click on the appropriate data pin and choose Promote to variable from the context menu. This does the following:

  • If you right-clicked on a data input (left side of a variable)

    • A new variable of the appropriate type is created.

    • You may immediately enter a name for the new variable.

  • If you right-clicked on a data output (right side of a variable)

    • A new variable of the appropriate type is created.

    • A Set node for the new variable is also created, setting the initial value of the new variable to equal the output value of the pin.

Construction Script

Most of the work in this effect is actually done within the Construction Script. Since the lights do not need to update once the game begins, we do not use the Event Graph.

To make understanding the Construction Script easy in this example, we have broken it up into a series of commented blocks, as you can see below:

Click for full size

It will be easier to visualize the Construction Script for this example if you open it up in the Blueprint Editor for yourself!

The tasks performed are:

  • Setting light color.

  • Create Dynamic Material Instances and store them into a variable.

  • Assign the new Dynamic Material Instances to the light fixture meshes.

  • Set the color for the Dynamic Material Instances.

Setting Light Color

SetLightColor.png

In these portions of the script, we simply take the default values that were applied and feed them into the Light Color for each light. Since this is the first thing done in the script, it starts by applying the default value, which was red for the private variable and green for the public one. The easiest way to set these nodes up is:

  1. Create a Get reference to each Spot Light Component by Ctrl-dragging them into the graph.

  2. Drag a wire off of each one and type "Light Color" into the search line. You will see the Set Light Color node in the list.

SetLightColor_node.png

Create Dynamic Material Instances and Store Them

CreateStoreDMI.png

The next portion of the network creates a Dynamic Material Instance for each of the Light Fixture Static Meshes. A Dynamic Material Instance is an instantiated copy of a Material that can be updated in some way during gameplay. In this case, we can change the emissive color of the Material so that it matches the color used in the Spot Light Components. You will notice that we create two separate Dynamic Material Instances. This is because we need different instances for the two different colors.

After each Create Dynamic Material Instance node, you will also see that we store the newly created Material in a variable. This gives us access to the Material later, which we will need if we want to be able to adjust the color. We could just connect the Return Value output to other places later on in the network, but storing in a variable makes the Blueprint script appear neater and gives us access to the Material if we should ever need it in the Event Graph.

Assigning the new Dynamic Material Instances

AssigningDMIs.png

Creating your Dynamic Material Instances is not enough. You must also assign those new Materials to the surfaces of your meshes. In this section of the script, we apply the new Dynamic Material Instances to the Light Fixture Static Meshes. It is important to note that we are using Material Element Index 1, which has been set up on the Static Mesh to be placed on the lens. This means our Material will be used to change the color of the light lenses.

Set Color for Dynamic Material Instances

SetLensColor.png

Our final step, now that the Dynamic Material Instances have been applied to the surface, is to assign colors to those Materials. In this case, we have done this through two variables. For this example, we have made one of them public and the other private. It should be noted, however, that this is primarily for academic purposes. Practically speaking, it would probably be more useful if both of the variables were public.