For some time now I’ve been asked if I would do a session on the “Darkside of MonoGame” about using XML with MonoGame and the Content Pipeline, for a while I put it off as I had my own schedule and agenda with the channel.  Eventually I got worn down and I’ve succumbed to the demands of my viewers (it can happen )

The video for this post can be found here if you prefer video:

Why use XML?

For as long as there have been games, there has been a need to generate game content outside of the game and avoid writing all this pesky code stuff, everything from:

It can be very powerful to use, if wielded correctly and it gives power to your content / mod creators of your game.  Any situation that requires lots of configuration or walls of text just works better if it’s separated from your code base and manageable outside of the core code.

Why use the MonoGame Content Pipeline?

Loading text (which is all xml is at the end of the day) can be slow, very slow if it’s pages long, so you don’t really want to be doing that at run-time inside your game.  Sure, you can but should you?  You can hide this behind clever loading screens or whilst the main menu is up, but at the end of the day your game needs to:

Don’t get me wrong, there is nothing wrong with this path specifically but it is wasteful and if anything goes wrong or you mistyped something in the XML, it’ll only fall down flat on its face when you run/load that file.  You can just create a separate tool to validate the XML for you but that’s even more work to do.

With the content pipeline in MonoGame however, the majority of this work is done offline when you are building your project, in fact the XML validation happens inside the pipeline itself so you don’t even need the game in order to test and build the XML, it can all be done separately and you know it will all “just work”™.

Another benefit is both size and compression. When using the Content Pipeline, all the assets are specifically serialized and compressed for each platform to cater with all their specific differences. How you binary serialize and deserialize on one platform is different to some others (just ask console developers!).

Lastly is ease of use and support. With MonoGame, we inherited the IntermediateSerializer which the XNA god Shawn Hargreaves created for XNA.  This little helper which he crafted between builds, greatly helps with serialization and can even support lists and dictionaries out of the box (as well as some xml performance improvements). That combined with turning every XML asset in to “just another asset” which is loaded from the Content Pipeline just like anything else, loading it becomes as simple as Content.Load<MyXML>, easy.

Setting up your data

Right, when getting started with XML, you need to understand there are three main components to handling XML serialization with MonoGame, the XML schema, the Data Class and the Game code:

image

This is a simple architectural principle to deal with when handling any content that is provided externally to your project (or internally in some cases) whereby you have a rigid schema, which will be populated by an unlisted source (conforming to the schema) and then consumed by game functions and logic.  The last two can be merged but can likely create troubles later if you start manipulating the wrong data, so my advice is to simply keep them separate, for example:

My Data schema has the following properties:

Now if the level loads with a certain number of enemies and the player starts killing them, do you simply start hacking away at the Enemies collection held in the XML? Doing so means you need to completely reload the XML should the player wish to restart the level. Alternatively, you might have a separate array either to track which enemies have been killed and then simply keep track of who’s dead or who isn’t. All comes down to the style of game.

Another view is if you use the Data Schema to run your game, or if you simply refer to the data within specific game functions, for example compare these two classes:

A Class extending schema

public class MyLevel
{
     //Data 

    //The name of the Level
     public string LevelName;
     //Number of enemies at the start of the level
     public int MaxEnemies;
     //Time Limit to complete the level
     public float TimeLimit;

    //Functions
     public void KillEnemy()
     {
         //Do Kill
     }
}

Class with data property

public class GameLevel
{
    //The current loaded level data
    MyLevel currentLevel;

    //Current Enemies
    private int enemyCount;
    //Time progressed in this level
    private float levelElapsedTime;

    //Functions
    public void KillEnemy()
    {
        //Do Kill
    }
}

One example simply extends the data class with additional functions (mixing data with function), the other takes the data in to itself and then works with it.  My recommendation is to use the second as it keeps a clear line between what is your loaded data and what you do with that data in your game but ultimately, it’s up to you.

Getting Started with XML in MonoGame

Once you’ve decided on your schema and data, getting this put together in MonoGame is fairly quick and painless, we simply need:

Once we understand what data we need, we need to decide where to keep it. This is critically important as it needs to be referenced by BOTH the Game project and the Content Project.

There are a couple of options, which sum up to:

Both have their advantages/disadvantages with regards to setup and maintenance. My preference is to use a library project as it offers the most flexibility and also enforces good architecture, which I’ll walk through creating here.

So, let’s walk through setting everything up and for simplicity, I’ll follow the portable library path.

1: Creating the library to hold the data schema

As stated, I always use a separate library to maintain the schema definitions for by data.  I also usually create extension methods or worker classes in my game to consume that data.  To get started (assuming you have created a MonoGame game project already), I create a new library project in the solution, to ensure maximum compatibility I also create it as a Portable Class Library, meaning I can use the same project for all platforms supported by MonoGame.

image

New project wizard, selecting a C# Portable Class Library

Once you click OK, you will be prompted with the platform targets selection and for simplicity’s sake, you can just select everything ensuring maximum compatibility.  Also, be sure to check the .NET framework is a minimum of 4.5 as that is what MonoGame is currently based on.

image

New Portable Class Library Platform Target selection screen.

Your project should now look as follows with your game and library projects.

image

Updated game solution.

From here the instructions for your path converge as we create a data class and then consume it from the Content Pipeline.

2: Create the Data/Model classes

