MonoGame.Forms is the easiest way of integrating a MonoGame render window into your Windows Forms project. It should make your life much easier, when you want to create your own editor environment.
Clone or download
Latest commit 83f677d Nov 20, 2018

README.md

Banner

Welcome to MonoGame.Forms!

Twitter Follow Wiki License

NuGet NuGet NuGet

MonoGame.Forms is the easiest way of integrating a MonoGame render window into your Windows Forms project. It should make your life much easier, when you want to create your own editor environment.

Now with OpenGL support!

Building

  • The MonoGame.Forms.DX project uses the MonoGame.Framwork 3.7.0.1114, which is already precompiled and included in this repo.
    • It's possible to use older MonoGame.Frameworks like the 3.6 iteration, but you will then lose the Mouse.GetState() functionallity. You would then rely on the WindowsForms Event System for mouse input, which can be slower in some cases.
  • The MonoGame.Forms.GL project uses a modified version of the MonoGame.Framework based on the development build from 16th of JULY 2018.
    • It's not possible to exchange the MonoGame.Framework easily. If you want to use a newer build, it would be neccessary to modify it to suit the needs of MonoGame.Forms!

Tips & Tricks / Dos & Don'ts

The OpenGL version of the library currently renders differently than the DirectX one, which makes it generally slower. If you need as much perormance as possible, you should definitley use the DirectX library.

  • Boost performance of a custom OpenGL control by raising its DrawIntervall with the property window during design time (try 50ms or 100ms. 1ms aims to 60 fps)
  • Never use DoubleBuffering on a custom control. This counts for the OpenGL library as well as for the DirectX library! It will cause flickering and slow downs.

How-To

Setup MonoGame.Forms

First you need to make your MonoGame.Forms library ready to use. This step is very easy; you just need to compile either the MonoGame.Forms.DX or the MonoGame.Forms.GL PCL from source and then just add the compiled DLL's to your project.

This is the prefered route, when you want to make you own custom changes to the library or extend it.

Another option is to install the library with the NuGet package manager:

NuGet

This is the prefered and easiest route to be automatically up to date.

Note: You need to set the .Net Framework version to 4.5.1 to install from NuGet!


Tutorial

The following tutorial is working exactly the same on both libraries (DX and GL).

Creating a simple DrawWindow

Let's start using the MonoGame.Forms library by creating a simple draw window!

(it's assumed that you already have created a new Windows Forms project with the installed library)

  1. Create a new class and name it DrawTest
  2. Inherit from MonoGame.Forms.Controls.DrawWindow
  3. Override the Initialize() method from DrawWindow
  4. Override the Draw() method from DrawWindow
  5. Save & Build your solution
  6. Double Click on Form1.cs so that the Designer opens
  7. Open the Toolbox
  8. Drag & Drop the newly created control onto the Form1 control
  9. Open the Properties of the new control and set the Dock option to Fill

This is how it should look now:

Tutorial

  1. Now run the solution and see the classical CornflowerBlue-Screen you are (surly) familiar with! ;-)

Tutorial

And yes, as you can see: it is realy THAT EASY!

Now I bet you wonder how to draw something to this control, right? I bet you think that this is now the difficult part, right? Well... it's not!

More than that it's basically the same like you are used to do in the MonoGame.Framework. Just with a small difference (no it's still not difficult!)

In MonoGame you could draw someting to the screen with the SpriteBatch. In MonoGame.Forms you will do the same but you need to use the DrawService for this.

In the DrawWindow class this service is called Editor. To draw something to the SpriteBatch you need to do this:

Editor.spriteBatch.DrawString();

Do you see? Easy! :)

The DrawService class inherits from GFXService. It contains some MonoGame specific stuff like a ContentManager. Examine everything calmly. I just want to explain a little how MonoGame.Forms works under the hood!

To sum things up, let's take a look at the final DrawTest class:

using Microsoft.Xna.Framework;
using MonoGame.Forms.Controls;

namespace nugetTest
{
    public class DrawTest : DrawWindow
    {
        string WelcomeMessage = "Hello MonoGame.Forms!";

        protected override void Initialize()
        {
            base.Initialize();
        }

        protected override void Draw()
        {
            base.Draw();

            Editor.spriteBatch.Begin();

            Editor.spriteBatch.DrawString(Editor.Font, WelcomeMessage, new Vector2(
                (Editor.graphics.Viewport.Width / 2) - (Editor.Font.MeasureString(WelcomeMessage).X / 2),
                (Editor.graphics.Viewport.Height / 2) - (Editor.FontHeight / 2)),
                Color.White);

            Editor.spriteBatch.End();
        }
    }
}

Result:

Tutorial

It's pretty much like in the MonoGame.Framework!


Creating a simple UpdateWindow

As you might though right: Yes, this is also very easy. It's the same like for the DrawWindow. I just want to show you the only difference:

protected override void Update(GameTime gameTime)
{
    base.Update(gameTime);
}

The update method makes realtime interactions with your game- / editor environment possible. Even complex mechanics are doable.

I just want to refer to the nice MonoGame.Forms.Test-Project, which is part of this repo. Take a look at it and learn from its samples.

Note: To raise the performance of an OpenGL UpdateWindow, it's recommended to change the DrawIntervall from 1ms to 50ms or 100ms!

DrawIntervall

Did you notice the BackColor and ForeColor property? Changing these values makes it possible to style your controls to something like this:

Style

Do it to keep the overview and feel of your custom editor project!

Note: The MonoGame logo is placed automatically inside a newly created control to make it clear, that it is a render control with MonoGame functionality!

Sample Pics

Here are some pics of some samples included with the repo:

DX (Windows 10 Pro 64 bit)

Sample

GL (Ubuntu 18.04 LTS [Bionic Beaver] 64 bit)

Sample

Projects using MonoGame.Forms!

Please watch the following YouTube videos in 1080p @ 60fps to see what is possible with MonoGame.Forms!

This project is called: "Rogue Engine Editor" and it's possible to create Rogue Adventures with it:

Rogue Engine Editor

Twitter: #RogueEngineEditor


This project is called: "PenumbraPhysics.Editor" and it was the prototype for the Rogue Engine Editor and MonoGame.Forms:

YouTube Video

GitHub: PenumbraPhysics.Editor


Now Have Fun with MonoGame.Forms!

Twitter Follow Wiki License

NuGet NuGet NuGet

Logo

Special Thanks