Material Editor User Guide

Document Summary: Guide to using the Unreal Material Editor.

Created by Dave Burke^?. Maintained by Richard Nalezynski.

Introduction

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.

Using the Material Editor

Opening the Material Editor

To open the Material Editor, double-click on a material in the Generic Browser. The Editor is divided in to five sections, labelled below:

Material Editor Overview

Material Editor Layout

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	Name	Description
	Home	Moves the material expression graph so that the base material node appears in the upper left corner of the main pane.
	Toggle Grid	Toggles the background grid in the material preview pane.
	Preview Shapes	Select from the standard shapes upon which to preview your material.
	Select Preview Mesh	Select a preview mesh from this drop-down list of all currently loaded static meshes.
	Use Selected StaticMesh in Generic Browser	Select a static mesh in the Generic Browser and press this button to make the selected mesh the preview mesh.
	Clean Unused Expressions	Deletes any material expression nodes that aren't connected to the material.
	Show/Hide Unused Connectors	Show/Hide material expression connectors that aren't connected to anything.
	Toggle Curved Connections	Toggle between curved and straight-line connections. Disable this flag for editor performance.
	Toggle Realtime Material Viewport	If enabled, update the material on the preview mesh in realtime. Disable this flag for editor performance.
	Toggle Realtime Expression Viewport	If enabled, update the materials in each material expression node in realtime. Disable this flag for editor performance.
	Toggle Expression Realtime Preview	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.

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.

Material Expressions Pane

This pane contains a list of material expressions that 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 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 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.

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:

Working with Materials

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 '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.

Materials Reference

This is a list of Material Properties.

Material

PhysMaterial

The Physical Material associated with this material. See PhysicalMaterialSystem.

OpacityMaskClipValue

This is the reference value which the OpacityMask input of masked materials will clip against per-pixel. Any value higher than OpacityMaskClipValue will pass and the pixel will be drawn, any value lower will fail and the pixel will be discarded.

BlendMode

BlendMode describes how the output of the current material (source color) will combine with what's already in the framebuffer (destination color) when rendered.

• BLEND_Opaque - Final color = Source color. This blend mode is compatible with lighting.
• BLEND_Masked - Final color = Source color if OpacityMask < OpacityMaskClipValue, otherwise the pixel is discarded. This blend mode is compatible with lighting.
• BLEND_Translucent - Final color = Source color * Opacity + Dest color * (1 - Opacity). This blend mode is NOT compatible with dynamic lighting.
• BLEND_Additive - Final color = Source color + Dest color. This blend mode is NOT compatible with dynamic lighting.
• BLEND_Modulate - Final color = Source color * Dest color. This blend mode is NOT compatible with dynamic lighting, or fog, unless this is a decal material.

LightingModel

Lighting models determine how material inputs (eg Emissive, Diffuse, Specular, Normal) are combined to make the final color.

• MLM_Phong - The default lighting model, diffuse and specular are calculated per-pixel.
• MLM_NonDirectional - Per-pixel diffuse only, no specular. Surface normal is also not a factor in the lighting equation. This currently only works for dynamically lit materials.
• MLM_Unlit - Emissive only, this lighting model is required for any transparent blend mode.
• MLM_SHPRT - Deprecated.
• MLM_Custom - Allows an arbitrary lighting model to be used. The camera and light vectors are already in tangent space, so a max(dot(lightvector, float3(0,0,1)), 0) will give you basic diffuse vertex lighting.

TwoSided

The normal will be flipped on backfaces, which means lighting will be calculated for both the front faces and the backfaces. This is commonly used on foliage to keep from having to double up the number of polygons. Two Sided does not work correctly with static lighting, since static lighting only stores incoming light in one hemisphere. As a result, two sided materials with static lighting will be shaded the same on both sides.

Wireframe

The material will render in wireframe.

Translucency

bDisableDepthTest

Allows the material to disable depth tests, which is only meaningful with translucent blend modes. Disabling depth tests will make rendering significantly slower since no occluded pixels can get zculled.

bAllowFog

Whether the material should allow fog or be unaffected by fog. This only has meaning for materials with translucent blend modes.

bUseOneLayerDistortion

Whether the material should use one-layer distortion, which can be cheaper than normal distortion for some primitive types (mainly fluid surfaces). One layer distortion won't handle overlapping one layer distortion primitives correctly. This causes an extra scene color resolve for the first primitive that uses one layer distortion and so should only be used in very specific circumstances.

FallbackMaterial

When compiling materials for shader model 2, each material is compiled unchanged. If this fails due to shader model restrictions, (too many instructions, etc) then the specular, normal, diffuse and emissive are dropped, one at a time, until the material compiles. This is called the automatic or generated fallback. Artists can override this process by specifying the Fallback Material, in which case the generation process will be skipped completely and the Fallback Material will be used on shader model 2 cards instead. Note that the material you want to set as the FallbackMaterial must have bIsFallbackMaterial specified first.

Usage

These flags are used to minimize the number of shaders that need to be compiled out for each material. Carefully set these appropriately or warnings will be thrown when they are used incorrectly such as: "Material blah used with skeletal mesh, but missing bUsedWithSkeletalMesh=True". For example, if a material does not have bUsedWithSkeletalMesh=True but it is assigned to a static mesh, in the editor the flag will be set for you and the material will be recompiled, and marked as dirty. In the game however, the default material will be used.

bUsedAsLightFunction

Indicates that this material will be used with light functions.

bUsedAsSpecialEngineMaterial

Indicates that this material should be compiled with all vertex factory and material combinations, basically saying that it can be used on any primitive type except decals. This will result in a massive amount of shaders compiled, (about 600, where a normal material uses about 30) so use sparingly.

bUsedWithSkeletalMesh

Indicates that this material will be used with skeletal meshes.

bUsedWithParticleSystem

Indicates that this material will be used with particle systems.

bIsFallbackMaterial

Indicates that this material will be used as a Fallback Material for another material. Any compile errors you get will be the result of compiling this material for shader model 2. Note that you should never apply a material with bIsFallbackMaterial directly to anything.