I’ve started working on a new ninja game that was going to use largely tile based maps. I first started down the same road of Pixel Man, using Paint.NET for my level editor. I quickly realized that the increased complexity meant a confusing palette which made life too hard. It also ruled out things like cutscenes or any other interesting level markers. So I started working on my own editor. My method for resizing 2D arrays was so I could support the editor as I went. I never got very far into making an editor because, frankly, it’s a lot of work.

So I started feeling burnt out. I want to make this game but I was stuck from the get-go without having any means to create my levels. I could have gone ahead and hard coded a few maps but I find that’s not a workflow I tend to like. I prefer to solve the content problem first that way I know what data I will be able to code around. Today I came up with a solution for all of this. I would simply be lazy and find a tile editor someone else had made, thus saving me time.

During some random searches, I found a nice tile editor called Tiled. Tiled is a near perfect editor for tile maps. You can attach metadata to pretty much everything and you can make layers that just hold arbitrary rectangles of metadata. It’s really quite nice. Here’s one of my test levels in Tiled:

You can see I dedicated a rectangle for a spawn point and two for cutscenes which I could use to display some text about the game or whatever (this is a test level so none of those really mean anything).

So this editor is great. It does pretty much everything I need out of an editor, but how can I use the levels? Thankfully all levels are saved as XML files which means it’s not a whole lot of work to parse them and use them. Since I was on a streak of using other people’s work, I went out in search of XNA GS code to use the level files.

My search started at the Tiled wiki which lead me to Kevin Gadd’s excellent website which pointed me to Stephen Belanger’s blog post expanding on Kevin’s code. I took a look at the code in excitement and was a bit let down. All of the XML parsing was done at runtime into very mutable objects with some design choices I didn’t quite agree with. So I decided that this is something to take into my own hands.

Starting at around 7:30 this morning (and ending just a few minutes ago), I feverishly wrote up a custom content pipeline extension project for parsing and processing the TMX files produced by Tiled and turning them into an easy to use, largely immutable structure. Why immutable? I’m personally a fan of closed systems until you need them open. Why would you make the width of the map mutable? What happens if I accidentally change that? So in my code, most variables are read only to stop me from shooting myself in the foot. Using C#’s ‘internal’ keyword, I’ve made it so most objects are only internally constructable with a lot of private members. This keeps all the data out of the hands of those meddling games (or people like me who accidentally change something and break it all).

The extensions are nice and minimal in what they require of you. Just drop a TMX file into your content project and you’re basically done. You will also need any tile sheets used by the map. You can place them anywhere in the content folder directory and you don’t need to add them to the content project; the map will build anything it needs and it also handles loading those in for you. The only parameter on the TMX processor is the directory where those sheets can be found, relative to the content project. In my project, I have a Maps directory in my content library with my TMX file and then a TileSets directory next to that with the sheets. Therefore my TMX files need to set their TileSet Directory values to “TileSets”.

Since I spent a good five hours creating this (which is likely orders of magnitude less than it would take for me to write something on par with Tiled), I decided to share with the community. I’m sure there are others out there who would want to use Tiled for their level editor and now you can have a great base on which to build up your own library for using those maps. The code is all MS-Pl so feel free to do with it what you will. I, of course, take no responsibility if the code manifests itself into the end of the world, a black hole, or your ex-girlfriend so use at your own risk. However I’ve yet to see any of those three things, so I think we’re good.

Enough blabbing. Links:

License
Libraries and Demo Project

Fill is an extension method I wrote because I’m sick of iterating over arrays to fill them in or alter values. Fill looks like this:

public static void Fill<T>(this T[,] array, Func<int, int, T, T> fill)
{
	int width = array.GetLength(0);
	int height = array.GetLength(1);

	for (int x = 0; x < width; x++)
	{
		for (int y = 0; y < height; y++)
		{
			array[x, y] = fill(x, y, array[x, y]);
		}
	}
}

You can see that it uses a Func to generate the new values. The Func takes in the x and y indices as well as the existing value at that location in the array, then returns the new value. This can be useful for a number of things. Let’s say I have an array of objects and I just used my Resize method to expand the array. I now have a bunch of null objects in there. I can easily use Fill to fix this:

