XNA Diaries : XNA

XNAExtras update

garykac — Fri, 01 Dec 2006 18:00:00 GMT

This is a minor update:

Beta2 update (ContentManager)
Minor bug fix with TextBoxes not deleting their backgrounds.
Initial stab at compiling for the 360 (by #ifdef'ing references to Texture2D.FromFile so that they can be removed easily)
Temporarily remove CollisionDemo since it's acting up under beta2 (there are reports that it was acting up under beta1, but I was unable to repro them...) This demo will come back once these bugs are fixed.

BMFontGen update (1119)

garykac — Sun, 19 Nov 2006 22:11:00 GMT

I had a request to add an option to expand each glyph with padding pixels, and I'm finally getting around to doing it.

To add n pixels of padding around each glyph, you can now use the glyph pad option: -gpad n. If you only want padding in the x or y direction, then you can use -gpadx or -gpady. Adding padding will not affect how the font is displayed, except that additional transparent "padding" pixels will be copied.

In general, you don't need to use these options, but they can be useful if you intend to manipulate the font bitmap in such a way that the glyphs expand in size. If you do not intend to edit the font bitmap, then you don't need to use these options.

BitmapFont update for beta2 (Finally!)

garykac — Sun, 19 Nov 2006 02:33:00 GMT

As you've probably surmised from the last post, I seem to be somewhat loose in my interpretation of "later this week".

Attached is an updated version (finally!) of the BitmapFont.cs class along with its corresponding demonstration project.

Note that this update only covers the BitmapFont class, not the entire XNA Extras package. I hope to have an updated version of all the XNA Extras classes sometime "later this week"...

XNA Extras and Beta2

garykac — Thu, 02 Nov 2006 21:11:00 GMT

This is a heads-up that the current release of XNA Extras requires some changes before it will work with the newly released XNA Game Studio Express Beta 2.

I'm hoping to find some time later this week (yes, I know it's already late in the week) and get an updated version up this weekend. Sorry about the delay!

Colliding sprites in XNAExtras

garykac — Sun, 24 Sep 2006 18:00:00 GMT

The latest release of XNAExtras added support for sprite collisions, and allows the collision detection to be either bounding box (bbox) or pixel based. This is settable per sprite - some sprites can use bboxes and others can use pixels. The sprites will collide appropriately with each other even if they can't agree on how to do it.

Here's a simple tutorial for how to use the collision detection built into XNAExtras:

(1) Create an XSpriteManager.

m_mgrSprites = new XSpriteManager();

(2) Create an XSprite.

m_mgrSprites.AddTexture("tex", "texture.png", 64, 64);
XSprite s1 = m_mgrSprites.AddSprite("ball1", "tex");

(3) Create another XSprite so that you have something to collide with.

XSprite s2 = m_mgrSprites.AddSprite("ball2", "tex");

(4) Enable collisions for these two sprites. For bounding box collisions, use:

s1.SetCollideable(true);
s2.SetCollideable(true);

If you want pixel based collisions, use:

s1.SetCollideable(true, XSpriteManager.CollisionFlags.Pixel, 0x40);
s2.SetCollideable(true, XSpriteManager.CollisionFlags.Pixel, 0x40);

where 0x40 is the alpha value of the sprite that defines the collideable part of the sprite - any alpha value >= this value will be added to the sprite's collision mask.

(5) In your Update method, after you've moved your sprites around a bit, you can check for collisions using CheckSpriteCollisions:

List<XSpriteManager.SpriteCollision> aColl = m_mgrSprites.CheckSpriteCollisions();

This method returns a list of collisions that were detected. It returns null if there are no collisions.

(6) To handle collisions, simply walk the list of collisions and do whatever you feel is appropriate.

  if (aColl != null)
  {
    // handle the collisions
    foreach (XSpriteManager.SpriteCollision c in aColl)
    {
     // if colliding with another sprite...
     if (c.Type == XSpriteManager.CollisionType.Sprite)
     {
        // handle collision between c.Sprite and c.Sprite2
      }
    }
}

A working demo of collision detection is given in the CollisionDemo project included with the XNAExtras download.

XNAExtras build 0923 release

garykac — Sun, 24 Sep 2006 09:50:00 GMT

Major addition for this version: collision detection has been added to XSpriteManager. Both bounding box and pixel based (mix-n-match sprites of different types). Also boundary collisions. These are demoed in the bouncy CollisionDemo example:

From the release notes:

