UDN
Search public documentation:

MaterialEditorUserGuide
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > Unreal Editor and Tools > Material Editor User Guide
UE3 Home > Materials & Textures > Material Editor User Guide

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:

materialeditor.jpg

  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

toolbar.jpg

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

Icon Description
toolbar_home.jpg Moves the material expression graph so that the base material node appears in the upper left corner of the main pane.
toolbar_grid.jpg Toggles the background grid in the material preview pane.
toolbar_cylinder.jpg toolbar_cube.jpg toolbar_sphere.jpg toolbar_plane.jpg Select from the standard shapes upon which to preview your material.
toolbar_find.jpg Opens the Content Browser and selects the material.
toolbar_usestatic.jpg Select a static mesh in the Content Browser and press this button to make the selected mesh the preview mesh.
toolbar_clean.jpg Deletes any material expression nodes that aren't connected to the material.
toolbar_show.jpg Show/Hide material expression connectors that aren't connected to anything.
toolbar_realtime_preview.jpg If enabled, update the material on the preview mesh in realtime. Disable this flag for editor performance.
toolbar_realtime_expression.jpg If enabled, update the materials in each material expression node in realtime. Disable this flag for editor performance.
toolbar_realtime_preview_expression.jpg 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.
toolbar_apply.jpg Applies any changes made in the Material Editor to the original material and any uses of that material in the world.
toolbar_stats.jpg Show/Hide material statistics in the expression graph pane.
toolbar_source.jpg Toggles display of the HLSL source for the currently selected expression.
toolbar_search.jpg Allows you to search the expressions for occurrences of a piece of text. See Material Expression Search for more information.

Preview Pane

previewpane.jpg

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

propertiespane.jpg

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

expressionpane.jpg

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

functionpane.jpg

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

graphpane.jpg

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.

material_node.jpg

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

Control Action
LMB or RMB + Drag on background Pan material expression graph
Mouse Wheel Scroll Zoom in and out
LMB + RMB + Drag Zoom in and out
LMB on object Select expression/comment
Ctrl + LMB on object Toggle selection of expression/comment
Ctrl + LMB + Drag Move current selection/comment
Ctrl + Alt + LMB + Drag Box select
Ctrl + Alt + Shift + Drag Box select (add to current selection)
LMB + Drag on connector Create connection (release on connector or variable)
LMB + Drag from connection Move connection (release on same type connector or variable)
Shift + LMB on connector Marks the connector. Performing the action again with a connector marked will create connection between the two connectors. This is a quick way of making connections over large distances.
RMB on background Bring up New Expression menu
RMB on object Bring up Object menu
RMB on connector Bring up Object menu
Alt + LMB on connector Break all connections to connector
Hold L + Drag (in preview pane) Rotate the preview light direction

Keyboard Controls

Control Action
Ctrl + C Copy selected expressions
Ctrl + V Paste
Ctrl + W Duplicate selected objects
Ctrl + Y Redo
Ctrl + Z Undo
Delete Delete selected objects
Spacebar Force update all material expression previews
Enter (same as clicking apply)

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:

Hotkey Expression
A Add
B BumpOffset
C ComponentMask
D Divide
E Power
F MaterialFunctionCall
I If
L LinearInterpolate
M Multiply
N Normalize
O OneMinus
P Panner
R ReflectionVector
S ScalarParameter
T TextureSample
U TexCoord
V VectorParameter
1 Constant
2 Constant2Vector
3 Constant3Vector
4 Constant4Vector
Shift + C Comment

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.

Comments.jpg

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


RealtimePreviewCloseup.jpg

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.

error_message.jpg

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.

error_highlight.jpg

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

search_highlight.jpg

Note: The search is case-insensitive.

Searches are performed against the following proeprty values:

Expression Type Searched Properties
All Desc
Texture Sample Texture
Parameters ParamName
Comment Text
FontSample Font
MaterialFunctionCall MaterialFunction

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 search_next_button.jpg and search_prev_button.jpg buttons.

search_cycle.gif

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

To clear a search, simply press the search_clear_button.jpg button.