The Content Importer

The Content Importer is a class that is used to load an asset from disk. The class must inherit from ContentImporter<T> and be marked by a ContentImporter attribute. This will allow the Content Pipeline Tool to discover the importer and present it as an option in the Importer drop-down. Figure 2-3 shows the available importers in the Content Pipeline Tool, with the Texture Importer selected.

The code above declares a TextureImporter class that inherits from the ContentImporter with a generic type TextureContent that is a class type that will be used to hold the image data in memory once the asset is loaded. The TextureImporter is marked with the ContentImporter class attribute that defines which file types can be imported by this code, which display name to put in the drop-down selection of the content pipeline tool, and which content processor class will be needed to process the asset once loaded.

The importer’s job is simple: open up a file stream, read the content of the file, and store the data into an instance of an object designed to hold that data. This is done within the Import() function of the importer. Once loaded, the content pipeline takes the data and passes it to the next stage of the pipeline, where it will be processed.

You will keep looking at how the content pipeline handles textures in this section, so it is important to note that the TextureImporter actually creates an instance of a Texture2DContent when loading an image, which is fine because Texture2DContent inherits from TextureContent, used as the generic type of the importer. This will be important to remember later.

The Content Processor

Similarly to the importer above, the content processor is also selectable from a drop-down in the Content Pipeline Tool, as Figure 2-4 shows. The processors available to the Pipeline Tool must inherit from the ContentProcessor<TInput, TOutput> abstract class and be marked by a ContentProcessor attribute that is used to specify the display name of the processor in the drop-down. The idea behind the processor is to take an object of type TInput and transform it into an object of type TOutput before passing it onto the next stage of the pipeline.

Here, the TextureProcessor class is designed to transform an object of type TextureContent into a new object of the same type. Since the importer you looked at above creates Texture2DContent objects, which inherit from TextureContent, the output of the TextureProcessor is also a Texture2DContent instance. One of the things that is done by the processor is the generation of mipmaps, if they are needed.

The processor parameters can be marked with a DefaultValueAttribute if you desire to change their default values, which is based on the type of the parameter.

Now that you have imported and processed your textures, it is time to save them back to disk.

The Content Writer

Saving a processed asset back to disk in an .xnb format is the job of the content writer. Content writers are discovered at runtime by the content pipeline tool when the time comes to save processed data of a certain type, so in order to save data of a certain type, T, there must be a class in the codebase that inherits from ContentTypeWriter<T> and is marked by the ContentTypeWriter attribute. Without that, no writer class will be found and the Pipeline Tool will fail to generate an .xnb file.

Note that BuiltInContentWriter<T> inherits from ContentTypeWriter<T>, so this works. The BuiltInContentWriter class is private and is only used for the content types that are built into the framework.

The Write() method of a given content writer will be called by the pipeline tool with two parameters: an output object with an interface allowing its user to write many different kinds of values to disk as binary data, and the content object that needs to be saved.

One secondary aspect of the content writer is that it is also responsible for indicating which content reader will be needed to load the .xnb file back into memory. Once the content object has been serialized, the Flush() method is called on the output object by the pipeline. This will cause a header to be written near the start of the .xnb file, and one of the elements in the header is the full class name of the content reader that will be instantiated to load the data back from disk. The name is accessed by calling the GetRuntimeReader() function on the content reader. You will not see one on the Texture2DWriter because it is overridden in its BuiltInContentWriter base class, where the content reader class name is set to the same name as the content writer (Texture2DWriter here), except that “Writer” is replaced with “Reader.” Using that logic, loading a Texture2DContent object will require an instance of the Texture2DReader, which we will discuss next.

The Content Reader

The content reader is a class that must inherit from ContentTypeReader<T>. Contrary to the other three classes used by the Content Pipeline Tool, this class does not need to be marked by an attribute. This is because this class is not auto-discovered by the MonoGame framework. Instead, when loading an .xnb file from disk, one of the file headers has the full class name that needs to be used to load the file. Once the class name has been read from the file headers, MonoGame will create an instance of the class and call its Read() function, which will load the same binary data that was written to disk by the content writer. This is all done when the content manager’s Load<T>() function is called to load an asset into the game.

We covered quite a bit of internal details here, but this knowledge will be important should you want to develop your own importers, processors, writers, and readers. Extending the content pipeline tool to be able to handle custom data types is not too unusual and it is something you can do right now.

Creating a Pipeline Extension

MonoGame has a template for creating pipeline extensions. In Visual Studio, create a new project and select the MonoGame Pipeline Extension template, as shown in Figure 2-5. Name your project PipelineExtensions.

This will create a .Net 2.0 C# library project in your solution that contains two initial files: Importer1.cs and Processor1.cs. Before compiling the project, set it up in the solution to be compiled in Release mode, as seen in Figure 2-6. To configure solution properties, right-click the solution and click Properties.

Compile the solution and then open the Content Pipeline Tool application. Click the top level Content item in the asset tree view to look at its properties. One of them, all the way at the bottom, is the list of references imported into the tool. It should look like Figure 2-7.

Click the References property and a pop-up will open, as shown in Figure 2-8. Click the Add button and navigate to where your pipeline extension project’s DLL is being built. It should be in the PipelineExtensionsinRelease etstandard2.0 folder. Select the PipelineeExtensions.DLL file and click Okay to close the pop-up.

You should now see Importer1 and Processor1 in the drop-down options when selecting processors and importers for your assets. See Figure 2-9 for an example.

Note that from this point on, you will need to close the Content Pipeline Tool application when you make changes to the PipelineExtensions project because it is using its DLL file and Visual Studio will not be able to overwrite it. Close it now since you are about to make changes.

Adding Logic to Your Extension

