unreal-lighting

Unreal 5.8 Lighting

Tune Lumen, exposure, lights, and atmosphere

---
name: unreal-lighting
description: Design, tune, profile, and debug lighting in Unreal Engine 5.8. Use for Lumen GI and reflections, MegaLights, physical light units, exposure and eye adaptation, Directional/Sky/Point/Spot/Rect Lights, Sky Atmosphere, fog, clouds, shadows, interiors, exteriors, day-night scenes, mood targets, or lighting performance problems.
---

# Unreal 5.8 Lighting

## Ownership boundary

This skill owns artistic light, exposure, atmosphere, physical units, and target-look setup. If the
request is an unmeasured performance complaint, start with
[`unreal-insights-profiling`](../unreal-insights-profiling/SKILL.md); after a render/GPU bound is
measured, route optimization to
[`unreal-rendering-performance`](../unreal-rendering-performance/SKILL.md). Route shader/surface graph
architecture to [`unreal-materials`](../unreal-materials/SKILL.md).

## Establish constraints first

Record:

- target platforms and frame-rate budget;
- deferred/forward renderer and scalability target;
- dynamic versus baked lighting requirement;
- Lumen software or hardware ray tracing;
- MegaLights enabled or disabled;
- intended exposure behavior: fixed, bounded adaptation, or full adaptation;
- reference image and desired focal hierarchy.

Do not tune lighting before exposure behavior is deliberate. A changing camera exposure
can hide whether the light or the exposure is wrong.

## Execute

1. Choose the rendering path and mobility.
2. Establish exposure and physical units.
3. Build broad environment light before local accents.
4. Add local lights with the smallest useful bounds.
5. Tune shadow softness with emitter size, not arbitrary intensity changes.
6. Inspect Lumen, exposure, shadow, and light-complexity visualizations.
7. Profile on target hardware.

Read:

- [`references/parameter-effects.md`](references/parameter-effects.md) for control behavior.
- [`references/recipes.md`](references/recipes.md) for concrete target looks.
- [`references/diagnostics.md`](references/diagnostics.md) for failures and performance.

## Required answer format

Return:

1. **Rendering/exposure assumptions**.
2. **Actor and component setup**.
3. **Ordered changes**, naming UE 5.8 properties and editor locations.
4. **Parameter direction**: what increasing or decreasing each value does.
5. **Starting values only when documented or physically grounded**; otherwise give a
   bounded tuning procedure.
6. **Debug views and console checks**.
7. **Performance validation** on the requested target.

Never prescribe an isolated intensity number without its light type, units, exposure,
distance, source size, and target platform.

## Hard rules

- Use Lux for Directional Light, cd/m² for Sky Light luminance, and Candela/Lumens for
  local lights when inverse-square falloff is enabled.
- Treat attenuation radius as an influence bound, not a brightness control.
- Treat exposure compensation in stops: `+1` doubles displayed brightness; `-1` halves it.
- Equal Min/Max EV100 disables auto exposure.
- With Lumen enabled, precomputed static lighting contributions are disabled/hidden.
- MegaLights handles local lights. Sky Light remains outside it. Directional Light support is
  opt-in with `r.MegaLights.DirectionalLights 1`, disabled by default, and has documented
  quality limitations; prefer Deferred Lighting with VSM for a strong sun unless target tests
  justify the MegaLights path.
- Narrow overlapping light bounds. MegaLights has fixed sampling; excessive local
  complexity reduces quality instead of scaling cost conventionally.
- Mark experimental features as experimental and provide a shippable fallback.
- Validate with visualizations and profiling, not the editor beauty view alone.

