       ___   ______     ___       _________   _________   ___
       \__\  \   __\    \  \__    \______  \  \   _____\  \__\
         ___  \  \       \  __\     _____\  \  \  \         ___
         \  \  \  \       \  \      \  ____  \  \  \        \  \
          \  \  \  \_____  \  \____  \  \__\  \  \  \        \  \
           \  \  \       \  \      \  \        \  \  \        \  \
            \__\  \_______\  \______\  \________\  \__\        \__\

                     *   m   a   g   a   z   i   n   e   *

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

                       I C T A R I   U S E R   G R O U P

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Pontoon Documentation
-=-=-=-=-=-=-=-=-=-=-

Note: This is not a complete game. It's just how far I've got so far.

The game is based  on  the  arcade  machines,  where  you can play either
Pontoon or hi/low. Both of these  have  been written in. However although
the game is quite  playable,  it  lacks  sound  effects,  and any form of
scoring.

Included is the STOS basic source  showing  how  far I've got so far. The
work is about 3 hours worth  and  below  shows  how, and what I did, etc.
Also I have mentioned what  problems  I  came  across, and how I overcame
them.

-------------------------------------------------------------------------
The first stage was to draw the  sprites.  I  used an art package to draw
the clubs, diamonds, hearts, spades,  and  the  numbers.  Then I used the
STOS sprite editor to put the  actual  cards together. The memory bank is
included with the source, and contains 53 sprites. 52 cards and 1 back of
a card.

I have not chosen the most efficient way to display sprites. The best way
would be to have just the  hearts,  spades,  etc  as sprites, and use the
various screen copy commands, etc  to  make  the cards up. However screen
copy is an instruction I don't understand  too well so unless someone can
help me out, I will have to  resort  to the current way. However this way
does cause unnecessary space to be wasted.  Take  a look at the length of
the source code to get my point.  Fortunately the space can be saved when
you compile and compress the program.

With the sprites drawn, I can now start  to move on to the actual coding.
The drawing of all the sprites took me  about an hour. The first step was
to decide what initial variables  would  be  needed.  I  came up with the
following:

PCARD(5) = An  array  of  the  players  hand.  The  number contained here
relates to the number of a sprite in the sprite bank, 1-52.
CCARD(5) = An array of computers hand, otherwise as PCARD(5).
           5 is the maximum number of cards.
PT       = The current total of players score.
CT       = The current total of computers score.
PC       = The number of players' cards.
CC       = The number of computers' cards.

This was all, I could think of initially.

The first stage was to write  the  initial  setups, and declare the known
variables. eg. Low res, and turn of cursor, mouse, and key click.

At this stage I decided to write  the  initial menu. This is in lines 70-
160. The code is very simple as it  just prints the options to screen and
waits for a key press relating to an option.

I was not bothered about the hi-low game for the time being and would put
that stage off until I had got the Pontoon part working.

The first thing to do in  the  Pontoon  game  was  to get 4 random cards.
Obviously getting a random card was something  I  would need to do a lot,
so I wrote this into a subroutine. The subroutine ranges from 880 - 1070.
It then occurred to me that I will  have to make sure that the card drawn
at random is not already drawn. Therefore  I declared a REP variable as a
flag. If the REP value was other than 0 then the card was repeated.

Line 890 gets a random number from 1  and  52,  and sets it to a new CARD
variable. This value relates directly  to  a  sprite number in the sprite
bank. The next stage was to check  the card drawn against all other cards
drawn. I did this and included a  check  in case the card being drawn was
the first card. Another important thing to  do was to decide the value of
the card. For example any picture card  is  worth  10 and an ace is worth
either 1 or 11. The ace causes a small problem which I will put aside for
now. The other problem is that  the  value  in  CARD does not contain the
actual value of the card.  So  therefore  the subroutine at 1400 converts
this. If you don't  understand  how  this  works  it's  because you don't
understand how the sprites are stored. Here is how they are stored.

          Suit 1      Suit 2       Suit 3       Suit 4

