Warzone Blog

There has been some talk of WarLight being a candidate for the next Google AI Challenge. For those not familiar with the Google AI Challenge, the GAIC is a competition where software engineers write a bot to play a game for them. They then upload their bot into the GAIC website which matches their AI against everyone else’s. It’s a lot of fun – they’ve featured other popular games such as Galcon and the Tron game, which is a bit like the old snake games.

To prepare for WarLight as a candidate, I threw together a prototype of a framework that can run a WarLight AI Challenge. This contains everything you need to write and run a WarLight AI on your own computer, completely separate from the WarLight servers.

I appreciate any feedback on this prototype – shoot me an email at fizzer@warlight.net!

Game Settings

WarLight is a very flexible engine that supports many different variations and settings. For this prototype, I selected settings that I think would make for a good AI challenge. I chose these settings both to make the game as fair as possible, as well as making it as easy as possible to write an AI.

Map

I chose the Double Earth map for this prototype, since it’s symmetrical and therefore can be completely fair to both parties. For the initial territory layout, I pick three random territories from the top earth and give these to one AI, and give the same three from the lower world to the other AI. The rest of the territories start out as neutral 2s.

Most strategic WarLight games let players choose where they start. This is entirely plausible for the AI Challenge as well, however I decided that a random (but mirroed) approach was better simply because it makes it easier to write an AI. Having to write code to determine where to start is a fun AI challenge itself, but doing this adds more syntax to the AI language and is just one more thing you need to learn and write before you can have a working AI. If the GAIC sponsors want this turned back on it can be.

Cards

For those unfamiliar, WarLight contains a dozen different types of cards that have a variety of effects on the game. I decided for the AI Challenge that cards should be left out, mostly because they add more syntax to the AI language and, like above, increase the base knowledge you need to learn to write an AI.

Fog

Fog is the WarLight feature that controls whether or not you can see the entire map or just what’s next to you. Whether or not to include fog in an AI challenge is an interesting decision that I thought a lot about. Ultimately I decided to turn it on, since it’s a feature unlike things that the GAIC has done before. If you’d like to try it without fog, you can turn it off in the downloaded source on line 34 that says “useFog: true”

Randomness

WarLight’s rules do contain some randomness, which enhances the game experience for human players. However, for an AI challenge, it may be beneficial to remove the use of the random number generator. There are four places that Warlight uses the RNG: distribution, combat, rounding, and move order. Two of these have already been removed from the prototype, and the other two could also be eliminated if we wanted to get rid of the RNG completely.

– Distribution: As mentioned above, bots don’t get to choose where they start so the normal randomness that affects strategic 1 v 1 games during distribution has already been removed for this AI challenge.

– Combat: WarLight’s main combat rules contain some use of the RNG. WarLight already contains a slider that allows you to control how much you want the RNG to affect your game. For the AI challenge, I have set this slider to 0, which eliminates this use of the RNG. If you want to turn it back on, you can do so in the downloaded source on line 33 that says “luckModifier: 0”

– Rounding: WarLight uses random rounding, where 0.4 has a 40% chance of being rounded up and a 60% chance of being rounded down. This is left turned on in the prototype, however if the GAIC sponsors wish, we could change this to a straight round to eliminate this use of the RNG.

– Move order: WarLight randomizes the order that players move within a turn. Although this does have an effect on the game, it’s typically not the deciding factor. Nevertheless, if the GAIC sponsors wish, we can change this to order based on a predictable heuristic, such as alternating turns or giving first move to the player with fewer armies or something like this.

How to Write an AI

For those unfamiliar with GAIC, this prototype uses standard in/out to communicate with bots. This means you can write your bot in any language that can print to and read from the console. The fastest way to get started is to take a look at the C# starter pack included in the downloadable below as it contains a fully functional (although not incredibly smart) AI.

At Startup: The Map

WarLight maps are obviously a graph. When your AI is started, the first thing it will do is read the map from standard-in. The first line is simply the word “Map” informing you that a map is coming up.

