feat: enable custom shader compilers by videobitva · Pull Request #23204 · bevyengine/bevy

videobitva · 2026-03-03T18:52:21Z

Objective

Pluggable shader compiler & import resolver

Solution

TLDR:

how it works on main

---
title: "shader compilation pipeline"
---
flowchart TD
    classDef asset fill:#fff2cc,stroke:#d6b656,color:#000
    classDef bevy fill:#dae8fc,stroke:#6c8ebf,color:#000
    classDef naga fill:#d5e8d4,stroke:#82b366,color:#000
    classDef decision fill:#f8cecc,stroke:#b85450,color:#000
    classDef lang fill:#e1d5e7,stroke:#9673a6,color:#000

    A["Shader Asset<br>(.wgsl / .glsl / .spv / .wesl)"]:::asset
    B["ShaderLoader"]:::bevy
    C["ShaderCache.set_shader()"]:::bevy
    D["<b>ShaderCache.get(id, shader_defs)</b>"]:::bevy
    E{"match shader.source"}:::decision

    A --> B --> C --> D --> E

    %% SpirV branch
    F["Source::SpirV<br><i>pass-through</i>"]:::lang
    E -- "SpirV" --> F

    %% WGSL / GLSL branch
    subgraph hardcoded ["Hardcoded in ShaderCache"]
        G["Source::Wgsl / Glsl"]:::lang
        H["naga_oil::Composer<br>add_composable_module()<br>make_naga_module()"]:::naga
        I["naga::Module"]:::naga
        G --> H --> I
    end
    E -- "Wgsl / Glsl" --> G

    %% WESL branch
    J["Source::Wesl<br>wesl::compile()<br><i>inline in ShaderCache</i>"]:::lang
    E -- "Wesl" --> J

    %% decoupled_naga decision
    K{"decoupled_naga?"}:::decision
    I --> K

    L["WGSL text<br>naga::back::wgsl"]:::naga
    M["Naga IR<br><i>direct</i>"]:::naga
    K -- "yes" --> L
    K -- "no" --> M

    %% Converge to ShaderCacheSource
    N["<b>ShaderCacheSource</b><br>SpirV | Wgsl | Naga"]:::asset
    F --> N
    L --> N
    M --> N
    J --> N

    %% GPU path
    O["load_module()"]:::bevy
    P["wgpu::create_shader_module()"]:::naga
    Q["PipelineCache.process_queue()"]:::bevy
    R["device.create_render_pipeline()<br>"]:::naga

    N --> O --> P --> Q --> R

how it works in this pr