Sprite    1 = Ace     14 = Ace     27 = Ace     40 =  Ace
Sprite    2 = Two     15 = Two     28 = Two     41 =  Two
Sprite    3 = Three   16 = Three   29 = Three   42 =  Three
Sprite    4 = Four    17 = Four    30 = Four    43 =  Four
.         . . .       .  . .       .  . .       .  .  .
.         . . .       .  . .       .  . .       .  .  .
Sprite   11 = Jack    24 = Jack    37 = Jack    50 =  Jack
Sprite   12 = Queen   25 = Queen   38 = Queen   51 =  Queen
Sprite   13 = King    26 = King    39 = King    52 =  King

Therefore if card 38 is  drawn  the  actual  value  is 10. The subroutine
checks which suit it is in, and  takes  away  the excess. In this case it
takes away 26 to get 12, 12 is  a  queen. Therefore all that is left is a
small routine that converts values over 10  to  10. Voila we now have the
value of the card drawn at random. Going  back to the problem of the ace,
I decided to presume the  value  will  be  treated  as  11 rather than 1.
Obviously later on I need to check that if the player has bust whether he
has an ace. At this stage I was  not  bothered about this so I decided to
create an ACE variable. If an ace is drawn then the CV (current value) is
set to 11, and the ACE flag is  set to 1. Therefore it is also neccessary
to set this flag to 0, at the start of this routine.

Going back to the main part of the program where we called the subroutine
we can now display the  sprites   for  the  first  four cards. We need to
display the two sprites in PCARD(1)  and  PCARD(2).  Also we need to show
two sprites face down to refer to the computer's cards.

When that is done we add and display  the total of the player's hand. The
next stage is to ask the player if he wishes to twist or stick.

The TWIST option begins at 440. The  first  thing to do now is to display
another card, as before. All  this  has  been  done,  so we just call the
subroutine. When we return we get the card number CARD, the value CV, and
whether i'ts an ace. If it's an ace  we set another PACE flag. The sprite
is drawn and the value is added to the Players total. Because the sprites
were part of a loop until the player stuck, bust or got a 5 card trick, I
needed to set a x coordinate  variable which increases. The x coordinates
show where the next card should be drawn.  PCX is the variable I used for
this and is incremented by 40 for each card.

Now we have to check the  total  value  of  the  card to check we haven't
bust. If we have then we need to  see  if the hand contains an ace. If it
does then the total will be adjusted  by  10,  as  the ace is taken to be
value 1 not 11, and also the  PACE  flag  needs decremented by 1. We also
need to check whether the number of cards is equal to 5. If it is and the
player has not bust, then he has a  five card trick. A five card trick is
treated as a total of 100, you  will  see  why later. If the player busts
then the RESULT variable is set to  1  and the program jumps to line 545,
which calls the result subroutine.  This  subroutine prints the result in
this case result 1 is 'You Bust - You Lose'.

This can now continue, until  the  player  sticks,  busts, or gets a five
card trick. The bust option has been  dealt with. The other two both jump
to the stick subroutine.

The stick routine  first  displays  the  computers  concealed  cards. The
computer's total is then added up  and  displayed. If the total equals 21
then the computer must have PONTOON. In this  case RESULT is set to 6 and
the suitable message printed. Likewise  if  the  players  total is 21 and
number of cards = 2 then the player has PONTOON.

The following bit repeats until either  the  computer equals or beats the
computer score, or until it busts  or  gets  a  five card trick. The five
card trick option would result in a win, so  at the end of a loop, a five
card trick is assumed. The same applies with ACE's for the computer using
the PACE flag.

Depending on whether the computer busts  or  whether  it gets a five card
trick, or wins - the  suitable  result  variable  is  set, and the result
subroutine is called  displaying  this  message  at  1500.  Line 620 then
prints a play again prompt. If yes is answered then the computer jumps to
210 and the player plays again. If  no is answered then the computer goes
back to the main menu.

