Methods

From WarfishWiki

Jump to: navigation, search

You call the API's using http. This can be done from a browser (javascript or directly in the location) or from a cgi script (such as python) for bots.


Contents

[edit] warfish.tables.getBoardImage

Gets the base image of the board.

Example usage:

http://warfish.net/war/services/rest?gid=35770110&_method=warfish.tables.getBoardImage

[edit] warfish.tables.getDetails

This method is specified on the url using the _method parameter and is used to retrieve static information about a particular game table. This static information is meant to be cacheable (in contrast to warfish.tables.getState which constantly changes at the game progresses) and includes information about the rules, game board geometry, player names, etc.

Parameters:

  • gid - game table id
  • sections - list of one or more of 'board','rules','map','continents' (unrecognized sections are ignored)

Example usage:

Possible error codes for "warfish.tables.getDetails" (each provided with a debug string):

  • "invalid game id"

Sample code:

<script src="jquery-1.2.6.js"></script>
<script>
  var gid = 31588379;
  var method = "warfish.tables.getDetails";
  var url = "/war/services/rest?_method=" + method + "&_format=json&gid=" + gid;
  $(document).ready(function() {
     $.getJSON(url, function(data){
                       alert(data['_content']['rules']['tselect']);
                    });
  });
</script>

Details on what the method returns is found at syntax.

[edit] warfish.tables.getState

This method retrieves information relating to the current state of the game table. This data changes as the game progresses so it should not be cached.

Parameters:

  • gid - game table id
  • sections - list of one or more of
    • cards
    • board
    • details
    • players
    • possibleactions - list the possible moves that will be accepted by warfish.tables.doMove. If it is not your turn an empty list will be returned

Example usage:

Possible error codes for "warfish.tables.getDetails" (each provided with a debug string):

  • "invalid game id"

Details of what the method returns can be found at syntax.

[edit] getHistory

Retrieve the game history. There are two ways to access the history.

  1. movelog - The movelog is a list of all the actions that have occurred on a game.
  2. turnindex - The turn index is a list of all the turns (in a turn-based game) or rounds (in a blind-at-once game)

Parameters:

  • gid - game table id
  • start - moveid, min 0 (i.e. moveid 0 = movenum 1), if "-1" then get the last "num" moves. the start parameter is handled slightly differently between section movelog and turnindex. For turnindex, the start parameter is a negative index from the end... so -3 would mean three turns from the end.
  • num - number moves to request, must min 1 and max 1500
  • sections - must be either empty (defaults to movelog), "movelog" or "turnindex"

Example usage:

     http://warfish.net/war/services/rest?_method=warfish.tables.getHistory&gid=123123123&start=-1&num=100
     http://warfish.net/war/services/rest?_method=warfish.tables.getHistory&sections=turnindex&gid=62049159&start=-3&num=3

Possible error codes for "warfish.tables.getHistory" (each provided with a debug string):

  1. "invalid game id"
  2. "invalid start"
  3. "invalid num"

Returns:

  • section=movelog - list of requested moves
    • total - total number of moves
    • numreturned - number moves returned in request
    • _content - list of moves (see movelog attributes below)
  • section=turnindex - list of turns
    • total - total number of turns in game
    • numreturned - number turns returned in request
    • _content - list of turns (see turninfo below)


 <?xml version="1.0" encoding="utf-8" ?>
 <rsp stat="ok">
   <turnindex total="7" numreturned="3">
   <t start="128" endtime="1195522477" end="138" players="2" />
   <t start="139" endtime="1195524547" end="158" players="3" />
   <t start="159" endtime="1195530115" end="173" players="0" />
   </turnindex>
 </rsp>


 {  "stat" : "ok"  ,  "_content" :  
 {  "turnindex" :  
    {  "total" : "7"  ,  "_content" :  
      {  
      "t" :  
        [   
           {  "start" : "128"  ,  "endtime" : "1195522477"  ,  "end" : "138"  ,  "players" : "2"  }   ,   
           {  "start" : "139"  ,  "endtime" : "1195524547"  ,  "end" : "158"  ,  "players" : "3"  }   ,   
           {  "start" : "159"  ,  "endtime" : "1195530115"  ,  "end" : "173"  ,  "players" : "0"  }   ]   }   ,  
      "numreturned" : "3"  }   }   } 