---
title: "shader compilation pipeline"
---
flowchart TD
    classDef asset fill:#fff2cc,stroke:#d6b656,color:#000
    classDef bevy fill:#dae8fc,stroke:#6c8ebf,color:#000
    classDef naga fill:#d5e8d4,stroke:#82b366,color:#000
    classDef dispatch fill:#f8cecc,stroke:#b85450,color:#000
    classDef plugin fill:#e1d5e7,stroke:#9673a6,color:#000,stroke-dasharray:5 5
    classDef trait fill:#f5f5f5,stroke:#0050ef,color:#000,stroke-width:2px

    A["Shader Asset<br>(.wgsl / .glsl / .spv / .wesl / .custom)"]:::asset
    B["ShaderLoader"]:::bevy
    C["ShaderCache.set_shader()"]:::bevy
    D["<b>ShaderCache.get(id, shader_defs)</b>"]:::bevy
    E["Lookup compiler by ShaderLanguage<br><i>HashMap&lt;ShaderLanguage, Box&lt;dyn ShaderCompiler&gt;&gt;</i>"]:::dispatch

    A --> B --> C --> D --> E

    %% Compiler implementations
    subgraph trait_boundary ["trait ShaderCompiler"]
        direction TB

        subgraph iface [" "]
            direction LR
            T1["fn add_import"]:::trait
            T2["fn remove_import"]:::trait
            T3["fn compile -> Result&lt;CompiledShader&gt;"]:::trait
        end

        F["<b>NagaOilCompiler</b><br><i>Wgsl + Glsl</i><br>───────────────<br>owns naga_oil::Composer<br>add_import -> add_composable_module<br>compile -> make_naga_module()"]:::naga
        G["<b>WeslCompiler</b><br><i>Wesl</i><br>───────────────<br>stores sources by path<br>compile -> wesl::compile()<br>returns WGSL text"]:::naga
        H["<b>SpirVPassthrough Compiler</b><br><i>SpirV</i><br>───────────────<br>compile -> pass bytes through"]:::naga
        I["<b>Custom Compiler</b><br><i>Custom&lpar;&amp;str&rpar;</i><br>───────────────<br>compile -> ???<br><i>user-defined logic</i>"]:::plugin
    end

    E --> F
    E --> G
    E --> H
    E --> I

    %% CompiledShader
    J["<b>CompiledShader</b><br>SpirV | Wgsl | Naga"]:::asset
    F --> J
    G --> J
    H --> J
    I --> J

    %% GPU path
    K["load_module()"]:::bevy
    L["wgpu::create_shader_module()"]:::naga
    M["PipelineCache.process_queue()"]:::bevy
    N["device.create_render_pipeline()<br>"]:::naga

    J --> K --> L --> M --> N

    %% Registration API note
    R["<b>Registration API</b><br>pipeline_cache.register_shader_compiler(<br>  ShaderLanguage::Custom, MyCompiler<br>)"]:::asset

    style trait_boundary fill:none,stroke:#0050ef,stroke-width:2px,stroke-dasharray:5 5
    style iface fill:none,stroke:none

Introduces pluggable ShaderCompiler trait in bevy_shader, registered per ShaderLanguage via PipelineCache::register_shader_compiler.

The existing WGSL, GLSL, WESL, SPIR-V, and paths are refactored into default trait implementations (NagaCompiler, WeslCompiler, SpirVPassthroughCompiler) with no behavioral changes.

A new ShaderLanguage::Custom variant and Shader::from_custom сonstructor allow plugins to define new shader languages.

An end-to-end stub example demonstrates the full workflow.

Testing

.. was done on Windows 10 / Vulkan and macOS M4 / Metal.

~~run the shader_material_hlsl example~~ this one has been cut from the pr for reasons, a separate repo with this example is in progress
run shader_material_wesl, shader_material_glsl, and shader_material examples to verify existing paths

Showcase

See the stub example in examples/shader/custom_shader_compiler.rs. The pattern is:

Click to view showcase

Implement ShaderCompiler for your language:

struct Compiler;

impl ShaderCompiler for Compiler{
    fn compile(
        &mut self,
        shader: &Shader,
        _shader_defs: &[ShaderDefVal],
    ) -> Result<CompiledShader, ShaderCompileError> {
        // compile with, for example, shaderc
        Ok(CompiledShader::SpirV(vec![]))
    }
}

Register it with the PipelineCache:

impl Plugin for CustomShaderPlugin {
    fn finish(&self, app: &mut App) {
        let render_app = app.sub_app_mut(RenderApp);
        let mut pipeline_cache = render_app.world_mut().resource_mut::<PipelineCache>();
        pipeline_cache.register_shader_compiler(ShaderLanguage::Custom("custom"), Compiler);
    }
}

Use it in a Material:

impl Material for CustomMaterial {
    fn vertex_shader() -> ShaderRef { "shaders/my_shader.vert".into() }
    fn fragment_shader() -> ShaderRef { "shaders/my_shader.frag".into() }
}

github-actions · 2026-03-03T19:37:55Z

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

mockersf · 2026-03-04T19:38:17Z

 [dependencies]
 bevy_internal = { path = "crates/bevy_internal", version = "0.19.0-dev", default-features = false }
 tracing = { version = "0.1", default-features = false, optional = true }
+shaderc = { version = "0.10", optional = true }