myArray.Fill((x, y, existing) => existing ?? new MyObject());

How’s that for succinct? It’s also useful for new arrays that you want to populate:

int[,] myArray = new int[10, 10];
myArray.Fill((x, y, existing) => x * y);

So you can easily ignore the existing value and simply return a value to replace the current one.

I have a blast making extension methods even if they aren’t revolutionizing how I write code. I find it gives me a chance to just think up a problem and try to solve it in a clean and simple way. Anyone else find themselves doing this? What extension methods are you writing?

Anyway, here’s the method. Hope this can save someone else some time. Also if you spot anything wrong about this let me know.

public enum HorizontalClamp
{
	Left,
	Right,
	Center
}

public enum VerticalClamp
{
	Top,
	Bottom,
	Center
}

public static class ArrayExtensions
{
	public static T[,] Resize<T>(
		this T[,] array,
		int newWidth,
		int newHeight,
		HorizontalClamp xClamp,
		VerticalClamp yClamp)
	{
		// get the current width and height of the array
		int width = array.GetLength(0);
		int height = array.GetLength(1);

		// start/end from the old array
		int xStart = 0, xEnd = Math.Min(width, newWidth);
		int yStart = 0, yEnd = Math.Min(height, newHeight);

		// start/end for new array
		int targetX = 0;
		int targetY = 0;

		// figure out start, end, and target coordinates.
		// no check for left or top; those are defaults.

		if (xClamp == HorizontalClamp.Right)
		{
			xStart = Math.Max(width - newWidth, 0);
			xEnd = xStart + Math.Min(width, newWidth);
			targetX = newWidth - (width - xStart);
		}
		else if (xClamp == HorizontalClamp.Center)
		{
			xStart = Math.Max(width / 2 - newWidth / 2, 0);
			xEnd = xStart + Math.Min(width, newWidth);
			targetX = Math.Max(newWidth / 2 - width / 2, 0);
		}

		if (yClamp == VerticalClamp.Bottom)
		{
			yStart = Math.Max(height - newHeight, 0);
			yEnd = yStart + Math.Min(height, newHeight);
			targetY = newHeight - (height - yStart);
		}
		else if (yClamp == VerticalClamp.Center)
		{
			yStart = Math.Max(height / 2 - newHeight / 2, 0);
			yEnd = xStart + Math.Min(height, newHeight);
			targetY = Math.Max(newHeight / 2 - height / 2, 0);
		}

		// create our return value
		T[,] newArray = new T[newWidth, newHeight];

		// copy over the values from the old array to the new array
		for (int x1 = targetX, x2 = xStart; x2 < xEnd; x1++, x2++)
		{
			for (int y1 = targetY, y2 = yStart; y2 < yEnd; y1++, y2++)
			{
				newArray[x1, y1] = array[x2, y2];
			}
		}

		return newArray;
	}
}

First let’s do the techie thing and just look at the arguments of the tool:

C:\Users\Nick\Desktop>sspack
Missing required argument '/image'.
Missing required argument '/map'.
/image:<string>  Output file name for the image.
/map:<string>    Output file name for the map.
/mw:<int>        Maximum ouput width. Default:'4096'
/mh:<int>        Maximum ouput height. Default:'4096'
/pad:<int>       Padding between images. Default:'1'
/pow2            Ensures output dimensions are powers of two.
/sqr             Ensures output is square.
/r               Searches subdirectories of any input directories.
/il:<string>     Path(s) to file(s) listing the images to build.
<input>          Images to pack.

Those first two lines are unfortunately a bit misleading but the library I used for parsing command line arguments didn’t have complex logic. You technically are required to have image and map but you also must have something for either il or the input images. Most of the arguments make sense but the last few may trip people up. First the /r. If you have that flag, your searches for input will be recursive. So you could invoke this:

sspack /image:test.png /map:test.txt C:\Users\Nick\Desktop\MyImages\*.png

And it would find all PNG images in the MyImages folder. Note that the wildcard is really primitive and likely to break if you try to do anything with it in the middle of the word; it’s mainly there for finding a bunch of images in one folder. Anyway, if you were to add in the /r flag, it would find any PNG image in the MyImages folder and any subdirectories. That’s it.

