MonoGame.Samples, the reference games and tutorials behind MonoGame

The samples and what each one demonstrates

This repository holds a number of simple MonoGame samples for all the supported platforms, and the four games are chosen to cover different things rather than to be variations on the same idea.

The Platformer 2D sample is a basic 2D platformer pulled from the original XNA samples and upgraded for MonoGame. That provenance matters, because the XNA samples were the reference code for a generation of developers and the upgrade path shows what changes when a framework moves on.

The Auto Pong sample is described as showing how to make the classic game of pong with generated sound effects, in 300 lines of code. The line count is the point, since it makes the sample small enough to read in one sitting and copy from.

The Neon Shooter sample is the opposite: a graphically intensive twin-stick shooter with particle effects and save data, from Michael Hoffman. It is the one to look at when you want to know what a game with actual effects looks like in the framework.

The Ship Game 3D sample is a Descent clone pulled from the XNA archives and updated for MonoGame. Its platform support is narrower than the others, listed as GL, DX, iOS and Android, which is a reasonable reflection of what a 3D sample needs.

Between them the four cover a 2D platformer, a minimal arcade game, a particle-heavy twin-stick shooter and a 3D flight game, each on a different platform baseline. That is a deliberately spread selection, and it is what makes the repository useful as a set of reference points rather than a single tutorial.

The tutorial series and where the code lives

The samples repository is also home to the source for each of the tutorial series, and the README tabulates tutorial, documentation link and source link.

Building 2D Games is the starting point, with its documentation in the MonoGame documentation site under the tutorials section and the source under Tutorials/learn-monogame-2d. Advanced 2D Shaders is the second, with the source under Tutorials/2dShaders. FuelCell 3D is the third, with the source at the top level in FuelCell, which is also a sample in its own right.

The distinction between the documentation and the source columns is the useful thing here. The articles on docs.monogame.net are the readable version, and the repository holds the code those articles refer to, at the branch that matches the current release. Following a tutorial therefore means reading the article and having the working code open in the same editor, which is a much better arrangement than a code listing embedded in a web page.

The 2D shaders tutorial is the one most likely to be useful to a developer working on something specific. Shaders are where a 2D framework stops being straightforward, and having a sample that builds and runs with a working shader setup saves the usual half hour of finding the right content pipeline settings.

The FuelCell 3D tutorial is the counterpart for 3D, and it is worth noticing that it is listed as a tutorial and as a standalone project at the same time.

The branch name is the other detail worth noting. The default branch is 3.8.5, so the samples are pinned to a specific MonoGame release rather than tracking the development branch. That is the right choice for a reference repository, since a sample that does not build is worse than no sample, but it does mean the samples lag the framework by a release cycle.

Building the samples and the CI NuGet caveat

There are two ways to build, and the second has a wrinkle.

The first is to open a project in Visual Studio for Mac or Windows and build it there. The second is to build with the .NET Core tool chain, and the README names one exception: the Windows UWP sample, which is Windows 10 only.

The wrinkle is the CI NuGets. If you are using those, the README says to unzip them to an accessible directory and add that directory to the list of NuGet sources on your machine, with a command of the form `dotnet nuget add source [unzipped-directory-location] -n MG-Nugets`. The README links out to the MonoGame documentation guide on packaging games and to the Microsoft documentation for adding a NuGet source.

The reason this comes up is worth understanding. The MonoGame build produces native binaries for each platform, and those are distributed as packages rather than as a normal project dependency. A build that resolves them from the network gets a version that may not match the framework source in the repository, which produces errors that look like code problems and are not. Pointing at a known directory of packages is what makes the build reproducible against the pinned branch.

The supported platform list is the other thing to note. The README says the samples demonstrate all the public platforms available for use: Windows with Desktop GL, Windows DX and UWP, Mac with Desktop GL, Linux with Desktop GL, Android and iOS. It also notes that platforms such as XBox, Playstation, Switch and Stadia are private platforms requiring developer accounts with the corresponding vendors.

And there is a build constraint that catches people out: to build a project for iOS or Mac you need a Mac. The projects will build on Windows but cannot be published unless built on a Mac. So a Windows-only CI can compile them for checking, and the packaging step has to happen elsewhere.

How this fits against the alternatives

There is really only one alternative, and it is the older XNA samples that several of these are derived from. The Platformer 2D and Ship Game 3D samples were both pulled from the XNA archives and upgraded, which makes the repository the maintained version of code that is otherwise frozen and increasingly hard to build.

The second comparison is with the documentation alone. The MonoGame documentation site carries the tutorials, and the samples add something the articles cannot: a project that opens and runs. For a framework where a great deal of the difficulty is in the content pipeline and the project settings rather than in the API calls, a working project is the more useful artefact.

The third is with other engines entirely, and that comparison is about what you are committing to. MonoGame is a low level framework in the C# ecosystem, which means it gives you control over the rendering and the pipeline and asks you to supply the architecture. A higher level engine gives you scenes, entities and input handling. Choosing MonoGame over those is a choice to do more of the work in exchange for the ability to do things the higher level engine does not model, and the samples are a good way to see how much work that is.

The practical recommendation is to treat this repository as a starting point. Copy the project file of whichever sample is closest to what you are building, keep the content pipeline configuration, and replace the game code. The pipeline settings are the part that takes longest to get right, and the samples are correct for the version they are pinned to.

One caveat to keep in mind. The pinned branch means the samples are built against a specific release, and a project that will ship should move to the current stable version of the framework and re-verify the pipeline settings rather than assuming they carry over unchanged.

Editorial conclusion

Adopt MonoGame.Samples as the starting point for a new MonoGame project and as the reference for the tutorial material rather than as a dependency. Skip it if you are on a MonoGame version other than the pinned branch, because the samples track a specific release. Verify first by opening one sample in Visual Studio and building it for your target platform, and by reading the CI NuGet note before you rely on the .NET Core build path.

Frequently asked questions

Official sources

1. Issues
2. MonoGame/MonoGame.Samples on GitHub
3. README