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

Revision: 0.10.2

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

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
preceded 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 separate (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-separated messages
themselves 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 decrease
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 host="string" version="string"/>

The client must then complete the handshake by using the "set name" command:

.n$1

$1	string	Player name.

Until this command has been sent, any data the client sends will be ignored.
When the handshake is completed the server gives the client some connection
info:

  <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://monopd.unixcode.org/ and can be used by clients to connect to
dedicated servers on the Internet.

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

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

The following is a 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 template list.
.gj$1    : join game number $1.
.gx      : exit a game without disconnecting from the monopd server
.gk$1    : the player listed as master for a game can use this to kick a
           player with playerid $1 from a game during configuration, back
           into the lounge
.gu$1    : upgrade spectating player with playerid $1 to a real player. Only
           the master can do so.
.gc$1:$2 : Make changes to the game configuration. $1 is the unique configId
           from a received configupdate and $2 is the new value for value,
           which can be string, int or bool depending on the type specificed
           in the configupdate.
.gS$1    : Join game $1 as spectator.

- 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.
.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
.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 readability.  Each line of messages is enclosed
by <monopd> and </monopd>.

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

 <server host="$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.  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.

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

 <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" spectator="bool" hasdebt="bool" canauction="bool"
    canusecard="bool" turnorder="int"/>

Most of these are obvious. Directmove is a suggestion to clients whether
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 trade or 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"
   canbewatched="bool" minplayers="int" maxplayers="int" master="int"
   turn="int"/>

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.
Master is -1 for no master (should not happen) or a player id indicating
this player is the master for the game. Turn is the number of turns that
players have done so far.

Status can be:

config		- Clients should display the configuration widget if their
                  player is in this game. Clients in the game selection
                  phase should offer players the option to join this game,
                  hooked to the .gj command.

init		- The client will retrieve the initial game data if its
                  player is within the game.  Other clients should disable
                  joining this game (because canbejoined will turn to
                  false, which also happens when players equals maxplayers).

run		- The game is running. Clients in it should display the game
                  board.

end		- The game has ended. Clients in it 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).

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

<deletegame gameid="int"/>

Delete a game object.

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

<configupdate configid="int" gameid="int" name="string" title="string"
  type="string" value="string|int|bool" edit="bool"/>

Allows clients to view/configure options (editing might only be available
before the game starts!). Each configuration option has its own unique ID
during a game and can be edited by sending the .gc$1:$2 where $1 is the
configId and $2 the new value, which can be string, int(eger) or bool(ean)
as defined by type. Edit tells clients whether the master can edit this
property.

Note that this behavior changed from monopd versions prior to 0.9.0 where
edit indicated whether the client itself could edit a property. Monopd will
now send all clients edit=1 for properties that can be changed. It is
assumed that clients will disable these items based on being the master
player for a game or not.

Configuration options may be sent globally in the future so clients can
display current game configuration before joining a game. Clients are
expected to filter on gameid attribute even if this doesn't seem necessary
for now.

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

<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 POSSIBLY to be used after
monopd 1.0. At present, the code sending such messages is commented out in
CVS.