# Shader Pipeline and Material Authoring Guide

The Maya renderer uses WGSL as the primary shader source language. Renderer
tools register sources with `ShaderPipelineManager`, then compile variants for
Vulkan, DX12, Metal, and WebGPU during content cook or development hot reload.

## Source layout

Organize shader files by render feature:

- `materials/` for surface shading such as standard lit, skin, glass, foliage,
  and water materials.
- `lighting/` for light evaluation, clustered lighting, and image-based lighting
  helpers.
- `shadows/` for cascaded shadows, contact shadows, and filtering.
- `post_process/` for bloom, tone mapping, color grading, and upscaling.
- `compute/` for culling, visibility, simulation, and prepass jobs.

Each `ShaderSourceFile` records its category, stage, path, WGSL text, entry
point, include list, and material tags. Material tags should match the asset
authoring vocabulary so cook reports can be grouped by material family.

## Include modules

Reusable WGSL lives in registered `ShaderModuleFile` records. Keep BRDF, math,
noise, packing, skin, and color utilities in modules and reference them with:

```wgsl
#include <brdf>
```

The pipeline resolves includes before compilation and reports a missing include
as an authoring error. Prefer small modules with named exported symbols so
shader debug symbols stay readable in GPU debuggers.

## Feature toggles

Material variants are generated from explicit `ShaderFeatureToggle` records.
Common toggles include:

- `HAS_NORMAL_MAP`
- `HAS_EMISSIVE`
- `SHADOW_QUALITY=LOW|HIGH`
- `USE_CLEARCOAT`
- `DEBUG_VIEW`

Use `createShaderVariantKey()` for stable keys in asset manifests, PSO cache
entries, cook logs, and usage reports. Keep toggle counts low. Every boolean
toggle doubles the variant count, and enum toggles multiply it by their number
of values.

## Cook and platform outputs

Content cook should call `createCookPlan()` for all shaders required by the
level, character, or material bundle, then call `compileCookPlan()` for each
target platform set. The manager records output format and compiler backend:

- Vulkan: WGSL -> SPIR-V through Naga.
- DX12: WGSL -> DXIL through Tint.
- Metal: WGSL -> MSL through Naga.
- WebGPU: WGSL remains the runtime source format.

Cook jobs should run before runtime packaging so players do not hit shader
compilation stalls during first use.

## PSO cache

Pipeline State Object descriptors are keyed by shader ID, variant key, target,
and render-state hash. After warmup, export the PSO cache snapshot and store it
with the platform build. On the next launch, import the snapshot before the
first draw so existing pipeline entries can be reused immediately.

## Hot reload

Development tools can call `hotReload(shaderId, nextWgsl)` when a WGSL file is
edited. The manager increments the source version, invalidates compiled variants
for that shader, and recompiles on the next request. Authoring tools should show
the invalidated variant keys so artists know which material previews will
refresh.

## Debugging and errors

`createDebugSymbols()` emits source-path and line-number mappings for shader
debugger integrations such as RenderDoc, PIX, and Nsight. Keep entry point names
and helper function names descriptive because they appear directly in the symbol
list.

Compilation errors include path, line, column, message, and a suggested fix.
Surface these fields directly in editor panels and CI cook logs.

## Complexity, usage, and size review

Run `analyzeComplexity()` on important variants during content review. High
texture fetch counts, branch counts, register pressure, or total complexity
warnings should trigger material simplification or a platform-specific variant.

Runtime should call `recordUsage()` when variants are drawn. Feed the usage
records into the next cook to prune variants that were never observed in play
sessions or automated traversal.

Use `createBinarySizeReport()` per platform after cook. Treat shader cache
growth as a release risk when it exceeds the configured regression threshold,
especially for console patch packages and mobile download sizes.

## Artist checklist

Before a material is approved:

1. The material uses existing include modules before adding new helpers.
2. Feature toggles are limited to visible quality or gameplay differences.
3. The default variant compiles on WebGPU, Vulkan, DX12, and Metal targets.
4. The high-quality variant has no complexity warnings for its target platform.
5. The material appears in the content-cook plan for every level that uses it.
6. Hot reload updates the material preview without restarting the editor.
