CMakeLists.txt

# ============================================================================
# WhiteoutFlakes — standalone renderer + basic_viewer tool.
# ============================================================================

cmake_minimum_required(VERSION 3.20)
project(WhiteoutFlakes LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# ---- Emscripten / WebAssembly target ----
# Configured via `emcmake cmake ...`. The web build is a lean subset:
# WebGPU only, no desktop windowing/audio/UI, no native game archives.
# Every gating decision below keys off EMSCRIPTEN; the desktop build is
# unaffected.
if(EMSCRIPTEN)
    set(WDX_ENABLE_TRACY  OFF CACHE BOOL "" FORCE)  # no web transport
    set(WDX_ENABLE_IMGUI  OFF CACHE BOOL "" FORCE)  # JS owns all UI chrome
    set(WDX_ENABLE_WEBGPU ON  CACHE BOOL "" FORCE)  # only web backend
    set(WDX_ENABLE_WEBP   OFF CACHE BOOL "" FORCE)  # viewer-only export
    # Exceptions: -fno-exceptions everywhere. The renderer doesn't throw
    # and WhiteoutLib has been adjusted to compile without `throw` under
    # Emscripten — so there's no reason to ship EH machinery. This is
    # what avoids the Chrome wasm-compile freeze we hit with both
    # -fexceptions (JS-trampolined invoke_*) and -fwasm-exceptions
    # (native try_table) — both emit code Chrome's wasm compiler stalls
    # on for >60 s, while the equivalent EH-free wasm compiles in ms.
    add_compile_options(-fno-exceptions)
    add_link_options(-fno-exceptions)
    # Compile-time: -O2 for better per-function codegen quality (register
    # allocation, CSE, loop opts, constant propagation). Link-time: -Oz
    # to keep the wasm binary small via wasm-opt. The Chrome V8 freeze we
    # used to hit was caused by *huge inlined functions* (50k+ wasm
    # instructions per func, e.g. PIMPL ctors absorbing their whole
    # subsystem graph) tipping V8 into synchronous TurboFan — that's
    # already blocked by `-fno-inline-functions` + `-fno-lto`, which we
    # keep. With those guards in place, -O2 produces faster code without
    # creating the giant functions V8 chokes on.
    #
    # Was -Oz globally; the Firefox profile showed 73% of frame time in
    # our WASM (Firefox WGPU/SpiderMonkey is more sensitive to AOT code
    # quality than Chrome/V8, which JIT-optimizes hot paths at run time).
    # Lifting compile -O to O2 closes a meaningful chunk of the gap.
    #
    # Flags retained:
    #   -fno-lto           : no cross-TU inlining at link time
    #   -fno-inline-functions: no intra-TU inlining of large funcs
    # Combined with `-O2`, individual function sizes stay manageable.
    add_compile_options(-O2 -fno-lto -fno-inline-functions)
    add_link_options(-Oz -fno-lto)
    message(STATUS "WhiteoutFlakes: Emscripten/WebAssembly build "
                   "(no exceptions, compile -O2 / link -Oz, no inlining/LTO)")
endif()

# Disable vcpkg's user-wide MSBuild integration (`vcpkg integrate install`)
# for every generated .vcxproj. WhiteoutFlakes pulls all its dependencies via
# FetchContent / add_subdirectory and uses no vcpkg toolchain or manifest, but
# a machine-wide vcpkg integration would otherwise auto-link every installed
# vcpkg package into our binaries — e.g. silently importing vcpkg's shared
# libwebp.dll alongside our own statically-built libwebp. Emitted into the
# Globals PropertyGroup, which vcpkg.user.targets honours. (VS generator only;
# harmless elsewhere, where the integration does not apply anyway.)
set(CMAKE_VS_GLOBALS "VcpkgEnabled=false")

# Pull in WhiteoutLib (provides whiteout_lib; optionally whiteout_casc, whiteout_mpq).
# CASC/MPQ are native file-I/O + threading — disabled under Emscripten; the web
# build receives bytes from JS via FetchContentProvider instead.
if(EMSCRIPTEN)
    set(WHITEOUT_ENABLE_CASC OFF CACHE BOOL "Enable CASC archive support" FORCE)
    set(WHITEOUT_ENABLE_MPQ  OFF CACHE BOOL "Enable MPQ archive support"  FORCE)
    # WhiteoutLib auto-enables embind bindings under EMSCRIPTEN. Those
    # bindings register every public C++ class/method into JS via a
    # massive static-init constructor — easily 40k+ wasm instructions in
    # a single function, which trips V8's synchronous-compile fallback
    # and freezes the page. We have our own `wf_*` C facade and never
    # call into JS-bound WhiteoutLib symbols, so the bindings are pure
    # dead weight here.
    set(WHITEOUT_BUILD_WASM_BINDINGS OFF CACHE BOOL "" FORCE)
else()
    set(WHITEOUT_ENABLE_CASC ON CACHE BOOL "Enable CASC archive support" FORCE)
    set(WHITEOUT_ENABLE_MPQ  ON CACHE BOOL "Enable MPQ archive support"  FORCE)
endif()
# DBC / DB2. Pure parsing over bytes the content provider hands it, so unlike
# CASC/MPQ it costs the web build nothing to keep on. World of Warcraft's
# replaceable textures are read out of these; see WowReplaceableTextures.
set(WHITEOUT_ENABLE_DATABASE ON CACHE BOOL "Enable WoW client database support" FORCE)

# Skip adding the bundled WhiteoutLib if the parent project has already
# provided the `whiteout_lib` target (e.g. the WhiteoutDex monorepo pins
# its own WhiteoutLib submodule and pulls it in before this subdir, so
# every plugin shares one copy). When standalone, pull in the bundled
# nested submodule as usual.
if(NOT TARGET whiteout_lib)
    add_subdirectory(externals/WhiteoutLib)
endif()

# Tracy — opt-in CPU + GPU profiler. When WDX_ENABLE_TRACY is ON, the
# Tracy::TracyClient target is built and TRACY_ENABLE is defined for
# everyone linking it; otherwise every TracyVk*/ZoneScoped macro expands
# to nothing and there's zero runtime cost. TRACY_ON_DEMAND keeps the
# client buffering minimal until Tracy.exe connects.
# World of Warcraft `.m2` and StarCraft II / Heroes `.m3`.
#
# ON so the standalone viewer can open them from File > Open — which is the
# only reason the default changed; REFACTOR_PLAN.md P9/P10 landed them OFF on
# the grounds that a release viewer shouldn't carry a half-implemented format.
# That caveat still holds and is worth repeating: **both load geometry only**.
# No bones, no textures, no materials, no animation — a model draws as a flat
# untextured silhouette. Turn them off for a build that should not offer that.
#
# Warcraft III rendering is byte-identical either way (G1/G2 gated in both
# configurations), so this costs compile time and nothing else. CI has no `.m2`
# or `.m3` assets, so the tests that use them skip rather than fail.
option(WDX_ENABLE_M2 "Enable World of Warcraft .m2 loading (geometry only)" ON)
option(WDX_ENABLE_M3 "Enable StarCraft II / Heroes .m3 loading (geometry only)" ON)

# Diablo III actors. Unlike the two above, nothing extra has to be enabled
# upstream: WhiteoutLib builds sno/d3/native and textures/tex into its core
# target unconditionally, so this option only gates our own sources.
option(WDX_ENABLE_D3 "Enable Diablo III actor loading" ON)

# Rigid-body physics, driven by Snowball — the re-implementation of Blizzard's
# Domino engine, vendored under src/renderer/physics/snowball. Both games that
# ship Domino data are covered: WoW's `.m2` cloth and tassels (`.phys`/PFDC) and
# StarCraft II's `.m3` rigid bodies and death ragdolls (PHRB/PHYJ). Needs at
# least one of WDX_ENABLE_M2 / WDX_ENABLE_M3, since physics reaches us only
# through a model format.
option(WDX_ENABLE_PHYSICS "Enable rigid-body simulation (needs Snowball)" ON)

option(WDX_ENABLE_TRACY "Enable Tracy profiler (CPU + Vulkan GPU)" ON)
if(WDX_ENABLE_TRACY AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/externals/tracy/CMakeLists.txt")
    set(TRACY_ENABLE    ON  CACHE BOOL "" FORCE)
    set(TRACY_ON_DEMAND ON  CACHE BOOL "" FORCE)
    set(TRACY_NO_FRAME_IMAGE ON CACHE BOOL "" FORCE)
    add_subdirectory(externals/tracy)
    set(WDX_TRACY_LIB Tracy::TracyClient)
    message(STATUS "Tracy: enabled (TRACY_ENABLE + TRACY_ON_DEMAND)")
else()
    set(WDX_TRACY_LIB "")
    if(WDX_ENABLE_TRACY)
        message(WARNING "WDX_ENABLE_TRACY=ON but externals/tracy is missing. "
                        "Run: git submodule update --init externals/tracy")
    endif()
endif()

# cornflakes is folded directly into WhiteoutFlakesLib as a renderer module
# the cornflakes determinism + warnings INTERFACE targets the upstream project
# defines are replaced by inline compile flags on WhiteoutFlakesLib.
set(CORNFLAKES_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/renderer/corn_effects/cornflakes")
set(CORNFLAKES_SOURCES
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/version.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/core/arena.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/diagnostics/issue.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/diagnostics/frame_trace.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/scheduler/serial_worker_pool.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/service/cornflakes_service.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/asset_reader.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/pkb_reader.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/pkmm_reader.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/pkvf_reader.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/file_mesh_provider.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/text_pkfx_reader.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/war3_compatibility_validator.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/object_accessors.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/asset/field_defs_generated.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/effect_binder.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/program_binder.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/renderer_binder.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/sampler_binder.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/external_binding.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/ir_to_cbem_lowerer.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/sampler_resource.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/binding/spatial_layer_resource.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/vm/bytecode_trace.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/vm/cbem/cbem_interpreter.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/vm/cbem/cbem_ir_ops.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/vm/cbem/cbem_dispatchers.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/vm/math_functions.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/vm/bytecode_decoder.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/mesh.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/shape_geometry.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/shape.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/curve.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/curve_cdf.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/texture.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/turbulence.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sampler/vector_field.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/particle_page.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/spawn_processor.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/spawn_evaluator_driver.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/evolve_page_task.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/simulation_runtime.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/layer_tick_harness.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/particle_pool.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/effect_runtime.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/state_digest.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/state_compare.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/sim/lod.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/simt/layer_stream_store.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/simt/scratch_validator.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/simt/register_census.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/simt/packet_register_file.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/simt/stream_extract.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/simt/simt_interpreter.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/events/payload_cache_store.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/events/payload_builder.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/events/event_generator.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/events/event_router.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/events/kick_processor.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/semantic_slot_reader.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/renderer_class_bucket.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/render_extractor.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/pool_extractor.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/ribbon_geometry.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/shader_perm.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/render/instance_stream.cpp"
    "${CORNFLAKES_MODULE_DIR}/internal/cornflakes/validation/batch_resource_tracker.cpp"
)

# ============================================================================
# Slang shader compilation (compile-time: .slang → DXBC → embedded C++ header)
# ============================================================================

set(SHADER_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/renderer/shaders")
set(SHADER_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/shaders")
file(MAKE_DIRECTORY "${SHADER_OUT_DIR}")

find_program(SLANGC slangc
    HINTS "${SLANG_DIR}/bin" "$ENV{SLANG_DIR}/bin"
    DOC   "Path to Slang compiler (slangc)")

if(NOT SLANGC)
    message(FATAL_ERROR
        "slangc not found. Install the Slang SDK from https://github.com/shader-slang/slang/releases "
        "and set -DSLANG_DIR=<path-to-slang-sdk> or add slangc to PATH.")
endif()
message(STATUS "Using slangc (default): ${SLANGC}")

# Optional override for the Vulkan-target slangc. Some upstream slang
# bugs (e.g. `Conditional<>` + SPIR-V specialise emit) are fixed in
# tip-of-tree slang but not in the Vulkan SDK build, while the SDK
# slangc still emits cleaner DXIL than tip — pass
# -DSLANGC_VULKAN=<path-to-newer-slangc.exe> to use the newer build
# for SPIR-V only, and keep the SDK slangc for d3d11 / d3d12.
if(NOT DEFINED SLANGC_VULKAN OR SLANGC_VULKAN STREQUAL "")
    set(SLANGC_VULKAN "${SLANGC}"
        CACHE FILEPATH "slangc used for the Vulkan (SPIR-V) target. Defaults to SLANGC.")
endif()
message(STATUS "Using slangc (vulkan): ${SLANGC_VULKAN}")

# Common Slang flags: column-major matrices (matches C++ transpose-before-upload convention)
# Use DXC as the downstream compiler instead of FXC for DXBC output
set(SLANG_COMMON_FLAGS -matrix-layout-column-major -I "${SHADER_SRC_DIR}"
    -default-downstream-compiler hlsl dxc)

# Shader entry points: <slang_file>  <entry>  <stage>  <output_name>
# Only line.slang (debug wires), blit.slang and framebuffer_capture.slang
# remain as Slang sources; every MDX-material draw goes through BLS, and the
# tonemap pass uses the engine's sprite.bls VS directly.
set(SHADER_ENTRIES
    "line.slang|vsLine|vertex|kLineVS"
    "line.slang|psLine|fragment|kLinePS"
    "blit.slang|vsBlit|vertex|kBlitVS"
    "blit.slang|psBlit|fragment|kBlitPS"
    "framebuffer_capture.slang|csCapture|compute|kCaptureCS"
    # UnlitShading — position-only, flat white. An IShadingModel of its own
    # (not a BLS program), so it lives here rather than in a .bls bundle.
    "unlit.slang|vsUnlit|vertex|kUnlitVS"
    "unlit.slang|psUnlit|fragment|kUnlitPS"
    # Lit permutations: POSITION+NORMAL, selected by the profile's
    # UnlitLighting(). They exist to make a MeshBuffer's layout description
    # checkable — flat white cannot tell a right normal from a missing one.
    "unlit.slang|vsUnlitLit|vertex|kUnlitLitVS"
    "unlit.slang|psUnlitLambert|fragment|kUnlitLambertPS"
    "unlit.slang|psUnlitBlinnPhong|fragment|kUnlitBlinnPhongPS"
    # Skinned permutations. Same pixel shaders; the vertex side poses the
    # geometry from a bone palette, reading BLENDWEIGHT/BLENDINDICES out of the
    # same interleaved buffer that carries position — which is how `.m3` ships
    # them, so nothing is decoded or duplicated to get here.
    "unlit.slang|vsUnlitSkinned|vertex|kUnlitSkinnedVS"
    "unlit.slang|vsUnlitSkinnedLit|vertex|kUnlitSkinnedLitVS"
    # GTAO ambient-occlusion pass — read by GtaoService. The same
    # vsGtao fullscreen-triangle VS feeds both the main pass (writes
    # the AO buffer) and the apply pass (modulates the HDR scene
    # colour in place via loadOp=Load + DST*SRC blend).
    "gtao.slang|vsGtao|vertex|kGtaoVS"
    "gtao.slang|gtao_main_low_ps|fragment|kGtaoMainLowPS"
    "gtao.slang|gtao_main_ps|fragment|kGtaoMainPS"
    "gtao.slang|gtao_main_high_ps|fragment|kGtaoMainHighPS"
    "gtao.slang|gtao_denoise_ps|fragment|kGtaoDenoisePS"
    "gtao.slang|gtao_temporal_ps|fragment|kGtaoTemporalPS"
    "gtao.slang|gtao_depth_copy_ps|fragment|kGtaoDepthCopyPS"
    "gtao.slang|gtao_ibl_boost_ps|fragment|kGtaoIblBoostPS"
    "gtao.slang|gtao_apply_ps|fragment|kGtaoApplyPS"
    # Bloom Gaussian blur (post-process). PostProcessService runs this
    # twice per frame (horizontal, then vertical) between BloomExtract
    # and BloomCombine. Renderer-internal — Wc3Shaders doesn't author a
    # blur source, so we ship our own embedded copy rather than relying
    # on the engine's shipped gaussianblur.bls being staged.
    "gaussian_blur.slang|vsBlur|vertex|kGaussianBlurVS"
    "gaussian_blur.slang|psBlur|fragment|kGaussianBlurPS"
    # ImGui colour-space-converting image draws. The retail imgui.bls permute
    # set is fixed (differentially tested against the shipped game), so the
    # mismatched-texture half of the colour-space matrix — a UNORM thumbnail
    # on an sRGB RTV, an sRGB texture on a UNORM RTV — ships as engine
    # entries that ImGuiRenderer swaps to per draw.
    "imgui_convert.slang|vsImGuiConvert|vertex|kImGuiConvertVS"
    "imgui_convert.slang|psImGuiToLinear|fragment|kImGuiToLinearPS"
    "imgui_convert.slang|psImGuiToDisplay|fragment|kImGuiToDisplayPS"
    # WoW refraction particles (RefractionService). Two passes: the emitters'
    # quads into a scalar distortion mask, then a full-screen pass that bends
    # the finished scene through it. Transcribed from the retail `refraction`
    # and `refractionapply` shaders — see M2_REFRACTION_DESIGN.md.
    "refraction_mask.slang|vsRefractParticle|vertex|kRefractParticleVS"
    "refraction_mask.slang|psRefractParticle|fragment|kRefractParticlePS"
    "refraction_apply.slang|vsRefractApply|vertex|kRefractApplyVS"
    "refraction_apply.slang|psRefractApply|fragment|kRefractApplyPS"
    # Diablo III screen-space distortion (DistortionService). Only the RESOLVE
    # is a shader of its own — the buffer is written by the ordinary D3 programs
    # into a different target. Transcribed from the shipped `v14 PostFX
    # Distortion` orphan; see D3_MATERIAL_DESIGN.md.
    "d3_distortion_apply.slang|vsD3DistortionApply|vertex|kD3DistortionApplyVS"
    "d3_distortion_apply.slang|psD3DistortionApply|fragment|kD3DistortionApplyPS"
    # WoW multi-texture particles (MultiTexParticleService). Three textures
    # through three UV sets, drawn in the transparent pass like any other
    # particle. Transcribed from the retail `particle_3colortex_3alphatex`
    # shader — see M2_MULTITEX_DESIGN.md.
    "particle_multitex.slang|vsMultiTexParticle|vertex|kMultiTexParticleVS"
    "particle_multitex.slang|psMultiTexParticle|fragment|kMultiTexParticlePS"
    # M2CombinerShading — WoW `.m2`. 16 vertex + 36 pixel entry points, indexed
    # directly by M2GetVertexShaderID / M2GetPixelShaderID (m2_shader_select.h).
    # Any VS pairs with any PS, so all 52 share one interstage signature.
    # Names keep Blizzard's underscores: Mod_AddAlpha and Mod_Add_Alpha are
    # two different combiners that collide the moment you camel-case them.
    "m2_combiners.slang|vsM2Diffuse_T1|vertex|kM2Vs_Diffuse_T1"
    "m2_combiners.slang|vsM2Diffuse_Env|vertex|kM2Vs_Diffuse_Env"
    "m2_combiners.slang|vsM2Diffuse_T1_T2|vertex|kM2Vs_Diffuse_T1_T2"
    "m2_combiners.slang|vsM2Diffuse_T1_Env|vertex|kM2Vs_Diffuse_T1_Env"
    "m2_combiners.slang|vsM2Diffuse_Env_T1|vertex|kM2Vs_Diffuse_Env_T1"
    "m2_combiners.slang|vsM2Diffuse_Env_Env|vertex|kM2Vs_Diffuse_Env_Env"
    "m2_combiners.slang|vsM2Diffuse_T1_Env_T1|vertex|kM2Vs_Diffuse_T1_Env_T1"
    "m2_combiners.slang|vsM2Diffuse_T1_T1|vertex|kM2Vs_Diffuse_T1_T1"
    "m2_combiners.slang|vsM2Diffuse_T1_T1_T1|vertex|kM2Vs_Diffuse_T1_T1_T1"
    "m2_combiners.slang|vsM2Diffuse_EdgeFade_T1|vertex|kM2Vs_Diffuse_EdgeFade_T1"
    "m2_combiners.slang|vsM2Diffuse_T2|vertex|kM2Vs_Diffuse_T2"
    "m2_combiners.slang|vsM2Diffuse_T1_Env_T2|vertex|kM2Vs_Diffuse_T1_Env_T2"
    "m2_combiners.slang|vsM2Diffuse_EdgeFade_T1_T2|vertex|kM2Vs_Diffuse_EdgeFade_T1_T2"
    "m2_combiners.slang|vsM2Diffuse_T1_T1_T1_T2|vertex|kM2Vs_Diffuse_T1_T1_T1_T2"
    "m2_combiners.slang|vsM2Diffuse_EdgeFade_Env|vertex|kM2Vs_Diffuse_EdgeFade_Env"
    "m2_combiners.slang|vsM2Diffuse_T1_T2_T1|vertex|kM2Vs_Diffuse_T1_T2_T1"
    "m2_combiners.slang|psM2Combiners_Opaque|fragment|kM2Ps_Combiners_Opaque"
    "m2_combiners.slang|psM2Combiners_Mod|fragment|kM2Ps_Combiners_Mod"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod|fragment|kM2Ps_Combiners_Opaque_Mod"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2x|fragment|kM2Ps_Combiners_Opaque_Mod2x"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2xNA|fragment|kM2Ps_Combiners_Opaque_Mod2xNA"
    "m2_combiners.slang|psM2Combiners_Opaque_Opaque|fragment|kM2Ps_Combiners_Opaque_Opaque"
    "m2_combiners.slang|psM2Combiners_Mod_Mod|fragment|kM2Ps_Combiners_Mod_Mod"
    "m2_combiners.slang|psM2Combiners_Mod_Mod2x|fragment|kM2Ps_Combiners_Mod_Mod2x"
    "m2_combiners.slang|psM2Combiners_Mod_Add|fragment|kM2Ps_Combiners_Mod_Add"
    "m2_combiners.slang|psM2Combiners_Mod_Mod2xNA|fragment|kM2Ps_Combiners_Mod_Mod2xNA"
    "m2_combiners.slang|psM2Combiners_Mod_AddNA|fragment|kM2Ps_Combiners_Mod_AddNA"
    "m2_combiners.slang|psM2Combiners_Mod_Opaque|fragment|kM2Ps_Combiners_Mod_Opaque"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2xNA_Alpha|fragment|kM2Ps_Combiners_Opaque_Mod2xNA_Alpha"
    "m2_combiners.slang|psM2Combiners_Opaque_AddAlpha|fragment|kM2Ps_Combiners_Opaque_AddAlpha"
    "m2_combiners.slang|psM2Combiners_Opaque_AddAlpha_Alpha|fragment|kM2Ps_Combiners_Opaque_AddAlpha_Alpha"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2xNA_Alpha_Add|fragment|kM2Ps_Combiners_Opaque_Mod2xNA_Alpha_Add"
    "m2_combiners.slang|psM2Combiners_Mod_AddAlpha|fragment|kM2Ps_Combiners_Mod_AddAlpha"
    "m2_combiners.slang|psM2Combiners_Mod_AddAlpha_Alpha|fragment|kM2Ps_Combiners_Mod_AddAlpha_Alpha"
    "m2_combiners.slang|psM2Combiners_Opaque_Alpha_Alpha|fragment|kM2Ps_Combiners_Opaque_Alpha_Alpha"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2xNA_Alpha_3s|fragment|kM2Ps_Combiners_Opaque_Mod2xNA_Alpha_3s"
    "m2_combiners.slang|psM2Combiners_Opaque_AddAlpha_Wgt|fragment|kM2Ps_Combiners_Opaque_AddAlpha_Wgt"
    "m2_combiners.slang|psM2Combiners_Mod_Add_Alpha|fragment|kM2Ps_Combiners_Mod_Add_Alpha"
    "m2_combiners.slang|psM2Combiners_Opaque_ModNA_Alpha|fragment|kM2Ps_Combiners_Opaque_ModNA_Alpha"
    "m2_combiners.slang|psM2Combiners_Mod_AddAlpha_Wgt|fragment|kM2Ps_Combiners_Mod_AddAlpha_Wgt"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod_Add_Wgt|fragment|kM2Ps_Combiners_Opaque_Mod_Add_Wgt"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2xNA_Alpha_UnshAlpha|fragment|kM2Ps_Combiners_Opaque_Mod2xNA_Alpha_UnshAlpha"
    "m2_combiners.slang|psM2Combiners_Mod_Dual_Crossfade|fragment|kM2Ps_Combiners_Mod_Dual_Crossfade"
    "m2_combiners.slang|psM2Combiners_Opaque_Mod2xNA_Alpha_Alpha|fragment|kM2Ps_Combiners_Opaque_Mod2xNA_Alpha_Alpha"
    "m2_combiners.slang|psM2Combiners_Mod_Masked_Dual_Crossfade|fragment|kM2Ps_Combiners_Mod_Masked_Dual_Crossfade"
    "m2_combiners.slang|psM2Combiners_Opaque_Alpha|fragment|kM2Ps_Combiners_Opaque_Alpha"
    "m2_combiners.slang|psM2Guild|fragment|kM2Ps_Guild"
    "m2_combiners.slang|psM2Guild_NoBorder|fragment|kM2Ps_Guild_NoBorder"
    "m2_combiners.slang|psM2Guild_Opaque|fragment|kM2Ps_Guild_Opaque"
    "m2_combiners.slang|psM2Combiners_Mod_Depth|fragment|kM2Ps_Combiners_Mod_Depth"
    "m2_combiners.slang|psM2Combiners_Mod_Mod_Depth|fragment|kM2Ps_Combiners_Mod_Mod_Depth"
    "m2_combiners.slang|psM2Illum|fragment|kM2Ps_Illum"
    # Debug views: every combiner, by pixel-shader id, at fixed light.
    "m2_combiners.slang|psM2Debug|fragment|kM2Ps_Debug"
    # M3 simple material (M3_SIMPLE_MATERIAL_DESIGN.md): forward and MRT pixel
    # entries share one shading function; the split exists because Vulkan
    # rejects a PS declaring outputs the pass never binds.
    "m3_standard.slang|vsM3Standard|vertex|kM3StandardVS"
    "m3_standard.slang|vsM3StandardSkinned|vertex|kM3StandardSkinnedVS"
    "m3_standard.slang|psM3Standard|fragment|kM3StandardPS"
    "m3_standard.slang|psM3StandardMrt|fragment|kM3StandardMrtPS"
    # Debug views: ShadeM3's terms through debug_view.slang. The MRT twin writes
    # the overridden albedo so the deferred lights agree in the lighting views.
    "m3_standard.slang|psM3StandardDebug|fragment|kM3StandardDebugPS"
    "m3_standard.slang|psM3StandardDebugMrt|fragment|kM3StandardDebugMrtPS"
    # The ribbon strip VS: world-space CPU strip into the shared full material
    # PS (psM3Standard). No PS of its own — the ribbon runs the geoset shader.
    "m3_standard.slang|vsM3Ribbon|vertex|kM3RibbonVS"
    # D3 standard material (Diablo III actors). One PS: the frame is gamma-LDR
    # with no G-buffer, so there is no MRT twin to split off.
    "d3_standard.slang|vsD3Standard|vertex|kD3StandardVS"
    "d3_standard.slang|vsD3StandardSkinned|vertex|kD3StandardSkinnedVS"
    "d3_standard.slang|psD3Standard|fragment|kD3StandardPS"
    # Debug views: both material shapes' terms through debug_view.slang.
    "d3_standard.slang|psD3StandardDebug|fragment|kD3StandardDebugPS"
    # D3 particles. `Billboard.fx` / `ps_legacy` is a four-stage fixed-function
    # chain with a UV transform per stage; the SD program has one texture and no
    # chain at all. See D3_PARTICLE_DESIGN.md §8.
    "d3_particle.slang|vsD3Particle|vertex|kD3ParticleVS"
    "d3_particle.slang|psD3Particle|fragment|kD3ParticlePS"
    "m3_deferred_light.slang|vsM3DeferredLight|vertex|kM3DeferredLightVS"
    "m3_deferred_light.slang|psM3DeferredLight|fragment|kM3DeferredLightPS"
    # Debug views (DEBUG_VIEW_DESIGN.md). The WC3 programs pair with the retail
    # HD / SD vertex permutations and import Wc3Shaders for every decode, so they
    # take the `wc3` flag set: its include path and the DX constant-buffer layout
    # the BLS build compiles the programs they stand in for with. The lighting
    # variants exist per shadow map a frame may or may not have bound.
    "wc3_debug.slang|psWc3HdDebug|fragment|kWc3HdDebugPS|wc3"
    "wc3_debug.slang|psWc3HdDebugCsm|fragment|kWc3HdDebugCsmPS|wc3"
    "wc3_debug.slang|psWc3HdDebugCube|fragment|kWc3HdDebugCubePS|wc3"
    "wc3_debug.slang|psWc3HdDebugCsmCube|fragment|kWc3HdDebugCsmCubePS|wc3"
    "wc3_debug.slang|psWc3SdDebug|fragment|kWc3SdDebugPS|wc3"
    "wc3_debug.slang|vsWc3SdDebug|vertex|kWc3SdDebugVS|wc3"
    "wc3_debug.slang|vsWc3SdDebugSkinned|vertex|kWc3SdDebugSkinnedVS|wc3"
    "wc3_debug.slang|psWc3SdDebugNormal|fragment|kWc3SdDebugNormalPS|wc3"
    # Mesh overlay (DEBUG_VIEW_DESIGN.md §9): one pixel entry, and per product a
    # vertex entry per skinning path that imports the product's own vertex code.
    # The `overlay` set silences the constant-buffer overlap the entries take on
    # purpose (the debug view's b3) and tracks the imported product files.
    "mesh_overlay.slang|psMeshOverlay|fragment|kMeshOverlayPS|overlay"
    "m2_overlay.slang|vsM2Overlay|vertex|kM2OverlayVS|overlay"
    "m3_overlay.slang|vsM3Overlay|vertex|kM3OverlayVS|overlay"
    "m3_overlay.slang|vsM3OverlaySkinned|vertex|kM3OverlaySkinnedVS|overlay"
    "d3_overlay.slang|vsD3Overlay|vertex|kD3OverlayVS|overlay"
    "d3_overlay.slang|vsD3OverlaySkinned|vertex|kD3OverlaySkinnedVS|overlay"
    "unlit_overlay.slang|vsUnlitOverlay|vertex|kUnlitOverlayVS|overlay"
    "unlit_overlay.slang|vsUnlitOverlaySkinned|vertex|kUnlitOverlaySkinnedVS|overlay"
    "wc3_overlay.slang|vsWc3HdOverlay|vertex|kWc3HdOverlayVS|wc3"
    "wc3_overlay.slang|vsWc3HdOverlayPalette|vertex|kWc3HdOverlayPaletteVS|wc3"
    "wc3_overlay.slang|vsWc3HdOverlayBoneBuffer|vertex|kWc3HdOverlayBoneBufferVS|wc3"
    "wc3_overlay.slang|vsWc3SdOverlay|vertex|kWc3SdOverlayVS|wc3"
    "wc3_overlay.slang|vsWc3SdOverlaySkinned|vertex|kWc3SdOverlaySkinnedVS|wc3"
    # NOTE: depth of field has no custom shader entry — DofService runs the
    # shipped WC3 depthoffield.bls (GxShaderID DepthOfField) through the BLS
    # shader cache, and reuses the embedded blit (kBlit*) for the round-trip.
)

# The WC3 debug pixel programs that pair with a RETAIL vertex program. On D3D12
# that program is DXIL (shaders/d3d12/), and the runtime will not link SM 6
# with SM 5, so these also build as DXIL. Through the same slangc that builds
# the d3d12 bundles, so both stages spell their semantics the same way.
set(WC3_DXIL_ENTRIES kWc3HdDebugPS kWc3HdDebugCsmPS kWc3HdDebugCubePS kWc3HdDebugCsmCubePS
    kWc3SdDebugPS)

set(SHADER_DXBC_FILES "")
set(SHADER_DXIL_FILES "")
set(SHADER_SPV_FILES  "")
set(SHADER_WGSL_FILES "")
set(SHADER_MTL_FILES  "")

foreach(entry IN LISTS SHADER_ENTRIES)
    string(REPLACE "|" ";" parts "${entry}")
    list(GET parts 0 src_file)
    list(GET parts 1 entry_name)
    list(GET parts 2 stage)
    list(GET parts 3 var_name)
    # Optional fifth column: a named flag set.
    set(entry_flags "")
    set(entry_spv_flags "")
    set(entry_deps "${SHADER_SRC_DIR}/common.slang" "${SHADER_SRC_DIR}/debug_view.slang")
    list(LENGTH parts part_count)
    if(part_count GREATER 4)
        list(GET parts 4 flag_set)
        if(flag_set STREQUAL "wc3")
            set(entry_flags -I "${CMAKE_CURRENT_SOURCE_DIR}/externals/Wc3Shaders/wc3_shaders"
                -warnings-disable 39001,15205,30056,41016)
            set(entry_spv_flags -fvk-use-dx-layout)
            list(APPEND entry_deps
                "${CMAKE_CURRENT_SOURCE_DIR}/externals/Wc3Shaders/wc3_shaders/wc3_shaders.slang"
                "${SHADER_SRC_DIR}/mesh_overlay.slang")
        elseif(flag_set STREQUAL "overlay")
            set(entry_flags -warnings-disable 39001)
            list(APPEND entry_deps "${SHADER_SRC_DIR}/mesh_overlay.slang"
                "${SHADER_SRC_DIR}/m2_combiners.slang" "${SHADER_SRC_DIR}/m3_standard.slang"
                "${SHADER_SRC_DIR}/d3_standard.slang" "${SHADER_SRC_DIR}/unlit.slang")
        endif()
    endif()

    set(dxbc_path "${SHADER_OUT_DIR}/${var_name}.dxbc")
    set(spv_path  "${SHADER_OUT_DIR}/${var_name}.spv")

    # DXBC is Windows-only: slangc's DXBC backend invokes fxc internally,
    # and fxc.exe ships with the Windows SDK / d3dcompiler — there's no
    # Linux/macOS equivalent. On non-Windows hosts we skip the DXBC step
    # entirely and let embed_shaders.cmake stub the DXBC C++ symbols so
    # the consumer call sites still compile (they're never reached at
    # runtime on platforms without D3D).
    if(WIN32)
        add_custom_command(
            OUTPUT  "${dxbc_path}"
            COMMAND "${SLANGC}" "${SHADER_SRC_DIR}/${src_file}"
                    ${SLANG_COMMON_FLAGS} ${entry_flags}
                    -entry ${entry_name} -stage ${stage}
                    -target dxbc -profile sm_5_0
                    -o "${dxbc_path}"
            DEPENDS "${SHADER_SRC_DIR}/${src_file}"
                    ${entry_deps}
            COMMENT "Slang: ${src_file} [${entry_name}] → ${var_name}.dxbc"
            VERBATIM
        )
        list(APPEND SHADER_DXBC_FILES "${dxbc_path}")

        if(var_name IN_LIST WC3_DXIL_ENTRIES)
            set(dxil_path "${SHADER_OUT_DIR}/${var_name}.dxil")
            add_custom_command(
                OUTPUT  "${dxil_path}"
                COMMAND "${SLANGC}" "${SHADER_SRC_DIR}/${src_file}"
                        ${SLANG_COMMON_FLAGS} ${entry_flags}
                        -entry ${entry_name} -stage ${stage}
                        -target dxil -profile sm_6_0
                        -o "${dxil_path}"
                DEPENDS "${SHADER_SRC_DIR}/${src_file}"
                        ${entry_deps}
                COMMENT "Slang: ${src_file} [${entry_name}] → ${var_name}.dxil"
                VERBATIM
            )
            list(APPEND SHADER_DXIL_FILES "${dxil_path}")
        endif()
    endif()

    # SPIR-V variant for the Vulkan backend. The embed script picks these
    # up alongside the .dxbc blobs and emits a parallel `<var>Spv[]` array
    # in compiled_shaders.h. Compiled here unconditionally — the resulting
    # bytes are unused (and harmless) when WDX_HAS_VULKAN is off.
    add_custom_command(
        OUTPUT  "${spv_path}"
        COMMAND "${SLANGC}" "${SHADER_SRC_DIR}/${src_file}"
                ${SLANG_COMMON_FLAGS} ${entry_flags} ${entry_spv_flags}
                -entry ${entry_name} -stage ${stage}
                -target spirv -profile glsl_450
                -o "${spv_path}"
        DEPENDS "${SHADER_SRC_DIR}/${src_file}"
                ${entry_deps}
        COMMENT "Slang: ${src_file} [${entry_name}] → ${var_name}.spv"
        VERBATIM
    )
    list(APPEND SHADER_SPV_FILES "${spv_path}")

    # WGSL variant for the WebGPU backend. Only emitted when WDX_ENABLE_WEBGPU
    # is on — otherwise the embed script's stub keeps the consumer code
    # type-checking without dragging the slangc invocation into every build.
    if(WDX_ENABLE_WEBGPU)
        set(wgsl_path "${SHADER_OUT_DIR}/${var_name}.wgsl")
        set(wgsl_post "")
        if(entry_spv_flags)
            # The wc3 set: slangc types comparison-sampled textures as colour.
            set(wgsl_post COMMAND "${CMAKE_COMMAND}" "-DWGSL=${wgsl_path}"
                          -P "${SHADER_SRC_DIR}/wgsl_depth_textures.cmake")
        endif()
        add_custom_command(
            OUTPUT  "${wgsl_path}"
            COMMAND "${SLANGC}" "${SHADER_SRC_DIR}/${src_file}"
                    ${SLANG_COMMON_FLAGS} ${entry_flags}
                    -DWGSL_TARGET=1
                    -entry ${entry_name} -stage ${stage}
                    -target wgsl
                    -o "${wgsl_path}"
            ${wgsl_post}
            DEPENDS "${SHADER_SRC_DIR}/${src_file}"
                    ${entry_deps}
            COMMENT "Slang: ${src_file} [${entry_name}] → ${var_name}.wgsl"
            VERBATIM
        )
        list(APPEND SHADER_WGSL_FILES "${wgsl_path}")
    endif()

    # Metal library bytecode for the Metal backend. macOS-only — needs
    # Apple's metal compiler (Xcode's Metal Toolchain). slangc's metallib
    # backend invokes xcrun metal internally and pins the container at
    # version 1.2.7 (Metal 4.x); fine for the debug line / blit /
    # framebuffer-capture shaders here — the renderer just loads them as
    # opaque bytes. The Wc3Shaders pipeline targets metallib 1.2.5 by
    # post-processing slangc's .metal emit, but that machinery isn't
    # needed for this small set of shaders.
    if(WDX_ENABLE_METAL AND APPLE)
        set(mtl_path "${SHADER_OUT_DIR}/${var_name}.metallib")
        add_custom_command(
            OUTPUT  "${mtl_path}"
            COMMAND "${SLANGC}" "${SHADER_SRC_DIR}/${src_file}"
                    ${SLANG_COMMON_FLAGS} ${entry_flags}
                    -DMETAL_TARGET=1
                    -entry ${entry_name} -stage ${stage}
                    -target metallib -profile sm_6_0
                    -o "${mtl_path}"
            DEPENDS "${SHADER_SRC_DIR}/${src_file}"
                    ${entry_deps}
            COMMENT "Slang: ${src_file} [${entry_name}] → ${var_name}.metallib"
            VERBATIM
        )
        list(APPEND SHADER_MTL_FILES "${mtl_path}")
    endif()
endforeach()

# Embed all DXBC blobs into a single C++ header
set(COMPILED_SHADERS_H "${SHADER_OUT_DIR}/compiled_shaders.h")

# Emscripten has no Vulkan backend, and the SPIR-V twin of every shader is
# ~780 KB the browser can never reach — a quarter of the wasm. Stub the bytes
# there; the symbols still exist, so the per-backend selectors compile.
if(EMSCRIPTEN)
    set(_wf_embed_spv OFF)
else()
    set(_wf_embed_spv ON)
endif()

add_custom_command(
    OUTPUT  "${COMPILED_SHADERS_H}"
    COMMAND "${CMAKE_COMMAND}"
            "-DSHADER_DIR=${SHADER_OUT_DIR}"
            "-DOUTPUT=${COMPILED_SHADERS_H}"
            "-DEMBED_SPV=${_wf_embed_spv}"
            -P "${SHADER_SRC_DIR}/embed_shaders.cmake"
    DEPENDS ${SHADER_DXBC_FILES} ${SHADER_DXIL_FILES} ${SHADER_SPV_FILES} ${SHADER_WGSL_FILES}
            ${SHADER_MTL_FILES}
            "${SHADER_SRC_DIR}/embed_shaders.cmake"
    COMMENT "Embedding compiled shaders into compiled_shaders.h"
    VERBATIM
)

add_custom_target(WhiteoutFlakesShaders DEPENDS "${COMPILED_SHADERS_H}")

# ============================================================================
# Embedded resources (build-time: binary file → C++ header with byte array)
# ============================================================================

set(EMBED_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/embedded")
file(MAKE_DIRECTORY "${EMBED_OUT_DIR}")

set(TEAM_GLOW_TGA "${CMAKE_CURRENT_SOURCE_DIR}/resources/teamglow.tga")
set(TEAM_GLOW_H   "${EMBED_OUT_DIR}/team_glow_embedded.h")

add_custom_command(
    OUTPUT  "${TEAM_GLOW_H}"
    COMMAND "${CMAKE_COMMAND}"
            "-DINPUT=${TEAM_GLOW_TGA}"
            "-DOUTPUT=${TEAM_GLOW_H}"
            "-DVAR_NAME=kTeamGlowTGA"
            "-DNAMESPACE=whiteout::flakes::io"
            -P "${CMAKE_CURRENT_SOURCE_DIR}/resources/embed_binary.cmake"
    DEPENDS "${TEAM_GLOW_TGA}"
            "${CMAKE_CURRENT_SOURCE_DIR}/resources/embed_binary.cmake"
    COMMENT "Embedding teamglow.tga into team_glow_embedded.h"
    VERBATIM
)

# Roboto-Medium for the ImGui host theme — hinted TTF (vs. ProggyClean bitmap)
# so DPI-scaled UIs stay crisp instead of bilinear-upscaled.
set(ROBOTO_TTF "${CMAKE_CURRENT_SOURCE_DIR}/externals/imgui/misc/fonts/Roboto-Medium.ttf")
set(ROBOTO_H   "${EMBED_OUT_DIR}/roboto_medium_embedded.h")

add_custom_command(
    OUTPUT  "${ROBOTO_H}"
    COMMAND "${CMAKE_COMMAND}"
            "-DINPUT=${ROBOTO_TTF}"
            "-DOUTPUT=${ROBOTO_H}"
            "-DVAR_NAME=kRobotoMediumTTF"
            "-DNAMESPACE=whiteout::flakes::ui"
            -P "${CMAKE_CURRENT_SOURCE_DIR}/resources/embed_binary.cmake"
    DEPENDS "${ROBOTO_TTF}"
            "${CMAKE_CURRENT_SOURCE_DIR}/resources/embed_binary.cmake"
    COMMENT "Embedding Roboto-Medium.ttf into roboto_medium_embedded.h"
    VERBATIM
)

# The application's own icon, for the ribbon's application tile. Embedded
# rather than staged beside the exe because a host that is not the standalone
# viewer — the Max plugin ships as one .dlu — has no asset directory to look in.
set(FLAKES_ICON_PNG "${CMAKE_CURRENT_SOURCE_DIR}/resources/flakes_icon_linux.png")
set(FLAKES_ICON_H   "${EMBED_OUT_DIR}/flakes_icon_embedded.h")

add_custom_command(
    OUTPUT  "${FLAKES_ICON_H}"
    COMMAND "${CMAKE_COMMAND}"
            "-DINPUT=${FLAKES_ICON_PNG}"
            "-DOUTPUT=${FLAKES_ICON_H}"
            "-DVAR_NAME=kFlakesIconPNG"
            "-DNAMESPACE=whiteout::flakes::ui"
            -P "${CMAKE_CURRENT_SOURCE_DIR}/resources/embed_binary.cmake"
    DEPENDS "${FLAKES_ICON_PNG}"
            "${CMAKE_CURRENT_SOURCE_DIR}/resources/embed_binary.cmake"
    COMMENT "Embedding flakes_icon_linux.png into flakes_icon_embedded.h"
    VERBATIM
)

add_custom_target(WhiteoutFlakesEmbedded DEPENDS "${TEAM_GLOW_H}" "${ROBOTO_H}" "${FLAKES_ICON_H}")

# ============================================================================
# Wc3Shaders — opt-in build of the externals/Wc3Shaders Slang reconstruction.
#
# When WDX_BUILD_WC3_SHADERS=ON, drives the submodule's two-step Python
# pipeline (compile_all_slang.py → DXBC + DXIL, then build_bls.py → .bls)
# and copies the resulting BLS bundles next to the standalone exe under
# Shaders/{ps,vs}/. Packing requires the shipped war3.w3mod/shaders/ tree
# (binding-metadata templates), supplied via -DWDX_SHADER_TEMPLATES=<path>.
# Both DXBC (sm 5.0, primary — what the BLS loader reads) and DXIL (sm 6.0,
# kept as raw .dxil under wc3_shaders/slang_out/ for future use) targets
# are produced.
# ============================================================================

option(WDX_BUILD_WC3_SHADERS
    "Compile the externals/Wc3Shaders Slang sources and pack BLS bundles"
    OFF)

# When ON (and WDX_BUILD_WC3_SHADERS is too), a second pass builds a
# parallel set of BLS bundles with full debug symbols (slangc -g2 -O0,
# +emit-spirv-directly) and stages them into standalone/debug_shaders/.
# The renderer loads those instead of standalone/shaders/ when graphics
# debug is on. Roughly doubles the Wc3Shaders compile time and the
# emitted bundles weigh ~865 MB — opt in only when actively debugging
# shaders. Not committed under prebuilt/ for the same size reason.
option(WDX_BUILD_WC3_DEBUG_SHADERS
    "Also build debug-symbol BLS bundles into debug_shaders/"
    OFF)

# Use the pre-baked .bls bundles committed under prebuilt/shaders/ instead of
# re-running slangc. Mutually exclusive with WDX_BUILD_WC3_SHADERS — the
# auto-detect at the bottom of this option block flips it on by default
# whenever the prebuilt dir exists *and* shader compilation is off, which
# covers both the GitHub CI case (slangc isn't installed) and a fresh clone
# without the Vulkan SDK.
option(WDX_USE_PREBUILT_SHADERS
    "Stage the prebuilt/shaders pack instead of running the Slang toolchain"
    OFF)
if(NOT WDX_USE_PREBUILT_SHADERS AND NOT WDX_BUILD_WC3_SHADERS
        AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/shaders")
    set(WDX_USE_PREBUILT_SHADERS ON CACHE BOOL
        "Stage the prebuilt/shaders pack instead of running the Slang toolchain"
        FORCE)
    message(STATUS "Wc3Shaders: WDX_USE_PREBUILT_SHADERS auto-enabled (prebuilt/shaders found)")
endif()
if(WDX_BUILD_WC3_SHADERS AND WDX_USE_PREBUILT_SHADERS)
    message(FATAL_ERROR
        "WDX_BUILD_WC3_SHADERS and WDX_USE_PREBUILT_SHADERS are mutually exclusive — "
        "one runs slangc, the other copies pre-baked bundles. Pick one.")
endif()

# Where the viewer exe lands, spelled without naming the target (a generator
# expression on WhiteoutFlakesStandalone would make Wc3Shaders depend on the
# viewer, which depends on Wc3Shaders). The viewer pins Debug and Release to
# standalone/; multi-config generators put every other config one level below.
if(CMAKE_CONFIGURATION_TYPES)
    set(WDX_VIEWER_EXE_DIR
        "${CMAKE_BINARY_DIR}/standalone/$<$<NOT:$<CONFIG:Debug,Release>>:$<CONFIG>>")
else()
    set(WDX_VIEWER_EXE_DIR "${CMAKE_BINARY_DIR}/standalone")
endif()

if(WDX_USE_PREBUILT_SHADERS)
    set(WDX_PREBUILT_SHADERS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/shaders"
        CACHE PATH "Pre-baked .bls staging tree (mirrors standalone/shaders/ layout)")
    if(NOT EXISTS "${WDX_PREBUILT_SHADERS_DIR}")
        message(FATAL_ERROR
            "WDX_USE_PREBUILT_SHADERS=ON but ${WDX_PREBUILT_SHADERS_DIR} is missing. "
            "Run cmake --build build --target update-prebuilt-shaders against a "
            "tree where WDX_BUILD_WC3_SHADERS=ON to populate it.")
    endif()
    # Stage prebuilt → standalone/shaders so the runtime exe-dir lookup
    # finds them with no extra path config (matches the WDX_BUILD_WC3_SHADERS
    # codegen layout exactly).
    set(_prebuilt_stage "${CMAKE_BINARY_DIR}/standalone/shaders")
    set(_prebuilt_stamp "${CMAKE_CURRENT_BINARY_DIR}/wc3_prebuilt.stamp")
    add_custom_command(
        OUTPUT  "${_prebuilt_stamp}"
        COMMAND "${CMAKE_COMMAND}" -E rm -rf "${_prebuilt_stage}"
        COMMAND "${CMAKE_COMMAND}" -E copy_directory
                "${WDX_PREBUILT_SHADERS_DIR}" "${_prebuilt_stage}"
        COMMAND "${CMAKE_COMMAND}" -E touch "${_prebuilt_stamp}"
        # Re-stage when any prebuilt file changes (developer pulled new
        # prebuilt/ from git).
        DEPENDS "${WDX_PREBUILT_SHADERS_DIR}"
        COMMENT "Wc3Shaders[prebuilt]: staging ${WDX_PREBUILT_SHADERS_DIR} -> ${_prebuilt_stage}"
        VERBATIM)
    # Beside the exe too, for the configs whose exe is not in standalone/
    # (the same reason as the compiled pack's exe stage below).
    set(_prebuilt_exe_stamp "${CMAKE_CURRENT_BINARY_DIR}/wc3_prebuilt_exe_$<CONFIG>.stamp")
    add_custom_command(
        OUTPUT  "${_prebuilt_exe_stamp}"
        COMMAND "${CMAKE_COMMAND}"
                "-DSRC=${_prebuilt_stage}"
                "-DDST=${WDX_VIEWER_EXE_DIR}/shaders"
                "-DSTAMP=${_prebuilt_exe_stamp}"
                -P "${CMAKE_CURRENT_SOURCE_DIR}/resources/copy_dir_unless_same.cmake"
        DEPENDS "${_prebuilt_stamp}" "${CMAKE_CURRENT_SOURCE_DIR}/resources/copy_dir_unless_same.cmake"
        COMMENT "Wc3Shaders[prebuilt]: staging the pack beside the viewer exe"
        VERBATIM)
    add_custom_target(Wc3Shaders ALL DEPENDS "${_prebuilt_exe_stamp}")

    # debug_shaders/ is intentionally not prebuilt — the .bls bundles
    # weigh ~865 MB and bloat the repo. Developers who need them flip
    # WDX_BUILD_WC3_SHADERS=ON locally (which also honors
    # WDX_BUILD_WC3_DEBUG_SHADERS=ON to produce standalone/debug_shaders/).
endif()

if(WDX_BUILD_WC3_SHADERS)
    set(WC3_SHADERS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/externals/Wc3Shaders")

    if(NOT EXISTS "${WC3_SHADERS_DIR}/compile_all_slang.py")
        message(FATAL_ERROR
            "WDX_BUILD_WC3_SHADERS=ON but externals/Wc3Shaders/ is empty. "
            "Initialize the submodule with: git submodule update --init externals/Wc3Shaders")
    endif()

    # Default to the locally-vendored war3.w3mod/shaders/ tree at the
    # project root (gitignored). Users can still override with
    # -DWDX_SHADER_TEMPLATES=<path> when their templates live elsewhere.
    if(NOT DEFINED WDX_SHADER_TEMPLATES OR WDX_SHADER_TEMPLATES STREQUAL "")
        set(WDX_SHADER_TEMPLATES "${CMAKE_CURRENT_SOURCE_DIR}/war3.w3mod/shaders"
            CACHE PATH "Path to extracted war3.w3mod/shaders/ BLS templates")
    endif()
    if(NOT EXISTS "${WDX_SHADER_TEMPLATES}")
        message(FATAL_ERROR
            "WDX_SHADER_TEMPLATES does not exist: ${WDX_SHADER_TEMPLATES}\n"
            "Point at an extracted war3.w3mod/shaders/ directory containing "
            "the shipped {ps,vs}/*.bls templates, or place the tree at "
            "${CMAKE_CURRENT_SOURCE_DIR}/war3.w3mod/shaders/ to use the default.")
    endif()

    find_package(Python3 REQUIRED COMPONENTS Interpreter)
    message(STATUS "Wc3Shaders: Python = ${Python3_EXECUTABLE}")
    message(STATUS "Wc3Shaders: BLS templates = ${WDX_SHADER_TEMPLATES}")

    # The Python scripts hardcode their output under <repo>/slang_out and
    # <repo>/bls_out (both gitignored inside the submodule). We use a stamp
    # file pattern for dependency tracking — globs catch source / config
    # changes; the slangc the renderer's debug shaders found is forwarded
    # so we don't need to re-resolve.
    file(GLOB_RECURSE WC3_SLANG_SOURCES
        "${WC3_SHADERS_DIR}/wc3_shaders/*.slang"
        "${WC3_SHADERS_DIR}/custom_shaders/*.slang")
    set(WC3_BUILD_SCRIPTS
        "${WC3_SHADERS_DIR}/compile_all_slang.py"
        "${WC3_SHADERS_DIR}/build_bls.py"
        "${WC3_SHADERS_DIR}/shader_config.py"
        "${WC3_SHADERS_DIR}/wc3_shaders.json"
        "${WC3_SHADERS_DIR}/custom_shaders.json")

    # Optional cache var: semicolon-separated list of shader families to
    # compile. Defaults to empty → compile every family. The compile
    # script's --family flag accepts the same names; only the listed
    # families get re-slang'd, every other family reuses the previous
    # slang_out/<target>/<family>/ output (and BLS bundles).
    set(WDX_WC3_FAMILIES "" CACHE STRING "Wc3Shaders families to re-compile (empty = all)")
    set(WC3_FAMILY_ARGS "")
    if(WDX_WC3_FAMILIES)
        foreach(fam IN LISTS WDX_WC3_FAMILIES)
            list(APPEND WC3_FAMILY_ARGS --family "${fam}")
        endforeach()
        message(STATUS "Wc3Shaders: limiting compile to families: ${WDX_WC3_FAMILIES}")
    endif()

    # Build one variant of the Wc3Shaders pipeline end to end:
    #   compile Slang -> {DXBC, DXIL, SPIR-V}  (compile_all_slang.py)
    #   pack .bls bundles                      (build_bls.py)
    #   stage into the standalone exe's <stage_subdir>/ tree
    #
    # The release variant compiles optimised bytecode into slang_out/ and
    # packs it (with --strip) into shaders/. The debug variant passes
    # --debug to compile_all_slang.py (slangc -g2 -O0, +emit-spirv-directly;
    # output diverted to slang_out_debug/), then packs *without* --strip —
    # stripping would trim the input-signature/debug data we want kept —
    # into debug_shaders/. Both reuse the same .slang sources, the same
    # WC3_FAMILY_ARGS filter, and the same v1.8/v1.14 → flat layout
    # flattening so the renderer's BLS cache only knows two roots:
    # shaders/ and debug_shaders/.
    #
    # Sets ${out_stamp_var} in the caller's scope to the final stage stamp.
    function(wc3_shader_pipeline variant is_debug stage_subdir out_stamp_var)
        if(is_debug)
            set(_compile_extra --debug)
            set(_slang_out "${WC3_SHADERS_DIR}/slang_out_debug")
            set(_bls_out   "${WC3_SHADERS_DIR}/bls_out_debug")
            set(_bls_slang_out_arg --slang-out "${_slang_out}")
            set(_bls_strip_arg)            # debug: keep signatures/debug info
        else()
            set(_compile_extra)            # release: no extra flag
            set(_slang_out "${WC3_SHADERS_DIR}/slang_out")
            set(_bls_out   "${WC3_SHADERS_DIR}/bls_out")
            set(_bls_slang_out_arg)        # build_bls.py defaults to slang_out
            set(_bls_strip_arg --strip)
        endif()

        set(_dxbc  "${CMAKE_CURRENT_BINARY_DIR}/wc3_${variant}_dxbc.stamp")
        set(_dxil  "${CMAKE_CURRENT_BINARY_DIR}/wc3_${variant}_dxil.stamp")
        set(_spirv "${CMAKE_CURRENT_BINARY_DIR}/wc3_${variant}_spirv.stamp")
        set(_wgsl  "${CMAKE_CURRENT_BINARY_DIR}/wc3_${variant}_wgsl.stamp")
        set(_bls   "${CMAKE_CURRENT_BINARY_DIR}/wc3_${variant}_bls.stamp")
        set(_stage "${CMAKE_CURRENT_BINARY_DIR}/wc3_${variant}_stage.stamp")

        add_custom_command(
            OUTPUT  "${_dxbc}"
            COMMAND "${Python3_EXECUTABLE}" "${WC3_SHADERS_DIR}/compile_all_slang.py"
                    --target d3d11 --slangc "${SLANGC}" ${_compile_extra} ${WC3_FAMILY_ARGS}
            COMMAND "${CMAKE_COMMAND}" -E touch "${_dxbc}"
            WORKING_DIRECTORY "${WC3_SHADERS_DIR}"
            DEPENDS ${WC3_SLANG_SOURCES} ${WC3_BUILD_SCRIPTS}
            COMMENT "Wc3Shaders[${variant}]: compiling Slang -> DXBC (d3d11)"
            VERBATIM)

        add_custom_command(
            OUTPUT  "${_dxil}"
            COMMAND "${Python3_EXECUTABLE}" "${WC3_SHADERS_DIR}/compile_all_slang.py"
                    --target d3d12 --slangc "${SLANGC}" ${_compile_extra} ${WC3_FAMILY_ARGS}
            COMMAND "${CMAKE_COMMAND}" -E touch "${_dxil}"
            WORKING_DIRECTORY "${WC3_SHADERS_DIR}"
            DEPENDS ${WC3_SLANG_SOURCES} ${WC3_BUILD_SCRIPTS}
            COMMENT "Wc3Shaders[${variant}]: compiling Slang -> DXIL (d3d12)"
            VERBATIM)

        add_custom_command(
            OUTPUT  "${_spirv}"
            COMMAND "${Python3_EXECUTABLE}" "${WC3_SHADERS_DIR}/compile_all_slang.py"
                    --target vulkan --slangc "${SLANGC_VULKAN}" ${_compile_extra} ${WC3_FAMILY_ARGS}
            COMMAND "${CMAKE_COMMAND}" -E touch "${_spirv}"
            WORKING_DIRECTORY "${WC3_SHADERS_DIR}"
            DEPENDS ${WC3_SLANG_SOURCES} ${WC3_BUILD_SCRIPTS}
            COMMENT "Wc3Shaders[${variant}]: compiling Slang -> SPIR-V (vulkan)"
            VERBATIM)

        # WGSL for the WebGPU backend — only emitted when WDX_ENABLE_WEBGPU
        # is on (the consumer side). compile_all_slang.py writes
        # slang_out/webgpu/<family>/*.wgsl; build_bls.py picks them up
        # automatically and packs them into bls_out_1_14/shaders/{pixel,
        # vertex}/wgsl_1_0/.
        add_custom_command(
            OUTPUT  "${_wgsl}"
            COMMAND "${Python3_EXECUTABLE}" "${WC3_SHADERS_DIR}/compile_all_slang.py"
                    --target webgpu --slangc "${SLANGC_VULKAN}" ${_compile_extra} ${WC3_FAMILY_ARGS}
            COMMAND "${CMAKE_COMMAND}" -E touch "${_wgsl}"
            WORKING_DIRECTORY "${WC3_SHADERS_DIR}"
            DEPENDS ${WC3_SLANG_SOURCES} ${WC3_BUILD_SCRIPTS}
            COMMENT "Wc3Shaders[${variant}]: compiling Slang -> WGSL (webgpu)"
            VERBATIM)

        # Upstream build_bls.py writes two trees:
        #   <output>_1_8/{ps,vs,mtlfs,mtlvs}/*.bls            (Wc3 v1.8 layout)
        #   <output>_1_14/shaders/{pixel,vertex}/<api>/*.bls  (v1.14, WoW-style)
        # where <api> ∈ {dx_5_0, dx_6_0, spv_1_3, …}. The SPIR-V subdir name
        # encodes the slangc-emitted SPIR-V version (1.3 for glsl_450 →
        # Vulkan 1.3).
        set(_bls_out_18 "${_bls_out}_1_8")
        set(_bls_out_14 "${_bls_out}_1_14")
        add_custom_command(
            OUTPUT  "${_bls}"
            COMMAND "${Python3_EXECUTABLE}" "${WC3_SHADERS_DIR}/build_bls.py"
                    --templates "${WDX_SHADER_TEMPLATES}"
                    --output    "${_bls_out}"
                    ${_bls_slang_out_arg}
                    ${_bls_strip_arg}
            COMMAND "${CMAKE_COMMAND}" -E touch "${_bls}"
            WORKING_DIRECTORY "${WC3_SHADERS_DIR}"
            DEPENDS "${_dxbc}" "${_dxil}" "${_spirv}" "${_wgsl}" ${WC3_BUILD_SCRIPTS}
            COMMENT "Wc3Shaders[${variant}]: packing .bls (v1.8 DX + v1.14 DX/SPIR-V/WGSL)"
            VERBATIM)

        # Stage the freshly packed bundles into the standalone exe's output
        # directory the moment Wc3Shaders rebuilds — independently of
        # whether the exe relinks (POST_BUILD on the exe wouldn't fire on a
        # BLS-only change). The standalone exe lands at
        # ${CMAKE_BINARY_DIR}/standalone, so the path is known up front. We
        # flatten the upstream layout into the renderer's path scheme
        # (<root>/{ps,vs,d3d12/ps,d3d12/vs,vulkan/ps,vulkan/vs,metal/ps,metal/vs}/)
        # so the BLS cache only needs to know the two roots shaders/ and
        # debug_shaders/.
        set(_stage_dir "${CMAKE_BINARY_DIR}/standalone/${stage_subdir}")
        # Metal v1.8 bundles — only emitted on macOS where Apple's Metal
        # toolchain is available. compile_all_slang.py auto-adds the
        # metal target on darwin, so the dxbc command above also
        # populates slang_out/metal and build_bls.py packs
        # bls_out_1_8/{mtlfs,mtlvs} in the same run. bls_shader_cache
        # routes GfxApi::Metal → metal/{ps,vs}/.
        set(_extra_stage_cmds "")
        if(APPLE)
            list(APPEND _extra_stage_cmds
                COMMAND "${CMAKE_COMMAND}" -E copy_directory
                        "${_bls_out_18}/mtlfs" "${_stage_dir}/metal/ps"
                COMMAND "${CMAKE_COMMAND}" -E copy_directory
                        "${_bls_out_18}/mtlvs" "${_stage_dir}/metal/vs"
            )
        endif()
        add_custom_command(
            OUTPUT  "${_stage}"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_18}/ps"                       "${_stage_dir}/ps"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_18}/vs"                       "${_stage_dir}/vs"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_14}/shaders/pixel/dx_6_0"     "${_stage_dir}/d3d12/ps"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_14}/shaders/vertex/dx_6_0"    "${_stage_dir}/d3d12/vs"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_14}/shaders/pixel/spv_1_3"    "${_stage_dir}/vulkan/ps"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_14}/shaders/vertex/spv_1_3"   "${_stage_dir}/vulkan/vs"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_14}/shaders/pixel/wgsl_1_0"   "${_stage_dir}/webgpu/ps"
            COMMAND "${CMAKE_COMMAND}" -E copy_directory
                    "${_bls_out_14}/shaders/vertex/wgsl_1_0"  "${_stage_dir}/webgpu/vs"
            ${_extra_stage_cmds}
            COMMAND "${CMAKE_COMMAND}" -E touch "${_stage}"
            DEPENDS "${_bls}"
            COMMENT "Wc3Shaders[${variant}]: staging BLS bundles into ${_stage_dir}"
            VERBATIM)

        # `standalone/` is not the exe directory for every config: Visual
        # Studio puts RelWithDebInfo / MinSizeRel exes one level below it (see
        # the lang/fonts staging on the viewer target). The viewer reads
        # shaders/ beside its exe and falls back to the game's CASC, so a
        # missed copy renders with the RETAIL shaders instead of this pack.
        # Mirror the stage into the exe directory wherever the two differ.
        set(_exe_stage "${CMAKE_BINARY_DIR}/wc3_${variant}_exe_stage_$<CONFIG>.stamp")
        add_custom_command(
            OUTPUT  "${_exe_stage}"
            COMMAND "${CMAKE_COMMAND}"
                    "-DSRC=${_stage_dir}"
                    "-DDST=${WDX_VIEWER_EXE_DIR}/${stage_subdir}"
                    "-DSTAMP=${_exe_stage}"
                    -P "${CMAKE_CURRENT_SOURCE_DIR}/resources/copy_dir_unless_same.cmake"
            DEPENDS "${_stage}" "${CMAKE_CURRENT_SOURCE_DIR}/resources/copy_dir_unless_same.cmake"
            COMMENT "Wc3Shaders[${variant}]: staging BLS bundles beside the viewer exe"
            VERBATIM)

        set(${out_stamp_var} "${_exe_stage}" PARENT_SCOPE)
    endfunction()

    wc3_shader_pipeline(release FALSE "shaders" WC3_RELEASE_STAGE_STAMP)
    set(WC3_ALL_STAGE_STAMPS "${WC3_RELEASE_STAGE_STAMP}")
    if(WDX_BUILD_WC3_DEBUG_SHADERS)
        wc3_shader_pipeline(debug TRUE "debug_shaders" WC3_DEBUG_STAGE_STAMP)
        list(APPEND WC3_ALL_STAGE_STAMPS "${WC3_DEBUG_STAGE_STAMP}")
    endif()

    add_custom_target(Wc3Shaders ALL DEPENDS ${WC3_ALL_STAGE_STAMPS})

    # `cmake --build build --target update-prebuilt-shaders` re-emits the
    # prebuilt/shaders pack from the freshly-built BLS bundles. Run
    # after touching .slang sources, then `git add prebuilt/` and commit
    # so CI / fresh clones can use WDX_USE_PREBUILT_SHADERS=ON without
    # invoking slangc themselves. debug_shaders/ is not mirrored — they
    # weigh ~865 MB and are local-only.
    set(_prebuilt_dir "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt")
    add_custom_target(update-prebuilt-shaders
        COMMAND "${CMAKE_COMMAND}" -E rm -rf "${_prebuilt_dir}/shaders"
        COMMAND "${CMAKE_COMMAND}" -E copy_directory
                "${CMAKE_BINARY_DIR}/standalone/shaders" "${_prebuilt_dir}/shaders"
        COMMENT "Updating ${_prebuilt_dir}/shaders from latest Wc3Shaders build"
        DEPENDS Wc3Shaders
        VERBATIM)
endif()

# ============================================================================
# Dear ImGui — optional debug UI integration.
#
# When WDX_ENABLE_IMGUI=ON, builds the ImGui core sources as a static lib and
# adds the engine-side BLS-backed renderer adapter (src/renderer/imgui/...) to
# WhiteoutFlakesLib. The renderer uses the engine's imgui.bls shader pair
# (from externals/Wc3Shaders/wc3_shaders/imgui_{vs,ps}.slang) — we do NOT use
# ImGui's own d3d11 / d3d12 / vulkan backends, only its platform backend
# (imgui_impl_glfw) for input.
#
# Hosts that don't call ImGui::CreateContext() pay only the link-time cost of
# the static lib; the engine's per-frame draw hook is a no-op when there is no
# ImGui context. The Max plugin falls in this bucket.
# ============================================================================

option(WDX_ENABLE_IMGUI "Build with Dear ImGui debug UI integration" ON)

if(WDX_ENABLE_IMGUI)
    if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/externals/imgui/imgui.cpp")
        message(FATAL_ERROR
            "WDX_ENABLE_IMGUI=ON but externals/imgui/ is empty. "
            "Initialize the submodule with: git submodule update --init externals/imgui")
    endif()

    add_library(imgui STATIC
        externals/imgui/imgui.cpp
        externals/imgui/imgui_draw.cpp
        externals/imgui/imgui_tables.cpp
        externals/imgui/imgui_widgets.cpp
        externals/imgui/imgui_demo.cpp
    )
    target_include_directories(imgui PUBLIC
        "${CMAKE_CURRENT_SOURCE_DIR}/externals/imgui"
        "${CMAKE_CURRENT_SOURCE_DIR}/externals/imgui/backends"
    )
    set_target_properties(imgui PROPERTIES
        CXX_STANDARD          17
        CXX_STANDARD_REQUIRED ON
    )
    if(MSVC)
        # ImGui targets warning-clean upstream but the engine compiles at /W3
        # with /wd4244 etc. Keep the same suppressions for visual parity.
        target_compile_options(imgui PRIVATE /W3 /EHsc /wd4244 /wd4267)
    endif()

    # ImGui's GLFW platform backend is a separate translation unit so the
    # engine library (which links imgui core) doesn't drag in GLFW. Only
    # the basic_viewer compiles it via add_library below.
endif()

# ---- Static library: GFX Service (backend-agnostic abstraction) ----
# The Vulkan backend compiles in whenever the Vulkan SDK is installed
# (find_package(Vulkan) succeeds). It targets Vulkan 1.3 + dynamic
# rendering and pulls VMA from the SDK's bundled vk_mem_alloc.h.
find_package(Vulkan QUIET)

# WebGPU/Dawn backend — opt-in (Dawn is a multi-minute first build).
# See WebGPU.md for the design. When ON, fetch a pinned Dawn revision via
# FetchContent and compile in src/gfx/webgpu/*.cpp.
option(WDX_ENABLE_WEBGPU "Enable WebGPU/Dawn backend (fetches Dawn via FetchContent)" OFF)

# Native Metal backend — macOS only. Default ON on Apple platforms so a
# stock checkout on macOS gets a native gfx path without manual flags.
# Forced OFF elsewhere because Metal.framework only ships with Xcode.
if(APPLE)
    option(WDX_ENABLE_METAL "Enable native Metal backend (macOS only)" ON)
else()
    set(WDX_ENABLE_METAL OFF CACHE BOOL "Enable native Metal backend (macOS only)" FORCE)
endif()

set(WHITEOUTFLAKES_GFX_SOURCES
    src/gfx/gfx_factory.cpp
)
# D3D11/D3D12 are Windows-only.
if(WIN32)
    list(APPEND WHITEOUTFLAKES_GFX_SOURCES
        src/gfx/d3d11/d3d11_device.cpp
        src/gfx/d3d11/d3d11_command_list.cpp
        src/gfx/d3d12/d3d12_device.cpp
        src/gfx/d3d12/d3d12_command_list.cpp
        src/gfx/d3d12/d3d12_resources.cpp
    )
endif()
if(Vulkan_FOUND)
    list(APPEND WHITEOUTFLAKES_GFX_SOURCES
        src/gfx/vulkan/vulkan_device.cpp
        src/gfx/vulkan/vulkan_init.cpp
        src/gfx/vulkan/vulkan_buffer.cpp
        src/gfx/vulkan/vulkan_texture.cpp
        src/gfx/vulkan/vulkan_pipeline.cpp
        src/gfx/vulkan/vulkan_command_list.cpp
        src/gfx/vulkan/vulkan_delete_queue.cpp
        src/gfx/vulkan/vulkan_swap_chain.cpp
        src/gfx/vulkan/vulkan_vma.cpp
    )
endif()
if(WDX_ENABLE_WEBGPU)
    list(APPEND WHITEOUTFLAKES_GFX_SOURCES
        src/gfx/webgpu/webgpu_device.cpp
        src/gfx/webgpu/webgpu_init.cpp
        src/gfx/webgpu/webgpu_buffer.cpp
        src/gfx/webgpu/webgpu_texture.cpp
        src/gfx/webgpu/webgpu_pipeline.cpp
        src/gfx/webgpu/webgpu_command_list.cpp
        src/gfx/webgpu/webgpu_delete_queue.cpp
        src/gfx/webgpu/webgpu_swap_chain.cpp
    )
    if(APPLE)
        # ObjC++ shim that hands Dawn a CAMetalLayer attached to GLFW's
        # NSWindow contentView (Dawn's SurfaceSourceMetalLayer can't be
        # populated from pure C++). Cocoa + QuartzCore are linked further
        # down where the WebGPU target wires up.
        list(APPEND WHITEOUTFLAKES_GFX_SOURCES
            src/gfx/webgpu/webgpu_surface_macos.mm
        )
    endif()
endif()

# Metal backend (Apple only). All Obj-C++ — pure C++ TUs see only the
# PIMPL'd MetalDevice. Framework linkage happens just below where the
# WhiteoutFlakesGfx target is finalized.
set(WHITEOUTFLAKES_GFX_METAL_MM_SOURCES)
if(WDX_ENABLE_METAL AND APPLE)
    set(WHITEOUTFLAKES_GFX_METAL_MM_SOURCES
        src/gfx/metal/metal_device.mm
        src/gfx/metal/metal_init.mm
        src/gfx/metal/metal_command_list.mm
        src/gfx/metal/metal_swap_chain.mm
        src/gfx/metal/metal_surface_macos.mm
        src/gfx/metal/metal_buffer.mm
        src/gfx/metal/metal_texture.mm
        src/gfx/metal/metal_pipeline.mm
        src/gfx/metal/metal_delete_queue.mm
    )
    list(APPEND WHITEOUTFLAKES_GFX_SOURCES
        ${WHITEOUTFLAKES_GFX_METAL_MM_SOURCES}
    )
endif()

add_library(WhiteoutFlakesGfx STATIC ${WHITEOUTFLAKES_GFX_SOURCES})

set_target_properties(WhiteoutFlakesGfx PROPERTIES
    CXX_STANDARD          20
    CXX_STANDARD_REQUIRED ON
)

target_include_directories(WhiteoutFlakesGfx PUBLIC
    "${CMAKE_CURRENT_SOURCE_DIR}/include"
    "${CMAKE_CURRENT_SOURCE_DIR}/src"
)

target_link_libraries(WhiteoutFlakesGfx PUBLIC whiteout_lib)
# D3D libs are Windows-only.
if(WIN32)
    target_link_libraries(WhiteoutFlakesGfx PRIVATE d3d11.lib d3d12.lib dxgi.lib)
endif()

# Tracy lives on WhiteoutFlakesGfx PUBLIC so consumers of the gfx
# library (the renderer, tools) pick up TRACY_ENABLE transitively and
# their ZoneScoped / TracyVkZone macros expand the same way as ours.
if(WDX_TRACY_LIB)
    target_link_libraries(WhiteoutFlakesGfx PUBLIC ${WDX_TRACY_LIB})
endif()

if(Vulkan_FOUND)
    message(STATUS "WhiteoutFlakesGfx: Vulkan = ${Vulkan_LIBRARIES} "
                   "(SDK=${Vulkan_INCLUDE_DIRS})")
    target_link_libraries(WhiteoutFlakesGfx PRIVATE Vulkan::Vulkan)
    # PUBLIC, like WDX_HAS_WEBGPU / WDX_HAS_METAL below: the C ABI's
    # BackendCompiledIn shim reads it in an expression, not an #if, so it
    # has to be defined for consumers of the library and not just inside it.
    target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_VULKAN=1)
    target_compile_definitions(WhiteoutFlakesGfx PRIVATE
        # vulkan.hpp config: no exceptions, default-dispatch (the dynamic
        # dispatcher would let us use the loader without linking
        # vulkan-1.lib, but we already link it). Result-based error
        # handling keeps with the codebase's no-throw style.
        VULKAN_HPP_NO_EXCEPTIONS
        VULKAN_HPP_NO_SMART_HANDLE
        # Removes the explicit constructors on vk::*CreateInfo / Desc
        # structs so they become aggregates — designated initializers
        # (`{ .field = value }`) become legal. sType is still default-
        # initialised correctly via the in-class initializer.
        VULKAN_HPP_NO_CONSTRUCTORS
    )
    # Platform-specific surface extensions: Win32 surface on Windows; on Linux
    # we drive the surface from GLFW (glfwCreateWindowSurface) which auto-
    # picks XCB/Xlib/Wayland — no platform define needed in the engine itself.
    if(WIN32)
        target_compile_definitions(WhiteoutFlakesGfx PRIVATE
            VK_USE_PLATFORM_WIN32_KHR=1
            NOMINMAX
            WIN32_LEAN_AND_MEAN
        )
    endif()
    # VMA ships under <Vulkan SDK>/Include/vma/vk_mem_alloc.h. The single
    # vulkan_vma.cpp TU defines VMA_IMPLEMENTATION before including it;
    # everywhere else we include without the implementation macro.
    target_include_directories(WhiteoutFlakesGfx PRIVATE
        "${Vulkan_INCLUDE_DIRS}/vma"
    )
else()
    message(STATUS "WhiteoutFlakesGfx: Vulkan SDK not found — Vulkan backend disabled")
    target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_VULKAN=0)
endif()

# ---- WebGPU / Dawn backend ----
#
# Dawn is fetched through eliemichel/WebGPU-distribution rather than
# upstream dawn.googlesource.com. Upstream Dawn runs
# `tools/fetch_dawn_dependencies.py` at configure time, which reads
# Dawn's DEPS file and tries to clone everything — including Chromium
# tooling on chrome-internal.googlesource.com (Google-only). That repo
# triggers a Git Credential Manager prompt and ultimately fails for
# non-Googlers. WebGPU-distribution sidesteps the whole mess by
# downloading prebuilt Dawn binaries (DLLs + headers).
#
# Headers exposed (the prebuilt zip includes all of Dawn's public
# headers + eliemichel's wrapper):
#   <webgpu/webgpu.h>     — Dawn-flavored C API (full surface incl. extensions)
#   <webgpu/webgpu_cpp.h> — Dawn's PascalCase C++ wrapper (the one we use)
#   <webgpu/webgpu.hpp>   — eliemichel's camelCase wrapper (unused)
# We pick webgpu_cpp.h to keep parity with upstream Dawn samples and the
# original FetchContent-from-source attempt — see webgpu_init.cpp for
# the async RequestAdapter / RequestDevice pattern we use instead of
# Dawn's private (and unshipped) dawn::native sync helpers.
if(WDX_ENABLE_WEBGPU)
    if(EMSCRIPTEN)
        # Emscripten ships emdawnwebgpu — Dawn-flavoured WebGPU bindings
        # for the browser. Same <webgpu/webgpu_cpp.h> surface our backend
        # already targets, so the gfx sources compile unchanged modulo the
        # surface-creation and device-acquisition #ifdefs in webgpu_init.cpp
        # and webgpu_swap_chain.cpp. No GLFW link here — JS owns the canvas.
        target_compile_options(WhiteoutFlakesGfx PUBLIC "--use-port=emdawnwebgpu")
        target_link_options(WhiteoutFlakesGfx PUBLIC "--use-port=emdawnwebgpu")
        target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_WEBGPU=1)
        message(STATUS "WhiteoutFlakesGfx: WebGPU enabled "
                       "(Emscripten emdawnwebgpu port)")
    else()
        include(FetchContent)
        # Pin to a specific commit — README warns against tracking branch tip.
        # Bump deliberately; see WebGPU.md §13.
        set(WDX_WEBGPU_DIST_TAG "main" CACHE STRING
            "WebGPU-distribution revision (commit or tag)")
        FetchContent_Declare(webgpu
            GIT_REPOSITORY https://github.com/eliemichel/WebGPU-distribution
            GIT_TAG        ${WDX_WEBGPU_DIST_TAG}
            GIT_SHALLOW    TRUE
        )
        # DAWN backend, prebuilt — no fetch script, no compile.
        set(WEBGPU_BACKEND          DAWN CACHE STRING "" FORCE)
        set(WEBGPU_BUILD_FROM_SOURCE OFF  CACHE BOOL   "" FORCE)
        # WebGPU-distribution selects its prebuilt Dawn slice from
        # CMAKE_SYSTEM_PROCESSOR (its detect_system_architecture()), which
        # ignores CMAKE_OSX_ARCHITECTURES. On a single-arch Apple cross-build
        # — e.g. arm64 on an Intel CI host — that fetches the host's x86_64
        # Dawn and the link fails against the arm64 objects ("found
        # architecture 'x86_64', required architecture 'arm64'"). Point the
        # processor at the requested arch for the fetch, then restore it.
        # Universal (x86_64;arm64) is skipped — no single prebuilt covers it.
        set(_wdx_saved_proc "${CMAKE_SYSTEM_PROCESSOR}")
        if(APPLE AND CMAKE_OSX_ARCHITECTURES AND NOT CMAKE_OSX_ARCHITECTURES MATCHES ";")
            set(CMAKE_SYSTEM_PROCESSOR "${CMAKE_OSX_ARCHITECTURES}")
        endif()
        FetchContent_MakeAvailable(webgpu)
        set(CMAKE_SYSTEM_PROCESSOR "${_wdx_saved_proc}")

        message(STATUS "WhiteoutFlakesGfx: WebGPU enabled "
                       "(eliemichel/WebGPU-distribution ${WDX_WEBGPU_DIST_TAG}, prebuilt Dawn)")
        target_link_libraries(WhiteoutFlakesGfx PRIVATE
            webgpu
            # GLFW: the WebGPU swap-chain pulls native handles (Display/Window
            # pair on X11, wl_display/wl_surface on Wayland, NSWindow on
            # macOS) via glfw3native.h. The target is added later via
            # add_subdirectory; CMake defers symbol resolution to generate
            # time so the forward reference resolves cleanly.
            glfw
        )
        target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_WEBGPU=1)
        if(WIN32)
            target_compile_definitions(WhiteoutFlakesGfx PRIVATE
                NOMINMAX
                WIN32_LEAN_AND_MEAN
            )
        elseif(APPLE)
            # SurfaceSourceMetalLayer needs the CAMetalLayer that the .mm
            # shim attaches to the NSWindow contentView — pull in Cocoa for
            # NSWindow/NSView and QuartzCore for CAMetalLayer.
            target_link_libraries(WhiteoutFlakesGfx PRIVATE
                "-framework Cocoa"
                "-framework QuartzCore"
            )
        endif()
    endif()
