Query game API: Difference between revisions
fixed player state documentation to reflect actual API output |
|||
| Line 7: | Line 7: | ||
To access the data, use a URL like this: https://www.warlight.net/API/GameFeed?GameID=1212978 | To access the data, use a URL like this: https://www.warlight.net/API/GameFeed?GameID=1212978 | ||
This will return data describing basic details about the game. | This will return data describing basic details(id, state, name, numberOfTurns, lastTurnTime*, templateID, players) about the game. | ||
<nowiki>*</nowiki> - lastTurnTime is the timestamp of the last turn or the game finish date | |||
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. | 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. | ||
Revision as of 06:17, 4 August 2017
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.
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.
* - lastTurnTime is the timestamp of the last turn or the game finish date
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.
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.
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.
- 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.
Each finished game is guaranteed to have at least one player with a Won state or a VotedToEnd state.
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.