===============================================================================
monopd API

Revision: 0.8.3

Erik Bourget <ebourg@po-box.mcgill.ca>
Rob Kaper <cap@capsi.com>
===============================================================================

Contents

	1) Notes
		i. protocol notes
		ii. server introduction
		iii. contact information
		iv. generally active servers
	2) Client->Server Messages
	3) Server->Client Messages
	
===============================================================================
1) Notes
===============================================================================

i. protocol notes
-----------------

Commands from clients to the monopd server are in the form of a tiny message
preceeded by a dot and followed by a newline:

.gn

Messages from the server to clients are in XML form.  An example:

<monopd><playerupdate playerid="1" money="1420"/></monopd>

All messages are complete and exclusive to the line they are sent on; a
message such as

<monopd>
	<gamelist>
		<game id="1" users="2"/>
	</gamelist>
</monopd>

should be parsed by clients as five seperate (and all invalid) messages.

<monopd><msg type="info" value="Rob throws a 6 and a 2."/></monopd>

is thus one valid message.

Further example messages in this document will however be wrapped using
newlines, for readability.

There have been complaints of monopd sending multiple root elements in one
"document", but unless there's a bug somewhere, newline seperated messages
itself should not contain more than one root element. Please do treat data
after a newline as a new document. Most modern network APIs provide methods
such as canReadLine() and readLine() which are optimised for this usage.

Not all fields of the XML messages are sent on every update; clients are to
assume that anything not referred to is either undefined if there has been no
previous mention of the attribute, or that it keeps the same value as the
last update that included it set it to. These incremental updates decreases
the amount of data sent over the network.

The encoding of the protocol is UTF-8.

ii. server introduction
-----------------------

The server identifies itself with an introductory XML message:

<monopd><server version="0.7.0"/>
  <client playerid="26" cookie="26/32631782"/></monopd>

Each client that connects to the server receives a unique playerid; this
will be used as identifier in games and eventually together with the cookie
field to support graceful reconnects after timeouts.

iii. contact information
------------------------

The monopd team uses the monopd-devel@lists.capsi.com mailinglist as its
primary discussion forum.

While this documentation ought to be complete and free of errors, there
might be inconsistencies, missing entries or other problems you might
experience when dealing with the protocol. Please do not hesitate to report
any problems or ask for clarification when in doubt.

iv. generally active servers
---------------------------

A list of available monopd servers is available on http://gator.monopd.net/
and can be used by clients to connect to dedicated servers on the Internet.

Please read the file README.monopigator from the monopd distribution for
more information.

===============================================================================
2) client->server messages
===============================================================================

The following is an exhaustive list of supported client-server messages.

$<number> refers to a value that should be supplied; i.e. for a command .xyz$1,
the message .xyz14 would be a valid instance of the command to send to the
server.

- connection commands

.R$1 : reconnect using cookie $1.

- game commands

.gn$1 : create a new game of optional type $1. monopd defaults to the
        Atlantic game type.
.gl   : request a game list.
.gj$1 : join game number $1.
.gx   : exit a game without disconnecting from the monopd server

- trade commands

.Tn$1          : Initiate a trade with player with playerid $1.
.Tc$1:$2:$3    : Set target owner of card $2 to player $3 in trade $1.
.Te$1:$2:$3    : Set target owner of estate $2 to player $3 in trade $1.
.Tm$1:$2:$3:$4 : Player $2 gives $3 an amount of $4 as part of trade $1.
.Ta$1:$2       : Accept current (revision $2) terms of trade with tradeid $1.
.Ta$1          : Accept current terms of trade with tradeid $1. (WARNING:
                 deprecated. Exists for backwards compatiblity but clients
                 are encouraged to use the above command instead)
.Tr$1          : Reject trade $1.

- movement commands

.r	 : roll dice for movement
.E	 : end current turn
.t$1     : confirm latest player movement to location $1.  This is used
	   for clients that animate token movement to let the daemon know
	   when to give money for going across "Go".

- debt settling commands

.D	 : declare bankruptcy
.p	 : pay off debts

- estate management commands

