Eve library

Shader Pipeline and Material Authoring Guide

Guide

Revision 1

On this page

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.