LICENSE
=======

This game is provided as-is with no warranties.
It has been thoroughly tested on an HP48GX Rev. R
calculator with two HP128k RAM cards installed
in ports 1 and 2.  The program should run fine
from any port, albeit a bit slower from a port
greater than 1.  I used only entries provided
by HP but have small code segments throughout.
I believe that this code may work on an HP48SX
machine, although not tested.

This code may be redistributed as a single
package that includes only this text and the
game library.  Both attachments must remain
unmodified.

This program is provided free of charge for
your entertainment.  You may share it with
your friends, etc. as you wish.

For problems, please provide details to:
   scott-t@pacbell.net


OVERVIEW
========

Pyramid Solitaire is a standard-deck card game
where 28 of the 52 cards are laid-out face-down
in a pyramid.  The remaining cards are held
face-down and are referred to as the "stack."
The object of pyramid solitaire is to clear the
base pyramid of its cards.  This can be accomplished
by matching one or two cards which total 13 or by
playing a linear up/down sequence, depending on the
game mode.  The following table summarizes
individual card values:

       A: 1
    2-10: Face Value
       J: 11
       Q: 12
       K: 13

Therefore, the possible 13 matches are:

      1. King alone
      2. Queen+Ace
      3. Jack+2
      4. Ten+3
      5. Nine+4
      6. Eight+5
      7. Seven+6

and vice-versa.

Examples of a linear match could be:

      1. 10+J+10+9...
      2. K+A+2...
      3. 3+4+3+2+A+2+A+K...

Linear matches can continue as long as the run
allows.  ONLY THE STACK CARD CAN START A LINEAR
RUN.

GAME MODES
==========

There are four game modes, identified as 0-3.
These are identified here:

      0. Removes all cards, regardless.
         Use this mode to define your own games.

      1. Linear mode.
         This mode starts at the stack deck.
         Any card removed from the stack deck
         sets the linear key from which remaining
         cards get played.  That is, if the stack
         card has a value of five (5), then either
         a four (4) or a six (6) can be played from
         either the discard deck or the main pyramid
         pile.  The newly played card then becomes the
         new linear key (4 or 6) from which one up
         or one down from the key is permitted.  Note
         that the play can roll from King to Ace and
         vice-versa.

      2. 13-Point with Wildcard King mode.
         Standard Pyramid Solitaire where any combination
         of cards can be removed as long as they total
         13 points.  Also, if a card is selected before
         a King, it is removed with the King.  The King
         may still be removed by itself, as in Game Mode 3.

      3. 13-Point mode.
         Similar to Mode 2, except that the WildCard King
         is discontinued.  Kings must be removed by
         themselves because they are 13 points alone.

The stack card may be transferred to another
deck called the "discard" deck.  The "discard"
deck is a face-up LIFO stack.  Only the top
element of the discard deck may be used to 
complete a 13-point match.  Once the stack
card is moved to the discard deck, it may
be moved back to the stack deck _only_ if no
other valid match has been made since the
last transfer.  That is, if a card is moved
from the stack deck to the discard deck and
then a pair is removed from the main pyramid
or a combination of pyramid/stack or a 
combination of pyramid/discard then the last
transferred card from the stack to the discard
deck is not permitted to return to the stack
deck.

A game score will be kept internally that will
be a summation of all of the card values taken
during a game.  The maximum possible points
is calculated by:

   {[(TotalCards-Kings)/2]+Kings}*13

and should be 364 for a normal deck of cards.


INSTALLATION
============

Installation of this program to your calculator
means that you agree to the terms of the enclosed
license.  You may not use nor disclose this software
outside of scope of the enclosed license.  This
software is provided as-is and offers no warranties.

Upload library 871:
PYSOL: Pyramid Solitaire V1.1 by Scott Thompson (C) 1998 AUG 17
Size: 8999.5 Byes, Checksum: #B011h

Store to the port of your choice (can be run from a 
covered port).  Turn your calculator off and then on.
Library 871 should auto-attach to the home directory.

To run, type "PYSOL" (all caps) from the command line
or press the softkey under the library PYSOL.

See your operator manual for details on uploading and
launching libraries if necessary.

TO PLAY *PYSOL* VER 1.1
=======================

From the main splash screen, enter a game level 0-3.

Game Level 0: Removes all cards.
Game Level 1: Removes linear sequences.
Game Level 2: Removes combinations of 13, King Wild.
Game Level 3: Removes combinations of 13 only.

Press ENTER to shuffle cards and begin gameplay, or
press SPACE (SPC) to replay the last shuffled deck.
NOTE that SPC is not valid when dealing the first
deck.  To see a listing of valid keys during play,
press the up arrow key.  Press any key to return to
the splash screen.

Move the cursor in the main pyramid deck by pressing
the left or right arrow keys.  To go to the source
deck, press the NXT key.  To go to the discard deck,
press the VAR key.  A black card in either the source
or discard decks means that no card is available there.
A badkey sound will be evident of a mistake if error
beeps are enabled (see user manual).  To return to the
main pyramid deck, press the power (y^x) key.

For the source, deck, the card must be turned-over
manully.  To turn over a face-down source card, press
the right arrow key when the cursor is in the sorce
deck.  To transfer the top turned-over card from the
source deck to the discard deck, press the left arrow
key when the cursor is in the source deck.  A transferred
card may be placed back to the source deck by going to
the discard deck (VAR key) and then pressing the right
arrow key.  This only works if no cards have been selected
or played.  Cards may be taken from combinations of the
source or discard decks and the main pyramid deck.  Note
that only two-card combinations are allowed in the pyramid
deck for game modes two and three.  That is, one cannot
remove two cards from the discard deck (unless game option 
zero or 1 is running), etc.  To quit the game, press ON.
To exit the game, press SPACE (SPC), or remove the last 
card from the pyramid deck.  WINNER or LOSER will be displayed
for games exited using SPC or a win along with the score
(sum of card values removed from all decks).  Press any key 
to return to the main splash screen.  Again, press ENTER to 
start a new game at the same game level, or press SPC to replay
the same game without shuffling the cards.  Note that a new
game level may be selected when at the opening splash
screen.  To deselect a selected card, press the down
arrow key (not applicable to game levels zero or one).


NEXT VERSION (1.2+)
===================

The next version will include an option to turn over the
discard deck and continue play and will also include 
more statistics such as number of hands played for each
game level, number of games won, number of games lost, etc.
The amount of code space should be minimal.
