Announcing WarLight 1.3

WarLight will be going down on Saturday, April 30th at 1am PDT (8am GMT) for up to 30 minutes. Please plan accordingly for any fast games or single player games that may get interrupted during this 30-minute window.

During this time, WarLight will be upgraded to v1.03.0. This blog post contains a summary of what’s changing. This is a smaller release than normal, as I’m simultaneously working on a bigger release that won’t be done for a while.

Cyclic Move Order

Members have a new setting they can set on their games: the Move Order. This setting controls the sequence that orders are carried out within each turn. The default is set to Random, which is how all the games work today — i.e. you never know if your first attack will happen before or after your opponents, since it’s determined randomly for each turn.

If this setting is changed to Cycle, then players will take turns getting first move. In this mode, you can figure out whether or not your first attack will happen before or after your opponent’s first attack. The first turn of a game is randomized just as it would be in the random move order that we’re all used to, but subsequent turns just cycle through that same order. For example: ABCD becomes BCDA for the next turn, followed by CDAB, and finally DABC before starting back at ABCD.

This is mostly designed for 1 v 1 games, in which one player to get first move on all evened numbered turns while the other player gets first move on all of the odd numbered turns.

One twist is that you can’t see the cycle for the game anywhere. You must deduce it by observing the sequence that attack orders happen in. This means that if you see an opponent attack happen before your first attack, then you know the cycle and will be able to know whether or not your first attack will happen before your opponent’s first attack.

This setting will be considered for the ladders in the future.

Gold Stars

Gold Stars are now awarded for each of the single-player levels if you can complete them in low turn times. These don’t do anything except look pretty, but they give you something else to shoot for when going through the single player levels. Stars are awarded for completing:

– Level 1 in 6 turns
– Level 2 in 14 or fewer turns
– Level 3 in 19 or fewer turns
– Europe challenge in 18 or fewer turns
– Crazy challenge in 22 or fewer turns
– Insane challenge in 28 or fewer turns

Map Feedback

In an effort to increase the quality of maps, players can now submit feedback on maps directly to the map creators. This is a great way to report any bugs you find in a map, or just to let a map creator know that you really enjoy their map.

To do this, from the game screen, click the Settings button, View Map, Send Feedback. This can also be done on the Create Game screen if you click Preview Map and then Send Feedback.

New Strategic 2 v 2 Settings

As mentioned in the previous blog post, the settings for the 2 v 2 ladder are being tweaked so that players now start with two territories each instead of one.

Ladder History

In this release, WarLight will begin keeping a history of each player/team’s ladder rating and rank changes over time. This means WarLight will be able to show a graph of your rank/rating, or helpful indicators showing whether players have been rising or falling.

While these features aren’t coming in this release, at least it will be tracking history so that when these features are eventually added, they’ll have data going back to now.

Misc Changes

– Player’s profiles now show what percentage of their games are real-time versus multi-day.
– When spectating a game that’s finished, the “Watch turn” phase will now be skipped automatically.
– Added a player’s best ladder rank to their profile page.
– Ladder player’s best rank is now shown even after they leave the ladder.
– The ladder’s rank-changed email now only sends a maximum of once per day.
– The ladder matchmaking algorithm has been tweaked to help pair you with players you have not played before.
– All tournaments must now be multi-day.
– When viewing a forum thread, the forum name is now displayed in the “Go back” link above it.
– The top-left corner label now says “Game start” in place of “Turn 0”
– Players are now given an alert if they try to submit an order delay card as their last order, since it would be a waste of the card.
– WarLight now uses a CDN to reduce bandwidth costs.
– Fixed a bug that occurs when a player you’re spying on gets a territory gifted to them.
– Fixed a bug that caused the Chat text box to not appear when joining an open tournament.
– Fixed a bug that caused open tournaments you created to show “Unread Chat Messages”
– Fixed a bug that, when creating a game, caused the auto-boot drop down to stay disabled if you go back and disable banking boot times.

New 2 v 2 Ladder Settings

Players recently voted on new 2v2 ladder settings (where each player is given two territories instead of one to start) in this thread. The results are in!

– 80% approve of the new settings
– 10% rejected the new settings
– 10% don’t care

Overwhelmingly, most of you like the new settings. Therefore, these new settings will go live in the next WarLight release, which will be v1.3. As is policy, the new settings won’t take effect for at least a week from the date of this announcement, so players have time to practice with the new settings before they go into effect.

You can view the new settings (or create games with them) with these links: multi-player, single-player

WarLight as a candidate to the Google AI Challenge

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!

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.


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.


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 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”


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

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


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.


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

The Impaller versus The World

I’m pleased to announce a special WarLight event called The Impaller versus The World! This is a public 1v1 WarLight game that anyone can participate in.

This game is a Strategic 1 v 1 game where one side of the game will be played by The Impaller, who’s one of WarLight’s best players, and the other side is played by you! Everyone in the WarLight community can vote on what move to make in the game, and the highest voted option will be carried out in the game.

This game’s primary purpose it to serve as a learning exercise — who wins isn’t important. The game will take two turns every week – one every Tuesday and another every Friday. Check the forum to follow along with the game, read strategies, share your strategy, and of course, vote!

The voting uses, which has a cool voting system that doesn’t require you to pick a single option. Rather, you can rate each option with a star rating between 0 and 5 stars. This means that if there are two options you can’t decide between (or that are very similar), you don’t need to decide between them – you can just put both of them at 5 stars.

Troll has agreed to moderate the game. Every Tuesday and Friday, he will create a forum post with instructions on how to vote. Troll will create several options to vote for, but feel free to suggest your own in the forum thread if what you really want to do is missing from the list.

Important: Be sure not to post your strategies or talk about the game anywhere except the official forum threads. The Impaller knows that he’s forbidden from reading the clearly marked threads, but if you talk about the game somewhere else he may accidentally come across it.

The game begins today! The first step is to do territory selection. Here’s the board we have to start with (click to enlarge):

Head over to this forum post to cast your votes!

Create WarLight Games Programmatically

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: 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:[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, you should POST xml that contains the details about the game you’re creating. Here’s an example:

	<gameName>Game name here (max 50 chars)</gameName>
	<personalMessage>Description to include with the game.
                   (Max 1024 characters)</personalMessage>
		<player token="" team="None" />
		<player token="" team="None" />
		<player token="123456789" team="None" />
		<player token="" team="None" />
  • 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 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.


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!