else()
    target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_WEBGPU=0)
endif()

# ---- Metal backend wiring ----
# Frameworks: Metal (id<MTLDevice> + all rendering APIs), QuartzCore
# (CAMetalLayer for the swap chain), Foundation/Cocoa (NSWindow handle
# from GLFW), MetalKit reserved for future MTKTextureLoader use.
# `-fobjc-arc` is scoped to the .mm files only via set_source_files_properties
# so the pure-C++ TUs (factory, etc.) don't see the flag.
if(WDX_ENABLE_METAL AND APPLE)
    target_link_libraries(WhiteoutFlakesGfx PRIVATE
        "-framework Metal"
        "-framework MetalKit"
        "-framework QuartzCore"
        "-framework Foundation"
        "-framework Cocoa"
    )
    target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_METAL=1)
    if(WHITEOUTFLAKES_GFX_METAL_MM_SOURCES)
        set_source_files_properties(${WHITEOUTFLAKES_GFX_METAL_MM_SOURCES}
            PROPERTIES COMPILE_FLAGS "-fobjc-arc"
        )
    endif()
    message(STATUS "WhiteoutFlakesGfx: Metal backend enabled")
else()
    target_compile_definitions(WhiteoutFlakesGfx PUBLIC WDX_HAS_METAL=0)