After that, your AI will read a series of lines starting with TerritoryDefinition. For example:

TerritoryDefinition 1 SolomonIslandsN 48 8
TerritoryDefinition 2 St.PetersburgN 87 4 11 110 111 104
TerritoryDefinition 3 PeruN 125 96 147 64
TerritoryDefinition 4 PermN 110 92 2 87 70
TerritoryDefinition 5 MyanmarN 26 29 49 119
TerritoryDefinition 6 PanamaN 147 25
TerritoryDefinition 7 ShanghaiN 50 26 151 114

Territory definition arguments:
– Argument 0: The word TerritoryDefinition
– Argument 1: The ID of this territory
– Argument 2: The name of the territory with spaces stripped out. This is not used by your AI, but it assists in debugging as knowing the name of the territory makes it easier to locate on a map.
– Argument 3+: The IDs of the territories that this territory connects to.

After reading territories, your AI will be fed a series of lines starting with BonusDefinition. For example:

BonusDefinition 5 CentralRussiaN 83 45 120 105 75 137 150
BonusDefinition 4 AustraliaN 27 122 14 135 134 12 91 15
BonusDefinition 6 EastRussiaN 136 115 66 18 46 103 65 129 72 149
BonusDefinition 6 EuropeN 54 51 109 34 10 80 11 101 95
BonusDefinition 4 MiddleEastN 138 52 21 53 43 19

Bonus definition arguments:
– Argument 0: The word BonusDefinition
– Argument 1: The number of armies this bonus is worth if you control all of its territories
– Argument 2: The name of the bonus. This is not used by your AI, but it assists in debugging as knowing the name of the bonus makes it easier to locate on a map.
– Argument 3+: The IDs of the territories that make up this bonus.

After the bonuses, your AI will be fed a line that says “EndMap” and nothing else. This notifies you to stop reading the map and to get ready to start the first turn of the game.

Each Turn: The Standing

In your main game loop, first read a line that will say either “GameOver” or “Turn #” where # is the turn number. Upon reading GameOver, you should obviously exit your process.

If you don’t see GameOver, you should start receiving a game “standing.” A standing is the state of the board at one point in time – it tells you who controls each territory and how many armies on are on it.

Territory 198 ownedBy Neutral withArmies 1
Territory 199 ownedBy Neutral withArmies 2
Territory 200 ownedBy You withArmies 5
Territory 209 ownedBy Neutral withArmies 2
Territory 214 ownedBy You withArmies 5

Territory arguments:
– Argument 0: The word “Territory”
– Argument 1: The territory ID
– Argument 2: The word “ownedBy”
– Argument 3: Either “You”, “Neutral” or “Opponent”
– Argument 4: The word “withArmies”
– Argument 5: The number of armies on this territory

Keep reading territories until you read the word “EndStanding” alone on a line.

Each Turn: Send Your Orders

After reading the standing, it’s time to execute your custom AI logic! As we’ve removed cards, the only thing your AI needs to issue are Deploy orders and AttackTransfer orders, which is what can order armies to attack or transfer from one territory to an adjacent one.

You should print out orders to standard out like this:

Deploy 4 on 5
Deploy 1 on 112
AttackTransfer 4 from 5 to 29
AttackTransfer 3 from 5 to 119
AttackTransfer 8 from 26 to 119
end

Deploy arguments:
– Argument 0: The word “Deploy”
– Argument 1: The number of armies you’re deploying
– Argument 2: The word “on”
– Argument 3: The territory ID you’re deploying on

AttackTransfer arguments:
– Argument 0: The word “AttackTransfer”
– Argument 1: The number of armies to attack or transfer
– Argument 2: The word “from”
– Argument 3: The territory ID to attack or transfer from
– Argument 4: The word “to”
– Argument 5: The territory ID to attack or transfer to

Finally, after issuing all of your orders, simply print out “end” to signal that you’re done. That’s all there is to it!

How to run your AI

