Create game API

Revision as of 07:20, 25 August 2011

The CreateGame API will create a single WarLight game. You can specify the game settings, game name, boot times, and what players are invited to the game.

Usage

Using this can allow you to create a program that hosts your own tournaments or ladder-type systems.

To create games via the API, you must POST some xml to http://warlight.net/API/CreateGame.aspx 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>Include a 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: This 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 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 identifies the player you're inviting. You can either pass an e-mail address or a player token. Using tokens is an option provided only because some players may not want to dilvulge their e-mail address to you. These players can instead give you their invite token. To find a player's invite token, they can visit http://warlight.net/InviteToken.aspx. The invite token is the same as the number displayed in the address bar when you view a player's profile page.
  • 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.

Output

The CreateGame API will output the ID of the newly created game if it is successful. If it is unsuccessful, it will output an 'error' node. Here are some examples:

Success:

 <root>
     <gameID>1234567</gameID>
 </root>

Failure:

 <root>
     <error>Description of the error</error>
 </root>

See Also

• Validate invite token API