endif()

if(MSVC)
    target_compile_options(WhiteoutFlakesGfx PRIVATE
        /W3 /EHsc
        /wd4100 /wd4127 /wd4244 /wd4267
    )
endif()

# ---- Renderer-native coordinate system (compile-time knob) ----
set(WDX_DEFAULT_COORD_SPACE "Blizzard" CACHE STRING
    "Renderer-native coordinate system. Valid values: Blizzard, Max.")
set_property(CACHE WDX_DEFAULT_COORD_SPACE PROPERTY STRINGS "Blizzard" "Max")

# ---- Static library: standalone renderer + MDX adapter ----
add_library(WhiteoutFlakesLib STATIC
    src/renderer/animation/actor_eval.cpp
    src/renderer/animation/animation_driver.cpp
    src/renderer/animation/clip_playlist.cpp
    src/renderer/frame_ticker.cpp
    src/renderer/model/model_loader.cpp
    src/renderer/model/model_template.cpp
    src/renderer/model/model_template_manager.cpp
    src/renderer/model/render_model.cpp
    src/renderer/render_pipeline.cpp
    src/renderer/frame_capture.cpp
    src/renderer/render_service.cpp
    src/renderer/core/render_detail.cpp
    src/renderer/core/render_profile.cpp
    src/renderer/profiles/wc3/wc3_classify.cpp
    src/renderer/profiles/wc3/wc3_lighting_frame.cpp
    src/renderer/profiles/wc3/wc3_debug_programs.cpp
    src/renderer/core/mesh_overlay.cpp
    src/renderer/mesh_overlay/mesh_overlay_renderer.cpp
    src/renderer/shading/surface_pass.cpp
    src/renderer/shading/unlit_shading.cpp
    src/renderer/render_target.cpp
    src/renderer/scene_manager.cpp
    src/renderer/coordinate_system.cpp
    src/renderer/assets/sampler_asset_manager.cpp
    src/renderer/assets/texture_asset_manager.cpp
    src/renderer/assets/replaceable_texture_manager.cpp
    src/renderer/assets/asset_manager.cpp
    src/renderer/assets/env_cube_texture.cpp
    src/renderer/debug/debug_renderer.cpp
    src/renderer/debug/draw_trace.cpp
    src/renderer/debug/draw_trace_hooks.cpp
    src/renderer/effects/event_emitter_pool.cpp
    src/renderer/ribbon/ribbon_emitter.cpp
    src/renderer/ribbon/ribbon_desc.cpp
    src/renderer/ribbon/ribbon_tick_sc2.cpp
    src/renderer/ribbon/ribbon_build.cpp
    src/renderer/ribbon/ribbon_stages_sc2.cpp
    src/renderer/ribbon/ribbon_service.cpp
    src/renderer/sc2/sc2_element.cpp
    src/renderer/sc2/sc2_rng.cpp
    src/renderer/effects/spn_spawner.cpp
    src/renderer/corn_effects/corn_effects_emitter.cpp
    src/renderer/corn_effects/corn_effects_gfx_backend.cpp
    src/renderer/corn_effects/corn_effects_resource_providers.cpp
    src/renderer/corn_effects/corn_effects_service.cpp
    ${CORNFLAKES_SOURCES}
    # The particle module, by folder: the shared base and its WC3/WoW dialect,
    # the SC2 dialect, the D3 emitter, the output side, and the service seam.
    src/renderer/particle/base/child_model_emitter.cpp
    src/renderer/particle/base/model_particle_emitter.cpp
    src/renderer/particle/base/particle2_emitter.cpp
    src/renderer/particle/base/particle_adapters_wc3_m2.cpp
    src/renderer/particle/base/particle_curve.cpp
    src/renderer/particle/base/particle_pool.cpp
    src/renderer/particle/base/particle_shape.cpp
    src/renderer/particle/base/trail_set.cpp
    src/renderer/particle/sc2/particle2_emitter_sc2.cpp
    src/renderer/particle/sc2/particle_adapters_sc2.cpp
    src/renderer/particle/sc2/particle_stages_sc2_model.cpp
    src/renderer/particle/sc2/sc2_compose.cpp
    src/renderer/particle/sc2/sc2_kernels_build.cpp
    src/renderer/particle/sc2/sc2_kernels_emit.cpp
    src/renderer/particle/sc2/sc2_kernels_move.cpp
    src/renderer/particle/sc2/sc2_kernels_spawn.cpp
    src/renderer/particle/sc2/sc2_model_particle_emitter.cpp
    src/renderer/particle/sc2/sc2_tick.cpp
    src/renderer/particle/d3/d3_birth.cpp
    src/renderer/particle/d3/d3_emit_shape.cpp
    src/renderer/particle/d3/d3_emitter.cpp
    src/renderer/particle/d3/d3_emitter_desc.cpp
    src/renderer/particle/d3/d3_motion.cpp
    src/renderer/particle/d3/d3_path.cpp
    src/renderer/particle/d3/d3_quad_build.cpp
    src/renderer/particle/d3/d3_uv_state.cpp
    src/renderer/particle/output/multitex_particle_service.cpp
    src/renderer/particle/output/particle_geometry.cpp
    src/renderer/particle/output/particle_trace.cpp
    src/renderer/particle/emitter_factory.cpp
    src/renderer/particle/particle_service.cpp
    src/renderer/effects/splat_service.cpp
    src/renderer/dnc/dnc_asset.cpp
    src/renderer/dnc/dnc_cache.cpp
    src/renderer/dnc/dnc_catalog.cpp
    src/renderer/dnc/dnc_service.cpp
    src/renderer/shadow/shadow_service.cpp
    src/renderer/shadow/shadow_pass.cpp
    src/renderer/gtao/gtao_service.cpp
    src/renderer/dof/dof_service.cpp
    src/renderer/refraction/refraction_service.cpp
    src/renderer/distortion/distortion_service.cpp
    src/renderer/post_process/post_process_service.cpp
    src/renderer/bls/bls_container.cpp
    src/renderer/bls/bls_shader_cache.cpp
    src/renderer/bls/bls_permuter.cpp
    src/renderer/bls/bls_program.cpp
    src/renderer/bls/bls_pso_builder.cpp
    src/renderer/bls/bls_pso_trace.cpp
    src/renderer/bls/bls_mat_params.cpp
    src/renderer/bls/layer_material.cpp
    src/renderer/bls/bls_frame.cpp
    src/renderer/bls/bls_draw_helpers.cpp
    src/renderer/ibl/split_sum.cpp
    src/renderer/ibl/env_probe.cpp
    src/io/mdx_animation.cpp
    src/io/mdx_model_adapter.cpp
    src/io/team_glow_data.cpp
    src/io/file_resolver.cpp
    src/io/file_content_provider.cpp
    # Per-game storage: what each product opens and how it spells a path.
    # The CASC / MPQ sources compile to nothing when their backend is off.
    src/io/storage/storage_paths.cpp
    src/io/storage/install_locator.cpp
    src/io/storage/casc_registry.cpp
    src/io/storage/casc_source.cpp
    src/io/storage/mpq_source.cpp
    src/io/storage/game_storage.cpp
    src/io/storage/game_rules.cpp
    src/io/fetch_content_provider.cpp
    src/io/content_provider.cpp
    src/io/progress.cpp
    src/io/load_task.cpp
    src/io/path_utf8.cpp
    src/io/replaceable_paths.cpp
    src/io/event_data.cpp
    src/io/slk.cpp
    src/io/texture_image_usage.cpp
    # WEM save/load. Unconditional, unlike the three formats below: the module
    # is in whiteout_lib whatever this build enables, the profiles a `.wem` can
    # be opened as are exactly what WDX_ENABLE_M2 / _M3 / _D3 leave reachable,
    # and wem_profiles.cpp is what states that. See WEM_INTEGRATION_DESIGN.md.
    src/io/wem/wem_profiles.cpp
    src/io/wem/wem_import.cpp
    src/io/wem/wem_export.cpp
    src/public_api/renderer_api.cpp
)

