NetSpades
=========

Welcome to NetSpades, a client/server implementation of the card game
spades.  Spades (known in some places as 500) is a four-player, team-based
game whose object is to be the first team to score 500 points by bidding on,
and taking tricks.  NetSpades includes the server program, a console-based
client (using the SLang library), and an X-based client (using the GTK
library).

For those of you not familiar with the rules of the game, please read
Appendix A at the end of this file.

Enjoy!
--Brent Hendricks <brentmh@ece.rice.edu>
http://www.ece.rice.edu/~brentmh/spades


Running the server
==================

Although you can play in "off-line" mode against computer opponents, it is
much more interesting to play in networked-mode, with humans (provided you
know a couple interesting ones).  NetSpades is a client/server application,
so in order to play across a network, the included spades server must be
running somewhere. This can be your local computer or a remote computer.
Only one server needs to be running for you to play, and a single server can
handle several games. Start the server by invoking the command spadesd.

Usage: spadesd [-V] [-l] [-p main_port] [-t taunt_port]

The -V option will cause spadesd to print the version number and then exit.
The -l option causes spadesd to log all game transactions to stdout. 
The -p and -t options are used to tell spadesd which ports to monitor for
incoming transactions.  NetSpades requires two ports: one for the basic
spades game and one for a special message server called the TauntServer(tm).
*Note* If you do not specify port numbers, spadesd will use the defaults:
7626 and 7627.


Running the client
==================

I have included both a console mode client (using the SLang library), and an
X client (using the GTK library).  If you do not have one of these
libraries, you will not be able to compile and run that particular client.
If you don't have either of these, you will not find NetSpades to be very
enjoyable as it is rather boring just to watch the server run.  

