GGP.org Game Services
GGP.org game services are a collection of HTTP-based APIs that developers can use to discover games and download game resources for their applications.
First, let's introduce the concept of a game repository. A game repository is a server that hosts a collection of games. Each game repository has its own URL. Given the URL for a game repository, you can discover the list of games available in that repository, and then access the individual games. All of the games are packaged in the same way, using a standard format.
GGP.org hosts several game repositories:
- base - This is the main game repository for GGP.org and Tiltyard.
- dresden - This repository contains games imported from the Dresden GGP Server.
- stanford - This repository contains games imported from the Stanford Gamemaster.
Given the URL for a game repository, how can you discover what games are available? Easy: go to the "/games/" page on the game repository you're interested in. This will list all of the available games in that repository as a JSON list. For example, if you look at http://games.ggp.org/base/games/, you'll find a list that looks like this:
["maze", "snake_2008_tweaked", "amazons", ...Okay! So let's say we'd like to get more information about the game "maze". Well, simply add that name onto the end of the previous URL, and look at http://games.ggp.org/base/games/maze/, where you will find:
{"numRoles":1, "stylesheet":"maze.xsl", "rulesheet":"maze.kif", "gameName":"Maze", "roleNames":["robot"], "version":0}This is the metadata about the game "maze": the name, the number of roles, and links to several important resource files for the game. The resources can include the game rulesheet, a visualization, a human-readable description of the game rules, a javascript-based user interface, and more. Let's say we want to look at the game rulesheet, because we'd like to run a match. To do that, we just look at the "rulesheet" entry in the JSON metadata above, and add that value to the end of our URL, yielding http://games.ggp.org/base/games/maze/maze.kif; and indeed, loading that page gives us the rulesheet for that game.
Looking for a more formal specification for how game repositories work? Well, here you go. After the URL prefix, each game repository has a specific directory structure:
| / | Undefined: may have any content or be inaccessible. |
| /games/ | A listing of available games, as a JSON array. |
| /games/X/ | Game metadata, as a JSON map, for game X. |
| /games/X/Y | A resource Y listed in the above metadata file. |
| /games/X/vN/ | Game metadata for game X version N. |
| /games/X/vN/Y | A resource Y listed in the above metadata file. |
| /A/B/C | A resource in the repository, referenced by another resource; can have any path. |
Game repositories provide a listing of all of their available games at /games/ as a JSON list. For every entry X in this list, there is a metadata file provided at /games/X/ as a JSON map, as described by the game packaging format. The other files referenced by the metadata file must also be in that directory. For example, if the metadata file refers to resource Y, that resource will be found in /games/X/Y.
Requesting a game resource without including a version number in the URL will return the latest version of that resource. Metadata files include the version number, so you can determine the current version of a game from them. Old versions of games will continue to be available indefinitely so that recorded matches which refer to them will continue to be intelligible. Games will increment their version numbers whenever they are changed in a way that would otherwise render older matches unintelligible: for example, tweaks to the visualization do not require a version number increase, but changes to the game rules that alter the structure of the game do.