Editing Create game API

The CreateGame API will create multi-player WarLight games programmatically.  You can specify the game settings, game name, 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 JSON to https://www.warlight.net/API/CreateGame that contains the details about the game you're creating.  Here's an example:


  {
    hostEmail: "your@email.com",
    hostAPIToken: "yourApiToken",
    templateID: 1234,
    gameName: "Game name here (max 50 chars)",
    personalMessage: "Include a description to include with the game. (Max 1024 characters)",
    players:  [
      { token: "66553413", team: "None" },
      { token: "134314314" team: "None" },
      { token: "123456789" team: "None" },
      { token: "13453531543" team: "None" }
    ],
    settings: { ... }
  }


 
* hostEmail / hostAPIToken: These elements identify you.  You can get your APIToken from the [[Get API Token API]].  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 choose a single-player or multi-player template.  This is optional -- if not specified, the "Normal Game" template will be used.
* 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.
* players:  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, or the string "OpenSeat".  Players can find their token by visiting https://www.warlight.net/InviteToken.  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 also 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.
* settings: Optionally, you can provide settings to customize the template you specified above.  To see a full list of settings, use the [[Query game API]] with GetSettings=true.

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

  {
      gameID: 1234567
  }

Failure:


  {
      error: 'Description of the error'
  }

== Specify Bonus Values ==

This API can optionally specify bonus values for the game it creates.  These will appear under the game's Settings as overridden bonuses.

To do this, add a new node to the JSON you send in named "overriddenBonuses".  Here's an example:


  {
    hostEmail: "your@email.com",
    ...
    players:  [
      ...
    ],
    overriddenBonuses: [
      { bonusName: 'Southeast Asia', value: 5 }, 
      { bonusName: 'South America', value: 9 }
    ]
  }

Values specified here will replace any values specified by the template in use.  

Typically you will specify bonuses by name as shown above.  However, if a map has multiple bonuses with the same name, you can specify a "bonusID" attribute instead of the "bonusName" attribute shown above.  To find the ID of a bonus, use the [[Query game API]] on a game using the same map.

== Open Seats ==

You may pass the string "OpenSeat" in place of the invite token of a player.  This will make that spot an open seat, and the game will be advertised on the Open Games tab along with other open games.  When using open seats via this API, a member-only prerequisite will automatically be set on the game. 

== Level Restriction ==

When creating games via this API, all players that are being invited to the game must have access to all features that your game uses.   For example, if you want to create a game that uses the spy card, then all players must have unlocked the ability to create games using the spy card.

This restriction exists to prevent players from bypassing WarLight's member and level restrictions completely.  For example, if this restriction did not exist, someone could make a website that allowed any non-member to create a game for themselves using all of the member-only features.

If you want to ensure that everyone you're inviting has access to the features you want to use, call the [[Validate invite token API]] and pass your template ID.

== Black List Restriction ==

This API cannot invite someone who to a game who has you on their black list.  This differs from the behavior of normally creating a game via the game's UI.  This restriction exists in order to prevent some run-away code (either due to a bug or malicious user), from inviting someone to an excessive number of games that they don't want.   This gives a way for players to forcibly stop the code from creating new games with them.

==See Also==

* [[Validate invite token API]]

[[Category:API]]