The downloadable below contains an executable named WarLightAIChallenge.exe. Simply run this with two arguments that point at the bots you wish to execute. For example, to have the included starter pack fight itself on Windows, run: (note: Windows users must have .net 4.0 installed)

WarLightAIChallenge.exe StarterPack.exe StarerPack.exe

On OSX or Linux, run it in Mono 2.8 or higher:

mono WarLightAIChallenge.exe StarterPack.exe StarerPack.exe

Visualizer

For this prototype, I have not yet written a visualizer. This means that there’s no provided app that lets you view your game data in a graphical format to easily see what’s going on. If anyone writes one and is willing to share, send me an e-mail and I’ll post it here.

Downloads

Download Here

This package contains:
– StarterPack source code
– StarterPack pre-compiled binary
– AI runner source code (named WarLightAIChallenge)
– AI runner pre-compiled binary (named WarLightAIChallenge.exe)

If you run into any problems or have any comments, please send me an email at fizzer@warlight.net.

WarLight now supports the ability to create multi-player games programmatically via an API. This opens up a wealth of new possibilities for application writers, such as creating custom WarLight tournaments or ladders.

Of course, it’s always been possible to create custom tournaments or ladders manually, but this API allows you to write a system that will automate this process. This blog post describes how to write an automated system like this.

Invite Tokens

To invite players to a game via the API, you must get each participating player’s invite token or e-mail address. It’s preferable to use invite tokens over e-mail addresses, since players may be reluctant to share their e-mail addresses. However, inviting by e-mail address is provided as an option for situations where you know everyone’s e-mail, such as setting up a tournament with friends or co-workers.

Players can get their invite token by visiting this url: http://warlight.net/InviteToken.aspx. Incidentally, this is the same number as what’s displayed in the address bar when looking at a player’s profile. So it’s easy to get someone’s invite token from a forum post, if you’re handling adding players to your system manually.

After getting a player’s invite token, you can pass it to the ValidateInviteToken API. This API tells you whether an invite token is valid, which ensures you that you will be able to invite them to a game. Calling VaidateInviteToken is not strictly necessary to invite players to a game, however it’s handy if you want to know up-front whether or not it’s valid rather than waiting for the game creation to fail later.

You can call ValidateInviteToken with a URL like this: http://warlight.net/API/ValidateInviteToken.aspx?Token=[token].

Creating the Games

Once you’ve got all your invite tokens, you can divide them up into games according to whatever logic you’re trying to achieve. To create a game, call the CreateGame API. You can specify the game settings, game name, boot times, and the players you’re inviting.

When calling http://warlight.net/API/CreateGame.aspx, you should POST xml that contains the details about the game you’re creating. Here’s an example:

 <createGame>
	<hostEmail>your@email.com</hostEmail>
	<hostPassword>yourPassword</hostPassword>
	<templateID>1234</templateID>
	<gameName>Game name here (max 50 chars)</gameName>
	<personalMessage>Description to include with the game.
                   (Max 1024 characters)</personalMessage>
	<realTime>false</realTime>
	<voteBootTimeInMinutes>Never</voteBootTimeInMinutes>
	<directBootTimeInMinutes>2880</directBootTimeInMinutes>
	<autoBootTimeInMinutes>4320</autoBootTimeInMinutes>
	<practiceGame>false</practiceGame>
	
	<invite>
		<player token="player1@email.com" team="None" />
		<player token="player2@email.com" team="None" />
		<player token="123456789" team="None" />
		<player token="player4@email.com" team="None" />
	</invite>
 </createGame>
 

