Basic Info

From WarfishWiki

Introduction [back to top]

Very Preliminary APIS. Welcome to the the Warfish XML/JSON APIs page. This is a new feature for Warfish. These preliminary APIs are provided early so that developers can get a feel for them and Warfish can get some feedback (what is missing? what is broken? etc.). However, they will under go change not only as Warfish gets feedback, but also since there are several new Warfish features in the works that may have an effect on these APIs. I'd like to start by listing out a couple of the areas where these APIs may change in the next couple months as new Warfish features come online. Hopefully, this will help you get a sense for which areas may affect your code.

1. API authentication. A temporary authentication scheme of enabling these APIs on a user by user basis and using the Warfish cookies is being used (see below), however a more permanent solution using APPids will be implemented at some point.

2. Design tool changes. There are several changes that will be added to the design tool that will affect any bots and other code using these APIS. Multiple unit types, randomized territories, starting scenarios and headquarters. Please contact support if you need more detail.

What would you want APIs for? These were created in response to several user requests for APIs to write bots that could play Warfish, so they were initially designed with that in mind. However, JSON apis have also been added and cookie base authentication which allows for another class of applications to be easily built: Warfish UI Plugins. Using javascript and the JSON apis developers can easily create analysis/stats/probability calculator tools using the data from a game, in theory once apis are fine-tuned full replacements for the game play page could be written with any number of extra little UI goodies (different info from different tabs displayed at once, heads up displays, etc). To learn more about Warfish UI plugins read the section below and also check your Settings > Plugins page.

Example bots process and "data flow" [back to top]

Since this API was original designed for bot designers first I'll go over a brief overview of one process and "data flow" for creating a bot for Warfish.

  1. First you need to create a "bot" user account. At this point just use a standard user, invite a test email to a game to create this accound.
  2. Then contact Warfish support to enable the Warfish APIs for that account
  3. Get an Warfish cookie for your bot (see Authentication below).
  4. Create a new bot.cgi script and save your cookie into a variable to use when making requests to the XML/API.
  5. Then implement bot.cgi that takes the gameid as an argument to utilize the appropriate APIs to make moves. You can test your bot easily by inviting your bot account to a game as usual and just running your script by hand when it is your bots turn that way you can fix bugs and make any adjustments along the way.
  6. Finally, when your bot.cgi is working you can copy it onto your webserver and setup a http notification url (see Notification below). Then anyone can invite your bot to play and it will be notified and make its moves on its own. 

That is the basic idea. Here is a listing of samplebot@warfish.net which is live and working bot: Sample Bot listing

Example UI Plugins process and "data flow" [back to top]

Building UI plugins is more straightforward since it only requires a webpage continaining some javasript code to get started. The main complication currently is that until a better authentication system is in place, only users who have requested to be enabled for XML/JSON apis will be able to use plugins built with these XML/JSON apis.

  1. First you need to get access to the XML/JSON apis for your user id by contacting support. Unlike when building bots it is just as easy to use your own account while developing UI Plugins.
  2. Once your userid has access to the XML/JSON apis you can begin constructing your html page containing JSON calls via script src= tags to the XML/JSON apis. You don't have to worry about authentication since your cookie is passed by your browser to Warfish when it is making the JSON calls. In this respect it is much similer to build UI plugins than bots.
  3. Finally, when your plugin is working you can register it with Warfish so that any user on warfish can "install" it into their account and use it along-side the regular Warfish UI. Check your Settings / Plugins page for more information. 

That is the basic idea. Here is a step by step tutorial on how to make a plugin using javascript: Javascript Plugin Tutorial