Material Editor User Guide

Overview

This document describes how to use UnrealEd's Material Editor. For a description of what the various material expressions do, see the Materials Compendium. For an explanation of how to create new material expressions, see CreatingMaterialExpressions.

For information about creating materials for mobile platforms, please see the mobile material reference page.

Opening the Material Editor

The Material Editor can be opened by double-clicking any Material asset or through the right-click context menu of a Material asset in the Content Browser. Either of these will open up that particular Material in the Material Editor for editing.

Material Editor Interface

The Material Editor is comprised of six regions:

1. Menu Bar
2. Tool Bar
3. Preview Pane - Previews the material on a mesh.
4. Material Expression Graph - Material expression nodes are connected together in this pane to create shader instructions.
5. Material Expressions List - A list of the available material expressions.
6. Material Functions Library - A list of the available material functions.
7. Properties Pane - Properties of the material or selected material expression nodes.

Menu Bar

Window

• Properties - Shows the Properties Pane.
• Preview - Shows the Preview Pane.
• Material Expressions - Shows the Material Expressions Graph.

Tool Bar

What follows is a description of each of the toolbar buttons, from left to right as they appear on the toolbar.

Icon	Description
	Moves the material expression graph so that the base material node appears in the upper left corner of the main pane.
	Toggles the background grid in the material preview pane.
	Select from the standard shapes upon which to preview your material.
	Opens the Content Browser and selects the material.
	Select a static mesh in the Content Browser and press this button to make the selected mesh the preview mesh.
	Deletes any material expression nodes that aren't connected to the material.
	Show/Hide material expression connectors that aren't connected to anything.
	If enabled, update the material on the preview mesh in realtime. Disable this flag for editor performance.
	If enabled, update the materials in each material expression node in realtime. Disable this flag for editor performance.
	This button is a global toggle for a material expression's bRealtimePreview flag. If enabled, the shaders of all subexpressions will be compiled every time nodes are added, deleted, connected, disconnected, or have their property values changed. Disable this flag for editor performance. See the Expression Preview section.
	Applies any changes made in the Material Editor to the original material and any uses of that material in the world.
	Show/Hide material statistics in the expression graph pane.
	Toggles display of the HLSL source for the currently selected expression.
	Allows you to search the expressions for occurrences of a piece of text. See Material Expression Search for more information.

Preview Pane

The material preview pane displays the material being edited applied to a mesh. Rotate the mesh by dragging with the left mouse button. Pan by dragging with the middle mouse button, and zoom by dragging with the right mouse button. Rotate the light direction by holding down L and dragging with the left mouse button.

The preview mesh can be changed by using the associated toolbar controls (the shape buttons, "Select Preview Mesh" combo, and "Use Selected StaticMesh" button). The preview mesh is saved with the material so that the next time the material is opened in a material editor, it will be previewed on the same mesh.

Properties Pane

This pane contains a property window for the selected material expression(s). If no expressions are selected, the properties of the material being edited will be displayed.

See Materials Overview for descriptions of all material properties.

Material Expressions Pane

This pane contains a list of material expressions that can be placed in a material via "drag and drop". To place a new material expression node, left click on the type of expression to place, drag your cursor over to the graph pane, and release.

Material Functions Library

This pane contains a list of Material Functions that can be placed in a material via "drag and drop". To place a new material function, left click on the type of function to place, drag your cursor over to the graph pane, and release. A new MaterialFunctionCall node will be placed withe the appropriate material function assigned to it.

Material Expression Graph Pane

This pane contains a graph of all material expressions that belong to this material. The number of shader instructions used in the material as well as any Compiler Errors are displayed in the upper left corner. The fewer the number of instructions, the less costly the material. Material expression nodes that are not connected to the base material node do not contribute to the instruction count (cost) of the material.

By default, materials contain a single material node. This node has a series of inputs, each associated with a different aspect of the material, that other expressions or networks of expressions can connect to.

See Materials Overview for descriptions of the various inputs of the material node.

Controls

Controls in the material editor generally match the controls of other tools in UnrealEd. For example, the material expression graph can be navigated as with other linked object editors, the material preview mesh can be oriented as per other mesh tools, etc.

Mouse Controls

Keyboard Controls

Hotkeys

There exist hotkeys for placing commonly used material expression types. Hold down the hotkey and left click to drop in the node. The hotkeys are as follows:

Expression Comments

Comments are a great way to document what your material is doing, making it easier for you and others to understand what might be a complicated material graph. Comments are displayed in blue text appearing above the associated nodes. Comments are rendered independently of zooming, making it easy to navigate complex material graphs.

Material expression nodes can be commented individually by putting text in the "Desc" property of that node.

Groups of nodes can be assigned group comments by selecting several nodes and hitting 'Shift + C'. Enter comment text in the "New Comment" dialog and hit OK. The selected nodes will then be grouped in a comment frame. Nodes in a group comment can be moved by dragging on the group comment text. The frame can be resized by dragging on the black triangle in the lower right corner of the comment frame. Any nodes inside a group comment will be moved with the frame, so you can resize an existing frame to include new nodes.

Comments can be renamed by selecting the comment and then modifying the "Text" property using the property window.

Expression Preview

Nodes in the material editor contain a small box in the upper left corner. This box indicates the node's bRealtimePreview property: yellow indicates enabled, black indicates disabled.

Whenever a material changes in any way (a node is created, deleted, connected, a property is changed, etc), all nodes with bRealtimePreview enabled have their shaders recompiled. This recompilation has to happen so that the material preview drawn at that node is up-to-date. However, recompiling these intermediate shaders can be time-consuming, especially if your material contains many nodes. So, to avoid hampering workflow, bRealtimePreview is disabled by default for all node types except TextureSample.

You can force-update all previews by hitting the Spacebar. So, fast iteration can be achieved by disabling bRealtimePreview for as many nodes as possible, and then hit space whenever you'd like to view your changes.

You can enable bRealtimePreview for a node by clicking on the box in the upper left corner of the node, or by using the property window with the node selected.

You can globally toggle all nodes with the "Toggle Expression Realtime Preview" button.

Compiler Errors

Each time a change is made to the material network, the material must be compiled. If any required inputs of an expression within the network have no connections or are being passed the wrong type of data, a compiler error will occur. These errors are displayed in the Graph Pane.

Compiler errors let you know a problem exists and what that problem is by providing information about the type of expression that the occurred on and a description of the error. In addition, the node that contains the error will be highlighted in red in the graph pane so that you can easily find it and make the necessary corrections.

Material Expression Search

The search functionality in the Material Editor allows you to quickly find any nodes (including comments) within the material network that contain a specific piece of text in their description or certain other properties specific to indivdual types of expressions. This makes it easy to add identifying keywords to nodes and jump to them at a later time without hunting through the network of expressions haphazardly.

Typing a full or partial keyword into the search box will perform a search against the properties of the expressions present in the graph pane. Matches are highlighted in green when they are the current active result

Note: The search is case-insensitive.

Searches are performed against the following proeprty values:

Searches can also be performed for specific types of expressions by using the NAME= switch with your search. For example, to find all texture samplers you could use the following search:

NAME=texture

You can cycle between all expressions matching the search using the and buttons.

When a new match is selected either initially or via the and buttons, it will be brought into view in the graph pane if it is not already visible.

To clear a search, simply press the button.