                  Card Game Utility v1.8 (beta)
		    By Bart McEndree

CONTENTS
----------
 FEATURES
 CONTROL
  Scoring
  Drawing
  Digging
  Stacks
  Keys
 COMMAND LINE OPTIONS
  Examples
 FILES
  Datafile
  Deck Construction
  Problem cards
  Deckinfo
  Savegames
  Lock deck
 COMMUNICATIONS
  Protocal
  Message types
 REVISION HISTORY


FEATURES:
	The Card Game Utility (CGU) is a program used to play 2 player card
games like Poker on a single computer or on 2 computers via a null modem
datalink or via a Netbios compatable network, or E-mail datafile transfere.
CGU allows you to draw, place, move, flip, turn, and discard cards by using a
mouse or keyboard. Each card is rendered as a 35x60 pixel rectangle on a
640x480 16 color display. Each card is filled with text read from a data file.
CGU is capable of displaying 9 cards in each hand and 50 total cards in play.
	Cards are drawn from 2 sperate decks that provide the defined number
of cards (up to 175 each) in random order. The number of cards available in
each deck is displayed and subtracted each time a card is drawn. Cards are
discarded by moving them into one of 2 discard piles. You can search thru
the deck & discard piles to find cards & move them to your hand or into play.
         Both players own two push/pop stacks capable of storing 99 cards
each. A counter displays the number of cards and the number of turned cards
in each stack.
	 You can use CGU with a keyboard or a mouse. Some of the features can
only be accessed with the keyboard. By using the keyboard or mouse to control
a large square cursor you can pass over each of your cards to activate the
zoom window along the right side of the screen. When activated, text
associated with the current card will appear in the zoom window in a slightly
larger font. Also displayed in the zoom window will be text from the cardtype
and cardspecs fields of the data file. Zooming on the decks, discard piles,
stacks, or counters will display information about special key controls
for with those areas.

CONTROL:
	Manipulating cards in CGU is simple. Just move your cursor over the
card you want to select and hit the left mouse button or the ENTER key. When
you select a card it will appear to slide up about 5 pixels and be sorrounded
by a red square cursor. You can then designate a new position for the selected
card by moving the mouse or cursor to an open area, your hand, a discard pile,
or stack. Hitting the left mouse button or ENTER will then move the selected
card to that spot. If you right click or hit SPACE on any selected card in
play it will rotate 90 degrees counter-clockwise. Hitting SPACE or the right
mouse button again resets the card. If you right click on the top or bottom
rows (player hands) the cards in your hand will toggle from hide all to show
all. Any cards you draw or hold in your hand will be hidden from a remote
player until the card is placed in play.

*In v1.6+ you must now move the cursor to a card before you can select it with
the mouse. This allows beginners to browse w/o affecting the cards. Use
-oneclick to turn off this option and allow you to select cards with only one
click of the left mouse button.

Scoring:
	Clicking the left/right buttons on the score counters will subtract
or add to the score. If any players score reaches -1 the game will end.

Drawing:
	To draw a card left click on the deck you want to draw from. This
will cause CGU to draw a card from a random location within the deck. CGU
does not normaly maintain your deck in shuffled order. CGU simulates a
shuffled deck by generating a random number taht is used as an index into
your defined deck. If you need to maintain your deck in a shuffled order
then read about deck-digging.

Deck-digging, Grave-digging:
        To sort thru your deck or graveyard (discard pile) right click on
them. This will put you in digging mode. Every time you click the right
button you will see the next card in the deck or graveyard. If you are
digging in the deck the card you are shown will be automatically selected.
To stop digging in your deck de-select or move the current card using the
left mouse button. In v1.6+ you are able to move cards from one deck to
another. This allows you to claim any ante you won or build a deck with cards
from another deck.
       Deck digging can also be used to draw from a shuffled deck that will
