ShadowDusk.MgcbPlugin 0.21.0

ShadowDusk.MgcbPlugin

A MonoGame Content Builder (MGCB) content-processor plugin that compiles your .fx shaders with ShadowDusk, inside MGCB's own process — no mgfxc, no fxc.exe, no Wine, no Windows SDK. It works on Linux, macOS, and Windows build agents alike.

This is a delivery shape of the ShadowDusk compiler library, not a second compiler. The processor builds a CompilerOptions from MGCB's build context and calls the same EffectCompiler the ShadowDusk CLI and the runtime API call, so the .mgfx bytes inside the .xnb are byte-for-byte what the CLI emits for the same source and target. The one deliberate difference is on DirectX 12 and Vulkan, whose MGFX v11 container stores a source-file string per shader: a content build hands the processor your effect's absolute path, so the processor writes <unknown> there, exactly as MonoGame's stock EffectProcessor does, instead of recording your build machine's directory in the game's content. The compiled effect is the same bytes wherever the project is checked out; build errors and warnings still name the real file, line and column.

MGCB compiles .fx in-process and never launches an external effect compiler, so putting a drop-in mgfxc on PATH does not route an .mgcb build through ShadowDusk. This plugin is the route.

Install

dotnet add package ShadowDusk.MgcbPlugin

It is a build-time (DevelopmentDependency) package: nothing from it ends up in your shipped game assembly.

Use

Add a /reference: line to your .mgcb, then select the ShadowDusk importer and processor on each effect:

/reference:$(NuGetPackageRoot)shadowdusk.mgcbplugin/<version>/tools/net8.0/any/ShadowDusk.MgcbPlugin.dll

#begin MyEffect.fx
/importer:ShadowDuskEffectImporter
/processor:ShadowDuskEffectProcessor
/build:MyEffect.fx

MGCB's /reference: needs a real path, so spell out the package-cache path (or copy the tools/net8.0/any directory somewhere stable in your repo and point at that). Everything the plugin needs — the ShadowDusk assemblies and the pinned DXC, SPIRV-Cross, and vkd3d-shader natives — ships in that one directory.

Nothing else is required. The target is derived from the content project's own /platform: line, and the output is the backwards-compatible MGFX v10 container that every MonoGame 3.8.1.263+ and KNI runtime loads.

The mapping keys on the platform's name, never its number: MonoGame renumbered TargetPlatform in 3.8.5, and the plugin is compiled against the 3.8.2.1105 contract so that it loads into every MGCB from 3.8.2 up.

Building a MonoGame 3.8.5 Content Builder project instead of a .mgcb? Use the library-shaped package, ShadowDusk.ContentPipeline — the same importer and processor as a normal PackageReference you new up in your ContentBuilder. This tools-only package has no lib/ and cannot be referenced from C#.

Processor parameters

Every one is optional; the defaults are the correct path.

Diagnostics

Shader errors surface through MGCB in the file(line,col-col): error CODE: message form fxc/mgfxc use and MSBuild and IDEs parse, with the underlying compiler's own words verbatim beneath. The build fails; nothing is silently swallowed.

Learn more

• ShadowDusk documentation
• MGCB content pipeline guide