.eb	 : buy current estate
.es$1    : sell estate with estateid $1 to bank
.ea	 : auction current estate
.hb$1	 : buy a house on estate with estateid $1
.hs$1	 : sell a house on estate with estateid $1
.em$1	 : toggle mortgage on estate with estateid $1

- auction commands

.ab$1:$2 : bid $2 dollars for auction with auctionid $1

- jail commands

.jc	 : use get out of jail free card
.jp	 : pay get out of jail fee
.jr	 : attempt to roll doubles in jail

- tax commands (only available when the tax dialog has been initialised)

.T$      : pay static tax
.T%      : pay tax as percentage of assets

- player management commands

.pi$1    : set player image to $1

- game management commands

.gn	 : start a new game
.gl      : request a list of open games
.gj$1	 : join game with gameid $1
.gd$1	 : set current game description to $1
.gp	 : get playerlist for current game
.gs	 : start current game

- miscellaneous commands

.d	 : disconnect from server
.n       : set name
.f       : request full update

===============================================================================
3) server->client messages
===============================================================================

While they won't come like this from the server, I've split some messages
onto more than one line for readibility.  Each line of messages is enclosed
by <monopd> and </monopd>.

--------------------

 <server name="$1" version="$2"/>

Identifies the server, sent upon connection.

--------------------

 <client playerid="$1" cookie="$2"/>

Gives the client a unique identification.

--------------------

 <msg type="string" playerid="int" author="string" value="string"/>

Used for sending informative messages to clients.  Possible types include
chat, info, error, standby, and startgame.  These are just to display to
users and can be ignored as they will always be accompanied by more
'official' messages. For chat messages, playerid and name of the chatting
player are sent.

--------------------

 <display estateid="$1" text="$2" cleartext="bool" clearbuttons="bool">
   <button command="$3" caption="$4" enabled="$5">
 </display>

Used for sending client estate landing and transaction messages to display.
Text is the body text of the message (text of chance cards, transaction
messages when purchasing/landing). In case this is a dialog that requires
user input, buttons can be requested for display, including the
corresponding response command (.e.g. button "pay x % tax" has command
".T%").

If estateid is -1, clients should clear the display.

--------------------

WARNING: Deprecated.

 <updateplayerlist type="$1">
	<player playerid="$2" name="$3" host="$4" master="$5"/>
	...
 </updateplayerlist>

Gives clients information about other players in game.  The "master" attribute
of the player element denotes if the player is the master of the current
game. Type can be "full", "edit", "add", or "del".

WARNING: Deprecated, will be removed for 1.0. Use playerupdate and its
gameid/name/host/master attributes.

--------------------

 <updategamelist type="$1">
	<game id="$2" players="$3" gametype="$4" name="$5" description="$6"
	 canbejoined="$7"/>
	...
 </updategamelist>

Gives clients information about available games.

The description field is optional (and set with .gd); type can be either
"full", "edit", "add", or "del".

If Id is -1, this is not an actual game which can be joined but a template
for a new game.

--------------------

 <playerupdate playerid="int" game="int" name="string" image="string"
    money="int" location="int" jailed="bool" directmove="bool"
    bankrupt="bool" hasturn="bool" can_roll="bool" can_buyestate="bool"
    host="string" master="bool" spectator="bool" hasdebt="bool" canauction="bool" canusecard="bool" />