The clients are named slspades (for the SLang version) and gspades (for the
GTK version).  The following information is common to both clients.  For
specific information about either of these programs, please see their
repective READMEs (README.slang and README.gtk).  A Win32 spades client is
progressing nicely 
(see http://www.cse.msu.edu/~hudsond2/programming/programming.html), 
and I've heard rumors of a Java client, but I haven't seen any code yet.

Usage: CLIENT [-V] [-o] [-n name] [-s server] [-p main_port] [-t taunt_port]

where CLIENT is either slspades or gspades.

The -V option will cause the client to print the version number and exit.
The -o option is for offline (non-networked) play.
The -s option tells the client where the spadesd program is running.  If you
are going to be playing across a network, you must let the client spades
program know where the server is running, but this can be done in several
ways:

First, you may set the environment variable SPADES_SERVER to the name of the
host which is running the server.  This is a good option if you know someone
who always has the server running.  Just set this variable in one of your
login scripts. 

Second, you may specify the name of the server machine using the
aforementioned -s commandline option.  Note that the server specified on the
command line will override any environment variable settings.

If you haven't specified a server using either of the above two methods, you
may enter one into the client once it is running.

You can also specify your name on the command line with the -n option. This
should be an 8 character name which will appear as your player name to all
four players.  If you enter more than 8 characters, it will be truncated.
If you don't give a name on the command line, the client will default to
your login name.

The -p and -t options tell the client on which ports the spades server is
operating (see above).  The default values of 7626 and 7627 respectively,
will be used if none are specified.

If you choose to play offline, you may begin immediately.  Otherwise, the
spades program will attempt to register you with the specified server.  Any
number of player from one to four may play in a spades game.  The first
player to register is allowed to choose game options, select how many and
which players will be human or computer.


Setting Options
===============

There are (at this point) only a few options which are able to be set.
These include the minimum team bid (default of 3), the score at which the
game ends (default of 500), and which players will human players.

If you are playing off-line, then you set the game options and begin. Things
are a little more interesting during network play, however.  Only the first
player to register is allowed to set options for that game.  So if someone
registers a game with the server where two players are human and the the
rest computer, the next player to register will be the second human player
and the game will start, ignoring the options requested by the second
player. 

This seems a little odd, I know, but it was the only way I could do it and
maintain backwards compatability with previous client versions.  The
upcoming version 5 of NetSpades will have a much better registration system
where you can view all registered games select your game based on options,
or start a new one if you so desire.  In the meantime, try to agree on the
rules with your friends before registering.


Multiple Games
==============

spadesd can handle serving multiple games simultaneously.  This should be
invisible to the players of any particular game.  The number of games
capable of being handled by spadesd is a compiled-in value, and is set by
the value of MAX_GAME in the file engine.h


NOTE: GtkSpinbutton source
==========================
The files gtkspinbutton.h and gtkspinbutton.c were taken directly from a
snapshot of the gtk+ library sources.  I slightly modified gtkspinbutton.c
for the location of the includes, and I modified the copyright to refer to
GNU General Public Licence (since NetSpades is distributed under the GPL) as
per Section 3 of the GNU LGPL.  As soon as GTK1.3 is released (and is
relatively stable) I will depend on that and no longer distribute these
files.


Appendix A - Playing Spades
===========================

NetSpades was written so that I could play spades with my friends from
school.  It therefore uses our house rules for playing.  Here is a brief
summary of the way we play spades (Thanks to Doug for this section!)

   
Spades - 2AB Bryan Style:
   
   
General Overview

Spades is a card game played with a standard fifty-two-card deck and four
players. The players partner up in two teams of two players each. The
players sit in a circle with the two players for each team facing each
other. The object of the game is to be the first team to reach 500 points or
more. A spades game consists of hands, and a hand consists of 4 stages: the
deal, bidding, playing tricks, and scoring.


The Deal


At the beginning of the game, one player is chosen to be dealer. After the
end of each hand, the deal passes to the left. The dealer shuffles the deck
of cards and deals thirteen to each player however he wishes.


Bidding


After the cards have been dealt, each player bids on his hand, starting with
the player to the dealer's left and continuing clockwise. Each player only
bids once, and no player may pass. A player's bid represents the number of
tricks a player thinks he or she can win in a hand.

The combined bid of both players on a team, or team bid, is the number of
tricks that that team must take in order to score points. (See Scoring) Each
team must bid a minimum of at least 3 tricks for every hand.


Tricks


For each of the 13 tricks, one player plays a card from his or her hand.
Then each other player does the same, one at a time, clockwise around the
circle. When each of the 4 players has played a card, the winner of the
trick is determined. The cards are removed from the playing area and the
winner leads (plays the first card) the next trick. For the first trick in a
hand, the player on the dealer's left leads. During any trick, each player
must play the same suit as the player who led the trick if he or she can. If
the player can not "follow suit", then the player may play any other card in
their hand.


Winning Tricks


For any trick, the highest card (2-A) in the suit that was led takes the
trick. If spades are played on any trick, then the highest spade wins the
trick. (For those of you who have ever play Euchre, just think of spades as
always being trump.) An example:


Player A (lead): 10 of Clubs

Player B: J of Diamonds

Player C: 2 of Spades

Player D: 5 of Spades

Player D wins the trick. Player B's Jack is higher than Player A's 10, but
it isn't a club, so it's worthless. Player C's 2 of spades beats Player A's
10, but Player D's 5 of spades beats Player C's 2 (and A's 10).

Scoring


At the end of every hand, each team counts up the number of tricks it took
and compares that to its bid. If a team takes fewer tricks than they bid,
then that team loses 10 times the number of tricks they bid in points. If a
team takes exactly the amount they bid, then they gain 10 times the number
of tricks they bid in points. If a team takes more tricks than they bid,
they gain 10 times the number of tricks, plus one extra point for each trick
taken over what they bid. These extra tricks are commonly referred to as
"bags." For every 10 bags that a team takes, that team loses 100 points.

The game is over when one team reaches or exceeds 500 points. If both teams
exceed 500 points, then the team with the higher score is the winner. If
both teams are at or over 500 and are tied, then another hand is played
until a winner is determined.

An example of scoring: Say Team B has 231 points and Team C has 479 points.
Team B bids 4 tricks and Team C bids 7 tricks. Team B takes 3 tricks and
Team C takes 10 tricks. Team B goes from 231 points to 191 points (231-40
for losing bid = 191). Team C goes from 479 points to 452 points (479 + 70
for making bid + 3 for bags - 100 for taking 10 bags = 452.)


Bidding nil


If you have a hand where you think that no one can force you to take a
trick, instead of bidding a number of tricks, you can bid 'nil'. If you bid
nil and take zero tricks, your team gains 100 points plus or minus any other
points for the hand. If you bid nil and take any number of tricks, your team
loses 100 points plus or minus any other points for the hand. Remember that
each team must bid at least 3 tricks. If your partner bids first and bids
zero, one, or two, you can't bid nil. On the other hand, if your partner
bids first and bids nil, you must bid at least 3.