[edit] movelog attributes

Definitions of movelog attributes names:

  • id - move id (first moveid = 0)
  • a - action id
    • a attack
    • b eliminate player bonus units
    • c capture territory
    • d decline to join a game
    • e elimiante player
    • f transfer
    • g awarded card
    • h capture cards
    • i capture reserve units
    • j join game
    • k seat order for blind-at-once round
    • l blind territory select
    • m message
    • n create new game
    • o assign seat position
    • p place unit
    • q blind-at-once transfer
    • r reshuffle cards
    • s start game
    • t select territory
    • u use cards
    • v blind-at-once attack
    • w win
    • y territory selected as neutral territory
    • z bonus units
    • sr surrender
    • bt booted
    • tg game terminated
    • tw team win
  • t - unix timestamp
  • logver - Warfish movelog version
  • s - seat number
  • cid - country id
  • num - number (usually of units or num cards)
  • ad - attack dice list
  • dd - defend dice list
  • ds - defender seat num
  • m - border mods
  • al - number of units lost by attacker
  • dl - number of units lost by defender
  • oid - blind-at-once order number
  • tcid - "to" country id
  • fcid - "from" country id
  • es - eliminated seat num
  • tid - team id
  • slist - seat num list
  • clist - card id list which cards captured / traded (only available post game)
  • cardid - card id a player was awarded (only available post game)


[edit] turninfo attributes

Each turn that is returned from the section=turnindex call contains several attributes

  • start - movelog start index
  • end - movelog end index
  • players - seat numbers of players who are involved in this turn / round
  • endtime - unix timestamp for when the turn/round finished

Once the start and end values are retrieved they can be used to retrieve the appropriate moves from the movelog

[edit] doMove

[edit] general

     This api is used for all actions on a game table. You can refer to the possibleaction section of warfish.tables.getState to see which actions are currently available to you on a particular game table.
     Parameters:
         o gid - game table id
         o action - actionid (see below for action details)
         o (action dependent args) - additional arguments required depending on action
     Possible error codes for "warfish.tables.doMove" (each provided with a debug string):
        1. "invalid game id"
        2. "invalid action"
        3. "missing action params"
        4. "invalid action param" 
     Returns:
         o success - returns success=1 if the move was successfully executed
         o error - otherwise returns error information 

[edit] join

     action=join [colorid, name] [back to top]
     The "join" action is simply used to join a game.
     Arguments:
         o colorid - colorid number
         o name - an in-game player handle 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=join&colorid=1&name=Conqueror
     Possible error codes for "join" (each provided with a debug string):
        1. "You are not a player"
        2. "You have already declined"
        3. "Invalid color id"
        4. "Please specify an ingame handle"
        5. "Please specify a different color"
        6. "Please specify a different name" 

[edit] select single

     action=selectsingle [cid] [back to top]
     The "selectsingle" action is used in manual territory selection during game setup
     Arguments:
         o cid - country id for an unoccupied country 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=selectsingle&cid=3
     Possible error codes for "selectsingle" (each provided with a debug string):
        1. "Invalid country id"
        2. "Country already occupied" 

[edit] select territories

     action=selectterritories [clist] [back to top]
     The "selectterritories" action is used in blind-at-once territory select during game setup.
     Arguments:
         o clist - comma separated ordered list of country ids 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=selectterritories&clist=3,2,1,4,5
     Possible error codes for "selectterritories" (each provided with a debug string):
        1. "Please select all countries"
        2. "Please provide country list"
        3. "Duplicate country id list"
        4. "Invalid country id list"
        5. "Occupied country selected" 

[edit] place single

     action=placesingle [cid] [back to top]
     The "placesingle" action is used in manual unit placement during game setup
     Arguments:
         o cid - country id of one of your territories (to place a single unit) 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=placesingle&cid=3
     Possible error codes for "placesingle" (each provided with a debug string):
        1. "Invalid country id"
        2. "Placing a unit there would exceed the maximum number of units per country set for this game" 