Most of these are obvious. Directmove is a suggestion to clients about if
they should animate tokens (or not, directmove is 1 for "go directly to
jail"). Master is 1 or 0 depending on whether the player is the controlling
player in a game and spectator indicates whether a player is participating
in the game or just watching it.

--------------------

<deleteplayer playerid="int"/>

Delete a player object.

--------------------

 <estateupdate estateid="int" name="string" owner="int" houses="int"
   houseprice="int" sellhouseprice="int" mortgaged="bool" group="int"
   can_be_owned="bool" can_toggle_mortgage="bool" can_buy_houses="bool"
   can_sell_houses="bool" money="int" price="int" mortgageprice="int"
   unmortgageprice="int" color="#rrggbb" bgcolor="#rrggbb" rent0="int"
   rent1="int" rent2="int" rent3="int" rent4="int" rent5="int" />

Again, stuff is pretty self-explanatory.  The "owner" attribute is set to
the playerid of the estate's owner or -1 if unowned; group is the groupid of
the group that the estate belongs to (or -1 if not part of a group). Money
is only used for Free Parking; it indicates how much money will be received
upon landing on an estate. Color and bgcolor are hexcodes, e.g. "#00ff00"

--------------------

<cardupdate cardid="$1" title="$2" owner="$3"/>

When a card is removed from the stack, all three attributes are shown: the
unique id, a title to be used in client GUI and dialogs and the playerid of
the owner. When trading and putting cards back on the stack only the cardid
and owner (-1 when the card is on the stack) are sent.

--------------------

<estategroupupdate groupid="int" name="string"/>

groupid Unique group id.
name    Name of the group.

--------------------

 <tradeupdate type="$1" tradeid="$2" actor="$3" revision="int">
	<tradeplayer playerid="$4" accept="$5"/>
	<tradecard cardid="$6" targetplayer="$7"/>
	<tradeestate estateid="$8" targetplayer="$9"/>
	<trademoney playerfrom="$10" playerto="$11" money="$12">
	...
 </tradeupdate>

Type can be either "new" for creating a new trade, or "completed" or
"rejected", both deleting the trade as object. If missing, "edit" is
assumed, for adding players and notifying whether they accept current
proposal or including cards and estates (targetplayer is a playerid, or -1
when a component is removed, money objects are removed when money is 0),
"accepted" (at which point the ownerships are being transferred).

Actor is the playerid of the player initiating the tradeof rejecting it.

Tradeplayer's accept field denotes whether that player has agreed to the
current terms of the trade; this is reset to 0 upon any change and must be
re-accepted with a .Ta.

--------------------

 <auctionupdate auctionid="$1" actor="$2" estateid="$3" highbid="$4"
   highbidder="$5" status="$6"/>

Actor is the playerid of the player auctioning the estate, estateid the
estate being auctioned, highbid the higgest bid at the moment and status is
is 0 for normal, 1 for "going once", 2 for "going twice", and 3 for "gone".

Auctionupdate will probably be deprecated soon and merged into the <display>
tag, as the actor is not of interest and the highest bid and bidder can also
be shown as description for a display widget.

--------------------

 <gameupdate gameid="int" gametype="string" name="string"
   description="string" status="string" players="int" canbejoined="bool"/>

Gives clients information about games on the server. 

The description field is optional (and set with .gd), if gameid is -1, this
is not an actual game which can be joined but a template for a new game.

Status can be:

config		- Clients should display the configuration widget.
init		- The client will retrieve the initial game data.
run		- The game is running. Client should display the game board.
end		- The game has ended. Clients should no longer offer
		  game-related commands, but may still show the board and
		  its info and can either disconnect or leave the game (and
		  request a new gamelist).

--------------------

WARNING: Deprecated.

  <commandlist type="$1">
    <command id="$2" syntax="$3" description="$4">
    ...
  </commandlist>

Informs clients about what commands are currently available.  Type can be
"add", "del", or "full".

WARNING: Commandlist is deprecated and all of its features will be replaced
by better estateupdate and playerupdate messages, such as playerupdate
can_roll or estateupdate can_toggle_mortgage.

--------------------

<configupdate gameid="$1">
  <option title="$2" type="$3" value="$4" command="$6" edit="$5"/>
  ...
</configupdate>

Allows clients to view/configure options (editing might only be available
before game start!). Supported types are: bool. Edit is a boolean to tell
clients whether this option can be edited or not. Commands should be
postfixed with the configuration value: for bools 0 or 1, such as .geaf1

--------------------

<update object="string" id="int">
  <int key="string" value="int"/>
  <string key="string" value="string"/>
</update>

WARNING: Do not use yet!

This is part of the new object wire protocol to be used after monopd 1.0.
CVS versions might send these already, but official releases should have
them filtered out so clients should not yet depend on the new XML. For now,
use the regular game/player/estate/card/config updates.