The next thing we need is our data schema we intend to use/store our XML data in. So, if we define a class for our level using the above example, we end up with the following:

public class MyLevel
{
    //The name of the Level
    public string LevelName;
    //Number of enemies at the start of the level
    public int MaxEnemies;
    //Time Limit to complete the level
    public float TimeLimit;
}

Once you’ve created your data class, you need to make a specific note of BOTH the Namespace and Class name of your data, as shown here:

namespace MyXMLData
{
    public class MyLevel
    {

Here you can see the direct reference in the sample data class is “MyXMLData.MyLevel” This is critical for the next step when you are constructing your XML.

3: Generating your XML

When you’re creating your XML for the first time, you have a couple of options:

When generating it yourself or through the Content Pipeline tool, you should be starting with the following default schema:

<?xml version="1.0" encoding="utf-8"?>
<XnaContent xmlns:ns="Microsoft.Xna.Framework">
  <Asset Type="Object">
  </Asset>
</XnaContent>

Here we see the top level “XnaContent” xml section which denotes this is an XML data content file for MonoGame (leaning on its XNA roots so that everything is backwards compatible). You can just remove the xml:ns block if you wish, as it doesn’t really add anything.

Within that, you then have an “Asset” node which tells the content pipeline what type of data it is that it will be loading, this is where the namespace and class name I mentioned earlier comes in.

Using the same example we used earlier, the resultant XML would look as follows:

<?xml version="1.0" encoding="utf-8"?>
<XnaContent>
  <Asset Type="MyXMLData.MyLevel">
    <LevelName>explosion</LevelName>
    <MaxEnemies>50</MaxEnemies>
    <TimeLimit>300</TimeLimit>
  </Asset>
</XnaContent>

Here you can now see I have created a new Asset of Type “MyXMLData.MyLevel”, using the same Namespace and class name of my data class.  Then we have individual nodes for each property in our class, simples.

So, with your XML in place, added to your Content Pipeline project, what’s next?

4: Finishing up and adding a reference to the Content Pipeline tool

With both our data class and the XML ready, we now just need to pair them up in the Content Pipeline tool, this is simply done by adding a reference to the project containing the data classes and then just let the magic happen.

With the Content project open and your XML imported, simply click on the Root “Content” node in the editor and then click on the “References” option in the properties window, as shown below:

image

Content Pipeline tool, adding references.

Once the Reference wizard is open, it’s simply a case of clicking add and pointing it to the DLL of your data project:

Now when you build your Content Project (providing everything is aligned) you should see a nice green tick meaning everything is good!  If you then want to pass the content project and data library to other people, they can then get on building content and use the Content Pipeline tool to validate everything is on the up and up.

image

A successful build

Once loaded it can be accessed anywhere in your game by simply calling:

MyXMLData.MyLevel Level1 = Content.Load<MyXMLData.MyLevel>("Level1");

The Sample

As even with each of these videos / posts, there is a sample drawn out of the XNA library to help support it. This time it’s the XML Particles sample which makes a nice show of using XML content to construct particle effects.  Check it out here:

Other tips and Tricks

it wouldn’t be a proper post if I didn’t also include some extra tips’n’tricks:

Building XML from code

one neat trick as outlined by Shawn Hargreaves here, is to use the Content Pipeline in your project whilst crafting your XML.  Here you simply instantiate your data class in code and then use the Content Pipeline’s IntermediateSerializer to serialize your code and generate the XML, for example:

MyXMLData.MyLevel testData = new MyXMLData.MyLevel();
testData.LevelName = "MyLevel";
testData.MaxEnemies = 99999;

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;

using (XmlWriter writer = XmlWriter.Create("test.xml", settings))
{
    Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer.Serialize(writer, testData, null);
}

Here I’ve created a new instance of the “MyXMLData.MyLevel” class, populated it with some data and then sent that to the serializer to output to a new XML file.

The only additional thing you need is to add a reference to the Content Pipeline in your project while you are building the content, you can find the DLL to reference in the following location

This should only be a temporary thing and you should remove both the reference and code (or at least comment it out) for a production or runtime build, just due to the sheer number of dependancies needed for the Content Pipeline itself.

Using MonoGame references in your XML

Want to use Vector2, Rectangles or Point’s in your schema, then fine. Just ensure your data project (ignore this if you have your data in your game project) has a reference to the MonoGame.Framework. If you are using a PCL, there is even a package for that. Simply install the MonoGame.Framework.Portable library in your PCL project and you are good to go. Simples.

image

MonoGame.Framework.Portable on NuGet

Content Pipeline tool not opening when you double click on the Content Reference?

Do you only see the text contents when you double-click on your content project in Visual Studio, then fear not as there is a simple fix for that.  All that happened is the launch action for the Pipeline tool didn’t get associated for some reason for .mgcb files (which usually happens when the wind is blowing east on a Tuesday and the milkman is at your door, normally).

To fix this simple right-click the .MGCB Content file and select “Open With”

image

Then select the “MonoGame Pipeline Tool” from the list on the left and then click on “Set as Default”

image

Now the handy tool will open with for your content project forevermore.

Ship it!

Right, that’s all from me for this session.  I’ve still got to go back and finish the Getting Started with 2D blog post to accompany that article as well as get some more work done to the MonoGame NuGet’s.

So, what are you still here reading this for, go get some XML in your game!

As usual, questions or queries in the comments below and I’ll get right on that.