# `.m2`, opt-in. The sources are added rather than compiled-out with an #if so
# that turning the option on is the only thing that ever builds them — a
# half-implemented format should not cost compile time in a release viewer.
if(WDX_ENABLE_M2)
    target_sources(WhiteoutFlakesLib PRIVATE
        src/io/m2/m2_animation.cpp
        src/io/m2/m2_model_adapter.cpp
        src/io/wow/character_appearance.cpp
        src/io/wow/character_geosets.cpp
        src/io/wow/chr_customization_table.cpp
        src/io/wow/creature_skin_table.cpp
        src/io/wow/item_appearance_table.cpp
        src/io/wow/particle_color_table.cpp
        src/renderer/profiles/wow/m2_lighting.cpp
        src/renderer/profiles/wow/m2_material.cpp
        src/renderer/profiles/wow/m2_shader_select.cpp
        src/renderer/profiles/wow/m2_shading.cpp
        src/renderer/profiles/wow/m2_surface_table.cpp
        src/renderer/profiles/wow/wow_character_appearance.cpp
        src/renderer/profiles/wow/wow_replaceable_textures.cpp
    )
    # Only the `.m2` path reads client databases, so the dependency is scoped
    # to the option that turns that path on.
    if(TARGET whiteout_database)
        target_link_libraries(WhiteoutFlakesLib PUBLIC whiteout_database)
    else()
        message(FATAL_ERROR "WDX_ENABLE_M2=ON needs WHITEOUT_ENABLE_DATABASE=ON.")
    endif()

    target_compile_definitions(WhiteoutFlakesLib PUBLIC WDX_ENABLE_M2=1)
    message(STATUS "WhiteoutFlakes: .m2 loading ENABLED (materials + combiners + animation)")