Next the il flag. Since you may want to pack lots and lots of images (like the tool requires), you can make a file like this:

C:\Users\Nick\Desktop\MyImages\1.png
C:\Users\Nick\Desktop\MyImages\2.png
C:\Users\Nick\Desktop\MyImages\3.png
C:\Users\Nick\Desktop\MyImages\4.png

And invoke sspack with that file which it uses to find the files:

sspack /image:test.png /map:test.txt C:\Users\Nick\Desktop\ImagesToPack.txt

This is really nice because you could make any other tool to generate that file and kick off the build. This is actually all that the UI tool does. It simply builds up that list (which it saves in %AppData%\Sprite Sheet Packer) and uses all the UI to simply build up the command to launch a Process to run sspack. Now you can make your own UI tool or integrate sprite sheet packing into your build.

If you have any suggestions, feel free to let me know, but no promises. As you can see, I don’t really do rapid development on this project. Also feel free to submit patches on CodePlex if you have fixes for bugs or enhancements. That really helps since I can do a quick code review and put it up for everyone else to use.

It started off with something like this:

public class MyContentManager : ContentManager
{
	public MyContentManager(IServiceProvider services)
		: base(services, "Content")
	{
	}

	public override T Load<T>(string assetName)
	{
		T content = base.Load<T>(assetName);

		if (content is GraphicsResource)
		{
			(content as GraphicsResource).Name = assetName;
		}
		else if (content is SoundEffect)
		{
			(content as SoundEffect).Name = assetName;
		}

		return content;
	}
}

And that works. But what if I miss some content? What if I add my own custom type with a Name property? On my second go I decided to use a reflection based approach by just seeing if the object has a settable Name property:

public class MyContentManager : ContentManager
{
	public MyContentManager(IServiceProvider services)
		: base(services, "Content")
	{
	}

	public override T Load<T>(string assetName)
	{
		T content = base.Load<T>(assetName);

		PropertyInfo nameProperty = typeof(T).GetProperty("Name", typeof(string));
		if (nameProperty != null && nameProperty.CanWrite)
		{
			nameProperty.SetValue(content, assetName, null);
		}

		return content;
	}
}

And now any content that I load that has a Name property with a setter will get its name set. But I’m not quite done yet. Reflection isn’t the quickest thing in the world and I do like to use the ContentManager as a cache. This implementation will set the Name property each time the content is pulled from the ContentManager. While this is a good thing if you plan to change the name other places, it can be a performance hit. So I decided to add a dictionary to track what content has already been named and avoid naming things twice:

public class MyContentManager : ContentManager
{
	private readonly Dictionary<string, bool> namedContent = new Dictionary<string, bool>();

	public MyContentManager(IServiceProvider services)
		: base(services, "Content")
	{
	}

	public override T Load<T>(string assetName)
	{
		T content = base.Load<T>(assetName);

		bool named = false;
		if (!namedContent.TryGetValue(assetName, out named) || !named)
		{
			PropertyInfo nameProperty = typeof(T).GetProperty("Name", typeof(string));
			if (nameProperty != null && nameProperty.CanWrite)
			{
				nameProperty.SetValue(content, assetName, null);
			}
			namedContent.Add(assetName, true);
		}

		return content;
	}
}

And that’s where I’m at now. I fully realize that reflection is not going to be as fast as doing those casts, but since I’m also doing this caching of what items have been named, I’m only going to see that performance hit the first time I load an object and generally loading the object takes enough time that the extra cost of the reflection isn’t likely to be noticeable or an issue.

I’d be interested in hearing what others are doing to extend this class. Anyone else using a custom ContentManager for anything?

The GamerServicesComponent is a very minimal wrapper on top of the GamerServicesDispatcher. If we avoid using the GamerServicesComponent in both games, we’ll be fine. I’m personally moving away from using the component entirely, but you can keep using it in the real game and just use the dispatcher directly in the second.

Basically what you’ll do in your exception game is simply initialize the dispatcher directly if it needs to by calling Initialize and setting the window handle.

protected override void Initialize()
{
	if (!GamerServicesDispatcher.IsInitialized)
	{
		GamerServicesDispatcher.Initialize(Services);
	}
	GamerServicesDispatcher.WindowHandle = Window.Handle;
	base.Initialize();
}