Let’s create your four pipeline building blocks. First, delete Importer1.cs and Processor1.cs. These two files will not be necessary anymore. Instead, create these four classes:

• LevelImporter

• LevelProcessor

• LevelWriter

• LevelReader

Your level importer will read the level text files and transform them into a single string. Then your level processor will take in the string and output a Level object that will be saved as an .xnb file by the level writer. Finally, the level reader will be in charge of reading in the .xnb level file and giving your game a Level object to work with.

This will change how the game code accesses and interacts with level assets. While we will not cover this part of the code in this chapter, please refer to the book’s source code for the full details of how the game code was modified to accommodate the new pipeline extensions. We will only go over the extension’s code in this chapter. It suffices to say that the responsibilities of reading in a level text file as a string and transforming it to a list of level events has been moved to the pipeline extension project in the Level.cs file.

Loading and Saving Assets

With that said, let’s take a look at your LevelImporter class :

[ContentImporter(".txt", DisplayName = "LevelImporter",

 DefaultProcessor = "LevelProcessor")]

public class LevelImporter : ContentImporter<string>

{

 public override string Import(string filename, ContentImporterContext context)

 {

 return File.ReadAllText(filename);

 }

}

The class inherits from ContentImporter<string>, meaning it will load the asset file and output a string. It is also marked with the ContentImporter attribute, which specifies that level asset files will be .txt files, that the Content Pipeline Tool application will use the name LevelImporter in the drop-down options and that the pipeline will pass the output string to the LevelProcessor class .

You then override the Import() function and use the basic IO.File.ReadAllText() function to read the entire .txt file, referenced by the filename parameter provided to you by the content pipeline when it calls your extension, as a string.

While you do not use the context parameter here, it can be useful for debugging purposes. Its properties can be used to inspect the intermediate and output directories of the current processor and the Logger property provides a logger that you can use to output messages while running the Content Pipeline Tool.

Next, your LevelProcessor will look like this:

[ContentProcessor(DisplayName = "LevelProcessor")]

public class LevelProcessor : ContentProcessor<string, Level>

{

 public override Level Process(string input, ContentProcessorContext context)

 {

 return new Level(input);

 }

}

The LevelProcessor inherits from ContentProcessor<string, Level>, which means that its overridden Process() function takes a string as input and will output a Level object. It is also marked by the ContentProcessor attribute with a DisplayName of LevelProcessor. Note that in the book’s source code, there is a Level class in the PipelineExtensions project and this is what the code is referring to here, not the Game’s Level class. The process of transforming a string into a Level is described in detail in the MonoGame Mastery book and its code has been migrated into the extension’s Level class.

Now let’s take a look at your LevelWriter so you can create the .xnb files, which will simply output the level as a string, the same string that was read from the original asset file. You could have been more precise and output the level grid’s dimensions, followed by each value of each row, but saving the string itself is more flexible at this point given that you will change the level assets in Chapter 4.

[ContentTypeWriter]

public class LevelWriter : ContentTypeWriter<Level>

{

 public override string GetRuntimeReader(TargetPlatform targetPlatform)

 {

 return "PipelineExtensions.LevelReader, PipelineExtensions";

 }

 protected override void Write(ContentWriter output, Level value)

 {

 output.Write(value.LevelStringEncoding);

 }

}

The LevelWriter is discovered by the content pipeline when the time comes to save the processed output into an .xnb file, because it is marked by the ContentTypeWriter attribute. A lot of work is done for you by the framework at this point, like creating the .xnb file and writing its headers. All you need to provide here is an overridden GetRuntimeReader() function that returns the full class name of the LevelReader class that will be used to read the .xnb file back, and an overridden Write() method that you can use to write the Level value to disk as a binary file.

Finally, here is your LevelReader class:

public class LevelReader : ContentTypeReader<Level>

{

 protected override Level Read(ContentReader input, Level existingInstance)

 {

 return new Level(input.ReadString());

 }

}

The LevelReader inherits from ContentTypeReader<Level>, which indicates that its Read() function will return an instance of the Level class. Read() takes two parameters: a ContentReader object that knows how to read different binary values and convert them into basic types, and an existingInstance of the object you are trying to create, which can be confusing. Before calling the Read() function , the pipeline will create a default instance of the desired object and pass it in as the existingInstance. Here, you are ignoring the parameter and creating a new instance of the level yourself.

Now that your pieces are in place, you can move your level files out of the code base and treat them just like any other asset. In the books’ source code, the evel1.txt file was moved to assetslevelslevel1.txt alongside the sounds, music, and texture assets. It was then added to the Content Pipeline Tool into the Levels folder, as shown in Figure 2-10.

Creating the XML Template

This code starts with two comments that indicate which namespaces need to be imported into the code if you are not using Visual Studio to auto-discover them.

The XML file starts with an XnaContent tag that indicates which assembly contains the class that you want to write the data to. It is followed by an Asset tag that is used to map the data below with a specific class that will receive it. From there, each tag represents a public variable on the class and lists, like the Frames list, contain a series of Item tags that are used to fill each frame in the list. With this information, you can move your PlayerSprite animation data into an asset.

Creating the TurnLeft Animation Asset

This file follows the same format as your template, but is filled with the data used in original game code used to create the _turnLeftAnimation animation. Now add this file to the content pipeline tool, set the importer to the “Xml Importer – MonoGame,” the processor to “No Processing Required,” and build the assets, which should build the .xnb file for the animation. All that you need to do now is load it as game content and build the animation from the AnimationData object.

Finally, after doing the same thing for the turnRightAnimation, running the game should give you the exact same behavior as the original game. While you have not improved the game itself, you have added flexibility into how you build your game assets and decoupled animation details from the code.