************************************************** 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  -  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  thru . 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 :)!