**************************************************
                    PoKeR                         
**************************************************

Table of contents

0. Disclaimer
1. Introduction
2. A guide to the game
3. Poker rules at Global Village BBS
4. Policy for playing the game
5. Internal functionality and code problematics
6. Numbers and Credits


Chapter 0.
Disclaimer

As any software, the Poker game may contain bugs, even when it was designed
to work correctly, and tested with the utmost care. Therefore Global Village
BBS can NOT BE held responsible for the loss of CUBES caused by bugs in the
game, or for any other inconvience a bug in the game may cause to its
players. There is no way to reclaim CUBES being lost!

Money games can cause addiction. Global Village BBS can not be held
responsible for any negative influences on poker players or the people in
their surrounding.

By entering the game, the user accepts this, as well as the game's special
rules (chapter 3.) and the game policy as stated in chapter 4. Poker players
accept that they are using the game on their own risk.
Violations of the game policy are being handled according to chapter 4 and 
the BBS Policy.

This document may contain errors. Global Village BBS does not guarantee the
information contained herein to be correct, and cannot be held liable for
any inconvience resulting out of errors in this document.


Chapter 1.
Introduction

For a long time, it was the programmer's intention to code a poker game for
public use. But time was low very often, and admittedly for a long time, the
programmer's coding abilities were not enough to program a game of that
scale. But finally, program development came to an end, and the result can
be seen by pressing <SHIFT>-<S> <2> or using <SHIFT>-<M> <S> <2> at the
BBS prompt.

Poker is a game with history: Originally, it evolved in Europe in the 16th
century, but it used to be played with three cards at that time. Later, by
beginning of the 18th century, it was usually played with five cards.
In the 19th century then, the game was carried to America where it reached
its highest popularity soon. Since 1834, the game is played with the
52 card set.

There are an uncountable number of variations to that game, with the
principal forms including Draw Poker and Stud Poker (closed respectively
open games). Every place where you might go, this game is played in a
different way, even depending on the people who you play with.
For coding this game, certain rules had to be established and put into
the program, so that no discussion of rules would ever have the chance
to evolve. Most often a rule discussion is encountered when the winner
should be determined among hands of the same rank. Global Village BBS'
Poker game uses page-long mathematical comparison and equality conditions
to determine the winner in these cases.
The game coded in here, most closely represents the "European form of
Draw Poker". The European form of Poker is given by the fact that the
low cards (2s, 3s and 4s) are taken out of the pack, thus a Straight can
be formed by 8-7-6-5-A with the ace used as low card, and that Flushes
rank above Full Houses. The first condition is coded in; we are using
a set of 40 cards with all 2s, 3s and 4s taken out of the pack, but the
second one isn't: Full House still ranks higher than a Flush.
There are several other exceptions, these can be read in chapter 3.

A discussion about the rules of the game is undesirable. The rules are
stated clearly and included in the program so that no questions have to
remain open. The rules were put together by merging a written explanation
of the Poker game from the Encyclopaedia Britannica, Macropaedia, 15th
edition, year 1974, volume 14, pages 623ff, together with personal
experience from the programmer of the game, and program-technical
requirements.


Chapter 2.
A guide to the game

The game may be invoked as stated in the first paragraph of chapter 1.
After invokation, the game will
- either give a message that nobody is currently using the poker game,
- or display the names of the persons sitting at the poker table.

If the number of people at the poker table has reached the maximum number
of players, which is FIVE, the game session will terminate at this point.
When less than five players are at the table, the program returns a yes/no
prompt, asking whether it is desired to join the table, or to sit down there
waiting for other people to join (in case of zero users playing the game).

Generally, it should be said that a single user who would like to play a
game of Poker, should either try to join an existing poker session, or to
find some players (possibly by using X-messages), BEFORE invoking the game.

After joining the poker table as a such, the game screen shows up.
Please note that the whole game uses terminal escape sequences to give a
better game impression (and make the game as a such even possible). These
terminal escape sequences may cause problems with incompatible terminal
programs or CLient programs! This is also stated in a sentence which is
displayed upon entering the casino menu. If you happen to experience
problems, there is only one workaround: get yourself another terminal
program or CLient: 95% of these work correctly.
Note: when your terminal program freezes after joining the game, this
might also be due to incompatibility issues.

