NETWORKING OF COMPUTER BRIDGE PROGRAMS
A PROTOCOL FOR INTER-PROGRAM COMMUNICATION
Version 18 (1 August 2005)
(latest revisions will be shown in
- 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
- 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
- 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
- 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
- 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.
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.
- Ready for team names
- Team names
- Ready to start
- Start of board
- Ready for deal
- 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
- 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]
- 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".
- At the start of each board, the Table Manager sends to each player "Start of
- 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).
- 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).
- 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
- 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
- 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
- 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
- Table Manager will not pause after the following bids :
After any pass except
>> Z - (Z) - pass
>> Z - (?) - ? - (Z) - pass
>> 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 - (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
- 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
- Opening leader sends "[Player] plays [Card]" to the Table
- [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
- 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
- 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
- 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
- The cycle is repeated until the designated number of boards have
- The Table Manager sends "End of session" to each player.
- After a short pause, the Table Manager
then disconnects each player from the network.
- 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
- 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.
- 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
- 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
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 ?