[edit] place units

     action=placeunits [clist, ulist] [back to top]
     The "place units" action can be used in two different scenarios. In blind-at-once unit placement during game setup and in unit placement phase during a turn-based play turn.
     Arguments:
         o clist - comma separated list of country ids
         o ulist - comma separated list of numunits to place on each country 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=placeunits&clist=3,2&ulist=1,3
     Possible error codes for "placeunits" (each provided with a debug string):
        1. "Game processing..."
        2. "Country ids list and units list different lengths"
        3. "Commands to place too many units"
        4. "Invalid country id found"
        5. "Placing units exceeds the max per country set for this game"
        6. "Country id specified twice"
        7. "Too many units in reserves"
        8. "Too many cards, must have less than 5"
        9. "No countries specified"
       10. "Invalid action order" 

[edit] use cards

     action=usecards [numA, numB, numC, numW] [back to top]
     The "usecards" action is used during turn-based play to trade cards.
     Arguments:
         o numA - number of A cards to use (default label "Ammunition")
         o numB - number of B cards to use (default label "Rations")
         o numC - number of C cards to use (default label "Supplies")
         o numW - number of wild cards to use 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=usecards&numA=1,numB=1,numC=1
     Possible error codes for "usecards" (each provided with a debug string):
        1. "You must select exactly three cards."
        2. "You do not have the cards"
        3. "You must select three different or three of the same"
        4. "Invalid action order" 

[edit] attack

     action=attack [fromcid, tocid, numunits, continuous] [back to top]
     The "attack" action is used during turn-based play to perform attacks.
     Arguments:
         o fromcid - attacker country id
         o tocid - adjacent enemy country id (defender)
         o numunits - number of units to attack 1-3 for continuous=0 or 3+ for continous=1
         o continuous - either "1" or "0" indicating if this should be a continuous attack with 3 units 
     Return values:
     The "attack" action returns all the die rolls and outcome of the attack so that information can be evaluated before performing your next move.

[edit] Example usage

      http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=attack&fromcid=3&tocid=4&numunits=3&continous=0
     Possible error codes for "attack" (each provided with a debug string):
        1. "Invalid numunits"
        2. "Invalid from country"
        3. "Invalid to country"
        4. "Num units too large"
        5. "Num units too small"
        6. "Maximum attacks taken already"
        7. "Game processing..."
        8. "Place more units, reserve can not store all extra"
        9. "Use cards until you have less than 5"
       10. "Invalid action order" 

[edit] Example XML Response

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
   <return msg="success" code="1">
      <info defenderseatid="0" attackerunits="3" defenderunits="1" />
      <attack defenderleft="0" defenddice="1" defenderlosses="1" attackerlosses="0" attackdice="5,4,2" />
      <dice ddie="6" adie="6" />
      <results totalattackerlosses="0" eliminate="0" captured="1" totaldefenderlosses="1" />
   </return>
</rsp>

Another example. This one was from "continuous attack, losing up to 5"

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok"><ret msg="success" code="1">
   <info defenderseatid="0" attackerunits="5" defenderunits="16" />
   <dice ddie="6" adie="6" />
   <possibleactions>
       <action id="attack" />
       <action id="transfer" />
       <action id="endturn" />
   </possibleactions>
   <results totalattackerlosses="4" totaldefenderlosses="6" />
   <attack defenderleft="15" defenddice="6,1" defenderlosses="1" attackerlosses="1" attackdice="6,3,2" />
   <attack defenderleft="13" defenddice="5,2" defenderlosses="2" attackerlosses="0" attackdice="6,3,2" />
   <attack defenderleft="12" defenddice="5,3" defenderlosses="1" attackerlosses="1" attackdice="5,4,3" />
   <attack defenderleft="10" defenddice="4,3" defenderlosses="2" attackerlosses="0" attackdice="5,4,2" />
   <attack defenderleft="10" defenddice="5,3" defenderlosses="0" attackerlosses="2" attackdice="5,3,1" />
</ret>
</rsp>

[edit] free transfer

action=freetransfer [numunits] [back to top]

The "freetransfer" action is used during turn-based play. It allows you to move additional armies after a successful attack.

Arguments:

         o numunits - number of additional units to move 

Example usage:

http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=freetransfer&numunits=3

Possible error codes for "freetransfer" (each provided with a debug string):

        1. "Invalid to numunits"
        2. "Numunits too large"
        3. "Game processing..."
        4. "Invalid action order" 

[edit] transfer

action=transfer [fromcid, tocid, numunits] [back to top]

The "transfer" action is used during turn-based play to transfer units between adjacent countries.