this shouldn't be added as a top level dependency

@mockersf resolved in c2cb526

mockersf · 2026-03-04T19:38:32Z

 shader_format_wesl = ["bevy_internal/shader_format_wesl"]

+# Enable the shaderc compiler (used by the shader_material_hlsl example)
+shader_compiler_shaderc = ["dep:shaderc"]


this isn't a feature of Bevy

this isn't a feature of Bevy

yeah, but otherwise i don't know how to add this dependency as an optional, so that it is to be compiled only for this specific example...

hmm, can probably move the shaderc dep to dev-dependecies with bring-your-own shaderc lib feature flag. this way it won't be much of a burden for running other examples, though for the one I added the user will need to have shaderc installed on their system

@mockersf resolved in c2cb526

re-resolved in efcae67

use shaderc-dyn (lightweight interface dyn-loading shaderc) insetad of heavy shaderc (which compiles/links to shaderc c++ lib). move the shaderc/shaderc-dyn dependency from bevy-level to dev-dependencies.

cart · 2026-03-05T21:48:16Z

 serde_json = "1.0.140"
 bytemuck = "1"
+# Needed for shader_material_hlsl example
+shaderc-dyn = "0.10.1"


I would prefer to not compile this by default for all examples. Its a small dep, and libloading does insulate us from non-existence of the library. But it is a dependency managed by a single person who is a new contributor to the bevy project, and for a number of reasons (trust, attack surface area, build breakage, increased dependency counts, etc) I think making this a dependency that every bevy developer consumes would be a mistake.

Additionally, including the HLSL shader example alongside our others implies a degree of support that we are not ready for.

I'd prefer it if this was reframed as a "custom shader compiler" example with a stub implementation, and a link to a repo that contains the full HLSL impl with this dependency.

i've though a bit before about just pointing to a crate with example impl, but did not know whether this is fine for you or not. from your response it seems that this is ok, so will do that 👍

1. merge import resolver and shader compilers trait into one, as it made no sense in the end to keep them separated 2. remove intermediate types representing shader state 3. consistent feature flags for different shading langs 4. a bit better public interface for registering compilers

videobitva · 2026-03-06T09:58:41Z

+        let render_app = app.sub_app_mut(bevy::render::RenderApp);
+        let mut pipeline_cache = render_app.world_mut().resource_mut::<PipelineCache>();
+
+        pipeline_cache
+            .register_shader_compiler(ShaderLanguage::Custom("custom"), CustomShaderCompiler);


i dont really like how the compiler registration looks rn, would be nice for it to be done the same way the AssetLoader does it, i.e. just a method on App. but need to look into how to do that

videobitva · 2026-03-06T10:04:31Z