maintain the shuffled order of the cards even in saved games. By default the
order of the deck while in deck digging mode is the order in which the cards
were read from the deck file. To change this order hit 'm'. Every time you
hit m CGU will swap the positions of 60 random cards in the selected deck.
To draw from this fixed-order-deck just draw your cards with the right
button. You are essentaily deck digging the first card out of a shuffled
deck.

Stacks:
        There are 4 stacks, two for each player. These stacks are used to
store excess cards in play. A stack is a first-in-last-out (FIFO) queue.
This means the first card you put into the stack is the last card you
will be able to pull out of the stack. There are counters that tells you
how many cards are in the stack and how many of those cards are tapped
(turned). These counters appear below each stack like this: "tapped/total".
To reset any tapped cards double left-click on the stack.

Keys:
q,Q                 Quit

cursors, mouse      control location of select box. (If you do not load a
		    mouse driver use the -nomouse command line option or the
		    the game will freeze and you have to re-boot).

enter, left click   select, move, new card, decrement score, clear stack
		    counter.

space, right click  tap, hide/show, increment score, dig thru deck or
		    discard pile.

1                   draw a card from player 1's deck into player 1's hand

2                   draw a card from player 2's deck into player 2's hand

d                   Discard selected card to the appropriate discard pile

home                reset both player's cursors (do this often in modem games
		     to ensure consistency).

F1, t               Talk window toggle. Opens/closes chat window.

F2, n               Add a 10 character note to selected card. (for counters)

F3, c               Change color of selected card (also '=').

F4, s               Save game. Makes save.txt deck file. To use it
		    type "ren save.txt deck.txt"

F5, e               Edit current card. Hit enter to select the line you wish
		    to edit. hit F5 again to exit.

f                   Flip selected card. This hides the card. The zoombox
		    won't even tell you what it is. This is a toggle.
		    Flip it again to show it.

x                   Remove card from game entirely.

l                   Shuffles & locks deck. Encodes save game.

m                   Shuffels dig mode deck.

y,Y                 Start another game after one ends.


COMMAND LINE OPTIONS:
CGU -file <filename> -com <1,2> -player <1,2> -slow -nomouse -oneclick

-file <name>  Loads specified file instead of default "deck.txt"
-com  <port>  Communicates with repomote player via the specified port
-player <#>   Designates the person using this station as player 1 or 2
-slow         Use 2400 baud instead of default 9600
-nomouse      Ignores mouse. Prevents lockup is mousedriver not loaded.
-oneclick     couse commands require 1 click instead of two.
-edit <name>  edits the specified .dek file

Example:
CGU
2 players share 1 computer using deck.txt as the deck file.

CGU -com 1 -player 1 -file bobnsam.txt
Loads CGU, accepts commands from remote player via COM1: at 9600 baud, and
designates this computer as player #1. Uses "bobnsam.txt" as the deck file.

CGU -com 2 -player 2 -slow  -oneclick
Loads CGU, accepts commands from remote player via COM2: at 2400 baud, and
designates this computer as player #2. Selecting cards requires only one
mouse click.

CGU -com 1  -nomouse
Loads CGU, accepts commands from remote player via COM1:, and allows this
computer to look at the cards in either players hand. Mouse will be ignored.

CGU -edit bart.dek
Loads CGU and runs the editor to edit bart.dek deck file.


FILES:

(required files)
cgu.exe     Executable. Main CGU program
egavga.bgi  Borland C++ 3.0 Graphics library
deck.txt    Example deck file (default deck)

(extra files, in order of importance)
readme.txt  This file
build.bat   Batch file for building deck.txt from .dek files
system.dek  Header used by build.bat to make deck.txt from .dek files
deck2.dek   Deck divider record used by build to seperate deck 1 from deck 2
blank.dek   A template .dek file that contains all known M:TG cards
bart.dek    Example .dek file that can be used with build.bat
save.txt    CGU savegame. Created when you save a game w/o specifing a name

Datafile:
	CGU accepts "deck.txt" as it's default deck file. A deck file contains
