The Problem

Let’s say we have a game where the board is made up of six-side polygons (“hexes”, if you will) and each hex can contain a unit like a spearman or a javelin thrower. Each unit on the board belongs to a player who can take turns moving his units, telling his units to attack other player’s units, etc. Some units have different capabilities than other units – a spearman must be within 1 hex of another unit to attack that unit, whereas a javelin thrower can be 2 units away. How do we design the application in such a way that:

• The game engine doesn’t need to know specifics about each unit (such as range of attack).
• A unit’s capabilities may change during the course of gameplay (such as a spearman being upgraded to a javelin thrower).

My Solution

Before we look at the code, lets run through what is going to happen in-game.

1. The user selects one of their units, then selects an opposing unit somewhere else on the gameboard, then clicks an “Attack” button.
2. The game engine creates a context (deriving from ITurnContext) that describes what the user has asked to do. In our case, an AttackContext is created containing references to the attacking unit and the defending unit.
3. That context is then passed into the ExecuteTurn method of the attacking Unit, which then passes it along into the Handle method of its CurrentState property (which is an object deriving from UnitState). Our attacker’s CurrentState property is currently Spearman, but could just as easily be JavelinThrower. Changing a unit from melee to ranged is as simple as changing the state of that unit.
4. Our Spearman state derives from UnitState, and the UnitState base class’ Handle method uses double dispatch to forward the Handle request on to the appropriate method of our subclass. In our case that would be the Handle(AttackContext) method of the Spearman class.
5. Our Spearman class’ Handle method then checks to see if the unit is within range to attack the defending unit – if it is, an AttackCommand is returned denoting who the attacker and the defender are; if it isn’t, a MovementCommand is returned denoting which hex to move to.
6. The Unit class then calls Execute on the returned command, causing the movement or attack operation to be, well, executed.

Let’s go through each of the above steps and take a look at the code involved one by one. Skipping the first step (the UI), we’ll move on to where the game engine is creating an AttackContext and passing it into the attacking Unit:

Attacker.ExecuteTurn(new AttackContext {Attacker = Attacker, Defender = Defender});

Okay, easy enough. Moving on we can see the Unit class’ ExecuteTurn method pass the context to its CurrentState property’s Handle method:

public class Unit
{
	public Hex Location { get; set; }
	public int Health { get; set; }
	public UnitState CurrentState { get; set; }

	public void ExecuteTurn(ITurnContext context)
	{
		CurrentState.Handle(context).Execute();
	}
}

Our attacking unit’s CurrentState property is currently set to an instance of Spearman, but before we take a look at that class we’ll take a look at its base class (UnitState - which is doing double dispatch to the Spearman‘s Handle method):

public abstract class UnitState
{
	private static readonly Dictionary Dispatch = new Dictionary();

	static UnitState()
	{
		foreach (var t in Assembly.GetCallingAssembly().GetTypes().Where(t => t.IsSubclassOf(typeof (UnitState))))
			foreach (var mi in t.GetMethods().Where(mi => mi.Name == "Handle" && mi.GetParameters().Length > 0))
				Dispatch.Add(((Int64) t.GetHashCode() << 32) + mi.GetParameters()[0].ParameterType.GetHashCode(), mi);
	}

	public IUnitCommand Handle(ITurnContext context)
	{
		var hash = ((Int64) GetType().GetHashCode() << 32) + context.GetType().GetHashCode();
		return Dispatch.ContainsKey(hash)
		       	? Dispatch[hash].Invoke(this, new[] {context}) as IUnitCommand
		       	: new NullCommand();
	}
}

The Spearman class’ Handle method is then invoked:

public class Spearman : UnitState
{
	public IUnitCommand Handle(AttackContext context)
	{
		if (context.Attacker.Location.DistanceTo(context.Defender.Location) == 1)
			return new AttackCommand(context);
		return new MovementCommand(new MovementContext
		                           	{
		                           		UnitToMove = context.Attacker,
		                           		HexToMoveTo =
		                           			context.Attacker.Location .FindClosestSurroundingHexTo( context.Defender.Location)
		                           	});
	}
}

Notice that the only concern Spearman currently has when handling an attack context is ensuring that it gets within range and then attacks the target. We’ll see an example of a JavelinThrower later. Finally we’ll peek at what the MovementCommand and AttackCommand actually do:

public class MovementCommand : IUnitCommand
{
	private readonly MovementContext _movementContext;

	public MovementCommand(MovementContext movementContext)
	{
		_movementContext = movementContext;
	}

	#region IUnitCommand Members

	public void Execute()
	{
		_movementContext.UnitToMove.Location = _movementContext.HexToMoveTo;
	}

	#endregion
}

public class AttackCommand : IUnitCommand
{
	private readonly AttackContext _attackContext;

	public AttackCommand(AttackContext attackContext)
	{
		_attackContext = attackContext;
	}

	#region IUnitCommand Members

	public void Execute()
	{
		_attackContext.Defender.Health -= 10;
	}

	#endregion
}

Before we move on, here is the promised JavelinThrower class:

public IUnitCommand Handle(AttackContext context)
{
	if (context.Attacker.Location.DistanceTo(context.Defender.Location) <= 2)
		return new AttackCommand(context);
	return new MovementCommand(new MovementContext
	                           	{
	                           		UnitToMove = context.Attacker,
	                           		HexToMoveTo =
	                           			context.Attacker.Location .FindClosestSurroundingHexTo( context.Defender.Location)
	                           	});
}

Obviously JavelinThrower & Spearman currently only differ in the range at which they can attack (<=2 and <= 1, respectively), so the code in their Handle methods could be abstracted out using the Strategy Pattern.

Prove It!

So now that we’ve had a chance to see the code involved the question comes down to: does it actually work? Here are our unit tests:

[Fact]
public void JavelinThrower_moves_to_two_hexes_away_and_attacks()
{
	//starting point
	Assert.Equal(4, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn one - moves closer
	Attacker.ExecuteTurn(new AttackContext { Attacker = Attacker, Defender = Defender });
	Assert.Equal(3, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn two - moves closer
	Attacker.ExecuteTurn(new AttackContext { Attacker = Attacker, Defender = Defender });
	Assert.Equal(2, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn three - attacks
	Attacker.ExecuteTurn(new AttackContext { Attacker = Attacker, Defender = Defender });
	Assert.Equal(2, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(90, Defender.Health);
}

[Fact]
public void Spearman_moves_to_one_hex_away_and_attacks()
{
	//starting point
	Assert.Equal(4, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn one - moves closer
	Attacker.ExecuteTurn(new AttackContext {Attacker = Attacker, Defender = Defender});
	Assert.Equal(3, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn two - moves closer
	Attacker.ExecuteTurn(new AttackContext {Attacker = Attacker, Defender = Defender});
	Assert.Equal(2, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn three - moves closer
	Attacker.ExecuteTurn(new AttackContext {Attacker = Attacker, Defender = Defender});
	Assert.Equal(1, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(100, Defender.Health);

	//turn four - attacks
	Attacker.ExecuteTurn(new AttackContext {Attacker = Attacker, Defender = Defender});
	Assert.Equal(1, Attacker.Location.DistanceTo(Defender.Location));
	Assert.Equal(90, Defender.Health);
}

And the results…

Yay!

So that is the road I went down, but what I really want to know is how would you solve this problem? If you’d like to take a deeper look at my code, download it and give it a try yourself:

EverlandStatePattern.zip