Editing Query game API

WarLight can provide programmatic access to the details about multi-player WarLight games.  This allows for the more technical users to write a program that can analyze information about games.  This data is only available for ladder games, tournament games, games created by the [[Create game API]], or games that you played in.

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. 

The primary goals of this API is to enable tools that do statistical analysis of finished games and to enable custom ladders or custom tournaments to check on the winners of the game after it's over.

==Usage==

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

This will return data describing basic details(id, state, name, numberOfTurns, lastTurnTime, templateID, players) about the game.

If you want to get the entire turn history of the game, add an additional querystring parameter '''GetHistory=true'''.  Adding this will cause the API to return you details about every turn of the game assuming it's finished.

If you want to get a game's settings, add an additional querystring parameter '''GetSettings=true'''.  Adding this will cause the API to return you details about the settings of the game.

If you want to get a game's public chat message, add an additional querystring parameter '''GetChat=true'''.

==JSON Definition==

* 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 JSON, 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. 

== Game State ==

This API returns a "state" attribute on the game.  This will be one of the following values:
* WaitingForPlayers: This game is in the lobby and has not yet begun.
* DistributingTerritories: This game is waiting for players to make their territory selections.  This state will not exist for games with automatic distribution.
* Playing: The game is in progress.
* Finished: The game has finished.

== Player States ==

This API returns a "players" collection which contains information about each player in the game.  Each player will have a "state" attribute with one of the following values:
* Invited: The game is waiting on this player to accept or decline the game.  This state will only ever be present for games still in the lobby.
* Playing: This player is in the game, and still alive.  This state will never be present in a game that has finished.
* Eliminated: This player has been eliminated from the game.
* SurrenderAccepted: This player has surrendered and is no longer in the game.
* Booted: This player was booted from the game.
* Won: This player has won the game.  This state will only be present in games that have finished.
* EndedByVote: This player, along with the other remaining players in the game, have voted to end the game.  This state will only ever be present for games that are finished by voting-to-end.
* Declined: This player declined the game and did not play.
* RemovedByHost: This player was removed by the host via the "Add/Remove Players" button and did not play.  If you created the game via the Create Game API, you don't have to worry about this state since you're the host, and only you could remove players.

==Getting a list of Game IDs==

In order to use the game feed, you'll need to know the game ID.  This can be obtained through the graphical WarLight client by opening up the Settings panel and examining the "Link to Game" field.  At the end of this field, you'll see GameID= followed by a number.

To find game IDs programmatically, you can use the [[Game ID feed API]].

==See Also==

* [[Game ID feed API]]

[[Category:API]]