6 or more records of length 167 delimited by CR/LF. The records are divided
into 3 sections. The first section, or SYSTEM section, is the first 6 records
which are used to store the labels, color, and directions of the decks,
discard piles, counters, and stacks. The second section defines the cards that
will be drawn from deck 1. Deck 1 continues until '-1 ' is found in the NID
field. The rest of the file is section 3 which defines the cards for deck 2.
This example shows part of a deck.txt file that defines deck 1 with 1
clay statue and deck 2 with 4 Mishra's Factories. Lines begining with 0 are
ignored by CGU and can be used for comments.

Deck.txt:
1   20  H   DIRECTIONS:Left click or ENTER toselect and move cards.Right cl...
1   20  H              DECK                             (new card)
1       B              GRAVEYARD                        (discards)
1       H              M A G I C                        *---------*
1       C               M A N A   S T A C K             (Push/Pop)
1       R              PLAYER     SCORE                 (counter)
0   Deck1
1       C              Clay Statue                      land
-1
0   Deck2
4       A              Mishra's Factory                 land

	The deck.txt file that comes with CGU v1.6 is defined for M:TG
games. It defines two decks, deck 1 is red/white and deck 2 is black/blue.
This doesn't mean CGU knows how to play M:TG. It won't keep you from breaking
any of the rules. All CGU knows how to do is display cards on the screen and
move them where you tell it to. It won't subtract your score for you when you
are attacked or send creatures to the graveyard for you when they are killed.
	 The provided deck.txt data file defines two decks, one red/white and
one black/blue. The Data file is easily edited with any text editor (Dos v5.0
edit works). If you would like to remove the clay statue for example, you could
change the number of times the clay statue appears in the deck from 1 to 0.
You could also delete the entire line defining the clay statue. To add another
clay statue change the number from 1 to 2. Its that easy!
	Defining new decks is not that hard either. I have provided a blank
deck that define all the M:TG cards I know about (all but Legends). You should
begin by copying blank.dek to a file that names your deck. Some of the names
I've used are bart.dek, gary.dek, sik1.dek, and bruiser.dek. You can use the
built in deck editor to edit these files by typing cgu -edit <deck>. For
example, if you wanted to edit bart.dek you would type cgu -edit bart.dek.
This deck editor will enable you to change the number of times each card
appears in your deck as well as the color and text of each card.
        Once you've defined your deck you can make a deck.txt file by using
the "build" batch file that I have provided. if you wanted to setup a game
between Bart and Gary you would type "Build bart gary" (The .dek extension
is assumed). This will add the system cards to the top of the file, add
bart.dek as deck 1, put in a -1 record, & add gary.dek as deck 2. In CGU v1.6
I povided my dek file as an example. Notice how I left some cards zero. Those
are the cards I keep on my sidebar. If I wanted to use them I'd have to edit
my .dek file or deck.txt directly. 0 occurance cards are not saved in
save.txt.

M:TG PROBLEM CARDS:
Magical Hack (maybe fixed by changing border color or adding note)
Sleight of Mind (as Magical Hack)
Laces (as Magical Hack)
Drafna's Restoration & Aladdin's Lamp (places Graveyard artifacts on top of
 library. Gravedig and set card beside deck. You can not add cards to the
 top or bottom of library. Cards added to deck can only be shuffled in)
Natural Selection (You should draw 3 cards now and add them to your hand
 1 turn at a time)
Fork (only for certain spells.  Don't know how this could be fixed.
 Possibly with notations)
