monogame-effects

MonoGame Custom Effects Implementation Guide

This skill covers the MGFX effect system, stock effects, and cross-platform shader compilation. For HLSL syntax, the Material pattern, and SpriteBatch integration, see the monogame-shaders skill. For compiled API signatures, see references/effects.md.

MGFX — MonoGame's Effect System

MonoGame uses its own FX runtime called MGFX, designed to support multiple shader backends from a single .fx source file. Core capabilities:

• Same technique/pass/shader structure as Microsoft FX files.
• Textual .fx source compiled to optimized .mgfxo binary at build time.
• Cross-platform: targets DirectX HLSL and OpenGL GLSL from one source via MojoShader.

Pipeline:

MyEffect.fx  →  MGFXC (or MGCB)  →  MyEffect.mgfxo  →  Content.Load<Effect>()

Stock Effects

MonoGame ships six built-in effects, all fully supported on current platforms:

These are built with the same MGFX pipeline. To optimize a stock effect for your target platform, copy it from MonoGame.Framework/Platform/Graphics/Effect/Resources, edit out unused features, and recompile with MGFXC.

Shader Model Targets

DirectX targets

OpenGL/GLSL targets (via MojoShader)

| Shader model | |---| | vs_2_0 / ps_2_0 | | vs_3_0 / ps_3_0 |

OpenGL targets are limited to SM 3.0 — do not use SM 4+ features in code paths that must run on GL platforms.

Cross-Platform Preprocessor Symbols

MonoGame defines these symbols when compiling .fx files:

Canonical cross-platform shader model selection

Always use #if OPENGL guards to pick the right shader model — never hardcode vs_4_0 in portable shaders:

#if OPENGL
    #define VS_SHADERMODEL vs_3_0
    #define PS_SHADERMODEL ps_3_0
#else
    #define VS_SHADERMODEL vs_4_0_level_9_1
    #define PS_SHADERMODEL ps_4_0_level_9_1
#endif

technique MyTechnique
{
    pass Pass1
    {
        VertexShader = compile VS_SHADERMODEL MainVS();
        PixelShader  = compile PS_SHADERMODEL MainPS();
    }
}

Custom symbols can be defined via the MGCB Editor (per-asset Defines field) or the MGFXC command line (--defines).

Effect Writing Rules

These prevent silent bugs and cross-platform breakage:

1. Vertex shader outputs must exactly match pixel shader inputs — same types, same semantic order. Omitting a parameter may compile but will pass garbage in the wrong register on some platforms.

1. No default values on GL platforms — float Intensity = 0.5; in the effect file works on DX but is silently ignored on OpenGL. Either set the value from C# after loading, or use #define:

   #define INTENSITY 0.5

1. Unused parameters are aggressively stripped — if you declare a parameter but never read it in a shader, the compiler removes it. Parameters["MyParam"].SetValue(...) will then silently fail (the parameter won't exist). Ensure every declared parameter is actually read in the shader body.

1. Preshaders are not supported — MonoGame ignores preshader blocks.

1. Test on both DX and GL — a shader that compiles on DX may fail on GL due to SM level differences or MojoShader translation limits.

Two Ways to Use Custom Effects

Prefer MGCB for all game assets. Use MGFXC directly only for tools or editor workflows that bypass the Content Pipeline.

Reference

For HLSL code templates, parameter setting patterns, and multi-pass effect examples, see references/effects.md. For SpriteBatch integration, post-processing pipelines, and the Material class pattern, see the monogame-shaders skill.