And then just remember to Update the dispatcher each frame:

protected override void Update(GameTime gameTime)
{
	GamerServicesDispatcher.Update();
	// update other stuff
	base.Update(gameTime);
}

And there you go. No more need to make your GamerServicesComponent a static property or rely on that bug in the Game class. Much better.

1) Scale each sprite individually when drawing. Pros: easy initially. Cons: adds a lot of redundant code since the scale will likely not change during runtime.
2) Scale each sprite during editing. Pros: easy to do. Cons: have to remember to scale each sprite for the game, but keep a low-res copy for any other editing.
3) Scale during build time. Pros: awesome. Cons: none?

As you can guess by the title of the post, I went with #3. I figured this would let me still draw and save each sprite as tiny little images (tiles are currently 10×10 and the ninja just slightly larger) and still have them nice and large in the game. I’ll now share some code with you in case this is something you’d want to do.

First I created a new content pipeline extension project and added a reference in my game’s content project. Next I added a basic class that will define any constants I might need as time moves on. For now, it’s just one:

public static class Constants
{
	public const int Scale = 4;
}

Currently I’m scaling everything up 4x, but this lets me change one number and instantly get the game at a new scale.

Next I wrote up a quick and dirty texture importer. Since I didn’t feel like dealing with initializing D3D like the standard XNA TextureImporter class, I added a reference to System.Drawing and just used those APIs instead. Ultimately this is a pretty basic class. We load a bitmap and then copy over the pixels into a new PixelBitmapContent object which we then use as the first item in the mipmap chain.

[ContentImporter(DisplayName = "Texture - Ninja!")]
public class NinjaTextureImporter : ContentImporter<TextureContent>
{
	public override TextureContent Import(string filename, ContentImporterContext context)
	{
		Bitmap bitmap = Bitmap.FromFile(filename) as Bitmap;

		// XColor is an alias for Microsoft.Xna.Framework.Graphics.Color
		PixelBitmapContent<XColor> bitmapContent = new PixelBitmapContent<XColor>(
			bitmap.Width * Constants.Scale,
			bitmap.Height * Constants.Scale);

		for (int x = 0; x < bitmap.Width; x++)
		{
			for (int y = 0; y < bitmap.Height; y++)
			{
				// DColor is an alias for System.Drawing.Color
				DColor pixel = bitmap.GetPixel(x, y);
				XColor xPixel = new XColor(pixel.R, pixel.G, pixel.B, pixel.A);

				for (int x2 = x * Constants.Scale; x2 < (x + 1) * Constants.Scale; x2++)
				{
					for (int y2 = y * Constants.Scale; y2 < (y + 1) * Constants.Scale; y2++)
					{
						bitmapContent.SetPixel(x2, y2, xPixel);
					}
				}
			}
		}

		Texture2DContent texture = new Texture2DContent();
		texture.Faces[0] = new MipmapChain { bitmapContent };
		return texture;
	}
}

And there you go. Head back to the game content, choose this importer for my sprites, and like magic all of my sprites are scaled up for me. And since I’m handling the scaling, it’s all done with no interpolation so my pixels are nice and crisp.

The nice corollary to this experiment is that now I (and you for reading this post) know how to make a texture importer, meaning that the possibilities are endless. You could start loading in any image format supported by System.Drawing or use any other imaging system. As long as you can pack those into the PixelBitmapContent, you’re good to go.

Now that you have at least a basic idea of how this works, let’s talk about how we can use this to do fun things. First let’s talk about using it for scripting. A common scenario for scripts are to be able to execute, pause a bit, and continue executing. For instance, your characters says something, pauses, and then says something more. Traditionally you’d use some sort of state management to track this process and handle all the updates. With ‘yield’, we can actually create an interesting array of ways to implement scripting into our game in a way that, visually, looks like exactly how we’d want to write scripts.

First we define a delegate for our scripts:

public delegate IEnumerator<float> Script();

Next we create a ScriptEngine class to handle all the logic of update a script, sleeping, and so forth. I’ll just toss in my script engine (with comments) so you can see how I implemented things:

// handles a set of scripts
public class ScriptEngine : GameComponent
{
	// the currently executing scripts
	private readonly List<ScriptState> scripts = new List<ScriptState>();

	public ScriptEngine(Game game)
		: base(game)
	{
	}

	public void ExecuteScript(Script script)
	{
		// wrap the script in our state
		ScriptState scriptState = new ScriptState(script);

		// the script may complete in one go
		scriptState.Execute(null);

		// if not, add it to our list
		if (!scriptState.IsComplete)
		{
			scripts.Add(scriptState);
		}
	}

	public override void Update(GameTime gameTime)
	{
		// execute all of our scripts
		foreach (var scriptState in scripts)
		{
			scriptState.Execute(gameTime);
		}

		// remove any completed scripts
		scripts.RemoveAll(s => s.IsComplete);
	}

	// a wrapper over the Script delegate to manage sleeping and the enumerator
	private class ScriptState
	{
		private float sleepLength;
		private Script script;
		private IEnumerator<float> scriptEnumerator;

		// the script is complete when we null out our script
		public bool IsComplete { get { return script == null; } }

		public ScriptState(Script script)
		{
			if (script == null)
				throw new ArgumentNullException("script");

			this.script = script;
		}

		// executes the script until the next sleep time.
		public void Execute(GameTime gameTime)
		{
			// the first run needs to get the script enumerator and first sleepLength (if any)
			if (scriptEnumerator == null)
			{
				scriptEnumerator = script();
				sleepLength = scriptEnumerator.Current;
			}

			// if we are sleeping, subtract the time from our timer
			if (sleepLength > 0 && gameTime != null)
			{
				sleepLength -= (float)gameTime.ElapsedGameTime.TotalSeconds;
			}

			// if the sleep timer is done...
			if (sleepLength <= 0)
			{
				bool unfinished = false;
				do
				{
					// MoveNext continues execution of our script until the end or until
					// the next yield return. MoveNext returns true if a yield return is
					// hit or false if the method is complete.
					unfinished = scriptEnumerator.MoveNext();
					sleepLength = scriptEnumerator.Current;

					// as soon as we are finished or we need to sleep, we exit our loop
				} while (sleepLength <= 0 && unfinished);

				// if the script is not unfinished (i.e. is complete), we null out our
				// script and enumerator which flags the script as IsComplete and lets
				// the engine clean it up.
				if (!unfinished)
				{
					script = null;
					scriptEnumerator = null;
				}
			}
		}
	}
}

You can see that I implemented my engine as a game component to make life a little easier. I also wrap each script into a nice little state object that tracks sleeping and the enumerator.

Now let’s see a little test game:

public class Game1 : Game
{
	ScriptEngine engine;

	public Game1()
	{
		new GraphicsDeviceManager(this);
		Content.RootDirectory = "Content";
		Components.Add(engine = new ScriptEngine(this));
	}

	protected override void LoadContent()
	{
		engine.ExecuteScript(TestScript);
	}

	private IEnumerator<float> TestScript()
	{
		Console.WriteLine("Hello... (wait for it)");
		yield return 3f;
		Console.WriteLine("World!");
	}

	protected override void Draw(GameTime gameTime)
	{
		GraphicsDevice.Clear(Color.CornflowerBlue);
		base.Draw(gameTime);
	}
}

When run you’ll see “Hello… (wait for it)” printed to the debug and then, three seconds later, “World!” is printed out. The yield return does the magic of handling our enumerator for us because the compiler really is building a whole state machine type class over that TestScript method. Then our ScriptEngine and ScriptState classes use an IEnumerator to track the enumerator. To get the enumerator, we call the delegate like normal. From there, we simply call MoveNext on the IEnumerator which will start execution at the last yield return statement.

I know this is a bit complex (especially if you dig in to the details of the compiler plumbing that makes it all work), but it’s still something you can play with. I find it nice because our TestScript method looks, for the most part, like what we’d want to script. Once we have this engine, we can tuck it away and not deal with it, making our life much easier for making scripts in our game. We could, of course, extend the scripting to not just return a float value. You could return any type you wanted to get information back to the engine. Maybe a custom type that has a sleep amount, other scripts to invoke before continuing, or any number of things. It’s really quite powerful.