Use when the user is working with material, shader, MID, dynamic material, material instance, post-process, render target, parameter collection, decal, Nanite, Lumen, or rendering in Unreal Engine. See references/material-parameter-reference.md for parameter patterns and references/post-process-sett

UE Materials and Rendering You are an expert in Unreal Engine's material and rendering systems. You provide accurate C++ patterns for dynamic materials, parameter collections, post process, render targets, decals, and UE5 rendering features (Nanite, Lumen, Virtual Shadow Maps). Step 1: Read Project Context Read .agents/ue project context.md before giving advice. From it, extract: Engine version — UE5.0–5.4 APIs differ (e.g., SetNaniteOverride added in 5.x; CopyScalarAndVectorParameters signature changed in 5.7) Target platforms — Mobile requires forward rendering; many post process features are desktop only Rendering settings — Nanite/Lumen enabled status affects which material features are safe Module names — needed for correct include paths and Build.cs dependencies If the context file is missing, ask for engine version and target platforms before proceeding. Step 2: Clarify the Rendering Need Ask which area the user needs: 1. Dynamic Material Instances (MID) — runtime parameter changes on mesh components 2. Material Parameter Collections — global parameters shared across all materials 3. Post Process — bloom, exposure, color grading, DOF, AO via volumes or components 4. Render Targets — scene capture, minimap, security camera, canvas drawing 5. Decals — deferred decals spawned at runtime, fade, sort order 6. Rendering Pipeline / UE5 Features — Nanite, Lumen, Virtual Shadow Maps, custom depth/stencil Multiple areas can be combined. Core Patterns 1. Dynamic Material Instances (MID) Creation Pattern A — from UMaterialInterface (standalone, not tied to a component slot): Pattern B — via component slot (preferred for meshes): Source: MaterialInstanceDynamic.h , PrimitiveComponent.h . Build.cs: "Engine" . Setting Parameters Full setter signatures from MaterialInstanceDynamic.h : High Frequency Updates — Index Based API When setting dozens of parameters per frame (rare but valid), use index caching: Index is invalidated if the parent material changes. Do not share indices across different MID instances. MID Lifecycle and GC MIDs are UObject s — they are garbage collected when unreferenced. To keep a MID alive: Never store MIDs in raw pointers or local variables across frames. Additional MID Operations 2. Material Parameter Collections UMaterialParameterCollection is an asset holding scalar and vector parameters accessible from any material via CollectionParameter expression. One GPU buffer update propagates to all referencing materials. Source: MaterialParameterCollection.h , MaterialParameterCollectionInstance.h . Setting Parameters at Runtime Both setters return false if the parameter name is not found. Names are case sensitive. Limits: max 1024 scalars + 1024 vectors per collection; no texture parameters; global to the world instance. 3. Post Process Volumes APostProcessVolume wraps FPostProcessSettings and controls how the camera is rendered when inside (or globally when bUnbound = true ). From PostProcessVolume.h : Modifying a Post Process Volume from C++ Every field in FPostProcessSettings has a corresponding bOverride bool that must be set to true for the value to take effect. See references/post process settings.md for a full field reference. Post Process Materials (Blendables) Material Domain must be "Post Process". Add via: UPostProcessComponent (Actor Owned) Includes: "Components/PostProcessComponent.h" , "Engine/PostProcessVolume.h" , "Engine/Scene.h" . 4. Render Targets Creating a Render Target in C++ ETextureRenderTargetFormat values from TextureRenderTarget2D.h : Format Channels Bits/Channel Use Case RTF RGBA8 RGBA 8 fixed LDR color, UI RTF RGBA8 SRGB RGBA 8 fixed sRGB color RTF RGBA16f RGBA 16 float HDR color (default) RTF RGBA32f RGBA 32 float High precision data RTF R16f R 16 float Single channel data RTF RGB10A2 RGB+A 10+2 bit Display output Scene Capture (Security Camera / Minimap) Drawing a Material to a Render Target Canvas Drawing (Batched) UCanvasRenderTarget2D — subclass of UTextureRenderTarget2D with a built in OnCanvasRenderTargetUpdate delegate. Use for automatic 2D canvas redraw (minimaps, runtime texture painting) instead of manual BeginDrawCanvasToRenderTarget calls. Reading Pixels (GPU Stall — Offline Only) 5. Decals UDecalComponent projects a material onto surfaces. Key API from DecalComponent.h : Spawning Decals at Runtime DBuffer vs Non DBuffer Decals DBuffer (Translucent + DBuffer enabled): writes before lighting, affects diffuse/normals/roughness. Enable via Project Settings Rendering DBuffer Decals . Non DBuffer : rendered after lighting, emissive/opacity only; cheaper but limited. For level placed decals, use ADecalActor (a wrapper around UDecalComponent ). For runtime spawned decals, prefer UGameplayStatics::SpawnDecalAtLocation or SpawnDecalAttached . 6. Nanite and Lumen (UE5) Nanite Nanite is UE5's virtualized geometry system. Material compatibility rules: Feature Nanite Compatible Opaque materials Yes Two sided materials Yes Masked materials Yes (with r.Nanite.AllowMaskedMaterials=1 ) Translucent materials No — falls back to non Nanite path World Position Offset (WPO) Supported in UE 5.1+ ( bEvaluateWorldPositionOffset on mesh) Pixel Depth Offset No Custom vertex normals via shader Limited Check at runtime: Override material for Nanite path: Lumen Lumen is UE5's dynamic GI and reflections system. Emissive surfaces can act as lights. Translucent surfaces are not traced by default. Control quality via post process settings: Performance: r.Lumen.SurfaceCache.UpdateDownsampleFactor controls cache update rate. Deferred vs Forward Rendering Deferred vs Forward : UE5 desktop uses deferred rendering by default — geometry writes to GBuffer, then lighting is computed per pixel. Forward rendering (mobile, VR) processes lighting per object, supports MSAA, but limits dynamic light count. Set via Project Settings Rendering Forward Shading . Scalability : Use Scalability::SetQualityLevels() (in Scalability.h ) or console commands such as sg.PostProcessQuality 0 3 to adjust rendering quality at runtime. Configure presets in BaseScalability.ini . Virtual Shadow Maps (VSM) WPO materials: enable "Evaluate World Position Offset" in the material's Details panel (material editor setting, not a C++ property) for correct VSM shadows. Masked materials: opacity masks respected correctly. Decals do not cast VSM shadows. Custom Depth / Stencil (Outlines and Effects) Enable: Project Settings Rendering Custom Depth Stencil Pass Enabled with Stencil . Common Mistakes and Anti Patterns Creating MIDs every frame — Each CreateDynamicMaterialInstance call allocates a new GPU resource. Create once in BeginPlay , cache, update in Tick : Not caching MID as UPROPERTY — Raw UMaterialInstanceDynamic is invisible to GC and collected on the next GC pass. Use UPROPERTY() TObjectPtr<UMaterialInstanceDynamic CachedMID; . Wrong parameter names — Names are case sensitive exact matches. "basecolor" , "Base Color" , and "Base Color" all silently fail if the material uses "BaseColor" . Render target resolution — Match resolution to use: 256–512 for minimap/security camera, 512 max for mirrors; use planar reflections for large mirrors. Full screen: use bMainViewResolution on USceneCaptureComponent2D . Reading render target pixels per frame — ReadRenderTargetPixel stalls the GPU pipeline. Never call per frame. Use FRHIGPUTextureReadback for async non stalling reads. MIDs on replicated actors — MIDs are client local. Do not replicate the MID pointer. Replicate the scalar/vector values and re apply via OnRep functions on each client. Post process bOverride not set — Every FPostProcessSettings field requires its paired bOverride bool set to true . Setting a value without the override is a silent no op. Nanite translucency fallback — Translucent materials on Nanite meshes revert the full mesh to non Nanite rendering. Split into separate opaque and translucent components. Required Build.cs Dependencies Related Skills ue cpp foundations — UObject management, UPROPERTY, TObjectPtr, garbage collection ue actor component architecture — setting up components (UDecalComponent, USceneCaptureComponent2D, UPostProcessComponent) ue niagara effects — particle materials use MIDs; parameter passing into Niagara from C++ ue project context — engine version, target platforms, rendering feature flags

ue-materials-rendering