Monday, August 23, 2010

A Developer Game Console plugin for XNA Games

This is a project I was recently working on and it's a developer console for XNA games. It can easily be added to any XNA game and modified


Quick Start

Add the compiled XnaGameConsole dll as a reference and initialize the GameConsole:

GameConsole console = new GameConsole(this, spriteBatch); // where `this` is your `Game` class

By default, the console is opened with the ` (OemTilde key) but this, amongst other settings, can be changed via the Options property.

You can then add commands and customize the console.


Source and Downloads

You can checkout a copy of the source at the Google Code page:

The compiled dll of XNAGameConsole can also be downloaded from here:


Clipboard Support

The console supports pasting via CTRL+V but this requires the game to be running in a Single Threaded Apartment.

To do this, add the STAThread attribute to the entry point of your game:
static class Program
    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    static void Main(string[] args)
        using (Game1 game = new Game1())

Adding Commands

There are currently 2 ways how to add custom commands to the console:

1. Using IConsoleCommand

Console commands can be built via the IConsoleCommand interface.
The following is an example of a command:
class MovePlayerCommand:IConsoleCommand
    public string Name
        get { return "move"; }

    public string Description
        get { return "Moves the player"; }

    private Player player;
    public MovePlayerCommand(Player player)
        this.player = player;

    public string Execute(string[] arguments)
        var newPosition = new Vector2(float.Parse(arguments[0]), float.Parse(arguments[1]));
        player.Position = newPosition;
        return "Moved player to " + newPosition;

Such a command can then be added to the console like such:
console.AddCommand(new MovePlayerCommand(player));

2. Via a Func<string, string>

Commands can also be added without using IConsoleCommand, like the following:

console.AddCommand("rotRad", a =>
                                     var angle = float.Parse(a[0]);
                                     player.Angle = angle;
                                     return String.Format("Rotated the player to {0} radians", angle);
                                 }, "Rotates the player");
The advantage of adding a command like this is that in the Func<> you have access to the variables outside the closure.

Writing to the Console

You can dynamically write to the console via the WriteLine method:
console.WriteLine("Writing from the code");

Console Options

The console can be customized with a number of options. These options can be accessed through the GameConsoleOptions class.

To set the initial options, instantiate a new GameConsoleOptions class, set your desired options and pass it through one of the GameConsole's overloaded constructors:

GameConsoleOptions options = new GameConsoleOptions { FontColor = Color.Crimson, Prompt = ">", BackgroundColor = Color.DarkGreen };
GameConsole console = new GameConsole(this, spriteBatch, options);

The options can also be changed dynamically through the Options property of GameConsole:
console.Options.Height = 200;

The following are the current available options:

ToggleKey (Microsoft.Xna.Framework.Input.Keys)

Gets or sets the key that is used to show / hide the console

Default: Keys.OemTilde

BackgroundColor (Microsoft.Xna.Framework.Graphics.Color)

Gets or sets the color for the background of the console

Default: new Color(0, 0, 0, 125)

FontColor (Microsoft.Xna.Framework.Graphics.Color)

Sets the same specified color for all of the following properties:
  • BufferColor
  • PastCommandColor
  • PastCommandOutputColor
  • PromptColor
  • CursorColor

Default: Color.White

BufferColor (Microsoft.Xna.Framework.Graphics.Color)

Gets or sets the color of the text in the buffer

Default: Color.White

PastCommandColor (Microsoft.Xna.Framework.Graphics.Color)

Gets or sets the color of the past commands

Default: Color.White

PastCommandOutputColor (Microsoft.Xna.Framework.Graphics.Color)

Gets or sets the color of the past command outputs

Default: Color.White

PromptColor (Microsoft.Xna.Framework.Graphics.Color)

Gets or sets the color of the prompt

Default: Color.White

CursorColor (Microsoft.Xna.Framework.Graphics.Color)

Gets or sets the color of the cursor

Default: Color.White

AnimationSpeed (float)

Gets or sets the speed by which the console opens/closes

Default: 1

CursorBlinkSpeed (float)

Gets or sets the speed by which the cursor blinks

Default: 0.5f

Height (int)

Gets or sets the height of the console, in pixels

Default: 300

Prompt (string)

Gets or sets the prompt

Default: $

Cursor (char)

Gets or sets the cursor display character

Default: _

Padding (int)

Gets or sets the padding, in pixels, between the border of the console and the inner text

Default: 30

Margin (int)

Gets or sets the margin, in pixels, between the left and right side of the screen to the console border

Default: 30

OpenOnWrite (bool)

Gets or sets a boolean value that indicates whether to open the console, if it's closed, when writing to the console

Default: true

Font (Microsoft.Xna.Framework.Graphics.SpriteFont)

Gets or sets the font that is used in the console

Default: Consolas, Regular, 11pt

Friday, August 20, 2010

Drawing lines and rectangles in XNA

In my last project, I needed a way to draw a grid with lines in XNA but I had some trouble in actually finding a way how to draw a simple line.  In this post, I will explain how to accomplish this.

First, create a new Texture2D with size: 1x1

Texture2D pixel = new Texture2D(GraphicsDevice, 1, 1, 1, TextureUsage.None, SurfaceFormat.Color);

You can access the GraphicsDevice from your Game (game.GraphicsDevice)

We then set the colour of this 1x1 texture to White. This allows us to choose what colour it should be drawn later on.

pixel.SetData(new[] { Color.White });

Now we can draw this texture by specifying a Rectangle holding the position and size:

spriteBatch.Draw(pixel, new Rectangle(10, 20, 100, 50), Color.DarkGreen);

The above snippet will draw a dark green 100x50 rectangle at {X: 10, Y: 20}

Saturday, August 14, 2010

Handling single keyboard strokes in XNA

In a game, there are times where you need to handle single key strokes, rather than repeating ones. Examples are of a Pause key or a 'Press any key to start' scenario.

Unfortunately, XNA does not directly offer this functionality.

Therefore I wrote this very simple event-driven class that does exactly that:

using System;
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Input;

namespace XNASingleStroke
    public class SingleKeyStroke : GameComponent
        public event EventHandler<KeyDownEventArgs> KeyDown = delegate { };

        private int pressedKeys;
        public SingleKeyStroke(Game game) : base(game) { }

        public override void Update(GameTime gameTime)
            var pressed = Keyboard.GetState().GetPressedKeys();
            var keys = 0;
            foreach (var key in pressed)
                var num = 1 << (int)key;
                keys |= num;
                if ((pressedKeys & num) != num)
                    KeyDown(this, new KeyDownEventArgs(key));
            pressedKeys = keys;

And this is KeyDownEventArgs that's used in the event handler:

using System;
using Microsoft.Xna.Framework.Input;

namespace XNASingleStroke
    public class KeyDownEventArgs:EventArgs
        public Keys Key { get; set; }
        public KeyDownEventArgs(Keys key)
            Key = key;

Usage is also very simple:

protected override void Initialize()
    // ...
    SingleKeyStroke singleStroke = new SingleKeyStroke(this); //where 'this' is your Game
    singleStroke.KeyDown += (o, e) => {
        switch (e.Key)
            case Keys.Space:Console.WriteLine("Space was pressed"); break;
            case Keys.Enter:Console.WriteLine("Enter was pressed"); break;

Friday, August 6, 2010

A simple menu for a Gosu game in ruby

For The Lost Battle, I wrote a very simple menu system that would allow me to add in-game menus. This allowed me to instantiate a menu and then add items to it and let the menu take care of the drawing.

The menu also takes care of notifying me when an item has been clicked via a callback, and also offsets the position of the item on hover.

The following is the basic gist of how it can be used:

@menu = #instantiate the menu, passing the Window in the constructor

@menu.add_item(, "item.png", false), 100, 200, 1, lambda { self.close },, "item_hover.png", false))
@menu.add_item(, "item2.png", false), 100, 250, 1, lambda { puts "something" },, "item2_hover.png", false))

The arguments of add_item are the image showed when the item is in its normal state, the x position, y position, z-order, the callback that will be invoked when that item is clicked and finally an optional parameter of an image that is used when the item is hovered upon.

Then hook to the button_down event of your Window, and inform the menu that the mouse has been clicked:

def button_down (id)
    if id == Gosu::MsLeft then

Finally, just draw and update the menu in the hooked methods:

def update

def draw

I made a simple demo of this and you can download it from here.

The following is the source of the two aforementioned classes:

class Menu
    def initialize (window)
        @window = window
        @items =

    def add_item (image, x, y, z, callback, hover_image = nil)
        item =, image, x, y, z, callback, hover_image)
        @items << item

    def draw
        @items.each do |i|

    def update
        @items.each do |i|

    def clicked
        @items.each do |i|

class MenuItem
    def initialize (window, image, x, y, z, callback, hover_image = nil)
        @window = window
        @main_image = image
        @hover_image = hover_image
        @original_x = @x = x
        @original_y = @y = y
        @z = z
        @callback = callback
        @active_image = @main_image

    def draw
        @active_image.draw(@x, @y, @z)

    def update
        if is_mouse_hovering then
            if !@hover_image.nil? then
                @active_image = @hover_image

            @x = @original_x + HOVER_OFFSET
            @y = @original_y + HOVER_OFFSET
            @active_image = @main_image
            @x = @original_x
            @y = @original_y

    def is_mouse_hovering
        mx = @window.mouse_x
        my = @window.mouse_y

        (mx >= @x and my >= @y) and (mx <= @x + @active_image.width) and (my <= @y + @active_image.height)

    def clicked
        if is_mouse_hovering then

Note that both the code and the method in general can be greatly improved and refactored. Just take a look at the code and modify it as you see fit :)

The Lost Battle - a ruby multiplayer game with Gosu and Chipmunk

This is a game I recently built to learn ruby in conjunction with the Gosu game engine and the Chipmunk physics engine.



The source of the game can be found at it's google code page here:

You can checkout using Mercurial with: hg clone the-lost-battle


For the game to run, it requires the following:

Running the game

To launch the game, fire up your terminal, navigate to the game's directory and run main.rb with the ruby interpreter: ruby main.rb
Or ruby1.9 main.rb if you have multiple versions of ruby installed.

After you click start game on the main screen, you will see the player selection, similar to the second screenshot above. If you do not have any joysticks connected, you will only be shown 1 player slot and the game will be unable to start since it requires 1 < players <= 4. Therefore, with a single joystick connected, you will be able to play a 2 player player with the keyboard+mouse and the other player with the controller. Make sure that the joysticks are connected before you go into the player selection screen because the amount of player slots that the screen will display depends on the number of connected controllers.

Additional Notes

Joystick support
The game requires at least one joystick to be connected. Since I had very limited time in building this game, I only pre-set configuration for PS3 controllers. You can try and play it with other controllers but it's unlikely that the usable buttons will be comfortable to use, and the axis may not even be configured correctly.

If you want to use a different controller, you need to add a new configuration in the gamestate.rb file, similar to the PS3 one:
PS3_CONTROLLER  ={horizontal: 0, vertical: 1}, {:horizontal => 2, :vertical => 3}, 11, 9)
Then use your new configuration instead of PS3_CONTROLLER when adding a new player to the player list:
@player_list.add(, rand(window.width), rand(window.height), p.controller_type == :joystick ?, PS3_CONTROLLER) :, p.vehicle, p.crosshair)

To find the correct button-mappings, use jstest.

Further info
I now plan to make other individual posts explaining some of the stuff I did, like Gosu Joystick support on linux, Health Bars with RMagick, Parallax scrolling, the Menu system and others.