endif()

# `.m3`, opt-in on the same terms.
if(WDX_ENABLE_M3)
    target_sources(WhiteoutFlakesLib PRIVATE
        src/io/m3/m3_model_adapter.cpp
        src/io/m3/m3_animation.cpp
        src/io/m3/m3_billboard.cpp
        src/io/m3/m3_pose_solvers.cpp
        src/renderer/profiles/sc2_heroes/m3_standard_shading.cpp
        src/renderer/profiles/sc2_heroes/m3_surface_table.cpp
        src/renderer/profiles/sc2_heroes/sc2_model_catalog.cpp
        src/renderer/sc2/m3_deferred_light_service.cpp
    )
    target_compile_definitions(WhiteoutFlakesLib PUBLIC WDX_ENABLE_M3=1)
    message(STATUS "WhiteoutFlakes: .m3 loading ENABLED (geometry only)")
endif()

# Diablo III actors, opt-in on the same terms.
if(WDX_ENABLE_D3)
    target_sources(WhiteoutFlakesLib PRIVATE
        src/io/d3/d3_asset_provider.cpp
        src/io/d3/d3_model_adapter.cpp
        src/io/d3/d3_effect_resolver.cpp
        src/io/d3/d3_item_registry.cpp
        src/io/d3/d3_particle_adapter.cpp
        src/io/d3/d3_sno_cache.cpp
        src/renderer/effects/d3_attachment_pool.cpp
        src/renderer/profiles/diablo3/d3_character_appearance.cpp
        # Collision primitives as DATA — no solver, so it is not behind
        # WDX_ENABLE_PHYSICS. It is also the cheapest test of the shape decode.
        src/renderer/profiles/diablo3/d3_collision.cpp
        src/renderer/profiles/diablo3/d3_particle_shading.cpp
        src/renderer/profiles/diablo3/d3_standard_shading.cpp
        src/renderer/profiles/diablo3/d3_surface_table.cpp
    )
    target_compile_definitions(WhiteoutFlakesLib PUBLIC WDX_ENABLE_D3=1)
    message(STATUS "WhiteoutFlakes: Diablo III actor loading ENABLED")
