# 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:

| Material graph concept      | Shader pipeline mapping                     |
| --------------------------- | ------------------------------------------- |
| Surface output              | WGSL entry point and `ShaderStage`          |
| Constant scalar or vector   | specialization define or uniform field      |
| Texture sample              | sampled texture binding and sampler binding |
| Normal processing           | reusable include module                     |
| Clear coat layer            | material feature toggle and branch          |
| Glass or water transparency | dedicated transparent material path         |
| Emissive bloom              | emissive output plus bloom classification   |
| Post-process material       | post-process shader source feature          |

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:

```bash
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:

```bash
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
```