Arguments:

         o fromcid - from country id
         o tocid - to country id
         o numunits - number of units 

Example usage:

http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=transfer&fromcid=4&tocid=5&numunits=3

Possible error codes for "transfer" (each provided with a debug string):

        1. "Invalid numunits"
        2. "Invalid from country"
        3. "Invalid to country"
        4. "Num units too large"
        5. "Num units too small"
        6. "Maximum fortifies taken already"
        7. "Game processing..."
        8. "Moving units exceeds the max per country set for this game"
        9. "Invalid action order"

[edit] end turn

     action=endturn (no args) [back to top]
     The "endturn" action is used during turn-based play to complete a turn when option actions (such as more attacks or more transfers) are available but you wish to send your turn without further actions.
     Arguments:
         o (no arguments) 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=endturn
     Possible error codes for "endturn" (each provided with a debug string):
        1. "Too many units in reserves"
        2. "Too many cards, must have less than 5" 

[edit] Blind at Once (BAO) issue orders

     action=issueorders [olist, alist] [back to top]
     The "issueorders" action is used in blind-at-once play turns to issue all your orders (i.e. usecards, placeunits, pretransfers and attacktransfers).
     Arguments:
         o olist - orders list, a comma separated list of order type ids indicating the type of each order
              1. usecards
              2. placeunits
              3. pretransfers
              4. attacktransfers 
         o alist - arguments list, a comma separated list of arguments for each order. Within each list element "sub arguments lists" are separated by a colon (see the example below)
              1. usecards - requires exactly 3 arguments, card ids representing each of the three cards to be used
                     + 0 - A card (default label "Ammunition")
                     + 1 - B card (default label "Rations")
                     + 2 - C card (default label "Supplies")
                     + 3 - Wild card 
              2. placeunits - requires exactly 2 arguments
                     + first argument is the country id to place the units
                     + second argument is the number of units to place 
              3. pretransfers - requires exactly 3 arguments
                     + first argument is the "from" country id
                     + second argument is the "to" country id
                     + third argument is the number of units to transfer 
              4. attacktransfers - requires exactly 5 arguments
                     + first argument is the "orderid", the order number (starting at 0, must be seqential)
                     + second argument is the "from" country id
                     + third argument is the "to" country id
                     + fourth argument is the number of units to transfer
                     + fifth argument is the number to represent attack/transfer:
                          1. transfer
                          2. attack
                          3. either 
     Example usage:
     http://warfish.net/war/rest?_method=warfish.tables.doMove&gid=123123123&action=issueorders&olist=1,2,2,3,4&alist=1:1:1,2:3,4:5,6:7:8,0:9:10:11:3
     Example usage explanation:
     In this usage example there are 5 orders being issued (one of each type and an extra unit placement). Here are orders from the above request with their arguments and what order would be issued:
         o order type id: "1" order arguments: "1:1:1" order issued: usecards(cardid=1,cardid=1,cardid=1)
         o order type id: "2" order arguments: "2:3" order issued: placeunits(tocid=2,numunits=3)
         o order type id: "2" order arguments: "4:5" order issued: placeunits(tocid=4,numunits=5)
         o order type id: "3" order arguments: "6:7:8" order issued: pretransfer(fromcid=6,tocid=7,numunits=8)
         o order type id: "4" order arguments: "0:9:10:11:3" order issued: attacktransfer(orderid=0,fromcid=9,tocid=10,numunits=11,attack/transfer=3) 
     Possible error codes for "issueorders" (each provided with a debug string):
        1. "No orders issued"
        2. "No order arguments"
        3. "Invalid orders ids"
        4. "Invalid order arguments"
        5. "Order ids out of range"
        6. "Order list and args list different length"
        7. "Must use three cards at a time"
        8. "Invalid card id"
        9. "You do not have the cards you trying to use"
       10. "Trade 3 unique or 3 different cards"
       11. "Place more units, reserve can not store all extra"
       12. "Invalid country id"
       13. "Can not place more units than you have"
       14. "Maximum units per country reached"
       15. "Not enough units in country"
       16. "To country not adjacent to from country"
       17. "Can not transfer units into enemy territory"
       18. "Order numbers much be sequential"
       19. "Invalid order"
       20. "Duplicate order number"
       21. "Use cards until you have less than 5"
Personal tools