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: 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!