endif()

# ---- Snowball rigid-body physics -----------------------------------------
#
# Everything the option adds is behind WDX_HAS_PHYSICS, and the rigid-body path
# simply does not exist when it is off rather than compiling to a stub.
#
# One engine, three hosts, one profile source file each — WoW's `.phys`,
# StarCraft II's PHRB/PHYJ and Diablo III's per-bone collision shapes share
# Snowball and essentially nothing above it (see each file's header): three
# gravity constants, three step policies, and in D3's case no kinematic body at
# all. Whichever formats are enabled bring their own glue; with none of them
# there is nothing to drive and Snowball is not built at all.
if(WDX_ENABLE_PHYSICS AND (WDX_ENABLE_M2 OR WDX_ENABLE_M3 OR WDX_ENABLE_D3))
    add_subdirectory(src/renderer/physics/snowball EXCLUDE_FROM_ALL)
    if(WDX_ENABLE_M2)
        target_sources(WhiteoutFlakesLib PRIVATE
            src/renderer/profiles/wow/wow_physics.cpp
        )
    endif()
    if(WDX_ENABLE_M3)
        target_sources(WhiteoutFlakesLib PRIVATE
            src/renderer/profiles/sc2_heroes/sc2_physics.cpp
            src/renderer/profiles/sc2_heroes/sc2_cloth.cpp
        )
    endif()
    if(WDX_ENABLE_D3)
        target_sources(WhiteoutFlakesLib PRIVATE
            src/renderer/profiles/diablo3/d3_physics.cpp
            # Cloth is NOT Snowball -- D3's is a game-side solver and the 2.6.2
            # image has no `dmCloth` anything. It sits under this option only
            # because "simulation" is the subsystem a user turns off, not
            # because it links against the engine.
            src/renderer/profiles/diablo3/d3_cloth.cpp
        )
    endif()
    target_link_libraries(WhiteoutFlakesLib PRIVATE snowball)
    target_compile_definitions(WhiteoutFlakesLib PRIVATE WDX_HAS_PHYSICS=1)
endif()

# Storage browser walks CASC/MPQ/the local filesystem — none of which the
# web build has (WHITEOUT_ENABLE_CASC is forced OFF above).
if(NOT EMSCRIPTEN)
    target_sources(WhiteoutFlakesLib PRIVATE
        src/io/storage_browser.cpp
        src/public_api/storage_browser_api.cpp
    )
endif()

if(WDX_ENABLE_IMGUI)
    target_sources(WhiteoutFlakesLib PRIVATE
        src/renderer/imgui/imgui_renderer.cpp
    )
endif()

add_dependencies(WhiteoutFlakesLib WhiteoutFlakesShaders WhiteoutFlakesEmbedded)

set_target_properties(WhiteoutFlakesLib PROPERTIES
    CXX_STANDARD          20
    CXX_STANDARD_REQUIRED ON
)

target_include_directories(WhiteoutFlakesLib PUBLIC
    "${CMAKE_CURRENT_SOURCE_DIR}/include"
    "${CMAKE_CURRENT_SOURCE_DIR}/src"
    "${CMAKE_CURRENT_SOURCE_DIR}/src/renderer"
    "${CMAKE_CURRENT_SOURCE_DIR}/src/io"
    "${SHADER_OUT_DIR}"
    "${EMBED_OUT_DIR}"
)
# cornflakes module include layout:
#   src/renderer/corn_effects          → so <cornflakes/interface/...> resolves
#                                    (public headers used by corn-fx host code).
#   cornflakes/internal           → so <cornflakes/...> resolves to the
#                                    private impl-side headers (e.g.
#                                    cornflakes/asset/field_defs.hpp lives at
#                                    cornflakes/internal/cornflakes/asset/...).
target_include_directories(WhiteoutFlakesLib PRIVATE
    "${CMAKE_CURRENT_SOURCE_DIR}/src/renderer/corn_effects"
    "${CORNFLAKES_MODULE_DIR}/internal"
)

# cornflakes' core/determinism.hpp asserts CORNFLAKES_DETERMINISM_FLAGS_APPLIED
# is defined as 1 in every TU that includes it. Upstream's INTERFACE target
# also pins MSVC FP semantics to /fp:precise /fp:except- to keep corn-fx
# evaluation bit-deterministic. Since cornflakes is now part of WhiteoutFlakesLib,
# we apply the same flags to the whole library.
target_compile_definitions(WhiteoutFlakesLib PRIVATE
    CORNFLAKES_DETERMINISM_FLAGS_APPLIED=1
)
if(MSVC)
    target_compile_options(WhiteoutFlakesLib PRIVATE /fp:precise /fp:except-)
endif()

target_link_libraries(WhiteoutFlakesLib PUBLIC
    whiteout_lib
    WhiteoutFlakesGfx
)

if(WIN32)
    target_link_libraries(WhiteoutFlakesLib PUBLIC user32.lib gdi32.lib comdlg32.lib)
endif()

target_compile_definitions(WhiteoutFlakesLib PUBLIC
    WDX_DEFAULT_COORD_SPACE=${WDX_DEFAULT_COORD_SPACE}
)

if(WDX_ENABLE_IMGUI)
    target_link_libraries(WhiteoutFlakesLib PUBLIC imgui)
    target_compile_definitions(WhiteoutFlakesLib PUBLIC WDX_ENABLE_IMGUI=1)
else()
    target_compile_definitions(WhiteoutFlakesLib PUBLIC WDX_ENABLE_IMGUI=0)
endif()

if(TARGET whiteout_casc)
    target_link_libraries(WhiteoutFlakesLib PUBLIC whiteout_casc)
endif()

if(TARGET whiteout_mpq)
    target_link_libraries(WhiteoutFlakesLib PUBLIC whiteout_mpq)
endif()

if(MSVC)
    target_compile_options(WhiteoutFlakesLib PRIVATE
        /W3 /EHsc
        /wd4100 /wd4127 /wd4244 /wd4267
    )
endif()

