NETWORKING OF COMPUTER BRIDGE PROGRAMS

A PROPOSED PROTOCOL FOR INTER-PROGRAM COMMUNICATION

Version 18 (1 August 2005)
(latest revisions will be shown in red)

Introductory

This draft protocol suggests a method by which bridge programs can communicate with each other in order to play bridge.
The basic concept is that there are five programs, ideally running on five separate computers. One program plays for each hand. The fifth program acts as the "Table Manager". The Table Manager’s function is to deal the cards, transmit and receive all communications among the playing programs, keep the score and (to a limited extent) enforce the rules of the game.
All communications are in plain-text ASCII format (characters #10, #13 and #32 to #127 only), using TCP/IP. It has been suggested that all 8-bit ASCII characters should be allowed for e.g. accented characters, but this might cause display problems for receiving computers (opinions please).
Note that no provision is made for handling transmission time-outs.
Before communications are initiated, the Table Manager’s IP address is given to the operators of the playing computers. In a LAN, this may instead be the network name of the Table Manager’s computer. Each computer will communicate with the Table Manager on a unique port, which should be agreed in advance with the Table Manager's operator. The port numbers should be within the standard range of 1024 to 5000.
Before communications are initiated, each pair decides on a team name and all four players decide on their seating positions.
The Table Manager opens four server sockets and waits to receive messages.
Hereafter, all messages are enclosed (for identification purposes only) in quotation marks. The quotation marks will not form part of the actual message. Variables are enclosed in square brackets. In the actual message, both the square brackets and their contents will be replaced by the appropriate value. All messages are to be terminated by <return><line-feed> (ASCII #13#10).
In messages, [Bidder], [Player], [Dummy] and [Hand] will be replaced by the players’ seat positions : North, South, East or West (as appropriate).
Most messages are in plain English, so that the transmissions will be intelligible to operators and observers without decoding.
Messages are not case-sensitive, so recipients (i.e. any program receiving a message) should mask all messages to a single-case and trim leading and trailing spaces before interpreting. However, because messages may optionally be displayed by programs, it is strongly recommended that they are generated by playing programs with appropriate casing, e.g. "North bids 3NT" rather than "north bids 3nt".
Throughout this protocol, a space (ASCII #32) is a single space. Additional spaces; or double spaces must not be inserted into messages where they are not defined in the protocol.
The deals are loaded by the Table Manager from a pre-existing PBN (Portable Bridge Notation) file. The Table Manager’s operator identifies the file for the Table Manager and specifies the number of boards to be played. As this is a local function of the Table Manager software, it is not discussed further here.
The protocol has been designed so that a single message is transmitted by a client to the Table Manager and a single message is transmitted in return.

Message summary

The following is an outline of the scheme of exchange of messages transmitted by the clients (purple) and the Table Manager (green). The messages are summarised and are defined in detail in the following sections.

Connecting
Seated
Ready for team names
Team names
Ready to start
Start of board
Ready for deal
Cards
Bidder bids x (bidder) or Ready for bidder's bid (others)
Transmit bid
[Loop to 9 until end of auction. If action passed out and not end of round, go to 6]
Ready for leader's card (except leader, or declarer when dummy is leader)
Leader to lead (only to leader)
Leader plays x (leader)
Transmit card 1 (to others)
Ready for dummy (only trick 1 and except dummy)
Dummy's cards (only trick 1 and except dummy)
Second hand plays x (second hand) or Ready for second hand's card (others)
Transmit card 2 (to others)
Third hand plays x (third hand) or Ready for third hand's card (others)
Transmit card 3 (to others)
Fourth hand plays x (fourth hand) or Ready for fourth hand's card (others)
Transmit card 4 (to others)
Table Manager pauses for one second
[loop to 12 until end of board]
[loop to 6 until end of round]
End of session

Connecting

To connect with the Table Manager, a player opens a client socket to the Table Manager’s computer. The player sends "Connecting ["team name"] as [Hand] using protocol version [x]". The team-name should be enclosed in double-quotation marks (ASCII #34) to avoid any conflict with reserved words used in this protocol. So that the team-name can be used as part of a file-name for hand records etc., it should consist only of characters which would be valid as part of a file-name. If a set of boards is replayed as part of a match with the same pairs but in rotated seats, exactly the same team-names as were used in the first set must be used in the second set. If the Table Manager detects an irregularity (e.g. seat taken, seat not specified, the pair not using the same team-name or a player using the opponents' team name), it will transmit an error message and close the connection. The protocol version number is as stated at the top of this page. If the version number does not match Table Manager's protocol version number, the connection will be rejected.
From now on, each player’s messages start with the player’s name ("North", "South", "East" or "West"). Except for the special case of declarer playing dummy’s cards (discussed below), if a message prefixed by a player’s name does not match the socket allocated to that player by the Table Manager, the Table Manager will ignore the message.
Technically, the Table Manager's server sockets can identify the origin of the client socket message, but it is proposed that TCP/IP is kept out of the specification and reliance is placed solely on ASCII messages. This will also allow future migration to non-TCP/IP systems without major change to the specification.
On receipt of a valid log-on message, the Table Manager allocates the player to the appropriate seat and sends to the player "[Hand] ("[team-name]") seated".
The player responds "[Hand] ready for teams".
When all four players have connected successfully, the Table Manager sends to each player "Teams : N/S : "[N/S team name]". E/W : "[E/W team name]"". Note that the inner quotation marks are literal. They are the delimiters of the team name and will be included in the message.
Each player responds "[Hand] ready to start".

Dealing

At the start of each board, the Table Manager sends to each player "Start of board".
Each player responds by sending "[Hand] ready for deal". The message must not be sent before receipt of the "Start of board" message.
The Table Manager (having set up a deal) sends information about the deal to each player.
The deal information, consisting of four elements, is in the following format :

"Board number [a number determined by the Table Manager]"

"Dealer [the name (North/South/East/West) of the dealer]"

"Neither vulnerable", "N/S vulnerable", "E/W vulnerable" or "Both vulnerable" (as appropriate)

Each of the first three elements is separated from the next by a full-stop (ASCII #46) and a space (ASCII #32).

As always, the entire string is terminated by #13#10.
Each player sends "[Hand] ready for cards".
When all four hands are ready for their cards, the Table Manager replies to each hand with :

"[Player]’s cards : [player’s hand]"
A hand of cards is in the following format :

The first letter of the suit (S, H, D or C) followed by a space (ASCII #32). Preferably, the suits should be specified in that order (spades, hearts, diamonds, clubs).

The initial letter of the value of each card in the suit (A K Q J T 9 8 7 6 5 4 3 2). Note that 10 is represented as T so that each card is a single character. Each character is separated from the next by a space. The cards should be specified in descending order.

The last card in each suit is followed by a full-stop.

A void suit is indicated by a dash (ASCII #45).

Bidding

A bid is the following format :

The message starts with [bidder’s name] followed by a space.

The bid is "passes", "doubles", redoubles" or "bids " [level] (as a digit) + [trump letter-string (S, H, D, C or NT)].

If appropriate, the bid is followed by alert information (see next section).
Dealer makes an opening bid.
Each player (other than the next player to bid) sends "[Player] ready for [bidder]'s bid".
The Table Manager re-transmits the bid to the other three players. If the bid has been alerted (see below), the Table manager re-transmits the alert and associated information to the bidder's opponents, but not to the bidder's partner.
The next hand bids.
This sequence continues until the auction is complete.
If the hand is passed out, each player sends "[Player] ready for deal" to the Table Manager and the sequence re-commences as above.
If the Table Manager receives an illegal bid, it will ignore it and respond "Illegal bid" to the bidder. It is assumed that playing programs will ensure that they do not make illegal bids so, at this stage in development, the protocol does not define what will then happen.

Alerting (introductory note)

In standard bridge played between humans, a bidder's partner is required to inform his/her opponents of an artificial bid or call (as defined by the laws of bridge). Such a bid or call is referred to here generically as an "alertable bid" (i.e. to include non-penalty doubles and redoubles). The next hand may then ask the bidder's partner for information about the bid or call.

In computer v computer and computer v human bridge, the World Bridge Federation and the American Contract Bridge league have decided that the bidder should alert its/his own bid and provide information about the bid. Bidder's partner should not be made aware of the alert nor of any information provided by the bidder.
In order to avoid the complication either of human intervention (where the computer's operator decides that his/her program does not understand the meaning of an opponent's bid) or of a decision-making process by the program making the next bid, it is proposed that the next bidder will be deemed always to ask for information about the alertable bid.
This protocol does not specify which bids are to be alerted or what information is to be given; nor is it concerned with the penalties for failing to alert or failing to provide correct information about a bid. Those are matters for the relevant conditions of contest. The Table Manager will not validate the alert. Any dispute about the need for, or accuracy of, an alert should be referred to the tournament director outside of the Table Manager system.

In passing, it should be noted that the general laws of bridge provide that the information required to be supplied is only information which has not already been disclosed as a result of earlier bidding. If bidder voluntarily gives additional information, that is acceptable within this protocol (although unnecessary).

Alerting (implementation)

An alertable bid is in the following format : [bid (as defined above)] [space] "Alert." [full-stop (ASCII #46) space] followed by information as defined in the next section.
Alert information consists of one or more of :

"[n] cards in [suit]" (repeated for each relevant suit)
"up to [n] cards in [suit]" (repeated for each relevant suit)
"at least [n] cards in [suit]" (repeated for each relevant suit)
"[n1] to [n2] cards in [suit]" (repeated for each relevant suit)

"[n] total points"
"up to [n] total points"
"at least [n] total points"
"[n1] to [n2] total points"

"[n] points in [suit]" (repeated for each relevant suit)
"up to [n] points in [suit]" (repeated for each relevant suit)
"at least [n] points in [suit]" (repeated for each relevant suit)
"[n1] to [n2] points in [suit]" (repeated for each relevant suit)

"[n] total aces"
"[n] total kings"
"ace of [suit]" (repeated for each relevant suit)
"king of [suit]" (repeated for each relevant suit)

"Asking for aces"
"Asking for kings"
"Asking for a major suit"
"Asking for a four-card major suit"
"Asking for a five-card major suit"
"Asking for a minor suit"
"Asking for a four-card suit"
"Asking for support"
"Asks for lead in [suit]"
"Asks for lead not in [suit]"
"Forcing for one round"
"Forcing until game"
"Promises a rebid"

Note : please suggest further items required for the "asking/forcing" bids.
The message is a single string. Each element is separated from the next by a comma (ASCII #44) and one space. The string is terminated by a full-stop.
Alternative meanings : if a bid may have an alternative meaning, each additional complete conjunctive statement after the first should be started by "Alternatively," and terminated by a full-stop (ASCII #46), for example :

"3NT Alert. 8 to 14 total points, 8 to 10 points in clubs, up to 6 cards in clubs. Alternatively, 8 to 14 total points, 8 to 10 points in diamonds, up to 6 cards in diamonds."

Note that this is not necessarily an accurate description of a gambling 3NT opening bid, but simply used as an example. Note also the repetition of "8 to 14 total points" because it applies to both cases.

It is envisaged that bids with more than three alternative meanings would not be permitted by the conditions of contest.
A future possible extension of the protocol might be that simple alternative information could be given by including a single "or" between the two numbers.

For example, 5C after a Blackwood 4NT bid may be defined as "5C Alert. 0 or 4 total aces". However, to avoid the complication of interpreting multiple "ors" or priorities between "and"s and "or"s, only one "or" may be included in a segment of information, and that, only between numeric values.
Points refer to the Milton Work count (Ace = 4, King = 3, Queen = 2, Jack = 1), adjusted as required for length, shortages, etc. Where an adjustment is made, the bidding program's human operator must be prepared to justify the adjustment in case of dispute.
n1 must be less than or equal to n2. For total points, n is in the range 0 .. 50 (40 Milton Work points + up to 10 points for distribution). For suit points, n is in the range 0 .. 15 (10 Milton Work points + up to 5 points for distribution). For card length, n is in the range 0 .. 13.
The name of any convention producing the alertable bid will not be mentioned. Not only would naming the convention add extraneous information, but it will imply a requirement to have prior understanding of the meaning of bids under that convention.
Opinions please : should the elements of the alert message be in a fixed order ?

Pausing for manual alerting

As an interim stage to fully automatic alerting, it has been decided to implement three variations of optional "manual alerting", i.e. to be used where the bidding computer does not itself make the alert and produce information about it.
In the first variation, the Table Manager will pause after every bid except for those detailed below and will wait for the operator to input whether or not the bid is alertable. This information will be provided by the bidding computer's operator. In the second variation, the Table Manager will pause only if the bid is suffixed by the keyword "Alert". In the third variation, the Table Manager will pause at the end of the auction.
If the bid is not alertable, the pause is released and bidding continues.
If the bid is alertable, an input dialog with be displayed on the Table Manager's computer for the entry of information (provided by the bidding computer's operator) in the format described above. The Table Manager will convert the input into an alert string as described above and will transmit it to the bidder's opponents. When bidder's left-hand opponent is ready (i.e. after right-hand opponent is ready), it will make the next bid. Whether the alert message is parsed automatically by the receiving computer or manually by its operator is of no concern to Table Manager.
No information beyond that defined in the protocol will be requested or given.
Table Manager will not pause after the following bids :

After any pass except
>> Z - (Z) - pass
>> Z - (?) - ? - (Z) - pass
where
>> means any prior bidding
Z means any bid or double or redouble (and each Z may be different)
? means anything

In the following definitions :

X means a suit and, where relevant, lower-ranking than Y
Y means a suit higher-ranking than X
B means any suit
NB means No Bid
Db means double
Any passes before the first bid are ignored

1X
1N
1X - (NB) - 1Y
1Y - (NB) - 2X
(1Y) - 2X
(1X) - Dbl
1X - (1Y) - 1B
1X - (1Y) - 1N
1X - (Dbl) - 1Y
1X - (Dbl) - 1N

unless inverted minor raises are being used :
1X - (NB) - 2X
1X - (1Y) - 2X
1X - (1N) - 2X
(1X) - 1Y - (NB) - 2Y (but pause for (1X) - 1N - (NB) - 2Y)

unless negative doubles are being used :
1X - (NB) - (1Y) - Dbl

Playing

At the start of each trick, the Table Manager sends "[Player] to lead" to the leader or, if dummy is to lead, "Dummy to lead" to declarer. The leader (or declarer, if dummy is to lead) must not transmit its card (see next item) until it receives this message. The reason is to prevent synchronization errors if the leader to the current trick was the last player to the previous trick and sends the lead card to the next trick before the Table Manager has completed its housekeeping for the preceding trick. For the same reason, Table Manager will pause for one second at the end of each trick before sending the ".. to lead" message to enable the leader to the next trick to complete its end-of-trick housekeeping.
Opening leader sends "[Player] plays [Card]" to the Table Manager.
[Card] is in two character format [A K Q J T 9 8 7 6 5 4 3 2] + [S H D C]. (Note : an alternative suggestion is [suit] + [value]).
Each hand which is not the player sends a "ready for card" message to the Table Manager as follows : declarer and the defenders each send "[Hand] ready for [Player]'s card to trick [trick number]" and dummy sends "[Hand] ready for dummy's card to trick [trick number]". Note that dummy will send this message for every card, since declarer will be the player of dummy’s cards.
The Table Manager sends "[Player] plays [Card]" to the other three players.
If the Table Manager receives an illegal card, it will ignore it and respond "Illegal card" to the player. It is assumed that playing programs will ensure that they do not play illegal cards so, at this stage in development, the protocol does not define what will then happen.
Strictly, it is not necessary to notify dummy of any cards played, but this is done by the Table Manager so that dummy’s screen can be updated during play.
Players other than dummy send "[Player] ready for dummy" to the Table Manager.
The Table Manager sends dummy’s hand to the other three players. The format is "Dummy's cards : " + [dummy’s hand] (in the format described above for a player’s hand). In a previous version of the protocol, players confirmed receipt of dummy's hand by sending to the Table Manager "[Player] received dummy". That requirement has now been removed from the protocol. Players should simply ensure that they do not transmit the "ready for [dummy's] card to trick 1" message until they have received (and, if necessary, processed) dummy's cards.
If it is dummy’s turn to play a card, declarer sends to the Table Manager "[Dummy] plays [Card]". Otherwise, the player sends to the Table Manager "[Player] plays [Card]".
The Table Manager sends "[Player] plays [Card]" to the other three players and the ready-plays-echo sequence continues until all 13 tricks have been played.
At the end of each hand, the Table Manager will send timing information to each hand in the form : "Timing - N/S : this board [minutes:seconds], total [hours:minutes:seconds]. E/W : this board [minutes:seconds], total [hours:minutes:seconds]".
To maintain synchronisation among all hands, every card is played and no assumptions are made about e.g. following with the last card held in a suit or claiming closing tricks.
It is assumed that programs will track the bidding and play locally if required, so the result and/or score is not transmitted to each hand.
The cycle is repeated until the designated number of boards have been played.
The Table Manager sends "End of session" to each player.
After a short pause, the Table Manager then disconnects each player from the network.

Claiming

It has been suggested that the protocol should include provisions for programs to make and accept claims for remaining tricks. Bearing in mind the speed of computer-players (particularly in the closing tricks) and the fact that a program receiving a claim has nothing to lose by rejecting it (in case the claiming program makes a mistake in the play-out), it is not considered necessary to include claiming in the protocol. Nevertheless, with a view to the possible future extension of the protocol to humans playing computers through an interface, the following is proposed (but not yet implemented).
A player wishing to claim the remaining tricks sends to the Table Manager "[Player] claims".
The Table Manager transmits "[Player] claims" to the player's opponents (if they are defending) or to the declarer (if the claim is made by a defender). The message is sent to dummy for information only so that, for example, it may update its display.
The Table Manager also transmits the claimant's hand (see above for format).
The recipient (but not dummy) responds "[Hand] accepts [Player's] claim" or "[Hand] rejects [Player's] claim".
If the claim is accepted by both defenders or by declarer (as appropriate), the Table Manager sends "[Player's] claim is accepted" to declarer and both defenders. Otherwise the Table Manager sends "[Player's] claim is rejected" to them.
If the claim is rejected, play continues.
If the claim is accepted, the Table Manager will treat the remaining tricks as having been won by the claiming player's partnership and will prepare for the next board as if the cards had been played out. The playing computers should do the same.

Taking-back of bids and cards

The taking back of bids and cards is not a normal part of bridge, but the matter has been raised, again in the context of humans playing against programs.
Allowing taking-back presents considerable problems for synchronisation of network messages. It is therefore proposed that taking-back will not be allowed within this protocol.
There is, of course, nothing to prevent a local program from pausing between the time that the interface operator enters his/her bid or card and transmitting the message to the Table Manager. If the operator wishes to retract the bid or card during that interval, that can be handled locally and the Table Manager will not be involved.

We have produced a development prototype of the Table Manager program which is now undergoing testing. Please contact us if you would like further information. Pending feedback from interested parties, no changes have yet been made to the program for Claims.

The prototype Table Manager is supplied (entirely at the discretion of Blue Chip Bridge Ltd) on an "as is" basis only. It is for the personal use of the recipient as a prototype and it is not to be redistributed. Full copyright and other intellectual property rights are reserved by Blue Chip Bridge Ltd.

IMPROVEMENTS

There are a few issues which need further consideration :

Whether the Table Manager should notify the players of the total number of boards at the start of the session ?
Whether time-limits should be imposed on the players ? To avoid complications over transmission speeds and the like, the prototype Table Manager program times each player’s response per bid/play and also keep running totals. It would then be a matter for the human participants to decide whether a participant should be penalized for unacceptable delays.
How to ensure that messages are correctly received ? TCP/IP is generally considered to be a reliable protocol and acknowledgement messages should theoretically not be necessary.
How to handle network time-outs and failures ?
How to handle bidding/play out of turn ?
How to handle illegal bids/cards ?

NETWORKING OF COMPUTER BRIDGE PROGRAMS

A PROPOSED PROTOCOL FOR INTER-PROGRAM COMMUNICATION

Version 18 (1 August 2005)(latest revisions will be shown in red)

Version 18 (1 August 2005)
(latest revisions will be shown in red)