Shader tree layout

The whole shader build is two `file(GLOB_RECURSE)` calls over `shaders/` — one collecting sources, one collecting headers for dependency tracking — plus one `glslc` command per matched source and a custom target that depends on the results. There is no shader database, no variant matrix, no reflection step.

The glob runs at *configure* time and carries no `CONFIGURE_DEPENDS`, so a newly added `.rgen` is invisible until CMake is re-run — the failure looks like a missing SPIR-V at load, not a build error. It also recurses without exclusions, which is why `shaders/_disabled/` is not archival: all 35 sources under it are globbed and compiled like everything else, for 91 SPIR-V modules total.

The compile line is where the architecture actually shows:

Two include roots — `shaders/` and `shaders/includes/` — and **zero `-D` flags**. That omission decides how variation is expressed everywhere in the engine. A shader cannot be compiled twice with different defines, so the three path-tracer profiles are three separate source files (`pt_raygen.rgen`, `pt_raygen_realtime.rgen`, `pt_raygen_offline.rgen`) rather than one file with a `#define PROFILE`. Copying does not keep them in step, and they have not drifted equally: against the 1270-line `pt_raygen.rgen`, `diff` reports 141 added or removed lines for the 1355-line `pt_raygen_offline.rgen` and 1075 for the 1925-line `pt_raygen_realtime.rgen`. Two of the three are near-duplicates; the realtime profile is a fork.

What stays configurable is pushed into SPIR-V specialization constants patched at pipeline creation. There is exactly one `constant_id` in the entire shader tree — the path tracer's sampler choice, in a header all three raygens include:

It is supplied to the raygen stage alone, so changing samplers rebuilds the pipeline object and not the SPIR-V:

The cost is visible in `forward.frag`, which guards its legacy Blinn-Phong lighting behind an override hook nothing in the build ever supplies:

`glslc -M` confirms the consequence: `includes/lighting/blinn_phong.glsl` is not in the dependency closure of any shader in the tree. It is not dead by deletion, it is dead by there being no `-D` in the build.

Output names are the source path with directory separators replaced by underscores, then `.spv` appended:

So `shaders/rt/rt_svgf_temporal.comp` becomes `rt_rt_svgf_temporal.comp.spv` — the stutter is the directory name surviving into the filename. That mangled string is not an internal detail; it is hard-coded at every C++ load site, which makes the flattening rule a binary interface between the build system and the renderer:

The mapping is not injective — `a/b.frag` and `a_b.frag` collide — and nothing in the build detects that. No collision exists in the tree today, but the invariant is maintained by nobody.

Every path is relative to the process working directory. There is no `install()` rule for shaders anywhere in the project, no environment variable, no absolute path, and no `.spv` committed to the repository — the binaries only ever exist in a build tree.

The RT stack names its modules under `bin/shaders/`:

`glslc` writes `build/shaders/`, so that prefix looks stale — but the build does still produce it. `renderer_test` mirrors the compiler's output directory into a `bin/shaders` beside its own executable,

and because the runtime output directory is the binary directory itself, that destination is `build/bin/shaders/`:

`renderer_test` is configured by default, so an ordinary configure-and-build produces both trees:

The loader's first candidate is the literal string, unmodified; its second strips the directory and retries under `build/shaders/`:

So rung one hits when the process working directory is `build/`, and rung two hits when it is the repository root. Two directories work, not one — and they are not interchangeable. The mirror is a `copy_directory` snapshot taken at link time, so on this tree `build/bin/shaders/` carries 94 modules against `build/shaders/`'s 96, and the two disagree in *both* directions: each holds stale outputs the other does not.

The deferred stack is different again: `VulkanRenderer` probes seven candidate directories at construction, testing each with a single sentinel file,

and then publishes whatever it found to every render pass through a static:

That makes one forward-rendering shader the discovery key for the entire deferred pipeline. The probe assigns only on a hit, but the publish is unconditional: if none of the seven candidates holds `core_forward.vert.spv`, an empty string is pushed, and `RenderPassBase`'s own default prefix is overwritten rather than left standing:

What the passes fall back to is not a per-pass guess: every deferred pass loads through one `RenderPassBase::loadShaderModule`, whose three rungs are `s_shaderBasePath + name`, a hard-coded `build/shaders/`, and a `build/Release/bin/shaders/` for multi-config generators. With the base path emptied the first rung degenerates to a bare flat filename — a hit only if the working directory *is* the SPIR-V directory — so in practice the middle rung carries every load, and only from the repository root:

The failure is loud but misdirected. The throw names the flat filename the pass asked for and never the directory it searched, so a wrong working directory and a genuinely missing module produce the same message:

Every shader is declared to depend on the full include list, so touching one header rebuilds the world:

Measured on this tree, touching `includes/common/math.glsl` recompiles all 91 modules — a deliberate over-approximation that avoids depfile plumbing. The under-approximation next to it is the dangerous half. `SHADER_INCLUDES` is built from a pattern with a directory component in the middle:

`**` is not the recursive wildcard it looks like, and it is not a one-level wildcard either. Under `GLOB_RECURSE` the trailing `*.glsl` is applied at every depth anyway; all `**/` contributes is a demand that *at least one* directory component sit between `includes/` and the file. Checked against CMake directly on a scratch tree, `includes/**/*.glsl` matches `includes/a/b/c/three.glsl` and does not match `includes/top.glsl`. The pattern therefore collects all 30 headers in subdirectories of `includes/` — which in this tree all happen to sit exactly one level down — and misses exactly the two at its top level, `noise.glsl` and `pbr_unpack.glsl`, along with everything under `shaders/rt/includes/`, which is outside the pattern's root entirely. Touching either copy of `pbr_unpack.glsl` and rebuilding recompiles **zero** shaders. The material unpack used by every raygen can be edited and shipped without the build noticing. (The second glob line, which adds `includes/water/*.glsl`, is redundant: that file already matches the first pattern.)

The tree contains `shaders/includes/pbr_unpack.glsl` and `shaders/rt/includes/pbr_unpack.glsl`, byte-identical today. All three raygens ask for the same string:

A quoted include is resolved relative to the *including file's* directory before any `-I` root is consulted, and `shaders/rt/` has an `includes/` of its own — so `glslc -M` reports that the raygens compile `shaders/rt/includes/pbr_unpack.glsl` and never touch the copy under `shaders/includes/`. Neither the include roots nor the flat naming rule are involved; the winner is decided by directory adjacency.

Cross-referencing the 91 produced names against every `.spv` string literal in `ohao/`, `examples/` and `tests/` leaves 43 modules that no code path names: the 35 under `_disabled/`, plus eight live compute shaders including `compute_skinning.comp`, `compute_light_culling.comp` and `compute_gpu_cull.comp`. The include tree tells the same story from the other side — of 34 `.glsl` headers, 11 are outside the dependency closure of every shader, among them `shadow_csm.glsl` and `rt_masks.glsl`, the latter carrying a comment promising it mirrors `rt_visibility.hpp`.

`compile_shaders.sh` arrived in the same commit as the CMake flattening rule and uses the same `${subdir}_${name}.spv` convention, so the two agree on output names for one-level directories. They agree on very little else. The script walks a fixed directory list:

`debug/` does not exist, and `rt/`, `particles/` and `overlay/` are absent — so it covers 30 of the 91 sources and compiles no ray-tracing stage at all. It uses `glslangValidator` with a single include root and no `--target-env`, where CMake uses `glslc` with two roots and targets Vulkan 1.3:

The compiler swap has a concrete consequence: `glslc` enables `GL_GOOGLE_include_directive` implicitly, `glslangValidator` requires the shader to declare it. Replaying the script's exact invocation over the four directories it walks, 29 files compile and exactly one fails — `shaders/postprocess/ssr.comp`, which uses `#include` without the `#extension` line. The script exits non-zero on a tree the real build compiles cleanly.

Each output is then copied into a Godot editor project, whose destination the script `mkdir -p`s first — so running it today recreates a directory tree the engine deleted:

The commit that removed `godot_editor/` is the last commit that touched this file, and left the copy target pointing into it.

• The `shaders` target is declared without `ALL` and nothing calls `add_dependencies` on it, so `cmake --build build` does **not** compile shaders. `--target shaders` is mandatory after any shader edit. {{cite shaders/CMakeLists.txt "add_custom_target(shaders"}}
• `renderer_test` mirrors `build/shaders/` into `build/bin/shaders/` as a POST_BUILD step with no dependency on the `shaders` target, so the mirror snapshots whatever SPIR-V existed at link time — including modules whose sources have since been deleted. Rebuild shaders without relinking the test and the two trees drift apart. {{cite tests/renderer/CMakeLists.txt "add_custom_command(TARGET renderer_test POST_BUILD"}}
• Nothing deletes stale outputs. A renamed or moved shader leaves its old `.spv` in `build/shaders/`, where the runtime's basename fallback will happily load it.
• Every shader path in the engine is CWD-relative, and on a single-config build exactly two working directories resolve: the repository root (via the `build/shaders/` + basename rung) and `build/` (via the `bin/shaders/` literal, served by the `renderer_test` mirror). They are not equivalent for anything else — `model_viewer`'s hard-coded environment map exists only under the source tree, so that example still has to run from the root. {{cite examples/model_viewer.cpp "renderer.setEnvironmentMap("assets/test_models/env_studio.hdr");"}}
• Renaming a shader file, or moving it between directories, renames its SPIR-V and breaks every C++ load site that spells the flat name. The build reports success either way.