# ---- Throwaway: dump a BLS permute's disassembly ----
# Windows-only: links d3d11.lib + d3dcompiler.lib + includes <d3d11.h>,
# none of which exist outside the Win32 SDK. Skipped under Emscripten and
# on non-Windows hosts so the macOS/Linux gfx build succeeds.
if(WIN32 AND NOT EMSCRIPTEN AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/renderer/bls/bls_reflect_tool.cpp")
  add_executable(BlsReflect
      src/renderer/bls/bls_reflect_tool.cpp
      src/renderer/bls/bls_container.cpp
  )
  set_target_properties(BlsReflect PROPERTIES
      CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON
      RUNTIME_OUTPUT_DIRECTORY         "${CMAKE_BINARY_DIR}/standalone"
      RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/standalone"
  )
  target_include_directories(BlsReflect PRIVATE
      "${CMAKE_CURRENT_SOURCE_DIR}/include"
      "${CMAKE_CURRENT_SOURCE_DIR}/src"
      "${CMAKE_CURRENT_SOURCE_DIR}/src/renderer")
  target_link_libraries(BlsReflect PRIVATE whiteout_lib d3d11.lib d3dcompiler.lib)
  if(MSVC)
    target_compile_options(BlsReflect PRIVATE /W3 /EHsc /wd4100 /wd4127 /wd4244 /wd4267)
  endif()
endif()

# ---- Throwaway: extract Diablo III's shader tree out of CASC ----
# Needs nothing but whiteout_casc, so it builds on any host that configured
# with CASC support. tools/d3_shader_atlas/atlas.py does the analysis on the
# folder it writes.
if(TARGET whiteout_casc AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tools/d3_shader_atlas/d3_shader_atlas.cpp")
  add_executable(D3ShaderAtlas tools/d3_shader_atlas/d3_shader_atlas.cpp)
  set_target_properties(D3ShaderAtlas PROPERTIES
      CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON
      RUNTIME_OUTPUT_DIRECTORY         "${CMAKE_BINARY_DIR}/standalone"
      RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/standalone"
  )
  target_link_libraries(D3ShaderAtlas PRIVATE whiteout_casc)
  if(MSVC)
    target_compile_options(D3ShaderAtlas PRIVATE /W3 /EHsc /wd4100 /wd4127 /wd4244 /wd4267)
  endif()
endif()

# ---- Standalone executable: basic MDX viewer ----
#
# The viewer drives the engine through GLFW (window + input) and Dear ImGui
# (every toolbar / menu / settings widget that used to be a Win32 control).
# Both must be enabled — WDX_ENABLE_IMGUI=OFF would leave the viewer with no
# UI surface at all. The entire block is gated on `NOT EMSCRIPTEN` (no
# native windowing/audio/UI in the web build); the closing `endif()` sits
# just before the Linux AppImage section.
if(NOT EMSCRIPTEN)

if(NOT WDX_ENABLE_IMGUI)
    message(FATAL_ERROR
        "WhiteoutFlakesStandalone requires WDX_ENABLE_IMGUI=ON; the viewer's UI "
        "is entirely Dear ImGui. Disable the viewer (don't add it to the build) "
        "if you want WDX_ENABLE_IMGUI=OFF.")
endif()

# GLFW — windowing + input. Bundled docs / tests / examples are off so the
# library compiles in a few seconds and doesn't drop binaries into the
# build tree.
set(GLFW_BUILD_DOCS     OFF CACHE BOOL "" FORCE)
set(GLFW_BUILD_TESTS    OFF CACHE BOOL "" FORCE)
set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(GLFW_INSTALL        OFF CACHE BOOL "" FORCE)
add_subdirectory(externals/glfw EXCLUDE_FROM_ALL)

# NFD — native file open / save dialogs. Linux builds want GTK/portal; on
# Windows it's IFileOpenDialog and has no extra deps.
add_subdirectory(externals/nativefiledialog-extended EXCLUDE_FROM_ALL)

# cubeb — cross-platform audio output (WASAPI / PulseAudio / AudioUnit).
# Drives CubebSoundEmitter, shared by the viewer and the Max plugin. The
# bundled tests / tools / sanitizer wiring are forced off so it builds as
# a lean static lib; the Rust backends stay off (the C++ WASAPI backend
# covers Windows). The `cubeb` target's bundled speex resampler is linked
# PRIVATE inside cubeb itself — CubebSoundEmitter does its own (linear)
# resampling so it doesn't reach into cubeb internals.
set(BUILD_TESTS     OFF CACHE BOOL "" FORCE)
set(BUILD_TOOLS     OFF CACHE BOOL "" FORCE)
set(BUILD_RUST_LIBS OFF CACHE BOOL "" FORCE)
set(USE_SANITIZERS  OFF CACHE BOOL "" FORCE)
add_subdirectory(externals/cubeb EXCLUDE_FROM_ALL)

# ---- Embeddable storage/model explorer library ----
# The model explorer factored into a reusable library: a CASC browser, a
# multi-scene thumbnail pool, and the StorageExplorer panel that hosts drive.
# It owns NO window / gfx device / ImGui context — a host (basic_viewer, the
# standalone explorer shell, …) supplies all three and a shared RenderService.
# See STORAGE_EXPLORER_DESIGN.md.
add_library(WhiteoutFlakesExplorerLib STATIC
    tools/model_explorer/thumbnail_pool.cpp
    # The pool's counterpart for images: a texture cell is one decode and one
    # upload, with none of the scene/target/per-frame-render machinery a model
    # cell needs. See texture_thumbnail_cache.h.
    tools/model_explorer/texture_thumbnail_cache.cpp
    tools/model_explorer/storage_explorer.cpp
    # Camera framing for a loaded model / standalone effect — used by the
    # thumbnail pool AND the basic_viewer, so it lives in this shared lib (each
    # consumer links the lib instead of compiling its own copy).
    tools/common/thumbnail_framing.cpp
    # The load-progress modal. Here rather than in each executable because both
    # hosts that draw it link this lib already, and the Storage Explorer panel
    # itself needs it for its own async open.
    tools/common/progress_dialog.cpp
)
set_target_properties(WhiteoutFlakesExplorerLib PROPERTIES
    CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON)
# Public: the lib's own headers (storage_explorer.h / casc_browser.h /
# thumbnail_pool.h) for any external consumer.
target_include_directories(WhiteoutFlakesExplorerLib PUBLIC
    "${CMAKE_CURRENT_SOURCE_DIR}/tools/model_explorer"
    "${CMAKE_CURRENT_SOURCE_DIR}/tools/common"
)
target_link_libraries(WhiteoutFlakesExplorerLib PUBLIC WhiteoutFlakesLib imgui nfd)
if(MSVC)
    target_compile_options(WhiteoutFlakesExplorerLib PRIVATE
        /W3 /EHsc /wd4100 /wd4127 /wd4244 /wd4267)
endif()
if(WDX_BUILD_WC3_SHADERS OR WDX_USE_PREBUILT_SHADERS)
    add_dependencies(WhiteoutFlakesExplorerLib Wc3Shaders)
endif()

# ---- Model conversion library ----
# The "Export to ..." converters and the texture work they share: device-free,
# so tests link it, and the viewer reaches it only through
# export/model_export_service. Built to move into src/ later: its one include
# directory of its own is export/, so a converter that reaches for another
# tools/ header fails to compile instead of slipping in.
add_library(WhiteoutFlakesConvert STATIC
    # What every converter shares: the subject and report core, the WEM hop,
    # texture reads and writes, and the texture containers.
    tools/basic_viewer/export/export_common.cpp
    tools/basic_viewer/export/texture_io.cpp
    tools/basic_viewer/export/texture_codec.cpp
    # "Export to MDX": a foreign model converted THROUGH WEM into Warcraft III.
    tools/basic_viewer/export/mdx_export.cpp
    # "Export to M3": the same crossing pointed at StarCraft II.
    tools/basic_viewer/export/m3_export.cpp
    # Which textures those write: what the written model reads, less War3 (Mod)'s.
    tools/basic_viewer/export/export_texture_set.cpp
    # "Export to glTF": the crossing pointed out of the Blizzard family.
    tools/basic_viewer/export/gltf_export.cpp
    # The Warcraft III -> StarCraft II game conventions that ride that export.
    tools/basic_viewer/export/wc3_to_sc2_export.cpp
    tools/basic_viewer/export/wc3_attachment_names.cpp
    # The one crossing a slot rename cannot make: StarCraft II's
    # specular/gloss baked into a Reforged occlusion/roughness/metalness map.
    tools/basic_viewer/export/sc2_pbr_export.cpp
)
# "Save As" for a model that IS `.m3`: written back through m3::Writer with no
# WEM hop. Needs the `.m3` adapter, so it ships only where that adapter does.
if(WDX_ENABLE_M3)
    target_sources(WhiteoutFlakesConvert PRIVATE tools/basic_viewer/export/m3_save.cpp)
endif()
set_target_properties(WhiteoutFlakesConvert PROPERTIES
    CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON)
# Consumers spell the folder: `#include "export/m3_export.h"`.
target_include_directories(WhiteoutFlakesConvert
    PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/tools/basic_viewer/export"
    INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/tools/basic_viewer")
target_link_libraries(WhiteoutFlakesConvert PUBLIC WhiteoutFlakesLib)
if(MSVC)
    target_compile_options(WhiteoutFlakesConvert PRIVATE
        /W3 /EHsc /wd4100 /wd4127 /wd4244 /wd4267)
endif()

set(WHITEOUTFLAKES_VIEWER_SOURCES
    # The entry point: parse, settle the platform, dispatch on the run mode.
    tools/basic_viewer/main.cpp
    tools/basic_viewer/platform/platform_paths.cpp
    # The command line as a table of options, and the work each mode runs on the app.
    tools/basic_viewer/cli/cli_options.cpp
    tools/basic_viewer/cli/cli_commands.cpp
    # The gate harnesses render-diff.ps1, particle-diff.ps1 and friends drive:
    # device + offscreen target, no window, no ViewerApp.
    tools/basic_viewer/harness/harness_common.cpp
    tools/basic_viewer/harness/smoke_test.cpp
    tools/basic_viewer/harness/multiscene_test.cpp
    tools/basic_viewer/harness/childmodel_check.cpp
    tools/basic_viewer/harness/particle_diff.cpp
    tools/basic_viewer/harness/draw_trace.cpp
    tools/basic_viewer/harness/draw_trace_scenario.cpp
    # The app: the composition root and frame loop, the window and camera input,
    # and the embedded Storage Explorer.
    tools/basic_viewer/app/viewer_app.cpp
    tools/basic_viewer/app/platform_window.cpp
    tools/basic_viewer/app/orbit_camera_input.cpp
    tools/basic_viewer/app/storage_explorer_host.cpp
    # Open documents (tabs), how they load, and playback of the active one.
    tools/basic_viewer/documents/document_manager.cpp
    tools/basic_viewer/documents/document_loader.cpp
    tools/basic_viewer/documents/playback_controller.cpp
    # The game storages and the settings profile.
    tools/basic_viewer/session/storage_session.cpp
    # Per-game features on a loaded model. Each implementation is listed under
    # its format's flag below; game_features.cpp makes the absent ones null.
    tools/basic_viewer/features/game_features.cpp
    # The conversion front door: what the active document can be written as,
    # the writes, and Save As for a model that stays in its own format.
    tools/basic_viewer/export/model_export_service.cpp
    tools/basic_viewer/export/mdx_save.cpp
    # The UI: the frame and its panels, and the widgets they share.
    tools/basic_viewer/ui/viewer_ui.cpp
    tools/basic_viewer/ui/menu_bar.cpp
    tools/basic_viewer/ui/ribbon.cpp
    tools/basic_viewer/ui/d3_equip_popup.cpp
    tools/basic_viewer/ui/tab_bar.cpp
    tools/basic_viewer/ui/animation_window.cpp
    tools/basic_viewer/ui/settings_window.cpp
    tools/basic_viewer/ui/settings_general_pages.cpp
    tools/basic_viewer/ui/settings_io_page.cpp
    tools/basic_viewer/ui/export_dialogs.cpp
    tools/basic_viewer/ui/open_dialog.cpp
    tools/basic_viewer/ui/widgets.cpp
    tools/basic_viewer/ui/setting_rows.cpp
    # The scalar settings as descriptors: ini key, read rule, page row, reset.
    tools/basic_viewer/settings/setting_descriptors.cpp
    # The animation exporter: the device-free recipe/schedule and its ini, the
    # output sinks, the capture loop, and the dialog.
    tools/basic_viewer/capture/export_recipe.cpp
    tools/basic_viewer/capture/export_ini.cpp
    tools/basic_viewer/capture/capture_sinks.cpp
    tools/basic_viewer/capture/export_runner.cpp
    tools/basic_viewer/capture/export_window.cpp
    tools/basic_viewer/capture/capture_controller.cpp
    tools/basic_viewer/settings_ini.cpp
    tools/basic_viewer/settings_io.cpp
    tools/basic_viewer/storage_explorer_ini.cpp
    tools/basic_viewer/localization.cpp
    # `--ui-shot`: the UI captured to a PNG with no visible window.
    tools/basic_viewer/harness/ui_shot.cpp
    # Every extension the viewer opens and what it is: the dialogs, the loader
    # and the game follow read this one table.
    tools/basic_viewer/documents/model_formats.cpp
    tools/basic_viewer/ui/file_dialogs.cpp
    # Shared host utilities live in tools/common (used by the Max plugin too).
    tools/common/cubeb_sound_emitter.cpp
    tools/common/imgui_theme.cpp
    # The ribbon widget: generic ImGui, no viewer types, so a second host can
    # take it without taking the viewer with it.
    tools/common/imgui_ribbon.cpp
    tools/common/imgui_app_icon.cpp
    tools/common/log_console.cpp
    # thumbnail_framing now ships in WhiteoutFlakesExplorerLib (linked below),
    # which the viewer also uses for its own camera framing + the embedded
    # Storage Explorer panel.
    # ImGui's GLFW platform backend lives with the viewer rather than the
    # imgui core lib because it pulls in <GLFW/glfw3.h> — the engine library
    # itself only links the renderer-agnostic ImGui core.
    externals/imgui/backends/imgui_impl_glfw.cpp
    # InputText over std::string, for the path rows and the item filters.
    externals/imgui/misc/cpp/imgui_stdlib.cpp
)
if(WDX_ENABLE_M3)
    list(APPEND WHITEOUTFLAKES_VIEWER_SOURCES tools/basic_viewer/features/sc2_animation_files.cpp)
endif()
if(WDX_ENABLE_M2)
    list(APPEND WHITEOUTFLAKES_VIEWER_SOURCES tools/basic_viewer/features/wow_appearance.cpp)
endif()
if(WDX_ENABLE_D3)
    list(APPEND WHITEOUTFLAKES_VIEWER_SOURCES
        tools/basic_viewer/features/d3_wardrobe.cpp
        tools/basic_viewer/features/d3_outfit_presets.cpp)
endif()
# Win32 .rc — embeds resources/flakes_icon.ico as IDI_WHITEOUT_ICON so the
# viewer can hand it to the GLFW HWND via WM_SETICON. On Linux we instead
# load the same icon via glfwSetWindowIcon at runtime (see PlatformWindow::Open).
if(WIN32)
    list(APPEND WHITEOUTFLAKES_VIEWER_SOURCES tools/basic_viewer/resource.rc)
endif()
# macOS: ObjC++ shim that creates the CAMetalLayer + Vulkan surface in
# the order MoltenVK expects (wantsLayer=YES before setLayer:). Replaces
# glfwCreateWindowSurface, which trips VK_ERROR_INITIALIZATION_FAILED on
# macOS 13+ / MoltenVK 1.4. cocoa_window_macos.mm tints the NSWindow's
# title bar to match the ImGui MenuBarBg — Cocoa parity for the Windows
# DwmSetWindowAttribute path in app/platform_window.cpp.
if(APPLE)
    list(APPEND WHITEOUTFLAKES_VIEWER_SOURCES
        tools/basic_viewer/vulkan_surface_macos.mm
        tools/basic_viewer/cocoa_window_macos.mm
    )
endif()
add_executable(WhiteoutFlakesStandalone ${WHITEOUTFLAKES_VIEWER_SOURCES})

set_target_properties(WhiteoutFlakesStandalone PROPERTIES
    CXX_STANDARD          20
    CXX_STANDARD_REQUIRED ON
    OUTPUT_NAME           "WhiteoutFlakes"
    RUNTIME_OUTPUT_DIRECTORY         "${CMAKE_BINARY_DIR}/standalone"
    RUNTIME_OUTPUT_DIRECTORY_DEBUG   "${CMAKE_BINARY_DIR}/standalone"
    RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/standalone"
)

# Ship as a GUI-subsystem app in non-Debug configs so no console window pops up
# for end users — the in-app Log Console (Debug menu) surfaces stdout/stderr on
# demand. Debug keeps the default console subsystem so developers still get a
# terminal automatically. /ENTRY:mainCRTStartup preserves the standard int
# main() under /SUBSYSTEM:WINDOWS (which would otherwise want WinMain).
if(MSVC)
    target_link_options(WhiteoutFlakesStandalone PRIVATE
        $<$<NOT:$<CONFIG:Debug>>:/SUBSYSTEM:WINDOWS>
        $<$<NOT:$<CONFIG:Debug>>:/ENTRY:mainCRTStartup>
    )
endif()

target_include_directories(WhiteoutFlakesStandalone PRIVATE
    "${CMAKE_CURRENT_SOURCE_DIR}/tools/basic_viewer"
    "${CMAKE_CURRENT_SOURCE_DIR}/tools/common"
    "${CMAKE_CURRENT_SOURCE_DIR}/externals/dr_libs"
    "${CMAKE_CURRENT_SOURCE_DIR}/externals/imgui/misc/cpp"
)

target_link_libraries(WhiteoutFlakesStandalone PRIVATE
    WhiteoutFlakesExplorerLib # embedded Storage Explorer + shared thumbnail_framing
    WhiteoutFlakesConvert     # the model converters behind export/model_export_service
    WhiteoutFlakesLib
    glfw
    nfd
    imgui
    cubeb
)

# ---- Animated WebP export (viewer only) ----
# libwebp is fetched and built at configure time, and linked into the viewer
# alone — no other WhiteoutFlakes target (engine, gfx, lib) depends on it. Only
# libwebp's encoder + mux libraries are built; its command-line tools are
# disabled, so it needs no libpng/libjpeg/libtiff. The viewer's WebP code is
# gated on WDX_HAVE_WEBP and falls back to a clear error when this is OFF.
option(WDX_ENABLE_WEBP
    "Enable animated WebP export in the viewer (fetches libwebp)" ON)
if(WDX_ENABLE_WEBP)
    include(FetchContent)
    set(WEBP_BUILD_ANIM_UTILS OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_CWEBP      OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_DWEBP      OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_GIF2WEBP   OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_IMG2WEBP   OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_VWEBP      OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_WEBPINFO   OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_WEBPMUX    OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_EXTRAS     OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_FUZZTEST   OFF CACHE BOOL "" FORCE)
    set(WEBP_BUILD_LIBWEBPMUX ON  CACHE BOOL "" FORCE) # WebPAnimEncoder lives here
    FetchContent_Declare(libwebp
        GIT_REPOSITORY https://github.com/webmproject/libwebp.git
        GIT_TAG        v1.5.0
        GIT_SHALLOW    TRUE
    )
    # Build libwebp as STATIC libraries regardless of the project-wide
    # BUILD_SHARED_LIBS, so the viewer embeds the encoder/mux directly and
    # ships no libwebp.dll. BUILD_SHARED_LIBS is shadowed as a normal variable
    # for libwebp's add_subdirectory scope, then restored.
    set(_wdx_prev_bsl_set FALSE)
    if(DEFINED BUILD_SHARED_LIBS)
        set(_wdx_prev_bsl_set TRUE)
        set(_wdx_prev_bsl "${BUILD_SHARED_LIBS}")
    endif()
    set(BUILD_SHARED_LIBS OFF)

    # libwebp registers install() rules for every one of its targets with no
    # opt-out. FetchContent leaves the ones we don't link (webpdecoder,
    # webpdemux) out of the build, so `cmake --install` would then fail trying
    # to stage artefacts that were never built. We link libwebp statically
    # into the viewer alone and never want it in WhiteoutFlakes' install tree,
    # so neutralise install() for the duration of libwebp's add_subdirectory.
    # Single override → _install is reliably the builtin; a flag re-enables it
    # afterwards so WhiteoutFlakes' own install rules still run.
    set(_wdx_suppress_install TRUE)
    function(install)
        if(NOT _wdx_suppress_install)
            _install(${ARGV})
        endif()
    endfunction()

    FetchContent_MakeAvailable(libwebp)

    set(_wdx_suppress_install FALSE)
    if(_wdx_prev_bsl_set)
        set(BUILD_SHARED_LIBS "${_wdx_prev_bsl}")
    else()
        unset(BUILD_SHARED_LIBS)
    endif()
    target_link_libraries(WhiteoutFlakesStandalone PRIVATE webp libwebpmux)
    target_include_directories(WhiteoutFlakesStandalone SYSTEM PRIVATE
        "${libwebp_SOURCE_DIR}/src")
    target_compile_definitions(WhiteoutFlakesStandalone PRIVATE WDX_HAVE_WEBP=1)
    message(STATUS
        "WhiteoutFlakesStandalone: animated WebP export enabled (libwebp v1.5.0)")
endif()

# ---- metal_smoke ----
# Tiny diagnostic tool that opens a GLFW window, asks gfx for a Metal
# device + swap chain, and runs a magenta clear loop. Bypasses the
# renderer entirely so it can run before the BLS / pipeline / asset
# wiring is finished. Used to verify the Metal backend's swap-chain +
# render-pass + Present path during bring-up.
if(WDX_ENABLE_METAL AND APPLE)
    # Compile the bundled triangle shader to a .metallib next to the
    # smoke binary at build time. xcrun metal needs `-mmacosx-version-min`
    # — we pin it to the same 11.0 the Wc3Shaders pipeline uses (metallib
    # 1.2.5, see externals/Wc3Shaders/compile_all_slang.py).
    set(_metal_smoke_metal "${CMAKE_CURRENT_SOURCE_DIR}/tools/metal_smoke/triangle.metal")
    set(_metal_smoke_air   "${CMAKE_BINARY_DIR}/standalone/triangle.air")
    set(_metal_smoke_lib   "${CMAKE_BINARY_DIR}/standalone/triangle.metallib")
    add_custom_command(
        OUTPUT  "${_metal_smoke_lib}"
        DEPENDS "${_metal_smoke_metal}"
        COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_BINARY_DIR}/standalone"
        COMMAND xcrun metal -c "-mmacosx-version-min=11.0"
                            "${_metal_smoke_metal}"
                            -o "${_metal_smoke_air}"
        COMMAND xcrun metallib "${_metal_smoke_air}" -o "${_metal_smoke_lib}"
        COMMAND ${CMAKE_COMMAND} -E remove "${_metal_smoke_air}"
        VERBATIM
        COMMENT "metal_smoke: compiling triangle.metal -> triangle.metallib"
    )
    add_custom_target(metal_smoke_shader DEPENDS "${_metal_smoke_lib}")

    add_executable(metal_smoke tools/metal_smoke/metal_smoke.cpp)
    add_dependencies(metal_smoke metal_smoke_shader)
    set_target_properties(metal_smoke PROPERTIES
        CXX_STANDARD          20
        CXX_STANDARD_REQUIRED ON
        RUNTIME_OUTPUT_DIRECTORY         "${CMAKE_BINARY_DIR}/standalone"
        RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/standalone"
    )
    target_link_libraries(metal_smoke PRIVATE WhiteoutFlakesGfx glfw)
endif()

# Viewer includes <vulkan/vulkan.h> unconditionally (for the Linux surface
# path via glfwCreateWindowSurface). On Windows the include compiles but
# the Vulkan-using code is gated behind `#if !defined(_WIN32)`; we still
# need the headers + import lib on PATH so the TU compiles.
if(Vulkan_FOUND)
    target_link_libraries(WhiteoutFlakesStandalone PRIVATE Vulkan::Vulkan)
elseif(UNIX AND NOT APPLE)
    message(FATAL_ERROR
        "WhiteoutFlakesStandalone requires the Vulkan SDK on Linux (it's the "
        "only swap-chain backend on this platform). Install vulkan-sdk or "
        "libvulkan-dev + headers and re-run CMake.")
endif()

# WebGPU-distribution ships prebuilt Dawn as a DLL — copy it next to the
# exe so the loader finds it at runtime. The helper is a no-op when the
# backend is built statically; see WebGPU.md §10.
if(WDX_ENABLE_WEBGPU)
    target_copy_webgpu_binaries(WhiteoutFlakesStandalone)
endif()

if(MSVC)
    target_compile_options(WhiteoutFlakesStandalone PRIVATE
        /W3 /EHsc
        /wd4100 /wd4127 /wd4244 /wd4267
    )
endif()

if(WDX_BUILD_WC3_SHADERS OR WDX_USE_PREBUILT_SHADERS)
    add_dependencies(WhiteoutFlakesStandalone Wc3Shaders)
endif()

# imgui_theme.cpp is compiled directly into the viewer and pulls in the
# embedded Roboto header generated by WhiteoutFlakesEmbedded.
add_dependencies(WhiteoutFlakesStandalone WhiteoutFlakesEmbedded)

# Localization catalogs (lang/*.ini) and the bundled Noto CJK fonts (fonts/*.ttf)
# are runtime assets. Stage them into standalone/ (the RUNTIME_OUTPUT_DIRECTORY),
# mirroring how the prebuilt shaders are staged — NOT into $<TARGET_FILE_DIR>,
# which on macOS is the bundle's Contents/MacOS/ where codesign rejects non-code
# files. On Windows/Linux standalone/ IS the exe dir, so the viewer finds them
# next to itself; on macOS they sit beside the .app and the install() rules below
# copy them into Contents/Resources/ (where AssetDir() resolves them at runtime).
# Uses copy_directory (not copy_directory_if_different) — the latter needs CMake
# 3.26, but our floor is 3.20 and CI runners ship as old as 3.22, matching the
# copy_directory the shader-staging rules above already use.
#
# Stage beside the exe, which is what AssetDir() reads. `standalone/` is NOT
# always that directory: this target pins RUNTIME_OUTPUT_DIRECTORY_DEBUG and
# _RELEASE to `standalone/`, so Visual Studio puts those two configs there —
# but every other config (RelWithDebInfo) still lands in a per-config
# subdirectory below it. A fixed CMAKE_CFG_INTDIR gets that backwards for
# BOTH: it staged Release into `standalone/Release/lang` while the exe sat in
# `standalone/` reading a catalog nothing had written since the last time the
# paths happened to agree, so every string added after that point rendered as
# its raw key. TARGET_FILE_DIR is the exe's directory in every config.
#
# Apple keeps the `standalone/` form: TARGET_FILE_DIR inside a bundle is
# Contents/MacOS/, where codesign rejects non-code files, so the catalogs sit
# beside the .app and the install() rules below place them in
# Contents/Resources/ (where AssetDir() resolves them at runtime).
if(APPLE)
    set(WDX_ASSET_STAGE_DIR "${CMAKE_BINARY_DIR}/standalone/${CMAKE_CFG_INTDIR}")
else()
    set(WDX_ASSET_STAGE_DIR "$<TARGET_FILE_DIR:WhiteoutFlakesStandalone>")
endif()
add_custom_command(TARGET WhiteoutFlakesStandalone POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        "${CMAKE_CURRENT_SOURCE_DIR}/resources/lang"
        "${WDX_ASSET_STAGE_DIR}/lang"
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        "${CMAKE_CURRENT_SOURCE_DIR}/resources/fonts"
        "${WDX_ASSET_STAGE_DIR}/fonts"
    VERBATIM)

# ---- ModelExplorer ----
# A CASC browser that renders a grid of live model/effect thumbnails, each in
# its own scene+viewport (exercises the multi-scene renderer). Mirrors the
# standalone viewer's window/device/ImGui boilerplate and shares tools/common.
# The browser / pool / panel / framing now live in WhiteoutFlakesExplorerLib;
# this target keeps only the standalone shell (window + device + ImGui context)
# and the entry point + headless self-tests.
set(WHITEOUTFLAKES_EXPLORER_SOURCES
    tools/model_explorer/explorer_main.cpp
    tools/model_explorer/explorer_app.cpp
    tools/common/cubeb_sound_emitter.cpp
    tools/common/imgui_theme.cpp
    externals/imgui/backends/imgui_impl_glfw.cpp
)
if(APPLE)
    list(APPEND WHITEOUTFLAKES_EXPLORER_SOURCES
        tools/basic_viewer/vulkan_surface_macos.mm
        tools/basic_viewer/cocoa_window_macos.mm
    )
endif()
add_executable(WhiteoutFlakesExplorer ${WHITEOUTFLAKES_EXPLORER_SOURCES})
set_target_properties(WhiteoutFlakesExplorer PROPERTIES
    CXX_STANDARD          20
    CXX_STANDARD_REQUIRED ON
    OUTPUT_NAME           "ModelExplorer"
    RUNTIME_OUTPUT_DIRECTORY         "${CMAKE_BINARY_DIR}/standalone"
    RUNTIME_OUTPUT_DIRECTORY_DEBUG   "${CMAKE_BINARY_DIR}/standalone"
    RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/standalone"
)
target_include_directories(WhiteoutFlakesExplorer PRIVATE
    "${CMAKE_CURRENT_SOURCE_DIR}/tools/model_explorer"
    "${CMAKE_CURRENT_SOURCE_DIR}/tools/common"
    "${CMAKE_CURRENT_SOURCE_DIR}/externals/dr_libs"
)
target_link_libraries(WhiteoutFlakesExplorer PRIVATE
    WhiteoutFlakesExplorerLib
    WhiteoutFlakesLib
    glfw
    nfd
    imgui
    cubeb
)
if(Vulkan_FOUND)
    target_link_libraries(WhiteoutFlakesExplorer PRIVATE Vulkan::Vulkan)
elseif(UNIX AND NOT APPLE)
    message(FATAL_ERROR "WhiteoutFlakesExplorer requires the Vulkan SDK on Linux.")
endif()
if(WDX_ENABLE_WEBGPU)
    target_copy_webgpu_binaries(WhiteoutFlakesExplorer)
endif()
if(MSVC)
    target_compile_options(WhiteoutFlakesExplorer PRIVATE
        /W3 /EHsc /wd4100 /wd4127 /wd4244 /wd4267)
endif()
if(WDX_BUILD_WC3_SHADERS OR WDX_USE_PREBUILT_SHADERS)
    add_dependencies(WhiteoutFlakesExplorer Wc3Shaders)
endif()
add_dependencies(WhiteoutFlakesExplorer WhiteoutFlakesEmbedded)

# ---- Optional: 3ds Max plugin (.dlx) ----
option(WDX_BUILD_MAX_PLUGIN
    "Build the WhiteoutFlakes 3ds Max plugin (requires Max SDK + -DMAX_VERSION)"
    OFF)

if(WDX_BUILD_MAX_PLUGIN)
    if(NOT WIN32)
        message(FATAL_ERROR "WDX_BUILD_MAX_PLUGIN=ON requires Windows (3ds Max SDK is Windows-only).")
    endif()
    add_subdirectory(tools/max_plugin)
endif()

# ---- Optional: C ABI shared library (language bindings) ------------------
# Flat-C surface over the public renderer headers, generated by
# `python -m tools.bindings.codegen flakes`. Consumed today by the Rust
# crate in bindings/rust/; see BINDINGS.md.
option(WDX_BUILD_C_BINDINGS
    "Build whiteoutflakes_native, the C ABI shared library for language bindings"
    OFF)
option(WDX_BUILD_C_STATIC
    "Also build whiteoutflakes_native_static (requires WDX_BUILD_C_BINDINGS)"
    OFF)
if(WDX_BUILD_C_BINDINGS)
    add_subdirectory(bindings/c)
endif()

# ---- CASC dev server -----------------------------------------------------
# Opt-in Crow HTTP server that fronts WhiteoutLib's CASC reader, used to
# feed real WC3 assets to the WASM viewer over a local origin (imitates
# Hiveworkshop's CASC-backed asset delivery). The Crow dep is fetched
# inside the subdirectory so it's scoped to this target only.
option(WDX_BUILD_CASC_SERVER
    "Build the wf_casc_server tool (Crow HTTP server + WhiteoutLib CASC)"
    OFF)
if(WDX_BUILD_CASC_SERVER)
    if(NOT WHITEOUT_ENABLE_CASC)
        message(FATAL_ERROR
            "WDX_BUILD_CASC_SERVER=ON requires WHITEOUT_ENABLE_CASC=ON.")
    endif()
    # Lives under tools/web_viewer/ since it exists to feed the web viewer
    # — CASC-backed loose-file delivery imitating Hiveworkshop's service.
    add_subdirectory(tools/web_viewer/casc_server)
endif()

endif()  # NOT EMSCRIPTEN — standalone viewer block

# ============================================================================
# Unit tests — Catch2 v3 (opt-in)
#
# `cmake -S . -B build -DWDX_BUILD_TESTS=ON` then `ctest --test-dir build`
# (or `cmake --build build --target check`). Off by default because it fetches
# Catch2 at configure time, which an offline / air-gapped configure can't do.
# Covers the headless parts of the engine only — see tests/CMakeLists.txt.
# ============================================================================
option(WDX_BUILD_TESTS "Build the Catch2 unit tests (fetches Catch2)" OFF)
if(WDX_BUILD_TESTS AND NOT EMSCRIPTEN)
    enable_testing()
    add_subdirectory(tests)
endif()

# ---- Web viewer: WASM module + JS facade (Emscripten only) ----
# The package defines wf_web (wf-core.{js,wasm} + JS staging); the demo
# layers index.html + sw.js on top, so the order matters.
if(EMSCRIPTEN)
    add_subdirectory(packages/whiteout-js-viewer)
    add_subdirectory(tools/web_viewer)
endif()

# ============================================================================
# Linux AppImage staging
#
# `cmake --install build --prefix AppDir/usr` populates the AppDir layout
# linuxdeploy expects. The AppImage runs the binary from AppDir/usr/bin and
# the engine's exe-dir search root picks up the staged BLS files next to it
# (no special XDG lookup needed). The .desktop file + icon get installed to
# AppDir/usr/share/{applications,icons/hicolor/256x256/apps}.
# ============================================================================
if(UNIX AND NOT APPLE AND NOT EMSCRIPTEN)
    include(GNUInstallDirs)

    install(TARGETS WhiteoutFlakesStandalone
            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

    # BLS shader bundles staged by the Wc3Shaders custom target sit at
    # ${CMAKE_BINARY_DIR}/standalone/shaders (and optionally debug_shaders).
    # Install them next to the binary so FileContentProvider's exe-dir
    # search root resolves them with no path config. Both WDX_BUILD_WC3_SHADERS
    # and WDX_USE_PREBUILT_SHADERS produce the same staging layout, so this
    # install fires for either source.
    if(WDX_BUILD_WC3_SHADERS OR WDX_USE_PREBUILT_SHADERS)
        install(DIRECTORY "${CMAKE_BINARY_DIR}/standalone/shaders/"
                DESTINATION ${CMAKE_INSTALL_BINDIR}/shaders
                OPTIONAL)
        if(WDX_BUILD_WC3_DEBUG_SHADERS)
            install(DIRECTORY "${CMAKE_BINARY_DIR}/standalone/debug_shaders/"
                    DESTINATION ${CMAKE_INSTALL_BINDIR}/debug_shaders
                    OPTIONAL)
        endif()
    endif()

    # AppImage / XDG installs need the icon basename to match the .desktop's
    # `Icon=WhiteoutFlakes` directive, so we rename the source file
    # (flakes_icon_linux.png is the right size for this slot) at install time.
    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/resources/flakes_icon_linux.png"
            DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/256x256/apps
            RENAME WhiteoutFlakes.png)

    # Pre-baked PSO replay trace: seeds the Vulkan pipeline cache on first
    # launch so the user doesn't pay the cold-build hitch. Lives next to the
    # binary inside the AppImage; platform_paths.cpp copies it into $XDG_CACHE_HOME/
    # WhiteoutFlakes/ if no per-user trace exists yet (subsequent runs save
    # their own additions there).
    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/pso_trace.bin")
        install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/pso_trace.bin"
                DESTINATION ${CMAKE_INSTALL_BINDIR})
    endif()

    # Localization catalogs + bundled Noto fonts, next to the binary where
    # AssetDir() (== the exe dir on Linux) resolves them inside the AppImage.
    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/resources/lang/"
            DESTINATION ${CMAKE_INSTALL_BINDIR}/lang)
    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/resources/fonts/"
            DESTINATION ${CMAKE_INSTALL_BINDIR}/fonts)

    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/packaging/linux/WhiteoutFlakes.desktop"
            DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