Thats the pontoon game complete.  The  only  real  problems were with the
ace's. For example it could be possible  to  be  dealt 4 aces in a row. 4
Aces can be a total of 4, 14, 24, 34, or 44. Obviously the last three are
irrelevant as this  means  that  the  player  has  bust.  The  game would
currently show a total of 14 with the PACE value being 1. This means that
if another card is drawn and its value  is  10, the total will be 24, but
the computer will see the PACE set  to  0,  and deduct 10 from the total.
Hope you understand this.

Hi-Low game

After writing the pontoon section this  section  was  easy as most of the
work had been done. Because there  will  only  be one hand, we don't need
both CCARD(5) and PCARD(5). However for some reason I choose to use CCARD
instead of PCARD, not that it matters.

This subroutine starts at line 1079. The first  thing to do was to draw 5
cards face down. Next we get  a  card  from  the same routine used by the
Pontoon game. The card is  displayed.  The  user  is  then prompted for a
higher or lower guess. Nothing new here.

The variable GS is set to 1 if  the player guesses higher or 2 for lower.
After a guess the next card is drawn  and shown. Now for the new bit. The
subroutine 1370 is called, and  the  value  of  the card is determined as
before, but Jacks, Queens, and Kings  are taken as 11,12,13 respectively,
and ACE's are treated as 1. The  routine  for this is a simple routine of
the same used for the Pontoon game in 1400. But we need to know the value
of the current card and the new card.  This took some thinking and I came
up with the lines at 1370 to  1390.  What  this does is set two variables
CV1 and CV2. CV1 is the last card,  and  CV2  is the new card. CV2 is the
simpler as it's just converted but CV1  is  set to the value of the first
card IF the number of cards = 2,  else  it  is simply set to the value of
CV2, which was last times new card.  Simple eh?, but it took some working
out. Hmmm the obvious always comes to you last.

All we need now is to check that  the guess (GS) is correct. This is done
at lines 1260, and 1270. If the  player  is correct then we print correct
and loop again to get  another  guess  for  the  next  card else Wrong is
printed and the game ends. The  user  is  asked  whether he wants to play
again, if he does we jump to 1080, if no then we jump to the main menu at
70.

The final bit to do is to end  the  game with a win message if the player
guesses all the cards. This is  simply  done  by  the exiting of the loop
shown at line 1160. If the end  is  reached then the player has won hence
the message.

-------------------------------------------------------------------------
-------
That's it, the game  appears  to  work,  although  I  have noticed a bug,
sometimes a card is repeated, so  I  will  work  on  this. Also I need to
consider the scoring system  and  would  appreciate  any help. Can anyone
remember what the actual arcade machine pays  out for a win. I think it's
3 for Pontoon but how much for a flush, run, a simple win, etc. Also how
much for a win at the hi-low game.

Sound effects are seriously  lacking  but  I  want  to  use more than the
pathetic STOS sounds you get with the  sample programs. Also I would like
to use screen copy commands to display the sprites instead of storing the
whole card as a sprite. But I will  need to experiment with the command a
lot.

Once all this is done the game will be finished in its simple form. I can
then consider adding some special effects,  maybe samples, etc. Who knows
but I won't think about  this  until  I  reach this stage. Another option
available would be to increase the  menu  to other card games. We already
have the pack of cards  as  sprites  so  why  not  write  a poker game or
something else. Anyway I've got a lot  I  can  do to this program so I'll
stop writing this and get stuck in.

I will add if anyone  has  any  ideas,  tips, advice, criticism, for this
program then please tell me them. Also what  do you think of this idea to
discuss and talk about your work as you go along. Let me know .....

Also if you are new to  programming  in  STOS, or programming in general,
and don't understand anything about this source, then please get in touch
and tell me what you  don't  understand.  I  will try and explain better.
However the source is well documented, too much if you want my opinion.

Nik Bates
<iCTARi>

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
                          E N D   O F   S E C T I O N
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
