Appendix D: MonoGame Compatibility

FNA is designed to be a fully-compatible XNA 4.0 Refresh reimplementation that focuses on accuracy and preservation of the XNA catalog.

MonoGame, in contrast, is an XNA-like framework that is designed to be like XNA, but not 100% the same. XNA compatibility is likely, but not guaranteed.

FNA and MonoGame are mostly compatible with one another, but there are a handful of exceptions that are documented on this page.

Code Compatibility

API Compatibility

MonoGame is mostly XNA4-compatible, but this is not a guarantee. The API is allowed to change mostly at the whims of whoever sends patches and/or has write access to the project. For a successor this makes sense because it is XNA-like, meaning it's meant to feel a lot like XNA without preservation taking priority over what the MonoGame community actually wants.

In the context of FNA compatibility, this can be problematic if incompatible APIs are accidentally used. MonoGame API changes are not explicitly marked or documented, so the only way to be sure you're compatible is to constantly build against XNA or FNA.

While FNA is extremely strict about API compatibility, we do have formal processes for adding features in the form of extensions, build options, and environment variables, all of which are very clearly marked and are explicitly mentioned in every release that affects them. These features are designed to fill in the absolute worst gaps in the XNA API (mouse events, borderless windows, etc.), and oftentimes this improves MonoGame compatibility. That said, all of these additions are subject to modification and removal, based on the needs of the ecosystem.

Project Compatibility

MonoGame has a build system that generates project files for each platform, as every platform has a special build with different backend files and platform definitions. Some platforms share project files (DesktopGL for Windows/macOS/Linux, for example), but some platforms have multiple projects (WindowsDX vs. DesktopGL, for example).

FNA has only one project file for all platforms and backends, and we do not use platform definitions for any reason and will ALWAYS ban them from the source code, with absolutely zero exceptions. Given that C# is managed code, we have opted to detect platform information at runtime instead, for the few scenarios that platform checks are needed. You are encouraged to do the same in your own code, to allow for single-assembly portability. "Write Once Run Anywhere" is usually a fat lie, but "Build Once Run Anywhere" is entirely feasible for managed assemblies.

Content Compatibility

FNA and MonoGame are both compatible with almost all content built by the XNA Content Pipeline. FNA's exceptions are explicitly documented.

Content Pipeline

MonoGame has their own Content Pipeline tool, called MGCB. It is meant to act as a successor to the XNA Content Pipeline and generates separate content for every platform.

FNA does not have and will not have its own Content Pipeline tool. The lead developer of FNA has outlined his reasons for omitting this feature. You are STRONGLY encouraged to develop your own content tools, as they will be simpler, easier to use, more specialized and optimized, and will probably take a few days to make, unlike an XNA-like pipeline which would probably take years to complete.

That said, FNA is mostly compatible with MGCB, as MGCB creates data that is remarkably close to XNA-generated content (though it is not compatible with XNA). When building MGCB data for FNA, use the DesktopGL configuration.

Incompatible Formats

The following content formats are incompatible between FNA and MonoGame:

Effects. MonoGame opted to create its own shader format, called MGFX. Each platform has its own MGFX file that only works on that platform. FNA continues to support DXBC and Effect framework binaries generated by both the XNA pipeline as well as FXC, the offline compiler for DirectX shaders and effects, from the June 2010 DirectX SDK (ideally; if you have your own FXC from a Windows SDK that works then that's fine too). The one effect binary will work on every platform and backend. To compile an existing XNA effect file with FXC:

fxc.exe /T fx_2_0 MyEffect.fx /Fo MyEffect.fxb

You can also call FXC as part of your MSBuild process, as Andrew Russell's FNA template does.

Note that FXC is usable with Wine, meaning shaders can be developed on Linux and macOS.

Songs/Videos. MonoGame has various formats and backends used on various platforms, but FNA uses Ogg Vorbis (or QOA) and Ogg Theora for all platforms.

MGCB FNA Support

Lennard Fonteijn has provided specialized code for MGCB that should allow for the use of MGCB with FNA, even for the formats listed above. You can find this code here:

OggSongProcessor and FxcEffectProcessor for FNA and MGCB

Platform Compatibility

As a reminder, while MonoGame targets each platform with a different project version, FNA supports all of its platforms with exactly one project with no special versions.

Platform FNA MonoGame
Windows Direct3D ✔️ ✔️
Windows Vulkan ✔️
Windows OpenGL ✔️ ✔️
Linux Vulkan ✔️
Linux OpenGL ✔️ ✔️
macOS Metal ✔️
macOS OpenGL ✔️ ✔️
iOS/tvOS Metal ✔️
iOS/tvOS OpenGL ✔️ ✔️
Nintendo Switch [1] ✔️ ✔️
Xbox One [2] ✔️ ✔️
Xbox Series X/S ✔️ 🚧
PlayStation 4 🚧 ✔️
PlayStation 5 🚧 ✔️
Android ❌[3] ✔️
GGP (formerly Stadia) ✔️ 🚧
  1. For Nintendo Switch, FNA uses Vulkan/OpenGL while MonoGame uses NVN.
  2. For Xbox One, FNA uses GDK and MonoGame uses XDK.
  3. Android FNA is unofficially supported via FNADroid