| name | shaders |
| description | Custom shaders in FlatRedBall2. Use when adding .fx shader files, troubleshooting shader compilation errors (libmojoshader, Wine), or working with precompiled shader XNBs. |
Shaders in FlatRedBall2
Precompiled Shaders
FlatRedBall2 ships precompiled .xnb shaders for its built-in Apos.Shapes dependency. These live in src/PrecompiledShaders/ with one subfolder per platform:
| Platform | Subfolder | Set by |
|---|
| MonoGame DesktopGL | DesktopGL/ | MonoGamePlatform property |
| KNI BlazorGL | BlazorGL/ | KniPlatform property |
Projects import AposShapesPrecompiled.props to use these instead of compiling from source. Unknown platforms fall back to normal Apos.Shapes shader compilation.
These xnbs are duplicated in a second place: the dotnet templates' build folders — templates/frb2-desktop/build/ and templates/frb2-multiplatform/build/ (each has a DesktopGL/; multiplatform also BlazorGL/), plus a copy of AposShapesPrecompiled.props. Any edit to a src/PrecompiledShaders/<platform>/apos-shapes.xnb must be copied byte-for-byte into the matching template folder(s). TemplatePackageReferenceTests fails CI on drift — run it after touching an xnb. This is invariant for any xnb change; the AposShapes.props rebuild checklist frames the sync under a version bump, but it isn't bump-specific.
The package version is centralized in $(AposShapesVersion) (src/PrecompiledShaders/AposShapes.props), imported by the engine. Apos.Shapes ships only buildTransitive assets, so both the version and the SkipAposShapeContent precompiled-XNB skip flow identically whether the package is referenced directly or transitively — sample Desktop projects inherit it from the engine and don't pin it. Re-adding a per-sample pin only reintroduces the drift NU1605 then fails the build on; bump the prop instead.
Version Guard
ShapesBatch.AposShapesVersion (in src/Rendering/Batches/ShapesBatch.cs) is a C# const that can't read MSBuild, so it mirrors $(AposShapesVersion) by hand. In Debug builds, a mismatch against the loaded Apos.Shapes assembly throws InvalidOperationException. See the comment on that constant (and AposShapes.props) for the rebuild checklist.
Custom Shaders
Adding your own .fx files to a project requires the MonoGame/KNI content pipeline to compile them at build time.
Windows
Install the Visual C++ 2013 Redistributable (x64) — the content pipeline's libmojoshader_64.dll depends on it:
winget install Microsoft.VCRedist.2013.x64
Or download from https://www.microsoft.com/download/details.aspx?id=40784.
Without it, builds fail with:
Unable to load DLL 'libmojoshader_64.dll' or one of its dependencies.
macOS and Linux
The MonoGame content pipeline uses Windows-only tools for shader compilation. Wine must be installed.
Follow the MonoGame setup guide:
https://docs.monogame.net/articles/tutorials/building_2d_games/02_getting_started/index.html?tabs=macos#setup-wine-for-effect-compilation-macos-and-linux-only
KNI Backend
Shader compilation is not supported on macOS or Linux with the KNI backend. KNI projects must have their shaders compiled on Windows.