• hostEmail / hostPassword: These elements identify you. The game will be recorded as created by you.
• templateID: Specifies the ID of a template that you create through the normal game GUI. You can either use a built-in template or you can create your own. It does not matter if you create it as a single-player or multi-player template.
• gameName: This will show up as the name of the game. Maximum 50 characters.
• personalMessage: This will show up in the Lobby as well as the Settings. Maximum 1024 characters.
• realTime: True for real-time game, false for a multi-day game. This is typically false.
• voteBootTimeInMinutes / directBootTimeInMinutes / autoBootTimeInMinutes: These define the boot times for the game. 2880 is 2 days, 4320 is 3 days.
• practiceGame: True for a practice game, false for a ranked game.
• invite: This node defines the players that will be invited. It consists of ‘player’ elements, each of which contains a ‘token’ attribute and a ‘team’ attribute:
  • player team: This can be the string ‘None’ if you’re not creating a team game. If you are creating a team game, then supply a number for each player identifying the team that they’re on. 0 is team A, 1 is team B, 2 is team C, etc.
  • player token: The token covered in the previous section.
  • slot: If you’re making a game that uses a custom scenario, you must provide a “slot” attribute on each player that let’s WarLight know what scenario to give this player. This should be an integer, where 0 is slot A, 1 is slot B, 2 is slot C, etc.

Check for Finished Games

If your call to CreateGame is successful, it will return you a game ID. Store this number for future reference, along with a flag indicating that the game is not finished.

Periodically, (say, every few hours), you should scan all unfinished games and query http://warlight.net/API/GameFeed.aspx for each one. If the game is still in-progress, this API will tell you so. If the game is finished, you can parse the results of this API to determine who won and update your own database accordingly and create new games if necessary.

Member Requirement

All of these APIs are only callable by members, and the CreateGame API can only invite members to games. I realize the latter requirement is a bit restrictive, but since the ladder is one of the biggest draws of becoming a WarLight member, there needs to be a restriction that prevents a third-party ladder from offering this benefit to non-members. This restriction may loosen up over time – it’s much easier to loosen up on these kinds of things than it is to tighten them. Tightening them breaks existing code, whereas loosening them just pleases people.

Reference

For a full reference that contains a few more details on how to use these APIs, please see the API Reference page. If you have any questions, feel free to e-mail me!

WarLight can now provide an xml feed of data about a specific game. This allows for the more technical users to write a program that can analyze information about games.

This initial release of the feed should be considered an “alpha” experimental project. If this proves useful, it can be expanded to include more information. Currently, the feed is only available for finished ladder and tournament games and is only available for WarLight members.

Being able to consume this data via an API allows for broader analysis of many games at once, which can answer questions such as:

– How often does a player know one or more of an opponent’s picks?
– How often does the person who definitively knows his opponents starting spots win?
– Does early 3v2 luck affect winning percentage?
– Does getting first pick affect winning percentage?
– Does first move affect winning percentage?

There’s nothing the feed can see that isn’t already available through the game’s normal interface. This is just a way to write custom analyzers which allows for a broader analysis across games.

To access the data, use a URL like this:
http://warlight.net/GameFeed.aspx?GameID=1212978

This will present you with a large XML blob describing everything about the game. To help understand the data, let’s first define some terminology:

– A “standing” is the state of the board at any given point in time. This contains one entry per territory that contains the number of armies on that territory, who controls it, and the fog level.
– A “turn” is just a collection of orders. This includes all the orders each player submitted, mixed together in the sequence they played out.
– An “order” is obviously one order that a player submitted. But it can also include other things, such notifications when a player gets eliminated, or when cards are received, etc. Essentially, this represents what you see in the “Orders” panel on the right side of a game when viewing history.

In the xml blob, you’ll find:

– The players in the game (their names, color, their state, etc.)
– All of the details of the map (it’s name, all of its territories and what they connect to, all of its bonuses and what territories are in each bonus)
– The “distribution standing”: This is what the map looked like when it was time to pick the territories you started with. This is only present for manual distribution games.
– The picks: This tells you which territories each player picked, and in what order. Like the distribution standing, this is only present for manual distribution games.
– Standing 0: This tells you what the map looked like at the beginning of the game.
– Turn 0: This is all of the orders that played out on the first turn of the game.
– Standing x/turn x: Standings and turns then alternate for each turn of the game, all the way until the final standing.

If there is something you’d like to see included that isn’t currently included, I’d like to hear about it.