endif()

# ============================================================================
# macOS .app bundle staging
#
# `cmake --install build --prefix <stagedir>` produces
# <stagedir>/WhiteoutFlakes.app/ with the standard layout:
#   Contents/MacOS/WhiteoutFlakes        ← executable
#   Contents/Resources/WhiteoutFlakes.icns
#   Contents/Resources/shaders/...        ← prebuilt BLS bundle
#   Contents/Resources/pso_trace.bin
#   Contents/Frameworks/                  ← MoltenVK + libvulkan + ICD
#   Contents/Info.plist
# Dylib + ICD bundling lives in the GitHub Actions YAML (dylibbundler /
# install_name_tool / hand-copy from the LunarG SDK) since it depends on
# the runner's SDK install path. The CMake side just builds the skeleton.
# ============================================================================
if(APPLE)
    # Mark the executable as a macOS bundle. CMake then arranges the build
    # output as `WhiteoutFlakes.app/Contents/MacOS/WhiteoutFlakes` directly
    # (no manual mkdir / mv needed).
    set_target_properties(WhiteoutFlakesStandalone PROPERTIES
        MACOSX_BUNDLE                          TRUE
        MACOSX_BUNDLE_BUNDLE_NAME              "WhiteoutFlakes"
        MACOSX_BUNDLE_GUI_IDENTIFIER           "com.whiteoutflakes.viewer"
        MACOSX_BUNDLE_BUNDLE_VERSION           "0.1.0"
        MACOSX_BUNDLE_SHORT_VERSION_STRING     "0.1.0"
        MACOSX_BUNDLE_ICON_FILE                "WhiteoutFlakes.icns"
        MACOSX_BUNDLE_INFO_PLIST
            "${CMAKE_CURRENT_SOURCE_DIR}/packaging/macos/Info.plist.in"
        # Bundled dylibs live next to the executable in
        # Contents/Frameworks; @executable_path is the bundle's MacOS dir
        # at runtime, so ../Frameworks resolves correctly. The plain
        # @executable_path entry covers libwebgpu_dawn.dylib, which Dawn's
        # WebGPU-distribution helper drops as a sibling of the exe via
        # target_copy_webgpu_binaries rather than moving it to Frameworks/.
        INSTALL_RPATH                          "@executable_path;@executable_path/../Frameworks"
        BUILD_WITH_INSTALL_RPATH               TRUE
    )

    # Generate WhiteoutFlakes.icns from the iconset committed under
    # resources/FlakesMacOS.iconset/. Apple's iconutil only exists on
    # macOS hosts; we use it as a build-time codegen step.
    set(_iconset_src "${CMAKE_CURRENT_SOURCE_DIR}/resources/FlakesMacOS.iconset")
    set(_icns_out    "${CMAKE_CURRENT_BINARY_DIR}/WhiteoutFlakes.icns")
    add_custom_command(
        OUTPUT  "${_icns_out}"
        COMMAND iconutil -c icns -o "${_icns_out}" "${_iconset_src}"
        DEPENDS "${_iconset_src}"
        COMMENT "macOS: iconutil ${_iconset_src} -> WhiteoutFlakes.icns"
        VERBATIM)
    add_custom_target(WhiteoutFlakesIcns ALL DEPENDS "${_icns_out}")
    add_dependencies(WhiteoutFlakesStandalone WhiteoutFlakesIcns)

    # ---- Install rules -------------------------------------------------
    # Bundle goes at the install root (`WhiteoutFlakes.app/`). Everything
    # except the executable itself lives under Contents/Resources/ —
    # macOS treats anything in Contents/MacOS/ as code and `codesign
    # --force` fails on non-Mach-O files (`.bls` etc.) shipped there.
    # The engine's DiscoverExecutableDirectory() has a .app-aware path:
    # when the exe sits at Contents/MacOS/X, the search root resolves
    # to Contents/Resources/ instead.
    install(TARGETS WhiteoutFlakesStandalone
            BUNDLE  DESTINATION .)

    install(FILES "${_icns_out}"
            DESTINATION WhiteoutFlakes.app/Contents/Resources)

    if(WDX_BUILD_WC3_SHADERS OR WDX_USE_PREBUILT_SHADERS)
        install(DIRECTORY "${CMAKE_BINARY_DIR}/standalone/shaders/"
                DESTINATION WhiteoutFlakes.app/Contents/Resources/shaders
                OPTIONAL)
    endif()

    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/pso_trace.bin")
        install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/pso_trace.bin"
                DESTINATION WhiteoutFlakes.app/Contents/Resources)
    endif()

    # Localization catalogs + bundled Noto fonts — into Contents/Resources/
    # (NOT Contents/MacOS/, where codesign rejects non-code files). AssetDir()
    # resolves these from Contents/Resources/ on macOS.
    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/resources/lang/"
            DESTINATION WhiteoutFlakes.app/Contents/Resources/lang)
    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/resources/fonts/"
            DESTINATION WhiteoutFlakes.app/Contents/Resources/fonts)

    # Self-contained bundle: stage the Vulkan loader + MoltenVK driver and
    # rewrite the ICD JSON's library_path to bundle-relative. platform_paths.cpp
    # sets VK_ICD_FILENAMES to <bundle>/Contents/Resources/vulkan/icd.d/
    # MoltenVK_icd.json at startup, so the loader finds MoltenVK without
    # any system Vulkan SDK on the user's machine — the .app is launchable
    # via Finder/double-click with no env-var prep.
    #
    # Python is needed by packaging/macos/rewrite_icd.py — find it lazily
    # here since WDX_BUILD_WC3_SHADERS already pulled it in earlier if on,
    # but we want this path to work in the common WDX_USE_PREBUILT_SHADERS
    # case too.
    if(NOT Python3_EXECUTABLE)
        find_package(Python3 QUIET COMPONENTS Interpreter)
    endif()
    #
    # Source paths: Vulkan_LIBRARY points at libvulkan.dylib (a symlink to
    # libvulkan.1.dylib on every modern SDK). libMoltenVK + its ICD JSON
    # live next to the loader, but the exact layout differs between LunarG
    # SDK (Frameworks/lib + share/) and Homebrew (split across opt/
    # vulkan-loader and opt/molten-vk). Glob both layouts so a local dev
    # build with brew, and the CI runner with the LunarG SDK installer,
    # both produce the same staged bundle.
    if(Vulkan_FOUND)
        # libvulkan: resolve symlinks so we install the real dylib, not
        # the version-suffixed symlink Homebrew ships at lib/libvulkan.dylib.
        get_filename_component(_wdx_vk_loader_real "${Vulkan_LIBRARY}" REALPATH)
        # libMoltenVK + ICD JSON: walk candidate layouts.
        set(_wdx_mvk_lib "")
        set(_wdx_mvk_icd "")
        foreach(_root
                "/opt/homebrew/opt/molten-vk"                       # brew arm64
                "/usr/local/opt/molten-vk"                          # brew x86_64
                "$ENV{VULKAN_SDK}"                                  # LunarG SDK
                "${Vulkan_INCLUDE_DIR}/.."                          # SDK-style
                "/opt/homebrew/opt/vulkan-loader/.."                # brew sibling
            )
            if(_root AND EXISTS "${_root}")
                if(NOT _wdx_mvk_lib AND EXISTS "${_root}/lib/libMoltenVK.dylib")
                    set(_wdx_mvk_lib "${_root}/lib/libMoltenVK.dylib")
                endif()
                if(NOT _wdx_mvk_icd AND EXISTS "${_root}/share/vulkan/icd.d/MoltenVK_icd.json")
                    set(_wdx_mvk_icd "${_root}/share/vulkan/icd.d/MoltenVK_icd.json")
                endif()
                if(NOT _wdx_mvk_icd AND EXISTS "${_root}/etc/vulkan/icd.d/MoltenVK_icd.json")
                    set(_wdx_mvk_icd "${_root}/etc/vulkan/icd.d/MoltenVK_icd.json")
                endif()
            endif()
        endforeach()
        if(_wdx_mvk_lib AND _wdx_mvk_icd)
            # Order matters: every file the .app should ship must land
            # *before* the bundle-wrapper codesign at the end of this block.
            # If we sign the wrapper and then drop a file inside (e.g. the
            # ICD JSON), the sealed CodeResources manifest no longer matches
            # the on-disk contents and `codesign --verify` reports
            # "a sealed resource is missing or invalid".
            install(CODE "
                # ---- Stage Vulkan loader + MoltenVK ----
                # Force the loader filename to libvulkan.1.dylib so the
                # @rpath/libvulkan.1.dylib load command resolves regardless
                # of whether the source path was a versioned symlink or the
                # canonical Cellar realpath.
                file(INSTALL \"${_wdx_vk_loader_real}\"
                     DESTINATION \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Frameworks\"
                     RENAME \"libvulkan.1.dylib\")
                file(INSTALL \"${_wdx_mvk_lib}\"
                     DESTINATION \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Frameworks\")
                execute_process(COMMAND install_name_tool -id @rpath/libvulkan.1.dylib
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Frameworks/libvulkan.1.dylib\")
                execute_process(COMMAND install_name_tool -id @rpath/libMoltenVK.dylib
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Frameworks/libMoltenVK.dylib\")

                # ---- Rewrite the exe's libvulkan load command ----
                # The linker bakes the dylib's LC_ID_DYLIB install_name into
                # the load command, which may be neither Vulkan_LIBRARY nor
                # its realpath — brew's libvulkan ships with install_name =
                # /opt/homebrew/opt/vulkan-loader/lib/libvulkan.1.dylib, the
                # LunarG SDK ships @rpath/... already. Read the actual load
                # command with otool and rewrite whatever's there to @rpath.
                execute_process(
                    COMMAND otool -L
                        \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/MacOS/WhiteoutFlakes\"
                    OUTPUT_VARIABLE _wdx_otool_out OUTPUT_STRIP_TRAILING_WHITESPACE)
                string(REGEX MATCH \"[^ \\t\\r\\n]+libvulkan\\\\.1\\\\.dylib\"
                    _wdx_exe_libvk \"\${_wdx_otool_out}\")
                message(STATUS \"macOS bundle: exe libvulkan load path = '\${_wdx_exe_libvk}'\")
                if(_wdx_exe_libvk AND NOT _wdx_exe_libvk MATCHES \"^@rpath\")
                    execute_process(COMMAND install_name_tool -change
                        \"\${_wdx_exe_libvk}\" @rpath/libvulkan.1.dylib
                        \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/MacOS/WhiteoutFlakes\")
                endif()

                # ---- Rewrite the MoltenVK ICD JSON's library_path ----
                # MUST happen before the wrapper codesign so the JSON is
                # part of the sealed bundle manifest.
                file(MAKE_DIRECTORY
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Resources/vulkan/icd.d\")
                execute_process(COMMAND \"${Python3_EXECUTABLE}\"
                    \"${CMAKE_CURRENT_SOURCE_DIR}/packaging/macos/rewrite_icd.py\"
                    \"${_wdx_mvk_icd}\"
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Resources/vulkan/icd.d/MoltenVK_icd.json\"
                    RESULT_VARIABLE _icd_rc)
                if(NOT _icd_rc EQUAL 0)
                    message(FATAL_ERROR \"rewrite_icd.py failed (rc=\${_icd_rc})\")
                endif()

                # ---- Ad-hoc codesign ----
                # Nested binaries first (signature freezes), then the exe,
                # then the bundle wrapper. macOS 14+ rejects code-signed
                # dylibs whose load commands have been edited post-sign, so
                # the install_name_tool steps above must precede this.
                execute_process(COMMAND codesign --force --sign -
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Frameworks/libvulkan.1.dylib\")
                execute_process(COMMAND codesign --force --sign -
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/Frameworks/libMoltenVK.dylib\")
                execute_process(COMMAND codesign --force --sign -
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app/Contents/MacOS/WhiteoutFlakes\")
                execute_process(COMMAND codesign --force --sign -
                    \"\${CMAKE_INSTALL_PREFIX}/WhiteoutFlakes.app\")
            ")
            message(STATUS "macOS bundle: bundling MoltenVK from ${_wdx_mvk_lib}")
        else()
            message(STATUS
                "macOS bundle: MoltenVK not found in standard layouts; "
                "user will need a system Vulkan install at runtime "
                "(checked: brew molten-vk, VULKAN_SDK, brew vulkan-loader sibling)")
        endif()
    endif()
endif()