Material To Shader Artist Guide

This guide explains how lookdev and technical artists author material intent that compiles cleanly into the Maya renderer shader pipeline. It is written for daily material review, not engine implementation work.

Source Of Truth#

The renderer pipeline source of truth is V2/docs/rendering/maya-shader-pipeline.md. Artist material graphs are edited through material_graph_editor, evaluated by material_eval, and lowered into WGSL-backed shader sources owned by shader_source_management.

Use this guide with these validation artifacts:

• V2/ue/Build/Shaders/v2-maya-shader-pipeline-documentation.json
• V2/ue/Build/Shaders/v2-maya-shader-complexity-analysis.json
• V2/ue/Build/Shaders/v2-maya-shader-binary-size-tracking.json
• V2/ue/Build/Shaders/v2-maya-shader-compilation-error-reporting.json
• V2/ue/Tools/check-v2-maya-shader-pipeline-documentation.py

Material Intent Checklist#

Every material handoff must state the intended surface class and the reason for each non-default feature. Use stable, reviewable language:

• Surface class: opaque PBR, clear coat, glass, water, emissive, post-process, light function, or special gameplay material.
• Lighting intent: unlit, lit, subsurface-like, reflective, transparent, or refractive.
• Runtime variation: damage, sweat, cloth, hair, team color, accessibility theme, weather, time of day, or cinematic override.
• Texture set: base color, normal, roughness, metallic, ambient occlusion, emissive, opacity, packed masks, and any authored lookup texture.
• Platform expectation: PC and console default, mobile-style fallback, cinematic only, or debug only.

If a feature is not visible in the final shot or gameplay camera, keep it out of the material graph. Hidden branches still create shader cost.

Material Graph To Shader Mapping#

The graph editor works best when artist graphs map cleanly to shader concepts:

Keep graph structure readable. Prefer named intermediate nodes for reusable concepts such as "sweat mask", "cloth tint", or "rim intensity". Avoid using generic names like "Multiply 14" in content submitted for review.

Parameters And Naming#

Parameter names become part of reviews, debug reports, and shader triage. Use lower snake case for material parameter ids and title case for artist labels. The required review phrase is parameter ids labels ranges units owners fallback values.

Required parameter metadata:

• parameter_id: stable lower snake case such as damage_blend.
• artist_label: concise label such as Damage Blend.
• value_range: min, max, and default for scalar controls.
• unit: color, normalized, meters, degrees, seconds, or bytes when relevant.
• runtime_owner: material instance, gameplay state, weather, cinematic, UI, or debug.
• fallback_value: value used when a platform disables the feature.

Do not rename a parameter to make a single graph prettier. Renames invalidate review notes and can invalidate content-driven automation.

Texture And Sampler Rules#

Texture bindings are usually the highest-risk artist-facing part of a material. Use these rules before requesting a shader change:

• Pack masks when channels share the same UVs and filtering.
• Keep normal maps in normal format and do not repurpose channels for masks.
• Use a shared sampler when wrap, clamp, anisotropy, and filter requirements match.
• Keep animated lookup textures small and document their frame count.
• Do not add a texture only to compensate for a missing scalar parameter.
• Name packed channels in the material note, for example R=damage, G=sweat, B=cloth, A=reserved.

When a platform fallback removes a texture, the material must still have an approved scalar or vector fallback so the shader output remains intentional.

Permutation Budget#

A material feature becomes a permutation only when the feature changes shader structure or removes meaningful work. Do not request a permutation for values that can be uniforms.

Allowed permutation reasons:

• Removes a texture sample or whole lighting branch.
• Changes target shader stage behavior.
• Switches an entire material family such as glass, water, clear coat, or emissive bloom.
• Protects a platform-specific fallback.
• Matches runtime usage evidence from shader_variant_usage_tracking.

Rejected permutation reasons:

• Single color, scalar, or threshold tweak.
• Shot-specific temporary look.
• Naming convenience.
• A branch that is never drawn in gameplay or capture scenes.

The current core library produces 32 variants and 96 cross-compile jobs. A new artist feature should explain how it avoids uncontrolled variant multiplication.

Complexity And Size Budgets#

Artists should read complexity and size reports as review feedback, not as compiler trivia. Treat this section as the complexity and binary-size budgets source for material review.

Complexity review uses shader_complexity_analysis:

• high ALU count means math should move to a texture, lookup, or simpler model;
• high texture fetch count means packing, reuse, or a feature toggle is needed;
• branch-heavy materials need usage evidence or a simpler fallback;
• critical severity blocks release until the material owner and rendering owner agree on the change.

Size review uses shader_binary_size_tracking:

• total cache growth over 10 percent is a release blocker;
• per-platform cache growth over 10 percent is a platform review blocker;
• individual artifact growth over 65536 bytes is a warning that needs a reason;
• all size review notes must name the platform: Vulkan, DX12, or Metal.

For Switch-style or memory-constrained targets, prefer fewer textures, fewer optional branches, and fewer feature permutations over hidden quality switches.

Debugging Artist Reports#

Compilation errors are reported through shader_compilation_error_reporting. Reports include the job id, target, stage, source path, original line, include module status, excerpt, and suggestion.

Triage order:

1. Read the human-readable summary.
2. Check whether the location is the material source or an include module.
3. Fix missing symbols, invalid bindings, and entry point mistakes before changing visual logic.
4. Re-run the material preview compile.
5. Attach the updated complexity and binary-size result to review.

Do not debug generated HLSL, MSL, DXIL, or SPIR-V first. Generated artifacts are useful after the WGSL source and include mapping are confirmed.

Review Checklist#

Before a material-to-shader change is accepted, the artist review checklist must confirm:

• material intent is written in the handoff note;
• graph node names are readable;
• parameter ids, labels, ranges, units, owners, and fallback values are present;
• textures and packed channels are documented;
• permutation requests have a release reason;
• complexity report is warning-free or has approved owner notes;
• binary-size report does not exceed the configured total or platform threshold;
• compilation errors and debug-symbol source maps are clean;
• the material has a platform fallback when required.

Verification Commands#

Run these checks for documentation-only guide changes:

python3 V2/ue/Tools/check-v2-maya-shader-pipeline-documentation.py
python3 V2/tools/validate-v2-docs.py

Run these checks when material graph or shader code changes:

CARGO_BUILD_JOBS=1 cargo test --locked --manifest-path libs/maya/engine-core/Cargo.toml -p maya-renderer material_graph_editor --lib
CARGO_BUILD_JOBS=1 cargo test --locked --manifest-path libs/maya/engine-core/Cargo.toml -p maya-renderer shader_compilation_error_reporting --lib
CARGO_BUILD_JOBS=1 cargo test --locked --manifest-path libs/maya/engine-core/Cargo.toml -p maya-renderer shader_complexity_analysis --lib
CARGO_BUILD_JOBS=1 cargo test --locked --manifest-path libs/maya/engine-core/Cargo.toml -p maya-renderer shader_binary_size_tracking --lib