Material Parameter Collections

A MaterialParameterCollection is an asset that stores an arbitrary set of scalar and vector parameters which can be referenced in any Material. It is a powerful tool that artists can use to get global data into many Materials at once. It can also be used to drive per-level effects, such as snow amount, destruction amount, wetness, etc., that would otherwise require setting individual parameter values on many different Material Instances in your level.

In the example above, global parameters are used to control the following aspects of the scene:

• The flower morph states along with the wind speed and strength are being controlled.
• The player's position is being tracked and fed into the foliage. That position information is used to move the flowers and grass away from the player as they walk nearby.
• The sun angle and color is also tracked and used to correctly colorize the water crests and limit the effect to only times when light shines directly through the wave crests (when the player is looking toward the sun).
• The coloration of effect across the time of day and overall diffuse lighting color for the water are also being controlled.

Creating and Editing Material Parameter Collections

MaterialParameterCollections are created through the Content Browser via the New menu or the Right-Click context menu and can be edited and saved like any other assets.

1. To create a Material Parameter Collection, you must first Right-click in the Content Browser to expose the create menu. From that menu, select the Materials & Textures section and then select Material Parameter Collection. Once selected, it will create a new Material Parameter Collection in the Content Browser.

   

2. The Material Parameter Collection will be added and saved to the Content Browser just like any other Asset.

   

3. To edit a Material Parameter Collection, you must first Double-click on it with the Left Mouse Button to open up the property window for it.

   

4. Click the next to Scalar Parameters or Vector Parameters to create new parameters that you want to access in Materials.
   Do not forget to input names and default values for any Scalar or Vector Parameters you enter.

   

Using Material Parameter Collections in Materials

Adding a Material Collection Parameter node to any Material is something that can be done in a few steps. In the following section we will look at how we can add a Material Collection Node to a very simple Material that will desaturate the Material when the Left Mouse Button is pressed while the game is playing.

1. The first thing that needs to be done is that we need to create a Material Collection Parameter node and fill it in with data. To do this, Right-Click in the Content Browser and then select the Materials & Textures section and then select Material Parameter Collection. This will create a Material Parameter Collection in the Content Browser. Once created, you need to name it. For this example we will be using MPC_Global_Material_Prams as the name. When completed you should have something that looks like this in your Content Browser.

   

2. Once the Material Collection Parameter has been created open it up by Double-Clicking on it with the Left Mouse Button. Once the Material Collection Parameter is open add one Scalar Parameters to and name it Global_Desaturation. Leave the default value of Global_Desaturation at 0.0. When completed your Material Collection Parameter should look like this.

3. Now that the Material Collection Parameter has been created we now need to create a simple Material to use it with. For this example we will be creating the following Material.

   

   For this Material we will need two Scalar Parameter Material Expression nodes as well as one Vector Parameter Material Expression node. The nodes should be named, Base_Color, Metallic, and Roughness and each node should be hooked up to its corresponding input.

4. With the nodes now hooked up to the Main Material Node, it is now time to add both the Desaturation Material Expression node as well as the Material Expression Parameter node to the Material. To add the Desaturation Material Expression node, search for Desaturation in the Palette and then drag it from the Palette into the Material Graph. Once that has been placed, locate the Material Parameter Collection in the Content Browser and then drag it from the Content Browser into the Material Graph. When completed your Material should look something like this.

   

5. Now that the all of the nodes have been added, it is now time to connect everything together. The first thing that we are going to want to connect is the Base Color output to the first input on the Desaturation node. Next, we are going to need to connect the output of the Material Collection Parameter to the Fraction input on the Desaturation node. Once that is completed, connect the output of the Desaturation node to the Base Color input on the Main Material node. Finally, make sure to press the Apply button to compile your Material. When completed your Material Graph should look like this.

   

6. To see the Material Collection Parameter in action, we must first apply the Material that is using the Material Collection Parameter to some objects in the world. Once the Material has been applied, open up the Material Collection Parameter by Double-Clicking on it with the Left Mouse Button inside of the Content Browser. Once opened, we can then change the Default Value of Global_Desaturation from 0 to 1 and see the objects with the Materials applied go from, in this case, blue to white like in the following example.