+    Utf8(#[from] std::string::FromUtf8Error),
+}
+
+impl AssetLoader for CustomShaderLoader {


for any non-bevy-native shader lang you'll need to impl an asset loader. hypothetically this can be bypassed by integrating the info about a shader into the ShaderCompiler trait and next somehow pass it through to the already existing ShaderLoader impl

videobitva · 2026-03-06T12:52:03Z

+        compilers.insert(ShaderLanguage::Wgsl, naga_oil.clone());
+        #[cfg(feature = "shader_format_glsl")]
+        compilers.insert(ShaderLanguage::Glsl, naga_oil.clone());
+        #[cfg(feature = "shader_format_wesl")]
+        compilers.insert(
+            ShaderLanguage::Wesl,
+            Arc::new(Mutex::new(WeslCompiler::new())),
+        );
+        #[cfg(feature = "shader_format_spirv")]
+        compilers.insert(
+            ShaderLanguage::SpirV,
+            Arc::new(Mutex::new(SpirVPassthroughCompiler)),
+        );


thinking about a possibility to move the default compilers registration out from the ShaderCache::new to a some more user-friendly place, so that adding new compilers/overriding existing could be more sound

(guess this is the same issue as in #23204 (comment))

videobitva · 2026-03-12T02:05:46Z

ok, i kinda found a way to tackle the issues i've mentioned in the comments above, but it will take some time to refine the impl. so to not waste maintainers time and not distract them from other pull requests i'll mark this one as draft for now

videobitva · 2026-03-12T02:26:21Z

note to myself: should probably ask what is the plan for wgsl to wesl migration, as with every change in this branch the bevy_shader itself and its interactions with bevy_render get refactored further and further

ncthbrt · 2026-03-17T08:42:50Z

Is there a way to add more information to materials or customise material compilation behaviour beyond just the path to the shader? For my experimental mew compiler for example, for generics you need to be able to specify the entry point to compile the shader from mew to wigs. For example: MySurface3d<f16>::vertex could be an entry point on mobile, and MySurface3d<f32>::vertex could be the entry point on desktop.

In a way it's part of specialisation, except the function exposed in the material for that is way too late in the pipeline for that to work correctly.

videobitva added 3 commits March 3, 2026 20:49

feat: enable custom shader compilers

c39476f

fix: CI / typos (pull_request)

ff5f3ed

fix: CI / markdownlint (pull_request)

25174b5

videobitva added 5 commits March 3, 2026 22:21

update features

57cd89e

fix: CI / markdownlint (pull_request)

ca2990d

fix: CI / check-doc (pull_request)

925f5d8

fix: CI / check-missing-features-in-docs (pull_request)

bb1008b

cleanup comments

69cb67e

github-project-automation Bot added this to Assets and Rendering Mar 4, 2026

github-project-automation Bot moved this to Needs SME Triage in Rendering Mar 4, 2026

github-project-automation Bot moved this to Needs SME Triage in Assets Mar 4, 2026

alice-i-cecile added the D-Complex Quite challenging from either a design or technical perspective. Ask for help! label Mar 4, 2026

videobitva added 4 commits March 4, 2026 11:43

cleanup docs, api surface & example

2a5b6d7

make ci happy

2eff94d

cleanup example

4439b7b

Update mod.rs

b3b4e66

mockersf reviewed Mar 4, 2026

View reviewed changes

videobitva added 4 commits March 5, 2026 16:52

chore: use shaderc-dyn instead of shaderc

c2cb526

use shaderc-dyn (lightweight interface dyn-loading shaderc) insetad of heavy shaderc (which compiles/links to shaderc c++ lib). move the shaderc/shaderc-dyn dependency from bevy-level to dev-dependencies.

chore: taplo fmt

2fff528

chore: update features

178f139

chore: const str as custom shader lang key

5aead6f

cart reviewed Mar 5, 2026

View reviewed changes

videobitva added 5 commits March 6, 2026 01:10

chore: stub-ify the custom shader compiler example

efcae67

make ci happy 2

4975282

make ci happy 3

3ac1c18

Merge branch 'main' into compiler_plugin

193e8f3

videobitva commented Mar 6, 2026

View reviewed changes

videobitva added 3 commits March 7, 2026 00:54

fix: glsl feature flag

0b32cce

fix: glsl on wasm regression

811bd54

clippy: example

7194e00

videobitva force-pushed the compiler_plugin branch from 8560cde to 7194e00 Compare March 6, 2026 23:13

fix: docs

6fbef6a

videobitva marked this pull request as draft March 12, 2026 02:04

Uh oh!

Conversation

videobitva commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Showcase

Uh oh!

github-actions Bot commented Mar 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

videobitva Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

videobitva Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

videobitva Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

videobitva commented Mar 12, 2026

Uh oh!

videobitva commented Mar 12, 2026

Uh oh!

ncthbrt commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

videobitva commented Mar 3, 2026 •

edited

Loading

videobitva Mar 5, 2026 •

edited

Loading

videobitva Mar 6, 2026 •

edited

Loading

videobitva Mar 6, 2026 •

edited

Loading

ncthbrt commented Mar 17, 2026 •

edited

Loading