All 50/50 cards (could be fixed by heads/tails generator or honest players)
Shahrazad (anyone using this card DESERVES to have problems :)
Winter Orb (Only a small problem, but would be annoying.  Not a problem for
players with good memory/attention)
Chaos Orb (Don't know how this could be fixed)
The Hive (probably fixed using counters, but how would you know when a wasp
 was tapped? Maybe use flipped discarded cards to represent wasps)
Tetravus (see Hive)
Library of Leng (played a real game the other day and had 18+ card in my
 hand. You will have to put excess cards in play and flip them.)
Glasses of Urza/Word of Command (This might be a problem in modem play.
 You will have to move your cards out of your hand and back in.)
Anything which removes a card permanently from the game should be noted
on the card and the cards should be kept in the graveyard.


Deck Info:
Datafile name: "Deck.txt"
Maximum cards: 350
# of system cards: 6
# deck cards:344 (deck1+deck2)

Deck data file structure:

nid[4],pig[4],color[1],tcolor[2],hid,cost[11],name[11],name2[11],note[11],type[22],spec[77],stats[11],dummy[3];

length=170 characters;

nid    number in deck, number of times this card occurs in your deck (0-170)
pig    position in game. Designates where card is displayed on the screen.
color  displays card boarder color:
	R red   G green   H dark blue   A brown (Artifacts)
	U blue  W White   B dark grey   C grey (Colorless)
tcolor text color. same field values as color. If blank, default colors used.
hid    if card is flipped (hidden) this will be 'H' otherwise it will be ' '.
cost   appears in the upper-right corner of card and zoom card. (right justify)
name   name that appears on card and zoom card below cost
name2  name that appears on the line below the first name
note   notation on card
type   name that appears below name2 on zoom card
specs  appears on the zoom below type, 11 characters per line for 7 lines
stats  appears in lower-right corner of card (right justify)
dummy  period,CR,LF

All white characters (invisible characters) must be spaces or nulls. no tabs
allowed. A period, CR, and LF must exist at the end of each line.

Saved Games:
	To save the game at any point hit F4 or s. This will create a file
called save.txt. This file is a deck file that has all the positions of the
cards recored in the PIG (position in game) field. It also records the current
score in the first two PIG fields of the system cards. Save.txt will probably
be larger than your deck.txt file because it saves 1 card per line,
duplicating cards that occur multiple times in your deck. For example:

Deck.txt:
1   20  H   DIRECTIONS:Left click or ENTER toselect and move cards.Right cl...
1   20  H              DECK                             (new card)
1       B              GRAVEYARD                        (discards)
1       H              M A G I C                        *---------*
1       C               M A N A   S T A C K             (Push/Pop)
1       R              PLAYER     SCORE                 (counter)
4       C              Undergroundsea                   land

Save.txt:
1   15  H   DIRECTIONS:Left click or ENTER toselect and move cards.Right cl...
1   11  H              DECK                             (new card)
1       B              GRAVEYARD                        (discards)
1       H              M A G I C                        *---------*
1       C               M A N A   S T A C K             (Push/Pop)
1       R              PLAYER     SCORE                 (counter)
1       C              Undergroundsea                   land
1       C              Undergroundsea                   land
-   60  C              Undergroundsea                   land
-   -60 C              Undergroundsea                   land

        This save.txt file will restore the game with player 1 having 15 life
and player 2 having 11 life. It will aslo restore 2 Underground seas to your
deck and 2 Undergound seas to the manastack located at position 60. One of them
is tapped (negative 60). Since I store a NULL "\0" character after the PIG
field sometimes, you might not be able to read the rest of the line using wimpy
text editors like DOS edit. I use Qedit v2.1 by SemWare. There are 80 posible
positions for a card on the screen. They follow this patern:

0   1   2   3   4   5   6   7   8   9
10  11  12  13  14  15  16  17  18  19
20  21  22  23  24  25  26  27  28  29
30  31  32  33  34  35  36  37  38  39
40  41  42  43  44  45  46  47  48  49
50  51  52  53  54  55  56  57  58  59
60  61  62  63  64  65  66  67  68  69
70  71  72  73  74  75  76  77  78  79

Locked decks:
	When you use the lock deck option 'l', both decks are shuffled and
locked. This means you will not be able to deck dig, add cards to a deck,
or draw from a random location within a deck. You will only be able to
draw the next card. This option also encodes the save game so it can not
be easily tampered with. CGU recognizes encoded save games and will decode
them when they are read into memory for play. CGU will remember that it
loaded an encoded deck and will save it as encoded if you save it again.
It is possible to decode a locked deck without CGU but only I know how to
do that <G>.

COMMUNICATIONS:
        CGU supports two types of communications that allow you to play
between two computers in realtime. They are serial and network.
        Serial communications require both computers to be connected using
a null modem cable. Each end of the null modem cable attaches to a com port
on each computer. Only COM1: and COM2: are supported.
        Network communications require two computers that are connected to
a network that runs a Netbios compatable network operating systems. Examples
are Novel Netware, Netware Lite, & Lantastic. The NETBIOS.EXE TSR must be
running on both computers. Both players must be logged onto the network.

Protocal:
        The protocal used by CGU is a master/slave token-ring echo
protocal with 7 bit message lengths. Only one computer owns the com link
at a time (the master, the computer which currently has the token). If the
slave computer wishes to gain ownership it must first request it and be
granted ownership by the current owner (by passing the token). Requests
of ownership are communicated as '' (ascii 1). Grants of ownership are
comunicated as NULL (ascii 0). All communications (except requests &
chat mode characters) are verified by echoing them back to the owner. This
provides a low level of error detection and flow contol. The owner will
not send another message until the last one sent was echoed back.

Messages:
   Typical messages consist of:
         ownership changes 1, 0
         cursor movements  72, 75, 80, 81
         keyboard buttons  13, 32, 49,..., 99, 100, 101,... 120
         chat characters   0-128
         card locations    0-79
         and card numbers  0/128 then 0-128 (requires two messages).

        Since there are no message type identifiers, all messages must be
handled under the appropriate context. A message containing "H" (ascii 72)
could be a cursor movement, chat character, location, or card number. Both
machines run the same code and therefore know what state the other computer
is in and what type of message to expect.
        Mouse commands are mapped to 1 or more keyboard commands. Button 1
& 2 are mapped to Enter (13) and Space Bar (32). Moving the cursor box to the
mouse pointer is acomplished by sending the cursor keystrokes required to move
the box from it's current position to the new location and my require up to
17 messages (down, down, left, left, left,...). At 2400 baud you can actually
see the cursor box move as it recieves each command.

REVISION HISTORY:
v2.0 Plan to implement overlapping cards. modem dial/answer. Save game
     encoding w/ password protection.

v1.8  Added -net option that sets up a link via a Netbios compatable
      network.

v1.7  Added lock deck feature. Fixed deck dig bug that did not display all
      available cards in the deck. Added -seed option.

v1.6  changed format of command line parameters. Changed format of deck.txt
      file to enable card editing (F5). Added extra keys (t,c,n,s,e). Added
      -nomouse option for people w/o a mouse driver. Changed the way cards
      are selected with the mouse. Added -oneclick option. Added -edit
      option to edit decks. Added 'x' key to remove cards from game.

v1.5  Added colored background on cards. Moved 'hid' field and inserted
      tcolor field. notes cleaned off when card goes to graveyard.
      notes now 10 characters.

v1.4  Added ability to move cards into a deck. You can also swap cards
      between decks to claim won ante or to build one deck from another.
      Added Token protocol to determine which player gets to issue a
      command if both players try to do something at the same time.
      added '-' & '+' to send current card to graveyard.
      Fixed '1' & '2' keys lockup if empty deck.

v1.3  Enabled '1' & '2' keys for non-modem games. Fixed associated bugs.
      Added text header to deck.txt. Added deckdigging, F-flip,
      F2-notations, F3-color, and F4-save for PBEM.

v1.2 Add F1 chat. Fixed cursor erasing deck,tap,grave counters. Fixed bug
     that locked up CGU when clicking right of deck. Fixed cost limit (from
     3 chrs to 5. right-justify cost field to make output look good).

v1.1 Added 2nd stack for each player. Implemented ability to search thru
     and remove cards from discard piles. Added null modem datalink.
     Made zoom window text larger and shortened data file. Keyboard
     control.

v1.0 Customized card locations into deck, discard pile, stacks, zoom window,
     and counters.

v0.9 Simple card engine. Allowed the moving of cards to 80 fixed locations
     on the screen.