Updating Material Parameters Collections Through Blueprints

One of the other ways that you can manipulate Material Collection Parameter parameters is via Blueprints. This is an extremely powerful way to manipulate Material Collection Parameter as this means that at any time during game play you can adjust the Material Collection Parameter as needed.

1. Before we can begin, we need to do a few things first. The first thing that we need to do is to make some Material Instances out of our Material. For this example we need to create three Material Instances based off of the Material that was created above. After the Material Instances have been created make sure and adjust the color so that you can tell them apart. For this example, the colors Red, Green, and Blue have been chosen as the colors for our Material Instances. When completed, your Content Browser should look like this.

   

2. Now that the Material Instances have been created, it is now time to apply them to various objects in the scene by clicking on the Material Instance with the Left Mouse Button in the Content Browser and then Dragging them onto the objects in the scene. Once you are over the object that you want to use the Material Instance on, release the Left Mouse Button to apply the Material Instance to the object. When completed you should have something that looks like this.

   

3. With the Material Instances now applied to objects in the level, it is now time to open up the Level Blueprint. To open up the Level Blueprint, click on Blueprints icon on the main tool bar and then from the drop down menu select Level Blueprint.

   
4. Once the Level Blueprint has been opened, it is now time to begin laying down some nodes. For this example we will be needing the following nodes and variables.
   • Left Mouse Button Pressed
   • Timeline
   • Set Scalar Parameter Value
   • Float Variable Named: Des

   When completed, your Blueprint Graph should look something like this.

5. With the correct nodes added to the Blueprint Graph, it is now time to set them up. The first thing that we are going to set up is the Set Scalar Parameter Value. To set this up we have to first define what Material Parameter Collection we are going to use. To do this, use your Left Mouse Button to click on the Collection input and then select which Material Parameter Collection you would wish to use. Next, select the Parameter Name you wish to manipulate, in this case it will be Global_Desaturation. When completed, your Set Scalar Parameter Value node should look like this.

   

6. Next we are going to need to set up our Timeline so that when the Left Mouse Button is pressed, the colors will change over time and then back once the Left Mouse Button has been released. To set up the Timeline, first use the Left Mouse Button and Double-Click on the Timeline to open it. When you do, you should see something like this.

7. Now that the Timeline has been opened, we now need to fill it in with some data so that it will do something when activated. The first thing that we need to do is to add a Float Track to the Timeline by clicking on the Add Float Track icon. Then we need to add two Key Tracks by using the Right Mouse Button and clicking anywhere in the light gray area and then selecting Add Key from the menu. We want to add two keys, one at 0 time and value of 0 and one Key at time 1 and value of 1. Once the key points have been added, do not forget to name the track so that it is easier to know what it does. For this example, we will use Des_Amount as the name. When completed, you should have something that looks like this.

8. With the Timeline now set up correctly, you can close the Timeline menu and get back to the Event Graph for the Level Blueprint. Once you have the Level Blueprint available, you can start to connect all of the nodes together. When completed, your Blueprint should look something like this.

9. Now that everything is connected, make sure to Compile your Level Blueprint by pressing the Compile button and then close the Blueprint Editor. Once the Blueprint Editor has been closed, it is now time to test to see our changes happen in game. To do this, all you need to do is press the Play icon that is on the Main Toolbar. Once you press play, a new window will be displayed with the level running inside of it. To see the Material Collection Parameter in action, hold down the Left Mouse Button and the colors of the Materials in the scene will go from their original color to grey. Release the Left Mouse Button, and the Materials will return their original color.

Limitations and Performance Characteristics

A Material can reference, at most, two different MaterialParameterCollections. One is typically used for game-wide values while the other can be used for level specific parameters. A collection can have up to 1024 scalar parameters and 1024 vector parameters.

Modifying the number of parameters in a collection will cause a recompile of all Materials that reference that collection. If you need to add numerous parameters, it can be faster to add a lot of parameters up front in an empty map.

If you rename a parameter, any Materials referencing that parameter will continue to work as expected. However, any Blueprint referencing that parameter will now be broken. You must reassign the ParameterName of the Blueprint function which operates on the collection to fix this.

Updating values in a MaterialParameterCollection is much more efficient than setting many different parameters on various Material instances.