(BMFontGen) Fixed bug where including undefined chars in your font -range would cause a crash
(BitmapFont) Changed loading embedded resources - now the resource name is specified in the same format as file-based resources
(BitmapFont) Fixed bug where font files wouldn't be found unless they were in a subdirectory
(TextBox) Added accessors for the text string
(XSpriteManager) Changed default FPS to 60
(XSpriteManager) Added support for collisions
(TexturePool) *Really* fixed bug in AddTexture(string,Color) where the texture wasn't being created if the GraphicsDevice already existed - the fix got lost for the last release

Thanks to redwyre, David Zakar (DMZ), Martin Szinger and Matt Moore for comments/suggestions.

You can download the 0923 build of XNAExtras here.

Separating your code and data

garykac — Sun, 17 Sep 2006 20:15:00 GMT

In the previous post, I talked about creating border art and using it in your game. One problem with the approach shown is that the description of the texture contents - the sprite locations and boundaries - is stored in the game code. This means that if you want to update the border artwork for a future version of your game, you need to make parallel code modifications and then recompile.

A nicer way of doing this is to keep the description of the texture contents in a file alongside the texture. This would allow you to change the appearance of your game without needing to recompile - useful if you're programming by yourself, and crucial if you're developing the game where someone else is helping out with the artwork.

This approach is supported in the XNAExtras class library by allowing texture and sprite information to be loaded from an XML file. A simple descriptor file is:

<?xml version="1.0" encoding="UTF-8" ?>
<texinfo>
  <textures>
   <texture name="whiteball" src="white ball.png" size="64x64" />
  </textures>
  <sprites>
   <sprite name="red" tex="whiteball" pos="50,50" tint="#ff0000" />
  </sprites>
</texinfo>

This XML file creates a single sprite based on the "white ball.png" texture, adds a red tint and positions the sprite at (50,50). While perhaps a bit of overkill for this simple texture, once you start having multiple sprites in the same texture (as you should), these descriptor files can be quite useful.

To load a texture definition file into your game, simply use:

sprites.LoadSprites("spriteinfo.xml");

Where sprites is your game's XSpriteManager. If you want to interact with this sprite in your code (for example, to move it around the screen), you can ask the XSpriteManager to return a reference to it using:

XSprite s = sprites.GetSprite("red") as XSprite;

You can find working examples of LoadSprites in the TextBoxDemo and XSpritesDemo projects (included with the XNAExtras download).

To assist with creating these "texture information" files, I've created an XML Schema Definition (XSD) file that you can use to perform basic validation. This XSD file (TextureInfo.xsd) is included as part of XNAExtras and is located in the "XML Schema" directory. To use it, copy the XSD file into the same directory as your XML file and replace your

tag at the beginning of the file with the following mess:

Now if you open your XML file in a application that supports XSD (like Visual C# Express), you'll get validation squiggles. It doesn't perform a complete validation of the file, but it will catch most basic errors/typos. If you want to keep the XSD files in a separate directory, replace "textureinfo.xsd" in the "xsi:schemaLocation" attribute with a path+filename.

Beyond making your code more manageable, there's another aspect to this code/data separation that can benefit your work: Your art assets become more shareable with others. If you're thinking "Why would I want to make it easier for people to steal my art?", try to step back and think about the XNA gaming community as a whole.

While it means that others can more easily make use of your assets, it also means that you can more easily make use of the assets that others create. This sharing is crucial to developing and maintaining a thriving game development community. Yes, some people will "steal" and not give credit, but that sort of thing will happen no matter what you do (unless you don't release your game at all).

As mentioned earlier, exposing your art like this makes it much easier to be replaced/updated. While this is obviously good for you, it can also enable a modding community to build up around your game - people (even those with no programminng experience) can now take your game and make new skins without messing with the code. How cool would that be?

Creating UI border elements in XNA

garykac — Sun, 17 Sep 2006 08:30:00 GMT

The XNAExtras.Border class provides a general border mechanism for UI elements. While currently only the XNAExtras.TextBox class makes use of it, future releases of XNAExtras will include Menus and perhaps some other elements that will be built on top of Borders.

When creating borders, you can use the default border graphics (e.g., those that come with the TextBox demo) or you can create your own custom graphics. This post describes what you need to do to create and use your own custom borders.

As an example, we'll make use of one of the borders included in the TextBoxDemo sample project. This project is part of the XNAExtras package, which you can download from here if you don't already have it.

The border image that we'll be examining is "border.png" - a simple 25x33 image that contains a single border. It's located in the "XNA Samples\TextBoxDemo\Content" folder and is shown in the following figure (with some markup denoting the different regions of the border image):

When designing a border image, you should think of it as 9 separate regions that need to blend together smoothly: the four corners, four edges and the center.

The four corners are typically the largest and most distinctive part of any border. The corners are never stretched or scaled when they are drawn.
The edges are drawn between two neighboring corners and stretch vertically or horizontally to make the border the correct size. As can be seen in "border.png", the edges do not need to be more than a single pixel wide or high.
The center is typically a single pixel that defines the background color for the border. The center is stretched both horizontally and vertically to match the border size.

So, now that you have a border image, what do you do with it? You can use the following code to create and display your border.

First, set up your project. This process is the same for all XNA projects that use XNAExtras.

Create a new "Windows Game (XNA)" project and add all of the XNAExtras source files to it.
Add a reference to System.Xml. To do this, right-click on the References folder in the Solution Explorer for your project. Select "Add Reference...". From the ".NET" tab, select "System.Xml" and then click the "Add" button.
Add "using XNAExtras;" to the top of your source files with the other using statements.

Now you can start adding code to the main game class. Add the following member variable to your game class:

private XSpriteManager m_sprites;

Add the following initialization code:

// create a sprite manager to manage the drawing
m_sprites = new XSpriteManager();

// load the texture that contains the border
m_sprites.AddTexture("tx_border", "border.png", 25, 33);

   // define a border type from the texture
   // (use the default settings to init the border)
   m_sprites.DefineBorder("border_def", "tx_border");

   // instantiate the border and set its size
   Border b = m_sprites.AddBorder("border test", "border_def");
   b.SetDestRect(50,50,100,100);

Add the following initialization code after the call to InitializeComponent (or place it wherever you handle device resets):

m_sprites.Reset(graphics.GraphicsDevice);

And finally, add the following to your Draw routine (between your BeginScene and your EndScene):

m_sprites.Draw();

Compile and run and you'll see a empty border on your screen. You'll need to have copied the "border.png" file into the same directory as the EXE or else the texture won't be found.

Note that the code given above uses the default parameters to define the border, which works in this example because the texture contained only this one border sprite. The left, top, right and bottom values for the border were also automatically determined by taking the image size and dividing it in half and assuming that the center was 1x1 pixels in size.

To have more control over the border creation parameters, you need to define the border using a Border.CreationParameters struct:

   Border.CreationParameters bcp = new Border.CreationParameters();
   bcp.strTexName = "tx_border";// name of texture with border
   bcp.SetLocation(0, 0);       // location of border image in texture
   bcp.SetSize(25, 33);         // size of border image
   bcp.SetEdges(12, 16, 12, 16);// size of LTRB edges in texture
   bcp.SetOrigin(4, 8);         // border position adjustment
   m_sprites.DefineBorder("border_def", bcp);

As a final comment about borders, note the SetOrigin line in the above example. This parameter is used to adjust the position of the border around the rectangle. Compare the borders in the next image:

The left column shows the border and the right column shows the same border with the content rectangle blanked out to make it easier to see. All of the rectangles are 100x100, but the bottom row used the SetOrigin method shown above to pull the border closer to the rectangle.

XNAExtras build 0916 release

garykac — Sat, 16 Sep 2006 20:01:00 GMT

This release includes a bunch of small enhancements and bug fixes. The only major class addition is XSpriteGroup, which allows you to manipulate a group of sprites as a single unit.

From the release notes:

   (XML Schema) Added XML schema definition (XSD) files for bitmap and texture files
   (BMFontGen) Fixed bug where custom glyphs couldn't replace chars that didn't exist in font
   (BitmapFont) Added Dispose method
   (BitmapFont) Fixed TextBox to format the string only once
   (BitmapFont) Allow fonts to be loaded from embedded resources
   (BitmapFont/XSpriteManager) Changed GetXMLAttribute to not throw exceptions
   (XSpriteManager) Changed sprites to sort by order of creation when at the same depth
   (XSpriteBase) Added Visible property
   (XSprite) Added SetTexture method
   (XSprite) Expose sprite alpha value directly
   (TexturePool) Fixed bug in AddTexture(string,Color) where the texture wasn't being created if the GraphicsDevice already existed

Thanks to everyone (and especially to David Zakar (DMZ), redwyre and Martin Szinger) who took the time to send comments, bug reports and feature requests.

[Update: Oops! Björn points out that I forgot the link to the updated version. The link to the latest version is here.]

"But I don't want to have to worry about sprite depths..."

garykac — Fri, 15 Sep 2006 02:34:00 GMT

Well, you don't have to really. Or maybe you're already dealing with depth and you don't realize it.

To recap: There are two ways of controlling sprite "depth". The first is to use the SpriteBatch.Draw methods that allow a layerDepth parameter. The second is just to draw your sprites at the same depth, but from back to front.

The layerDepth approach is nice when you have lots of sprites at different depths, or when they're changing depths regularly. You give each sprite a depth and then forget about it. This allows you to draw your objects ordered by type (first the map, then the player, then the objects, ...) as opposed to by how far they are into the screen.

The simpler approach of drawing from back to front is seen when you draw your background first, then your objects and then finish up with your overlay and UI elements. Basically, you've hardcoded your back-to-front sort order in your code. Not very flexible perhaps, but perfectly appropriate for a large number of games. And you don't have to worry about depth at all - beyond the coarse background/objects/overlay distinction.

XSpriteManager supports both approaches. If you give it a depth, the right thing will happen - and the sprites will be kept in sorted order so that they render quickly. But if you don't want to set the depth, you can just add sprites and they will be rendered in the order that they were created. By default, XSprites are drawn at depth=0.0 (which is closest to the screen).

The motivation for all this is the game that I'm working on (big surprise there, eh?). It's a basic tile-based isometric RPG which had a definite need for a class to manage all the sprites. To handle the map tiles, I wanted to put each row at a different depth and then place the player (and NPCs) at depths between the rows.

I'll try to talk more about this game once I get a few more basic classes finished up.

XNAExtras : tools and classes for XNA

garykac — Mon, 11 Sep 2006 08:40:00 GMT

In order to simplify releases, I'm collecting all of my XNA tools, classes and sample code into a single XNAExtras package. You can find a link to the latest version of XNAExtras here.

This first XNAExtras release contains updated versions of BMFontGen and BitmapFont:

BMFontGen :

Added font face name, size and style info to XML font descriptor file.
Added option to prevent custom glyphs from being tinted when drawing colored text.
Fixed crash when cancelling the font select dialog (oops!).
Changed code to prevent substitute fonts being used when the requested font is unavailable.
Changed "origin" attribute in font XML files to "loc" (location) since this is a better description and is more consistent with usage in sprite/texture XML files. Fonts created with "origin" attribute are still supported.
Removed support for ClearType anti-aliasing.

BitmapFont :

Fixed path problem whereby font image files weren't found if the font was in a subdirectory.
Changed GlyphInfo struct (in BitmapFont) to use bytes/sbytes instead of ints.
Added support for new features in XML font file.
Added TextBox method to format left, center or right-aligned text in a rectangle.
Added Save/RestoreState methods to save and restore the font rendering state.

Thanks to David Wyand, Thijs Kruithof (Gleoi), Jim Welch and Roger Bocksnick for their comments/suggestions.

In addition, a few extra classes (and associated demos) have been added:

TextBox : Class to manage more complex text rendering, includes support for rendering text borders to create UI elements. Makes use of BitmapFont and Border. (TextBox.cs)

Border : Class to draw sprite-based borders around rectangles. Makes use of XSprite. (Border.cs)

XSprite : Classes to manage sprites. Supports shared textures, animated sprites, different framerates for each sprite, keeps sprites sorted by depth (so that transparency works correctly) and allows sprites to be loaded from an XML descriptor file. (XSprite.cs, XSpriteBase.cs, XSpriteManager.cs, TexturePool.cs)

Note that I wasn't originally intending to include the XSprite classes with this release because there are still a few features that I wanted to add and I still need to finish the sprite demo to make it more interesting. However, because the Border class relies on it, you get to see a preview of these classes.

I'll probably talk about these classes and demos more in upcoming posts. As always, comments, suggestions and bug reports are welcome.

The cost of SpriteBlendMode.AlphaBlend and the SpriteSortOptions

garykac — Sun, 10 Sep 2006 21:11:00 GMT

The SpriteBatch.Begin method has a couple of parameters that control how the sprites are rendered on the screen. Most people are aware of SpriteBlendMode.AlphaBlend, but for transparency to work correctly, you need to ensure that your sprites are being drawn back to front.

Now, if you're just using transparency to knock the background out of an image, then you might not notice any problems - even if you draw your sprites in the wrong order. In this case the effect is localized to the edges of your objects where they're less likely to draw attention.

But if you have large regions of transparency, the impact of not drawing back to front can be quite noticeable.

The above image shows what happens when 5 circles (white with alpha=68%) are drawn in the wrong order and the correct order. On the left side, the front circle is drawn first so it is blended with the background image (resulting in the blue outline) and the depth buffer prevents the back circles from being drawn behind the front circle. The right side shows the desired effect, where the front circle is drawn last and is blended correctly with the back circles.

This is where SpriteSortOptions comes into the picture (so to speak). With this option, you draw your sprites in any order (but at the correct depth) and the right thing will happen.

So the next questions are : How expensive is it to have the SpriteBatch class manage our sprite sort order? Is it better to sort the sprites once (in your app) and then draw them in the correct order?

To test this, I wrote a simple app that creates a bunch of 64x64 sprites and places them at random depths and locations. I then plotted the FPS as I increased the number of sprites:

The lines in this graph are for SpriteBlendMode.None (in red), SpriteBlendMode.AlphaBlend (in green), and AlphaBlend with SpriteSortOptions.BackToFront (in blue). The gray line at the top is for SpriteSortOptions.FrontToBack, which is (surprisingly) faster than SpriteBlendMode.None but blends the sprites incorrectly. [Reminder: these data points are from the beta XNA release]

If you sort your own sprites and draw them in the correct order, then you get to use the green line. For large numbers (> 500) of sprites, this can be a big win.

Having SpriteBatch sort your sprites for you limits you to around 400 sprites (64x64) before it starts to impact the framerate. If you're content with 30 fps, then you're good up to 1000 sprites.

Of course, if you don't mind having your sprites blended incorrectly, you can have even more.

[Note that the beta XNA release sorts the sprites front to back when you specify SpriteSortOptions.BackToFront. You need to get the bizarro-world version of XNA to have BackToFront actually mean back to front. Or wait for the release version, I imagine. ^_^

Fortunately, FrontToBack in the beta means back to front, so you can use that as a workaround. In this post, I've applied the workaround so when I say "BackToFront" I'm really using SpriteSortOptions.FrontToBack (and vice versa).]

360 Controller Demo

garykac — Fri, 01 Sep 2006 19:00:00 GMT

Don't you hate it when you have a little demo that you're thinking of releasing and someone comes around and and does basically what you wanted to do, only better? How 'bout if it's a whole lot better?

Well, Paul just did that to me with his 360 Controller Test sample app. He took his original app (which used C#, MDX, XInput & Windows Forms) and converted it to XNA in a few hours. It gives graphic feedback of the controller state and makes it rumble when the triggers are pulled.

On the upside, it means that I can focus on other things instead of polishing and wrapping up my code...

Creating and using bitmap fonts in XNA

garykac — Thu, 31 Aug 2006 06:00:00 GMT

As mentioned in a previous post, there is a clear need for a bitmap font generator that provides proper Unicode support.

To address this need, I created BMFontGen.exe. This program can generate a bitmap font from any of the fonts currently installed on your system and it provides a variety of options for controlling which glyphs get placed in the font and how they appear. More details about the tool (including a download link) are given in this document, but for our purposes it suffices to know that BMFontGen takes a font name and a font size and produces an XML file (containing the font description) and a collection of PNG files (that contain the glyph bitmaps).

To use these fonts in an XNA game, you need some code that can load these files and let you draw a string of text on the screen. To fill this role, I created the BitmapFont class. This class handles the font loading and exposes a set of DrawString methods that do what you would expect them to do.

To demonstrate the class in action, I've created a simple demo app (attached to this post - see link at bottom) which I've cleverly named "BitmapFontDemo". Here is a screenshot from the app that shows off some of the capabilities of the font renderer.

The BitmapFont class is intended to provide basic text rendering services only, so don't expect it to handle linebreaks or format text in a rectangle or provide any other advanced text options. However, I'll be adding functionality to it as time goes on, and I also intend to release other game support classes that build upon the base functionality provided by BitmapFont.

This is the first release for this tool, so let me know if you find this useful or if you think there're features missing. I'm curious to see games that make use of these fonts (even if I can't read them ^_^).

Finally...

garykac — Wed, 30 Aug 2006 18:26:00 GMT

Microsoft XNA Game Studio Express (Beta) is now available!