See [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Ownership boundary

This skill owns artistic light, exposure, atmosphere, physical units, and target-look setup. If the
request is an unmeasured performance complaint, start with
[`unreal-insights-profiling`](/unreal/unreal-insights-profiling/); after a render/GPU bound is
measured, route optimization to
[`unreal-rendering-performance`](/unreal/unreal-rendering-performance/). Route shader/surface graph
architecture to [`unreal-materials`](/unreal/unreal-materials/).

## Establish constraints first

Record:

- target platforms and frame-rate budget;
- deferred/forward renderer and scalability target;
- dynamic versus baked lighting requirement;
- Lumen software or hardware ray tracing;
- MegaLights enabled or disabled;
- intended exposure behavior: fixed, bounded adaptation, or full adaptation;
- reference image and desired focal hierarchy.

Do not tune lighting before exposure behavior is deliberate. A changing camera exposure
can hide whether the light or the exposure is wrong.

## Execute

1. Choose the rendering path and mobility.
2. Establish exposure and physical units.
3. Build broad environment light before local accents.
4. Add local lights with the smallest useful bounds.
5. Tune shadow softness with emitter size, not arbitrary intensity changes.
6. Inspect Lumen, exposure, shadow, and light-complexity visualizations.
7. Profile on target hardware.

Read:

- [`references/parameter-effects.md`](/unreal/unreal-lighting/parameter-effects/) for control behavior.
- [`references/recipes.md`](/unreal/unreal-lighting/recipes/) for concrete target looks.
- [`references/diagnostics.md`](/unreal/unreal-lighting/diagnostics/) for failures and performance.

## Required answer format

Return:

1. **Rendering/exposure assumptions**.
2. **Actor and component setup**.
3. **Ordered changes**, naming UE 5.8 properties and editor locations.
4. **Parameter direction**: what increasing or decreasing each value does.
5. **Starting values only when documented or physically grounded**; otherwise give a
   bounded tuning procedure.
6. **Debug views and console checks**.
7. **Performance validation** on the requested target.

Never prescribe an isolated intensity number without its light type, units, exposure,
distance, source size, and target platform.

## Hard rules

- Use Lux for Directional Light, cd/m² for Sky Light luminance, and Candela/Lumens for
  local lights when inverse-square falloff is enabled.
- Treat attenuation radius as an influence bound, not a brightness control.
- Treat exposure compensation in stops: `+1` doubles displayed brightness; `-1` halves it.
- Equal Min/Max EV100 disables auto exposure.
- With Lumen enabled, precomputed static lighting contributions are disabled/hidden.
- MegaLights handles local lights. Sky Light remains outside it. Directional Light support is
  opt-in with `r.MegaLights.DirectionalLights 1`, disabled by default, and has documented
  quality limitations; prefer Deferred Lighting with VSM for a strong sun unless target tests
  justify the MegaLights path.
- Narrow overlapping light bounds. MegaLights has fixed sampling; excessive local
  complexity reduces quality instead of scaling cost conventionally.
- Mark experimental features as experimental and provide a shippable fallback.
- Validate with visualizations and profiling, not the editor beauty view alone.

See [`references/sources.md`](/unreal/unreal-lighting/sources/) for the UE 5.8 source trail.

unreal 5.8 lighting design, tune, profile, and debug lighting in unreal engine 5.8. use for lumen gi and reflections, megalights, physical light units, exposure and eye adaptation, directional/sky/point/spot/rect lights, sky atmosphere, fog, clouds, shadows, interiors, exteriors, day-night scenes, mood targets, or lighting performance problems. diagnostics and validation diagnostics and validation | symptom | check | action | |---|---|---| | everything is too bright/dark | exposure mode, ev100, compensation | lock manual exposure; establish light values; then restore bounded adaptation | | bright object at screen edge pumps exposure | hdr histogram / metering | add center-weighted exposure metering mask or narrow histogram selection | | interior is black with lumen | surface cache/card coverage, mesh scale/topology | split overly complex meshes; verify distance fields and lumen representation | | light leaks through thin walls | lumen representation, wall thickness, shadow method | increase physical thickness; inspect distance fields; choose appropriate tracing/shadow path | | reflections miss objects | lumen reflection mode/scene representation | inspect lumen scene; consider hardware rt where target supports it | | soft shadow is wrong | source size, not intensity | tune source radius/width/height/angle | | local light costs too much | bounds, shadows, overlaps | reduce attenuation, disable unnecessary shadows, profile megalights versus conventional path | | megalights looks noisy/blurry | too many important overlapping lights per pixel | narrow bounds, merge small lights, reduce local complexity | | megalights ghosts in motion | denoiser under high stochastic complexity | simplify overlapping lights; test shadow method and temporal behavior | | fog glows everywhere | volumetric scattering and large light bounds | lower scattering; narrow bounds; remove irrelevant fog contribution | | day/night color looks fake | manual tint fights sky atmosphere | return sun toward neutral and let atmospheric scattering drive color | | emissive surface does not light enough | emissive is visible but gi contribution is insufficient/noisy | add a matching controlled light; do not rely on tiny bright emissives alone | | shadow acne/peter-panning | bias settings or geometry | inspect geometry/normals; tune bias minimally; verify vsm/ray-traced path | debug sequence 1. disable stylistic post effects that obscure diagnosis. 2. lock exposure. 3. inspect unlit/material values where relevant. 4. inspect hdr (eye adaptation). 5. inspect lumen overview, surface cache, and reflection views. 6. inspect shadow/vsm or ray-tracing debug views. 7. inspect light bounds and overlapping influence. 8. measure gpu timing on target hardware and intended scalability. 9. re-enable post effects one category at a time. acceptance checks - focal subject reads at gameplay camera distance. - exposure transitions behave intentionally in both directions. - direct, indirect, reflection, emissive, and volumetric contributions are identifiable. - no major light leaks, black lumen surfaces, temporal ghosting, or unstable pumping. - scene remains legible at required scalability tiers. - gpu cost meets the declared budget on target hardware. parameter effects parameter effects contents - light selection - core light properties - mobility - exposure - physical-unit anchors - lumen - megalights light selection | need | light | |---|---| | sun, moon, or effectively infinite source | directional light | | captured environment/sky contribution | sky light | | bare bulb or omnidirectional fixture | point light | | flashlight, headlamp, stage cone | spot light | | window, panel, fluorescent fixture, softbox | rect light | core light properties | property | increase | decrease / caution | |---|---|---| | intensity | more direct contribution in the selected physical unit | interpret only with exposure and distance | | temperature | cooler/bluer at higher kelvin | warmer/oranger at lower kelvin; avoid double-tinting a physically scattered sun unless stylized | | attenuation radius | affects more geometry and increases overlap | not a brightness control; keep close to useful influence | | source radius / soft source radius | larger apparent emitter; softer, broader shadows/reflections | excessive size can erase contact definition | | source length | elongates emitter and shadow softness | match tube/strip fixture shape | | indirect lighting intensity | scales bounced contribution from this light | nonphysical artistic override; debug gi before using | | volumetric scattering intensity | stronger effect in participating media | can create fog glow/noise and flatten contrast | | specular scale | changes specular response | keep at default for physical work; use only as a deliberate art override | spot light - inner cone angle: fully lit core. - outer cone angle: full edge of influence. - larger gap between inner and outer angles creates a softer penumbra. - use ies profiles for fixture distribution when available instead of hand-shaping every falloff. rect light - source width/height define emitter size and reflection shape. - use for windows and panels where emitter geometry matters. - face the emitting side toward the scene. mobility | mobility | use | cost/constraint | |---|---|---| | static | never changes; baked lightmass workflow | requires precomputed lighting; not useful as a lumen dynamic source | | stationary | color/intensity may change, transform stays fixed | mixed baked/dynamic constraints; overlapping stationary limits apply | | movable | transform and properties change at runtime | fully dynamic shadows; profile shadow path | for lumen-first fully dynamic projects, movable lights are the normal baseline. do not choose mobility from habit; choose it from the rendering path. exposure | control | effect | |---|---| | metering mode: manual | fixed exposure; camera/light comparison is stable | | histogram | 64-bin adaptive exposure; default adaptive mode | | exposure compensation | offset in stops; +1 = 2× brighter, -1 = 2× darker | | min/max ev100 | clamp adaptation range; equal values disable adaptation | | speed up | adaptation rate from dark environment/view to bright | | speed down | adaptation rate from bright environment/view to dark | | metering mask | weights screen regions; center weighting reduces edge-light pumping | | low/high percent | select histogram range used for target exposure; extreme values can destabilize or clip | workflow: 1. use manual exposure while establishing physically plausible lights. 2. enable hdr (eye adaptation) visualization. 3. if adaptation is required, set a purposeful min/max ev100 range. 4. set speed from desired perceptual behavior. 5. add a metering mask if peripheral bright objects cause pumping. 6. use local exposure only after global exposure and light values are sound. physical-unit anchors - ue documents a zenith sun around 120,000 lux with a 0.545° angular diameter. - a perpendicular white diffuse surface under that sun may receive roughly 150,000 lux total. - point/spot/rect lights can use candela or lumens when inverse-square falloff is on. - 1000 cd produces 1000 lux at one meter for a perpendicular receiver in the documented example. use real fixture specifications as starting points. do not compensate for incorrect exposure by multiplying every light arbitrarily. lumen - dynamic global illumination: lumen. - reflection method: lumen. - software tracing requires generate mesh distance fields. - hardware ray tracing improves representation/quality in supported cases but costs more and requires compatible hardware. - high scalability targets lumen gi/reflections for 60 fps on current-generation consoles; epic targets cleaner indoor lighting at 30 fps. - inspect surface cache/card visualization when meshes appear black or fail to bounce light. megalights - enable under project settings > rendering > direct lighting. - hardware ray tracing support is recommended. - all local lights are handled when enabled; disable per light with allow megalights. - directional light support is disabled by default. enable it with r.megalights.directionallights 1 only after testing: epic recommends deferred lighting with vsm for a strong sun, while megalights may fit a dim, soft moonlight. sky light is not handled. - select ray tracing or virtual shadow maps per light as shadow method. - disable by scalability/device profile with r.megalights.allow 0. - avoid huge light bounds. merge many tiny emitters when they create noise, blur, or ghosting at the same pixels. lighting recipes lighting recipes physically based clear daylight 1. add directional light, sky atmosphere, sky light, and optional volumetric clouds. 2. enable atmosphere sun light on the directional light. 3. set directional light in lux; use approximately 120,000 lux for a documented zenith sun starting point. 4. enable sky light real time capture for dynamic time of day. 5. start with manual exposure; inspect hdr eye adaptation values. 6. rotate the directional light for time of day before altering intensity/color. 7. enable bounded auto exposure only after the noon reference is stable. 8. verify shadow, atmosphere, cloud, lumen, and target-platform cost. golden hour 1. lower the directional light angle near the horizon. 2. let sky atmosphere produce longer optical paths and warm scattering first. 3. increase mie contribution/anisotropy only when the desired haze is missing; inspect silhouettes and aerial perspective. 4. preserve a cooler sky light/environment contrast unless the art target is uniformly warm. 5. use restrained exposure compensation; do not turn sunset into daylight brightness. 6. add local practicals only to guide focal hierarchy. night exterior that still reads as night 1. use a second atmospheric directional light for moon if required; set atmosphere sun light index appropriately. 2. reduce broad environment contribution rather than crushing blacks with post color. 3. clamp auto exposure so the camera cannot adapt the night back to daytime. 4. place local lights in purposeful pools; minimize attenuation overlap. 5. keep navigable silhouettes and landmark contrast. 6. check emissives at gameplay distance; use real lights when they must illuminate. 7. verify local-light noise/ghosting with megalights enabled. interior lit by windows 1. establish exterior directional/sky lighting and exposure. 2. use lumen for indirect bounce. 3. add rect lights at important apertures only when the dynamic solution needs an art- directed key or stronger directionality. 4. match rect light dimensions/orientation to the opening. 5. keep attenuation bounds inside the useful room volume. 6. inspect lumen surface cache and mesh modularity when interiors stay black. 7. compare interior-to-exterior exposure transition and set speed up/down intentionally. practical-lit interior 1. give emissive materials plausible luminance for visible fixture surfaces. 2. pair important fixtures with point/spot/rect lights for controlled illumination. 3. match source size and shape to the fixture. 4. use ies profiles for real fixture distributions where available. 5. limit attenuation to the room/area of influence. 6. with megalights, merge clusters that produce stochastic blur or ghosting at the same pixels. 7. test with fog/translucency because megalights includes those paths. horror or high-contrast scene 1. lock or tightly bound exposure; uncontrolled eye adaptation destroys authored darkness. 2. preserve readable navigation and interactable silhouettes. 3. use small areas of motivated light rather than globally lowering every value. 4. control source radius: smaller sources create harder, more threatening shadows; larger sources create softer ambiguity. 5. use volumetric scattering only where it supports composition. 6. test black-level visibility on the target display and scalability tiers. stylized scene 1. start from stable exposure and functional key/fill separation. 2. use temperature/color and indirect intensity as deliberate nonphysical controls. 3. keep values consistent by light role, not per-object improvisation. 4. validate material roughness and albedo before fixing every problem with lights. 5. preserve performance rules: bounded lights, intentional shadows, target profiling. ue 5.8 primary sources ue 5.8 primary sources - epic games, lighting the environment - epic games, physical lighting units - epic games, auto exposure - epic games, light types and mobility - epic games, lumen global illumination and reflections - epic games, lumen technical details - epic games, megalights - epic games, environmental light with fog, clouds, sky and atmosphere - epic games, sky atmosphere - epic games, shadowing version target: unreal engine 5.8. recheck defaults, scalability behavior, and feature status before using this skill with a later engine version.

Diagnostics and validation

# Diagnostics and validation

| Symptom | Check | Action |
|---|---|---|
| Everything is too bright/dark | Exposure mode, EV100, compensation | Lock Manual exposure; establish light values; then restore bounded adaptation |
| Bright object at screen edge pumps exposure | HDR histogram / metering | Add center-weighted Exposure Metering Mask or narrow histogram selection |
| Interior is black with Lumen | Surface Cache/Card coverage, mesh scale/topology | Split overly complex meshes; verify distance fields and Lumen representation |
| Light leaks through thin walls | Lumen representation, wall thickness, shadow method | Increase physical thickness; inspect distance fields; choose appropriate tracing/shadow path |
| Reflections miss objects | Lumen reflection mode/scene representation | Inspect Lumen scene; consider hardware RT where target supports it |
| Soft shadow is wrong | Source size, not intensity | Tune Source Radius/Width/Height/Angle |
| Local light costs too much | Bounds, shadows, overlaps | Reduce attenuation, disable unnecessary shadows, profile MegaLights versus conventional path |
| MegaLights looks noisy/blurry | Too many important overlapping lights per pixel | Narrow bounds, merge small lights, reduce local complexity |
| MegaLights ghosts in motion | Denoiser under high stochastic complexity | Simplify overlapping lights; test shadow method and temporal behavior |
| Fog glows everywhere | Volumetric scattering and large light bounds | Lower scattering; narrow bounds; remove irrelevant fog contribution |
| Day/night color looks fake | Manual tint fights Sky Atmosphere | Return sun toward neutral and let atmospheric scattering drive color |
| Emissive surface does not light enough | Emissive is visible but GI contribution is insufficient/noisy | Add a matching controlled light; do not rely on tiny bright emissives alone |
| Shadow acne/peter-panning | Bias settings or geometry | Inspect geometry/normals; tune bias minimally; verify VSM/ray-traced path |

## Debug sequence

1. Disable stylistic post effects that obscure diagnosis.
2. Lock exposure.
3. Inspect unlit/material values where relevant.
4. Inspect HDR (Eye Adaptation).
5. Inspect Lumen Overview, Surface Cache, and reflection views.
6. Inspect shadow/VSM or ray-tracing debug views.
7. Inspect light bounds and overlapping influence.
8. Measure GPU timing on target hardware and intended scalability.
9. Re-enable post effects one category at a time.

## Acceptance checks

- Focal subject reads at gameplay camera distance.
- Exposure transitions behave intentionally in both directions.
- Direct, indirect, reflection, emissive, and volumetric contributions are identifiable.
- No major light leaks, black Lumen surfaces, temporal ghosting, or unstable pumping.
- Scene remains legible at required scalability tiers.
- GPU cost meets the declared budget on target hardware.

Parameter effects

# Parameter effects

## Contents

- [Light selection](#light-selection)
- [Core light properties](#core-light-properties)
- [Mobility](#mobility)
- [Exposure](#exposure)
- [Physical-unit anchors](#physical-unit-anchors)
- [Lumen](#lumen)
- [MegaLights](#megalights)

## Light selection

| Need | Light |
|---|---|
| Sun, moon, or effectively infinite source | Directional Light |
| Captured environment/sky contribution | Sky Light |
| Bare bulb or omnidirectional fixture | Point Light |
| Flashlight, headlamp, stage cone | Spot Light |
| Window, panel, fluorescent fixture, softbox | Rect Light |

## Core light properties

| Property | Increase | Decrease / caution |
|---|---|---|
| Intensity | More direct contribution in the selected physical unit | Interpret only with exposure and distance |
| Temperature | Cooler/bluer at higher Kelvin | Warmer/oranger at lower Kelvin; avoid double-tinting a physically scattered sun unless stylized |
| Attenuation Radius | Affects more geometry and increases overlap | Not a brightness control; keep close to useful influence |
| Source Radius / Soft Source Radius | Larger apparent emitter; softer, broader shadows/reflections | Excessive size can erase contact definition |
| Source Length | Elongates emitter and shadow softness | Match tube/strip fixture shape |
| Indirect Lighting Intensity | Scales bounced contribution from this light | Nonphysical artistic override; debug GI before using |
| Volumetric Scattering Intensity | Stronger effect in participating media | Can create fog glow/noise and flatten contrast |
| Specular Scale | Changes specular response | Keep at default for physical work; use only as a deliberate art override |

### Spot Light

- Inner Cone Angle: fully lit core.
- Outer Cone Angle: full edge of influence.
- Larger gap between inner and outer angles creates a softer penumbra.
- Use IES profiles for fixture distribution when available instead of hand-shaping every
  falloff.

### Rect Light

- Source Width/Height define emitter size and reflection shape.
- Use for windows and panels where emitter geometry matters.
- Face the emitting side toward the scene.

## Mobility

| Mobility | Use | Cost/constraint |
|---|---|---|
| Static | Never changes; baked Lightmass workflow | Requires precomputed lighting; not useful as a Lumen dynamic source |
| Stationary | Color/intensity may change, transform stays fixed | Mixed baked/dynamic constraints; overlapping Stationary limits apply |
| Movable | Transform and properties change at runtime | Fully dynamic shadows; profile shadow path |

For Lumen-first fully dynamic projects, Movable lights are the normal baseline. Do not
choose mobility from habit; choose it from the rendering path.

## Exposure

| Control | Effect |
|---|---|
| Metering Mode: Manual | Fixed exposure; camera/light comparison is stable |
| Histogram | 64-bin adaptive exposure; default adaptive mode |
| Exposure Compensation | Offset in stops; `+1` = 2× brighter, `-1` = 2× darker |
| Min/Max EV100 | Clamp adaptation range; equal values disable adaptation |
| Speed Up | Adaptation rate from dark environment/view to bright |
| Speed Down | Adaptation rate from bright environment/view to dark |
| Metering Mask | Weights screen regions; center weighting reduces edge-light pumping |
| Low/High Percent | Select histogram range used for target exposure; extreme values can destabilize or clip |

Workflow:

1. Use Manual exposure while establishing physically plausible lights.
2. Enable HDR (Eye Adaptation) visualization.
3. If adaptation is required, set a purposeful Min/Max EV100 range.
4. Set speed from desired perceptual behavior.
5. Add a metering mask if peripheral bright objects cause pumping.
6. Use Local Exposure only after global exposure and light values are sound.

## Physical-unit anchors

- UE documents a zenith sun around **120,000 lux** with a 0.545° angular diameter.
- A perpendicular white diffuse surface under that sun may receive roughly **150,000
  lux** total.
- Point/Spot/Rect Lights can use Candela or Lumens when inverse-square falloff is on.
- `1000 cd` produces `1000 lux` at one meter for a perpendicular receiver in the
  documented example.

Use real fixture specifications as starting points. Do not compensate for incorrect
exposure by multiplying every light arbitrarily.

## Lumen

- Dynamic Global Illumination: Lumen.
- Reflection Method: Lumen.
- Software tracing requires Generate Mesh Distance Fields.
- Hardware ray tracing improves representation/quality in supported cases but costs
  more and requires compatible hardware.
- High scalability targets Lumen GI/reflections for 60 FPS on current-generation
  consoles; Epic targets cleaner indoor lighting at 30 FPS.
- Inspect Surface Cache/Card visualization when meshes appear black or fail to bounce
  light.

## MegaLights

- Enable under Project Settings > Rendering > Direct Lighting.
- Hardware ray tracing support is recommended.
- All local lights are handled when enabled; disable per light with `Allow MegaLights`.
- Directional Light support is disabled by default. Enable it with
  `r.MegaLights.DirectionalLights 1` only after testing: Epic recommends Deferred Lighting with
  VSM for a strong sun, while MegaLights may fit a dim, soft moonlight. Sky Light is not handled.
- Select Ray Tracing or Virtual Shadow Maps per light as shadow method.
- Disable by scalability/device profile with `r.MegaLights.Allow 0`.
- Avoid huge light bounds. Merge many tiny emitters when they create noise, blur, or
  ghosting at the same pixels.

Lighting recipes

# Lighting recipes

## Physically based clear daylight

1. Add Directional Light, Sky Atmosphere, Sky Light, and optional Volumetric Clouds.
2. Enable Atmosphere Sun Light on the Directional Light.
3. Set Directional Light in Lux; use approximately 120,000 lux for a documented zenith
   sun starting point.
4. Enable Sky Light Real Time Capture for dynamic time of day.
5. Start with Manual exposure; inspect HDR Eye Adaptation values.
6. Rotate the Directional Light for time of day before altering intensity/color.
7. Enable bounded auto exposure only after the noon reference is stable.
8. Verify shadow, atmosphere, cloud, Lumen, and target-platform cost.

## Golden hour

1. Lower the Directional Light angle near the horizon.
2. Let Sky Atmosphere produce longer optical paths and warm scattering first.
3. Increase Mie contribution/anisotropy only when the desired haze is missing; inspect
   silhouettes and aerial perspective.
4. Preserve a cooler Sky Light/environment contrast unless the art target is uniformly
   warm.
5. Use restrained exposure compensation; do not turn sunset into daylight brightness.
6. Add local practicals only to guide focal hierarchy.

## Night exterior that still reads as night

1. Use a second atmospheric Directional Light for moon if required; set Atmosphere Sun
   Light Index appropriately.
2. Reduce broad environment contribution rather than crushing blacks with post color.
3. Clamp auto exposure so the camera cannot adapt the night back to daytime.
4. Place local lights in purposeful pools; minimize attenuation overlap.
5. Keep navigable silhouettes and landmark contrast.
6. Check emissives at gameplay distance; use real lights when they must illuminate.
7. Verify local-light noise/ghosting with MegaLights enabled.

## Interior lit by windows

1. Establish exterior Directional/Sky lighting and exposure.
2. Use Lumen for indirect bounce.
3. Add Rect Lights at important apertures only when the dynamic solution needs an art-
   directed key or stronger directionality.
4. Match Rect Light dimensions/orientation to the opening.
5. Keep attenuation bounds inside the useful room volume.
6. Inspect Lumen Surface Cache and mesh modularity when interiors stay black.
7. Compare interior-to-exterior exposure transition and set Speed Up/Down intentionally.

## Practical-lit interior

1. Give emissive materials plausible luminance for visible fixture surfaces.
2. Pair important fixtures with Point/Spot/Rect Lights for controlled illumination.
3. Match source size and shape to the fixture.
4. Use IES profiles for real fixture distributions where available.
5. Limit attenuation to the room/area of influence.
6. With MegaLights, merge clusters that produce stochastic blur or ghosting at the same
   pixels.
7. Test with fog/translucency because MegaLights includes those paths.

## Horror or high-contrast scene

1. Lock or tightly bound exposure; uncontrolled eye adaptation destroys authored
   darkness.
2. Preserve readable navigation and interactable silhouettes.
3. Use small areas of motivated light rather than globally lowering every value.
4. Control source radius: smaller sources create harder, more threatening shadows;
   larger sources create softer ambiguity.
5. Use volumetric scattering only where it supports composition.
6. Test black-level visibility on the target display and scalability tiers.

## Stylized scene

1. Start from stable exposure and functional key/fill separation.
2. Use temperature/color and indirect intensity as deliberate nonphysical controls.
3. Keep values consistent by light role, not per-object improvisation.
4. Validate material roughness and albedo before fixing every problem with lights.
5. Preserve performance rules: bounded lights, intentional shadows, target profiling.

UE 5.8 primary sources

# UE 5.8 primary sources

- Epic Games, [Lighting the Environment](https://dev.epicgames.com/documentation/en-us/unreal-engine/lighting-the-environment-in-unreal-engine)
- Epic Games, [Physical Lighting Units](https://dev.epicgames.com/documentation/unreal-engine/using-physical-lighting-units-in-unreal-engine)
- Epic Games, [Auto Exposure](https://dev.epicgames.com/documentation/en-us/unreal-engine/auto-exposure-in-unreal-engine)
- Epic Games, [Light Types and Mobility](https://dev.epicgames.com/documentation/en-us/unreal-engine/light-types-and-their-mobility-in-unreal-engine)
- Epic Games, [Lumen Global Illumination and Reflections](https://dev.epicgames.com/documentation/en-us/unreal-engine/lumen-global-illumination-and-reflections-in-unreal-engine)
- Epic Games, [Lumen Technical Details](https://dev.epicgames.com/documentation/unreal-engine/lumen-technical-details-in-unreal-engine)
- Epic Games, [MegaLights](https://dev.epicgames.com/documentation/en-us/unreal-engine/megalights-in-unreal-engine)
- Epic Games, [Environmental Light with Fog, Clouds, Sky and Atmosphere](https://dev.epicgames.com/documentation/en-us/unreal-engine/environmental-light-with-fog-clouds-sky-and-atmosphere-in-unreal-engine)
- Epic Games, [Sky Atmosphere](https://dev.epicgames.com/documentation/en-us/unreal-engine/sky-atmosphere-component-in-unreal-engine)
- Epic Games, [Shadowing](https://dev.epicgames.com/documentation/en-us/unreal-engine/shadowing-in-unreal-engine)

Version target: Unreal Engine 5.8. Recheck defaults, scalability behavior, and feature
status before using this skill with a later engine version.


unreal-materials

Unreal 5.8 Materials

Build, tune, and profile Unreal materials

---
name: unreal-materials
description: Select, build, parameterize, layer, profile, and debug materials in Unreal Engine 5.8. Use for PBR inputs, blend modes, shading models, parent materials, instances, functions, static switches, Material Layers, Substrate, decals, Runtime Virtual Textures, Custom Primitive Data, animated material effects, shader permutations, overdraw, or material performance.
---

# Unreal 5.8 Materials

## Ownership boundary

This skill owns surface/shader graph architecture and material parameter behavior. Route artistic
light/exposure/atmosphere setup to [`unreal-lighting`](../unreal-lighting/SKILL.md). If material cost is
only suspected, start with [`unreal-insights-profiling`](../unreal-insights-profiling/SKILL.md); route a
measured render/GPU optimization to
[`unreal-rendering-performance`](../unreal-rendering-performance/SKILL.md).

## Select the architecture first

Read [`references/architecture-selector.md`](references/architecture-selector.md).

- Shared surface family -> parent Material + Material Instances.
- Reusable graph behavior -> Material Function.
- Artist-reorderable surface stack -> Material Layers.
- Global world state -> Material Parameter Collection.
- Per-object variation without unique dynamic instances -> Custom Primitive Data.
- Large static terrain shading cache -> Runtime Virtual Texture.
- Local projected breakup/damage -> decal.

Do not begin from a universal master material. Begin from a bounded surface family and measured
platform needs.

## Execute

1. State the target look, geometry, lighting path, platform, and performance constraints.
2. Choose Material Domain, Blend Mode, Shading Model, and Two Sided behavior before graph work.
3. Build a physically coherent minimum surface and validate texture import/sampler assumptions.
4. Expose only parameters that represent intentional art controls.
5. Extract reused logic into documented functions; use static branching sparingly.
6. Add layers, decals, RVT, WPO, or translucency only when the use case requires them.
7. Test representative instances and worst-case screen coverage.
8. Inspect compile stats, permutations, Shader Complexity/overdraw, and target hardware.

Load only the relevant reference:

- [`references/pbr-and-properties.md`](references/pbr-and-properties.md)
- [`references/instances-functions-and-data.md`](references/instances-functions-and-data.md)
- [`references/layers-substrate-and-decals.md`](references/layers-substrate-and-decals.md)
- [`references/rvt-and-world-effects.md`](references/rvt-and-world-effects.md)
- [`references/effect-recipes.md`](references/effect-recipes.md)
- [`references/profiling-and-debugging.md`](references/profiling-and-debugging.md)

## Required answer format

Return:

1. **Chosen material architecture** and rejected alternatives.
2. **Domain, blend, shading, lighting, and platform assumptions**.
3. **Graph/function/layer structure in evaluation order**.
4. **Parameters with units/ranges and visual effect of increase/decrease**.
5. **Texture, UV, normal, and color-space requirements**.
6. **Permutation, overdraw, memory, WPO, RVT, and lighting consequences**.
7. **Debug views and acceptance shots on target hardware**.

## Hard rules

- Choose blend mode and shading model intentionally; they control available inputs and passes.
- Treat Base Color, Metallic, Roughness, and Specular as physically related inputs, not arbitrary style sliders.
- Use instances for variations and functions for reusable logic; document function inputs/outputs.
- Static parameters create compile-time variants. Audit them; do not expose every feature as a switch.
- Prefer masked over translucent when the look allows it; measure overlapping transparency.
- WPO changes vertices and bounds, not collision. Expand bounds only as much as required.
- Use RVT for suitable mostly static large-area shading; not as a continuously refreshed animation buffer.
- Validate decals on the actual rendering path and receiving material settings.
- Shader instruction count is a clue, not complete timing; profile target hardware and screen coverage.
- Keep lighting diagnosis in `unreal-lighting`; this skill owns surface response.

See [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Ownership boundary

This skill owns surface/shader graph architecture and material parameter behavior. Route artistic
light/exposure/atmosphere setup to [`unreal-lighting`](/unreal/unreal-lighting/). If material cost is
only suspected, start with [`unreal-insights-profiling`](/unreal/unreal-insights-profiling/); route a
measured render/GPU optimization to
[`unreal-rendering-performance`](/unreal/unreal-rendering-performance/).

## Select the architecture first

Read [`references/architecture-selector.md`](/unreal/unreal-materials/architecture-selector/).

- Shared surface family -> parent Material + Material Instances.
- Reusable graph behavior -> Material Function.
- Artist-reorderable surface stack -> Material Layers.
- Global world state -> Material Parameter Collection.
- Per-object variation without unique dynamic instances -> Custom Primitive Data.
- Large static terrain shading cache -> Runtime Virtual Texture.
- Local projected breakup/damage -> decal.

Do not begin from a universal master material. Begin from a bounded surface family and measured
platform needs.

## Execute

1. State the target look, geometry, lighting path, platform, and performance constraints.
2. Choose Material Domain, Blend Mode, Shading Model, and Two Sided behavior before graph work.
3. Build a physically coherent minimum surface and validate texture import/sampler assumptions.
4. Expose only parameters that represent intentional art controls.
5. Extract reused logic into documented functions; use static branching sparingly.
6. Add layers, decals, RVT, WPO, or translucency only when the use case requires them.
7. Test representative instances and worst-case screen coverage.
8. Inspect compile stats, permutations, Shader Complexity/overdraw, and target hardware.

Load only the relevant reference:

- [`references/pbr-and-properties.md`](/unreal/unreal-materials/pbr-and-properties/)
- [`references/instances-functions-and-data.md`](/unreal/unreal-materials/instances-functions-and-data/)
- [`references/layers-substrate-and-decals.md`](/unreal/unreal-materials/layers-substrate-and-decals/)
- [`references/rvt-and-world-effects.md`](/unreal/unreal-materials/rvt-and-world-effects/)
- [`references/effect-recipes.md`](/unreal/unreal-materials/effect-recipes/)
- [`references/profiling-and-debugging.md`](/unreal/unreal-materials/profiling-and-debugging/)

## Required answer format

Return:

1. **Chosen material architecture** and rejected alternatives.
2. **Domain, blend, shading, lighting, and platform assumptions**.
3. **Graph/function/layer structure in evaluation order**.
4. **Parameters with units/ranges and visual effect of increase/decrease**.
5. **Texture, UV, normal, and color-space requirements**.
6. **Permutation, overdraw, memory, WPO, RVT, and lighting consequences**.
7. **Debug views and acceptance shots on target hardware**.

## Hard rules

- Choose blend mode and shading model intentionally; they control available inputs and passes.
- Treat Base Color, Metallic, Roughness, and Specular as physically related inputs, not arbitrary style sliders.
- Use instances for variations and functions for reusable logic; document function inputs/outputs.
- Static parameters create compile-time variants. Audit them; do not expose every feature as a switch.
- Prefer masked over translucent when the look allows it; measure overlapping transparency.
- WPO changes vertices and bounds, not collision. Expand bounds only as much as required.
- Use RVT for suitable mostly static large-area shading; not as a continuously refreshed animation buffer.
- Validate decals on the actual rendering path and receiving material settings.
- Shader instruction count is a clue, not complete timing; profile target hardware and screen coverage.
- Keep lighting diagnosis in `unreal-lighting`; this skill owns surface response.

See [`references/sources.md`](/unreal/unreal-materials/sources/) for the UE 5.8 source trail.

unreal 5.8 materials select, build, parameterize, layer, profile, and debug materials in unreal engine 5.8. use for pbr inputs, blend modes, shading models, parent materials, instances, functions, static switches, material layers, substrate, decals, runtime virtual textures, custom primitive data, animated material effects, shader permutations, overdraw, or material performance. material architecture selector material architecture selector | need | use | cost/risk to check | |---|---|---| | variants of one surface family | parent + material instances | parent scope, static permutations | | repeated math or mapping | material function | propagation to every caller | | reorderable artist-facing layers | material layers | per-pixel layer cost and masks | | global scalar/vector state | material parameter collection | global coupling; not per-object | | unique values per primitive/instance | custom primitive data | index contract and update ownership | | landscape/object blending cache | rvt | page memory, uploads, static suitability | | local grime/damage/signage | dbuffer/deferred decal | receiving response, overlap, sort | | complex physical bsdf composition | substrate | project/platform support and cost | | one-off simple surface | direct material | avoid needless framework overhead | before choosing, answer: - how many assets and variants share the logic? - which parameters vary globally, per material, per object, or per frame? - does the choice create new shader permutations or only runtime uniform values? - is the surface opaque, masked, or truly translucent? - what is the largest screen coverage and overlap count? split parent families when domains, blend modes, shading models, or platform feature sets differ. material effect recipes material effect recipes dissolve / reveal compare a stable mask/noise field with a scalar threshold. use masked blend when a hard clipped edge is acceptable. derive a narrow edge band from the threshold difference for emissive/color. expose threshold, edge width, edge color/intensity, and coordinate controls. test temporal aliasing, shadows, depth, and bounds if wpo accompanies the dissolve. hit flash / selection pulse drive a scalar/vector parameter from gameplay on the owning material instance or primitive data. blend a bounded tint/emissive contribution over the existing surface. restore/default the value explicitly; do not continuously create new dynamic instances. uv panning / flow use time and panner (or equivalent math) with parameterized direction and speed. keep units and coordinate space explicit. for networked cosmetic effects, synchronize an event/start time only when visual phase agreement matters. triplanar/world-aligned texture blend projections by surface normal for assets lacking suitable uvs or for consistent world scale. it increases texture samples; reserve it for surfaces where seams or authoring cost justify it. foliage wind apply wpo weighted by vertex mask, keeping attachment points stable. parameterize amplitude and frequency, then test bounds, shadow stability, lod transitions, and worst-case instance counts. distance/quality reduction remove the cost that matters: texture reads, per-pixel layers, expensive math, or wpo. quality switches produce additional permutations and are not simultaneous distance lods. verify with the material stats and on hardware rather than assuming the simpler-looking graph is faster. instances, functions, and parameter data instances, functions, and parameter data parent and instances 1. define a bounded family: for example opaque hard surface, foliage, or translucent vfx. 2. put invariant graph structure in the parent. 3. convert only intentional art controls to scalar, vector, texture, or static parameters. 4. group and describe parameters; give safe defaults. 5. create material instances for asset variations. 6. use dynamic instances only when values must change on that object at runtime. static switches remove an inactive branch from a compiled variant but each distinct combination can create another shader permutation. use material analyzer (tools -> audit -> material analyzer) to inspect descendants, static overrides, and opportunities to reparent common configurations. material functions - package repeated calculations, not arbitrary portions of a graph. - name and describe every input/output; set meaningful preview defaults cautiously. - enable expose to library and choose a concise category for team functions. - apply/save changes deliberately: edits propagate to loaded callers, and deleted pins break links. - duplicate engine/default functions before modifying them. - avoid circular function dependencies. parameter ownership - material instance: per material/asset variant. - dynamic material instance: per runtime material slot/component. - custom primitive data: per primitive values exposed to a shared material. - material parameter collection: global or level-wide scalar/vector state. do not use a global collection for actor-local state or spawn a dynamic instance for every object when primitive data or instancing can express the variation. layers, substrate, and decals layers, substrate, and decals layering use material functions with material attributes when the graph author owns a fixed blend architecture. use material layers when artists need to reorder, swap, and tune layers in the material instance editor. every extra per-pixel layer and mask still has a rendering cost. for each layer define: - physical surface contribution; - blend mask source and coordinate space; - normal-combination method; - which values remain exposed; - fallback for lower quality/platform tiers. substrate use substrate when the surface requires bsdf composition that the conventional shading model cannot express cleanly. confirm project enablement, platform support, material complexity, and the ue 5.8 production decision before making it a shared dependency. do not migrate a simple surface merely because the framework is newer. decals 1. create a material with deferred decal domain and the required decal blend response. 2. display it through a decal actor/component or decal mesh. 3. confirm the receiving materials respond to the relevant dbuffer channels. 4. use sort priority only where overlap order matters; avoid a proliferation of unique priorities. 5. inspect angle stretch, projection depth, fade distance, overlap, and target-platform path. dbuffer is the default decal path for ue5 projects. decals are suited to localized breakup, grime, damage, and signage; do not replace base material structure with thousands of overlapping full-screen projections. pbr inputs and material properties pbr inputs and material properties minimum surface 1. select the material domain for the job: surface unless it is explicitly decal, light function, post process, ui, or another specialized domain. 2. choose blend mode. use opaque by default, masked for binary coverage, and translucent only when partial transmission is required. 3. choose the shading model that represents the surface response. 4. set two sided only when backfaces must render and the lighting result is acceptable. 5. connect base color, metallic, roughness, normal, and optional emissive/ao inputs. input meaning - base color: intrinsic surface color, without baked directional lighting. - metallic: normally 0 for dielectric or 1 for metal; avoid unexplained mid-values. - roughness: low sharpens reflections; high broadens them. - specular: dielectric specular level; leave the physically reasonable default unless the material calls for a measured exception. - normal: fine lighting orientation; verify tangent-space import and sampler type. - emissive: emitted radiance appearance; it is not a free replacement for actual lighting. - opacity mask: compared with clip threshold in masked mode. texture gates - color textures use the correct srgb interpretation; packed masks/data usually do not. - normal textures use the normal sampler/compression path. - confirm channel packing, uv set, tiling, addressing, mip behavior, and streaming size. - test at near, typical, and far viewing distances under representative neutral lighting. if an input is disabled, inspect domain, blend mode, and shading model before rebuilding the graph. profiling and debugging profiling and debugging visual defect ladder 1. preview texture channels and constants independently. 2. verify uv set/scale and object/world/tangent coordinate spaces. 3. verify srgb, normal sampler, compression, channel packing, and mip level. 4. reduce the graph to the minimum surface; re-enable functions/layers one at a time. 5. test neutral direct lighting before blaming the material or lighting system. 6. inspect bounds, decals, rvt writer/receiver assignment, and platform feature switches. cost ladder 1. record target resolution, view, material screen coverage, and overlapping transparency. 2. use material editor stats/platform stats for compiled shader information. 3. use shader complexity (alt+8) to locate costly pixel regions and particle/translucency overdraw. 4. use material analyzer for static-switch/permutation families. 5. use gpu profiling/insights on target hardware to verify actual passes and time. 6. change one suspected cost and compare the same capture. instruction count alone misses important differences such as texture fetches, bandwidth, divergent work, and vertex cost. a costly pixel shader matters most over large screen area; wpo/vertex work matters for every submitted vertex. translucent layers can repeatedly shade the same pixel. common causes: - pink/checker/default material -> compile error, missing shader, unsupported path. - flat/no normal response -> sampler/import type or tangent basis. - dark/bright mismatch -> color-space or packed-channel error. - flickering displacement -> bounds, precision, temporal aliasing, or lod discontinuity. - shader compile explosion -> unconstrained static switches and instance override combinations. runtime virtual textures and world effects runtime virtual textures and world effects rvt workflow 1. create a runtime virtual texture asset with the required material type/resolution. 2. add and size an rvt volume; assign the rvt asset. 3. configure writer materials with rvt output expressions. 4. configure receiving materials with rvt sample or rvt sample parameter. 5. assign the rvt asset to components that render into it. 6. verify main-pass behavior, virtual-texture support fallback, mips, memory, and page uploads. good writers are mostly static large-area contributors: landscape, landscape splines, static meshes, instances, and foliage. skeletal, movable, and frequently animated writers are poor fits because rvt acts as a shading cache rather than a fully refreshed render target. use ycocg base-color storage when smooth-gradient color quality justifies roughly 25% extra memory and decode cost. if overlapping writers disappear or order incorrectly, inspect translucency sort priority; equal priority order is undefined. world-space effects - global wetness/snow value -> material parameter collection. - local accumulation around many objects -> primitive data, masks, decals, or rvt according to scale. - vertex wind/displacement -> wpo with explicit amplitude, bounds, lod, shadow, and nanite checks. - camera-distance simplification -> explicit quality/lod design, not an unmeasured chain of branches. wpo does not move collision. when gameplay requires changed collision, modify the owning geometry or gameplay representation, not only the shader. ue 5.8 primary sources ue 5.8 primary sources - materials - material inputs - creating and using material instances - material functions - creating and using material functions - layering materials - using material layers - material parameter collections - decal materials - runtime virtual texturing - material analyzer - viewport modes / shader complexity - transparency - scalability reference pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, platform support, and shader behavior after an engine upgrade.

Material architecture selector

# Material architecture selector

| Need | Use | Cost/risk to check |
|---|---|---|
| Variants of one surface family | Parent + Material Instances | parent scope, static permutations |
| Repeated math or mapping | Material Function | propagation to every caller |
| Reorderable artist-facing layers | Material Layers | per-pixel layer cost and masks |
| Global scalar/vector state | Material Parameter Collection | global coupling; not per-object |
| Unique values per primitive/instance | Custom Primitive Data | index contract and update ownership |
| Landscape/object blending cache | RVT | page memory, uploads, static suitability |
| Local grime/damage/signage | DBuffer/deferred decal | receiving response, overlap, sort |
| Complex physical BSDF composition | Substrate | project/platform support and cost |
| One-off simple surface | Direct Material | avoid needless framework overhead |

Before choosing, answer:

- How many assets and variants share the logic?
- Which parameters vary globally, per material, per object, or per frame?
- Does the choice create new shader permutations or only runtime uniform values?
- Is the surface opaque, masked, or truly translucent?
- What is the largest screen coverage and overlap count?

Split parent families when domains, blend modes, shading models, or platform feature sets differ.

Material effect recipes

# Material effect recipes

## Dissolve / reveal

Compare a stable mask/noise field with a scalar threshold. Use Masked blend when a hard clipped
edge is acceptable. Derive a narrow edge band from the threshold difference for emissive/color.
Expose threshold, edge width, edge color/intensity, and coordinate controls. Test temporal aliasing,
shadows, depth, and bounds if WPO accompanies the dissolve.

## Hit flash / selection pulse

Drive a scalar/vector parameter from gameplay on the owning material instance or primitive data.
Blend a bounded tint/emissive contribution over the existing surface. Restore/default the value
explicitly; do not continuously create new dynamic instances.

## UV panning / flow

Use Time and Panner (or equivalent math) with parameterized direction and speed. Keep units and
coordinate space explicit. For networked cosmetic effects, synchronize an event/start time only
when visual phase agreement matters.

## Triplanar/world-aligned texture

Blend projections by surface normal for assets lacking suitable UVs or for consistent world scale.
It increases texture samples; reserve it for surfaces where seams or authoring cost justify it.

## Foliage wind

Apply WPO weighted by vertex mask, keeping attachment points stable. Parameterize amplitude and
frequency, then test bounds, shadow stability, LOD transitions, and worst-case instance counts.

## Distance/quality reduction

Remove the cost that matters: texture reads, per-pixel layers, expensive math, or WPO. Quality
switches produce additional permutations and are not simultaneous distance LODs. Verify with the
material stats and on hardware rather than assuming the simpler-looking graph is faster.

# Instances, functions, and parameter data

## Parent and instances

1. Define a bounded family: for example opaque hard surface, foliage, or translucent VFX.
2. Put invariant graph structure in the parent.
3. Convert only intentional art controls to scalar, vector, texture, or static parameters.
4. Group and describe parameters; give safe defaults.
5. Create Material Instances for asset variations.
6. Use dynamic instances only when values must change on that object at runtime.

Static switches remove an inactive branch from a compiled variant but each distinct combination
can create another shader permutation. Use Material Analyzer (Tools -> Audit -> Material Analyzer)
to inspect descendants, static overrides, and opportunities to reparent common configurations.

## Material Functions

- Package repeated calculations, not arbitrary portions of a graph.
- Name and describe every input/output; set meaningful preview defaults cautiously.
- Enable Expose to Library and choose a concise category for team functions.
- Apply/save changes deliberately: edits propagate to loaded callers, and deleted pins break links.
- Duplicate engine/default functions before modifying them.
- Avoid circular function dependencies.

## Parameter ownership

- Material Instance: per material/asset variant.
- Dynamic Material Instance: per runtime material slot/component.
- Custom Primitive Data: per primitive values exposed to a shared material.
- Material Parameter Collection: global or level-wide scalar/vector state.

Do not use a global collection for actor-local state or spawn a dynamic instance for every object
when primitive data or instancing can express the variation.

Layers, Substrate, and decals

# Layers, Substrate, and decals

## Layering

Use Material Functions with Material Attributes when the graph author owns a fixed blend
architecture. Use Material Layers when artists need to reorder, swap, and tune layers in the
Material Instance Editor. Every extra per-pixel layer and mask still has a rendering cost.

For each layer define:

- physical surface contribution;
- blend mask source and coordinate space;
- normal-combination method;
- which values remain exposed;
- fallback for lower quality/platform tiers.

## Substrate

Use Substrate when the surface requires BSDF composition that the conventional shading model
cannot express cleanly. Confirm project enablement, platform support, material complexity, and
the UE 5.8 production decision before making it a shared dependency. Do not migrate a simple
surface merely because the framework is newer.

## Decals

1. Create a material with Deferred Decal domain and the required decal blend response.
2. Display it through a Decal Actor/component or decal mesh.
3. Confirm the receiving materials respond to the relevant DBuffer channels.
4. Use sort priority only where overlap order matters; avoid a proliferation of unique priorities.
5. Inspect angle stretch, projection depth, fade distance, overlap, and target-platform path.

DBuffer is the default decal path for UE5 projects. Decals are suited to localized breakup,
grime, damage, and signage; do not replace base material structure with thousands of overlapping
full-screen projections.

PBR inputs and material properties

# PBR inputs and material properties

## Minimum surface

1. Select the Material Domain for the job: Surface unless it is explicitly decal, light function,
   post process, UI, or another specialized domain.
2. Choose Blend Mode. Use Opaque by default, Masked for binary coverage, and Translucent only
   when partial transmission is required.
3. Choose the Shading Model that represents the surface response.
4. Set Two Sided only when backfaces must render and the lighting result is acceptable.
5. Connect Base Color, Metallic, Roughness, Normal, and optional Emissive/AO inputs.

## Input meaning

- **Base Color**: intrinsic surface color, without baked directional lighting.
- **Metallic**: normally 0 for dielectric or 1 for metal; avoid unexplained mid-values.
- **Roughness**: low sharpens reflections; high broadens them.
- **Specular**: dielectric specular level; leave the physically reasonable default unless the
  material calls for a measured exception.
- **Normal**: fine lighting orientation; verify tangent-space import and sampler type.
- **Emissive**: emitted radiance appearance; it is not a free replacement for actual lighting.
- **Opacity Mask**: compared with clip threshold in Masked mode.

## Texture gates

- Color textures use the correct sRGB interpretation; packed masks/data usually do not.
- Normal textures use the Normal sampler/compression path.
- Confirm channel packing, UV set, tiling, addressing, mip behavior, and streaming size.
- Test at near, typical, and far viewing distances under representative neutral lighting.

If an input is disabled, inspect Domain, Blend Mode, and Shading Model before rebuilding the graph.

Profiling and debugging

# Profiling and debugging

## Visual defect ladder

1. Preview texture channels and constants independently.
2. Verify UV set/scale and object/world/tangent coordinate spaces.
3. Verify sRGB, normal sampler, compression, channel packing, and mip level.
4. Reduce the graph to the minimum surface; re-enable functions/layers one at a time.
5. Test neutral direct lighting before blaming the material or lighting system.
6. Inspect bounds, decals, RVT writer/receiver assignment, and platform feature switches.

## Cost ladder

1. Record target resolution, view, material screen coverage, and overlapping transparency.
2. Use Material Editor stats/platform stats for compiled shader information.
3. Use Shader Complexity (`Alt+8`) to locate costly pixel regions and particle/translucency overdraw.
4. Use Material Analyzer for static-switch/permutation families.
5. Use GPU profiling/Insights on target hardware to verify actual passes and time.
6. Change one suspected cost and compare the same capture.

Instruction count alone misses important differences such as texture fetches, bandwidth, divergent
work, and vertex cost. A costly pixel shader matters most over large screen area; WPO/vertex work
matters for every submitted vertex. Translucent layers can repeatedly shade the same pixel.

Common causes:

- Pink/checker/default material -> compile error, missing shader, unsupported path.
- Flat/no normal response -> sampler/import type or tangent basis.
- Dark/bright mismatch -> color-space or packed-channel error.
- Flickering displacement -> bounds, precision, temporal aliasing, or LOD discontinuity.
- Shader compile explosion -> unconstrained static switches and instance override combinations.

# Runtime Virtual Textures and world effects

## RVT workflow

1. Create a Runtime Virtual Texture asset with the required material type/resolution.
2. Add and size an RVT Volume; assign the RVT asset.
3. Configure writer materials with RVT output expressions.
4. Configure receiving materials with RVT Sample or RVT Sample Parameter.
5. Assign the RVT asset to components that render into it.
6. Verify main-pass behavior, virtual-texture support fallback, mips, memory, and page uploads.

Good writers are mostly static large-area contributors: Landscape, Landscape Splines, static
meshes, instances, and foliage. Skeletal, movable, and frequently animated writers are poor fits
because RVT acts as a shading cache rather than a fully refreshed render target.

Use YCoCg base-color storage when smooth-gradient color quality justifies roughly 25% extra
memory and decode cost. If overlapping writers disappear or order incorrectly, inspect
Translucency Sort Priority; equal priority order is undefined.

## World-space effects

- Global wetness/snow value -> Material Parameter Collection.
- Local accumulation around many objects -> primitive data, masks, decals, or RVT according to scale.
- Vertex wind/displacement -> WPO with explicit amplitude, bounds, LOD, shadow, and Nanite checks.
- Camera-distance simplification -> explicit quality/LOD design, not an unmeasured chain of branches.

WPO does not move collision. When gameplay requires changed collision, modify the owning geometry
or gameplay representation, not only the shader.

UE 5.8 primary sources

# UE 5.8 primary sources

- [Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-materials)
- [Material Inputs](https://dev.epicgames.com/documentation/en-us/unreal-engine/material-inputs-in-unreal-engine)
- [Creating and Using Material Instances](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-and-using-material-instances-in-unreal-engine)
- [Material Functions](https://dev.epicgames.com/documentation/en-us/unreal-engine/material-functions-in-unreal-engine)
- [Creating and Using Material Functions](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-and-using-material-functions-in-unreal-engine)
- [Layering Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/layering-materials-in-unreal-engine)
- [Using Material Layers](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-material-layers-in-unreal-engine)
- [Material Parameter Collections](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-material-parameter-collections-in-unreal-engine)
- [Decal Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/decal-materials-in-unreal-engine)
- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)
- [Material Analyzer](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-material-analyzer-tool)
- [Viewport Modes / Shader Complexity](https://dev.epicgames.com/documentation/en-us/unreal-engine/viewport-modes-in-unreal-engine)
- [Transparency](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-transparency-in-unreal-engine-materials)
- [Scalability Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/scalability-reference-for-unreal-engine)

Pages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,
platform support, and shader behavior after an engine upgrade.