---

The game screen:

The game screen is parted into 7 different areas, which are in sequence
and position:
(1) Opponent's area [upper left corner]
(2) Game information area [upper right corner]
(3) Player's area [mid left]
(4) Command area [mid right]
(5) Status line [below Player's and Command area, a single line]
(6) Message area [lower half of the screen]
(7) Message input area [the last line of the screen]
(8) X-Message-Counter [the line between (1) and (3)]

These areas are used for the following displays:

2.1. Opponent's area

In this region, the names of all opponents in the game, are being displayed.
If the opponent is active, i.e. a game is in progress and the opponent is
still allowed to compete for the pot, this area displays the cards of the
opponent, hidden and symbolized with a "[?]" sign. If the game is over and
a showdown has been invoked before, the player's name is displayed along
with his revealed cards.
If a user leaves the table, his entry in this region is removed and the
seat at the poker table is free again.

2.2. Game information area

Here, four different informations are on display:

First, the name of the so-called "Master". This is the person who is the
first player in every interval being played, and during a game, a game-master
must ALWAYS be an active player. If the current game-master passes during a
game, the game-mastership is passed on to the next player in turn. Other
conditions for passing on this privilege, include:
- The game-master is changed after every game being played
- A timeout of three minutes is in effect when there is no game in progress
  and the game-master is not starting a new game. Mastership is passed on
  after these three minutes.
Due to the nature of the "passing-on", it is possible that a person is the
game-master of two consecutive games, i.e. when he passes during the game,
then the privilege is passed on, and after game handed back to him (always
under the condition that no new users were joining the poker-table).
The game-master is the only person who may start a new game!

Second, the name of the player who is currently in turn, can be seen in
that area of the screen. When there is no game in progress, this line
reads "NO GAME".

Third, the pot is being displayed. This is the sum of all money that was
put in the game by the players since the start of the game. When there
is no game in progress, this line reads "NO GAME".

And finally, the current round is on display. The possible variations
displayed here, include:
1 ................... the first round, the first betting interval
DISCARDING INTERVAL . during this interval, a user may discard a number
                        of zero up to three cards, and receive replace-
                        ments for them
3, 4, ... 32699 ..... the n'th round, or betting interval. The showdown
                        does not start before one of the players has
                        requested seeing hands, or the round 32700 is
                        reached, when the showdown begins automatically
SHOWDOWN ............ every user who wants to compete for the pot, has
                        to show his cards to the other players

2.3. Player's area

This area allows three basic kinds of displays:
- Five cards, all face down: no game is currently in progress
- An information message, saying that you may join the next game: this is
  invoked when you pass in the game because of one of several reasons, or
  when you join the poker table while a game is already in progress. In
  this last case, you can view everything which is going on, but not
  participate before the game is not over and a new one is started.
- Five cards, face up: a game is in progress; THESE ARE YOUR CARDS!

2.4. Command area

This area shows the commands which are at that certain point of time avail-
able to the player. 

There are two commands which are always available:
[.] Send a chat message
[X] Exit the game

Other commands which might show up at another point of time:
[S] Open the game [game-master ONLY]
[B] Place bet
[P] Pass
[1] - [5] Discard cards
[D] Done, continue
[H] See hand!
[R] Reveal hand

Commands may only be used when they show up as available option.

The command area is also used as additional information display.
y/n questions pop up there, as well as error messages which tell the
player why something is taking place at the moment.

2.5. Status line

The left part of this line displays the player's (=your) name, along
with the actual amount of CUBES you have. The CUBES value is updated
every time when a change of CUBES within the poker game takes place.
Therefore this display might sometimes change by more than the amount
of CUBES you used at the poker table, simply because of receiving
CUBES for online time, or stock updates taking place.

The right part of this line might display a clock. When you are the
game-master and have not started a new game yet, the clock counts down
from 3:00 minutes to 0:00, afterwards hands over the game-master
privilege, if there is another player to hand it over to.
When you are the user at current turn, this clock counts down from
1:00 minutes to 0:00, afterwards either invoking auto-passing if you
should place a bet (in this case you are OUT of the game!), or just
giving the game control to the next player in turn, if there is a 
discarding interval or the showdown.

2.6. Message area

The message area is a circular system, programmed after the good-old UNIX
"talk" program. A maximum of ten messages are displayed there at a time,
including system messages (marked with [SYSTEM]), informational messages
(marked with [INFO]), and user messages (marked with the user name in
parentheses []).
The newest message is preceded by an arrow "->", and additionally the
oldest message is deleted from the screen (if there are more than 10
messages on display) to make the output more legible.

2.7. Message input area

When the [.] key is pressed, which may be done at any time when sitting
at the poker table, the user name shows up in this line, and a message
may be entered there. Sometimes, due to timeouts taking place, the system
response to entering messages there, might not be immediate and a short
delay of one up to four seconds may take place. This is not a bug.

2.8. X-Message-Counter

In this area you see a counter if you receive x-messages during the game.
Login and logout-messages, messages telling you that someone profiled you 
or is going to write you a message, aren't received during the game. 
But you can read all other messages after leaving the poker-table.
Everyone who wants to send an X-message to you, is informed that you are 
playing poker and that it might take a longer time until you will answer.

---

Game start and betting intervals:

The game-master is the only person who may start a new game, and this 
only when no game is currently in progress.
When a new game is started with [S], the game-master becomes the current
player, and the one-minute timeout starts.

At the very same moment, everyone who is sitting at the table right then,
becomes an active player, and 10 CUBES are subtracted from his cash, 
which adds up to the initial pot.
If a user at this phase is found not to have the required 10 CUBES (and
this may even be the game-master himself!), he becomes inactive again
without further notice. Therefore it is not at all of use to sit at the
poker table with less than 10 CUBES: You are just blocking a seat!

When being the current player, you may place a bet by pressing the [B] key.
The maximum or minimum values for bets are determined the following way:
- The maximum bet is 200 CUBES, or if the user does not have that much, his
  maximum number of cubes in cash
- The mimimum bet is always the number of the previous bet, or 1 if there
  has not been a previous bet.

Due to these conditions, the maximum bet could be lower than the minimum
bet. In this case, the user is taken out of the game by the system, acting
as if he had passed by himself. The user is informed of this by both a
message in the Command area and the Message area, which is also received
by the other players.
The same thing happens when the timeout of one minute is exceeded without
placing a valid bet.

Bets are done by entering numbers. If it is desired to just call the bet,
not raise it, it is enough to press the [ENTER] key as soon as the bet
prompt appears.

Beginning from round 3, a user who wants to see the other player's hands,
may document his desire by using the [H] key instead of the [B] key.
However, the pressing of the [H] key must be followed by a valid bet within
the limits of the timeout to be accepted by the system.

Bets are always subtracted from a player's cash in the very same moment
when the bet was confirmed. This means that you cannot avoid loss of CUBES
by exiting the game with [X] at a later point of time!

When being the current player, pressing [P] is also an available option.
This causes the system to pass (drop cards and no longer compete for the
pot) and give control to the next player in turn. The [P] option is
preceded with a y/n prompt to ensure that the key was not pressed in error.

---

Discarding interval:

During the discarding interval, a user has one minute time to discard none,
one, two or three of his original cards and receive replacements from the
undealt portion of the card pack.
If the discarding of cards is desired, you select the cards you want to 
discard with the keys [1] thru [5]. A card selected to discard is turned 
face-down. If you want to change your mind, you can turn it face-up again 
by pressing the same key a second time. After you are sure you made the 
right choice, you can discard all selected cards with the key [D].  
Cards are always automatically sorted by their rank, highest at the 
right, lowest at the left. This sorting of cards does also take place 
after your turn during the discarding interval is over, which might cause 
confusion, but it's important for the progress of the game. 
As soon as the key [D] is pressed to finish your turn, all cards are
on display face-up again. The same happens when the timeout is exceeded.

---

Showdown:

The showdown is only invoked, if:
- either the showdown-request was stated by a user using the [H] key,
  followed by a regular bet,
- or there is only one active player left, along with at least one inactive
  player; in this case the active player has to show his cards to get the
  money from the pot (if he wants the money).

During the showdown, [R] is the only available option besides the two
standard options. With [R] you may reveal your cards to the other players
at the table. When the one-minute timeout is exceeded, this revelation is
taking place automatically, but the player still stays active.

---

End of game:

The game ends, when:
- there is no active player any more
- there is only one active player and no inactive players 
- after the showdown

As soon as there is no active player any more, the game is declared
finished by the system. All money in the pot goes to the system and may
not be reclaimed.

When there is only one active player left, the system will say so and
declare this one for the winner. But: For this taking place, there must
not be a single inactive player sitting at the table. If there are
inactive players, the game can only end after a showdown, or even after
a valid bet in the last round, followed by a showdown. This is no bug!
Only users who at least call the bet in the last round and reveal their
cards may compete for the pot. So please do not complain about having to
bet even when all players before you have passed, or about having to
show your cards: this is normal system behaviour, and everything else would
be unlogic.

After the showdown, the winner is determined among the active players, if
there is only one active player, he is the winner. In all other cases,
the winner is determined automatically, according to chapter 3.

The winner receives all of the money in the pot.
Afterwards, the pot is reset to zero, a new game-master is determined, and
after a period of 30 seconds, a new game may be started by the new game-
master. This period is necessary to give all players the time to check out
the revealed cards of their opponents, and furthermore to allow users who
don't want to take part in a successive game, to leave the table.

If the new game-master tries to start a game before this period has ended,
he will receive display of how many seconds he has to wait until this is
possible. In case of trying to start a game with only one player at the
table, the output will result in an error message.

---

Removal from the table:

A player is automatically removed from the table, if
- he is found to be not online any more
- the system detects that a user with the same name is already sitting
  at the table (yes, there is a condition when this can occur)
- a user's system process shows up with another ID than the one stored
  in the poker game memory area.
Checking on these conditions is periodically done by ALL system processes
of players sitting at the table, this means that in the worst case when
only one person is there, this checking takes place every 60 seconds, when
there are more players, then checking is done statistically more often.
Additionally, every time when a user joins the table, checking is invoked.
If a user is automatically removed from the table, all his game entries
are removed (his money stays in the pot), and the other players are
informed of the step taking place. Note: The removal from the table is
*NOT* sending the user back to the normal BBS prompt, but merely the
"purging" of a memory structure which believes that someone is there but
in fact isn't. Please note that just closing your telnet session or
your terminal window, results also in your auto-removal from the table.


Chapter 3.
Poker rules at Global Village BBS

No money comes from the system. All money in the pot is from the users
playing poker. Therefore, it is allowed to "work together", or "cheat"
with other users. As in real poker, two or more players might build a
team to defeat the other players. 
However, this does not mean that unfair means may be used which are
against the policy. Chapter 4 gives additional detail on this.

The game takes the following course:

(0) Ante
(a) First betting interval
(b) Discarding interval
(c) Additional betting intervals (one or more!)
(d) Showdown

During and after the showdown, the player with the highest ranking hand
is determined:

All suits are equal by definition. However, if two hands are completely
equal, then the suit is taken as the deciding factor of who has won.
In this case, and only in this case, the suits rank as follows (highest
first, lowest last):
'+', '*', '#', '-'.
This ranking of suits is only very rarely being used. A discussion about
using suits for ranking is not desirable. Bringing up such a discussion
can be the reason for a degradation within the BBS.

Cards rank: A-K-Q-J-10-9-8-7-6-5

The following rules of ranking (the lower the number, the higher)
and equality (described in the texts), are applied:

(1) Royal Flush

    Five cards of the same suit and in sequence, being exactly A-K-Q-J-10.
    Among two Royal Flushes, the one with the "higher" suit wins.

(2) Straight Flush

    Five cards of the same suit and in sequence, lower than a Royal Flush.
    The player containing the higher card in his Straight, wins. If both
    Straights are identical, the suit decides.

(3) Four of a kind

    Four cards of the same kind, regardless of suit.
    Among two players with four of a kind, the higher matched set wins.

(4) Full House

    Three of one kind and a pair.
    Among two Full Houses, the higher three of a kind wins.

(5) Flush

    Five cards of the same suit, regardless of sequence.
    Among two Flushes, the highest card wins. If these are identical,
    the second highest card decides, and so on. If even the lowest
    cards are identical, the suit of the highest card is the deciding
    factor.

(6) Straight

    Five cards in succession, regardless of suit.
    Among two Straights, the one containing the highest card wins.
    Please note that a straight may also be built with 8-7-6-5-A,
    in this case the ace being the low card; this Straight always
    looses to other Straights.

(7) Three of a kind

    Three cards of the same kind, and two others not being a pair.
    Among two of these, the higher matched set wins.

(8) Two pairs

    Two pairs, and a fifth card.
    Among two players having each two pairs, the highest pair decides,
    or if these are identical, the other pair. If these two are
    identical, the odd card is the deciding factor. If even the odd
    card proves to be equal, the player having the '+' suit among
    the cards of his higher ranked pair, wins.

(9) One pair

    One pair and three unmatched cards.
    Among two players having a pair, the higher pair wins, or if
    identical, the highest odd card. If that one is identical, then
    the suit of the highest odd card decides.
    Please note that the second and third highest odd cards are not
    part of deciding the winner in this case!

(10) High card or No pair

    This is a hand having no pair, ranked by its highest card or cards.
    The winner is determined according to the rules for Flushes.
    See (5) on further detail.


Chapter 4.
Policy for playing the game

The number of seats at the poker table is limited to five. Therefore, it
is essential that users are not BLOCKING the table when users want to
play. It is okay to use the poker game not for playing but the chat
function contained therein as a quasi-chatmode. But: When users want to
play, it is an offense to still stay there and continue chatting.
To sum it up: chatting YES, but please leave the table if people want to
play and you don't want to do so. 

Additionally, it is forbidden to stay idle for the period of two complete
successive poker games. What will happen (in the worst case), is the
following: Given that you are the game-master, other users will have to
wait three minutes until your privilege has passed on to someone else.
Then your first turn in the game will cause an additional delay of one
minute for the other people. Stuff like this is completely unnecessary and
definitely considered a serious offense.

Never be offending to other players. Don't use an offensive language or
a very aggressive kind of playing. Be nice to others and don't do to others
what you wouldn't like be done to your own!

Working together, i.e. "cheating" with other users at the table, is
allowed, since there is no money coming from the system. But this cheating
may only take place so far as two players are working together within the
rules. As soon as a known bug is exploited, the cheating is a serious
offense.

When a user detects a bug in the game which affects the course of the game,
and does not immediately report it, this is also a policy violation.

Policy violations are dealt with according to the normal BBS policy.
Sanctions may go from warnings to TWITS and even the deletion from the BBS!


Chapter 5.
Internal functionality and code problematics

This chapter may only be of interest to programmers or really interested
users. Normal users please continue reading in chapter 6.

This game features:
- a command system working with broadcast technique
- semaphore locking for multi-express-messages (i.e. broadcasting)
- terminal escape sequences
- redirection of the alarm() handler to an own game-function and recalling
  of the alarm() handler after game-exit
- decentralized game handling
- avoiding of reentrant functions

Commands between the processes are exchanged by making use of the broadcast
technique. The broadcast memory area is filled with the necessary command
data, and then the signal is sent to all processes. The problem with this,
however, is that the broadcast area is at the same time also used by a lot
of other system messages, i.e. the login-information ("ABC just logged in"),
and really a lot of other stuff. Therefore caution had to be taken that
these messages can in no case overwrite the command data of the poker game.
This was ensured by introducing semaphore-locking. The YAWC-code contains
a lock_function() which was part from the ISCA code (!). This function was
changed to also lock the broadcast area whenever a function is using this
memory areay. But since multi-express-messages never give a feedback signal
back, the sending process has to find out when its time to unlock the
memory region again. This is the weak point of the game (admittedly). It
is _impossible_ to find that out. Therefore, for normal broadcasts,
unlocking is done immediately after loading the memory structure with the
broadcast data, but for poker-command-messages, either containing important
game information, or chat data, or even the vital process information
about who is going to be next in turn, the structure is unlocked after a
timeout of 350 milliseconds. This causes the following behaviour: The
processes of the people playing the game have enough time to read the data
from the structure, and additionally, the structure may not be loaded by
either another poker game message or a broadcast-like message from the BBS
during that time. This way it is ensured that the messagee arrives where it
should, at just the small cost of a delay of 1/3 of a second.
But it is possible that the message does not arrive in 10042f all cases.
If the message is by accident a vital game information, the game will stall
immediately, possibly not being able to reactivate itself by making use of
the auto-purge functions. Users might note this and leave the poker-table
to enter it again. Except under special testing conditions, the vital
command and message data did always arrive at all poker player processes,
which gives the programmer enough positive feedback to believe that stalls
of the game might either never or hardly ever really take place.
A variant was tried, in which the process currently in turn, sends a signal
(a direct X-message, so-to-say!) to the player next in turn. However, this
did not work as well as the broadcast method. It used to be unstable and
made the code crash because of non-avoidable reentrant calling of the
sendx() and catchx() functions, respectively.

Terminal escape sequences are being used for a better game impression. They
contain just a handful:
- clear screen
- clear to end of line
- go to cursor position X,Y on screen
- save cursor position
- restore cursor position
Problematic is the use of these sequences only in the cases when the
user's terminal is in no way ANSI-compatible. But most terminals are,
thanks God. Some aren't, but it should not be the intention to limit
the game impression for 9942f all users, only to satisfy the need of
a minority.

Redirection of the alarm() handler: Normally, during a BBS session, every
60 seconds a function is called which does check for idling and other
important stuff. There may only be ONE alarm() handler active at one time.
But the alarm() handler was needed to realize the timeouts during the game,
and to display the clock(s). The workaround was as follows:
Upon every invokation of the normal sleeping() function within the BBS,
the current time is stored in a global system variable. During the poker
game, the alarm() handler points to an own function which upon every call
to itself checks if it's already time again to call the sleeping()
function of the BBS. The function in the poker game works just with number
of consecutive calls, and every call takes place all five seconds.
When the user leaves the poker game, the last call to the function will
determine that the user is no longer within the game, and restore the
normal sleeping() function after the appropriate amount of time (which can
easily be calculated). Therefore, the normal course of the sleeping()
function is not shifted by more than 4 seconds!

Decentralized game handling: All processes contain the full information
to do everything. But only certain processes (i.e. the game-master) are
actually allowed to do something. The game-master and the current player
are stored in shared memory, and every process checks if it is allowed
to do functions, by first checking the shared memory. Therefore it is
ensured that no process does what it should not do!
The only function that is invoked by all processes, is the checking of
the players online (whether they are still all there and logged in). In
this case, the "removal" of a user from the table might under certain
circumstances be announced twice. But that is all there is, so this is
no big deal. In testing, even under extreme conditions, this did never
occur.

Avoiding of reentrant functions: It is clear that a process which sends
the command-message may not at the same time receive that signal and
send another command-message. This would cause reentrant functions, and
I had this often during my experiments. Especially the function which
determines the end of the game, is being called by non-privileged
processes (not gamemaster, but current player!). Having seen no way out
of this, I did the following: an override variable is stored in shared
memory, and when the game-end function is called, the process calling
this function, stores its ID in shared memory. When the informational
signal is now sent back to all processes, it is checked back whether
the receiving process is the sending process at the same time. If it
is, it waits till the sending function terminates and then the receiving
function is re-entered. This was a special problem with the previously
mentioned semaphore-locking, but using the methods as described, it
could be done more or less "properly", even when there *might* be more
elegant ways of doing it.

There was a lot of other technical problems, but these were the ones
which might be of basic interest.


Chapter 6.
Numbers and Credits

Numbers:

70 000 ... combined size in bytes of all source codes to the poker game
 2 500 ... number of lines for the game in all source codes
   165 ... number of hours needed for program development

Credits:

Idea ......... Michael Tritthart
Programmer ... Michael Tritthart
Layout ....... Romain Lheritier / Michael Tritthart
Testing ...... All Sysops and Supervisors of Global Village BBS

Dedication ... This program is dedicated to M.H.,
               and to all users of Global Village BBS!


I wish everyone a lot of fun with this game! Hopefully you will have as much
fun in playing it as I had in coding it (although it was sometimes a pain :)!