This tutorial will go over the basics of setting up a new Nez project.

Nez is a lightweight, 2D framework built upon MonoGame/FNA. You can read more about what Nez is and it’s features in the official documentation. It uses a Scene/Entity/Component system with Component render layer tracking and optional entity systems, which will be covered in future tutorials. However, if you’re unfamiliar with Entity Component Systems, be sure to familiarize yourself with them.

This tutorial uses Windows 10, Visual Studio 2017, and MonoGame 3.6.

MonoGame Setup

Nez requires a standard MonoGame project to be set up. You can follow the official documentation to do this here, but basically all you need to do is:

  1. Download Monogame for VisualStudio.

  2. Create a new MonoGame Cross Platform Desktop Project. We’ll call it “NezProject”. The reason I’ve chosen this type of project is that is uses OpenGL, which Nez supports out of the box. Using DirectX instead may lead to complications down the road.

    New Monogame Project

  3. Ensure everything works by building the project. You should be greeted by a nice cornflower blue window.

    Monogame Works!

Adding Nez

Now we’ll add Nez to our solution. The official documentation for this process can be found here.

  1. Clone or download the Nez repository.

  2. Add the Nez project to the solution by right clicking the NezProject solution > Add > Existing Project…

    Adding a project

  3. Navigate to the Nez repository previously downloaded and open Nez/Nez.Portable/Nez.csproj.

    Selecting Nez Project

  4. Add a reference to the Nez project by selecting NezProject > Add > Add Reference… , select the Projects tab then select Nez.

    Adding Nez Reference

    It should be noted that Nez’s project references may need to be re-linked at this point. If we come across build issues after setup, this is a place to check.

Adding Nez Pipeline Importer

Here we’ll add the Nez Pipeline Importer to our solution. This step is optional, but recommended. As per documentation:

“Nez provides a plethora of Pipeline Tool importers out of the box. Importers take data such as Tiled maps and convert them into a binary format that is much faster and more efficient to use at runtime.”

Adding the Pipeline Importer is similar to adding the Nez project above.

  1. Add the Nez.PipelineImporter project by right clicking our solution > Add > Existing Project… , navigating to and adding Nez/Nez.PipelineImporter/Nez.PipelineImporter.csproj.

  2. Open the Nez.PipelineImporter’s references and add a reference to the Nez Project.

  3. Build the Nez.PipelineImporter project.

    Building Nez Pipeline

  4. Open the Pipeline tool by navigating to our project’s root folder > NezProject > Content, then opening the Content.mgcb file.


  5. Add references to PipelineImporter.dll, Ionic.ZLib.dll, Newtonsoft.Json.dll and Nez.dll.

    Content References

Now we’re set up! Nez supports many importers out of the box. You can read more about it in the Pipeline Importers FAQ.

Setting up the Game class

Now that we have Nez set up, we can move into hooking it up to our previously created MonoGame project.

We’ll start by sub-classing Game1.cs into Nez.Core. You can read more about Nez Core here.

We’ll then clean up extra code by removing references to GraphicsDeviceManager graphics and SpriteBatch spriteBatch. For flavor, I’ve changed the background fill color to LightGreen.

Game1.cs will end up looking like this:

using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;
using Microsoft.Xna.Framework.Input;

namespace NezProject  {
    public class Game1 : Nez.Core {
        public Game1() {
            Content.RootDirectory = "Content";
        protected override void Initialize() {
        protected override void LoadContent() {
            // TODO: use this.Content to load your game content here
        protected override void UnloadContent() {
            // TODO: Unload any non ContentManager content here

        protected override void Update(GameTime gameTime) {
            if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed || Keyboard.GetState().IsKeyDown(Keys.Escape))

            // TODO: Add your update logic here


        protected override void Draw(GameTime gameTime) {

            // TODO: Add your drawing code here


Building the project should display a nice, green window.

Nez Build Success


That’s it! Setting up Nez is pretty straightforward. We’ll use this as the base of tutorials going forward as we learn how to make games using Nez!

You can see the results of the tutorial on this Github Repo.

Coming up next will be Entity Component System basics, and how Nez fits into the puzzle. We’ll set up our first Nez Scene and add a simple player to it.